Next: vector() Up: MacAnova Help File Previous: vecread_file   Contents

vecread_keys

Usage:
List of keywords that can be used on vecread() or readcols().
 Keyword               Value
 badkeyok              T or F*
 badvalue              REAL scalar or MISSING
 bychar                T or F*
 byfields              T or F*
 bylines               T or F*
 bypass                Nonnegative integer
 bywords               T or F*
 echo                  T or F
 file                  CHARACTER scalar file name
 go                    CHARACTER scalar with one character
 n                     Positive integer
 nofileok              T or F*
 printname             T or F*
 prompt                T* or F
 quiet                 T or F*
 silent                T or F*
 skip                  CHARACTER scalar with one character, default "#"
 skipthru              CHARACTER scalar with one character
 startline             Positive integer
 stop                  CHARACTER scalar with one character
 string                CHARACTER scalar or vector
* Default



Keywords: files, input, output
This topic summarizes the use of keyword phrases as arguments to
vecread() which reads data items row by row from a text file.  Type
usage(vecread_keys) for a list of vecread() keywords.  See also topics
vecread() and 'vecread_file'.

Some of the examples use keyword 'string'.  See below for information.

     Keyword phrases specifying that CHARACTER data should be read
bywords:T              Read CHARACTER data by words
  The file is interpreted as a sequence "words" or fields separated by
  commas, or "invisible" characters (spaces, tab characters and ends of
  lines).  The result is a CHARACTER vector, each element of which is a
  word from the file.

  Each word is empty or consists of a sequence of visible characters
  that are not commas.  An empty word occurs before a leading comma,
  after a trailing comma or between two commas with no intervening
  visible characters and is read as "".  For example
  vecread(string:",a ,, b,",bywords:T) returns vector("","a","","b","")

bylines:T              Read CHARACTER data by lines
  Each line read becomes a single element of a CHARACTER vector.  The
  line-separating character "\n" is not included.  All other characters,
  including commas and invisible characters are read.  If no line starts
  with the stopping character, the length of the result is the number of
  lines in the file.

bychar:T               Read CHARACTER data as separate characters
  Each character read, including commas, invisible characters and line
  separating characters, is read as a single element.  If no line starts
  with the stopping character, the length of the result is the number of
  characters in the file.

          Keyword phrase specifying how REAL data will be read
byfields:T             REAL items read by "fields"
  The file is interpreted as a sequence of "fields" separated by commas
  or "invisible" characters.  The result is a REAL vector, each element
  of which is derived from a field in the file.

  A field is either empty or consists of a sequence of visible
  characters that are not commas.  An empty field occurs before a
  leading comma, after a trailing comma or between two commas with no
  intervening visible characters and is read as MISSING.  A non-empty
  field that is a well formed number (for example, -17, 3.14e73 or
  2.7182818) is read as that number.  If the number is too large to be
  represented in the computer (for example -3.1e3000), it is read as
  MISSING.  When a non-empty field is not a well formed number (for
  example 3.5a7 or Foo), it is read as badV when 'badvalue:badV' is an
  argument, or as MISSING otherwise.

                Keyword phrases specifying what to read
file:FileName          Read from file FileName
  This is an alternate way to specify the file to be read.  That is
  vecread(file:FileName [,keyword phrases]) is equivalent to
  vecread(FileName [,keyword phrases]).  Filename must be a quoted
  string or CHARACTER scalar.

string:CharVar         "Read" from CHARACTER scalar or vector CharVar
  CharVar is "read" as if it were a file whose contents are specified by
  CharVar.  Any instances of "\n" are treated as terminating a line.
  When CharVar is a vector, each element is assumed to start a new line.

  When CharVar is a CHARACTER vector, each element is read as for a
  CHARACTER scalar, with each element starting with a new line.  With
  bychar:T, "" is inserted between each element of CharVar.

  Examples:  Suppose S1 is "12\n34" and S2 is vector("12","34").

  vecread(string:S1 [,byfields:T]) and vecread(string:S2 [,byfields:T])
  return vector(12,34).

  vecread(string:S1, bywords:T or bylines:T) and vecread(string:S2,
  bywords:T or bylines:T) return vector("12","34")

  vecread(string:S1, bychars:T) returns vector("1","2","\n","3","4")

  vecread(string:S2, bychars:T) returns vector("1","2","","3","4")

       Keyword phrase limiting the number of items to be returned
n:N                   No more than N items to be returned
  If fewer than N items are found before the stop character or the end
  of the file, a warning message is printed.  N must be a positive
  integer.

  Keyword 'n' is illegal as an argument to readdata().

     Keyword phrases specifying which lines should be read as data.
stop:"$"               Set stop character to '$' (default is "!")
  Reading stops when a stop character is encountered.  With 'bychars:T'
  and 'bylines:T', a stop characters is recognized only as the first
  character in a line.  With 'byfields:T' and 'bywords:T' it is
  recognized only as the first character in a field or word.

  For numerical data, the stop character can be any punctuation
  character except '+', '-', ',', '?'  or  '.', that is, any of
  !"#$%&'()*/:;<=>@[\]^_`{|}~.

  For CHARACTER data, the stop character can be any punctuation
  character except ',', including '+', '-', '?' or '.'.

  For both numerical and CHARACTER data, the stop character can also be
  a "non-ASCII" character (code >= 128 = octal 200 = hexadecimal 80)
  such as "\200", "\377", "\x80" or "\xff", except when reading from
  CONSOLE.  This might be called for when you want to ensure the whole
  file is read, and you know the file does not contain non-ASCII
  characters.

bypass:P               Skips past P lines starting with stop character
  When P > 0, nothing is read or echoed until P lines starting with
  the stop character have been read.  This allows you to read several
  sets of data on the same file provided they are separated by lines
  starting with the stop character.  This takes precedence over all
  other keywords that control which lines are read.  'bypass' is
  illegal with readdata().

startline:M            Sets the first line to be scanned.
  Start reading on line M of the file, that is, the first M-1 lines are
  ignored and never echoed.  This takes precedence over all other
  keywords except bypass that control which lines are read.  Stop,
  skip, skipthru, and go characters are not recognized if they come
  before line M.  The default value for M is 1.  With bypass:P, reading
  starts on line M after the P-th line starting with the stop character.

skipthru:"@"           Set skipthru character to '@' (no default)
  Lines up to and including the first line starting with the skipthru
  character are ignored.  They may be echoed, depending on the values of
  keywords 'echo', 'quiet' and 'silent'.

  The skipthru character can be any character.  When the skipthru
  character is "\n", reading starts after the first completely "white"
  line, that is, a line with no visible characters.

  The skipthru character takes precedence over and can be the same as
  the skip, stop or go characters.  It is ignored until after the lines
  skipped because of keywords 'bypass' and 'startline'.

go:"%"                 Set go character to '%' (no default)
  Reading stops with the first line that does not start with the go
  character.  It is ignored until after the lines skipped because of
  keywords 'bypass' and 'startline'.

skip:"#"               Set skip character to '#' (default is "#")
  Lines starting with skip character are ignored (they may be echoed).

  For numerical data, the allowable skip characters are the same as for
  stop characters.

  For CHARACTER data, any visible printing character, including a comma,
  may be a skip character.

  When the skip character is the same as the stop character (for
  example, stop:"#",skip:"#"), scanning will be stopped only if the stop
  character occurs after the first character in a non-skipped line (for
  example, by a line starting " #..." but not by "#...").

              Keyword phrases controlling what is printed
quiet:F                Prints skipped lines, if any
  The lines printed are those skipped because of the skip or skipthru
  characters, but not those skipped by 'bypass:P' or 'startline:M'.

echo:T or F            Control echoing of lines scanned.
  With echo:T, all lines scanned, including lines skipped because of the
  skip or skipthru character, are echoed to output.  With echo:F, the
  only lines echoed are skipped lines with quiet:F.

  When FileName is CONSOLE and the vecread() command is in a batch file,
  data that is read is echoed to output unless echo:F is an argument.
  This also happens in windowed versions (Macintosh, Windows, Motif)
  even when not reading from a batch file.

silent:T               Suppress all warning messages and echoing
  This is incompatible with echo:T or quiet:F.

printname:F             Suppress printing the name of the file read
  The default is printname:T except with string:CharVar.

prompt:F               Suppresses prompt when reading from CONSOLE

                  Keyword phrases related to anomalies
badkeyok:T             Ignore unrecognized or duplicate keywords
  Without badkeyok:T, unrecognized or duplicate keywords are considered
  errors.  This feature is useful in a macro where a line like
  @x <- vecread("data.txt",silent:T,badkeyok:T,$K) should work,
  even if the argument list to the macro includes keyword 'silent' or
  other keywords not recognized by vecread().

badvalue:badVal        Replace unreadable REAL items by badVal
  When reading REAL data with badvalue:badVal an argument, any
  unreadable items are replaced by badVal, which must be a REAL scalar
  or MISSING.  Without badvalue:badVal, unreadable items are replaced by
  MISSING when 'byfields:T' is an argument and are skipped otherwise.

nofileok:T             Failure to open the file is OK.
  When a file can't be opened, NULL is returned and no error message is
  printed.  Without nofileok:T, this is an error.


Gary Oehlert 2003-01-15