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

# Porting notes for new AST #

## Pointer Types ##
* raw pointer `T*` is used for construction, but not storage
* `ast::ptr_base<T,R>` is a pointer to AST node `T` with reference type `R`
  * specialization: strong pointer `ast::ptr<T>` is used for an ownership relationship
  * specialization: weak pointer `ast::readonly<T>` is used for an observation relationship
  * added `ast::ptr_base<T,R>::as<S>()` with same semantics as `dynamic_cast<S*>(p)`

## Visitors ##
* `Visitor` and `Mutator` are combined into a single `ast::Visitor` class
  * Base nodes now override `Node* accept( Visitor& v ) = 0` with, e.g. `Stmt* accept( Visitor& v ) override = 0`
* `PassVisitor` is replaced with `ast::Pass`

## Structural Changes ##
`CodeLocation` has been devolved from `BaseSyntaxNode` to `ast::ParseNode`
* excludes `ast::Type` from carrying location information
* `CodeLocation` is a mandatory constructor field for `ast::ParseNode`
  * all subclass constructors must fill it; by convention, from their first argument

`N->print(std::ostream&)` is a visitor now, port these methods to `ast::Print` class
* **TODO** write this visitor
* **TODO** write `std::ostream& operator<< ( std::ostream& out, const Node* node )` in `Node.hpp` in terms of `ast::Print`
* `Declaration::printShort` should also be integrated

`clone` is private to `Node` now
* still needs to be overriden to return appropriate type
  * e.g. `private: virtual Stmt* clone() const override = 0;`

All leaves of the `Node` inheritance tree are now declared `final`
* e.g. `class CompoundStmt final : public Stmt`
* allows compiler to optimize virtual calls to static calls if given static type

Pulled `FuncSpecifiers` and `StorageClasses` out of `Type` into their own headers
* Made `BFCommon` a `MakeBitfield` macro in its own header
  * added default and field-init constructors to macro

Prefer move semantics for containers passed to node constructors

## Code Style ##

### Files ###
* Headers have a `.hpp` suffix
* Source code has a `.cpp` suffix
* All source has the project-standard leading and trailing comments
* prefer `#pragma once` over `#ifdef` guards
* namespaces that cover entire files don't get indented

### Documentation ###
* class, method, and field comments should use doxygen-style `///` prefix
  * should be included on all classes
  * 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
* use explanatory comments with `//` wherever appropriate
  * older comments should be maintained in porting process wherever possible

### Naming ###
* Preserve names from previous AST whenever reasonable, and get team consensus on any changes.
* Strong justification required for private fields
  * No `get_` prefix on getters (including for generated fields)
    * exception is `DeclWithType::get_type()`
* Notable changes:
  * for concision and consistency with subclasses:
    * `Declaration` => `ast::Decl`
        * `DeclarationWithType` => `ast::DeclWithType`
        * `Expression` => `ast::Expr`
        * `Initializer` => `ast::Init`
    * `Statement` => `ast::Stmt`
  * because they don't really belong to `Type` (and for consistency with `Linkage::Spec`):
    * `Type::StorageClasses` => `ast::Storage::Classes`
          * `Type::Extern` etc. => `ast::Storage::Extern` etc.
        * `LinkageSpec::Spec` => `ast::Linkage::Spec`
          * `LinkageSpec::Mangle` etc. => `ast::Linkage::Mangle` etc.
          * `LinkageSpec::linkageUpdate` => `ast::Linkage::update`
          * `LinkageSpec::linkageName` => `ast::Linkage::name`
          * `LinkageSpec::isMangled(Spec)` etc. => `Spec.is_mangled` etc.
          * `LinkageSpec::Intrinsic` etc. => `ast::Linkage::Intrinsic` etc.

## Specific Nodes ##
`Decl`
* `storageClasses` => `storage`
* `declFromId()` => `fromId()`
  * not 100% sure about the return type here...

`DeclWithType`
* When `SymTab::Validate::Pass2` is rewritten, update comment on `mangleName` with new name of pass
* `get_scopedMangleName()` => `scopedMangleName()`
* `get_type()` now returns `const Type*` so can't be inadvertently mutated
  * still with `get_` name so it doesn't conflict with subclass field names

`ObjectDecl`
* changed constructor parameter order for better defaults
  * allows `newObject` as just default settings

`TypeDecl`
* stripped `isComplete()` accessor in favour of direct access to `sized`

`EnumDecl`
* **TODO** rebuild `eval` for new AST (re: `valueOf` implementation)

`Expr`
* Merged `inferParams`/`resnSlots` into union, as suggested by comment in old version
  * does imply get_/set_ API, and some care about moving backward

`Label`
* `get_statement()` exclusively used for code location, replaced with `CodeLocation` field

`CompoundStmt`
* **TODO** port copy operator
  * Needs to be an almost-shallow clone, where the declarations are cloned only if needed
  * **TODO** port DeclReplacer
* Still a `std::list` for children, rather than `std::vector`
  * allows more-efficient splicing for purposes of later code generation

`Type`
* `forall` field split off into `ParameterizedType` subclass
  * any type that needs it can inherit from `ParameterizedType`
* `get_qualifiers()` replaced with accessor `qualifiers()` and mutator `set_qualifiers()`
  * `get_CV()` replaced with `is_CV()` variants
* A number of features only supported on aggregates pushed down to `ReferenceToType`:
  * `attributes`: per docs [1] GCC only supports type attributes on aggregates and typedefs
    * suggest adding a `TypeWithAttributes` wrapper type if this proves insufficient
  * `getAggr()`
  * `genericSubstitution()`

`BasicType`
* does not inherit from `Type` to allow pointer inlining
* moved `Kind` before qualifiers in constructor to allow for default
* **TODO** move `kind`, `typeNames` into code generator

[1] https://gcc.gnu.org/onlinedocs/gcc-9.1.0/gcc/Type-Attributes.html#Type-Attributes