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

#include <cliutil.hpp>

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	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::app::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 237 of file cliutil.cpp.

Here is the call graph for this function:

◆ DumpParseResults()

AString & alib::app::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 352 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetCommandDecl()

CommandDecl * alib::app::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 15 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetCommandUsageFormat()

AString alib::app::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 32 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetHelp() [1/3]

bool alib::app::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 a 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 56 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetHelp() [2/3]

bool alib::app::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 87 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetHelp() [3/3]

bool alib::app::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 70 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetOptionDecl()

OptionDecl * alib::app::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 4 of file cliutil.cpp.

Here is the call graph for this function:

◆ GetParameterDecl()

ParameterDecl * alib::app::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 23 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()

◆ GetHelp() [1/3]

◆ GetHelp() [2/3]

◆ GetHelp() [3/3]

◆ GetOptionDecl()

◆ GetParameterDecl()