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)
void	handle_args (int argc, const char *argv[])
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 309 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 6433 of file quickstart.cpp.

{
#ifdef RYML_NO_DEFAULT_CALLBACKS
    ryml::set_callbacks(default_callbacks());
#endif
}

default_callbacks()

ryml::Callbacks default_callbacks

(

)

a bare-bones implementation of the callbacks

Definition at line 6393 of file quickstart.cpp.

{
    return ryml::Callbacks{}
        .set_allocate([](size_t len, void* , void *){
            return malloc(len); // NOLINT
        })
        .set_free([](void* mem, size_t, void *){
            free(mem); // NOLINT
        })
        //
        // The error callbacks won't be called in this quickstart,
        // because no errors are expected. But we implement them here
        // to show how a bare-bones implementation looks like.
        //
        // For a different (more involved) implementation of the error
        // callbacks, see the implementation of ErrorHandlerExample
        // below.
        //
        // LCOV_EXCL_START
        .set_error_basic([](ryml::csubstr msg, ryml::ErrorDataBasic const& errdata, void *){
            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 *){
            ryml::err_visit_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)
        });
        // LCOV_EXCL_STOP
}

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 6651 of file quickstart.cpp.

{
    CharContainer cc;
    file_get_contents(filename, &cc);
    return cc;
}

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 6632 of file quickstart.cpp.

{
    std::FILE *fp = std::fopen(filename, "rb"); // NOLINT
    if(fp == nullptr) _RYML_ERR_BASIC("{}: could not open file", filename);
    std::fseek(fp, 0, SEEK_END); // NOLINT
    long sz = std::ftell(fp); // NOLINT
    v->resize(static_cast<typename CharContainer::size_type>(sz));
    if(sz)
    {
        std::rewind(fp); // NOLINT
        size_t ret = std::fread(&(*v)[0], 1, v->size(), fp);
        if(ret != (size_t)sz) _RYML_ERR_BASIC("{}: failed to read: expect {}B, got {}B", filename, sz, ret);
    }
    std::fclose(fp); // NOLINT
    return v->size();
}

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 6660 of file quickstart.cpp.

{
    file_put_contents(filename, v.empty() ? "" : &v[0], v.size(), access);
}

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 6666 of file quickstart.cpp.

{
    std::FILE *fp = std::fopen(filename, access);
    if(fp == nullptr) _RYML_ERR_BASIC("{}: could not open file", filename);
    std::fwrite(buf, 1, sz, fp); // NOLINT
    std::fclose(fp); // NOLINT
}

report_check()

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

Definition at line 6339 of file quickstart.cpp.

{
    ++num_checks;
    const char *msg = predicate ? "OK! " : "OK!";
    if(!result)
    {
        ++num_failed_checks;                  // LCOV_EXCL_LINE
        msg = predicate ?  "FAIL: " : "FAIL"; // LCOV_EXCL_LINE
    }
    if(!result || !quiet_mode)
    {
        std::cout << __FILE__ << ':' << line << ": " << msg << (predicate ? predicate : "") << std::endl;
    }
    return result;
}

handle_args()

void handle_args	(	int	argc,
		const char *	argv[]
	)

Definition at line 6329 of file quickstart.cpp.

{
    auto arg_matches = [](const char *arg, const char *shortform, const char *longform) {
        return (0 == strcmp(arg, shortform) || 0 == strcmp(arg, longform));
    };
    for(int i = 1; i < argc; ++i)
        if(arg_matches(argv[i], "-q", "--quiet"))
            quiet_mode = true;
}

report_checks()

int report_checks

(

)

Definition at line 6356 of file quickstart.cpp.

{
    std::cout << "Completed " << num_checks << " checks." << std::endl;
    if(num_failed_checks)
        std::cout << "ERROR: " << num_failed_checks << '/' << num_checks << " checks failed." << std::endl;
    else
        std::cout << "SUCCESS!" << std::endl;
    return num_failed_checks;
}

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 6454 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
}

check_error_occurs()

template<class Fn >

bool ErrorHandlerExample::check_error_occurs

(

Fn &&

fn

)

checking that an error occurs while calling fn

Definition at line 6466 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 = {};
    saved_visit_id = ryml::NONE;
    bool got_error = false;
    #ifdef C4_EXCEPTIONS
    try
    {
        std::forward<Fn>(fn)();
    }
    catch(std::exception const&)
    {
        got_error = true;
    }
    #else
    if(setjmp(s_jmp_env) == 0)
    {
        std::forward<Fn>(fn)();
    }
    else
    {
        got_error = true;
    }
    #endif
    return got_error;
}

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 6514 of file quickstart.cpp.

{
    saved_msg_short.assign(msg.str, msg.len);
    // build a full error message with location
    ryml::err_basic_format([this](ryml::csubstr s){
        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;
    stopexec(saved_msg_short);
}

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 6530 of file quickstart.cpp.

{
    saved_msg_short.assign(msg.str, msg.len);
    // build a full error message with location
    ryml::err_parse_format([this](ryml::csubstr s){
        saved_msg_full.append(s.str, s.len);
    }, msg, errdata);
    // Save the error params for subsequent testing in the quickstart.
    //
    // To add the source context, the source buffer is required. If
    // the caller is interested in enriching the full message with the
    // source buffer context, he can ensure that the source buffer is
    // kept, and then arrange the handler to access it.
    // For now, we assign the full message without context:
    saved_msg_full_with_context = saved_msg_full;
    saved_basic_loc = errdata.cpploc;
    saved_parse_loc = errdata.ymlloc;
    stopexec(saved_msg_full);
}

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 6552 of file quickstart.cpp.

{
    saved_msg_short.assign(msg.str, msg.len);
    // build a full error message with location
    ryml::err_visit_format([this](ryml::csubstr s){
        saved_msg_full.append(s.str, s.len);
    }, msg, errdata);
    // Save the error params for subsequent testing in the quickstart.
    //
    // To add the source context, the source buffer is required. If
    // the caller is interested in enriching the full message with the
    // source buffer context, he can ensure that the source buffer is
    // kept, and then arrange the handler to access it.
    // For now, we assign the full message without context:
    saved_msg_full_with_context = saved_msg_full;
    saved_basic_loc = errdata.cpploc;
    saved_visit_tree = errdata.tree;
    saved_visit_id = errdata.node;
    stopexec(saved_msg_full);
}

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 6574 of file quickstart.cpp.

{
    static_cast<ErrorHandlerExample*>(this_)->on_error_basic(msg, errdata);
}

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 6579 of file quickstart.cpp.

{
    static_cast<ErrorHandlerExample*>(this_)->on_error_parse(msg, errdata);
}

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 6584 of file quickstart.cpp.

{
    static_cast<ErrorHandlerExample*>(this_)->on_error_visit(msg, errdata);
}

callbacks()

ryml::Callbacks ErrorHandlerExample::callbacks

(

)

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

Definition at line 6593 of file quickstart.cpp.

{
    ryml::Callbacks copy = original_callbacks;
    copy.set_user_data(this)
        .set_error_basic(&ErrorHandlerExample::s_error_basic)
        .set_error_parse(&ErrorHandlerExample::s_error_parse)
        .set_error_visit(&ErrorHandlerExample::s_error_visit);
    return copy;
}

check_enabled()

void ErrorHandlerExample::check_enabled

(

)

const

test that this handler is currently set

Definition at line 6604 of file quickstart.cpp.

{
    ryml::Callbacks const& current = ryml::get_callbacks();
    CHECK(current.m_error_basic == &s_error_basic);
    CHECK(current.m_error_parse == &s_error_parse);
    CHECK(current.m_error_visit == &s_error_visit);
    CHECK(current.m_allocate == original_callbacks.m_allocate);
    CHECK(current.m_free == original_callbacks.m_free);
}

check_disabled()

void ErrorHandlerExample::check_disabled

(

)

const

test that this handler is currently not set

Definition at line 6614 of file quickstart.cpp.

{
    ryml::Callbacks const& current = ryml::get_callbacks();
    CHECK(current.m_error_basic != &s_error_basic);
    CHECK(current.m_error_parse != &s_error_parse);
    CHECK(current.m_error_visit != &s_error_visit);
    CHECK(current.m_allocate == original_callbacks.m_allocate);
    CHECK(current.m_free == original_callbacks.m_free);
}

Variable Documentation

s_jmp_env

std::jmp_buf s_jmp_env

static

Definition at line 6446 of file quickstart.cpp.

s_jmp_msg

std::string s_jmp_msg

static

Definition at line 6447 of file quickstart.cpp.