>>-PARSE--+-------+--+----------+------------------------------->
+-UPPER-+ +-CASELESS-+
+-LOWER-+
>--+-ARG-------------------------+--+---------------+--;-------><
+-LINEIN----------------------+ +-template_list-+
+-PULL------------------------+
+-SOURCE----------------------+
+-VALUE--+------------+--WITH-+
| +-expression-+ |
+-VAR--name-------------------+
+-VERSION---------------------+Note: You can specify UPPER and CASELESS or LOWER and CASELESS in either order.
PARSE assigns data from various sources to one or more variables according to the rules of parsing. (See Parsing.)
If you specify UPPER or LOWER, any character strings to be parsed are first translated. Otherwise no translation takes place during the parsing. If you specify UPPER, the strings are translated to uppercase. If you specify LOWER, the strings are translated to lowercase.
If you specify CASELESS, character string matches during parsing are made independent of the case. This means a letter in uppercase is equal to the same letter in lowercase.
The template_list can be a single template or list of templates separated by commas. Each template consists of one or more symbols separated by blanks, patterns, or both.
Each template is applied to a single source string. Specifying several templates is not a syntax error, but only the PARSE ARG variant can supply more than one non-null source string. See Parsing Several Strings for information on parsing several source strings.
If you do not specify a template, no variables are set but the data is prepared for parsing, if necessary. Thus for PARSE PULL, a data string is removed from the current data queue, for PARSE LINEIN (and PARSE PULL if the queue is empty), a line is taken from the default input stream, and for PARSE VALUE, expression is evaluated. For PARSE VAR, the specified variable is accessed. If it does not have a value, the NOVALUE condition is raised, if it is enabled.
The following list describes the data for each variant of the PARSE instruction.
parses the strings passed to a program or internal routine as input arguments. (See the ARG instruction in ARG for details and examples.)
Note: Parsing uses the argument string values. The USE ARG instruction provides access to string and non-string argument objects. You can also retrieve or check the argument objects to a Rexx program or internal routine with the ARG built-in function (see ARG (Argument)).
parses the next line of the default input stream. (See Input and Output Streams for a discussion of Rexx input and output.) PARSE LINEIN is a shorter form of the following instruction:
>>-PARSE VALUE LINEIN()WITH--+---------------+--;--------------><
+-template_list-+If no line is available, program execution usually pauses until a line is complete. Use PARSE LINEIN only when direct access to the character input stream is necessary. Use the PULL or PARSE PULL instructions for the usual line-by-line dialog with the user to maintain generality.
To check if any lines are available in the default input stream, use the built-in function LINES. See LINES (Lines Remaining) and LINEIN (Line Input).
parses the next string of the external data queue. If the external data queue is empty, PARSE PULL reads a line of the default input stream (the user's terminal), and the program pauses, if necessary, until a line is complete. You can add data to the head or tail of the queue by using the PUSH and QUEUE instructions, respectively. You can find the number of lines currently in the queue with the QUEUED built-in function. (See QUEUED.) The queue remains active as long as the language processor is active. Other programs in the system can alter the queue and use it to communicate with programs written in Rexx. See also the PULL instruction in PULL.
Note: PULL and PARSE PULL read the current data queue. If the queue is empty, they read the default input stream, STDIN (typically, the keyboard).
parses data describing the source of the program running. The language processor returns a string that does not change while the program is running.
The source string contains operating system name, followed by either COMMAND, FUNCTION, METHOD, or SUBROUTINE, depending on whether the program was called as a host command or from a function call in an expression or as a method of an object or using the CALL instruction. These two tokens are followed by the complete path specification of the program file.
The string parsed might, therefore, look like this:
Windows95 COMMAND C:\MYDIR\RexxTRY.CMD
or
WindowsNT COMMAND C:\MYDIR\RexxTRY.CMD
or
LINUX COMMAND /opt/orexx/bin/rexxtry.cmd
parses the data, a character string, that is the result of evaluating expression. If you specify no expression, the null string is used. Note that WITH is a subkeyword in this context and cannot be used as a symbol within expression.
Thus, for example:
PARSE VALUE time() WITH hours ":" mins ":" secs
gets the current time and splits it into its constituent parts.
parses the character string value of the variable name. The name must be a symbol that is valid as a variable name, which means it cannot start with a period or a digit. Note that the variable name is not changed unless it appears in the template, so that, for example:
PARSE VAR string word1 string
removes the first word from string, puts it in the variable word1, and assigns the remainder back to string.
PARSE UPPER VAR string word1 string
also translates the data from string to uppercase before it is parsed.
parses information describing the language level and the date of the language processor. This information consists of five blank-delimited words:
The string REXX-ooRexx
The language level description, for example 6.00.
Three tokens that describe the language processor release date in the same format as the default for the DATE built-in function (see DATE), for example, "27 Sep 1997".