#include <cliapp.hpp>

Collaboration diagram for CLIApp:

[legend]

Class Description

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

For an introduction to its use see documentation of ALib Module CLI.

See also: "Utility" methods which could have been implemented as an interface of this class have instead been located in CLIUtil.

Friends

class CLIUtil

Exceptions

aworx::lib::cli::Exceptions

Definition at line 49 of file cliapp.hpp.

Public Fields
String	AppInfo

int	ArgcOriginal

const char **	ArgNOriginal

std::vector< integer, StdContMA< integer > >	ArgsLeft

std::vector< String, StdContMA< String > >	ArgStrings

const wchar_t **	ArgWOriginal

List< CommandDecl * >	CommandDecls

List< Command >	CommandsParsed

DryRunModes	DryRun =DryRunModes::Off

HashMap< Enum, ExitCodeDecl * >	ExitCodeDecls

integer	MaxNameLength [3] = { 0,0, 0 }

List< Command >::Iterator	NextCommandIt

List< String, Recycling::Shared >	OptionArgsIgnored

List< OptionDecl * >	OptionDecls

List< Option * >	Options

List< ParameterDecl * >	ParameterDecls

Module *	ResModule = nullptr

Public Methods
	CLIApp ()

virtual	~CLIApp ()

virtual String	Arg (integer idx)

virtual integer	ArgCount ()

template<typename TEnum >
void	DefineCommands ()

template<typename TEnum >
void	DefineExitCodes ()

template<typename TEnum >
void	DefineOptions ()

template<typename TEnum >
void	DefineParameters ()

Option *	GetOption (Enum element)

virtual ALIB_API void	Init (Module *resModule)

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)

Protected Fields
MonoAllocator	allocator

List< Parameter *, Recycling::Shared >::TSharedRecycler	paramListRecycler

List< String, Recycling::Shared >::TSharedRecycler	stringListRecycler

Constructor & Destructor Documentation

◆ CLIApp()

CLIApp ( )

inline

Constructor.

Definition at line 188 of file cliapp.hpp.

◆ ~CLIApp()

virtual ~CLIApp ( )

inlinevirtual

Virtual empty destructor.

Definition at line 205 of file cliapp.hpp.

Member Function Documentation

◆ Arg()

virtual String Arg ( integer idx )

inlinevirtual

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

Parameters

idx	The requested argument's index.

Returns: The element idx of vector ArgStrings.

Definition at line 476 of file cliapp.hpp.

Here is the caller graph for this function:

◆ ArgCount()

virtual integer ArgCount ( )

inlinevirtual

Retrieves the argument at the given position.

In debug builds, this method assert the index range.

Returns: The element idx of vector ArgStrings.

Definition at line 464 of file cliapp.hpp.

Here is the caller graph for this function:

◆ DefineCommands()

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

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

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

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.

◆ 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 the CLI argument.

Parameters

element The option's declaration enum element.

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

Definition at line 166 of file cliapp.cpp.

◆ Init()

void Init ( Module * resModule )

virtual

Initializes this class. This function has to be invoked after construction and after the ALib module system is initialized.

Parameters

resModule The module used to load resource strings.

Definition at line 30 of file cliapp.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 209 of file cliapp.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 492 of file cliapp.hpp.

Here is the caller graph for this function:

◆ 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 233 of file cliapp.cpp.

Here is the call graph for this function:

Here is the caller 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 prior to 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 prior to 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 175 of file cliapp.cpp.

Here is the call graph for this function:

Here is the caller 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 assured 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 CLIArgs used with ALib configuration variables. After this method has been invoked, vector OptionArgsIgnored may/should be passed to the plug-in CLIArgs 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<aworx::lib::config::CLIArgs>()->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 95 of file cliapp.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 243 of file cliapp.cpp.

Here is the caller graph for this function:

Member Data Documentation

◆ allocator

MonoAllocator allocator

protected

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

Definition at line 75 of file cliapp.hpp.

◆ AppInfo

String AppInfo

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

Definition at line 92 of file cliapp.hpp.

◆ ArgcOriginal

int ArgcOriginal

The original number of command line arguments (provided in constructor)

Definition at line 98 of file cliapp.hpp.

◆ ArgNOriginal

const char** ArgNOriginal

The original command line arguments (provided in constructor). Might be nullptr, if wchar_t variant of constructor was used.

Definition at line 104 of file cliapp.hpp.

◆ ArgsLeft

std::vector<integer, StdContMA<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 126 of file cliapp.hpp.

◆ ArgStrings

std::vector<String, StdContMA<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 119 of file cliapp.hpp.

◆ ArgWOriginal

const wchar_t** ArgWOriginal

The original command line arguments (provided in constructor) Might be nullptr, if char variant of constructor was used.

Definition at line 110 of file cliapp.hpp.

◆ CommandDecls

List<CommandDecl*> CommandDecls

Commands defined.

Definition at line 130 of file cliapp.hpp.

◆ CommandsParsed

List<Command> CommandsParsed

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

Definition at line 156 of file cliapp.hpp.

◆ DryRun

DryRunModes DryRun =DryRunModes::Off

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

Definition at line 179 of file cliapp.hpp.

◆ ExitCodeDecls

HashMap<Enum, ExitCodeDecl*> ExitCodeDecls

Possible Errors.

Definition at line 139 of file cliapp.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 167 of file cliapp.hpp.

◆ NextCommandIt

List<Command>::Iterator NextCommandIt

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

Definition at line 159 of file cliapp.hpp.

◆ OptionArgsIgnored

List<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 153 of file cliapp.hpp.

◆ OptionDecls

List<OptionDecl*> OptionDecls

Possible Options.

Definition at line 133 of file cliapp.hpp.

◆ Options

List<Option*> Options

The options parsed in the order of their appearance.

Definition at line 145 of file cliapp.hpp.

◆ ParameterDecls

List<ParameterDecl*> ParameterDecls

Possible Parameters.

Definition at line 136 of file cliapp.hpp.

◆ paramListRecycler

List<Parameter*, Recycling::Shared>::TSharedRecycler paramListRecycler

protected

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

Definition at line 82 of file cliapp.hpp.

◆ ResModule

Module* ResModule = nullptr

The module of the main application. Several resources are loaded from this in addition to what is loaded as enum meta information of the cli declaration objects.

Definition at line 173 of file cliapp.hpp.

◆ stringListRecycler

List<String, Recycling::Shared>::TSharedRecycler stringListRecycler

protected

The element recycler shared between lists of strings.

Definition at line 78 of file cliapp.hpp.

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

Class Description

Friends

Public Fields

Public Methods

Protected Fields

Constructor & Destructor Documentation

◆ CLIApp()

◆ ~CLIApp()

Member Function Documentation

◆ Arg()

◆ ArgCount()

◆ DefineCommands()

◆ DefineExitCodes()

◆ DefineOptions()

◆ DefineParameters()

◆ GetOption()

◆ Init()

◆ NextCommand()

◆ PeekArg()

◆ PopArg()

◆ ReadNextCommands()

◆ ReadOptions()

◆ RemoveArg()

Member Data Documentation

◆ allocator

◆ AppInfo

◆ ArgcOriginal

◆ ArgNOriginal

◆ ArgsLeft

◆ ArgStrings

◆ ArgWOriginal

◆ CommandDecls

◆ CommandsParsed

◆ DryRun

◆ ExitCodeDecls

◆ MaxNameLength

◆ NextCommandIt

◆ OptionArgsIgnored

◆ OptionDecls

◆ Options

◆ ParameterDecls

◆ paramListRecycler

◆ ResModule

◆ stringListRecycler