Release 0.3.0

Breaking changes

Despite ryml being still in a non-stable 0.x.y version, considerable effort goes into trying to avoid breaking changes. However, this release has to collect on the semantic versioning prerogative for breaking changes. This is a needed improvement, so sorry for any nuisance!

The allocation and error callback logic was revamped on the amalgamation PR. Now trees and parsers receive (and store) a full ryml::Callbacks object instead of the (now removed) ryml::Allocator which had a pointer to a (now removed) ryml::MemoryResourceCallbacks, which was a (now removed) ryml::MemoryResource. To be clear, the Callbacks class is unchanged, other than removing some unneeded helper methods.

These changes were motivated by unfortunate name clashes between c4::Allocator/ryml::Allocator and c4::MemoryResource/ryml::MemoryResource, occurring if <c4/allocator.hpp> or <c4/memory_resource.hpp> were included before <c4/yml/common.hpp>. They also significantly simplify this part of the API, making it really easier to understand.

As a consequence of the above changes, the global memory resource getters and setters for ryml were also removed: ryml::get_memory_resource()/ryml::set_memory_resource().

Here's an example of the required changes in client code. First the old client code (from the quickstart):

struct PerTreeMemoryExample : public ryml::MemoryResource
{
    void *allocate(size_t len, void * hint) override;
    void free(void *mem, size_t len) override;
};

PerTreeMemoryExample mrp;
PerTreeMemoryExample mr1;
PerTreeMemoryExample mr2;

ryml::Parser parser = {ryml::Allocator(&mrp)};
ryml::Tree   tree1  = {ryml::Allocator(&mr1)};
ryml::Tree   tree2  = {ryml::Allocator(&mr2)};

Should now be rewritten to:

struct PerTreeMemoryExample
{
    ryml::Callbacks callbacks() const; // helper to create the callbacks
};

PerTreeMemoryExample mrp;
PerTreeMemoryExample mr1;
PerTreeMemoryExample mr2;

ryml::Parser parser = {mrp.callbacks()};
ryml::Tree   tree1  = {mr1.callbacks()};
ryml::Tree   tree2  = {mr2.callbacks()};

New features

• Add amalgamation into a single header file (PR #172):
  • The amalgamated header will be available together with the deliverables from each release.
  • To generate the amalgamated header:

    $ python tools/amalgamate.py ryml_all.hpp

  • To use the amalgamated header:
    • Include at will in any header of your project.
    • In one - and only one - of your project source files, #define RYML_SINGLE_HDR_DEFINE_NOW and then #include <ryml_all.hpp>. This will enable the function and class definitions in the header file. For example, here's a sample program:

      #include <iostream>
      #define RYML_SINGLE_HDR_DEFINE_NOW // do this before the include
      #include <ryml_all.hpp>
      int main()
      {
          auto tree = ryml::parse("{foo: bar}");
          std::cout << tree["foo"].val() << "\n";
      }

• Add Tree::change_type() and NodeRef::change_type() (PR #171):

  // clears a node and sets its type to a different type (one of `VAL`, `SEQ`, `MAP`):
  Tree t = parse("{keyval0: val0, keyval1: val1, keyval2: val2}");
  t[0].change_type(VAL);
  t[1].change_type(MAP);
  t[2].change_type(SEQ);
  Tree expected = parse("{keyval0: val0, keyval1: {}, keyval2: []}");
  assert(emitrs<std::string>(t) == emitrs<std::string>(expected));

• Add support for compilation with emscripten (WebAssembly+javascript) (PR #176).

Fixes

• Take block literal indentation as relative to current indentation level, rather than as an absolute indentation level (PR #178):

  foo:
    - |
     child0
    - |2
      child2  # indentation is 4, not 2

• Fix parsing when seq member maps start without a key (PR #178):

  # previously this resulted in a parse error
  - - : empty key
  - - : another empty key

• Prefer passing substr and csubstr by value instead of const reference (PR #171)
• Fix #173: add alias target ryml::ryml (PR #174)
• Speedup compilation of tests by removing linking with yaml-cpp and libyaml. (PR #177)
• Fix c4core#53: cmake install targets were missing call to export() (PR #179).
• Add missing export to Tree (PR #181).

Thanks

• @aviktorov