Commits

Juancarlo Añez committed 768aabe Merge

Merged latest changes from the default branch.

Comments (0)

Files changed (5)

+64bab5d7fe9622505069666d379c9844e3018b26 0.0.1
+e84354fbff943d0233e68da064cd579903de098c 1.0.0-rc.1
+e84354fbff943d0233e68da064cd579903de098c 1.0.0-rc.1
+0000000000000000000000000000000000000000 1.0.0-rc.1
+0000000000000000000000000000000000000000 1.0.0-rc.1
+b78e397ed28449b9fa2473ab63b50cfce8f99f4e 1.0.0-rc.1
+6eec9c1caabcb5ed33e32a7843b39510c310715e 1.0.0-rc.2
+aa6b6428e3ade497a6ca60ffceef1c31afe12078 1.0.0-rc.3
+b4c9cd09891da4d03d2404fcc765226eaacc3e17 1.0.0-rc.4
+7e61371f5395574a75275569b9dade78a462a3aa 1.0.0
+b4c9cd09891da4d03d2404fcc765226eaacc3e17 1.0rc4
+0000000000000000000000000000000000000000 1.0rc4
+aa6b6428e3ade497a6ca60ffceef1c31afe12078 1.0rc3
+0000000000000000000000000000000000000000 1.0rc3
+6eec9c1caabcb5ed33e32a7843b39510c310715e 1.0rc2
+0000000000000000000000000000000000000000 1.0rc2
+b78e397ed28449b9fa2473ab63b50cfce8f99f4e 1.0rc1
+0000000000000000000000000000000000000000 1.0rc1
 64bab5d7fe9622505069666d379c9844e3018b26 0.1
-e84354fbff943d0233e68da064cd579903de098c 1.0rc1
-e84354fbff943d0233e68da064cd579903de098c 1.0rc1
-0000000000000000000000000000000000000000 1.0rc1
+0000000000000000000000000000000000000000 0.1
+b78e397ed28449b9fa2473ab63b50cfce8f99f4e 1.0rc1
 0000000000000000000000000000000000000000 1.0rc1
 b78e397ed28449b9fa2473ab63b50cfce8f99f4e 1.0rc1
-6eec9c1caabcb5ed33e32a7843b39510c310715e 1.0rc2
-aa6b6428e3ade497a6ca60ffceef1c31afe12078 1.0rc3
-b4c9cd09891da4d03d2404fcc765226eaacc3e17 1.0rc4
-7e61371f5395574a75275569b9dade78a462a3aa 1.0.0
+0000000000000000000000000000000000000000 1.0rc1
- .. -*- restructuredtext -*-
-
+=====
 Grako
 =====
 
 .. _PyPy: http://pypy.org/
 
 
+Table of Contents
+=================
+.. contents:: \
+
+
 Rationale
----------
+=========
 
 **Grako** was created to address recurring problems encountered over decades of working with parser generation tools:
 
 .. _Ruby: http://www.ruby-lang.org/
 
 The Generated Parsers
----------------------
+=====================
 
 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):
         return ast
        
 
 Using the Tool
---------------
+==============
 
 **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::
 
         $ python -m grako -h
         usage: grako [-h] [-m name] [-o outfile] [-v] grammar
           grammar               The file name of the grammar to generate a parser for
 
         optional arguments:
-          -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, --outfile 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::
 
 
 
 The EBNF Grammar Syntax
------------------------
+=======================
 
 **Grako** uses a variant of the standard EBNF_ syntax. A grammar consists of a sequence of one or more rules of the form::
 
 
 
 Whitespace
-----------
+==========
 
 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::
 
 
 
 Case Sensitivity
-----------------
+================
 
 If the source language is case insensitive, you can tell your parser by using the ``ignorecase`` parameter::
 
 
 
 Comments
---------
+========
 
 Parsers will skip over comments specified as a regular expression using the ``comments_re`` paramenter::
     
 
 
 Semantic Actions
-----------------
+================
 
 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.
 
 
 Examples
---------
+========
 
 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**.
+
 
 License
--------
+=======
 
 **Grako** is Copyright 2012-2013 by `ResQSoft Inc.`_ and  `Juancarlo Añez`_
 
 
 
 Contact
--------
+=======
 
 For queries and comments about **Grako**, please use the `Grako Forum`_.
 
 
 
 Credits
--------
+=======
 
 The following must be mentioned as contributors of thoughts, ideas, code, *and funding* to the **Grako** project:
 
 
 
 Change History
---------------
+==============
+
+**tip**
+    * Also memoize exception results.
+    * Work with unicode while rendering.
+    * Added a table of contents to this *README*.
 
 **1.0.0**
-   No significant changes. 
+    First feature-complete release.
 
-**1.0rc4**
-    * 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``
-
-**1.0rc3**
-    * 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*.
-
-**1.0rc2**
-    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.
-
-**1.0rc1**
-    First release candidate.
-

examples/regexp/README.rst

 .. _EBNF: http://en.wikipedia.org/wiki/Ebnf 
 .. _PEG:http://en.wikipedia.org/wiki/Parsing_expression_grammar 
 
-The project has no practical use, but it's complete yet concise example of how to implement translators in **Grakos**'.
+The project has no practical use, but it's complete yet concise example of how to implement translators in **Grako**'.
 
 The parser builds an OO model of each parsed regexp using semantic actions. The model generates a **Grako** grammar with the help the *rendering* module using inline templates. The generated grammar is then parsed to generate a parser. The generated parser can be executed thus::
 

grako/rendering.py

 """
 from __future__ import print_function, division, absolute_import, unicode_literals
 import itertools
-from .util import trim
+from .util import trim, ustr
 
 def render(item, join='', **fields):
     """ Render the given item
     elif isinstance(item, list):
         return join.join(render(e, join=join, **fields) for e in item)
     else:
-        return str(item)
+        return ustr(item)
 
 
 class Renderer(object):
 # -*- coding: utf-8 -*-
 from __future__ import print_function, division, absolute_import, unicode_literals
+import sys
 
 __all__ = ['simplify', 'memoize', 'trim', 'indent']
 
+def ustr(s):
+    if sys.version_info[0] >= 3:
+        return str(s)
+    else:
+        return unicode(s)
+
 def simplify(x):
     if isinstance(x, list) and len(x) == 1:
         return simplify(x[0])
     """
     if text is None:
         return ''
-    text = str(text)
+    text = ustr(text)
     if indent >= 0:
         lines = [' ' * 4 * indent + t for t in text.split('\n')]
         text = '\n'.join(lines)