Errors and error handlers

Functions
void	sample_error_handler ()
	set custom error handlers
void	sample_error_basic ()
	handler for basic errors, and obtain a full error message with basic context
void	sample_error_parse ()
	handler for parse errors, and obtain a full error message with parse context
void	sample_error_visit ()
	handler for visit errors, and obtain a full error message with visit context
void	sample_error_visit_location ()
	obtaining the YAML location from a visit error

Detailed Description

Function Documentation

sample_error_handler()

void sample_error_handler

(

)

set custom error handlers

demonstrates how to set a custom error handler for ryml

Definition at line 6355 of file quickstart.cpp.

{
    ErrorHandlerExample errh; // browse the implementation of this
                              // class to understand more details
    errh.check_disabled();
    // set the global error handlers. Note the error callbacks must
    // never return: they must either throw an exception, use setjmp()
    // and longjmp(), or abort. Otherwise, the parser will enter into
    // an infinite loop, or the program may crash.
    ryml::set_callbacks(errh.callbacks());
    errh.check_enabled();
    CHECK(errh.check_error_occurs([&]{
        ryml::Tree tree = ryml::parse_in_arena("errorhandler.yml", "[a: b\n}");
    }));
    ryml::set_callbacks(errh.original_callbacks); // restore defaults.
    errh.check_disabled();
}

Referenced by main().

sample_error_basic()

void sample_error_basic

(

)

handler for basic errors, and obtain a full error message with basic context

Definition at line 6376 of file quickstart.cpp.

{
    auto cause_basic_error = []{
        ryml::Tree t;
        ryml::csubstr tag_handle = {}, tag_prefix = {}; // invalid, not filled
        t.add_tag_directive(tag_handle, tag_prefix, 0);
    };
    {
        ScopedErrorHandlerExample errh; // set the example callbacks (scoped)
        CHECK(errh.check_error_occurs(cause_basic_error));
    }
#ifdef RYML_WITH_EXCEPTIONS_
    bool gotit = false;
    try
    {
        cause_basic_error();
    }
    catch(ryml::ExceptionBasic const& exc)
    {
        gotit = true;
        ryml::csubstr msg = ryml::to_csubstr(exc.what());
        CHECK(!exc.errdata_basic.location.name.empty());
        CHECK(!msg.empty());
    }
    CHECK(gotit);
#endif
}

Referenced by main().

sample_error_parse()

void sample_error_parse

(

)

handler for parse errors, and obtain a full error message with parse context

Definition at line 6405 of file quickstart.cpp.

{
    ryml::csubstr ymlsrc = ""
        "{"       "\n"
        "  a: b"  "\n"
        "   ["    "\n"
        "";
    ryml::csubstr ymlfile = "file.yml";
    auto cause_parse_error = [&]{
        return ryml::parse_in_arena(ymlfile, ymlsrc);
    };
    // the YAML in ymlsrc must cause a parse error while it is being
    // parsed. We use our error handler to catch that error, and save
    // the error info:
    ErrorHandlerExample errh;
    {
        ryml::set_callbacks(errh.callbacks());
        CHECK(errh.check_error_occurs(cause_parse_error));
        // the handler in errh saves the error info in itself. Let's
        // use that to see the messages we get.
        //
        // this message is the short message passed into the parse
        // error handler:
        CHECK(errh.saved_msg_short == "invalid character: '['");
        // this message was created inside the handler, by calling
        // ryml::err_parse_format():
        CHECK(ryml::to_csubstr(errh.saved_msg_full).begins_with("file.yml:3: col=4 (12B): ERROR: [parse] invalid character: '['"));
        // If you keep the YAML source buffer around, you can also use
        // it to create/print a larger error message showing the
        // YAML source code context which causes the error:
        std::string msg_ctx = errh.saved_msg_full + "\n";
        ryml::location_format_with_context([&msg_ctx](ryml::csubstr s){
            msg_ctx.append(s.str, s.len);
        }, errh.saved_parse_loc, ymlsrc, "err");
        CHECK(ryml::to_csubstr(msg_ctx).begins_with("file.yml:3: col=4 (12B): ERROR: [parse] invalid character: '['"));
        CHECK(ryml::to_csubstr(msg_ctx).ends_with(
                  "file.yml:3: col=4 (12B): err:"     "\n"
                  "err:"                              "\n"
                  "err:        ["                     "\n"
                  "err:         |"                    "\n"
                  "err:         (here)"               "\n"
                  "err:"                              "\n"
                  "err: see region:"                  "\n"
                  "err:"                              "\n"
                  "err:     {"                        "\n"
                  "err:       a: b"                   "\n"
                  "err:        ["                     "\n"
                  "err:         |"                    "\n"
                  "err:         (here)"               "\n"
                  ""));
        //
        // Let's now check the location (see the message above):
        CHECK(errh.saved_parse_loc.name == ymlfile);
        CHECK(errh.saved_parse_loc.line == 3);
        CHECK(errh.saved_parse_loc.col == 4);
        CHECK(errh.saved_parse_loc.offset == 12);
        CHECK(errh.saved_parse_loc.offset <= ymlsrc.len);
        // ... and this is the location in the ryml source code file where
        // this error was found:
        CHECK(!errh.saved_basic_loc.name.empty());
        CHECK(errh.saved_basic_loc.line > 0);
        CHECK(errh.saved_basic_loc.col > 0);
        CHECK(errh.saved_basic_loc.offset > 0);
        ryml::set_callbacks(errh.original_callbacks);
    }
    // A parse error is also a basic error. If no parse error handler
    // is set, then ryml falls back to a basic error:
    {
        ryml::Callbacks cb = errh.callbacks();
        cb.m_error_parse = nullptr;
        ryml::set_callbacks(cb);
        CHECK(ryml::get_callbacks().m_error_parse == nullptr);
        CHECK(errh.check_error_occurs(cause_parse_error));
        // we got a basic error instead of a parse error:
        CHECK(errh.saved_msg_short == "invalid character: '['");
        // notice that the full message now displays this as a basic
        // error:
        CHECK(errh.saved_msg_full == "file.yml:3: col=4 (12B): ERROR: [basic] invalid character: '['");
        // the yml location is now in the location saved from the basic error
        CHECK(errh.saved_basic_loc.name == ymlfile);
        CHECK(errh.saved_basic_loc.line == 3);
        CHECK(errh.saved_basic_loc.col == 4);
        CHECK(errh.saved_basic_loc.offset == 12);
        CHECK(errh.saved_basic_loc.offset <= ymlsrc.len);
        CHECK(errh.saved_parse_loc.name == ryml::csubstr{});
        CHECK(errh.saved_parse_loc.line == ryml::csubstr::npos);
        CHECK(errh.saved_parse_loc.col == ryml::csubstr::npos);
        CHECK(errh.saved_parse_loc.offset == ryml::csubstr::npos);
        ryml::set_callbacks(errh.original_callbacks);
    }
#ifdef RYML_WITH_EXCEPTIONS_
    bool gotit = false;
    try
    {
        cause_parse_error();
    }
    catch(ryml::ExceptionParse const& exc)
    {
        gotit = true;
        ryml::csubstr msg = ryml::to_csubstr(exc.what());
        CHECK(exc.errdata_parse.ymlloc.name == ymlfile);
        CHECK(exc.errdata_parse.ymlloc.line == 3);
        CHECK(exc.errdata_parse.ymlloc.col == 4);
        CHECK(exc.errdata_parse.ymlloc.offset == 12);
        CHECK(exc.errdata_parse.ymlloc.offset <= ymlsrc.len);
        // the message saved in the exception is just the concrete error description:
        CHECK(msg == "invalid character: '['");
        // to print richer error messages, ryml provides helpers to
        // format that description into a complete error message,
        // containing location and source context indication:
        std::string full;
        auto dumpfn = [&full](ryml::csubstr s) { full.append(s.str, s.len); };
        ryml::err_parse_format(dumpfn, msg, exc.errdata_parse);
        full += '\n';
        ryml::location_format_with_context(dumpfn, exc.errdata_parse.ymlloc, ymlsrc, "err", 3);
        CHECK(ryml::to_csubstr(full).begins_with("file.yml:3: col=4 (12B): ERROR: [parse] invalid character: '['"));
        CHECK(ryml::to_csubstr(full).ends_with(
                  "file.yml:3: col=4 (12B): err:"      "\n"
                  "err:"                               "\n"
                  "err:        ["                      "\n"
                  "err:         |"                     "\n"
                  "err:         (here)"                "\n"
                  "err:"                               "\n"
                  "err: see region:"                   "\n"
                  "err:"                               "\n"
                  "err:     {"                         "\n"
                  "err:       a: b"                    "\n"
                  "err:        ["                      "\n"
                  "err:         |"                     "\n"
                  "err:         (here)"                "\n"
                  ""));
    }
    CHECK(gotit);
    gotit = false;
    try
    {
        cause_parse_error();
    }
    catch(ryml::ExceptionBasic const& exc) // use references! don't slice the exception
    {
        gotit = true;
        ryml::csubstr msg = ryml::to_csubstr(exc.what());
        CHECK(!exc.errdata_basic.location.name.empty());
        CHECK(!msg.empty());
    }
    CHECK(gotit);
#endif
}

Referenced by main().

sample_error_visit()

void sample_error_visit

(

)

handler for visit errors, and obtain a full error message with visit context

Visit errors happen when an error is triggered while reading from a node.

Definition at line 6557 of file quickstart.cpp.

{
    ryml::csubstr ymlfile = "file.yml";
    ryml::csubstr ymlsrc = "float: 123.456";
    ErrorHandlerExample errh;
    {
        ryml::set_callbacks(errh.callbacks());
        ryml::Tree tree = ryml::parse_in_arena(ymlfile, ymlsrc);
        CHECK(errh.check_error_occurs([&]{
            int intval = 0;
            tree["float"].load(&intval); // cannot deserialize 123.456 to int
        }));
        // the handler in errh saves the error info in itself. Let's
        // use that to see the messages we get.
        //
        // this message is the short message passed into the visit error
        CHECK(errh.saved_msg_short == "could not deserialize node");
        // this message was created inside the handler, by calling
        // ryml::err_visit_format():
        CHECK(ryml::csubstr::npos != ryml::to_csubstr(errh.saved_msg_full).find("ERROR: [visit] could not deserialize node"));
        // The location of the visit error is of the C++ source file where
        // the error was detected -- NOT of the YAML source file:
        CHECK(errh.saved_basic_loc.name != ymlfile);
        // However, note that the tree and node id are available:
        CHECK(errh.saved_visit_tree == &tree);
        CHECK(errh.saved_visit_id == tree["float"].id());
        // see sample_error_visit_location() for an example on how
        // to extract the location.
    }
    // visit errors also fall back to basic errors when the visit
    // handler is not set (similar to the behavior of ExceptionVisit):
    {
        ryml::Callbacks cb = errh.callbacks();
        cb.m_error_visit = nullptr;
        ryml::set_callbacks(cb);
        CHECK(ryml::get_callbacks().m_error_visit == nullptr);
        ryml::Tree tree = ryml::parse_in_arena(ymlfile, ymlsrc);
        CHECK(errh.check_error_occurs([&]{
            int intval = 0;
            tree["float"].load(&intval); // cannot deserialize 123.456 to int
        }));
        // we got a basic error instead of a visit error:
        CHECK(errh.saved_msg_short == "could not deserialize node");
        // notice that the full message now displays this as a basic
        // error:
        CHECK(ryml::csubstr::npos != ryml::to_csubstr(errh.saved_msg_full).find("ERROR: [basic] could not deserialize node"));
        // the tree and id are not set, because this was called as a basic error
        CHECK(errh.saved_visit_tree == nullptr);
        CHECK(errh.saved_visit_id == ryml::NONE);
        ryml::set_callbacks(errh.original_callbacks);
    }
#ifdef RYML_WITH_EXCEPTIONS_
    // when using the default ryml callbacks (see
    // RYML_NO_DEFAULT_CALLBACKS), and
    // RYML_DEFAULT_CALLBACK_USES_EXCEPTIONS is defined, the ryml
    // parse handler throws an exception of type ryml::ExceptionVisit,
    // which is derived from ryml::ExceptionBasic.
    {
        const ryml::Tree tree = ryml::parse_in_arena(ymlfile, ymlsrc);
        bool gotit = false;
        try
        {
            int intval = 0;
            tree["float"].load(&intval); // cannot deserialize 123.456 to int
        }
        catch(ryml::ExceptionVisit const& exc)
        {
            gotit = true;
            ryml::csubstr msg = ryml::to_csubstr(exc.what());
            CHECK(!exc.errdata_visit.cpploc.name.empty());
            CHECK(exc.errdata_visit.tree == &tree);
            CHECK(exc.errdata_visit.node == tree["float"].id());
            CHECK(!msg.empty());
        }
        CHECK(gotit);
    }
    // you can also catch the exception as its base,
    // ryml::ExceptionBasic:
    {
        const ryml::Tree tree = ryml::parse_in_arena(ymlfile, ymlsrc);
        bool gotit = false;
        try
        {
            int intval = 0;
            tree["float"].load(&intval); // cannot deserialize 123.456 to int
        }
        catch(ryml::ExceptionBasic const& exc) // use references! don't slice the exception
        {
            gotit = true;
            ryml::csubstr msg = ryml::to_csubstr(exc.what());
            CHECK(!exc.errdata_basic.location.name.empty());
            CHECK(!msg.empty());
        }
        CHECK(gotit);
    }
#endif
}

Referenced by main().

sample_error_visit_location()

void sample_error_visit_location

(

)

obtaining the YAML location from a visit error

It is possible to obtain the YAML location from a visit error: when the tree is obtained from parsing YAML, the messages may be enriched by using a parser set to track the locations.

See sample_location_tracking() for more details on how to use locations.

Definition at line 6661 of file quickstart.cpp.

{
    ScopedErrorHandlerExample errh;
    // we will use locations to show the YAML source context of the
    // node where the visit error was triggered. This is a very
    // convenient feature to show detailed messages when deserializing
    // data read from a file (but do note this is opt-in, and it is
    // not mandatory). See sample_location_tracking() for more details
    // on location tracking.
    ryml::ParserOptions opts = ryml::ParserOptions{}.locations(true);
    ryml::EventHandlerTree evt_handler{};
    ryml::Parser parser(&evt_handler, opts);
    ryml::csubstr ymlfile = "file.yml";
    ryml::csubstr ymlsrc = ""
        "foo: bar"           "\n"
        "char: a"            "\n"
        "int: a"             "\n"
        "float: 123.456"     "\n"
        "";
    const ryml::Tree tree = ryml::parse_in_arena(&parser, ymlfile, ymlsrc);
    // This function will cause a visit error when being called:
    auto cause_visit_error = [&]{
        int intval = 0;
        tree["float"].load(&intval); // cannot deserialize 123.456 to int
    };
    // Like with the parse error, we will use our error handler to
    // catch that visit error, and save the error info:
    CHECK(evt_handler.callbacks() == errh.callbacks());
    CHECK(parser.callbacks() == errh.callbacks());
    CHECK(tree.callbacks() == errh.callbacks());
    {
        CHECK(errh.check_error_occurs(cause_visit_error));
        // the handler in errh saves the error info in itself. Let's
        // use that to see the messages we get.
        //
        // this message is the short message passed into the visit error
        CHECK(errh.saved_msg_short == "could not deserialize node");
        // this message was created inside the handler, by calling
        // ryml::err_visit_format():
        CHECK(ryml::csubstr::npos != ryml::to_csubstr(errh.saved_msg_full).find("ERROR: [visit] could not deserialize node"));
        // The location of the visit error is of the C++ source file where
        // the error was detected -- NOT of the YAML source file:
        CHECK(errh.saved_basic_loc.name != ymlfile);
        // However, note that the tree and node id are available:
        CHECK(errh.saved_visit_tree == &tree);
        CHECK(errh.saved_visit_id == tree["float"].id());
        // ... which we can use to get the location in the YAML source
        // from the parser (but see @ref sample_location_tracking()):
        ryml::Location ymlloc = errh.saved_visit_tree->location(parser, errh.saved_visit_id);
        CHECK(ymlloc.name == ymlfile);
        // In turn, we can use format_location_context() to
        // print/create an error message pointing at the YAML source
        // code:
        std::string msg = errh.saved_msg_full;
        ryml::location_format_with_context([&msg](ryml::csubstr s){
            msg.append(s.str, s.len);
        }, ymlloc, ymlsrc, "err", /*number of lines to show before the error*/3);
        CHECK(ryml::to_csubstr(msg).ends_with(
                  "file.yml:3: col=0 (24B): err:"     "\n"
                  "err:"                              "\n"
                  "err:     float: 123.456"           "\n"
                  "err:     |"                        "\n"
                  "err:     (here)"                   "\n"
                  "err:"                              "\n"
                  "err: see region:"                  "\n"
                  "err:"                              "\n"
                  "err:     foo: bar"                 "\n"
                  "err:     char: a"                  "\n"
                  "err:     int: a"                   "\n"
                  "err:     float: 123.456"           "\n"
                  "err:     |"                        "\n"
                  "err:     (here)"                   "\n"
                  ""));
    }
}

Referenced by main().