ALib C++ Library
Library Version: 2412 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
CLIUtil Class Reference

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

#include <cliutil.hpp>

Public Static Method Index:

static ALIB_API AStringDumpDeclarations (CommandLine &cmdLine, Paragraphs &text)
 
static ALIB_API AStringDumpParseResults (CommandLine &cmdLine, Paragraphs &text)
 
static ALIB_API CommandDeclGetCommandDecl (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 OptionDeclGetOptionDecl (CommandLine &cmdLine, const String &identString)
 
static ALIB_API ParameterDeclGetParameterDecl (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
cmdLineThe friend object we work on.
textThe target text.
Returns
An internal AString object containing the dump text. (Beware of concurrent debugging threads :-)

Definition at line 331 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
cmdLineThe friend object we work on.
textThe target text.
Returns
Returns an internal AString object containing the dump text. (Beware of concurrent debugging threads :-)

Definition at line 454 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
cmdLineThe friend object we work on.
identStringThe identifier of the command to search.
Returns
The object of type CommandDecl. nullptr if not found.

Definition at line 33 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
cmdLineThe command line instance.
commandDeclThe declaration of the command to get help on.
Returns
The help text.

Definition at line 52 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:

  1. 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.
  2. Check for the "forbidden" argument type after the invocation of this method and exit your cli app
  3. 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
cmdLineThe command line instance.
dryOptThe option object parsed.
Returns
true on success. false if an argument was given that is not recognized.

Definition at line 293 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
cmdLineThe friend object we work on.
exceptionThe cli exception caught.
Returns
The exit code to return to the caller. -1, if not found.

Definition at line 126 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
cmdLineThe command line instance.
helpCmdThe command to write the help text for.
helpOptThe option to write the help text for.
textThe 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 75 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
cmdLineThe friend object we work on.
identStringThe 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 21 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
cmdLineThe friend object we work on.
identStringThe identifier of the command to search.
Returns
The object of type CommandDecl. nullptr if not found.

Definition at line 42 of file cliutil.cpp.


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