mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-26 12:53:13 +00:00
c6093ad782
The `read` command `-m` and `--mode-name` vars are now deprecated and do nothing other than result in a warning message. The `read` command now honors the `FISH_HISTORY` var that is used to control where commands are read from and written to. You can set that var to the empty string to suppress the use of both history files. Or you can set it to a history session ID in which case that will limit the `read` history that is available. Fixes #1504
67 lines
4.5 KiB
Text
67 lines
4.5 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.
|
|
|
|
- `-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-history Using another read history file
|
|
|
|
The `read` command supported the `-m` and `--mode-name` flags in fish versions prior to 2.7.0 to specify an alternative read history file. Those flags are now deprecated and ignored. Instead, set the `FISH_HISTORY` variable to specify a history session ID. That will affect both the `read` history file and the fish command history file. You can set it to an empty string to specify that no history should be read or written. This is useful for presentations where you do not want possibly private or sensitive history to be exposed to the audience but do want history relevant to the presentation to be available.
|
|
|
|
\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
|