flow::cfg::Option_set_base Class Reference

Un-templated base for Option_set. More...

#include <option_set.hpp>

Inheritance diagram for flow::cfg::Option_set_base:

Public Types
enum class	Declare_options_func_call_type {   S_FILL_PARSING_ROLE_OPT_TABLE , S_FILL_OUTPUT_HELP_ROLE_OPT_TABLE , S_FILL_OUTPUT_CURRENT_ROLE_OPT_TABLE , S_COMPARE_PARSED_VALS ,   S_LOAD_VALS_AS_IF_PARSED , S_VALIDATE_STORED_VALS }
	Internal-use type to use with Option_set::Declare_options_func callback. More...

Static Public Member Functions
template<typename Value >
static void	declare_option_for_output (util::String_view name, opts::options_description *target_opts, const Value &value_default, const Value &current_value, util::String_view description)
	Internal-through-macro helper function; the user shall not call this directly but only through FLOW_CFG_OPTION_SET_DECLARE_OPTION() (see Option_set main constructor doc header). More...
template<typename Value >
static void	validate_parsed_option (util::String_view name, const Value &value, Function< bool(const Value &val)> &&validator_func_moved, util::String_view validator_cond_str)
	Internal-through-macro helper function; the user shall not call this directly but only through FLOW_CFG_OPTION_SET_DECLARE_OPTION() (see Option_set main constructor doc header). More...

Protected Types
using	Opt_table = opts::options_description
	Short-hand for boost.program_options config options description, each of which is used for parsing and/or describing (to humans) one or more config option/its value. More...

Static Protected Member Functions
template<typename Value >
static Function< void(const Value &val)>	throw_on_invalid_func (util::String_view name, Function< bool(const Value &val)> &&validator_func_moved, util::String_view validator_cond_str)
	Returns a function that wraps a Value->Boolean validator function, as passed to declare_option_for_parsing() and others, in code that will throw an exception with a human-useful message if that validator function indicates the Value passed to it is invalid; else will no-op. More...

Detailed Description

Un-templated base for Option_set.

Definition at line 33 of file option_set.hpp.

Member Typedef Documentation

Opt_table

using flow::cfg::Option_set_base::Opt_table = opts::options_description

protected

Short-hand for boost.program_options config options description, each of which is used for parsing and/or describing (to humans) one or more config option/its value.

boost.program_options allows for a wide variety of features and capacities for this object type, but our goal is to use it for our specific and more constrained config context, and hence we use this type in more specific/constrained ways which we describe here.

We use it in our context in two primary roles; and since storage space and processor cycle are not practically affected, we tend to store separate copies of an Opt_table in each role (possibly even more than 1, as there can be sub-roles of each). The roles are:

• Parsing: Used during a parsing pass from a given config source (like a config file) solely to parse values and store the resulting bits into a target Values and a mirroring Iterable_values. opts::{parse_*|store}() and other such functions take this Opt_table and a config source as input. Such an Opt_table stores a table of options; for each option storing:
  • Name: A string to be found in a config source like a config file.
  • C++ type: Essentially a size in bytes plus a >> stream input operator for reading values into the target location from the config source.
  • Target location: Pointer to the actual value, within a Values, which to load with the parsed bits obtained from the config source.
  • NOTE: There is no default value stores in this parsing-role Opt_table. We expect each target value to already contain the default before parsing begins; if the option is not present in the particular config source, then that value remains untouched. Moreover note that the pre-parse value is not necessarily the user-specified default per se; it might be, for example, the value set by the previous config source's parsing phase; or even (in the case of dynamic option sets) in a much earlier config application.
  • Note: There's no reason to store a textual description for this role, as the computer doesn't care about human explanations when parsing.
• Output: Used in various settings to print out – to humans – both the semantic info and actual values of the options maintained by an Option_set. To use this capability of boost.program_options – which it intends as help text, but we can leverage it in slightly different roles also – simply output this output-role Opt_table via a stream <<. For each option:
  • Name: Same as for the parsing-role.
  • Description: Textual description of the meaning/semantics of the option.
    • If it's not output of help text/similar, then description might be omitted, depending on usefulness.
  • C++ type: Essentially a size in bytes plus a << stream output operator for writing values via standard stream output.
  • Value: A pointer to a value to print out along with the previous name and description. boost.program_options supports printing in one 2 ways:
    • Via << stream output operator. In this case that operator needs to be (conceptually) stored too.
    • As an explicit string. Sometimes, for human readability, we might want to provide custom output for certain types beyond what << would do; for example if we store a Fine_duration (typically outputting which would be in nanoseconds, because it usually stores nanoseconds), it's often more convenient to round down (if precision would not be lost) and output using coarser units like sec or even minutes, etc. In this case we would prepare this value as an std::string and store that; instead of storing a value in the original type as in parsing-role Opt_table. At least these reasons exist to print this value:
    • As the default in a help message. The user would glean that not specifying a value in any config source will lead to this value being taken.
    • As the current stored value after the last round of parsing. If it is also desired to output a default at the same time, it can be added into the description.

Definition at line 216 of file option_set.hpp.

Member Enumeration Documentation

Declare_options_func_call_type

enum class flow::cfg::Option_set_base::Declare_options_func_call_type

strong

Internal-use type to use with Option_set::Declare_options_func callback.

The user of the class need not understand this nor use it directly.

The reason for the Option_set::Declare_options_func call, originally from FLOW_CFG_OPTION_SET_DECLARE_OPTION().

Enumerator
S_FILL_PARSING_ROLE_OPT_TABLE	Internal use only through macro. Do not use directly. Add option entries into Option_set::m_opts_for_parsing using Option_set::declare_option_for_parsing().
S_FILL_OUTPUT_HELP_ROLE_OPT_TABLE	Internal use only through macro. Do not use directly. Add option entries into Option_set::m_opts_for_help using Option_set::declare_option_for_help().
S_FILL_OUTPUT_CURRENT_ROLE_OPT_TABLE	Internal use only through macro. Do not use directly. Add option entries into an Option_set::Opt_table that shall be output to an ostream to print a Value_set's payload, using declare_option_for_output().
S_COMPARE_PARSED_VALS	Internal use only through macro. Do not use directly. Compare recently parsed values in Option_set::m_iterable_values_candidate to the canonical Option_set::m_values values, using Option_set::scan_parsed_option().
S_LOAD_VALS_AS_IF_PARSED	Internal use only through macro. Do not use directly. Load values in Option_set::m_values_candidate and Option_set::m_iterable_values_candidate from a ready-made Value_set – as if the latter was parsed from some config source – using load_option_value_as_if_parsed().
S_VALIDATE_STORED_VALS	Internal use only through macro. Do not use directly. Validate values stored – perhaps manually in code, not through parsing – in a Value_set structure using the same per-individual-option validator checks as configured into Option_set::m_opts_for_parsing via Declare_options_func_call_type::S_FILL_PARSING_ROLE_OPT_TABLE, using validate_parsed_option().

Definition at line 46 of file option_set.hpp.

Member Function Documentation

declare_option_for_output()

template<typename Value >

void flow::cfg::Option_set_base::declare_option_for_output ( util::String_view  name, opts::options_description *  target_opts, const Value &  value_default, const Value &  current_value, util::String_view  description  )

static

Internal-through-macro helper function; the user shall not call this directly but only through FLOW_CFG_OPTION_SET_DECLARE_OPTION() (see Option_set main constructor doc header).

Loads an entry into target_opts which will enable the proper text to appear for that option in Option_set::values_to_ostream() or Option_set::log_values(): including its name, default value, current values, and description.

Template Parameters

Value

Type of the value inside a Value_set object. It must be reasonably copyable; and it must be supported by some version (including specialization(s) and overload(s)) of value_to_ostream().

Parameters

name	See Option_set::declare_option_for_parsing().
target_opts	The Opt_table that shall be filled out for output to ostream.
value_default	See Option_set::declare_option_for_help().
current_value	Current value to show to the user.
description	See Option_set::declare_option_for_help().

Definition at line 1669 of file option_set.hpp.

References flow::cfg::value_to_ostream().

Here is the call graph for this function:

throw_on_invalid_func()

template<typename Value >

Function< void(const Value &val)> flow::cfg::Option_set_base::throw_on_invalid_func ( util::String_view  name, Function< bool(const Value &val)> &&  validator_func_moved, util::String_view  validator_cond_str  )

staticprotected

Returns a function that wraps a Value->Boolean validator function, as passed to declare_option_for_parsing() and others, in code that will throw an exception with a human-useful message if that validator function indicates the Value passed to it is invalid; else will no-op.

Template Parameters

Value

See Option_set::declare_option_for_parsing().

Parameters

name	See Option_set::declare_option_for_parsing(). For nice human-readable message formation.
validator_func_moved	See Option_set::declare_option_for_parsing().
validator_cond_str	See Option_set::declare_option_for_parsing(). For nice human-readable message formation.

Returns

See above.

Definition at line 1610 of file option_set.hpp.

References flow::util::String_ostream::os(), and flow::cfg::value_to_ostream().

Referenced by validate_parsed_option().

Here is the call graph for this function:

Here is the caller graph for this function:

validate_parsed_option()

template<typename Value >

void flow::cfg::Option_set_base::validate_parsed_option ( util::String_view  name, const Value &  value, Function< bool(const Value &val)> &&  validator_func_moved, util::String_view  validator_cond_str  )

static

Internal-through-macro helper function; the user shall not call this directly but only through FLOW_CFG_OPTION_SET_DECLARE_OPTION() (see Option_set main constructor doc header).

Runs the validator function, with the same semantics as in declare_option_for_parsing(), for the given option. If the validation passes, no-op. If the validation fails throws exception containing (in its message) a user-friendly description of what failed.

Template Parameters

Value

Type of the value inside a Value_set object. It must be reasonably copyable.

Parameters

name	See Option_set::declare_option_for_parsing().
value	Value to validate.
validator_func_moved	See Option_set::declare_option_for_parsing().
validator_cond_str	See Option_set::declare_option_for_parsing().

Definition at line 1773 of file option_set.hpp.

References throw_on_invalid_func().

Here is the call graph for this function:

---

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

• cfg/option_set.hpp