diff options
Diffstat (limited to 'test/external/metalang99/docs')
20 files changed, 309 insertions, 0 deletions
diff --git a/test/external/metalang99/docs/Makefile b/test/external/metalang99/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/test/external/metalang99/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/test/external/metalang99/docs/assert.rst b/test/external/metalang99/docs/assert.rst new file mode 100644 index 0000000..18d1ac0 --- /dev/null +++ b/test/external/metalang99/docs/assert.rst @@ -0,0 +1,5 @@ +assert.h +======== + +.. doxygenfile:: assert.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/bool.rst b/test/external/metalang99/docs/bool.rst new file mode 100644 index 0000000..8ef73f1 --- /dev/null +++ b/test/external/metalang99/docs/bool.rst @@ -0,0 +1,5 @@ +bool.h +====== + +.. doxygenfile:: bool.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/choice.rst b/test/external/metalang99/docs/choice.rst new file mode 100644 index 0000000..3ee0ab6 --- /dev/null +++ b/test/external/metalang99/docs/choice.rst @@ -0,0 +1,5 @@ +choice.h +======== + +.. doxygenfile:: choice.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/conf.py b/test/external/metalang99/docs/conf.py new file mode 100644 index 0000000..daebca3 --- /dev/null +++ b/test/external/metalang99/docs/conf.py @@ -0,0 +1,57 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +# -- Project information ----------------------------------------------------- + +import subprocess + +subprocess.call("cd .. ; doxygen", shell=True) + +project = 'Metalang99' +copyright = '2021, hirrolot' +author = 'hirrolot' + +# The full version, including alpha/beta/rc tags +release = '1.13.5' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ["breathe"] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "insipid" + +breathe_projects = {"Metalang99": "../xml"} +breathe_default_project = "Metalang99" +primary_domain = 'c' +highlight_language = 'c' diff --git a/test/external/metalang99/docs/either.rst b/test/external/metalang99/docs/either.rst new file mode 100644 index 0000000..5da16a2 --- /dev/null +++ b/test/external/metalang99/docs/either.rst @@ -0,0 +1,5 @@ +either.h +======== + +.. doxygenfile:: either.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/gen.rst b/test/external/metalang99/docs/gen.rst new file mode 100644 index 0000000..09a20b2 --- /dev/null +++ b/test/external/metalang99/docs/gen.rst @@ -0,0 +1,5 @@ +gen.h +===== + +.. doxygenfile:: gen.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/ident.rst b/test/external/metalang99/docs/ident.rst new file mode 100644 index 0000000..51823cf --- /dev/null +++ b/test/external/metalang99/docs/ident.rst @@ -0,0 +1,5 @@ +ident.h +======= + +.. doxygenfile:: ident.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/index.rst b/test/external/metalang99/docs/index.rst new file mode 100644 index 0000000..4666879 --- /dev/null +++ b/test/external/metalang99/docs/index.rst @@ -0,0 +1,120 @@ +.. Metalang99 documentation master file, created by + sphinx-quickstart on Mon Jan 4 08:10:23 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +The Metalang99 Standard Library +=============================== + +The Metalang99 standard library exports a set of macros implemented using the `Metalang99 metalanguage`_. + +Definitions +----------- + + - A plain macro is a macro whose result can be computed only by preprocessor expansion. + + - A Metalang99-compliant macro is a macro called through `ML99_call`/`ML99_callUneval`, directly or indirectly. To compute its result, the Metalang99 interpreter is needed. + + - A desugaring macro is a convenience macro `X(params...)` which expands to `ML99_call(X, params...)` so that you can invoke `X` as `X(v(1), v(2), v(3))`. Desugaring macros are provided for all public Metalang99-compliant macros. + +Naming conventions +------------------ + + - Plain macros follow the `SCREAMING_CASE` convention. + - Metalang99-compliant macros follow the `camelCase` convention. + - Macros denoting language terms (defined by `lang.h`) follow the `camelCase` convention. + +Sometimes, there exist two versions of the same macro: one is plain, and the other is Metalang99-compliant. For example, here are two complete metaprograms, one using `ML99_untuple` and the second one using `ML99_UNTUPLE`: + +.. code:: c + + ML99_EVAL(ML99_untuple(v((1, 2, 3)))) + +.. code:: c + + ML99_UNTUPLE((1, 2, 3)) + +Both metaprograms result in `1, 2, 3`. + +Version manipulation macros +--------------------------- + +*The following macros are defined in metalang99.h*. + +`ML99_MAJOR`, `ML99_MINOR`, and `ML99_PATCH` denote the major, the minor, and the patch version numbers, respectively. + +`ML99_VERSION_COMPATIBLE(x, y, z)` and `ML99_VERSION_EQ(x, y, z)` are function-like macros that expand to a constant boolean expression: + + - The former holds iff the current Metalang99 version is at least vx.y.z in a `SemVer`_-compatible way. Thus, if the current version is v1.2.3, then `ML99_VERSION_COMPATIBLE` will hold for v1.2.3, v1.2.6, v1.6.0, but not for v2.5.0 or v3.0.0. + - The latter one holds iff the version is exactly vx.y.z. + +These macros can be used as follows: + +.. code:: c + + #if !ML99_VERSION_COMPATIBLE(1, 2, 3) + #error Please, update your Metalang99 to v1.2.3 or higher! + #endif + +.. toctree:: + :hidden: + + lang + choice + tuple + variadics + list + seq + either + maybe + nat + ident + bool + util + assert + gen + stmt + +Contents +==================================== + + - `lang.h`_ - The core metalanguage. + - `choice.h`_ - Choice types: `(tag, ...)`. + - `tuple.h`_ - Tuples: `(x, y, z)`. + - `variadics.h`_ - Variadic arguments: `x, y, z`. + - `list.h`_ - Cons-lists. + - `seq.h`_ - Sequences: `(x)(y)(z)`. + - `either.h`_ - A choice type with two cases. + - `maybe.h`_ - An optional value. + - `nat.h`_ - Natural numbers: [0; 255]. + - `ident.h`_ - Identifiers: `[a-zA-Z0-9_]+`. + - `bool.h`_ - Boolean algebra. + - `util.h`_ - Utilitary stuff. + - `assert.h`_ - Static assertions. + - `gen.h`_ - Support for C language constructions. + - `stmt.h`_ - Statement chaining. + +Indices and tables +==================================== + +* :ref:`genindex` +* :ref:`search` + +.. _Metalang99 metalanguage: https://github.com/hirrolot/metalang99 +.. _SemVer: https://semver.org/ + +.. _lang.h: lang.html +.. _choice.h: choice.html +.. _tuple.h: tuple.html +.. _variadics.h: variadics.html +.. _list.h: list.html +.. _seq.h: seq.html +.. _either.h: either.html +.. _maybe.h: maybe.html +.. _nat.h: nat.html +.. _ident.h: ident.html +.. _bool.h: bool.html +.. _util.h: util.html +.. _assert.h: assert.html +.. _gen.h: gen.html +.. _stmt.h: stmt.html diff --git a/test/external/metalang99/docs/lang.rst b/test/external/metalang99/docs/lang.rst new file mode 100644 index 0000000..1e413c1 --- /dev/null +++ b/test/external/metalang99/docs/lang.rst @@ -0,0 +1,5 @@ +lang.h +====== + +.. doxygenfile:: lang.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/list.rst b/test/external/metalang99/docs/list.rst new file mode 100644 index 0000000..7da444c --- /dev/null +++ b/test/external/metalang99/docs/list.rst @@ -0,0 +1,5 @@ +list.h +====== + +.. doxygenfile:: list.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/make.bat b/test/external/metalang99/docs/make.bat new file mode 100644 index 0000000..2119f51 --- /dev/null +++ b/test/external/metalang99/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/test/external/metalang99/docs/maybe.rst b/test/external/metalang99/docs/maybe.rst new file mode 100644 index 0000000..7b23c60 --- /dev/null +++ b/test/external/metalang99/docs/maybe.rst @@ -0,0 +1,5 @@ +maybe.h +======= + +.. doxygenfile:: maybe.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/nat.rst b/test/external/metalang99/docs/nat.rst new file mode 100644 index 0000000..e1410c2 --- /dev/null +++ b/test/external/metalang99/docs/nat.rst @@ -0,0 +1,5 @@ +nat.h +===== + +.. doxygenfile:: nat.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/requirements.txt b/test/external/metalang99/docs/requirements.txt new file mode 100644 index 0000000..2b0e822 --- /dev/null +++ b/test/external/metalang99/docs/requirements.txt @@ -0,0 +1,2 @@ +breathe >= 4.25.1 +insipid-sphinx-theme >= 0.2.8 diff --git a/test/external/metalang99/docs/seq.rst b/test/external/metalang99/docs/seq.rst new file mode 100644 index 0000000..dc8ea0d --- /dev/null +++ b/test/external/metalang99/docs/seq.rst @@ -0,0 +1,5 @@ +seq.h +===== + +.. doxygenfile:: seq.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/stmt.rst b/test/external/metalang99/docs/stmt.rst new file mode 100644 index 0000000..c0548c6 --- /dev/null +++ b/test/external/metalang99/docs/stmt.rst @@ -0,0 +1,5 @@ +stmt.h +====== + +.. doxygenfile:: stmt.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/tuple.rst b/test/external/metalang99/docs/tuple.rst new file mode 100644 index 0000000..c81bcf2 --- /dev/null +++ b/test/external/metalang99/docs/tuple.rst @@ -0,0 +1,5 @@ +tuple.h +======= + +.. doxygenfile:: tuple.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/util.rst b/test/external/metalang99/docs/util.rst new file mode 100644 index 0000000..f0637e8 --- /dev/null +++ b/test/external/metalang99/docs/util.rst @@ -0,0 +1,5 @@ +util.h +====== + +.. doxygenfile:: util.h + :project: Metalang99 diff --git a/test/external/metalang99/docs/variadics.rst b/test/external/metalang99/docs/variadics.rst new file mode 100644 index 0000000..126c2a8 --- /dev/null +++ b/test/external/metalang99/docs/variadics.rst @@ -0,0 +1,5 @@ +variadics.h +=========== + +.. doxygenfile:: variadics.h + :project: Metalang99 |