ts::Args Class Reference

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

#include <tsArgs.h>

Inheritance diagram for ts::Args:

Collaboration diagram for ts::Args:

Public Types
enum	ArgType {   NONE ,   STRING ,   FILENAME ,   DIRECTORY ,   HEXADATA ,   INTEGER ,   UNSIGNED ,   POSITIVE ,   UINT8 ,   UINT16 ,   UINT32 ,   UINT63 ,   PIDVAL ,   INT8 ,   INT16 ,   INT32 ,   INT64 ,   ANUMBER ,   CHRONO ,   TRISTATE ,   IPADDR ,   IPSOCKADDR ,   IPSOCKADDR_OA ,   IPSOCKADDR_OP ,   IPSOCKADDR_OAP }
	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 ,   HELP_OPTIONS }
	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.
virtual bool	analyze (const UString &app_name, const UStringVector &arguments, bool processRedirections=true)
	Load command arguments and analyze them.
virtual bool	analyze (const UString &command, bool processRedirections=true)
	Load command arguments and analyze them.
virtual bool	analyze (int argc, char *argv[], bool processRedirections=true)
	Load command arguments and analyze them.
UString	appName () const
	Get the application name from the last command line analysis.
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.
UString	commandLine () const
	Get the full command line from the last command line analysis.
Args &	copyOptions (const Args &other, const bool replace=false)
	Copy all option definitions from another Args object into this one.
size_t	count (const UChar *name=nullptr) const
	Check the number of occurences of an option in the last analyzed command line.
bool	debug () const
	Check if debugging is active.
template<class... Args>
void	debug (const UChar *fmt, Args &&... args)
	Report a debug message with a printf-like interface.
void	debug (const UChar *msg)
	Report a debug message.
template<class... Args>
void	debug (const UString &fmt, Args &&... args)
	Report a debug message with a printf-like interface.
void	debug (const UString &msg)
	Report a debug message.
Report *	delegateReport (Report *report)
	Delegate message logging to another report object.
template<class... Args>
void	error (const UChar *fmt, Args &&... args)
	Report an error message with a printf-like interface.
void	error (const UChar *msg)
	Report an error message.
template<class... Args>
void	error (const UString &fmt, Args &&... args)
	Report an error message with a printf-like interface.
void	error (const UString &msg)
	Report an error message.
void	exitOnError (bool force=false)
	Exit application when errors were reported in the last analyzed command line.
template<class... Args>
void	fatal (const UChar *fmt, Args &&... args)
	Report a fatal error message with a printf-like interface.
void	fatal (const UChar *msg)
	Report a fatal error message.
template<class... Args>
void	fatal (const UString &fmt, Args &&... args)
	Report a fatal error message with a printf-like interface.
void	fatal (const UString &msg)
	Report a fatal error message.
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.
template<class Rep , class Period >
void	getChronoValue (cn::duration< Rep, Period > &value, const UChar *name=nullptr, size_t index=0) const
	Get the value of an std::chrono::duration option in the last analyzed command line.
template<class Rep1 , class Period1 , class Rep2 , class Period2 >
void	getChronoValue (cn::duration< Rep1, Period1 > &value, const UChar *name=nullptr, const cn::duration< Rep2, Period2 > &def_value=cn::duration< Rep1, Period1 >::zero(), size_t index=0) const
	Get the value of an std::chrono::duration option in the last analyzed command line.
void	getCommandArgs (UStringVector &args) const
	Get the command line parameters from the last command line analysis.
const UString &	getDescription () const
	Get the description of the command.
int	getFlags () const
	Get the option flags of the command.
virtual UString	getHelpText (HelpFormat format, size_t line_width=DEFAULT_LINE_WIDTH) const
	Get a formatted help text.
void	getHexaValue (ByteBlock &value, const UChar *name=nullptr, const ByteBlock &def_value=ByteBlock(), size_t index=0) const
	Get the value of an hexadecimal option in the last analyzed command line.
template<typename INT , typename INT2 = INT, typename std::enable_if< std::is_integral< INT >::value||std::is_enum< INT >::value >::type * = nullptr>
void	getIntValue (INT &value, const UChar *name=nullptr, const INT2 def_value=static_cast< INT2 >(0), size_t index=0) const
	Get the value of an integer option in the last analyzed command line.
template<std::size_t N>
void	getIntValues (CompactBitSet< N > &values, const UChar *name=nullptr, bool defValue=false) const
	Get all occurences of an option as a compact bitset of values.
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 bitset of values.
template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< 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.
template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< 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.
void	getIPValue (IPv4Address &value, const UChar *name=nullptr, const IPv4Address &def_value=IPv4Address(), size_t index=0) const
	Get the value of an option as an IPv4 address in the last analyzed command line.
template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< INT >::value >::type * = nullptr>
void	getOptionalIntValue (std::optional< INT > &value, const UChar *name=nullptr, bool clear_if_absent=false) const
	Get the value of an integer option in the last analyzed command line, only if present.
void	getOptionalValue (std::optional< UString > &value, const UChar *name=nullptr, bool clear_if_absent=false) const
	Get the value of an option in the last analyzed command line, only if present.
void	getPathValue (fs::path &value, const UChar *name=nullptr, const fs::path &def_value=fs::path(), size_t index=0) const
	Get the value of a filesystem path option in the last analyzed command line.
template<class CONTAINER , typename std::enable_if< std::is_base_of< fs::path, typename CONTAINER::value_type >::value >::type * = nullptr>
void	getPathValues (CONTAINER &values, const UChar *name=nullptr) const
	Get all occurences of a filesystem path option in a container of path.
const UString &	getShell () const
	Get the "shell" string.
void	getSocketValue (IPv4SocketAddress &value, const UChar *name=nullptr, const IPv4SocketAddress &def_value=IPv4SocketAddress(), size_t index=0) const
	Get the value of an option as an IPv4 socket address in the last analyzed command line.
const UString &	getSyntax () const
	Get the syntax of the command.
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.
template<class NUMTYPE , typename INT1 , typename std::enable_if< std::is_base_of< AbstractNumber, NUMTYPE >::value &&std::is_integral< INT1 >::value, int >::type = 0>
void	getValue (NUMTYPE &value, const UChar *name, INT1 def_value, size_t index=0) const
	Get the value of an AbstractNumber option in the last analyzed command line.
template<class NUMTYPE , typename std::enable_if< std::is_base_of< AbstractNumber, NUMTYPE >::value, int >::type = 0>
void	getValue (NUMTYPE &value, const UChar *name=nullptr, const NUMTYPE &def_value=NUMTYPE(0), size_t index=0) const
	Get the value of an AbstractNumber option in the last analyzed command line.
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.
template<class CONTAINER , typename std::enable_if< std::is_base_of< UString, typename CONTAINER::value_type >::value >::type * = nullptr>
void	getValues (CONTAINER &values, const UChar *name=nullptr) const
	Get all occurences of an option in a container of strings.
bool	gotErrors () const
	Check if errors (or worse) were reported through this object.
Args &	help (const UChar *name, const UString &syntax, const UString &text)
	Add the help text of an existing option.
Args &	help (const UChar *name, const UString &text)
	Add the help text of an existing option.
ByteBlock	hexaValue (const UChar *name=nullptr, const ByteBlock &def_value=ByteBlock(), size_t index=0) const
	Get the value of an hexadecimal option in the last analyzed command line.
template<class... Args>
void	info (const UChar *fmt, Args &&... args)
	Report an informational message with a printf-like interface.
void	info (const UChar *msg)
	Report an informational message.
template<class... Args>
void	info (const UString &fmt, Args &&... args)
	Report an informational message with a printf-like interface.
void	info (const UString &msg)
	Report an informational message.
template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< 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.
void	invalidate ()
	Force en error state in this object, as if an error was reported.
IPv4Address	ipValue (const UChar *name=nullptr, const IPv4Address &def_value=IPv4Address(), size_t index=0) const
	Get the value of an option as an IPv4 address in the last analyzed command line.
template<class... Args>
void	log (int severity, const UChar *fmt, Args &&... args)
	Report a message with an explicit severity and a printf-like interface.
template<class... Args>
void	log (int severity, const UString &fmt, Args &&... args)
	Report a message with an explicit severity and a printf-like interface.
void	log (int severity, const UString &msg)
	Report a message with an explicit severity.
int	maxSeverity () const
	Get maximum severity level.
template<class NUMTYPE , typename std::enable_if< std::is_base_of< AbstractNumber, NUMTYPE >::value, int >::type = 0>
NUMTYPE	numValue (const UChar *name=nullptr, const NUMTYPE &def_value=NUMTYPE(0), size_t index=0) const
	Get the value of an AbstractNumber option in the last analyzed command line.
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.
template<class NUMTYPE , typename INT1 = int64_t, typename INT2 = int64_t, typename std::enable_if< std::is_base_of< AbstractNumber, NUMTYPE >::value &&std::is_integral< INT1 >::value &&std::is_integral< INT2 >::value, int >::type = 0>
Args &	option (const UChar *name, UChar short_name=0, size_t min_occur=0, size_t max_occur=0, INT1 min_value=std::numeric_limits< INT2 >::min(), INT2 max_value=std::numeric_limits< INT1 >::max(), bool optional=false)
	Add the definition of an option, the value being an instance of AbstractNumber.
template<class DURATION , typename std::enable_if< std::is_integral< typename DURATION::rep >::value, int >::type = 0>
Args &	option (const UChar *name, UChar short_name=0, size_t min_occur=0, size_t max_occur=0, int64_t min_value=0, int64_t max_value=std::numeric_limits< int64_t >::max(), bool optional=false)
	Add the definition of an option, the value being an instance of std::chrono::duration.
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, size_t decimals=0)
	Add the definition of an option.
UString	optionNames (const UChar *name, const UString &separator=u", ") const
	When an option has an Enumeration type, get a list of all valid names.
bool	present (const UChar *name=nullptr) const
	Check if an option is present in the last analyzed command line.
bool	processArgsRedirection (UStringVector &args)
	Process argument redirection using '@' on a vector of strings.
void	raiseMaxSeverity (int level)
	Raise maximum severity level.
UString	reportPrefix () const
	Get the current prefix to display.
void	resetErrors ()
	Reset the error indicator.
void	setAppName (const UString &name)
	Set the initial application name (will be overwritten at next command analysis).
virtual void	setDescription (const UString &description)
	Set the description of the command.
virtual void	setFlags (int flags)
	Set the option flags of the command.
virtual void	setIntro (const UString &intro)
	Set the introduction or preamble text for help description.
void	setMaxSeverity (int level)
	Set maximum severity level.
void	setReportPrefix (const UString &prefix)
	Set the prefix to display before each message.
void	setShell (const UString &shell)
	Set the "shell" string.
virtual void	setSyntax (const UString &syntax)
	Set the syntax of the command.
virtual void	setTail (const UString &tail)
	Set the conclusion or tailing text for help description.
template<class... Args>
void	severe (const UChar *fmt, Args &&... args)
	Report a severe error message with a printf-like interface.
void	severe (const UChar *msg)
	Report a severe error message.
template<class... Args>
void	severe (const UString &fmt, Args &&... args)
	Report a severe error message with a printf-like interface.
void	severe (const UString &msg)
	Report a severe error message.
IPv4SocketAddress	socketValue (const UChar *name=nullptr, const IPv4SocketAddress &def_value=IPv4SocketAddress(), size_t index=0) const
	Get the value of an option as an IPv4 socket address in the last analyzed command line.
Tristate	tristateValue (const UChar *name=nullptr, size_t index=0) const
	Get the value of tristate option in the last analyzed command line.
bool	valid () const
	Check if options were correct during the last command line analysis.
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.
bool	verbose () const
	Check if verbose reporting is active.
template<class... Args>
void	verbose (const UChar *fmt, Args &&... args)
	Report a verbose message with a printf-like interface.
void	verbose (const UChar *msg)
	Report a verbose message.
template<class... Args>
void	verbose (const UString &fmt, Args &&... args)
	Report a verbose message with a printf-like interface.
void	verbose (const UString &msg)
	Report a verbose message.
template<class... Args>
void	warning (const UChar *fmt, Args &&... args)
	Report a warning message with a printf-like interface.
void	warning (const UChar *msg)
	Report a warning error message.
template<class... Args>
void	warning (const UString &fmt, Args &&... args)
	Report a warning message with a printf-like interface.
void	warning (const UString &msg)
	Report a warning error message.

Static Public Member Functions
static UString	GetAppName (int argc, char *argv[])
	Get the application name from a standard argc/argv pair.

Static Public Attributes
static constexpr size_t	DEFAULT_LINE_WIDTH = 79
	Default line width for help texts.
static const Enumeration	HelpFormatEnum
	Enumeration description of HelpFormat.
static constexpr size_t	UNLIMITED_COUNT = std::numeric_limits<size_t>::max()
	Unlimited number of occurences.
static const int64_t	UNLIMITED_VALUE = std::numeric_limits<int64_t>::max()
	Unlimited value.

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

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 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
  --verbose
      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

enum ts::Args::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

enum ts::Args::ArgType

Type of an argument or parameter.

Enumerator
NONE	Option without argument.
STRING	Uninterpreted string argument.
FILENAME	String argument which will be interpreted as a file name.
DIRECTORY	String argument which will be interpreted as a directory name.
HEXADATA	String argument which will be interpreted as a suite of hexadecimal digits.
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.
UINT63	63-bit unsigned (cannot represent 2^63 and higher).
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.
INT64	64-bit signed.
ANUMBER	A subclass of AbstractNumber.
CHRONO	Any instantiation of std::chrono::duration.
TRISTATE	Tristate value, ts::Maybe if absent.
IPADDR	IPv4 address or host name translating to an address.
IPSOCKADDR	IPv4 socket address (or host name) and port, both are mandatory.
IPSOCKADDR_OA	IPv4 socket address (or host name) and port, address is optional.
IPSOCKADDR_OP	IPv4 socket address (or host name) and port, port is optional.
IPSOCKADDR_OAP	IPv4 socket address (or host name) and port, address and port are optional.

HelpFormat

enum ts::Args::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.
HELP_OPTIONS	Options names, one by line.

Constructor & Destructor Documentation

Args()

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

Constructor.

Parameters

[in]	description	A short one-line description, eg. "Wonderful File Copier".
[in]	syntax	A short one-line syntax summary, eg. "[options] filename ...".
[in]	flags	An or'ed mask of Flags values.

Member Function Documentation

option() [1/4]

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, size_t  decimals = 0  )

inline

Add the definition of an option.

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

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	short_name	Optional one letter short name.
[in]	type	Option or parameter value type.
[in]	min_occur	Minimum number of occurences of this option on the command line, ignored if type is NONE.
[in]	max_occur	Maximum number of occurences, ignored if type is NONE, 0 means default (1 for an option, unlimited for a parameters).
[in]	min_value	Minimum value for integer, minimum size for string and hexa data.
[in]	max_value	Maximum value for integer, maximum size for string and hexa data.
[in]	optional	When true, the option's value is optional.
[in]	decimals	Reference number of decimal digits. When decimals is greater than zero, the result is automatically adjusted by the corresponding power of ten. For instance, when decimals is 3, u"12" returns 12000, u"12.34" returns 12340 and "12.345678" returns 12345. All extra decimals are accepted but ignored.

Returns

A reference to this instance.

option() [2/4]

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  )

inline

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]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	short_name	Optional one letter short name.
[in]	enumeration	List 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_occur	Minimum number of occurences of this option on the command line.
[in]	max_occur	Maximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]	optional	When true, the option's value is optional.

Returns

A reference to this instance.

option() [3/4]

template<class NUMTYPE , typename INT1 = int64_t, typename INT2 = int64_t, typename std::enable_if< std::is_base_of< AbstractNumber, NUMTYPE >::value &&std::is_integral< INT1 >::value &&std::is_integral< INT2 >::value, int >::type = 0>

Args & ts::Args::option ( const UChar *  name, UChar  short_name = 0, size_t  min_occur = 0, size_t  max_occur = 0, INT1  min_value = std::numeric_limits<INT2>::min(), INT2  max_value = std::numeric_limits<INT1>::max(), bool  optional = false  )

inline

Add the definition of an option, the value being an instance of AbstractNumber.

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

Template Parameters

NUMTYPE

A subclass of AbstractNumber.

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	short_name	Optional one letter short name.
[in]	min_occur	Minimum number of occurences of this option on the command line.
[in]	max_occur	Maximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]	min_value	Minimum value. Use an integer value, not a NUMTYPE value.
[in]	max_value	Maximum value. Use an integer value, not a NUMTYPE value
[in]	optional	When true, the option's value is optional.

Returns

A reference to this instance.

option() [4/4]

template<class DURATION , typename std::enable_if< std::is_integral< typename DURATION::rep >::value, int >::type = 0>

Args & ts::Args::option ( const UChar *  name, UChar  short_name = 0, size_t  min_occur = 0, size_t  max_occur = 0, int64_t  min_value = 0, int64_t  max_value = std::numeric_limits<int64_t>::max(), bool  optional = false  )

inline

Add the definition of an option, the value being an instance of std::chrono::duration.

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

Template Parameters

DURATION

An instance of std::chrono::duration.

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	short_name	Optional one letter short name.
[in]	min_occur	Minimum number of occurences of this option on the command line.
[in]	max_occur	Maximum number of occurences. 0 means default : 1 for an option, unlimited for a parameters.
[in]	min_value	Minimum value. Use an integer value, not a DURATION value.
[in]	max_value	Maximum value. Use an integer value, not a DURATION value.
[in]	optional	When 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 existing option.

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	syntax	String to display for the option value instead of the default "value". For instance: "address:port" "'string'".
[in]	text	Help 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  )

inline

Add the help text of an existing option.

Parameters

[in]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	text	Help 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]	name	Long name of option. 0 or "" means a parameter, not an option.
[in]	separator	The 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]	other	Another instance from which to get the options.
[in]	replace	If 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 )

virtual

Set the description of the command.

Parameters

[in]

description

A short one-line description, e.g. "Wonderful File Copier".

setSyntax()

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

virtual

Set the syntax of the command.

Parameters

[in]

syntax

A short one-line syntax summary, e.g. "[options] filename ...".

Reimplemented in ts::ArgsWithPlugins.

setIntro()

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

virtual

Set the introduction or preamble text for help description.

Parameters

[in]

intro

Introduction text.

setTail()

virtual void ts::Args::setTail ( const UString &  tail )

virtual

Set the conclusion or tailing text for help description.

Parameters

[in]

tail

Tailing text.

setFlags()

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

virtual

Set the option flags of the command.

Parameters

[in]

flags

Define 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()

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

virtual

Get a formatted help text.

Parameters

[in]	format	Requested format of the help text.
[in]	line_width	Maximum width of text lines.

Returns

The formatted help text.

Reimplemented in ts::ArgsWithPlugins.

setAppName()

void ts::Args::setAppName ( const UString &  name )

inline

Set the initial application name (will be overwritten at next command analysis).

Parameters

[in]

name

Application name string.

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]

shell

Shell name string.

getShell()

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

inline

Get the "shell" string.

Returns

The shell name string.

See also

setShell()

analyze() [1/3]

virtual bool ts::Args::analyze ( const UString &  command, 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]	command	Full command line, with application name and parameters. Parameters are separated with spaces. Special characters and spaces must be escaped or quoted in the parameters.
[in]	processRedirections	If 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/3]

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]	argc	Number of arguments from command line.
[in]	argv	Arguments from command line. The application name is in argv[0]. The subsequent elements contain the arguments.
[in]	processRedirections	If 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() [3/3]

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_name	Application name.
[in]	arguments	Arguments from command line.
[in]	processRedirections	If 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.

GetAppName()

static UString ts::Args::GetAppName ( int  argc, char *  argv[]  )

static

Get the application name from a standard argc/argv pair.

Parameters

[in]	argc	Number of arguments from command line.
[in]	argv	Arguments from command line.

Returns

The corresponding application name.

getCommandArgs()

void ts::Args::getCommandArgs ( UStringVector &  args ) const

inline

Get the command line parameters from the last command line analysis.

Parameters

[out]

args

The command parameters from the last command line analysis.

commandLine()

UString ts::Args::commandLine

(

)

const

Get the full command line from the last command line analysis.

Returns

The full command line from the last command line analysis. It contains the application name and arguments. Special characters are escaped or quoted.

present()

bool ts::Args::present

(

const UChar *

name = nullptr

)

const

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

Parameters

[in]

name

The 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]

name

The 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() [1/3]

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]	value	A string receiving the value of the option or parameter.
[in]	name	The 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_value	The string to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The 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]	name	The 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_value	The string to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The value of the option or parameter.

getOptionalValue()

void ts::Args::getOptionalValue	(	std::optional< UString > &	value,
		const UChar *	name = nullptr,
		bool	clear_if_absent = false
	)		const

Get the value of an option in the last analyzed command line, only if present.

Parameters

[in,out]	value	A std::optional string receiving the value of the option or parameter.
[in]	name	The 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]	clear_if_absent	When the option is not present, the std::optional object is cleared (set to uninitialized) when clear_if_absent it true. Otherwise, it is left unmodified.

getValues()

template<class CONTAINER , typename std::enable_if< std::is_base_of< ts::UString, typename CONTAINER::value_type >::value >::type * >

void ts::Args::getValues	(	CONTAINER &	values,
		const UChar *	name = nullptr
	)		const

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

Template Parameters

CONTAINER

A container type of UString such as list, vector, etc.

Parameters

[out]	values	A container of strings receiving all values of the option or parameter.
[in]	name	The 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.

getPathValue()

void ts::Args::getPathValue	(	fs::path &	value,
		const UChar *	name = nullptr,
		const fs::path &	def_value = fs::path(),
		size_t	index = 0
	)		const

Get the value of a filesystem path option in the last analyzed command line.

Parameters

[out]	value	A path receiving the value of the option or parameter.
[in]	name	The 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_value	The path to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

getPathValues()

template<class CONTAINER , typename std::enable_if< std::is_base_of< fs::path, typename CONTAINER::value_type >::value >::type * >

void ts::Args::getPathValues	(	CONTAINER &	values,
		const UChar *	name = nullptr
	)		const

Get all occurences of a filesystem path option in a container of path.

Template Parameters

CONTAINER

A container type of fs::path such as list, vector, etc.

Parameters

[out]	values	A container of fs::path receiving all values of the option or parameter.
[in]	name	The 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 INT2 , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< INT >::value >::type * >

void ts::Args::getIntValue	(	INT &	value,
		const UChar *	name = nullptr,
		const INT2	def_value = static_cast<INT2>(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

INT	An integer or enumeration type for the result.

Parameters

[out]	value	A variable receiving the integer value of the option or parameter.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

intValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< INT >::value >::type * >

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

INT	An integer or enumeration type for the result.

Parameters

[in]	name	The 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_value	The value to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The integer value of the option or parameter.

getOptionalIntValue()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< INT >::value >::type * >

void ts::Args::getOptionalIntValue	(	std::optional< INT > &	value,
		const UChar *	name = nullptr,
		bool	clear_if_absent = false
	)		const

Get the value of an integer option in the last analyzed command line, only if present.

Template Parameters

INT	An integer or enumeration type for the result.

Parameters

[in,out]	value	A std::optional integer receiving the value of the option or parameter.
[in]	name	The 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]	clear_if_absent	When the option is not present, the std::optional object is cleared (set to uninitialized) when clear_if_absent it true. Otherwise, it is left unmodified.

getIntValues() [1/4]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< INT >::value >::type * >

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.

Template Parameters

INT	An integer or enumeration type for the result.

Parameters

[out]	values	A container of integers receiving all values of the option or parameter.
[in]	name	The 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/4]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< INT >::value >::type * >

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.

Template Parameters

INT	An integer or enumeration type for the result.

Parameters

[out]	values	A container of integers receiving all values of the option or parameter.
[in]	name	The 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/4]

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 bitset of values.

Parameters

[out]	values	A 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]	name	The 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]	defValue	The boolean to set in all values if the option or parameter is not present in the command line.

getIntValues() [4/4]

template<std::size_t N>

void ts::Args::getIntValues	(	CompactBitSet< N > &	values,
		const UChar *	name = nullptr,
		bool	defValue = false
	)		const

Get all occurences of an option as a compact bitset of values.

Parameters

[out]	values	A compact 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]	name	The 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]	defValue	The 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 * >

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

INT	An integer type for the result.

Parameters

[in]	name	The 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_value	The 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 * >

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

INT	An integer type for the result.

Parameters

[out]	value	A variable receiving the OR'ed values of the integer option.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line.

getChronoValue() [1/2]

template<class Rep1 , class Period1 , class Rep2 , class Period2 >

void ts::Args::getChronoValue	(	cn::duration< Rep1, Period1 > &	value,
		const UChar *	name = nullptr,
		const cn::duration< Rep2, Period2 > &	def_value = cn::duration<Rep1, Period1>::zero(),
		size_t	index = 0
	)		const

Get the value of an std::chrono::duration option in the last analyzed command line.

If the option has been declared with a std::chrono::duration 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.

Parameters

[out]	value	A variable receiving the duration value of the option or parameter.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence. Add the definition of an option, the value being an instance of std::chrono::duration.

getChronoValue() [2/2]

template<class Rep , class Period >

void ts::Args::getChronoValue ( cn::duration< Rep, Period > &  value, const UChar *  name = nullptr, size_t  index = 0  ) const

inline

Get the value of an std::chrono::duration option in the last analyzed command line.

If the option has been declared with a std::chrono::duration 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.

Parameters

[out]	value	A variable receiving the duration value of the option or parameter.
[in]	name	The 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]	index	The occurence of the option to return. Zero designates the first occurence. Add the definition of an option, the value being an instance of std::chrono::duration.

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]	value	A 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]	name	The 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]	index	The 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]	name	The 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]	index	The 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.

getHexaValue()

void ts::Args::getHexaValue	(	ByteBlock &	value,
		const UChar *	name = nullptr,
		const ByteBlock &	def_value = ByteBlock(),
		size_t	index = 0
	)		const

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

Parameters

[out]	value	A variable receiving the decoded binary value of the option or parameter.
[in]	name	The 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_value	The data to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

hexaValue()

ByteBlock ts::Args::hexaValue	(	const UChar *	name = nullptr,
		const ByteBlock &	def_value = ByteBlock(),
		size_t	index = 0
	)		const

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

Parameters

[in]	name	The 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_value	The data to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The decoded binary value of the option or parameter.

getIPValue()

void ts::Args::getIPValue	(	IPv4Address &	value,
		const UChar *	name = nullptr,
		const IPv4Address &	def_value = IPv4Address(),
		size_t	index = 0
	)		const

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

Parameters

[out]	value	A variable receiving the resolved IPv4 address value of the option or parameter.
[in]	name	The 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_value	The IPv4 address to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

ipValue()

IPv4Address ts::Args::ipValue	(	const UChar *	name = nullptr,
		const IPv4Address &	def_value = IPv4Address(),
		size_t	index = 0
	)		const

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

Parameters

[in]	name	The 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_value	The IPv4 address to return if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The resolved IPv4 address value of the option or parameter.

getSocketValue()

void ts::Args::getSocketValue	(	IPv4SocketAddress &	value,
		const UChar *	name = nullptr,
		const IPv4SocketAddress &	def_value = IPv4SocketAddress(),
		size_t	index = 0
	)		const

Get the value of an option as an IPv4 socket address in the last analyzed command line.

Parameters

[out]	value	A variable receiving the resolved IPv4 socket address value of the option or parameter.
[in]	name	The 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_value	The IPv4 address socket to return if the option or parameter is not present in the command line or with fewer occurences than index. If the parameter is present but either address or port is missing, the missing part is copied from def_value.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

socketValue()

IPv4SocketAddress ts::Args::socketValue	(	const UChar *	name = nullptr,
		const IPv4SocketAddress &	def_value = IPv4SocketAddress(),
		size_t	index = 0
	)		const

Get the value of an option as an IPv4 socket address in the last analyzed command line.

Parameters

[in]	name	The 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_value	The IPv4 socket address to return if the option or parameter If the parameter is present but either address or port is missing, the missing part is copied from def_value. is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The resolved IPv4 socket address value of the option or parameter.

getValue() [2/3]

template<class NUMTYPE , typename std::enable_if< std::is_base_of< ts::AbstractNumber, NUMTYPE >::value, int >::type N>

void ts::Args::getValue	(	NUMTYPE &	value,
		const UChar *	name = nullptr,
		const NUMTYPE &	def_value = NUMTYPE(0),
		size_t	index = 0
	)		const

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

If the option has been declared with an AbstractNumber 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

NUMTYPE

A subclass of AbstractNumber.

Parameters

[out]	value	A variable receiving the value of the option or parameter.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

getValue() [3/3]

template<class NUMTYPE , typename INT1 , typename std::enable_if< std::is_base_of< AbstractNumber, NUMTYPE >::value &&std::is_integral< INT1 >::value, int >::type = 0>

void ts::Args::getValue ( NUMTYPE &  value, const UChar *  name, INT1  def_value, size_t  index = 0  ) const

inline

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

If the option has been declared with an AbstractNumber 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

NUMTYPE

A subclass of AbstractNumber.

Parameters

[out]	value	A variable receiving the value of the option or parameter.
[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

numValue()

template<class NUMTYPE , typename std::enable_if< std::is_base_of< ts::AbstractNumber, NUMTYPE >::value, int >::type N>

NUMTYPE ts::Args::numValue	(	const UChar *	name = nullptr,
		const NUMTYPE &	def_value = NUMTYPE(0),
		size_t	index = 0
	)		const

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

If the option has been declared with an AbstractNumber 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

NUMTYPE

A subclass of AbstractNumber.

Parameters

[in]	name	The 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_value	The value to return in value if the option or parameter is not present in the command line or with fewer occurences than index.
[in]	index	The occurence of the option to return. Zero designates the first occurence.

Returns

The value of the option or parameter.

exitOnError()

void ts::Args::exitOnError

(

bool

force = false

)

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

Parameters

[in]

force

If true, ignore flag NO_EXIT_ON_ERROR and force application termination on error.

processArgsRedirection()

bool ts::Args::processArgsRedirection

(

UStringVector &

args

)

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

Parameters

[in,out]

args

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

The method is called only when a message passed the severity filter. It is not necessary to recheck the maximum severity inside the method. By default, does nothing.

Parameters

[in]	severity	Message severity.
[in]	msg	Message text.

Reimplemented from ts::Report.

setMaxSeverity()

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

inherited

Set maximum severity level.

Messages with higher severities are not reported.

Parameters

[in]

level

Set report to that level.

raiseMaxSeverity()

void ts::Report::raiseMaxSeverity ( int  level )

inherited

Raise maximum severity level.

The severity can only be increased (more verbose, more debug), never decreased.

Parameters

[in]

level

Set report at least to that level.

maxSeverity()

int ts::Report::maxSeverity ( ) const

inlineinherited

Get maximum severity level.

Returns

Current maximum debug level.

gotErrors()

bool ts::Report::gotErrors ( ) const

inlineinherited

Check if errors (or worse) were reported through this object.

Errors which were reported through delegated reports are ignored.

Returns

True if errors (or worse) were reported through this object.

resetErrors()

void ts::Report::resetErrors ( )

inlineinherited

Reset the error indicator.

See also

gotErrors()

setReportPrefix()

void ts::Report::setReportPrefix ( const UString &  prefix )

inlineinherited

Set the prefix to display before each message.

Parameters

[in]

prefix

The prefix to prepend to all messages.

reportPrefix()

UString ts::Report::reportPrefix ( ) const

inlineinherited

Get the current prefix to display.

Returns

The current prefix to display.

delegateReport()

Report * ts::Report::delegateReport ( Report *  report )

inherited

Delegate message logging to another report object.

Parameters

[in]

report

New report object to which messages are delegated. Use nullptr to remove the delegation and return to normal logging.

Returns

Previous delegate report, return a null pointer if there was no previous delegate.

debug() [1/5]

bool ts::Report::debug ( ) const

inlineinherited

Check if debugging is active.

Returns

True if current reporting level is Debug or higher.

debug() [2/5]

void ts::Report::debug ( const UChar *  msg )

inlineinherited

Report a debug message.

Parameters

[in]

msg

Message line.

debug() [3/5]

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

inlineinherited

Report a debug message.

Parameters

[in]

msg

Message line.

debug() [4/5]

template<class... Args>

void ts::Report::debug ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report a debug message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

debug() [5/5]

template<class... Args>

void ts::Report::debug ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report a debug message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

verbose() [1/5]

bool ts::Report::verbose ( ) const

inlineinherited

Check if verbose reporting is active.

Returns

True if current reporting level is Verbose or higher.

verbose() [2/5]

void ts::Report::verbose ( const UChar *  msg )

inlineinherited

Report a verbose message.

Parameters

[in]

msg

Message line.

verbose() [3/5]

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

inlineinherited

Report a verbose message.

Parameters

[in]

msg

Message line.

verbose() [4/5]

template<class... Args>

void ts::Report::verbose ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report a verbose message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

verbose() [5/5]

template<class... Args>

void ts::Report::verbose ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report a verbose message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

log() [1/3]

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

inherited

Report a message with an explicit severity.

Parameters

[in]	severity	Message severity.
[in]	msg	Message line.

log() [2/3]

template<class... Args>

void ts::Report::log ( int  severity, const UChar *  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	severity	Message severity.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

log() [3/3]

template<class... Args>

void ts::Report::log ( int  severity, const UString &  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	severity	Message severity.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

fatal() [1/4]

void ts::Report::fatal ( const UChar *  msg )

inlineinherited

Report a fatal error message.

Parameters

[in]

msg

Message line.

fatal() [2/4]

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

inlineinherited

Report a fatal error message.

Parameters

[in]

msg

Message line.

fatal() [3/4]

template<class... Args>

void ts::Report::fatal ( const UChar *  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

fatal() [4/4]

template<class... Args>

void ts::Report::fatal ( const UString &  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

severe() [1/4]

void ts::Report::severe ( const UChar *  msg )

inlineinherited

Report a severe error message.

Parameters

[in]

msg

Message line.

severe() [2/4]

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

inlineinherited

Report a severe error message.

Parameters

[in]

msg

Message line.

severe() [3/4]

template<class... Args>

void ts::Report::severe ( const UChar *  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

severe() [4/4]

template<class... Args>

void ts::Report::severe ( const UString &  fmt, Args &&...  args  )

inlineinherited

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

error() [1/4]

void ts::Report::error ( const UChar *  msg )

inlineinherited

Report an error message.

Parameters

[in]

msg

Message line.

error() [2/4]

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

inlineinherited

Report an error message.

Parameters

[in]

msg

Message line.

error() [3/4]

template<class... Args>

void ts::Report::error ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report an error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

error() [4/4]

template<class... Args>

void ts::Report::error ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report an error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

warning() [1/4]

void ts::Report::warning ( const UChar *  msg )

inlineinherited

Report a warning error message.

Parameters

[in]

msg

Message line.

warning() [2/4]

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

inlineinherited

Report a warning error message.

Parameters

[in]

msg

Message line.

warning() [3/4]

template<class... Args>

void ts::Report::warning ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report a warning message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

warning() [4/4]

template<class... Args>

void ts::Report::warning ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report a warning message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

info() [1/4]

void ts::Report::info ( const UChar *  msg )

inlineinherited

Report an informational message.

Parameters

[in]

msg

Message line.

info() [2/4]

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

inlineinherited

Report an informational message.

Parameters

[in]

msg

Message line.

info() [3/4]

template<class... Args>

void ts::Report::info ( const UChar *  fmt, Args &&...  args  )

inlineinherited

Report an informational message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

info() [4/4]

template<class... Args>

void ts::Report::info ( const UString &  fmt, Args &&...  args  )

inlineinherited

Report an informational message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

UString::format()

Member Data Documentation

UNLIMITED_COUNT

constexpr size_t ts::Args::UNLIMITED_COUNT = std::numeric_limits<size_t>::max()

staticconstexpr

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 = std::numeric_limits<int64_t>::max()

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:

• tsArgs.h