cpython/Lib/AST.py
1996-08-21 14:32:37 +00:00

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