Class CCommandLine#

Defined in File cmdlnparser.h

Class Documentation#

class CCommandLine#

The class provides a generic implementation of command line argument parsing. Instantiate this class and define which arguments are supported. The parsing is done by calling the Parse function. Parse errors are reported with std::exception.

This class allows the generic implementation of a command line parser by defining the arguments and the variables connected to the arguments. The parsing of the command line is done by calling the function CCommandLine::Parse, which automatically fills the corresponding variables when an argument is supplied on the command line.

The following command line argument types are supported:

+——————–

—+——————+————————————————————–—+—————-—+ | Variable | Description | Source code example | Argument Example | +=======================+==================+=================================================================+===================+ | bool | Boolean variable | bool bHelp = false; | -help | | | | commandline.DefineOption(“help”, bHelp, “Show help.”); | | +——————–—+——————+————————————————————–—+—————-—+ | int8_t | Integer variable | int iTest = 0; | -test_int=10 | | uint8_t | | commandline.DefineOption(“test_int”, iTest, “Example.”); | | | int16_t | | double dTest = 0.0; | | | uint16_t | | commandline.DefineOption(“test_d”, dTest, “Example.”); | -test_d=1.1 | | int32_t | | | | | uint32_t | | | | | int64_t | | | | | uint64_t | | | | | float | | | | | double | | | | +——————–—+——————+————————————————————–—+—————-—+ | std::vector | Vector container | std::vector<int> vec; sdv::sequence<int> seq; | -vec_int=10,20 | | std::list | List container | commandline.DefineOption(“vec_int”, vec, “Example”); | | | sdv::sequence | Sequence | commandline.DefineOption(“vec_int”, seq, “Example”); | | +——————–—+——————+————————————————————–—+—————-—+ | bool | Flag variable | bool bExample = false; | -flag+ | | | | commandline.DefineFlagOption(“flag”, bExample, “Example.”); | -flag- | +——————–—+——————+————————————————————–—+—————-—+ | enum | Enum variable | enum ETest { test1, test2, test3 }; | -e_tst=tst2 | | | | SEnumArgumentAssoc<ETest> rgsAssociations[] = | | | | | { { test1, “tst1”, “Test the #1” }, | | | | | { test2, “tst2”, “Test the #2” }, | | | | | { test3, “tst3”, “Test the #3” } }; | | | | | ETest eTest = test3; | | | | | CArgumentDefT<ETest>& rEnumTest = | | | | | commandline.DefineOption(“e_tst”, eTest, “Test.”); | | | | | rEnumTest.AddAssociations(rgsAssociations); | | +——————–—+——————+————————————————————–—+—————-—+ | std::vector | Enum vector | enum ETest { test1, test2, test3 }; | -e_tst=tst2,tst3 | | std::list | Enum list | SEnumArgumentAssoc<ETest> rgsAssociations[] = | | | sdv::sequence | Enum sequence | { { test1, “tst1”, “Test the #1” }, | | | | | { test2, “tst2”, “Test the #2” }, | | | | | { test3, “tst3”, “Test the #3” } }; | | | | | std::vector<ETest> vecEnumArg; | | | | | CArgumentDefT<std::vector<ETest>>& rEnumTest = | | | | | commandline.DefineOption(“e_tst”, vecEnumArg, “Test.”); | | | | | rEnumTest.AddAssociations(rgsAssociations); | | +——————–—+——————+————————————————————–—+—————-—+ | std::string | String variable | std::string ssTest; | -str=abc | | | | commandline.DefineOption(“str”, ssTest, “Example.”); | -str=”abc def” | +——————–—+——————+————————————————————–—+—————-—+ | std::vector | String vector | std::list<std::string> lst; sdv::sequence<sdv::u8string> seq | -str=abc,”def” | | std::list | String list | commandline.DefineOption(“lst_str”, lst, “Example.”); | | | sdv::sequence | String sequence | commandline.DefineOption(“lst_str”, seq, “Example.”); | | +——————–—+——————+————————————————————–—+—————-—

| | | commandline.DefineOption(“path”, pathTest, “Example.”); | |

+——————–—+——————+————————————————————–—+—————-—+

+——————–—+——————+————————————————————–—+—————-—+

| | | commandline.DefineDefaultArgument(vec, “text chunks”); | | +——————–

—+——————+————————————————————–—+—————-—+

The command line class holds a list of argument definitions. Dependable on the provided arguments, the argument definitions receive the parsed values from the command line. Since so many different types of arguments are possible, the implementation uses a construct of class derivation implementing portions of the arguments (e.g. value assignment, containers, flags, etc.).

Implementing a new argument type, it is necessary to provide a definition and a value class for the type.

Public Types

enum class EParseFlags : uint32_t#

Parsing flags.

Values:

enumerator assignment_character#: Default argument assignment: -option=ARG and —suboption=ARG.

enumerator no_assignment_character#: When set, assignment arguments do not use the assignment character. This allows values to be glueed directly to the (sub-)option as it is used by many programs. -optionARG and —suboptionARG

enumerator assignment_next_arg#: When set, assignment arguments provide the arguments as separate arguments: -option ARG —suboption ARG. This is also a common way to provide options. NOTE: although this is a very common way to provide options, arrays cannot be provided. If multiple values need to be provided, each value has to be repeated using the option tag.

Public Functions

CCommandLine(uint32_t uiFlags = static_cast<uint32_t>(EParseFlags::assignment_character))#

Constructor.

Parameters:: uiFlags – [in] Zero or more flags of EParseFlags (default using assignment character).

~CCommandLine()#: Destructor.

std::filesystem::path GetApplicationPath() const#

Return the application path.

Returns:: Returns the application path.

inline uint32_t GetParseFlags() const#

Get the parse flags that were supplied to the parse function.

Returns:: The parse flags of zero or more flags of EParseFlags.

inline bool CheckParseFlag(EParseFlags eParseFlag) const#

Check whether the parse flag has been set.

Parameters:: eParseFlag – [in] The parse flag to check for.
Returns:: Returns whether the flag has been set, or not.

template<typename TCharType>
inline void Parse(size_t nArgs, const TCharType **rgszArgs)#

Parse the command line, to be called after the command line class has been filled with argument definitions. This function will trow exceptions using the std::exception mechanism. tparam Character type.

Parameters:

nArgs – [in] The amount of arguments.
rgszArgs – [in] Array of arguments.

void DefineGroup(const std::string &rssTitle, const std::string &rssDescription = std::string{})#

Define a group that cover the options following.

Parameters:

rssTitle – [in] Zero terminated string containing the title of the group.
rssDescription – [in] The description of the group. This parameter is optional. If not supplied, can be NULL.

template<typename TVar> inline CArgumentDefT<TVar> &DefineDefaultArgument(TVar &rtVar, const std::string &rssHelpText)#

Argument definition for a default argument, which is an argument without option (-/) character.

Template Parameters:

TVar – Variable type of the argument to define.

Parameters:

rtVar – [inout] Reference to the argument that receives the content of the command line after parsing.
rssHelpText – [in] Pointer to the zero terminated text to present when printing help information about the argument.

Returns:

CArgumentDefT<TVar>& Reference to the argument command class, which can be used to set additional attributes.

template<typename TVar, typename ...TArgumentGroup> inline CArgumentDefT<TVar> &DefineOption(const std::string &rssArgument, TVar &rtVar, const std::string &rssHelpText, bool bCaseSensitive = true, size_t nArgumentGroup = 0, TArgumentGroup... nAdditionalGroups)#

Option definition, which is an argument with option (-/) character.

Template Parameters:

TVar – Variable type of the argument to define.
TArgumentGroup – Types of additional argument groups for showing argument specific help.

Parameters:

rssArgument – [in] Pointer to the zero terminated string with the argument name.
rtVar – [inout] Reference to the argument that receives the content of the command line after parsing.
rssHelpText – [in] Pointer to the zero terminated text to present when printing help information about the argument.
bCaseSensitive – [in] Boolean telling whether the argument should be compared case sensitive or case insensitive.
nArgumentGroup – [in] During the generation of the help test, to optionally show the options based on the arguments supplied, argument groups can be used. The options are assigned to one or more argument groups and during the PrintHelp function, the group to show will be supplied. The default group is group #0.
nAdditionalGroups – [in] Zero or more additional group scan be supplied.

Returns:

CArgumentDefT<TVar>& Reference to the argument command class, which can be used to set additional attributes.

template<typename TVar, typename ...TArgumentGroup> inline CArgumentDefT<TVar> &DefineSubOption(const std::string &rssArgument, TVar &rtVar, const std::string &rssHelpText, bool bCaseSensitive = true, size_t nArgumentGroup = 0, TArgumentGroup... nAdditionalGroups)#

Sub-option definition, which is an argument with sub-option (—) characters.

Template Parameters:

TVar – Variable type of the argument to define.
TArgumentGroup – Types of additional argument groups for showing argument specific help.

Parameters:

rssArgument – [in] Pointer to the zero terminated string with the argument name.
rtVar – [inout] Reference to the argument that receives the content of the command line after parsing.
rssHelpText – [in] Pointer to the zero terminated text to present when printing help information about the argument.
bCaseSensitive – [in] Boolean telling whether the argument should be compared case sensitive or case insensitive.
nArgumentGroup – [in] During the generation of the help test, to optionally show the options based on the arguments supplied, argument groups can be used. The options are assigned to one or more argument groups and during the PrintHelp function, the group to show will be supplied. The default group is group #0.
nAdditionalGroups – [in] Zero or more additional group scan be supplied.

Returns:

CArgumentDefT<TVar>& Reference to the argument command class, which can be used to set additional attributes.

template<typename ...TArgumentGroup> inline CArgumentDefT<bool> &DefineFlagOption(const std::string &rssArgument, bool &rbFlag, const std::string &rssHelpText, bool bCaseSensitive = true, size_t nArgumentGroup = 0, TArgumentGroup... nAdditionalGroups)#

Flag option definition, which is an argument with option (-/) character.

Template Parameters:

TArgumentGroup – Types of additional argument groups for showing argument specific help.

Parameters:

rssArgument – [in] Pointer to the zero terminated string with the argument name.
rbFlag – [inout] Reference to the argument that receives the content of the command line after parsing.
rssHelpText – [in] Pointer to the zero terminated text to present when printing help information about the argument.
bCaseSensitive – [in] Boolean telling whether the argument should be compared case sensitive or case insensitive.
nArgumentGroup – [in] During the generation of the help test, to optionally show the options based on the arguments supplied, argument groups can be used. The options are assigned to one or more argument groups and during the PrintHelp function, the group to show will be supplied. The default group is group #0.
nAdditionalGroups – [in] Zero or more additional group scan be supplied.

Returns:

CArgumentDefT<TVar>& Reference to the argument command class, which can be used to set additional attributes.

template<typename ...TArgumentGroup> inline CArgumentDefT<bool> &DefineFlagSubOption(const std::string &rssArgument, bool &rbFlag, const std::string &rssHelpText, bool bCaseSensitive = true, size_t nArgumentGroup = 0, TArgumentGroup... nAdditionalGroups)#

Flag sub-option definition, which is an argument with option (-/) character.

Template Parameters:

TArgumentGroup – Types of additional argument groups for showing argument specific help.

Parameters:

rssArgument – [in] Pointer to the zero terminated string with the argument name.
rbFlag – [inout] Reference to the argument that receives the content of the command line after parsing.
rssHelpText – [in] Pointer to the zero terminated text to present when printing help information about the argument.
bCaseSensitive – [in] Boolean telling whether the argument should be compared case sensitive or case insensitive.
nArgumentGroup – [in] During the generation of the help test, to optionally show the options based on the arguments supplied, argument groups can be used. The options are assigned to one or more argument groups and during the PrintHelp function, the group to show will be supplied. The default group is group #0.
nAdditionalGroups – [in] Zero or more additional group scan be supplied.

Returns:

CArgumentDefT<TVar>& Reference to the argument command class, which can be used to set additional attributes.

void PrintFixedWidth(size_t nWidth)#

Set or remove a fixed with printing of the help text.

Parameters:: nWidth – [in] The width of the printable area. Can be 0, then the width should be dynamically taken from the console width the application is running in.

size_t PrintFixedWidth() const#

Get the current fixed width for printing help. If no fixed width has been selected, returns 0.

Returns:: Returns the fixed width selected to print help or 0 for dynamic width.

void PrintMaxWidth(size_t nWidth)#

Set the maximum width of printing the help text when the console width is larger. This will automatically select dynamic width.

Parameters:: nWidth – [in] The maximum width of the printing text if the console is larger.

size_t PrintMaxWidth() const#

Get the maximum width of printing the help text. Could be 0 when there is no limit.

Returns:: Returns the maximum width of the printing the help text.

void PrintSyntax(bool bEnable)#

Enable or disable syntax explanation during printing of the help text.

Parameters:: bEnable – [in] When set, enables the syntax printing; otherwise disables syntax printing.

bool PrintSyntax() const#

Get the current syntax printing state.

Returns:: The syntax printing state; either enabled, or disabled.

void PrintHelp(std::ostream &rstream, const std::string &rssHelpText = std::string{}, size_t nArgumentGroup = 0) const#

Print help information based on the configured arguments.

Template Parameters:

TGroup – Zero or more help groups to show. If none are supplied, the default group #0 is shown.

Parameters:

rstream – [in] The stream to be used to print the help.
rssHelpText – [in] A description of the application formatted to fit the console width.
nArgumentGroup – [in] During the generation of the help test, to optionally show the options based on the arguments supplied, argument groups can be used. The options are assigned to one or more argument groups and during the PrintHelp function, the group to show will be supplied. The default group is group #0.

void DumpArguments(std::ostream &rstream, bool bAll = true) const#

Dump command line arguments.

Parameters:

rstream – [inout] Reference to the stream to dump the arguments to.
bAll – [in] When set, dump all arguments; otherwise only the ones that we provided over the command line.

std::vector<std::string> IncompatibleArguments(size_t nArgumentGroup, bool bFull = true) const#

Get a list of incompatible supplied arguments base don the supplied argument group.

Options can be assigned one or more groups. This can be useful to selective enable/disable options based on the state on the command line (e.g. based on a command provided on the command line). Not all options are compatible to the currently active group and the compatibility can be checked using this function. Provided options belonging to group 0 are always compatible. For all other provided options, the compatibility is checked with the provided argument group number.

Parameters:

nArgumentGroup – [in] Argument group that currently defines the compatibility.
bFull – [in] When set, returns the complete supplied argument text. If not, returns the option label only.

Returns:

List of incompatible provided arguments.

Public Static Functions

static void PrintHelpText(std::ostream &rstream, const std::string &rssHelpText, size_t nPrintWidth = 0)#

Print help text information (not printing the arguments).

Parameters:

rstream – [in] The stream to be used to print the help.
rssHelpText – [in] A description of the application formatted to fit the console width.
nPrintWidth – [in] The width of the printable area. Can be 0, then the width is taken from the console width the application is running in.

Class CCommandLine#

Class Documentation#

Contents

Contents