|
Quick Links: |
#include <balcl_commandline.h>
Public Member Functions | |
| BSLMF_NESTED_TRAIT_DECLARATION (CommandLine, bslma::UsesBslmaAllocator) | |
| BSLMF_NESTED_TRAIT_DECLARATION (CommandLine, bdlb::HasPrintMethod) | |
| template<int LENGTH> | |
| CommandLine (const OptionInfo(&specTable)[LENGTH], bsl::ostream &stream, bslma::Allocator *basicAllocator=0) | |
| template<int LENGTH> | |
| CommandLine (OptionInfo(&specTable)[LENGTH], bsl::ostream &stream, bslma::Allocator *basicAllocator=0) | |
| template<int LENGTH> | |
| CommandLine (const OptionInfo(&specTable)[LENGTH], bslma::Allocator *basicAllocator=0) | |
| template<int LENGTH> | |
| CommandLine (OptionInfo(&specTable)[LENGTH], bslma::Allocator *basicAllocator=0) | |
| CommandLine (const OptionInfo *specTable, int length, bslma::Allocator *basicAllocator=0) | |
| CommandLine (const OptionInfo *specTable, int length, bsl::ostream &stream, bslma::Allocator *basicAllocator=0) | |
| CommandLine (const CommandLine &original, bslma::Allocator *basicAllocator=0) | |
| ~CommandLine () | |
| CommandLine & | operator= (const CommandLine &rhs) |
| int | parse (int argc, const char *const argv[]) |
| int | parse (int argc, const char *const argv[], bsl::ostream &stream) |
| bool | hasOption (const bsl::string_view &name) const |
| bool | hasValue (const bsl::string_view &name) const |
| bool | isParsed () const |
| bool | isSpecified (const bsl::string_view &name) const |
| bool | isSpecified (const bsl::string_view &name, int *count) const |
| bool | isValid () const |
| int | numSpecified (const bsl::string_view &name) const |
| CommandLineOptionsHandle | options () const |
| int | position (const bsl::string_view &name) const |
| const bsl::vector< int > & | positions (const bsl::string_view &name) const |
| void | printUsage () const |
| void | printUsage (bsl::ostream &stream) const |
| CommandLineOptionsHandle | specifiedOptions () const |
| OptionType::Enum | type (const bsl::string_view &name) const |
| bool | theBool (const bsl::string_view &name) const |
| char | theChar (const bsl::string_view &name) const |
| int | theInt (const bsl::string_view &name) const |
| bsls::Types::Int64 | theInt64 (const bsl::string_view &name) const |
| double | theDouble (const bsl::string_view &name) const |
| const bsl::string & | theString (const bsl::string_view &name) const |
| const bdlt::Datetime & | theDatetime (const bsl::string_view &name) const |
| const bdlt::Date & | theDate (const bsl::string_view &name) const |
| const bdlt::Time & | theTime (const bsl::string_view &name) const |
| const bsl::vector< char > & | theCharArray (const bsl::string_view &name) const |
| const bsl::vector< int > & | theIntArray (const bsl::string_view &name) const |
| const bsl::vector < bsls::Types::Int64 > & | theInt64Array (const bsl::string_view &name) const |
| const bsl::vector< double > & | theDoubleArray (const bsl::string_view &name) const |
| const bsl::vector< bsl::string > & | theStringArray (const bsl::string_view &name) const |
| const bsl::vector < bdlt::Datetime > & | theDatetimeArray (const bsl::string_view &name) const |
| const bsl::vector< bdlt::Date > & | theDateArray (const bsl::string_view &name) const |
| const bsl::vector< bdlt::Time > & | theTimeArray (const bsl::string_view &name) const |
| bslma::Allocator * | allocator () const |
| bsl::ostream & | print (bsl::ostream &stream, int level=0, int spacesPerLevel=4) const |
Static Public Member Functions | |
| template<int LENGTH> | |
| static bool | isValidOptionSpecificationTable (const OptionInfo(&specTable)[LENGTH]) |
| template<int LENGTH> | |
| static bool | isValidOptionSpecificationTable (OptionInfo(&specTable)[LENGTH]) |
| template<int LENGTH> | |
| static bool | isValidOptionSpecificationTable (const OptionInfo(&specTable)[LENGTH], bsl::ostream &stream) |
| template<int LENGTH> | |
| static bool | isValidOptionSpecificationTable (OptionInfo(&specTable)[LENGTH], bsl::ostream &stream) |
| static bool | isValidOptionSpecificationTable (const OptionInfo *specTable, int length) |
| static bool | isValidOptionSpecificationTable (const OptionInfo *specTable, int length, bsl::ostream &stream) |
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).
See Component balcl_commandline
| balcl::CommandLine::CommandLine | ( | const OptionInfo(&) | specTable[LENGTH], | |
| bsl::ostream & | stream, | |||
| bslma::Allocator * | basicAllocator = 0 | |||
| ) |
| balcl::CommandLine::CommandLine | ( | OptionInfo(&) | specTable[LENGTH], | |
| bsl::ostream & | stream, | |||
| bslma::Allocator * | basicAllocator = 0 | |||
| ) |
Create an object accepting the command-line options described by the specified (statically-initialized) specTable. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The behavior is undefined unless specTable satisfies the isValidOptionSpecificationTable function. Note that an appropriate error message is written to the specified stream.
| balcl::CommandLine::CommandLine | ( | const OptionInfo(&) | specTable[LENGTH], | |
| bslma::Allocator * | basicAllocator = 0 | |||
| ) | [explicit] |
| balcl::CommandLine::CommandLine | ( | OptionInfo(&) | specTable[LENGTH], | |
| bslma::Allocator * | basicAllocator = 0 | |||
| ) | [explicit] |
Create an object accepting the command-line options described by the specified (statically-initialized) specTable. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The behavior is undefined unless specTable satisfies the isValidOptionSpecificationTable function. Note that an appropriate error message is written to bsl::cerr.
| balcl::CommandLine::CommandLine | ( | const OptionInfo * | specTable, | |
| int | length, | |||
| bslma::Allocator * | basicAllocator = 0 | |||
| ) |
Create an object accepting the command-line options described by the specified specTable of the specified length. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The behavior is undefined unless specTable satisfies the isValidOptionSpecificationTable function. Note that an appropriate error message is written to bsl::cerr. Also note that specTable need not be statically initialized.
| balcl::CommandLine::CommandLine | ( | const OptionInfo * | specTable, | |
| int | length, | |||
| bsl::ostream & | stream, | |||
| bslma::Allocator * | basicAllocator = 0 | |||
| ) |
Create an object accepting the command-line options described by the specified specTable of the specified length. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The behavior is undefined unless specTable satisfies the isValidOptionSpecificationTable function. Note that an appropriate error message is written to the specified stream. Also note that specTable need not be statically initialized.
| balcl::CommandLine::CommandLine | ( | const CommandLine & | original, | |
| bslma::Allocator * | basicAllocator = 0 | |||
| ) |
Create a command-line object having the value of the specified original command line, if the original is parsed, and otherwise having a state such that parsing command-line arguments results in the same value as parsing the same command-line arguments with the original. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The behavior is undefined unless original is valid (i.e., original.isValid() returns true).
| balcl::CommandLine::~CommandLine | ( | ) |
Destroy this command-line object.
| balcl::CommandLine::BSLMF_NESTED_TRAIT_DECLARATION | ( | CommandLine | , | |
| bslma::UsesBslmaAllocator | ||||
| ) |
| balcl::CommandLine::BSLMF_NESTED_TRAIT_DECLARATION | ( | CommandLine | , | |
| bdlb::HasPrintMethod | ||||
| ) |
| static bool balcl::CommandLine::isValidOptionSpecificationTable | ( | const OptionInfo(&) | specTable[LENGTH] | ) | [static] |
| static bool balcl::CommandLine::isValidOptionSpecificationTable | ( | OptionInfo(&) | specTable[LENGTH] | ) | [static] |
| static bool balcl::CommandLine::isValidOptionSpecificationTable | ( | const OptionInfo(&) | specTable[LENGTH], | |
| bsl::ostream & | stream | |||
| ) | [static] |
| static bool balcl::CommandLine::isValidOptionSpecificationTable | ( | OptionInfo(&) | specTable[LENGTH], | |
| bsl::ostream & | stream | |||
| ) | [static] |
Return true if the specified (statically-initialized) specTable of the specified LENGTH has a valid set of command-line option specifications, and false otherwise. Optionally specify stream to which error messages are written. If no stream is specified, this method produces no output. See Valid balcl::OptionInfo Specifications for a description of the validity requirements.
| static bool balcl::CommandLine::isValidOptionSpecificationTable | ( | const OptionInfo * | specTable, | |
| int | length | |||
| ) | [static] |
| static bool balcl::CommandLine::isValidOptionSpecificationTable | ( | const OptionInfo * | specTable, | |
| int | length, | |||
| bsl::ostream & | stream | |||
| ) | [static] |
Return true if the specified specTable of the specified length has a valid set of command-line option specifications, and false otherwise. Optionally specify stream to which error messages are written. If no stream is specified, this method produces not output. See Valid balcl::OptionInfo Specifications for a description of the validity requirements. The behavior is undefined unless 0 <= length. Note that specTable need not be statically initialized.
| CommandLine& balcl::CommandLine::operator= | ( | const CommandLine & | rhs | ) |
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).
| int balcl::CommandLine::parse | ( | int | argc, | |
| const char *const | argv[] | |||
| ) |
| int balcl::CommandLine::parse | ( | int | argc, | |
| const char *const | argv[], | |||
| bsl::ostream & | stream | |||
| ) |
Parse the command-line arguments contained in the array starting at the specified argv having the specified argc length. Optionally specify a stream to which an appropriate error message is written if parsing fails. If stream is not specified, bsl::cerr is used. Return 0 on success, and a non-zero value otherwise. After a successful call true == isParsed(), true == isValid(), and the information provided by argv can be viewed via the accessors. After an unsuccessful call false == isParsed() and false == isValid(). The behavior is undefined unless false == isParsed() and true == isValid(). Note that the behavior is undefined if parse is invoked more than once on an object (successful or not).
| bool balcl::CommandLine::hasOption | ( | const bsl::string_view & | name | ) | const |
Return true if this command-line object is configured with an option having the specified name, and false otherwise.
| bool balcl::CommandLine::hasValue | ( | const bsl::string_view & | name | ) | const |
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).
| bool balcl::CommandLine::isParsed | ( | ) | const |
Return true if this object was parsed successfully, and false otherwise. Note that if parse was invoked but failed, this method returns false.
| bool balcl::CommandLine::isSpecified | ( | const bsl::string_view & | name | ) | const |
| bool balcl::CommandLine::isSpecified | ( | const bsl::string_view & | name, | |
| int * | count | |||
| ) | const |
Return true if the option with the specified name has been entered on the command line and, if the optionally specified count is not 0, load into count the number of times the option name has been entered on the command line; otherwise, return false and leave count unaffected. Note that, in order to receive the valid value, the command line must be successfully parsed.
| bool balcl::CommandLine::isValid | ( | ) | const |
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.
| int balcl::CommandLine::numSpecified | ( | const bsl::string_view & | name | ) | const |
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.
| CommandLineOptionsHandle balcl::CommandLine::options | ( | ) | const |
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.
| int balcl::CommandLine::position | ( | const bsl::string_view & | name | ) | const |
Return the position 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 -1. The behavior is undefined unless the option is of scalar type.
| const bsl::vector<int>& balcl::CommandLine::positions | ( | const bsl::string_view & | name | ) | const |
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.
| void balcl::CommandLine::printUsage | ( | ) | const |
| void balcl::CommandLine::printUsage | ( | bsl::ostream & | stream | ) | const |
Print usage to the specified output stream, describing what the command line should look like. If stream is not specified, print usage to stderr. This method can be invoked at any time, even before parse has been invoked on this object.
| CommandLineOptionsHandle balcl::CommandLine::specifiedOptions | ( | ) | const |
Return the command-line options and their values. If an option was not entered on the command line, 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.
| OptionType::Enum balcl::CommandLine::type | ( | const bsl::string_view & | name | ) | const |
Return the type of the option having the specified name. The behavior is undefined unless this command-line object hasOption(name).
| bool balcl::CommandLine::theBool | ( | const bsl::string_view & | name | ) | const |
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).
| char balcl::CommandLine::theChar | ( | const bsl::string_view & | name | ) | const |
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).
| int balcl::CommandLine::theInt | ( | const bsl::string_view & | name | ) | const |
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).
| bsls::Types::Int64 balcl::CommandLine::theInt64 | ( | const bsl::string_view & | name | ) | const |
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).
| double balcl::CommandLine::theDouble | ( | const bsl::string_view & | name | ) | const |
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).
| const bsl::string& balcl::CommandLine::theString | ( | const bsl::string_view & | name | ) | const |
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).
| const bdlt::Datetime& balcl::CommandLine::theDatetime | ( | const bsl::string_view & | name | ) | const |
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).
| const bdlt::Date& balcl::CommandLine::theDate | ( | const bsl::string_view & | name | ) | const |
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).
| const bdlt::Time& balcl::CommandLine::theTime | ( | const bsl::string_view & | name | ) | const |
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).
| const bsl::vector<char>& balcl::CommandLine::theCharArray | ( | const bsl::string_view & | name | ) | const |
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).
| const bsl::vector<int>& balcl::CommandLine::theIntArray | ( | const bsl::string_view & | name | ) | const |
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).
| const bsl::vector<bsls::Types::Int64>& balcl::CommandLine::theInt64Array | ( | const bsl::string_view & | name | ) | const |
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).
| const bsl::vector<double>& balcl::CommandLine::theDoubleArray | ( | const bsl::string_view & | name | ) | const |
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).
| const bsl::vector<bsl::string>& balcl::CommandLine::theStringArray | ( | const bsl::string_view & | name | ) | const |
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).
| const bsl::vector<bdlt::Datetime>& balcl::CommandLine::theDatetimeArray | ( | const bsl::string_view & | name | ) | const |
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).
| const bsl::vector<bdlt::Date>& balcl::CommandLine::theDateArray | ( | const bsl::string_view & | name | ) | const |
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).
| const bsl::vector<bdlt::Time>& balcl::CommandLine::theTimeArray | ( | const bsl::string_view & | name | ) | const |
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).
| bslma::Allocator* balcl::CommandLine::allocator | ( | ) | const |
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.
| bsl::ostream& balcl::CommandLine::print | ( | bsl::ostream & | stream, | |
| int | level = 0, |
|||
| int | spacesPerLevel = 4 | |||
| ) | const |
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.
1.7.1