Syntax: READ WORD INTEGER
or      READ [ ! ] { WORD INTEGER WORD INTEGER ... }
or      READ [ ! ] { ... WORD range ... }
or      READ ROW WORD INTEGER
or      READ [ ! ] 'format' { WORD WORD ... }
or      READ OLD WORD WORD
or      READ EDIT WORD
or      META READ WORD

   READ WORD INTEGER reads a column of data from the file specified by
the DATA command, using the lines specified by LINES. The data is read
into the vector WORD, which will be created, from column INTEGER. Any
field beginning with a * is taken to be `empty', and is assigned the
value 1.001e36. Any line beginning with a ! or # is treated as a
comment.  Lines starting # are echoed to the terminal if VERBOSE is 2
or more; ! lines are always echoed.  Long (logical) lines may be
spread over several (physical) lines by ending the line with a \.

   You may optionally specify a type for the vector to be read by adding a
suffix onto the INTEGER, either `.f' for floating point (the default),
`.d' or `.i' for integer, or `.s' for a string-valued vector.

   READ { ... } is the same as repeated READ WORD INTEGERs but more
efficient, as it only reads the file once to define all the vectors.
For example, READ { x 1 s 3.s y 5.f z 2.i } reads floating point
vectors x and y from columns 1 and 5, a string vector s from column 3,
and an integer vector z from column 2. Usually SM stops reading at the
first invalid line, but if you say READ ! all the lines specified with
LINES (or the entire file) are read. Missing numerical fields are set
to be invalid (i.e. they are treated as *); missing string values are
left blank.  You can omit the INTEGERs by specifying an empty format:
READ '' { x y z }; in this case you may specify the types as e.g. "x.d";
the default is ".f" (floating); a column to skip may be specified as ".".

   If INTEGER is invalid (<= 0), the contents of the file are written
to the standard output.

   If VERBOSE is greater than 0, the lines actually read will be reported

   In order to speed up multiple reads of the same file, SM is usually
remembers where is got to in a file; this can be disabled by undefining
the variable $save_read_ptr (which can be done in your .sm file by setting
it to 0).

If your data is in a number of columns (e.g. you have written it out
to a file ten values to a line) you can specify a range of columns,
for example "READ { x 1-4 y 5 z 6-10 }". You can only use ranges for
numerical vectors, and only with the list form of READ.

   READ ROW WORD INTEGER is the same as READ WORD INTEGER, except that
the INTEGER refers to a row number (the LINES command is ignored).
Every column is read into the vector. You can specify string-valued
vectors as for reading columns.

   Instead of using simple column-orientated input it is possible to
specify a format rather like those used by C's `scanf' functions
(Fortran formats are not supported). Unlike scanf, you can provide field
widths -- see the manual for examples, or try something like
        READ '%10f %d:%d' { x y z }
The %n format is supported, and returns the number of fields correctly
matched in the current line; this is only useful in conjunction with
READ !.  As a special case, of you specify an empty format ('') the
named vectors are read as floats from the first n columns of the file.

   READ OLD WORD1 WORD2 defines macro WORD1 to be the the contents of
file WORD2. This is provided for compatibility with Mongo. Any macro
definition (i.e. from a line beginning `def' to a line beginning
`end') is converted to the SM form (i.e. $s not &s) and defined.

   READ EDIT is used to read a set of keymaps from a file. The file
should have 2 lines of header, then pairs of operation_name key_name
where key_name is the name of the key either as a letter, a ^letter,
or \nnn where nnn is in octal. The (complete) default mapping is given
under EDIT

   META READ WORD reads a metafile, as produced with the pseudo-device
META, and executes the enclosed commands on the current device.
