src/ozulis/visitors/scope-builder.doch

   1 /**
   2  * @page scopebuilder Scope builder
   3  *
   4  * @section introduction Introduction
   5  * The scope builder builds scope. A scope is a collection of Symbol.
   6  *
   7  * @section implementation Implementation
   8  *
   9  * @subsection rules Rules
  10  * - The scope builder can not override a symbol. (weakness is not implemented
  11  * at the moment).
  12  *  - => You can not use the ScopeBuilder two times on the same AST.
  13  *
  14  * @subsection symbols Symbols
  15  * What is a symbol ? A data structure which describe 3 things:
  16  * - the name of the symbol.
  17  * - the type of the symbol.
  18  * - the address of the symbol. An address can be:
  19  *  - a register address
  20  *  - a memory address. Usually it is scope's prefix + symbol's name.
  21  *
  22  * @subsection global_scope Global scope
  23  * This scope is the first scope. It has no parents.
  24  * Symbol addresses are prefixed with `@'.
  25  *
  26  * @subsection namespace_scope Namespace scope
  27  * This scope is the child of a global scope or a namespace scope.
  28  * Symbol addresses are prefixed with the parent prefix plus `.N'
  29  * plus the name of the namespace.
  30  *
  31  * @subsection structure_scope Structure, class and union scope
  32  * This scope is the child of a global scope or a namespace scope.
  33  * Symbol addresses are prefixed with the parent prefix plus `.S'
  34  * plus the name of the structure or class or union.
  35  *
  36  * @subsection function_scope Function scope
  37  * This scope is the child of a global scope or a namespace scope.
  38  * Symbol addresses are prefixed with `@%'.
  39  *
  40  * @subsection block_scope Block scope
  41  * This scope is the child of a block or function scope.
  42  * Symbol addresses are prefixed with parent prefix plus `.B'
  43  * plus the number of the scope (ie it's index in it's parent).
  44  *
  45  * @subsection strings Strings
  46  * When the scope builder meet a StringExp, it should create a internal
  47  * constant in a global scope and replace the string with a SymbolExp pointing
  48  * to the new constant. The type of the constant is [i8 x size].
  49  *
  50  * @subsection id_exp IdExp
  51  * Every IdExp should be resolved and replaced with the corresponding
  52  * SymbolExp.
  53  *
  54  * @subsection functions Functions
  55  * There is an exception for functions: because of overloading, functions
  56  * may have many entries for the same name in a scope. Their memory address
  57  * must be suffixed with their types. (TODO: allow the user to specify
  58  * something like extern "C". If we want to be able to call C functions...).
  59  * The user can do this:
  60  * @code
  61  * void myFunc(); // Weak symbol
  62  *
  63  * void myFunc() // Strong symbol
  64  * {
  65  * }
  66  * @endcode
  67  * And it should work fine. So it implies that you should be able to know if
  68  * a function symbol comes from a function prototype or a function
  69  * implementation.
  70  */