unikernel/duniverse/dune_/doc/reference/dune/menhir.rst

@@ -0,0 +1,51 @@
+menhir
+------
+
+A ``menhir`` stanza is available to support the Menhir parser generator.
+
+To use Menhir in a Dune project, the language version should be selected in the
+``dune-project`` file. For example:
+
+.. code:: dune
+
+  (using menhir 3.0)
+
+This will enable support for Menhir stanzas in the current project. If the
+language version is absent, Dune will automatically add this line with the
+latest Menhir version once a Menhir stanza is used anywhere.
+
+The basic form for defining menhir_ parsers (analogous to :doc:`ocamlyacc`)
+is:
+
+.. code:: dune
+
+    (menhir
+     (modules <parser1> <parser2> ...)
+     <optional-fields>)
+
+``<optional-fields>`` are:
+
+- ``(merge_into <base_name>)`` is used to define modular parsers. This
+  correspond to the ``--base`` command line option of ``menhir``. With this
+  option, a single parser named ``base_name`` is generated.
+
+- ``(flags <option1> <option2> ...)`` is used to pass extra flags to Menhir.
+
+- ``(infer <bool>)`` is used to enable Menhir with type inference. This option
+  is enabled by default with Menhir language 2.0.
+
+Menhir supports writing the grammar and automation to the ``.cmly`` file.
+Therefore, if this is flag is passed to Menhir, Dune will know to introduce a
+``.cmly`` target for the module.
+
+- ``(explain <blang expression>)`` is used to control the generation of the
+  ``.conflicts`` file explaining conflicts found while generating the
+  parser. The condition is specified using the
+  :doc:`/reference/boolean-language`. This field was introduced in version 3.0
+  of the Menhir extension.
+
+Note that starting in version 3.0 of the Menhir extension, the ``.conflicts``
+file is generated by default. If this is not desired, it needs to be disabled
+explicitly by using the ``(explain)`` field.
+
+.. _menhir: https://gitlab.inria.fr/fpottier/menhir