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

Config module of the StormByte suite. More...

Namespaces

namespace  Binary
namespace  Item
 Configuration document items.

Classes

class  Config
 Configuration document (text or versioned binary). More...
class  Exception
 Root exception for Config. More...
class  WrongValueTypeConversion
 Thrown when a value is converted to an incorrect type. More...
class  ValueFailure
 Thrown when setting a value fails due to type mismatch. More...
class  InvalidName
 Thrown when an invalid name is used for an item. More...
class  InvalidPath
 Thrown when an invalid path is used for an item. More...
class  ParseError
 Thrown when a parsing error occurs in a configuration file. More...
class  ItemNotFound
 Thrown when an item cannot be found by its path or name. More...
class  ItemAlreadyExists
 Thrown when attempting to add an item that already exists. More...
class  ItemNameAlreadyExists
 Thrown when an item's name conflicts with an existing name. More...
class  OutOfBounds
 Thrown when an index is out of bounds. More...

Typedefs

using HookFunctions = StormByte::Safe::Vector<StormByte::Safe::Shared<ReadHook>>
 Read callbacks owned by Config.
using OptionalFailureHook = StormByte::Safe::Shared<FailureHook>
 Optional parse-failure callback.
using ReadHook = StormByte::Safe::Function<void(StormByte::Safe::Shared<Item::Group>)>
 Safe read callback receiving a Base-owned mutable group handle.
using FailureHook = StormByte::Safe::Function<bool(StormByte::Safe::Shared<const Item::Group>)>
 Safe parse-failure callback receiving a Base-owned read-only group handle.
using ExpectedConfig = StormByte::Expected<Config, StormByte::Exception>
 Result of loading a configuration document (text or binary).

Enumerations

enum class  OnExistingAction : unsigned short { Keep , Overwrite , ThrowException }
 Forward declaration of the configuration document. More...
enum class  Mode : unsigned short { Text , Binary }
 Serialization / deserialization mode for configuration documents. More...

Functions

Config & operator>> (std::istream &istream, Config &file)
 Initializes configuration when istream is on the left-hand side.
Config & operator>> (std::string_view str, Config &file)
 Initializes configuration when text is on the left-hand side.
std::ostream & operator<< (std::ostream &ostream, const Config &file)
 Output configuration when ostream is on the left-hand side.
std::string & operator<< (std::string &str, const Config &file)
 Output configuration when string is on the left-hand side.
template<typename Callable>
requires StormByte::Type::CopyConstructible<std::remove_cvref_t<Callable>>
ReadHook MakeReadHook (Callable &&callable)
 Creates a read hook whose callable context is cloned and released by its creator.
template<typename Callable>
requires StormByte::Type::CopyConstructible<std::remove_cvref_t<Callable>>
FailureHook MakeFailureHook (Callable &&callable)
 Creates a failure hook whose callable context is cloned and released by its creator.

Detailed Description

Config module of the StormByte suite.

Human-readable and versioned configuration documents.

Typedef Documentation

◆ ExpectedConfig

Result of loading a configuration document (text or binary).

On failure, the error is a StormByte::Exception derivative (for example ParseError or StormByte::DeserializeError).

◆ FailureHook

Safe parse-failure callback receiving a Base-owned read-only group handle.

◆ HookFunctions

◆ OptionalFailureHook

◆ ReadHook

Safe read callback receiving a Base-owned mutable group handle.

Enumeration Type Documentation

◆ Mode

enum class StormByte::Config::Mode : unsigned short
strong

Serialization / deserialization mode for configuration documents.

Selects whether a document is exchanged as human-readable text (the classic StormByte config syntax) or as the versioned binary wire format.

See also
Config::Save
Config::Load
Enumerator
Text 

Human-readable configuration syntax (UTF-8 text).

Binary 

Versioned binary format (magic + format version + payload).

◆ OnExistingAction

enum class StormByte::Config::OnExistingAction : unsigned short
strong

Forward declaration of the configuration document.

Specifies the action to take when a name conflict occurs.

Enumerator
Keep 

Retain the existing item.

Overwrite 

Replace the existing item with the new one.

ThrowException 

Throw an exception to indicate the conflict.

Function Documentation

◆ MakeFailureHook()

template<typename Callable>
requires StormByte::Type::CopyConstructible<std::remove_cvref_t<Callable>>
FailureHook StormByte::Config::MakeFailureHook ( Callable && callable)

Creates a failure hook whose callable context is cloned and released by its creator.

Template Parameters
CallableCopy-constructible callable accepting a shared const group handle and returning bool.
Parameters
callableCallback invoked with the partially parsed group.
Returns
Safe callback value suitable for storing or copying across a DLL boundary.

◆ MakeReadHook()

template<typename Callable>
requires StormByte::Type::CopyConstructible<std::remove_cvref_t<Callable>>
ReadHook StormByte::Config::MakeReadHook ( Callable && callable)

Creates a read hook whose callable context is cloned and released by its creator.

Template Parameters
CallableCopy-constructible callable accepting a shared mutable group handle.
Parameters
callableCallback invoked before/after text parsing.
Returns
Safe callback value suitable for storing or copying across a DLL boundary.

◆ operator<<() [1/2]

std::ostream & StormByte::Config::operator<< ( std::ostream & ostream,
const Config & file )

Output configuration when ostream is on the left-hand side.

Parameters
ostreamOutput stream.
fileConfig to get data from.
Returns
Reference to the output stream.

◆ operator<<() [2/2]

std::string & StormByte::Config::operator<< ( std::string & str,
const Config & file )

Output configuration when string is on the left-hand side.

Parameters
strOutput string.
fileConfig to get data from.
Returns
Reference to the string.

◆ operator>>() [1/2]

Config & StormByte::Config::operator>> ( std::istream & istream,
Config & file )

Initializes configuration when istream is on the left-hand side.

Parameters
istreamInput stream.
fileConfig to put data into.
Returns
Reference to the Config.

◆ operator>>() [2/2]

Config & StormByte::Config::operator>> ( std::string_view str,
Config & file )

Initializes configuration when text is on the left-hand side.

Parameters
strInput text.
fileConfig to put data into.
Returns
Reference to the Config.