NAME

grabchars - get keystrokes directly from user

SYNOPSIS

grabchars [options]

DESCRIPTION

Grabchars gets characters from the user as they are typed in, without having to wait for the return key to be pressed.  Among other things, this allows shell scripts to be written with highly interactive menus. 

By default, grabchars will obtain one character from stdin, echo that character to stdout, and return with a status of one; meaning one character read. 

−b Both stdout and stderr are used for output.  This is useful for setting a variable in a shell script and echoing a keystroke to the screen at the same time. 

−c<valid characters>
Only characters in <valid characters> are accepted.  Regular expressions such as [a-z] may be used to specify ranges.  All other characters are ignored. 

−d<char(s)>
Default char or string to output if the user hits RETURN or lets grabchars timeout.  The status that is returned is the same as if the user had typed in the character or string, so this option may be used with the −s (silent) flag. 

−e Output goes to stderr rather than stdout. 

−f Flush any previous input.  By default, grabchars will see any characters present in stdin, which allows for some typeahead in shell scripts. 

−h Help/usage screen. 

−p<prompt>
Sets up a prompt for the user.  See EXAMPLES. 

−q<prompt>
Sets up a prompt for the user, except it is printed to stderr rather than stdout. 

−r The RETURN key exits.  Use this with the -n option to allow for variable numbers of characters to be typed in. 

−n<number>
Number of characters to read.  By default, grabchars looks for one character. 

−s Silent.  Do not output anything. Just return a status. 

−t<seconds>
Time to allow the user to respond.  By default, the user can take as long as he or she wants to.  The timeout option allows you to write shell scripts where you can offer some assistance if it’s obvious that the user might be stuck.

−E Erase/kill processing is done.  You have use of the keys (usually DELETE and ^U or ^X) that you would normally have from the shell for deleting characters.  This is useful with the −n option, where many characters are being typed in.  This code hasn’t been thoroughly tested. 

EXAMPLES

grabchars
gets one keystroke

grabchars −caeiou
get one of the vowels

grabchars -c i
get the letter ’i’

grabchars ’−penter a letter ’
print the prompt "enter a letter "

grabchars ’−qenter a letter ’
print the prompt (’q’ for question) "enter a letter " through stderr. 

grabchars −n4
get four characters.

grabchars −d a
If the first character typed is a RETURN, pretend it was an ’a’. 

grabchars −d gumby
If the first character typed is a RETURN, pretend that the user typed in "gumby". 

grabchars −r
The RETURN key will exit grabchars. You would use this with -n option, so that variable numbers of characters may be entered. 

grabchars −n 4 −r −t 10
Accept up to four characters, or exit when RETURN is hit, or exit when 10 seconds have elapsed. 

grabchars −t2
timeout after two seconds.

grabchars −d gumby −t2
If the first character typed is a RETURN, or if two seconds have gone by, pretend that the user typed in "gumby". 

grabchars −n3 −p ’initials: ’
print a prompt and grab three characters.

grabchars −c 0123456789 −n2 −t10
get two numbers with a ten second timeout.

note that arguments like "-n4" or "-n 4" are handled the same way

SEE ALSO

csh(1) and sh(1) for syntax of csh and sh scripts, respectively. 

DIAGNOSTICS

Grabchars returns −2 if it times out, or −1 if it gives a usage statement.  Otherwise, it returns the number of characters successfully read. 

AUTHOR

Dan Smith (daniel@island.uu.net or {ucbvax!ucbcad,well,sun}!island!daniel)

7th Edition  —  Revision 1.1 of 10/05/89