Describes a valid program command-line option. More...

#include <option.hpp>

Public Types
enum	arg_type { string_arg, int_arg, uint_arg, double_arg }
	Holds the possible argument types.

Public Member Functions
	option () noexcept
	Default constructor. More...

	option (char short_name)
	Construct an option with a given short name. More...

	option (const std::string &long_name, char short_name='\0', const std::string &description="", const std::string &arg_name="", bool arg_required=false)
	Construct an option with given information. More...

option &	name (const std::string &long_name, char short_name='\0')
	Sets the long and short name for the option. More...

std::string	name () const noexcept
	Returns a name for the option. More...

option &	long_name (const std::string &name)
	Set the option's long name. More...

const std::string &	long_name () const noexcept
	Retrieve the option's long name. More...

option &	short_name (char name) noexcept
	Set the option's short name. More...

char	short_name () const noexcept
	Retrieve the option's short name. More...

option &	argument (const std::string &name, bool required=true)
	Set the option's argument information. More...

const std::string &	argument_name () const noexcept
	Retrieve the option's argument name. More...

bool	is_argument_required () const noexcept
	Return true if the argument is mandatory. More...

arg_type	argument_type () const noexcept
	Return the type of argument. More...

option &	bind_bool (bool *var) noexcept
	Designates a location to store whether the option was set. More...

option &	bind_string (std::string *var) noexcept
	Designates that the option should take a string argument which should be stored in `*var`. More...

option &	bind_int (int *var) noexcept
	Designates that the option should take an integer argument which should be stored in `*var`. More...

option &	bind_uint (unsigned int *var) noexcept
	Designates that the option should take an unsigned integer argument which should be stored in `*var`. More...

option &	bind_double (double *var) noexcept
	Designates that the option should take a double-precision floating point argument which should be stored in `*var`. More...

bool	has_bound_argument_variable () const noexcept
	Returns true if a variable has been bound to the option's argument. More...

void	write_bool (bool value) const noexcept
	Writes to the bound boolean variable that was specified in `bind_bool`. More...

void	write_string (const std::string &value) const
	Writes to the bound string variable that was specified in `bind_string`. More...

void	write_int (int value) const
	Writes to the bound integer variable that was specified in `bind_int`. More...

void	write_uint (unsigned int value) const
	Writes to the bound unsigned integer variable that was specified in `bind_uint`. More...

void	write_double (double value) const
	Writes to the bound double variable that was specified in `bind_double`. More...

option &	description (const std::string &desc)
	Set the option description. More...

const std::string &	description () const noexcept
	Retrieve the option description. More...

Detailed Description

Describes a valid program command-line option.

A option can hold information about a program option that the user can pass through the command line. Among this information, the most important are the long name and the short name.

If an option has a long name, then the user can specify that option using a double-hyphen. For example, --version would specify an option with a long name of version.

If an option has a short name, then the user can specify the option with a single hyphen. For example -v would specify an option with a short name of v. Short names are always a single character, and can be combined in a single command-line argument. For example, the command-line argument -xvf specifies three different options: one with a short name of x, another with short name v, and another with f.

Program options can accept arguments. These can be mandatory or optional. The argument name (set in the name parameter of the argument method) is used in the help text and usage string.

A description and a group name can be set as well. These are used in generating the program help text.

Note that many of the methods in the class return a reference to the current instance. This allows for convenient chaining. For example, to create an option with a long name of help, a short name of ?, and an appropriate description, one could write:

option help_opt{};

help_opt.long_name("help").short_name('?').description("Show help text.");

Constructor & Destructor Documentation

◆ option() [1/3]

optionpp::option::option ( )

inlinenoexcept

Default constructor.

Constructs an option without initial information.

◆ option() [2/3]

optionpp::option::option ( char short_name )

inline

Construct an option with a given short name.

Other fields are left empty.

Parameters

short_name The short name for the option.

◆ option() [3/3]

optionpp::option::option	(	const std::string &	long_name,
		char	short_name = `'\0'`,
		const std::string &	description = `""`,
		const std::string &	arg_name = `""`,
		bool	arg_required = `false`
	)

Construct an option with given information.

The argument, description, and group fields are left empty.

Parameters

long_name	The long name for the option.
short_name	The short name for the option.
description	Description of the option.
arg_name	Name of the option's argument, if any (usually uppercase).
arg_required	Set to true if argument is mandatory.

Member Function Documentation

◆ argument()

option & optionpp::option::argument	(	const std::string &	name,
		bool	required = `true`
	)

Set the option's argument information.

The name is used in the program help text and usage string.

Parameters

name	Name of the argument (usually all uppercase).
required	True if the option is mandatory, false if it is optional.

Returns: Reference to the current instance (for chaining calls).

◆ argument_name()

const std::string& optionpp::option::argument_name ( ) const

inlinenoexcept

Retrieve the option's argument name.

This is the name that is used in the help text.

Returns: The name of the argument.

◆ argument_type()

arg_type optionpp::option::argument_type ( ) const

inlinenoexcept

Return the type of argument.

Returns: Expected argument type.

◆ bind_bool()

option & optionpp::option::bind_bool ( bool * var )

noexcept

Designates a location to store whether the option was set.

If the option is encountered on the command line, the bound value is set to true. Otherwise, it is set to false.

Parameters

var	Address of boolean to set.

Returns: Reference to the current instance (for chaining calls).

◆ bind_double()

option & optionpp::option::bind_double ( double * var )

noexcept

Designates that the option should take a double-precision floating point argument which should be stored in *var.

If a non-numeric argument is given, then the parser will throw a parse_error exception.

Parameters

var	Address of double to receive argument value.

Returns: Reference to the current instance (for chaining calls).

◆ bind_int()

option & optionpp::option::bind_int ( int * var )

noexcept

Designates that the option should take an integer argument which should be stored in *var.

If a non-integer argument is given, then the parser will throw a parse_error exception.

Parameters

var	Address of integer to receive argument value.

Returns: Reference to the current instance (for chaining calls).

◆ bind_string()

option & optionpp::option::bind_string ( std::string * var )

noexcept

Designates that the option should take a string argument which should be stored in *var.

Parameters

var	Address of string to receive argument value.

Returns: Reference to the current instance (for chaining calls).

◆ bind_uint()

option & optionpp::option::bind_uint ( unsigned int * var )

noexcept

Designates that the option should take an unsigned integer argument which should be stored in *var.

If a non-integer argument is given, or if a negative integer is encountered, then the parser will throw a parse_error exception.

Parameters

var	Address of unsigned int to receive argument value.

Returns: Reference to the current instance (for chaining calls).

◆ description() [1/2]

const std::string& optionpp::option::description ( ) const

inlinenoexcept

Retrieve the option description.

Returns: Option description, used in generating program help text.

◆ description() [2/2]

option& optionpp::option::description ( const std::string & desc )

inline

Set the option description.

This description is used in generating the program help text.

Parameters

desc	Description of the option.

Returns: Reference to the current instance (for chaining calls).

◆ has_bound_argument_variable()

bool optionpp::option::has_bound_argument_variable ( ) const

inlinenoexcept

Returns true if a variable has been bound to the option's argument.

Note that binding a boolean value to the option does not affect the return value of this method.

Returns: True if a variable is bound, false otherwise.

◆ is_argument_required()

bool optionpp::option::is_argument_required ( ) const

inlinenoexcept

Return true if the argument is mandatory.

Returns: True if the argument is required and false if it is optional.

◆ long_name() [1/2]

const std::string& optionpp::option::long_name ( ) const

inlinenoexcept

Retrieve the option's long name.

Returns: The long name for the option.

◆ long_name() [2/2]

option& optionpp::option::long_name ( const std::string & name )

inline

Set the option's long name.

Parameters

name	The long name to use.

Returns: Reference to the current instance (for chaining calls).

◆ name() [1/2]

std::string optionpp::option::name ( ) const

inlinenoexcept

Returns a name for the option.

This will be the long name if it exists, otherwise the short name is used. If neither name is set, returns an empty string.

Returns: Option name.

◆ name() [2/2]

option& optionpp::option::name	(	const std::string &	long_name,
		char	short_name = `'\0'`
	)

inline

Sets the long and short name for the option.

Parameters

long_name	Long name form for the option.
short_name	Single-character short option name.

Returns: Reference to the current instance (for chaining calls).

◆ short_name() [1/2]

char optionpp::option::short_name ( ) const

inlinenoexcept

Retrieve the option's short name.

Returns: The single-character short name for the option.

◆ short_name() [2/2]

option& optionpp::option::short_name ( char name )

inlinenoexcept

Set the option's short name.

Parameters

name	The character to use as the short name.

Returns: Reference to the current instance (for chaining calls).

◆ write_bool()

void optionpp::option::write_bool ( bool value ) const

noexcept

Writes to the bound boolean variable that was specified in bind_bool.

It is safe to call this function even when no boolean variable is currently bound. Doing so is effectively a no-op.

Parameters

value Value to write to the bound bool variable.

◆ write_double()

void optionpp::option::write_double ( double value ) const

Writes to the bound double variable that was specified in bind_double.

This method should not be called unless a double variable was previously bound. You can use the argument_type method to check what type of argument the option expects.

Exceptions

type_error If no double variable was bound.

Parameters

value Value to write to the bound double variable.

◆ write_int()

void optionpp::option::write_int ( int value ) const

Writes to the bound integer variable that was specified in bind_int.

This method should not be called unless an int variable was previously bound. You can use the argument_type method to check what type of argument the option expects.

Exceptions

type_error If no int variable was bound.

Parameters

value Value to write to the bound int variable.

◆ write_string()

void optionpp::option::write_string ( const std::string & value ) const

Writes to the bound string variable that was specified in bind_string.

This method should not be called unless a string variable was previously bound. You can use the argument_type method to check what type of argument the option expects.

Exceptions

type_error If no string variable was bound.

Parameters

value Value to write to the bound string variable.

◆ write_uint()

void optionpp::option::write_uint ( unsigned int value ) const

Writes to the bound unsigned integer variable that was specified in bind_uint.

This method should not be called unless an unsigned int variable was previously bound. You can use the argument_type method to check what type of argument the option expects.

Exceptions

type_error If no unsigned int variable was bound.

Parameters

value Value to write to the bound unsigned int variable.

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

/home/gkikola/Code/optionpp/include/optionpp/option.hpp
/home/gkikola/Code/optionpp/src/option.cpp

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ option() [1/3]

◆ option() [2/3]

◆ option() [3/3]

Member Function Documentation

◆ argument()

◆ argument_name()

◆ argument_type()

◆ bind_bool()

◆ bind_double()

◆ bind_int()

◆ bind_string()

◆ bind_uint()

◆ description() [1/2]

◆ description() [2/2]

◆ has_bound_argument_variable()

◆ is_argument_required()

◆ long_name() [1/2]

◆ long_name() [2/2]

◆ name() [1/2]

◆ name() [2/2]

◆ short_name() [1/2]

◆ short_name() [2/2]

◆ write_bool()

◆ write_double()

◆ write_int()

◆ write_string()

◆ write_uint()