- .. -*- restructuredtext -*-
.. _PyPy: http://pypy.org/
**Grako** was created to address recurring problems encountered over decades of working with parser generation tools:
.. _Ruby: http://www.ruby-lang.org/
A **Grako** generated parser consists of the following classes:
* An *abstract* parser class that inherits from the root parser and verifies at runtime that there's a semantic method (see below) for every rule invoked. This class is useful as a parent class when changes are being made to the grammar, as it will throw an exception if there are missing semantic methods.
-* An base class with one semantic method per grammar rule. Each method receives as its single parameter the `Abstract Syntax Tree`_ (AST_) built from the rule invocation.::
+* An base class with one semantic method per grammar rule. Each method receives as its single parameter the `Abstract Syntax Tree`_ (AST_) built from the rule invocation::
def myrulename(self, ast):
**Grako** is run from the commandline::
if **Grako** was installed using *easy_install* or *pip*.
-The *-h* and *-
-help* parameters provide full usage information::
+The *-h* and *help* parameters provide full usage information::
usage: grako [-h] [-m name] [-o outfile] [-v] grammar
grammar The file name of the grammar to generate a parser for
- -h, --help show this help message and exit
- -m name, --name name An optional name for the grammar. It defaults to the
+ -h, ==help show this help message and exit
+ -m name, ==name name An optional name for the grammar. It defaults to the
basename of the grammar file's name
- -o outfile, -
+ -o outfile, outfile outfile
specify where the output should go (default is stdout)
- -t, -
-trace produce verbose parsing output
+ -t, trace produce verbose parsing output
Using the Generated Parser
To use the generated parser, just subclass the base or the abstract parser, create an instance of it, and invoke its ``parse()`` method passing the text to parse and the starting rule's name as parameter::
**Grako** uses a variant of the standard EBNF_ syntax. A grammar consists of a sequence of one or more rules of the form::
By default, **Grako** generated parsers skip the usual whitespace charactes (whatever Python_ defines as ``string.whitespace``), but you can change that behaviour by passing a ``whitespace`` parameter to your parser. For example::
If the source language is case insensitive, you can tell your parser by using the ``ignorecase`` parameter::
Parsers will skip over comments specified as a regular expression using the ``comments_re`` paramenter::
There are no constructs for semantic actions in **Grako** grammars. This is on purpose, as we believe that semantic actions obscure the declarative nature of grammars and provide for poor modularization from the parser execution perspective.
The (lack of) Documentation
**Grako** so lacking in comments and doc-comments for these reasons:
1. Inline documentation easily goes out of phase with what the code actually does. It is an equivalent and more productive effort to provide out-of-line documentation.
The file ``etc/grako.ebnf`` contains a grammar for the **Grako** EBNF_ language written in the same language. It is used in the *bootstrap* test suite to prove that **Grako** can generate a parser to parse its own language.
+The project ``examples/regexp`` contains a regexp-to-EBNF translator and parser generator. The project has no practical use, but it's a complete, end-to-end example of how to implement translators using **Grako**.
**Grako** is Copyright 2012-2013 by `ResQSoft Inc.`_ and `Juancarlo Añez`_
For queries and comments about **Grako**, please use the `Grako Forum`_.
The following must be mentioned as contributors of thoughts, ideas, code, *and funding* to the **Grako** project:
+ * Also memoize exception results.
+ * Work with unicode while rendering.
+ * Added a table of contents to this *README*.
No significant changes.
- * Grammar models (not so the generated parsers) were not producing correct ASTs_. Enough of a bug to require another release candidate.
- * Added the *override* (@) operator to grammars.
- * Try to honor a ``filename=`` keyword argument throughout (specially in error messages).
- * Refactored code that was identical in ``Parser`` and ``Context``
- * Now the text to parse is passed directly to the `parse()` method.
- * Added a *grako* script to invoke the tool directly.
- * An end-to-end translation example is provided in the *examples/regexp* project.
- * Tweaked for convenience and clearness while developing the *regexp* example.
- * Many corrections to this *README*.
- * Tested under Python_ 3.3.
- * Final release candidate for 1.0. Only improvements to the documentation will be accepted from now on.
- * Line by line review of this *README*.
- Second release candidate. Made memoization local to each parser instance so the cached information from one parse doesn't stay (as garbage) when parsing multiple (hundreds of) input files.
- First release candidate.