C++ Utilities  4.17.0
Useful C++ classes and routines such as argument parser, IO and conversion utilities
Namespaces | Classes | Typedefs | Enumerations | Functions | Variables
ApplicationUtilities Namespace Reference

Contains currently only ArgumentParser and related classes. More...

Namespaces

 ValueConversion
 Contains functions to convert raw argument values to certain types.
 

Classes

class  Argument
 The Argument class is a wrapper for command line argument information. More...
 
struct  ArgumentCompletionInfo
 The ArgumentCompletionInfo struct holds information internally used for shell completion and suggestions. More...
 
struct  ArgumentOccurrence
 The ArgumentOccurrence struct holds argument values for an occurrence of an argument. More...
 
class  ArgumentParser
 The ArgumentParser class provides a means for handling command line arguments. More...
 
class  ArgumentReader
 The ArgumentReader class internally encapsulates the process of reading command line arguments. More...
 
struct  ArgumentSuggestion
 
class  ConfigValueArgument
 The ConfigValueArgument class is an Argument where setCombinable() is true by default. More...
 
class  Failure
 The Failure class is thrown by an ArgumentParser when a parsing error occurs. More...
 
class  FakeQtConfigArguments
 The FakeQtConfigArguments class provides arguments for the Qt GUI used when the application hasn't been built with Qt GUI support. More...
 
class  HelpArgument
 The HelpArgument class prints help information for an argument parser when present (–help, -h). More...
 
class  Indentation
 The Indentation class allows printing indentation conveniently, eg. More...
 
class  NoColorArgument
 The NoColorArgument class allows to specify whether use of escape codes or similar technique to provide formatted output on the terminal should be enabled/disabled. More...
 
class  OperationArgument
 The OperationArgument class is an Argument where denotesOperation() is true by default. More...
 
struct  TerminalSize
 The TerminalSize struct describes a terminal size. More...
 
class  Wrapper
 The Wrapper class is internally used print text which might needs to be wrapped preserving the indentation. More...
 

Typedefs

using ArgumentInitializerList = std::initializer_list< Argument * >
 
using ArgumentVector = std::vector< Argument * >
 
using ArgumentPredicate = std::function< bool(Argument *)>
 

Enumerations

enum  UnknownArgumentBehavior { UnknownArgumentBehavior::Ignore, UnknownArgumentBehavior::Warn, UnknownArgumentBehavior::Fail }
 The UnknownArgumentBehavior enum specifies the behavior of the argument parser when an unknown argument is detected. More...
 
enum  ParseArgumentBehavior { ParseArgumentBehavior::ReadArguments = 0x0, ParseArgumentBehavior::CheckConstraints = 0x1, ParseArgumentBehavior::InvokeCallbacks = 0x2, ParseArgumentBehavior::ExitOnFailure = 0x4 }
 The ParseArgumentBehavior enum specifies the behavior when parsing arguments. More...
 
enum  ValueCompletionBehavior : unsigned char {
  ValueCompletionBehavior::None = 0, ValueCompletionBehavior::PreDefinedValues = 2, ValueCompletionBehavior::Files = 4, ValueCompletionBehavior::Directories = 8,
  ValueCompletionBehavior::FileSystemIfNoPreDefinedValues = 16, ValueCompletionBehavior::AppendEquationSign = 32, ValueCompletionBehavior::InvokeCallback = 64
}
 The ValueCompletionBehavior enum specifies the items to be considered when generating completion for an argument value. More...
 
enum  Response { Response::None, Response::Yes, Response::No }
 The Response enum is used to specify the default response for the confirmPrompt() method. More...
 
enum  ArgumentDenotationType : unsigned char { Value = 0, Abbreviation = 1, FullName = 2 }
 The ArgumentDenotationType enum specifies the type of a given argument denotation. More...
 

Functions

Argument CPP_UTILITIES_EXPORTfirstPresentUncombinableArg (const ArgumentVector &args, const Argument *except)
 This function return the first present and uncombinable argument of the given list of arguments. More...
 
bool CPP_UTILITIES_EXPORT confirmPrompt (const char *message, Response defaultResponse)
 Prompts for confirmation displaying the specified message. More...
 
TerminalSize CPP_UTILITIES_EXPORT determineTerminalSize ()
 Returns the current size of the terminal. More...
 
CPP_UTILITIES_EXPORT std::ostream & operator<< (std::ostream &out, Indentation indentation)
 
CPP_UTILITIES_EXPORT std::ostream & operator<< (std::ostream &o, const Failure &failure)
 Prints an error message "Unable to parse arguments: ..." for the specified failure. More...
 
std::ostream & operator<< (std::ostream &os, const Wrapper &wrapper)
 
bool compareArgs (const Argument *arg1, const Argument *arg2)
 Returns whether arg1 should be listed before arg2 when printing completion. More...
 
void insertSiblings (const ArgumentVector &siblings, list< const Argument * > &target)
 Inserts the specified siblings in the target list. More...
 

Variables

CPP_UTILITIES_EXPORT const char * applicationName = nullptr
 Specifies the name of the application (used by ArgumentParser::printHelp()). More...
 
CPP_UTILITIES_EXPORT const char * applicationAuthor = nullptr
 Specifies the author of the application (used by ArgumentParser::printHelp()). More...
 
CPP_UTILITIES_EXPORT const char * applicationVersion = nullptr
 Specifies the version of the application (used by ArgumentParser::printHelp()). More...
 
CPP_UTILITIES_EXPORT const char * applicationUrl = nullptr
 Specifies the URL to the application website (used by ArgumentParser::printHelp()). More...
 
CPP_UTILITIES_EXPORT std::initializer_list< const char * > dependencyVersions
 Specifies the dependency versions the application was linked against (used by ArgumentParser::printHelp()). More...
 
CPP_UTILITIES_EXPORT std::vector< const char * > dependencyVersions2
 Specifies the dependency versions the application was linked against (used by ArgumentParser::printHelp()). More...
 
CPP_UTILITIES_EXPORT void(* exitFunction )(int) = &exit
 Specifies a function quit the application. More...
 

Detailed Description

Contains currently only ArgumentParser and related classes.

Typedef Documentation

◆ ArgumentInitializerList

using ApplicationUtilities::ArgumentInitializerList = typedef std::initializer_list<Argument *>

Definition at line 57 of file argumentparser.h.

◆ ArgumentPredicate

using ApplicationUtilities::ArgumentPredicate = typedef std::function<bool(Argument *)>

Definition at line 59 of file argumentparser.h.

◆ ArgumentVector

using ApplicationUtilities::ArgumentVector = typedef std::vector<Argument *>

Definition at line 58 of file argumentparser.h.

Enumeration Type Documentation

◆ ArgumentDenotationType

The ArgumentDenotationType enum specifies the type of a given argument denotation.

Enumerator
Value 

parameter value

Abbreviation 

argument abbreviation

FullName 

full argument name

Definition at line 35 of file argumentparser.cpp.

◆ ParseArgumentBehavior

The ParseArgumentBehavior enum specifies the behavior when parsing arguments.

This concerns checking constraints, invoking callbacks and handling failures. The values are supposed to be combined using the |-operator. Note that ParseArgumentBehavior::ReadArguments is always implied.

Enumerator
ReadArguments 

reads the specified CLI arguments, equivalent to simply calling readArgs()

CheckConstraints 

whether the constraints should be checked after reading the arguments

InvokeCallbacks 

whether the callbacks should be invoked after reading the arguments and (maybe) checking the constraints

ExitOnFailure 

whether the parser should print an error message and terminate the application on failure (rather than throwing an exception)

Definition at line 77 of file argumentparser.h.

◆ Response

The Response enum is used to specify the default response for the confirmPrompt() method.

Enumerator
None 
Yes 
No 

Definition at line 18 of file commandlineutils.h.

◆ UnknownArgumentBehavior

The UnknownArgumentBehavior enum specifies the behavior of the argument parser when an unknown argument is detected.

Enumerator
Ignore 

Unknown arguments are ignored without warnings.

Warn 

A warning is printed to std::cerr if an unknown argument is detected.

Fail 

Further parsing is aborted and an ApplicationUtilities::Failure instance with an error message is thrown.

Definition at line 65 of file argumentparser.h.

◆ ValueCompletionBehavior

enum ApplicationUtilities::ValueCompletionBehavior : unsigned char
strong

The ValueCompletionBehavior enum specifies the items to be considered when generating completion for an argument value.

Remarks
Enumerator
None 

no auto-completion

PreDefinedValues 

values assigned with Argument::setPreDefinedCompletionValues()

Files 

files

Directories 

directories

FileSystemIfNoPreDefinedValues 

files and directories but only if no values have been assigned (default behavior)

AppendEquationSign 

an equation sign is appended to values which not contain an equation sign already

InvokeCallback 

whether to invoke the callback before reading pre-defined values

Definition at line 106 of file argumentparser.h.

Function Documentation

◆ compareArgs()

bool ApplicationUtilities::compareArgs ( const Argument arg1,
const Argument arg2 
)

Returns whether arg1 should be listed before arg2 when printing completion.

Arguments are sorted by name (ascending order). However, all arguments denoting an operation are listed before all other arguments.

Definition at line 1069 of file argumentparser.cpp.

◆ confirmPrompt()

bool ApplicationUtilities::confirmPrompt ( const char *  message,
Response  defaultResponse = Response::None 
)

Prompts for confirmation displaying the specified message.

Definition at line 21 of file commandlineutils.cpp.

◆ determineTerminalSize()

TerminalSize ApplicationUtilities::determineTerminalSize ( )

Returns the current size of the terminal.

Remarks
Unknown members of the returned TerminalSize are set to zero.

Definition at line 46 of file commandlineutils.cpp.

◆ firstPresentUncombinableArg()

Argument * ApplicationUtilities::firstPresentUncombinableArg ( const ArgumentVector args,
const Argument except 
)

This function return the first present and uncombinable argument of the given list of arguments.

The Argument except will be ignored.

Definition at line 560 of file argumentparser.cpp.

◆ insertSiblings()

void ApplicationUtilities::insertSiblings ( const ArgumentVector siblings,
list< const Argument * > &  target 
)

Inserts the specified siblings in the target list.

Remarks
Only inserts siblings which could still occur at least once more.

Definition at line 1084 of file argumentparser.cpp.

◆ operator<<() [1/3]

std::ostream & ApplicationUtilities::operator<< ( std::ostream &  o,
const Failure failure 
)

Prints an error message "Unable to parse arguments: ..." for the specified failure.

Definition at line 52 of file failure.cpp.

◆ operator<<() [2/3]

ostream & ApplicationUtilities::operator<< ( std::ostream &  os,
const Wrapper wrapper 
)

Definition at line 374 of file argumentparser.cpp.

◆ operator<<() [3/3]

CPP_UTILITIES_EXPORT std::ostream& ApplicationUtilities::operator<< ( std::ostream &  out,
Indentation  indentation 
)
inline

Definition at line 83 of file commandlineutils.h.

Variable Documentation

◆ applicationAuthor

const char * ApplicationUtilities::applicationAuthor = nullptr

Specifies the author of the application (used by ArgumentParser::printHelp()).

Definition at line 406 of file argumentparser.cpp.

◆ applicationName

const char * ApplicationUtilities::applicationName = nullptr

Specifies the name of the application (used by ArgumentParser::printHelp()).

Definition at line 404 of file argumentparser.cpp.

◆ applicationUrl

const char * ApplicationUtilities::applicationUrl = nullptr

Specifies the URL to the application website (used by ArgumentParser::printHelp()).

Definition at line 410 of file argumentparser.cpp.

◆ applicationVersion

const char * ApplicationUtilities::applicationVersion = nullptr

Specifies the version of the application (used by ArgumentParser::printHelp()).

Definition at line 408 of file argumentparser.cpp.

◆ dependencyVersions

std::initializer_list< const char * > ApplicationUtilities::dependencyVersions

Specifies the dependency versions the application was linked against (used by ArgumentParser::printHelp()).

Deprecated:
Not used anymore. Use dependencyVersions2 instead.

Definition at line 413 of file argumentparser.cpp.

◆ dependencyVersions2

std::vector< const char * > ApplicationUtilities::dependencyVersions2

Specifies the dependency versions the application was linked against (used by ArgumentParser::printHelp()).

Definition at line 415 of file argumentparser.cpp.

◆ exitFunction

void(* ApplicationUtilities::exitFunction)(int) = &exit

Specifies a function quit the application.

Remarks
Currently only used after printing Bash completion. Default is std::exit().

Definition at line 423 of file argumentparser.cpp.