.. Copyright (c) 2017-2026 Juancarlo Añez (apalala@gmail.com)
.. SPDX-License-Identifier: BSD-4-Clause

.. include:: links.rst


Grammar Directives
------------------

|TatSu| allows *directives* in the grammar that control the behavior of the generated parsers. All directives are of the form ``@@name :: <value>``. For example:

.. code::

    @@ignorecase :: True


The *directives* supported by |TatSu| are described below.


@@grammar :: <word>
~~~~~~~~~~~~~~~~~~~

    Specifies the name of the grammar, and provides the base name for the classes in parser source-code generation.


@@comments :: <regexp>
~~~~~~~~~~~~~~~~~~~~~~

Specifies a regular expression to identify and exclude inline (bracketed) comments before the text is scanned by the parser. For ``(* ... *)`` comments:

.. code::

    @@comments :: /\(\*((?:.|\n)*?)\*\)/

.. note::
    In previous versions of |TatSu|, the `re.MULTILINE <https://docs.python .org/3/library/re.html#re.MULTILINE>`_
    option was enabled by default. This is no longer the case. Use ``(?m)`` at the start of your
    regular expressions to make them multi-line.

@@eol_comments :: <regexp>
~~~~~~~~~~~~~~~~~~~~~~~~~~

Specifies a regular expression to identify and exclude end-of-line comments before the text is scanned by the parser. For ``# ...`` comments:

.. code::

    @@eol_comments :: /#([^\n]*?)$/

.. note::
    In previous versions of |TatSu|, the `re.MULTILINE <https://docs.python .org/3/library/re.html#re.MULTILINE>`_
    option was enabled by default. This is no longer the case. Use ``(?m)`` at the start of your
    regular expressions to make them multi-line.


@@ignorecase :: <bool>
~~~~~~~~~~~~~~~~~~~~~~

If set to ``True`` makes |TatSu| not consider case when parsing tokens. Defaults to ``False``:


.. code::

    @@ignorecase :: True


@@keyword :: {<word>|<string>}+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Specifies the list of strings or words that the grammar should consider as
*"keywords"*. May appear more than once. See the `Reserved Words and Keywords`_
section for an explanation.

.. _`Reserved Words and Keywords`: syntax.html#reserved-words-and-keywords


@@left_recursion :: <bool>
~~~~~~~~~~~~~~~~~~~~~~~~~~

Enables left-recursive rules in the grammar. See the `Left Recursion`_ sections for an explanation.

.. _`Left Recursion`: left_recursion.html

Left recursion is enabled by default. Yo may obtain faster parsing by disabling it when
it's not needed.


@@memoize :: <boolean>
~~~~~~~~~~~~~~~~~~~~~~

Enables or disables memoization during parser. Setting it fo ``False`` disables left recursion.


@@namechars :: <string>
~~~~~~~~~~~~~~~~~~~~~~~

A list of (non-alphanumeric) characters that should be considered part of names when using the `@@nameguard`_ feature:

.. code::

    @@namechars :: '-_$'

.. _`@@nameguard`: #nameguard-bool


@@nameguard :: <bool>
~~~~~~~~~~~~~~~~~~~~~

When set to ``True``, avoids matching tokens when the next character in the input sequence is alphanumeric or a ``@@namechar``. Defaults to ``True``. See the `'text' expression`_ for an explanation.

.. code::

    @@nameguard :: False

.. _`'text' expression`: syntax.html?highlight=nameguard#text-or-text


@@parseinfo :: <bool>
~~~~~~~~~~~~~~~~~~~~~

When ``True``, the parser will add parse information to every ``AST`` and ``Node`` generated by the parse under a ``parseinfo`` field. The information will include:

* ``rule`` the rule name that parsed the node
* ``pos`` the initial position for the node in the input
* ``endpos`` the final position for the node in the input
* ``line`` the initial input line number for the element
* ``endline`` the final line number for the element

Enabling ``@@parseinfo`` will allow precise reporting over the input source-code while performing semantic actions.


@@whitespace :: <regexp>
~~~~~~~~~~~~~~~~~~~~~~~~

Provides a regular expression for the whitespace to be ignored by the parser. If no definition is
provided, then ``r'(?m)\s+'`` will be used as default:

.. code::

    @@whitespace :: /[\t ]+/

To disable any parsing of whitespace, use ``None`` for the definition:

.. code::

    @@whitespace :: None

.. note::
    In previous versions of |TatSu|, the `re.MULTILINE <https://docs.python .org/3/library/re.html#re.MULTILINE>`_
    option was enabled by default. This is no longer the case. Use ``(?m)`` at the start of your
    regular expressions to make them multi-line.