Description:

This class provides a foundation for software executables that processes command-line parameters.

See also: "Utility" methods which could have been implemented as an interface of this class have instead been located as static methods in friend class CLIUtil which receive a pointer to an instance of this type.

Friends

Exceptions

cli::Exceptions

Definition at line 27 of file commandline.inl.

Public Field Index:
String	AppInfo
StdVectorMA< integer >	ArgsLeft
StdVectorMA< String >	ArgStrings
ListMA< CommandDecl * >	CommandDecls
	Commands defined.
ListMA< Command * >	CommandsParsed
	A list of commands actually parsed. Filled with method ReadNextCommands.
DryRunModes	DryRun =DryRunModes::Off
HashMap< MonoAllocator, Enum, ExitCodeDecl * >	ExitCodeDecls
	Possible Errors.
integer	MaxNameLength [3] ={ 0, 0, 0 }
ListMA< Command * >::iterator	NextCommandIt
	The next command in CommandsParsed to be processed. Used with method NextCommand.
ListMA< String, Recycling::Shared >	OptionArgsIgnored
ListMA< OptionDecl * >	OptionDecls
	Possible Options.
ListMA< Option * >	Options
	The options parsed in the order of their appearance.
ListMA< ParameterDecl * >	ParameterDecls
	Possible Parameters.
NCString	ResourceCategory
	The resource category to fetch CLI resources within field Resources.
resources::ResourcePool *	Resources =nullptr

Public Method Index:
	CommandLine ()
	Constructor.
virtual	~CommandLine ()
	Virtual empty destructor.
virtual int	ArgCount ()
template<typename TEnum>
void	DefineCommands ()
template<typename TEnum>
void	DefineExitCodes ()
template<typename TEnum>
void	DefineOptions ()
template<typename TEnum>
void	DefineParameters ()
MonoAllocator &	GetAllocator () noexcept
virtual String	GetArg (integer idx)
Option *	GetOption (Enum element)
const String &	GetResource (const NString &name)
void	Init (camp::Camp *resModule)
virtual void	Init (resources::ResourcePool *resourcePool, NCString resCategory)
virtual Command *	NextCommand ()
virtual String	PeekArg ()
virtual String	PopArg ()
virtual void	ReadNextCommands ()
virtual void	ReadOptions ()
void	RemoveArg (integer argNo)
const String &	TryResource (const NString &name)
void	UndefineCommand (Enum command)
void	UndefineExitCode (Enum exitCode)
void	UndefineOption (Enum option)
void	UndefineParameter (Enum parameter)

Protected Field Index:
MonoAllocator	allocator
ListMA< Parameter *, Recycling::Shared >::SharedRecyclerType	paramListRecycler
ListMA< String, Recycling::Shared >::SharedRecyclerType	stringListRecycler
	The element recycler shared between lists of strings.

Field Details:

◆ allocator

MonoAllocator alib::cli::CommandLine::allocator

protected

Monotonic allocator used for all resourced static definitions as well as the data used during parsing.

Definition at line 51 of file commandline.inl.

◆ AppInfo

String alib::cli::CommandLine::AppInfo

Application information text. Used as a sort of "header" output by class CLIUtil .

Definition at line 66 of file commandline.inl.

◆ ArgsLeft

StdVectorMA<integer> alib::cli::CommandLine::ArgsLeft

A vector of args. If constructor variant accepting wchar strings is used, those unicode strings get converted to 1-byte strings using the current locale.
Values that are 'consumed' by options that get defined, are removed.

Definition at line 79 of file commandline.inl.

◆ ArgStrings

StdVectorMA<String> alib::cli::CommandLine::ArgStrings

A vector of args. If the type of CLI argument strings provided with the constructor does not match the default ALib string width, the strings get converted.
Values that are 'consumed' by options that get defined, are not removed from this list. Instead, they are removed from index vector ArgsLeft.

Definition at line 74 of file commandline.inl.

◆ CommandDecls

ListMA<CommandDecl*> alib::cli::CommandLine::CommandDecls

Commands defined.

Definition at line 83 of file commandline.inl.

◆ CommandsParsed

ListMA<Command*> alib::cli::CommandLine::CommandsParsed

A list of commands actually parsed. Filled with method ReadNextCommands.

Definition at line 106 of file commandline.inl.

◆ DryRun

DryRunModes alib::cli::CommandLine::DryRun =DryRunModes::Off

Specifies if a "dry run" should be performed. For more information, see static bool GetDryOpt(CommandLine&, Option&) .

Definition at line 131 of file commandline.inl.

◆ ExitCodeDecls

HashMap<MonoAllocator, Enum, ExitCodeDecl*> alib::cli::CommandLine::ExitCodeDecls

Possible Errors.

Definition at line 92 of file commandline.inl.

◆ MaxNameLength

integer alib::cli::CommandLine::MaxNameLength[3] ={ 0, 0, 0 }

The maximum length of token names:

0: Commands
1: Options

Note: Used for formatted help/dump output. (0= command, 1= option, 2= param)

Definition at line 116 of file commandline.inl.

◆ NextCommandIt

ListMA<Command*>::iterator alib::cli::CommandLine::NextCommandIt

The next command in CommandsParsed to be processed. Used with method NextCommand.

Definition at line 109 of file commandline.inl.

◆ OptionArgsIgnored

ListMA<String, Recycling::Shared> alib::cli::CommandLine::OptionArgsIgnored

List of arguments that start with a hyphen and are ignored by this class due to the fact that they were not recognized.

See also: Method ReadOptions for details on this.

Definition at line 103 of file commandline.inl.

◆ OptionDecls

ListMA<OptionDecl*> alib::cli::CommandLine::OptionDecls

Possible Options.

Definition at line 86 of file commandline.inl.

◆ Options

ListMA<Option*> alib::cli::CommandLine::Options

The options parsed in the order of their appearance.

Definition at line 97 of file commandline.inl.

◆ ParameterDecls

ListMA<ParameterDecl*> alib::cli::CommandLine::ParameterDecls

Possible Parameters.

Definition at line 89 of file commandline.inl.

◆ paramListRecycler

ListMA<Parameter*,Recycling::Shared>::SharedRecyclerType alib::cli::CommandLine::paramListRecycler

protected

The element recycler shared between fields ListMA< Parameter *, Recycling::Shared > ParametersMandatory and ListMA< Parameter *, Recycling::Shared > ParametersOptional.

Definition at line 58 of file commandline.inl.

◆ ResourceCategory

NCString alib::cli::CommandLine::ResourceCategory

The resource category to fetch CLI resources within field Resources.

Definition at line 127 of file commandline.inl.

◆ Resources

resources::ResourcePool* alib::cli::CommandLine::Resources =nullptr

The resource pool used to fetch resources from. Several resources are loaded from this in addition to what is loaded as enum meta-information of the cli declaration objects.

It is recommended to have the main application implement a custom module, as described here.

Definition at line 124 of file commandline.inl.

◆ stringListRecycler

ListMA<String,Recycling::Shared>::SharedRecyclerType alib::cli::CommandLine::stringListRecycler

protected

The element recycler shared between lists of strings.

Definition at line 54 of file commandline.inl.

Constructor(s) / Destructor Details:

◆ CommandLine()

alib::cli::CommandLine::CommandLine ( )

inline

Constructor.

Definition at line 138 of file commandline.inl.

◆ ~CommandLine()

virtual alib::cli::CommandLine::~CommandLine ( )

inlinevirtual

Virtual empty destructor.

Definition at line 155 of file commandline.inl.

Method Details:

◆ ArgCount()

virtual int alib::cli::CommandLine::ArgCount ( )

inlinevirtual

Retrieves the number of arguments.

Returns: The number of arguments given.

Definition at line 452 of file commandline.inl.

◆ DefineCommands()

template<typename TEnum>

void alib::cli::CommandLine::DefineCommands ( )

inline

Defines commands given with enumeration TEnum. ALib Enum Records of type ERCommandDecl need to be associated to the given enumeration type TEnum.

Template Parameters

TEnum The enum type.

Definition at line 255 of file commandline.inl.

◆ DefineExitCodes()

template<typename TEnum>

void alib::cli::CommandLine::DefineExitCodes ( )

inline

Defines exit-codes given with enumeration TEnum. ALib Enum Records of type ERExitCodeDecl need to be associated to the given enumeration type TEnum.

Template Parameters

TEnum The enum type.

Definition at line 316 of file commandline.inl.

◆ DefineOptions()

template<typename TEnum>

void alib::cli::CommandLine::DefineOptions ( )

inline

Defines options given with enumeration TEnum. ALib Enum Records of type EROptionDecl need to be associated to the given enumeration type TEnum.

Template Parameters

TEnum The enum type.

Definition at line 286 of file commandline.inl.

◆ DefineParameters()

template<typename TEnum>

void alib::cli::CommandLine::DefineParameters ( )

inline

Defines parameters given with enumeration TEnum. ALib Enum Records of type ERParameterDecl need to be associated to the given enumeration type TEnum.

Template Parameters

TEnum The enum type.

Definition at line 225 of file commandline.inl.

◆ GetAllocator()

MonoAllocator & alib::cli::CommandLine::GetAllocator ( )

inlinenoexcept

Returns the allocator used for all command parsing, resourced enum record creation and so on. This allocator might be used for allocations that align with (or are shorter as) the lifecycle of the instance of this class.

Returns: The internal allocator

Definition at line 166 of file commandline.inl.

◆ GetArg()

virtual String alib::cli::CommandLine::GetArg ( integer idx )

inlinevirtual

Retrieves the argument at the given position.
In debug-builds, this method asserts the index is in the available range.

Parameters

idx	The requested argument's index.

Returns: The element idx of vector ArgStrings.

Definition at line 459 of file commandline.inl.

◆ GetOption()

Option * alib::cli::CommandLine::GetOption ( Enum element )

Searches and returns the last occurrence of the specified option.

This method is to be used with options that overwrite previous values in case that it was given multiple times as a CLI argument. Instead, options that may occur multiple times without overriding a previous occurrence, are to be processed "manually" by examining field Options.

Parameters

element The option's declaration enum element.

Returns: A pointer to the parsed option, respectively nullptr if not given.

Definition at line 145 of file commandline.cpp.

◆ GetResource()

const String & alib::cli::CommandLine::GetResource ( const NString & name )

inline

Helper function that uses fields Resources and ResourceCategory to fetch a resourced string.

With debug-builds, this method asserts that a resource was found. If this is not wanted, use TryResource.

Parameters

name	The resource name.

Returns: The resource string, respectively a nulled string on failure.

Definition at line 176 of file commandline.inl.

◆ Init() [1/2]

void alib::cli::CommandLine::Init ( camp::Camp * resModule )

inline

Simple helper method that invokes Init(resources::ResourcePool*, NCString ) providing the resource pool and categery of the given resModule.

Parameters

resModule The module used to load resource strings.

Definition at line 196 of file commandline.inl.

◆ Init() [2/2]

void alib::cli::CommandLine::Init	(	resources::ResourcePool *	resourcePool,
		NCString	resCategory )

virtual

Initializes this class. This function has to be invoked after construction and after ALib was bootstrapped.

This method accesses global ALib variables ARG_C, ARG_VN, and ARG_VW, and thus those have to be set by the user's main()-function properly.

A resource pool has to be provided along with a corresponding resource category to use. While it is not necessary to do, it is recommended to create a custom ALib module, which holds such resource pool. For this case, overloaded helper method Init(camp::Camp*) is provided which calls this method by forwarding the pool and category name from that module.

Parameters

resourcePool	The resource pool used to load resource strings.
resCategory	The resource category used to load resource strings.

Definition at line 35 of file commandline.cpp.

◆ NextCommand()

Command * alib::cli::CommandLine::NextCommand ( )

virtual

Returns the next item in vector NextCommand. If needed, ReadNextCommands is invoked.

Returns: The next command parsed from CLI argument list. nullptr, if no more commands are found.

Definition at line 180 of file commandline.cpp.

◆ PeekArg()

virtual String alib::cli::CommandLine::PeekArg ( )

inlinevirtual

Retrieves the next argument from the list without removing it.

See also: Method PopArg, RemoveArg and ReadNextCommands.

Returns: The first argument of (respectively remaining in) the list. If no argument is available, a nulled string is returned.

Definition at line 472 of file commandline.inl.

◆ PopArg()

String alib::cli::CommandLine::PopArg ( )

virtual

Retrieves the next argument and removes it from list ArgsLeft.

See also: Method PeekArg, RemoveArg and ReadNextCommands.

Returns: The first argument of vector ArgsLeft. If no argument is available, a nulled string is returned.

Definition at line 202 of file commandline.cpp.

◆ ReadNextCommands()

void alib::cli::CommandLine::ReadNextCommands ( )

virtual

Parses as many commands as possible and stores them in CommandsParsed. Prior to invoking this method, all CLI declarations have to be made. Furthermore, usually method ReadOptions has to be invoked before this method.

The name of the method indicates that one or more, but maybe not all commands are read. The reason for this behavior lies in the fact that commands may be defined that do their own, specifically coded parsing. As a matter of the fact that the flags and options of structs CommandDecl and ParameterDecl are kept rather simple to match the most usual cases, the parsing of arguments of a command often has to be left to be done by custom code. Mostly just when processing (executing) a command. In contrast to the need of parsing (and processing) all CLI options, given before processing commands, this is not a problem. The usual inner part of a command processing loop then looks like this:

Check if CommandsParsed is empty
Invoke this method (ReadNextCommands )
If still no command is found, break loop
Remove and process first command in CommandsParsed.

A similar parsing approach is supported with method NextCommand. The only difference is that the parsed commands stay in CommandsParsed and instead field NextCommandIt indicates the position of the next command to read. This way, commands may refer to previous ones, if this is needed.

As a final note it should be mentioned, that implementing a "dry run" option on the level of command parsing, for the reasons explained above, might need some specific custom code to be able to parse all commands (without processing them). If such functionality is wanted, it is best to separate custom command parsing from command execution (the opposite was recommended above). Only the last command in the list has to be 'manually' processed, as the previous ones obviously got parsed well. With this approach, all commands can be parsed without executing them. Static utility method static AString & DumpParseResults(CommandLine&, Paragraphs&) is a predefined way to then write information about all options and commands parsed.
A lower level "dry run", that receives information about the concrete actions that the processing of commands would perform, is of course a different, application specific task.

Definition at line 153 of file commandline.cpp.

◆ ReadOptions()

void alib::cli::CommandLine::ReadOptions ( )

virtual

Finalizes Initialization and has to be called after all invocations of:

DefineCommands,
DefineOptions,
DefineParameters and
DefineExitCodes,

have been performed. All options recognized get collected in list Options The arguments of the options get removed from ArgsLeft.

In case of options that have own parameter arguments, such arguments may not be fully removed. This depends on whether it is possible with the simple flags and values provided in OptionDecl to enable class Option to fully detect them. Therefore, after this method is invoked, for options with more complex syntax, custom code may be needed to pull the "remainders" of option arguments from ArgsLeft. For this, the inherited field integer Position is quite useful, as well as the method RemoveArg.

It has to be ensured that before the next step, which is the invocation of ReadNextCommands, all option-related CLI arguments are cleaned away!

For this reason, this method removes all arguments that start with a hyphen '-' from the ArgsLeft, even if they got not recognized. Those CLI arguments get collected in OptionArgsIgnored. Finding unrecognized options is not considered an error, because other libraries used with the software might read CLI options autonomously.

Note

A good sample for this is class CLIVariablesPlugin used with ALib configuration variables. After this method has been invoked, vector OptionArgsIgnored may/should be passed to the plug-in CLIVariablesPlugin of (all) Configuration object(s) used with the application. For this, an invocation, similar to this may be used with all ALib Modules that use an own configuration object:

  XYZModule.GetConfig()->GetPluginTypeSafe<alib::variables::CLIVariablesPlugin>()->SetArgs( &OptionArgsIgnored );

In the case that other libraries have more complex option syntax, e.g., options consisting of multiple arguments or such that do not even start with a hyphen character, then, this method should be called only after a custom code removes such 3rd party options in a reliable way!

If all this was not done, the "remainder" of custom options might confuse parsing of commands and its parameters and most probably would lead to an "unknown" command error when the remainders of non-removed 3rd party option arguments are consumed later.

As a consequence of this approach, a subsequent call to this method has no effect.

Definition at line 85 of file commandline.cpp.

◆ RemoveArg()

void alib::cli::CommandLine::RemoveArg ( integer argNo )

Removes the argument at position argNo. If the argument is not in ArgsLeft, an ALib Assertion is raised.

See also: Method PeekArg, PopArg and ReadNextCommands.

Parameters

argNo The argument number to remove.

Definition at line 211 of file commandline.cpp.

◆ TryResource()

const String & alib::cli::CommandLine::TryResource ( const NString & name )

inline

Helper function that uses fields Resources and ResourceCategory to fetch a resourced string.

Note: Usually, it is recommended to use GetResource, which asserts with debug-builds if a resource was not found.

Parameters

name	The resource name.

Returns: The resource string, respectively a nulled string on failure.

Definition at line 188 of file commandline.inl.

◆ UndefineCommand()

void alib::cli::CommandLine::UndefineCommand ( Enum command )

inline

Removes a recognizable command previously defined with DefineCommands.

See also: Chapter 4.2 Undefine CLI Elements of the Programmer's Manual.

Parameters

command The enumeration element that identifies the command to undefine.

Definition at line 270 of file commandline.inl.

◆ UndefineExitCode()

void alib::cli::CommandLine::UndefineExitCode ( Enum exitCode )

inline

Removes a recognizable exit-code previously defined with DefineExitCodes.

See also: Chapter 4.2 Undefine CLI Elements of the Programmer's Manual.

Parameters

exitCode The enumeration element that identifies the exitCode to undefine.

Definition at line 327 of file commandline.inl.

◆ UndefineOption()

void alib::cli::CommandLine::UndefineOption ( Enum option )

inline

Removes a recognizable option previously defined with DefineOptions.

See also: Chapter 4.2 Undefine CLI Elements of the Programmer's Manual.

Parameters

option The enumeration element that identifies the option to undefine.

Definition at line 300 of file commandline.inl.

◆ UndefineParameter()

void alib::cli::CommandLine::UndefineParameter ( Enum parameter )

inline

Removes a recognizable parameter previously defined with DefineParameters.

See also: Chapter 4.2 Undefine CLI Elements of the Programmer's Manual.

Parameters

parameter The enumeration element that identifies the parameter to undefine.

Definition at line 239 of file commandline.inl.

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

Description:

Friends

Public Field Index:

Public Method Index:

Protected Field Index:

Field Details:

◆ allocator

◆ AppInfo

◆ ArgsLeft

◆ ArgStrings

◆ CommandDecls

◆ CommandsParsed

◆ DryRun

◆ ExitCodeDecls

◆ MaxNameLength

◆ NextCommandIt

◆ OptionArgsIgnored

◆ OptionDecls

◆ Options

◆ ParameterDecls

◆ paramListRecycler

◆ ResourceCategory

◆ Resources

◆ stringListRecycler

Constructor(s) / Destructor Details:

◆ CommandLine()

◆ ~CommandLine()

Method Details:

◆ ArgCount()

◆ DefineCommands()

◆ DefineExitCodes()

◆ DefineOptions()

◆ DefineParameters()

◆ GetAllocator()

◆ GetArg()

◆ GetOption()

◆ GetResource()

◆ Init() [1/2]

◆ Init() [2/2]

◆ NextCommand()

◆ PeekArg()

◆ PopArg()

◆ ReadNextCommands()

◆ ReadOptions()

◆ RemoveArg()

◆ TryResource()

◆ UndefineCommand()

◆ UndefineExitCode()

◆ UndefineOption()

◆ UndefineParameter()