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  * @code
  25  * addr_prefix = "@";
  26  * @endcode
  27  *
  28  * @subsection namespace_scope Namespace scope
  29  * This scope is the child of a global scope or a namespace scope.
  30  * @code
  31  * addr_prefix = parent.prefix + ".N" + symbol.name + ".";
  32  * @endcode
  33  *
  34  * @subsection structure_scope Structure, class and union scope
  35  * This scope is the child of a global scope or a namespace scope.
  36  * @code
  37  * addr_prefix = parent.prefix + ".S" + symbol.name + ".";
  38  * @endcode
  39  *
  40  * @subsection function_scope Function scope
  41  * This scope is the child of a global scope or a namespace scope.
  42  * @code
  43  * addr_prefix = "%";
  44  * @endcode
  45  *
  46  * @subsection block_scope Block scope
  47  * This scope is the child of a block or function scope.
  48  * @code
  49  * addr_prefix = parent.prefix + ".B" + parent.index(this) + ".";
  50  * @endcode
  51  *
  52  * @subsection strings Strings
  53  * When the scope builder meet a StringExp, it should create a internal
  54  * constant in a global scope and replace the string with a SymbolExp pointing
  55  * to the new constant. The type of the constant is [i8 x size].
  56  *
  57  * @subsection id_exp IdExp
  58  * Every IdExp should be resolved and replaced with the corresponding
  59  * SymbolExp.
  60  *
  61  * @subsection function_args Function arguments
  62  * When you define:
  63  * @code
  64  * int32 my_func(int32 a)
  65  * {
  66  *   return 0;
  67  * }
  68  * @endcode
  69  *
  70  * It should be translated into:
  71  * @code
  72  * define i32 my_fun(i32 %.a)
  73  * {
  74  *   %a = alloca i32
  75  *   store i32 %.a, i32 * %a
  76  *   ret 0
  77  * }
  78  * @endcode
  79  *
  80  * @subsection functions Functions
  81  * <b>This spec is advanced for the moment, we don't suffix with the type
  82  * because we don't support function overloading yet.</b>
  83  * There is an exception for functions: because of overloading, functions
  84  * may have many entries for the same name in a scope. Their memory address
  85  * must be suffixed with their types. (TODO: allow the user to specify
  86  * something like extern "C". If we want to be able to call C functions...).
  87  * The user can do this:
  88  * @code
  89  * void myFunc(); // Weak symbol
  90  *
  91  * void myFunc() // Strong symbol
  92  * {
  93  * }
  94  * @endcode
  95  * And it should work fine. So it implies that you should be able to know if
  96  * a function symbol comes from a function prototype or a function
  97  * implementation.
  98  */