source: src/AST/porting.md @ 6d51bd7

arm-ehcleanup-dtorsjacob/cs343-translationjenkins-sandboxnew-astnew-ast-unique-expr
Last change on this file since 6d51bd7 was 6d51bd7, checked in by Thierry Delisle <tdelisle@…>, 3 years ago

Fixes to the new templated pass and started on conversions

  • Property mode set to 100644
File size: 4.9 KB
Line 
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 `const Node * accept( Visitor & v ) const = 0` with, e.g. `const Stmt * accept( Visitor & v ) const 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  * because friendship is not inherited, all implementations of clone need
28      /// Must be copied in ALL derived classes
29      template<typename node_t>
30      friend auto mutate(const node_t * node);
31
32All leaves of the `Node` inheritance tree are now declared `final`
33* e.g. `class CompoundStmt final : public Stmt`
34* allows compiler to optimize virtual calls to static calls if given static type
35
36Pulled `FuncSpecifiers` and `StorageClasses` out of `Type` into their own headers
37* Made `BFCommon` a `MakeBitfield` macro in its own header
38  * added default and field-init constructors to macro
39
40Prefer move semantics for containers passed to node constructors
41
42## Code Style ##
43
44### Files ###
45* Headers have a `.hpp` suffix
46* Source code has a `.cpp` suffix
47* All source has the project-standard leading and trailing comments
48* prefer `#pragma once` over `#ifdef` guards
49* namespaces that cover entire files don't get indented
50
51### Documentation ###
52* class, method, and field comments should use doxygen-style `///` prefix
53  * should be included on all classes
54  * 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
55* use explanatory comments with `//` wherever appropriate
56  * older comments should be maintained in porting process wherever possible
57
58### Naming ###
59* Preserve names from previous AST whenever reasonable, and get team consensus on any changes.
60* Strong justification required for private fields
61  * No `get_` prefix on getters (including for generated fields)
62* Notable changes:
63  * for concision and consistency with subclasses:
64    * `Declaration` => `ast::Decl`
65        * `DeclarationWithType` => `ast::DeclWithType`
66        * `Expression` => `ast::Expr`
67        * `Initializer` => `ast::Init`
68    * `Statement` => `ast::Stmt`
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.
72        * `LinkageSpec::Spec` => `ast::Linkage::Spec`
73          * `LinkageSpec::Mangle` etc. => `ast::Linkage::Mangle` etc.
74          * `LinkageSpec::linkageUpdate` => `ast::Linkage::update`
75          * `LinkageSpec::linkageName` => `ast::Linkage::name`
76          * `LinkageSpec::isMangled(Spec)` etc. => `Spec.is_mangled` etc.
77          * `LinkageSpec::Intrinsic` etc. => `ast::Linkage::Intrinsic` etc.
78
79## Specific Nodes ##
80`Decl`
81* `storageClasses` => `storage`
82* `declFromId()` => `fromId()`
83  * not 100% sure about the return type here...
84
85`DeclWithType`
86* When `SymTab::Validate::Pass2` is rewritten, update comment on `mangleName` with new name of pass
87* `get_scopedMangleName()` => `scopedMangleName()`
88* `get_type()` now returns `const Type*` so can't be inadvertently mutated
89  * still with `get_` name so it doesn't conflict with subclass field names
90
91`ObjectDecl`
92* changed constructor parameter order for better defaults
93  * allows `newObject` as just default settings
94
95`TypeDecl`
96* stripped `isComplete()` accessor in favour of direct access to `sized`
97
98`EnumDecl`
99* **TODO** rebuild `eval` for new AST (re: `valueOf` implementation)
100
101`Expr`
102* Merged `inferParams`/`resnSlots` into union, as suggested by comment in old version
103  * does imply get_/set_ API, and some care about moving backward
104
105`Label`
106* `get_statement()` exclusively used for code location, replaced with `CodeLocation` field
107
108`CompoundStmt`
109* **TODO** port copy operator
110  * Needs to be an almost-shallow clone, where the declarations are cloned only if needed
111  * **TODO** port DeclReplacer
112* Still a `std::list` for children, rather than `std::vector`
113  * allows more-efficient splicing for purposes of later code generation
Note: See TracBrowser for help on using the repository browser.