1
- //! Implement abstract syntax tree nodes for the python language.
1
+ //! Implement abstract syntax tree (AST) nodes for the python language.
2
2
//!
3
- //! Roughly equivalent to this: https://docs.python.org/3/library/ast.html
3
+ //! Roughly equivalent to [the python AST](https://docs.python.org/3/library/ast.html)
4
+ //! Many AST nodes have a location attribute, to determine the sourcecode
5
+ //! location of the node.
4
6
5
7
pub use crate :: location:: Location ;
6
8
use num_bigint:: BigInt ;
7
9
8
- /*
9
- #[derive(Debug)]
10
-
11
- #[derive(Debug)]
12
- pub struct Node {
13
- pub location: Location,
14
- }
15
- */
16
-
17
10
#[ allow( clippy:: large_enum_variant) ]
18
11
#[ derive( Debug , PartialEq ) ]
19
12
pub enum Top {
@@ -23,6 +16,7 @@ pub enum Top {
23
16
}
24
17
25
18
#[ derive( Debug , PartialEq ) ]
19
+ /// A full python program, it's a sequence of statements.
26
20
pub struct Program {
27
21
pub statements : Suite ,
28
22
}
@@ -45,89 +39,126 @@ pub type Suite = Vec<Statement>;
45
39
/// Abstract syntax tree nodes for python statements.
46
40
#[ derive( Debug , PartialEq ) ]
47
41
pub enum StatementType {
42
+ /// A [`break`](https://docs.python.org/3/reference/simple_stmts.html#the-break-statement) statement.
48
43
Break ,
44
+
45
+ /// A [`continue`](https://docs.python.org/3/reference/simple_stmts.html#the-continue-statement) statement.
49
46
Continue ,
50
- Return {
51
- value : Option < Expression > ,
52
- } ,
53
- Import {
54
- names : Vec < ImportSymbol > ,
55
- } ,
47
+
48
+ /// A [`return`](https://docs.python.org/3/reference/simple_stmts.html#the-return-statement) statement.
49
+ /// This is used to return from a function.
50
+ Return { value : Option < Expression > } ,
51
+
52
+ /// An [`import`](https://docs.python.org/3/reference/simple_stmts.html#the-import-statement) statement.
53
+ Import { names : Vec < ImportSymbol > } ,
54
+
55
+ /// An [`import` `from`](https://docs.python.org/3/reference/simple_stmts.html#the-import-statement) statement.
56
56
ImportFrom {
57
57
level : usize ,
58
58
module : Option < String > ,
59
59
names : Vec < ImportSymbol > ,
60
60
} ,
61
+
62
+ /// A [`pass`](https://docs.python.org/3/reference/simple_stmts.html#pass) statement.
61
63
Pass ,
64
+
65
+ /// An [`assert`](https://docs.python.org/3/reference/simple_stmts.html#the-assert-statement) statement.
62
66
Assert {
63
67
test : Expression ,
64
68
msg : Option < Expression > ,
65
69
} ,
66
- Delete {
67
- targets : Vec < Expression > ,
68
- } ,
70
+
71
+ /// A `del` statement, to delete some variables.
72
+ Delete { targets : Vec < Expression > } ,
73
+
74
+ /// Variable assignment. Note that we can assign to multiple targets.
69
75
Assign {
70
76
targets : Vec < Expression > ,
71
77
value : Expression ,
72
78
} ,
79
+
80
+ /// Augmented assignment.
73
81
AugAssign {
74
82
target : Box < Expression > ,
75
83
op : Operator ,
76
84
value : Box < Expression > ,
77
85
} ,
86
+
87
+ /// A type annotated assignment.
78
88
AnnAssign {
79
89
target : Box < Expression > ,
80
90
annotation : Box < Expression > ,
81
91
value : Option < Expression > ,
82
92
} ,
83
- Expression {
84
- expression : Expression ,
85
- } ,
86
- Global {
87
- names : Vec < String > ,
88
- } ,
89
- Nonlocal {
90
- names : Vec < String > ,
91
- } ,
93
+
94
+ /// An expression used as a statement.
95
+ Expression { expression : Expression } ,
96
+
97
+ /// The [`global`](https://docs.python.org/3/reference/simple_stmts.html#the-global-statement) statement,
98
+ /// to declare names as global variables.
99
+ Global { names : Vec < String > } ,
100
+
101
+ /// A [`nonlocal`](https://docs.python.org/3/reference/simple_stmts.html#the-nonlocal-statement) statement,
102
+ /// to declare names a non-local variables.
103
+ Nonlocal { names : Vec < String > } ,
104
+
105
+ /// An [`if`](https://docs.python.org/3/reference/compound_stmts.html#the-if-statement) statement.
92
106
If {
93
107
test : Expression ,
94
108
body : Suite ,
95
109
orelse : Option < Suite > ,
96
110
} ,
111
+
112
+ /// A [`while`](https://docs.python.org/3/reference/compound_stmts.html#the-while-statement) statement.
97
113
While {
98
114
test : Expression ,
99
115
body : Suite ,
100
116
orelse : Option < Suite > ,
101
117
} ,
118
+
119
+ /// The [`with`](https://docs.python.org/3/reference/compound_stmts.html#the-with-statement) statement.
102
120
With {
103
121
is_async : bool ,
104
122
items : Vec < WithItem > ,
105
123
body : Suite ,
106
124
} ,
125
+
126
+ /// A [`for`](https://docs.python.org/3/reference/compound_stmts.html#the-for-statement) statement.
127
+ /// Contains the body of the loop, and the `else` clause.
107
128
For {
108
129
is_async : bool ,
109
130
target : Box < Expression > ,
110
131
iter : Box < Expression > ,
111
132
body : Suite ,
112
133
orelse : Option < Suite > ,
113
134
} ,
135
+
136
+ /// A `raise` statement.
114
137
Raise {
115
138
exception : Option < Expression > ,
116
139
cause : Option < Expression > ,
117
140
} ,
141
+
142
+ /// A [`try`](https://docs.python.org/3/reference/compound_stmts.html#the-try-statement) statement.
118
143
Try {
119
144
body : Suite ,
120
145
handlers : Vec < ExceptHandler > ,
121
146
orelse : Option < Suite > ,
122
147
finalbody : Option < Suite > ,
123
148
} ,
149
+
150
+ /// A [class definition](https://docs.python.org/3/reference/compound_stmts.html#class-definitions).
124
151
ClassDef {
125
152
name : String ,
126
153
body : Suite ,
127
154
bases : Vec < Expression > ,
128
155
keywords : Vec < Keyword > ,
129
156
decorator_list : Vec < Expression > ,
130
157
} ,
158
+
159
+ /// A [function definition](https://docs.python.org/3/reference/compound_stmts.html#function-definitions).
160
+ /// Contains the name of the function, it's body
161
+ /// some decorators and formal parameters to the function.
131
162
FunctionDef {
132
163
is_async : bool ,
133
164
name : String ,
@@ -144,95 +175,150 @@ pub struct WithItem {
144
175
pub optional_vars : Option < Expression > ,
145
176
}
146
177
178
+ /// An expression at a given location in the sourcecode.
147
179
pub type Expression = Located < ExpressionType > ;
148
180
181
+ /// A certain type of expression.
149
182
#[ derive( Debug , PartialEq ) ]
150
183
pub enum ExpressionType {
151
184
BoolOp {
152
185
op : BooleanOperator ,
153
186
values : Vec < Expression > ,
154
187
} ,
188
+
189
+ /// A binary operation on two operands.
155
190
Binop {
156
191
a : Box < Expression > ,
157
192
op : Operator ,
158
193
b : Box < Expression > ,
159
194
} ,
195
+
196
+ /// Subscript operation.
160
197
Subscript {
161
198
a : Box < Expression > ,
162
199
b : Box < Expression > ,
163
200
} ,
201
+
202
+ /// An unary operation.
164
203
Unop {
165
204
op : UnaryOperator ,
166
205
a : Box < Expression > ,
167
206
} ,
207
+
208
+ /// An await expression.
168
209
Await {
169
210
value : Box < Expression > ,
170
211
} ,
212
+
213
+ /// A yield expression.
171
214
Yield {
172
215
value : Option < Box < Expression > > ,
173
216
} ,
217
+
218
+ // A yield from expression.
174
219
YieldFrom {
175
220
value : Box < Expression > ,
176
221
} ,
222
+
223
+ /// A chained comparison. Note that in python you can use
224
+ /// `1 < a < 10` for example.
177
225
Compare {
178
226
vals : Vec < Expression > ,
179
227
ops : Vec < Comparison > ,
180
228
} ,
229
+
230
+ /// Attribute access in the form of `value.name`.
181
231
Attribute {
182
232
value : Box < Expression > ,
183
233
name : String ,
184
234
} ,
235
+
236
+ /// A call expression.
185
237
Call {
186
238
function : Box < Expression > ,
187
239
args : Vec < Expression > ,
188
240
keywords : Vec < Keyword > ,
189
241
} ,
242
+
243
+ /// A numeric literal.
190
244
Number {
191
245
value : Number ,
192
246
} ,
247
+
248
+ /// A `list` literal value.
193
249
List {
194
250
elements : Vec < Expression > ,
195
251
} ,
252
+
253
+ /// A `tuple` literal value.
196
254
Tuple {
197
255
elements : Vec < Expression > ,
198
256
} ,
257
+
258
+ /// A `dict` literal value.
259
+ /// For example: `{2: 'two', 3: 'three'}`
199
260
Dict {
200
261
elements : Vec < ( Option < Expression > , Expression ) > ,
201
262
} ,
263
+
264
+ /// A `set` literal.
202
265
Set {
203
266
elements : Vec < Expression > ,
204
267
} ,
268
+
205
269
Comprehension {
206
270
kind : Box < ComprehensionKind > ,
207
271
generators : Vec < Comprehension > ,
208
272
} ,
273
+
274
+ /// A starred expression.
209
275
Starred {
210
276
value : Box < Expression > ,
211
277
} ,
278
+
279
+ /// A slice expression.
212
280
Slice {
213
281
elements : Vec < Expression > ,
214
282
} ,
283
+
284
+ /// A string literal.
215
285
String {
216
286
value : StringGroup ,
217
287
} ,
288
+
289
+ /// A bytes literal.
218
290
Bytes {
219
291
value : Vec < u8 > ,
220
292
} ,
293
+
294
+ /// An identifier, designating a certain variable or type.
221
295
Identifier {
222
296
name : String ,
223
297
} ,
298
+
299
+ /// A `lambda` function expression.
224
300
Lambda {
225
301
args : Box < Parameters > ,
226
302
body : Box < Expression > ,
227
303
} ,
304
+
305
+ /// An if-expression.
228
306
IfExpression {
229
307
test : Box < Expression > ,
230
308
body : Box < Expression > ,
231
309
orelse : Box < Expression > ,
232
310
} ,
311
+
312
+ /// The literal 'True'.
233
313
True ,
314
+
315
+ /// The literal 'False'.
234
316
False ,
317
+
318
+ // The literal `None`.
235
319
None ,
320
+
321
+ /// The ellipsis literal `...`.
236
322
Ellipsis ,
237
323
}
238
324
@@ -282,10 +368,10 @@ impl Expression {
282
368
}
283
369
}
284
370
285
- /*
286
- * In cpython this is called arguments, but we choose parameters to
287
- * distinguish between function parameters and actual call arguments.
288
- */
371
+ /// Formal parameters to a function.
372
+ ///
373
+ /// In cpython this is called arguments, but we choose parameters to
374
+ /// distinguish between function parameters and actual call arguments.
289
375
#[ derive( Debug , PartialEq , Default ) ]
290
376
pub struct Parameters {
291
377
pub args : Vec < Parameter > ,
@@ -296,6 +382,7 @@ pub struct Parameters {
296
382
pub kw_defaults : Vec < Option < Expression > > ,
297
383
}
298
384
385
+ /// A single formal parameter to a function.
299
386
#[ derive( Debug , PartialEq , Default ) ]
300
387
pub struct Parameter {
301
388
pub location : Location ,
@@ -312,6 +399,7 @@ pub enum ComprehensionKind {
312
399
Dict { key : Expression , value : Expression } ,
313
400
}
314
401
402
+ /// A list/set/dict/generator compression.
315
403
#[ derive( Debug , PartialEq ) ]
316
404
pub struct Comprehension {
317
405
pub location : Location ,
@@ -341,6 +429,7 @@ pub struct ExceptHandler {
341
429
pub body : Suite ,
342
430
}
343
431
432
+ /// An operator for a binary operation (an operation with two operands).
344
433
#[ derive( Debug , PartialEq ) ]
345
434
pub enum Operator {
346
435
Add ,
@@ -358,12 +447,14 @@ pub enum Operator {
358
447
FloorDiv ,
359
448
}
360
449
450
+ /// A boolean operation.
361
451
#[ derive( Debug , PartialEq ) ]
362
452
pub enum BooleanOperator {
363
453
And ,
364
454
Or ,
365
455
}
366
456
457
+ /// An unary operator. This is an operation with only a single operand.
367
458
#[ derive( Debug , PartialEq ) ]
368
459
pub enum UnaryOperator {
369
460
Pos ,
@@ -372,6 +463,7 @@ pub enum UnaryOperator {
372
463
Inv ,
373
464
}
374
465
466
+ /// A comparison operation.
375
467
#[ derive( Debug , PartialEq ) ]
376
468
pub enum Comparison {
377
469
Equal ,
@@ -386,6 +478,7 @@ pub enum Comparison {
386
478
IsNot ,
387
479
}
388
480
481
+ /// A numeric literal.
389
482
#[ derive( Debug , PartialEq ) ]
390
483
pub enum Number {
391
484
Integer { value : BigInt } ,
0 commit comments