TSDuck Version 3.16-1064 (TSDuck - The MPEG Transport Stream Toolkit)
ts::Args Class Reference

An encapsulation of command line syntax and analysis. More...

Inheritance diagram for ts::Args:
Collaboration diagram for ts::Args:

Classes

class  ArgsError
 Internal application error in command line argument handling. More...
 

Public Types

enum  ArgType {
  NONE,
  STRING,
  INTEGER,
  UNSIGNED,
  POSITIVE,
  UINT8,
  UINT16,
  UINT32,
  PIDVAL,
  INT8,
  INT16,
  INT32,
  TRISTATE
}
 Type of an argument or parameter. More...
 
enum  Flags {
  NO_ERROR_DISPLAY = 0x0001,
  NO_EXIT_ON_ERROR = 0x0002,
  NO_EXIT_ON_HELP = 0x0004,
  NO_EXIT_ON_VERSION = 0x0008,
  GATHER_PARAMETERS = 0x0010,
  HELP_ON_THIS = 0x0020,
  NO_DEBUG = 0x0040,
  NO_HELP = 0x0080,
  NO_VERBOSE = 0x0100,
  NO_VERSION = 0x0200,
  NO_CONFIG_FILE = 0x0400
}
 Args object flags, used in an or'ed mask. More...
 
enum  HelpFormat {
  HELP_NAME,
  HELP_DESCRIPTION,
  HELP_USAGE,
  HELP_SYNTAX,
  HELP_FULL
}
 Types of help formatting, for getHelpText() and predefined option --help. More...
 

Public Member Functions

 Args (const UString &description=UString(), const UString &syntax=UString(), int flags=0)
 Constructor. More...
 
virtual bool analyze (int argc, char *argv[], bool processRedirections=true)
 Load command arguments and analyze them. More...
 
virtual bool analyze (const UString &app_name, const UStringVector &arguments, bool processRedirections=true)
 Load command arguments and analyze them. More...
 
UString appName () const
 Get the application name from the last command line analysis. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT bitMaskValue (const UChar *name=nullptr, const INT &def_value=static_cast< INT >(0)) const
 Get an OR'ed of all values of an integer option in the last analyzed command line. More...
 
ArgscopyOptions (const Args &other, const bool replace=false)
 Copy all option definitions from another Args object into this one. More...
 
size_t count (const UChar *name=nullptr) const
 Check the number of occurences of an option in the last analyzed command line. More...
 
bool debug () const
 Check if debugging is active. More...
 
void debug (const UString &msg)
 Report a debug message. More...
 
void debug (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a debug message with a printf-like interface. More...
 
void debug (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a debug message with a printf-like interface. More...
 
template<typename ENUM >
ENUM enumValue (const UChar *name=nullptr, ENUM def_value=static_cast< ENUM >(0), size_t index=0) const
 Get the value of an enum option in the last analyzed command line. More...
 
void error (const UString &msg)
 Report an error message. More...
 
void error (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report an error message with a printf-like interface. More...
 
void error (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report an error message with a printf-like interface. More...
 
void exitOnError (bool force=false)
 Exit application when errors were reported in the last analyzed command line. More...
 
void fatal (const UString &msg)
 Report a fatal error message. More...
 
void fatal (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a fatal error message with a printf-like interface. More...
 
void fatal (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a fatal error message with a printf-like interface. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void getBitMaskValue (INT &value, const UChar *name=nullptr, const INT &def_value=static_cast< INT >(0)) const
 Get an OR'ed of all values of an integer option in the last analyzed command line. More...
 
const UStringgetDescription () const
 Get the description of the command. More...
 
template<typename ENUM >
void getEnumValue (ENUM &value, const UChar *name=nullptr, ENUM def_value=static_cast< ENUM >(0), size_t index=0) const
 Get the value of an enum option in the last analyzed command line. More...
 
int getFlags () const
 Get the option flags of the command. More...
 
UString getHelpText (HelpFormat format, size_t line_width=79) const
 Get a formatted help text. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void getIntValue (INT &value, const UChar *name=nullptr, const INT &def_value=static_cast< INT >(0), size_t index=0) const
 Get the value of an integer option in the last analyzed command line. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void getIntValues (std::vector< INT > &values, const UChar *name=nullptr) const
 Get all occurences of an integer option in a vector of integers. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void getIntValues (std::set< INT > &values, const UChar *name=nullptr) const
 Get all occurences of an integer option in a set of integers. More...
 
template<std::size_t N>
void getIntValues (std::bitset< N > &values, const UChar *name=nullptr, bool defValue=false) const
 Get all occurences of an option as a bitmask of values. More...
 
const UStringgetShell () const
 Get the "shell" string. More...
 
const UStringgetSyntax () const
 Get the syntax of the command. More...
 
void getTristateValue (Tristate &value, const UChar *name=nullptr, size_t index=0) const
 Get the value of tristate option in the last analyzed command line. More...
 
void getValue (UString &value, const UChar *name=nullptr, const UChar *def_value=u"", size_t index=0) const
 Get the value of an option in the last analyzed command line. More...
 
void getValues (UStringVector &values, const UChar *name=nullptr) const
 Get all occurences of an option in a container of strings. More...
 
Argshelp (const UChar *name, const UString &syntax, const UString &text)
 Add the help text of an exiting option. More...
 
Argshelp (const UChar *name, const UString &text)
 Add the help text of an exiting option. More...
 
void info (const UString &msg)
 Report an informational message. More...
 
void info (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report an informational message with a printf-like interface. More...
 
void info (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report an informational message with a printf-like interface. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT intValue (const UChar *name=nullptr, const INT &def_value=static_cast< INT >(0), size_t index=0) const
 Get the value of an integer option in the last analyzed command line. More...
 
void invalidate ()
 Force en error state in this object, as if an error was reported.
 
virtual void log (int severity, const UString &msg)
 Report a message with an explicit severity. More...
 
virtual void log (int severity, const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a message with an explicit severity and a printf-like interface. More...
 
virtual void log (int severity, const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a message with an explicit severity and a printf-like interface. More...
 
int maxSeverity () const
 Get maximum severity level. More...
 
Argsoption (const UChar *name=nullptr, UChar short_name=0, ArgType type=NONE, size_t min_occur=0, size_t max_occur=0, int64_t min_value=0, int64_t max_value=0, bool optional=false)
 Add the definition of an option. More...
 
Argsoption (const UChar *name, UChar short_name, const Enumeration &enumeration, size_t min_occur=0, size_t max_occur=0, bool optional=false)
 Add the definition of an option, the value being from an enumeration type. More...
 
UString optionNames (const UChar *name, const UString &separator=u", ") const
 When an option has an Enumeration type, get a list of all valid names. More...
 
bool present (const UChar *name=nullptr) const
 Check if an option is present in the last analyzed command line. More...
 
bool processArgsRedirection (UStringVector &args)
 Process argument redirection using '@' on a vector of strings. More...
 
virtual void raiseMaxSeverity (int level) override
 Raise maximum severity level. More...
 
void redirectReport (Report *report)
 Redirect report logging. More...
 
virtual void setDescription (const UString &description)
 Set the description of the command. More...
 
virtual void setFlags (int flags)
 Set the option flags of the command. More...
 
virtual void setIntro (const UString &intro)
 Set the introduction or preamble text for help description. More...
 
virtual void setMaxSeverity (int level)
 Set maximum severity level. More...
 
void setShell (const UString &shell)
 Set the "shell" string. More...
 
virtual void setSyntax (const UString &syntax)
 Set the syntax of the command. More...
 
void severe (const UString &msg)
 Report a severe error message. More...
 
void severe (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a severe error message with a printf-like interface. More...
 
void severe (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a severe error message with a printf-like interface. More...
 
Tristate tristateValue (const UChar *name=nullptr, size_t index=0) const
 Get the value of tristate option in the last analyzed command line. More...
 
bool valid () const
 Check if options were correct during the last command line analysis. More...
 
UString value (const UChar *name=nullptr, const UChar *def_value=u"", size_t index=0) const
 Get the value of an option in the last analyzed command line. More...
 
bool verbose () const
 Check if verbose reporting is active. More...
 
void verbose (const UString &msg)
 Report a verbose message. More...
 
void verbose (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a verbose message with a printf-like interface. More...
 
void verbose (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a verbose message with a printf-like interface. More...
 
void warning (const UString &msg)
 Report a warning message. More...
 
void warning (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Report a warning message with a printf-like interface. More...
 
void warning (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Report a warning message with a printf-like interface. More...
 

Static Public Attributes

static const Enumeration HelpFormatEnum
 Enumeration description of HelpFormat. More...
 
static const size_t UNLIMITED_COUNT
 Unlimited number of occurences. More...
 
static const int64_t UNLIMITED_VALUE
 Unlimited value. More...
 

Protected Member Functions

virtual void writeLog (int severity, const UString &message) override
 Actual message reporting method. More...
 

Protected Attributes

volatile int _max_severity
 Debug level is accessible to subclasses.
 

Detailed Description

An encapsulation of command line syntax and analysis.

The various properties of a command line (an instance of this class) are:

  • The "description" string: A short one-line description, e.g. "Wonderful File Copier".
  • The "syntax" string: A short one-line syntax summary, e.g. "[options] filename ...".

Parameters and options

The syntax of a command line which is analyzed by this class follows the GNU getopt_long(3) conventions. See the corresponding Linux manual page for details.

In short, this means that all options have a "long name" preceded by a double dash and optionally a short name (one dash, one letter). Long options can be abbreviated if there is no ambiguity. Although this syntax is inspired by Linux and the GNU utilities, the same syntax is used in all environments where this class is compiled.

As an example, consider a utility which accepts the two options --verbose (short name -­v) and --version (no short name). Then, the verbose mode can be equally triggered by ­-v, --verbose, --verb but not --ver since there an ambiguity with --version.

The various options are declared using an option() method. An option can be declared with a mandatory value (e.g. –output file.txt), without value (e.g. --verbose) or with an optional value.

The options may be specified on the command line in any order. Everything which is not an option (or the value of an option) is considered as a parameter. The syntax of the parameters is declared using an option() method with an empty option name.

When an option is declared with a mandatory value, two syntaxes are accepted: an optional value, only the second form is possible, e.g. –debug=2. The form –debug 2 is considered as option --debug without value(it is optional) followed by parameter 2.

Following the GNU convention, when the short one-letter form of an option is used, the value may immediately follow the option without space.

If the option –output has a short form -o, all the following forms are equivalent:

  • --output file.txt
  • --output=file.txt
  • -o file.txt
  • -ofile.txt

Predefined options

Some options are always predefined and do not need to be redefined using a call to option().

  • --help : displays the help text and terminates the application.
  • --version : displays the TSDuck version and terminates the application.
  • --verbose or -v : sets the reporting level to verbose.
  • --debug or -d : sets the reporting level to debug. This option accepts an optional positive number, the debug level. The default debug level is 1. The higher the level is, the more information is logged.

The short names -v and -d are mapped by default to --verbose and --debug respectively, unless an application-defined option reuses them.

Command line argument type

The value of options and parameters are typed using ArgType.

For integer values, the minimum and maximum allowed values are specified and the actual values for the command line are checked for valid integer values. The integer values can be entered in decimal or hexadecimal (using the 0x prefix). The comma, dot and space characters are considered as possible "thousands separators" and are ignored.

Error management

There are several types of error situations:

  • Internal coding errors: These errors are internal inconsistencies of the application. Examples include declaring an option with an integer value in the range 1..0 (min > max) or fetching the state of option "foo" when no such option has been declared in the syntax of the command. These errors are bugs in the application and are reported with severity ts::Severity::Fatal. If the declared log does not terminate the application on fatal errors, a default "void" processing is then applied, depending on the situation.
  • Command line errors: They are user errors, when the user enters an incorrect command. These errors are reported with severity ts::Severity::Error. In the various analyze() methods, after the command line is completely analyzed and all command line errors reported, the application is terminated.
  • Predefined help or version options: This is triggered when the user enters the --help or --version option. This is not really an error but the command is not usable. In this case, the help text is displayed and the command is terminated.

When the flag NO_EXIT_ON_ERROR is specified, command line errors and predefined help or version options do not terminate the application. Instead, the analyze() method returns false.

By default, error messages on the standard error device and terminates the application on fatal errors. Any user-defined subclass of ts::Report can be used to report errors. See the method redirectReport(). To drop all messages, simply use an instance of ts::NullReport, typically NULLREP.

Sample code

The following sample application, a "super file merger" illustrates a typical usage of the Args class.

#include "tsArgs.h"
#include <iostream>
// Define a class which encapsulates the command line arguments.
class CommandArgs: public ts::Args
{
public:
CommandArgs(int argc, char *argv[]);
ts::UString inFile1;
ts::UString inFile2;
ts::UString outFile;
bool force;
size_t bufferSize;
};
// Constructor: define the command syntax and analyze the command line.
CommandArgs::CommandArgs(int argc, char *argv[]) :
ts::Args(u"Super file merger", u"[options] file-1 [file-2]")
{
// Define the syntax of the command
option(u"", 0, STRING, 1, 2);
help(u"", u"file-1 : Base file to merge.\nfile-2 : Optional secondary file to merge.");
option(u"buffer-size", u'b', INTEGER, 0, 1, 256, 4096);
help(u"buffer-size", u"Buffer size in bytes, from 256 to 4096 bytes (default: 1024).");
option(u"output", u'o', STRING);
help(u"output", u"Specify the output file (default: standard output).");
option(u"force", u'f');
help(u"force", u"Force overwriting the output file if it already exists.");
// Analyze the command
analyze(argc, argv);
// Get the command line arguments
getValue(inFile1, u"", u"", 0);
getValue(inFile2, u"", u"", 1);
getValue(outFile, u"output");
force = present(u"force");
bufferSize = intValue<size_t>(u"buffer-size", 1024);
}
// Main program
int main(int argc, char* argv[])
{
// Declare an object which analyzes the command line.
CommandArgs args(argc, argv);
std::cout
<< "inFile1 = \"" << args.inFile1 << "\", "
<< "inFile2 = \"" << args.inFile2 << "\", "
<< "outFile = \"" << args.outFile << "\", "
<< "force = " << ts::UString::TrueFalse(args.force) << ", "
<< "bufferSize = " << args.bufferSize << std::endl;
return EXIT_SUCCESS;
}

The following command illustrates the predefined --help option:

$ supermerge --help
Super file merger
Usage: supermerge [options] file-1 [file-2]
Parameters:
file-1 : Base file to merge.
file-2 : Optional secondary file to merge.
Options:
-b value
--buffer-size value
Buffer size in bytes, from 256 to 4096 bytes (default: 1024).
-d[level]
--debug[=level]
Produce debug traces. The default level is 1. Higher levels produce more
messages.
-f
--force
Force overwriting the output file if it already exists.
--help
Display this help text.
-o filename
--output filename
Specify the output file (default: standard output).
-v
Produce verbose output.
--version
Display the TSDuck version number.
$

And the following commands illustrate various usages of the command:

$ supermerge f1
inFile1 = "f1", inFile2 = "", outFile = "", force = false, bufferSize = 1024
$
$ supermerge f1 f2
inFile1 = "f1", inFile2 = "f2", outFile = "", force = false, bufferSize = 1024
$
$ supermerge f1 f2 f3
supermerge: too many parameter, 2 maximum
$
$ supermerge f1 -o out.txt -f
inFile1 = "f1", inFile2 = "", outFile = "out.txt", force = true, bufferSize = 1024
$
$ supermerge f1 -o out.txt -f --buffer-size 2048
inFile1 = "f1", inFile2 = "", outFile = "out.txt", force = true, bufferSize = 2048
$
$ supermerge f1 -o out.txt --ver
supermerge: ambiguous option --ver (--verbose, --version)
$
$ supermerge f1 -o out.txt --verb
inFile1 = "f1", inFile2 = "", outFile = "out.txt", force = false, bufferSize = 1024
$

Member Enumeration Documentation

◆ Flags

Args object flags, used in an or'ed mask.

Enumerator
NO_ERROR_DISPLAY 

Don't display errors.

NO_EXIT_ON_ERROR 

Don't terminate application on error.

NO_EXIT_ON_HELP 

Don't terminate application on --help.

NO_EXIT_ON_VERSION 

Don't terminate application on --version.

GATHER_PARAMETERS 

Specifies that all options must be placed before the parameters.

Once the first parameter is found, all subsequent elements on the command line are considered as parameters, even if they start with '-' or '--'.

HELP_ON_THIS 

Display help using info() on this object, not standard error.

NO_DEBUG 

No predefined option "--debug".

NO_HELP 

No predefined option "--help".

NO_VERBOSE 

No predefined option "--verbose".

NO_VERSION 

No predefined option "--version".

NO_CONFIG_FILE 

No default option from the configuration file.

◆ ArgType

Type of an argument or parameter.

Enumerator
NONE 

Option without argument.

STRING 

Uninterpreted string argument.

INTEGER 

Integer argument, must set min & max values.

UNSIGNED 

Integer 0..unlimited.

POSITIVE 

Integer 1..unlimited.

UINT8 

Integer 0..0xFF.

UINT16 

Integer 0..0xFFFF.

UINT32 

Integer 0..0xFFFFFFFF.

PIDVAL 

Integer 0..0x1FFF (an MPEG PID value).

INT8 

Integer -128..127.

INT16 

Integer -32,768..32,767.

INT32 

Integer -2,147,483,648..2,147,483,647.

TRISTATE 

Tristate value, ts::MAYBE if absent.

◆ HelpFormat

Types of help formatting, for getHelpText() and predefined option --help.

Enumerator
HELP_NAME 

Application name only.

HELP_DESCRIPTION 

One-line description.

HELP_USAGE 

Formatted command line syntax.

HELP_SYNTAX 

One-line command line syntax.

HELP_FULL 

Full help text.

Constructor & Destructor Documentation

◆ Args()

ts::Args::Args ( const UString description = UString(),
const UString syntax = UString(),
int  flags = 0 
)

Constructor.

Parameters
[in]descriptionA short one-line description, eg. "Wonderful File Copier".
[in]syntaxA short one-line syntax summary, eg. "[options] filename ...".
[in]flagsAn or'ed mask of Flags values.

Member Function Documentation

◆ option() [1/2]

Args& ts::Args::option ( const UChar name = nullptr,
UChar  short_name = 0,
ArgType  type = NONE,
size_t  min_occur = 0,
size_t  max_occur = 0,
int64_t  min_value = 0,
int64_t  max_value = 0,
bool  optional = false 
)

Add the definition of an option.

This method is typically invoked in the constructor of a subclass.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]short_nameOptional one letter short name.
[in]typeOption or parameter value type.
[in]min_occurMinimum number of occurences of this option on the command line.
[in]max_occurMaximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]min_valueMinimum value, ignored if type is not INTEGER.
[in]max_valueMaximum value, ignored if type is not INTEGER.
[in]optionalWhen true, the option's value is optional.
Returns
A reference to this instance.

◆ option() [2/2]

Args& ts::Args::option ( const UChar name,
UChar  short_name,
const Enumeration enumeration,
size_t  min_occur = 0,
size_t  max_occur = 0,
bool  optional = false 
)

Add the definition of an option, the value being from an enumeration type.

This method is typically invoked in the constructor of a subclass.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]short_nameOptional one letter short name.
[in]enumerationList of enumeration values. The command line parameter value can be a string describing an enumeration value or directly an integer value. In the application, the option's value is always the integer value of the enumeration value.
[in]min_occurMinimum number of occurences of this option on the command line.
[in]max_occurMaximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]optionalWhen true, the option's value is optional.
Returns
A reference to this instance.

◆ help() [1/2]

Args& ts::Args::help ( const UChar name,
const UString syntax,
const UString text 
)

Add the help text of an exiting option.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]syntaxString to display for the option value instead of the default "value". For instance: "address:port" "'string'".
[in]textHelp text. Unformatted, line breaks will be added automatically.
Returns
A reference to this instance.

◆ help() [2/2]

Args& ts::Args::help ( const UChar name,
const UString text 
)

Add the help text of an exiting option.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]textHelp text. Unformatted, line breaks will be added automatically.
Returns
A reference to this instance.

◆ optionNames()

UString ts::Args::optionNames ( const UChar name,
const UString separator = u", " 
) const

When an option has an Enumeration type, get a list of all valid names.

Parameters
[in]nameLong name of option. 0 or "" means a parameter, not an option.
[in]separatorThe separator to be used between values, a comma by default.
Returns
A comma-separated list of all possible names.
See also
Enumeration::nameList()

◆ copyOptions()

Args& ts::Args::copyOptions ( const Args other,
const bool  replace = false 
)

Copy all option definitions from another Args object into this one.

This method is typically invoked in the constructor of a subclass to import all option definitions of another instance.

Parameters
[in]otherAnother instance from which to get the options.
[in]replaceIf true, override duplicated options which were already declared in this object. If false (the default), duplicated options are ignored.
Returns
A reference to this object.

◆ setDescription()

virtual void ts::Args::setDescription ( const UString description)
inlinevirtual

Set the description of the command.

Parameters
[in]descriptionA short one-line description, e.g. "Wonderful File Copier".

◆ setSyntax()

virtual void ts::Args::setSyntax ( const UString syntax)
inlinevirtual

Set the syntax of the command.

Parameters
[in]syntaxA short one-line syntax summary, e.g. "[options] filename ...".

◆ setIntro()

virtual void ts::Args::setIntro ( const UString intro)
inlinevirtual

Set the introduction or preamble text for help description.

Parameters
[in]introIntroduction text.

◆ setFlags()

virtual void ts::Args::setFlags ( int  flags)
inlinevirtual

Set the option flags of the command.

Parameters
[in]flagsDefine various options, a combination of or'ed values from Flags.

◆ getDescription()

const UString& ts::Args::getDescription ( ) const
inline

Get the description of the command.

Returns
A short one-line description of the command.

◆ getSyntax()

const UString& ts::Args::getSyntax ( ) const
inline

Get the syntax of the command.

Returns
A short one-line syntax summary of the command.

◆ getFlags()

int ts::Args::getFlags ( ) const
inline

Get the option flags of the command.

Returns
A combination of or'ed values from Flags.

◆ getHelpText()

UString ts::Args::getHelpText ( HelpFormat  format,
size_t  line_width = 79 
) const

Get a formatted help text.

Parameters
[in]formatRequested format of the help text.
[in]line_widthMaximum width of text lines.
Returns
The formatted help text.

◆ setShell()

void ts::Args::setShell ( const UString shell)
inline

Set the "shell" string.

The shell string is an optional prefix for the syntax line as displayed by the --help predefined option. The shell name is displayed before the application name.

Parameters
[in]shellShell name string.

◆ getShell()

const UString& ts::Args::getShell ( ) const
inline

Get the "shell" string.

Returns
The shell name string.
See also
setShell()

◆ analyze() [1/2]

virtual bool ts::Args::analyze ( int  argc,
char *  argv[],
bool  processRedirections = true 
)
virtual

Load command arguments and analyze them.

Normally, in case of error or if --help or --version is specified, the application is automatically terminated. If some flags prevent the termination of the application, return true if the command is correct, false if the command is incorrect or --help or --version is specified.

Parameters
[in]argcNumber of arguments from command line.
[in]argvArguments from command line. The application name is in argv[0]. The subsequent elements contain the arguments.
[in]processRedirectionsIf true (the default), process command line arguments redirection. All lines with the form '@filename' are replaced by the content of filename.
Returns
By default, always return true or the application is automatically terminated in case of error. If some flags prevent the termination of the application, return true if the command is correct, false if the command is incorrect or --help or --version is specified.

Reimplemented in ts::ArgsWithPlugins.

◆ analyze() [2/2]

virtual bool ts::Args::analyze ( const UString app_name,
const UStringVector arguments,
bool  processRedirections = true 
)
virtual

Load command arguments and analyze them.

Normally, in case of error or if --help or --version is specified, the application is automatically terminated. If some flags prevent the termination of the application, return true if the command is correct, false if the command is incorrect or --help or --version is specified.

Parameters
[in]app_nameApplication name.
[in]argumentsArguments from command line.
[in]processRedirectionsIf true (the default), process command line arguments redirection. All lines with the form '@filename' are replaced by the content of filename.
Returns
By default, always return true or the application is automatically terminated in case of error. If some flags prevent the termination of the application, return true if the command is correct, false if the command is incorrect or --help or --version is specified.

Reimplemented in ts::ArgsWithPlugins.

◆ valid()

bool ts::Args::valid ( ) const
inline

Check if options were correct during the last command line analysis.

Returns
True if the last analyze() completed successfully.

◆ appName()

UString ts::Args::appName ( ) const
inline

Get the application name from the last command line analysis.

Returns
The application name from the last command line analysis.

◆ present()

bool ts::Args::present ( const UChar name = nullptr) const

Check if an option is present in the last analyzed command line.

Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
Returns
True if the corresponding option or parameter is present on the command line, false otherwise.

◆ count()

size_t ts::Args::count ( const UChar name = nullptr) const

Check the number of occurences of an option in the last analyzed command line.

Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
Returns
The number of occurences of the corresponding option or parameter in the command line.

◆ getValue()

void ts::Args::getValue ( UString value,
const UChar name = nullptr,
const UChar def_value = u"",
size_t  index = 0 
) const

Get the value of an option in the last analyzed command line.

Parameters
[out]valueA string receiving the value of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
[in]def_valueThe string to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.

◆ value()

UString ts::Args::value ( const UChar name = nullptr,
const UChar def_value = u"",
size_t  index = 0 
) const

Get the value of an option in the last analyzed command line.

Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
[in]def_valueThe string to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.
Returns
The value of the option or parameter.

◆ getValues()

void ts::Args::getValues ( UStringVector values,
const UChar name = nullptr 
) const

Get all occurences of an option in a container of strings.

Parameters
[out]valuesA container of strings receiving all values of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.

◆ getIntValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::Args::getIntValue ( INT value,
const UChar name = nullptr,
const INT def_value = static_cast< INT >(0),
size_t  index = 0 
) const

Get the value of an integer option in the last analyzed command line.

If the option has been declared with an integer type in the syntax of the command, the validity of the supplied option value has been checked by the analyze() method. If analyze() did not fail, the option value is guaranteed to be in the declared range.

Template Parameters
INTAn integer type for the result.
Parameters
[out]valueA variable receiving the integer value of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.

◆ intValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT ts::Args::intValue ( const UChar name = nullptr,
const INT def_value = static_cast< INT >(0),
size_t  index = 0 
) const

Get the value of an integer option in the last analyzed command line.

Template Parameters
INTAn integer type for the result.
Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.
Returns
The integer value of the option or parameter.

◆ getIntValues() [1/3]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::Args::getIntValues ( std::vector< INT > &  values,
const UChar name = nullptr 
) const

Get all occurences of an integer option in a vector of integers.

Parameters
[out]valuesA container of integers receiving all values of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.

◆ getIntValues() [2/3]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::Args::getIntValues ( std::set< INT > &  values,
const UChar name = nullptr 
) const

Get all occurences of an integer option in a set of integers.

Parameters
[out]valuesA container of integers receiving all values of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.

◆ getIntValues() [3/3]

template<std::size_t N>
void ts::Args::getIntValues ( std::bitset< N > &  values,
const UChar name = nullptr,
bool  defValue = false 
) const

Get all occurences of an option as a bitmask of values.

Parameters
[out]valuesA bitset receiving all values of the option or parameter. For each value of the option, the corresponding bit is set. Values which are out of range are ignored.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command, a fatal error is reported.
[in]defValueThe boolean to set in all values if the option or parameter is not present in the command line.

◆ bitMaskValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
INT ts::Args::bitMaskValue ( const UChar name = nullptr,
const INT def_value = static_cast< INT >(0) 
) const

Get an OR'ed of all values of an integer option in the last analyzed command line.

This method is typically useful when the values of an option are taken from an Enumeration and each value is a bit mask. When specifying several values, the result of this method is a mask of all specified options.

Template Parameters
INTAn integer type for the result.
Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return in value if the option or parameter is not present in the command line.
Returns
The OR'ed values of the integer option.

◆ getBitMaskValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::Args::getBitMaskValue ( INT value,
const UChar name = nullptr,
const INT def_value = static_cast< INT >(0) 
) const

Get an OR'ed of all values of an integer option in the last analyzed command line.

This method is typically useful when the values of an option are taken from an Enumeration and each value is a bit mask. When specifying several values, the result of this method is a mask of all specified options.

Template Parameters
INTAn integer type for the result.
Parameters
[out]valueA variable receiving the OR'ed values of the integer option.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return in value if the option or parameter is not present in the command line.

◆ getEnumValue()

template<typename ENUM >
void ts::Args::getEnumValue ( ENUM &  value,
const UChar name = nullptr,
ENUM  def_value = static_cast< ENUM >(0),
size_t  index = 0 
) const

Get the value of an enum option in the last analyzed command line.

Typically used when the option was declared using an Enumeration object.

Template Parameters
ENUMAn enumeration type for the result.
Parameters
[out]valueA variable receiving the enum value of the option or parameter.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.

◆ enumValue()

template<typename ENUM >
ENUM ts::Args::enumValue ( const UChar name = nullptr,
ENUM  def_value = static_cast< ENUM >(0),
size_t  index = 0 
) const

Get the value of an enum option in the last analyzed command line.

Typically used when the option was declared using an Enumeration object.

Template Parameters
ENUMAn enumeration type for the result.
Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]def_valueThe value to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]indexThe occurence of the option to return. Zero designates the first occurence.
Returns
The enum value of the option or parameter.

◆ getTristateValue()

void ts::Args::getTristateValue ( Tristate value,
const UChar name = nullptr,
size_t  index = 0 
) const

Get the value of tristate option in the last analyzed command line.

Parameters
[out]valueA variable receiving the tristate value of the option or parameter. The returned value is always one of the three valid Tristate values. When the option or parameter is not present in the command line or with fewer occurences than index, the returned value is MAYBE. For options with optional values, if the the option is present without value, the returned value is TRUE.
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]indexThe occurence of the option to return. Zero designates the first occurence.

◆ tristateValue()

Tristate ts::Args::tristateValue ( const UChar name = nullptr,
size_t  index = 0 
) const

Get the value of tristate option in the last analyzed command line.

Parameters
[in]nameThe full name of the option. If the parameter is a null pointer or an empty string, this specifies a parameter, not an option. If the specified option was not declared in the syntax of the command or declared as a non-string type, a fatal error is reported.
[in]indexThe occurence of the option to return. Zero designates the first occurence.
Returns
The tristate value of the option or parameter. The returned value is always one of the three valid Tristate values. When the option or parameter is not present in the command line or with fewer occurences than index, the returned value is MAYBE. For options with optional values, if the the option is present without value, the returned value is TRUE.

◆ exitOnError()

void ts::Args::exitOnError ( bool  force = false)

Exit application when errors were reported in the last analyzed command line.

Parameters
[in]forceIf true, ignore flag NO_EXIT_ON_ERROR and force application termination on error.

◆ redirectReport()

void ts::Args::redirectReport ( Report report)

Redirect report logging.

Parameters
[in]reportWhere to report errors. The redirection is cancelled if zero.

◆ raiseMaxSeverity()

virtual void ts::Args::raiseMaxSeverity ( int  level)
overridevirtual

Raise maximum severity level.

Parameters
[in]levelSet report at least to that level.

Reimplemented from ts::Report.

◆ processArgsRedirection()

bool ts::Args::processArgsRedirection ( UStringVector args)

Process argument redirection using '@' on a vector of strings.

Parameters
[in,out]argsA vector of strings. All lines of the form '@filename' are replaced by the content of the given file. A double '@@' at the beginning of a line is replaced by a single '@' without reading a file.
Returns
True on success, false on error (non existent file for instance). Errors are reported though this object.

◆ writeLog()

virtual void ts::Args::writeLog ( int  severity,
const UString msg 
)
overrideprotectedvirtual

Actual message reporting method.

Must be implemented in actual classes. The method is called only when a message passed the severity filter. It is not necessary to recheck severity inside the method.

Parameters
[in]severityMessage severity.
[in]msgMessage text.

Implements ts::Report.

Reimplemented in ts::Plugin.

◆ setMaxSeverity()

virtual void ts::Report::setMaxSeverity ( int  level)
virtualinherited

Set maximum severity level.

Messages with higher severities are not reported.

Parameters
[in]levelSet report to that level.

◆ maxSeverity()

int ts::Report::maxSeverity ( ) const
inlineinherited

Get maximum severity level.

Returns
Current maximum debug level.

◆ debug() [1/4]

bool ts::Report::debug ( ) const
inlineinherited

Check if debugging is active.

Returns
True if current reporting level is Debug or higher.

◆ debug() [2/4]

void ts::Report::debug ( const UString msg)
inlineinherited

Report a debug message.

Parameters
[in]msgMessage text.

◆ debug() [3/4]

void ts::Report::debug ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a debug message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ debug() [4/4]

void ts::Report::debug ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a debug message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ verbose() [1/4]

bool ts::Report::verbose ( ) const
inlineinherited

Check if verbose reporting is active.

Returns
True if current reporting level is Verbose or higher.

◆ verbose() [2/4]

void ts::Report::verbose ( const UString msg)
inlineinherited

Report a verbose message.

Parameters
[in]msgMessage text.

◆ verbose() [3/4]

void ts::Report::verbose ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a verbose message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ verbose() [4/4]

void ts::Report::verbose ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a verbose message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ log() [1/3]

virtual void ts::Report::log ( int  severity,
const UString msg 
)
virtualinherited

Report a message with an explicit severity.

This method is the central reporting point. If filters the severity and drops the message if severity is higher than maxSeverity().

Subclasses should override writeLog() to implement a specific reporting device. It is not necessary to override log() unless the subclass needs to implement a different severity filtering policy.

Parameters
[in]severityMessage severity.
[in]msgMessage text.

◆ log() [2/3]

virtual void ts::Report::log ( int  severity,
const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
virtualinherited

Report a message with an explicit severity and a printf-like interface.

Parameters
[in]severityMessage severity.
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ log() [3/3]

virtual void ts::Report::log ( int  severity,
const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
virtualinherited

Report a message with an explicit severity and a printf-like interface.

Parameters
[in]severityMessage severity.
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ fatal() [1/3]

void ts::Report::fatal ( const UString msg)
inlineinherited

Report a fatal error message.

Parameters
[in]msgMessage text.

◆ fatal() [2/3]

void ts::Report::fatal ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a fatal error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ fatal() [3/3]

void ts::Report::fatal ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a fatal error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ severe() [1/3]

void ts::Report::severe ( const UString msg)
inlineinherited

Report a severe error message.

Parameters
[in]msgMessage text.

◆ severe() [2/3]

void ts::Report::severe ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a severe error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ severe() [3/3]

void ts::Report::severe ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a severe error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ error() [1/3]

void ts::Report::error ( const UString msg)
inlineinherited

Report an error message.

Parameters
[in]msgMessage text.

◆ error() [2/3]

void ts::Report::error ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report an error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ error() [3/3]

void ts::Report::error ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report an error message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ warning() [1/3]

void ts::Report::warning ( const UString msg)
inlineinherited

Report a warning message.

Parameters
[in]msgMessage text.

◆ warning() [2/3]

void ts::Report::warning ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a warning message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ warning() [3/3]

void ts::Report::warning ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report a warning message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ info() [1/3]

void ts::Report::info ( const UString msg)
inlineinherited

Report an informational message.

Parameters
[in]msgMessage text.

◆ info() [2/3]

void ts::Report::info ( const UChar fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report an informational message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

◆ info() [3/3]

void ts::Report::info ( const UString fmt,
const std::initializer_list< ArgMixIn > &  args 
)
inlineinherited

Report an informational message with a printf-like interface.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
UString::format()

Member Data Documentation

◆ UNLIMITED_COUNT

const size_t ts::Args::UNLIMITED_COUNT
static

Unlimited number of occurences.

To be used as value for parameter max_occur to indicate that there is no limit to the number of occurences of an option.

Warning: use only for max_occur (size_t ). Do not use for max_value (int64_t ) since size_t is uint64_t on 64-bit platforms.

◆ UNLIMITED_VALUE

const int64_t ts::Args::UNLIMITED_VALUE
static

Unlimited value.

To be used as value for parameter @ max_value to indicate that there is no limit to the parameter integer value.

◆ HelpFormatEnum

const Enumeration ts::Args::HelpFormatEnum
static

Enumeration description of HelpFormat.

Typically used to implement the --help command line option.


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