NAME

input - free format read

SYNOPSIS

#include <basic/string.h>
#include <basic/type.h>
#include <basic/generic.h>

input (prompt, nlflag, qflag, nargs [, type, generic, ] . . .  )
struct string *prompt;
int nlflag, qflag;
int type . . .  ;
union generic *generic . . .  ;

DESCRIPTION

Input implements the BASIC free format read statements: INPUT, INPUT #, and READ.  This function reads from the current file (see initio(io)).  It is legal to read sequentially from a random file provided the read is entirely within the buffer.  If the current file is a tty and prompt is not null, the string it points to is echoed; if qflag is set, a question mark is echoed.  The data are then interpreted. 

A series of data items is read according to the series of type, generic argument pairs.  Type is the expected type of the item and generic points to a generic union in which to store the item (see generic(inc)).  This function takes a variable number of arguments.  Nargs is the number of type, generic pairs. 

When an item is to be read, any initial blanks or tabs are first read and discarded.  At this point, an error is generate if the end of file is reached, for a buffered file, the end of the line is reached for a tty, or the end of the last DATA statement is reached for the data area.  Now, if the next character is a double quote and the item to be read is a string, then the item is a quoted string and the double quote is discarded.  The text of the item begins with the next character.  Characters are then read and appended to the text of the item until a termination condition exists. 

The text of any item is terminated by the end of the file for a buffered file.  This is not an error.  In addition, the text of any item is terminated by the end of the line, except within a quoted string for a buffered file, in which case, the newline character is added to the text of the item.  A quoted string is (except as provided above) terminated by a second double quote; any other string or numeric is terminated by a comma.  These termination characters are not part of the text of the item.  Finally, a numeric item in a buffered file may also be terminated by a blank or tab.  This completes the reading of the text of the item.  However, if the termination character was a double quote, blank or tab, then any following sequence of blanks or tabs is also read and discarded until another character (or the end of the file or end of the line) is read.  This becomes the new termination character. 

If the end of the file, end of the line, or a comma is not now the termination character then the character is put back on the input stream, for a buffered file, or an error is generated for a tty or the data area.  This has the effect, in the former case of requiring no other terminator for quoted strings and blank and tab terminators for numeric items in buffered files, and, in the latter case, of forbidding (non-white space) text beyond the closing double quote of a quoted string (before a comma or the end of the line) for a tty or the data area. 

The resulting item text may, itself, contain trailing blanks and tabs at this point.  If the item is not a quoted string, this trailing white space is removed.  Now, if the item is a string (quoted or otherwise), this text becomes the text of the string.  Otherwise (the item is numeric), the text is converted to the appropriate numeric type in the manner of a BASIC numeric constant.  For a tty or the data area, if it is not possible interpret the entire text as a constant, an error is generated.  Contrapositively, it is permissible, for a buffered file, for the text of a numeric item to contain an initial (possibly empty) prefix text which is interpretable as a constant, the remainder is ignored.  This is not an error.  In any case, the text of an item may finally appear empty; for a string this results in a null string item and for a numeric item, zero. 

Items are read and stored in the generic unions in sequence.  In the case of a string, a pointer to a valid string or initialized (cleared) header must be provided; the text buffer is freed (if appropriate) and new space is allocated. 

In the case of a tty, characters are read from a line gotten by inline (see linein(io)).  If after all items are read successfully, characters remain unread from the line, then an error is generated.  The effect of this and a previously defined condition is that there must be exactly nargs items on the line.  The error generated is not a true error condition, but a message echoed to the tty after which another line is gotten and the item list is read again from the beginning.  This cycle can continue indefinitely or until the user rises above his or her station. 

After every data item has been read successfully, if nlflag is set and the current file is a full-duplex tty (see io(inc)), a newline is echoed. 

This function resets the current file. 

SEE ALSO

generic(inc), io(inc), string(inc), initio(io), linein(io)
data(stmt), input(stmt), input #(stmt), read(stmt)

DIAGNOSTICS

Error 5 (Illegal function call) is generated if the file is open for output only. 

Error 62 (Input past end) is generated if the end of file is reached when attempting to read an item from a buffered file. 

Error 4 (Out of data) is generated if the end of the last DATA statement is reached when attempting to read an item from the data area. 

For the data area, error 2 (Syntax error) is generated if a character besides comma or the end of the line appears after the closing double quote of a quoted string and any following white space and if the text of a numeric item can not be interpreted entirely as a constant. 

Error 6 (Overflow) is generated if the value of the item exceeds the precision of the expected numeric type, for a buffered file or the data area. 

For a tty, this functions asks the user to re-enter the data if the number of items entered does not match the number of items expected, if a character besides comma or the end of the line appears after the closing double quote of a quoted string and any following white space and if the text of a numeric item can not be interpreted entirely as a constant.  Overflow is noted with an additional message. 

from The Basmark QuickBASIC Programmerís Manual by Lawrence Leinweber