aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
configuration.h
Go to the documentation of this file.
1/****************************************************************************
2 * This file is part of the aGrUM/pyAgrum library. *
3 * *
4 * Copyright (c) 2005-2026 by *
5 * - Pierre-Henri WUILLEMIN(_at_LIP6) *
6 * - Christophe GONZALES(_at_AMU) *
7 * *
8 * The aGrUM/pyAgrum library is free software; you can redistribute it *
9 * and/or modify it under the terms of either : *
10 * *
11 * - the GNU Lesser General Public License as published by *
12 * the Free Software Foundation, either version 3 of the License, *
13 * or (at your option) any later version, *
14 * - the MIT license (MIT), *
15 * - or both in dual license, as here. *
16 * *
17 * (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html) *
18 * *
19 * This aGrUM/pyAgrum library is distributed in the hope that it will be *
20 * useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, *
21 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or FITNESS *
22 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE *
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, *
25 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR *
26 * OTHER DEALINGS IN THE SOFTWARE. *
27 * *
28 * See LICENCES for more details. *
29 * *
30 * SPDX-FileCopyrightText: Copyright 2005-2026 *
31 * - Pierre-Henri WUILLEMIN(_at_LIP6) *
32 * - Christophe GONZALES(_at_AMU) *
33 * SPDX-License-Identifier: LGPL-3.0-or-later OR MIT *
34 * *
35 * Contact : info_at_agrum_dot_org *
36 * homepage : http://agrum.gitlab.io *
37 * gitlab : https://gitlab.com/agrumery/agrum *
38 * *
39 ****************************************************************************/
40
41
59#ifndef GUM_CONFIGURATION_H
60#define GUM_CONFIGURATION_H
61
62#include <array>
63#include <atomic>
64#include <cstdint>
65#include <functional>
66#include <mutex>
67#include <string>
68#include <utility>
69#include <variant>
70#include <vector>
71
72#include <agrum/agrum.h>
73
74#include <initializer_list>
75#include <shared_mutex>
76#include <string_view>
77#include <unordered_map>
78
79namespace gum {
80
105 class GUM_SHARED_PUBLIC Configuration {
106 public:
108 enum class Kind : unsigned char { INT, FLOAT, BOOL, STR, ENUM, DEPRECATED };
109
111 struct GUM_SHARED_PUBLIC Meta {
115 struct GUM_SHARED_PUBLIC Domain {
116 bool hasLower{false};
117 bool hasUpper{false};
118 bool lowerIncluded{true};
119 bool upperIncluded{true};
120 double lower{0.};
121 double upper{0.};
122 std::string
124
126 bool contains(double x) const;
127 };
128
131 std::vector< std::string > values;
132 std::string doc;
133 std::string targetSection;
134 std::string targetKey;
135
137 std::string joinedValues() const;
138 };
139
141 using Value = std::variant< bool, std::int64_t, double, std::string >;
142
144 static std::string kindName(Kind kind);
145
147 struct SchemaEntry {
148 std::string section;
149 std::string key;
151 std::string defaultValue;
152 };
153
155 struct Notice {
156 enum class Kind : unsigned char { DEPRECATION, FILE };
158 std::string message;
159 };
160
161 using Hook = std::function< void(const Configuration&) >;
162
165
168 std::string_view text;
169 std::string_view origin;
170 };
171
180 explicit Configuration(std::string_view defaultsText, std::string_view origin = "defaults.ini");
181
197 explicit Configuration(std::initializer_list< DefaultsSource > sources);
198
199 Configuration(const Configuration&) = delete;
201 ~Configuration() = default;
202
211 static Configuration& instance();
212
214 static std::string userFileName();
215
217
220
225 std::string get(std::string_view section, std::string_view key) const;
226
234 template < typename T >
235 T typed(std::string_view section, std::string_view key) const;
236
244 Value getValue(std::string_view section, std::string_view key) const;
245
247 bool has(std::string_view section, std::string_view key) const;
248
250 Meta meta(std::string_view section, std::string_view key) const;
251
253 std::string doc(std::string_view section, std::string_view key) const;
254
256 std::vector< SchemaEntry > schema() const;
257
259 std::vector< std::string > sections() const;
260
262
265
276 void set(std::string_view section,
277 std::string_view key,
278 std::string_view value,
279 bool noHook = false);
280
282 void reset();
283
285 void push();
286
291 void pop();
292
294
297
308 void load(const std::string& filename);
309
314 void save(const std::string& filename) const;
315
318 std::string grep(std::string_view search) const;
319
321 std::string diff() const;
322
324 std::string toString() const;
325
328 std::string describe() const;
329
331
334
343 double epsilonCoarse() const noexcept;
344
346 double epsilonStandard() const noexcept;
347
349 double epsilonFine() const noexcept;
350
352
355
357 void addHook(Hook hook);
358
360 void runHooks() const;
361
364 std::vector< Notice > takeNotices();
365
367
368 private:
369 struct Item {
370 std::string section;
371 std::string key;
373 std::string value;
374 std::string defaultValue;
375 std::string origin; // name of the defaults source that defines the key
376 };
377
378 using Snapshot = std::vector< std::string >; // values, in the order of items_
379
380 mutable std::shared_mutex _mutex_;
381 std::vector< Item > _items_;
382 std::vector< std::string > _sections_;
383 std::unordered_map< std::string, std::size_t >
384 _index_; // "section\0key" -> position in _items_
385 std::vector< Snapshot > _stack_;
386 std::vector< Hook > _hooks_;
387
388 // the numerical tolerances (core.epsilonCoarse, ...) are copied in atomics, under the lock,
389 // each time a value changes; their positions in _items_ are _npos_ if the schema does not have
390 // them
391 static constexpr std::size_t _nbEpsilons_ = 3;
392 std::array< std::atomic< double >, _nbEpsilons_ > _epsilons_{{1e-2, 1e-6, 1e-10}};
393 std::array< std::size_t, _nbEpsilons_ > _epsilonPos_{};
394
395 mutable std::mutex _noticeMutex_;
396 mutable std::vector< Notice > _notices_;
397
398 // reads one defaults source: its sections may already exist (opened by a previous source)
399 void _parse_(std::string_view text, std::string_view origin);
400 // gathers the items of each section (the sections can have been completed by later sources)
401 void _groupBySection_();
402 // checks the consistency of the schema and canonicalizes the default values
403 void _checkSchema_();
404
405 static constexpr std::size_t _npos_ = static_cast< std::size_t >(-1);
406
407 static std::string _indexKey_(std::string_view section, std::string_view key);
408 // position of section.key, _npos_ if unknown
409 std::size_t _tryFind_(std::string_view section, std::string_view key) const;
410 // position of section.key; throws SyntaxError if unknown
411 std::size_t _find_(std::string_view section, std::string_view key) const;
412 bool _hasSection_(std::string_view section) const;
413 // position of the item that actually carries the value (follows a deprecation and gives a
414 // notice: queued, or appended to sink if not null)
415 std::size_t _resolve_(std::size_t pos, std::vector< Notice >* sink = nullptr) const;
416 // value and declared kind of the item that actually carries the value of section.key
417 std::pair< std::string, Kind > _typedRaw_(std::string_view section, std::string_view key) const;
418 // checks value against the declared type of item; on success gives its canonical form,
419 // otherwise gives the reason in error
420 static bool _validate_(const Item& item,
421 std::string_view value,
422 std::string& canonical,
423 std::string& error);
424 // sets the value of _items_[pos]; throws InvalidArgument if it does not respect the declared
425 // type
426 void _setAt_(std::size_t pos, std::string_view value);
427 // loads the user file of instance(), never throws
428 void _loadUserFile_();
429 std::string _render_(const std::function< bool(const Item&) >& keep) const;
430 Snapshot _snapshot_() const;
431 void _restore_(const Snapshot& snapshot);
432 // copies the values of the numerical tolerances in their atomics (needs the exclusive lock)
433 void _refreshEpsilons_();
434 void _queue_(Notice::Kind kind, std::string message) const;
435 };
436
439 GUM_SHARED_PUBLIC Configuration& config();
440
441} // namespace gum
442
444
445#ifndef GUM_NO_INLINE
447#endif // GUM_NO_INLINE
448
449#endif /* GUM_CONFIGURATION_H */
Sectioned key/value configuration with typed and documented keys.
std::string describe() const
static Configuration & instance()
The global configuration.
static constexpr std::size_t _npos_
std::unordered_map< std::string, std::size_t > _index_
Configuration(std::string_view defaultsText, std::string_view origin="defaults.ini")
Builds a configuration from a defaults text.
bool has(std::string_view section, std::string_view key) const
std::size_t _find_(std::string_view section, std::string_view key) const
std::string diff() const
std::mutex _noticeMutex_
std::shared_mutex _mutex_
void reset()
Back to the defaults. Runs the hooks.
double epsilonStandard() const noexcept
Configuration & operator=(const Configuration &)=delete
The global configuration.
std::vector< Notice > _notices_
std::string _render_(const std::function< bool(const Item &) > &keep) const
static std::string _indexKey_(std::string_view section, std::string_view key)
T typed(std::string_view section, std::string_view key) const
Value of section.key converted according to its declared type.
std::vector< Notice > takeNotices()
std::array< std::size_t, _nbEpsilons_ > _epsilonPos_
std::vector< Snapshot > _stack_
void _queue_(Notice::Kind kind, std::string message) const
static bool _validate_(const Item &item, std::string_view value, std::string &canonical, std::string &error)
std::size_t _resolve_(std::size_t pos, std::vector< Notice > *sink=nullptr) const
void save(const std::string &filename) const
Writes the difference with the defaults (see diff()) in a file.
void addHook(Hook hook)
Adds a function called after each change (see set(), reset(), pop(), load()).
std::vector< std::string > _sections_
std::vector< Hook > _hooks_
std::array< std::atomic< double >, _nbEpsilons_ > _epsilons_
void runHooks() const
Runs the hooks (outside of any lock).
void push()
Pushes the current values on a stack.
void _parse_(std::string_view text, std::string_view origin)
static std::string kindName(Kind kind)
void pop()
Restores the values on top of the stack.
std::function< void(const Configuration &) > Hook
std::string toString() const
std::string grep(std::string_view search) const
std::string doc(std::string_view section, std::string_view key) const
Snapshot _snapshot_() const
std::vector< Item > _items_
std::pair< std::string, Kind > _typedRaw_(std::string_view section, std::string_view key) const
Configuration(const Configuration &)=delete
The global configuration.
static std::string userFileName()
std::variant< bool, std::int64_t, double, std::string > Value
a value converted according to the declared type of its key (see getValue())
void _setAt_(std::size_t pos, std::string_view value)
std::size_t _tryFind_(std::string_view section, std::string_view key) const
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 _hasSection_(std::string_view section) const
void set(std::string_view section, std::string_view key, std::string_view value, bool noHook=false)
Sets section.key.
double epsilonCoarse() const noexcept
The coarse tolerance (key core.epsilonCoarse, 1e-2 by default).
static constexpr std::size_t _nbEpsilons_
void load(const std::string &filename)
Loads a user file and changes the values it contains.
std::vector< SchemaEntry > schema() const
Kind
the declared type of a key
void _restore_(const Snapshot &snapshot)
~Configuration()=default
The global configuration.
Meta meta(std::string_view section, std::string_view key) const
std::vector< std::string > sections() const
std::string get(std::string_view section, std::string_view key) const
Value of section.key, as a string.
double epsilonFine() const noexcept
std::vector< std::string > Snapshot
Inline definitions of gum::Configuration.
Template definitions of gum::Configuration.
gum is the global namespace for all aGrUM entities
Definition agrum.h:46
Configuration & config()
A short name for Configuration::instance() : gum::config().epsilonStandard(). It is not inline so tha...
STL namespace.
a text of defaults, with the name designating it in error messages
domain of validity of an int or float key, written after the type in the ### line: float]0,...
std::string text
the domain as written, without blanks (e.g. ]0,1[) ; empty if none
metadata attached to a key by a ### line
std::string doc
one-line documentation
std::vector< std::string > values
allowed values (kind == ENUM)
std::string joinedValues() const
Domain domain
domain of validity (kind == INT or FLOAT)
std::string targetKey
replacement key (kind == DEPRECATED)
std::string targetSection
replacement key (kind == DEPRECATED)
a message that cannot be an exception (the operation went on), see takeNotices()
one line of the schema (see schema())
std::string defaultValue
empty for a deprecated key