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

#include <NidasApp.h>

Inheritance diagram for nidas::core::NidasAppArg:

[legend]

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.

virtual	~NidasAppArg ()

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

bool	isRequired ()
	Return whether this argument is required.

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

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

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

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

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

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

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.

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

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.

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

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

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.

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

void	setUsageString (const std::string &text)

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

void	setDefault (const std::string &dvalue)

std::string	getDefault ()

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

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

nidas::core::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()

nidas::core::NidasAppArg::~NidasAppArg ( )

virtual

◆ NidasAppArg() [2/2]

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

private

Member Function Documentation

◆ accept()

bool nidas::core::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().

◆ acceptShortFlag()

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 PacketReader::parseRunstring(), and NidsMerge::parseRunstring().

◆ addFlag()

void nidas::core::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, and nidas::core::getSample().

◆ asBool()

bool nidas::core::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, nidas::core::getSample(), and getValue().

Referenced by DataStats::parseRunstring(), DataPrep::parseRunstring(), StatsProcess::parseRunstring(), TeeI2C::parseRunstring(), nidas::core::DSMEngine::parseRunstring(), nidas::core::DSMServerApp::parseRunstring(), DataStats::printReport(), NidsMerge::run(), nidas::core::NidasApp::setFileSetTimes(), nidas::core::NidasApp::setOutputClipping(), nidas::core::NidasApp::setupDaemon(), nidas::core::NidasApp::setupDaemonLogging(), and TeeI2C::writeOutput().

◆ asFloat()

float nidas::core::NidasAppArg::asFloat ( )

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

References _flags, nidas::core::getSample(), and getValue().

Referenced by nidas::core::NidasApp::getSorterLength(), and DataDump::parseRunstring().

◆ asInt()

int nidas::core::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, nidas::core::getSample(), and getValue().

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

◆ getDefault()

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

inline

References _default.

◆ getFlag()

const std::string & nidas::core::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.

◆ getUsageFlags()

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

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

References _default, _enableShortFlag, _flags, nidas::core::getSample(), and single().

Referenced by usage().

◆ getValue()

const std::string & nidas::core::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(), nidas::core::NidasApp::getSorterLength(), DataStats::jsonReport(), nidas::core::NidasApp::parseNext(), DataPrep::parseRunstring(), StatsProcess::parseRunstring(), TeeI2C::parseRunstring(), nidas::core::DSMServerApp::parseRunstring(), and StatsProcess::run().

◆ isRequired()

bool nidas::core::NidasAppArg::isRequired ( )

Return whether this argument is required.

See setRequired().

References _required.

Referenced by setRequired().

◆ operator nidas_app_arglist_t()

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.

References nidas::core::getSample().

◆ operator=()

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

private

◆ parse()

bool nidas::core::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(), nidas::core::getSample(), and single().

◆ setDefault()

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

inline

References _default, and nidas::core::getSample().

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

◆ setFlags()

void nidas::core::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 DataPrep::parseRunstring(), and StatsProcess::parseRunstring().

◆ setRequired()

void nidas::core::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().

◆ setUsageString()

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

inline

References _usage, and nidas::core::getSample().

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

◆ single()

bool nidas::core::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().

◆ specified()

bool nidas::core::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(), TeeI2C::parseRunstring(), DataStats::report(), StatsProcess::run(), and nidas::core::NidasApp::setupDaemonLogging().

◆ usage()

std::string nidas::core::NidasAppArg::usage	(	const std::string &	indent = " ",
		bool	brief = false )

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

The returned string is formatted like below, each line prefixed with indent, and always ends in a newline. If * brief is true, the usage lines are omitted.

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

References _default, _syntax, _usage, nidas::core::getSample(), getUsageFlags(), and len.

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

Friends And Related Symbol Documentation

◆ NidasApp

friend class NidasApp

friend

Member Data Documentation

◆ _arg

std::string nidas::core::NidasAppArg::_arg

protected

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

◆ _default

std::string nidas::core::NidasAppArg::_default

protected

Referenced by accept(), getDefault(), getUsageFlags(), getValue(), setDefault(), and usage().

◆ _enableShortFlag

bool nidas::core::NidasAppArg::_enableShortFlag

protected

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

◆ _flags

std::string nidas::core::NidasAppArg::_flags

protected

Referenced by accept(), addFlag(), asBool(), asFloat(), asInt(), getUsageFlags(), and setFlags().

◆ _required

bool nidas::core::NidasAppArg::_required

protected

Referenced by isRequired(), and setRequired().

◆ _syntax

std::string nidas::core::NidasAppArg::_syntax

protected

Referenced by single(), and usage().

◆ _usage

std::string nidas::core::NidasAppArg::_usage

protected

Referenced by setUsageString(), and usage().

◆ _value

std::string nidas::core::NidasAppArg::_value

protected

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

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

nidas/core/NidasApp.h
nidas/core/NidasApp.cc

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ NidasAppArg() [1/2]

◆ ~NidasAppArg()

◆ NidasAppArg() [2/2]

Member Function Documentation

◆ accept()

◆ acceptShortFlag()

◆ addFlag()

◆ asBool()

◆ asFloat()

◆ asInt()

◆ getDefault()

◆ getFlag()

◆ getUsageFlags()

◆ getValue()

◆ isRequired()

◆ operator nidas_app_arglist_t()

◆ operator=()

◆ parse()

◆ setDefault()

◆ setFlags()

◆ setRequired()

◆ setUsageString()

◆ single()

◆ specified()

◆ usage()

Friends And Related Symbol Documentation

◆ NidasApp

Member Data Documentation

◆ _arg

◆ _default

◆ _enableShortFlag

◆ _flags

◆ _required

◆ _syntax

◆ _usage

◆ _value