parsimonious 0.4

Goals

• Speed

• Frugal RAM use

• Minimalistic, understandable, idiomatic Python code

• Readable grammars

• Extensible grammars

• Complete test coverage

• Separation of concerns. Some Python parsing kits mix recognition with instructions about how to turn the resulting tree into some kind of other representation. This is limiting when you want to do several different things with a tree: for example, render wiki markup to HTML or to text.

• Good error reporting. I want the parser to work with me as I develop a grammar.

Example Usage

Here’s how to build a simple grammar:

>>> from parsimonious.grammar import Grammar
>>> grammar = Grammar(
...     """
...     bold_text  = bold_open text bold_close
...     text       = ~"[A-Z 0-9]*"i
...     bold_open  = "(("
...     bold_close = "))"
...     """)

You can have forward references and even right recursion; it’s all taken care of by the grammar compiler. The first rule is taken to be the default start symbol, but you can override that.

Next, let’s parse something and get an abstract syntax tree:

>>> print grammar.parse('((bold stuff))')
<Node called "bold_text" matching "((bold stuff))">
    <Node called "bold_open" matching "((">
    <RegexNode called "text" matching "bold stuff">
    <Node called "bold_close" matching "))">

You’d typically then use a nodes.NodeVisitor subclass (see below) to walk the tree and do something useful with it.

Status

• Everything that exists works. Test coverage is good.

• I don’t plan on making any backward-incompatible changes to the rule syntax in the future, so you can write grammars without fear.

• It may be slow and use a lot of RAM; I haven’t measured either yet. However, I have yet to begin optimizing in earnest.

• Error reporting is fairly uninformative, and debugging is nonexistent. However, repr methods of expressions, grammars, and nodes are very clear and helpful. Ones of Grammar objects are even round-trippable! Huge things are planned for grammar debugging in the future.

• The grammar extensibility story is underdeveloped at the moment. You should be able to extend a grammar by simply concatening more rules onto the existing ones; later rules of the same name should override previous ones. However, this is untested and may not be the final story.

• Sphinx docs are coming, but the docstrings are quite useful now.

• Note that there may be API changes until we get to 1.0.

A Little About PEG Parsers

PEG parsers don’t draw a distinction between lexing and parsing; everything is done at once. As a result, there is no lookahead limit, as there is with, for instance, Yacc. And, due to both of these properties, PEG grammars are easier to write: they’re basically just a more practical dialect of EBNF. With caching, they take O(grammar size * text length) memory (though I plan to do better), but they run in O(text length) time.

Writing Grammars

Grammars are defined by a series of rules, one per line. The syntax should be familiar to anyone who uses regexes or reads programming language manuals. An example will serve best:

styled_text = bold_text / italic_text
bold_text   = "((" text "))"
italic_text = "''" text "''"
text        = ~"[A-Z 0-9]*"i

Optimizing Grammars

Processing Parse Trees

A parse tree has a node for each expression matched, even if it matched a zero-length string, like "thing"? might.

The NodeVisitor class provides an inversion-of-control framework for walking a tree and returning a new construct (tree, string, or whatever) based on it. For now, have a look at its docstrings for more detail. There’s also a good example in grammar.RuleVisitor. Notice how we take advantage of nodes’ iterability by using tuple unpacks in the formal parameter lists:

def visit_or_term(self, or_term, (_, slash, term)):
    ...

When something goes wrong in your visitor, you get a nice error like this:

[normal traceback here...]
VisitationException: 'Node' object has no attribute 'foo'

Parse tree:
<Node called "rules" matching "number = ~"[0-9]+"">  <-- *** We were here. ***
    <Node matching "number = ~"[0-9]+"">
        <Node called "rule" matching "number = ~"[0-9]+"">
            <Node matching "">
            <Node called "label" matching "number">
            <Node matching " ">
                <Node called "_" matching " ">
            <Node matching "=">
            <Node matching " ">
                <Node called "_" matching " ">
            <Node called "rhs" matching "~"[0-9]+"">
                <Node called "term" matching "~"[0-9]+"">
                    <Node called "atom" matching "~"[0-9]+"">
                        <Node called "regex" matching "~"[0-9]+"">
                            <Node matching "~">
                            <Node called "literal" matching ""[0-9]+"">
                            <Node matching "">
            <Node matching "">
            <Node called "eol" matching "
            ">
    <Node matching "">

The parse tree is tacked onto the exception, and the node whose visitor method raised the error is pointed out.

Future Directions

Version History

0.4

• Support Python 3.

• Fix import * for parsimonious.expressions.

• Rewrite grammar compiler so right-recursive rules can be compiled and parsing no longer fails in some cases with forward rule references.

0.3

• Support comments, the ! (“not”) operator, and parentheses in grammar definition syntax.

• Change the & operator to a prefix operator to conform to the original PEG syntax. The version in Parsing Techniques was infix, and that’s what I used as a reference. However, the unary version is more convenient, as it lets you spell AB & A as simply A &B.

• Take the print statements out of the benchmark tests.

• Give Node an evaluate-able __repr__.

0.2

• Support matching of prefixes and other not-to-the-end slices of strings by making match() public and able to initialize a new cache. Add match() callthrough method to Grammar.

• Report a BadGrammar exception (rather than crashing) when there are mistakes in a grammar definition.

• Simplify grammar compilation internals: get rid of superfluous visitor methods and factor up repetitive ones. Simplify rule grammar as well.

• Add NodeVisitor.lift_child convenience method.

• Rename VisitationException to VisitationError for consistency with the standard Python exception hierarchy.

• Rework repr and str values for grammars and expressions. Now they both look like rule syntax. Grammars are even round-trippable! This fixes a unicode encoding error when printing nodes that had parsed unicode text.

• Add tox for testing. Stop advertising Python 2.5 support, which never worked (and won’t unless somebody cares a lot, since it makes Python 3 support harder).

• Settle (hopefully) on the term “rule” to mean “the string representation of a production”. Get rid of the vague, mysterious “DSL”.

0.1

• A rough but useable preview release

Thanks to Wiki Loves Monuments Panama for showing their support with a generous gift.