diff --git a/sphinx_doc_src/cmds/prompt_pwd.rst b/sphinx_doc_src/cmds/prompt_pwd.rst index 5af850c94..fcd38f3f3 100644 --- a/sphinx_doc_src/cmds/prompt_pwd.rst +++ b/sphinx_doc_src/cmds/prompt_pwd.rst @@ -25,16 +25,16 @@ Examples >_ cd ~/ >_ echo $PWD - /home/alfa + /home/alfa >_ prompt_pwd - ~ + ~ >_ cd /tmp/banana/sausage/with/mustard >_ prompt_pwd - /t/b/s/w/mustard + /t/b/s/w/mustard >_ set -g fish_prompt_pwd_dir_length 3 >_ prompt_pwd - /tmp/ban/sau/wit/mustard + /tmp/ban/sau/wit/mustard diff --git a/sphinx_doc_src/cmds/string.rst b/sphinx_doc_src/cmds/string.rst index befe6df22..e252ca07d 100644 --- a/sphinx_doc_src/cmds/string.rst +++ b/sphinx_doc_src/cmds/string.rst @@ -249,7 +249,7 @@ Examples :: >_ string length 'hello, world' - 12 + 12 >_ set str foo >_ string length -q $str; echo $status @@ -262,13 +262,13 @@ Examples :: >_ string sub --length 2 abcde - ab + ab >_ string sub -s 2 -l 2 abcde - bc + bc >_ string sub --start=-2 abcde - de + de @@ -276,17 +276,17 @@ Examples :: >_ string split . example.com - example - com + example + com >_ string split -r -m1 / /usr/local/bin/fish - /usr/local/bin - fish + /usr/local/bin + fish >_ string split '' abc - a - b - c + a + b + c @@ -294,7 +294,7 @@ Examples :: >_ seq 3 | string join ... - 1...2...3 + 1...2...3 @@ -302,11 +302,11 @@ Examples :: >_ string trim ' abc ' - abc + abc >_ string trim --right --chars=yz xyzzy zany - x - zan + x + zan @@ -333,32 +333,32 @@ Match Glob Examples :: >_ string match '?' a - a + a >_ string match 'a*b' axxb - axxb + axxb >_ string match -i 'a??B' Axxb - Axxb + Axxb >_ echo 'ok?' | string match '*\\?' - ok? + ok? # Note that only the second STRING will match here. >_ string match 'foo' 'foo1' 'foo' 'foo2' - foo + foo >_ string match -e 'foo' 'foo1' 'foo' 'foo2' - foo1 + foo1 foo foo2 - + >_ string match 'foo?' 'foo1' 'foo' 'foo2' - foo1 + foo1 foo foo2 - + Match Regex Examples @@ -369,35 +369,35 @@ Match Regex Examples :: >_ string match -r 'cat|dog|fish' 'nice dog' - dog + dog >_ string match -r -v "c.*[12]" {cat,dog}(seq 1 4) - dog1 - dog2 - cat3 - dog3 - cat4 - dog4 + dog1 + dog2 + cat3 + dog3 + cat4 + dog4 >_ string match -r '(\\d\\d?):(\\d\\d):(\\d\\d)' 2:34:56 - 2:34:56 - 2 - 34 - 56 + 2:34:56 + 2 + 34 + 56 >_ string match -r '^(\\w{{2,4}})\\g1$' papa mud murmur - papa - pa - murmur - mur + papa + pa + murmur + mur >_ string match -r -a -n at ratatat - 2 2 - 4 2 - 6 2 + 2 2 + 4 2 + 6 2 >_ string match -r -i '0x[0-9a-f]{{1,8}}' 'int magic = 0xBadC0de;' - 0xBadC0de + 0xBadC0de NUL Delimited Examples @@ -409,13 +409,13 @@ NUL Delimited Examples >_ # Count files in a directory, without being confused by newlines. >_ count (find . -print0 | string split0) - 42 + 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 + alpha\\ngamma Replace Literal Examples @@ -426,15 +426,15 @@ Replace Literal Examples :: >_ string replace is was 'blue is my favorite' - blue was my favorite + blue was my favorite >_ string replace 3rd last 1st 2nd 3rd - 1st - 2nd - last + 1st + 2nd + last >_ string replace -a ' ' _ 'spaces to underscores' - spaces_to_underscores + spaces_to_underscores Replace Regex Examples @@ -445,14 +445,14 @@ Replace Regex Examples :: >_ string replace -r -a '[^\\d.]+' ' ' '0 one two 3.14 four 5x' - 0 3.14 5 + 0 3.14 5 >_ string replace -r '(\\w+)\\s+(\\w+)' '$2 $1 $$' 'left right' - right left $ + right left $ >_ string replace -r '\\s*newline\\s*' '\\n' 'put a newline here' - put a - here + put a + here Repeat Examples @@ -463,14 +463,14 @@ Repeat Examples :: >_ string repeat -n 2 'foo ' - foo foo + foo foo >_ echo foo | string repeat -n 2 - foofoo + foofoo >_ string repeat -n 2 -m 5 'foo' - foofo + foofo >_ string repeat -m 5 'foo' - foofo + foofo diff --git a/sphinx_doc_src/cmds/type.rst b/sphinx_doc_src/cmds/type.rst index 18ddcefe0..7c6b1ae68 100644 --- a/sphinx_doc_src/cmds/type.rst +++ b/sphinx_doc_src/cmds/type.rst @@ -39,5 +39,5 @@ Example :: >_ type fg - fg is a builtin + fg is a builtin diff --git a/sphinx_doc_src/index.rst b/sphinx_doc_src/index.rst index 76e606a27..3311792f5 100644 --- a/sphinx_doc_src/index.rst +++ b/sphinx_doc_src/index.rst @@ -857,25 +857,25 @@ Lists adjacent to other lists or strings are expanded as cartesian products: Examples:: >_ echo {good,bad}" apples" - good apples bad apples + good apples bad apples >_ set -l a x y z >_ set -l b 1 2 3 >_ echo $a$b - x1 y1 z1 x2 y2 z2 x3 y3 z3 + x1 y1 z1 x2 y2 z2 x3 y3 z3 >_ echo $a"-"$b - x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3 + x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3 >_ echo {x,y,z}$b - x1 y1 z1 x2 y2 z2 x3 y3 z3 + x1 y1 z1 x2 y2 z2 x3 y3 z3 >_ echo {$b}word - 1word 2word 3word + 1word 2word 3word >_ echo {$c}word - # Output is an empty line + # Output is an empty line Be careful when you try to use braces to separate variable names from text. The problem shown above can be avoided by wrapping the variable in double quotes instead of braces (``echo "$c"word``). @@ -887,7 +887,7 @@ E.g. >_ echo (printf '%s' '')banana # the printf prints literally nothing >_ echo (printf '%s\n' '')banana # the printf prints just a newline, so the command substitution expands to an empty string - banana + banana # After command substitution, the previous line looks like: >_ echo ""banana @@ -895,7 +895,7 @@ Examples:: >_ set b 1 2 3 >_ echo (echo x)$b - x1 x2 x3 + x1 x2 x3 .. _expand-index-range: @@ -1148,10 +1148,10 @@ When an array is exported as an environment variable, it is either space or colo set -x smurf blue small set -x smurf_PATH forest mushroom env | grep smurf - + # smurf=blue small # smurf_PATH=forest:mushroom - + ``fish`` automatically creates arrays from all environment variables whose name ends in PATH, by splitting them on colons. Other variables are not automatically split. @@ -1169,12 +1169,12 @@ PATH variables act as normal arrays, except they are are implicitly joined and s set MYPATH 1 2 3 echo "$MYPATH" - # 1:2:3 + # 1:2:3 set MYPATH "$MYPATH:4:5" echo $MYPATH # 1 2 3 4 5 echo "$MYPATH" - # 1:2:3:4:5 + # 1:2:3:4:5 Variables can be marked or unmarked as PATH variables via the ``--path`` and ``--unpath`` options to ``set``. diff --git a/sphinx_doc_src/tutorial.rst b/sphinx_doc_src/tutorial.rst index 6beeb6b32..36d1131de 100644 --- a/sphinx_doc_src/tutorial.rst +++ b/sphinx_doc_src/tutorial.rst @@ -20,8 +20,8 @@ You will be greeted by the standard fish prompt, which means you are all set up and can start using fish:: > fish - Welcome to fish, the friendly interactive shell - Type help for instructions on how to use fish + Welcome to fish, the friendly interactive shell + Type help for instructions on how to use fish you@hostname ~>____ @@ -46,7 +46,7 @@ Running Commands ``fish`` runs commands like other shells: you type a command, followed by its arguments. Spaces are separators:: >_ echo hello world - hello world + hello world You can include a literal space in an argument with a backslash, or by using single or double quotes:: @@ -54,7 +54,7 @@ You can include a literal space in an argument with a backslash, or by using sin >_ mkdir My\ Files >_ cp ~/Some\ File 'My Files' >_ ls "My Files" - Some File + Some File Commands can be chained with semicolons. @@ -70,8 +70,8 @@ Getting Help :: >_ man set - set - handle shell variables - Synopsis... + set - handle shell variables + Synopsis... @@ -104,23 +104,23 @@ Wildcards ``fish`` supports the familiar wildcard ``*``. To list all JPEG files:: >_ ls *.jpg - lena.jpg - meena.jpg - santa maria.jpg + lena.jpg + meena.jpg + santa maria.jpg You can include multiple wildcards:: >_ ls l*.p* - lena.png - lesson.pdf + lena.png + lesson.pdf Especially powerful is the recursive wildcard ** which searches directories recursively:: >_ ls /var/**.log - /var/log/system.log - /var/run/sntp.log + /var/log/system.log + /var/run/sntp.log If that directory traversal is taking a long time, you can :kbd:`Control+C` out of it. @@ -132,7 +132,7 @@ Pipes and Redirections You can pipe between commands with the usual vertical bar:: >_ echo hello world | wc - 1 2 12 + 1 2 12 stdin and stdout can be redirected via the familiar `<` and `<`. stderr is redirected with a `2>`. @@ -178,7 +178,7 @@ Press :kbd:`Tab`, and ``fish`` will attempt to complete the command, argument, o If there's more than one possibility, it will list them:: >_ ~/stuff/s :kbd:`Tab` - ~/stuff/script.sh (Executable, 4.8kB) \mtch{~/stuff/sources/ (Directory)} + ~/stuff/script.sh (Executable, 4.8kB) \mtch{~/stuff/sources/ (Directory)} Hit tab again to cycle through the possibilities. @@ -187,7 +187,7 @@ Hit tab again to cycle through the possibilities. >_ git merge pr :kbd:`Tab` => git merge prompt_designer >_ git checkout b :kbd:`Tab` - builtin_list_io_merge (Branch) \mtch{builtin_set_color (Branch) busted_events (Tag)} + builtin_list_io_merge (Branch) \mtch{builtin_set_color (Branch) busted_events (Tag)} Try hitting tab and see what ``fish`` can do! @@ -198,15 +198,15 @@ Variables Like other shells, a dollar sign performs variable substitution:: >_ echo My home directory is $HOME - My home directory is /home/tutorial + My home directory is /home/tutorial Variable substitution also occurs in double quotes, but not single quotes:: >_ echo "My current directory is $PWD" - My current directory is /home/tutorial + My current directory is /home/tutorial >_ echo 'My current directory is $PWD' - My current directory is $PWD + My current directory is $PWD Unlike other shells, ``fish`` has no dedicated syntax for setting variables. Instead it has an ordinary command: ``set``, which takes a variable name, and then its value. @@ -217,7 +217,7 @@ Unlike other shells, ``fish`` has no dedicated syntax for setting variables. Ins >_ set name 'Mister Noodle' >_ echo $name - Mister Noodle + Mister Noodle (Notice the quotes: without them, ``Mister`` and ``Noodle`` would have been separate arguments, and ``$name`` would have been made into a list of two elements.) @@ -226,7 +226,7 @@ Unlike other shells, variables are not further split after substitution:: >_ mkdir $name >_ ls - Mister Noodle + Mister Noodle In bash, this would have created two directories "Mister" and "Noodle". In ``fish``, it created only one: the variable had the value "Mister Noodle", so that is the argument that was passed to ``mkdir``, spaces and all. Other shells use the term "arrays", rather than lists. @@ -243,7 +243,7 @@ Unlike other shells, ``fish`` stores the exit status of the last command in ``$s >_ false >_ echo $status - 1 + 1 Zero is considered success, and non-zero is failure. There is also a ``$pipestatus`` array variable for the exit statues of processes in a pipe. @@ -260,7 +260,7 @@ Unlike other shells, ``fish`` does not have an export command. Instead, a variab >_ set -x MyVariable SomeValue >_ env | grep MyVariable - MyVariable=SomeValue + MyVariable=SomeValue You can erase a variable with ``-e`` or ``--erase`` @@ -271,7 +271,7 @@ You can erase a variable with ``-e`` or ``--erase`` >_ set -e MyVariable >_ env | grep MyVariable - (no output) + (no output) @@ -285,7 +285,7 @@ Some variables, like ``$PWD``, only have one value. By convention, we talk about Other variables, like ``$PATH``, really do have multiple values. During variable expansion, the variable expands to become multiple arguments:: >_ echo $PATH - /usr/bin /bin /usr/sbin /sbin /usr/local/bin + /usr/bin /bin /usr/sbin /sbin /usr/local/bin Note that there are three environment variables that are automatically split on colons to become lists when fish starts running: ``PATH``, ``CDPATH``, ``MANPATH``. Conversely, they are joined on colons when exported to subcommands. All other environment variables (e.g., ``LD_LIBRARY_PATH``) which have similar semantics are treated as simple strings. @@ -295,7 +295,7 @@ Lists cannot contain other lists: there is no recursion. A variable is a list o Get the length of a list with ``count``:: >_ count $PATH - 5 + 5 You can append (or prepend) to a list by setting the list to itself, with some additional arguments. Here we append /usr/local/bin to $PATH:: @@ -307,11 +307,11 @@ You can append (or prepend) to a list by setting the list to itself, with some a You can access individual elements with square brackets. Indexing starts at 1 from the beginning, and -1 from the end:: >_ echo $PATH - /usr/bin /bin /usr/sbin /sbin /usr/local/bin + /usr/bin /bin /usr/sbin /sbin /usr/local/bin >_ echo $PATH[1] - /usr/bin + /usr/bin >_ echo $PATH[-1] - /usr/local/bin + /usr/local/bin You can also access ranges of elements, known as "slices:" @@ -321,9 +321,9 @@ You can also access ranges of elements, known as "slices:" :: >_ echo $PATH[1..2] - /usr/bin /bin + /usr/bin /bin >_ echo $PATH[-1..2] - /usr/local/bin /sbin /usr/sbin /bin + /usr/local/bin /sbin /usr/sbin /bin You can iterate over a list (or a slice) with a for loop:: @@ -331,11 +331,11 @@ You can iterate over a list (or a slice) with a for loop:: >_ for val in $PATH echo "entry: $val" end - entry: /usr/bin/ - entry: /bin - entry: /usr/sbin - entry: /sbin - entry: /usr/local/bin + entry: /usr/bin/ + entry: /bin + entry: /usr/sbin + entry: /sbin + entry: /usr/local/bin Lists adjacent to other lists or strings are expanded as :ref:`cartesian products ` unless quoted (see :ref:`Variable expansion `):: @@ -343,11 +343,11 @@ Lists adjacent to other lists or strings are expanded as :ref:`cartesian product >_ set a 1 2 3 >_ set 1 a b c >_ echo $a$1 - 1a 2a 3a 1b 2b 3b 1c 2c 3c + 1a 2a 3a 1b 2b 3b 1c 2c 3c >_ echo $a" banana" - 1 banana 2 banana 3 banana + 1 banana 2 banana 3 banana >_ echo "$a banana" - 1 2 3 banana + 1 2 3 banana This is similar to `Brace expansion `__. @@ -358,21 +358,21 @@ Command Substitutions Command substitutions use the output of one command as an argument to another. Unlike other shells, ``fish`` does not use backticks `` for command substitutions. Instead, it uses parentheses:: >_ echo In (pwd), running (uname) - In /home/tutorial, running FreeBSD + In /home/tutorial, running FreeBSD A common idiom is to capture the output of a command in a variable:: >_ set os (uname) >_ echo $os - Linux + Linux Command substitutions are not expanded within quotes. Instead, you can temporarily close the quotes, add the command substitution, and reopen them, all in the same argument:: >_ touch "testing_"(date +%s)".txt" >_ ls *.txt - testing_1360099791.txt + testing_1360099791.txt Unlike other shells, fish does not split command substitutions on any whitespace (like spaces or tabs), only newlines. This can be an issue with commands like ``pkg-config`` that print what is meant to be multiple arguments on a single line. To split it on spaces too, use ``string split``. @@ -382,11 +382,11 @@ Unlike other shells, fish does not split command substitutions on any whitespace :: >_ printf '%s\n' (pkg-config --libs gio-2.0) - -lgio-2.0 -lgobject-2.0 -lglib-2.0 + -lgio-2.0 -lgobject-2.0 -lglib-2.0 >_ printf '%s\n' (pkg-config --libs gio-2.0 | string split " ") - -lgio-2.0 + -lgio-2.0 -lgobject-2.0 - -lglib-2.0 + -lglib-2.0 @@ -416,7 +416,7 @@ fish supports the familiar ``&&`` and ``||`` to combine commands, and ``!`` to n fish also supports ``and``, ``or``, and ``not``. The first two are job modifiers and have lower precedence. Example usage:: >_ cp file1.txt file1_bak.txt && cp file2.txt file2_bak.txt ; and echo "Backup successful"; or echo "Backup failed" - Backup failed + Backup failed As mentioned in `the section on the semicolon <#tut_semicolon>`__, this can also be written in multiple lines, like so:: @@ -503,9 +503,9 @@ A ``fish`` function is a list of commands, which may optionally take arguments. echo Hello $argv end >_ say_hello - Hello + Hello >_ say_hello everybody! - Hello everybody! + Hello everybody! Unlike other shells, ``fish`` does not have aliases or special prompt syntax. Functions take their place. @@ -513,7 +513,7 @@ Unlike other shells, ``fish`` does not have aliases or special prompt syntax. Fu You can list the names of all functions with the ``functions`` keyword (note the plural!). ``fish`` starts out with a number of functions:: >_ functions - alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, trap, type, umask, up-or-search, vared + alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, trap, type, umask, up-or-search, vared You can see the source for any function by passing its name to ``functions``:: @@ -533,10 +533,10 @@ While loops:: >_ while true echo "Loop forever" end - Loop forever - Loop forever - Loop forever - ... + Loop forever + Loop forever + Loop forever + ... For loops can be used to iterate over a list. For example, a list of files::