YAML anchors

Functions
void	sample_anchors_and_aliases ()
	deal with YAML anchors and aliases More...
void	sample_anchors_and_aliases_create ()
	how to create YAML anchors and aliases More...

Detailed Description

Function Documentation

void sample_anchors_and_aliases

(

)

deal with YAML anchors and aliases

demonstrates usage with anchors and alias references.

Note that dereferencing is opt-in; after parsing, you have to call c4::yml::Tree::resolve() explicitly if you want resolved references in the tree. This method will resolve all references and substitute the anchored values in place of the reference.

The c4::yml::Tree::resolve() method first does a full traversal of the tree to gather all anchors and references in a separate collection, then it goes through that collection to locate the names, which it does by obeying the YAML standard diktat that

> an alias node refers to the most recent node in
> the serialization having the specified anchor

So, depending on the number of anchor/alias nodes, this is a potentially expensive operation, with a best-case linear complexity (from the initial traversal) and a worst-case quadratic complexity (if every node has an alias/anchor). This potential cost is the reason for requiring an explicit call to c4::yml::Tree::resolve()

Definition at line 5914 of file quickstart.cpp.

Referenced by main().

{
    std::string unresolved = ""
        "base: &base"                       "\n"
        "  name: Everyone has same name"    "\n"
        "foo: &foo"                         "\n"
        "  <<: *base"                       "\n"
        "  age: 10"                         "\n"
        "bar: &bar"                         "\n"
        "  <<: *base"                       "\n"
        "  age: 20"                         "\n"
        "bill_to: &id001"                   "\n"
        "  street: |-"                      "\n"
        "    123 Tornado Alley"             "\n"
        "    Suite 16"                      "\n"
        "  city: East Centerville"          "\n"
        "  state: KS"                       "\n"
        "ship_to: *id001"                   "\n"
        "&keyref key: &valref val"          "\n"
        "*valref : *keyref"                 "\n"
        "";
    std::string resolved = ""
        "base:"                             "\n"
        "  name: Everyone has same name"    "\n"
        "foo:"                              "\n"
        "  name: Everyone has same name"    "\n"
        "  age: 10"                         "\n"
        "bar:"                              "\n"
        "  name: Everyone has same name"    "\n"
        "  age: 20"                         "\n"
        "bill_to:"                          "\n"
        "  street: |-"                      "\n"
        "    123 Tornado Alley"             "\n"
        "    Suite 16"                      "\n"
        "  city: East Centerville"          "\n"
        "  state: KS"                       "\n"
        "ship_to:"                          "\n"
        "  street: |-"                      "\n"
        "    123 Tornado Alley"             "\n"
        "    Suite 16"                      "\n"
        "  city: East Centerville"          "\n"
        "  state: KS"                       "\n"
        "key: val"                          "\n"
        "val: key"                          "\n"
        "";

    ryml::Tree tree = ryml::parse_in_arena(ryml::to_csubstr(unresolved));
    // by default, references are not resolved when parsing:
    CHECK( ! tree["base"].has_key_anchor());
    CHECK(   tree["base"].has_val_anchor());
    CHECK(   tree["base"].val_anchor() == "base");
    CHECK(   tree["key"].key_anchor() == "keyref");
    CHECK(   tree["key"].val_anchor() == "valref");
    CHECK(   tree["*valref"].is_key_ref());
    CHECK(   tree["*valref"].is_val_ref());
    CHECK(   tree["*valref"].key_ref() == "valref");
    CHECK(   tree["*valref"].val_ref() == "keyref");

    // to resolve references, simply call tree.resolve(),
    // which will perform the reference instantiations:
    tree.resolve();

    // all the anchors and references are substistuted and then removed:
    CHECK( ! tree["base"].has_key_anchor());
    CHECK( ! tree["base"].has_val_anchor());
    CHECK( ! tree["base"].has_val_anchor());
    CHECK( ! tree["key"].has_key_anchor());
    CHECK( ! tree["key"].has_val_anchor());
    CHECK( ! tree["val"].is_key_ref()); // notice *valref is now turned to val
    CHECK( ! tree["val"].is_val_ref()); // notice *valref is now turned to val

    CHECK(tree["ship_to"]["city"].val() == "East Centerville");
    CHECK(tree["ship_to"]["state"].val() == "KS");
}

void sample_anchors_and_aliases_create

(

)

how to create YAML anchors and aliases

demonstrates how to use the API to programatically create anchors and aliases

Definition at line 5991 of file quickstart.cpp.

Referenced by main().

{
    // part 1: anchor/ref
    {
        ryml::Tree t;
        t.rootref().set_map(ryml::BLOCK);
        t["kanchor"].set_val("2");
        t["kanchor"].set_key_anchor("kanchor");
        t["vanchor"].set_val("3");
        t["vanchor"].set_val_anchor("vanchor");
        // to set a reference, need to call .set_val_ref()/.set_key_ref()
        t["kref"].set_val_ref("kanchor");
        t["vref"].set_val_ref("vanchor");
        t["nref"].set_val("*vanchor");  // NOTE: this is not set as a reference in the tree!
        CHECK(ryml::emitrs_yaml<std::string>(t) == ""
              "&kanchor kanchor: 2"  "\n"
              "vanchor: &vanchor 3"  "\n"
              "kref: *kanchor"       "\n"
              "vref: *vanchor"       "\n"
              // note that ryml emits nref with quotes to disambiguate
              // (because no style was set)
              "nref: '*vanchor'"     "\n"
              "");
        t.resolve();
        CHECK(ryml::emitrs_yaml<std::string>(t) == ""
              "kanchor: 2"           "\n"
              "vanchor: 3"           "\n"
              "kref: kanchor"        "\n"
              "vref: 3"              "\n"
              // note that nref was not resolved
              "nref: '*vanchor'"     "\n"
              "");
    }

    // part 2: simple inheritance (ie, adding `<<: *anchor` nodes)
    {
        ryml::Tree t = ryml::parse_in_arena(""
            "orig: &orig {foo: bar, baz: bat}"  "\n"
            "copy: {}"                          "\n"
            "notcopy: {}"                       "\n"
            "notref: {}"                        "\n"
            "");
        t["copy"]["<<"].set_val_ref("orig");
        t["notcopy"]["test"].set_val_ref("orig");
        t["notcopy"]["<<"].set_val_ref("orig");
        t["notref"]["<<"].set_val("*orig"); // not a reference! .set_val_ref() was not called
        CHECK(ryml::emitrs_yaml<std::string>(t) == ""
              "orig: &orig {foo: bar,baz: bat}"      "\n"
              "copy: {<<: *orig}"                    "\n"
              "notcopy: {test: *orig,<<: *orig}"     "\n"
              "notref: {<<: '*orig'}"                "\n"
              "");
        t.resolve();
        CHECK(ryml::emitrs_yaml<std::string>(t) == ""
              "orig: {foo: bar,baz: bat}"                                "\n"
              "copy: {foo: bar,baz: bat}"                                "\n"
              "notcopy: {test: {foo: bar,baz: bat},foo: bar,baz: bat}"   "\n"
              "notref: {<<: '*orig'}"                                    "\n"
              "");
    }

    // part 3: multiple inheritance (ie, `<<: [*ref1,*ref2,*etc]`)
    {
        ryml::Tree t = ryml::parse_in_arena(""
            "orig1: &orig1 {foo: bar}"       "\n"
            "orig2: &orig2 {baz: bat}"       "\n"
            "orig3: &orig3 {and: more}"      "\n"
            "copy: {}"                       "\n"
            "");
        ryml::NodeRef seq = t["copy"]["<<"];
        seq.set_seq();
        seq.append_child().set_val_ref("orig1");
        seq.append_child().set_val_ref("orig2");
        seq.append_child().set_val_ref("orig3");
        CHECK(ryml::emitrs_yaml<std::string>(t) == ""
              "orig1: &orig1 {foo: bar}"                  "\n"
              "orig2: &orig2 {baz: bat}"                  "\n"
              "orig3: &orig3 {and: more}"                 "\n"
              "copy: {<<: [*orig1,*orig2,*orig3]}"        "\n"
              "");
        t.resolve();
        CHECK(ryml::emitrs_yaml<std::string>(t) == ""
              "orig1: {foo: bar}"                        "\n"
              "orig2: {baz: bat}"                        "\n"
              "orig3: {and: more}"                       "\n"
              "copy: {foo: bar,baz: bat,and: more}"      "\n");
    }
}