ot::auxil
class MultiListOption

A MultiLisOption could be thought of as a container of several BasicOption objects, but with the exception that it allows each BasicOption to appear more than once on the same command line.

A MultiListOption is useful when an application can take a variable number of arguments of the same type (or types). For example the webform sample application uses a MultiListOption to hold details of the form fields expressed on the command line. It assembles fields in the order that they are specified on the command line, and allows both filename fields and text fields. For example the following command line may be passed to the webform sample application:-

    webform -f to:another@acme.com -F thefile:myfile.txt -f subject:File

In the webform sample, the -f and -F options are both handled by the same MultiListOption object, with the result that al the fields can be retrieved in the order they appear on the command line as well allowing the application to determine how each option was specified (i.e. as -F or -f).

See also:

CommandLineParser , BasicOption

MultiListOption

 MultiListOption()

Default constructor. This creates an empty MultiListOption. Before it can usefully be used with a CommandLineParser options should be added via the addOption() method.

MultiListOption

 MultiListOption(const String& longName,
                 CharType shortName,
                 ArgumentType argType)

Constructor taking the details of a single option type. Further option types may be added via the addOption method.

addOption

void addOption(const String& longName,
               CharType shortName,
               ArgumentType argType)

Adds a command line option to the list of options handled by this MultiListOption. The number of options that may be managed by one MultiListOption is limited only by available memory, but each option name must be unique.

Parameters:

longName - the long name for the option.
shortName - the short name for the option. A value of 0 (zero) indicates that the option cannot be specified using a short name.
argType - flag indicating whether or not an argument should follow the option when specified on the command line.

getArgument

String getArgument(size_t index) const

Returns the argument (if any) for an option which was specified on the command line.

Parameters:

index - a zero-based index value which identifies the option item. Every time an option on a command line is recognised as being handled by an object of this class, the option details are stored in an internal array, which is indexed by index.

getHowSpecified

String getHowSpecified(size_t index) const

Returns a String depicting how an option was specified on the command line.

Parameters:

index - a zero-based index value which identifies the option item. Every time an option on a command line is recognised as being handled by an object of this class, the option details are stored in an internal array, which is indexed by index.

getLongName

String getLongName(size_t index) const

Returns the long name for an option which was specified on the command line.

Parameters:

index - a zero-based index value which identifies the option item. Every time an option on a command line is recognised as being handled by an object of this class, the option details are stored in an internal array, which is indexed by index.

getNumPresent

size_t getNumPresent() const

Returns the number of command line options, matching options handled by this MultiListOption, that was specified on the parsed command line. The returned value provides the size of the internal array which is used to store how (and how many) options, which are recognised and managed by this MultiListOption, were specified on the command line.

getShortName

CharType getShortName(size_t index) const

Returns the short name for an option which was specified on the command line.

Parameters:

index - a zero-based index value which identifies the option item. Every time an option on a command line is recognised as being handled by an object of this class, the option details are stored in an internal array, which is indexed by index.

setPresent

virtual void setPresent(const String& howSpecified,
                        OptionType optionTypeUsed,
                        const String& argument)

Called by the CommandLineParser once it has determined that this CommandLineOption has been specified on the command line being parsed. It is usual practice for the implementation to store the fact that a command option has been specified together with any associated argument. The application can then interrogate the object later on to see which options have been specified by the user.

Parameters:

howSpecified - the option as it appears on the command line.
optionTypeUsed - an indication if the option was recognised as a short or long option.
argument - the value of the option's argument (if specified)

Exceptions:

CommandLineException - if the option is invalid and parsing should stop.

testLongOption

virtual ArgumentType testLongOption(const String& option) const

Called by the CommandLineParser to test if a long option contained within the command line matches the long option name accepted by this CommandLineOption. In this case, the implementation should only check that the supplied option matches the first n characters of this option's long name (where n is the length of the supplied option string). This is to allow for long option abreviation.

If the passed option name does match, a value from the CommandLineOption::ArgumentType enumeration is returned to indicate whether an argument is expected for this option.

Parameters:

option - the option as contained within the command line being parsed.

Returns:

One of the values from the CommandLineOption::ArgumentType enumeration. If the option does not match then notknown is returned.

testShortOption

virtual ArgumentType testShortOption(CharType option) const

Called by the CommandLineParser to test if a short option contained within the command line matches the short option name accepted by this CommandLineOption. If the passed option name does match, a value from the CommandLineOption::ArgumentType enumeration is returned to indicate whether an argument is expected for this option.

Parameters:

option - the option as contained within the command line being parsed.

Returns:

One of the values from the CommandLineOption::ArgumentType enumeration. If the option does not match then notknown is returned.