| README (4479:61d3ed46e373) | README (6498:e21e9ab5fad0) |
|---|---|
| 1PLY (Python Lex-Yacc) Version 2.3 (February 18, 2007) | 1PLY (Python Lex-Yacc) Version 3.2 |
| 2 | 2 |
| 3David M. Beazley (dave@dabeaz.com) | 3Copyright (C) 2001-2009, 4David M. Beazley (Dabeaz LLC) 5All rights reserved. |
| 4 | 6 |
| 5Copyright (C) 2001-2007 David M. Beazley | 7Redistribution and use in source and binary forms, with or without 8modification, are permitted provided that the following conditions are 9met: |
| 6 | 10 |
| 7This library is free software; you can redistribute it and/or 8modify it under the terms of the GNU Lesser General Public 9License as published by the Free Software Foundation; either 10version 2.1 of the License, or (at your option) any later version. | 11* Redistributions of source code must retain the above copyright notice, 12 this list of conditions and the following disclaimer. 13* Redistributions in binary form must reproduce the above copyright notice, 14 this list of conditions and the following disclaimer in the documentation 15 and/or other materials provided with the distribution. 16* Neither the name of the David Beazley or Dabeaz LLC may be used to 17 endorse or promote products derived from this software without 18 specific prior written permission. |
| 11 | 19 |
| 12This library is distributed in the hope that it will be useful, 13but WITHOUT ANY WARRANTY; without even the implied warranty of 14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15Lesser General Public License for more details. | 20THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 24OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 26LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 16 | 31 |
| 17You should have received a copy of the GNU Lesser General Public 18License along with this library; if not, write to the Free Software 19Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 20 21See the file COPYING for a complete copy of the LGPL. 22 | |
| 23Introduction 24============ 25 26PLY is a 100% Python implementation of the common parsing tools lex | 32Introduction 33============ 34 35PLY is a 100% Python implementation of the common parsing tools lex |
| 27and yacc. Although several other parsing tools are available for 28Python, there are several reasons why you might want to consider PLY: | 36and yacc. Here are a few highlights: |
| 29 | 37 |
| 30 - The tools are very closely modeled after traditional lex/yacc. | 38 - PLY is very closely modeled after traditional lex/yacc. |
| 31 If you know how to use these tools in C, you will find PLY 32 to be similar. 33 34 - PLY provides *very* extensive error reporting and diagnostic 35 information to assist in parser construction. The original 36 implementation was developed for instructional purposes. As 37 a result, the system tries to identify the most common types 38 of errors made by novice users. 39 40 - PLY provides full support for empty productions, error recovery, 41 precedence specifiers, and moderately ambiguous grammars. 42 43 - Parsing is based on LR-parsing which is fast, memory efficient, 44 better suited to large grammars, and which has a number of nice 45 properties when dealing with syntax errors and other parsing problems. | 39 If you know how to use these tools in C, you will find PLY 40 to be similar. 41 42 - PLY provides *very* extensive error reporting and diagnostic 43 information to assist in parser construction. The original 44 implementation was developed for instructional purposes. As 45 a result, the system tries to identify the most common types 46 of errors made by novice users. 47 48 - PLY provides full support for empty productions, error recovery, 49 precedence specifiers, and moderately ambiguous grammars. 50 51 - Parsing is based on LR-parsing which is fast, memory efficient, 52 better suited to large grammars, and which has a number of nice 53 properties when dealing with syntax errors and other parsing problems. |
| 46 Currently, PLY builds its parsing tables using the SLR algorithm which 47 is slightly weaker than LALR(1) used in traditional yacc. | 54 Currently, PLY builds its parsing tables using the LALR(1) 55 algorithm used in yacc. |
| 48 49 - PLY uses Python introspection features to build lexers and parsers. 50 This greatly simplifies the task of parser construction since it reduces 51 the number of files and eliminates the need to run a separate lex/yacc 52 tool before running your program. 53 54 - PLY can be used to build parsers for "real" programming languages. 55 Although it is not ultra-fast due to its Python implementation, 56 PLY can be used to parse grammars consisting of several hundred 57 rules (as might be found for a language like C). The lexer and LR 58 parser are also reasonably efficient when parsing typically | 56 57 - PLY uses Python introspection features to build lexers and parsers. 58 This greatly simplifies the task of parser construction since it reduces 59 the number of files and eliminates the need to run a separate lex/yacc 60 tool before running your program. 61 62 - PLY can be used to build parsers for "real" programming languages. 63 Although it is not ultra-fast due to its Python implementation, 64 PLY can be used to parse grammars consisting of several hundred 65 rules (as might be found for a language like C). The lexer and LR 66 parser are also reasonably efficient when parsing typically |
| 59 sized programs. | 67 sized programs. People have used PLY to build parsers for 68 C, C++, ADA, and other real programming languages. |
| 60 | 69 |
| 61The original version of PLY was developed for an Introduction to 62Compilers course where students used it to build a compiler for a 63simple Pascal-like language. Their compiler had to include lexical 64analysis, parsing, type checking, type inference, and generation of 65assembly code for the SPARC processor. Because of this, the current 66implementation has been extensively tested and debugged. In addition, 67most of the API and error checking steps have been adapted to address 68common usability problems. 69 | |
| 70How to Use 71========== 72 73PLY consists of two files : lex.py and yacc.py. These are contained 74within the 'ply' directory which may also be used as a Python package. 75To use PLY, simply copy the 'ply' directory to your project and import 76lex and yacc from the associated 'ply' package. For example: 77 --- 13 unchanged lines hidden (view full) --- 91 92The example directory contains several different examples including a 93PLY specification for ANSI C as given in K&R 2nd Ed. 94 95A simple example is found at the end of this document 96 97Requirements 98============ | 70How to Use 71========== 72 73PLY consists of two files : lex.py and yacc.py. These are contained 74within the 'ply' directory which may also be used as a Python package. 75To use PLY, simply copy the 'ply' directory to your project and import 76lex and yacc from the associated 'ply' package. For example: 77 --- 13 unchanged lines hidden (view full) --- 91 92The example directory contains several different examples including a 93PLY specification for ANSI C as given in K&R 2nd Ed. 94 95A simple example is found at the end of this document 96 97Requirements 98============ |
| 99PLY requires the use of Python 2.1 or greater. However, you should | 99PLY requires the use of Python 2.2 or greater. However, you should |
| 100use the latest Python release if possible. It should work on just 101about any platform. PLY has been tested with both CPython and Jython. | 100use the latest Python release if possible. It should work on just 101about any platform. PLY has been tested with both CPython and Jython. |
| 102However, it does not seem to work with IronPython. | 102It also seems to work with IronPython. |
| 103 104Resources 105========= 106More information about PLY can be obtained on the PLY webpage at: 107 108 http://www.dabeaz.com/ply 109 110For a detailed overview of parsing theory, consult the excellent --- 11 unchanged lines hidden (view full) --- 122suffered through about 25 different versions of these tools :-). 123 124The CHANGES file acknowledges those who have contributed patches. 125 126Elias Ioup did the first implementation of LALR(1) parsing in PLY-1.x. 127Andrew Waters and Markus Schoepflin were instrumental in reporting bugs 128and testing a revised LALR(1) implementation for PLY-2.0. 129 | 103 104Resources 105========= 106More information about PLY can be obtained on the PLY webpage at: 107 108 http://www.dabeaz.com/ply 109 110For a detailed overview of parsing theory, consult the excellent --- 11 unchanged lines hidden (view full) --- 122suffered through about 25 different versions of these tools :-). 123 124The CHANGES file acknowledges those who have contributed patches. 125 126Elias Ioup did the first implementation of LALR(1) parsing in PLY-1.x. 127Andrew Waters and Markus Schoepflin were instrumental in reporting bugs 128and testing a revised LALR(1) implementation for PLY-2.0. 129 |
| 130Special Note for PLY-2.x | 130Special Note for PLY-3.0 |
| 131======================== | 131======================== |
| 132PLY-2.0 is the first in a series of PLY releases that will be adding a 133variety of significant new features. The first release in this series 134(Ply-2.0) should be 100% compatible with all previous Ply-1.x releases 135except for the fact that Ply-2.0 features a correct implementation of 136LALR(1) table generation. | 132PLY-3.0 the first PLY release to support Python 3. However, backwards 133compatibility with Python 2.2 is still preserved. PLY provides dual 134Python 2/3 compatibility by restricting its implementation to a common 135subset of basic language features. You should not convert PLY using 1362to3--it is not necessary and may in fact break the implementation. |
| 137 | 137 |
| 138If you have suggestions for improving PLY in future 2.x releases, please 139contact me. - Dave 140 | |
| 141Example 142======= 143 144Here is a simple example showing a PLY implementation of a calculator 145with variables. 146 147# ----------------------------------------------------------------------------- 148# calc.py --- 15 unchanged lines hidden (view full) --- 164t_DIVIDE = r'/' 165t_EQUALS = r'=' 166t_LPAREN = r'\(' 167t_RPAREN = r'\)' 168t_NAME = r'[a-zA-Z_][a-zA-Z0-9_]*' 169 170def t_NUMBER(t): 171 r'\d+' | 138Example 139======= 140 141Here is a simple example showing a PLY implementation of a calculator 142with variables. 143 144# ----------------------------------------------------------------------------- 145# calc.py --- 15 unchanged lines hidden (view full) --- 161t_DIVIDE = r'/' 162t_EQUALS = r'=' 163t_LPAREN = r'\(' 164t_RPAREN = r'\)' 165t_NAME = r'[a-zA-Z_][a-zA-Z0-9_]*' 166 167def t_NUMBER(t): 168 r'\d+' |
| 172 try: 173 t.value = int(t.value) 174 except ValueError: 175 print "Integer value too large", t.value 176 t.value = 0 | 169 t.value = int(t.value) |
| 177 return t 178 179# Ignored characters 180t_ignore = " \t" 181 182def t_newline(t): 183 r'\n+' 184 t.lexer.lineno += t.value.count("\n") --- 65 unchanged lines hidden (view full) --- 250 s = raw_input('calc > ') 251 except EOFError: 252 break 253 yacc.parse(s) 254 255 256Bug Reports and Patches 257======================= | 170 return t 171 172# Ignored characters 173t_ignore = " \t" 174 175def t_newline(t): 176 r'\n+' 177 t.lexer.lineno += t.value.count("\n") --- 65 unchanged lines hidden (view full) --- 243 s = raw_input('calc > ') 244 except EOFError: 245 break 246 yacc.parse(s) 247 248 249Bug Reports and Patches 250======================= |
| 258Because of the extremely specialized and advanced nature of PLY, I 259rarely spend much time working on it unless I receive very specific 260bug-reports and/or patches to fix problems. I also try to incorporate 261submitted feature requests and enhancements into each new version. To 262contact me about bugs and/or new features, please send email to 263dave@dabeaz.com. | 251My goal with PLY is to simply have a decent lex/yacc implementation 252for Python. As a general rule, I don't spend huge amounts of time 253working on it unless I receive very specific bug reports and/or 254patches to fix problems. I also try to incorporate submitted feature 255requests and enhancements into each new version. To contact me about 256bugs and/or new features, please send email to dave@dabeaz.com. |
| 264 265In addition there is a Google group for discussing PLY related issues at 266 267 http://groups.google.com/group/ply-hack 268 269-- Dave 270 271 272 273 274 275 276 277 278 | 257 258In addition there is a Google group for discussing PLY related issues at 259 260 http://groups.google.com/group/ply-hack 261 262-- Dave 263 264 265 266 267 268 269 270 271 |