fish-shell/doc_src/read.txt

\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 one line from standard input and stores the result in one or more shell variables.

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.

- `-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.

- `-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>.

- `-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.

- `-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.


\subsection read-example Example

The following code stores the value 'hello' in the shell variable `$foo`.

\fish
echo hello|read foo
\endfish
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 21:31:55 +08:00			`\section read read - read line of input into variables`

			`\subsection read-synopsis Synopsis`
Simplify styling 2014-08-01 20:25:41 +08:00			`\fish{synopsis}`
Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. 2014-08-01 10:37:32 +08:00			`read [OPTIONS] [VARIABLES...]`
			`\endfish`
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 21:31:55 +08:00
			`\subsection read-description Description`

Make line length, wrapping and spacing consistent 2014-08-19 20:41:23 +08:00			`read` reads one line from standard input and stores the result in one or more shell variables.
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 21:31:55 +08:00
Help cleanup Large list of changes, including formatting and typos for most commands. More substantive changes have been made to alias, bind, block, break, builtin, case, cd, commandline, count, else, emit, fish_config, funced, function, functions, history, math, mimedb, nextd, not, popd, prevd, pushd, pwd, random, read, set, set_color, switch, test, trap, type, ulimit, umask, and while. 2013-05-12 15:56:01 +08:00			`The following options are available:`

Rebase documentation changes 2014-09-03 22:10:53 +08:00			- `-c CMD` or `--command=CMD` sets the initial string in the interactive mode command buffer to `CMD`.

			- `-g` or `--global` makes the variables global.

			- `-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.

Merge branch 'master' into documentation-update Conflicts (fixed): doc_src/design.hdr 2014-09-04 17:00:52 +08:00			- `-n NCHARS` or `--nchars=NCHARS` causes `read` to return after reading NCHARS characters rather than waiting for a complete line of input.

Rebase documentation changes 2014-09-03 22:10:53 +08:00			- `-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>.

Add --right-prompt flag to read Add a flag to read to allow for setting the right prompt command in addition to the existing support for setting the prompt command. Fixes #1698. 2014-09-22 12:09:21 +08:00			- `-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.

Rebase documentation changes 2014-09-03 22:10:53 +08:00			- `-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.

Implement new `read --null` flag The `--null` flag to `read` makes it split incoming lines on NUL instead of newlines. This is intended for processing the output of a command that uses NUL separators (such as `find -print0`). Fixes #1694. 2014-09-22 10:18:56 +08:00			- `-z` or `--null` reads up to NUL instead of newline. Disables interactive mode.

Rebase documentation changes 2014-09-03 22:10:53 +08:00			`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.
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 21:31:55 +08:00
Merge branch 'master' into documentation-update Conflicts (fixed): doc_src/design.hdr 2014-09-04 17:00:52 +08:00			See the documentation for `set` for more details on the scoping rules for variables.

Fix documentation on variable scopes for `read` The `read` docs incorrectly asserted that -g was the default for variables. In actuality it behaves the same way that `set` does. 2014-07-14 08:47:44 +08:00
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 21:31:55 +08:00			`\subsection read-example Example`

Rebase documentation changes 2014-09-03 22:10:53 +08:00			The following code stores the value 'hello' in the shell variable `$foo`.
Add subdirectories darcs-hash:20050920133155-ac50b-9a14c6c664dd03afbe8e15e7c7998fcfb5c3c750.gz 2005-09-20 21:31:55 +08:00
Make line length, wrapping and spacing consistent 2014-08-19 20:41:23 +08:00			`\fish`
			`echo hello\|read foo`
			`\endfish`