Sample helpers

Helper utilities used in the sample. More...

Modules
	Serialize/deserialize scalar types
	Serialize/deserialize container types
	To serialize/deserialize container types to a tree, implement the appropriate functions:

Classes
struct	ErrorHandlerExample
	an example error handler, required for some of the quickstart examples. More...
struct	ScopedErrorHandlerExample
	Shows how to create a scoped error handler. More...
struct	GlobalAllocatorExample
struct	PerTreeMemoryExample
	an example for a per-tree memory allocator More...

Macros
#define	CHECK(predicate)   assert(predicate)
	a quick'n'dirty assertion to verify a predicate More...

Functions
void	ensure_callbacks ()
	set up default callbacks when ryml does not provide them (ie when RYML_NO_DEFAULT_CALLBACKS is defined) More...
ryml::Callbacks	default_callbacks ()
	a bare-bones implementation of the callbacks More...
template<class CharContainer >
CharContainer	file_get_contents (const char *filename)
	load a file from disk and return a newly created CharContainer More...
template<class CharContainer >
size_t	file_get_contents (const char *filename, CharContainer *v)
	load a file from disk into an existing CharContainer More...
template<class CharContainer >
void	file_put_contents (const char *filename, CharContainer const &v, const char *access)
	save a buffer into a file More...
void	file_put_contents (const char *filename, const char *buf, size_t sz, const char *access)
	save a buffer into a file More...
bool	report_check (int line, const char *predicate, bool result)
int	report_checks ()
template<class Fn >
bool	ErrorHandlerExample::check_assertion_occurs (Fn &&fn)
	checking that an assertion occurs while calling fn. More...
template<class Fn >
bool	ErrorHandlerExample::check_error_occurs (Fn &&fn)
	checking that an error occurs while calling fn More...
void	ErrorHandlerExample::on_error_basic (ryml::csubstr msg, ryml::ErrorDataBasic const &errdata)
	this is where the callback implementation goes. More...
void	ErrorHandlerExample::on_error_parse (ryml::csubstr msg, ryml::ErrorDataParse const &errdata)
	this is where the callback implementation goes. More...
void	ErrorHandlerExample::on_error_visit (ryml::csubstr msg, ryml::ErrorDataVisit const &errdata)
	this is where the callback implementation goes. More...
static void	ErrorHandlerExample::s_error_basic (ryml::csubstr msg, ryml::ErrorDataBasic const &errdata, void *this_)
	trampoline function to call the object's method More...
static void	ErrorHandlerExample::s_error_parse (ryml::csubstr msg, ryml::ErrorDataParse const &errdata, void *this_)
	trampoline function to call the object's method More...
static void	ErrorHandlerExample::s_error_visit (ryml::csubstr msg, ryml::ErrorDataVisit const &errdata, void *this_)
	trampoline function to call the object's method More...
ryml::Callbacks	ErrorHandlerExample::callbacks ()
	a helper to create the Callbacks object for the custom error handler More...
void	ErrorHandlerExample::check_enabled () const
	test that this handler is currently set More...
void	ErrorHandlerExample::check_disabled () const
	test that this handler is currently not set More...

Variables
static std::jmp_buf	s_jmp_env
static std::string	s_jmp_msg

Detailed Description

Helper utilities used in the sample.

Macro Definition Documentation

CHECK

#define CHECK

(

predicate

)

assert(predicate)

a quick'n'dirty assertion to verify a predicate

Definition at line 294 of file quickstart.cpp.

Function Documentation

ensure_callbacks()

void ensure_callbacks

(

)

set up default callbacks when ryml does not provide them (ie when RYML_NO_DEFAULT_CALLBACKS is defined)

Definition at line 6094 of file quickstart.cpp.

                                                                 : "));

default_callbacks()

ryml::Callbacks default_callbacks

(

)

a bare-bones implementation of the callbacks

Definition at line 6054 of file quickstart.cpp.

     : buffer
to: be parsed
map with key:
  first: value
  second: value
seq with key:
  - first value
  - second value
  -
    - nested first value
    - nested second value
  -
    nested first: value
    nested second: value
)");
    // (Likewise, the docval tree can no longer be used to query.)
    //
    // For key-less block-style maps, the location of the container
    // points at the first child's key. For example, in this case
    // the root does not have a key, so its location is taken
    // to be at the first child:
    loc = tree2.rootref().location(parser);
    CHECK(parser.location_contents(loc).begins_with("a new"));
    CHECK(loc.offset == 1u);
    CHECK(loc.line == 1u);
    CHECK(loc.col == 0u);
    // note the first child points exactly at the same place:
    loc = tree2["a new"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("a new"));
    CHECK(loc.offset == 1u);
    CHECK(loc.line == 1u);
    CHECK(loc.col == 0u);
    loc = tree2["to"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("to"));
    CHECK(loc.line == 2u);
    CHECK(loc.col == 0u);

file_get_contents() [1/2]

template<class CharContainer >

CharContainer file_get_contents

(

const char *

filename

)

load a file from disk and return a newly created CharContainer

Definition at line 6312 of file quickstart.cpp.

{
    #ifdef C4_EXCEPTIONS
    throw std::runtime_error(s);
    #else
    s_jmp_msg = s;
    std::longjmp(s_jmp_env, 1);  // jump to the corresponding call to setjmp().

References s_jmp_env, and s_jmp_msg.

file_get_contents() [2/2]

template<class CharContainer >

size_t file_get_contents	(	const char *	filename,
		CharContainer *	v
	)

load a file from disk into an existing CharContainer

Definition at line 6293 of file quickstart.cpp.

    {
        std::forward<Fn>(fn)();
    }
    else
    {
        got_error = true;
    }
    #endif
    return got_error;
}
 
namespace {

file_put_contents() [1/2]

template<class CharContainer >

void file_put_contents	(	const char *	filename,
		CharContainer const &	v,
		const char *	access = "wb"
	)

save a buffer into a file

Definition at line 6321 of file quickstart.cpp.

{

References ErrorHandlerExample::saved_msg_short.

file_put_contents() [2/2]

void file_put_contents	(	const char *	filename,
		const char *	buf,
		size_t	sz,
		const char *	access
	)

save a buffer into a file

Definition at line 6327 of file quickstart.cpp.

                                              {
        saved_msg_full.append(s.str, s.len);
    }, msg, errdata);
    // Save the error params for subsequent testing in the quickstart.
    saved_msg_full_with_context = saved_msg_full;
    saved_basic_loc = errdata.location;

References ErrorHandlerExample::saved_msg_full.

report_check()

bool report_check	(	int	line,
		const char *	predicate,
		bool	result
	)

Definition at line 6003 of file quickstart.cpp.

                                                     {"));
    CHECK(loc.offset == 0u);
    CHECK(loc.line == 0u);
    CHECK(loc.col == 0u);
    // on the next call, we only pay O(log(numlines)) because the
    // rebuild is already available:
    loc = tree["aa"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("aa"));
    CHECK(loc.offset == 2u);
    CHECK(loc.line == 1u);
    CHECK(loc.col == 0u);
    // KEYSEQ in flow style: points at the key

report_checks()

int report_checks

(

)

Definition at line 6017 of file quickstart.cpp.

check_assertion_occurs()

template<class Fn >

bool ErrorHandlerExample::check_assertion_occurs

(

Fn &&

fn

)

checking that an assertion occurs while calling fn.

assertions are enabled if RYML_USE_ASSERT is defined.

Definition at line 6115 of file quickstart.cpp.

                                                                 : "));

check_error_occurs()

template<class Fn >

bool ErrorHandlerExample::check_error_occurs

(

Fn &&

fn

)

checking that an error occurs while calling fn

Definition at line 6127 of file quickstart.cpp.

                                                                 : "));
    CHECK(loc.line == 13u);
    CHECK(loc.col == 4u);
    loc = tree2["seq with key"][3][0].location(parser);
    CHECK(parser.location_contents(loc).begins_with("nested first: "));
    CHECK(loc.line == 13u);
    CHECK(loc.col == 4u);
}
 
 
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
 
 
/** @addtogroup doc_sample_helpers
 * @{ */
 
namespace /*anon*/ {
static int num_checks = 0;
static int num_failed_checks = 0;
} // namespace /*anon*/
 
 
bool report_check(int line, const char *predicate, bool result)
{
    ++num_checks;
    const char *msg = predicate ? "OK! " : "OK!";
    if(!result)
    {

on_error_basic()

void ErrorHandlerExample::on_error_basic	(	ryml::csubstr	msg,
		ryml::ErrorDataBasic const &	errdata
	)

this is where the callback implementation goes.

Remember that it must not return.

Definition at line 6175 of file quickstart.cpp.

          {
// LCOV_EXCL_START
/** dump (part of an) error message to terminal
 * @ingroup doc_sample_helpers */
void errdump(ryml::csubstr s)
{

on_error_parse()

void ErrorHandlerExample::on_error_parse	(	ryml::csubstr	msg,
		ryml::ErrorDataParse const &	errdata
	)

this is where the callback implementation goes.

Remember that it must not return.

See also

ryml::format_location_context

Definition at line 6191 of file quickstart.cpp.

{
    fputc('\n', stderr); // NOLINT
    fflush(NULL); // NOLINT
}
// LCOV_EXCL_STOP
} // namespace
 
 
/** a bare-bones implementation of the callbacks
 * @ingroup doc_sample_helpers */
ryml::Callbacks default_callbacks()
{
    return ryml::Callbacks{}
        .set_allocate([](size_t len, void* , void *){
            return malloc(len); // NOLINT
        })
        .set_free([](void* mem, size_t, void *){

on_error_visit()

void ErrorHandlerExample::on_error_visit	(	ryml::csubstr	msg,
		ryml::ErrorDataVisit const &	errdata
	)

this is where the callback implementation goes.

Remember that it must not return.

Definition at line 6213 of file quickstart.cpp.

                                                                                       {
            ryml::err_basic_format(errdump, msg, errdata); // format the message, printing to stderr
            errend(); // print newline and flush
            abort(); // abort (must never return: abort, or exception or setjmp)
        })
        .set_error_parse([](ryml::csubstr msg, ryml::ErrorDataParse const& errdata, void *){
            ryml::err_parse_format(errdump, msg, errdata); // format the message, printing to out
            errend(); // print newline and flush
            abort(); // abort (must never return: abort, or exception or setjmp)
        })
        .set_error_visit([](ryml::csubstr msg, ryml::ErrorDataVisit const& errdata, void *){

References c4::yml::err_basic_format().

s_error_basic()

void ErrorHandlerExample::s_error_basic ( ryml::csubstr  msg, ryml::ErrorDataBasic const &  errdata, void *  this_  )

static

trampoline function to call the object's method

Definition at line 6235 of file quickstart.cpp.

{

s_error_parse()

void ErrorHandlerExample::s_error_parse ( ryml::csubstr  msg, ryml::ErrorDataParse const &  errdata, void *  this_  )

static

trampoline function to call the object's method

Definition at line 6240 of file quickstart.cpp.

{

s_error_visit()

void ErrorHandlerExample::s_error_visit ( ryml::csubstr  msg, ryml::ErrorDataVisit const &  errdata, void *  this_  )

static

trampoline function to call the object's method

Definition at line 6245 of file quickstart.cpp.

callbacks()

ryml::Callbacks ErrorHandlerExample::callbacks

(

)

a helper to create the Callbacks object for the custom error handler

Definition at line 6254 of file quickstart.cpp.

check_enabled()

void ErrorHandlerExample::check_enabled

(

)

const

test that this handler is currently set

Definition at line 6265 of file quickstart.cpp.

{
    #if RYML_USE_ASSERT
    return check_error_occurs(std::forward<Fn>(fn));
    #else
    (void)fn; // do nothing otherwise, as there would be undefined behavior
    return true;
    #endif
}
/** checking that an error occurs while calling fn

References ErrorHandlerExample::check_error_occurs().

check_disabled()

void ErrorHandlerExample::check_disabled

(

)

const

test that this handler is currently not set

Definition at line 6275 of file quickstart.cpp.

{
    saved_msg_short.clear();
    saved_msg_full.clear();
    saved_msg_full_with_context.clear();
    saved_basic_loc = {};
    saved_parse_loc = {};
    saved_visit_tree = {};

References c4::yml::NONE, ErrorHandlerExample::saved_basic_loc, ErrorHandlerExample::saved_msg_full, ErrorHandlerExample::saved_msg_full_with_context, ErrorHandlerExample::saved_msg_short, ErrorHandlerExample::saved_parse_loc, ErrorHandlerExample::saved_visit_id, and ErrorHandlerExample::saved_visit_tree.

Variable Documentation

s_jmp_env

std::jmp_buf s_jmp_env

static

Definition at line 6107 of file quickstart.cpp.

s_jmp_msg

std::string s_jmp_msg

static

Definition at line 6108 of file quickstart.cpp.