NAME
       scan  -  Parse  string  using conversion specifiers in the
       style of sscanf

SYNOPSIS
       scan string format varName ?varName ...?


INTRODUCTION
       This command parses fields from an  input  string  in  the
       same  fashion as the ANSI C sscanf procedure and returns a
       count of the number of conversions performed, or -1 if the
       end  of the input string is reached before any conversions
       have been performed.  String gives the input to be  parsed
       and  format  indicates how to parse it, using % conversion
       specifiers as in sscanf.  Each varName gives the name of a
       variable;  when  a field is scanned from string the result
       is converted back into a string and assigned to the corre-
       sponding variable.  If no varName variables are specified,
       then scan works in an inline manner,  returning  the  data
       that would otherwise be stored in the variables as a list.
       In the inline case, an empty string is returned  when  the
       end  of the input string is reached before any conversions
       have been performed.


DETAILS ON SCANNING
       Scan operates by scanning string and format together.   If
       the  next  character  in  format is a blank or tab then it
       matches any number of white  space  characters  in  string
       (including  zero).   Otherwise,  if it isn't a % character
       then it must match the next character of string.  When a %
       is encountered in format, it indicates the start of a con-
       version specifier.  A conversion specifier contains up  to
       four  fields  after  the  %: a *, which indicates that the
       converted value is to be discarded instead of assigned  to
       a variable; a XPG3 position specifier; a number indicating
       a maximum field width; and a conversion character.  All of
       these  fields are optional except for the conversion char-
       acter.  The fields that are present  must  appear  in  the
       order given above.

       When scan finds a conversion specifier in format, it first
       skips any white-space characters  in  string  (unless  the
       specifier  is  [  or  c).  Then it converts the next input
       characters  according  to  the  conversion  specifier  and
       stores  the result in the variable given by the next argu-
       ment to scan.

       If the % is followed by a decimal number and a  $,  as  in
       ``%2$d'',  then  the variable to use is not taken from the
       next sequential argument.  Instead, it is taken  from  the
       argument  indicated  by the number, where 1 corresponds to
       the first varName.  If there are any positional specifiers
       in  format  then all of the specifiers must be positional.
       Every varName on the  argument  list  must  correspond  to
       exactly one conversion specifier or an error is generated,
       or in the inline case, any position can  be  specified  at
       most  once  and the empty positions will be filled in with
       empty strings.

       The following conversion characters are supported:

       d         The input field must be a decimal  integer.   It
                 is  read in and the value is stored in the vari-
                 able as a decimal string.

       o         The input field must be an octal integer. It  is
                 read  in and the value is stored in the variable
                 as a decimal string.

       x         The input field must be a  hexadecimal  integer.
                 It  is  read  in  and the value is stored in the
                 variable as a decimal string.

       u         The input field must be a decimal integer.   The
                 value  is  stored in the variable as an unsigned
                 decimal integer string.

       i         The input field must be an  integer.   The  base
                 (i.e.  decimal, octal, or hexadecimal) is deter-
                 mined in the same fashion as described in  expr.
                 The value is stored in the variable as a decimal
                 string.

       c         A single character is read  in  and  its  binary
                 value  is  stored  in  the variable as a decimal
                 string.  Initial white space is not  skipped  in
                 this  case,  so  the input field may be a white-
                 space character.  This conversion  is  different
                 from  the  ANSI standard in that the input field
                 always consists of a  single  character  and  no
                 field width may be specified.

       s         The  input  field consists of all the characters
                 up to the next white-space character; the  char-
                 acters are copied to the variable.

       e or f or g
                 The  input field must be a floating-point number
                 consisting of an optional sign, a string of dec-
                 imal digits possibly containing a decimal point,
                 and an optional exponent consisting of an e or E
                 followed  by  an  optional  sign and a string of
                 decimal digits.  It is read in and stored in the
                 variable as a floating-point string.

       [chars]   The  input  field  consists  of  any  number  of
                 characters in chars.   The  matching  string  is
                 stored  in the variable.  If the first character
                 between the brackets is a ] then it  is  treated
                 as part of chars rather than the closing bracket
                 for the set.  If chars contains  a  sequence  of
                 the  form a-b then any character between a and b
                 (inclusive) will match.  If the  first  or  last
                 character  between  the brackets is a -, then it
                 is treated as part of chars rather than indicat-
                 ing a range.

       [^chars]  The  input field consists of any number of char-
                 acters not in chars.   The  matching  string  is
                 stored  in the variable.  If the character imme-
                 diately following the  ^  is  a  ]  then  it  is
                 treated as part of the set rather than the clos-
                 ing bracket for the set.  If  chars  contains  a
                 sequence  of  the  form  a-b  then any character
                 between a and b  (inclusive)  will  be  excluded
                 from  the  set.   If the first or last character
                 between the brackets is a -, then it is  treated
                 as part of chars rather than indicating a range.

       n         No input is  consumed  from  the  input  string.
                 Instead,  the  total  number of chacters scanned
                 from the input string so far is  stored  in  the
                 variable.

       The number of characters read from the input for a conver-
       sion is the largest number that makes sense for that  par-
       ticular conversion (e.g.  as many decimal digits as possi-
       ble for %d, as many octal digits as possible for  %o,  and
       so on).  The input field for a given conversion terminates
       either when a white-space character is encountered or when
       the  maximum field width has been reached, whichever comes
       first.  If a * is present in the conversion specifier then
       no  variable is assigned and the next scan argument is not
       consumed.


DIFFERENCES FROM ANSI SSCANF
       The behavior of the scan command is the same as the behav-
       ior  of the ANSI C sscanf procedure except for the follow-
       ing differences:

       [1]    %p conversion specifier is not currently supported.

       [2]    For %c conversions a single character value is con-
              verted to a decimal string, which is then  assigned
              to the corresponding varName; no field width may be
              specified for this conversion.

       [3]    The l, h, and L  modifiers  are  ignored;   integer
              values  are  always  converted  as if there were no
              modifier present and real values  are  always  con-
              verted as if the l modifier were present (i.e. type
              double is used for the internal representation).

       [4]    If the end of the input string  is  reached  before
              any  conversions  have  been performed and no vari-
              ables are given, and empty string is returned.


KEYWORDS
       conversion specifier, parse, scan
