Sample helpers

Helper utilities used in the quickstart. More...

Topics
	Serialize/deserialize scalar types
	Serialize container types (brief)
	Serialization definitions used in sample_user_container_types_brief().
	Serialize container types
	Serialization definitions used in sample_user_container_types().

Classes
struct	ErrorHandlerExample
	an error handler used by 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 testing assertion, used only in this quickstart

Functions
bool	report_check (int line, const char *predicate, bool result)
	used by CHECK()
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 ()
	set up a bare-bones implementation of the callbacks
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 quickstart.

Macro Definition Documentation

CHECK

#define CHECK

(

predicate

)

Value:

assert(predicate)

a testing assertion, used only in this quickstart

Definition at line 310 of file quickstart.cpp.

Referenced by GlobalAllocatorExample::check_and_reset(), PerTreeMemoryExample::check_and_reset(), ErrorHandlerExample::check_disabled(), ErrorHandlerExample::check_enabled(), my_map_type< K, V >::check_eq(), my_seq_type< T >::check_eq(), my_type::check_eq(), GlobalAllocatorExample::free(), PerTreeMemoryExample::free(), sample_anchors_and_aliases(), sample_anchors_and_aliases_create(), sample_base64(), sample_create_tree(), sample_create_tree_style(), sample_deserialize_error(), sample_docs(), sample_emit_nested_node(), sample_emit_to_container(), sample_emit_to_stream(), sample_empty_null_values(), sample_error_basic(), sample_error_handler(), sample_error_parse(), sample_error_visit(), sample_error_visit_location(), sample_float_precision(), sample_formatting(), sample_fundamental_types(), sample_global_allocator(), sample_iterate_tree(), sample_json(), sample_lightning_overview(), sample_location_tracking(), sample_parse_file(), sample_parse_in_arena(), sample_parse_in_place(), sample_parse_reuse_parser(), sample_parse_reuse_tree(), sample_parse_reuse_tree_and_parser(), sample_parse_style(), sample_per_tree_allocator(), sample_quick_overview(), sample_serialize_basic(), sample_static_trees(), sample_std_types(), sample_style(), sample_style_flow_formatting(), sample_style_flow_ml_indent(), sample_substr(), sample_tag_directives(), sample_tags(), sample_tree_arena(), sample_user_container_types(), sample_user_container_types_brief(), and sample_user_scalar_types().

Function Documentation

report_check()

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

used by CHECK()

Definition at line 7121 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;
}

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

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

Referenced by main().

default_callbacks()

ryml::Callbacks default_callbacks

(

)

set up a bare-bones implementation of the callbacks

The default 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, and also because they are needed when RYML_NO_DEFAULT_CALLBACKS is defined.

For a different (more involved) implementation of the error callbacks, see the implementation of ErrorHandlerExample below.

Definition at line 7175 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 default 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, and also because they are needed when
        /// @ref RYML_NO_DEFAULT_CALLBACKS is defined.
        ///
        /// For a different (more involved) implementation of the error
        /// callbacks, see the implementation of @ref 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
}

Referenced by ensure_callbacks(), and sample_static_trees().

handle_args()

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

Definition at line 7111 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;
}

Referenced by main().

report_checks()

int report_checks

(

)

Definition at line 7138 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; // LCOV_EXCL_LINE
    else
        std::cout << "SUCCESS!" << std::endl;
    return num_failed_checks;
}

Referenced by main().

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

Referenced by sample_quick_overview().

check_error_occurs()

template<class Fn>

bool ErrorHandlerExample::check_error_occurs

(

Fn &&

fn

)

checking that an error occurs while calling fn

Definition at line 7250 of file quickstart.cpp.

{
    RYML_SAVE_TEST_EXPFAIL_(); // a dev helper to dump all tests
    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;
}

Referenced by check_assertion_occurs(), sample_deserialize_error(), sample_docs(), sample_error_basic(), sample_error_handler(), sample_error_parse(), sample_error_visit(), sample_error_visit_location(), sample_fundamental_types(), and sample_quick_overview().

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 7299 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);
}

Referenced by s_error_basic().

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 7315 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);
}

Referenced by s_error_parse().

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 7337 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);
}

Referenced by s_error_visit().

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

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

Referenced by callbacks(), check_disabled(), and check_enabled().

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

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

Referenced by callbacks(), check_disabled(), and check_enabled().

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

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

Referenced by callbacks(), check_disabled(), and check_enabled().

callbacks()

ryml::Callbacks ErrorHandlerExample::callbacks

(

)

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

Definition at line 7378 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;
}

Referenced by ScopedErrorHandlerExample::ScopedErrorHandlerExample(), sample_docs(), sample_error_handler(), sample_error_parse(), sample_error_visit(), sample_error_visit_location(), sample_fundamental_types(), and sample_quick_overview().

check_enabled()

void ErrorHandlerExample::check_enabled

(

)

const

test that this handler is currently set

Definition at line 7389 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);
}

Referenced by ScopedErrorHandlerExample::ScopedErrorHandlerExample(), and sample_error_handler().

check_disabled()

void ErrorHandlerExample::check_disabled

(

)

const

test that this handler is currently not set

Definition at line 7399 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);
}

Referenced by ScopedErrorHandlerExample::~ScopedErrorHandlerExample(), and sample_error_handler().

Variable Documentation

s_jmp_env

std::jmp_buf s_jmp_env

static

Definition at line 7230 of file quickstart.cpp.

Referenced by ErrorHandlerExample::check_error_occurs().

s_jmp_msg

std::string s_jmp_msg

static

Definition at line 7231 of file quickstart.cpp.