blob: 370cfe4f46c0a1322b9c9f4be12873dcba04b4d7 [file] [log] [blame]
Guido van Rossum154a5391996-07-21 02:17:52 +00001"""Object-oriented interface to the parser module.
2
Guido van Rossum47478871996-08-21 14:32:37 +00003This module exports four classes which together provide an interface
Guido van Rossum154a5391996-07-21 02:17:52 +00004to the parser module. Together, the three classes represent two ways
5to create parsed representations of Python source and the two starting
6data types (source text and tuple representations). Each class
7provides interfaces which are identical other than the constructors.
8The constructors are described in detail in the documentation for each
9class and the remaining, shared portion of the interface is documented
Guido van Rossum47478871996-08-21 14:32:37 +000010below. Briefly, the classes provided are:
Guido van Rossum154a5391996-07-21 02:17:52 +000011
12AST
13 Defines the primary interface to the AST objects and supports creation
14 from the tuple representation of the parse tree.
15
16ExpressionAST
17 Supports creation of expression constructs from source text.
18
19SuiteAST
20 Supports creation of statement suites from source text.
21
22FileSuiteAST
23 Convenience subclass of the `SuiteAST' class; loads source text of the
24 suite from an external file.
25
Guido van Rossum47478871996-08-21 14:32:37 +000026Common Methods
27--------------
28
Guido van Rossum154a5391996-07-21 02:17:52 +000029Aside from the constructors, several methods are provided to allow
30access to the various interpretations of the parse tree and to check
31conditions of the construct represented by the parse tree.
32
33ast()
34 Returns the corresponding `parser.ASTType' object.
35
36code()
37 Returns the compiled code object.
38
39filename()
40 Returns the name of the associated source file, if known.
41
42isExpression()
43 Returns true value if parse tree represents an expression, or a false
44 value otherwise.
45
46isSuite()
47 Returns true value if parse tree represents a suite of statements, or
48 a false value otherwise.
49
50text()
51 Returns the source text, or None if not available.
52
53tuple()
54 Returns the tuple representing the parse tree.
55"""
56
57__version__ = '$Revision$'
58__copyright__ = """Copyright (c) 1995, 1996 by Fred L. Drake, Jr.
59
60This software may be used and distributed freely for any purpose provided
61that this notice is included unchanged on any and all copies. The author
62does not warrant or guarantee this software in any way.
63"""
64
65class AST:
66 """Base class for Abstract Syntax Tree objects.
67
68 Creates an Abstract Syntax Tree based on the tuple representation
69 of the parse tree. The parse tree can represent either an
70 expression or a suite; which will be recognized automatically.
71 This base class provides all of the query methods for subclass
72 objects defined in this module.
73 """
Guido van Rossum47478871996-08-21 14:32:37 +000074 import parser # import internally to avoid
75 _p = parser # namespace pollution at the
Guido van Rossum154a5391996-07-21 02:17:52 +000076 # top level
77 _text = None
78 _code = None
79 _ast = None
80 _type = 'unknown'
81 _tupl = None
82
83 def __init__(self, tuple):
84 """Create an `AST' instance from a tuple-tree representation.
85
86 tuple
87 The tuple tree to convert.
88
89 The tuple-tree may represent either an expression or a suite; the
Guido van Rossum47478871996-08-21 14:32:37 +000090 type will be determined automatically. Line number information may
91 optionally be present for any subset of the terminal tokens.
Guido van Rossum154a5391996-07-21 02:17:52 +000092 """
93 if type(tuple) is not type(()):
94 raise TypeError, 'Base AST class requires tuple parameter.'
95
96 self._tupl = tuple
97 self._ast = self._p.tuple2ast(tuple)
98 self._type = (self._p.isexpr(self._ast) and 'expression') or 'suite'
99
Guido van Rossum47478871996-08-21 14:32:37 +0000100 def list(self, line_info = 0):
101 """Returns a fresh list representing the parse tree.
102
103 line_info
104 If true, includes line number information for terminal tokens in
105 the output data structure,
106 """
107 return self._p.ast2list(self._ast, line_info)
108
109 def tuple(self, line_info = 0):
Guido van Rossum154a5391996-07-21 02:17:52 +0000110 """Returns the tuple representing the parse tree.
Guido van Rossum47478871996-08-21 14:32:37 +0000111
112 line_info
113 If true, includes line number information for terminal tokens in
114 the output data structure,
Guido van Rossum154a5391996-07-21 02:17:52 +0000115 """
116 if self._tupl is None:
Guido van Rossum47478871996-08-21 14:32:37 +0000117 self._tupl = self._p.ast2tuple(self._ast, line_info)
Guido van Rossum154a5391996-07-21 02:17:52 +0000118 return self._tupl
119
120 def code(self):
121 """Returns the compiled code object.
122
123 The code object returned by this method may be passed to the
124 exec statement if `AST.isSuite()' is true or to the eval()
125 function if `AST.isExpression()' is true. All the usual rules
126 regarding execution of code objects apply.
127 """
128 if not self._code:
129 self._code = self._p.compileast(self._ast)
130 return self._code
131
132 def ast(self):
133 """Returns the corresponding `parser.ASTType' object.
134 """
135 return self._ast
136
137 def filename(self):
138 """Returns the name of the source file if known, or None.
139 """
140 return None
141
142 def text(self):
143 """Returns the source text, or None if not available.
144
145 If the instance is of class `AST', None is returned since no
146 source text is available. If of class `ExpressionAST' or
147 `SuiteAST', the source text passed to the constructor is
148 returned.
149 """
150 return self._text
151
152 def isSuite(self):
153 """Determine if `AST' instance represents a suite of statements.
154 """
155 return self._type == 'suite'
156
157 def isExpression(self):
158 """Determine if `AST' instance represents an expression.
159 """
160 return self._type == 'expression'
161
162
163
164class SuiteAST(AST):
165 """Statement suite parse tree representation.
166
167 This subclass of the `AST' base class represents statement suites
168 parsed from the source text of a Python suite. If the source text
169 does not represent a parsable suite of statements, the appropriate
170 exception is raised by the parser.
171 """
172 _type = 'suite'
173
174 def __init__(self, text):
175 """Initialize a `SuiteAST' from source text.
176
177 text
178 Source text to parse.
179 """
180 if type(text) is not type(''):
181 raise TypeError, 'SuiteAST requires source text parameter.'
182 self._text = text
183 self._ast = self._p.suite(text)
184
185 def isSuite(self):
186 return 1
187
188 def isExpression(self):
189 return 0
190
191
192class FileSuiteAST(SuiteAST):
193 """Representation of a python source file syntax tree.
194
195 This provides a convenience wrapper around the `SuiteAST' class to
196 load the source text from an external file.
197 """
198 def __init__(self, fileName):
199 """Initialize a `SuiteAST' from a source file.
200
201 fileName
202 Name of the external source file.
203 """
204 self._fileName = fileName
205 SuiteAST.__init__(self, open(fileName).read())
206
207 def filename(self):
208 return self._fileName
209
210
211
212class ExpressionAST(AST):
213 """Expression parse tree representation.
214
215 This subclass of the `AST' base class represents expression
216 constructs parsed from the source text of a Python expression. If
217 the source text does not represent a parsable expression, the
218 appropriate exception is raised by the Python parser.
219 """
220 _type = 'expression'
221
222 def __init__(self, text):
223 """Initialize an expression AST from source text.
224
225 text
226 Source text to parse.
227 """
228 if type(text) is not type(''):
229 raise TypeError, 'ExpressionAST requires source text parameter.'
230 self._text = text
231 self._ast = self._p.expr(text)
232
233 def isSuite(self):
234 return 0
235
236 def isExpression(self):
237 return 1
238
239
240#
241# end of file