2001-2006
Bernd Schoeller
Bernd
Schoeller
bernd@fams.de 14 September 2006

# 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.

## 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.

make_empty

  This creation routine does not create a help option. It should be used if an own or no help flag should be used.

help_option

  This query allows access to the instance of `AP_DISPLAY_HELP_FLAG` that is created by the creation with make. If the instance was created with make_empty, the result of this query will be Void.

## 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 are 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 calls to start the parser. Any of these calls with call reset_parser prior to parsing, that 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 parts classes.

## Results of parsing

Options and their arguments 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.