source: src/AST/porting.md @ 9e1d485

ADTarm-ehast-experimentalcleanup-dtorsenumforall-pointer-decayjacob/cs343-translationjenkins-sandboxnew-astnew-ast-unique-exprpthread-emulationqualifiedEnum
Last change on this file since 9e1d485 was 9e1d485, checked in by Aaron Moss <a3moss@…>, 5 years ago

First draft of ast::Type with subclasses

  • Property mode set to 100644
File size: 7.8 KB
RevLine 
[2bb4a01]1# Porting notes for new AST #
2
3## Pointer Types ##
4* raw pointer `T*` is used for construction, but not storage
[fdbd4fd]5* `ast::ptr_base<T,R>` is a pointer to AST node `T` with reference type `R`
6  * specialization: strong pointer `ast::ptr<T>` is used for an ownership relationship
7  * specialization: weak pointer `ast::readonly<T>` is used for an observation relationship
8  * added `ast::ptr_base<T,R>::as<S>()` with same semantics as `dynamic_cast<S*>(p)`
[2bb4a01]9
10## Visitors ##
11* `Visitor` and `Mutator` are combined into a single `ast::Visitor` class
12  * Base nodes now override `Node* accept( Visitor& v ) = 0` with, e.g. `Stmt* accept( Visitor& v ) override = 0`
13* `PassVisitor` is replaced with `ast::Pass`
14
15## Structural Changes ##
16`CodeLocation` has been devolved from `BaseSyntaxNode` to `ast::ParseNode`
17* excludes `ast::Type` from carrying location information
18* `CodeLocation` is a mandatory constructor field for `ast::ParseNode`
19  * all subclass constructors must fill it; by convention, from their first argument
20
21`N->print(std::ostream&)` is a visitor now, port these methods to `ast::Print` class
22* **TODO** write this visitor
23* **TODO** write `std::ostream& operator<< ( std::ostream& out, const Node* node )` in `Node.hpp` in terms of `ast::Print`
24* `Declaration::printShort` should also be integrated
25
26`clone` is private to `Node` now
27* still needs to be overriden to return appropriate type
28  * e.g. `private: virtual Stmt* clone() const override = 0;`
29
30All leaves of the `Node` inheritance tree are now declared `final`
31* e.g. `class CompoundStmt final : public Stmt`
32* allows compiler to optimize virtual calls to static calls if given static type
33
[9e1d485]34Pulled `FuncSpecifiers`, `StorageClasses`, `CVQualifiers` out of `Type` into their own headers
[2bb4a01]35* Made `BFCommon` a `MakeBitfield` macro in its own header
36  * added default and field-init constructors to macro
37
38Prefer move semantics for containers passed to node constructors
39
40## Code Style ##
41
42### Files ###
43* Headers have a `.hpp` suffix
44* Source code has a `.cpp` suffix
45* All source has the project-standard leading and trailing comments
46* prefer `#pragma once` over `#ifdef` guards
47* namespaces that cover entire files don't get indented
48
49### Documentation ###
50* class, method, and field comments should use doxygen-style `///` prefix
51  * should be included on all classes
52  * should be included on any method declaration that doesn't have an obvious behaviour from either naming convention (e.g. constructor, print operator, implement visitor pattern) or an inline implementation
53* use explanatory comments with `//` wherever appropriate
54  * older comments should be maintained in porting process wherever possible
55
56### Naming ###
57* Preserve names from previous AST whenever reasonable, and get team consensus on any changes.
58* Strong justification required for private fields
[a300e4a]59  * No `get_` prefix on getters (including for generated fields)
[fdbd4fd]60    * exception is `DeclWithType::get_type()`
[2bb4a01]61* Notable changes:
62  * for concision and consistency with subclasses:
63    * `Declaration` => `ast::Decl`
[14cebb7a]64        * `DeclarationWithType` => `ast::DeclWithType`
[2bb4a01]65        * `Expression` => `ast::Expr`
66        * `Initializer` => `ast::Init`
67    * `Statement` => `ast::Stmt`
[9e1d485]68        * any field names should follow a similar renaming
[2bb4a01]69  * because they don't really belong to `Type` (and for consistency with `Linkage::Spec`):
70    * `Type::StorageClasses` => `ast::Storage::Classes`
71          * `Type::Extern` etc. => `ast::Storage::Extern` etc.
[9e1d485]72        * `Type::FuncSpecifiers` => `ast::Function::Specs`
73          * `Type::Inline` etc. => `ast::Function::Inline` etc.
74        * `Type::Qualifiers` => `ast::CV::Qualifiers`
75          * `Type::Const` etc. => `ast::CV::Const`
76          * couldn't break name-dependency loop without pulling `Qualifiers` out of `Type`
[2bb4a01]77        * `LinkageSpec::Spec` => `ast::Linkage::Spec`
78          * `LinkageSpec::Mangle` etc. => `ast::Linkage::Mangle` etc.
79          * `LinkageSpec::linkageUpdate` => `ast::Linkage::update`
80          * `LinkageSpec::linkageName` => `ast::Linkage::name`
81          * `LinkageSpec::isMangled(Spec)` etc. => `Spec.is_mangled` etc.
82          * `LinkageSpec::Intrinsic` etc. => `ast::Linkage::Intrinsic` etc.
[9e1d485]83* Boolean constructor parameters get replaced with a dedicated flag enum:
84  * e.g. `bool isVarLen;` => `enum LengthFlag { FixedLen, VariableLen };` `LengthFlag isVarLen;`
85  * field can be *read* in the existing boolean contexts, but requires documentation to write
86  * suggest naming all flag enums `FooFlag` to hint at boolean nature
[2bb4a01]87
88## Specific Nodes ##
89`Decl`
90* `storageClasses` => `storage`
91* `declFromId()` => `fromId()`
92  * not 100% sure about the return type here...
93
94`DeclWithType`
95* When `SymTab::Validate::Pass2` is rewritten, update comment on `mangleName` with new name of pass
[a300e4a]96* `get_scopedMangleName()` => `scopedMangleName()`
[77a3f41]97* `get_type()` now returns `const Type*` so can't be inadvertently mutated
98  * still with `get_` name so it doesn't conflict with subclass field names
99
100`ObjectDecl`
101* changed constructor parameter order for better defaults
102  * allows `newObject` as just default settings
[a300e4a]103
[360b2e13]104`TypeDecl`
[9e1d485]105* moved `TypeDecl::Kind` to `ast::TypeVar::Kind`
[360b2e13]106
[a300e4a]107`EnumDecl`
108* **TODO** rebuild `eval` for new AST (re: `valueOf` implementation)
[2bb4a01]109
110`Expr`
[79f7875]111* Merged `inferParams`/`resnSlots` into union, as suggested by comment in old version
112  * does imply get_/set_ API, and some care about moving backward
[2bb4a01]113
[9e1d485]114`Init`
115* `bool maybeConstruct` => `enum ConstructFlag { DoConstruct, MaybeConstruct }`
116
[2bb4a01]117`Label`
118* `get_statement()` exclusively used for code location, replaced with `CodeLocation` field
119
120`CompoundStmt`
121* **TODO** port copy operator
122  * Needs to be an almost-shallow clone, where the declarations are cloned only if needed
[9e1d485]123  * **TODO** port `DeclReplacer`
[2bb4a01]124* Still a `std::list` for children, rather than `std::vector`
[fdbd4fd]125  * allows more-efficient splicing for purposes of later code generation
126
127`Type`
[9e1d485]128* `CV::Qualifiers` moved to end of constructor parameter list, defaulted to `{}`
129  * `ReferenceToType` puts a defaulted list of attributes after qualifiers
[fdbd4fd]130* `forall` field split off into `ParameterizedType` subclass
131  * any type that needs it can inherit from `ParameterizedType`
[9e1d485]132    * currently `FunctionType`, `ReferenceToType`
[fdbd4fd]133* `get_qualifiers()` replaced with accessor `qualifiers()` and mutator `set_qualifiers()`
[9e1d485]134  * `get_const()` etc. replaced with `is_const()` etc. variants
135* `referenceDepth()` now returns `unsigned` rather than `int`
[fdbd4fd]136* A number of features only supported on aggregates pushed down to `ReferenceToType`:
137  * `attributes`: per docs [1] GCC only supports type attributes on aggregates and typedefs
138    * suggest adding a `TypeWithAttributes` wrapper type if this proves insufficient
[9e1d485]139  * `getAggr()` => `aggr()`
140    * also now returns `const AggregateDecl *`
141* `genericSubstitution()` moved to own visitor **TODO** write
[fdbd4fd]142
143`BasicType`
144* **TODO** move `kind`, `typeNames` into code generator
145
[9e1d485]146`ReferenceToType`
147* deleted `get_baseParameters()` from children
148  * replace with `aggr() ? aggr()->parameters : nullptr`
149* hoisted `lookup` implementation into parent, made non-virtual
150  * also changed to return vector rather than filling; change back if any great win for reuse
151* `baseStruct` etc. renamed to `base`
152
153`PointerType`/`ArrayType`
154* `is_array()` => `isArray()`
155* `bool isVarLen;` => `enum LengthFlag { FixedLen, VariableLen }; LengthFlag isVarLen;`
156* `bool isStatic;` => `enum DimensionFlag { DynamicDim, StaticDim }; DimensionFlag isStatic;`
157
158`FunctionType`
159* `bool isVarArgs;` => `enum ArgumentFlag { FixedArgs, VariableArgs }; ArgumentFlag isVarArgs;`
160
161`TypeInstType`
162* `bool isFtype` => `TypeVar::Kind kind`
163
164`TypeofType`
165* `bool is_basetypeof` => `enum Kind { Typeof, Basetypeof } kind;`
166
167`TupleType`
168* removed `value_type` typedef due to likely error
169  * if readded, should be `const Type *`
170
171`AttrType`
172* did not port due to (likely) disuse
173  * best guess at use (from printing code) is deprecated handling for attributes
174
[fdbd4fd]175[1] https://gcc.gnu.org/onlinedocs/gcc-9.1.0/gcc/Type-Attributes.html#Type-Attributes
176
Note: See TracBrowser for help on using the repository browser.