![]() |
aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
|
Sectioned key/value configuration with typed and documented keys. More...
#include <agrum/base/core/configuration/configuration.h>
Classes | |
| struct | Meta |
| metadata attached to a key by a ### line More... | |
| struct | SchemaEntry |
| one line of the schema (see schema()) More... | |
| struct | Notice |
| a message that cannot be an exception (the operation went on), see takeNotices() More... | |
| struct | DefaultsSource |
| a text of defaults, with the name designating it in error messages More... | |
| struct | Item |
Public Types | |
| enum class | Kind : unsigned char { INT , FLOAT , BOOL , STR , ENUM , DEPRECATED } |
| the declared type of a key More... | |
| using | Value = std::variant< bool, std::int64_t, double, std::string > |
| a value converted according to the declared type of its key (see getValue()) | |
| using | Hook = std::function< void(const Configuration&) > |
Public Member Functions | |
Accessors | |
| std::string | get (std::string_view section, std::string_view key) const |
| Value of section.key, as a string. | |
| template<typename T> | |
| T | typed (std::string_view section, std::string_view key) const |
| Value of section.key converted according to its declared type. | |
| Value | getValue (std::string_view section, std::string_view key) const |
| Value of section.key converted according to its declared type (following a deprecation). | |
| bool | has (std::string_view section, std::string_view key) const |
| Meta | meta (std::string_view section, std::string_view key) const |
| std::string | doc (std::string_view section, std::string_view key) const |
| std::vector< SchemaEntry > | schema () const |
| std::vector< std::string > | sections () const |
Modifiers | |
| void | set (std::string_view section, std::string_view key, std::string_view value, bool noHook=false) |
| Sets section.key. | |
| void | reset () |
| Back to the defaults. Runs the hooks. | |
| void | push () |
| Pushes the current values on a stack. | |
| void | pop () |
| Restores the values on top of the stack. | |
Files and display | |
| void | load (const std::string &filename) |
| Loads a user file and changes the values it contains. | |
| void | save (const std::string &filename) const |
| Writes the difference with the defaults (see diff()) in a file. | |
| std::string | grep (std::string_view search) const |
| std::string | diff () const |
| std::string | toString () const |
| std::string | describe () const |
Numerical tolerances | |
| double | epsilonCoarse () const noexcept |
| The coarse tolerance (key core.epsilonCoarse, 1e-2 by default). | |
| double | epsilonStandard () const noexcept |
| double | epsilonFine () const noexcept |
Hooks and notices | |
| void | addHook (Hook hook) |
| Adds a function called after each change (see set(), reset(), pop(), load()). | |
| void | runHooks () const |
| Runs the hooks (outside of any lock). | |
| std::vector< Notice > | takeNotices () |
Static Public Member Functions | |
| static std::string | kindName (Kind kind) |
Private Types | |
| using | Snapshot = std::vector< std::string > |
Private Member Functions | |
| void | _parse_ (std::string_view text, std::string_view origin) |
| void | _groupBySection_ () |
| void | _checkSchema_ () |
| std::size_t | _tryFind_ (std::string_view section, std::string_view key) const |
| std::size_t | _find_ (std::string_view section, std::string_view key) const |
| bool | _hasSection_ (std::string_view section) const |
| std::size_t | _resolve_ (std::size_t pos, std::vector< Notice > *sink=nullptr) const |
| std::pair< std::string, Kind > | _typedRaw_ (std::string_view section, std::string_view key) const |
| void | _setAt_ (std::size_t pos, std::string_view value) |
| void | _loadUserFile_ () |
| std::string | _render_ (const std::function< bool(const Item &) > &keep) const |
| Snapshot | _snapshot_ () const |
| void | _restore_ (const Snapshot &snapshot) |
| void | _refreshEpsilons_ () |
| void | _queue_ (Notice::Kind kind, std::string message) const |
Static Private Member Functions | |
| static std::string | _indexKey_ (std::string_view section, std::string_view key) |
| static bool | _validate_ (const Item &item, std::string_view value, std::string &canonical, std::string &error) |
Private Attributes | |
| std::shared_mutex | _mutex_ |
| std::vector< Item > | _items_ |
| std::vector< std::string > | _sections_ |
| std::unordered_map< std::string, std::size_t > | _index_ |
| std::vector< Snapshot > | _stack_ |
| std::vector< Hook > | _hooks_ |
| std::array< std::atomic< double >, _nbEpsilons_ > | _epsilons_ {{1e-2, 1e-6, 1e-10}} |
| std::array< std::size_t, _nbEpsilons_ > | _epsilonPos_ {} |
| std::mutex | _noticeMutex_ |
| std::vector< Notice > | _notices_ |
Static Private Attributes | |
| static constexpr std::size_t | _nbEpsilons_ = 3 |
| static constexpr std::size_t | _npos_ = static_cast< std::size_t >(-1) |
Constructors, destructor and singleton | |
| static Configuration & | instance () |
| The global configuration. | |
| static std::string | userFileName () |
| Configuration (std::string_view defaultsText, std::string_view origin="defaults.ini") | |
| Builds a configuration from a defaults text. | |
| Configuration (std::initializer_list< DefaultsSource > sources) | |
| Builds a configuration from several defaults texts (e.g. | |
| Configuration (const Configuration &)=delete | |
| The global configuration. | |
| Configuration & | operator= (const Configuration &)=delete |
| The global configuration. | |
| ~Configuration ()=default | |
| The global configuration. | |
Sectioned key/value configuration with typed and documented keys.
Values are stored as strings and canonicalized according to the declared type of their key: booleans are stored as True or False (accepted spellings, whatever the case: TRUE, 1, ON, YES / FALSE, 0, OFF, NO), enumerated values with the casing declared in the defaults.
Section names are case-sensitive, key names are not (they are stored in lowercase).
Thread-safety: every public method is thread-safe (readers run concurrently, writers are exclusive). Values are returned by copy. Hooks are run outside of any lock, so a hook may freely read the configuration.
See also the howto How to use the configuration singleton (gum::Configuration) (syntax of the defaults, hooks, notices, examples).
Errors:
Definition at line 105 of file configuration.h.
| using gum::Configuration::Hook = std::function< void(const Configuration&) > |
Definition at line 161 of file configuration.h.
|
private |
Definition at line 378 of file configuration.h.
| using gum::Configuration::Value = std::variant< bool, std::int64_t, double, std::string > |
a value converted according to the declared type of its key (see getValue())
Definition at line 141 of file configuration.h.
|
strong |
the declared type of a key
| Enumerator | |
|---|---|
| INT | |
| FLOAT | |
| BOOL | |
| STR | |
| ENUM | |
| DEPRECATED | |
Definition at line 108 of file configuration.h.
|
explicit |
Builds a configuration from a defaults text.
| defaultsText | the content of a defaults ini. |
| origin | the name used in error messages to designate the defaults text. |
| SyntaxError | if the text or its metadata are malformed, or if a deprecated key points to an unknown (or itself deprecated) key. |
| InvalidArgument | if a default value does not respect its own declared type. |
Definition at line 319 of file configuration.cpp.
References Configuration().
Referenced by Configuration(), Configuration(), ~Configuration(), instance(), and operator=().
|
explicit |
Builds a configuration from several defaults texts (e.g.
those of aGrUM and of pyAgrum).
The sources are read in order. A section may be opened by several sources (the keys of the later ones are added to the section), but only once inside a source. A key can be defined only once, whatever the sources. In the resulting configuration, the keys of a section are grouped: those of the first source defining the section come first. A source whose text is empty is ignored. A deprecated key may point to a key defined by another source.
| sources | the defaults texts, in reading order. |
| SyntaxError | if a text or its metadata are malformed, if a section is opened twice in a source, if a key is defined twice, or if a deprecated key points to an unknown (or itself deprecated) key. |
| InvalidArgument | if a default value does not respect its own declared type. |
Definition at line 323 of file configuration.cpp.
References _checkSchema_(), _epsilonPos_, _groupBySection_(), _nbEpsilons_, _parse_(), _refreshEpsilons_(), and _tryFind_().
|
delete |
The global configuration.
Built at first call from the defaults embedded in the library (those of aGrUM and, for a pyAgrum build, those of pyAgrum). If the user file (see userFileName()) exists in the current directory, it is loaded: it can change the value of a key but never creates one (problems are queued in the notices, see takeNotices()).
References Configuration().
|
default |
The global configuration.
Built at first call from the defaults embedded in the library (those of aGrUM and, for a pyAgrum build, those of pyAgrum). If the user file (see userFileName()) exists in the current directory, it is loaded: it can change the value of a key but never creates one (problems are queued in the notices, see takeNotices()).
References Configuration(), addHook(), describe(), diff(), doc(), epsilonCoarse(), epsilonFine(), epsilonStandard(), get(), getValue(), grep(), has(), instance(), load(), meta(), pop(), push(), reset(), runHooks(), save(), schema(), sections(), set(), takeNotices(), toString(), typed(), and userFileName().
|
private |
Definition at line 432 of file configuration.cpp.
References _items_, _npos_, _tryFind_(), _validate_(), DEPRECATED, GUM_ERROR, GUM_SYNTAX_ERROR, and meta().
Referenced by Configuration().
|
private |
Definition at line 484 of file configuration.cpp.
References _hasSection_(), _npos_, _tryFind_(), and GUM_SYNTAX_ERROR.
Referenced by _typedRaw_(), doc(), get(), meta(), and set().
|
private |
Definition at line 415 of file configuration.cpp.
References _index_, _indexKey_(), _items_, and _sections_.
Referenced by Configuration().
|
private |
Definition at line 480 of file configuration.cpp.
References _sections_.
Referenced by _find_(), _parse_(), and load().
|
staticprivate |
Definition at line 468 of file configuration.cpp.
References gum::toLower().
Referenced by _groupBySection_(), _parse_(), and _tryFind_().
|
private |
Definition at line 879 of file configuration.cpp.
References _queue_(), gum::Configuration::Notice::FILE, load(), and userFileName().
Referenced by instance().
|
private |
Definition at line 334 of file configuration.cpp.
References _hasSection_(), _index_, _indexKey_(), _items_, _npos_, _sections_, _tryFind_(), doc(), gum::Configuration::Meta::doc, gum::Configuration::Item::key, gum::Configuration::Item::meta, gum::Configuration::Item::origin, gum::Configuration::Item::section, gum::toLower(), gum::trim_copy(), and gum::Configuration::Item::value.
Referenced by Configuration().
|
private |
Definition at line 493 of file configuration.cpp.
References _noticeMutex_, and _notices_.
Referenced by _loadUserFile_(), _resolve_(), instance(), and load().
|
private |
Definition at line 661 of file configuration.cpp.
References _epsilonPos_, _epsilons_, _items_, _nbEpsilons_, _npos_, and gum::parseDecimal().
Referenced by Configuration(), _restore_(), _setAt_(), load(), reset(), and set().
|
private |
Definition at line 812 of file configuration.cpp.
References _items_, _mutex_, and DEPRECATED.
Referenced by diff(), grep(), and toString().
|
private |
Definition at line 502 of file configuration.cpp.
References _items_, _queue_(), _tryFind_(), DEPRECATED, gum::Configuration::Notice::DEPRECATION, gum::Configuration::Notice::kind, and gum::Configuration::Notice::message.
Referenced by _typedRaw_(), get(), load(), and set().
|
private |
Definition at line 708 of file configuration.cpp.
References _items_, and _refreshEpsilons_().
Referenced by pop().
|
private |
Definition at line 651 of file configuration.cpp.
References _epsilonPos_, _items_, _refreshEpsilons_(), _validate_(), and GUM_ERROR.
Referenced by set().
|
private |
|
private |
Definition at line 475 of file configuration.cpp.
References _index_, _indexKey_(), and _npos_.
Referenced by Configuration(), _checkSchema_(), _find_(), _parse_(), _resolve_(), has(), and load().
|
private |
Definition at line 515 of file configuration.cpp.
References _find_(), _items_, _mutex_, and _resolve_().
Referenced by getValue(), and typed().
|
staticprivate |
Definition at line 525 of file configuration.cpp.
References BOOL, gum::Configuration::Meta::Domain::contains(), gum::Configuration::Meta::domain, ENUM, FLOAT, INT, gum::Configuration::Meta::joinedValues(), gum::Configuration::Item::key, gum::Configuration::Meta::kind, gum::Configuration::Item::meta, gum::parseDecimal(), gum::Configuration::Item::section, gum::Configuration::Meta::Domain::text, gum::toLower(), gum::trim_copy(), and gum::Configuration::Meta::values.
Referenced by _checkSchema_(), _setAt_(), and load().
| void gum::Configuration::addHook | ( | Hook | hook | ) |
Adds a function called after each change (see set(), reset(), pop(), load()).
Definition at line 853 of file configuration.cpp.
References _hooks_, and _mutex_.
Referenced by ~Configuration(), and instance().
| std::string gum::Configuration::describe | ( | ) | const |
Definition at line 844 of file configuration.cpp.
References diff(), and toString().
Referenced by ~Configuration().
| std::string gum::Configuration::diff | ( | ) | const |
Definition at line 836 of file configuration.cpp.
References _render_(), gum::Configuration::Item::defaultValue, and gum::Configuration::Item::value.
Referenced by ~Configuration(), describe(), and save().
| std::string gum::Configuration::doc | ( | std::string_view | section, |
| std::string_view | key ) const |
Definition at line 621 of file configuration.cpp.
References _find_(), _items_, _mutex_, DEPRECATED, ENUM, and kindName().
Referenced by ~Configuration(), and _parse_().
|
noexcept |
The coarse tolerance (key core.epsilonCoarse, 1e-2 by default).
The three tolerances of aGrUM are read without any lock nor allocation (an atomic load), so that they can be used in loops. Their domains do not overlap (coarse in [1e-3,1e-1], standard in [1e-8,1e-5], fine in [1e-11,1e-9]), so that fine < standard < coarse always holds : a value out of the domain is refused as any invalid value (see set() and load()).
Definition at line 56 of file configuration_inl.h.
References _epsilons_.
Referenced by ~Configuration(), and gum::IBayesNet< GUM_SCALAR >::check().
|
noexcept |
Definition at line 66 of file configuration_inl.h.
References _epsilons_.
Referenced by ~Configuration().
|
noexcept |
Definition at line 61 of file configuration_inl.h.
References _epsilons_.
Referenced by ~Configuration(), gum::credal::CredalNet< GUM_SCALAR >::_intervalToCredal_(), gum::credal::MultipleInferenceEngine< GUM_SCALAR, BNInferenceEngine >::_updateThreadCredalSets_(), gum::almostDifferentEpsilon(), gum::IBayesNet< GUM_SCALAR >::check(), gum::Rational< GUM_SCALAR >::continuedFracBest(), gum::Rational< GUM_SCALAR >::continuedFracFirst(), gum::Chi2::criticalValue(), gum::credal::LRSWrapper< GUM_SCALAR >::fillV(), gum::IMarkovRandomField< GUM_SCALAR >::operator==(), gum::InfluenceDiagram< GUM_SCALAR >::operator==(), and gum::credal::InferenceEngine< GUM_SCALAR >::updateCredalSets_().
| std::string gum::Configuration::get | ( | std::string_view | section, |
| std::string_view | key ) const |
Value of section.key, as a string.
| SyntaxError | if the section or the key does not exist. |
Definition at line 591 of file configuration.cpp.
References _find_(), _items_, _mutex_, and _resolve_().
Referenced by ~Configuration().
| Configuration::Value gum::Configuration::getValue | ( | std::string_view | section, |
| std::string_view | key ) const |
Value of section.key converted according to its declared type (following a deprecation).
| SyntaxError | if the section or the key does not exist. |
Definition at line 596 of file configuration.cpp.
References _typedRaw_(), BOOL, FLOAT, INT, and gum::parseDecimal().
Referenced by ~Configuration().
| std::string gum::Configuration::grep | ( | std::string_view | search | ) | const |
search, with their section; a matching section name selects the whole section. Definition at line 829 of file configuration.cpp.
References _render_(), gum::contains(), gum::Configuration::Item::key, gum::Configuration::Item::section, and gum::toLower().
Referenced by ~Configuration().
| bool gum::Configuration::has | ( | std::string_view | section, |
| std::string_view | key ) const |
Definition at line 611 of file configuration.cpp.
References _mutex_, _npos_, and _tryFind_().
Referenced by ~Configuration().
|
static |
The global configuration.
Built at first call from the defaults embedded in the library (those of aGrUM and, for a pyAgrum build, those of pyAgrum). If the user file (see userFileName()) exists in the current directory, it is loaded: it can change the value of a key but never creates one (problems are queued in the notices, see takeNotices()).
Definition at line 890 of file configuration.cpp.
References Configuration(), _loadUserFile_(), _queue_(), addHook(), gum::configurationEmbeddedDefaults(), gum::configurationEmbeddedPyAgrumDefaults(), gum::Configuration::Notice::FILE, gum::getMaxNumberOfThreads(), runHooks(), gum::setNumberOfThreads(), and typed().
Referenced by gum::GibbsSampling< GUM_SCALAR >::GibbsSampling(), ~Configuration(), gum::config(), gum::defaultJgumIndent(), gum::ApproximationScheme::setFromConfiguration_(), gum::ApproximationScheme::sizeFromConfiguration_(), and gum::Tensor< GUM_SCALAR >::toString().
|
static |
Definition at line 304 of file configuration.cpp.
References BOOL, DEPRECATED, ENUM, FLOAT, and INT.
Referenced by doc().
| void gum::Configuration::load | ( | const std::string & | filename | ) |
Loads a user file and changes the values it contains.
Runs the hooks.
Unknown sections, unknown keys, invalid values and deprecated keys do not stop the loading: they are queued as notices and the file is never modified (a deprecated key is applied to its replacement; save() writes the replacement, not the deprecated key). Only a malformed line stops the loading, and nothing is changed in this case.
| IOError | if the file cannot be read. |
| SyntaxError | if the file contains a malformed line. |
Definition at line 743 of file configuration.cpp.
References _hasSection_(), _items_, _mutex_, _npos_, _queue_(), _refreshEpsilons_(), _resolve_(), _tryFind_(), _validate_(), gum::Configuration::Notice::FILE, runHooks(), gum::toLower(), and gum::trim_copy().
Referenced by ~Configuration(), and _loadUserFile_().
| Configuration::Meta gum::Configuration::meta | ( | std::string_view | section, |
| std::string_view | key ) const |
Definition at line 616 of file configuration.cpp.
References _find_(), _items_, and _mutex_.
Referenced by ~Configuration(), and _checkSchema_().
|
delete |
The global configuration.
Built at first call from the defaults embedded in the library (those of aGrUM and, for a pyAgrum build, those of pyAgrum). If the user file (see userFileName()) exists in the current directory, it is loaded: it can change the value of a key but never creates one (problems are queued in the notices, see takeNotices()).
References Configuration().
| void gum::Configuration::pop | ( | ) |
Restores the values on top of the stack.
Runs the hooks.
| OperationNotAllowed | if the stack is empty. |
Definition at line 729 of file configuration.cpp.
References _mutex_, _restore_(), _stack_, GUM_ERROR, and runHooks().
Referenced by ~Configuration().
| void gum::Configuration::push | ( | ) |
Pushes the current values on a stack.
Definition at line 724 of file configuration.cpp.
References _mutex_, _snapshot_(), and _stack_.
Referenced by ~Configuration().
| void gum::Configuration::reset | ( | ) |
Back to the defaults. Runs the hooks.
Definition at line 714 of file configuration.cpp.
References _items_, _mutex_, _refreshEpsilons_(), DEPRECATED, and runHooks().
Referenced by ~Configuration().
| void gum::Configuration::runHooks | ( | ) | const |
Runs the hooks (outside of any lock).
Definition at line 858 of file configuration.cpp.
References _hooks_, and _mutex_.
Referenced by ~Configuration(), instance(), load(), pop(), reset(), and set().
| void gum::Configuration::save | ( | const std::string & | filename | ) | const |
Writes the difference with the defaults (see diff()) in a file.
| IOError | if the file cannot be written. |
Definition at line 804 of file configuration.cpp.
References diff(), and GUM_ERROR.
Referenced by ~Configuration().
| std::vector< Configuration::SchemaEntry > gum::Configuration::schema | ( | ) | const |
Definition at line 632 of file configuration.cpp.
References _items_, and _mutex_.
Referenced by ~Configuration().
| std::vector< std::string > gum::Configuration::sections | ( | ) | const |
Definition at line 642 of file configuration.cpp.
References _mutex_, and _sections_.
Referenced by ~Configuration().
| void gum::Configuration::set | ( | std::string_view | section, |
| std::string_view | key, | ||
| std::string_view | value, | ||
| bool | noHook = false ) |
Sets section.key.
Setting a deprecated key sets its replacement and queues a deprecation notice. If a hook throws, the previous value is restored (the hooks are run again, their exceptions being ignored) and the exception is propagated.
| noHook | if true, the hooks are not run. |
| SyntaxError | if the section or the key does not exist. |
| InvalidArgument | if the value does not respect the declared type of the key. |
Definition at line 670 of file configuration.cpp.
References _find_(), _items_, _mutex_, _refreshEpsilons_(), _resolve_(), _setAt_(), and runHooks().
Referenced by ~Configuration().
| std::vector< Configuration::Notice > gum::Configuration::takeNotices | ( | ) |
Definition at line 868 of file configuration.cpp.
References _noticeMutex_, and _notices_.
Referenced by ~Configuration().
| std::string gum::Configuration::toString | ( | ) | const |
Definition at line 840 of file configuration.cpp.
References _render_().
Referenced by ~Configuration(), and describe().
| T gum::Configuration::typed | ( | std::string_view | section, |
| std::string_view | key ) const |
Value of section.key converted according to its declared type.
| T | bool (for a bool key), int64_t (int key), double (float or int key) or std::string (any key). |
| SyntaxError | if the section or the key does not exist. |
| InvalidArgument | if T is not compatible with the declared type of the key. |
Definition at line 62 of file configuration_tpl.h.
References _typedRaw_(), BOOL, FLOAT, GUM_ERROR, INT, and gum::parseDecimal().
Referenced by ~Configuration(), gum::defaultJgumIndent(), gum::learning::IKTBNLearner< GUM_SCALAR >::defaultPriorWeight_(), gum::learning::IKTBNLearner< GUM_SCALAR >::defaultTabuListSize_(), gum::learning::IKTBNLearner< GUM_SCALAR >::defaultTabuNbDecrease_(), instance(), gum::learning::IBNLearner::preferredAlgo(), gum::ApproximationScheme::sizeFromConfiguration_(), and gum::Tensor< GUM_SCALAR >::toString().
|
static |
Definition at line 877 of file configuration.cpp.
References GUM_CONFIGURATION_USER_FILE.
Referenced by ~Configuration(), and _loadUserFile_().
|
private |
Definition at line 393 of file configuration.h.
Referenced by Configuration(), _refreshEpsilons_(), and _setAt_().
|
private |
Definition at line 392 of file configuration.h.
Referenced by _refreshEpsilons_(), epsilonCoarse(), epsilonFine(), and epsilonStandard().
|
private |
Definition at line 386 of file configuration.h.
Referenced by addHook(), and runHooks().
|
private |
Definition at line 384 of file configuration.h.
Referenced by _groupBySection_(), _parse_(), and _tryFind_().
|
private |
Definition at line 381 of file configuration.h.
Referenced by _checkSchema_(), _groupBySection_(), _parse_(), _refreshEpsilons_(), _render_(), _resolve_(), _restore_(), _setAt_(), _snapshot_(), _typedRaw_(), doc(), get(), load(), meta(), reset(), schema(), and set().
|
mutableprivate |
Definition at line 380 of file configuration.h.
Referenced by _render_(), _typedRaw_(), addHook(), doc(), get(), has(), load(), meta(), pop(), push(), reset(), runHooks(), schema(), sections(), and set().
|
staticconstexprprivate |
Definition at line 391 of file configuration.h.
Referenced by Configuration(), and _refreshEpsilons_().
|
mutableprivate |
Definition at line 395 of file configuration.h.
Referenced by _queue_(), and takeNotices().
|
mutableprivate |
Definition at line 396 of file configuration.h.
Referenced by _queue_(), and takeNotices().
|
staticconstexprprivate |
Definition at line 405 of file configuration.h.
Referenced by _checkSchema_(), _find_(), _parse_(), _refreshEpsilons_(), _tryFind_(), has(), and load().
|
private |
Definition at line 382 of file configuration.h.
Referenced by _groupBySection_(), _hasSection_(), _parse_(), and sections().
|
private |
Definition at line 385 of file configuration.h.