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

Method Details:

◆ DumpDeclarations()

AString & 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 341 of file cliutil.cpp.

Here is the call graph for this function:

◆ DumpParseResults()

AString & 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 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.

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 464 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetCommandDecl()

CommandDecl * 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 CommandDecl::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 CommandLine::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 43 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetCommandUsageFormat()

AString 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.

Here is the call graph for this function:

◆ GetDryOpt()

bool GetDryOpt	(	CommandLine &	cmdLine,
		Option &	dryOpt )

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:

"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), 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:

Do not use this method but implement a custom version. In case that only DryRunModes::Application should be accepted, instead calling this util method, simply set field CommandLine::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. 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.

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 303 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetExitCode()

static ALIB_API integer GetExitCode	(	CommandLine &	cmdLine,
		Exception &	exception )

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.

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 133 of file cliutil.hpp.

Here is the call graph for this function:

◆ GetHelp()

bool GetHelp	(	CommandLine &	cmdLine,
		Command *	helpCmd,
		Option *	helpOpt,
		Paragraphs &	text )

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.

Parameters

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.

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 85 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetOptionDecl()

OptionDecl * 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 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.

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 CommandLine::ReadOptions , which parses and collects options in filed CommandLine::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 31 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetParameterDecl()

ParameterDecl * 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 CommandDecl::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 52 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()

◆ GetOptionDecl()

◆ GetParameterDecl()