diff options
| -rw-r--r-- | src/tools/fish.md | 150 |
1 files changed, 118 insertions, 32 deletions
diff --git a/src/tools/fish.md b/src/tools/fish.md index fb795dd..117ead2 100644 --- a/src/tools/fish.md +++ b/src/tools/fish.md @@ -26,10 +26,18 @@ set <name> [<values>] -u unexport from ENV ``` +### Special Variables [ref](https://fishshell.com/docs/current/language.html#special-variables) +```sh +$status # exit code of last command +$pipestatus # list of exit codes of pipe chain + +$CMD_DURATION # runtime of last command in ms +``` + ### Lists In `fish` all variables are lists (start with index `1`, but lists can't contain lists. -```text +```sh set foo a b c d echo $foo[1] # a @@ -39,13 +47,13 @@ echo $foo[1 3] # a c ``` `$` can be seen as dereference operator. -```text +```sh set foo a; set a 1337 echo $$foo # outputs 1337 ``` Cartesian product. -```text +```sh echo file.{h,cc} # file.h file.cc @@ -53,38 +61,35 @@ echo {a,b}{1,2} # a1 b1 a2 b2 ``` -### Special Variables (Lists) -```text -$status # exit code of last command -$pipestatus # list of exit codes of pipe chain - -$CMD_DURATION # runtime of last command in ms -``` - -#### `*PATH` +#### `*PATH` [ref](https://fishshell.com/docs/current/language.html#path-variables) Lists ending with `PATH` are automatically split at `:` when used and joined -with `:` when exported to the environment. -```text +with `:` when quoted or exported to the environment. +```sh set -x BLA_PATH a:b:c:d -echo $BLA_PATH # a b c d -env | grep BLA_PATH # BLA_PATH=a:b:c:d +echo $BLA_PATH # a b c d +echo "$BLA_PATH" # a:b:c:d (quoted) +env | grep BLA_PATH # BLA_PATH=a:b:c:d (env) + +set FOO_PATH x y z +echo $FOO_PATH # x y z +echo "$FOO_PATH" # x:y:z ``` ## Command Handling -```text +```sh # sub-commands are not run in quotes echo "ls output: "(ls) ``` ### I/O redirection -```text +```sh # 'noclobber', fail if 'log' already exists echo foo >? log ``` ## Control Flow ### `if` / `else` -```text +```sh if grep foo bar # do sth else if grep foobar bar @@ -95,7 +100,7 @@ end ``` ### `switch` -```text +```sh switch (echo foo) case 'foo*' # do start with foo @@ -107,14 +112,14 @@ end ``` ### `while` Loop -```text +```sh while true echo foo end ``` ### `for` Loop -```text +```sh for f in (ls) echo $f end @@ -122,11 +127,12 @@ end ## Functions Function arguments are passed via `$argv` list. -```text +```sh function fn_foo echo $argv end ``` + ### Autoloading When running a command fish attempts to autoload a function. The shell looks for `<cmd>.fish` in the locations defined by `$fish_function_path` and loads @@ -136,7 +142,7 @@ This is the preferred way over monolithically defining all functions in a startup script. ### Helper -```text +```sh functions # list al functions functions foo # describe function 'foo' functions -e foo # erase function 'foo' @@ -145,36 +151,116 @@ funced foo # edit function 'foo' # '-e vim' to edit in vim ``` +### Argument parsing and completion +`argparse` puts options into variables of name `_flag_NAME`. + +References: +- [Argument Handling](https://fishshell.com/docs/current/language.html#argument-handling) +- [`argparse`](https://fishshell.com/docs/current/cmds/argparse.html) +- [Writing your own completions](https://fishshell.com/docs/current/completions.html) +- [`complete`](https://fishshell.com/docs/current/cmds/complete.html) + +```sh +function moose --d "my moose fn" + # h/help : short / long option (boolean) + # color : only long option (boolean) + # u/user= : option with required argument, only last specified is taken + # f/file+= : option with required argument, can be specified multiple times + # + argparse h/help color= u/user= f/file=+ -- $argv + or return + + if set -ql _flag_help + echo "usage ..." + return 0 + end + + set -ql _flag_file + and echo "file=$_flag_file | cnt:" (count $_flag_file) + + set -ql _flag_color + and echo "color=$_flag_color" + + set -ql _flag_user + and echo "user=$_flag_user" +end + +# Delete all previous defined completions for 'moose'. +complete -c moose -e + +# Don't complete files for command. +complete -c moose --no-files + +# Help completion. +# -n specifies a conditions. The completion is only active if the command +# returns 0. +complete -c moose -s h -l help -n "not __fish_contains_opt -s h help" \ + --description "Print usage help and exit" + +# File completion. +# -F force complete files (overwrite --no-files). +# -r requires argument. +complete -c moose -s f -l file -F -r \ + --description "Specify file (can be passed multiple times)" + +# Color completion. +# -a options for completion. +# -x short for -r and --no-files (-f) +complete -c moose -x -l color -a "red blue" \ + --description "Specify a color." + +# User completion. +# -a options for completion. Call a function to generate arguments. +complete -c moose -x -s u -l user -a "(__fish_complete_users)" \ + --description "Specify a user" +``` + ## Prompt The prompt is defined by the output of the `fish_prompt` function. -```text +```sh function fish_prompt set -l cmd_ret echo "> "(pwd) $cmd_ret" " end ``` -> Use `set_color` to manipulate terminal colors. +> Use `set_color` to manipulate terminal colors and `set_color -c` to print the +> current colors. ## Useful Builtins -```text +List all builtins with `builtins -n`. + +```sh # history history search <str> # search history for <str> history merge # merge histories from fish sessions # list -count $var # count elements in list +count $var # count elements in list + +contains /bin $PATH # return 0 (true) 1 (false) +contains -i /bin $PATH # additionally print index on stdout # string string split SEP STRING + +# math +math -b hex 4096 # output dec as hex +math 0x1000 # output hex as dec +math "log2(1024)" # call functions +math -s0 7/3 # integer division (by default float) + +# status +status -f # abs path of current file ``` ## Keymaps ```text - Shift-Tab ........... tab-completion with search - Alt-Up / Alt-Down ... search history with token under the cursor - Alt-l ............... list content of dir under cursor - Alt-p ............... append '2>&1 | less;' to current cmdline + Shift-Tab .............. tab-completion with search + Alt-Up / Alt-Down ...... search history with token under the cursor + Alt-l .................. list content of dir under cursor + Alt-p .................. append '2>&1 | less;' to current cmdline + Alt-Left / Alt - Right . prevd / nextd, walk dir history ``` ## Debug |