aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
configuration.cpp
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
48
49// to ease automatic parsers
50#include <algorithm>
51#include <cctype>
52#include <charconv>
53#include <cmath>
54#include <cstdlib>
55#include <filesystem>
56#include <fstream>
57#include <sstream>
58
59#include <agrum/agrum.h>
60
62#ifdef GUM_NO_INLINE
64#endif // GUM_NO_INLINE
67
69
70// the whole of aGrUM is compiled with GUM_FOR_SWIG for a pyAgrum build: the embedded defaults are
71// then those of aGrUM followed by those of pyAgrum (two sources, embedded by cmake), and the user
72// file is pyagrum.ini. Both files only change existing keys: they never create a section or a key.
73#ifdef GUM_FOR_SWIG
74# define GUM_CONFIGURATION_USER_FILE "pyagrum.ini"
75#else
76# define GUM_CONFIGURATION_USER_FILE "agrum.ini"
77#endif
78
79namespace gum {
80
81 // the content of the defaults.ini of aGrUM and of the one of pyAgrum (empty if pyAgrum is not
82 // compiled), generated at build time (see src/cmake)
85
86 namespace {
87
88 constexpr std::string_view _undocumented_ = "(undocumented)";
89
90 // the keys of section core copied in atomics (see Configuration::epsilonCoarse() and so on), in
91 // the order of Configuration::_epsilons_
92 constexpr std::array< std::string_view, 3 > _epsilonKeys_
93 = {"epsiloncoarse", "epsilonstandard", "epsilonfine"};
94
95 [[noreturn]] void
96 _syntaxError_(const std::string& msg, std::string_view origin, std::size_t line) {
97 GUM_SYNTAX_ERROR(msg, std::string(origin), line, 0)
98 }
99
100 bool _isCommentOrBlank_(std::string_view trimmed) {
101 return trimmed.empty() || trimmed.front() == '#' || trimmed.front() == ';';
102 }
103
104 // `###` followed by anything but another `#`
105 bool _isMetaLine_(std::string_view trimmed) {
106 return trimmed.size() >= 3 && trimmed.substr(0, 3) == "###"
107 && (trimmed.size() == 3 || trimmed[3] != '#');
108 }
109
110 bool _isSectionLine_(std::string_view trimmed, std::string& name) {
111 if (trimmed.size() < 3 || trimmed.front() != '[' || trimmed.back() != ']') return false;
112 const auto inner = trimmed.substr(1, trimmed.size() - 2);
113 if (inner.find(']') != std::string_view::npos) return false;
114 name = std::string(inner);
115 return true;
116 }
117
118 // `key = value` or `key : value`, whichever delimiter comes first
119 bool _splitKeyValue_(std::string_view trimmed, std::string& key, std::string& value) {
120 const auto pos = trimmed.find_first_of("=:");
121 if (pos == std::string_view::npos) return false;
122 key = trim_copy(trimmed.substr(0, pos));
123 value = trim_copy(trimmed.substr(pos + 1));
124 return !key.empty();
125 }
126
127 bool _isIdentifier_(std::string_view s) {
128 if (s.empty() || !(std::isalpha(static_cast< unsigned char >(s[0])) || s[0] == '_')) {
129 return false;
130 }
131 return std::all_of(s.begin(), s.end(), [](char c) {
132 return std::isalnum(static_cast< unsigned char >(c)) || c == '_';
133 });
134 }
135
136 bool _hasSpace_(std::string_view s) {
137 return std::any_of(s.begin(), s.end(), [](char c) {
138 return std::isspace(static_cast< unsigned char >(c));
139 });
140 }
141
142 std::vector< std::string > _lines_(std::string_view text) {
143 std::vector< std::string > lines;
144 std::size_t prev = 0;
145 while (prev <= text.size()) {
146 auto pos = text.find('\n', prev);
147 if (pos == std::string_view::npos) pos = text.size();
148 auto line = text.substr(prev, pos - prev);
149 if (!line.empty() && line.back() == '\r') line.remove_suffix(1);
150 lines.emplace_back(line);
151 prev = pos + 1;
152 }
153 if (!lines.empty() && lines.back().empty()) lines.pop_back(); // text ending with '\n'
154 return lines;
155 }
156
157 bool _toInt_(std::string_view s, std::int64_t& res) {
158 if (!s.empty() && s.front() == '+') s.remove_prefix(1);
159 if (s.empty()) return false;
160 const auto [ptr, ec] = std::from_chars(s.data(), s.data() + s.size(), res);
161 return ec == std::errc() && ptr == s.data() + s.size();
162 }
163
164 // parses the domain of an int or float (e.g. `]0,1[`, `[1,]`); on failure, gives the reason in
165 // error
166 bool _parseDomain_(std::string_view text,
167 bool isInt,
169 std::string& error) {
170 std::string t;
171 for (const char c: text)
172 if (!std::isspace(static_cast< unsigned char >(c))) t += c;
173
174 const auto isBracket = [](char c) { return c == '[' || c == ']'; };
175 const auto comma = t.find(',');
176 if (t.size() < 3 || !isBracket(t.front()) || !isBracket(t.back())
177 || comma == std::string::npos || t.find(',', comma + 1) != std::string::npos) {
178 error = "'" + t + "' is not a valid domain (e.g. ]0,1[ or [1,])";
179 return false;
180 }
181
182 const auto parseBound = [&](const std::string& s, bool& has, double& value) {
183 has = !s.empty();
184 if (!has) return true;
185 if (isInt) {
186 std::int64_t i = 0;
187 if (!_toInt_(s, i)) return false;
188 value = static_cast< double >(i);
189 return true;
190 }
191 return parseDecimal(s, value);
192 };
193
195 domain.lowerIncluded = t.front() == '[';
196 domain.upperIncluded = t.back() == ']';
197 if (!parseBound(t.substr(1, comma - 1), domain.hasLower, domain.lower)
198 || !parseBound(t.substr(comma + 1, t.size() - comma - 2),
199 domain.hasUpper,
200 domain.upper)) {
201 error = "'" + t + "' has a bound that is not " + (isInt ? "an int" : "a float");
202 return false;
203 }
204 if (domain.hasLower && domain.hasUpper
205 && (domain.lower > domain.upper
206 || (domain.lower == domain.upper
207 && !(domain.lowerIncluded && domain.upperIncluded)))) {
208 error = "the domain '" + t + "' is empty";
209 return false;
210 }
211 domain.text = t;
212 return true;
213 }
214
215 // parses the `type` part of a metadata line; on failure, gives the reason in error
216 bool _parseMetaSpec_(const std::string& spec,
217 const std::string& doc,
219 std::string& error) {
220 meta = Configuration::Meta();
221 meta.doc = doc;
222
223 // the type, without the domain of validity that may follow it (e.g. `float]0,1[`)
224 const auto cut = spec.find_first_of("[]");
225 const auto type = trim_copy(std::string_view(spec).substr(0, cut));
226
227 if (spec.rfind("deprecated", 0) == 0) {
228 const auto rest = trim_copy(std::string_view(spec).substr(10));
229 if (rest.rfind("->", 0) == 0) {
230 const auto target = trim_copy(std::string_view(rest).substr(2));
231 const auto dot = target.find('.');
232 if (dot != std::string::npos && dot > 0 && dot + 1 < target.size()
233 && !_hasSpace_(target)) {
235 meta.targetSection = target.substr(0, dot);
236 meta.targetKey = toLower(target.substr(dot + 1));
237 return true;
238 }
239 }
240 } else if (type == "int" || type == "float" || type == "bool" || type == "str") {
241 meta.kind = type == "int" ? Configuration::Kind::INT
242 : type == "float" ? Configuration::Kind::FLOAT
243 : type == "bool" ? Configuration::Kind::BOOL
245 if (cut == std::string::npos) return true;
246 if (meta.kind == Configuration::Kind::INT || meta.kind == Configuration::Kind::FLOAT) {
247 return _parseDomain_(std::string_view(spec).substr(cut),
248 meta.kind == Configuration::Kind::INT,
249 meta.domain,
250 error);
251 }
252 error = "'" + type + "' cannot have a domain";
253 return false;
254 } else if (spec.find('|') != std::string::npos) {
255 std::size_t prev = 0;
256 bool ok = true;
257 while (true) {
258 auto pos = spec.find('|', prev);
259 if (pos == std::string::npos) pos = spec.size();
260 auto value = trim_copy(std::string_view(spec).substr(prev, pos - prev));
261 if (value.empty()) ok = false;
262 meta.values.push_back(std::move(value));
263 if (pos == spec.size()) break;
264 prev = pos + 1;
265 }
266 if (ok) {
267 meta.kind = Configuration::Kind::ENUM;
268 return true;
269 }
270 }
271 error = "'" + spec
272 + "' is not a valid type (int, float, bool, str, int[min,max], float]min,max[, "
273 "v1|v2|..., "
274 "deprecated -> section.key)";
275 return false;
276 }
277
278 std::string _readFile_(const std::string& filename) {
279 std::ifstream f(filename, std::ios::binary);
280 if (!f) { GUM_ERROR(IOError, "Cannot read file '" << filename << "'.") }
281 std::ostringstream content;
282 content << f.rdbuf();
283 return content.str();
284 }
285
286 } // namespace
287
289 std::string res;
290 for (const auto& v: values) {
291 if (!res.empty()) res += '|';
292 res += v;
293 }
294 return res;
295 }
296
298 if ((hasLower || hasUpper) && std::isnan(x)) return false;
299 if (hasLower && (x < lower || (x == lower && !lowerIncluded))) return false;
300 if (hasUpper && (x > upper || (x == upper && !upperIncluded))) return false;
301 return true;
302 }
303
304 std::string Configuration::kindName(Kind kind) {
305 switch (kind) {
306 case Kind::INT : return "int";
307 case Kind::FLOAT : return "float";
308 case Kind::BOOL : return "bool";
309 case Kind::ENUM : return "enum";
310 case Kind::DEPRECATED : return "deprecated";
311 default : return "str";
312 }
313 }
314
315 // ==========================================================================
316 // construction / parsing
317 // ==========================================================================
318
319 Configuration::Configuration(std::string_view defaultsText, std::string_view origin) :
320 Configuration(std::initializer_list< DefaultsSource >{DefaultsSource{defaultsText, origin}}) {
321 }
322
323 Configuration::Configuration(std::initializer_list< DefaultsSource > sources) {
324 for (const auto& source: sources) {
325 if (!source.text.empty()) _parse_(source.text, source.origin);
326 }
329 for (std::size_t i = 0; i < _nbEpsilons_; ++i)
330 _epsilonPos_[i] = _tryFind_("core", _epsilonKeys_[i]);
332 }
333
334 void Configuration::_parse_(std::string_view text, std::string_view origin) {
335 const auto lines = _lines_(text);
336
337 // a section can be reopened by another source but not inside the same one
338 std::vector< std::string > openedHere;
339
340 bool inSection = false;
341 std::string section;
342 bool pending = false;
343 Meta pendingMeta;
344 std::size_t numline = 0;
345
346 auto err = [&](const std::string& msg) { _syntaxError_(msg, origin, numline); };
347
348 for (const auto& rawLine: lines) {
349 ++numline;
350 const auto trimmed = trim_copy(rawLine);
351 std::string key, value, name;
352
353 const bool hasKeyValue = !_isCommentOrBlank_(trimmed) && _splitKeyValue_(trimmed, key, value);
354 const bool isKeyLine = hasKeyValue && _isIdentifier_(key);
355
356 if (pending && !isKeyLine) {
357 err("metadata line must be immediately followed by a 'key = value' line");
358 }
359
360 if (_isMetaLine_(trimmed)) {
361 const auto payload = trim_copy(std::string_view(trimmed).substr(3));
362 const auto sep = payload.find("::");
363 if (sep == std::string::npos) {
364 err("metadata line must follow the syntax '### type :: documentation'");
365 }
366 const auto spec = trim_copy(std::string_view(payload).substr(0, sep));
367 const auto doc = trim_copy(std::string_view(payload).substr(sep + 2));
368 if (doc.empty()) err("missing documentation in metadata line");
369 std::string error;
370 if (!_parseMetaSpec_(spec, doc, pendingMeta, error)) err(error);
371 pending = true;
372 continue;
373 }
374
375 if (_isCommentOrBlank_(trimmed)) continue;
376
377 if (_isSectionLine_(trimmed, name)) {
378 if (std::find(openedHere.begin(), openedHere.end(), name) != openedHere.end()) {
379 err("duplicate section '" + name + "'");
380 }
381 openedHere.push_back(name);
382 if (!_hasSection_(name)) _sections_.push_back(name);
383 section = name;
384 inSection = true;
385 continue;
386 }
387
388 if (!inSection) err("key outside of any section");
389 if (!hasKeyValue) err("malformed line '" + trimmed + "'");
390
391 key = toLower(key);
392 if (const auto first = _tryFind_(section, key); first != _npos_) {
393 err("duplicate key '" + section + "." + key + "' (already defined in "
394 + _items_[first].origin + ")");
395 }
396
397 Item item;
398 item.section = section;
399 item.key = key;
400 item.value = value;
401 item.origin = std::string(origin);
402 if (pending) {
403 item.meta = pendingMeta;
404 pending = false;
405 } else {
406 item.meta.doc = std::string(_undocumented_);
407 }
408 _index_[_indexKey_(section, key)] = _items_.size();
409 _items_.push_back(std::move(item));
410 }
411
412 if (pending) err("metadata line at end of file");
413 }
414
416 // a section opened by several sources has its items spread in _items_: gather them, keeping
417 // the order of the sections and, inside a section, the order of reading
418 std::vector< Item > grouped;
419 grouped.reserve(_items_.size());
420 for (const auto& section: _sections_) {
421 for (auto& item: _items_) {
422 if (item.section == section) grouped.push_back(std::move(item));
423 }
424 }
425 _items_ = std::move(grouped);
426 _index_.clear();
427 for (std::size_t pos = 0; pos < _items_.size(); ++pos) {
428 _index_[_indexKey_(_items_[pos].section, _items_[pos].key)] = pos;
429 }
430 }
431
433 for (auto& item: _items_) {
434 if (item.meta.kind == Kind::DEPRECATED) {
435 const auto pos = _tryFind_(item.meta.targetSection, item.meta.targetKey);
436 if (pos == _npos_) {
437 GUM_SYNTAX_ERROR("deprecated key '"
438 << item.section << "." << item.key << "' redirects to unknown key '"
439 << item.meta.targetSection << "." << item.meta.targetKey << "'",
440 item.origin,
441 0,
442 0)
443 }
444 if (_items_[pos].meta.kind == Kind::DEPRECATED) {
445 GUM_SYNTAX_ERROR("deprecated key '" << item.section << "." << item.key
446 << "' redirects to deprecated key '"
447 << item.meta.targetSection << "."
448 << item.meta.targetKey << "'",
449 item.origin,
450 0,
451 0)
452 }
453 } else {
454 std::string canonical, error;
455 if (!_validate_(item, item.value, canonical, error)) {
456 GUM_ERROR(InvalidArgument, "[" << item.origin << "] " << error)
457 }
458 item.value = canonical;
459 item.defaultValue = canonical;
460 }
461 }
462 }
463
464 // ==========================================================================
465 // lookup
466 // ==========================================================================
467
468 std::string Configuration::_indexKey_(std::string_view section, std::string_view key) {
469 std::string res(section);
470 res += '\0';
471 res += toLower(key);
472 return res;
473 }
474
475 std::size_t Configuration::_tryFind_(std::string_view section, std::string_view key) const {
476 const auto it = _index_.find(_indexKey_(section, key));
477 return it == _index_.end() ? _npos_ : it->second;
478 }
479
480 bool Configuration::_hasSection_(std::string_view section) const {
481 return std::find(_sections_.begin(), _sections_.end(), section) != _sections_.end();
482 }
483
484 std::size_t Configuration::_find_(std::string_view section, std::string_view key) const {
485 const auto pos = _tryFind_(section, key);
486 if (pos != _npos_) return pos;
487 if (!_hasSection_(section)) {
488 GUM_SYNTAX_ERROR("Section '" << section << "' unknown in configuration.", "", 0, 0)
489 }
490 GUM_SYNTAX_ERROR("Key '" << section << "." << key << "' unknown in configuration.", "", 0, 0)
491 }
492
493 void Configuration::_queue_(Notice::Kind kind, std::string message) const {
494 std::lock_guard< std::mutex > lock(_noticeMutex_);
495 // a notice already waiting is not queued twice (e.g. a deprecated key read in a loop)
496 const auto same = [&](const Notice& n) { return n.kind == kind && n.message == message; };
497 if (std::none_of(_notices_.begin(), _notices_.end(), same)) {
498 _notices_.push_back(Notice{kind, std::move(message)});
499 }
500 }
501
502 std::size_t Configuration::_resolve_(std::size_t pos, std::vector< Notice >* sink) const {
503 const auto& item = _items_[pos];
504 if (item.meta.kind != Kind::DEPRECATED) return pos;
506 "'" + item.section + "." + item.key + "' is deprecated (" + item.meta.doc
507 + "), use '" + item.meta.targetSection + "." + item.meta.targetKey
508 + "' instead."};
509 if (sink != nullptr) sink->push_back(std::move(notice));
510 else _queue_(notice.kind, std::move(notice.message));
511 return _tryFind_(item.meta.targetSection, item.meta.targetKey); // checked by _checkSchema_
512 }
513
514 std::pair< std::string, Configuration::Kind >
515 Configuration::_typedRaw_(std::string_view section, std::string_view key) const {
516 std::shared_lock lock(_mutex_);
517 const auto& item = _items_[_resolve_(_find_(section, key))];
518 return {item.value, item.meta.kind};
519 }
520
521 // ==========================================================================
522 // validation
523 // ==========================================================================
524
526 std::string_view value,
527 std::string& canonical,
528 std::string& error) {
529 const auto name = item.section + "." + item.key;
530 const auto s = trim_copy(value);
531 canonical = s;
532
533 switch (item.meta.kind) {
534 case Kind::INT : {
535 std::int64_t res = 0;
536 if (!_toInt_(s, res)) {
537 error = "'" + s + "' must be an int for '" + name + "'.";
538 return false;
539 }
540 if (!item.meta.domain.contains(static_cast< double >(res))) {
541 error = "'" + s + "' must be in " + item.meta.domain.text + " for '" + name + "'.";
542 return false;
543 }
544 return true;
545 }
546 case Kind::FLOAT : {
547 double res = 0;
548 if (!parseDecimal(s, res)) {
549 error = "'" + s + "' must be a float for '" + name + "'.";
550 return false;
551 }
552 if (!item.meta.domain.contains(res)) {
553 error = "'" + s + "' must be in " + item.meta.domain.text + " for '" + name + "'.";
554 return false;
555 }
556 return true;
557 }
558 case Kind::BOOL : {
559 const auto low = toLower(s);
560 if (low == "true" || low == "1" || low == "on" || low == "yes") {
561 canonical = "True";
562 return true;
563 }
564 if (low == "false" || low == "0" || low == "off" || low == "no") {
565 canonical = "False";
566 return true;
567 }
568 error
569 = "'" + s + "' must be a boolean (False/True, 0/1, Off/On, No/Yes) for '" + name + "'.";
570 return false;
571 }
572 case Kind::ENUM : {
573 const auto low = toLower(s);
574 for (const auto& v: item.meta.values) {
575 if (toLower(v) == low) {
576 canonical = v;
577 return true;
578 }
579 }
580 error = "'" + s + "' must be one of " + item.meta.joinedValues() + " for '" + name + "'.";
581 return false;
582 }
583 default : canonical = std::string(value); return true;
584 }
585 }
586
587 // ==========================================================================
588 // accessors
589 // ==========================================================================
590
591 std::string Configuration::get(std::string_view section, std::string_view key) const {
592 std::shared_lock lock(_mutex_);
593 return _items_[_resolve_(_find_(section, key))].value;
594 }
595
597 std::string_view key) const {
598 const auto [value, kind] = _typedRaw_(section, key);
599 switch (kind) {
600 case Kind::BOOL : return value == "True";
601 case Kind::INT : return static_cast< std::int64_t >(std::strtoll(value.c_str(), nullptr, 10));
602 case Kind::FLOAT : {
603 double res = 0;
604 parseDecimal(value, res);
605 return res;
606 }
607 default : return value;
608 }
609 }
610
611 bool Configuration::has(std::string_view section, std::string_view key) const {
612 std::shared_lock lock(_mutex_);
613 return _tryFind_(section, key) != _npos_;
614 }
615
616 Configuration::Meta Configuration::meta(std::string_view section, std::string_view key) const {
617 std::shared_lock lock(_mutex_);
618 return _items_[_find_(section, key)].meta;
619 }
620
621 std::string Configuration::doc(std::string_view section, std::string_view key) const {
622 std::shared_lock lock(_mutex_);
623 const auto& m = _items_[_find_(section, key)].meta;
624 switch (m.kind) {
625 case Kind::DEPRECATED :
626 return "deprecated -> " + m.targetSection + "." + m.targetKey + " :: " + m.doc;
627 case Kind::ENUM : return m.joinedValues() + " :: " + m.doc;
628 default : return kindName(m.kind) + m.domain.text + " :: " + m.doc;
629 }
630 }
631
632 std::vector< Configuration::SchemaEntry > Configuration::schema() const {
633 std::shared_lock lock(_mutex_);
634 std::vector< SchemaEntry > res;
635 res.reserve(_items_.size());
636 for (const auto& item: _items_) {
637 res.push_back(SchemaEntry{item.section, item.key, item.meta, item.defaultValue});
638 }
639 return res;
640 }
641
642 std::vector< std::string > Configuration::sections() const {
643 std::shared_lock lock(_mutex_);
644 return _sections_;
645 }
646
647 // ==========================================================================
648 // modifiers
649 // ==========================================================================
650
651 void Configuration::_setAt_(std::size_t pos, std::string_view value) {
652 std::string canonical, error;
653 if (!_validate_(_items_[pos], value, canonical, error)) { GUM_ERROR(InvalidArgument, error) }
654 _items_[pos].value = std::move(canonical);
655 // the atomics only depend on the three tolerances
656 if (std::find(_epsilonPos_.begin(), _epsilonPos_.end(), pos) != _epsilonPos_.end()) {
658 }
659 }
660
662 for (std::size_t i = 0; i < _nbEpsilons_; ++i) {
663 double value = 0;
664 if (_epsilonPos_[i] != _npos_ && parseDecimal(_items_[_epsilonPos_[i]].value, value)) {
665 _epsilons_[i].store(value, std::memory_order_relaxed);
666 }
667 }
668 }
669
670 void Configuration::set(std::string_view section,
671 std::string_view key,
672 std::string_view value,
673 bool noHook) {
674 std::size_t pos = 0;
675 std::string previous;
676 {
677 std::unique_lock lock(_mutex_);
678 pos = _resolve_(_find_(section, key));
679 previous = _items_[pos].value;
680 _setAt_(pos, value);
681 }
682 if (noHook) return;
683
684 try {
685 runHooks();
686 } catch (...) {
687 {
688 std::unique_lock lock(_mutex_);
689 _items_[pos].value = std::move(previous);
691 }
692 // bring back the state driven by the hooks; the original exception is the one to report
693 try {
694 runHooks();
695 } catch (...) {}
696 throw;
697 }
698 }
699
701 Snapshot res;
702 res.reserve(_items_.size());
703 for (const auto& item: _items_)
704 res.push_back(item.value);
705 return res;
706 }
707
708 void Configuration::_restore_(const Snapshot& snapshot) {
709 for (std::size_t i = 0; i < _items_.size(); ++i)
710 _items_[i].value = snapshot[i];
712 }
713
715 {
716 std::unique_lock lock(_mutex_);
717 for (auto& item: _items_)
718 if (item.meta.kind != Kind::DEPRECATED) item.value = item.defaultValue;
720 }
721 runHooks();
722 }
723
725 std::unique_lock lock(_mutex_);
726 _stack_.push_back(_snapshot_());
727 }
728
730 {
731 std::unique_lock lock(_mutex_);
732 if (_stack_.empty()) { GUM_ERROR(OperationNotAllowed, "No configuration to pop.") }
733 _restore_(_stack_.back());
734 _stack_.pop_back();
735 }
736 runHooks();
737 }
738
739 // ==========================================================================
740 // files and display
741 // ==========================================================================
742
743 void Configuration::load(const std::string& filename) {
744 const auto lines = _lines_(_readFile_(filename));
745
746 // The whole file is read before anything is changed: a malformed line leaves the values (and
747 // thus the state driven by the hooks) untouched.
748 std::vector< std::pair< std::size_t, std::string > > changes; // (position, canonical value)
749 std::vector< Notice > notices;
750 auto note = [&](std::string message) {
751 notices.push_back(Notice{Notice::Kind::FILE, "[" + filename + "] " + std::move(message)});
752 };
753 {
754 std::shared_lock lock(_mutex_);
755 std::string section;
756 bool knownSection = false;
757 std::size_t numline = 0;
758
759 for (const auto& rawLine: lines) {
760 ++numline;
761 const auto trimmed = trim_copy(rawLine);
762 std::string name, key, value;
763 if (_isCommentOrBlank_(trimmed)) continue;
764
765 if (_isSectionLine_(trimmed, name)) {
766 section = name;
767 knownSection = _hasSection_(section);
768 if (!knownSection) { note("Section '" + section + "' does not exist."); }
769 continue;
770 }
771
772 if (section.empty() || !_splitKeyValue_(trimmed, key, value)) {
773 _syntaxError_("malformed line '" + trimmed + "'", filename, numline);
774 }
775 if (!knownSection) continue;
776
777 const auto pos = _tryFind_(section, key);
778 if (pos == _npos_) {
779 note("Option '" + section + "." + toLower(key) + "' does not exist.");
780 continue;
781 }
782 const auto target = _resolve_(pos, &notices);
783
784 std::string canonical, error;
785 if (_validate_(_items_[target], value, canonical, error)) {
786 changes.emplace_back(target, std::move(canonical));
787 } else {
788 note("Invalid value for '" + section + "." + toLower(key) + "': " + error);
789 }
790 }
791 }
792
793 {
794 std::unique_lock lock(_mutex_);
795 for (auto& [pos, value]: changes)
796 _items_[pos].value = std::move(value);
798 }
799 for (auto& notice: notices)
800 _queue_(notice.kind, std::move(notice.message));
801 runHooks();
802 }
803
804 void Configuration::save(const std::string& filename) const {
805 const auto content = diff();
806 std::ofstream f(filename, std::ios::binary | std::ios::trunc);
807 if (!f) { GUM_ERROR(IOError, "Cannot write file '" << filename << "'.") }
808 f << content << '\n';
809 if (!f) { GUM_ERROR(IOError, "Cannot write file '" << filename << "'.") }
810 }
811
812 std::string Configuration::_render_(const std::function< bool(const Item&) >& keep) const {
813 std::shared_lock lock(_mutex_);
814 std::string res;
815 // the keys of a section are contiguous in _items_ (a duplicate section is refused by _parse_)
816 const std::string* current = nullptr; // section of the last rendered key
817 for (const auto& item: _items_) {
818 if (item.meta.kind == Kind::DEPRECATED || !keep(item)) continue;
819 if (current == nullptr || *current != item.section) {
820 if (current != nullptr) res += '\n';
821 res += "[" + item.section + "]";
822 current = &item.section;
823 }
824 res += "\n " + item.key + " = " + item.value;
825 }
826 return res;
827 }
828
829 std::string Configuration::grep(std::string_view search) const {
830 const auto low = toLower(search);
831 return _render_([&](const Item& item) {
832 return contains(toLower(item.section), low) || contains(item.key, low);
833 });
834 }
835
836 std::string Configuration::diff() const {
837 return _render_([](const Item& item) { return item.value != item.defaultValue; });
838 }
839
840 std::string Configuration::toString() const {
841 return _render_([](const Item&) { return true; });
842 }
843
844 std::string Configuration::describe() const {
845 const auto changes = diff();
846 return changes.empty() ? "# no customized property\n" + toString() : changes;
847 }
848
849 // ==========================================================================
850 // hooks and notices
851 // ==========================================================================
852
854 std::unique_lock lock(_mutex_);
855 _hooks_.push_back(std::move(hook));
856 }
857
859 std::vector< Hook > hooks;
860 {
861 std::shared_lock lock(_mutex_);
862 hooks = _hooks_;
863 }
864 for (const auto& hook: hooks)
865 hook(*this);
866 }
867
868 std::vector< Configuration::Notice > Configuration::takeNotices() {
869 std::lock_guard< std::mutex > lock(_noticeMutex_);
870 return std::exchange(_notices_, {});
871 }
872
873 // ==========================================================================
874 // singleton
875 // ==========================================================================
876
878
880 try {
881 const auto filename = userFileName();
882 if (std::filesystem::is_regular_file(filename)) load(filename);
883 } catch (const std::exception& e) {
884 _queue_(Notice::Kind::FILE, std::string("[") + userFileName() + "] " + e.what());
885 }
886 }
887
889
891 // built, completed by the user file and applied once (thread-safe), the first time it is needed
892 static Configuration& instanceRef = []() -> Configuration& {
893 static Configuration global{
894 {configurationEmbeddedDefaults(), "defaults.ini (aGrUM)"},
895 {configurationEmbeddedPyAgrumDefaults(), "defaults.ini (pyAgrum)"}};
896 // the number of threads is the only [core] key acting directly on the library; a negative
897 // value gives back what the machine (or OMP_NUM_THREADS) provides, read before any change
898 global.addHook([machine = gum::getMaxNumberOfThreads()](const Configuration& c) {
899 const auto n = c.typed< std::int64_t >("core", "maxNumberOfThreads");
900 gum::setNumberOfThreads(n < 0 ? machine : static_cast< unsigned int >(n));
901 });
902 global._loadUserFile_();
903 try {
904 global.runHooks();
905 } catch (const std::exception& e) {
906 // e.g. a number of threads that cannot be honoured: the library must stay usable
907 global._queue_(Notice::Kind::FILE, std::string("hook failed: ") + e.what());
908 }
909 return global;
910 }();
911 return instanceRef;
912 }
913
914 namespace {
915 // loads the configuration (and applies its hooks) as soon as the library is loaded, so that the
916 // user file acts even on a program which never reads the configuration. Beware: with a static
917 // library, this object is only kept if something else references this translation unit.
918 const struct ConfigurationInitializer {
919 ConfigurationInitializer() {
920 try {
922 } catch (...) {} // never let an exception escape a static initializer
923 }
924 } _configurationInitializer_;
925 } // namespace
926
927} // namespace gum
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.
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
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.
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)
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.
std::vector< std::string > Snapshot
Exception : input/output problem.
Exception: at least one argument passed to a function is not what was expected.
Exception : operation not allowed.
#define GUM_CONFIGURATION_USER_FILE
Typed, documented, sectioned configuration singleton read from an .ini content.
Inline definitions of gum::Configuration.
aGrUM's exceptions
#define GUM_SYNTAX_ERROR(msg, filename, line, column)
Definition exceptions.h:121
#define GUM_ERROR(type, msg)
Definition exceptions.h:76
void setNumberOfThreads(unsigned int number)
Set the max number of threads to be used when entering the next parallel region.
Definition threads.cpp:55
GUM_SHARED_PUBLIC bool contains(std::string_view s, std::string_view needle)
true if needle in s
GUM_SHARED_PUBLIC std::string toLower(std::string_view str)
Returns the lowercase version of str.
GUM_SHARED_PUBLIC std::string trim_copy(std::string_view s)
trim from both ends (copying)
bool parseDecimal(std::string_view val, double &res)
parse a decimal number, whatever the locale of the program
gum is the global namespace for all aGrUM entities
Definition agrum.h:46
std::string_view configurationEmbeddedPyAgrumDefaults()
Configuration & config()
A short name for Configuration::instance() : gum::config().epsilonStandard(). It is not inline so tha...
GUM_SHARED_PUBLIC unsigned int getMaxNumberOfThreads()
Returns the maximum number of threads you should use at any time.
std::string_view configurationEmbeddedDefaults()
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)
a message that cannot be an exception (the operation went on), see takeNotices()
one line of the schema (see schema())
Utility functions used for exploiting OpenMP/STL parallelism.
Utilities for manipulating strings.