hpx/program_options/options_description.hpp

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx
namespace program_options
class duplicate_option_error : public hpx::program_options::error
#include <options_description.hpp>

Class thrown when duplicate option description is found.

Public Functions

duplicate_option_error(const std::string &xwhat)
class option_description
#include <options_description.hpp>

Describes one possible command line/config file option. There are two kinds of properties of an option. First describe it syntactically and are used only to validate input. Second affect interpretation of the option, for example default value for it or function that should be called when the value is finally known. Routines which perform parsing never use second kind of properties – they are side effect free.

See

options_description

Public Types

enum match_result

Values:

no_match
full_match
approximate_match

Public Functions

option_description()
option_description(const char *name, const value_semantic *s)

Initializes the object with the passed data.

Note: it would be nice to make the second parameter auto_ptr, to explicitly pass ownership. Unfortunately, it’s often needed to create objects of types derived from ‘value_semantic’: options_description d; d.add_options()(“a”, parameter<int>(“n”)->default_value(1)); Here, the static type returned by ‘parameter’ should be derived from value_semantic.

Alas, derived->base conversion for auto_ptr does not really work, see http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#84

So, we have to use plain old pointers. Besides, users are not expected to use the constructor directly.

The ‘name’ parameter is interpreted by the following rules:

  • if there’s no “,” character in ‘name’, it specifies long name

  • otherwise, the part before “,” specifies long name and the part after – short name.

option_description(const char *name, const value_semantic *s, const char *description)

Initializes the class with the passed data.

virtual ~option_description()
match_result match(const std::string &option, bool approx, bool long_ignore_case, bool short_ignore_case) const

Given ‘option’, specified in the input source, returns ‘true’ if ‘option’ specifies *this.

const std::string &key(const std::string &option) const

Returns the key that should identify the option, in particular in the variables_map class. The ‘option’ parameter is the option spelling from the input source. If option name contains ‘*’, returns ‘option’. If long name was specified, it’s the long name, otherwise it’s a short name with pre-pended ‘-‘.

std::string canonical_display_name(int canonical_option_style = 0) const

Returns the canonical name for the option description to enable the user to recognized a matching option. 1) For short options (‘-‘, ‘/’), returns the short name prefixed. 2) For long options (‘’ / ‘-‘) returns the first long name prefixed 3) All other cases, returns the first long name (if present) or the short name, un-prefixed.

const std::string &long_name() const
const std::pair<const std::string*, std::size_t> long_names() const
const std::string &description() const

Explanation of this option.

std::shared_ptr<const value_semantic> semantic() const

Semantic of option’s value.

std::string format_name() const

Returns the option name, formatted suitably for usage message.

std::string format_parameter() const

Returns the parameter name and properties, formatted suitably for usage message.

Private Functions

option_description &set_names(const char *name)

Private Members

std::string m_short_name

a one-character “switch” name - with its prefix, so that this is either empty or has length 2 (e.g. “-c”

std::vector<std::string> m_long_names

one or more names by which this option may be specified on a command-line or in a config file, which are not a single-letter switch. The names here are without any prefix.

std::string m_description
std::shared_ptr<const value_semantic> m_value_semantic
class options_description
#include <options_description.hpp>

A set of option descriptions. This provides convenient interface for adding new option (the add_options) method, and facilities to search for options by name.

See here for option adding interface discussion.

See

option_description

Public Functions

options_description(unsigned line_length = m_default_line_length, unsigned min_description_length = m_default_line_length / 2)

Creates the instance.

options_description(const std::string &caption, unsigned line_length = m_default_line_length, unsigned min_description_length = m_default_line_length / 2)

Creates the instance. The ‘caption’ parameter gives the name of this ‘options_description’ instance. Primarily useful for output. The ‘description_length’ specifies the number of columns that should be reserved for the description text; if the option text encroaches into this, then the description will start on the next line.

void add(std::shared_ptr<option_description> desc)

Adds new variable description. Throws duplicate_variable_error if either short or long name matches that of already present one.

options_description &add(const options_description &desc)

Adds a group of option description. This has the same effect as adding all option_descriptions in ‘desc’ individually, except that output operator will show a separate group. Returns *this.

std::size_t get_option_column_width() const

Find the maximum width of the option column, including options in groups.

options_description_easy_init add_options()

Returns an object of implementation-defined type suitable for adding options to options_description. The returned object will have overloaded operator() with parameter type matching ‘option_description’ constructors. Calling the operator will create new option_description instance and add it.

const option_description &find(const std::string &name, bool approx, bool long_ignore_case = false, bool short_ignore_case = false) const
const option_description *find_nothrow(const std::string &name, bool approx, bool long_ignore_case = false, bool short_ignore_case = false) const
const std::vector<std::shared_ptr<option_description>> &options() const
void print(std::ostream &os, std::size_t width = 0) const

Outputs ‘desc’ to the specified stream, calling ‘f’ to output each option_description element.

Public Static Attributes

const unsigned m_default_line_length

Private Types

using name2index_iterator = std::map<std::string, int>::const_iterator
using approximation_range = std::pair<name2index_iterator, name2index_iterator>

Private Members

std::string m_caption
const std::size_t m_line_length
const std::size_t m_min_description_length
std::vector<std::shared_ptr<option_description>> m_options
std::vector<char> belong_to_group
std::vector<std::shared_ptr<options_description>> groups

Friends

std::ostream &operator<<(std::ostream &os, const options_description &desc)

Produces a human readable output of ‘desc’, listing options, their descriptions and allowed parameters. Other options_description instances previously passed to add will be output separately.

class options_description_easy_init
#include <options_description.hpp>

Class which provides convenient creation syntax to option_description.

Public Functions

options_description_easy_init(options_description *owner)
options_description_easy_init &operator()(const char *name, const char *description)
options_description_easy_init &operator()(const char *name, const value_semantic *s)
options_description_easy_init &operator()(const char *name, const value_semantic *s, const char *description)

Private Members

options_description *owner