[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 | |
---|
| 30 | All 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] | 34 | Pulled `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 | |
---|
| 38 | Prefer 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 | |
---|