| 1 | # Porting notes for new AST #
|
|---|
| 2 |
|
|---|
| 3 | ## Pointer Types ##
|
|---|
| 4 | * raw pointer `T*` is used for construction, but not storage
|
|---|
| 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)`
|
|---|
| 9 | * added `N * ast::ptr_base<N,R>::set_and_mutate( const N * n )`
|
|---|
| 10 | * takes ownership of `n`, then returns a mutable version owned by this pointer
|
|---|
| 11 | * Some debate on whether this is a good approach:
|
|---|
| 12 | * makes an easy path to cloning, which we were trying to eliminate
|
|---|
| 13 | * counter-point: these are all mutating clones rather than lifetime-preserving clones, and thus "necessary" (for some definition)
|
|---|
| 14 | * existing uses:
|
|---|
| 15 | * `VariableExpr::VariableExpr`, `UntypedExpr::createDeref`
|
|---|
| 16 | * both involve grabbing a type from elsewhere and making an `lvalue` copy of it
|
|---|
| 17 | * could potentially be replaced by a view class something like this:
|
|---|
| 18 | ```
|
|---|
| 19 | template<unsigned Quals>
|
|---|
| 20 | class AddQualifiersType final : public Type {
|
|---|
| 21 | readonly<Type> base;
|
|---|
| 22 | // ...
|
|---|
| 23 | };
|
|---|
| 24 | ```
|
|---|
| 25 | * requires all `qualifiers` use (and related helpers) to be virtual, non-zero overhead
|
|---|
| 26 | * also subtle semantic change, where mutations to the source decl now change the viewing expression
|
|---|
| 27 |
|
|---|
| 28 | ## Visitors ##
|
|---|
| 29 | * `Visitor` and `Mutator` are combined into a single `ast::Visitor` class
|
|---|
| 30 | * Base nodes now override `const Node * accept( Visitor & v ) const = 0` with, e.g. `const Stmt * accept( Visitor & v ) const override = 0`
|
|---|
| 31 | * `PassVisitor` is replaced with `ast::Pass`
|
|---|
| 32 |
|
|---|
| 33 | ## Structural Changes ##
|
|---|
| 34 | `CodeLocation` has been devolved from `BaseSyntaxNode` to `ast::ParseNode`
|
|---|
| 35 | * excludes `ast::Type` from carrying location information
|
|---|
| 36 | * `CodeLocation` is a mandatory constructor field for `ast::ParseNode`
|
|---|
| 37 | * all subclass constructors must fill it; by convention, from their first argument
|
|---|
| 38 |
|
|---|
| 39 | `N->print(std::ostream&)` is a visitor now, port these methods to `ast::Print` class
|
|---|
| 40 | * **TODO** `Declaration::printShort` should also be integrated
|
|---|
| 41 |
|
|---|
| 42 | `clone` is private to `Node` now
|
|---|
| 43 | * still needs to be overriden to return appropriate type
|
|---|
| 44 | * e.g. `private: virtual Stmt * clone() const override = 0;`
|
|---|
| 45 | * because friendship is not inherited, all implementations of clone need
|
|---|
| 46 | /// Must be copied in ALL derived classes
|
|---|
| 47 | template<typename node_t>
|
|---|
| 48 | friend node_t * mutate(const node_t * node);
|
|---|
| 49 |
|
|---|
| 50 | All leaves of the `Node` inheritance tree are now declared `final`
|
|---|
| 51 | * e.g. `class CompoundStmt final : public Stmt`
|
|---|
| 52 | * allows compiler to optimize virtual calls to static calls if given static type
|
|---|
| 53 |
|
|---|
| 54 | Pulled `FuncSpecifiers`, `StorageClasses`, `CVQualifiers` out of `Type` into their own headers
|
|---|
| 55 | * Made `BFCommon` a `MakeBitfield` macro in its own header
|
|---|
| 56 | * added default and field-init constructors to macro
|
|---|
| 57 |
|
|---|
| 58 | Prefer move semantics for containers passed to node constructors
|
|---|
| 59 |
|
|---|
| 60 | ## Code Style ##
|
|---|
| 61 |
|
|---|
| 62 | ### Files ###
|
|---|
| 63 | * Headers have a `.hpp` suffix
|
|---|
| 64 | * Source code has a `.cpp` suffix
|
|---|
| 65 | * All source has the project-standard leading and trailing comments
|
|---|
| 66 | * prefer `#pragma once` over `#ifdef` guards
|
|---|
| 67 | * namespaces that cover entire files don't get indented
|
|---|
| 68 | * The general node headers only `#include "Fwd.hpp"` if they can get away with it
|
|---|
| 69 | * Anything that needs definitions goes in the .cpp file
|
|---|
| 70 | * `Type.hpp` includes `Decl.hpp` so that it knows the `AggregateDecl` subclasses for `ReferenceToType::aggr()` overloads
|
|---|
| 71 |
|
|---|
| 72 | ### Documentation ###
|
|---|
| 73 | * class, method, and field comments should use doxygen-style `///` prefix
|
|---|
| 74 | * should be included on all classes
|
|---|
| 75 | * 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
|
|---|
| 76 | * use explanatory comments with `//` wherever appropriate
|
|---|
| 77 | * older comments should be maintained in porting process wherever possible
|
|---|
| 78 |
|
|---|
| 79 | ### Naming ###
|
|---|
| 80 | * Preserve names from previous AST whenever reasonable, and get team consensus on any changes.
|
|---|
| 81 | * Strong justification required for private fields
|
|---|
| 82 | * No `get_` prefix on getters (including for generated fields)
|
|---|
| 83 | * exception is `DeclWithType::get_type()`
|
|---|
| 84 | * Notable changes:
|
|---|
| 85 | * for concision and consistency with subclasses:
|
|---|
| 86 | * `Declaration` => `ast::Decl`
|
|---|
| 87 | * `DeclarationWithType` => `ast::DeclWithType`
|
|---|
| 88 | * `Expression` => `ast::Expr`
|
|---|
| 89 | * `Initializer` => `ast::Init`
|
|---|
| 90 | * `Statement` => `ast::Stmt`
|
|---|
| 91 | * any field names should follow a similar renaming
|
|---|
| 92 | * because they don't really belong to `Type` (and for consistency with `Linkage::Spec`):
|
|---|
| 93 | * `Type::StorageClasses` => `ast::Storage::Classes`
|
|---|
| 94 | * `Type::Extern` etc. => `ast::Storage::Extern` etc.
|
|---|
| 95 | * `Type::FuncSpecifiers` => `ast::Function::Specs`
|
|---|
| 96 | * `Type::Inline` etc. => `ast::Function::Inline` etc.
|
|---|
| 97 | * `Type::Qualifiers` => `ast::CV::Qualifiers`
|
|---|
| 98 | * `Type::Const` etc. => `ast::CV::Const`
|
|---|
| 99 | * couldn't break name-dependency loop without pulling `Qualifiers` out of `Type`
|
|---|
| 100 | * `LinkageSpec::Spec` => `ast::Linkage::Spec`
|
|---|
| 101 | * `LinkageSpec::Mangle` etc. => `ast::Linkage::Mangle` etc.
|
|---|
| 102 | * `LinkageSpec::linkageUpdate` => `ast::Linkage::update`
|
|---|
| 103 | * `LinkageSpec::linkageName` => `ast::Linkage::name`
|
|---|
| 104 | * `LinkageSpec::isMangled(Spec)` etc. => `Spec.is_mangled` etc.
|
|---|
| 105 | * `LinkageSpec::Intrinsic` etc. => `ast::Linkage::Intrinsic` etc.
|
|---|
| 106 | * Boolean constructor parameters get replaced with a dedicated flag enum:
|
|---|
| 107 | * e.g. `bool isVarLen;` => `enum LengthFlag { FixedLen, VariableLen };` `LengthFlag isVarLen;`
|
|---|
| 108 | * field can be *read* in the existing boolean contexts, but requires documentation to write
|
|---|
| 109 | * suggest naming all flag enums `FooFlag` to hint at boolean nature
|
|---|
| 110 |
|
|---|
| 111 | ## Specific Nodes ##
|
|---|
| 112 | `Decl`
|
|---|
| 113 | * `storageClasses` => `storage`
|
|---|
| 114 | * `declFromId()` => `fromId()`
|
|---|
| 115 | * not 100% sure about the return type here...
|
|---|
| 116 |
|
|---|
| 117 | `DeclWithType`
|
|---|
| 118 | * When `SymTab::Validate::Pass2` is rewritten, update comment on `mangleName` with new name of pass
|
|---|
| 119 | * `get_scopedMangleName()` => `scopedMangleName()`
|
|---|
| 120 | * `get_type()` now returns `const Type*` so can't be inadvertently mutated
|
|---|
| 121 | * still with `get_` name so it doesn't conflict with subclass field names
|
|---|
| 122 |
|
|---|
| 123 | `ObjectDecl`
|
|---|
| 124 | * changed constructor parameter order for better defaults
|
|---|
| 125 | * allows `newObject` as just default settings
|
|---|
| 126 |
|
|---|
| 127 | `NamedTypeDecl`
|
|---|
| 128 | * `parameters` => `params`
|
|---|
| 129 |
|
|---|
| 130 | `TypeDecl`
|
|---|
| 131 | * moved `TypeDecl::Kind` to `ast::TypeVar::Kind`
|
|---|
| 132 |
|
|---|
| 133 | `AggregateDecl`
|
|---|
| 134 | * `parameters` => `params`
|
|---|
| 135 |
|
|---|
| 136 | `EnumDecl`
|
|---|
| 137 | * **TODO** rebuild `eval` for new AST (re: `valueOf` implementation)
|
|---|
| 138 |
|
|---|
| 139 | `Expr`
|
|---|
| 140 | * Merged `inferParams`/`resnSlots` into union, as suggested by comment in old version
|
|---|
| 141 | * does imply get_/set_ API, and some care about moving backward
|
|---|
| 142 | * added constructor that sets result, for benefit of types that set it directly
|
|---|
| 143 |
|
|---|
| 144 | `ApplicationExpr`
|
|---|
| 145 | * `function` => `func`
|
|---|
| 146 |
|
|---|
| 147 | `UntypedExpr`
|
|---|
| 148 | * `function` => `func`
|
|---|
| 149 | * removed `begin_args()` in favour of `args.begin()`
|
|---|
| 150 |
|
|---|
| 151 | `MemberExpr`
|
|---|
| 152 | * **TODO** port setup of `result` in constructor
|
|---|
| 153 |
|
|---|
| 154 | `ConstantExpr`
|
|---|
| 155 | * inlined features of `Constant`, never used elsewhere, so removed `Constant`
|
|---|
| 156 | * `Constant Constant::from_int(int)` etc. => `ConstantExpr * ConstantExpr::from_int(CodeLocation, int)`
|
|---|
| 157 | * allocates new `ConstantExpr`, consistent with all existing uses
|
|---|
| 158 |
|
|---|
| 159 | `SizeofExpr`, `AlignofExpr`
|
|---|
| 160 | * `isType` deprecated in favour of boolean check on `type`
|
|---|
| 161 | * all existing uses assume `type` set if true and don't use `expr`
|
|---|
| 162 |
|
|---|
| 163 | `AttrExpr`
|
|---|
| 164 | * did not port due to feature deprecation (e.g. `expr@attribute`)
|
|---|
| 165 |
|
|---|
| 166 | `LogicalExpr`
|
|---|
| 167 | * un-defaulted constructor parameter determining `&&` or `||`
|
|---|
| 168 |
|
|---|
| 169 | `CompoundLiteralExpr`
|
|---|
| 170 | * `initializer` => `init`
|
|---|
| 171 |
|
|---|
| 172 | `RangeExpr`
|
|---|
| 173 | * removed `set_low`, `set_high` due to disuse
|
|---|
| 174 |
|
|---|
| 175 | `TupleIndexExpr`
|
|---|
| 176 | * removed `set_tuple`, `set_index` due to disuse
|
|---|
| 177 |
|
|---|
| 178 | `GenericExpr`
|
|---|
| 179 | * `Association::isDefault` removed: `! type` is equivalent
|
|---|
| 180 |
|
|---|
| 181 | `StmtExpr`
|
|---|
| 182 | * `statements` => `stmts`
|
|---|
| 183 |
|
|---|
| 184 | `Init`
|
|---|
| 185 | * `bool maybeConstruct` => `enum ConstructFlag { DoConstruct, MaybeConstruct }`
|
|---|
| 186 |
|
|---|
| 187 | `Label`
|
|---|
| 188 | * `get_statement()` exclusively used for code location, replaced with `CodeLocation` field
|
|---|
| 189 |
|
|---|
| 190 | `CaseStmt`
|
|---|
| 191 | * `_isDefault` has been removed
|
|---|
| 192 | * `isDefault` calculates value from `cond`
|
|---|
| 193 | * default may not have a condition. I believe case (!default) requires a condition.
|
|---|
| 194 |
|
|---|
| 195 | `BranchStmt`
|
|---|
| 196 | * `Type` -> `Kind` and `type` -> `kind`
|
|---|
| 197 | * Constructors no longer throw SemanticErrorException:
|
|---|
| 198 | * `label` constructor claims it is now considered a syntax error, replaced with assert.
|
|---|
| 199 | * `computedTarget` constructor assumes `Goto`, other check would have SegFaulted.
|
|---|
| 200 |
|
|---|
| 201 | `TryStmt`
|
|---|
| 202 | * `block` -> `body` and `finallyBlock` -> `finally`
|
|---|
| 203 |
|
|---|
| 204 | `FinallyStmt`
|
|---|
| 205 | * `block` -> `body`
|
|---|
| 206 |
|
|---|
| 207 | `CompoundStmt`
|
|---|
| 208 | * Still a `std::list` for children, rather than `std::vector`
|
|---|
| 209 | * allows more-efficient splicing for purposes of later code generation
|
|---|
| 210 |
|
|---|
| 211 | `Type`
|
|---|
| 212 | * `CV::Qualifiers` moved to end of constructor parameter list, defaulted to `{}`
|
|---|
| 213 | * removed getter, setter in favour of public `qualifiers` field
|
|---|
| 214 | * `ReferenceToType` puts a defaulted list of attributes after qualifiers
|
|---|
| 215 | * `forall` field split off into `ParameterizedType` subclass
|
|---|
| 216 | * any type that needs it can inherit from `ParameterizedType`
|
|---|
| 217 | * currently `FunctionType`, `ReferenceToType`
|
|---|
| 218 | * `get_qualifiers()` replaced with accessor `qualifiers()` and mutator `set_qualifiers()`
|
|---|
| 219 | * `get_const()` etc. replaced with `is_const()` etc. variants
|
|---|
| 220 | * `referenceDepth()` now returns `unsigned` rather than `int`
|
|---|
| 221 | * A number of features only supported on aggregates pushed down to `ReferenceToType`:
|
|---|
| 222 | * `attributes`: per docs [1] GCC only supports type attributes on aggregates and typedefs
|
|---|
| 223 | * suggest adding a `TypeWithAttributes` wrapper type if this proves insufficient
|
|---|
| 224 | * `getAggr()` => `aggr()`
|
|---|
| 225 | * also now returns `const AggregateDecl *`
|
|---|
| 226 | * `genericSubstitution()` moved to own visitor in `AST/GenericSubstitution.hpp`
|
|---|
| 227 |
|
|---|
| 228 | `BasicType`
|
|---|
| 229 | * **TODO** move `kind`, `typeNames` into code generator
|
|---|
| 230 |
|
|---|
| 231 | `ReferenceToType`
|
|---|
| 232 | * deleted `get_baseParameters()` from children
|
|---|
| 233 | * replace with `aggr() ? aggr()->params : nullptr`
|
|---|
| 234 | * `parameters` => `params`
|
|---|
| 235 | * hoisted `lookup` implementation into parent, made non-virtual
|
|---|
| 236 | * also changed to return vector rather than filling; change back if any great win for reuse
|
|---|
| 237 | * `baseStruct` etc. renamed to `base`
|
|---|
| 238 |
|
|---|
| 239 | `PointerType`/`ArrayType`
|
|---|
| 240 | * `is_array()` => `isArray()`
|
|---|
| 241 | * `bool isVarLen;` => `enum LengthFlag { FixedLen, VariableLen }; LengthFlag isVarLen;`
|
|---|
| 242 | * `bool isStatic;` => `enum DimensionFlag { DynamicDim, StaticDim }; DimensionFlag isStatic;`
|
|---|
| 243 |
|
|---|
| 244 | `FunctionType`
|
|---|
| 245 | * `returnVals` => `returns`
|
|---|
| 246 | * `parameters` => `params`
|
|---|
| 247 | * `bool isVarArgs;` => `enum ArgumentFlag { FixedArgs, VariableArgs }; ArgumentFlag isVarArgs;`
|
|---|
| 248 |
|
|---|
| 249 | `TypeInstType`
|
|---|
| 250 | * `bool isFtype` => `TypeVar::Kind kind`
|
|---|
| 251 |
|
|---|
| 252 | `TypeofType`
|
|---|
| 253 | * `bool is_basetypeof` => `enum Kind { Typeof, Basetypeof } kind;`
|
|---|
| 254 |
|
|---|
| 255 | `TupleType`
|
|---|
| 256 | * removed `value_type` typedef due to likely error
|
|---|
| 257 | * if readded, should be `const Type *`
|
|---|
| 258 |
|
|---|
| 259 | `AttrType`
|
|---|
| 260 | * did not port due to deprecation of feature
|
|---|
| 261 | * feature is `type@thing` e.g. `int@MAX`
|
|---|
| 262 |
|
|---|
| 263 | [1] https://gcc.gnu.org/onlinedocs/gcc-9.1.0/gcc/Type-Attributes.html#Type-Attributes
|
|---|
| 264 |
|
|---|
