program_options

The contents of this module can be included with the header hpx/modules/program_options.hpp. These headers may be used by user-code but are not guaranteed stable (neither header location nor contents). You are using these at your own risk. If you wish to use non-public functionality from a module we strongly suggest only including the module header hpx/modules/program_options.hpp, not the particular header in which the functionality you would like to use is defined. See Public API for a list of names that are part of the public HPX API.

namespace hpx

namespace program_options

namespace command_line_style

Enums

enum style_t

Various possible styles of options.

There are “long” options, which start with “–” and “short”, which start with either “-” or “/”. Both kinds can be allowed or disallowed, see allow_long and allow_short. The allowed character for short options is also configurable.

Option’s value can be specified in the same token as name (“–foo=bar”), or in the next token.

It’s possible to introduce long options by the same character as short options, see allow_long_disguise.

Finally, guessing (specifying only prefix of option) and case insensitive processing are supported.

Values:

allow_long = 1

Allow “–long_name” style.

allow_short = allow_long << 1

Allow “-<single character” style.

allow_dash_for_short = allow_short << 1

Allow “-” in short options.

allow_slash_for_short = allow_dash_for_short << 1

Allow “/” in short options.

long_allow_adjacent = allow_slash_for_short << 1

Allow option parameter in the same token for long option, like in

        --foo=10

long_allow_next = long_allow_adjacent << 1

Allow option parameter in the next token for long options.

short_allow_adjacent = long_allow_next << 1

Allow option parameter in the same token for short options.

short_allow_next = short_allow_adjacent << 1

Allow option parameter in the next token for short options.

allow_sticky = short_allow_next << 1

Allow to merge several short options together, so that “-s -k” become “-sk”. All of the options but last should accept no parameter. For example, if “-s” accept a parameter, then “k” will be taken as parameter, not another short option. Dos-style short options cannot be sticky.

allow_guessing = allow_sticky << 1

Allow abbreviated spellings for long options, if they unambiguously identify long option. No long option name should be prefix of other long option name if guessing is in effect.

long_case_insensitive = allow_guessing << 1

Ignore the difference in case for long options.

short_case_insensitive = long_case_insensitive << 1

Ignore the difference in case for short options.

case_insensitive = (long_case_insensitive | short_case_insensitive)

Ignore the difference in case for all options.

allow_long_disguise = short_case_insensitive << 1

Allow long options with single option starting character, e.g -foo=10

unix_style = (allow_short | short_allow_adjacent | short_allow_next | allow_long | long_allow_adjacent | long_allow_next | allow_sticky | allow_guessing | allow_dash_for_short)

The more-or-less traditional unix style.

default_style = unix_style

The default style.

namespace hpx

namespace program_options

Typedefs

using any = hpx::any_nonser

template<typename T>
using optional = hpx::util::optional<T>

namespace hpx

namespace program_options

class environment_iterator : public hpx::program_options::eof_iterator<environment_iterator, std::pair<std::string, std::string>>

Public Functions

environment_iterator(char **environment)

environment_iterator()

void get()

Private Members

char **m_environment

namespace hpx

namespace program_options

template<class Derived, class ValueType>
class eof_iterator : public util::iterator_facade<Derived, ValueType const, std::forward_iterator_tag>

#include <eof_iterator.hpp>

The ‘eof_iterator’ class is useful for constructing forward iterators in cases where iterator extract data from some source and it’s easy to detect ‘eof’ – i.e. the situation where there’s no data. One apparent example is reading lines from a file.

Implementing such iterators using ‘iterator_facade’ directly would require to create class with three core operation, a couple of constructors. When using ‘eof_iterator’, the derived class should define only one method to get new value, plus a couple of constructors.

The basic idea is that iterator has ‘eof’ bit. Two iterators are equal only if both have their ‘eof’ bits set. The ‘get’ method either obtains the new value or sets the ‘eof’ bit.

Specifically, derived class should define:

1. A default constructor, which creates iterator with ‘eof’ bit set. The constructor body should call ‘found_eof’ method defined here.

2. Some other constructor. It should initialize some ‘data pointer’ used in iterator operation and then call ‘get’.

3. The ‘get’ method. It should operate this way:

   • look at some ‘data pointer’ to see if new element is available; if not, it should call ‘found_eof’.

   • extract new element and store it at location returned by the ‘value’ method.

   • advance the data pointer.

Essentially, the ‘get’ method has the functionality of both ‘increment’ and ‘dereference’. It’s very good for the cases where data extraction implicitly moves data pointer, like for stream operation.

Public Functions

eof_iterator()

Protected Functions

ValueType &value()

Returns the reference which should be used by derived class to store the next value.

void found_eof()

Should be called by derived class to indicate that it can’t produce next element.

Private Functions

void increment()

bool equal(const eof_iterator &other) const

const ValueType &dereference() const

Private Members

bool m_at_eof

ValueType m_value

Friends

friend hpx::program_options::hpx::util::iterator_core_access

namespace hpx

namespace program_options

Functions

std::string strip_prefixes(const std::string &text)

class ambiguous_option : public hpx::program_options::error_with_no_option_name

#include <errors.hpp>

Class thrown when there’s ambiguity among several possible options.

Public Functions

ambiguous_option(const std::vector<std::string> &xalternatives)

~ambiguous_option()

const std::vector<std::string> &alternatives() const

Protected Functions

void substitute_placeholders(const std::string &error_template) const

Makes all substitutions using the template

Private Members

std::vector<std::string> m_alternatives

class error : public logic_error

#include <errors.hpp>

Base class for all errors in the library.

Subclassed by hpx::program_options::duplicate_option_error, hpx::program_options::error_with_option_name, hpx::program_options::invalid_command_line_style, hpx::program_options::reading_file, hpx::program_options::too_many_positional_options_error

Public Functions

error(const std::string &xwhat)

class error_with_no_option_name : public hpx::program_options::error_with_option_name

#include <errors.hpp>

Base class of un-parsable options, when the desired option cannot be identified.

It makes no sense to have an option name, when we can’t match an option to the parameter

Having this a part of the error_with_option_name hierarchy makes error handling a lot easier, even if the name indicates some sort of conceptual dissonance!

Subclassed by hpx::program_options::ambiguous_option, hpx::program_options::unknown_option

Public Functions

error_with_no_option_name(const std::string &template_, const std::string &original_token = "")

void set_option_name(const std::string&)

Does NOT set option name, because no option name makes sense

~error_with_no_option_name()

class error_with_option_name : public hpx::program_options::error

#include <errors.hpp>

Base class for most exceptions in the library.

Substitutes the values for the parameter name placeholders in the template to create the human readable error message

Placeholders are surrounded by % signs: example% Poor man’s version of boost::format

If a parameter name is absent, perform default substitutions instead so ugly placeholders are never left in-place.

Options are displayed in “canonical” form This is the most unambiguous form of the parsed option name and would correspond to option_description::format_name() i.e. what is shown by print_usage()

The “canonical” form depends on whether the option is specified in short or long form, using dashes or slashes or without a prefix (from a configuration file)

Subclassed by hpx::program_options::error_with_no_option_name, hpx::program_options::invalid_syntax, hpx::program_options::multiple_occurrences, hpx::program_options::multiple_values, hpx::program_options::required_option, hpx::program_options::validation_error

Public Functions

error_with_option_name(const std::string &template_, const std::string &option_name = "", const std::string &original_token = "", int option_style = 0)

~error_with_option_name()

gcc says that throw specification on dtor is loosened without this line

void set_substitute(const std::string &parameter_name, const std::string &value)

Substitute parameter_name->value to create the error message from the error template

void set_substitute_default(const std::string &parameter_name, const std::string &from, const std::string &to)

If the parameter is missing, then make the from->to substitution instead

void add_context(const std::string &option_name, const std::string &original_token, int option_style)

Add context to an exception

void set_prefix(int option_style)

virtual void set_option_name(const std::string &option_name)

Overridden in error_with_no_option_name

std::string get_option_name() const

void set_original_token(const std::string &original_token)

const char *what() const

Creates the error_message on the fly Currently a thin wrapper for substitute_placeholders()

Public Members

std::string m_error_template

template with placeholders

Protected Types

using string_pair = std::pair<std::string, std::string>

Protected Functions

virtual void substitute_placeholders(const std::string &error_template) const

Makes all substitutions using the template

void replace_token(const std::string &from, const std::string &to) const

std::string get_canonical_option_name() const

Construct option name in accordance with the appropriate prefix style: i.e. long dash or short slash etc

std::string get_canonical_option_prefix() const

Protected Attributes

int m_option_style

can be 0 = no prefix (config file options) allow_long allow_dash_for_short allow_slash_for_short allow_long_disguise

std::map<std::string, std::string> m_substitutions

substitutions from placeholders to values

std::map<std::string, string_pair> m_substitution_defaults

std::string m_message

Used to hold the error text returned by what()

class invalid_bool_value : public hpx::program_options::validation_error

#include <errors.hpp>

Class thrown if there is an invalid bool value given

Public Functions

invalid_bool_value(const std::string &value)

class invalid_command_line_style : public hpx::program_options::error

#include <errors.hpp>

Class thrown when there are programming error related to style

Public Functions

invalid_command_line_style(const std::string &msg)

class invalid_command_line_syntax : public hpx::program_options::invalid_syntax

#include <errors.hpp>

Class thrown when there are syntax errors in given command line

Public Functions

invalid_command_line_syntax(kind_t kind, const std::string &option_name = "", const std::string &original_token = "", int option_style = 0)

~invalid_command_line_syntax()

class invalid_config_file_syntax : public hpx::program_options::invalid_syntax

Public Functions

invalid_config_file_syntax(const std::string &invalid_line, kind_t kind)

~invalid_config_file_syntax()

std::string tokens() const

Convenience functions for backwards compatibility

class invalid_option_value : public hpx::program_options::validation_error

#include <errors.hpp>

Class thrown if there is an invalid option value given

Public Functions

invalid_option_value(const std::string &value)

invalid_option_value(const std::wstring &value)

class invalid_syntax : public hpx::program_options::error_with_option_name

#include <errors.hpp>

Class thrown when there’s syntax error either for command line or config file options. See derived children for concrete classes.

Subclassed by hpx::program_options::invalid_command_line_syntax, hpx::program_options::invalid_config_file_syntax

Public Types

enum kind_t

Values:

long_not_allowed = 30

long_adjacent_not_allowed

short_adjacent_not_allowed

empty_adjacent_parameter

missing_parameter

extra_parameter

unrecognized_line

Public Functions

invalid_syntax(kind_t kind, const std::string &option_name = "", const std::string &original_token = "", int option_style = 0)

~invalid_syntax()

kind_t kind() const

virtual std::string tokens() const

Convenience functions for backwards compatibility

Protected Functions

std::string get_template(kind_t kind)

Used to convert kind_t to a related error text

Protected Attributes

kind_t m_kind

class multiple_occurrences : public hpx::program_options::error_with_option_name

#include <errors.hpp>

Class thrown when there are several occurrences of an option, but user called a method which cannot return them all.

Public Functions

multiple_occurrences()

~multiple_occurrences()

class multiple_values : public hpx::program_options::error_with_option_name

#include <errors.hpp>

Class thrown when there are several option values, but user called a method which cannot return them all.

Public Functions

multiple_values()

~multiple_values()

class reading_file : public hpx::program_options::error

#include <errors.hpp>

Class thrown if config file can not be read

Public Functions

reading_file(const char *filename)

class required_option : public hpx::program_options::error_with_option_name

#include <errors.hpp>

Class thrown when a required/mandatory option is missing

Public Functions

required_option(const std::string &option_name)

~required_option()

class too_many_positional_options_error : public hpx::program_options::error

#include <errors.hpp>

Class thrown when there are too many positional options. This is a programming error.

Public Functions

too_many_positional_options_error()

class unknown_option : public hpx::program_options::error_with_no_option_name

#include <errors.hpp>

Class thrown when option name is not recognized.

Public Functions

unknown_option(const std::string &original_token = "")

~unknown_option()

class validation_error : public hpx::program_options::error_with_option_name

#include <errors.hpp>

Class thrown when value of option is incorrect.

Subclassed by hpx::program_options::invalid_bool_value, hpx::program_options::invalid_option_value

Public Types

enum kind_t

Values:

multiple_values_not_allowed = 30

at_least_one_value_required

invalid_bool_value

invalid_option_value

invalid_option

Public Functions

validation_error(kind_t kind, const std::string &option_name = "", const std::string &original_token = "", int option_style = 0)

~validation_error()

kind_t kind() const

Protected Functions

std::string get_template(kind_t kind)

Used to convert kind_t to a related error text

Protected Attributes

kind_t m_kind

namespace hpx

namespace program_options

Typedefs

using option = basic_option<char>

using woption = basic_option<wchar_t>

template<class Char>
class basic_option

#include <option.hpp>

Option found in input source. Contains a key and a value. The key, in turn, can be a string (name of an option), or an integer (position in input source) – in case no name is specified. The latter is only possible for command line. The template parameter specifies the type of char used for storing the option’s value.

Public Functions

basic_option()

basic_option(const std::string &xstring_key, const std::vector<std::string> &xvalue)

Public Members

std::string string_key

String key of this option. Intentionally independent of the template parameter.

int position_key

Position key of this option. All options without an explicit name are sequentially numbered starting from 0. If an option has explicit name, ‘position_key’ is equal to -1. It is possible that both position_key and string_key is specified, in case name is implicitly added.

std::vector<std::basic_string<Char>> value

Option’s value

std::vector<std::basic_string<Char>> original_tokens

The original unchanged tokens this option was created from.

bool unregistered

True if option was not recognized. In that case, ‘string_key’ and ‘value’ are results of purely syntactic parsing of source. The original tokens can be recovered from the “original_tokens” member.

bool case_insensitive

True if string_key has to be handled case insensitive.

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

namespace hpx

namespace program_options

Typedefs

using parsed_options = basic_parsed_options<char>

using wparsed_options = basic_parsed_options<wchar_t>

using ext_parser = std::function<std::pair<std::string, std::string>(const std::string&)>

Augments basic_parsed_options<wchar_t> with conversion from ‘parsed_options’

using command_line_parser = basic_command_line_parser<char>

using wcommand_line_parser = basic_command_line_parser<wchar_t>

Enums

enum collect_unrecognized_mode

Controls if the ‘collect_unregistered’ function should include positional options, or not.

Values:

include_positional

exclude_positional

Functions

template<class Char>
basic_parsed_options<Char> parse_command_line(int argc, const Char *const argv[], const options_description&, int style = 0, std::function<std::pair<std::string, std::string>(const std::string&)> ext = ext_parser())

Creates instance of ‘command_line_parser’, passes parameters to it, and returns the result of calling the ‘run’ method.

template<class Char>
basic_parsed_options<Char> parse_config_file(std::basic_istream<Char>&, const options_description&, bool allow_unregistered = false)

Parse a config file.

Read from given stream.

template<class Char = char>
basic_parsed_options<Char> parse_config_file(const char *filename, const options_description&, bool allow_unregistered = false)

Parse a config file.

Read from file with the given name. The character type is passed to the file stream.

template<class Char>
std::vector<std::basic_string<Char>> collect_unrecognized(const std::vector<basic_option<Char>> &options, enum collect_unrecognized_mode mode)

Collects the original tokens for all named options with ‘unregistered’ flag set. If ‘mode’ is ‘include_positional’ also collects all positional options. Returns the vector of original tokens for all collected options.

parsed_options parse_environment(const options_description&, const std::function<std::string(std::string)> &name_mapper)

Parse environment.

For each environment variable, the ‘name_mapper’ function is called to obtain the option name. If it returns empty string, the variable is ignored.

This is done since naming of environment variables is typically different from the naming of command line options.

parsed_options parse_environment(const options_description&, const std::string &prefix)

Parse environment.

Takes all environment variables which start with ‘prefix’. The option name is obtained from variable name by removing the prefix and converting the remaining string into lower case.

parsed_options parse_environment(const options_description&, const char *prefix)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This function exists to resolve ambiguity between the two above functions when second argument is of ‘char*’ type. There’s implicit conversion to both std::function and string.

std::vector<std::string> split_unix(const std::string &cmdline, const std::string &separator = " \t", const std::string &quote = "'\"", const std::string &escape = "\\")

Splits a given string to a collection of single strings which can be passed to command_line_parser. The second parameter is used to specify a collection of possible separator chars used for splitting. The separator is defaulted to space ” “. Splitting is done in a unix style way, with respect to quotes ‘”’ and escape characters ‘'

std::vector<std::wstring> hpx::program_options::split_unix(const std::wstring & cmdline, const std::wstring & separator = L" \t", const std::wstring & quote = L"'\"", const std::wstring & escape = L"\\")

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

template<class Char>
class basic_command_line_parser : private cmdline

#include <parsers.hpp>

Command line parser.

The class allows one to specify all the information needed for parsing and to parse the command line. It is primarily needed to emulate named function parameters – a regular function with 5 parameters will be hard to use and creating overloads with a smaller number of parameters will be confusing.

For the most common case, the function parse_command_line is a better alternative.

There are two typedefs – command_line_parser and wcommand_line_parser, for charT == char and charT == wchar_t cases.

Public Functions

basic_command_line_parser(const std::vector<std::basic_string<Char>> &args)

Creates a command line parser for the specified arguments list. The ‘args’ parameter should not include program name.

basic_command_line_parser(int argc, const Char *const argv[])

Creates a command line parser for the specified arguments list. The parameters should be the same as passed to ‘main’.

basic_command_line_parser &options(const options_description &desc)

Sets options descriptions to use.

basic_command_line_parser &positional(const positional_options_description &desc)

Sets positional options description to use.

basic_command_line_parser &style(int)

Sets the command line style.

basic_command_line_parser &extra_parser(ext_parser)

Sets the extra parsers.

basic_parsed_options<Char> run()

Parses the options and returns the result of parsing. Throws on error.

basic_command_line_parser &allow_unregistered()

Specifies that unregistered options are allowed and should be passed though. For each command like token that looks like an option but does not contain a recognized name, an instance of basic_option<charT> will be added to result, with ‘unrecognized’ field set to ‘true’. It’s possible to collect all unrecognized options with the ‘collect_unrecognized’ function.

basic_command_line_parser &extra_style_parser(style_parser s)

Private Members

const options_description *m_desc

template<class Char>
class basic_parsed_options

#include <parsers.hpp>

Results of parsing an input source. The primary use of this class is passing information from parsers component to value storage component. This class does not makes much sense itself.

Public Functions

basic_parsed_options(const options_description *xdescription, int options_prefix = 0)

Public Members

std::vector<basic_option<Char>> options

Options found in the source.

const options_description *description

Options description that was used for parsing. Parsers should return pointer to the instance of option_description passed to them, and issues of lifetime are up to the caller. Can be NULL.

int m_options_prefix

Mainly used for the diagnostic messages in exceptions. The canonical option prefix for the parser which generated these results, depending on the settings for basic_command_line_parser::style() or cmdline::style(). In order of precedence of command_line_style enums: allow_long allow_long_disguise allow_dash_for_short allow_slash_for_short

template<>
class basic_parsed_options<wchar_t>

#include <parsers.hpp>

Specialization of basic_parsed_options which:

• provides convenient conversion from basic_parsed_options<char>

• stores the passed char-based options for later use.

Public Functions

basic_parsed_options(const basic_parsed_options<char> &po)

Constructs wrapped options from options in UTF8 encoding.

Public Members

std::vector<basic_option<wchar_t>> options

const options_description *description

basic_parsed_options<char> utf8_encoded_options

Stores UTF8 encoded options that were passed to constructor, to avoid reverse conversion in some cases.

int m_options_prefix

Mainly used for the diagnostic messages in exceptions. The canonical option prefix for the parser which generated these results, depending on the settings for basic_command_line_parser::style() or cmdline::style(). In order of precedence of command_line_style enums: allow_long allow_long_disguise allow_dash_for_short allow_slash_for_short

namespace hpx

namespace program_options

class positional_options_description

#include <positional_options.hpp>

Describes positional options.

The class allows to guess option names for positional options, which are specified on the command line and are identified by the position. The class uses the information provided by the user to associate a name with every positional option, or tell that no name is known.

The primary assumption is that only the relative order of the positional options themselves matters, and that any interleaving ordinary options don’t affect interpretation of positional options.

The user initializes the class by specifying that first N positional options should be given the name X1, following M options should be given the name X2 and so on.

Public Functions

positional_options_description()

positional_options_description &add(const char *name, int max_count)

Species that up to ‘max_count’ next positional options should be given the ‘name’. The value of ‘-1’ means ‘unlimited’. No calls to ‘add’ can be made after call with ‘max_value’ equal to ‘-1’.

unsigned max_total_count() const

Returns the maximum number of positional options that can be present. Can return (numeric_limits<unsigned>::max)() to indicate unlimited number.

const std::string &name_for_position(unsigned position) const

Returns the name that should be associated with positional options at ‘position’. Precondition: position < max_total_count()

Private Members

std::vector<std::string> m_names

std::string m_trailing

namespace hpx

namespace program_options

Functions

template<class T>
typed_value<T> *value()

Creates a typed_value<T> instance. This function is the primary method to create value_semantic instance for a specific type, which can later be passed to ‘option_description’ constructor. The second overload is used when it’s additionally desired to store the value of option into program variable.

template<class T>
typed_value<T> *value(T *v)

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

template<class T>
typed_value<T, wchar_t> *wvalue()

Creates a typed_value<T> instance. This function is the primary method to create value_semantic instance for a specific type, which can later be passed to ‘option_description’ constructor.

template<class T>
typed_value<T, wchar_t> *wvalue(T *v)

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

typed_value<bool> *bool_switch()

Works the same way as the ‘value<bool>’ function, but the created value_semantic won’t accept any explicit value. So, if the option is present on the command line, the value will be ‘true’.

typed_value<bool> *bool_switch(bool *v)

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

template<class T, class Char = char>
class typed_value : public hpx::program_options::value_semantic_codecvt_helper<char>, public hpx::program_options::typed_value_base

#include <value_semantic.hpp>

Class which handles value of a specific type.

Public Functions

typed_value(T *store_to)

Ctor. The ‘store_to’ parameter tells where to store the value when it’s known. The parameter can be NULL.

typed_value *default_value(const T &v)

Specifies default value, which will be used if none is explicitly specified. The type ‘T’ should provide operator<< for ostream.

typed_value *default_value(const T &v, const std::string &textual)

Specifies default value, which will be used if none is explicitly specified. Unlike the above overload, the type ‘T’ need not provide operator<< for ostream, but textual representation of default value must be provided by the user.

typed_value *implicit_value(const T &v)

Specifies an implicit value, which will be used if the option is given, but without an adjacent value. Using this implies that an explicit value is optional,

typed_value *value_name(const std::string &name)

Specifies the name used to to the value in help message.

typed_value *implicit_value(const T &v, const std::string &textual)

Specifies an implicit value, which will be used if the option is given, but without an adjacent value. Using this implies that an explicit value is optional, but if given, must be strictly adjacent to the option, i.e.: ‘-ovalue’ or ‘option=value’. Giving ‘-o’ or ‘option’ will cause the implicit value to be applied. Unlike the above overload, the type ‘T’ need not provide operator<< for ostream, but textual representation of default value must be provided by the user.

typed_value *notifier(std::function<void(const T&)> f)

Specifies a function to be called when the final value is determined.

typed_value *composing()

Specifies that the value is composing. See the ‘is_composing’ method for explanation.

typed_value *multitoken()

Specifies that the value can span multiple tokens.

typed_value *zero_tokens()

Specifies that no tokens may be provided as the value of this option, which means that only presence of the option is significant. For such option to be useful, either the ‘validate’ function should be specialized, or the ‘implicit_value’ method should be also used. In most cases, you can use the ‘bool_switch’ function instead of using this method.

typed_value *required()

Specifies that the value must occur.

std::string name() const

Returns the name of the option. The name is only meaningful for automatic help message.

bool is_composing() const

Returns true if values from different sources should be composed. Otherwise, value from the first source is used and values from other sources are discarded.

unsigned min_tokens() const

The minimum number of tokens for this option that should be present on the command line.

unsigned max_tokens() const

The maximum number of tokens for this option that should be present on the command line.

bool is_required() const

Returns true if value must be given. Non-optional value

void xparse(hpx::any_nonser &value_store, const std::vector<std::basic_string<Char>> &new_tokens) const

Creates an instance of the ‘validator’ class and calls its operator() to perform the actual conversion.

virtual bool apply_default(hpx::any_nonser &value_store) const

If default value was specified via previous call to ‘default_value’, stores that value into ‘value_store’. Returns true if default value was stored.

void notify(const hpx::any_nonser &value_store) const

If an address of variable to store value was specified when creating *this, stores the value there. Otherwise, does nothing.

const std::type_info &value_type() const

Private Members

T *m_store_to

std::string m_value_name

hpx::any_nonser m_default_value

std::string m_default_value_as_text

hpx::any_nonser m_implicit_value

std::string m_implicit_value_as_text

bool m_composing

bool m_implicit

bool m_multitoken

bool m_zero_tokens

bool m_required

std::function<void(const T&)> m_notifier

class typed_value_base

#include <value_semantic.hpp>

Base class for all option that have a fixed type, and are willing to announce this type to the outside world. Any ‘value_semantics’ for which you want to find out the type can be dynamic_cast-ed to typed_value_base. If conversion succeeds, the ‘type’ method can be called.

Subclassed by hpx::program_options::typed_value< T, Char >

Public Functions

virtual const std::type_info &value_type() const = 0

virtual ~typed_value_base()

class untyped_value : public hpx::program_options::value_semantic_codecvt_helper<char>

#include <value_semantic.hpp>

Class which specifies a simple handling of a value: the value will have string type and only one token is allowed.

Public Functions

untyped_value(bool zero_tokens = false)

std::string name() const

Returns the name of the option. The name is only meaningful for automatic help message.

unsigned min_tokens() const

The minimum number of tokens for this option that should be present on the command line.

unsigned max_tokens() const

The maximum number of tokens for this option that should be present on the command line.

bool is_composing() const

Returns true if values from different sources should be composed. Otherwise, value from the first source is used and values from other sources are discarded.

bool is_required() const

Returns true if value must be given. Non-optional value

void xparse(hpx::any_nonser &value_store, const std::vector<std::string> &new_tokens) const

If ‘value_store’ is already initialized, or new_tokens has more than one elements, throws. Otherwise, assigns the first string from ‘new_tokens’ to ‘value_store’, without any modifications.

bool apply_default(hpx::any_nonser&) const

Does nothing.

void notify(const hpx::any_nonser&) const

Does nothing.

Private Members

bool m_zero_tokens

class value_semantic

#include <value_semantic.hpp>

Class which specifies how the option’s value is to be parsed and converted into C++ types.

Subclassed by hpx::program_options::value_semantic_codecvt_helper< char >, hpx::program_options::value_semantic_codecvt_helper< wchar_t >

Public Functions

virtual std::string name() const = 0

Returns the name of the option. The name is only meaningful for automatic help message.

virtual unsigned min_tokens() const = 0

The minimum number of tokens for this option that should be present on the command line.

virtual unsigned max_tokens() const = 0

The maximum number of tokens for this option that should be present on the command line.

virtual bool is_composing() const = 0

Returns true if values from different sources should be composed. Otherwise, value from the first source is used and values from other sources are discarded.

virtual bool is_required() const = 0

Returns true if value must be given. Non-optional value

virtual void parse(hpx::any_nonser &value_store, const std::vector<std::string> &new_tokens, bool utf8) const = 0

Parses a group of tokens that specify a value of option. Stores the result in ‘value_store’, using whatever representation is desired. May be be called several times if value of the same option is specified more than once.

virtual bool apply_default(hpx::any_nonser &value_store) const = 0

Called to assign default value to ‘value_store’. Returns true if default value is assigned, and false if no default value exists.

virtual void notify(const hpx::any_nonser &value_store) const = 0

Called when final value of an option is determined.

virtual ~value_semantic()

template<class Char>
class value_semantic_codecvt_helper

#include <value_semantic.hpp>

Helper class which perform necessary character conversions in the ‘parse’ method and forwards the data further.

template<>
class value_semantic_codecvt_helper<char> : public hpx::program_options::value_semantic

#include <value_semantic.hpp>

Helper conversion class for values that accept ascii strings as input. Overrides the ‘parse’ method and defines new ‘xparse’ method taking std::string. Depending on whether input to parse is ascii or UTF8, will pass it to xparse unmodified, or with UTF8->ascii conversion.

Subclassed by hpx::program_options::typed_value< T, Char >, hpx::program_options::untyped_value

Protected Functions

virtual void xparse(hpx::any_nonser &value_store, const std::vector<std::string> &new_tokens) const = 0

Private Functions

void parse(hpx::any_nonser &value_store, const std::vector<std::string> &new_tokens, bool utf8) const

Parses a group of tokens that specify a value of option. Stores the result in ‘value_store’, using whatever representation is desired. May be be called several times if value of the same option is specified more than once.

template<>
class value_semantic_codecvt_helper<wchar_t> : public hpx::program_options::value_semantic

#include <value_semantic.hpp>

Helper conversion class for values that accept ascii strings as input. Overrides the ‘parse’ method and defines new ‘xparse’ method taking std::wstring. Depending on whether input to parse is ascii or UTF8, will recode input to Unicode, or pass it unmodified.

Protected Functions

virtual void xparse(hpx::any_nonser &value_store, const std::vector<std::wstring> &new_tokens) const = 0

Private Functions

void parse(hpx::any_nonser &value_store, const std::vector<std::string> &new_tokens, bool utf8) const

Parses a group of tokens that specify a value of option. Stores the result in ‘value_store’, using whatever representation is desired. May be be called several times if value of the same option is specified more than once.

namespace hpx

namespace program_options

Functions

void store(const basic_parsed_options<char> &options, variables_map &m, bool utf8 = false)

Stores in ‘m’ all options that are defined in ‘options’. If ‘m’ already has a non-defaulted value of an option, that value is not changed, even if ‘options’ specify some value.

void store(const basic_parsed_options<wchar_t> &options, variables_map &m)

Stores in ‘m’ all options that are defined in ‘options’. If ‘m’ already has a non-defaulted value of an option, that value is not changed, even if ‘options’ specify some value. This is wide character variant.

void notify(variables_map &m)

Runs all ‘notify’ function for options in ‘m’.

class abstract_variables_map

#include <variables_map.hpp>

Implements string->string mapping with convenient value casting facilities.

Subclassed by hpx::program_options::variables_map

Public Functions

abstract_variables_map()

abstract_variables_map(const abstract_variables_map *next)

virtual ~abstract_variables_map()

const variable_value &operator[](const std::string &name) const

Obtains the value of variable ‘name’, from *this and possibly from the chain of variable maps.

• if there’s no value in *this.

  • if there’s next variable map, returns value from it

  • otherwise, returns empty value

• if there’s defaulted value

  • if there’s next variable map, which has a non-defaulted value, return that

  • otherwise, return value from *this

• if there’s a non-defaulted value, returns it.

void next(abstract_variables_map *next)

Sets next variable map, which will be used to find variables not found in *this.

Private Functions

virtual const variable_value &get(const std::string &name) const = 0

Returns value of variable ‘name’ stored in *this, or empty value otherwise.

Private Members

const abstract_variables_map *m_next

class variable_value

#include <variables_map.hpp>

Class holding value of option. Contains details about how the value is set and allows to conveniently obtain the value.

Public Functions

variable_value()

variable_value(const hpx::any_nonser &xv, bool xdefaulted)

template<class T>
const T &as() const

If stored value if of type T, returns that value. Otherwise, throws boost::bad_any_cast exception.

template<class T>
T &as()

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

bool empty() const

Returns true if no value is stored.

bool defaulted() const

Returns true if the value was not explicitly given, but has default value.

hpx::any_nonser &value() const

Returns the contained value.

hpx::any_nonser &value()

Returns the contained value.

Private Members

hpx::any_nonser v

bool m_defaulted

std::shared_ptr<const value_semantic> m_value_semantic

Friends

friend hpx::program_options::variables_map

void store(const basic_parsed_options<char> &options, variables_map &m, bool utf8)

Stores in ‘m’ all options that are defined in ‘options’. If ‘m’ already has a non-defaulted value of an option, that value is not changed, even if ‘options’ specify some value.

class variables_map : public hpx::program_options::abstract_variables_map, public std::map<std::string, variable_value>

#include <variables_map.hpp>

Concrete variables map which store variables in real map.

This class is derived from std::map<std::string, variable_value>, so you can use all map operators to examine its content.

Public Functions

variables_map()

variables_map(const abstract_variables_map *next)

const variable_value &operator[](const std::string &name) const

void clear()

void notify()

Private Functions

const variable_value &get(const std::string &name) const

Implementation of abstract_variables_map::get which does ‘find’ in *this.

Private Members

std::set<std::string> m_final

Names of option with ‘final’ values – which should not be changed by subsequence assignments.

std::map<std::string, std::string> m_required

Names of required options, filled by parser which has access to options_description. The map values are the “canonical” names for each corresponding option. This is useful in creating diagnostic messages when the option is absent.

Friends

void store(const basic_parsed_options<char> &options, variables_map &xm, bool utf8)

Stores in ‘m’ all options that are defined in ‘options’. If ‘m’ already has a non-defaulted value of an option, that value is not changed, even if ‘options’ specify some value.

Defines

HPX_PROGRAM_OPTIONS_VERSION

The version of the source interface. The value will be incremented whenever a change is made which might cause compilation errors for existing code.

HPX_PROGRAM_OPTIONS_IMPLICIT_VALUE_NEXT_TOKEN