Args Class Reference

Argument parser class. More...

#include <args.hh>

Inheritance diagram for Args:

Public Member Functions
	Args (ErrorHandler *errh=0)
	Construct an argument parser.
	Args (const Vector< String > &conf, ErrorHandler *errh=0)
	Construct an argument parser parsing a copy of conf.
	Args (const Element *context, ErrorHandler *errh=0)
	Construct an argument parser.
	Args (const Vector< String > &conf, const Element *context, ErrorHandler *errh=0)
	Construct an argument parser parsing a copy of conf.
	Args (const Args &x)
	Copy construct an argument parser.
Args &	operator= (const Args &x)
	Assign to a copy of x.
bool	empty () const
	Return true iff this parser has no arguments or results.
bool	results_empty () const
	Return true iff this parser has no results.
Args &	clear ()
	Remove all arguments.
Args &	bind (Vector< String > &conf)
	Bind this parser's arguments to conf.
Args &	push_back (const String &arg)
	Append argument arg to this parser.
template<typename Iter >
Args &	push_back (Iter begin, Iter end)
	Append arguments in the range [begin, end) to this parser.
Args &	push_back_words (const String &str)
	Append the space-separated words in str to this parser.
Args &	push_back_args (const String &str)
	Append the comma-separated arguments in str to this parser.
Args &	reset ()
	Reset the parse status for every argument.
template<typename T >
Args &	read (const char *keyword, T &x)
	Read an argument using its type's default parser.
template<typename T >
Args &	read_m (const char *keyword, T &x)
template<typename T >
Args &	read_p (const char *keyword, T &x)
template<typename T >
Args &	read_mp (const char *keyword, T &x)
template<typename T >
Args &	read (const char *keyword, int flags, T &x)
template<typename T , typename V >
Args &	read_or_set (const char *keyword, T &x, const V &default_value)
	Read an argument using the default parser, or set it to a default value if the argument is was not supplied.
template<typename T , typename V >
Args &	read_or_set_p (const char *keyword, T &x, const V &default_value)
template<typename T , typename V >
Args &	read_or_set (const char *keyword, int flags, T &x, const V &default_value)
Args &	validate (const char *keyword, bool present=false)
template<typename T >
Args &	validate (const char *keyword, T &x, const char *static_value)
template<typename T , typename V >
Args &	validate (const char *keyword, T &x, const V &static_value)
template<typename T , typename V >
Args &	validate_f (const char *keyword, T &x, int flags, const V &static_value)
template<typename T , typename V >
Args &	validate_p (const char *keyword, T &x, const V &static_value)
template<typename T , typename V >
Args &	validate_mp (const char *keyword, T &x, const V &static_value)
template<typename T >
Args &	validate_p (const char *keyword, T &x, const char *static_value)
template<typename T >
Args &	validate_mp (const char *keyword, T &x, const char *static_value)
template<typename P , typename T >
Args &	read (const char *keyword, P parser, T &x)
	Read an argument using a specified parser.
template<typename P , typename T >
Args &	read_m (const char *keyword, P parser, T &x)
template<typename P , typename T >
Args &	read_p (const char *keyword, P parser, T &x)
template<typename P , typename T >
Args &	read_mp (const char *keyword, P parser, T &x)
template<typename P , typename T >
Args &	read (const char *keyword, int flags, P parser, T &x)
template<typename P , typename T , typename V >
Args &	read_or_set (const char *keyword, P parser, T &x, const V &default_value)
	Read an argument using a specified parser, or set it to a default value if the argument is was not supplied.
template<typename P , typename T , typename V >
Args &	read_or_set_p (const char *keyword, P parser, T &x, const V &default_value)
template<typename P , typename T , typename V >
Args &	read_or_set (const char *keyword, int flags, P parser, T &x, const V &default_value)
template<typename P , typename T1 , typename T2 >
Args &	read (const char *keyword, P parser, T1 &x1, T2 &x2)
	Read an argument using a specified parser with two results.
template<typename P , typename T1 , typename T2 >
Args &	read_m (const char *keyword, P parser, T1 &x1, T2 &x2)
template<typename P , typename T1 , typename T2 >
Args &	read_p (const char *keyword, P parser, T1 &x1, T2 &x2)
template<typename P , typename T1 , typename T2 >
Args &	read_mp (const char *keyword, P parser, T1 &x1, T2 &x2)
template<typename P , typename T1 , typename T2 >
Args &	read (const char *keyword, int flags, P parser, T1 &x1, T2 &x2)
template<typename P >
Args &	read_with (const char *keyword, P parser)
	Pass an argument to a specified parser.
template<typename P >
Args &	read_m_with (const char *keyword, P parser)
template<typename P >
Args &	read_p_with (const char *keyword, P parser)
template<typename P >
Args &	read_mp_with (const char *keyword, P parser)
template<typename P >
Args &	read_with (const char *keyword, int flags, P parser)
template<typename P , typename T >
Args &	read_with (const char *keyword, P parser, T &x)
	Pass an argument to a specified parser.
template<typename P , typename T >
Args &	read_m_with (const char *keyword, P parser, T &x)
template<typename P , typename T >
Args &	read_p_with (const char *keyword, P parser, T &x)
template<typename P , typename T >
Args &	read_mp_with (const char *keyword, P parser, T &x)
template<typename P , typename T >
Args &	read_with (const char *keyword, int flags, P parser, T &x)
template<typename P >
Args &	read_all_with (const char *keyword, P parser)
	Pass all matching arguments to a specified parser.
template<typename P >
Args &	read_all_with (const char *keyword, int flags, P parser)
template<typename P , typename T >
Args &	read_all_with (const char *keyword, P parser, T &x)
	Pass all matching arguments to a specified parser.
template<typename P , typename T >
Args &	read_all_with (const char *keyword, int flags, P parser, T &x)
template<typename P , typename T >
Args &	read_all (const char *keyword, P parser, Vector< T > &x)
	Pass all matching arguments to a specified parser.
template<typename T >
Args &	read_all (const char *keyword, Vector< T > &x)
template<typename P , typename T >
Args &	read_all (const char *keyword, int flags, P parser, Vector< T > &x)
template<typename P , typename T >
Args &	read_all (const char *keyword, int flags, Vector< T > &x)
bool	status () const
	Return the current parse status.
Args &	status (bool &x)
	Set x to the current parse status.
const Args &	status (bool &x) const
bool	read_status () const
	Return true iff the last read request succeeded.
Args &	read_status (bool &x)
	Set x to the success status of the last read request.
const Args &	read_status (bool &x) const
Args &	strip ()
	Remove all arguments matched so far.
int	execute ()
	Assign results.
int	consume ()
	Assign results and remove matched arguments.
int	complete ()
	Assign results if all arguments matched.
template<typename T >
T *	slot (T &x)
	Create and return a result slot for x.
template<typename T >
T *	initialized_slot (T &x)
	Create and return a result slot for x.
template<typename T , typename V >
Args &	set (T &x, const V &value)
	Add a result that assigns x to value.
Public Member Functions inherited from ArgContext
	ArgContext (ErrorHandler *errh=0)
	Construct an argument context.
	ArgContext (const Element *context, ErrorHandler *errh=0)
	Construct an argument context.
const Element *	context () const
	Return the element context.
ErrorHandler *	errh () const
	Return the associated error handler.
String	error_prefix () const
	Return a prefix string associated with the current argument.
void	error (const char *fmt,...) const
	Report a parse error for the current argument.
void	warning (const char *fmt,...) const
	Report a parse warning for the current argument.
void	message (const char *fmt,...) const
	Report a message for the current argument.
void	xmessage (const String &anno, const String &str) const
void	xmessage (const String &anno, const char *fmt, va_list val) const

Static Public Attributes
static constexpr int	mandatory = 1
	read flag for mandatory arguments
static constexpr int	positional = 2
	read flag for positional arguments
static constexpr int	deprecated = 4
	read flag for deprecated arguments
static constexpr int	firstmatch = 8
	read flag to take first matching argument

Additional Inherited Members
Protected Attributes inherited from ArgContext
const Element *	_context
ErrorHandler *	_errh
const char *	_arg_keyword
bool	_read_status

Detailed Description

Argument parser class.

never

Args parses Click configuration strings in a type-safe manner.

Args manages arguments and result slots. Arguments are strings to be parsed and result slots are parsed values.

The read() functions parse arguments into result slots.

Args args;
args.push_back("A 1"); // add argument
 
int a_result;
args.read("A", a_result); // parse "A" into a result slot

As arguments are parsed, Args marks them off and adds new result slots. Each result slot is paired with a variable belonging to the caller. However, the caller's variables aren't modified until the parse executes via complete(), consume(), or execute().

Args args; args.push_back("A 1");
 
int a_result = 0;
args.read("A", a_result);
assert(a_result == 0);  // parsed value not yet assigned
args.execute();         // this call assigns results
assert(a_result == 1);

If Args encounters a parse error, then execution doesn't modify any of the caller's variables.

Args args; args.push_back("A 1, B NOT_AN_INTEGER");
 
int a_result = 0, b_result = 0;
args.read("A", a_result)   // succeeds
    .read("B", b_result)   // fails, since B is not an integer
    .execute();
assert(a_result == 0 && b_result == 0);

Each read() function comes in five variants. read() reads an optional keyword argument. read_m() reads a mandatory keyword argument: if the argument was not supplied, Args will report a parse error. read_p() reads an optional positional argument. If the keyword was not supplied, but a positional argument was, that is used. read_mp() reads a mandatory positional argument. Positional arguments are parsed in order. The fifth variant of read() takes an integer flags argument; flags include Args::positional, Args::mandatory, and others, such as Args::deprecated.

The complete() execution method checks that every argument has been successfully parsed and reports an error if not. consume() doesn't check for completion, but removes parsed arguments from the argument set. Execution methods return 0 on success and <0 on failure. You can check the parse status before execution using status().

Args methods are designed to chain. All read() methods (and some others) return a reference to the Args itself. It is often possible to parse a whole set of arguments using a single temporary Args. For example:

Vector<String> conf;
conf.push_back("A 1");
conf.push_back("B 2");
 
int a, b;
if (Args(conf).read("A", a)
    .read("B", b)
    .complete() >= 0)
    click_chatter("Success! a=%d, b=%d", a, b);

The actual work of parsing is handled by parser objects. Many common variable types have default parsers defined by the DefaultArg<T> template. For example, the default parser for an integer value understands the common textual representations of integers. You can also pass a parser explicitly. For example:

int a, b, c;
args.read("A", a)      // parse A using DefaultArg<int> = IntArg()
    .read("B", IntArg(2), b);   // parse B using IntArg(2): base-2

Args generally calls a parser object's parse() method with three arguments:

1. const String &str: The string to be parsed.
2. T &result: A reference to the result. The parsed value, if any, should be stored here. (This points to storage local to Args, not to the caller's variable.)
3. Args &args: A reference to the calling Args object, for error reporting.

The parse() method should return true if the parse succeeds and false if it fails. Type-specific error messages should be reported using methods like args.error(). For generic errors, the parse() method can simply return false; Args will generate a "KEYWORD: parse error" message.

Most parsers are disciplined, meaning that they modify result only if the parse succeeds. This doesn't matter in the context of Args, but can matter to users who call a parse function directly.

Constructor & Destructor Documentation

Args() [1/5]

Args::Args

(

ErrorHandler *

errh = 0

)

Construct an argument parser.

Parameters

errh	optional error handler

Args() [2/5]

Args::Args	(	const Vector< String > &	conf,
		ErrorHandler *	errh = 0
	)

Construct an argument parser parsing a copy of conf.

Parameters

conf	list of configuration arguments
errh	optional error handler

Args() [3/5]

Args::Args	(	const Element *	context,
		ErrorHandler *	errh = 0
	)

Construct an argument parser.

Parameters

context	optional element context
errh	optional error handler

Args() [4/5]

Args::Args	(	const Vector< String > &	conf,
		const Element *	context,
		ErrorHandler *	errh = 0
	)

Construct an argument parser parsing a copy of conf.

Parameters

conf	list of configuration arguments
context	optional element context
errh	optional error handler

Args() [5/5]

Args::Args

(

const Args &

x

)

Copy construct an argument parser.

Note

x's results are not copied.

Member Function Documentation

operator=()

Args & Args::operator=

(

const Args &

x

)

Assign to a copy of x.

Precondition

results_empty() && x.results_empty()

empty()

bool Args::empty ( ) const

inline

Return true iff this parser has no arguments or results.

results_empty()

bool Args::results_empty ( ) const

inline

Return true iff this parser has no results.

clear()

Args & Args::clear ( )

inline

Remove all arguments.

Returns

*this

bind()

Args & Args::bind

(

Vector< String > &

conf

)

Bind this parser's arguments to conf.

Parameters

conf	reference to new arguments

Returns

*this

Postcondition

This Args shares conf with the caller. For instance, consume() will modify conf.

push_back() [1/2]

Args & Args::push_back

(

const String &

arg

)

Append argument arg to this parser.

Returns

*this

push_back() [2/2]

template<typename Iter >

Args & Args::push_back ( Iter  begin, Iter  end  )

inline

Append arguments in the range [begin, end) to this parser.

Returns

*this

push_back_words()

Args & Args::push_back_words

(

const String &

str

)

Append the space-separated words in str to this parser.

Returns

*this

push_back_args()

Args & Args::push_back_args

(

const String &

str

)

Append the comma-separated arguments in str to this parser.

Returns

*this

reset()

Args & Args::reset ( )

inline

Reset the parse status for every argument.

Returns

*this

For example:

Vector<String> conf; conf.push_back("1"); conf.push_back("2");
int a, b;
Args(conf).read_p("A", a).read_p("B", b).execute();
assert(a == 1 && b == 2);
Args(conf).read_p("A", a).reset().read_p("B", b).execute();
assert(a == 1 && b == 1);

Results are not affected.

read() [1/3]

template<typename T >

Args & Args::read ( const char *  keyword, T &  x  )

inline

Read an argument using its type's default parser.

Parameters

keyword	argument name
x	reference to result

Returns

*this

Creates a result slot for x and calls DefaultArg<T>().parse(string, result, *this).

read_or_set() [1/2]

template<typename T , typename V >

Args & Args::read_or_set ( const char *  keyword, T &  x, const V &  default_value  )

inline

Read an argument using the default parser, or set it to a default value if the argument is was not supplied.

Parameters

keyword	argument name
x	reference to result
default_value	default value

Returns

*this

Creates a result slot for x. If keyword was supplied, calls DefaultArg<T>().parse(string, result, this). Otherwise, assigns the result to value.

validate()

Args & Args::validate ( const char *  keyword, bool  present = false  )

inline

Verify a value is given

read() [2/3]

template<typename P , typename T >

Args & Args::read ( const char *  keyword, P  parser, T &  x  )

inline

Read an argument using a specified parser.

Parameters

keyword	argument name
parser	parser object
x	reference to result

Returns

*this

Creates a result slot for x and calls parser.parse(string, result, *this).

read_or_set() [2/2]

template<typename P , typename T , typename V >

Args & Args::read_or_set ( const char *  keyword, P  parser, T &  x, const V &  default_value  )

inline

Read an argument using a specified parser, or set it to a default value if the argument is was not supplied.

Parameters

keyword	argument name
parser	parser object
x	reference to result variable
default_value	default value

Returns

*this

Creates a result slot for x. If argument keyword was supplied, calls parser.parse(string, result, *this). Otherwise, assigns the result to default_value.

read() [3/3]

template<typename P , typename T1 , typename T2 >

Args & Args::read ( const char *  keyword, P  parser, T1 &  x1, T2 &  x2  )

inline

Read an argument using a specified parser with two results.

Parameters

keyword	argument name
parser	parser object
x1	reference to first result
x2	reference to second result

Returns

*this

Creates results for x1 and x2 and calls parser.parse(string, result1, result2, *this).

read_with() [1/2]

template<typename P >

Args & Args::read_with ( const char *  keyword, P  parser  )

inline

Pass an argument to a specified parser.

Parameters

keyword	argument name
parser	parser object

Returns

*this

Calls parser.parse(string, *this).

read_with() [2/2]

template<typename P , typename T >

Args & Args::read_with ( const char *  keyword, P  parser, T &  x  )

inline

Pass an argument to a specified parser.

Parameters

keyword	argument name
parser	parser object
x	reference to result

Returns

*this

Creates a result slot for x and calls parser.parse(string, result, *this).

Deprecated:

Use read(keyword, parser, variable) instead.

read_all_with() [1/2]

template<typename P >

Args & Args::read_all_with ( const char *  keyword, P  parser  )

inline

Pass all matching arguments to a specified parser.

Parameters

keyword	argument name
parser	parser object

Returns

*this

Calls parser.parse(string, *this) zero or more times.

Note

The value of read_status() is true iff at least one argument matched and all matching arguments successfully parsed.

read_all_with() [2/2]

template<typename P , typename T >

Args & Args::read_all_with ( const char *  keyword, P  parser, T &  x  )

inline

Pass all matching arguments to a specified parser.

Parameters

keyword	argument name
parser	parser object
x	reference to result

Returns

*this

Creates a result for x and calls parser.parse(string, result, *this) zero or more times, once per matching argument.

Note

The value of read_status() is true iff at least one argument matched and all matching arguments successfully parsed.

read_all()

template<typename P , typename T >

Args & Args::read_all ( const char *  keyword, P  parser, Vector< T > &  x  )

inline

Pass all matching arguments to a specified parser.

Parameters

keyword	argument name
parser	parser object
x	reference to vector of results

Returns

*this

For each keyword argument, calls parser.parse(string, value, *this). The resulting values are collected into a vector result slot for x.

Note

The value of read_status() is true iff at least one argument matched and all matching arguments successfully parsed.

status() [1/3]

bool Args::status ( ) const

inline

Return the current parse status.

status() [2/3]

Args & Args::status ( bool &  x )

inline

Set x to the current parse status.

Returns

*this

status() [3/3]

const Args & Args::status ( bool &  x ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

read_status() [1/3]

bool Args::read_status ( ) const

inline

Return true iff the last read request succeeded.

This function should only be called after a read.

read_status() [2/3]

Args & Args::read_status ( bool &  x )

inline

Set x to the success status of the last read request.

This function should only be called after a read.

read_status() [3/3]

const Args & Args::read_status ( bool &  x ) const

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

strip()

Args & Args::strip

(

)

Remove all arguments matched so far.

execute()

int Args::execute

(

)

Assign results.

Returns

0 if the parse succeeded, <0 otherwise

Postcondition

results_empty()

Results are only assigned if status() is true (the parse is successful so far). Clears results as a side effect.

consume()

int Args::consume

(

)

Assign results and remove matched arguments.

Returns

0 if the parse succeeded, <0 otherwise

Postcondition

results_empty()

Matched arguments are always removed. Results are only assigned if status() is true (the parse is successful so far). Clears results as a side effect.

complete()

int Args::complete

(

)

Assign results if all arguments matched.

Returns

0 if the parse succeeded, <0 otherwise

Postcondition

results_empty()

Results are only assigned if status() is true (the parse is successful so far) and all arguments have been parsed. Clears results as a side effect.

slot()

template<typename T >

T * Args::slot ( T &  x )

inline

Create and return a result slot for x.

If T is a trivially copyable type, such as int, then the resulting slot might not be initialized.

initialized_slot()

template<typename T >

T * Args::initialized_slot ( T &  x )

inline

Create and return a result slot for x.

The resulting slot is always default-initialized.

set()

template<typename T , typename V >

Args & Args::set ( T &  x, const V &  value  )

inline

Add a result that assigns x to value.

Returns

*this

Member Data Documentation

mandatory

constexpr int Args::mandatory = 1

staticconstexpr

read flag for mandatory arguments

positional

constexpr int Args::positional = 2

staticconstexpr

read flag for positional arguments

deprecated

constexpr int Args::deprecated = 4

staticconstexpr

read flag for deprecated arguments

firstmatch

constexpr int Args::firstmatch = 8

staticconstexpr

read flag to take first matching argument

---

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

• include/click/args.hh
• lib/args.cc