Un-templated base for Option_set.
More...
#include <option_set.hpp>
|
| 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...
|
| |
|
| 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...
|
| |
Un-templated base for Option_set.
◆ Opt_table
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.
◆ Declare_options_func_call_type
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.
| Enumerator |
|---|
| S_FILL_PARSING_ROLE_OPT_TABLE | Internal use only through macro.
Do not use directly.
|
| S_FILL_OUTPUT_HELP_ROLE_OPT_TABLE | Internal use only through macro.
Do not use directly.
|
| S_FILL_OUTPUT_CURRENT_ROLE_OPT_TABLE | Internal use only through macro.
Do not use directly.
|
| S_COMPARE_PARSED_VALS | Internal use only through macro.
Do not use directly.
|
| S_LOAD_VALS_AS_IF_PARSED | Internal use only through macro.
Do not use directly.
|
| S_VALIDATE_STORED_VALS | Internal use only through macro.
Do not use directly.
|
◆ 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).
- 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
-
◆ 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
-
- Parameters
-
- Returns
- See above.
◆ 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).
- Template Parameters
-
| Value | Type of the value inside a Value_set object. It must be reasonably copyable. |
- Parameters
-
The documentation for this class was generated from the following file:
