Commit c703ef12 authored by Eckhart Arnold's avatar Eckhart Arnold
Browse files

documentation extended

parent 338bb636
......@@ -297,14 +297,16 @@ Clutter-free grammars
DHParser tries to minimize unnecessary clutter in grammar definitions.
To reach this goal DHParser follows a few, mostly intuitive, conventions:
1. The symbols on the left hand side of any definition (or "rule" or "production"
if you prefer one of theses terms) in the grammar is considered significant
by default. The nodes produced by the parsing-expression on the right hand
side will carry the symbol as a tag-name.
2. Some symbols can explicitly be marked as "disposable" (or "insignificant"),
however. A node generated by the parser associated with a disposable symbol
will not appear in the syntax-tree but be replaced by its children, silently.
1. The symbols on the left hand side of any definition (or "rule" or "production")
are considered significant by default.
Nodes generated by a parser associated to a symbol will carry the
symbol's name and cannot be elminated, silently. All other nodes are
considered as disposable and may silently be removed from the tree to
simplify its structe, but preserving the content.
2. Symbols can, however, be marked as "disposable", too.
Thus, you'll never see an "_elment"-node in a JSON-syntaxtree produced
by the above grammar, but only object-, array-, string-, number-, true-,
false- or null-nodes. (See :py:ref:`~ebnf.simplifying_syntax_trees`.)
......@@ -313,27 +315,29 @@ To reach this goal DHParser follows a few, mostly intuitive, conventions:
4. Comments defined by the ``@comment``-directive at the top of the grammar
are allowed in any place where insignificant ``~``-whitespace is
allowed. Thus, you never need to worry about where to provide for
allowed.
Thus, you never need to worry about where to provide for
comments in you grammar. It is as easy as it is intuitive.
(See :py:ref:`~ebnf.comments_and_whitespace`.)
5. Delimiters like "," or "[", "]" etc. typically appear as literal
string values in a grammar. Now, since delimiters are typically
surrounded by insignificant whitespace, DHParser can be advised via
the ``@literalws`` to automatically eat whitespace to the right hand
side (or to the left hand side, if you prefer) of any string literal
in the grammar without mentioning. This immediately removes a lot of
clutter from most grammars.
5. To keep the grammar clean, delimiters like "," or "[", "]"
can catch adjacent whitespace (and comments), automatically.
Since delimiters are typically surrounded by insignificant whitespace,
DHParser can be advised via the ``@literalws``-directive to
catch insignificant whitespace to the
right or left hand side of any string literal, keeping the
grammar clear of too many whitespace markers.
In case you want to grab a string without
eating its adjacent whitespace, you can still use the "backticked"
notation for string literals ```backticked string```.
6. DHParser can be advised (vie the ``@drop``-directive) to drop
tokens in form of (non-backticked) strings from the syntax-tree
already while parsing. Likewise with insignificant whitespace
or any disposable symbol. This greatly simplifies syntax-trees
at a very early stage, already.
string-tokens completely from the syntax-tree and, likewise,
insignificant whitespace or disposable symbols. This greatly reduces
the verbosity of the concrete syntax tree.
In case you want to keep a particular string token in the tree
none the less, you can still do so by assigning it to a
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment