Detailed Description

A group of options.

option_group is the basis for organizing options. It can hold a number of basic_value objects. These are typically also its members:

struct my_option_group : public option_group {
    value<> opt1;
    value<bool> opt2;
    ...

    my_option_group()
        : option_group(nullptr, "My option group")
        , opt1(this, "opt1", ...
        , opt2(this, "opt2", ...
        , ...
    { }
};

Option groups can also be nested and using this property one can build a tree of option groups and values. This tree then can be visited using the two visitor methods exposed by option_group:

Using these two visitors one can easily implement glue code to expose an entire options tree to the command line. Use describe() to build the command-line level description of the objects (using e.g. boost::program_options) and after parsing the provided command-line options use mutate() to propagate the extracted values back into the options tree. How this is done is entirely up to the visitors, the above methods only offer an API to visit each group and value in the tree, they don't make any assumption about how the visitor works and what its purpose is.

#include <seastar/util/program-options.hh>

Inheritance diagram for seastar::program_options::option_group:

Public Types
using	value_list_type = boost::intrusive::list< basic_value, boost::intrusive::base_hook< list_base_hook >, boost::intrusive::constant_time_size< false > >

using	option_group_list_type = boost::intrusive::list< option_group, boost::intrusive::base_hook< list_base_hook >, boost::intrusive::constant_time_size< false > >

Public Member Functions
	option_group (option_group *parent, std::string name)

	option_group (option_group *parent, std::string name, unused)

	option_group (option_group &&)

	option_group (const option_group &)=delete

option_group &	operator= (option_group &&)=delete

option_group &	operator= (const option_group &)=delete

	operator bool () const
	Does the option group has any values contained in it?

bool	used () const

const std::string &	name () const

const value_list_type &	values () const

value_list_type &	values ()

void	describe (options_descriptor &descriptor) const

void	mutate (options_mutator &mutator)

Constructor & Destructor Documentation

◆ option_group() [1/2]

seastar::program_options::option_group::option_group	(	option_group *	parent,
		std::string	name
	)

explicit

Construct an option group.

Parameters

parent	- the parent option-group, this option group will become a sub option group of the parent group
name	- the name of the option group

◆ option_group() [2/2]

seastar::program_options::option_group::option_group	(	option_group *	parent,
		std::string	name,
		unused
	)

explicit

Construct an unused option group.

Parameters

parent	- the parent option-group, this option group will become a sub option group of the parent group
name	- the name of the option group

Member Function Documentation

◆ describe()

void seastar::program_options::option_group::describe ( options_descriptor & descriptor ) const

Describe the content of this option group to the visitor.

The content is visited in a depth-first manner:

First the option groups itself is visited with options_descriptor::visit_group_start(). If this returns false the entire content of the group, including all its subgroups and values are skipped and options_descriptor::visit_group_end() is called immediately. Otherwise visiting the content of the group proceeds.
All the values contained therein are visited. For each value the following happens:
- First options_descriptor::visit_value_metadata() is called with generic metadata that all values have. If this return false the value is skipped, otherwise visiting the value proceeds.
- Then the appropriate overload of options_descriptor::visit_value() is called, with a pointer to the default value of the respective value. The pointer is null if there is no default value.
- For selection_value, options_descriptor::visit_selection_value() will be called instead of options_descriptor::visit_value(). After the value is visited, the option_group instance belonging to each candidate (if set) will be visited.
All the nested option_group instances in the current group are visited.
Finally options_descriptor::visit_group_end() is called.

◆ mutate()

void seastar::program_options::option_group::mutate ( options_mutator & mutator )

Mutate the content of this option group by the visitor.

The visiting algorithm is identical to that of describe(), with the following differences:

options_mutator::visit_value() is allowed to mutate the value through the passed-in reference. It should return true if it did so and false otherwise.
When visiting a selection value, only the nested group belonging to the selected value is visited afterwards.

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

seastar/util/program-options.hh