Sample helpers

Helper utilities used in the sample. More...

Topics
	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)
	a quick'n'dirty assertion to verify a predicate

Functions
void	ensure_callbacks ()
	set up default callbacks when ryml does not provide them (ie when RYML_NO_DEFAULT_CALLBACKS is defined)
ryml::Callbacks	default_callbacks ()
	a bare-bones implementation of the callbacks
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.
template<class Fn>
bool	ErrorHandlerExample::check_error_occurs (Fn &&fn)
	checking that an error occurs while calling fn
void	ErrorHandlerExample::on_error_basic (ryml::csubstr msg, ryml::ErrorDataBasic const &errdata)
	this is where the callback implementation goes.
void	ErrorHandlerExample::on_error_parse (ryml::csubstr msg, ryml::ErrorDataParse const &errdata)
	this is where the callback implementation goes.
void	ErrorHandlerExample::on_error_visit (ryml::csubstr msg, ryml::ErrorDataVisit const &errdata)
	this is where the callback implementation goes.
static void	ErrorHandlerExample::s_error_basic (ryml::csubstr msg, ryml::ErrorDataBasic const &errdata, void *this_)
	trampoline function to call the object's method
static void	ErrorHandlerExample::s_error_parse (ryml::csubstr msg, ryml::ErrorDataParse const &errdata, void *this_)
	trampoline function to call the object's method
static void	ErrorHandlerExample::s_error_visit (ryml::csubstr msg, ryml::ErrorDataVisit const &errdata, void *this_)
	trampoline function to call the object's method
ryml::Callbacks	ErrorHandlerExample::callbacks ()
	a helper to create the Callbacks object for the custom error handler
void	ErrorHandlerExample::check_enabled () const
	test that this handler is currently set
void	ErrorHandlerExample::check_disabled () const
	test that this handler is currently not set

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

)

Value:

assert(predicate)

a quick'n'dirty assertion to verify a predicate

Definition at line 305 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 6570 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 6530 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
}

report_check()

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

Definition at line 6476 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 6466 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 6493 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 6591 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 6603 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 6651 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 6667 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 6689 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 6711 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 6716 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 6721 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 6730 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 6741 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 6751 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 6583 of file quickstart.cpp.

s_jmp_msg

std::string s_jmp_msg

static

Definition at line 6584 of file quickstart.cpp.