Parsing Arguments

To parse a command-line, you create a new <argument-list-parser>, connect a number of individual <option-parser>s, call parse-arguments, and use the resulting information.

Argument List Parsers


<argument-list-parser>[Sealed Class]

Describes how to parse an argument list, and contains the data found when parsing one.

Superclasses

<object>

Initialization Keywords

None.

Description

An <argument-list-parser> represents both a description of the data to be found in an argument list, and the results of parsing a particular argument list for that data.

Prior to calling parse-arguments for the first time, no useful information can be extracted from an argument list parser. Subsequent calls to parse-arguments will update the data contained within the parser.


regular-arguments[Function]

Returns the regular arguments found by parsing an argument list.

Synopsis

regular-arguments (parser) => (arguments)

Parameters

parserAn instance of <argument-list-parser>.

Return Values

argumentsAn instance of <sequence>.

Description

After calling parse-arguments, this function can be used to find all of the regular arguments that weren't consumed by any option parser.

Option Parsers


<option-parser>[Abstract Open Primary Class]

Parses a single command-line option and any parameters.

Superclasses

<object>

Initialization Keywords

long-options:An instance of <list>. Specifies the long options handled by this parser, represented as strings. Defaults to #().
short-options:An instance of <list>. Specifies the short options handled by this parser, represented as strings. Defaults to #().

Description

Different types of command-line options are parsed according to different rules. An <option-parser> knows how to handle one type of option. The long-options: and short-options: keywords are used to specify which option names should be handled by a given parser.

An option parser can be connected to an <argument-list-parser> for and the values to be found.


option-present?[Function]

Tests whether an option was present on the command-line.

Synopsis

option-present? (parser) => (present?)

Parameters

parserAn instance of <option-parser>.

Return Values

present?An instance of <boolean>.

Description

Returns #t if and only if parse-arguments found at least one corresponding option on the command line. Returns #f if parse-arguments has not been called.


option-value[Function]

Returns the value found by an option parser after processing the command line.

Synopsis

option-value (parser) => (value)

Parameters

parserAn instance of <option-parser>.

Return Values

valueAn instance of <object>.

Description

Returns the value calculated by parser after running parse-arguments. Returns #f if parse-arguments has not been called.

The exact type of value will vary depending on the class of the option parser.

Parsing an Argument List


add-option-parser[Function]

Attaches an <option-parser> to an <argument-list-parser>.

Synopsis

add-option-parser (args-parser, option-parser) => ()

Parameters

args-parserAn instance of <argument-list-parser>.
option-parserAn instance of <option-parser>.

Return Values

None.

Description

Attaches an <option-parser> to an <argument-list-parser>. It is an error to attach an <option-parser> more than once, and no mechanism is provided to detach one.


add-option-parser-by-type[Function]

Create an <option-parser> and add it to an <argument-list-parser>.

Synopsis

add-option-parser-by-type (args-parser, option-parser-type, #rest init-keys) => ()

Parameters

args-parserAn instance of <argument-list-parser>.
option-parser-typeAn instance of subclass(<option-parser>). The class for the new option parser.
init-keysInstances of <object>. Inititialization keywords for for the new option parser.

Return Values

None.

Description

This function is equivalent to calling:

let opt-parser =
  apply(make, option-parser-type, init-keys);
add-option-parser(args-parser, opt-parser);

Most programs will use this function instead of add-option-parser.


parse-arguments[Function]

Parses a list of command-line arguments.

Synopsis

parse-arguments (parser, argument-list) => (success?)

Parameters

parserAn instance of <argument-list-parser>.
argument-listAn instance of <sequence>. The strings to be parsed.

Return Values

success?An instance of <boolean>.

Description

This routine does most of the work in the Parse-Arguments library. It performs a number of different steps:

  1. Split the argument list. If the string "--" appears in the argument list, discard it, and set aside everything to right for later processing.

  2. Chop individual arguments around any equals sign. If any argument contains the character '=', break the argument into three strings: everything before the first occurance of the equals sign, the sign itself, and the remainder of the original string.

  3. Tokenize the argument list. Convert the argument list into a series of tokens. For more details on this process, see the Section called Writing New Option Parser Classes.

  4. Process the argument list from left to right. For each option token, invoke the appropriate option parser (which may consume additional tokens). Record all regular argument tokens for later use. If any other kinds of tokens appear in the argument list, they must be consumed by an option parser or the entire process will fail.

  5. Collect the regular arguments. Take the regular arguments found while parsing, and append any arguments set aside in the first step.

If an error occurs during this process, parsing will stop immediately and parse-arguments will return #f. Otherwise, it will return #t.


option-parser-by-long-name[Function]

Find an option parser, given a corresponding option name.

Synopsis

option-parser-by-long-name (parser, long-name) => (option-parser)

Parameters

parserAn instance of <argument-list-parser>.
long-nameAn instance of <string>.

Return Values

option-parserAn instance of <option-parser>.

Description

This function can be used to recover an option parser previously attached to an <argument-list-parser>.


option-present?-by-long-name[Function]

Determine whether an option was present, given a corresponding option name.

Synopsis

option-present?-by-long-name (parser, long-name) => (present?)

Parameters

parserAn instance of <argument-list-parser>.
long-nameAn instance of <string>.

Return Values

present?An instance of <boolean>.

Description

This function provides an easy way to determine whether a given option parser found anything in an argument list.

Note: If an option has multiple names, any one of them can be used as the argument to this function without changing the result.


option-value-by-long-name[Function]

Find the value of an option, given a corresponding option name.

Synopsis

option-value-by-long-name (parser, long-name) => (value)

Parameters

parserAn instance of <argument-list-parser>.
long-nameAn instance of <string>.

Return Values

valueAn instance of <object>.

Description

This function provides an easy way to find the value of a particular option parser.

Note: If an option has multiple names, any one of them can be used as the argument to this function without changing the result.