From ff47b2dad53d185c09893877402b8d79e3a3e27b Mon Sep 17 00:00:00 2001 From: Fabian Homborg Date: Mon, 14 May 2018 00:36:49 +0200 Subject: [PATCH] [docs] Some rewording to the builtins Plus some additional examples. --- doc_src/and.txt | 2 +- doc_src/begin.txt | 5 +++-- doc_src/bg.txt | 4 +++- doc_src/bind.txt | 2 +- doc_src/case.txt | 6 +++--- doc_src/command.txt | 4 +++- doc_src/contains.txt | 16 +++++++++++++--- doc_src/continue.txt | 3 +++ doc_src/count.txt | 2 +- doc_src/eval.txt | 1 + doc_src/or.txt | 2 +- 11 files changed, 33 insertions(+), 14 deletions(-) diff --git a/doc_src/and.txt b/doc_src/and.txt index 2670a35e1..3757847de 100644 --- a/doc_src/and.txt +++ b/doc_src/and.txt @@ -7,7 +7,7 @@ COMMAND1; and COMMAND2 \subsection and-description Description -`and` is used to execute a command if the current exit status (as set by the previous command) is 0. +`and` is used to execute a command if the previous command was successful (returned a status of 0). `and` statements may be used as part of the condition in an `if` or `while` block. See the documentation for `if` and `while` for examples. diff --git a/doc_src/begin.txt b/doc_src/begin.txt index 374fc78ce..dd008bda9 100644 --- a/doc_src/begin.txt +++ b/doc_src/begin.txt @@ -9,9 +9,9 @@ begin; [COMMANDS...;] end `begin` is used to create a new block of code. -The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`. +A block allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`. -`begin` is used to group a number of commands into a block. This allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like `and`. +The block is unconditionally executed. `begin; ...; end` is equivalent to `if true; ...; end`. `begin` does not change the current exit status itself. After the block has completed, `$status` will be set to the status returned by the most recent command. @@ -23,6 +23,7 @@ The following code sets a number of variables inside of a block scope. Since the \fish begin set -l PIRATE Yarrr + ... end diff --git a/doc_src/bg.txt b/doc_src/bg.txt index 6d9e01f72..13733f58e 100644 --- a/doc_src/bg.txt +++ b/doc_src/bg.txt @@ -7,7 +7,9 @@ bg [PID...] \subsection bg-description Description -`bg` sends jobs to the background, resuming them if they are stopped. A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background. +`bg` sends jobs to the background, resuming them if they are stopped. + +A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background. When at least one of the arguments isn't a valid job specifier (i.e. PID), `bg` will print an error without backgrounding anything. diff --git a/doc_src/bind.txt b/doc_src/bind.txt index f6ec1403b..88039d03b 100644 --- a/doc_src/bind.txt +++ b/doc_src/bind.txt @@ -26,7 +26,7 @@ If the `-k` switch is used, the name of the key (such as 'down', 'up' or 'backsp When `COMMAND` is a shellscript command, it is a good practice to put the actual code into a function and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well. -If such a script produces output, the script needs to finish by calling `commandline -f repaint` in order to tell fish that a repaint is in order. +If a script produces output, it should finish by calling `commandline -f repaint` to tell fish that a repaint is in order. When multiple `COMMAND`s are provided, they are all run in the specified order when the key is pressed. Note that special input functions cannot be combined with ordinary shell script commands. The commands must be entirely a sequence of special input functions (from `bind -f`) or all shell script commands (i.e., valid fish script). diff --git a/doc_src/case.txt b/doc_src/case.txt index 24fde2803..065c19e9b 100644 --- a/doc_src/case.txt +++ b/doc_src/case.txt @@ -7,7 +7,7 @@ switch VALUE; [case [WILDCARD...]; [COMMANDS...]; ...] end \subsection case-description Description -`switch` performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. `case` is used together with the `switch` statement in order to determine which block should be executed. +`switch` executes one of several blocks of commands, depending on whether a specified value matches one of several values. `case` is used together with the `switch` statement in order to determine which block should be executed. Each `case` command is given one or more parameters. The first `case` command with a parameter that matches the string specified in the switch command will be evaluated. `case` parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames. @@ -18,8 +18,7 @@ Note that command substitutions in a case statement will be evaluated even if it \subsection case-example Example -If the variable \$animal contains the name of an animal, the following -code would attempt to classify it: +Say \$animal contains the name of an animal. Then this code would classify it: \fish switch $animal @@ -40,3 +39,4 @@ end If the above code was run with `$animal` set to `whale`, the output would be `mammal`. +If `$animal` was set to "banana", it would print "I have no idea what a banana is". diff --git a/doc_src/command.txt b/doc_src/command.txt index 19b1cf13f..e4f5c2cf6 100644 --- a/doc_src/command.txt +++ b/doc_src/command.txt @@ -17,7 +17,7 @@ The following options are available: - `-s` or `--search` returns the name of the external command that would be executed, or nothing if no file with the specified name could be found in the `$PATH`. -With the `-s` option, `command` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. Additionally passing a `-q` or `--quiet` option prevents any paths from being printed, like the `type -q`, for testing only the exit status. +With the `-s` option, `command` treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found. Additionally passing a `-q` or `--quiet` option prevents any paths from being printed, like `type -q`, for testing only the exit status. For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`. @@ -26,3 +26,5 @@ For basic compatibility with POSIX `command`, the `-v` flag is recognized as an `command ls` causes fish to execute the `ls` program, even if an `ls` function exists. `command -s ls` returns the path to the `ls` program. + +`command -sq git; and command git log` runs `git log` only if `git` exists. diff --git a/doc_src/contains.txt b/doc_src/contains.txt index 3b5060bad..c65292c09 100644 --- a/doc_src/contains.txt +++ b/doc_src/contains.txt @@ -13,10 +13,20 @@ The following options are available: - `-i` or `--index` print the word index -Note that, like GNU tools, `contains` interprets all arguments starting with a `-` as options to contains, until it reaches an argument that is `--` (two dashes). See the examples below. +Note that, like GNU tools and most of fish's builtins, `contains` interprets all arguments starting with a `-` as options to contains, until it reaches an argument that is `--` (two dashes). See the examples below. \subsection contains-example 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 + +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 @@ -25,7 +35,7 @@ for i in ~/bin /usr/local/bin end \endfish -The above code tests if `~/bin` and `/usr/local/bin` are in the path and adds them if not. +While this will check if `hasargs` was run with the `-q` option: \fish function hasargs @@ -35,4 +45,4 @@ function hasargs end \endfish -The above code checks for `-q` in the argument list, using the `--` argument to demarcate options to `contains` from the key to search for. +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/doc_src/continue.txt b/doc_src/continue.txt index 1585b04a8..26346be6a 100644 --- a/doc_src/continue.txt +++ b/doc_src/continue.txt @@ -18,6 +18,9 @@ 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 \endfish diff --git a/doc_src/count.txt b/doc_src/count.txt index 279ead7d5..bf11a6350 100644 --- a/doc_src/count.txt +++ b/doc_src/count.txt @@ -9,7 +9,7 @@ count $VARIABLE `count` prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains. -`count` does not accept any options, including `-h` or `--help`. +`count` does not accept any options, not even `-h` or `--help`. `count` exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed. diff --git a/doc_src/eval.txt b/doc_src/eval.txt index 1ba8f97ee..5e7785077 100644 --- a/doc_src/eval.txt +++ b/doc_src/eval.txt @@ -8,6 +8,7 @@ eval [COMMANDS...] \subsection eval-description Description `eval` evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator. +If your command does not need access to stdin, consider using `source` instead. \subsection eval-example Example diff --git a/doc_src/or.txt b/doc_src/or.txt index 40b6bfcc7..b79e707d6 100644 --- a/doc_src/or.txt +++ b/doc_src/or.txt @@ -7,7 +7,7 @@ COMMAND1; or COMMAND2 \subsection or-description Description -`or` is used to execute a command if the current exit status (as set by the previous command) is not 0. +`or` is used to execute a command if the previous command was not successful (returned a status of something other than 0). `or` statements may be used as part of the condition in an `and` or `while` block. See the documentation for `if` and `while` for examples.