Emitting

Functions
void	sample_emit_to_container ()
	emit to memory, eg a string or vector-like container
void	sample_emit_to_stream ()
	emit to a stream, eg std::ostream
void	sample_emit_to_file ()
	emit to a FILE*
void	sample_emit_nested_node ()
	pick a nested node as the root when emitting

Detailed Description

Function Documentation

sample_emit_to_container()

void sample_emit_to_container

(

)

emit to memory, eg a string or vector-like container

demonstrates how to emit to a linear container of char

Definition at line 4765 of file quickstart.cpp.

{
    ryml::csubstr ymla =
        "- 1\n"
        "- 2\n"
        "";
    ryml::csubstr ymlb =
        "- a"                           "\n"
        "- b"                           "\n"
        "- x0: 1"                       "\n"
        "  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"
        "- foo"                         "\n"
        "- bar"                         "\n"
        "- baz"                         "\n"
        "- bat"                         "\n"
        "";
    const ryml::Tree treea = ryml::parse_in_arena(ymla);
    const ryml::Tree treeb = ryml::parse_in_arena(ymlb);
 
    // it is possible to emit to any linear container of char.
    //
    // eg, std::vector<char>
    {
        // do a blank call on an empty buffer to find the required size.
        // no overflow will occur, and returns a substr with the size
        // required to output
        ryml::csubstr output = ryml::emit_yaml(treea, treea.root_id(), ryml::substr{}, /*error_on_excess*/false);
        CHECK(output.str == nullptr);
        CHECK(output.len > 0);
        size_t num_needed_chars = output.len;
        std::vector<char> buf(num_needed_chars);
        // now try again with the proper buffer
        output = ryml::emit_yaml(treea, treea.root_id(), ryml::to_substr(buf), /*error_on_excess*/true);
        CHECK(output == ymla);
 
        // it is possible to reuse the buffer and grow it as needed.
        // first do a blank run to find the size:
        output = ryml::emit_yaml(treeb, treeb.root_id(), ryml::substr{}, /*error_on_excess*/false);
        CHECK(output.str == nullptr);
        CHECK(output.len > 0);
        CHECK(output.len == ymlb.len);
        num_needed_chars = output.len;
        buf.resize(num_needed_chars);
        // now try again with the proper buffer
        output = ryml::emit_yaml(treeb, treeb.root_id(), ryml::to_substr(buf), /*error_on_excess*/true);
        CHECK(output == ymlb);
 
        // there is a convenience wrapper performing the same as above:
        // provided to_substr() is defined for that container.
        output = ryml::emitrs_yaml(treeb, &buf);
        CHECK(output == ymlb);
 
        // or you can just output a new container:
        // provided to_substr() is defined for that container.
        std::vector<char> another = ryml::emitrs_yaml<std::vector<char>>(treeb);
        CHECK(ryml::to_csubstr(another) == ymlb);
 
        // you can also emit nested nodes:
        another = ryml::emitrs_yaml<std::vector<char>>(treeb[3][2]);
        CHECK(ryml::to_csubstr(another) == ""
              "more:"                           "\n"
              "  vinho verde: Soalheiro"        "\n"
              "  vinho tinto: Redoma 2017"      "\n"
              "");
    }
 
 
    // eg, std::string. notice this is the same code as above
    {
        // do a blank call on an empty buffer to find the required size.
        // no overflow will occur, and returns a substr with the size
        // required to output
        ryml::csubstr output = ryml::emit_yaml(treea, treea.root_id(), ryml::substr{}, /*error_on_excess*/false);
        CHECK(output.str == nullptr);
        CHECK(output.len > 0);
        size_t num_needed_chars = output.len;
        std::string buf;
        buf.resize(num_needed_chars);
        // now try again with the proper buffer
        output = ryml::emit_yaml(treea, treea.root_id(), ryml::to_substr(buf), /*error_on_excess*/true);
        CHECK(output == ymla);
 
        // it is possible to reuse the buffer and grow it as needed.
        // first do a blank run to find the size:
        output = ryml::emit_yaml(treeb, treeb.root_id(), ryml::substr{}, /*error_on_excess*/false);
        CHECK(output.str == nullptr);
        CHECK(output.len > 0);
        CHECK(output.len == ymlb.len);
        num_needed_chars = output.len;
        buf.resize(num_needed_chars);
        // now try again with the proper buffer
        output = ryml::emit_yaml(treeb, treeb.root_id(), ryml::to_substr(buf), /*error_on_excess*/true);
        CHECK(output == ymlb);
 
        // there is a convenience wrapper performing the above instructions:
        // provided to_substr() is defined for that container
        output = ryml::emitrs_yaml(treeb, &buf);
        CHECK(output == ymlb);
 
        // or you can just output a new container:
        // provided to_substr() is defined for that container.
        std::string another = ryml::emitrs_yaml<std::string>(treeb);
        CHECK(ryml::to_csubstr(another) == ymlb);
 
        // you can also emit nested nodes:
        another = ryml::emitrs_yaml<std::string>(treeb[3][2]);
        CHECK(ryml::to_csubstr(another) == ""
              "more:"                           "\n"
              "  vinho verde: Soalheiro"        "\n"
              "  vinho tinto: Redoma 2017"      "\n"
              "");
    }
}

Referenced by main().

sample_emit_to_stream()

void sample_emit_to_stream

(

)

emit to a stream, eg std::ostream

demonstrates how to emit to a stream-like structure

Definition at line 4892 of file quickstart.cpp.

{
    ryml::csubstr ymlb =
        "- a"                           "\n"
        "- b"                           "\n"
        "- x0: 1"                       "\n"
        "  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"
        "- foo"                         "\n"
        "- bar"                         "\n"
        "- baz"                         "\n"
        "- bat"                         "\n"
        "";
    const ryml::Tree tree = ryml::parse_in_arena(ymlb);
 
    std::string s;
 
    // emit a full tree
    {
        std::stringstream ss;
        ss << tree; // works with any stream having .operator<<() and .write()
        s = ss.str();
        CHECK(ryml::to_csubstr(s) == ymlb);
    }
 
    // emit a full tree as json
    {
        std::stringstream ss;
        ss << ryml::as_json(tree); // works with any stream having .operator<<() and .write()
        s = ss.str();
        CHECK(s ==
              "["                                        "\n"
              "  \"a\","                                 "\n"
              "  \"b\","                                 "\n"
              "  {"                                      "\n"
              "    \"x0\": 1,"                           "\n"
              "    \"x1\": 2"                            "\n"
              "  },"                                     "\n"
              "  {"                                      "\n"
              "    \"champagne\": \"Dom Perignon\","     "\n"
              "    \"coffee\": \"Arabica\","             "\n"
              "    \"more\": {"                          "\n"
              "      \"vinho verde\": \"Soalheiro\","    "\n"
              "      \"vinho tinto\": \"Redoma 2017\""   "\n"
              "    },"                                   "\n"
              "    \"beer\": ["                          "\n"
              "      \"Rochefort 10\","                  "\n"
              "      \"Busch\","                         "\n"
              "      \"Leffe Rituel\""                   "\n"
              "    ]"                                    "\n"
              "  },"                                     "\n"
              "  \"foo\","                               "\n"
              "  \"bar\","                               "\n"
              "  \"baz\","                               "\n"
              "  \"bat\""                                "\n"
              "]"                                        "\n"
              "");
    }
 
    // emit a nested node
    {
        std::stringstream ss;
        ss << tree[3][2]; // works with any stream having .operator<<() and .write()
        s = ss.str();
        CHECK(s == ""
              "more:"                             "\n"
              "  vinho verde: Soalheiro"          "\n"
              "  vinho tinto: Redoma 2017"        "\n"
              "");
    }
 
    // emit a nested node as json
    {
        std::stringstream ss;
        ss << ryml::as_json(tree[3][2]); // works with any stream having .operator<<() and .write()
        s = ss.str();
        CHECK(ryml::to_csubstr(s) ==
              "\"more\": {"                           "\n"
              "  \"vinho verde\": \"Soalheiro\","     "\n"
              "  \"vinho tinto\": \"Redoma 2017\""    "\n"
              "}"                                     "\n"
              "");
    }
}

Referenced by main().

sample_emit_to_file()

void sample_emit_to_file

(

)

emit to a FILE*

demonstrates how to emit to a FILE*

Definition at line 4989 of file quickstart.cpp.

{
    ryml::csubstr yml = ""
        "- a"                           "\n"
        "- b"                           "\n"
        "- x0: 1"                       "\n"
        "  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"
        "- foo"                         "\n"
        "- bar"                         "\n"
        "- baz"                         "\n"
        "- bat"                         "\n"
        "";
    const ryml::Tree tree = ryml::parse_in_arena(yml);
    // this is emitting to stdout, but of course you can pass in any
    // FILE* obtained from fopen()
    ryml::emit_yaml(tree, tree.root_id(), stdout);
}

Referenced by main().

sample_emit_nested_node()

void sample_emit_nested_node

(

)

pick a nested node as the root when emitting

just like parsing into a nested node, you can also emit from a nested node.

Definition at line 5020 of file quickstart.cpp.

{
    const ryml::Tree tree = ryml::parse_in_arena(""
        "- a"                            "\n"
        "- b"                            "\n"
        "- x0: 1"                        "\n"
        "  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"
        "    - - and so"                 "\n"
        "      - many other"             "\n"
        "      - wonderful beers"        "\n"
        "- more"                         "\n"
        "- seq"                          "\n"
        "- members"                      "\n"
        "- here"                         "\n"
        "");
    // Let's now emit the beer node. Note that its key is also
    // emitted, making the result a map with a single child:
    CHECK(ryml::emitrs_yaml<std::string>(tree[3]["beer"]) == ""
          "beer:"                    "\n"
          "  - Rochefort 10"         "\n"
          "  - Busch"                "\n"
          "  - Leffe Rituel"         "\n"
          "  - - and so"             "\n"
          "    - many other"         "\n"
          "    - wonderful beers"    "\n"
          "");
    // You can use EmitOptions to prevent the key from being
    // emitted. Note how the result is now just the contents without
    // the key, and therefore the root is now a seq:
    auto without_key = ryml::EmitOptions{}.emit_nonroot_key(false);
    CHECK(ryml::emitrs_yaml<std::string>(tree[3]["beer"], without_key) == ""
          "- Rochefort 10"         "\n"
          "- Busch"                "\n"
          "- Leffe Rituel"         "\n"
          "- - and so"             "\n"
          "  - many other"         "\n"
          "  - wonderful beers"    "\n"
          "");
    // For sequences, the behavior is opposite. Notice how the leading
    // dash defaults to omit:
    CHECK(ryml::emitrs_yaml<std::string>(tree[3]["beer"][3]) == ""
          "- and so"                 "\n"
          "- many other"             "\n"
          "- wonderful beers"        "\n"
          "");
    // And likewise, you can use EmitOptions to force the dash:
    auto with_dash = ryml::EmitOptions{}.emit_nonroot_dash(true);
    CHECK(ryml::emitrs_yaml<std::string>(tree[3]["beer"][3], with_dash) == ""
          "- - and so"                 "\n" // note the added dash and indentation
          "  - many other"             "\n"
          "  - wonderful beers"        "\n"
          "");
    // Example: emit a scalar node (seq member):
    CHECK(ryml::emitrs_yaml<std::string>(tree[3]["beer"][0]) == "Rochefort 10");
    CHECK(ryml::emitrs_yaml<std::string>(tree[3]["beer"][0], with_dash) == "- Rochefort 10\n");
    // Example: emit a scalar node (map member):
    CHECK(ryml::emitrs_yaml<std::string>(tree[3]["more"][0]) == "vinho verde: Soalheiro\n");
    CHECK(ryml::emitrs_yaml<std::string>(tree[3]["more"][0], without_key) == "Soalheiro");
}

Referenced by main().