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

class CLIUtil

Exceptions

alib::cli::Exceptions

Definition at line 35 of file commandline.hpp.

#include <commandline.hpp>

Collaboration diagram for CommandLine:

[legend]

Public Field Index:
String	AppInfo

StdVectorMono< integer >	ArgsLeft

StdVectorMono< String >	ArgStrings

List< MonoAllocator, CommandDecl * >	CommandDecls
	Commands defined.

List< MonoAllocator, 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 }

List< MonoAllocator, Command * >::Iterator	NextCommandIt
	The next command in CommandsParsed to be processed. Used with method NextCommand.

List< MonoAllocator, String, Recycling::Shared >	OptionArgsIgnored

List< MonoAllocator, OptionDecl * >	OptionDecls
	Possible Options.

List< MonoAllocator, Option * >	Options
	The options parsed in the order of their appearance.

List< MonoAllocator, ParameterDecl * >	ParameterDecls
	Possible Parameters.

NCString	ResourceCategory
	The resource category to fetch CLI resources within field Resources.

lang::resources::ResourcePool *	Resources = nullptr

Public Method Index:
	CommandLine ()
	Constructor.

virtual	~CommandLine ()
	Virtual empty destructor.

virtual integer	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)

ALIB_API Option *	GetOption (Enum element)

const String &	GetResource (const NString &name)

void	Init (lang::Camp *resModule)

virtual ALIB_API void	Init (lang::resources::ResourcePool *resourcePool, NCString resCategory)

virtual ALIB_API Command *	NextCommand ()

virtual String	PeekArg ()

virtual ALIB_API String	PopArg ()

virtual ALIB_API void	ReadNextCommands ()

virtual ALIB_API void	ReadOptions ()

ALIB_API void	RemoveArg (integer argNo)

const String &	TryResource (const NString &name)

Protected Field Index:
MonoAllocator	allocator

List< MonoAllocator, Parameter *, Recycling::Shared >::SharedRecyclerType	paramListRecycler

List< MonoAllocator, String, Recycling::Shared >::SharedRecyclerType	stringListRecycler
	The element recycler shared between lists of strings.

Field Details:

◆ allocator

MonoAllocator allocator

protected

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

Definition at line 61 of file commandline.hpp.

◆ AppInfo

String AppInfo

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

Definition at line 76 of file commandline.hpp.

◆ ArgsLeft

StdVectorMono<integer> 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 89 of file commandline.hpp.

◆ ArgStrings

StdVectorMono<String> 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 84 of file commandline.hpp.

◆ CommandDecls

List<MonoAllocator, CommandDecl*> CommandDecls

Commands defined.

Definition at line 93 of file commandline.hpp.

◆ CommandsParsed

List<MonoAllocator, Command*> CommandsParsed

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

Definition at line 116 of file commandline.hpp.

◆ DryRun

DryRunModes DryRun =DryRunModes::Off

Specifies if a "dry run" should be performed. For more information, see CLIUtil::GetDryOpt.

Definition at line 141 of file commandline.hpp.

◆ ExitCodeDecls

HashMap<MonoAllocator, Enum, ExitCodeDecl*> ExitCodeDecls

Possible Errors.

Definition at line 102 of file commandline.hpp.

◆ MaxNameLength

integer 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 126 of file commandline.hpp.

◆ NextCommandIt

List<MonoAllocator,Command*>::Iterator NextCommandIt

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

Definition at line 119 of file commandline.hpp.

◆ OptionArgsIgnored

List<MonoAllocator, String, Recycling::Shared> 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 113 of file commandline.hpp.

◆ OptionDecls

List<MonoAllocator, OptionDecl*> OptionDecls

Possible Options.

Definition at line 96 of file commandline.hpp.

◆ Options

List<MonoAllocator, Option*> Options

The options parsed in the order of their appearance.

Definition at line 107 of file commandline.hpp.

◆ ParameterDecls

List<MonoAllocator, ParameterDecl*> ParameterDecls

Possible Parameters.

Definition at line 99 of file commandline.hpp.

◆ paramListRecycler

List<MonoAllocator,Parameter*,Recycling::Shared>::SharedRecyclerType paramListRecycler

protected

The element recycler shared between fields Command::ParametersMandatory and Command::ParametersOptional.

Definition at line 68 of file commandline.hpp.

◆ ResourceCategory

NCString ResourceCategory

The resource category to fetch CLI resources within field Resources.

Definition at line 137 of file commandline.hpp.

◆ Resources

lang::resources::ResourcePool* 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 134 of file commandline.hpp.

◆ stringListRecycler

List<MonoAllocator,String,Recycling::Shared>::SharedRecyclerType stringListRecycler

protected

The element recycler shared between lists of strings.

Definition at line 64 of file commandline.hpp.

Constructor(s) / Destructor Details:

◆ CommandLine()

CommandLine ( )

inline

Constructor.

Definition at line 148 of file commandline.hpp.

◆ ~CommandLine()

virtual ~CommandLine ( )

inlinevirtual

Virtual empty destructor.

Definition at line 166 of file commandline.hpp.

Method Details:

◆ ArgCount()

virtual integer ArgCount ( )

inlinevirtual

Retrieves the number of arguments.

Returns: The number of arguments given.

Definition at line 484 of file commandline.hpp.

◆ DefineCommands()

template<typename TEnum >

void DefineCommands ( )

inline

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

Template Parameters

TEnum The enum type.

◆ DefineExitCodes()

template<typename TEnum >

void DefineExitCodes ( )

inline

Defines errors given with enumeration TEnum. ALib Enum Records of type ERExitCodeDecl need to associated to given enumeration type TEnum.

Template Parameters

TEnum The enum type.

◆ DefineOptions()

template<typename TEnum >

void DefineOptions ( )

inline

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

Template Parameters

TEnum The enum type.

◆ DefineParameters()

template<typename TEnum >

void DefineParameters ( )

inline

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

Template Parameters

TEnum The enum type.

◆ GetAllocator()

MonoAllocator & 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 lifecylce of the instance of this class.

Returns: The internal allocator

Definition at line 180 of file commandline.hpp.

◆ GetArg()

virtual String GetArg ( integer idx )

inlinevirtual

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

Parameters

idx	The requested argument's index.

Returns: The element idx of vector ArgStrings.

Definition at line 496 of file commandline.hpp.

◆ GetOption()

Option * 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 157 of file commandline.cpp.

◆ GetResource()

const String & 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 193 of file commandline.hpp.

Here is the call graph for this function:

◆ Init() [1/2]

void Init ( lang::Camp * resModule )

inline

Simple helper method that invokes Init(lang::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 217 of file commandline.hpp.

Here is the call graph for this function:

◆ Init() [2/2]

void Init	(	lang::resources::ResourcePool *	resourcePool,
		NCString	resCategory )

virtual

Initializes this class. This function has to be invoked after construction and after this object 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(lang::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 22 of file commandline.cpp.

Here is the call graph for this function:

◆ NextCommand()

Command * 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 200 of file commandline.cpp.

Here is the call graph for this function:

◆ PeekArg()

virtual String 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 512 of file commandline.hpp.

◆ PopArg()

String 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 224 of file commandline.cpp.

Here is the call graph for this function:

◆ ReadNextCommands()

void ReadNextCommands ( )

virtual

Parses as many commands as possible and stores them in CommandsParsed. Prior to invoking this methods, 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 CLIUtil::DumpParseResults 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 166 of file commandline.cpp.

Here is the call graph for this function:

◆ ReadOptions()

void 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, field Option::Position is quite useful, as well as 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::config::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 86 of file commandline.cpp.

Here is the call graph for this function:

◆ RemoveArg()

void 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 234 of file commandline.cpp.

◆ TryResource()

const String & 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 207 of file commandline.hpp.

Here is the call graph for this function:

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