💅 merge pull request #112 from FWDekker/better-usage-and-man-and-comp…

…letions~

💅 better usage and man and completions and a bunch of other stuff~

.github/img/samples.md

@@ -1,4 +1,32 @@
-## sample1.png
+## General settings
+### Konsole
+* Set font size to 32
+* Set window size to 60x12
+* Hide all toolbars, hide the title bar, and hide the frame.
+
+### Screenshot
+* Take a screenshot of the entire Konsole window.
+* Resize the image to be 450px wide.
+
+
+## bash.png
+1. Add the following to `~/.bashrc`:
+   ```shell
+   PROMPT_COMMAND="mommy -1 -s \$?; $PROMPT_COMMAND"
+   ```
+2. Use the following settings in `~/.config/mommy/config.sh`:
+   ```shell
+   MOMMY_COMPLIMENTS_ENABLED="0";MOMMY_ENCOURAGEMENTS="it's okay to make mistakes"
+   ```
+3. Apply the Konsole settings described above.
+4. Run
+   ```shell
+   ssh cia.gov
+   ```
+5. Take a screenshot as described above.
+
+
+## fish.png
 1. Install fish, and add the following to `~/.config/fish/functions/fish_right_prompt.fish`:
    ```shell
    function fish_right_prompt
@@ -9,16 +37,33 @@
    ```shell
    MOMMY_COMPLIMENTS_ENABLED="0";MOMMY_ENCOURAGEMENTS="it's okay to make mistakes";MOMMY_COLOR="lolcat"
    ```
-3. Open Konsole, set font size to 32, set window size to 60x12, and hide window borders.
+3. Apply the Konsole settings described above.
 4. Run
    ```shell
    sudo apt update
    ```
 5. Enter the wrong password three times.
-6. Take a screenshot.
+6. Take a screenshot as described above.
+
+
+## nushell.png
+1. Install brew and nushell, and add the following to `~/.config/nushell/config.nu`:
+   ```shell
+   $env.PROMPT_COMMAND_RIGHT = {|| mommy -1 -s $env.LAST_EXIT_CODE }
+   ```
+2. Use the following settings in `~/.config/mommy/config.sh`:
+   ```shell
+   MOMMY_COMPLIMENTS_ENABLED="0";MOMMY_ENCOURAGEMENTS="just a little further, mommy knows you can do it"
+   ```
+3. Apply the Konsole settings described above.
+4. Run
+   ```shell
+   rm -rf /
+   ```
+5. Take a screenshot as described above.
 
 
-## sample2.png
+## zsh.png
 1. Install zsh, and add the following to `~/.zshrc`:
    ```shell
    set -o PROMPT_SUBST
@@ -28,9 +73,9 @@
    ```shell
    MOMMY_COMPLIMENTS_ENABLED="0";MOMMY_COLOR="";MOMMY_PREFIX="%F{005}";MOMMY_SUFFIX="~%f";MOMMY_ENCOURAGEMENTS="never give up, my love"
    ```
-3. Open Konsole, set font size to 32, set window size to 60x12, and hide window borders.
+3. Apply the Konsole settings described above.
 4. Run
    ```shell
    git clone [email protected]/nyancrimew/noflylist.git
    ```
-5. Take a screenshot.
+5. Take a screenshot as described above.

CHANGELOG.md

@@ -2,6 +2,7 @@
 ## [unreleased]
 ### added
 * 🦓 mommy now supports templates with literal slashes using `%%S%%`~ ([#107](https://github.com/FWDekker/mommy/issues/107))
+* 🐟 mommy added completions for fish and zsh for the new options introduced in v1.4.0~ ([#105](https://github.com/FWDekker/mommy/issues/105))
 
 ### changed
 * 🙅‍♀️ mommy's `MOMMY_FORBIDDEN_WORDS` setting now interprets each word as a regex~ ([#103](https://github.com/FWDekker/mommy/issues/103))

README.md

@@ -17,7 +17,7 @@ so well~
 mommy is fully customizable, integrates with any shell, works on any system, and most importantly, loves you very
 much~ ❤️
 
-![mommy demo](.github/img/demo.gif)
+<img width="450px" src=".github/img/fish.png" alt="a command-line interface showing the text 'it's okay to make mistakes' after the user has failed to enter their password correctly three times in a row" />
 
 
 ## 🚚 installation<a name="installation"></a> <small><sup>[top ▲](#toc)</sup></small>
@@ -322,9 +322,11 @@ if you want to customise where and how mommy installs, you can just compile her
    this step builds mommy's files and copies them into your system.
    the exact paths differ per system, so find the instructions that are right for your system.
 
-   > ℹ️ if you want to install mommy only for the current user, add `prefix='~/.local/'` before `install`~
+   > [!NOTE]
+   > if you want to install mommy only for the current user, add `prefix='~/.local/'` before `install`~
 
-   > ℹ️ check the [makefile](https://github.com/FWDekker/mommy/blob/main/GNUmakefile) for a list of all prefix variables
+   > [!TIP]
+   > check the [makefile](https://github.com/FWDekker/mommy/blob/main/GNUmakefile) for a list of all prefix variables
    > you can override~
 
     * _debian/ubuntu/apt-based_
@@ -400,36 +402,36 @@ tar -C ./ -xzf mommy-*.tar.gz
 check out [how to use mommy](#usage), read all about [ways you can configure mommy](#configuration), and
 [integrate mommy with your shell](#shell-integration)~
 
-<img width="450px" src=".github/img/sample1.png" alt="mommy integrated with the fish shell" />
+<img width="450px" src=".github/img/demo.gif" alt="a command-line interface showing the text 'never give up, my love' after running a command that has failed, and showing the text 'mommy knew you could do it' after running a command that has succeeded" />
 
 
 ## 📖 usage<a name="usage"></a> <small><sup>[top ▲](#toc)</sup></small>
-mommy processes the output status of a command and compliments you if the command succeeds and encourages you if it
+mommy processes (the output status of) a command and compliments you if the command succeeds and encourages you if it
 fails~
 
-you can ask mommy to support you in a few ways, shown below.
-alternatively, you can [integrate mommy into your shell](#shell-integration) so `mommy` is invoked for each command~
+> [!TIP]
+> the **recommended** way of long-term mommy usage is to [integrate mommy into your shell](#shell-integration), so
+> mommy will run after every command you run~
 
-```shell
-$ mommy [command] ...
-# e.g. `mommy npm test`
-
-$ mommy -e eval
-# e.g. `mommy -e "ls -l | wc -l"`
+### 💃 how to run<a name="how-to-run"></a>
+for reference, here's the three main ways to invoke mommy~
 
-$ mommy -s status
-# e.g. `mommy -s 0` or `mommy -s $?`
-```
+| format                | example                     | when to use                                                          |
+|-----------------------|-----------------------------|----------------------------------------------------------------------|
+| `mommy [command] ...` | `mommy npm test`            | if you want mommy to respond to a single command~                    |
+| `mommy -e [command]`  | `mommy -e "ls -l \| wc -l"` | if you want mommy when using `\|` or `>`, or need mommy in a script~ |
+| `mommy -s [status]`   | `mommy -s $?`               | if you already ran a command and want mommy's help afterwards~       |
 
+### 🛸 extra options<a name="extra-options"></a>
 additionally, mommy knows a few extra options, which you can use to discover who mommy is and to tell mommy which
-[configuration files](#configuration) she should use.
+[configuration files](#configuration) she should use~
 
 | short option | long option                   | description                                                                                       |
 |--------------|-------------------------------|---------------------------------------------------------------------------------------------------|
 | `-h`         | `--help`                      | opens mommy's manual page~                                                                        |
-| `-v`         | `--version`                   | displays version information~                                                                     |
+| `-v`         | `--version`                   | displays mommy's version information~                                                             |
 | `-1`         |                               | writes output to stdout instead of stderr~                                                        |
-| `-c <file>`  | `--config=<file>`             | reads the [configuration](#configuration) from `<file>`~                                          |
+| `-c <file>`  | `--config=<file>`             | tells mommy that she should read your [config](#configuration) from `<file>`~                     |
 |              | `--global-config-dirs=<dirs>` | sets [global configuration dirs](#config-file-locations) to the colon-separated list in `<dirs>`~ |
 
 
@@ -569,6 +571,8 @@ just add the following line to `~/.bashrc`:
 ```shell
 PROMPT_COMMAND="mommy -1 -s \$?; $PROMPT_COMMAND"
 ```
+
+<img width="450px" src=".github/img/demo.gif" alt="bash showing the text 'it's okay to make mistakes' after running a command that has failed" />
 </details>
 
 <details>
@@ -579,6 +583,8 @@ in nushell you can have mommy output a message on the right side of your prompt
 ```shell
 $env.PROMPT_COMMAND_RIGHT = {|| mommy -1 -s $env.LAST_EXIT_CODE }
 ```
+
+<img width="450px" src=".github/img/nushell.png" alt="nushell showing the text 'just a little further, mommy knows you can do it' in the right prompt after running a command that has failed" />
 </details>
 
 <details>
@@ -595,6 +601,8 @@ if you have an [oh my fish](https://github.com/oh-my-fish/oh-my-fish) theme inst
 see if there's an easy way to extend the theme's right prompt.
 if not, you can either overwrite it with the above code, or copy-paste the theme's code into your own config file and
 then add mommy yourself~
+
+<img width="450px" src=".github/img/fish.png" alt="fish shell showing the text 'it's okay to make mistakes' in the right prompt after running a command that has failed" />
 </details>
 
 <details>
@@ -622,7 +630,7 @@ MOMMY_SUFFIX="~%f"
 this code randomly changes the output between magenta and cyan.
 note the `%f` in the suffix, which resets the color~
 
-<img width="450px" src=".github/img/sample2.png" alt="mommy integrated with the zsh shell" />
+<img width="450px" src=".github/img/zsh.png" alt="zsh showing the text 'never give up, my love' in the right prompt after running a command that has failed" />
 </details>
 
 <details>
@@ -671,7 +679,8 @@ sudo ln -fs /usr/bin/mommy /usr/bin/daddy
 sudo ln -fs /usr/share/man/man1/mommy.1.gz /usr/share/man/man1/daddy.1.gz
 ```
 
-> ℹ️ uninstalling mommy will not remove the manually created symlinks~
+> [!IMPORTANT]
+> uninstalling mommy will not remove the manually created symlinks~
 </details>
 
 

src/main/completions/fish/mommy.fish

@@ -1,22 +1,23 @@
+## Helper functions
 # Extracts the non-option commands from `$argv` and writes to stdout.
 # For example, given `mommy -c ./config.sh apt update -f`, writes `apt update -f`.
 function extract_command
-    set -e argv[1]
+    set --erase argv[1]
 
-    set -l is_option_argument 0
+    set --local is_option_argument 0
     for arg in $argv
         if test $is_option_argument -eq 1
-            set -e argv[1]
+            set --erase argv[1]
             set is_option_argument 0
             continue
         end
 
         switch $arg
-            case '-c' '-e' '-s'
-                set -e argv[1]
+            case '-c' '-e' '-s'  # Do not include long options here!
+                set --erase argv[1]
                 set is_option_argument 1
             case '-*'
-                set -e argv[1]
+                set --erase argv[1]
             case '*'
                 echo $argv
                 return 0
@@ -26,60 +27,71 @@ function extract_command
     return 0
 end
 
-# Extract the args, excluding the arg that the user is currently writing
+# Extract the args, excluding the arg that the user is currently writing.
 function get_args
-    set -l tokens (commandline -opc)
+    set --local tokens (commandline -opc)
 
     extract_command $tokens
 end
 
-# Extract the args, including the arg that the user is currently writing
+# Extract the args, including the arg that the user is currently writing.
 function get_args_with_token
-    set -l tokens (commandline -opc) (commandline -ct)
+    set --local tokens (commandline -opc) (commandline -ct)
 
     extract_command $tokens
 end
 
 
-# Set common elements
-set -l opt_help    "-o h -l help"
-set -l opt_version "-o v -l version"
+## Completions
+set --local opt_help    "--short-option h --long-option help"
+set --local opt_version "--short-option v --long-option version"
+set --local opt_eval    "--short-option e --long-option eval"
+set --local opt_status  "--short-option s --long-option status"
 
+complete --command mommy --no-files  # Disabled by default, but re-enabled for specific cases below
 
-# Add completions
-complete -c mommy -f
+# Help/version
+complete --command mommy --short-option h --long-option help \
+    --description "Show manual" \
+    --condition "__fish_is_first_arg"
+complete --command mommy --short-option v --long-option version \
+    --description "Show version" \
+    --condition "__fish_is_first_arg"
 
-complete -c mommy -o h -l help \
-    -d "Show manual" \
-    -n "__fish_is_first_arg"
-complete -c mommy -o v -l version \
-    -d "Show version" \
-    -n "__fish_is_first_arg"
+# Config
+complete --command mommy --short-option c --long-option config \
+    --require-parameter --force-files \
+    --description "Configuration file" \
+    --condition "not __fish_seen_argument $opt_help $opt_version"\
+    --condition "test -z (get_args)"
+complete --command mommy --long-option global-config-dirs \
+    --require-parameter \
+    --arguments "(__fish_complete_directories)" \
+    --description "Colon-separated global config file dirs" \
+    --condition "not __fish_seen_argument $opt_help $opt_version"\
+    --condition "test -z (get_args)"
 
-complete -c mommy -o 1 \
-    -d "Write to stdout" \
-    -n "not __fish_seen_argument $opt_help $opt_version" \
-    -n "test -z (get_args)"
-complete -c mommy -o c \
-    -rF \
-    -d "Configuration file" \
-    -n "not __fish_seen_argument $opt_help $opt_version"\
-    -n "test -z (get_args)"
+# Misc
+complete --command mommy --short-option 1 \
+    --description "Write to stdout" \
+    --condition "not __fish_seen_argument $opt_help $opt_version" \
+    --condition "test -z (get_args)"
 
-complete -c mommy -o e \
-    -r \
-    -d "Evaluate string" \
-    -n "not __fish_seen_argument $opt_help $opt_version -o s" \
-    -n "test -z (get_args)"
-complete -c mommy -o s \
-    -rf \
-    -d "Exit code" \
-    -a "(echo 0\tSuccess\n1\tError)" \
-    -n "not __fish_seen_argument $opt_help $opt_version -o e" \
-    -n "test -z (get_args)"
-
-complete -c mommy \
-    # `complete -C` requires one argument, so must be wrapped in quotes. Fish <3.4.0 cannot do `$(...)`, so workaround
-    # is to assign to temporary variable.
-    -k -a "(set -l command (get_args_with_token); complete -C \"\$command\")" \
-    -n "test -n (get_args_with_token); or not __fish_seen_argument $opt_help $opt_version -o e -o s"
+# Usage
+complete --command mommy \
+    # `complete --do-complete` requires one argument, so must be wrapped in quotes.
+    # Fish <3.4.0 cannot do `$(...)`, so workaround is to assign to temporary variable.
+    --keep-order \
+    --arguments "(set --local command (get_args_with_token); complete --do-complete \"\$command\")" \
+    --condition "test -n (get_args_with_token); or not __fish_seen_argument $opt_help $opt_version $opt_eval $opt_status"
+complete --command mommy --short-option e --long-option eval \
+    --require-parameter \
+    --description "Evaluate string" \
+    --condition "not __fish_seen_argument $opt_help $opt_version $opt_status" \
+    --condition "test -z (get_args)"
+complete --command mommy --short-option s --long-option status \
+    --require-parameter --no-files \
+    --description "Exit code" \
+    --arguments "(echo 0\tSuccess\n1\tError)" \
+    --condition "not __fish_seen_argument $opt_help $opt_version $opt_eval" \
+    --condition "test -z (get_args)"

src/main/completions/zsh/_mommy

@@ -11,9 +11,10 @@ _arguments \
     "(- *)"{-h,--help}'[Show manual]' \
     "(- *)"{-v,--version}'[Show version]' \
     -1'[Write to stdout]' \
-    -c'[Configuration file]:config:_files' \
-    -e'[Evaluate string]:string' \
-    -s'[Exit code]:code:->status' \
+    {-c,--config}'[Configuration file]:config:_files' \
+    --global-config-dirs'[Colon-separated global config file dirs]:global config:_dir_list' \
+    {-e,--eval}'[Evaluate string]:string' \
+    {-s,--status}'[Exit code]:code:->status' \
     '*::command:'
 
 # suggest exit codes for --status