Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2025-01-12 21:18:53 +00:00
Code Issues Projects Releases Packages Wiki Activity

Rebase documentation changes

Browse source
This commit is contained in:
Mark Griffiths 2014-09-03 15:10:53 +01:00
parent 3df9e20ca7
commit adbcecb456
14 changed files with 342 additions and 488 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.gitignore vendored
View file

@ -38,5 +38,5 @@ version
messages.pot
lexicon.txt
lexicon_filter
lexicon-debug.log
lexicon.log

8
Makefile.in
View file

@ -264,14 +264,6 @@ user_doc: $(HDR_FILES_SRC) Doxyfile.user $(HTML_SRC) $(HELP_SRC) doc.h $(HDR_FIL
echo PROJECT_NUMBER=$(FISH_BUILD_VERSION) | sed "s/-.*//") | doxygen - && touch user_doc; \
cd user_doc/html; rm -f bc_s.png bdwn.png closed.png ftv2*.png nav*.png open.png sync_*.png tab*.* doxygen.* dynsections.js jquery.js pages.html
#
# Build the help CSS files, using fish_lexicon_filter
#
doc_src/user_doc.css: doc_src/user_doc.css.in doc_src/fish_lexicon_filter
-rm $@
cd doc_src; \
cat user_doc.css.in >> user_doc.css
#
# Source code documentation. Also includes user documentation.
#

16
doc_src/command.txt
View file

@ -1,22 +1,24 @@
\section command command - run a program
\subsection command-synopsis Synopsis
<tt>command [OPTIONS] COMMANDNAME [ARGS...]</tt>
\fish{synopsis}
command [OPTIONS] COMMANDNAME [ARGS...]
\endfish
\subsection command-description Description
`command` forces the shell to execute the program `COMMANDNAME` and ignore any functions or builtins with the same name.
The following options are available:
- \c -h or \c --help prints help and then exits.
- \c -s or \c --search returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the <tt>$PATH</tt>.
With the \c -s option, \c 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.
- `-s` or `--search` returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the `$PATH`.
For basic compatibility with POSIX <tt>command</tt>, the \c -v flag is recognized as an alias for <tt>-s</tt>.
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.
For basic compatibility with POSIX `command`, the `-v` flag is recognized as an alias for `-s`.
\subsection command-example Examples
<tt>command ls</tt> causes fish to execute the \c ls program, even if an 'ls' function exists.
`command ls` causes fish to execute the `ls` program, even if an `ls` function exists.
<tt>command -s ls</tt> returns the path to the \c ls program.
`command -s ls` returns the path to the `ls` program.

69
doc_src/complete.txt
View file

@ -1,7 +1,14 @@
\section complete complete - edit command specific tab-completions
\subsection complete-synopsis Synopsis
<tt>complete (-c|--command|-p|--path) COMMAND [(-s|--short-option) SHORT_OPTION] [(-l|--long-option|-o|--old-option) LONG_OPTION [(-a||--arguments) OPTION_ARGUMENTS] [(-w|--wraps) WRAPPED_COMMAND] [(-d|--description) DESCRIPTION] </tt>
\fish{synopsis}
complete ( -c | --command | -p | --path ) COMMAND
[( -s | --short-option ) SHORT_OPTION]
[( -l | --long-option | -o | --old-option ) LONG_OPTION]
[( -a | --arguments ) OPTION_ARGUMENTS]
[( -w | --wraps ) WRAPPED_COMMAND]
[( -d | --description ) DESCRIPTION]
\endfish
\subsection complete-description Description
@ -9,29 +16,39 @@ For an introduction to specifying completions, see <a
href='index.html#completion-own'>Writing your own completions</a> in
the fish manual.
- <tt>COMMAND</tt> is the name of the command for which to add a completion
- <tt>SHORT_OPTION</tt> is a one character option for the command
- <tt>LONG_OPTION</tt> is a multi character option for the command
- <tt>OPTION_ARGUMENTS</tt> is parameter containing a space-separated list of possible option-arguments, which may contain subshells
- <tt>DESCRIPTION</tt> is a description of what the option and/or option arguments do
- <tt>-C STRING</tt> or <tt>--do-complete=STRING</tt> makes complete try to find all possible completions for the specified string
- <tt>-e</tt> or <tt>--erase</tt> implies that the specified completion should be deleted
- <tt>-f</tt> or <tt>--no-files</tt> specifies that the option specified by this completion may not be followed by a filename
- <tt>-n</tt> or <tt>--condition</tt> specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
- <tt>-o</tt> or <tt>--old-option</tt> implies that the command uses old long style options with only one dash
- <tt>-p</tt> or <tt>--path</tt> implies that the string COMMAND is the full path of the command
- <tt>-r</tt> or <tt>--require-parameter</tt> specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option
- <tt>-u</tt> or <tt>--unauthoritative</tt> implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors
- <tt>-A</tt> or <tt>--authoritative</tt> implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors
- <tt>-x</tt> or <tt>--exclusive</tt> implies both <tt>-r</tt> and <tt>-f</tt>
- <tt>-w WRAPPED_COMMAND</tt> or <tt>--wraps=WRAPPED_COMMAND</tt> causes the specified command to inherit completions from the wrapped comamnd.
- `COMMAND` is the name of the command for which to add a completion.
Command specific tab-completions in \c fish are based on the notion
of options and arguments. An option is a parameter which begins with a
hyphen, such as '`-h`', '`-help`' or '`--help`'. Arguments are parameters
that do not begin with a hyphen. Fish recognizes three styles of
options, the same styles as the GNU version of the getopt
library. These styles are:
- `SHORT_OPTION` is a one character option for the command.
- `LONG_OPTION` is a multi character option for the command.
- `OPTION_ARGUMENTS` is parameter containing a space-separated list of possible option-arguments, which may contain subshells.
- `DESCRIPTION` is a description of what the option and/or option arguments do.
- `-C STRING` or `--do-complete=STRING` makes complete try to find all possible completions for the specified string.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the specified command to inherit completions from the wrapped command.
- `-e` or `--erase` implies that the specified completion should be deleted.
- `-f` or `--no-files` specifies that the option specified by this completion may not be followed by a filename.
- `-n` or `--condition` specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.
- `-o` or `--old-option` implies that the command uses old long style options with only one dash.
- `-p` or `--path` implies that the string `COMMAND` is the full path of the command.
- `-r` or `--require-parameter` specifies that the option specified by this completion always must have an option argument, i.e. may not be followed by another option.
- `-u` or `--unauthoritative` implies that there may be more options than the ones specified, and that fish should not assume that options not listed are spelling errors.
- `-A` or `--authoritative` implies that there may be no more options than the ones specified, and that fish should assume that options not listed are spelling errors.
- `-x` or `--exclusive` implies both `-r` and `-f`.
Command specific tab-completions in `fish` are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as '`-h`', '`-help`' or '`--help`'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU version of the getopt library. These styles are:
- Short options, like '`-a`'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '`-la`', which is equivalent to '`-l -a`'). Option arguments may be specified in the following parameter ('`-w 32`') or by appending the option with the value ('`-w32`').
@ -76,9 +93,11 @@ complete -c rpm -n "__fish_contains_opt -s e erase" -l nodeps -d "Don't check de
where `__fish_contains_opt` is a function that checks the commandline buffer for the presence of a specified set of options.
To implement an alias, use the \c -w or \c --wraps option:
To implement an alias, use the `-w` or `--wraps` option:
<tt>complete -c hub -w git</tt>
\fish
complete -c hub -w git
\endfish
Now hub inherits all of the completions from git. Note this can also be specified in a function declaration.

13
doc_src/design.hdr
View file

@ -90,18 +90,7 @@ A program should be designed to make its features as easy as possible to discove
Rationale:
A program whose features are discoverable turns a new user into an expert in a shorter span of time, since the user will become an expert on the program simply by using it.
A program whose features are discoverable turns a new user into an
expert in a shorter span of time, since the user will become an expert
on the program simply by using it.
The main benefit of a graphical program over a command line-based
program is discoverability. In a graphical program, one can discover
all the common features by simply looking at the user interface and
guessing what the different buttons, menus and other widgets do. The
traditional way to discover features in commandline programs is
through manual pages. This requires both that the user starts to use a
different program, and then she/he remembers the new information
until the next time she/he uses the same program.
The main benefit of a graphical program over a command line-based program is discoverability. In a graphical program, one can discover all the common features by simply looking at the user interface and guessing what the different buttons, menus and other widgets do. The traditional way to discover features in commandline programs is through manual pages. This requires both that the user starts to use a different program, and then she/he remembers the new information until the next time she/he uses the same program.
Examples:
- Everything should be tab-completable, and every tab completion should have a description.

29
doc_src/function.txt
View file

@ -13,15 +13,23 @@ A function is a list of commands that will be executed when the name of the func
The following options are available:
- <code>-a NAMES</code> or <code>--argument-names NAMES</code> assigns the value of successive command-line arguments to the names given in NAMES.
- <code>-d DESCRIPTION</code> or \c --description=DESCRIPTION is a description of what the function does, suitable as a completion description.
- <code>-w WRAPPED_COMMAND</code> or \c --wraps=WRAPPED_COMMAND causes the function to inherit completions from the given wrapped command. See the documentation for \c complete for more information.
- <code>-e</code> or <code>--on-event EVENT_NAME</code> tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
- <code>-j PID</code> or <code> --on-job-exit PID</code> tells fish to run this function when the job with group ID PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
- <code>-p PID</code> or <code> --on-process-exit PID</code> tells fish to run this function when the fish child process with process ID PID exits.
- <code>-s</code> or <code>--on-signal SIGSPEC</code> tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).
- \c -S or \c --no-scope-shadowing allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.
- <code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value.
- `-a NAMES` or `--argument-names NAMES` assigns the value of successive command-line arguments to the names given in NAMES.
- `-d DESCRIPTION` or `--description=DESCRIPTION` is a description of what the function does, suitable as a completion description.
- `-w WRAPPED_COMMAND` or `--wraps=WRAPPED_COMMAND` causes the function to inherit completions from the given wrapped command. See the documentation for <a href="#complete">`complete`</a> for more information.
- `-e` or `--on-event EVENT_NAME` tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.
- `-j PID` or `--on-job-exit PID` tells fish to run this function when the job with group ID PID exits. Instead of PID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.
- `-p PID` or `--on-process-exit PID` tells fish to run this function when the fish child process with process ID PID exits.
- `-s` or `--on-signal SIGSPEC` tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).
- `-S` or `--no-scope-shadowing` allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.
- `-v` or `--on-variable VARIABLE_NAME` tells fish to run this function when the variable VARIABLE_NAME changes value.
If the user enters any additional arguments after the function, they are inserted into the environment <a href="index.html#variables-arrays">variable array</a> `$argv`. If the `--argument-names` option is provided, the arguments are also assigned to names specified in that option.
@ -57,6 +65,5 @@ function mkdir -d "Create a directory and set CWD"
end
\endfish
will run the mkdir command, and if it is successful, change the
current working directory to the one just created.
This will run the `mkdir` command, and if it is successful, change the current working directory to the one just created.

41
doc_src/history.txt
View file

@ -1,40 +1,31 @@
\section history history - Show and manipulate command history
\subsection history-synopsis Synopsis
<pre>
history (--save | --clear | --merge)
history (--search | --delete ) (--prefix "prefix string" | --contains "search string")
</pre>
\fish{synopsis}
history ( --merge | --save | --clear )
history ( --search | --delete ) [ --prefix "prefix string" | --contains "search string" ]
\endfish
\subsection history-description Description
`history` is used to list, search and delete the history of commands used.
The following options are available:
- `--save` saves all changes in the history file. The shell automatically saves the history file; this option is provided for internal use.
- `--save` saves all changes in the history file. The shell automatically
saves the history file; this option is provided for internal use.
- `--clear` clears the history file. A prompt is displayed before the history
is erased.
- \c --merge immediately incorporates history changes from other sessions. Ordinarily
fish ignores history changes from sessions started after the current one. This command
applies those changes immediately.
- \c --search returns history items in keeping with the \c --prefix or
\c --contains options.
- \c --delete deletes history items.
- \c --prefix searches or deletes items in the history that begin with the
specified text string.
- `--contains` searches or deletes items in the history that contain the
specified text string.
- `--clear` clears the history file. A prompt is displayed before the history is erased.
If `--search` is specified without `--contains` or `--prefix`,
`--contains` will be assumed.
- `--merge` immediately incorporates history changes from other sessions. Ordinarily `fish` ignores history changes from sessions started after the current one. This command applies those changes immediately.- `--search` returns history items in keeping with the `--prefix` or `--contains` options.
If `--delete` is specified without `--contains` or `--prefix`,
only a history item which exactly matches the parameter will be erased. No
prompt will be given. If `--delete` is specified with either of these
parameters, an interactive prompt will be displayed before any items are
deleted.
- `--delete` deletes history items.
- `--prefix` searches or deletes items in the history that begin with the specified text string.
- `--contains` searches or deletes items in the history that contain the specified text string.
If `--search` is specified without `--contains` or `--prefix`, `--contains` will be assumed.
If `--delete` is specified without `--contains` or `--prefix`, only a history item which exactly matches the parameter will be erased. No prompt will be given. If `--delete` is specified with either of these parameters, an interactive prompt will be displayed before any items are deleted.
\subsection history-examples Example

151
doc_src/index.hdr.in
View file

@ -138,49 +138,46 @@ separation of errors and warnings from regular program output.
Any file descriptor can be directed to a different output than its default through a simple mechanism called a redirection.
An example of a file redirection is `echo hello > output.txt`, which directs the output of the echo command to the file output.txt.
- To read standard input from a file, write <code>\<SOURCE_FILE</code>
- To write standard output to a file, write <code>\>DESTINATION</code>
- To write standard error to a file, write <code>^DESTINATION</code>
- To append standard output to a file, write <code>\>\>DESTINATION_FILE</code>
- To append standard error to a file, write <code>^^DESTINATION_FILE</code>
- To read standard input from a file, write `<SOURCE_FILE`
- To write standard output to a file, write `DESTINATION`
- To write standard error to a file, write `^DESTINATION`
- To append standard output to a file, write `>>DESTINATION_FILE`
- To append standard error to a file, write `^^DESTINATION_FILE`
- To redirect standard input, write `<SOURCE_FILE`
- To redirect standard output, write `>DESTINATION`
- To redirect standard error, write `^DESTINATION`
- To redirect standard output to a file which will be appended, write `>>DESTINATION_FILE`
- To redirect standard error to a file which will be appended, write `^^DESTINATION_FILE`
`DESTINATION` can be one of the following:
- A filename. The output will be written to the specified file.
- An ampersand (\&) followed by the number of another file descriptor. The output will be written to that file descriptor instead.
- An ampersand followed by a minus sign (\&-). The file descriptor will be closed.
- An ampersand (`&`) followed by the number of another file descriptor. The output will be written to that file descriptor instead.
- An ampersand followed by a minus sign (`&-`). The file descriptor will be closed.
Example:
To redirect both standard output and standard error to the file 'all_output.txt', you can write `echo Hello > all_output.txt ^&1`.
Any FD can be redirected in an arbitrary way by prefixing the redirection with the number of the FD.
Any file descriptor can be redirected in an arbitrary way by prefixing the
redirection with the file descriptor.
- To redirect input of FD N, write <code>N\<DESTINATION</code>
- To redirect output of FD N, write <code>N\>DESTINATION</code>
- To append the output of FD N to a file, write <code>N\>\>DESTINATION_FILE</code>
- To redirect input of FD N, write `N<DESTINATION`
- To redirect output of FD N, write `N>DESTINATION`
- To append the output of FD N to a file, write `N>>DESTINATION_FILE`
Example: <code>echo Hello 2\>output.stderr</code> and <code>echo Hello
^output.stderr</code> are equivalent, and write the standard error (file
descriptor 2) of the target program to <code>output.stderr</code>.
Example: `echo Hello 2>output.stderr` and `echo Hello
^output.stderr` are equivalent, and write the standard error (file
descriptor 2) of the target program to `output.stderr`.
\subsection piping Piping
The user can string together multiple commands into a so called pipeline. This means that the standard output of one command will be read in as standard input into the next command. This is done by separating the commands by the pipe character '`|`'. For example
The user can string together multiple commands into a so called pipeline. This means that the standard output of one command will be read in as standard input into the next command. This is done by separating the commands by the pipe character '`|`'. For example:
\fish
cat foo.txt | head
\endfish
will call the `cat` program with the parameter 'foo.txt', which will print the contents of the file 'foo.txt'. The contents of foo.txt will then be filtered through the program 'head', which will pass on the first ten lines of the file to the screen. For more information on how to combine commands through pipes, read the manual pages of the commands you want to use using the `man` command. If you want to find out more about the `cat` program, type `man cat`.
This will call the `cat` program with the parameter 'foo.txt', which will print the contents of the file 'foo.txt'. The contents of foo.txt will then be filtered through the program 'head', which will pass on the first ten lines of the file to the screen. For more information on how to combine commands through pipes, read the manual pages of the commands you want to use using the `man` command. If you want to find out more about the `cat` program, type `man cat`.
Pipes usually connect file descriptor 1 (standard output) of the first process to file descriptor 0 (standard input) of the second process. It is possible use a different output file descriptor by prepending the desired FD number and then output redirect symbol to the pipe. For example:
@ -188,7 +185,7 @@ Pipes usually connect file descriptor 1 (standard output) of the first process t
make fish 2> | less
\endfish
will attempt to build the fish program, and any errors will be shown using the less pager.
This will attempt to build the fish program, and any errors will be shown using the less pager.
\subsection syntax-background Background jobs
@ -420,12 +417,7 @@ Note that if no matches are found for a specific wildcard, it will expand into z
\subsection expand-command-substitution Command substitution
The output of a series of commands can be used as the parameters to another
command. If a parameter contains a set of parenthesis, the text enclosed by the
parenthesis will be interpreted as a list of commands. On expansion,
this list is executed, and substituted by the output. If the output is
more than one line long, each line will be expanded to a new
parameter. Setting \c IFS to the empty string will disable line splitting.
The output of a series of commands can be used as the parameters to another command. If a parameter contains a set of parenthesis, the text enclosed by the parenthesis will be interpreted as a list of commands. On expansion, this list is executed, and substituted by the output. If the output is more than one line long, each line will be expanded to a new parameter. Setting `IFS` to the empty string will disable line splitting.
The exit status of the last run command substitution is available in the <a href='#variables-status'>status</a> variable.
@ -436,13 +428,14 @@ Examples:
echo (basename image.jpg .jpg).png
# Outputs 'image.png'.
The command `echo (basename image.jpg .jpg).png` will output 'image.png'.
for i in *.jpg; convert $i (basename $i .jpg).png; end
# Convert all JPEG files in the current directory to the
# PNG format using the 'convert' program.
The command `for i in *.jpg; convert $i (basename $i .jpg).png; end` will convert all JPEG files in the current directory to the PNG format using the `convert` program.
The command <code>begin; set -l IFS; set data (cat data.txt); end</code>
will set the \c data variable to the contents of 'data.txt' without
splitting it into an array.
begin; set -l IFS; set data (cat data.txt); end
# Set the `data` variable to the contents of 'data.txt'
# without splitting it into an array.
\endfish
\subsection expand-brace Brace expansion
@ -723,31 +716,46 @@ All arrays are one-dimensional and cannot contain other arrays, although it is p
\subsection variables-special Special variables
The user can change the settings of \c fish by changing the values of
The user can change the settings of `fish` by changing the values of
certain environment variables.
- \c BROWSER, the user's preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
- \c CDPATH, an array of directories in which to search for the new directory for the \c cd builtin. By default, the fish configuration defines \c CDPATH to be a universal variable with the values \c . and \c ~.
- A large number of variable starting with the prefixes \c fish_color and \c fish_pager_color. See <a href='#variables-color'>Variables for changing highlighting colors</a> for more information.
- \c fish_greeting, the greeting message printed on startup.
- \c LANG, \c LC_ALL, \c LC_COLLATE, \c LC_CTYPE, \c LC_MESSAGES, \c LC_MONETARY, \c LC_NUMERIC and \c LC_TIME set the language option for the shell and subprograms. See the section <a href='#variables-locale'>Locale variables</a> for more information.
- \c fish_user_paths, an array of directories that are prepended to PATH. This can be a universal variable.
- \c PATH, an array of directories in which to search for commands
- \c umask, the current file creation mask. The preferred way to change the umask variable is through the <a href="commands.html#umask">umask function</a>. An attempt to set umask to an invalid value will always fail.
- `BROWSER`, the user's preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
\c fish also sends additional information to the user through the
- `CDPATH`, an array of directories in which to search for the new directory for the `cd` builtin. By default, the fish configuration defines `CDPATH` to be a universal variable with the values `.` and `~`.
- A large number of variable starting with the prefixes `fish_color` and `fish_pager_color.` See <a href='#variables-color'>Variables for changing highlighting colors</a> for more information.
- `fish_greeting`, the greeting message printed on startup.
- `LANG`, `LC_ALL`, `LC_COLLATE`, `LC_CTYPE`, `LC_MESSAGES`, `LC_MONETARY`, `LC_NUMERIC` and `LC_TIME` set the language option for the shell and subprograms. See the section <a href='#variables-locale'>Locale variables</a> for more information.
- `fish_user_paths`, an array of directories that are prepended to `PATH`. This can be a universal variable.
- `PATH`, an array of directories in which to search for commands
- `umask`, the current file creation mask. The preferred way to change the umask variable is through the <a href="commands.html#umask">umask function</a>. An attempt to set umask to an invalid value will always fail.
`fish` also sends additional information to the user through the
values of certain environment variables. The user cannot change the
values of most of these variables.
- \c _, the name of the currently running command.
- \c argv, an array of arguments to the shell or function. \c argv is only defined when inside a function call, or if fish was invoked with a list of arguments, like 'fish myscript.fish foo bar'. This variable can be changed by the user.
- \c history, an array containing the last commands that were entered.
- \c HOME, the user's home directory. This variable can be changed by the user.
- \c IFS, the internal field separator that is used for word splitting with the <a href="commands.html#read">read builtin</a>. Setting this to the empty string will also disable line splitting in <a href="#expand-command-substitution">command substitution</a>. This variable can be changed by the user.
- \c PWD, the current working directory.
- \c status, the <a href="#variables-status">exit status</a> of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number.
- \c USER, the current username. This variable can be changed by the user.
- \c CMD_DURATION, the runtime of the last command in milliseconds.
- `_`, the name of the currently running command.
- `argv`, an array of arguments to the shell or function. `argv` is only defined when inside a function call, or if fish was invoked with a list of arguments, like `fish myscript.fish foo bar`. This variable can be changed by the user.
- `history`, an array containing the last commands that were entered.
- `HOME`, the user's home directory. This variable can be changed by the user.
- `IFS`, the internal field separator that is used for word splitting with the <a href="commands.html#read">read builtin</a>. Setting this to the empty string will also disable line splitting in <a href="#expand-command-substitution">command substitution</a>. This variable can be changed by the user.
- `PWD`, the current working directory.
- `status`, the <a href="#variables-status">exit status</a> of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number.
- `USER`, the current username. This variable can be changed by the user.
- `CMD_DURATION`, the runtime of the last command in milliseconds.
The names of these variables are mostly derived from the csh family of shells and differ from the ones used by Bourne style shells such as bash.
@ -756,9 +764,9 @@ Variables whose name are in uppercase are exported to the commands started by fi
Variables whose name are in uppercase are exported to the commands
started by fish, while those in lowercase are not exported. This rule is not
enforced by fish, but it is good coding practice to use casing to
distinguish between exported and unexported variables. \c fish also
distinguish between exported and unexported variables. `fish` also
uses several variables internally. Such variables are prefixed with
the string \c __FISH or \c __fish. These should never be used by the
the string `__FISH` or `__fish.` These should never be used by the
user. Changing their value may break fish.
\subsection variables-status The status variable
@ -1007,7 +1015,6 @@ function on_exit --on-process %self
end
\endfish
<a href="#variables-universal">Universal variables</a> are stored in the file `.config/fish/fishd.MACHINE_ID`, where MACHINE_ID is typically your MAC address. Do not edit this file directly, as your edits may be overwritten. Edit them through fish scripts or by using fish interactively instead.
@ -1038,35 +1045,21 @@ set fish_color_error black --background=red --bold
\subsection title Programmable title
When using most virtual terminals, it is possible to set the message
displayed in the titlebar of the terminal window. This can be done
automatically in fish by defining the \c fish_title function. The \c
fish_title function is executed before and after a new command is
executed or put into the foreground and the output is used as a
titlebar message. The $_ environment variable will always contain the
name of the job to be put into the foreground (Or 'fish' if control is
returning to the shell) when the \c fish_prompt function is called.
The first argument to fish_title will contain the most
recently executed foreground command as a string, starting with fish 2.2.
When using most virtual terminals, it is possible to set the message displayed in the titlebar of the terminal window. This can be done automatically in fish by defining the `fish_title` function. The `fish_title` function is executed before and after a new command is executed or put into the foreground and the output is used as a titlebar message. The $_ environment variable will always contain the name of the job to be put into the foreground (Or 'fish' if control is returning to the shell) when the `fish_prompt` function is called. The first argument to fish_title will contain the most recently executed foreground command as a string, starting with fish 2.2.
Examples:
<p>
The default \c fish title is
</p>
<p>
<pre>
The default `fish` title is
\fish
function fish_title
echo $_ ' '
pwd
end
</pre>
</p>
\endfish
<p>
To show the last command in the title:
</p>
<p>
<pre>
\fish
function fish_title
echo $argv[1]
end
@ -1117,7 +1110,7 @@ If you install fish in your home directory, fish will not work correctly for any
If you have a question not answered by this documentation, there are several avenues for help:
-# The official mailing list at <a href='https://lists.sf.net/lists/listinfo/fish-users'>fish-users@lists.sf.net</a>
-# The Internet Relay Chat channel, \c #fish on \c irc.oftc.net
-# The Internet Relay Chat channel, `#fish` on `irc.oftc.net`
-# The <a href="https://github.com/fish-shell/fish-shell/">project GitHub page</a>

248
doc_src/license.hdr
View file

@ -335,241 +335,71 @@ The precise terms and conditions for copying, distribution and modification foll
## TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
- This License applies to any program or other work which contains a notice
placed by the copyright holder saying it may be distributed under the terms of
this General Public License. The "Program", below, refers to any such program
or work, and a "work based on the Program" means either the Program or any
derivative work under copyright law: that is to say, a work containing the
Program or a portion of it, either verbatim or with modifications and/or
translated into another language. (Hereinafter, translation is included
without limitation in the term "modification".) Each licensee is addressed as
"you".
- This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".
Activities other than copying, distribution and modification are not covered
by this License; they are outside its scope. The act of running the Program
is not restricted, and the output from the Program is covered only if its
contents constitute a work based on the Program (independent of having been
made by running the Program). Whether that is true depends on what the Program
does.
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Program's source code as
you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice and
disclaimer of warranty; keep intact all the notices that refer to this License
and to the absence of any warranty; and give any other recipients of the
Program a copy of this License along with the Program.
1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may
at your option offer warranty protection in exchange for a fee.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
2. You may modify your copy or copies of the Program or any portion of it,
thus forming a work based on the Program, and copy and distribute such
modifications or work under the terms of Section 1 above, provided that you
also meet all of these conditions:
2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
-# You must cause the modified files to carry prominent notices stating
that you changed the files and the date of any change.
-# You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
-# You must cause any work that you distribute or publish, that in whole or
in part contains or is derived from the Program or any part thereof, to be
licensed as a whole at no charge to all third parties under the terms of this
License.
-# You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
-# If the modified program normally reads commands interactively when run,
you must cause it, when started running for such interactive use in the most
ordinary way, to print or display an announcement including an appropriate
copyright notice and a notice that there is no warranty (or else, saying that
you provide a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this License.
(Exception: if the Program itself is interactive but does not normally print
such an announcement, your work based on the Program is not required to print
an announcement.)
-# If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If identifiable
sections of that work are not derived from the Program, and can be reasonably
considered independent and separate works in themselves, then this License,
and its terms, do not apply to those sections when you distribute them as
separate works. But when you distribute the same sections as part of a whole
which is a work based on the Program, the distribution of the whole must be on
the terms of this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your
rights to work written entirely by you; rather, the intent is to exercise the
right to control the distribution of derivative or collective works based on
the Program.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with
the Program (or with a work based on the Program) on a volume of a storage or
distribution medium does not bring the other work under the scope of this
License.
In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
3. You may copy and distribute the Program (or a work based on it, under
Section 2) in object code or executable form under the terms of Sections 1 and
2 above provided that you also do one of the following:
3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
-# Accompany it with the complete corresponding machine-readable source code,
which must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange; or,
-# Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
-# Accompany it with a written offer, valid for at least three years, to give
any third party, for a charge no more than your cost of physically
performing source distribution, a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of Sections 1
and 2 above on a medium customarily used for software interchange; or,
-# Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
-# Accompany it with the information you received as to the offer to
distribute corresponding source code. (This alternative is allowed only
for noncommercial distribution and only if you received the program in
object code or executable form with such an offer, in accord with
Subsection b above.)
-# Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for making
modifications to it. For an executable work, complete source code means all
the source code for all modules it contains, plus any associated interface
definition files, plus the scripts used to control compilation and
installation of the executable. However, as a special exception, the source
code distributed need not include anything that is normally distributed (in
either source or binary form) with the major components (compiler, kernel, and
so on) of the operating system on which the executable runs, unless that
component itself accompanies the executable.
The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to
copy from a designated place, then offering equivalent access to copy the
source code from the same place counts as distribution of the source code,
even though third parties are not compelled to copy the source along with the
object code.
If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program except as
expressly provided under this License. Any attempt otherwise to copy, modify,
sublicense or distribute the Program is void, and will automatically terminate
your rights under this License. However, parties who have received copies, or
rights, from you under this License will not have their licenses terminated so
long as such parties remain in full compliance.
4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
5. You are not required to accept this License, since you have not signed it.
However, nothing else grants you permission to modify or distribute the
Program or its derivative works. These actions are prohibited by law if you
do not accept this License. Therefore, by modifying or distributing the
Program (or any work based on the Program), you indicate your acceptance of
this License to do so, and all its terms and conditions for copying,
distributing or modifying the Program or works based on it.
5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.
6. Each time you redistribute the Program (or any work based on the Program),
the recipient automatically receives a license from the original licensor to
copy, distribute or modify the Program subject to these terms and conditions.
You may not impose any further restrictions on the recipients' exercise of the
rights granted herein. You are not responsible for enforcing compliance by
third parties to this License.
6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.
7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or otherwise)
that contradict the conditions of this License, they do not excuse you from
the conditions of this License. If you cannot distribute so as to satisfy
simultaneously your obligations under this License and any other pertinent
obligations, then as a consequence you may not distribute the Program at all.
For example, if a patent license would not permit royalty-free redistribution
of the Program by all those who receive copies directly or indirectly through
you, then the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.
<P>
7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.
If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.
<P>
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
<P>
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.
9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.
__NO WARRANTY__
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
<P>
----
<STRONG>8.</STRONG>
If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.
<P>
<STRONG>9.</STRONG>
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
<P>
Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.
<P>
<STRONG>10.</STRONG>
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
<P><STRONG>NO WARRANTY</STRONG></P>
<P>
<STRONG>11.</STRONG>
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
<P>
<STRONG>12.</STRONG>
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
<P>
<h2>License for UTF8</h2>
## License for UTF8

42
doc_src/read.txt
View file

@ -11,32 +11,34 @@ read [OPTIONS] [VARIABLES...]
The following options are available:
- <tt>-c CMD</tt> or <tt>--command=CMD</tt> sets the initial string in the interactive mode command buffer to <tt>CMD</tt>.
- <tt>-g</tt> or <tt>--global</tt> makes the variables global.
- <tt>-l</tt> or <tt>--local</tt> makes the variables local.
- <tt>-m NAME</tt> or <tt>--mode-name=NAME</tt> specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.
- <tt>-p PROMPT_CMD</tt> or <tt>--prompt=PROMPT_CMD</tt> uses the output of the shell command \c PROMPT_CMD as the prompt for the interactive mode. The default prompt command is <tt>set_color green; echo read; set_color normal; echo "> "</tt>.
- <code>-s</code> or <code>--shell</code> enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.
- <code>-u</code> or <code>--unexport</code> prevents the variables from being exported to child processes (default behaviour).
- <code>-U</code> or <code>--universal</code> causes the specified shell variable to be made universal.
- <code>-x</code> or <code>--export</code> exports the variables to child processes.
- <code>-a</code> or <code>--array</code> stores the result as an array.
- `-c CMD` or `--command=CMD` sets the initial string in the interactive mode command buffer to `CMD`.
\c read reads a single line of input from stdin, breaks it into tokens
based on the <tt>IFS</tt> shell variable, and then assigns one
token to each variable specified in <tt>VARIABLES</tt>. If there are more
tokens than variables, the complete remainder is assigned to the last variable.
As a special case, if \c IFS is set to the empty string, each character of the
input is considered a separate token.
- `-g` or `--global` makes the variables global.
If \c -a or \c --array is provided, only one variable name is allowed and the
tokens are stored as an array in this variable.
- `-l` or `--local` makes the variables local.
- `-m NAME` or `--mode-name=NAME` specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.
- `-p PROMPT_CMD` or `--prompt=PROMPT_CMD` uses the output of the shell command `PROMPT_CMD` as the prompt for the interactive mode. The default prompt command is <code>set_color green; echo read; set_color normal; echo "> "</code>.
- `-s` or `--shell` enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.
- `-u` or `--unexport` prevents the variables from being exported to child processes (default behaviour).
- `-U` or `--universal` causes the specified shell variable to be made universal.
- `-x` or `--export` exports the variables to child processes.
- `-a` or `--array` stores the result as an array.
`read` reads a single line of input from stdin, breaks it into tokens based on the `IFS` shell variable, and then assigns one token to each variable specified in `VARIABLES`. If there are more tokens than variables, the complete remainder is assigned to the last variable. As a special case, if `IFS` is set to the empty string, each character of the input is considered a separate token.
If `-a` or `--array` is provided, only one variable name is allowed and the tokens are stored as an array in this variable.
\subsection read-example Example
The following code stores the value 'hello' in the shell variable
`$foo`.
The following code stores the value 'hello' in the shell variable `$foo`.
\fish
echo hello|read foo

59
doc_src/test.txt
View file

@ -7,9 +7,7 @@ test [EXPRESSION]
\subsection test-description Description
Tests the expression given and sets the exit status to 0 if true,
and 1 if false. An expression is made up of one or more operators
and their arguments.
Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments.
The following operators are available to examine files and directories:
@ -24,11 +22,13 @@ The following operators are available to examine files and directories:
- `-f FILE` returns true if `FILE` is a regular file.
- `-g FILE` returns true if `FILE` has the set-group-ID bit set.
- `-G FILE` returns true if `FILE` exists and has the same group ID
as the current user.
- `-G FILE` returns true if `FILE` exists and has the same group ID as the current user.
- `-L FILE` returns true if `FILE` is a symbolic link.
- `-O FILE` returns true if `FILE` exists and is owned by the current
user.
- `-O FILE` returns true if `FILE` exists and is owned by the current user.
- `-p FILE` returns true if `FILE` is a named pipe.
- `-r FILE` returns true if `FILE` is marked as readable.
@ -46,10 +46,11 @@ user.
- `-x FILE` returns true if `FILE` is marked as executable.
The following operators are available to compare and examine text strings:
- `STRING1 = STRING2` returns true if the strings `STRING1` and
`STRING2` are identical.
- `STRING1 != STRING2` returns true if the strings `STRING1` and
`STRING2` are not identical.
- `STRING1 = STRING2` returns true if the strings `STRING1` and `STRING2` are identical.
- `STRING1 != STRING2` returns true if the strings `STRING1` and `STRING2` are not identical.
- `-n STRING` returns true if the length of `STRING` is non-zero.
- `-z STRING` returns true if the length of `STRING` is zero.
@ -68,9 +69,7 @@ The following operators are available to compare and examine numbers:
- `NUM1 -le NUM2` returns true if `NUM1` is less than or equal to `NUM2`.
Note that only integers are supported. For more complex mathematical
operations, including fractions, the `env` program may be useful. Consult the
documentation for your operating system.
Note that only integers are supported. For more complex mathematical operations, including fractions, the `env` program may be useful. Consult the documentation for your operating system.
Expressions can be combined using the following operators:
@ -79,14 +78,15 @@ Expressions can be combined using the following operators:
- `COND1 -o COND2` returns true if either `COND1` or `COND2` are true.
Expressions can be inverted using the `!` operator:
- `! EXPRESSION` returns true if `EXPRESSION` is false, and false if
`EXPRESSION` is true.
- `! EXPRESSION` returns true if `EXPRESSION` is false, and false if `EXPRESSION` is true.
Expressions can be grouped using parentheses.
- `( EXPRESSION )` returns the value of `EXPRESSION`.
Note that parentheses will usually require escaping with `\\(` to avoid
being interpreted as a command substitution.
Note that parentheses will usually require escaping with `\(` to avoid being interpreted as a command substitution.
\subsection test-example Examples
@ -98,19 +98,15 @@ if test -d /tmp
end
\endfish
If the variable \c MANPATH is defined and not empty, print the contents.
(If \c MANPATH is not defined, then it will expand to zero arguments, unless
quoted.)
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.)
<pre>
\fish
if test -n "$MANPATH"
echo $MANPATH
end
\endfish
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.
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 \)
@ -121,15 +117,10 @@ end.
\subsection test-standards Standards
`test` implements a subset of the
<a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008
(POSIX.1) standard</a>. The following exceptions apply:
`test` implements a subset of the <a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008 (POSIX.1) standard</a>. The following exceptions apply:
- The `<` and `>` operators for comparing strings are not implemented.
- Because this test is a shell builtin and not a standalone utility, using
the -c flag on a special file descriptors like standard input and output
may not return the same result when invoked from within a pipe as one
would expect when invoking the `test` utility in another shell.
In cases such as this, one can use `command` `test` to explicitly
use the system's standalone `test` rather than this `builtin` `test`.
- Because this test is a shell builtin and not a standalone utility, using the -c flag on a special file descriptors like standard input and output may not return the same result when invoked from within a pipe as one would expect when invoking the `test` utility in another shell.
In cases such as this, one can use `command` `test` to explicitly use the system's standalone `test` rather than this `builtin` `test`.

18
doc_src/type.txt
View file

@ -11,15 +11,17 @@ With no options, `type` indicates how each `NAME` would be interpreted if used a
The following options are available:
- \c -h or \c --help prints help and then exits.
- \c -a or \c --all prints all of possible definitions of the specified names.
- \c -f or \c --no-functions suppresses function and builtin lookup.
- \c -t or \c --type prints <tt>function</tt>, <tt>builtin</tt>, or <tt>file</tt> if \c NAME is a shell function, builtin, or disk file, respectively.
- \c -p or \c --path returns the name of the disk file that would be executed, or nothing if 'type -t name' would not return 'file'.
- \c -P or \c --force-path returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the <tt>$PATH</tt>.
- \c -q or \c --quiet suppresses all output; this is useful when testing the exit status.
- `-a` or `--all` prints all of possible definitions of the specified names.
`type` sets the exit status to 0 if the specified command was found, and 1 if it could not be found.
- `-f` or `--no-functions` suppresses function and builtin lookup.
- `-t` or `--type` prints `function`, `builtin`, or `file` if `NAME` is a shell function, builtin, or disk file, respectively.
- `-p` or `--path` returns the name of the disk file that would be executed, or nothing if `type -t name` would not return `file`.
- `-P` or `--force-path` returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the <tt>$PATH</tt>.
- `-q` or `--quiet` suppresses all output; this is useful when testing the exit status.
\subsection type-example Example

122
doc_src/user_doc.css
View file

@ -127,7 +127,11 @@ h3 {
padding-bottom: 10px;
border-bottom: 1px solid #AAA;
}
/*Special Formmating for Code and keys*/
em {
font-style: normal;
}
/* Special Formmating */
/* Keyboard */
.key span {
display:none;
}
@ -144,70 +148,102 @@ h3 {
white-space: nowrap;
box-shadow: 0 1px 2px #ddd;
}
/* Console display */
tt, code, pre, .fish {
font-family: "DejaVu Sans Mono", "Source Code Pro", Menlo, "Ubuntu Mono", "Consolas", Monaco, "Lucida Console", monospace, fixed;
font-weight: 500;
text-shadow: 0 0 0 rgba(0,0,0,0.2);
}
tt {
color: red; /*REMOVE THIS*/
}
code, pre, .line {
white-space: -moz-pre-wrap;
white-space: -pre-wrap;
white-space: -o-pre-wrap;
white-space: pre-wrap;
word-wrap: break-word;
}
h1 > code, h2 > code, h3 > code {
font-family: "DejaVu Sans Mono", Menlo, "Source Code Pro", "Consolas", "Lucida Console", Roboto, Verdana, sans-serif;
font-weight: 700;
}
/*Default 'light' console*/
.fish {
margin: 1rem 0;
padding: 0.6rem 1rem;
font-size: 1.3rem;
line-height: 1.9rem;
font-size: 1.2rem;
line-height: 1.8rem;
color: #111;
text-shadow: 0 0 0 #000; /* Stronger anti-aliasing */
background-color: #fafafa;
border: 1px solid #f0f0f0;
border-radius: 0.4rem;
border: 1px solid #bbb;
border-radius: 0.6rem;
box-shadow: 0 0.2rem 0.2rem #ddd;
}
.comment { color: #777; }
.command { color: #0A0; }
.function { color: #0A0; }
.binary { color: #060; }
.argument { color: #906; }
.variable { color: #339; }
.redirect { color: #F00; }
.operator { color: #990; }
.file { color: #c97922; }
.path { color: #c97922; }
.string { color: #770; }
.prompt { color: #03C; }
.suggest { color: cyan ; }
.error { color: red; font-weight: bold; }
.cursor { border-bottom: 2px solid green; }
.comment { color: #555; }
/*.command, .function, .binary { color: #23326b; }*/
.command { color: #00F; }
.binary { color: #F0F; }
.function { color: #0FF; }
.string { color: #725000; }
.operator, .variable { color: #741ba3; }
.path { color: #F00; }
.file { color: #0F0; }
.argument { color: #19c9ff; }
.redirect { color: #f00; }
.prompt { color: #000; }
.cursor { border-bottom: 2px solid #444; }
.underline { text-decoration: underline; }
/*.keyword, .keywordflow { color: #050; }*/
/*.stringliteral, .charliteral { color: #226; }*/
/*.preprocessor, .comment { color: #555; text-shadow: none; }*/
/*.comment { color: #c33; }
.command, .function, .binary { color: #2568e2; }
.argument, .variable, .path, .file { color: #00afff; }
.redirect { color: #fff; }
.operator, .match, .history { color: #2ff; }
.string { color: #c07d2f; }
.suggest { color: #555; }
.error { color: #f33; font-weight: bold; }
.match { color: #2ff; }
.search_match { background-color: #f2f; }
.cwd { color: #2f2; }
.prompt { color: #fff; }
.cursor { border-bottom: 2px solid #ccc; }
.underline { text-decoration: underline; }*/
.synopsis {
border: none;
color: #333;
text-shadow: 0 0 0 rgba(0,0,0,0.2);
background: none;
font-size: 1.3rem;
padding: 0;
box-shadow: none;
}
/* Console variants */
.cli-dark {
background-color: #111;
color: #ddd;
padding: 0.4rem 2rem;
border-radius: 0.4rem;
background-color: #222;
color: #ccc;
text-shadow: 0 0 0 #222;
padding: 0.6rem 1.2rem;
border-radius: 0.6rem;
}
/*
.cli .command {
color: #0E0;
font-weight: bold;
.cli-dark .comment { color: #c33; }
.cli-dark .command, .cli-dark .function, .cli-dark .binary { color: #6159de; }
.cli-dark .argument, .cli-dark .path, .cli-dark .file { color: #00afff; }
.cli-dark .redirect { color: #fff; }
.cli-dark .operator,.cli-dark .variable, .cli-dark .match, .cli-dark .history { color: #2ff; }
.cli-dark .string { color: #b3b206; }
.cli-dark .suggest, .cli-dark em { color: #777; }
.cli-dark .match { color: #2ff; }
.cli-dark .search_match { background-color: #a100a3; }
.cli-dark .cwd, .cli-dark .prompt .path { color: #2f2; }
.cli-dark .prompt { color: #999; }
.cli-dark .cursor { border-bottom: 2px solid #3F3; }
.cli-dark .underline { color: #00afff; text-decoration: underline; }
.cli-dark .error, .cli-dark .error .path { color: #f33; font-weight: bold; }
.cli-dark .key em, .cli-dark .key b {
background-color: #ccc;
box-shadow: 0 0.1rem 0 #666;
border: 1px solid #333;
color: #000;
padding: 0 3px;
}
.cli .function {
color: #0C0;
}*/
/*Menus*/
.menu { margin: 1.4rem 0; line-height: 2.2rem; }
.menu ul { list-style-type: none; }

12
lexicon_filter.in
View file

@ -272,8 +272,8 @@ x
G
#.
# Uncomment the folowing two lines (ss) to log the buffer join.
s/^.*$/JOIN: &/w debug-lexicon.log
s/^JOIN: //
s/^.*$/Joined : &/w lexicon.log
s/^Joined : //
#.
# Iterate over alternate lines, matching '<' to '\'
:join
@ -617,8 +617,8 @@ s/\([^@]\)\([A-Za-z0-9_-][A-Za-z0-9_-]*\.[a-z0-9*][a-z0-9*]*\)/\1@fsfo{\2}/g
# As the lexicon is written into the output lexicon_filter, portability is
# automatically handled.
#.
#!# sbin whoami
#!# sbin mkdir
#!# sbin basename
#!# cmnd sleep
#!# cmnd whoami
#!# cmnd mkdir
#!# cmnd basename
#!# bltn sleep
#!# args in