Description:

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.

Note: The nature of this class is to provide a basic, standard functionality. It was created while building a CLI application based on this library and provided for convenience.

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 26 of file cliutil.inl.

Public Static Method Index:
static AString &	DumpDeclarations (CommandLine &cmdLine, Paragraphs &text)
static AString &	DumpParseResults (CommandLine &cmdLine, Paragraphs &text)
static CommandDecl *	GetCommandDecl (CommandLine &cmdLine, const String &identString)
static AString	GetCommandUsageFormat (CommandLine &cmdLine, CommandDecl &commandDecl)
static bool	GetDryOpt (CommandLine &cmdLine, Option &dryOpt)
static integer	GetExitCode (CommandLine &cmdLine, Exception &exception)
static bool	GetHelp (CommandLine &cmdLine, Command *helpCmd, Paragraphs &text)
static bool	GetHelp (CommandLine &cmdLine, const String &topics, Paragraphs &text)
static bool	GetHelp (CommandLine &cmdLine, Option *helpOpt, Paragraphs &text)
static OptionDecl *	GetOptionDecl (CommandLine &cmdLine, const String &identString)
static ParameterDecl *	GetParameterDecl (CommandLine &cmdLine, const String &identString)

Method Details:

◆ DumpDeclarations()

AString & alib::cli::CLIUtil::DumpDeclarations	(	CommandLine &	cmdLine,
		Paragraphs &	text )

static

Dumps the configuration. Shows which commands, options, parameters and errors are set with enums and their meta info. Useful during development.

Parameters

cmdLine	The friend object we work on.
text	The target text.

Returns: An internal AString object containing the dump text. (Beware of concurrent debugging threads :-)

Definition at line 297 of file cliutil.cpp.

◆ DumpParseResults()

AString & alib::cli::CLIUtil::DumpParseResults	(	CommandLine &	cmdLine,
		Paragraphs &	text )

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 virtual void 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.

Parameters

cmdLine	The friend object we work on.
text	The target text.

Returns: Returns an internal AString object containing the dump text. (Beware of concurrent debugging threads :-)

Definition at line 412 of file cliutil.cpp.

◆ GetCommandDecl()

CommandDecl * alib::cli::CLIUtil::GetCommandDecl	(	CommandLine &	cmdLine,
		const String &	identString )

static

Searches and if found, retrieves the declaration of the command identified by identString. Matching is done case-insensitive and with respecting int MinimumRecognitionLength() .

This method is useful to implement a help command or option, with an optional "topic" parameter.

Note: If parsing of arguments should be (or has to be) customized, of course this method can also be used for implementing such custom code. Otherwise, use virtual Command * NextCommand() to retrieve command objects (instead of command declarations).

See also: Methods GetOptionDecl, GetParameterDecl.

Parameters

cmdLine	The friend object we work on.
identString	The identifier of the command to search.

Returns: The object of type CommandDecl. nullptr if not found.

Definition at line 45 of file cliutil.cpp.

◆ GetCommandUsageFormat()

AString alib::cli::CLIUtil::GetCommandUsageFormat	(	CommandLine &	cmdLine,
		CommandDecl &	commandDecl )

static

Returns an AString providing a formatted help text on the defined command.

Parameters

cmdLine	The command-line instance.
commandDecl	The declaration of the command to get help on.

Returns: The help text.

Definition at line 62 of file cliutil.cpp.

◆ GetDryOpt()

bool alib::cli::CLIUtil::GetDryOpt	(	CommandLine &	cmdLine,
		Option &	dryOpt )

static

Reads a dry-run option and stores the result in DryRunModes DryRun.

Option arguments as defined with records of enumeration DryRunModes are accepted. These records are resourced and default to:

"DRM" ,  A_CHAR( "0"  ","   "Off"              ","      "1"  ","
                 "2"  ","   "CLIDeclarations"  ","      "4"  ","
                 "1"  ","   "CLIArgs"          ","      "1"  ","
                 "3"  ","   "Application"      ","      "1"       ) ,

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), Application is chosen and stored.

If one of the modes offered by enumeration DryRunModes should not be recognizable, three ways of implementing this exist:

Do not use this method but implement a custom version. In case that only Application should be accepted, instead calling this util method, simply set field DryRunModes DryRun to this value.
Check for the "forbidden" argument type after the invocation of this method and exit your cli app
Modify this module's resource string "CLI/DRM" to not contain the suppressed argument's record. (With that, the defaulted argument names can also be modified).

By modifying the resource string, it is also possible to add custom options. Remember, 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.

Parameters

cmdLine	The command-line instance.
dryOpt	The option object parsed.

Returns: true on success. false if an argument was given that is not recognized.

Definition at line 264 of file cliutil.cpp.

◆ GetExitCode()

integer alib::cli::CLIUtil::GetExitCode	(	CommandLine &	cmdLine,
		Exception &	exception )

inlinestatic

Translates exceptions thrown by the ALib CLI library to exit-codes defined with void 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.

Parameters

cmdLine	The friend object we work on.
exception	The cli exception caught.

Returns: The exit-code to return to the caller. -1, if not found.

Definition at line 108 of file cliutil.inl.

◆ GetHelp() [1/3]

bool alib::cli::CLIUtil::GetHelp	(	CommandLine &	cmdLine,
		Command *	helpCmd,
		Paragraphs &	text )

static

Creates a help text from the given help command.

This method accepts a command-object that the command-line instance uses to process help requests.

If no argument is set in helpCmd, the next argument is peeked and is 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. If not, the general help text is generated.

Parameters

cmdLine	The command-line instance.
helpCmd	The command to write the help text for.
text	The target text.

Returns: 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 83 of file cliutil.cpp.

◆ GetHelp() [2/3]

bool alib::cli::CLIUtil::GetHelp	(	CommandLine &	cmdLine,
		const String &	topics,
		Paragraphs &	text )

static

Creates a help text from the resource strings.

Parameters

cmdLine	The command-line instance.
topics	A comma-separated list of topics. If empty or nulled, general help is created.
text	The target text.

Returns: 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 110 of file cliutil.cpp.

◆ GetHelp() [3/3]

bool alib::cli::CLIUtil::GetHelp	(	CommandLine &	cmdLine,
		Option *	helpOpt,
		Paragraphs &	text )

static

Creates a help text from the given help option.

This method accepts an option-object that the command-line instance uses to process help requests.

If no argument is set in helpOpt, the next argument is peeked and is 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 helpOpt. If not, the general help text is generated.

Parameters

cmdLine	The command-line instance.
helpOpt	The option to write the help text for.
text	The target text.

Returns: 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 95 of file cliutil.cpp.

◆ GetOptionDecl()

OptionDecl * alib::cli::CLIUtil::GetOptionDecl	(	CommandLine &	cmdLine,
		const String &	identString )

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 character IdentifierChar() . Otherwise, matching is done case-insensitive and with respecting int MinimumRecognitionLength() .

This method is useful to implement a help command or option, with an optional "topic" parameter.

Note: If parsing of arguments should be (or has to be) customized, of course this method can also be used for implementing such custom code. Otherwise, use method virtual void ReadOptions() , which parses and collects options in filed ListMA< Option * > Options.

See also: Methods GetCommandDecl, GetParameterDecl.

Parameters

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.

Returns: The object of type OptionDecl. nullptr if not found.

Definition at line 34 of file cliutil.cpp.

◆ GetParameterDecl()

ParameterDecl * alib::cli::CLIUtil::GetParameterDecl	(	CommandLine &	cmdLine,
		const String &	identString )

static

Searches and if found, retrieves the declaration of the parameter identified by identString. Matching is done case-insensitive and with respecting int MinimumRecognitionLength() .

This method is useful to implement a help command (or option), with an optional "topic" parameter.

See also: Methods GetOptionDecl, GetCommandDecl.

Parameters

cmdLine	The friend object we work on.
identString	The identifier of the command to search.

Returns: The object of type CommandDecl. nullptr if not found.

Definition at line 53 of file cliutil.cpp.

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

Description:

Public Static Method Index:

Method Details:

◆ DumpDeclarations()

◆ DumpParseResults()

◆ GetCommandDecl()

◆ GetCommandUsageFormat()

◆ GetDryOpt()

◆ GetExitCode()

◆ GetHelp() [1/3]

◆ GetHelp() [2/3]

◆ GetHelp() [3/3]

◆ GetOptionDecl()

◆ GetParameterDecl()