mirror of
https://github.com/biojppm/rapidyaml.git
synced 2026-01-18 21:41:18 +01:00
Doxygen improvements
This commit is contained in:
Joao Paulo Magalhaes
@@ -952,8 +952,7 @@ WARN_LOGFILE =
|
||||
INPUT = \
|
||||
./doxy_main.md \
|
||||
../src \
|
||||
../test/test_suite/test_suite_event_handler.hpp \
|
||||
../test/test_suite/test_suite_event_handler.cpp \
|
||||
../src_extra \
|
||||
../samples/quickstart.cpp \
|
||||
../ext/c4core/src/c4/substr.hpp \
|
||||
../ext/c4core/src/c4/charconv.hpp \
|
||||
|
||||
@@ -25,7 +25,7 @@ help:
|
||||
cp -favr doxygen/html "$(BUILDDIR)/html/doxygen"
|
||||
|
||||
doxy:
|
||||
# ensure submodules are checked out
|
||||
@# ensure submodules are checked out
|
||||
if [ ! -f $(shell pwd)/../ext/c4core/cmake/c4Project.cmake ] ; then echo "ERROR: submodules not present" ; exit 1 ; fi
|
||||
if [ ! -f $(shell pwd)/../ext/c4core/src/c4/charconv.hpp ] ; then echo "ERROR: submodules not present" ; exit 1 ; fi
|
||||
doxygen Doxyfile
|
||||
|
||||
@@ -2,11 +2,35 @@ Other languages
|
||||
===============
|
||||
|
||||
One of the aims of ryml is to provide an efficient YAML API for other
|
||||
languages. JavaScript is fully available, and there is already a cursory
|
||||
implementation for Python using only the low-level API. After ironing
|
||||
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).
|
||||
languages. JavaScript is fully available, and there is already a
|
||||
cursory implementation for Python using only the low-level API. After
|
||||
ironing out the general approach, other languages are likely to follow
|
||||
suit.
|
||||
|
||||
|
||||
|
||||
Event buffer int handler
|
||||
------------------------
|
||||
|
||||
Recently we added an alternative parser event handler (not part of the
|
||||
library). This handler parses the YAML source into a linear buffer of
|
||||
integers, which contains events encoded as bitmasks, interleaved with
|
||||
strings encoded as an offset (from the beginning of the source buffer)
|
||||
and length.
|
||||
|
||||
This handler is fully compliant (ie it can handle container keys,
|
||||
unlike the ryml C++ tree), and is also 2x to 3x faster to parse.
|
||||
|
||||
This handler is meant to be used in other programming languages while
|
||||
also minimizing speed-killing inter-language calls, creating a full
|
||||
representation of the YAML tree that can be processed at once in the
|
||||
target programming language.
|
||||
|
||||
You can find the int event handler in the `src_extra source folder
|
||||
<https://github.com/biojppm/rapidyaml/tree/master/src_extra>`__. See
|
||||
its doxygen documentation for details on how to use it, and how to
|
||||
process the event array.
|
||||
|
||||
|
||||
|
||||
JavaScript
|
||||
|
||||
@@ -38,24 +38,32 @@ Windows via Git Bash or the WSL). Click on the links below to find out
|
||||
more about each sample:
|
||||
|
||||
|
||||
+-------------------------------------------------------------------------------------------------+----------------------------------+--------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
|
||||
| Sample name | ryml is part of build? | cmake file | commands |
|
||||
+=================================================================================================+==================================+==============================================================================================================+=============================================================================================================+
|
||||
| `singleheader <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheader>`_ | | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheader/CMakeLists.txt>`_ | `run.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheader/run.sh>`_ |
|
||||
| | | ryml brought as a single | | |
|
||||
| | | header, not as a library | | |
|
||||
+-------------------------------------------------------------------------------------------------+----------------------------------+--------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
|
||||
| `singleheaderlib <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib>`_ | | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib/CMakeLists.txt>`_ | | `run_shared.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib/run_shared.sh>`_ |
|
||||
| | | ryml brought as library | | | `run_static.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib/run_static.sh>`_ |
|
||||
| | | but from the single header | | |
|
||||
+-------------------------------------------------------------------------------------------------+----------------------------------+--------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
|
||||
| `add_subdirectory <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/add_subdirectory>`_ | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/add_subdirectory/CMakeLists.txt>`_ | `run.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/add_subdirectory/run.sh>`_ |
|
||||
+-------------------------------------------------------------------------------------------------+----------------------------------+--------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
|
||||
| `fetch_content <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/fetch_content>`_ | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/fetch_content/CMakeLists.txt>`_ | `run.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/fetch_content/run.sh>`_ |
|
||||
+-------------------------------------------------------------------------------------------------+----------------------------------+--------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
|
||||
| `find_package <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/find_package>`_ | | **no** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/find_package/CMakeLists.txt>`_ | `run.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/find_package/run.sh>`_ |
|
||||
| | | needs prior install or package | | |
|
||||
+-------------------------------------------------------------------------------------------------+----------------------------------+--------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------+
|
||||
+----------------------------------------------------------------------------------------------------------+----------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| Sample name | ryml is part of build? | cmake file | commands |
|
||||
+==========================================================================================================+==================================+===================================================================================================================+==================================================================================================================+
|
||||
| `singleheader <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheader>`_ | | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheader/CMakeLists.txt>`_ | `run.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheader/run.sh>`_ |
|
||||
| | | ryml brought as a single | | |
|
||||
| | | header, not as a library | | |
|
||||
+----------------------------------------------------------------------------------------------------------+----------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| `singleheaderlib <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib>`_ | | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib/CMakeLists.txt>`_ | | `run_shared.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib/run_shared.sh>`_ |
|
||||
| | | ryml brought as library | | | `run_static.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib/run_static.sh>`_ |
|
||||
| | | but from the single header | | |
|
||||
+----------------------------------------------------------------------------------------------------------+----------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| `singleheader-ints <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheader-ints>`_ | | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheader-ints/CMakeLists.txt>`_ | `run.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheader-ints/run.sh>`_ |
|
||||
| | | ryml brought as a single | | |
|
||||
| | | header, not as a library | | |
|
||||
+----------------------------------------------------------------------------------------------------------+----------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| `singleheaderlib-ints <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib-ints>`_ | | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib-ints/CMakeLists.txt>`_ | | `run_shared.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib-ints/run_shared.sh>`_ |
|
||||
| | | ryml brought as library | | | `run_static.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/singleheaderlib-ints/run_static.sh>`_ |
|
||||
| | | but from the single header | | |
|
||||
+----------------------------------------------------------------------------------------------------------+----------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| `add_subdirectory <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/add_subdirectory>`_ | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/add_subdirectory/CMakeLists.txt>`_ | `run.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/add_subdirectory/run.sh>`_ |
|
||||
+----------------------------------------------------------------------------------------------------------+----------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| `fetch_content <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/fetch_content>`_ | **yes** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/fetch_content/CMakeLists.txt>`_ | `run.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/fetch_content/run.sh>`_ |
|
||||
+----------------------------------------------------------------------------------------------------------+----------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+
|
||||
| `find_package <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/find_package>`_ | | **no** | `CMakeLists.txt <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/find_package/CMakeLists.txt>`_ | `run.sh <https://github.com/biojppm/rapidyaml/blob/v0.9.0/samples/find_package/run.sh>`_ |
|
||||
| | | needs prior install or package | | |
|
||||
+----------------------------------------------------------------------------------------------------------+----------------------------------+-------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
|
||||
As a single-header
|
||||
@@ -72,20 +80,38 @@ file suiting your particular needs (or commit):
|
||||
.. code-block:: console
|
||||
|
||||
[user@host rapidyaml]$ python3 tools/amalgamate.py -h
|
||||
usage: amalgamate.py [-h] [--c4core | --no-c4core] [--fastfloat | --no-fastfloat] [--stl | --no-stl] [output]
|
||||
|
||||
positional arguments:
|
||||
output output file. defaults to stdout
|
||||
|
||||
optional arguments:
|
||||
-h, --help show this help message and exit
|
||||
--c4core amalgamate c4core together with ryml. this is the default.
|
||||
--no-c4core amalgamate c4core together with ryml. the default is --c4core.
|
||||
--fastfloat enable fastfloat library. this is the default.
|
||||
--no-fastfloat enable fastfloat library. the default is --fastfloat.
|
||||
--stl enable stl interop. this is the default.
|
||||
--no-stl enable stl interop. the default is --stl.
|
||||
usage: amalgamate.py [-h] [--c4core | --no-c4core] [--fastfloat | --no-fastfloat]
|
||||
[--stl | --no-stl]
|
||||
[-e {tree,testsuite,int,all,none} [{tree,testsuite,int,all,none} ...]]
|
||||
[output]
|
||||
|
||||
positional arguments:
|
||||
output output file. defaults to stdout
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--c4core amalgamate c4core together with ryml. this is the default.
|
||||
--no-c4core amalgamate c4core together with ryml. the default is
|
||||
--c4core.
|
||||
--fastfloat enable fastfloat library. this is the default.
|
||||
--no-fastfloat enable fastfloat library. the default is --fastfloat.
|
||||
--stl enable stl interop. this is the default.
|
||||
--no-stl enable stl interop. the default is --stl.
|
||||
-e, --events {tree,testsuite,int,all,none} [{tree,testsuite,int,all,none} ...]
|
||||
Specify which event handlers to include. Possible values
|
||||
are: 'tree': (the default) enable the normal ryml event
|
||||
handler to create the tree, and additionally the Tree, Node,
|
||||
parser and emitter utilities; if this is not enabled, none
|
||||
of these components will be included in the amalgamated
|
||||
file. 'testsuite': enable the (extra) YAML test suite event
|
||||
handler. 'int': enable the (extra) integer-based event
|
||||
handler. 'all': enable all event handlers. 'none': disable
|
||||
all event handlers. The default is tree.
|
||||
|
||||
Note that you can select which event handlers are to be included in the
|
||||
amalgamated header. This is useful for example when using only the int
|
||||
event parsing (withou the ryml tree/node/parse/emit) for a programming
|
||||
language or special application.
|
||||
|
||||
The amalgamated header file contains all the function declarations and
|
||||
definitions. To use it in the project, ``#include`` the header at will
|
||||
|
||||
Reference in New Issue
Block a user