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.
| 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 |
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.
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:
Config installs FindStormByteConfig.cmake in share/cmake/Modules. Public headers are included as #include <StormByte/config/….hxx>.
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.
Existing keys: OnExistingAction (Keep, Overwrite, ThrowException; default is throw).
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<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 |
Integer promotes to Double. Double does not narrow to Integer. A wrong tag throws StormByte::Config::Exception.
Hooks run only on text read (operator<< / >> from a stream or string). They do not run on binary Load.
Inject a default timeout if the file omitted it, and refuse to throw on a known-bad lab fixture:
Captured state is copied with the callback and remains owned by its creating module:
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 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).
Issues only on this repository. Fork and open a pull request against master.
From 2.0.0, original StormByte-Config source is dual-licensed:
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.
StormByte is developed in spare time. Sponsorship is optional and does not buy features, priority or support.