Parsing

Functions
void	sample_parse_file ()
	ready-to-go example of parsing a file from disk More...
void	sample_parse_in_place ()
	parse a mutable YAML source buffer More...
void	sample_parse_in_arena ()
	parse a read-only YAML source buffer More...
void	sample_parse_reuse_tree ()
	parse into an existing tree, maybe into a node More...
void	sample_parse_reuse_parser ()
	reuse an existing parser More...
void	sample_parse_reuse_tree_and_parser ()
	how to reuse existing trees and parsers More...
void	sample_parse_style ()
	shows how rapidyaml retains the style of parsed YAML More...

Detailed Description

Function Documentation

void sample_parse_file

(

)

ready-to-go example of parsing a file from disk

demonstrate how to load a YAML file from disk to parse with ryml.

ryml offers no overload to directly parse files from disk; it only parses source buffers (which may be mutable or immutable). It is up to the caller to first load the file contents into a buffer before parsing with ryml. To help with this you can use the (efficient) helper [file_get_contents](c4::yml::file_get_contents()). See also the analogous c4::yml::file_put_contents( "file_put_contents")

See also

Parse utilities

Definition at line 1951 of file quickstart.cpp.

Referenced by main().

{
    const char filename[] = "ryml_example.yml";
    std::string yaml = ""
        "foo: 1"  "\n"
        "bar:"    "\n"
        "- 2"     "\n"
        "- 3"     "\n";
    // because this is a minimal sample, it assumes nothing on the
    // environment/OS (other than that it can read/write files). So we
    // create the file on the fly:
    ryml::file_put_contents(yaml, filename);

    // now we can load it into a std::string (for example):
    {
        std::string contents = ryml::file_get_contents<std::string>(filename);
        ryml::Tree tree = ryml::parse_in_arena(ryml::to_csubstr(contents)); // immutable (csubstr) overload
        CHECK(tree["foo"].val() == "1");
        CHECK(tree["bar"][0].val() == "2");
        CHECK(tree["bar"][1].val() == "3");
    }

    // or we can use a vector<char> instead:
    {
        std::vector<char> contents = ryml::file_get_contents<std::vector<char>>(filename);
        ryml::Tree tree = ryml::parse_in_place(ryml::to_substr(contents)); // mutable (substr) overload
        CHECK(tree["foo"].val() == "1");
        CHECK(tree["bar"][0].val() == "2");
        CHECK(tree["bar"][1].val() == "3");
    }

    // generally, any contiguous char container can be used with ryml,
    // provided that the ryml::substr/ryml::csubstr view can be
    // created out of it.
    //
    // ryml provides the overloads above for these two containers, but
    // if you are using another container it should be very easy (only
    // requires pointer and length).
}

void sample_parse_in_place

(

)

parse a mutable YAML source buffer

demonstrate in-place parsing of a mutable YAML source buffer.

See also

Parse utilities

Definition at line 1996 of file quickstart.cpp.

Referenced by main().

{
    // Like the name suggests, parse_in_place() directly mutates the
    // source buffer in place
    char src[] = "{foo: 1, bar: [2, 3]}"; // ryml can parse in situ
    ryml::substr srcview = src; // a mutable view to the source buffer
    ryml::Tree tree = ryml::parse_in_place(srcview); // you can also reuse the tree and/or parser
    ryml::ConstNodeRef root = tree.crootref(); // get a constant reference to the root

    CHECK(root.is_map());
    CHECK(root["foo"].is_keyval());
    CHECK(root["foo"].key() == "foo");
    CHECK(root["foo"].val() == "1");
    CHECK(root["bar"].is_seq());
    CHECK(root["bar"].has_key());
    CHECK(root["bar"].key() == "bar");
    CHECK(root["bar"][0].val() == "2");
    CHECK(root["bar"][1].val() == "3");

    // deserializing:
    int foo = 0, bar0 = 0, bar1 = 0;
    root["foo"].load(&foo);
    root["bar"][0].load(&bar0);
    root["bar"][1].load(&bar1);
    CHECK(foo == 1);
    CHECK(bar0 == 2);
    CHECK(bar1 == 3);

    // after parsing, the tree holds views to the source buffer:
    CHECK(root["foo"].val().data()     == src + strlen("{foo: "));
    CHECK(root["foo"].val().begin()    == src + strlen("{foo: "));
    CHECK(root["foo"].val().end()      == src + strlen("{foo: 1"));
    CHECK(root["foo"].val().is_sub(srcview)); // equivalent to the previous three assertions
    CHECK(root["bar"][0].val().data()  == src + strlen("{foo: 1, bar: ["));
    CHECK(root["bar"][0].val().begin() == src + strlen("{foo: 1, bar: ["));
    CHECK(root["bar"][0].val().end()   == src + strlen("{foo: 1, bar: [2"));
    CHECK(root["bar"][0].val().is_sub(srcview)); // equivalent to the previous three assertions
    CHECK(root["bar"][1].val().data()  == src + strlen("{foo: 1, bar: [2, "));
    CHECK(root["bar"][1].val().begin() == src + strlen("{foo: 1, bar: [2, "));
    CHECK(root["bar"][1].val().end()   == src + strlen("{foo: 1, bar: [2, 3"));
    CHECK(root["bar"][1].val().is_sub(srcview)); // equivalent to the previous three assertions

    // NOTE. parse_in_place() cannot accept ryml::csubstr
    // so this will cause a /compile/ error:
    ryml::csubstr csrcview = srcview; // ok, can assign from mutable to immutable
    //tree = ryml::parse_in_place(csrcview); // compile error, cannot mutate an immutable view
    (void)csrcview;
}

void sample_parse_in_arena

(

)

parse a read-only YAML source buffer

demonstrate parsing of a read-only YAML source buffer

See also

Parse utilities

Definition at line 2050 of file quickstart.cpp.

Referenced by main().

{
    // to parse read-only memory, ryml will copy first to the tree's
    // arena, and then parse the copied buffer:
    ryml::Tree tree = ryml::parse_in_arena("{foo: 1, bar: [2, 3]}");
    ryml::ConstNodeRef root = tree.crootref(); // get a const reference to the root

    CHECK(root.is_map());
    CHECK(root["foo"].is_keyval());
    CHECK(root["foo"].key() == "foo");
    CHECK(root["foo"].val() == "1");
    CHECK(root["bar"].is_seq());
    CHECK(root["bar"].has_key());
    CHECK(root["bar"].key() == "bar");
    CHECK(root["bar"][0].val() == "2");
    CHECK(root["bar"][1].val() == "3");

    // deserializing:
    int foo = 0, bar0 = 0, bar1 = 0;
    root["foo"].load(&foo);
    root["bar"][0].load(&bar0);
    root["bar"][1].load(&bar1);
    CHECK(foo == 1);
    CHECK(bar0 == 2);
    CHECK(bar1 == 3);

    // NOTE. parse_in_arena() cannot accept ryml::substr. Overloads
    // receiving substr buffers are declared, but intentionally left
    // undefined, so this will cause a /linker/ error
    char src[] = "{foo: is it really true}";
    ryml::substr srcview = src;
    //tree = ryml::parse_in_place(srcview); // linker error, overload intentionally undefined

    // If you really intend to parse a mutable buffer in the arena,
    // then simply convert it to immutable prior to calling
    // parse_in_arena():
    ryml::csubstr csrcview = srcview; // assigning from src also works
    tree = ryml::parse_in_arena(csrcview); // OK! csrcview is immutable
    CHECK(tree["foo"].val() == "is it really true");
}

void sample_parse_reuse_tree

(

)

parse into an existing tree, maybe into a node

demonstrate reuse/modification of tree when parsing

See also

Parse utilities

Definition at line 2096 of file quickstart.cpp.

Referenced by main().

{
    ryml::Tree tree;

    // it will always be faster if the tree's size is conveniently reserved:
    tree.reserve(30); // reserve 30 nodes (good enough for this sample)
    // if you are using the tree's arena to serialize data,
    // then reserve also the arena's size:
    tree.reserve_arena(256); // reserve 256 characters (good enough for this sample)

    // now parse into the tree:
    ryml::csubstr yaml = ""
        "foo: 1"        "\n"
        "bar: [2,3]"    "\n"
        "";
    ryml::parse_in_arena(yaml, &tree);

    ryml::ConstNodeRef root = tree.crootref();
    CHECK(root.num_children() == 2);
    CHECK(root.is_map());
    CHECK(root["foo"].is_keyval());
    CHECK(root["foo"].key() == "foo");
    CHECK(root["foo"].val() == "1");
    CHECK(root["bar"].is_seq());
    CHECK(root["bar"].has_key());
    CHECK(root["bar"].key() == "bar");
    CHECK(root["bar"][0].val() == "2");
    CHECK(root["bar"][1].val() == "3");
    CHECK(ryml::emitrs_yaml<std::string>(tree) == yaml);

    // WATCHOUT: parsing into an existing tree will APPEND to it:
    ryml::parse_in_arena("{foo2: 12, bar2: [22, 32]}", &tree);
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "foo: 1"         "\n"
          "bar: [2,3]"     "\n"
          "foo2: 12"       "\n"
          "bar2: [22,32]"  "\n"
          "");
    CHECK(root.num_children() == 4);
    CHECK(root["foo2"].is_keyval());
    CHECK(root["foo2"].key() == "foo2");
    CHECK(root["foo2"].val() == "12");
    CHECK(root["bar2"].is_seq());
    CHECK(root["bar2"].has_key());
    CHECK(root["bar2"].key() == "bar2");
    CHECK(root["bar2"][0].val() == "22");
    CHECK(root["bar2"][1].val() == "32");

    // if you want to fully replace the tree, you need to clear first
    // before parsing into an existing tree:
    tree.clear();
    tree.clear_arena();  // you may or may not want to clear the arena
    ryml::parse_in_arena("- a\n- b\n- {x0: 1, x1: 2}", &tree);
    CHECK(ryml::emitrs_yaml<std::string>(tree) == "- a\n- b\n- {x0: 1,x1: 2}\n");
    CHECK(root.is_seq());
    CHECK(root[0].val() == "a");
    CHECK(root[1].val() == "b");
    CHECK(root[2].is_map());
    CHECK(root[2]["x0"].val() == "1");
    CHECK(root[2]["x1"].val() == "2");

    // we can parse directly into a node nested deep in an existing tree:
    ryml::NodeRef mroot = tree.rootref(); // modifiable root
    ryml::parse_in_arena("champagne: Dom Perignon\ncoffee: Arabica", mroot.append_child());
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "- a"                              "\n"
          "- b"                              "\n"
          "- {x0: 1,x1: 2}"                  "\n"
          "- champagne: Dom Perignon"        "\n"
          "  coffee: Arabica"                "\n"
          "");
    CHECK(root.is_seq());
    CHECK(root[0].val() == "a");
    CHECK(root[1].val() == "b");
    CHECK(root[2].is_map());
    CHECK(root[2]["x0"].val() == "1");
    CHECK(root[2]["x1"].val() == "2");
    CHECK(root[3].is_map());
    CHECK(root[3]["champagne"].val() == "Dom Perignon");
    CHECK(root[3]["coffee"].val() == "Arabica");

    mroot[3]["more"].set_map();
    mroot[3]["beer"].set_seq();
    CHECK(mroot[3]["more"].readable());
    CHECK(mroot[3]["more"].key() == "more");
    CHECK(mroot[3]["more"].is_map());
    CHECK(!mroot[3]["more"].is_val());
    ryml::parse_in_arena("{vinho verde: Soalheiro, vinho tinto: Redoma 2017}", mroot[3]["more"]);
    ryml::parse_in_arena("- Rochefort 10\n- Busch\n- Leffe Rituel", mroot[3]["beer"]);
    ryml::parse_in_arena("lots\nof\nwater", mroot[3]["always"]);
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "- a"                              "\n"
          "- b"                              "\n"
          "- {x0: 1,x1: 2}"                  "\n"
          "- champagne: Dom Perignon"        "\n"
          "  coffee: Arabica"                "\n"
          // note these were added:
          "  more:"                          "\n"
          "    vinho verde: Soalheiro"       "\n"
          "    vinho tinto: Redoma 2017"     "\n"
          "  beer:"                          "\n"
          "    - Rochefort 10"               "\n"
          "    - Busch"                      "\n"
          "    - Leffe Rituel"               "\n"
          "  always: lots of water"          "\n"
          "");

    // can append at the top:
    ryml::parse_in_arena("- foo\n- bar\n- baz\n- bat", mroot);
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "- a"                              "\n"
          "- b"                              "\n"
          "- {x0: 1,x1: 2}"                  "\n"
          "- champagne: Dom Perignon"        "\n"
          "  coffee: Arabica"                "\n"
          "  more:"                          "\n"
          "    vinho verde: Soalheiro"       "\n"
          "    vinho tinto: Redoma 2017"     "\n"
          "  beer:"                          "\n"
          "    - Rochefort 10"               "\n"
          "    - Busch"                      "\n"
          "    - Leffe Rituel"               "\n"
          "  always: lots of water"          "\n"
          // note these were added
          "- foo"                            "\n"
          "- bar"                            "\n"
          "- baz"                            "\n"
          "- bat"                            "\n"
          "");

    // or nested:
    ryml::parse_in_arena("[Kasteel Donker]", mroot[3]["beer"]);
    CHECK(ryml::emitrs_yaml<std::string>(tree) ==
          "- a"                              "\n"
          "- b"                              "\n"
          "- {x0: 1,x1: 2}"                  "\n"
          "- champagne: Dom Perignon"        "\n"
          "  coffee: Arabica"                "\n"
          "  more:"                          "\n"
          "    vinho verde: Soalheiro"       "\n"
          "    vinho tinto: Redoma 2017"     "\n"
          "  beer:"                          "\n"
          "    - Rochefort 10"               "\n"
          "    - Busch"                      "\n"
          "    - Leffe Rituel"               "\n"
          "    - Kasteel Donker"             "\n"  // added this
          "  always: lots of water"          "\n"
          "- foo"                            "\n"
          "- bar"                            "\n"
          "- baz"                            "\n"
          "- bat"                            "\n"
          "");
}

void sample_parse_reuse_parser

(

)

reuse an existing parser

Demonstrates reuse of an existing parser.

Doing this is recommended when multiple files are parsed.

See also

Parse utilities

Definition at line 2256 of file quickstart.cpp.

Referenced by main().

{
    ryml::EventHandlerTree evt_handler = {};
    ryml::Parser parser(&evt_handler);

    // it is also advised to reserve the parser depth
    // to the expected depth of the data tree:
    parser.reserve_stack(10); // uses small storage optimization
                              // defaulting to 16 depth, so this
                              // instruction is a no-op, and the stack
                              // will located in the parser object.
    parser.reserve_stack(20); // But this will cause an allocation
                              // because it is above 16.

    ryml::csubstr yaml = "[Dom Perignon,Gosset Grande Reserve,Jacquesson 742]";
    ryml::Tree champagnes = parse_in_arena(&parser, "champagnes.yml", yaml);
    CHECK(ryml::emitrs_yaml<std::string>(champagnes) == yaml);

    yaml = "[Rochefort 10,Busch,Leffe Rituel,Kasteel Donker]";
    ryml::Tree beers = parse_in_arena(&parser, "beers.yml", yaml);
    CHECK(ryml::emitrs_yaml<std::string>(beers) == yaml);
}

void sample_parse_reuse_tree_and_parser

(

)

how to reuse existing trees and parsers

for ultimate speed when parsing multiple times, reuse both the tree and parser

See also

Parse utilities

Definition at line 2285 of file quickstart.cpp.

Referenced by main().

{
    ryml::Tree tree;
    // it will always be faster if the tree's size is conveniently reserved:
    tree.reserve(30); // reserve 30 nodes (good enough for this sample)
    // if you are using the tree's arena to serialize data,
    // then reserve also the arena's size:
    tree.reserve(256); // reserve 256 characters (good enough for this sample)

    ryml::EventHandlerTree evt_handler;
    ryml::Parser parser(&evt_handler);
    // it is also advised to reserve the parser depth
    // to the expected depth of the data tree:
    parser.reserve_stack(10); // the parser uses small storage
                              // optimization defaulting to 16 depth,
                              // so this instruction is a no-op, and
                              // the stack will be located in the
                              // parser object.
    parser.reserve_stack(20); // But this will cause an allocation
                              // because it is above 16.

    ryml::csubstr champagnes = ""
        "- Dom Perignon\n"
        "- Gosset Grande Reserve\n"
        "- Jacquesson 742\n"
        "";
    ryml::csubstr beers = ""
        "- Rochefort 10\n"
        "- Busch\n"
        "- Leffe Rituel\n"
        "- Kasteel Donker\n"
        "";
    ryml::csubstr wines = ""
        "- Soalheiro\n"
        "- Niepoort Redoma 2017\n"
        "- Vina Esmeralda\n"
        "";

    parse_in_arena(&parser, "champagnes.yml", champagnes, &tree);
    CHECK(ryml::emitrs_yaml<std::string>(tree) == champagnes);

    // watchout: this will APPEND to the given tree:
    parse_in_arena(&parser, "beers.yml", beers, &tree);
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "- Dom Perignon\n"
          "- Gosset Grande Reserve\n"
          "- Jacquesson 742\n"
          "- Rochefort 10\n"
          "- Busch\n"
          "- Leffe Rituel\n"
          "- Kasteel Donker\n"
          "");

    // if you don't wish to append, clear the tree first:
    tree.clear();
    parse_in_arena(&parser, "wines.yml", wines, &tree);
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
        "- Soalheiro\n"
        "- Niepoort Redoma 2017\n"
        "- Vina Esmeralda\n"
        "");
}

void sample_parse_style

(

)

shows how rapidyaml retains the style of parsed YAML

shows how rapidyaml marks the tree nodes with their original style in the parsed YAML.

See also

Tree utilities

Node classes

Definition at line 2357 of file quickstart.cpp.

Referenced by main().

{
    ryml::csubstr yaml = ""
        "doe: a deer, a female deer"        "\n"
        "ray: 'a drop of golden sun'"       "\n"
        "me: \"a name I call myself\""      "\n"
        "far: |-"                           "\n"
        "  a long long way to go"           "\n"
        "sow: >-"                           "\n"
        "  a needle pulling thread"         "\n"
        "seq: [0,1,2,3]"                    "\n"
        "map: {"                            "\n"
        "    0: 10,"                        "\n"
        "    1: 11,"                        "\n"
        "    2: 12,"                        "\n"
        "    3: 13"                         "\n"
        "  }"                               "\n"
        "";
    const ryml::Tree tree = ryml::parse_in_arena(yaml);
    // note how every node is tagged with its original style:
    CHECK(tree["doe"].is_val_plain());
    CHECK(tree["ray"].is_val_squo());
    CHECK(tree["me"].is_val_dquo());
    CHECK(tree["far"].is_val_literal());
    CHECK(tree["sow"].is_val_folded());
    CHECK(tree["seq"].is_flow());
    CHECK(tree["seq"].is_flow_sl());
    CHECK(tree["map"].is_flow());
    CHECK(tree["map"].is_flow_mlx());
    CHECK(tree.rootref().is_block());
    // ... which results in roundtrip-stable YAML:
    CHECK(ryml::emitrs_yaml<std::string>(tree) == yaml);
}