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-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 toparse-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
parser An instance of <argument-list-parser>
.
Return Values
arguments An 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-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. Thelong-options:
andshort-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
parser An instance of <option-parser>
.
Return Values
present? An instance of <boolean>
.
Description
Returns
#t
if and only ifparse-arguments
found at least one corresponding option on the command line. Returns#f
ifparse-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
parser An instance of <option-parser>
.
Return Values
value An instance of <object>
.
Description
Returns the value calculated by parser after running
parse-arguments
. Returns#f
ifparse-arguments
has not been called.The exact type of value will vary depending on the class of the option parser.
add-option-parser | [Function] |
Attaches an<option-parser>
to an<argument-list-parser>
.
Synopsis
add-option-parser (args-parser, option-parser) => ()
Parameters
args-parser An instance of <argument-list-parser>
.option-parser An 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-parser An instance of <argument-list-parser>
.option-parser-type An instance of subclass(<option-parser>)
. The class for the new option parser.init-keys Instances 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
parser An instance of <argument-list-parser>
.argument-list An 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:
Split the argument list. If the string
"--"
appears in the argument list, discard it, and set aside everything to right for later processing.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.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.
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.
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
parser An instance of <argument-list-parser>
.long-name An instance of <string>
.
Return Values
option-parser An 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
parser An instance of <argument-list-parser>
.long-name An 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
parser An instance of <argument-list-parser>
.long-name An instance of <string>
.
Return Values
value An 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.