#include <conf.hpp>

Public Member Functions
	Conf (Json data)

	Conf (std::string file)

	Conf (Json data, std::string file)

	Conf (Json data, std::string file, std::string root)

bool	is_from_file () const

const std::string &	file () const

bool	is_empty () const

const Json &	operator* () const

Json &	operator* ()

const Json *	operator-> () const

Json *	operator-> ()

std::string	root () const

bool	has (const std::string &key) const

bool	has (const JsonPointer &ptr) const

bool	has_pointer (const std::string &ptr) const

Conf	at (const std::string &key) const

Conf	at (const JsonPointer &ptr) const

Conf	at_pointer (const std::string &ptr) const

size_t	erase (const std::string &key)

size_t	erase (const JsonPointer &ptr, bool preserve_empty=false)

size_t	erase_pointer (const std::string &ptr, bool preserve_empty=false)

std::vector< Conf >	to_array () const

template<typename T >
T	get () const

template<typename T >
T	get (const std::string &key) const

template<typename T >
T	get (const JsonPointer &ptr) const

template<typename T >
T	get_pointer (const std::string &ptr) const

template<typename T >
T	get_or (const std::string &key, T def) const

template<typename T >
T	get_or (const JsonPointer &ptr, T def) const

template<typename T >
T	get_pointer_or (const std::string &ptr, T def) const

template<typename T >
void	with (const std::string &key, std::function< void(const T &)> fn) const

template<typename T >
void	with (const JsonPointer &ptr, std::function< void(const T &)> fn) const

template<typename T >
void	with_pointer (const std::string &ptr, std::function< void(const T &)> fn) const

template<typename T >
void	try_from (const std::string &key, T &val) const

template<typename T >
void	try_from (const JsonPointer &ptr, T &val) const

template<typename T >
void	try_from_pointer (const std::string &ptr, T &val) const

void	assert_has (const std::string &key) const

void	assert_has (const JsonPointer &ptr) const

void	assert_has_pointer (const std::string &key) const

void	assert_has_type (const std::string &key, JsonType t) const

void	assert_has_type (const JsonPointer &ptr, JsonType t) const

void	assert_has_pointer_type (const std::string &ptr, JsonType t) const

void	assert_has_not (const std::string &key, const std::string &msg="") const

void	assert_has_not (const JsonPointer &ptr, const std::string &msg="") const

void	assert_has_pointer_not (const std::string &ptr, const std::string &msg="") const

std::filesystem::path	resolve_file (const std::filesystem::path &filename) const

std::string	resolve_file (const std::string &filename) const

template<typename... Args>
void	throw_error (std::string_view format, Args &&... args) const

void	throw_error (const std::string &msg) const

void	throw_unexpected (const std::string &key, const std::string &msg="") const

void	throw_unexpected (const JsonPointer &ptr, const std::string &msg="") const

void	throw_missing (const std::string &key) const

void	throw_missing (const JsonPointer &ptr) const

void	throw_wrong_type (const std::string &key="") const

void	throw_wrong_type (const JsonPointer &ptr) const

void	throw_wrong_type (const std::string &key, JsonType expected) const

void	throw_wrong_type (const JsonPointer &ptr, JsonType expected) const

Friends
void	to_json (Json &j, const Conf &c)

void	from_json (const Json &j, Conf &c)

Detailed Description

Conf wraps a JSON with context that allows for more user-friendly errors.

In general, a Conf wraps JSON content that comes from the filesystem and is used for configuration purposes. Even if a class requires only a subset of the JSON, Conf maintains the connection to the original file, which allows errors to be returned that refer to the file and location.

Conf is best used together with the Confable and Schema types.

This class provides many methods that take JSON pointers, either as strings (these methods have pointer in the name to differentiate them from the plain versions) or as JsonPointer.

For more information, see: https://datatracker.ietf.org/doc/html/rfc6901

Member Function Documentation

◆ assert_has() [1/2]

void fable::Conf::assert_has ( const JsonPointer & ptr ) const

Assert that the pointer ptr resolves, throw a ConfError otherwise.

Parameters

ptr	JSON pointer to check

Exceptions

ConfError if field does not exist

◆ assert_has() [2/2]

void fable::Conf::assert_has ( const std::string & key ) const

Assert that the field key resolves, throw a ConfError otherwise.

Parameters

key	target field to check

Exceptions

ConfError if field does not exist

Here is the caller graph for this function:

◆ assert_has_not() [1/2]

void fable::Conf::assert_has_not	(	const JsonPointer &	ptr,
		const std::string &	msg = `""`
	)		const

Assert that the field given by the JSON pointer is not available, throw a ConfError otherwise.

Parameters

ptr	JSON pointer to target field to check for non-existence
msg	optional custom error message (use to explain what AND why)

Exceptions

ConfError if field exists

◆ assert_has_not() [2/2]

void fable::Conf::assert_has_not	(	const std::string &	key,
		const std::string &	msg = `""`
	)		const

Assert that the field key is not available, throw a ConfError otherwise.

Parameters

key	target field to check for non-existence
msg	optional custom error message (use to explain what AND why)

Here is the caller graph for this function:

◆ assert_has_pointer()

void fable::Conf::assert_has_pointer ( const std::string & key ) const

inline

Assert that the pointer ptr resolves, throw a ConfError otherwise.

Parameters

ptr	JSON pointer to check

Exceptions

ConfError	if field does not exist
Json::parse_error	if ptr is not a valid JSON pointer

Here is the call graph for this function:

◆ assert_has_pointer_not()

void fable::Conf::assert_has_pointer_not	(	const std::string &	ptr,
		const std::string &	msg = `""`
	)		const

inline

Assert that the field given by the JSON pointer is not available, throw a ConfError otherwise.

Parameters

ptr	JSON pointer to target field to check for non-existence
msg	optional custom error message (use to explain what AND why)

Exceptions

ConfError if field exists

Here is the call graph for this function:

◆ assert_has_pointer_type()

void fable::Conf::assert_has_pointer_type	(	const std::string &	ptr,
		JsonType	t
	)		const

inline

Assert that the pointer ptr exists and resolves to the type t, throw a ConfError otherwise.

Parameters

ptr	JSON pointer to target field, e.g. "/foo/bar"
t	type target value should have

Exceptions

ConfError	if field non-existent or is wrong type
Json::parse_error	if ptr is not a valid JSON pointer

Here is the call graph for this function:

◆ assert_has_type() [1/2]

void fable::Conf::assert_has_type	(	const JsonPointer &	ptr,
		JsonType	t
	)		const

Assert that the pointer ptr exists and resolves to the type t, throw a ConfError otherwise.

Parameters

ptr	JSON pointer to target field, e.g. "/foo/bar"
t	type target value should have

Exceptions

ConfError if field non-existent or is wrong type

◆ assert_has_type() [2/2]

void fable::Conf::assert_has_type	(	const std::string &	key,
		JsonType	t
	)		const

Assert that the field key exists and resolves to the type t, throw a ConfError otherwise.

Parameters

key	target field to access
t	type target value should have

Exceptions

ConfError if field non-existent or is wrong type

Here is the caller graph for this function:

◆ at() [1/2]

Conf fable::Conf::at ( const JsonPointer & ptr ) const

Return a new Conf basing off the JSON referred to by the JSON pointer.

The root of the new Conf will contain the current root + ptr.

Parameters

ptr	JSON pointer to target field, e.g. "/foo/bar"

Returns: Conf of JSON if it exists

Exceptions

ConfError if the ptr cannot be resolved

Here is the call graph for this function:

◆ at() [2/2]

Conf fable::Conf::at ( const std::string & key ) const

Return a new Conf basing off the JSON at the target field.

The root of the new Conf will contain the current root + key.

Parameters

key	target field to access

Returns: Conf of JSON if it exists

Exceptions

ConfError if the key cannot be found

Here is the call graph for this function:

Here is the caller graph for this function:

◆ at_pointer()

Conf fable::Conf::at_pointer ( const std::string & ptr ) const

inline

Return a new Conf basing off the JSON referred to by the JSON pointer.

The root of the new Conf will contain the current root + ptr.

Parameters

ptr	JSON pointer to target field, e.g. "/foo/bar"

Returns: Conf of JSON if it exists

Exceptions

ConfError	if the ptr cannot be resolved
Json::parse_error	if ptr is not a valid JSON pointer

Here is the call graph for this function:

◆ erase() [1/2]

size_t fable::Conf::erase	(	const JsonPointer &	ptr,
		bool	preserve_empty = `false`
	)

Erase a field from the Conf if it exists and return number of elements removed.

When removing the last element in an object, erase will by default then remove the whole object. This can lead to a cascade, resulting in multiple elements being removed. You can inhibit this behavior by passing true to the preserve_empty parameter.

Notes:

The root object ("/") cannot be erased.
This method should not throw.

Parameters

ptr	JSON pointer to target field to remove
preserve_empty	whether to preserve empty objects

Returns: number of elements removed

◆ erase() [2/2]

size_t fable::Conf::erase ( const std::string & key )

Erase a field from the Conf if it exists and return 1 or 0.

Notes:

The object itself cannot be erased with a key of "".
This method should not throw.

Parameters

key	target field to erase

Returns: number of elements removed

Here is the call graph for this function:

Here is the caller graph for this function:

◆ erase_pointer()

size_t fable::Conf::erase_pointer	(	const std::string &	ptr,
		bool	preserve_empty = `false`
	)

inline

Erase a field from the Conf if it exists and return number of elements removed.

When removing the last element in an object, erase will by default then remove the whole object. This can lead to a cascade, resulting in multiple elements being removed. You can inhibit this behavior by passing true to the preserve_empty parameter.

Notes:

The root object ("/") cannot be erased.

Parameters

ptr	JSON pointer to target field to remove
preserve_empty	whether to preserve empty objects

Returns: number of elements removed

Exceptions

Json::parse_error if ptr is not a valid JSON pointer

Here is the call graph for this function:

◆ file()

const std::string& fable::Conf::file ( ) const

inline

Return the file associated with this configuration.

◆ get() [1/3]

template<typename T >

T fable::Conf::get ( ) const

inline

Return a value of type T.

Exceptions

ConfError if the key is of the wrong type

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get() [2/3]

template<typename T >

T fable::Conf::get ( const JsonPointer & ptr ) const

inline

Return a value of type T at the pointer ptr.

Parameters

ptr	JSON pointer to target field to get

Exceptions

ConfError if the ptr cannot be found or is wrong type

Here is the call graph for this function:

◆ get() [3/3]

template<typename T >

T fable::Conf::get ( const std::string & key ) const

inline

Return a value of type T at the position key.

Parameters

key	target field to get

Exceptions

ConfError if the key cannot be found or is wrong type

Here is the call graph for this function:

◆ get_or() [1/2]

template<typename T >

T fable::Conf::get_or	(	const JsonPointer &	ptr,
		T	def
	)		const

inline

Return a value of type T at the pointer ptr, returning def if the field cannot be found.

Parameters

ptr	JSON pointer to target field to get
def	default value if target field does not exist

Exceptions

ConfError if target Json is of wrong type

Here is the call graph for this function:

◆ get_or() [2/2]

template<typename T >

T fable::Conf::get_or	(	const std::string &	key,
		T	def
	)		const

inline

Return a value of type T for the field key, returning def if the field cannot be found.

Parameters

key	target field to get
def	default value if target field does not exist

Exceptions

ConfError if target Json is of wrong type

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_pointer()

template<typename T >

T fable::Conf::get_pointer ( const std::string & ptr ) const

inline

Return a value of type T at the pointer ptr.

Parameters

ptr	JSON pointer to target field to get

Exceptions

ConfError	if the ptr cannot be found or is wrong type
Json::parse_error	if ptr is not a valid JSON pointer

◆ get_pointer_or()

template<typename T >

T fable::Conf::get_pointer_or	(	const std::string &	ptr,
		T	def
	)		const

inline

Return a value of type T at the pointer ptr, returning def if the field cannot be found.

Parameters

ptr	JSON pointer to target field to get
def	default value if target field does not exist

Exceptions

ConfError	if target Json is of wrong type
Json::parse_error	if ptr is not a valid JSON pointer

Here is the call graph for this function:

◆ has() [1/2]

bool fable::Conf::has ( const JsonPointer & ptr ) const

Return whether the field referred to by JSON pointer is present.

Notes:

This method should not throw.
A field with value 'null' counts as present.

Parameters

ptr	JSON pointer to target field to check for existence

Returns: true if present, false otherwise

◆ has() [2/2]

bool fable::Conf::has ( const std::string & key ) const

inline

Return whether the field is present.

Notes:

This method should not throw.
A field with value 'null' counts as present.

Parameters

key	target field to check for existence

Returns: true if present, false otherwise

Here is the caller graph for this function:

◆ has_pointer()

bool fable::Conf::has_pointer ( const std::string & ptr ) const

inline

Return whether the field referred to by JSON pointer is present.

Notes:

A field with value 'null' counts as present.

Parameters

ptr	JSON pointer to target field to check for existence

Returns: true if present, false otherwise

Exceptions

Json::parse_error if ptr is not a valid JSON pointer

Here is the call graph for this function:

◆ is_empty()

bool fable::Conf::is_empty ( ) const

inline

Return whether this configuration is empty.

◆ is_from_file()

bool fable::Conf::is_from_file ( ) const

inline

Return whether this configuration was read from a file.

If not from a file, then the configuration must have come from one of: a) stdin b) command line c) network
This method should not throw.

◆ operator*() [1/2]

Json& fable::Conf::operator* ( )

inline

Return a reference to the JSON.

This allows operations to be performed on the underlying Json type.

◆ operator*() [2/2]

const Json& fable::Conf::operator* ( ) const

inline

Return a reference to the JSON.

This allows operations to be performed on the underlying Json type.

◆ operator->() [1/2]

Json* fable::Conf::operator-> ( )

inline

Return a pointer to the JSON.

This allows operations to be performed with the underlying Json type.

◆ operator->() [2/2]

const Json* fable::Conf::operator-> ( ) const

inline

Return a pointer to the JSON.

This allows operations to be performed with the underlying Json type.

◆ resolve_file() [1/2]

std::filesystem::path fable::Conf::resolve_file ( const std::filesystem::path & filename ) const

Resolve a path to an absolute path by taking the configuration file into account.

If the path is absolute, return as is.
If the path is relative, but file is stdin, return relative to current working directory.
If the path is relative and file is not stdin, return relative to the file.

◆ resolve_file() [2/2]

std::string fable::Conf::resolve_file ( const std::string & filename ) const

Resolve a path to an absolute path by taking the configuration file into account.

If the path is absolute, return as is.
If the path is relative, but file is stdin, return relative to current working directory.
If the path is relative and file is not stdin, return relative to the file.

◆ root()

std::string fable::Conf::root ( ) const

inline

Return the root of the current JSON formatted as a JSON pointer.

When a Conf is initially created, it has a root of '/'. When at() is used to index into the Conf, a new Conf is returned with the root of that new object set to / plus the field. So if the root is '/foo', and you use at("bar"), then the new root is /foo/bar.

This is primarily used for creating better error messages when something goes wrong.

Returns: string of Conf root formatted as a JSON pointer

◆ throw_error() [1/2]

void fable::Conf::throw_error ( const std::string & msg ) const

Throw a ConfError with the Conf data as the context and the message provided.

Exceptions

ConfError

◆ throw_error() [2/2]

template<typename... Args>

void fable::Conf::throw_error	(	std::string_view	format,
		Args &&...	args
	)		const

inline

Throw a ConfError with the Conf data as the context.

The format string and arguments passed are formated with fmt.

Parameters

format	format string according to fmt
args	arguments for format string

Exceptions

ConfError

Here is the caller graph for this function:

◆ throw_missing() [1/2]

void fable::Conf::throw_missing ( const JsonPointer & ptr ) const

Throw a ConfError explaining the named field is missing, with the Conf data as the context.

Exceptions

ConfError

◆ throw_missing() [2/2]

void fable::Conf::throw_missing ( const std::string & key ) const

Throw a ConfError explaining the named field is missing, with the Conf data as the context.

Exceptions

ConfError

Here is the caller graph for this function:

◆ throw_unexpected() [1/2]

void fable::Conf::throw_unexpected	(	const JsonPointer &	ptr,
		const std::string &	msg = `""`
	)		const

Throw a ConfError explaining the named field is unexpected, with the Conf data as the context.

Parameters

msg	optional message to replace default message

Exceptions

ConfError

◆ throw_unexpected() [2/2]

void fable::Conf::throw_unexpected	(	const std::string &	key,
		const std::string &	msg = `""`
	)		const

Throw a ConfError explaining the named field is unexpected, with the Conf data as the context.

Parameters

msg	optional message to replace default message

Exceptions

ConfError

◆ throw_wrong_type() [1/4]

void fable::Conf::throw_wrong_type ( const JsonPointer & ptr ) const

Throw a ConfError explaining that the named field has the wrong type, with the Conf data as the context.

Exceptions

ConfError

◆ throw_wrong_type() [2/4]

void fable::Conf::throw_wrong_type	(	const JsonPointer &	ptr,
		JsonType	expected
	)		const

Throw a ConfError explaining that the named field has the wrong type, with the Conf data as the context.

Parameters

expected JSON type that is expected

Exceptions

ConfError

◆ throw_wrong_type() [3/4]

void fable::Conf::throw_wrong_type	(	const std::string &	key,
		JsonType	expected
	)		const

Throw a ConfError explaining that the named field has the wrong type, with the Conf data as the context.

Parameters

expected JSON type that is expected

Exceptions

ConfError

◆ throw_wrong_type() [4/4]

void fable::Conf::throw_wrong_type ( const std::string & key = "" ) const

Throw a ConfError explaining that the named field has the wrong type, with the Conf data as the context.

Exceptions

ConfError

Here is the caller graph for this function:

◆ to_array()

std::vector< Conf > fable::Conf::to_array ( ) const

Return an array of Conf values.

This is useful when you want to iterate through individual Conf values (for better error reporting) instead of Json values.

Example:

for (auto&& c : conf.to_array()) {
  // do something with c
}

Exceptions

ConfError if the object is not an array

Here is the caller graph for this function:

◆ try_from() [1/2]

template<typename T >

void fable::Conf::try_from	(	const JsonPointer &	ptr,
		T &	val
	)		const

inline

Write the value at the pointer key to val, if the key can be found.

If the field cannot be found, the value is not modified.

Parameters

[in]	ptr	JSON pointer to target field to get data from
[out]	val	target variable to write value to

Exceptions

ConfError if the value is of the wrong type

Here is the call graph for this function:

◆ try_from() [2/2]

template<typename T >

void fable::Conf::try_from	(	const std::string &	key,
		T &	val
	)		const

inline

Write the value at the field key to val, if the key can be found.

If the field cannot be found, the value is not modified.

Parameters

[in]	key	target field to get data from
[out]	val	target variable to write value to

Exceptions

ConfError if the value is of the wrong type

Here is the caller graph for this function:

◆ try_from_pointer()

template<typename T >

void fable::Conf::try_from_pointer	(	const std::string &	ptr,
		T &	val
	)		const

inline

Write the value at the pointer key to val, if the key can be found.

If the field cannot be found, the value is not modified.

Parameters

[in]	ptr	JSON pointer to target field to get data from
[out]	val	target variable to write value to

Exceptions

a	ConfError if the value is of the wrong type
Json::parse_error	if ptr is not a valid JSON pointer

Here is the call graph for this function:

◆ with() [1/2]

template<typename T >

void fable::Conf::with	(	const JsonPointer &	ptr,
		std::function< void(const T &)>	fn
	)		const

inline

Perform the function on the value of the pointer ptr, if the field can be found; otherwise the function is not executed.

Exceptions

ConfError if the value is of the wrong type

◆ with() [2/2]

template<typename T >

void fable::Conf::with	(	const std::string &	key,
		std::function< void(const T &)>	fn
	)		const

inline

Perform the function on the value of the field key, if the field can be found; otherwise the function is not executed.

Exceptions

ConfError if the value is of the wrong type

◆ with_pointer()

template<typename T >

void fable::Conf::with_pointer	(	const std::string &	ptr,
		std::function< void(const T &)>	fn
	)		const

inline

Perform the function on the value of the pointer ptr, if the field can be found; otherwise the function is not executed.

Exceptions

ConfError	if the value is of the wrong type
Json::parse_error	if ptr is not a valid JSON pointer

Friends And Related Function Documentation

◆ from_json

void from_json	(	const Json &	j,
		Conf &	c
	)

friend

Conversion function for automatic "deserialization" of Json in Conf.

This fulfills the interface provided by nlohmann::json.

◆ to_json

void to_json	(	Json &	j,
		const Conf &	c
	)

friend

Conversion function for automatic "serialization" of Conf in Json.

This fulfills the interface provided by nlohmann::json.

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

/home/docs/checkouts/readthedocs.org/user_builds/cloe/checkouts/v0.23.0/fable/include/fable/conf.hpp
/home/docs/checkouts/readthedocs.org/user_builds/cloe/checkouts/v0.23.0/fable/src/fable/conf.cpp

Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ assert_has() [1/2]

◆ assert_has() [2/2]

◆ assert_has_not() [1/2]

◆ assert_has_not() [2/2]

◆ assert_has_pointer()

◆ assert_has_pointer_not()

◆ assert_has_pointer_type()

◆ assert_has_type() [1/2]

◆ assert_has_type() [2/2]

◆ at() [1/2]

◆ at() [2/2]

◆ at_pointer()

◆ erase() [1/2]

◆ erase() [2/2]

◆ erase_pointer()

◆ file()

◆ get() [1/3]

◆ get() [2/3]

◆ get() [3/3]

◆ get_or() [1/2]

◆ get_or() [2/2]

◆ get_pointer()

◆ get_pointer_or()

◆ has() [1/2]

◆ has() [2/2]

◆ has_pointer()

◆ is_empty()

◆ is_from_file()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ resolve_file() [1/2]

◆ resolve_file() [2/2]

◆ root()

◆ throw_error() [1/2]

◆ throw_error() [2/2]

◆ throw_missing() [1/2]

◆ throw_missing() [2/2]

◆ throw_unexpected() [1/2]

◆ throw_unexpected() [2/2]

◆ throw_wrong_type() [1/4]

◆ throw_wrong_type() [2/4]

◆ throw_wrong_type() [3/4]

◆ throw_wrong_type() [4/4]

◆ to_array()

◆ try_from() [1/2]

◆ try_from() [2/2]

◆ try_from_pointer()

◆ with() [1/2]

◆ with() [2/2]

◆ with_pointer()

Friends And Related Function Documentation

◆ from_json

◆ to_json