mirror of
https://github.com/biojppm/rapidyaml.git
synced 2026-01-18 21:41:18 +01:00
event-based parser policy pt6: docs
This commit is contained in:
Joao Paulo Magalhaes
@@ -952,6 +952,8 @@ WARN_LOGFILE =
|
||||
INPUT = \
|
||||
./doxy_main.md \
|
||||
../src \
|
||||
../test/test_suite/test_suite_event_handler.hpp \
|
||||
../test/test_suite/test_suite_event_handler.cpp \
|
||||
../samples/quickstart.cpp \
|
||||
../ext/c4core/src/c4/substr.hpp \
|
||||
../ext/c4core/src/c4/charconv.hpp \
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -47,6 +47,8 @@ ryml is written in C++11, and compiles cleanly with:
|
||||
<https://github.com/biojppm/c4conf>`_.
|
||||
|
||||
|
||||
----
|
||||
|
||||
Table of contents
|
||||
=================
|
||||
|
||||
@@ -54,6 +56,7 @@ Table of contents
|
||||
: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
|
||||
@@ -61,6 +64,7 @@ Table of contents
|
||||
./sphinx_other_languages
|
||||
./sphinx_alternative_libraries
|
||||
|
||||
----
|
||||
|
||||
API teaser
|
||||
==========
|
||||
|
||||
@@ -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`:
|
||||
|
||||
@@ -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.6.0] <https://github.com/biojppm/rapidyaml/blob/v0.6.0/README.md>`_
|
||||
|
||||
|
||||
* Since latest release (master branch):
|
||||
|
||||
* `README [master] <https://github.com/biojppm/rapidyaml/blob/master/README.md>`_
|
||||
|
||||
@@ -210,8 +210,7 @@ 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``.
|
||||
- ``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:
|
||||
|
||||
@@ -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::
|
||||
|
||||
Known limitations
|
||||
-----------------
|
||||
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.
|
||||
|
||||
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user