1 | # Porting notes for new AST # |
---|
2 | |
---|
3 | ## Pointer Types ## |
---|
4 | * raw pointer `T*` is used for construction, but not storage |
---|
5 | * strong pointer `ast::ptr<T>` is used for an ownership relationship |
---|
6 | * weak pointer `ast::readonly<T>` is used for an observation relationship |
---|
7 | |
---|
8 | ## Visitors ## |
---|
9 | * `Visitor` and `Mutator` are combined into a single `ast::Visitor` class |
---|
10 | * Base nodes now override `Node* accept( Visitor& v ) = 0` with, e.g. `Stmt* accept( Visitor& v ) override = 0` |
---|
11 | * `PassVisitor` is replaced with `ast::Pass` |
---|
12 | |
---|
13 | ## Structural Changes ## |
---|
14 | `CodeLocation` has been devolved from `BaseSyntaxNode` to `ast::ParseNode` |
---|
15 | * excludes `ast::Type` from carrying location information |
---|
16 | * `CodeLocation` is a mandatory constructor field for `ast::ParseNode` |
---|
17 | * all subclass constructors must fill it; by convention, from their first argument |
---|
18 | |
---|
19 | `N->print(std::ostream&)` is a visitor now, port these methods to `ast::Print` class |
---|
20 | * **TODO** write this visitor |
---|
21 | * **TODO** write `std::ostream& operator<< ( std::ostream& out, const Node* node )` in `Node.hpp` in terms of `ast::Print` |
---|
22 | * `Declaration::printShort` should also be integrated |
---|
23 | |
---|
24 | `clone` is private to `Node` now |
---|
25 | * still needs to be overriden to return appropriate type |
---|
26 | * e.g. `private: virtual Stmt* clone() const override = 0;` |
---|
27 | |
---|
28 | All leaves of the `Node` inheritance tree are now declared `final` |
---|
29 | * e.g. `class CompoundStmt final : public Stmt` |
---|
30 | * allows compiler to optimize virtual calls to static calls if given static type |
---|
31 | |
---|
32 | Pulled `FuncSpecifiers` and `StorageClasses` out of `Type` into their own headers |
---|
33 | * Made `BFCommon` a `MakeBitfield` macro in its own header |
---|
34 | * added default and field-init constructors to macro |
---|
35 | |
---|
36 | Prefer move semantics for containers passed to node constructors |
---|
37 | |
---|
38 | ## Code Style ## |
---|
39 | |
---|
40 | ### Files ### |
---|
41 | * Headers have a `.hpp` suffix |
---|
42 | * Source code has a `.cpp` suffix |
---|
43 | * All source has the project-standard leading and trailing comments |
---|
44 | * prefer `#pragma once` over `#ifdef` guards |
---|
45 | * namespaces that cover entire files don't get indented |
---|
46 | |
---|
47 | ### Documentation ### |
---|
48 | * class, method, and field comments should use doxygen-style `///` prefix |
---|
49 | * should be included on all classes |
---|
50 | * 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 |
---|
51 | * use explanatory comments with `//` wherever appropriate |
---|
52 | * older comments should be maintained in porting process wherever possible |
---|
53 | |
---|
54 | ### Naming ### |
---|
55 | * Preserve names from previous AST whenever reasonable, and get team consensus on any changes. |
---|
56 | * Strong justification required for private fields |
---|
57 | * No `get_` prefix on getters (including for generated fields) |
---|
58 | * Notable changes: |
---|
59 | * for concision and consistency with subclasses: |
---|
60 | * `Declaration` => `ast::Decl` |
---|
61 | * `DeclarationWithType` => `ast::DeclWithType` |
---|
62 | * `Expression` => `ast::Expr` |
---|
63 | * `Initializer` => `ast::Init` |
---|
64 | * `Statement` => `ast::Stmt` |
---|
65 | * because they don't really belong to `Type` (and for consistency with `Linkage::Spec`): |
---|
66 | * `Type::StorageClasses` => `ast::Storage::Classes` |
---|
67 | * `Type::Extern` etc. => `ast::Storage::Extern` etc. |
---|
68 | * `LinkageSpec::Spec` => `ast::Linkage::Spec` |
---|
69 | * `LinkageSpec::Mangle` etc. => `ast::Linkage::Mangle` etc. |
---|
70 | * `LinkageSpec::linkageUpdate` => `ast::Linkage::update` |
---|
71 | * `LinkageSpec::linkageName` => `ast::Linkage::name` |
---|
72 | * `LinkageSpec::isMangled(Spec)` etc. => `Spec.is_mangled` etc. |
---|
73 | * `LinkageSpec::Intrinsic` etc. => `ast::Linkage::Intrinsic` etc. |
---|
74 | |
---|
75 | ## Specific Nodes ## |
---|
76 | `Decl` |
---|
77 | * `storageClasses` => `storage` |
---|
78 | * `declFromId()` => `fromId()` |
---|
79 | * not 100% sure about the return type here... |
---|
80 | |
---|
81 | `DeclWithType` |
---|
82 | * When `SymTab::Validate::Pass2` is rewritten, update comment on `mangleName` with new name of pass |
---|
83 | * `get_scopedMangleName()` => `scopedMangleName()` |
---|
84 | * `get_type()` now returns `const Type*` so can't be inadvertently mutated |
---|
85 | * still with `get_` name so it doesn't conflict with subclass field names |
---|
86 | |
---|
87 | `ObjectDecl` |
---|
88 | * changed constructor parameter order for better defaults |
---|
89 | * allows `newObject` as just default settings |
---|
90 | |
---|
91 | `TypeDecl` |
---|
92 | * stripped `isComplete()` accessor in favour of direct access to `sized` |
---|
93 | |
---|
94 | `EnumDecl` |
---|
95 | * **TODO** rebuild `eval` for new AST (re: `valueOf` implementation) |
---|
96 | |
---|
97 | `Expr` |
---|
98 | * Merged `inferParams`/`resnSlots` into union, as suggested by comment |
---|
99 | |
---|
100 | `Label` |
---|
101 | * `get_statement()` exclusively used for code location, replaced with `CodeLocation` field |
---|
102 | |
---|
103 | `CompoundStmt` |
---|
104 | * **TODO** port copy operator |
---|
105 | * Needs to be an almost-shallow clone, where the declarations are cloned only if needed |
---|
106 | * **TODO** port DeclReplacer |
---|
107 | * Still a `std::list` for children, rather than `std::vector` |
---|
108 | * allows more-efficient splicing for purposes of later code generation |
---|