n= read(f, format=fstring, obj1, obj2, ...)  
          or n= read(prompt= pstring, format=fstring, obj1, obj2, ...)  
 	 or n= sread(source, format=fstring, obj1, obj2, ...)  
  
     reads text from I/O stream F (1st form), or from the keyboard (2nd  
     form), or from the string or string array SOURCE (3rd form),  
     interprets it according to the optional FSTRING, and uses that  
     interpretation to assign values to OBJ1, OBJ2, ...  If the input  
     is taken from the keyboard, the optional prompt PSTRING (default  
     "read> ") is printed before each line is read.  The Yorick write  
     function does not interact with the read function -- writes are  
     always to end-of-file, and do not affect the sequence of lines  
     returned by read.  The backup (and bookmark) function is the  
     only way to change the sequence of lines returned by read.  
  
     There must be one non-supressed conversion specifier (see below)  
     in FSTRING for each OBJ to be read; the type of the conversion  
     specifier must generally match the type of the OBJ.  That is,  
     an integer OBJ requires an integer specifier (d, i, o, u, or x)  
     in FSTRING, a real OBJ requires a real specifier (e, f, or g),  
     and a string OBJ requires a string specifier (s or []).  An OBJ  
     may not be complex, a pointer, a structure instance, or any non-  
     array Yorick object.  If FSTRING is not supplied, or if it has  
     fewer conversion specifiers than the number of OBJ arguments,  
     then Yorick supplies default specifiers ("%ld" for integers,  
     "%lg" for reals, and "%s" for strings).  If FSTRING contains more  
     specifiers than there are OBJ arguments, the part of FSTRING  
     beginning with the first specifier with no OBJ is ignored.  
  
     The OBJ may be scalar or arrays, but the dimensions of every OBJ  
     must be identical.  If the OBJ are arrays, Yorick behaves as  
     if the read were called in a loop numberof(OBJ1) times, filling  
     one array element of each of the OBJ according to FSTRING on  
     each pass through the loop.  (Note that this behavior includes  
     the case of reading columns of numbers by a single call to read.)  
  
     The return value N is the total number of scalar assignments  
     which were made as a result of this call.  (If there were 4  
     OBJ arguments, and each was an array with 17 elements, a return  
     value of N==35 would mean the following:  The first 8 elements  
     of OBJ1, OBJ2, OBJ3, and OBJ4 were read, and the 9th element of  
     OBJ1, OBJ2, and OBJ3 was read.)  The read function sets any  
     elements of the OBJ which were not read to zero -- hence,  
     independent of the returned N, the all of the old data in the  
     OBJ arguments is overwritten.  
  
     The read or sread functions continue reading until either:  
     (1) all elements of all OBJ have been filled, or (2) end-of-file  
     (or end of SOURCE for sread) is reached ("input failure"), or  
     (3) part of FSTRING or a conversion specifier supplied by  
     default fails to match the source text ("matching failure").  
  
     The FSTRING is composed of a series of "directives" which are  
     (1) whitespace -- means to skip any amount of whitespace in the  
         source text  
     (2) characters other than whitespace and % -- must match the  
         characters in the source text exactly, or matching failure  
	 occurs and the read operation stops  
     (3) conversion specifiers beginning with % and ending with a  
         character specifying the type of conversion -- optionally  
	 skip whitespace, then convert as many characters as  
	 continue to "look like" the conversion type, possibly  
	 producing a matching failure  
     The conversion specifier is of the form %*WSC, where:  
     * is either the character '*' or not present  
       A specifier beginning with %* does not correspond to any of  
       the OBJ; the converted value will be discarded.  
     W is either a positive decimal integer specifying the maximum  
       field width (not including any skipped leading whitespace),  
       or not present if any number of characters up to end-of-line  
       is acceptable.  
     S is either one of the characters 'h', 'l', or 'L', or not  
       present.  Yorick allows this for compatibility with the C  
       library functions, but ignores it.  
     C is a character specifying the type of conversion:  
       d   - decimal integer  
       i   - decimal, octal (leading 0), or hex (leading 0x) integer  
       o   - octal integer  
       u   - unsigned decimal integer (same as d for Yorick)  
       x, X            - hex integer  
       e, f, g, E, G   - floating point real  
       s   - string of non-whitespace characters  
       [xxx]   - (xxx is any sequence of characters) longest string  
                 of characters matching those in the list  
       [^xxx]  - longest string of characters NOT matching those in  
                 the list (this is how you can extend %s to be  
		 delimited by something other than whitespace)  
       %   - the ordinary % character; complete conversion  
             specification must be "%%"  
  
     The read function is modeled on the ANSI standard C library  
     fscanf and sscanf functions, but differs in several respects:  
       (1) Yorick's read cannot handle the %c, %p, or %n conversion  
           specifiers in FSTRING.  
       (2) Yorick's read never results in a portion of a line  
           being read -- any unused part of a line is simply discarded  
	   (end FSTRING with "%[^\n]" if you want to save the trailing  
	   part of an input line).  
       (3) As a side effect of (2), there are some differences between  
           fscanf and Yorick's read in how whitespace extending across  
	   newlines is handled.  

unknown type function, documented at startup/std.i   line 1343