|
ALib C++ Framework
|
by |  |
|
Loading...
Searching...
No Matches
|
ALib C++ Framework
|
by | |
|
This class provides a foundation for software executables that processes command-line parameters.
class CLIUtil
| Exception | app::CLIExceptions |
#include <cli.hpp>
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. | |
| 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 () |
| bool | 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. | |
|
protected |
| String alib::app::CommandLine::AppInfo |
| StdVectorMA<integer> alib::app::CommandLine::ArgsLeft |
| StdVectorMA<String> alib::app::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.
| ListMA<CommandDecl*> alib::app::CommandLine::CommandDecls |
A list of commands actually parsed. Filled with method ReadNextCommands.
| HashMap<MonoAllocator, Enum, ExitCodeDecl*> alib::app::CommandLine::ExitCodeDecls |
| integer alib::app::CommandLine::MaxNameLength[3] ={ 0, 0, 0 } |
The next command in CommandsParsed to be processed. Used with method NextCommand.
List of arguments that start with a hyphen and are ignored by this class due to the fact that they were not recognized.
| ListMA<OptionDecl*> alib::app::CommandLine::OptionDecls |
| ListMA<ParameterDecl*> alib::app::CommandLine::ParameterDecls |
|
protected |
The element recycler shared between fields ListMA< Parameter *, Recycling::Shared > ParametersMandatory and ListMA< Parameter *, Recycling::Shared > ParametersOptional.
| NCString alib::app::CommandLine::ResourceCategory |
| resources::ResourcePool* alib::app::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.
|
inlinevirtual |
|
inlinevirtual |
|
inline |
Defines commands given with enumeration TEnum. ALib Enum Records of type ERCommandDecl need to be associated to the given enumeration type TEnum.
| TEnum | The enum type. |
Definition at line 252 of file cli.hpp.
|
inline |
Defines exit-codes given with enumeration TEnum. ALib Enum Records of type ERExitCodeDecl need to be associated to the given enumeration type TEnum.
| TEnum | The enum type. |
Definition at line 313 of file cli.hpp.
|
inline |
Defines options given with enumeration TEnum. ALib Enum Records of type EROptionDecl need to be associated to the given enumeration type TEnum.
| TEnum | The enum type. |
Definition at line 283 of file cli.hpp.
|
inline |
Defines parameters given with enumeration TEnum. ALib Enum Records of type ERParameterDecl need to be associated to the given enumeration type TEnum.
| TEnum | The enum type. |
Definition at line 222 of file cli.hpp.
|
inlinenoexcept |
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.
| element | The option's declaration enum element. |
nullptr if not given. 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.
| name | The resource name. |
|
inline |
Simple helper method that invokes Init(resources::ResourcePool*, NCString) providing the resource pool and categery of the given resModule.
| resModule | The module used to load resource strings. |
Definition at line 193 of file cli.hpp.
|
virtual |
Initializes this class. This function has to be invoked after construction and after ALib was bootstrapped.
This method accesses global ALib variables alib::ARG_C, alib::ARG_VN, and alib::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.
| resourcePool | The resource pool used to load resource strings. |
| resCategory | The resource category used to load resource strings. |
Definition at line 7 of file cli.cpp.
|
virtual |
Returns the next item in vector NextCommand. If needed, ReadNextCommands is invoked.
nullptr, if no more commands are found. Definition at line 152 of file cli.cpp.
|
inlinevirtual |
|
virtual |
Retrieves the next argument and removes it from list ArgsLeft.
Definition at line 164 of file cli.cpp.
|
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:
ReadNextCommands )A similar parsing approach is supported with the 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 125 of file cli.cpp.
|
virtual |
Finalizes Initialization and has to be called after all invocations of:
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.
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 57 of file cli.cpp.
| bool alib::app::CommandLine::RemoveArg | ( | integer | argNo | ) |
Removes the argument at position argNo. If the argument is not in ArgsLeft, an ALib Assertion is raised.
| argNo | The argument number to remove. |
false if the arg was removed before, true if the arg was removed now. Helper function that uses fields Resources and ResourceCategory to fetch a resourced string.
| name | The resource name. |
|
inline |
Removes a recognizable command previously defined with DefineCommands.
| command | The enumeration element that identifies the command to undefine. |
|
inline |
Removes a recognizable exit-code previously defined with DefineExitCodes.
| exitCode | The enumeration element that identifies the exitCode to undefine. |
|
inline |
Removes a recognizable option previously defined with DefineOptions.
| option | The enumeration element that identifies the option to undefine. |
|
inline |
Removes a recognizable parameter previously defined with DefineParameters.
| parameter | The enumeration element that identifies the parameter to undefine. |
