The Rexx.Parser class

Rexx.Parser is the main class of the Rexx Parser framework. A Rexx.Parser object is a parsed version of a Rexx program. The parsing process is configurable, according to a set of options which can be specified when the Rexx.Parser object is created.

The supplied or identified program is parsed at object creation time. The parser version of the program can be accessed using the package method of the Rexx.Parser object. You can also use the firstElement method to access the first element in the parsed program element chain.

new (Class method)

Initializes the Rexx.Parser object with a program that has a certain name, a program source, and some optional options.

Name can be any string that identifies the program to parse. When source is not specified, name is used to identify a file containing the source program.

When specified, source should be an array of strings containing the program to be parsed.

The optional argument options is an array suitable to initialize a Rexx Directory object.

Object creation automatically parses the supplied or identified program. If no error is found during parsing, a Rexx.Package object is created; you can retrieve this object using the package method

firstElement

Returns the first element in the parsed program element chain.

This is a convenience method. The term parser~firstElement is equivalent to parser~package~firstElement.

package

Returns the Rexx.Package object that represents the parsed version of the program.

Available options

The options argument to the new method is an array that will be used to create a Rexx Directory object, using

  dir = .Directory~sendWith("of", options)

This means that every item in options has to be a one-dimensional array containing two elements; the first item is a unique key string, and the second item is the value associated to the key.

Unrecognized keys are ignored. This is the list of currently recognized keys and their corresponding values. Keys are transtaled to uppercase when the Rexx.Parser object is created.

docComments="option1 [,] option2..."

The value associated with the docComments key is a collection of comma- or blank- separated case-insensitive option words. The following options are recognized:

• ALL, the default, means that both standard (block) comments and line comments located immediately before a directive or a callable label are inspected to see if they are doc-comments.
• LINE and MARKDOWN mean that line comments located immediately before a directive or a callable label are inspected to see if they are doc-comments.
• STANDARD, BLOCK and CLASSIC mean that standard comments located immediately before a directive or a callable label are inspected to see if they are doc-comments.

extraLetters=string

The value associated with the extraLetters key is a string containing characters that are to be considered letters, in addition to the ones defined by ooRexx (see the ANSI standard, section 5.3.2). By default, the set of extra letters is empty (that is, letters are limited to the A-Z and a-z ranges, and to the "?", "!" and "_" characters). Markdown and HTML fenced code blocks can specify the value of this key by using the extraLetters=string attribute on the rexx code marker:

  -- This is a valid variable name because 'extraletters="@"' was specified
  VariableUsing@AsALetter_____@@@@@ = 1