fix rebase problems and update docs

.github/workflows/benchmarks.yml

@@ -60,7 +60,7 @@ jobs:
       - name: Verify vars.sh
         run: cat vars.sh ; source vars.sh ; echo $SRC_TAG ; echo $SRC_VERSION
       - name: Save vars.sh
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with: {name: vars.sh, path: ./vars.sh}
 
   benchmarks:
@@ -141,7 +141,7 @@ jobs:
             mv -vf build/$bl/bm/bm-results/* $dst/.
           done
       - name: upload benchmark result artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: ryml-benchmark_results
           path: ryml-benchmark_results/

.github/workflows/coverage.yml

@@ -33,7 +33,6 @@ jobs:
       (!contains(github.event.head_commit.message, 'skip coverage')) ||
       contains(github.event.head_commit.message, 'only coverage')
     continue-on-error: true
-    if: always()  # https://stackoverflow.com/questions/62045967/github-actions-is-there-a-way-to-continue-on-error-while-still-getting-correct
     runs-on: ${{matrix.os}}
     strategy:
       fail-fast: false
@@ -63,7 +62,7 @@ jobs:
       - {name: static64-build, run: source .github/setenv.sh && c4_build_test static64}
       - {name: static64-run, run: source .github/setenv.sh && c4_build_target static64 ryml-coverage}
       - name: static64-coverage-artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: coverage-static64
           path: |
@@ -77,7 +76,7 @@ jobs:
       - {name: static32-build, run: source .github/setenv.sh && c4_build_test static32}
       - {name: static32-run, run: source .github/setenv.sh && c4_build_target static32 ryml-coverage}
       - name: static32-coverage-artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: coverage-static32-cxx${{matrix.std}}
           path: |

.github/workflows/release.yml

@@ -71,7 +71,7 @@ jobs:
       - name: Verify vars.sh
         run: cat vars.sh ; source vars.sh ; echo $SRC_TAG ; echo $SRC_VERSION
       - name: Save vars.sh
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with: {name: vars.sh, path: ./vars.sh}
 
   #----------------------------------------------------------------------------
@@ -86,7 +86,7 @@ jobs:
     steps:
       - {name: checkout, uses: actions/checkout@v4, with: {submodules: recursive}}
       - name: Download vars.sh
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v3
         with: {name: vars.sh, path: ./}
       - name: Install python 3.9
         uses: actions/setup-python@v5
@@ -109,7 +109,7 @@ jobs:
           python --version
           python tools/amalgamate.py assets/$id.hpp
       - name: Save source artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with: {name: assets, path: assets}
 
   #----------------------------------------------------------------------------
@@ -128,14 +128,15 @@ jobs:
       matrix:
         config:
           #  name of the artifact    | suffix (gen)    | suffix (package)         | cpack gen | mime type                      | os              | cxx
+          - {name: Ubuntu 22.04 deb  , sfxg: unix64.deb, sfxp: ubuntu-22.04.deb   , gen: DEB  , mime: vnd.debian.binary-package, os: ubuntu-22.04             }
           - {name: Ubuntu 20.04 deb  , sfxg: unix64.deb, sfxp: ubuntu-20.04.deb   , gen: DEB  , mime: vnd.debian.binary-package, os: ubuntu-20.04             }
           #- {name: Ubuntu 18.04 deb  , sfxg: unix64.deb, sfxp: ubuntu-18.04.deb   , gen: DEB  , mime: vnd.debian.binary-package, os: ubuntu-18.04             }
           - {name: Windows VS2019 zip, sfxg: win64.zip , sfxp: windows-vs2019.zip , gen: ZIP  , mime: zip                      , os: windows-2019, cxx: vs2019}
           - {name: MacOSX sh         , sfxg: apple64.sh, sfxp: macosx-xcode.sh    , gen: STGZ , mime: x-sh                     , os: macos-11.0  , cxx: xcode }
     steps:
       - {name: checkout, uses: actions/checkout@v4, with: {submodules: recursive}}
       - name: Download vars.sh
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v3
         with: {name: vars.sh, path: ./}
       - {name: install requirements, run: source .github/reqs.sh && c4_install_test_requirements $OS}
       - {name: show info, run: source .github/setenv.sh && c4_show_info }
@@ -154,7 +155,7 @@ jobs:
           [ ! -f $asset_src ] && exit 1
           cp -fav $asset_src $asset_dst
       - name: Save artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with: {name: assets, path: assets}
 
   #----------------------------------------------------------------------------
@@ -186,7 +187,7 @@ jobs:
           sdist=`echo $sdist_orig | sed 's:\.zip:-python_src.zip:'`
           mv -fv $sdist_orig $sdist
       - name: Save artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with: {name: dist, path: dist}
 
   python_wheels:
@@ -253,7 +254,7 @@ jobs:
           mv -fv wheelhouse dist
           ls -lFhp dist/
       - name: Save artifacts for publishing to PyPI
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with: {name: dist, path: dist}
       # run the tests
       - name: install python ${{matrix.config.pythonv}}
@@ -299,10 +300,10 @@ jobs:
     steps:
       - {name: checkout, uses: actions/checkout@v4, with: {submodules: recursive}}
       - name: Gather artifacts - ./assets
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v3
         with: {name: assets, path: assets}
       - name: Gather artifacts - ./dist
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v3
         with: {name: dist, path: dist}
       - name: Verify existing artifacts
         run: |
@@ -312,7 +313,7 @@ jobs:
       # Github
       - name: Restore vars.sh
         if: contains(github.ref, 'tags/v')
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v3
         with: {name: vars.sh, path: ./}
       - name: Save vars for following steps
         if: contains(github.ref, 'tags/v')

doc/doxy_main.md

@@ -11,6 +11,7 @@
     * @ref doc_tree
     * @ref doc_node_classes
   * For serialization/deserialization, see @ref doc_serialization.
+  * @ref doc_ref_utils - how to resolve references to anchors
   * @ref doc_tag_utils - how to resolve tags
   * @ref doc_callbacks - how to set up error/allocation/deallocation
     callbacks either globally for the library, or for specific objects

doc/index.rst

@@ -47,20 +47,24 @@ ryml is written in C++11, and compiles cleanly with:
     <https://github.com/biojppm/c4conf>`_.
 
 
+----
+
 Table of contents
 =================
 
 .. toctree::
    :maxdepth: 3
 
    Doxygen docs <doxygen/index.html#http://>
+   YAML playground <https://play.yaml.io/main/parser?input=IyBFZGl0IE1lIQoKJVlBTUwgMS4yCi0tLQpmb286IEhlbGxvLCBZQU1MIQpiYXI6IFsxMjMsIHRydWVdCmJhejoKLSBvbmUKLSB0d28KLSBudWxsCg==>
    ./sphinx_quicklinks
    ./sphinx_is_it_rapid
    ./sphinx_yaml_standard
    ./sphinx_using
    ./sphinx_other_languages
    ./sphinx_alternative_libraries
 
+----
 
 API teaser
 ==========

doc/sphinx_other_languages.rst

@@ -8,11 +8,21 @@ out the general approach, other languages are likely to follow (all of
 this is possible because we’re using `SWIG <http://www.swig.org/>`__,
 which makes it easy to do so).
 
+
 JavaScript
 ----------
 
 A JavaScript+WebAssembly port is available, compiled through
-`emscripten <https://emscripten.org/>`__.
+`emscripten <https://emscripten.org/>`__. Here's a quick example of
+how to compile ryml with emscripten using ``emcmake``:
+
+.. code:: bash
+
+   git clone --recursive https://github.com/biojppm/rapidyaml
+   cd rapidyaml
+   emcmake cmake -S . -B build \
+       -DCMAKE_CXX_FLAGS="-s DISABLE_EXCEPTION_CATCHING=0"
+
 
 Here's a quick example on how to configure, compile and run the tests
 using `emscripten`:

doc/sphinx_quicklinks.rst

@@ -3,7 +3,11 @@ Quick links
 
 * `API documentation (Doxygen) <./doxygen/index.html>`_
 
-* `Github repo <https://github.com/biojppm/rapidyaml>`_
+* `YAML playground <https://play.yaml.io/main/parser?input=IyBFZGl0IE1lIQoKJVlBTUwgMS4yCi0tLQpmb286IEhlbGxvLCBZQU1MIQpiYXI6IFsxMjMsIHRydWVdCmJhejoKLSBvbmUKLSB0d28KLSBudWxsCg==>`_
+
+* YAML Test Suite `online <https://matrix.yaml.info>`_ / `Github <https://github.com/yaml/yaml-test-suite>`_
+
+* `rapidyaml Github repo <https://github.com/biojppm/rapidyaml>`_
 
   * `Issues <https://github.com/biojppm/rapidyaml/issues>`_
 
@@ -17,7 +21,6 @@ Quick links
 
   * `README [0.5.0] <https://github.com/biojppm/rapidyaml/blob/v0.5.0/README.md>`_
 
-
 * Since latest release (master branch):
 
   * `README [master] <https://github.com/biojppm/rapidyaml/blob/master/README.md>`_

doc/sphinx_using.rst

@@ -199,6 +199,8 @@ of ryml:
    low-level multi-platform utilities for C++. When
    ``RYML_STANDALONE=ON``, c4core is incorporated into ryml as if it is
    the same library. Defaults to ``ON``.
+- ``RYML_INSTALL=ON/OFF``. enable/disable install target. Defaults to
+  ``ON``.
 
 If you’re developing ryml or just debugging problems with ryml itself,
 the following cmake variables can be helpful:

doc/sphinx_yaml_standard.rst

@@ -10,22 +10,43 @@ appear cases which ryml fails to parse. Your `bug reports or pull
 requests <https://github.com/biojppm/rapidyaml/issues>`__ are very
 welcome.
 
-See also `the roadmap <https://github.com/biojppm/rapidyaml/tree/master/ROADMAP.md>`__ for a list of future work.
+.. note::
+
+   If you do run into trouble and would like to investigate
+   conformance of your YAML code, **do not use existing online YAML
+   linters**, many of which are not fully conformant; instead, try
+   using `https://play.yaml.io
+   <https://play.yaml.io/main/parser?input=IyBFZGl0IE1lIQoKJVlBTUwgMS4yCi0tLQpmb286IEhlbGxvLCBZQU1MIQpiYXI6IFsxMjMsIHRydWVdCmJhejoKLSBvbmUKLSB0d28KLSBudWxsCg==>`__,
+   an amazing tool which lets you dynamically input your YAML and
+   continuously see the results from all the existing parsers (kudos
+   to @ingydotnet and the people from the YAML test suite). And of
+   course, if you detect anything wrong with ryml, please `open an
+   issue <https://github.com/biojppm/rapidyaml/issues>`__ so that we
+   can improve.
+
 
-Known limitations
------------------
+Deliberate deviations
+---------------------
 
 ryml deliberately makes no effort to follow the standard in the
 following situations:
 
--  Containers are not accepted as mapping keys: keys must be scalars.
+-  ryml's tree does NOT accept containers are as mapping keys: keys
+   must be scalars. HOWEVER, this is a limitation only of the tree. The
+   event-based parser engine DOES parse container keys. The parser
+   engine is the result of a recent refactor and its usage is meant to
+   be used by other programming languages to create their native
+   data-structures. This engine is fully tested and fully conformant
+   (other than the general error permissiveness noted below). But
+   because it is recent, it is still undocumented, and it requires some
+   API cleanup before being ready for isolated use. Please get in touch
+   if you are interested in integrating the event-based parser engine
+   without the standalone `ryml::parse_*()`
 -  Tab characters after ``:`` and ``-`` are not accepted tokens, unless
    ryml is compiled with the macro ``RYML_WITH_TAB_TOKENS``. This
    requirement exists because checking for tabs introduces branching
    into the parser’s hot code and in some cases costs as much as 10% in
    parsing time.
--  Anchor names must not end with a terminating colon: eg
-   ``&anchor: key: val``.
 -  Non-unique map keys are allowed. Enforcing key uniqueness in the
    parser or in the tree would cause log-linear parsing complexity (for
    root children on a mostly flat tree), and would increase code size
@@ -45,31 +66,22 @@ following situations:
    tag directives; also, be aware that this feature is under
    consideration for removal in YAML 1.3.
 
-Also, ryml tends to be on the permissive side where the YAML standard
-dictates there should be an error; in many of these cases, ryml will
-tolerate the input. This may be good or bad, but in any case is being
-improved on (meaning ryml will grow progressively less tolerant of YAML
-errors in the coming releases). So we strongly suggest to stay away from
-those dark corners of YAML which are generally a source of problems,
-which is a good practice anyway.
 
-.. note::
+Known (unintended) deviations
+-----------------------------
+
+ryml tends to be on the permissive side in several cases where the
+YAML standard dictates that there should be an error; in many of these
+cases, ryml will tolerate the input without producing an error. This
+is being improved on, meaning **ryml will grow progressively less
+tolerant of YAML errors** in the coming releases. So we strongly
+suggest to stay away from those dark corners of YAML which are
+generally a source of problems; this is good practice anyway.
 
-   If you do run into trouble and would like to investigate
-   conformance of your YAML code, **do not use existing online YAML
-   linters**, many of which are not fully conformant; instead, try
-   using `https://play.yaml.io
-   <https://play.yaml.io/main/parser?input=IyBFZGl0IE1lIQoKJVlBTUwgMS4yCi0tLQpmb286IEhlbGxvLCBZQU1MIQpiYXI6IFsxMjMsIHRydWVdCmJhejoKLSBvbmUKLSB0d28KLSBudWxsCg==>`__,
-   an amazing tool which lets you dynamically input your YAML and
-   continuously see the results from all the existing parsers (kudos
-   to @ingydotnet and the people from the YAML test suite). And of
-   course, if you detect anything wrong with ryml, please `open an
-   issue <https://github.com/biojppm/rapidyaml/issues>`__ so that we
-   can improve.
 
 
 YAML test suite
-===============
+---------------
 
 As part of its CI testing, ryml uses the `YAML test
 suite <https://github.com/yaml/yaml-test-suite>`__. This is an extensive
@@ -99,7 +111,7 @@ several hundred thousand individual tests to which ryml is subjected,
 which are added to the unit tests in ryml, which also employ the same
 extensive combinatorial approach.
 
-Also, note that in `their own words <http://matrix.yaml.io/>`__, the
+Also, note that in `their own words <http://matrix.yaml.info/>`__, the
 tests from the YAML test suite *contain a lot of edge cases that don’t
 play such an important role in real world examples*. And yet, despite
 the extreme focus of the test suite, currently ryml only fails a minor

samples/quickstart.cpp

@@ -299,22 +299,16 @@ void sample_lightning_overview()
 
     // emit tree
     // to std::string
-    CHECK(ryml::emitrs_yaml<std::string>(tree) == R"(foo: 1
-bar:
-  - 10
-  - 11
-  - 12
-john: doe
-)");
-    std::cout << tree; // emit to stdout
-    ryml::emit_yaml(tree, stdout); // emit to file
+    CHECK(ryml::emitrs_yaml<std::string>(tree) == R"({foo: 1,bar: [10,11,12],john: doe})");
+    std::cout << tree; // emit to ostream
+    ryml::emit_yaml(tree, stdout); // emit to FILE*
 
     // emit node
     ryml::ConstNodeRef foo = tree["foo"];
     // to std::string
     CHECK(ryml::emitrs_yaml<std::string>(foo) == "foo: 1\n");
-    std::cout << foo; // emit node to stdout
-    ryml::emit_yaml(foo, stdout); // emit node to file
+    std::cout << foo; // emit node to ostream
+    ryml::emit_yaml(foo, stdout); // emit node to FILE*
 }
 
 
@@ -869,25 +863,6 @@ I am something: indeed
     CHECK(!(constnoderef != noderef));
 
 
-    //------------------------------------------------------------------
-    // Getting the location of nodes in the source:
-    //
-    // Location tracking is opt-in:
-    ryml::Parser parser(ryml::ParserOptions().locations(true));
-    // Now the parser will start by building the accelerator structure:
-    ryml::Tree tree2;
-    parser.parse_in_arena("expected.yml", expected_result, &tree2);
-    // ... and use it when querying
-    ryml::ConstNodeRef subject_node = tree2["bar"][1];
-    CHECK(subject_node.val() == "30");
-    ryml::Location loc = parser.location(subject_node);
-    CHECK(parser.location_contents(loc).begins_with("30"));
-    CHECK(loc.line == 3u);
-    CHECK(loc.col == 4u);
-    // For further details in location tracking,
-    // refer to the sample function below.
-
-
     //------------------------------------------------------------------
     // Getting the location of nodes in the source:
     //