mirror of
https://github.com/fish-shell/fish-shell
synced 2024-11-14 17:07:44 +00:00
65 lines
4 KiB
Text
65 lines
4 KiB
Text
\section read read - read line of input into variables
|
|
|
|
\subsection read-synopsis Synopsis
|
|
\fish{synopsis}
|
|
read [OPTIONS] [VARIABLES...]
|
|
\endfish
|
|
|
|
\subsection read-description Description
|
|
|
|
`read` reads from standard input and stores the result in one or more shell variables. By default it reads one line terminated by a newline but options are available to read up to a null character and to limit each "line" to a maximum number of characters.
|
|
|
|
The following options are available:
|
|
|
|
- `-c CMD` or `--command=CMD` sets the initial string in the interactive mode command buffer to `CMD`.
|
|
|
|
- `-g` or `--global` makes the variables global.
|
|
|
|
- `-i` or `--silent` makes the characters typed obfuscated. This is useful for reading things like passwords or other sensitive information. Note that in bash the short flag is `-s`. We can't use that due to the existing use as an alias for `--shell`.
|
|
|
|
- `-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.
|
|
|
|
- `-n NCHARS` or `--nchars=NCHARS` causes `read` to return after reading NCHARS characters rather than waiting for a complete line of input (either newline or null terminated).
|
|
|
|
- `-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>.
|
|
|
|
- `-P PROMPT_STR` or `--prompt-str=PROMPT_STR` uses the string as the prompt for the interactive mode. It is equivalent to <code>echo PROMPT_STR</code> and is provided solely to avoid the need to frame the prompt as a command. All special characters in the string are automatically escaped before being passed to the <code>echo</code> command.
|
|
|
|
- `-R RIGHT_PROMPT_CMD` or `--right-prompt=RIGHT_PROMPT_CMD` uses the output of the shell command `RIGHT_PROMPT_CMD` as the right prompt for the interactive mode. There is no default right prompt command.
|
|
|
|
- `-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 in a single variable.
|
|
|
|
- `-z` or `--null` reads up to NUL instead of newline. Disables interactive mode.
|
|
|
|
`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.
|
|
|
|
See the documentation for `set` for more details on the scoping rules for variables.
|
|
|
|
When read reaches the end-of-file (EOF) instead of the separator, it sets `$status` to 1. If not, it sets it to 0.
|
|
|
|
Fish has a default limit of 10 MiB on the number of characters each `read` will consume. If you attempt to read more than that `$status` is set to 122 and the variable will be empty. You can modify that limit by setting the `FISH_READ_BYTE_LIMIT` variable at any time including in the environment before fish starts running. This is a safety mechanism to keep the shell from consuming an unreasonable amount of memory if the input is malformed.
|
|
|
|
\subsection read-example Example
|
|
|
|
The following code stores the value 'hello' in the shell variable `$foo`.
|
|
|
|
\fish
|
|
echo hello|read foo
|
|
|
|
# This is a neat way to handle command output by-line:
|
|
printf '%s\n' line1 line2 line3 line4 | while read -l foo
|
|
echo "This is another line: $foo"
|
|
end
|
|
\endfish
|