fix rebase problems and update docs

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"
+
 
 
 Python

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_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

@@ -293,22 +293,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*
 }
 
 
@@ -863,26 +857,6 @@ I am something: indeed
     CHECK(!(constnoderef != noderef));
 
 
-    //------------------------------------------------------------------
-    // Getting the location of nodes in the source:
-    //
-    // Location tracking is opt-in:
-    ryml::EventHandlerTree evt_handler(ryml::ParserOptions().locations(true));
-    ryml::Parser parser(&evt_handler);
-    // 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:
     //

src/c4/yml/common.hpp

@@ -90,6 +90,11 @@
  *
  */
 
+/** @defgroup doc_ref_utils Anchor/Reference utilities
+ *
+ * @see sample::sample_anchors_and_aliases
+ * */
+
 /** @defgroup doc_tag_utils Tag utilities
  * @see sample::sample_tags
  */
@@ -208,9 +213,11 @@ C4_SUPPRESS_WARNING_GCC_CLANG_WITH_PUSH("-Wold-style-cast")
 #endif
 
 
-/** The type of a node id in the YAML tree.
- * @see RYML_ID_TYPE */
+/** The type of a node id in the YAML tree; to override the default
+ * type, define the macro @ref RYML_ID_TYPE to a suitable integer
+ * type. */
 using id_type = RYML_ID_TYPE;
+static_assert(std::is_integral<id_type>::value, "id_type must be an integer type");
 
 
 C4_SUPPRESS_WARNING_GCC_WITH_PUSH("-Wuseless-cast")
@@ -402,9 +409,7 @@ do                                                                      \
 {                                                                       \
     const char msg[] = msg_literal;                                     \
     RYML_DEBUG_BREAK()                                                  \
-    c4::yml::error((cb),                                                \
-                   msg, sizeof(msg),                                    \
-                   c4::yml::Location(__FILE__, 0, __LINE__, 0));        \
+    c4::yml::error((cb), msg, sizeof(msg), loc);                        \
     C4_UNREACHABLE_AFTER_ERR();                                         \
 } while(0)
 #define _RYML_CB_CHECK_(cb, cond, loc)                                  \
@@ -414,9 +419,7 @@ do                                                                      \
         {                                                               \
             const char msg[] = "check failed: " #cond;                  \
             RYML_DEBUG_BREAK()                                          \
-            c4::yml::error((cb),                                        \
-                           msg, sizeof(msg),                            \
-                           c4::yml::Location(__FILE__, 0, __LINE__, 0)); \
+            c4::yml::error((cb), msg, sizeof(msg), loc);                \
             C4_UNREACHABLE_AFTER_ERR();                                 \
         }                                                               \
     } while(0)

src/c4/yml/event_handler_tree.hpp

@@ -23,15 +23,17 @@
 #endif
 #endif
 
+C4_SUPPRESS_WARNING_MSVC_WITH_PUSH(4702) // unreachable code
 
 namespace c4 {
 namespace yml {
 
 /** @addtogroup doc_event_handlers
  * @{ */
 
-/** See the documentation for @ref doc_event_handlers, which has
- * important notes about the event model used by rapidyaml. */
+/** The event handler to create a ryml @ref Tree. See the
+ * documentation for @ref doc_event_handlers, which has important
+ * notes about the event model used by rapidyaml. */
 struct EventHandlerTree
 {
 
@@ -771,4 +773,6 @@ for(auto const& s : m_stack) printf("popped! state[%zu]: ind=%zu node=%zu\n", s.
 } // namespace yml
 } // namespace c4
 
+C4_SUPPRESS_WARNING_MSVC_POP
+
 #endif /* _C4_YML_PARSER_SINK_HPP_ */

src/c4/yml/filter_processor.hpp

@@ -11,7 +11,13 @@
 namespace c4 {
 namespace yml {
 
-/** @name filter_processors filter processors */
+/** @defgroup doc_filter_processors Scalar filter processors
+ *
+ * These are internal classes used by @ref ParseEngine to parse the
+ * scalars; normally there is no reason for a user to be manually
+ * using these classes.
+ *
+ * @ingroup doc_parse */
 /** @{ */
 
 //-----------------------------------------------------------------------------
@@ -122,11 +128,13 @@ struct FilterProcessorSrcDst
 // filter in place
 
 // debugging scaffold
+/** @cond dev */
 #if defined(RYML_DBG) && 0
 #define _c4dbgip(...) _c4dbgpf(__VA_ARGS__)
 #else
 #define _c4dbgip(...)
 #endif
+/** @endcond */
 
 /** Filters in place. While the result may be larger than the source,
  * any extending happens only at the end of the string. Consequently,
@@ -253,6 +261,10 @@ struct FilterProcessorInplaceEndExtending
 };
 
 
+//-----------------------------------------------------------------------------
+//-----------------------------------------------------------------------------
+//-----------------------------------------------------------------------------
+
 /** Filters in place. The result may be larger than the source, and
  * extending may happen anywhere. As a result some characters may be
  * left unfiltered when there is no slack in the buffer and the

src/c4/yml/parse_engine.def.hpp

@@ -45,6 +45,7 @@
 #if defined(_MSC_VER)
 #   pragma warning(push)
 #   pragma warning(disable: 4296/*expression is always 'boolean_value'*/)
+#   pragma warning(disable: 4702/*unreachable code*/)
 #elif defined(__clang__)
 #   pragma clang diagnostic push
 #   pragma clang diagnostic ignored "-Wtype-limits" // to remove a warning on an assertion that a size_t >= 0. Later on, this size_t will turn into a template argument, and then it can become < 0.