diff --git a/sphinx_doc_src/cmds/abbr.rst b/sphinx_doc_src/cmds/abbr.rst index 91174d6a5..79705df0b 100644 --- a/sphinx_doc_src/cmds/abbr.rst +++ b/sphinx_doc_src/cmds/abbr.rst @@ -42,29 +42,44 @@ See the "Internals" section for more on them. Examples ------------ -\fish -abbr -a -g gco git checkout -\endfish + + +:: + + abbr -a -g gco git checkout + Add a new abbreviation where `gco` will be replaced with `git checkout` global to the current shell. This abbreviation will not be automatically visible to other shells unless the same command is run in those shells (such as when executing the commands in config.fish). -\fish -abbr -a -U l less -\endfish + + +:: + + abbr -a -U l less + Add a new abbreviation where `l` will be replaced with `less` universal so all shells. Note that you omit the `-U` since it is the default. -\fish -abbr -r gco gch -\endfish + + +:: + + abbr -r gco gch + Renames an existing abbreviation from `gco` to `gch`. -\fish -abbr -e gco -\endfish + + +:: + + abbr -e gco + Erase the `gco` abbreviation. -\fish -ssh another_host abbr -s | source -\endfish + + +:: + + ssh another_host abbr -s | source + Import the abbreviations defined on another_host over SSH. Internals @@ -73,13 +88,16 @@ Each abbreviation is stored in its own global or universal variable. The name co Defining an abbreviation with global scope is slightly faster than universal scope (which is the default). But in general you'll only want to use the global scope when defining abbreviations in a startup script like `~/.config/fish/config.fish` like this: -\fish -if status --is-interactive - abbr --add --global first 'echo my first abbreviation' - abbr --add --global second 'echo my second abbreviation' - abbr --add --global gco git checkout - # etcetera -end -\endfish + + +:: + + if status --is-interactive + abbr --add --global first 'echo my first abbreviation' + abbr --add --global second 'echo my second abbreviation' + abbr --add --global gco git checkout + # etcetera + end + You can create abbreviations interactively and they will be visible to other fish sessions if you use the `-U` or `--universal` flag or don't explicitly specify the scope and the abbreviation isn't already defined with global scope. If you want it to be visible only to the current shell use the `-g` or `--global` flag. diff --git a/sphinx_doc_src/cmds/alias.rst b/sphinx_doc_src/cmds/alias.rst index 23a424d14..73ff79784 100644 --- a/sphinx_doc_src/cmds/alias.rst +++ b/sphinx_doc_src/cmds/alias.rst @@ -32,14 +32,17 @@ Example The following code will create `rmi`, which runs `rm` with additional arguments on every invocation. -\fish -alias rmi="rm -i" -# This is equivalent to entering the following function: -function rmi --wraps rm --description 'alias rmi=rm -i' - rm -i $argv -end -# This needs to have the spaces escaped or "Chrome.app..." will be seen as an argument to "/Applications/Google": -alias chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana' -\endfish +:: + + alias rmi="rm -i" + + # This is equivalent to entering the following function: + function rmi --wraps rm --description 'alias rmi=rm -i' + rm -i $argv + end + + # This needs to have the spaces escaped or "Chrome.app..." will be seen as an argument to "/Applications/Google": + alias chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana' + diff --git a/sphinx_doc_src/cmds/and.rst b/sphinx_doc_src/cmds/and.rst index 7a11b6b88..fa28dd694 100644 --- a/sphinx_doc_src/cmds/and.rst +++ b/sphinx_doc_src/cmds/and.rst @@ -21,7 +21,10 @@ Example The following code runs the `make` command to build a program. If the build succeeds, `make`'s exit status is 0, and the program is installed. If either step fails, the exit status is 1, and `make clean` is run, which removes the files created by the build process. -\fish -make; and make install; or make clean -\endfish + + +:: + + make; and make install; or make clean + diff --git a/sphinx_doc_src/cmds/argparse.rst b/sphinx_doc_src/cmds/argparse.rst index 999cf6ce7..341727e37 100644 --- a/sphinx_doc_src/cmds/argparse.rst +++ b/sphinx_doc_src/cmds/argparse.rst @@ -40,26 +40,35 @@ Usage Using this command involves passing two sets of arguments separated by `--`. The first set consists of one or more option specifications (`OPTION_SPEC` above) and options that modify the behavior of `argparse`. These must be listed before the `--` argument. The second set are the arguments to be parsed in accordance with the option specifications. They occur after the `--` argument and can be empty. More about this below but here is a simple example that might be used in a function named `my_function`: -\fish -argparse --name=my_function 'h/help' 'n/name=' -- $argv -or return -\endfish + + +:: + + argparse --name=my_function 'h/help' 'n/name=' -- $argv + or return + If `$argv` is empty then there is nothing to parse and `argparse` returns zero to indicate success. If `$argv` is not empty then it is checked for flags `-h`, `--help`, `-n` and `--name`. If they are found they are removed from the arguments and local variables (more on this below) are set so the script can determine which options were seen. Assuming `$argv` doesn't have any errors, such as a missing mandatory value for an option, then `argparse` exits with status zero. Otherwise it writes appropriate error messages to stderr and exits with a status of one. The `--` argument is required. You do not have to include any arguments after the `--` but you must include the `--`. For example, this is acceptable: -\fish -set -l argv -argparse 'h/help' 'n/name' -- $argv -\endfish + + +:: + + set -l argv + argparse 'h/help' 'n/name' -- $argv + But this is not: -\fish -set -l argv -argparse 'h/help' 'n/name' $argv -\endfish + + +:: + + set -l argv + argparse 'h/help' 'n/name' $argv + The first `--` seen is what allows the `argparse` command to reliably separate the option specifications from the command arguments. diff --git a/sphinx_doc_src/cmds/begin.rst b/sphinx_doc_src/cmds/begin.rst index f53e26585..2d24381b9 100644 --- a/sphinx_doc_src/cmds/begin.rst +++ b/sphinx_doc_src/cmds/begin.rst @@ -24,27 +24,33 @@ Example The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends. -\fish -begin - set -l PIRATE Yarrr - ... -end -echo $PIRATE -# This will not output anything, since the PIRATE variable -# went out of scope at the end of the block -\endfish +:: + + begin + set -l PIRATE Yarrr + + ... + end + + echo $PIRATE + # This will not output anything, since the PIRATE variable + # went out of scope at the end of the block + In the following code, all output is redirected to the file out.html. -\fish -begin - echo $xml_header - echo $html_header - if test -e $file + + +:: + + begin + echo $xml_header + echo $html_header + if test -e $file + ... + end ... - end - ... -end > out.html -\endfish + end > out.html + diff --git a/sphinx_doc_src/cmds/bind.rst b/sphinx_doc_src/cmds/bind.rst index 9a5faebf8..cf2feebe7 100644 --- a/sphinx_doc_src/cmds/bind.rst +++ b/sphinx_doc_src/cmds/bind.rst @@ -149,20 +149,29 @@ The following special input functions are available: Examples ------------ -\fish -bind \\cd 'exit' -\endfish + + +:: + + bind \\cd 'exit' + Causes `fish` to exit when @key{Control,D} is pressed. -\fish -bind -k ppage history-search-backward -\endfish + + +:: + + bind -k ppage history-search-backward + Performs a history search when the @key{Page Up} key is pressed. -\fish -set -g fish_key_bindings fish_vi_key_bindings -bind -M insert \\cc kill-whole-line force-repaint -\endfish + + +:: + + set -g fish_key_bindings fish_vi_key_bindings + bind -M insert \\cc kill-whole-line force-repaint + Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line. diff --git a/sphinx_doc_src/cmds/block.rst b/sphinx_doc_src/cmds/block.rst index 4244c5795..35efdd625 100644 --- a/sphinx_doc_src/cmds/block.rst +++ b/sphinx_doc_src/cmds/block.rst @@ -30,19 +30,22 @@ The following parameters are available: Example ------------ -\fish -# Create a function that listens for events -function --on-event foo foo; echo 'foo fired'; end -# Block the delivery of events -block -g -emit foo -# No output will be produced +:: + + # Create a function that listens for events + function --on-event foo foo; echo 'foo fired'; end + + # Block the delivery of events + block -g + + emit foo + # No output will be produced + + block -e + # 'foo fired' will now be printed -block -e -# 'foo fired' will now be printed -\endfish Notes diff --git a/sphinx_doc_src/cmds/break.rst b/sphinx_doc_src/cmds/break.rst index ebbac6608..6ee7f9573 100644 --- a/sphinx_doc_src/cmds/break.rst +++ b/sphinx_doc_src/cmds/break.rst @@ -19,11 +19,14 @@ Example ------------ The following code searches all .c files for "smurf", and halts at the first occurrence. -\fish -for i in *.c - if grep smurf $i - echo Smurfs are present in $i - break + + +:: + + for i in *.c + if grep smurf $i + echo Smurfs are present in $i + break + end end -end -\endfish + diff --git a/sphinx_doc_src/cmds/builtin.rst b/sphinx_doc_src/cmds/builtin.rst index 6afb4c6ab..71de7ed19 100644 --- a/sphinx_doc_src/cmds/builtin.rst +++ b/sphinx_doc_src/cmds/builtin.rst @@ -20,7 +20,10 @@ The following parameters are available: Example ------------ -\fish -builtin jobs -# executes the jobs builtin, even if a function named jobs exists -\endfish + + +:: + + builtin jobs + # executes the jobs builtin, even if a function named jobs exists + diff --git a/sphinx_doc_src/cmds/case.rst b/sphinx_doc_src/cmds/case.rst index faf21d401..bc0fe08dd 100644 --- a/sphinx_doc_src/cmds/case.rst +++ b/sphinx_doc_src/cmds/case.rst @@ -24,21 +24,24 @@ Example Say \$animal contains the name of an animal. Then this code would classify it: -\fish -switch $animal - case cat - echo evil - case wolf dog human moose dolphin whale - echo mammal - case duck goose albatross - echo bird - case shark trout stingray - echo fish - # Note that the next case has a wildcard which is quoted - case '*' - echo I have no idea what a $animal is -end -\endfish + + +:: + + switch $animal + case cat + echo evil + case wolf dog human moose dolphin whale + echo mammal + case duck goose albatross + echo bird + case shark trout stingray + echo fish + # Note that the next case has a wildcard which is quoted + case '*' + echo I have no idea what a $animal is + end + If the above code was run with `$animal` set to `whale`, the output would be `mammal`. diff --git a/sphinx_doc_src/cmds/cd.rst b/sphinx_doc_src/cmds/cd.rst index 96d7283bd..1e8b45191 100644 --- a/sphinx_doc_src/cmds/cd.rst +++ b/sphinx_doc_src/cmds/cd.rst @@ -24,13 +24,16 @@ As a special case, `cd .` is equivalent to `cd $PWD`, which is useful in cases w Examples ------------ -\fish -cd -# changes the working directory to your home directory. -cd /usr/src/fish-shell -# changes the working directory to /usr/src/fish-shell -\endfish + +:: + + cd + # changes the working directory to your home directory. + + cd /usr/src/fish-shell + # changes the working directory to /usr/src/fish-shell + See Also ------------ diff --git a/sphinx_doc_src/cmds/commandline.rst b/sphinx_doc_src/cmds/commandline.rst index dd02668d5..6026171db 100644 --- a/sphinx_doc_src/cmds/commandline.rst +++ b/sphinx_doc_src/cmds/commandline.rst @@ -65,22 +65,28 @@ Example `commandline -j $history[3]` replaces the job under the cursor with the third item from the command line history. If the commandline contains -\fish ->_ echo $fl___ounder >&2 | less; and echo $catfish -\endfish + + +:: + + >_ echo $fl___ounder >&2 | less; and echo $catfish + (with the cursor on the "o" of "flounder") Then the following invocations behave like this: -\fish ->_ commandline -t -$flounder ->_ commandline -ct -$fl ->_ commandline -b # or just commandline -echo $flounder >&2 | less; and echo $catfish ->_ commandline -p -echo $flounder >&2 ->_ commandline -j -echo $flounder >&2 | less -\endfish + + +:: + + >_ commandline -t + $flounder + >_ commandline -ct + $fl + >_ commandline -b # or just commandline + echo $flounder >&2 | less; and echo $catfish + >_ commandline -p + echo $flounder >&2 + >_ commandline -j + echo $flounder >&2 | less + diff --git a/sphinx_doc_src/cmds/complete.rst b/sphinx_doc_src/cmds/complete.rst index 12d5a9ec1..a6884a9ae 100644 --- a/sphinx_doc_src/cmds/complete.rst +++ b/sphinx_doc_src/cmds/complete.rst @@ -99,37 +99,52 @@ Example The short style option `-o` for the `gcc` command requires that a file follows it. This can be done using writing: -\fish -complete -c gcc -s o -r -\endfish + + +:: + + complete -c gcc -s o -r + The short style option `-d` for the `grep` command requires that one of the strings '`read`', '`skip`' or '`recurse`' is used. This can be specified writing: -\fish -complete -c grep -s d -x -a "read skip recurse" -\endfish + + +:: + + complete -c grep -s d -x -a "read skip recurse" + The `su` command takes any username as an argument. Usernames are given as the first colon-separated field in the file /etc/passwd. This can be specified as: -\fish -complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)" -\endfish + + +:: + + complete -x -c su -d "Username" -a "(cat /etc/passwd | cut -d : -f 1)" + The `rpm` command has several different modes. If the `-e` or `--erase` flag has been specified, `rpm` should delete one or more packages, in which case several switches related to deleting packages are valid, like the `nodeps` switch. This can be written as: -\fish -complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies" -\endfish + + +:: + + complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check dependencies" + where `__fish_contains_opt` is a function that checks the command line buffer for the presence of a specified set of options. To implement an alias, use the `-w` or `--wraps` option: -\fish -complete -c hub -w git -\endfish + + +:: + + complete -c hub -w git + Now hub inherits all of the completions from git. Note this can also be specified in a function declaration. diff --git a/sphinx_doc_src/cmds/contains.rst b/sphinx_doc_src/cmds/contains.rst index 25b0bd84d..05316bef4 100644 --- a/sphinx_doc_src/cmds/contains.rst +++ b/sphinx_doc_src/cmds/contains.rst @@ -23,30 +23,39 @@ Example If $animals is a list of animals, the following will test if it contains a cat: -\fish -if contains cat $animals - echo Your animal list is evil! -end -\endfish + + +:: + + if contains cat $animals + echo Your animal list is evil! + end + This code will add some directories to $PATH if they aren't yet included: -\fish -for i in ~/bin /usr/local/bin - if not contains $i $PATH - set PATH $PATH $i + + +:: + + for i in ~/bin /usr/local/bin + if not contains $i $PATH + set PATH $PATH $i + end end -end -\endfish + While this will check if `hasargs` was run with the `-q` option: -\fish -function hasargs - if contains -- -q $argv - echo '$argv contains a -q option' + + +:: + + function hasargs + if contains -- -q $argv + echo '$argv contains a -q option' + end end -end -\endfish + The `--` here stops `contains` from treating `-q` to an option to itself. Instead it treats it as a normal string to check. diff --git a/sphinx_doc_src/cmds/continue.rst b/sphinx_doc_src/cmds/continue.rst index 2f131f5e8..95a4a3ec5 100644 --- a/sphinx_doc_src/cmds/continue.rst +++ b/sphinx_doc_src/cmds/continue.rst @@ -17,14 +17,17 @@ Example The following code removes all tmp files that do not contain the word smurf. -\fish -for i in *.tmp - if grep smurf $i - continue + + +:: + + for i in *.tmp + if grep smurf $i + continue + end + # This "rm" is skipped over if "continue" is executed. + rm $i + # As is this "echo" + echo $i end - # This "rm" is skipped over if "continue" is executed. - rm $i - # As is this "echo" - echo $i -end -\endfish + diff --git a/sphinx_doc_src/cmds/count.rst b/sphinx_doc_src/cmds/count.rst index afe51ddc4..3047b9338 100644 --- a/sphinx_doc_src/cmds/count.rst +++ b/sphinx_doc_src/cmds/count.rst @@ -20,10 +20,13 @@ Description Example ------------ -\fish -count $PATH -# Returns the number of directories in the users PATH variable. -count *.txt -# Returns the number of files in the current working directory ending with the suffix '.txt'. -\endfish \ No newline at end of file + +:: + + count $PATH + # Returns the number of directories in the users PATH variable. + + count *.txt + # Returns the number of files in the current working directory ending with the suffix '.txt'. + diff --git a/sphinx_doc_src/cmds/echo.rst b/sphinx_doc_src/cmds/echo.rst index d29facf00..523848fe9 100644 --- a/sphinx_doc_src/cmds/echo.rst +++ b/sphinx_doc_src/cmds/echo.rst @@ -54,12 +54,18 @@ If `-e` is used, the following sequences are recognized: Example ------------ -\fish -echo 'Hello World' -\endfish + + +:: + + echo 'Hello World' + Print hello world to stdout -\fish -echo -e 'Top\\nBottom' -\endfish + + +:: + + echo -e 'Top\\nBottom' + Print Top and Bottom on separate lines, using an escape sequence diff --git a/sphinx_doc_src/cmds/else.rst b/sphinx_doc_src/cmds/else.rst index c6c583deb..6760295a7 100644 --- a/sphinx_doc_src/cmds/else.rst +++ b/sphinx_doc_src/cmds/else.rst @@ -18,10 +18,13 @@ Example The following code tests whether a file `foo.txt` exists as a regular file. -\fish -if test -f foo.txt - echo foo.txt exists -else - echo foo.txt does not exist -end -\endfish + + +:: + + if test -f foo.txt + echo foo.txt exists + else + echo foo.txt does not exist + end + diff --git a/sphinx_doc_src/cmds/emit.rst b/sphinx_doc_src/cmds/emit.rst index b6c25bdfc..794049117 100644 --- a/sphinx_doc_src/cmds/emit.rst +++ b/sphinx_doc_src/cmds/emit.rst @@ -18,13 +18,16 @@ Example The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type. -\fish -function event_test --on-event test_event - echo event test: $argv -end -emit test_event something -\endfish + +:: + + function event_test --on-event test_event + echo event test: $argv + end + + emit test_event something + Notes diff --git a/sphinx_doc_src/cmds/eval.rst b/sphinx_doc_src/cmds/eval.rst index 9b75e5406..9611dd36a 100644 --- a/sphinx_doc_src/cmds/eval.rst +++ b/sphinx_doc_src/cmds/eval.rst @@ -18,8 +18,11 @@ Example The following code will call the ls command. Note that `fish` does not support the use of shell variables as direct commands; `eval` can be used to work around this. -\fish -set cmd ls -eval $cmd -\endfish + + +:: + + set cmd ls + eval $cmd + diff --git a/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst b/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst index 47a411e98..b8f6730ca 100644 --- a/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst +++ b/sphinx_doc_src/cmds/fish_breakpoint_prompt.rst @@ -24,11 +24,14 @@ Example A simple prompt that is a simplified version of the default debugging prompt: -\fish -function fish_breakpoint_prompt -d "Write out the debug prompt" - set -l function (status current-function) - set -l line (status current-line-number) - set -l prompt "$function:$line >" - echo -ns (set_color $fish_color_status) "BP $prompt" (set_color normal) ' ' -end -\endfish + + +:: + + function fish_breakpoint_prompt -d "Write out the debug prompt" + set -l function (status current-function) + set -l line (status current-line-number) + set -l prompt "$function:$line >" + echo -ns (set_color $fish_color_status) "BP $prompt" (set_color normal) ' ' + end + diff --git a/sphinx_doc_src/cmds/fish_mode_prompt.rst b/sphinx_doc_src/cmds/fish_mode_prompt.rst index cbaeb2817..6eaa9a022 100644 --- a/sphinx_doc_src/cmds/fish_mode_prompt.rst +++ b/sphinx_doc_src/cmds/fish_mode_prompt.rst @@ -14,27 +14,30 @@ will be one of `default`, `insert`, `replace_one`, or `visual`. Example ------------ -\fish -function fish_mode_prompt - switch $fish_bind_mode - case default - set_color --bold red - echo 'N' - case insert - set_color --bold green - echo 'I' - case replace_one - set_color --bold green - echo 'R' - case visual - set_color --bold brmagenta - echo 'V' - case '*' - set_color --bold red - echo '?' - end - set_color normal -end -\endfish + + +:: + + function fish_mode_prompt + switch $fish_bind_mode + case default + set_color --bold red + echo 'N' + case insert + set_color --bold green + echo 'I' + case replace_one + set_color --bold green + echo 'R' + case visual + set_color --bold brmagenta + echo 'V' + case '*' + set_color --bold red + echo '?' + end + set_color normal + end + Outputting multiple lines is not supported in `fish_mode_prompt`. diff --git a/sphinx_doc_src/cmds/fish_opt.rst b/sphinx_doc_src/cmds/fish_opt.rst index e92b0c8ad..8faf08120 100644 --- a/sphinx_doc_src/cmds/fish_opt.rst +++ b/sphinx_doc_src/cmds/fish_opt.rst @@ -35,24 +35,33 @@ Examples Define a single option spec for the boolean help flag: -\fish -set -l options (fish_opt -s h -l help) -argparse $options -- $argv -\endfish + + +:: + + set -l options (fish_opt -s h -l help) + argparse $options -- $argv + Same as above but with a second flag that requires a value: -\fish -set -l options (fish_opt -s h -l help) -set options $options (fish_opt -s m -l max --required-val) -argparse $options -- $argv -\endfish + + +:: + + set -l options (fish_opt -s h -l help) + set options $options (fish_opt -s m -l max --required-val) + argparse $options -- $argv + Same as above but with a third flag that can be given multiple times saving the value of each instance seen and only the long flag name (`--token`) can be used: -\fish -set -l options (fish_opt --short=h --long=help) -set options $options (fish_opt --short=m --long=max --required-val) -set options $options (fish_opt --short=t --long=token --multiple-vals --long-only) -argparse $options -- $argv -\endfish + + +:: + + set -l options (fish_opt --short=h --long=help) + set options $options (fish_opt --short=m --long=max --required-val) + set options $options (fish_opt --short=t --long=token --multiple-vals --long-only) + argparse $options -- $argv + diff --git a/sphinx_doc_src/cmds/fish_prompt.rst b/sphinx_doc_src/cmds/fish_prompt.rst index 285d87140..add5e7453 100644 --- a/sphinx_doc_src/cmds/fish_prompt.rst +++ b/sphinx_doc_src/cmds/fish_prompt.rst @@ -24,10 +24,13 @@ Example A simple prompt: -\fish -function fish_prompt -d "Write out the prompt" - printf '%s@%s%s%s%s> ' (whoami) (hostname | cut -d . -f 1) \ - (set_color $fish_color_cwd) (prompt_pwd) (set_color normal) -end -\endfish + + +:: + + function fish_prompt -d "Write out the prompt" + printf '%s@%s%s%s%s> ' (whoami) (hostname | cut -d . -f 1) \ + (set_color $fish_color_cwd) (prompt_pwd) (set_color normal) + end + diff --git a/sphinx_doc_src/cmds/fish_right_prompt.rst b/sphinx_doc_src/cmds/fish_right_prompt.rst index c027e6f84..e9069c1fc 100644 --- a/sphinx_doc_src/cmds/fish_right_prompt.rst +++ b/sphinx_doc_src/cmds/fish_right_prompt.rst @@ -22,9 +22,12 @@ Example A simple right prompt: -\fish -function fish_right_prompt -d "Write out the right prompt" - date '+%m/%d/%y' -end -\endfish + + +:: + + function fish_right_prompt -d "Write out the right prompt" + date '+%m/%d/%y' + end + diff --git a/sphinx_doc_src/cmds/for.rst b/sphinx_doc_src/cmds/for.rst index 3dc81e0e1..1b934f04e 100644 --- a/sphinx_doc_src/cmds/for.rst +++ b/sphinx_doc_src/cmds/for.rst @@ -15,27 +15,33 @@ Description Example ------------ -\fish -for i in foo bar baz; echo $i; end -# would output: -foo -bar -baz -\endfish + +:: + + for i in foo bar baz; echo $i; end + + # would output: + foo + bar + baz + Notes ------------ The `VARNAME` was local to the for block in releases prior to 3.0.0. This means that if you did something like this: -\fish -for var in a b c - if break_from_loop - break + + +:: + + for var in a b c + if break_from_loop + break + end end -end -echo $var -\endfish + echo $var + The last value assigned to `var` when the loop terminated would not be available outside the loop. What `echo $var` would write depended on what it was set to before the loop was run. Likely nothing. diff --git a/sphinx_doc_src/cmds/function.rst b/sphinx_doc_src/cmds/function.rst index ee7e8c631..0d740d590 100644 --- a/sphinx_doc_src/cmds/function.rst +++ b/sphinx_doc_src/cmds/function.rst @@ -60,42 +60,51 @@ By using one of the event handler switches, a function can be made to run automa Example ------------ -\fish -function ll - ls -l $argv -end -\endfish + + +:: + + function ll + ls -l $argv + end + will run the `ls` command, using the `-l` option, while passing on any additional files and switches to `ls`. -\fish -function mkdir -d "Create a directory and set CWD" - command mkdir $argv - if test $status = 0 - switch $argv[(count $argv)] - case '-*' - case '*' - cd $argv[(count $argv)] - return + +:: + + function mkdir -d "Create a directory and set CWD" + command mkdir $argv + if test $status = 0 + switch $argv[(count $argv)] + case '-*' + + case '*' + cd $argv[(count $argv)] + return + end end end -end -\endfish + This will run the `mkdir` command, and if it is successful, change the current working directory to the one just created. -\fish -function notify - set -l job (jobs -l -g) - or begin; echo "There are no jobs" >&2; return 1; end - function _notify_job_$job --on-job-exit $job --inherit-variable job - echo -n \a # beep - functions -e _notify_job_$job + +:: + + function notify + set -l job (jobs -l -g) + or begin; echo "There are no jobs" >&2; return 1; end + + function _notify_job_$job --on-job-exit $job --inherit-variable job + echo -n \a # beep + functions -e _notify_job_$job + end end -end -\endfish + This will beep when the most recent job completes. diff --git a/sphinx_doc_src/cmds/functions.rst b/sphinx_doc_src/cmds/functions.rst index c11e623a2..f5820c595 100644 --- a/sphinx_doc_src/cmds/functions.rst +++ b/sphinx_doc_src/cmds/functions.rst @@ -61,13 +61,16 @@ The exit status of `functions` is the number of functions specified in the argum Examples ------------ -\fish -functions -n -# Displays a list of currently-defined functions -functions -c foo bar -# Copies the 'foo' function to a new function called 'bar' -functions -e bar -# Erases the function `bar` -\endfish +:: + + functions -n + # Displays a list of currently-defined functions + + functions -c foo bar + # Copies the 'foo' function to a new function called 'bar' + + functions -e bar + # Erases the function `bar` + diff --git a/sphinx_doc_src/cmds/history.rst b/sphinx_doc_src/cmds/history.rst index aead95569..0b3701b30 100644 --- a/sphinx_doc_src/cmds/history.rst +++ b/sphinx_doc_src/cmds/history.rst @@ -54,17 +54,20 @@ These flags can appear before or immediately after one of the sub-commands liste Example ------------ -\fish -history clear -# Deletes all history items -history search --contains "foo" -# Outputs a list of all previous commands containing the string "foo". -history delete --prefix "foo" -# Interactively deletes commands which start with "foo" from the history. -# You can select more than one entry by entering their IDs separated by a space. -\endfish +:: + + history clear + # Deletes all history items + + history search --contains "foo" + # Outputs a list of all previous commands containing the string "foo". + + history delete --prefix "foo" + # Interactively deletes commands which start with "foo" from the history. + # You can select more than one entry by entering their IDs separated by a space. + Customizing the name of the history file ------------ diff --git a/sphinx_doc_src/cmds/if.rst b/sphinx_doc_src/cmds/if.rst index ca0e3a594..fea89d3b0 100644 --- a/sphinx_doc_src/cmds/if.rst +++ b/sphinx_doc_src/cmds/if.rst @@ -24,20 +24,26 @@ Example The following code will print `foo.txt exists` if the file foo.txt exists and is a regular file, otherwise it will print `bar.txt exists` if the file bar.txt exists and is a regular file, otherwise it will print `foo.txt and bar.txt do not exist`. -\fish -if test -f foo.txt - echo foo.txt exists -else if test -f bar.txt - echo bar.txt exists -else - echo foo.txt and bar.txt do not exist -end -\endfish + + +:: + + if test -f foo.txt + echo foo.txt exists + else if test -f bar.txt + echo bar.txt exists + else + echo foo.txt and bar.txt do not exist + end + The following code will print "foo.txt exists and is readable" if foo.txt is a regular file and readable -\fish -if test -f foo.txt - and test -r foo.txt - echo "foo.txt exists and is readable" -end -\endfish + + +:: + + if test -f foo.txt + and test -r foo.txt + echo "foo.txt exists and is readable" + end + diff --git a/sphinx_doc_src/cmds/isatty.rst b/sphinx_doc_src/cmds/isatty.rst index b421bc725..26d2c9ca0 100644 --- a/sphinx_doc_src/cmds/isatty.rst +++ b/sphinx_doc_src/cmds/isatty.rst @@ -22,18 +22,24 @@ Examples From an interactive shell, the commands below exit with a return value of zero: -\fish -isatty -isatty stdout -isatty 2 -echo | isatty 1 -\endfish + + +:: + + isatty + isatty stdout + isatty 2 + echo | isatty 1 + And these will exit non-zero: -\fish -echo | isatty -isatty 9 -isatty stdout > file -isatty 2 2> file -\endfish + + +:: + + echo | isatty + isatty 9 + isatty stdout > file + isatty 2 2> file + diff --git a/sphinx_doc_src/cmds/nextd.rst b/sphinx_doc_src/cmds/nextd.rst index 15f66726c..fd4ca53c6 100644 --- a/sphinx_doc_src/cmds/nextd.rst +++ b/sphinx_doc_src/cmds/nextd.rst @@ -21,16 +21,19 @@ You may be interested in the `cdh` command which Example ------------ -\fish -cd /usr/src -# Working directory is now /usr/src -cd /usr/src/fish-shell -# Working directory is now /usr/src/fish-shell -prevd -# Working directory is now /usr/src +:: + + cd /usr/src + # Working directory is now /usr/src + + cd /usr/src/fish-shell + # Working directory is now /usr/src/fish-shell + + prevd + # Working directory is now /usr/src + + nextd + # Working directory is now /usr/src/fish-shell -nextd -# Working directory is now /usr/src/fish-shell -\endfish diff --git a/sphinx_doc_src/cmds/not.rst b/sphinx_doc_src/cmds/not.rst index 73def4b37..de19ae7a4 100644 --- a/sphinx_doc_src/cmds/not.rst +++ b/sphinx_doc_src/cmds/not.rst @@ -18,10 +18,13 @@ Example The following code reports an error and exits if no file named spoon can be found. -\fish -if not test -f spoon - echo There is no spoon - exit 1 -end -\endfish + + +:: + + if not test -f spoon + echo There is no spoon + exit 1 + end + diff --git a/sphinx_doc_src/cmds/or.rst b/sphinx_doc_src/cmds/or.rst index 83c8dfe93..9f2eab5de 100644 --- a/sphinx_doc_src/cmds/or.rst +++ b/sphinx_doc_src/cmds/or.rst @@ -22,6 +22,9 @@ Example The following code runs the `make` command to build a program. If the build succeeds, the program is installed. If either step fails, `make clean` is run, which removes the files created by the build process. -\fish -make; and make install; or make clean -\endfish + + +:: + + make; and make install; or make clean + diff --git a/sphinx_doc_src/cmds/popd.rst b/sphinx_doc_src/cmds/popd.rst index 2ebdb2874..c55d2d45f 100644 --- a/sphinx_doc_src/cmds/popd.rst +++ b/sphinx_doc_src/cmds/popd.rst @@ -17,16 +17,19 @@ You may be interested in the `cdh` command which Example ------------ -\fish -pushd /usr/src -# Working directory is now /usr/src -# Directory stack contains /usr/src -pushd /usr/src/fish-shell -# Working directory is now /usr/src/fish-shell -# Directory stack contains /usr/src /usr/src/fish-shell -popd -# Working directory is now /usr/src -# Directory stack contains /usr/src -\endfish +:: + + pushd /usr/src + # Working directory is now /usr/src + # Directory stack contains /usr/src + + pushd /usr/src/fish-shell + # Working directory is now /usr/src/fish-shell + # Directory stack contains /usr/src /usr/src/fish-shell + + popd + # Working directory is now /usr/src + # Directory stack contains /usr/src + diff --git a/sphinx_doc_src/cmds/prevd.rst b/sphinx_doc_src/cmds/prevd.rst index 50486a7dd..b73d6eab5 100644 --- a/sphinx_doc_src/cmds/prevd.rst +++ b/sphinx_doc_src/cmds/prevd.rst @@ -21,16 +21,19 @@ You may be interested in the `cdh` command which Example ------------ -\fish -cd /usr/src -# Working directory is now /usr/src -cd /usr/src/fish-shell -# Working directory is now /usr/src/fish-shell -prevd -# Working directory is now /usr/src +:: + + cd /usr/src + # Working directory is now /usr/src + + cd /usr/src/fish-shell + # Working directory is now /usr/src/fish-shell + + prevd + # Working directory is now /usr/src + + nextd + # Working directory is now /usr/src/fish-shell -nextd -# Working directory is now /usr/src/fish-shell -\endfish diff --git a/sphinx_doc_src/cmds/printf.rst b/sphinx_doc_src/cmds/printf.rst index dd27e690b..cc3a528b5 100644 --- a/sphinx_doc_src/cmds/printf.rst +++ b/sphinx_doc_src/cmds/printf.rst @@ -63,12 +63,18 @@ This file has been imported from the printf in GNU Coreutils version 6.9. If you Example ------------ -\fish -printf '%s\\t%s\\n' flounder fish -\endfish + + +:: + + printf '%s\\t%s\\n' flounder fish + Will print "flounder fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character. -\fish -printf '%s:%d' "Number of bananas in my pocket" 42 -\endfish + + +:: + + printf '%s:%d' "Number of bananas in my pocket" 42 + Will print "Number of bananas in my pocket: 42", _without_ a newline. diff --git a/sphinx_doc_src/cmds/prompt_pwd.rst b/sphinx_doc_src/cmds/prompt_pwd.rst index 58286b1cc..3d914d0cc 100644 --- a/sphinx_doc_src/cmds/prompt_pwd.rst +++ b/sphinx_doc_src/cmds/prompt_pwd.rst @@ -17,19 +17,22 @@ To change the number of characters per path component, set $fish_prompt_pwd_dir_ Examples ------------ -\fish{cli-dark} ->_ cd ~/ ->_ echo $PWD -/home/alfa ->_ prompt_pwd -~ ->_ cd /tmp/banana/sausage/with/mustard ->_ prompt_pwd -/t/b/s/w/mustard +:: + + >_ cd ~/ + >_ echo $PWD + /home/alfa + + >_ prompt_pwd + ~ + + >_ cd /tmp/banana/sausage/with/mustard + >_ prompt_pwd + /t/b/s/w/mustard + + >_ set -g fish_prompt_pwd_dir_length 3 + >_ prompt_pwd + /tmp/ban/sau/wit/mustard ->_ set -g fish_prompt_pwd_dir_length 3 ->_ prompt_pwd -/tmp/ban/sau/wit/mustard -\endfish diff --git a/sphinx_doc_src/cmds/psub.rst b/sphinx_doc_src/cmds/psub.rst index d63689aea..5e3e4a984 100644 --- a/sphinx_doc_src/cmds/psub.rst +++ b/sphinx_doc_src/cmds/psub.rst @@ -23,10 +23,13 @@ The following options are available: Example ------------ -\fish -diff (sort a.txt | psub) (sort b.txt | psub) -# shows the difference between the sorted versions of files `a.txt` and `b.txt`. -source-highlight -f esc (cpp main.c | psub -f -s .c) -# highlights `main.c` after preprocessing as a C source. -\endfish + +:: + + diff (sort a.txt | psub) (sort b.txt | psub) + # shows the difference between the sorted versions of files `a.txt` and `b.txt`. + + source-highlight -f esc (cpp main.c | psub -f -s .c) + # highlights `main.c` after preprocessing as a C source. + diff --git a/sphinx_doc_src/cmds/pushd.rst b/sphinx_doc_src/cmds/pushd.rst index 238765c65..ef96186a1 100644 --- a/sphinx_doc_src/cmds/pushd.rst +++ b/sphinx_doc_src/cmds/pushd.rst @@ -25,24 +25,27 @@ You may be interested in the `cdh` command which Example ------------ -\fish -pushd /usr/src -# Working directory is now /usr/src -# Directory stack contains /usr/src -pushd /usr/src/fish-shell -# Working directory is now /usr/src/fish-shell -# Directory stack contains /usr/src /usr/src/fish-shell -pushd /tmp/ -# Working directory is now /tmp -# Directory stack contains /tmp /usr/src /usr/src/fish-shell +:: -pushd +1 -# Working directory is now /usr/src -# Directory stack contains /usr/src /usr/src/fish-shell /tmp + pushd /usr/src + # Working directory is now /usr/src + # Directory stack contains /usr/src + + pushd /usr/src/fish-shell + # Working directory is now /usr/src/fish-shell + # Directory stack contains /usr/src /usr/src/fish-shell + + pushd /tmp/ + # Working directory is now /tmp + # Directory stack contains /tmp /usr/src /usr/src/fish-shell + + pushd +1 + # Working directory is now /usr/src + # Directory stack contains /usr/src /usr/src/fish-shell /tmp + + popd + # Working directory is now /usr/src/fish-shell + # Directory stack contains /usr/src/fish-shell /tmp -popd -# Working directory is now /usr/src/fish-shell -# Directory stack contains /usr/src/fish-shell /tmp -\endfish diff --git a/sphinx_doc_src/cmds/random.rst b/sphinx_doc_src/cmds/random.rst index c073d23c9..0dde95e6a 100644 --- a/sphinx_doc_src/cmds/random.rst +++ b/sphinx_doc_src/cmds/random.rst @@ -35,14 +35,20 @@ Example The following code will count down from a random even number between 10 and 20 to 1: -\fish -for i in (seq (random 10 2 20) -1 1) - echo $i -end -\endfish + + +:: + + for i in (seq (random 10 2 20) -1 1) + echo $i + end + And this will open a random picture from any of the subdirectories: -\fish -open (random choice **jpg) -\endfish + + +:: + + open (random choice **jpg) + diff --git a/sphinx_doc_src/cmds/read.rst b/sphinx_doc_src/cmds/read.rst index d7f69974c..69e2ef91b 100644 --- a/sphinx_doc_src/cmds/read.rst +++ b/sphinx_doc_src/cmds/read.rst @@ -82,18 +82,21 @@ Example The following code stores the value 'hello' in the shell variable `$foo`. -\fish -echo hello|read foo -# This is a neat way to handle command output by-line: -printf '%s\n' line1 line2 line3 line4 | while read -l foo - echo "This is another line: $foo" - end -# Delimiters given via "-d" are taken as one string -echo a==b==c | read -d == -l a b c -echo $a # a -echo $b # b -echo $c # c +:: + + echo hello|read foo + + # This is a neat way to handle command output by-line: + printf '%s\n' line1 line2 line3 line4 | while read -l foo + echo "This is another line: $foo" + end + + # Delimiters given via "-d" are taken as one string + echo a==b==c | read -d == -l a b c + echo $a # a + echo $b # b + echo $c # c + -\endfish diff --git a/sphinx_doc_src/cmds/return.rst b/sphinx_doc_src/cmds/return.rst index f3141bce9..38c8c82db 100644 --- a/sphinx_doc_src/cmds/return.rst +++ b/sphinx_doc_src/cmds/return.rst @@ -20,10 +20,13 @@ Example The following code is an implementation of the false command as a fish function -\fish -function false - return 1 -end -\endfish + + +:: + + function false + return 1 + end + diff --git a/sphinx_doc_src/cmds/set.rst b/sphinx_doc_src/cmds/set.rst index 1d2159d55..f5a7f4742 100644 --- a/sphinx_doc_src/cmds/set.rst +++ b/sphinx_doc_src/cmds/set.rst @@ -85,31 +85,34 @@ In assignment mode, `set` does not modify the exit status. This allows simultane Examples ------------ -\fish -# Prints all global, exported variables. -set -xg -# Sets the value of the variable $foo to be 'hi'. -set foo hi -# Appends the value "there" to the variable $foo. -set -a foo there +:: -# Does the same thing as the previous two commands the way it would be done pre-fish 3.0. -set foo hi -set foo $foo there + # Prints all global, exported variables. + set -xg + + # Sets the value of the variable $foo to be 'hi'. + set foo hi + + # Appends the value "there" to the variable $foo. + set -a foo there + + # Does the same thing as the previous two commands the way it would be done pre-fish 3.0. + set foo hi + set foo $foo there + + # Removes the variable $smurf + set -e smurf + + # Changes the fourth element of the $PATH array to ~/bin + set PATH[4] ~/bin + + # Outputs the path to Python if `type -p` returns true. + if set python_path (type -p python) + echo "Python is at $python_path" + end -# Removes the variable $smurf -set -e smurf - -# Changes the fourth element of the $PATH array to ~/bin -set PATH[4] ~/bin - -# Outputs the path to Python if `type -p` returns true. -if set python_path (type -p python) - echo "Python is at $python_path" -end -\endfish Notes ------------ diff --git a/sphinx_doc_src/cmds/set_color.rst b/sphinx_doc_src/cmds/set_color.rst index bae06ddfe..7a330bc51 100644 --- a/sphinx_doc_src/cmds/set_color.rst +++ b/sphinx_doc_src/cmds/set_color.rst @@ -42,12 +42,15 @@ Notes Examples ------------ -\fish -set_color red; echo "Roses are red" -set_color blue; echo "Violets are blue" -set_color 62A; echo "Eggplants are dark purple" -set_color normal; echo "Normal is nice" # Resets the background too -\endfish + + +:: + + set_color red; echo "Roses are red" + set_color blue; echo "Violets are blue" + set_color 62A; echo "Eggplants are dark purple" + set_color normal; echo "Normal is nice" # Resets the background too + Terminal Capability Detection ------------ diff --git a/sphinx_doc_src/cmds/source.rst b/sphinx_doc_src/cmds/source.rst index 6d72bf2fb..a560608d7 100644 --- a/sphinx_doc_src/cmds/source.rst +++ b/sphinx_doc_src/cmds/source.rst @@ -23,10 +23,13 @@ The return status of `source` is the return status of the last job to execute. I Example ------------ -\fish -source ~/.config/fish/config.fish -# Causes fish to re-read its initialization file. -\endfish + + +:: + + source ~/.config/fish/config.fish + # Causes fish to re-read its initialization file. + \subsection Caveats diff --git a/sphinx_doc_src/cmds/string.rst b/sphinx_doc_src/cmds/string.rst index 2149dc4d4..7a71f275f 100644 --- a/sphinx_doc_src/cmds/string.rst +++ b/sphinx_doc_src/cmds/string.rst @@ -188,193 +188,232 @@ And some other things: Examples ------------ -\fish{cli-dark} ->_ string length 'hello, world' -12 ->_ set str foo ->_ string length -q $str; echo $status -0 -# Equivalent to test -n $str -\endfish -\fish{cli-dark} ->_ string sub --length 2 abcde -ab +:: ->_ string sub -s 2 -l 2 abcde -bc + >_ string length 'hello, world' + 12 + + >_ set str foo + >_ string length -q $str; echo $status + 0 + # Equivalent to test -n $str ->_ string sub --start=-2 abcde -de -\endfish -\fish{cli-dark} ->_ string split . example.com -example -com ->_ string split -r -m1 / /usr/local/bin/fish -/usr/local/bin -fish ->_ string split '' abc -a -b -c -\endfish +:: -\fish{cli-dark} ->_ seq 3 | string join ... -1...2...3 -\endfish + >_ string sub --length 2 abcde + ab + + >_ string sub -s 2 -l 2 abcde + bc + + >_ string sub --start=-2 abcde + de -\fish{cli-dark} ->_ string trim ' abc ' -abc ->_ string trim --right --chars=yz xyzzy zany -x -zan -\endfish -\fish{cli-dark} ->_ echo \\x07 | string escape -cg -\endfish -\fish{cli-dark} ->_ string escape --style=var 'a1 b2'\\u6161 -a1_20b2__c_E6_85_A1 -\endfish +:: + + >_ string split . example.com + example + com + + >_ string split -r -m1 / /usr/local/bin/fish + /usr/local/bin + fish + + >_ string split '' abc + a + b + c + + + + +:: + + >_ seq 3 | string join ... + 1...2...3 + + + + +:: + + >_ string trim ' abc ' + abc + + >_ string trim --right --chars=yz xyzzy zany + x + zan + + + + +:: + + >_ echo \\x07 | string escape + cg + + + + +:: + + >_ string escape --style=var 'a1 b2'\\u6161 + a1_20b2__c_E6_85_A1 + Match Glob Examples ------------ -\fish{cli-dark} ->_ string match '?' a -a ->_ string match 'a*b' axxb -axxb ->_ string match -i 'a??B' Axxb -Axxb +:: ->_ echo 'ok?' | string match '*\\?' -ok? + >_ string match '?' a + a + + >_ string match 'a*b' axxb + axxb + + >_ string match -i 'a??B' Axxb + Axxb + + >_ echo 'ok?' | string match '*\\?' + ok? + + # Note that only the second STRING will match here. + >_ string match 'foo' 'foo1' 'foo' 'foo2' + foo + + >_ string match -e 'foo' 'foo1' 'foo' 'foo2' + foo1 + foo + foo2 + + + >_ string match 'foo?' 'foo1' 'foo' 'foo2' + foo1 + foo + foo2 + -# Note that only the second STRING will match here. ->_ string match 'foo' 'foo1' 'foo' 'foo2' -foo - ->_ string match -e 'foo' 'foo1' 'foo' 'foo2' -foo1 -foo -foo2 - - ->_ string match 'foo?' 'foo1' 'foo' 'foo2' -foo1 -foo -foo2 - -\endfish Match Regex Examples ------------ -\fish{cli-dark} ->_ string match -r 'cat|dog|fish' 'nice dog' -dog ->_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4) -dog1 -dog2 -cat3 -dog3 -cat4 -dog4 ->_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' 2:34:56 -2:34:56 -2 -34 -56 +:: ->_ string match -r '^(\\w{{2,4}})\\g1$' papa mud murmur -papa -pa -murmur -mur + >_ string match -r 'cat|dog|fish' 'nice dog' + dog + + >_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4) + dog1 + dog2 + cat3 + dog3 + cat4 + dog4 + + >_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' 2:34:56 + 2:34:56 + 2 + 34 + 56 + + >_ string match -r '^(\\w{{2,4}})\\g1$' papa mud murmur + papa + pa + murmur + mur + + >_ string match -r -a -n at ratatat + 2 2 + 4 2 + 6 2 + + >_ string match -r -i '0x[0-9a-f]{{1,8}}' 'int magic = 0xBadC0de;' + 0xBadC0de ->_ string match -r -a -n at ratatat -2 2 -4 2 -6 2 - ->_ string match -r -i '0x[0-9a-f]{{1,8}}' 'int magic = 0xBadC0de;' -0xBadC0de -\endfish \subsection string-example-split0 NUL Delimited Examples -\fish{cli-dark} ->_ # Count files in a directory, without being confused by newlines. ->_ count (find . -print0 | string split0) -42 ->_ # Sort a list of elements which may contain newlines ->_ set foo beta alpha\\ngamma ->_ set foo (string join0 $foo | sort -z | string split0) ->_ string escape $foo[1] -alpha\\ngamma -\endfish + +:: + + >_ # Count files in a directory, without being confused by newlines. + >_ count (find . -print0 | string split0) + 42 + + >_ # Sort a list of elements which may contain newlines + >_ set foo beta alpha\\ngamma + >_ set foo (string join0 $foo | sort -z | string split0) + >_ string escape $foo[1] + alpha\\ngamma + Replace Literal Examples ------------ -\fish{cli-dark} ->_ string replace is was 'blue is my favorite' -blue was my favorite ->_ string replace 3rd last 1st 2nd 3rd -1st -2nd -last ->_ string replace -a ' ' _ 'spaces to underscores' -spaces_to_underscores -\endfish +:: + + >_ string replace is was 'blue is my favorite' + blue was my favorite + + >_ string replace 3rd last 1st 2nd 3rd + 1st + 2nd + last + + >_ string replace -a ' ' _ 'spaces to underscores' + spaces_to_underscores + Replace Regex Examples ------------ -\fish{cli-dark} ->_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x' -0 3.14 5 ->_ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right' -right left $ ->_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here' -put a -here -\endfish +:: + + >_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x' + 0 3.14 5 + + >_ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right' + right left $ + + >_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here' + put a + here + Repeat Examples ------------ -\fish{cli-dark} ->_ string repeat -n 2 'foo ' -foo foo ->_ echo foo | string repeat -n 2 -foofoo ->_ string repeat -n 2 -m 5 'foo' -foofo +:: + + >_ string repeat -n 2 'foo ' + foo foo + + >_ echo foo | string repeat -n 2 + foofoo + + >_ string repeat -n 2 -m 5 'foo' + foofo + + >_ string repeat -m 5 'foo' + foofo ->_ string repeat -m 5 'foo' -foofo -\endfish diff --git a/sphinx_doc_src/cmds/switch.rst b/sphinx_doc_src/cmds/switch.rst index 821db0456..531240767 100644 --- a/sphinx_doc_src/cmds/switch.rst +++ b/sphinx_doc_src/cmds/switch.rst @@ -24,20 +24,23 @@ Example If the variable \$animal contains the name of an animal, the following code would attempt to classify it: -\fish -switch $animal - case cat - echo evil - case wolf dog human moose dolphin whale - echo mammal - case duck goose albatross - echo bird - case shark trout stingray - echo fish - case '*' - echo I have no idea what a $animal is -end -\endfish + + +:: + + switch $animal + case cat + echo evil + case wolf dog human moose dolphin whale + echo mammal + case duck goose albatross + echo bird + case shark trout stingray + echo fish + case '*' + echo I have no idea what a $animal is + end + If the above code was run with `$animal` set to `whale`, the output would be `mammal`. diff --git a/sphinx_doc_src/cmds/test.rst b/sphinx_doc_src/cmds/test.rst index b5e308e3f..dae2b6642 100644 --- a/sphinx_doc_src/cmds/test.rst +++ b/sphinx_doc_src/cmds/test.rst @@ -109,59 +109,80 @@ Examples If the `/tmp` directory exists, copy the `/etc/motd` file to it: -\fish -if test -d /tmp - cp /etc/motd /tmp/motd -end -\endfish + + +:: + + if test -d /tmp + cp /etc/motd /tmp/motd + end + If the variable `MANPATH` is defined and not empty, print the contents. (If `MANPATH` is not defined, then it will expand to zero arguments, unless quoted.) -\fish -if test -n "$MANPATH" - echo $MANPATH -end -\endfish + + +:: + + if test -n "$MANPATH" + echo $MANPATH + end + Parentheses and the `-o` and `-a` operators can be combined to produce more complicated expressions. In this example, success is printed if there is a `/foo` or `/bar` file as well as a `/baz` or `/bat` file. -\fish -if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \) - echo Success. -end. -\endfish + + +:: + + if test \( -f /foo -o -f /bar \) -a \( -f /baz -o -f /bat \) + echo Success. + end. + Numerical comparisons will simply fail if one of the operands is not a number: -\fish -if test 42 -eq "The answer to life, the universe and everything" - echo So long and thanks for all the fish # will not be executed -end -\endfish + + +:: + + if test 42 -eq "The answer to life, the universe and everything" + echo So long and thanks for all the fish # will not be executed + end + A common comparison is with $status: -\fish -if test $status -eq 0 - echo "Previous command succeeded" -end -\endfish + + +:: + + if test $status -eq 0 + echo "Previous command succeeded" + end + The previous test can likewise be inverted: -\fish -if test ! $status -eq 0 - echo "Previous command failed" -end -\endfish + + +:: + + if test ! $status -eq 0 + echo "Previous command failed" + end + which is logically equivalent to the following: -\fish -if test $status -ne 0 - echo "Previous command failed" -end -\endfish + + +:: + + if test $status -ne 0 + echo "Previous command failed" + end + Standards ------------ diff --git a/sphinx_doc_src/cmds/trap.rst b/sphinx_doc_src/cmds/trap.rst index b02aa10fb..870c8bedb 100644 --- a/sphinx_doc_src/cmds/trap.rst +++ b/sphinx_doc_src/cmds/trap.rst @@ -35,7 +35,10 @@ The return status is 1 if any `REASON` is invalid; otherwise trap returns 0. Example ------------ -\fish -trap "status --print-stack-trace" SIGUSR1 -# Prints a stack trace each time the SIGUSR1 signal is sent to the shell. -\endfish + + +:: + + trap "status --print-stack-trace" SIGUSR1 + # Prints a stack trace each time the SIGUSR1 signal is sent to the shell. + diff --git a/sphinx_doc_src/cmds/type.rst b/sphinx_doc_src/cmds/type.rst index 6c4a6a6bd..4426a0981 100644 --- a/sphinx_doc_src/cmds/type.rst +++ b/sphinx_doc_src/cmds/type.rst @@ -32,7 +32,10 @@ The `-q`, `-p`, `-t` and `-P` flags (and their long flag aliases) are mutually e Example ------------ -\fish{cli-dark} ->_ type fg -fg is a builtin -\endfish + + +:: + + >_ type fg + fg is a builtin + diff --git a/sphinx_doc_src/cmds/wait.rst b/sphinx_doc_src/cmds/wait.rst index c40d45b44..904ae557e 100644 --- a/sphinx_doc_src/cmds/wait.rst +++ b/sphinx_doc_src/cmds/wait.rst @@ -20,19 +20,28 @@ Description Example ------------ -\fish -sleep 10 & -wait $last_pid -\endfish + + +:: + + sleep 10 & + wait $last_pid + spawns `sleep` in the background, and then waits until it finishes. -\fish -for i in (seq 1 5); sleep 10 &; end -wait -\endfish + + +:: + + for i in (seq 1 5); sleep 10 &; end + wait + spawns five jobs in the background, and then waits until all of them finishes. -\fish -for i in (seq 1 5); sleep 10 &; end -hoge & -wait sleep -\endfish + + +:: + + for i in (seq 1 5); sleep 10 &; end + hoge & + wait sleep + spawns five jobs and `hoge` in the background, and then waits until all `sleep`s finishes, and doesn't wait for `hoge` finishing. diff --git a/sphinx_doc_src/cmds/while.rst b/sphinx_doc_src/cmds/while.rst index ba8e7fd2b..af1429afe 100644 --- a/sphinx_doc_src/cmds/while.rst +++ b/sphinx_doc_src/cmds/while.rst @@ -22,7 +22,10 @@ You can use `and` or `or` for complex condi Example ------------ -\fish -while test -f foo.txt; or test -f bar.txt ; echo file exists; sleep 10; end -# outputs 'file exists' at 10 second intervals as long as the file foo.txt or bar.txt exists. -\endfish + + +:: + + while test -f foo.txt; or test -f bar.txt ; echo file exists; sleep 10; end + # outputs 'file exists' at 10 second intervals as long as the file foo.txt or bar.txt exists. +