This value‐semantic class parses, validates, and provides access to command‐line arguments. The constructor takes the specification describing the command‐line arguments. Once created, printUsage can be invoked to print the usage syntax. The parse method takes command‐line arguments and validates them against the specification provided at creation, writing a suitable message to an optionally‐specified stream in case of a parsing error. Once parsed, options and values can be accessed using various accessors. The class has a set of theType methods (e.g., theString, theInt) that provide access, by name, to the value of the indicated option. It is also possible to link a variable with an option in the specification; doing so will cause the variable to be loaded with the option value once parse has been invoked. The options method returns a balcl::CommandLineOptionsHandle object referring to the option names and their values. A similar but different method, specifiedOptions, is suitable for overwriting other configuration parameters (possibly obtained from a configuration file).

Synopsis

Declared in <balcl_commandline.h>

class CommandLine;

Member Functions

Name

Description

CommandLine [constructor]

Constructors

~CommandLine [destructor]

Destroy this command‐line object.

operator=

Assign to this command‐line object the value of the specified rhs command‐line object and return a reference providing modifiable access to this object. The behavior is undefined unless both rhs and this object are valid (i.e., isValid() and rhs.isValid() both return true).

allocator

Return the allocator used by this object to supply memory. Note that if no allocator was supplied at construction the currently installed default allocator at construction is used.

hasOption

Return true if this command‐line object is configured with an option having the specified name, and false otherwise.

hasValue

Return true if this command‐line object's option having the specified name has a defined value, and false otherwise. An option has a defined value if isSpecified(name) or if a default value was configured for the option (see {Occurrence Information Field}). The behavior is undefined unless this command‐line object isParsed() and hasOption(name).

isParsed

Return true if this object was parsed successfully, and false otherwise. Note that if parse was invoked but failed, this method returns false.

isSpecified

isSpecified overloads

isValid

Return true if this object is in a valid state, and false otherwise. Objects are in a valid state after construction from a valid set of option specifications (see the function‐level documentation of the isValidOptionSpecificationTable method) and after a successful invocation of the parse method. Conversely, construction from invalid option specifications or an unsuccessful invocation of the parse method leaves this object in an invalid state. Note that additional object state is available from the isParsed accessor method.

numSpecified

Return the number of times the option with the specified name has been entered on the command line, or 0 if name is not the name of a field in the command‐line specification passed at construction to this object. Note that, in order to receive the valid number of occurrences, the command line must be successfully parsed.

options

Return the command‐line options and their values. If an option was not entered on the command line and a default value was provided for that option, then that default value will be used (note the difference with the specifiedOptions method). If an option was not entered on the command line and no default value was provided for that option, then the corresponding option will be in a null state. The behavior is undefined unless isParsed returns true.

parse

parse overloads

position

Return the position where the option with the specified name has been entered on the command line (i.e., the index in the argv argument to the parse method). If the option was specified multiple times on the command line, return the position of the first instance. If the option was specified as an environment variable but not on the command line, return ‐2. If the option was not specified, return ‐1. The behavior is undefined unless the option is of scalar type.

positions

Return the positions where the option with the specified name has been entered on the command line (i.e., the offset in the argv argument to the parse method). If the option was not specified, return an empty vector. Note that, in order to receive the valid positions, the command line must be successfully parsed.

print

Format this command‐line object to the specified output stream at the (absolute value of) the optionally specified indentation level and return a reference to stream. If level is specified, optionally specify spacesPerLevel, the number of spaces per indentation level for this object. If level is negative, suppress indentation of the first line. The behavior is undefined unless 0 <= spacesPerLevel. If stream is not valid on entry, this operation has no effect.

printUsage

printUsage overloads

specifiedOptions

Return the command‐line options and their values. If an option was not entered on the command line or set through an environment variable, then the option will be in a null state (note the difference with the options method). This method is especially useful for overwriting some other configuration (potentially obtained from a configuration file). The behavior is undefined unless isParsed returns true.

theBool

Return the value of the option having the specified name. The value returned matches that returned by isSpecified(name). The behavior is undefined unless this command‐line object isParsed(), hasOption(name), and OptionType::e_BOOL == type(name).

theChar

Return the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_CHAR == type(name), and hasValue(name).

theCharArray

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_CHAR_ARRAY == type(name), and hasValue(name).

theDate

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_DATE == type(name), and hasValue(name).

theDateArray

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_DATE_ARRAY == type(name), and hasValue(name).

theDatetime

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_DATETIME == type(name), and hasValue(name).

theDatetimeArray

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_DATETIME_ARRAY == type(name), and hasValue(name).

theDouble

Return the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_DOUBLE == type(name), and hasValue(name).

theDoubleArray

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_DOUBLE_ARRAY == type(name), and hasValue(name).

theInt

Return the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_INT == type(name), and hasValue(name).

theInt64

Return the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_INT64 == type(name), and hasValue(name).

theInt64Array

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_INT64_ARRAY == type(name), and hasValue(name).

theIntArray

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_INT_ARRAY == type(name), and hasValue(name).

theString

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_STRING == type(name), and hasValue(name).

theStringArray

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_STRING_ARRAY == type(name), and hasValue(name).

theTime

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_TIME == type(name), and hasValue(name).

theTimeArray

Return a const reference to the value of the option having the specified name. The behavior is undefined unless this command‐line object isParsed(), hasOption(name), OptionType::e_TIME_ARRAY == type(name), and hasValue(name).

type

Return the type of the option having the specified name. The behavior is undefined unless this command‐line object hasOption(name).

operator BloombergLP::bslmf::NestedTraitDeclaration<CommandLine, HasPrintMethod>

Nested trait declaration for bslma::UsesBslmaAllocator.

Static Member Functions

Name

Description

isValidOptionSpecificationTable

isValidOptionSpecificationTable overloads

Non-Member Functions

Name

Description

operator!=

Return false if the specified lhs and rhs have the same value, and true otherwise. Two command‐line arguments do not have the same value if and only if they have different command‐line specifications, or one is parsed successfully but the other is not, or neither is, or else both have the same specification and both are parsed successfully but they have different values for at least one flag, option or non‐option argument. Note that two identical copies built with the same option table, but unparsed, are not equal.

operator==

Return true if the specified lhs and rhs have the same value, and false otherwise. Two command‐line arguments have the same value if and only if they are both parsed successfully and have the same command‐line specifications and the same values for flags, options, and non‐option arguments. Note that two identical copies built with the same option table, but unparsed, are not equal.

Created with MrDocs