PATCH: Document mysteries of the `read' builtin

["Bart Schaefer" <schaefer@xxxxxxxxxxxxxxxx>]

The documentation for the `read' builtin omits a lot of useful information
(e.g., that you can't read N characters from the editor buffer stack) and
is unclear about some of what it does say (e.g., what does "the number of
the word the cursor is on" really mean, and what is an editor buffer stack
anyway?).  This patch clears things up. 

If what this patch says bothers you, consider fixing bin_read() to interpret
its flags a little more consistently.

Index: Doc/Zsh/builtins.yo
===================================================================
--- builtins.yo	1998/06/01 17:08:42	1.1.1.1
+++ builtins.yo	1998/06/14 01:55:31
@@ -656,7 +656,10 @@
 item(tt(read) [ tt(-rzpqAclneE) ] [ tt(-k) [ var(num) ] ] \
 [ tt(-u)var(n) ] [ var(name)[tt(?)var(prompt)] ] [ var(name) ...  ])(
 Read one line and break it into fields using the characters
-in tt($IFS) as separators.
+in tt($IFS) as separators, except as noted below.
+The first field is assigned to the first var(name), the second field
+to the second var(name), etc., with leftover
+fields assigned to the last var(name).
 
 startitem()
 item(tt(-r))(
@@ -667,39 +670,48 @@
 Read only one character from the terminal and set var(name) to
 `tt(y)' if this character was `tt(y)' or `tt(Y)' and to `tt(n)' otherwise.
 With this flag set the return value is zero only if the character was
-`tt(y)' or `tt(Y)'.
+`tt(y)' or `tt(Y)'.  Note that this always reads from the terminal, even
+if used with the tt(-p) or tt(-u) or tt(-z) flags or with redirected input.
 )
 item(tt(-k) [ var(num) ])(
-Read only one (or var(num)) characters from the terminal.
+Read only one (or var(num)) characters.  All are assigned to the first
+var(name), without word splitting.  This flag is ignored when tt(-q) is
+present.  Input is read from the terminal unless one of tt(-u) or tt(-p)
+is present.
 )
 item(tt(-z))(
-Read from the editor buffer stack.
-The first field is assigned to the first var(name), the second field
-to the second var(name), etc., with leftover
-fields assigned to the last var(name).
+Read one entry from the editor buffer stack and assign it to the first
+var(name), without word splitting.  Text is pushed onto the stack with
+`tt(print -z)' or with tt(push-line) from the line editor (see
+ifzman(zmanref(zshzle))\
+ifnzman(noderef(Zsh Line Editor))\
+).  This flag is ignored when the tt(-k) or tt(-q) flags are present.
 )
 xitem(tt(-e))
 item(tt(-E))(
-The words read are printed after the whole line is read. If the
-tt(-e) flag is set, the words are not assigned to the parameters.
+The input read is printed (echoed) to the standard output.  If the tt(-e)
+flag is used, no input is assigned to the parameters.
 )
 item(tt(-A))(
-The first var(name) is taken as the
-name of an array and all words are assigned to it.
+The first var(name) is taken as the name of an array and all words are
+assigned to it.
 )
 xitem(tt(-c))
 item(tt(-l))(
 These flags are allowed only if called inside a
 function used for completion (specified with the tt(-K) flag to
-tt(compctl)). If the tt(-c) flag is given, the words of the
+tt(compctl)).  If the tt(-c) flag is given, the words of the
 current command are read. If the tt(-l) flag is given, the whole
-line is assigned as a scalar.  If var(name) is omitted then
+line is assigned as a scalar.  If both flags are present, tt(-l)
+is used and tt(-c) is ignored.  If var(name) is omitted then
 tt(REPLY) is used for scalars and tt(reply) for arrays.
 )
 item(tt(-n))(
-Together with either of the previous flags, this
-option gives the number of the word the cursor is on or the index of
-the character the cursor is on respectively.
+Together with tt(-c), the number of the word the cursor is on is
+read.  With tt(-l), the index of the character the cursor is on is
+read.  Note that the command name is word number 1, not word 0,
+and that when the cursor is at the end of the line, its character
+index is the length of the line plus one.
 )
 item(tt(-u)var(n))(
 Input is read from file descriptor var(n).
@@ -711,8 +723,18 @@
 
 If the first argument contains a `tt(?)', the remainder of this
 word is used as a var(prompt) on standard error when the shell
-is interactive.  The exit status is 0 unless an end-of-file
-is encountered.
+is interactive.
+
+The value (exit status) of tt(read) is 1 when an end-of-file is
+encountered, or when tt(-c) or tt(-l) is present and the command is
+not called from a tt(compctl) function.  Otherwise the value is 0.
+
+The behavior of some combinations of the tt(-k), tt(-p), tt(-q), tt(-u)
+and tt(-z) flags is undefined.  Presently tt(-q) cancels all the others,
+tt(-p) cancels tt(-u), tt(-k) cancels tt(-z), and otherwise tt(-z)
+cancels both tt(-p) and tt(-u).
+
+The tt(-c) or tt(-l) flags cancel any and all of tt(-kpquz).
 )
 cindex(parameters, marking readonly)
 alias(readonly)(typeset -r)

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com