diff --git a/CMakeLists.txt b/CMakeLists.txt index 114a512a..b61a75d5 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -116,6 +116,6 @@ add_subdirectory(xo-pyjit) # ---------------------------------------------------------------- # documentation. must follow add_subdirectory() for satellite projects -xo_umbrella_doxygen_deps(xo_flatstring xo_ratio xo_unit xo_tokenizer xo_jit) +xo_umbrella_doxygen_deps(xo_flatstring xo_ratio xo_unit xo_tokenizer xo_reader xo_jit) xo_umbrella_doxygen_config() xo_umbrella_sphinx_config(index.rst docs/install.rst docs/glossary.rst) diff --git a/index.rst b/index.rst index 441d1ef4..c33d6377 100644 --- a/index.rst +++ b/index.rst @@ -16,6 +16,7 @@ Some features: kalman filters, stochastic processes, complex event processing, s xo-ratio/docs/index xo-unit/docs/index xo-tokenizer/docs/index + xo-reader/docs/index xo-jit/docs/index glossary genindex diff --git a/xo-reader/CMakeLists.txt b/xo-reader/CMakeLists.txt index 7748dc4f..0fb90c0c 100644 --- a/xo-reader/CMakeLists.txt +++ b/xo-reader/CMakeLists.txt @@ -19,9 +19,12 @@ add_definitions(${PROJECT_CXX_FLAGS}) # ---------------------------------------------------------------- add_subdirectory(src/reader) +add_subdirectory(examples) add_subdirectory(utest) +xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets) # ---------------------------------------------------------------- -# provide find_package() support - -xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets) +# docs targets depends on other library/utest/exec targets, +# must come after them +# +add_subdirectory(docs) diff --git a/xo-reader/docs/CMakeLists.txt b/xo-reader/docs/CMakeLists.txt new file mode 100644 index 00000000..9e5aca53 --- /dev/null +++ b/xo-reader/docs/CMakeLists.txt @@ -0,0 +1,7 @@ +# xo-reader/docs/CMakeLists.txt + +xo_doxygen_collect_deps() +xo_docdir_doxygen_config() +xo_docdir_sphinx_config( + index.rst +) diff --git a/xo-reader/docs/README b/xo-reader/docs/README new file mode 100644 index 00000000..ea8a9a25 --- /dev/null +++ b/xo-reader/docs/README @@ -0,0 +1,41 @@ +standalone build + + +-----------------------------------------------+ + | cmake | + | CMakeLists.txt | + | $PREFIX/share/cmake/xo_macros/xo_cxx.cmake | + +-----------------------------------------------+ + | + | +----------------------+ + +------------------------------------------------->| .build/docs/Doxyfile | + | +----------------------+ + | ^ + | (cmake | + | /------------/ + | | + | +---------------------------------------+ +-----------------+ + +---->| doxygen |--->| .build/docs/dox | + | | $PREFIX/share/xo-macros/Doxyfile.in | | +- html/ | + | +---------------------------------------+ | +- xml/ | + | +-----------------+ + | | + | /------------/ + | | + | v + | +---------------------------------------+ +--------------------+ + \---->| sphinx |--->| .build/docs/sphinx | + | +- conf.py | | +- html/ | + | +- _static/ | +--------------------+ + | +- *.rst | + +---------------------------------------+ + +umbrella build relies on top-level cmake macros + +files + + README this file + CMakeLists.txt build entry point + conf.py sphinx config + _static static files for sphinx + + index.rst toplevel sphinx document; entry point diff --git a/xo-reader/docs/_static/README b/xo-reader/docs/_static/README new file mode 100644 index 00000000..8230095c --- /dev/null +++ b/xo-reader/docs/_static/README @@ -0,0 +1 @@ +add any static {.html, .js, ..} files for sphinx to pickup here \ No newline at end of file diff --git a/xo-reader/docs/_static/img/favicon.ico b/xo-reader/docs/_static/img/favicon.ico new file mode 100644 index 00000000..15da2145 Binary files /dev/null and b/xo-reader/docs/_static/img/favicon.ico differ diff --git a/xo-reader/docs/conf.py b/xo-reader/docs/conf.py new file mode 100644 index 00000000..a598d229 --- /dev/null +++ b/xo-reader/docs/conf.py @@ -0,0 +1,39 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'xo reader documentation' +copyright = '2024-2025, Roland Conybeare' +author = 'Roland Conybeare' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +#extensions = [] +extensions = [ "breathe", + "sphinx.ext.mathjax", # inline math + "sphinx.ext.autodoc", # generate info from docstrings + "sphinxcontrib.ditaa", # diagrams-through-ascii-art + "sphinxcontrib.plantuml" # text -> uml diagrams + ] + +# note: breathe requires doxygen xml output -> must have GENERATE_XML = YES in Doxyfile.in +# match project name in Doxyfile.in +breathe_default_project = "xodoxxml" + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +pygments_style = 'sphinx' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +#html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] +html_favicon = '_static/img/favicon.ico' diff --git a/xo-reader/docs/example.rst b/xo-reader/docs/example.rst new file mode 100644 index 00000000..5ceddc4a --- /dev/null +++ b/xo-reader/docs/example.rst @@ -0,0 +1,45 @@ +.. _examples: + +.. toctree:: + :maxdepth: 2 + +Examples +======== + +See ``xo-reader/examples`` for built examples + +.. code-block:: cpp + :linenos: + + #include "xo/reader/reader.h" + + int + main() { + using namespace xo::scm; + using namespace std; + + reader rdr; + rdr.begin_translation_unit(); + + bool eof = false; + while (!eof) { + auto input = ins.read_some(); + + eof = ins.eof(); + + for (auto rem = input; !rem.empty();) { + // res: (parsed-expr, used) + auto [expr, rem2] = rdr.read_expr(rem, eof); + + if (expr) { + cout << expr << endl; + } + + rem = rem.suffix_after(rem2); + } + } + + if (rdr.has_prefix()) { + cout << "error: unparsed input after expression" << endl; + } + } diff --git a/xo-reader/docs/index.rst b/xo-reader/docs/index.rst new file mode 100644 index 00000000..2c6a1b96 --- /dev/null +++ b/xo-reader/docs/index.rst @@ -0,0 +1,12 @@ +.. xo-reader documentation master file. + +xo-reader documentation +======================= + +xo-reader provides a parser for the Schematika language. + +.. toctree:: + :maxdepth: 2 + :caption: xo-reader contents + + example diff --git a/xo-tokenizer/docs/CMakeLists.txt b/xo-tokenizer/docs/CMakeLists.txt index 898ea65d..1763e146 100644 --- a/xo-tokenizer/docs/CMakeLists.txt +++ b/xo-tokenizer/docs/CMakeLists.txt @@ -4,6 +4,6 @@ xo_doxygen_collect_deps() xo_docdir_doxygen_config() xo_docdir_sphinx_config( index.rst install.rst examples.rst implementation.rst - token-class.rst tokenizer-error-class.rst span-class.rst tokentype-enum.rst - input-state.rst + input-state-class.rst scan-result-class.rst schematika-tokens.rst span-class.rst + token-class-rst tokenizer-error-class.rst tokentype-enum.rst ) diff --git a/xo-tokenizer/docs/README b/xo-tokenizer/docs/README index f29a7b41..ea8a9a25 100644 --- a/xo-tokenizer/docs/README +++ b/xo-tokenizer/docs/README @@ -9,10 +9,10 @@ standalone build | +----------------------+ +------------------------------------------------->| .build/docs/Doxyfile | | +----------------------+ - | | + | ^ + | (cmake | | /------------/ | | - | v | +---------------------------------------+ +-----------------+ +---->| doxygen |--->| .build/docs/dox | | | $PREFIX/share/xo-macros/Doxyfile.in | | +- html/ | @@ -37,3 +37,5 @@ files CMakeLists.txt build entry point conf.py sphinx config _static static files for sphinx + + index.rst toplevel sphinx document; entry point diff --git a/xo-tokenizer/docs/schematika-tokens.rst b/xo-tokenizer/docs/schematika-tokens.rst index 21b4cdad..3d99a7ee 100644 --- a/xo-tokenizer/docs/schematika-tokens.rst +++ b/xo-tokenizer/docs/schematika-tokens.rst @@ -11,5 +11,95 @@ Schematika Tokens - examples - description * - tk_i64 - - 123, -8, + - ``123``, ``-8`` - 64-bit integer literal + * - tk_f64 + - ``1.234``, ``-10``., ``-1.981e-10``, ``3e6`` + - 64-bit floating-point literal + * - tk_string + - ``"hello"``, ``"Q: \"what's up?\"\nA: \"parsing!\""`` + - string literal. Usual escapes ``\n``, ``\r``, ``\t``, ``\"``, ``\\`` + * - tk_symbol + - ``apple``, ``funKy``, ``x123``, ``_mumble``, ``hyphenated-var`` + - symbol name + * - tk_type + - ``type`` + - keyword + * - tk_def + - ``def`` + - keyword + * - tk_lambda + - ``lambda`` + - keyword + * - tk_if + - ``if`` + - keyword + * - tk_let + - ``let`` + - keyword + * - tk_in + - ``in`` + - keyword + * - tk_end + - ``end`` + - keyword + * - tk_leftparen + - ``(`` + - + * - tk_rightparen + - ``)`` + - + * - tl_leftbracket + - ``[`` + - + * - tk_rightbracket + - ``]`` + - + * - tk_leftbrace + - ``{`` + - + * - tk_rightbrace + - ``}`` + - + * - tk_leftangle + - ``<`` + - + * - tk_rightangle + - ``>`` + - + * - tk_dot + - ``.`` + - + * - tk_comma + - ``,`` + - + * - tk_colon + - ``:`` + - + * - tk_doublecolon + - ``::`` + - + * - tk_semicolon + - ``;`` + - + * - tk_singleassign + - ``=`` + - + * - tk_assign + - ``:=`` + - + * - tk_yields + - ``->`` + - + * - tk_plus + - ``+`` + - allowed in symbol + * - tk_minus + - ``-`` + - allowed in symbol + * - tk_star + - ``*`` + - allowed in symbol + * - tk_slash + - ``/`` + - allowed in symbol diff --git a/xo-tokenizer/example/tokenrepl/tokenrepl.cpp b/xo-tokenizer/example/tokenrepl/tokenrepl.cpp index 3b70d435..9afe0059 100644 --- a/xo-tokenizer/example/tokenrepl/tokenrepl.cpp +++ b/xo-tokenizer/example/tokenrepl/tokenrepl.cpp @@ -1,4 +1,4 @@ -/** @file tokenrepl.cp **/ +/** @file tokenrepl.cpp **/ #include "xo/tokenizer/tokenizer.hpp" #include