This is a friend class of CommandLine that exposes a collection of utility methods useful for CLI applications.
The methods found here are static and receive the friend CommandLine object. They have been gathered in this class to keep CommandLine tidy and more easily understandable as only needed methods are found there.
Methods found here, might be used as a jump start for own implementations. Their documentation is considered only fundamental. For details, please consult the source code.
Definition at line 34 of file cliutil.hpp.
#include <cliutil.hpp>
Public Static Method Index: | |
static ALIB_API AString & | DumpDeclarations (CommandLine &cmdLine, Paragraphs &text) |
static ALIB_API AString & | DumpParseResults (CommandLine &cmdLine, Paragraphs &text) |
static ALIB_API CommandDecl * | GetCommandDecl (CommandLine &cmdLine, const String &identString) |
static ALIB_API AString | GetCommandUsageFormat (CommandLine &cmdLine, CommandDecl &commandDecl) |
static ALIB_API bool | GetDryOpt (CommandLine &cmdLine, Option &dryOpt) |
static ALIB_API integer | GetExitCode (CommandLine &cmdLine, Exception &exception) |
static ALIB_API bool | GetHelp (CommandLine &cmdLine, Command *helpCmd, Option *helpOpt, Paragraphs &text) |
static ALIB_API OptionDecl * | GetOptionDecl (CommandLine &cmdLine, const String &identString) |
static ALIB_API ParameterDecl * | GetParameterDecl (CommandLine &cmdLine, const String &identString) |
|
static |
Dumps the configuration. Shows which commands, options, parameters and errors are set with enums and their meta info. Useful during development.
cmdLine | The friend object we work on. |
text | The target text. |
AString
object containing the dump text. (Beware of concurrent debugging threads :-) Definition at line 331 of file cliutil.cpp.
|
static |
Write in human-readable form, which commands and options have been read from the command line.
This is useful for debugging as well as to implement a "dry run" option of the CLI application, that offers the user a list of what is parsed with a given set of CLI arguments. In this case, method read CommandLine::ReadNextCommands should be invoked after the provisions of the various definitions.
Probably, depending on the command syntax, not all commands can be parsed prior to executing them. However, options can.
cmdLine | The friend object we work on. |
text | The target text. |
AString
object containing the dump text. (Beware of concurrent debugging threads :-) Definition at line 454 of file cliutil.cpp.
|
static |
Searches and if found, retrieves the declaration of the command identified by identString. Matching is done case insensitive and with respecting CommandDecl::MinimumRecognitionLength.
This method is useful to implement a help command or option, with an optional "topic" parameter.
cmdLine | The friend object we work on. |
identString | The identifier of the command to search. |
nullptr
if not found. Definition at line 33 of file cliutil.cpp.
|
static |
Returns an AString providing a formatted help text on the defined command.
cmdLine | The command line instance. |
commandDecl | The declaration of the command to get help on. |
Definition at line 52 of file cliutil.cpp.
|
static |
Reads a dry-run options and stores the result in CommandLine::DryRun.
Option arguments as defined with records of enumeration DryRunModes are accepted. These records are resourced and default to:
If no argument is set in the given dryOpt, the next unread CLI-argument is checked for being parsable as an element of enum DryRunModes. If yes, the CLI-argument is consumed and duly stored in dryOpt.
In case no argument was set (or successfully peeked), DryRunModes::Application is chosen and stored.
If one of the modes offered by enumeration DryRunModes should not be recognizable, three ways of implementing this exist:
By modifying the resource string, it is also possible to add custom options. Remeber, that it is allowed in C++ to have an enum element evaluate to any integral, regardless whether it is defined in the C++ definition or not.
cmdLine | The command line instance. |
dryOpt | The option object parsed. |
true
on success. false
if an argument was given that is not recognized. Definition at line 293 of file cliutil.cpp.
|
inlinestatic |
Translates exceptions thrown by the ALib CLI library to exit codes defined with CommandLine::DefineExitCodes.
If the code is not found, this indicates an error in the resource data, as an exit code corresponding to the ALib CLI exceptions is obviously missing. In this case, -1
is returned. With debug-builds an ALib assertion is raised.
cmdLine | The friend object we work on. |
exception | The cli exception caught. |
-1
, if not found. Definition at line 126 of file cliutil.hpp.
|
static |
Creates a help text from the resource strings.
This method accepts either a command object or an option object that the command line instance uses to process help requests. Only one of the objects has to be provided, the other has to be nullptr
.
If no argument is set in helpCmd (respectively helpOpt), the next argument is peeked and checked to be a command, option, parameter or special help topic found in resource string "HlpAddnlTopics".
If found, the argument is consumed and stored in helpCmd (respectively helpOpt). If not, the general help text is generated.
cmdLine | The command line instance. |
helpCmd | The command to write the help text for. |
helpOpt | The option to write the help text for. |
text | The target text. |
true
on success. false
if an argument was given that is not recognized or if a topic list was found in the next argument where only some of the topics could be identified. Definition at line 75 of file cliutil.cpp.
|
static |
Searches and if found, retrieves the declaration of the option identified by identString which, if it contains a single character is compared to the OptionDecl::IdentifierChar. Otherwise, matching is done case insensitive and with respecting OptionDecl::MinimumRecognitionLength.
This method is useful to implement a help command or option, with an optional "topic" parameter.
cmdLine | The friend object we work on. |
identString | The identifier string of the option to search. If this is a single character, the short identifier is searched. |
nullptr
if not found. Definition at line 21 of file cliutil.cpp.
|
static |
Searches and if found, retrieves the declaration of the parameter identified by identString. Matching is done case insensitive and with respecting CommandDecl::MinimumRecognitionLength.
This method is useful to implement a help command (or option), with an optional "topic" parameter.
cmdLine | The friend object we work on. |
identString | The identifier of the command to search. |
nullptr
if not found. Definition at line 42 of file cliutil.cpp.