Utilities

Options

The options library provides classes and functions for the validation of values and the conversion of values to and from YAML.

At the basis is the Value class that is derived from the ValueBase class. The Value class is templated and acts as a container for a value of certain type. For example, Value<double> will hold a double value.

The get or set the contained object, use:

Value<double> v{0.};  // initialize value to 0.
v.get_value();  // retrieve value
v();  // retrieve value
v.set_value(1.);  // set value
v = 1.;  // set value

• Available validators: inrange, clamped, squared, multiplied, notempty

• Predefined values type: Bool, Double, Int, ConstrainedValue, ClampedValue

Example: keep (ordered) list of options.

Double a{1.5, inrange<double>(0.,2.)};
Bool b;

// note that the option will store a reference to the value
// and so the values need to live for as long as the optionlist is used
optionlist.add("value", a);
optionlist.add("nested/enabled", b);

// adding another option with the same name is an error
//Bool c;
//optionlist.add("value", c);

// set value from yaml
c.from_yaml(YAML::Load("false"));

// set options from yaml
optionlist.from_yaml(YAML::Load("{value: 1.0, nested: {enabled: true}}"));

// convert value to yaml
c.to_yaml();

// convert options to yaml with custom error handler
optionlist.to_yaml(error_handler)

// save to yaml file
optionlist.save_yaml("test.yaml", error_handler);

Use of options in falcon processors

1. Declare values as class members in the header file

   options::String option1_{"default_value", options::notempty<std::string>()};
   options::Bool option2_{true};
   

2. Add options in constructor.

   add_option("option1 name", option1_, "description of the option");
   add_option("option2 name", option2_, "description of the option");
   

3. Internally, falcon will parse the processor options and set the values.

   if(option2_())    // option 2 is a boolean
     LOG(INFO) << option1_() ;   // option 1 is a string
   

namespace options

Typedefs

typedef std::function<bool(std::string name, bool required, OptionError error, std::string msg)> option_error_handler

template<typename T>
using ValidatorFunc = std::function<T(const T&)>

using Bool = Value<bool, false>

using NullableBool = Value<bool, true>

using Double = Value<double, false>

using NullableDouble = Value<double, true>

using Int = Value<int, false>

using NullableInt = Value<int, true>

using String = Value<std::string, false>

using NullableString = Value<std::string, true>

Enums

enum class OptionError

Values:

enumerator validation_failed

enumerator conversion_to_yaml_failed

enumerator conversion_from_yaml_failed

enumerator requirement_failed

Functions

bool get_nested_yaml_node(const YAML::Node &root, const std::vector<std::string> &path, YAML::Node &out)

void set_nested_yaml_node(YAML::Node &root, const std::vector<std::string> &path, const YAML::Node &value)

template<typename T>
ValidatorFunc<T> compose(ValidatorFunc<T> f, ValidatorFunc<T> g)

template<typename T>
T generic_fromyaml(const YAML::Node &node)

template<typename T>
YAML::Node generic_toyaml(const T &x)

template<typename T>
std::vector<T> vector_fromyaml(const YAML::Node &node)

class SkipError : public std::runtime_error

Public Functions

inline SkipError(std::string msg = "")

class OptionBase

Subclassed by options::Option< T >

Public Functions

OptionBase(std::string name, ValueBase &value, std::string description = "", bool required = false)

inline OptionBase(const OptionBase &other)

inline OptionBase &operator=(const options::OptionBase &other)

std::string name() const

std::string description() const

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

bool is_required() const

void from_yaml(const YAML::Node &node)

YAML::Node to_yaml() const

OptionBase &required()

OptionBase &optional()

OptionBase &describe(std::string description)

OptionBase &set_null()

bool is_null() const

bool is_nullable() const

template<typename T>
class Option : public options::OptionBase

Public Functions

inline Option(std::string name, T &value, std::string description = "", bool required = false)

inline Option<T> &init(const typename T::ValueType &value)

inline Option<T> &validate(std::function<typename T::ValueType(typename T::ValueType)> validator = {})

template<typename ...Args>
inline Option<T> &dependencies(const Args&&... args)

inline Option<T> &required()

inline Option<T> &optional()

inline Option<T> &describe(std::string description)

inline Option<T> &set_null()

inline const T::ValueType &get_value() const

inline void set_value(const typename T::ValueType &value)

inline void operator=(const typename T::ValueType &value)

inline const T::ValueType &operator()() const

class OptionList

Public Functions

template<typename TValue>
inline void add(std::string name, TValue &value, std::string description = "", bool required = false)

template<typename TValue>
inline void add(const Option<TValue> &value)

OptionBase &operator[](std::string key)

void remove(std::string key)

std::vector<std::string> options() const

std::vector<std::string> required_options() const

bool has_option(std::string name) const noexcept

void from_yaml(const YAML::Node &node, const option_error_handler &handler = {}, bool check = true)

YAML::Node to_yaml(const option_error_handler &handler = {}) const

void load_yaml(std::string filename, const option_error_handler &handler = {})

void save_yaml(std::string filename, const option_error_handler &handler = {}) const

inline std::string list_options()

class ValidationError : public std::runtime_error

Public Functions

inline ValidationError(std::string msg)

class ConversionError : public std::runtime_error

Public Functions

inline ConversionError(std::string msg)

template<typename T>
class validator

Subclassed by options::clamped< T >, options::inrange< T >, options::multiplied< T >, options::notempty< T >, options::positive< T >, options::squared< T >, options::zeroismax< T >

Friends

inline friend auto operator+(const ValidatorFunc<T> &lhs, const ValidatorFunc<T> &rhs)

template<typename T>
class inrange : public options::validator<T>

Public Types

using value_type = T

Public Functions

inline inrange(T min, T max)

inline T operator()(const T &x) const

template<typename T>
class clamped : public options::validator<T>

Public Types

using value_type = T

Public Functions

inline clamped(T min, T max)

inline T operator()(const T &x) const

template<typename T>
class squared : public options::validator<T>

Public Functions

inline T operator()(const T &x) const

template<typename T>
class multiplied : public options::validator<T>

Public Functions

inline multiplied(T multiplier)

inline T operator()(const T &x) const

class invert : public options::validator<bool>

Public Functions

inline bool operator()(const bool &x) const

template<typename T>
class zeroismax : public options::validator<T>

Public Functions

inline T operator()(const T &x)

template<typename T>
class notempty : public options::validator<T>

Public Functions

inline T operator()(const T &x)

template<typename T>
class each : public options::validator<std::vector<T>>

Public Functions

inline each(ValidatorFunc<T> validator)

inline std::vector<T> operator()(const std::vector<T> &x)

template<typename T>
class positive : public options::validator<T>

Public Functions

inline positive(bool strict = false)

inline T operator()(const T &x) const

class isfile : public options::validator<std::string>

Public Functions

inline isfile(bool exists = false)

inline std::string operator()(const std::string &x) const

class isdir : public options::validator<std::string>

Public Functions

inline isdir(bool exists = true, bool create = false)

inline std::string operator()(const std::string &x) const

class ValueBase

Subclassed by options::Value< std::vector< T >, false >, options::Value< ThreadPriority, false >, options::Value< ThreadCore, false >, options::Value< T, false >, options::Value< std::map< std::string, int > >, options::Value< T, Nullable >, options::ValueMap< VT >

Public Functions

inline ValueBase()

inline virtual ~ValueBase()

virtual void from_yaml(const YAML::Node &node) = 0

virtual YAML::Node to_yaml() const = 0

virtual bool is_nullable() const = 0

virtual bool is_null() const = 0

virtual void set_null() = 0

template<typename T, bool Nullable = true>
class Value : public options::ValueBase

Public Types

using ValueType = T

using ValidatorType = ValidatorFunc<T>

Public Functions

inline Value(const T &value, ValidatorType validator = {})

inline Value(ValidatorType validator = {})

inline T validate(T value)

inline virtual void from_yaml(const YAML::Node &node) override

inline virtual YAML::Node to_yaml() const override

inline const T &get_value() const

inline const T &operator()() const

inline void set_value(const T &value)

inline Value<T, Nullable> &operator=(const T &value)

inline Value<T, Nullable> &operator=(const Value<T> &value)

inline void set_validator(ValidatorType validator = {})

inline virtual bool is_nullable() const final

inline virtual bool is_null() const final

inline virtual void set_null() final

template<typename T, bool Nullable = false>
class Vector : public options::Value<std::vector<T>, false>

Public Functions

inline Vector(const std::vector<T> &value = {}, ValidatorFunc<std::vector<T>> validator = {})

inline virtual void from_yaml(const YAML::Node &node) override

template<typename VT>
class ValueMap : public options::ValueBase

Public Types

using ValueType = typename VT::ValueType

Public Functions

inline ValueMap(const VT &value = VT(), const std::map<std::string, ValueType> map = {})

inline void set_map(std::map<std::string, ValueType> m)

inline virtual void from_yaml(const YAML::Node &node)

inline virtual YAML::Node to_yaml() const

inline VT &operator[](const std::string &key)

inline std::map<std::string, ValueType> get_map() const

inline std::map<std::string, ValueType> operator()() const

inline virtual bool is_nullable() const

inline virtual bool is_null() const

inline virtual void set_null()

template<typename T>
class measurement_toyaml

Public Functions

inline measurement_toyaml(units::precise_unit u)

inline YAML::Node operator()(const T &x)

template<typename T>
class measurement_fromyaml

Public Functions

inline measurement_fromyaml(units::precise_unit u)

inline T operator()(const YAML::Node &node)

template<typename T, bool Nullable = false>
class Measurement : public options::Value<T, false>

Public Functions

inline Measurement(T value, std::string u, ValidatorFunc<T> validator = {}, std::vector<std::string> alt = {})

inline void set_repr_unit(std::string s)

inline units::precise_unit unit() const

inline std::string to_string() const

inline virtual void from_yaml(const YAML::Node &node) override

inline virtual YAML::Node to_yaml() const override

inline Measurement<T, Nullable> &operator=(const T &value)

inline Measurement<T, Nullable> &operator=(const Value<T> &value)

Factory

namespace factory

Typedefs

template<typename AbstractObject, typename ...Args>
using ObjectCreator = AbstractObject *(*)(Args&&...)

Functions

template<typename Base, typename Derived, typename ...Args>
Base *createInstance(Args&&... args)

class UnknownClass : public std::runtime_error

Public Functions

inline UnknownClass(std::string const &error)

class DuplicateClass : public std::runtime_error

Public Functions

inline DuplicateClass(std::string const &error)

template<typename AbstractObject, typename IdentifierType, typename ...Args>
class ObjectFactory

Public Functions

inline AbstractObject *create(const IdentifierType &id, Args... args)

inline bool hasClass(const IdentifierType &id)

inline bool registerClass(const IdentifierType &id, ObjectCreator<AbstractObject, Args...> creator)

inline std::vector<IdentifierType> listEntries() const

Public Static Functions

static inline ThisClass &instance()