= Read built-in
:encoding: UTF-8
:lang: en
//:title: Yash manual - Read built-in

The dfn:[read built-in] reads a line from the standard input.

[[syntax]]
== Syntax

- +read [-Aer] [-P|-p] {{variable}}...+

[[description]]
== Description

The read built-in reads a line of string from the standard input and assigns
it to the specified link:params.html#variables[variables].

If the +-r+ (+--raw-mode+) option is specified, all characters in the line are
treated literally.

If the +-r+ (+--raw-mode+) option is not specified, backslashes in the line
are treated as link:syntax.html#quotes[quotations].
If a backslash is at the end of the line, it is treated as a line
continuation.
When the built-in reads the next line, the link:params.html#sv-ps2[+PS2+
variable] is used as a prompt if the shell is link:interact.html[interactive]
and the standard input is a terminal.

The input line is subject to link:expand.html#split[field splitting].
The resulting words are assigned to {{variable}}s in order.
If there are more words than {{variable}}s, the last variable is assigned all
the remaining words (as if the words were not split).
If the words are fewer than {{variable}}s, the remaining variables are
assigned empty strings.

[[options]]
== Options

+-A+::
+--array+::
Make the last {{variable}} an link:params.html#arrays[array].
Instead of assigning a concatenation of the remaining words to a normal
variable, the words are assigned to an array.

+-e+::
+--line-editing+::
Use link:lineedit.html[line-editing] to read the line.
+
To use line-editing, all of the following conditions must also be met:
+
- The shell is link:interact.html[interactive].
- The link:_set.html#so-vi[vi] or link:_set.html#so-emacs[emacs] option is
  enabled.
- The standard input and standard error are connected to a terminal.

+-P+::
+--ps1+::
Print the link:params.html#sv-ps1[+PS1+ variable] as a prompt before reading
the (first) line if the shell is interactive and the standard input is a
terminal.

+-p {{prompt}}+::
+--prompt={{prompt}}+::
Print the specified {{prompt}} before reading the (first) line if the shell
is interactive and the standard input is a terminal.

+-r+::
+--raw-mode+::
Don't treat backslashes as quotations.

[[operands]]
== Operands

{{variable}}s::
Names of variables to which input words are assigned.

[[exitstatus]]
== Exit status

The exit status of the read built-in is zero unless there is any error.

Note that the exit status is non-zero if an end of input is encountered before
reading the entire line.

[[notes]]
== Notes

The read built-in is a link:builtin.html#types[mandatory built-in].

The POSIX standard defines the +-r+  option only:
other options cannot be used in the link:posix.html[POSIXly-correct mode].

The link:params.html#sv-ps1r[+PS1R+] and link:params.html#sv-ps1s[+PS1S+]
variables affect the behavior of line-editing if the +PS1+ prompt is used. The
same for +PS2+.

// vim: set filetype=asciidoc textwidth=78 expandtab:
