StormByte-Config 3.0.0
C++26 configuration-document module of the StormByte suite
Loading...
Searching...
No Matches
StormByte-Config

Platform C++26 CMake License: LGPL v3 or commercial CI Sponsor

This repository is StormByte Config: human-readable text and versioned binary documents for the StormByte C++ suite.

It depends on StormByte Base 3.0.0 and StormByte-BuildMaster >= 2.1.4. Public headers live under StormByte/config/ and cover the document, items (values, comments, groups, lists), Save / Load, and collision / hook policy.

The suite is split on purpose. Base, Buffer, Crypto, Database, Logger, Multimedia, Network and System are other repositories. This one does not implement them.

What this module does

  • Text and binary I/O — Save / Load with Mode::Text or Mode::Binary on any std::ostream / std::istream. Stream operators stay text-only.
  • Versioned binary — magic STBTCF + format version. Older layouts load; newer ones are rejected; save always writes the current version.
  • Values — one concrete Item::Value (text, integer, double, boolean, StormByte::Safe::Binary). Access is Base::As<T>(). Text binary form is Base64 b"..."; the binary document stores raw bytes.
  • Comments — #, //, /* */.
  • Containers — lists [] and groups {}. Counts and indices use StormByte::Size.
  • Hooks — AddHookBeforeRead / AddHookAfterRead / OnParseFailure use copyable StormByte::Safe::Function callbacks and Base-owned group handles.
  • On existing — Keep, Overwrite, or ThrowException (default).
  • Heap — items are Clonable<Base, Safe::Shared<Base>>. Build them with MakePointer when you hold PointerType.

The rest of the suite

Module Role API
Base Exceptions, Expected, serialization, strings, UUID, concepts /StormByte
Buffer FIFO, SharedFIFO, Ring, Producer/Consumer and multi-stage pipelines /StormByte-Buffer
Config This repository /StormByte-Config
Crypto Hash, compress, encrypt, sign and key agreement — Crypto++ never leaves the private tree /StormByte-Crypto
Database One API over SQLite, PostgreSQL and MariaDB /StormByte-Database
Logger Stream logger with levels, headers, human-readable sizes and redaction (ThreadedLog) /StormByte-Logger
Multimedia Decode, encode and containers without raw FFmpeg types; codecs enabled only if present /StormByte-Multimedia
Network Framed packets, Client/Server, IPv4/IPv6 TCP and Buffer pipelines (compress/encrypt) /StormByte-Network
System Processes, pipes and environment variables across Linux, Windows and macOS /StormByte-System

Table of Contents

Installation

Needs a C++26 compiler, CMake 3.28 or newer, StormByte-BuildMaster >= 2.1.4, and StormByte Base 3.0.0. Configure downloads the matching Base release archive. There is no Base submodule. BuildMaster is the installed package when it is >= 2.1.4, otherwise the buildmaster submodule.

git clone --recursive https://github.com/StormByte-Suite/StormByte-Config.git
cd StormByte-Config
cmake -S . -B build
cmake --build build

Manual builds use the compiler and CMake defaults for optimization and CPU selection; set CMAKE_C_FLAGS / CMAKE_CXX_FLAGS or CFLAGS / CXXFLAGS to choose a CPU baseline. Existing build directories may retain Release flags cached by an older version; configure a fresh build directory to discard them. ENABLE_LTO defaults to ON and can be disabled with -DENABLE_LTO=OFF. CI and releases select cpu-baseline: auto through the build action.

Shared vs static follows CMake BUILD_SHARED_LIBS (default ON). A plain configure builds the shared library. -DBUILD_SHARED_LIBS=OFF builds a static archive; on Windows the headers then do not use dllimport. The downloaded Base archive is the same mode.

A shared build keeps this library as its own .so / .dll. Under the LGPL that is usually the simpler way to ship: the user can replace that file. A static archive is folded into your binary. The LGPL still applies to this code; you must give the recipient a way to relink your product with a different build of this library. If that does not fit how you distribute the final product, a commercial license is available from the copyright holder (see License).

For installed Base and Config prefixes, add Base's share/cmake/Modules to CMAKE_MODULE_PATH and both prefixes to CMAKE_PREFIX_PATH, then use the component finder:

find_package(StormByte REQUIRED COMPONENTS Base Config)
target_link_libraries(app PRIVATE StormByte::Config)

Config installs FindStormByteConfig.cmake in share/cmake/Modules. Public headers are included as #include <StormByte/config/….hxx>.

Usage

Headers are #include <StormByte/config/….hxx>. Namespace root is StormByte::Config.

A name or a path takes std::string_view. A literal, a std::string and a Safe::String bind without a cast. A text literal passed to Item::Value binds to const char*: a pointer would otherwise prefer bool.

Load from a stream

#include <fstream>
#include <iostream>
using namespace StormByte::Config;
int main() {
Config config;
std::ifstream file("config.cfg");
file >> config;
const int timeout = config["timeout"].As<Item::Integer>();
const auto& user = config["settings/username"].As<Item::Text>();
std::cout << static_cast<std::string_view>(user) << " " << timeout << std::endl;
}
Configuration document (text or versioned binary).
Definition config.hxx:79
Config module of the StormByte suite.
Definition alias.hxx:51
Tag for As<Integer>() → int.
Definition type.hxx:147
Tag for As<Text>() → StormByte::Safe::String.
Definition type.hxx:150

Existing keys: OnExistingAction (Keep, Overwrite, ThrowException; default is throw).

Build a document

using namespace StormByte::Config;
Config config;
config.Add(Item::Value("username", "example_user"));
config.Add(Item::Value("timeout", 30));
config.Add(Item::Value("feature_timeout", 60.5));
config.Add(Item::Value("enabled", true));
std::byte{'H'}, std::byte{'i'}
})));
Item::Group& settings = config.Add(Item::Group("settings")).As<Item::Group>();
settings.Add(Item::Value("retries", 3));
Item::List& numbers = config.Add(Item::List("favorite_numbers")).As<Item::List>();
numbers.Add(Item::Value(3));
numbers.Add(Item::Value(14));
numbers.Add(Item::Value("pi constant"));
Item::Base & Add(const Item::Base &item)
Adds an item to the configuration.
Definition config.hxx:378
decltype(auto) As()
Typed view of this item.
Definition comment.hxx:71
Base & Add(const Base &item, const StormByte::Config::OnExistingAction &on_existing)
Adds an item (const reference) using an explicit policy.
Definition container.hxx:244
Named container ({ ... }).
Definition group.hxx:57
Unnamed container ([ ... ]).
Definition list.hxx:57
Scalar configuration item.
Definition value.hxx:73

Add copies or moves the item onto the Config heap (Safe::Shared<Base>). After Add, look the node up and mutate it through As.

As

As<T>() is the typed view of an item. T is either a node type or a leaf tag.

T Meaning
Item::Value The scalar leaf. Assignment writes the payload.
Item::Integer int
Item::Double double (an Integer is accepted)
Item::Bool bool
Item::Text StormByte::Safe::String
Item::Binary StormByte::Safe::Binary
Item::Group / Item::List Containers
Item::Comment<CommentType::…> Comment specializations
config["timeout"].As<Item::Integer>() = 45;
int n = config["timeout"].As<Item::Integer>();
double d = config["timeout"].As<Item::Double>();
config["username"].As<Item::Value>() = "other";
const auto& name = config["username"].As<Item::Text>();
Item::Group& settings = config["settings"].As<Item::Group>();
const int retries = settings["retries"].As<Item::Integer>();
const StormByte::Safe::Binary& bytes = config["payload"].As<Item::Binary>();
const auto first = numbers[StormByte::Size{0}].As<Item::Integer>();
Tag for As<Binary>() → StormByte::Safe::Binary.
Definition type.hxx:151
Tag for As<Double>() → double (Integer promotes).
Definition type.hxx:148

Integer promotes to Double. Double does not narrow to Integer. A wrong tag throws StormByte::Config::Exception.

Hooks

Hooks run only on text read (operator<< / >> from a stream or string). They do not run on binary Load.

  • Before-read and after-read callbacks receive StormByte::Safe::Shared<Item::Group>. The handle owns a copy on Base's heap; mutations are committed to the document when the callback succeeds. After-read runs only if parsing succeeded.
  • Parse-failure callbacks receive StormByte::Safe::Shared<const Item::Group>. Return false to swallow the error; true (or no callback) keeps the throw.
  • Use MakeReadHook / MakeFailureHook to wrap copyable callables, including capturing lambdas. Base clones and releases each callable context through functions supplied by the module that created it.

Inject a default timeout if the file omitted it, and refuse to throw on a known-bad lab fixture:

#include <sstream>
using namespace StormByte::Config;
void EnsureTimeout(StormByte::Safe::Shared<Item::Group> root) {
if (!root->Exists("timeout"))
root->Add(Item::Value("timeout", 30));
}
bool IgnoreBrokenFixture(StormByte::Safe::Shared<const Item::Group>) {
return false;
}
void load_app_config(Config& config) {
config.AddHookAfterRead(MakeReadHook(&EnsureTimeout));
config.OnParseFailure(MakeFailureHook(&IgnoreBrokenFixture));
std::istringstream file("username = \"ada\"\n");
file >> config;
// config["timeout"] is 30 even though the file had no timeout key
}
void OnParseFailure(FailureHook hook)
Sets a safe function to execute on parse failure.
void AddHookAfterRead(ReadHook hook)
Adds a safe callback executed after a successful read.
FailureHook MakeFailureHook(Callable &&callable)
Creates a failure hook whose callable context is cloned and released by its creator.
Definition hook.hxx:111
ReadHook MakeReadHook(Callable &&callable)
Creates a read hook whose callable context is cloned and released by its creator.
Definition hook.hxx:77

Captured state is copied with the callback and remains owned by its creating module:

#include <sstream>
using namespace StormByte::Config;
void load_with_counter(Config& config, int& total) {
++total;
root->Add(Item::Value("loads", total), OnExistingAction::Overwrite);
}));
std::istringstream file("username = \"ada\"\n");
file >> config;
}
@ Overwrite
Replace the existing item with the new one.
Definition typedefs.hxx:58

Binary Save / Load

#include <fstream>
#include <iostream>
using namespace StormByte::Config;
int main() {
Config config;
config.Add(Item::Value("username", "example_user"));
config.Add(Item::Value("timeout", 30));
{
std::ofstream out("config.bin", std::ios::binary);
config.Save(out, Mode::Binary);
}
std::ifstream in("config.bin", std::ios::binary);
auto loaded = Config::Load(in, Mode::Binary);
if (!loaded) {
std::cerr << loaded.error()->what() << std::endl;
return 1;
}
std::cout << static_cast<std::string_view>(loaded.value()["username"].As<Item::Text>()) << std::endl;
std::cout << loaded.value()["timeout"].As<Item::Integer>() << std::endl;
}
void Save(std::ostream &stream, Mode mode=Mode::Text) const
Write this document to an output stream.
Definition config.hxx:303
static ExpectedConfig Load(std::string_view text)
Load a document from text.
@ Binary
Versioned binary format (magic + format version + payload).
Definition typedefs.hxx:74

Load returns ExpectedConfig (StormByte::Expected<Config, StormByte::Exception>). A bad magic or a newer format version is an error, not a thrown parse of the payload. For callers passing data across a DLL boundary, use Config::Binary() / Config::Load(const StormByte::Safe::Binary&) or Config::Load(std::string_view) for text. Stream overloads remain caller-side adapters.

Container::Items() and Config::Items() return StormByte::Safe::Vector<StormByte::Safe::Shared<Item::Base>>. Path traversal uses Base's StormByte::Safe::Queue internally.

Text syntax

username = "example_user"
timeout = 30
feature_timeout = 60.5
enabled = true
payload = b"SGVsbG8gV29ybGQ="
favorite_numbers = [3 14 42 "pi constant"]
settings = {
username = "example_user"
timeout = 30
}
# bash comment
// C++ comment
/* multiline */

Text values are UTF-8 and are stored as StormByte::Safe::String. Binary values are StormByte::Safe::Binary. Paths use /. List slots are numeric path segments (list/0).

Contributing

Issues only on this repository. Fork and open a pull request against master.

License

From 2.0.0, original StormByte-Config source is dual-licensed:

  1. GNU Lesser General Public License version 3 or later. See [LICENSE](LICENSE) and https://www.gnu.org/licenses/lgpl-3.0.html.
  2. A commercial license from the copyright holder (David C. Manuelda, StormBytePP).

Neither license covers other StormByte modules or third-party material shipped under thirdparty/. Those keep their own licenses. Neither license grants patent rights.

Binary releases add THIRD-PARTY beside LICENSE. That file is a notice for what was compiled into the shared library, not another grant. The texts it names are the COPYING.* files in the same archive.

Static linking under the LGPL is described under Installation.

Support

StormByte is developed in spare time. Sponsorship is optional and does not buy features, priority or support.