StormByte-Config 3.0.0
C++26 configuration-document module of the StormByte suite
Loading...
Searching...
No Matches
config.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This file is part of StormByte-Config.
5 *
6 * StormByte-Config original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte-Config source in this
20 * repository. They do not cover other StormByte modules or any third-party
21 * material shipped with this repository (including everything under
22 * thirdparty/, and in particular the bundled StormByte-String tree and
23 * the StormByte Base tree it vendors), which remains under its own license.
24 *
25 * Neither license grants any patent rights. Any patent licenses required
26 * to use this software or third-party components must be obtained separately
27 * from the patent holders.
28 *
29 * StormByte-Config is distributed in the hope that it will be useful,
30 * but WITHOUT ANY WARRANTY; without even the implied warranty of
31 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
32 * GNU Lesser General Public License for more details.
33 *
34 * You should have received a copy of the GNU Lesser General Public License
35 * version 3 along with StormByte-Config. If not, see
36 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
37 *
38 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
39 */
40
41#pragma once
42
49#include <StormByte/platform.h>
50#include <StormByte/safe/binary.hxx>
51#include <StormByte/safe/string.hxx>
52#include <StormByte/size.hxx>
53
54#include <istream>
55#include <ostream>
56#include <span>
57#include <string>
58#include <string_view>
59#include <vector>
60
64namespace StormByte::Config {
65 namespace Binary {
66 class Reader;
67 class Writer;
68 }
69
80 friend class Binary::Reader;
81 friend class Binary::Writer;
82 public:
91
96 Config(const Config& config);
97
102 Config(Config&& config) noexcept;
103
109 Config& operator=(const Config& config);
110
116 Config& operator=(Config&& config) noexcept;
117
121 virtual ~Config() noexcept;
123
133 inline Item::Base& operator[](std::string_view path) {
134 return m_root.operator[](path);
135 }
136
142 inline const Item::Base& operator[](std::string_view path) const {
143 return m_root.operator[](path);
144 }
145
153 return m_root[index];
154 }
155
162 const Item::Base& operator[](const StormByte::Size& index) const {
163 return m_root[index];
164 }
165
171 inline bool operator==(const Config& config) const noexcept {
172 return m_root == config.m_root;
173 }
174
180 inline bool operator!=(const Config& config) const noexcept {
181 return !operator==(config);
182 }
183
184
194 Config& operator<<(const Config& source);
195
200 STORMBYTE_FORCE_INLINE void operator<<(std::istream& istream) {
201 std::string text;
202 char chunk[4096];
203 while (istream.read(chunk, sizeof(chunk)) || istream.gcount() > 0)
204 text.append(chunk, static_cast<std::size_t>(istream.gcount()));
205 operator<<(std::string_view(text));
206 }
207
212 void operator<<(std::string_view str);
213
220 friend Config& operator>>(std::istream& istream, Config& file);
221
228 friend Config& operator>>(std::string_view str, Config& file);
230
240 Config& operator>>(Config& dest) const;
241
247 STORMBYTE_FORCE_INLINE std::ostream& operator>>(std::ostream& ostream) const {
248 Save(ostream, Mode::Text);
249 return ostream;
250 }
251
257 STORMBYTE_FORCE_INLINE std::string& operator>>(std::string& str) const {
258 str += static_cast<std::string>(Text());
259 return str;
260 }
261
268 friend std::ostream& operator<<(std::ostream& ostream, const Config& file);
269
276 friend std::string& operator<<(std::string& str, const Config& file);
277
283
288 STORMBYTE_FORCE_INLINE explicit operator std::string() const {
289 return static_cast<std::string>(Text());
290 }
291
297
303 STORMBYTE_FORCE_INLINE void Save(std::ostream& stream, Mode mode = Mode::Text) const {
304 if (mode == Mode::Text) {
305 stream << static_cast<std::string>(Text());
306 return;
307 }
308
309 const auto data = Binary();
310 const auto view = data.span();
311 if (!view.empty())
312 stream.write(reinterpret_cast<const char*>(view.data()), static_cast<std::streamsize>(view.size()));
313 }
314
320 static ExpectedConfig Load(std::string_view text);
321
328
335 STORMBYTE_FORCE_INLINE static ExpectedConfig Load(std::istream& stream, Mode mode = Mode::Text) {
336 if (mode == Mode::Text) {
337 std::string text;
338 char chunk[4096];
339 while (stream.read(chunk, sizeof(chunk)) || stream.gcount() > 0)
340 text.append(chunk, static_cast<std::size_t>(stream.gcount()));
341 return Load(std::string_view(text));
342 }
343
344 if (stream.bad())
345 return StormByte::Unexpected<StormByte::DeserializeError>("Failed to read binary config stream");
346 stream.clear();
347 stream.seekg(0, std::ios::end);
348 const std::streamsize size = stream.tellg();
349 stream.seekg(0, std::ios::beg);
350 std::vector<std::byte> bytes;
351 if (size < 0) {
352 stream.clear();
353 char chunk[4096];
354 while (stream.read(chunk, sizeof(chunk)) || stream.gcount() > 0) {
355 const auto count = static_cast<std::size_t>(stream.gcount());
356 const auto* begin = reinterpret_cast<const std::byte*>(chunk);
357 bytes.insert(bytes.end(), begin, begin + count);
358 }
359 } else {
360 bytes.resize(static_cast<std::size_t>(size));
361 if (size > 0 && !stream.read(reinterpret_cast<char*>(bytes.data()), size))
362 return StormByte::Unexpected<StormByte::DeserializeError>("Failed to read binary config stream");
363 }
364 return Load(StormByte::Safe::Binary(std::span<const std::byte>(bytes)));
365 }
366
367
378 inline Item::Base& Add(const Item::Base& item) {
379 return m_root.Add(item.Clone(), m_on_existing_action);
380 }
381
389 return m_root.Add(std::move(item.Move()), m_on_existing_action);
390 }
391
399 return m_root.Add(item, m_on_existing_action);
400 }
401
409 return m_root.Add(item, on_existing);
410 }
411
415 inline void Clear() noexcept {
416 m_root.Clear();
417 }
418
424 inline bool Exists(std::string_view path) const {
425 return m_root.Exists(path);
426 }
427
433 inline void Remove(std::string_view path) {
434 m_root.Remove(path);
435 }
436
442 inline void Remove(const StormByte::Size& index) {
443 m_root.Remove(index);
444 }
445
450 StormByte::Size Size() const noexcept {
451 return m_root.Size();
452 }
453
458 StormByte::Size Count() const noexcept {
459 return m_root.Count();
460 }
461
467 return m_root.Items();
468 }
469
475 return m_root.Items();
476 }
477
478
489
495
501
508
509 protected:
511
516 };
517
524 STORMBYTE_FORCE_INLINE Config& operator>>(std::istream& istream, Config& file) {
525 file << istream;
526 return file;
527 }
528
535 STORMBYTE_FORCE_INLINE Config& operator>>(std::string_view str, Config& file) {
536 file << str;
537 return file;
538 }
539
546 STORMBYTE_FORCE_INLINE std::ostream& operator<<(std::ostream& ostream, const Config& file) {
547 file.Save(ostream, Mode::Text);
548 return ostream;
549 }
550
557 STORMBYTE_FORCE_INLINE std::string& operator<<(std::string& str, const Config& file) {
558 return file.operator>>(str);
559 }
560}
561
Configuration document (text or versioned binary).
Definition config.hxx:79
void operator<<(std::string_view str)
Initialize configuration from text.
const Item::Base & operator[](std::string_view path) const
Gets a const reference to an item by path.
Definition config.hxx:142
HookFunctions m_before_read_hooks
Hooks executed before reading.
Definition config.hxx:512
void OnParseFailure(FailureHook hook)
Sets a safe function to execute on parse failure.
Item::Base & Add(const Item::Base &item)
Adds an item to the configuration.
Definition config.hxx:378
StormByte::Size Size() const noexcept
Gets the number of items in the current level.
Definition config.hxx:450
void OnExistingAction(const StormByte::Config::OnExistingAction &on_existing)
Sets the action to take when an item name/identity collision occurs.
void AddHookAfterRead(ReadHook hook)
Adds a safe callback executed after a successful read.
std::ostream & operator>>(std::ostream &ostream) const
Output configuration serialized to an output stream (text).
Definition config.hxx:247
void operator<<(std::istream &istream)
Initialize configuration from an input stream (text mode).
Definition config.hxx:200
const Item::Base & operator[](const StormByte::Size &index) const
Gets a const reference to an item by index.
Definition config.hxx:162
Config & operator=(Config &&config) noexcept
Move assignment operator.
Item::Base & Add(Item::Base &&item)
Adds an item to the configuration (move).
Definition config.hxx:388
std::string & operator>>(std::string &str) const
Append serialized text to a caller-owned string.
Definition config.hxx:257
void Save(std::ostream &stream, Mode mode=Mode::Text) const
Write this document to an output stream.
Definition config.hxx:303
Config & operator<<(const Config &source)
Import data from another configuration.
static ExpectedConfig Load(std::istream &stream, Mode mode=Mode::Text)
Read a document from a caller-owned stream.
Definition config.hxx:335
Config(const Config &config)
Copy constructor.
Config & operator>>(Config &dest) const
Output current configuration into another configuration.
bool operator==(const Config &config) const noexcept
Equality operator.
Definition config.hxx:171
void Remove(const StormByte::Size &index)
Removes an item by index.
Definition config.hxx:442
Item::Group m_root
Root group.
Definition config.hxx:510
OptionalFailureHook m_on_parse_failure_hook
Callback executed on failure, empty if unset.
Definition config.hxx:514
bool Exists(std::string_view path) const
Checks if an item exists by path.
Definition config.hxx:424
bool operator!=(const Config &config) const noexcept
Inequality operator.
Definition config.hxx:180
Item::Base & Add(Item::Base::PointerType item, const StormByte::Config::OnExistingAction &on_existing)
Adds an item pointer using an explicit policy.
Definition config.hxx:408
StormByte::Safe::Binary Binary() const
Serialize the document to Base-owned binary bytes.
void Clear() noexcept
Clears all configuration items.
Definition config.hxx:415
void Remove(std::string_view path)
Removes an item by path.
Definition config.hxx:433
virtual ~Config() noexcept
Destructor.
void AddHookBeforeRead(ReadHook hook)
Adds a safe callback executed before reading starts.
Item::Base & operator[](const StormByte::Size &index)
Gets a reference to an item by index.
Definition config.hxx:152
Item::Base & Add(Item::Base::PointerType item)
Adds an item pointer to the configuration.
Definition config.hxx:398
friend Config & operator>>(std::istream &istream, Config &file)
Initializes configuration when istream is on the left-hand side.
Definition config.hxx:524
StormByte::Config::OnExistingAction m_on_existing_action
Collision policy.
Definition config.hxx:515
const StormByte::Safe::Vector< Item::Base::PointerType > & Items() noexcept
Items in the current level.
Definition config.hxx:466
Config & operator=(const Config &config)
Copy assignment operator.
Config()
Default constructor.
static ExpectedConfig Load(const StormByte::Safe::Binary &data)
Load a document from Base-owned binary bytes.
Config(Config &&config) noexcept
Move constructor.
const StormByte::Safe::Vector< Item::Base::PointerType > & Items() const noexcept
Items in the current level.
Definition config.hxx:474
StormByte::Safe::String Text() const
Serialized document as StormByte text.
StormByte::Size Count() const noexcept
Gets the full number of items (including nested).
Definition config.hxx:458
static ExpectedConfig Load(std::string_view text)
Load a document from text.
HookFunctions m_after_read_hooks
Hooks executed after successful reading.
Definition config.hxx:513
Base class for all configuration items.
Definition base.hxx:66
Named container ({ ... }).
Definition group.hxx:57
virtual PointerType Clone() const=0
STORMBYTE_DECLARE_MAYBE_SAFE(StormByte::Config::Config)
All the classes for item configuration.
Definition config.hxx:65
Config module of the StormByte suite.
Definition alias.hxx:51
StormByte::Safe::Function< void(StormByte::Safe::Shared< Item::Group >)> ReadHook
Safe read callback receiving a Base-owned mutable group handle.
Definition hook.hxx:62
StormByte::Expected< Config, StormByte::Exception > ExpectedConfig
Result of loading a configuration document (text or binary).
Definition typedefs.hxx:83
StormByte::Safe::Shared< FailureHook > OptionalFailureHook
Optional parse-failure callback.
Definition alias.hxx:53
OnExistingAction
Forward declaration of the configuration document.
Definition typedefs.hxx:56
StormByte::Safe::Vector< StormByte::Safe::Shared< ReadHook > > HookFunctions
Read callbacks owned by Config.
Definition alias.hxx:52
std::ostream & operator<<(std::ostream &ostream, const Config &file)
Output configuration when ostream is on the left-hand side.
Definition config.hxx:546
StormByte::Safe::Function< bool(StormByte::Safe::Shared< const Item::Group >)> FailureHook
Safe parse-failure callback receiving a Base-owned read-only group handle.
Definition hook.hxx:67
Mode
Serialization / deserialization mode for configuration documents.
Definition typedefs.hxx:72
@ Text
Human-readable configuration syntax (UTF-8 text).
Definition typedefs.hxx:73
Config & operator>>(std::istream &istream, Config &file)
Initializes configuration when istream is on the left-hand side.
Definition config.hxx:524
auto Unexpected(Safe::Shared< E > error)
STL namespace.
#define STORMBYTE_FORCE_INLINE
#define STORMBYTE_CONFIG_PUBLIC
Definition visibility.h:53