read 0.3.6  (2004-04-30)
Copyright (c) 2004 Kalle Risnen <kal@aros-stuff.tk>.

This is a (more or less complete) rewrite of the bash builtin `read',
for AROS. It prompts for input, and places it in the given
environmental variable(s), or, if no variable name is passed to it,
in the variable $REPLY.
	You can build a Termios version of `read' by replacing `-DAROS'
with `-DHAVE_TERMIOS_H' in `Makefile'. It is, however, practically
untested. I've just checked to see if it compiles. I have no use for
it (bash is your friend), and will not support it, other than fixing
serious and/or embarrassing bugs. You can build a pure ANSI C version
of `read' by simply removing the `-DAROS'. This has not been tested 
*at all*, use at own risk.


`read' behaves differently to bash read in the following ways:
	* `-a ANAME' adds ANAME to the list of variables to which to save
	  input. bash read places input (word for word) as sequential
	  indices of the array ANAME.
	* You can specify multiple end delimiters with the `-e DELIM' option,
	  including escapes.
	* `-f' makes `read' exit with OK, if the number of words read does
	  not match the number of NAMEs.
	* `-e' does nothing.
	* The prompt (specified with `-p PROMPT') can contain backslash 
	  escapes (the same ones as `printf(3)') unless the argument `-r' is
	  given. (As can input and the WDELIM).
	* I've added the `-q' option, which makes `read' emulate `Ask' (more
	  or less), somewhat like what zsh read does.
	* The `-t' option doesn't quite work as it should, the user has to 
	  enter a char before it exits after the timeout.
	* The `-u' option takes afilename, unlike {ba,z,k}sh read(s), which
	  take a filedescriptor.
	* When reading to multiple variables, you can enclose words in double
	  quotes (`"') to include the delimiter(s).
	* `-w WDELIM' lets you change the default word delimiter(s) to WDELIM.
	* The `--copyright', `--help', and `--version' options.
	* Arguments can come in any order.

Report any bugs to <bugs@aros-stuff.tk>, see <http://www.aros-stuff.tk/>
for updates.



INSTALLING

Just copy `read' into somewhere in your path.



USAGE

read [ [OPTION ...] [NAME ...] | [ --help | --copyright | --version ] ]

	-a ANAME
	    Should assign each input word into sequential indices of the array
	    ANAME, as bash read does. Since we're working with environmentals,
	    not variables, it just adds ANAME to NAMEs.
	-d DELIM
	    Use any character from DELIM to end input, rather than newline.
	-e  Does nothing, kept for bash read compatibility (and, to some extent,
	    for ash read compatibility).
	-f  Return OK if fewer words were entered than there are NAMEs.
	-n NCHARS
	    Return after reading NCHARS instead of upon reaching end of line.
	-p PROMPT
	    Display PROMPT before reading. Not displayed if reading from file.
	-q  `Ask' mode, reads only one char and, if it is 'y' or 'Y', sets NAME to
	    'y' and returns WARN, otherwise sets NAME to 'n' and returns OK.
	-r  Don't allow backslash escapes (eg. typeing '\' + <ENTER> to enter
	    newline, or using '\n' in prompt to echo newline).
	-s  Silent, don't echo input.
	-t TIMEOUT
	    If input isn't done in TIMEOUT seconds, return failure.
	-u FILENAME
	    Take input from FILENAME, rather than standard input.
	-w WDELIM
	    Use WDELIM is delimiter between words. By default, read looks for the
	    environmental variable IFS, and uses it. If IFS is not found, it
	    defaults to " \t" (space or tab). Please note that WDELIM can be an
	    arbitrary number of chars, any of which'll be recognized as WDELIMs.
	    (IFS, btw, stands for `Input Field Separator' - this is a standard
	    term in {ba,z,k}sh docs).
	NAME
	    Save input into the environmental variable NAME. If more than one NAME
	    is specified, split input by WDELIM, and save each `word' into each
	    NAME.
	--copyright
	    Outputs copyright information.
	--help
	    Outputs this message.
	--version
	    Outputs read version.

Read returns WARN if it recieved any input, and OK if no input was given (or, if
the `-f' flag is given, if fewer words were input than there are NAMEs). Returns FAIL
if it failed setting NAME(s).
	Report any bugs to <bugs@aros-stuff.tk>.



COPYRIGHT

read 0.3: Copyright (c) 2004 Kalle Risnen.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
