mirror of
https://github.com/python/cpython.git
synced 2024-12-01 11:15:56 +01:00
242 lines
6.6 KiB
Python
242 lines
6.6 KiB
Python
"""Object-oriented interface to the parser module.
|
|
|
|
This module exports four classes which together provide an interface
|
|
to the parser module. Together, the three classes represent two ways
|
|
to create parsed representations of Python source and the two starting
|
|
data types (source text and tuple representations). Each class
|
|
provides interfaces which are identical other than the constructors.
|
|
The constructors are described in detail in the documentation for each
|
|
class and the remaining, shared portion of the interface is documented
|
|
below. Briefly, the classes provided are:
|
|
|
|
AST
|
|
Defines the primary interface to the AST objects and supports creation
|
|
from the tuple representation of the parse tree.
|
|
|
|
ExpressionAST
|
|
Supports creation of expression constructs from source text.
|
|
|
|
SuiteAST
|
|
Supports creation of statement suites from source text.
|
|
|
|
FileSuiteAST
|
|
Convenience subclass of the `SuiteAST' class; loads source text of the
|
|
suite from an external file.
|
|
|
|
Common Methods
|
|
--------------
|
|
|
|
Aside from the constructors, several methods are provided to allow
|
|
access to the various interpretations of the parse tree and to check
|
|
conditions of the construct represented by the parse tree.
|
|
|
|
ast()
|
|
Returns the corresponding `parser.ASTType' object.
|
|
|
|
code()
|
|
Returns the compiled code object.
|
|
|
|
filename()
|
|
Returns the name of the associated source file, if known.
|
|
|
|
isExpression()
|
|
Returns true value if parse tree represents an expression, or a false
|
|
value otherwise.
|
|
|
|
isSuite()
|
|
Returns true value if parse tree represents a suite of statements, or
|
|
a false value otherwise.
|
|
|
|
text()
|
|
Returns the source text, or None if not available.
|
|
|
|
tuple()
|
|
Returns the tuple representing the parse tree.
|
|
"""
|
|
|
|
__version__ = '$Revision$'
|
|
__copyright__ = """Copyright (c) 1995, 1996 by Fred L. Drake, Jr.
|
|
|
|
This software may be used and distributed freely for any purpose provided
|
|
that this notice is included unchanged on any and all copies. The author
|
|
does not warrant or guarantee this software in any way.
|
|
"""
|
|
|
|
class AST:
|
|
"""Base class for Abstract Syntax Tree objects.
|
|
|
|
Creates an Abstract Syntax Tree based on the tuple representation
|
|
of the parse tree. The parse tree can represent either an
|
|
expression or a suite; which will be recognized automatically.
|
|
This base class provides all of the query methods for subclass
|
|
objects defined in this module.
|
|
"""
|
|
import parser # import internally to avoid
|
|
_p = parser # namespace pollution at the
|
|
# top level
|
|
_text = None
|
|
_code = None
|
|
_ast = None
|
|
_type = 'unknown'
|
|
_tupl = None
|
|
|
|
def __init__(self, tuple):
|
|
"""Create an `AST' instance from a tuple-tree representation.
|
|
|
|
tuple
|
|
The tuple tree to convert.
|
|
|
|
The tuple-tree may represent either an expression or a suite; the
|
|
type will be determined automatically. Line number information may
|
|
optionally be present for any subset of the terminal tokens.
|
|
"""
|
|
if type(tuple) is not type(()):
|
|
raise TypeError, 'Base AST class requires tuple parameter.'
|
|
|
|
self._tupl = tuple
|
|
self._ast = self._p.tuple2ast(tuple)
|
|
self._type = (self._p.isexpr(self._ast) and 'expression') or 'suite'
|
|
|
|
def list(self, line_info = 0):
|
|
"""Returns a fresh list representing the parse tree.
|
|
|
|
line_info
|
|
If true, includes line number information for terminal tokens in
|
|
the output data structure,
|
|
"""
|
|
return self._p.ast2list(self._ast, line_info)
|
|
|
|
def tuple(self, line_info = 0):
|
|
"""Returns the tuple representing the parse tree.
|
|
|
|
line_info
|
|
If true, includes line number information for terminal tokens in
|
|
the output data structure,
|
|
"""
|
|
if self._tupl is None:
|
|
self._tupl = self._p.ast2tuple(self._ast, line_info)
|
|
return self._tupl
|
|
|
|
def code(self):
|
|
"""Returns the compiled code object.
|
|
|
|
The code object returned by this method may be passed to the
|
|
exec statement if `AST.isSuite()' is true or to the eval()
|
|
function if `AST.isExpression()' is true. All the usual rules
|
|
regarding execution of code objects apply.
|
|
"""
|
|
if not self._code:
|
|
self._code = self._p.compileast(self._ast)
|
|
return self._code
|
|
|
|
def ast(self):
|
|
"""Returns the corresponding `parser.ASTType' object.
|
|
"""
|
|
return self._ast
|
|
|
|
def filename(self):
|
|
"""Returns the name of the source file if known, or None.
|
|
"""
|
|
return None
|
|
|
|
def text(self):
|
|
"""Returns the source text, or None if not available.
|
|
|
|
If the instance is of class `AST', None is returned since no
|
|
source text is available. If of class `ExpressionAST' or
|
|
`SuiteAST', the source text passed to the constructor is
|
|
returned.
|
|
"""
|
|
return self._text
|
|
|
|
def isSuite(self):
|
|
"""Determine if `AST' instance represents a suite of statements.
|
|
"""
|
|
return self._type == 'suite'
|
|
|
|
def isExpression(self):
|
|
"""Determine if `AST' instance represents an expression.
|
|
"""
|
|
return self._type == 'expression'
|
|
|
|
|
|
|
|
class SuiteAST(AST):
|
|
"""Statement suite parse tree representation.
|
|
|
|
This subclass of the `AST' base class represents statement suites
|
|
parsed from the source text of a Python suite. If the source text
|
|
does not represent a parsable suite of statements, the appropriate
|
|
exception is raised by the parser.
|
|
"""
|
|
_type = 'suite'
|
|
|
|
def __init__(self, text):
|
|
"""Initialize a `SuiteAST' from source text.
|
|
|
|
text
|
|
Source text to parse.
|
|
"""
|
|
if type(text) is not type(''):
|
|
raise TypeError, 'SuiteAST requires source text parameter.'
|
|
self._text = text
|
|
self._ast = self._p.suite(text)
|
|
|
|
def isSuite(self):
|
|
return 1
|
|
|
|
def isExpression(self):
|
|
return 0
|
|
|
|
|
|
class FileSuiteAST(SuiteAST):
|
|
"""Representation of a python source file syntax tree.
|
|
|
|
This provides a convenience wrapper around the `SuiteAST' class to
|
|
load the source text from an external file.
|
|
"""
|
|
def __init__(self, fileName):
|
|
"""Initialize a `SuiteAST' from a source file.
|
|
|
|
fileName
|
|
Name of the external source file.
|
|
"""
|
|
self._fileName = fileName
|
|
SuiteAST.__init__(self, open(fileName).read())
|
|
|
|
def filename(self):
|
|
return self._fileName
|
|
|
|
|
|
|
|
class ExpressionAST(AST):
|
|
"""Expression parse tree representation.
|
|
|
|
This subclass of the `AST' base class represents expression
|
|
constructs parsed from the source text of a Python expression. If
|
|
the source text does not represent a parsable expression, the
|
|
appropriate exception is raised by the Python parser.
|
|
"""
|
|
_type = 'expression'
|
|
|
|
def __init__(self, text):
|
|
"""Initialize an expression AST from source text.
|
|
|
|
text
|
|
Source text to parse.
|
|
"""
|
|
if type(text) is not type(''):
|
|
raise TypeError, 'ExpressionAST requires source text parameter.'
|
|
self._text = text
|
|
self._ast = self._p.expr(text)
|
|
|
|
def isSuite(self):
|
|
return 0
|
|
|
|
def isExpression(self):
|
|
return 1
|
|
|
|
|
|
#
|
|
# end of file
|