Command line arguments for commands with plugins. More...

#include <tsArgsWithPlugins.h>

Inheritance diagram for ts::ArgsWithPlugins:

[legend]

Collaboration diagram for ts::ArgsWithPlugins:

[legend]

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
	ArgsWithPlugins (size_t min_inputs=0, size_t max_inputs=UNLIMITED_COUNT, size_t min_plugins=0, size_t max_plugins=UNLIMITED_COUNT, size_t min_outputs=0, size_t max_outputs=UNLIMITED_COUNT, 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) override
	Load command arguments and analyze them.

virtual bool	analyze (const UString &command, bool processRedirections=true) override
	Load command arguments and analyze them.

virtual bool	analyze (int argc, char *argv[], bool processRedirections=true) override
	Load command arguments and analyze them.

UString	appName () const
	Get the application name from the last command line analysis.

template<typename INT > requires std::integral<INT>
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 > requires std::integral<INT>
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 override
	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> requires ts::int_enum<INT> && ts::int_enum<INT2>
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 > requires ts::int_enum<INT>
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 > requires ts::int_enum<INT>
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 (IPAddress &value, const UChar *name=nullptr, const IPAddress &def_value=IPAddress(), size_t index=0) const
	Get the value of an option as an IP address in the last analyzed command line.

template<typename INT > requires ts::int_enum<INT>
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 > requires std::derived_from<typename CONTAINER::value_type, fs::path>
void	getPathValues (CONTAINER &values, const UChar *name=nullptr) const
	Get all occurences of a filesystem path option in a container of path.

void	getPlugin (PluginOptions &plugin, PluginType type, const UChar *def_value=u"", size_t index=0) const
	Get a plugin of a given type, after command line analysis.

void	getPlugins (PluginOptionsVector &plugins, PluginType type) const
	Get all plugins of a given type, after command line analysis.

const UString &	getShell () const
	Get the "shell" string.

void	getSocketValue (IPSocketAddress &value, const UChar *name=nullptr, const IPSocketAddress &def_value=IPSocketAddress(), size_t index=0) const
	Get the value of an option as an IP 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 > requires std::derived_from<NUMTYPE, AbstractNumber> && std::integral<INT1>
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 > requires std::derived_from<NUMTYPE, ts::AbstractNumber>
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 > requires std::derived_from<typename CONTAINER::value_type, ts::UString>
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 > requires ts::int_enum<INT>
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.

IPAddress	ipValue (const UChar *name=nullptr, const IPAddress &def_value=IPAddress(), size_t index=0) const
	Get the value of an option as an IP 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 > requires std::derived_from<NUMTYPE, ts::AbstractNumber>
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> requires std::derived_from<NUMTYPE, AbstractNumber> && std::integral<INT1> && std::integral<INT2>
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 > requires std::integral<typename DURATION::rep>
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.

size_t	pluginCount (PluginType type) const
	Get the number of plugins of a given type, after command line analysis.

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) override
	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.

IPSocketAddress	socketValue (const UChar *name=nullptr, const IPSocketAddress &def_value=IPSocketAddress(), size_t index=0) const
	Get the value of an option as an IP 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

Command line arguments for commands with plugins.

The command line is analyzed, keeping command-specific options and plugin descriptions apart.

The option --list-plugins is automatically added and processed.

Member Enumeration Documentation

◆ Flags

enum ts::Args::Flags

inherited

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

inherited

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	IP address or host name translating to an address.
IPSOCKADDR	IP socket address (or host name) and port, both are mandatory.
IPSOCKADDR_OA	IP socket address (or host name) and port, address is optional.
IPSOCKADDR_OP	IP socket address (or host name) and port, port is optional.
IPSOCKADDR_OAP	IP socket address (or host name) and port, address and port are optional.

◆ HelpFormat

enum ts::Args::HelpFormat

inherited

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

◆ ArgsWithPlugins()

ts::ArgsWithPlugins::ArgsWithPlugins	(	size_t	min_inputs = `0`,
		size_t	max_inputs = `UNLIMITED_COUNT`,
		size_t	min_plugins = `0`,
		size_t	max_plugins = `UNLIMITED_COUNT`,
		size_t	min_outputs = `0`,
		size_t	max_outputs = `UNLIMITED_COUNT`,
		const UString &	description = `UString()`,
		const UString &	syntax = `UString()`,
		int	flags = `0`
	)

Constructor.

Parameters

[in]	min_inputs	Minimum number of input plugins.
[in]	max_inputs	Maximum number of input plugins.
[in]	min_plugins	Minimum number of packet processor plugins.
[in]	max_plugins	Maximum number of packet processor plugins.
[in]	min_outputs	Minimum number of output plugins.
[in]	max_outputs	Maximum number of output plugins.
[in]	description	A short one-line description.
[in]	syntax	A short one-line syntax summary.
[in]	flags	An or'ed mask of Flags values.

Member Function Documentation

◆ analyze() [1/3]

virtual bool ts::ArgsWithPlugins::analyze	(	const UString &	command,
		bool	processRedirections = `true`
	)

overridevirtual

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 from ts::Args.

◆ analyze() [2/3]

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

overridevirtual

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 from ts::Args.

◆ analyze() [3/3]

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

overridevirtual

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 from ts::Args.

◆ getHelpText()

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

overridevirtual

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 from ts::Args.

◆ setSyntax()

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

overridevirtual

Set the syntax of the command.

Parameters

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

Reimplemented from ts::Args.

◆ pluginCount()

size_t ts::ArgsWithPlugins::pluginCount ( PluginType type ) const

Get the number of plugins of a given type, after command line analysis.

Parameters

[in] type Type of plugin to find.

Returns: The number of plugins of that type.

◆ getPlugin()

void ts::ArgsWithPlugins::getPlugin	(	PluginOptions &	plugin,
		PluginType	type,
		const UChar *	def_value = `u""`,
		size_t	index = `0`
	)		const

Get a plugin of a given type, after command line analysis.

Parameters

[out]	plugin	Returned name and arguments of the plugin.
[in]	type	Type of plugin to find.
[in]	def_value	The plugin name to set in plugin if the plugin is not present.
[in]	index	Index of the plugin to find.

◆ getPlugins()

void ts::ArgsWithPlugins::getPlugins	(	PluginOptionsVector &	plugins,
		PluginType	type
	)		const

Get all plugins of a given type, after command line analysis.

Parameters

[out]	plugins	Returned name and arguments of the plugins.
[in]	type	Type of plugin to find.

◆ 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`
	)

inlineinherited

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`
	)

inlineinherited

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>
requires std::derived_from<NUMTYPE, AbstractNumber> && std::integral<INT1> && std::integral<INT2>

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`
	)

inlineinherited

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 >
requires std::integral<typename DURATION::rep>

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`
	)

inlineinherited

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
	)

inherited

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
	)

inlineinherited

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

inherited

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`
	)

inherited

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 )

virtualinherited

Set the description of the command.

Parameters

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

◆ setIntro()

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

virtualinherited

Set the introduction or preamble text for help description.

Parameters

[in] intro Introduction text.

◆ setTail()

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

virtualinherited

Set the conclusion or tailing text for help description.

Parameters

[in] tail Tailing text.

◆ setFlags()

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

virtualinherited

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

inlineinherited

Get the description of the command.

Returns: A short one-line description of the command.

◆ getSyntax()

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

inlineinherited

Get the syntax of the command.

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

◆ getFlags()

int ts::Args::getFlags ( ) const

inlineinherited

Get the option flags of the command.

Returns: A combination of or'ed values from Flags.

◆ setAppName()

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

inlineinherited

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 )

inlineinherited

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

inlineinherited

Get the "shell" string.

Returns: The shell name string.

See also: setShell()

◆ valid()

bool ts::Args::valid ( ) const

inlineinherited

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

inlineinherited

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[]
	)

staticinherited

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

inlineinherited

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

inherited

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

inherited

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

inherited

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

inherited

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.

◆ getValue() [2/3]

template<class NUMTYPE >
requires std::derived_from<NUMTYPE, ts::AbstractNumber>

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

inherited

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 >
requires std::derived_from<NUMTYPE, AbstractNumber> && std::integral<INT1>

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

inlineinherited

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.

◆ value()

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

inherited

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

inherited

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 >
requires std::derived_from<typename CONTAINER::value_type, ts::UString>

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

inherited

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

inherited

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 >
requires std::derived_from<typename CONTAINER::value_type, fs::path>

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

inherited

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 >
requires ts::int_enum<INT> && ts::int_enum<INT2>

void ts::Args::getIntValue	(	INT &	value,
		const UChar *	name = `nullptr`,
		const INT2	def_value = `static_cast<INT2>(0)`,
		size_t	index = `0`
	)		const

inherited

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 >
requires ts::int_enum<INT>

INT ts::Args::intValue	(	const UChar *	name = `nullptr`,
		const INT	def_value = `static_cast<INT>(0)`,
		size_t	index = `0`
	)		const

inherited

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 >
requires ts::int_enum<INT>

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

inherited

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 >
requires ts::int_enum<INT>

void ts::Args::getIntValues	(	std::vector< INT > &	values,
		const UChar *	name = `nullptr`
	)		const

inherited

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 >
requires ts::int_enum<INT>

void ts::Args::getIntValues	(	std::set< INT > &	values,
		const UChar *	name = `nullptr`
	)		const

inherited

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

inherited

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

inherited

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 >
requires std::integral<INT>

INT ts::Args::bitMaskValue	(	const UChar *	name = `nullptr`,
		const INT &	def_value = `static_cast<INT>(0)`
	)		const

inherited

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 >
requires std::integral<INT>

void ts::Args::getBitMaskValue	(	INT &	value,
		const UChar *	name = `nullptr`,
		const INT &	def_value = `static_cast<INT>(0)`
	)		const

inherited

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

inherited

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

inlineinherited

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

inherited

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

inherited

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

inherited

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

inherited

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	(	IPAddress &	value,
		const UChar *	name = `nullptr`,
		const IPAddress &	def_value = `IPAddress()`,
		size_t	index = `0`
	)		const

inherited

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

Parameters

[out]	value	A variable receiving the resolved IP 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 IP 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()

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

inherited

Get the value of an option as an IP 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 IP 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 IP address value of the option or parameter.

◆ getSocketValue()

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

inherited

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

Parameters

[out]	value	A variable receiving the resolved IP 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 IP 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()

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

inherited

Get the value of an option as an IP 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 IP 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 IP socket address value of the option or parameter.

◆ numValue()

template<class NUMTYPE >
requires std::derived_from<NUMTYPE, ts::AbstractNumber>

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

inherited

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 )

inherited

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 )

inherited

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
	)

overrideprotectedvirtualinherited

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

staticconstexprinherited

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

staticinherited

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

staticinherited

Enumeration description of HelpFormat.

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

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

tsArgsWithPlugins.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ Flags

◆ ArgType

◆ HelpFormat

Constructor & Destructor Documentation

◆ ArgsWithPlugins()

Member Function Documentation

◆ analyze() [1/3]

◆ analyze() [2/3]

◆ analyze() [3/3]

◆ getHelpText()

◆ setSyntax()

◆ pluginCount()

◆ getPlugin()

◆ getPlugins()

◆ option() [1/4]

◆ option() [2/4]

◆ option() [3/4]

◆ option() [4/4]

◆ help() [1/2]

◆ help() [2/2]

◆ optionNames()

◆ copyOptions()

◆ setDescription()

◆ setIntro()

◆ setTail()

◆ setFlags()

◆ getDescription()

◆ getSyntax()

◆ getFlags()

◆ setAppName()

◆ setShell()

◆ getShell()

◆ valid()

◆ appName()

◆ GetAppName()

◆ getCommandArgs()

◆ commandLine()

◆ present()

◆ count()

◆ getValue() [1/3]

◆ getValue() [2/3]

◆ getValue() [3/3]

◆ value()

◆ getOptionalValue()

◆ getValues()

◆ getPathValue()

◆ getPathValues()

◆ getIntValue()

◆ intValue()

◆ getOptionalIntValue()

◆ getIntValues() [1/4]

◆ getIntValues() [2/4]

◆ getIntValues() [3/4]

◆ getIntValues() [4/4]

◆ bitMaskValue()

◆ getBitMaskValue()

◆ getChronoValue() [1/2]

◆ getChronoValue() [2/2]

◆ getTristateValue()

◆ tristateValue()

◆ getHexaValue()

◆ hexaValue()

◆ getIPValue()

◆ ipValue()

◆ getSocketValue()

◆ socketValue()

◆ numValue()

◆ exitOnError()

◆ processArgsRedirection()

◆ writeLog()

◆ setMaxSeverity()

◆ raiseMaxSeverity()

◆ maxSeverity()