Configuration document (text or versioned binary). More...

#include <StormByte/config/config.hxx>

Collaboration diagram for StormByte::Config::Config:

[legend]

Public Member Functions
Construction
	Config ()
	Default constructor.

	Config (const Config &config)
	Copy constructor.

	Config (Config &&config) noexcept
	Move constructor.

Config &	operator= (const Config &config)
	Copy assignment operator.

Config &	operator= (Config &&config) noexcept
	Move assignment operator.

virtual	~Config () noexcept
	Destructor.

Access
Item::Base &	operator[] (const StormByte::String::String &path)
	Gets a reference to an item by path.

const Item::Base &	operator[] (const StormByte::String::String &path) const
	Gets a const reference to an item by path.

Item::Base &	operator[] (std::string_view path)
	Gets a reference to an item by a path view.

const Item::Base &	operator[] (std::string_view path) const
	Gets a const reference to an item by a path view.

Item::Base &	operator[] (const StormByte::Size &index)
	Gets a reference to an item by index.

const Item::Base &	operator[] (const StormByte::Size &index) const
	Gets a const reference to an item by index.

bool	operator== (const Config &config) const noexcept
	Equality operator.

bool	operator!= (const Config &config) const noexcept
	Inequality operator.

Items
Item::Base &	Add (const Item::Base &item)
	Adds an item to the configuration.

Item::Base &	Add (Item::Base &&item)
	Adds an item to the configuration (move).

Item::Base &	Add (Item::Base::PointerType item)
	Adds an item pointer to the configuration.

Item::Base &	Add (Item::Base::PointerType item, const StormByte::Config::OnExistingAction &on_existing)
	Adds an item pointer using an explicit policy.

void	Clear () noexcept
	Clears all configuration items.

bool	Exists (const StormByte::String::String &path) const
	Checks if an item exists by path.

bool	Exists (std::string_view path) const
	Checks if an item exists by a path view.

void	Remove (const StormByte::String::String &path)
	Removes an item by path.

void	Remove (std::string_view path)
	Removes an item by a path view.

void	Remove (const StormByte::Size &index)
	Removes an item by index.

StormByte::Size	Size () const noexcept
	Gets the number of items in the current level.

StormByte::Size	Count () const noexcept
	Gets the full number of items (including nested).

constexpr std::span< const Item::Base::PointerType >	Items () noexcept
	Items in the current level.

constexpr std::span< const Item::Base::PointerType >	Items () const noexcept
	Items in the current level.

Policy
void	OnExistingAction (const StormByte::Config::OnExistingAction &on_existing)
	Sets the action to take when an item name/identity collision occurs.

void	OnParseFailure (OnFailureHook hook)
	Sets a stateless function to execute on parse failure.

void	OnParseFailure (StormByte::Shared< FailureHook > hook)
	Sets a stateful hook to execute on parse failure.

void	AddHookBeforeRead (HookFunction hook)
	Adds a stateless hook executed before reading starts.

void	AddHookBeforeRead (StormByte::Shared< ReadHook > hook)
	Adds a stateful hook executed before reading starts.

void	AddHookAfterRead (HookFunction hook)
	Adds a stateless hook executed after a successful read.

void	AddHookAfterRead (StormByte::Shared< ReadHook > hook)
	Adds a stateful hook executed after a successful read.

Protected Attributes
Item::Group	m_root
	Root group.

HookFunctions	m_before_read_hooks
	Hooks executed before reading.

HookFunctions	m_after_read_hooks
	Hooks executed after successful reading.

OptionalFailureHook	m_on_parse_failure_hook
	Hook executed on failure.

StormByte::Config::OnExistingAction	m_on_existing_action
	Collision policy.

Friends
class	Binary::Reader

class	Binary::Writer

Input
Config &	operator>> (std::istream &istream, Config &file)
	Initializes configuration when istream is on the left-hand side.

Config &	operator>> (const StormByte::String::String &str, Config &file)
	Initializes configuration when String is on the left-hand side.

Config &	operator>> (const std::string &str, Config &file)
	Initializes configuration when string is on the left-hand side.

Config &	operator<< (const Config &source)
	Import data from another configuration.

void	operator<< (std::istream &istream)
	Initialize configuration from an input stream (text mode).

void	operator<< (const StormByte::String::String &str)
	Initialize configuration from a string (text mode).

void	operator<< (const std::string &str)
	Initialize configuration from a caller-owned `std::string` (text mode).

Output
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.

Config &	operator>> (Config &dest) const
	Output current configuration into another configuration.

std::ostream &	operator>> (std::ostream &ostream) const
	Output configuration serialized to an output stream (text).

std::string &	operator>> (std::string &str) const
	Append serialized text to a caller-owned string.

StormByte::String::String	Text () const
	Serialized document as StormByte text.

	operator std::string () const
	Converts the current configuration to a string (text form).

void	Save (std::ostream &stream, Mode mode=Mode::Text) const
	Write this document to an output stream.

static ExpectedConfig	Load (std::istream &stream, Mode mode=Mode::Text)
	Read a document from an input stream.

Detailed Description

Configuration document (text or versioned binary).

A document holds:

Boolean, double, integer, string and binary values
Comments (single-line or multi-line)
Groups and lists

Constructor & Destructor Documentation

◆ Config() [1/3]

StormByte::Config::Config::Config ( )

Default constructor.

◆ Config() [2/3]

StormByte::Config::Config::Config ( const Config & config )

Copy constructor.

Parameters

config Configuration to copy.

◆ Config() [3/3]

StormByte::Config::Config::Config ( Config && config )

noexcept

Move constructor.

Parameters

config Configuration to move.

◆ ~Config()

virtual StormByte::Config::Config::~Config ( )

virtualnoexcept

Destructor.

Defined in this module so catch matches across a DLL.

Member Function Documentation

◆ Add() [1/4]

Item::Base & StormByte::Config::Config::Add ( const Item::Base & item )

inline

Adds an item to the configuration.

Parameters

item	The item to add.

Exceptions

ItemNameAlreadyExists if the item's name already exists.

Returns: A reference to the added item.

◆ Add() [2/4]

Item::Base & StormByte::Config::Config::Add ( Item::Base && item )

inline

Adds an item to the configuration (move).

Parameters

item	Item to add.

Exceptions

ItemNameAlreadyExists if item name already exists.

Returns: Reference to the added item.

◆ Add() [3/4]

Item::Base & StormByte::Config::Config::Add ( Item::Base::PointerType item )

inline

Adds an item pointer to the configuration.

Parameters

item	Item pointer to add.

Exceptions

ItemNameAlreadyExists if item name already exists.

Returns: Reference to the added item.

◆ Add() [4/4]

Item::Base & StormByte::Config::Config::Add	(	Item::Base::PointerType	item,
		const StormByte::Config::OnExistingAction &	on_existing
	)

inline

Adds an item pointer using an explicit policy.

Parameters

item	Item pointer to add.
on_existing	Action to take if the item already exists.

Returns: Reference to the added item.

◆ AddHookAfterRead() [1/2]

void StormByte::Config::Config::AddHookAfterRead ( HookFunction hook )

Adds a stateless hook executed after a successful read.

Parameters

hook	Function pointer.

◆ AddHookAfterRead() [2/2]

void StormByte::Config::Config::AddHookAfterRead ( StormByte::Shared< ReadHook > hook )

Adds a stateful hook executed after a successful read.

Parameters

hook	Hook allocated with MakePointer / MakeReadHook.

◆ AddHookBeforeRead() [1/2]

void StormByte::Config::Config::AddHookBeforeRead ( HookFunction hook )

Adds a stateless hook executed before reading starts.

Parameters

hook	Function pointer.

◆ AddHookBeforeRead() [2/2]

void StormByte::Config::Config::AddHookBeforeRead ( StormByte::Shared< ReadHook > hook )

Adds a stateful hook executed before reading starts.

Parameters

hook	Hook allocated with MakePointer / MakeReadHook.

◆ Clear()

void StormByte::Config::Config::Clear ( )

inlinenoexcept

Clears all configuration items.

◆ Count()

StormByte::Size StormByte::Config::Config::Count ( ) const

inlinenoexcept

Gets the full number of items (including nested).

Returns: Total number of items.

◆ Exists() [1/2]

bool StormByte::Config::Config::Exists ( const StormByte::String::String & path ) const

inline

Checks if an item exists by path.

Parameters

path	Path to the item.

Returns: true if the item exists.

◆ Exists() [2/2]

bool StormByte::Config::Config::Exists ( std::string_view path ) const

inline

Checks if an item exists by a path view.

Parameters

path	Path to the item.

Returns: true if the item exists.

◆ Items() [1/2]

constexpr std::span< const Item::Base::PointerType > StormByte::Config::Config::Items ( ) const

inlineconstexprnoexcept

Items in the current level.

Returns: Span of item pointers.

◆ Items() [2/2]

constexpr std::span< const Item::Base::PointerType > StormByte::Config::Config::Items ( )

inlineconstexprnoexcept

Items in the current level.

The span cannot reseat or grow the store; each pointer's item is mutable.

Returns: Span of item pointers.

◆ Load()

static ExpectedConfig StormByte::Config::Config::Load	(	std::istream &	stream,
		Mode	mode = `Mode::Text`
	)

static

Read a document from an input stream.

Parameters

stream	Source (file, stringstream, etc.).
mode	Text (default): config syntax; Binary: versioned wire format.

Returns: Config on success, or a StormByte::Exception derivative on failure.

◆ OnExistingAction()

void StormByte::Config::Config::OnExistingAction ( const StormByte::Config::OnExistingAction & on_existing )

Sets the action to take when an item name/identity collision occurs.

The policy is applied to the root container and will be inherited by all nested containers.

Parameters

on_existing The policy to use.

◆ OnParseFailure() [1/2]

void StormByte::Config::Config::OnParseFailure ( OnFailureHook hook )

Sets a stateless function to execute on parse failure.

Parameters

hook	Function to execute. Return false to swallow the error.

◆ OnParseFailure() [2/2]

void StormByte::Config::Config::OnParseFailure ( StormByte::Shared< FailureHook > hook )

Sets a stateful hook to execute on parse failure.

Parameters

hook	Hook allocated with MakePointer / MakeFailureHook.

◆ operator std::string()

StormByte::Config::Config::operator std::string ( ) const

inlineexplicit

Converts the current configuration to a string (text form).

Returns: Serialized configuration text on the caller heap.

◆ operator!=()

bool StormByte::Config::Config::operator!= ( const Config & config ) const

inlinenoexcept

Inequality operator.

Parameters

config Configuration to compare.

Returns: true if not equal.

◆ operator<<() [1/4]

Config & StormByte::Config::Config::operator<< ( const Config & source )

Import data from another configuration.

Parameters

source Source configuration to import.

Returns: Reference to this configuration.

◆ operator<<() [2/4]

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

Initialize configuration from a caller-owned std::string (text mode).

Parameters

str	Input text.

◆ operator<<() [3/4]

void StormByte::Config::Config::operator<< ( const StormByte::String::String & str )

Initialize configuration from a string (text mode).

Parameters

str	Input text. Copied into the parser; not stored as `std::string`.

◆ operator<<() [4/4]

void StormByte::Config::Config::operator<< ( std::istream & istream )

Initialize configuration from an input stream (text mode).

Parameters

istream Input stream.

◆ operator=() [1/2]

Config & StormByte::Config::Config::operator= ( Config && config )

noexcept

Move assignment operator.

Parameters

config Configuration to move.

Returns: Reference to this Config.

◆ operator=() [2/2]

Config & StormByte::Config::Config::operator= ( const Config & config )

Copy assignment operator.

Parameters

config Configuration to assign.

Returns: Reference to this Config.

◆ operator==()

bool StormByte::Config::Config::operator== ( const Config & config ) const

inlinenoexcept

Equality operator.

Parameters

config Configuration to compare.

Returns: true if equal.

◆ operator>>() [1/3]

Config & StormByte::Config::Config::operator>> ( Config & dest ) const

Output current configuration into another configuration.

Parameters

dest	Destination configuration.

Returns: Reference to the destination configuration.

◆ operator>>() [2/3]

std::ostream & StormByte::Config::Config::operator>> ( std::ostream & ostream ) const

Output configuration serialized to an output stream (text).

Parameters

ostream Output stream.

Returns: Reference to the output stream.

◆ operator>>() [3/3]

std::string & StormByte::Config::Config::operator>> ( std::string & str ) const

Append serialized text to a caller-owned string.

Parameters

str	Output string.

Returns: Reference to the string.

◆ operator[]() [1/6]

Item::Base & StormByte::Config::Config::operator[] ( const StormByte::Size & index )

inline

Gets a reference to an item by index.

Parameters

index Index of the item.

Exceptions

OutOfBounds if index is out of bounds.

Returns: Item reference.

◆ operator[]() [2/6]

const Item::Base & StormByte::Config::Config::operator[] ( const StormByte::Size & index ) const

inline

Gets a const reference to an item by index.

Parameters

index Index of the item.

Exceptions

OutOfBounds if index is out of bounds.

Returns: Item const reference.

◆ operator[]() [3/6]

Item::Base & StormByte::Config::Config::operator[] ( const StormByte::String::String & path )

inline

Gets a reference to an item by path.

Parameters

path	Path to the item.

Returns: Item reference.

◆ operator[]() [4/6]

const Item::Base & StormByte::Config::Config::operator[] ( const StormByte::String::String & path ) const

inline

Gets a const reference to an item by path.

Parameters

path	Path to the item.

Returns: Item const reference.

◆ operator[]() [5/6]

Item::Base & StormByte::Config::Config::operator[] ( std::string_view path )

inline

Gets a reference to an item by a path view.

Parameters

path	Path to the item.

Returns: Item reference.

◆ operator[]() [6/6]

const Item::Base & StormByte::Config::Config::operator[] ( std::string_view path ) const

inline

Gets a const reference to an item by a path view.

Parameters

path	Path to the item.

Returns: Item const reference.

◆ Remove() [1/3]

void StormByte::Config::Config::Remove ( const StormByte::Size & index )

inline

Removes an item by index.

Parameters

index Index of the item.

Exceptions

OutOfBounds if index is out of bounds.

◆ Remove() [2/3]

void StormByte::Config::Config::Remove ( const StormByte::String::String & path )

inline

Removes an item by path.

Parameters

path	Item path.

Exceptions

ItemNotFound if item is not found.

◆ Remove() [3/3]

void StormByte::Config::Config::Remove ( std::string_view path )

inline

Removes an item by a path view.

Parameters

path	Item path.

◆ Save()

void StormByte::Config::Config::Save	(	std::ostream &	stream,
		Mode	mode = `Mode::Text`
	)		const

Write this document to an output stream.

Parameters

stream	Destination (file, stringstream, etc.).
mode	Text (default): config syntax; Binary: versioned wire format.

◆ Size()

StormByte::Size StormByte::Config::Config::Size ( ) const

inlinenoexcept

Gets the number of items in the current level.

Returns: Number of items.

◆ Text()

StormByte::String::String StormByte::Config::Config::Text ( ) const

Serialized document as StormByte text.

Returns: Owned UTF-8 text.

Friends And Related Symbol Documentation

◆ Binary::Reader

friend class Binary::Reader

friend

◆ Binary::Writer

friend class Binary::Writer

friend

◆ operator<< [1/2]

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

friend

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

Parameters

ostream	Output stream.
file	Config to get data from.

Returns: Reference to the output stream.

◆ operator<< [2/2]

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

friend

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

Parameters

str	Output string.
file	Config to get data from.

Returns: Reference to the string.

◆ operator>> [1/3]

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

friend

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

Parameters

str	Input text.
file	Config to put data into.

Returns: Reference to the Config.

◆ operator>> [2/3]

Config & operator>>	(	const StormByte::String::String &	str,
		Config &	file
	)

friend

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

Parameters

str	Input text.
file	Config to put data into.

Returns: Reference to the Config.

◆ operator>> [3/3]

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

friend

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

Parameters

istream	Input stream.
file	Config to put data into.

Returns: Reference to the Config.

Member Data Documentation

◆ m_after_read_hooks

HookFunctions StormByte::Config::Config::m_after_read_hooks

protected

Hooks executed after successful reading.

◆ m_before_read_hooks

HookFunctions StormByte::Config::Config::m_before_read_hooks

protected

Hooks executed before reading.

◆ m_on_existing_action

StormByte::Config::OnExistingAction StormByte::Config::Config::m_on_existing_action

protected

Collision policy.

◆ m_on_parse_failure_hook

OptionalFailureHook StormByte::Config::Config::m_on_parse_failure_hook

protected

Hook executed on failure.

◆ m_root

Item::Group StormByte::Config::Config::m_root

protected

Root group.

The documentation for this class was generated from the following file:

lib/public/StormByte/config/config.hxx

Public Member Functions

Protected Attributes

Friends

Input

Output

Detailed Description

Constructor & Destructor Documentation

◆ Config() [1/3]

◆ Config() [2/3]

◆ Config() [3/3]

◆ ~Config()

Member Function Documentation

◆ Add() [1/4]

◆ Add() [2/4]

◆ Add() [3/4]

◆ Add() [4/4]

◆ AddHookAfterRead() [1/2]

◆ AddHookAfterRead() [2/2]

◆ AddHookBeforeRead() [1/2]

◆ AddHookBeforeRead() [2/2]

◆ Clear()

◆ Count()

◆ Exists() [1/2]

◆ Exists() [2/2]

◆ Items() [1/2]

◆ Items() [2/2]

◆ Load()

◆ OnExistingAction()

◆ OnParseFailure() [1/2]

◆ OnParseFailure() [2/2]

◆ operator std::string()

◆ operator!=()

◆ operator<<() [1/4]

◆ operator<<() [2/4]

◆ operator<<() [3/4]

◆ operator<<() [4/4]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ operator>>() [1/3]

◆ operator>>() [2/3]

◆ operator>>() [3/3]

◆ operator[]() [1/6]

◆ operator[]() [2/6]

◆ operator[]() [3/6]

◆ operator[]() [4/6]

◆ operator[]() [5/6]

◆ operator[]() [6/6]

◆ Remove() [1/3]

◆ Remove() [2/3]

◆ Remove() [3/3]

◆ Save()

◆ Size()

◆ Text()

Friends And Related Symbol Documentation

◆ Binary::Reader

◆ Binary::Writer

◆ operator<< [1/2]

◆ operator<< [2/2]

◆ operator>> [1/3]

◆ operator>> [2/3]

◆ operator>> [3/3]

Member Data Documentation

◆ m_after_read_hooks

◆ m_before_read_hooks

◆ m_on_existing_action

◆ m_on_parse_failure_hook

◆ m_root