A NidasAppArg is command-line argument which can be handled by NidasApp. More...

#include <NidasApp.h>

Inheritance diagram for nidas::core::NidasAppArg:

Public Member Functions
	NidasAppArg (const std::string &flags, const std::string &syntax="", const std::string &usage="", const std::string &default_="", bool required=false)
	Construct a NidasAppArg from a list of accepted short and long flags, the syntax for any arguments to the flag, a usage string, and a default value. More...

virtual	~NidasAppArg ()

void	setRequired (bool isRequired=true)
	Set whether this argument is required. More...

bool	isRequired ()
	Return whether this argument is required. More...

void	acceptShortFlag (bool enable)
	Set whether short flags are enabled or not. More...

void	addFlag (const std::string &flag)
	Add a flag which this argument should accept. More...

void	setFlags (const std::string &flags)
	Completely replace the flags which this argument should accept. More...

	operator nidas_app_arglist_t ()
	Provide conversion to an arglist so a single NidasAppArg can be passed where an arglist is expected. More...

std::string	usage (const std::string &indent=" ")
	Render the usage string for this particular argument, taking into account which flags are enabled. More...

bool	specified ()
	Return true if this argument has been filled in from a command-line argument list, such as after a call to NidasApp::parseArgs(). More...

const std::string &	getValue ()
	If this argument has been parsed from a command line list (specified() returns true), then return the value passed after the flag. More...

const std::string &	getFlag ()
	Return the command-line flag which this argument consumed. More...

bool	asBool ()
	An argument is true if it is a stand-alone flag and was specified in the arguments, or else if the flag value evaluates to true. More...

int	asInt ()
	Parse the argument value as an integer, where the value could be the default if no value has been explicitly parsed with parse(). More...

float	asFloat ()
	Same as asInt(), except parse the argument value as a float. More...

virtual bool	parse (const ArgVector &argv, int *argi=0)
	If argv[argi] matches this argument, then set the flag that was found and also the value if this argument takes a value, and return true. More...

bool	accept (const std::string &flag)
	Return true if the given command-line `flag` matches one of this argument's flags. More...

void	setUsageString (const std::string &text)

std::string	getUsageFlags ()
	Return the string of flags accepted by this NidasAppArg according to the acceptShortFlag() setting. More...

void	setDefault (const std::string &dvalue)

std::string	getDefault ()

Protected Member Functions
bool	single ()
	Return true for arguments which are only a single argument. More...

Protected Attributes
std::string	_flags

std::string	_syntax

std::string	_usage

std::string	_default

std::string	_arg

std::string	_value

bool	_enableShortFlag

bool	_required

Private Member Functions
NidasAppArg &	operator= (const NidasAppArg &)

	NidasAppArg (const NidasAppArg &)

Friends
class	NidasApp

Detailed Description

A NidasAppArg is command-line argument which can be handled by NidasApp.

The base class defines basic state and behavior about the argument, then arguments can be subclassed from this class to provide extra customization. More standard arguments, shared by more than one nidas app, are defined as members of the NidasApp class. NIDAS applications can add their own arguments.

Constructor & Destructor Documentation

NidasAppArg::NidasAppArg	(	const std::string &	flags,
		const std::string &	syntax = `""`,
		const std::string &	usage = `""`,
		const std::string &	default_ = `""`,
		bool	required = `false`
	)

Construct a NidasAppArg from a list of accepted short and long flags, the syntax for any arguments to the flag, a usage string, and a default value.

flags is a comma-separated list of the command-line flags recognized by this argument. The usage string describes the argument, something which can be printed as part of an application's usage information.

The flags specifier can include multiple flags that are accepted for an argument, separated by commas. In the example below, -l is obviously the short form, and it will not be accepted if acceptShortFlag() is not true. The others are long forms, each equivalent to the other. Deprecated options can be surrounded by brackets. If an option is deprecated, it will still be accepted on the command-line, but it will not be shown in the usage. (Probably it should be documented as deprecated in the usage string.)

-l,–log[,–loglevel,–logconfig]

If an argument is only a flag and no additional parameter, then the syntax must be empty, and the default value is assumed to be boolean false. When the flag is parsed in the arguments, then the value will be true. If a default boolean value is specified for a flag with no parameters, then as a special case for long arguments, a long form can be prefixed with –no- to set the value to false. Thus a boolean option can be given an explicit default value by passing "true" or "false" as the default value, and then it can be set to "true" with the normal flag and set to "false" using the –no form.

Typically an application's arguments are instantiated as part of the application's class, so they have the same lifetime as the application instance and can be referenced to generate usage information. See NidasApp::enableArguments().

When the application's arguments are parsed, then this argument is updated with the exact flag and value that set it.

Arguments can be marked as required, which allows unset required arguments to be detected by NidasApp::checkRequiredArguments(). See setRequired().

NidasAppArg::~NidasAppArg ( )

virtual

nidas::core::NidasAppArg::NidasAppArg ( const NidasAppArg & )

private

Member Function Documentation

bool NidasAppArg::accept ( const std::string & flag )

Return true if the given command-line flag matches one of this argument's flags.

References _default, _enableShortFlag, _flags, _value, and single().

Referenced by nidas::core::BadSampleFilterArg::parse(), and parse().

void nidas::core::NidasAppArg::acceptShortFlag ( bool enable )

inline

Set whether short flags are enabled or not.

Pass enable as false to disable short flags and require only long flags instead. By default short flags are enabled.

References _enableShortFlag.

Referenced by NidsMerge::parseRunstring(), and PacketReader::parseRunstring().

void NidasAppArg::addFlag ( const std::string & flag )

Add a flag which this argument should accept.

Use this to allow an application to accept deprecated flags like -B and -E.

References _flags.

bool NidasAppArg::asBool ( )

An argument is true if it is a stand-alone flag and was specified in the arguments, or else if the flag value evaluates to true.

References _flags, and getValue().

Referenced by TeeI2C::i2c_byte_reads(), nidas::core::DSMServerApp::parseRunstring(), StatsProcess::parseRunstring(), PConfig::parseRunstring(), nidas::core::DSMEngine::parseRunstring(), TeeI2C::parseRunstring(), DataPrep::parseRunstring(), DataStats::parseRunstring(), NidsMerge::run(), DataDump::run(), nidas::core::NidasApp::setupDaemon(), and nidas::core::NidasApp::setupDaemonLogging().

float NidasAppArg::asFloat ( )

Same as asInt(), except parse the argument value as a float.

References _flags, and getValue().

Referenced by StatsProcess::parseRunstring(), DataPrep::parseRunstring(), and DataDump::parseRunstring().

int NidasAppArg::asInt ( )

Parse the argument value as an integer, where the value could be the default if no value has been explicitly parsed with parse().

Throw NidasAppException if the whole value cannot be parsed as an integer. See also asFloat().

References _flags, and getValue().

Referenced by NidsMerge::parseRunstring(), StatsProcess::parseRunstring(), TeeI2C::parseRunstring(), DataPrep::parseRunstring(), DataStats::parseRunstring(), and DataPrep::run().

std::string nidas::core::NidasAppArg::getDefault ( )

inline

References _default.

const std::string & NidasAppArg::getFlag ( )

Return the command-line flag which this argument consumed.

For example, if an argument with multiple flags is matched, then getFlag() returns the flag that matched the argument.

References _arg.

Referenced by DataPrep::parseRunstring().

std::string NidasAppArg::getUsageFlags ( )

Return the string of flags accepted by this NidasAppArg according to the acceptShortFlag() setting.

References _default, _enableShortFlag, _flags, and single().

Referenced by usage().

const std::string & NidasAppArg::getValue ( )

If this argument has been parsed from a command line list (specified() returns true), then return the value passed after the flag.

Otherwise return the default value.

References _default, _value, and specified().

Referenced by asBool(), asFloat(), asInt(), nidas::core::NidasApp::checkPidFile(), DataStats::jsonReport(), nidas::core::NidasApp::parseNext(), NidsMerge::parseRunstring(), DmdA2dCk::parseRunstring(), nidas::core::DSMServerApp::parseRunstring(), StatsProcess::parseRunstring(), PConfig::parseRunstring(), and DataPrep::parseRunstring().

bool NidasAppArg::isRequired ( )

Return whether this argument is required.

See setRequired().

References _required.

Referenced by setRequired().

nidas::core::NidasAppArg::operator nidas_app_arglist_t ( )

inline

Provide conversion to an arglist so a single NidasAppArg can be passed where an arglist is expected.

NidasAppArg& nidas::core::NidasAppArg::operator= ( const NidasAppArg & )

private

bool NidasAppArg::parse	(	const ArgVector &	argv,
		int *	argi = `0`
	)

virtual

If argv[argi] matches this argument, then set the flag that was found and also the value if this argument takes a value, and return true.

Otherwise return false. The vector is not modified, but if argi is nonzero, then it is used as the starting index into argv, and it is advanced according to the number of elements of argv consumed by this argument. This method is virtual so subclasses can implement customized parsing, such as optionally consuming more than one argument following a flag.

Reimplemented in nidas::core::BadSampleFilterArg.

References _arg, _value, accept(), nidas::core::expectArg(), and single().

void nidas::core::NidasAppArg::setDefault ( const std::string & dvalue )

inline

References _default.

Referenced by nidas::core::NidasApp::NidasApp().

void NidasAppArg::setFlags ( const std::string & flags )

Completely replace the flags which this argument should accept.

This should be avoided if possible, otherwise the flags will not be consistent across applications. However, in some cases this is necessary to remove a conflicting short flag.

References _flags.

Referenced by StatsProcess::parseRunstring(), and DataPrep::parseRunstring().

void NidasAppArg::setRequired ( bool isRequired = true )

Set whether this argument is required.

A required argument must be supplied on the command line even if it has a default value. If an argument is not required because it has a default value, then an application should not set that argument to be required.

Defaults to true, but the client may disable this option by setting the argument to false.

References _required, and isRequired().

void nidas::core::NidasAppArg::setUsageString ( const std::string & text )

inline

References _usage.

Referenced by nidas::core::NidasApp::NidasApp(), DataPrep::parseRunstring(), and nidas::core::NidasAppInputFilesArg::updateUsage().

bool NidasAppArg::single ( )

protected

Return true for arguments which are only a single argument.

They are a single command-line flag with no following value, and typically implying a boolean value. This is equivalent to not specifying a syntax when the argument is created.

References _syntax.

Referenced by accept(), getUsageFlags(), and parse().

bool NidasAppArg::specified ( )

Return true if this argument has been filled in from a command-line argument list, such as after a call to NidasApp::parseArgs().

If true, then this argument stores the flag that was recognized, and also the value of any additional parameters to this argument.

References _arg.

Referenced by DataStats::addCounter(), getValue(), NidsMerge::parseRunstring(), TeeI2C::parseRunstring(), DataStats::report(), and nidas::core::NidasApp::setupDaemonLogging().

std::string NidasAppArg::usage ( const std::string & indent = " " )

Render the usage string for this particular argument, taking into account which flags are enabled.

The returned string is formatted like below, and always ends in a newline:

<indent><flag>[,<flag>...] [<syntax>] [default: <default>] <indent><indent>Description line one <indent><indent>Description line two ...

References _default, _syntax, _usage, and getUsageFlags().