[#BloombergLP-balcl-CommandLine]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/balcl.adoc[balcl]::CommandLine
:relfileprefix: ../../
:mrdocs:

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>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class CommandLine;
----

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balcl/CommandLine/2constructor-03.adoc[`CommandLine`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/balcl/CommandLine/2destructor.adoc[`~CommandLine`] [.small]#[destructor]#
| Destroy this command‐line object.
| xref:BloombergLP/balcl/CommandLine/operator_assign.adoc[`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`).
| xref:BloombergLP/balcl/CommandLine/allocator.adoc[`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.
| xref:BloombergLP/balcl/CommandLine/hasOption.adoc[`hasOption`] 
| Return `true` if this command‐line object is configured with an option having the specified `name`, and `false` otherwise.
| xref:BloombergLP/balcl/CommandLine/hasValue.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/isParsed.adoc[`isParsed`] 
| Return `true` if this object was parsed successfully, and `false` otherwise. Note that if `parse` was invoked but failed, this method returns `false`.
| xref:BloombergLP/balcl/CommandLine/isSpecified-02.adoc[`isSpecified`] 
| `isSpecified` overloads
| xref:BloombergLP/balcl/CommandLine/isValid.adoc[`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.
| xref:BloombergLP/balcl/CommandLine/numSpecified.adoc[`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.
| xref:BloombergLP/balcl/CommandLine/options.adoc[`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`.
| xref:BloombergLP/balcl/CommandLine/parse-05.adoc[`parse`] 
| `parse` overloads
| xref:BloombergLP/balcl/CommandLine/position.adoc[`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.
| xref:BloombergLP/balcl/CommandLine/positions.adoc[`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.
| xref:BloombergLP/balcl/CommandLine/print.adoc[`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.
| xref:BloombergLP/balcl/CommandLine/printUsage-0b.adoc[`printUsage`] 
| `printUsage` overloads
| xref:BloombergLP/balcl/CommandLine/specifiedOptions.adoc[`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`.
| xref:BloombergLP/balcl/CommandLine/theBool.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theChar.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theCharArray.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theDate.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theDateArray.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theDatetime.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theDatetimeArray.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theDouble.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theDoubleArray.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theInt.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theInt64.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theInt64Array.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theIntArray.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theString.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theStringArray.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theTime.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/theTimeArray.adoc[`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)`.
| xref:BloombergLP/balcl/CommandLine/type.adoc[`type`] 
| Return the type of the option having the specified `name`. The behavior is undefined unless this command‐line object `hasOption(name)`.
| xref:BloombergLP/balcl/CommandLine/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<CommandLine, HasPrintMethod>`] 
| Nested trait declaration for `bslma::UsesBslmaAllocator`.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balcl/CommandLine/isValidOptionSpecificationTable-09.adoc[`isValidOptionSpecificationTable`] 
| `isValidOptionSpecificationTable` overloads
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balcl/operator_not_eq-05.adoc[`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.
| xref:BloombergLP/balcl/operator_eq-01.adoc[`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.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#