From aa974b58bc6d4919c6bfd9336f420e5303c4b12a Mon Sep 17 00:00:00 2001 From: Jak Wings Date: Sun, 13 Dec 2015 11:13:15 +0800 Subject: Doc: Introduce another simple way to separate variable names from text. This can avoid the confusion between brace expansion and the cartesian product behavior of arrays, even if braces can help to do some hacks. --- doc_src/index.hdr.in | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'doc_src') diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in index 34b25755..1b28e140 100644 --- a/doc_src/index.hdr.in +++ b/doc_src/index.hdr.in @@ -460,7 +460,7 @@ A dollar sign followed by a string of characters is expanded into the value of t Undefined and empty variables expand to nothing. -To separate a variable name from text it should immediately be followed by, encase the variable within braces. +To separate a variable name from text it should immediately be followed by, encase the variable within quotes. Examples: \fish @@ -470,15 +470,17 @@ echo $HOME echo $nonexistentvariable # Prints no output. -echo The plural of $WORD is {$WORD}s +echo The plural of $WORD is "$WORD"s # Prints "The plural of cat is cats" when $WORD is set to cat. +echo The plural of $WORD is {$WORD}s +# ditto \endfish -Note that without the braces, fish will try to expand a variable called `$WORDs`, which may not exist. +Note that without the quotes or braces, fish will try to expand a variable called `$WORDs`, which may not exist. -The latter syntax works by exploiting brace expansion; care should be taken with array variables and undefined variables, as these behave very differently to POSIX shells. +The latter syntax `{$WORD}` works by exploiting brace expansion; care should be taken with array variables and undefined variables, as these behave very differently to POSIX shells. -Variable expansion is the only type of expansion performed on double quoted strings. There is, however, an important difference in how variables are expanded when quoted and when unquoted. An unquoted variable expansion will result in a variable number of arguments. For example, if the variable `$foo` has zero elements or is undefined, the argument `$foo` will expand to zero elements. If the variable $foo is an array of five elements, the argument `$foo` will expand to five elements. When quoted, like `"$foo"`, a variable expansion will always result in exactly one argument. Undefined variables will expand to the empty string, and array variables will be concatenated using the space character. The dangers noted in the third example above can therefore be avoided by wrapping the variable in double quotes (`echo {"$WORD"}s`). +Variable expansion is the only type of expansion performed on double quoted strings. There is, however, an important difference in how variables are expanded when quoted and when unquoted. An unquoted variable expansion will result in a variable number of arguments. For example, if the variable `$foo` has zero elements or is undefined, the argument `$foo` will expand to zero elements. If the variable $foo is an array of five elements, the argument `$foo` will expand to five elements. When quoted, like `"$foo"`, a variable expansion will always result in exactly one argument. Undefined variables will expand to the empty string, and array variables will be concatenated using the space character. There is one further notable feature of fish variable expansion. Consider the following code snippet: -- cgit v1.2.3 From 70ee7650f37ed302f6879af1b303aaf687921148 Mon Sep 17 00:00:00 2001 From: Jak Wings Date: Sun, 13 Dec 2015 11:49:52 +0800 Subject: Doc: Introduce Cartesian Products on the main documentaion page. --- doc_src/index.hdr.in | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'doc_src') diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in index 1b28e140..0f6f1f79 100644 --- a/doc_src/index.hdr.in +++ b/doc_src/index.hdr.in @@ -500,6 +500,32 @@ end The above code demonstrates how to use multiple '`$`' symbols to expand the value of a variable as a variable name. One can think of the `$` symbol as a variable dereference operator. When using this feature together with array brackets, the brackets will always match the innermost `$` dereference. Thus, `$$foo[5]` will always mean the fifth element of the `foo` variable should be dereferenced, not the fifth element of the doubly dereferenced variable `foo`. The latter can instead be expressed as `$$foo[1][5]`. +\subsection cartesian-product Cartesian Products + +Lists adjacent to other lists or strings are expanded as cartesian products: + +Examples: +\fish +echo {good,bad}" apples" +# Outputs 'good apples bad apples' + +set -l a x y z +set -l b 1 2 3 +echo $a$b +# Outputs 'x1 y1 z1 x2 y2 z2 x3 y3 z3' +echo $a"-"$b +# Outputs 'x-1 y-1 z-1 x-2 y-2 z-2 x-3 y-3 z-3' + +echo {x,y,z}$b +# Outputs 'x1 y1 z1 x2 y2 z2 x3 y3 z3' + +echo {$b}word +# Outputs '1word 2word 3word' +\endfish + +Be careful when you try to use braces to separate variable names from text. The dangers noted in the last example above can be avoided by wrapping the variable in double quotes instead of braces (`echo "$b"word`). + + \subsection expand-index-range Index range expansion Both command substitution and shell variable expansion support accessing only specific items by providing a set of indices in square brackets. It's often needed to access a sequence of elements. To do this, use the range operator '`..`' for this. A range '`a..b`', where range limits 'a' and 'b' are integer numbers, is expanded into a sequence of indices '`a a+1 a+2 ... b`' or '`a a-1 a-2 ... b`' depending on which of 'a' or 'b' is higher. The negative range limits are calculated from the end of the array or command substitution. -- cgit v1.2.3 From 666dcd78badb1c377e9798bc82bb0a9742a4b0ae Mon Sep 17 00:00:00 2001 From: Jak Wings Date: Mon, 14 Dec 2015 01:27:33 +0800 Subject: Doc: Link Cartesian Product in tutorial to main documentaion. --- doc_src/tutorial.hdr | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc_src') diff --git a/doc_src/tutorial.hdr b/doc_src/tutorial.hdr index 6ecd13c6..1b0e121a 100644 --- a/doc_src/tutorial.hdr +++ b/doc_src/tutorial.hdr @@ -348,7 +348,7 @@ You can iterate over a list (or a slice) with a for loop: entry: /usr/local/bin \endfish -Lists adjacent to other lists or strings are expanded as cartesian products unless quoted (see Variable expansion): +Lists adjacent to other lists or strings are expanded as cartesian products unless quoted (see Variable expansion): \fish{cli-dark} >_ set -l a 1 2 3 -- cgit v1.2.3