| The Argument Parser |
  |
The argument parser is provided through the class
AP_PARSER. The parser will parse
through the command line arguments, and look for matching
options within the set of registered options. If a matching
option is found, the parser will notify the option of the
occurrence, supplying it (through the
last_option_parameter query) with a
parameter that was given to the option if the option required
it. The parser is automatically equiped with a help option.
There is also a class AP_BASIC_PARSER
which does not have a help option by default.
Creation
The following features are either used during creation
or query the results of the object creation.
-
make
-
This is the normal creation routine that
initializes the parser with sane defaults.
-
help_option
-
This query allows access to the instance of
AP_DISPLAY_HELP_FLAG
that is created by the creation with
make.
Parser settings
The AP_PARSER is the class that
captures the global options of the parsing process.
-
application_description
-
The application description describes the
overall purpose of the application. It is used
for the generation of help texts and can be
set by the
set_application_description
feature.
-
parameters_description
-
This text is a short description of the kind
of (non-option) parameters expected by the
application. The default value is 'parameters
...', but should be set to a more descriptive text.
It can be set by the
set_parameters_description
feature and is also used for the generation of the help
text.
-
options
-
This is the DS_LIST of
options that is used for command line
parsing. New options are registered with the
parser by adding them to the list (for example
with
force_last. Also,
other operations from
DS_LIST are valid, like
removing or sorting options. The validity of
all options can be checked at any time with
the valid_options
query.
-
alternative_options_lists
-
The purpose of this list is described in
section Alternative options
lists. It is also a DS_LIST
and also changed directly, as with the options
query. The validity of all options provided with
alternative options list can be checked at any
time with the
valid_options
query, too.
-
error_handler
-
This query returns the current error handler of the parser. A default
error handler is provided through object creation. The error handler
can be changed using the set_error_handler
command.
Parsing arguments
The parser offers the following features to start the parser.
Any of these features calls reset_parser
prior to parsing, which will reset the parser and the registered
options.
-
parse_arguments
-
The parser parses the arguments passed to the
application. The arguments are read directly
from the shared
KL_ARGUMENTS class.
-
parse_array
-
The parser parses the arguments from a
supplied ARRAY.
-
parse_list
-
The parser parses the arguments from a
supplied DS_LIST. The
cursor on the list will be used during parsing
to mark the current argument that is parsed
and should not be moved by other clients.
Results of parsing
Options and their parameters can be directly read from the
corresponding instances. The other results of the parsing
process are provided through the following queries:
-
parameters
-
This DS_LIST
collects all non-option arguments that were
encountered during parsing of the command
line.
