balcl::CommandLine Class Reference

#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 &errorStream, bslma::Allocator *basicAllocator=0)
template<int LENGTH>
	CommandLine (OptionInfo(&specTable)[LENGTH], bsl::ostream &errorStream, 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 &errorStream, bslma::Allocator *basicAllocator=0)
	CommandLine (const CommandLine &original, bslma::Allocator *basicAllocator=0)
	~CommandLine ()
	Destroy this command-line object.
CommandLine &	operator= (const CommandLine &rhs)
int	parse (int argc, const char *const argv[])
int	parse (int argc, const char *const argv[], bsl::ostream &errorStream)
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 (const bsl::string_view &programName) const
void	printUsage (bsl::ostream &errorStream) const
void	printUsage (bsl::ostream &errorStream, const bsl::string_view &programName) 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 &errorStream)
template<int LENGTH>
static bool	isValidOptionSpecificationTable (OptionInfo(&specTable)[LENGTH], bsl::ostream &errorStream)
static bool	isValidOptionSpecificationTable (const OptionInfo *specTable, int length)
static bool	isValidOptionSpecificationTable (const OptionInfo *specTable, int length, bsl::ostream &errorStream)

Detailed Description

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 balcl_commandline

Constructor & Destructor Documentation

CommandLine() [1/7]

template<int LENGTH>

balcl::CommandLine::CommandLine	(	const OptionInfo(&)	specTable[LENGTH],
		bsl::ostream &	errorStream,
		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 errorStream.

CommandLine() [2/7]

template<int LENGTH>

balcl::CommandLine::CommandLine	(	OptionInfo(&)	specTable[LENGTH],
		bsl::ostream &	errorStream,
		bslma::Allocator *	basicAllocator = 0
	)

CommandLine() [3/7]

template<int LENGTH>

balcl::CommandLine::CommandLine ( const 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.

CommandLine() [4/7]

template<int LENGTH>

balcl::CommandLine::CommandLine ( OptionInfo(&)  specTable[LENGTH], bslma::Allocator *  basicAllocator = 0  )

explicit

CommandLine() [5/7]

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.

CommandLine() [6/7]

balcl::CommandLine::CommandLine	(	const OptionInfo *	specTable,
		int	length,
		bsl::ostream &	errorStream,
		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 errorStream. Also note that specTable need not be statically initialized.

CommandLine() [7/7]

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

~CommandLine()

balcl::CommandLine::~CommandLine

(

)

Member Function Documentation

allocator()

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.

BSLMF_NESTED_TRAIT_DECLARATION() [1/2]

balcl::CommandLine::BSLMF_NESTED_TRAIT_DECLARATION	(	CommandLine	,
		bdlb::HasPrintMethod
	)

BSLMF_NESTED_TRAIT_DECLARATION() [2/2]

balcl::CommandLine::BSLMF_NESTED_TRAIT_DECLARATION	(	CommandLine	,
		bslma::UsesBslmaAllocator
	)

hasOption()

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.

hasValue()

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

isParsed()

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.

isSpecified() [1/2]

bool balcl::CommandLine::isSpecified

(

const bsl::string_view &

name

)

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.

isSpecified() [2/2]

bool balcl::CommandLine::isSpecified	(	const bsl::string_view &	name,
		int *	count
	)		const

isValid()

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.

isValidOptionSpecificationTable() [1/6]

bool balcl::CommandLine::isValidOptionSpecificationTable ( const OptionInfo *  specTable, int  length  )

inlinestatic

isValidOptionSpecificationTable() [2/6]

static bool balcl::CommandLine::isValidOptionSpecificationTable ( const OptionInfo *  specTable, int  length, bsl::ostream &  errorStream  )

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 errorStream to which error messages are written. If no errorStream 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.

isValidOptionSpecificationTable() [3/6]

template<int LENGTH>

bool balcl::CommandLine::isValidOptionSpecificationTable ( const OptionInfo(&)  specTable[LENGTH] )

inlinestatic

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 errorStream to which error messages are written. If no errorStream is specified, this method produces no output. See {Valid balcl::OptionInfo Specifications} for a description of the validity requirements.

isValidOptionSpecificationTable() [4/6]

template<int LENGTH>

bool balcl::CommandLine::isValidOptionSpecificationTable ( const OptionInfo(&)  specTable[LENGTH], bsl::ostream &  errorStream  )

inlinestatic

isValidOptionSpecificationTable() [5/6]

template<int LENGTH>

bool balcl::CommandLine::isValidOptionSpecificationTable ( OptionInfo(&)  specTable[LENGTH] )

inlinestatic

isValidOptionSpecificationTable() [6/6]

template<int LENGTH>

bool balcl::CommandLine::isValidOptionSpecificationTable ( OptionInfo(&)  specTable[LENGTH], bsl::ostream &  errorStream  )

inlinestatic

numSpecified()

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.

operator=()

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

options()

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.

parse() [1/2]

int balcl::CommandLine::parse	(	int	argc,
		const char *const	argv[]
	)

parse() [2/2]

int balcl::CommandLine::parse	(	int	argc,
		const char *const	argv[],
		bsl::ostream &	errorStream
	)

Parse the command-line arguments contained in the array starting at the specified argv having the specified argc length. Optionally specify an errorStream to which an appropriate error message is written if parsing fails. If errorStream is not specified, bsl::cerr is used. Return 0 on success, and a non-zero value otherwise. If an argument is not specified on the command-line, then if the Option object configuration for this CommandLine defines an environment variable name and the runtime environment for this application has set that environment variable, then set the option to the value of the environment variable. Otherwise, if an option is not set by the command line, or the environment, set the option using the default value if one has been provided. If the option has not been set by the command line, environment, or by default, hasValue for the option will return false. After a successful call isParsed() and isValid() will both be true, and the information provided by argv can be viewed via the accessors. After an unsuccessful call isParsed() and isValid() will both be false. The behavior is undefined unless isValid() is true and isParsed() is false (i.e. the CommandLine was constructed in a valid state, and parse has not previously been called).

position()

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 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()

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.

print()

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.

printUsage() [1/4]

void balcl::CommandLine::printUsage

(

)

const

Print usage to the specified output errorStream, describing what the command line should look like. If errorStream is not specified, print usage to stderr. Optionally specify programName to use as the name of the program in the printed usage. If programName is not specified and if parse has been previously called successfully, use the first element of the argv argument; otherwise, use a default name. This method can be invoked at any time, even before parse has been invoked on this object.

printUsage() [2/4]

void balcl::CommandLine::printUsage

(

bsl::ostream &

errorStream

)

const

printUsage() [3/4]

void balcl::CommandLine::printUsage	(	bsl::ostream &	errorStream,
		const bsl::string_view &	programName
	)		const

printUsage() [4/4]

void balcl::CommandLine::printUsage

(

const bsl::string_view &

programName

)

const

specifiedOptions()

CommandLineOptionsHandle balcl::CommandLine::specifiedOptions

(

)

const

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()

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

theChar()

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

theCharArray()

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

theDate()

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

theDateArray()

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

theDatetime()

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

theDatetimeArray()

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

theDouble()

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

theDoubleArray()

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

theInt()

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

theInt64()

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

theInt64Array()

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

theIntArray()

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

theString()

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

theStringArray()

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

theTime()

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

theTimeArray()

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

type()

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

---

The documentation for this class was generated from the following file:

• balcl_commandline.h