PARSE [UPPER] string [template] (also: ARG [template], PULL [template])

[PARSE [UPPER]] ARG template
[PARSE [UPPER]] PULL [template]
PARSE [UPPER] LINEIN [template]
PARSE [UPPER] SOURCE template
PARSE [UPPER] VERSION template
PARSE [UPPER] NUMERIC template
PARSE [UPPER] VAR symbol template
PARSE [UPPER] VALUE expression WITH template

This command is a powerful parser which divides the operand up as
specified by the `template'. If the UPPER keyword is specified, then the
operand is uppercased before parsing.

The "ARG template" and "PULL template" commands are short forms of
"PARSE UPPER ARG template" and "PARSE UPPER PULL template" respectively.

The possible operands are as follows:

ARG   - the command-line arguments, or the arguments passed by a function
        or procedure call, are parsed.
PULL  - the top value on the stack, if one exists, is parsed; otherwise
        a line of input is read from the standard input and parsed as
        described for LINEIN below.  See QUEUE/PUSH for details about
        the stack.
LINEIN- A line is read directly from stdin.  The stack is not affected
        by this instruction.  In general, PULL is recommended in
        preference to LINEIN.

        If a line cannot be read because of an I/O error or EOF
        condition, then the NOTREADY condition will be raised and an
        empty string will be parsed.  The NOTREADY condition is ignored
        unless trapped by SIGNAL ON or CALL ON, in which case it is
        difficult to tell the difference between an empty input line
        and an I/O error.  However, the STREAM() function may be
        used to examine the most recent I/O error on stream "stdin".

        NOTE: If the program is interrupted (via ^C) while input is being
              read, then the characters which have been read in may be
              lost, but the remainder of a partially-input line will
              remain to be read again.

SOURCE- An implementation-dependent string representing the `source' of
        the program is parsed.
        In this implementation, the string contains five words:
         1. the system under which the interpreter runs (always UNIX)
         2. the way in which the program was called (one of COMMAND,
            FUNCTION or SUBROUTINE, depending whether the program was
            invoked by a command shell or as a function or subroutine)
         3. the name of the file containing the program, with the full
            path name (unless no directory was specified and getwd could
            not name the current directory)
         4. the name by which the program was called (always without a
            path name).
         5. the environment name which was current when the program
            started up
VERSION-A string representing the version of the REXX interpreter is
        parsed. This contains five words:
         1. A word describing the language, of which the first four
            letters are always REXX. In this implementation the word is
            REXX/imc.
         2. A string representing the version number (e.g. 1.0)
         3,4,5. The date on which the interpreter was compiled, in the
            same format as the DATE() function (e.g. 18 May 1990).
NUMERIC-The current NUMERIC settings are parsed.  There are three words
        in the string to be parsed: NUMERIC DIGITS, NUMERIC FUZZ and
        NUMERIC FORM respectively.
VAR   - The symbol specified is evaluated, and if it represents
        a currently defined variable, its value is substituted. The
        result is then parsed.
VALUE - The expression between "VALUE" and "WITH" is evaluated and then
        parsed (note that WITH is a reserved keyword in this instruction)

If no template is supplied, the information to be parsed is collected and
then thrown away.

The "ARG" and "VALUE" forms may parse more than one string at once. This
comes about with "ARG" when a function or procedure call (note - not a
command line call) passes more than one argument, or with "VALUE" when
the expression contains comma separators. In this case, the parse
template may contain commas. The part of the template before the first
comma applies to the first operand string, that part between the first
and second commas applies to the second string, and so on. E.g.

 PARSE VALUE 43 56,5*9,hello,there WITH template1,template2,
 
Here template1 applies to "43 56"; template2 applies to "5*9" and no
other parsing takes place. Note that there does not have to be a template
for each operand string, and also that there does not have to be an
operand string for each template (in this case the extra templates will
be applied to the empty string).

LOCAL: Parsing multiple strings with the PARSE VALUE construction is a
       local extension.

A parse template obeys the following grammar. A symbol in brackets
indicates that that symbol may be optionally present. A character in
single quotes indicates that that character should be typed literally.
A symbol in double quotes is a terminal symbol, indicating the
appropriate REXX entity should be present.

 template        -> [firstPosition] assignments [assignments]
 assignments     -> [nextPosition] varlist [stopPosition]
 varlist         -> varname [varlist]
 varname         ->   "non-constant symbol"
                    | '.'
 firstPosition   -> position
 nextPosition    -> position [nextPosition]
 stopPosition    -> position
 position        ->   searchPosition
                    | absPosition
                    | relPosition
                    | '(' "expression" ')'
 searchPosition  -> "string constant"
 absPosition     ->   "integer"
                    | '=' numexpr
 relPosition     ->   '+' numexpr
                    | '-' numexpr
 numexpr         ->   "integer"
                    | '(' "integer expression" ')'

Each position symbol in this grammar indicates a column number to the
parser. Positions are translated to column numbers (numbered from 1 up to
l+1, where l is the length of the string being parsed) in the following
way. Note that the absPosition indicator "1" is implicitly present
before and after any parse template.

absPosition:    gives the column number directly, except that numbers not
                between 1 and l+1 are translated into 1 or l+1 as
                appropriate.
searchPosition: searches for the given string constant in the string
                being parsed, starting from the most recent column number
                Usually, two column numbers result: the column number of
                the first character which matched, and that of the first
                character after the matching string. The latter number is
                suppressed if the next position indicator (if any) is a
                `relPosition'. If the string is not found, then the
                single column number l+1 results.
"expression":   evaluates the expression and then treats it as the string
                constant of a searchPosition
relPosition:    The given positive or negative number is added to the
                previous column number to give the result. As for an
                absolute position, numbers which are out of range are
                translated into 1 or l+1 as appropriate.

For example, given the string "hello, world, hello!" and the position
indicators 1 "ello" +4 ! 5 -3 'x' -2 1, the resulting column numbers
would be:
  1  (the given number)
  2  (the first character of "ello" - the second number is suppressed)
  6  (+4 characters from the previous position)
 20}{(the first character of "!")
 21}{(the first character after "!")
  5  (the given number)
  2  (-3 characters from 5)
 21  (the end of the string, since "x" is not found)
 19  (-2 characters from 21)
  1  (the given number)

The position indicators are translated into column numbers independent
of the varlist, except in one case described below. Thus the parse
template may be reduced by the above rules into a sequence of column
numbers and varlists. Taking into account the rule that each template is
implicitly prefixed and suffixed by the column number "1", each varlist
thus occurs between two column numbers. Each varlist is treated
separately, as follows:

Denote the varlist, together with the column numbers immediately before
and after the varlist, as m v1 v2 ... vk n. If m<n, or if m=n and
n resulted from a search, then there exists a well-defined substring s of
the string being parsed, which starts at column m and is of length n-m.
(this string ends at, but does not include, column n). Otherwise, let s
be that substring which starts at column m and continues to the end of
the string being parsed. Then the string s is divided between the
variables of the varlist by assigning the blank-delimited tokens to v1,
v2, ... in order. If there are more varnames in the varlist than there
are blank-delimited tokens, then the extra varnames are assigned with the
empty string. The tokens assigned to varnames v1, v2, ... , v(k-1) will
contain no leading or trailing blanks, but the token assigned to vk will
contain all blanks which occur after v(k-1), except for the one blank
immediately after v(k-1).

Each varname is either a symbol name or a dot. If the varname is a dot,
then the token which would be assigned to it is thrown away. Otherwise
the token is assigned to it in the usual way, just as if there had been
an instruction: symbol = token

NOTE: Most versions of REXX allow only a symbol name between parentheses
      where this version allows an arbitrary expression.

The one case in which the presence of a varlist may affect the
translation from position indicators to column numbers is when one or
more of the symbols mentioned in an "expression" is also stated in a
varlist. Hence:

PARSE VALUE "s/this/that" WITH 2 delim +1 first (delim) second

will assign "/" to delim, "this" to first and "that" to second. This is
because the variable delim is assigned as soon as the "+1" is reached.
This provides a way to provide commands (such as locate commands) which
take any string parameter and also some options. It allows any delimiter
to separate the parameter from the options.
However,

PARSE VALUE "s / this/that" WITH . delim first (delim) second

will not have the same effect, since delim and first are not assigned
until after the expression (delim) has been searched for.

Note that the symbols are assigned in order from left to right, so

PARSE VALUE "1 2 3" WITH a x.a y.a

will assign 1 to a, then 2 to x.1, then 3 to y.1

Other Examples:

PARSE VALUE "Hello there ! etc.." WITH a b ! . "c" c

will assign "Hello" to a and "there " to b, then throw away " et" and
assign ".." to c.

PARSE VALUE "123456789" WITH a +4 b 6 c

will assign "1234" to a, "5" to b, and "6789" to c.

PARSE VALUE "   multiple   spaces   between   words" WITH a b c

will assign "multiple" to a, "spaces" to b and "  between   words" to c.

PARSE VALUE "a  b  c  d  e  f" WITH "b" a b "e"

will assign "c" to a and " d  " to b.

PARSE VALUE "hello-there" WITH a "-" b -1 c +1

This assigns "hello" to a, "-there" to b and "o" to c.