Compiler (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.language.design.kernel

## Class Compiler

- java.lang.Object
- - hlt.language.design.kernel.Compiler

-     public class Compiler
      extends java.lang.Object

  This is the class defining a compiler object. Such an object serves as the common compilation context shared by an `Expression` and the subexpressions comprising it. Each type of expression representing a syntactic construct of the kernel language defines a `compile(Compiler)` method that specifies the way the construct is to be compiled in the context of a given compiler. Such a compiler object consists of attributes and methods for generating straight-line code which consists of the sequence of `Instruction`s corresponding to a top-level expression and its subexpressions. Upon completion of the compilation of a top-level expression, a resulting code array is extracted from the sequence of instructions, which may then be executed in the context of a `Runtime` object, or, in the case of a `Definition`, be saved in the code array in the `Definition`'s `_codeEntry` field - a `DefinedEntry` object encapsulating its code entry point (which may then be used to access the defined symbol's code for execution).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `LCO_IS_EFFECTIVE` When this flag is set to `true`, last call optimization is made effective.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Compiler()` Creates and returns a new Compiler.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Instruction[]` | `code()` Returns the extracted code array of this compiler's latest complete compilation.
    `DefinedEntry` | `codeEntry()` When compiling a definition, this returns the `DefinedEntry` of the symbol being defined; `null` otherwise.
    `void` | `compile(Expression exp)` Compiles the specified expression in the context of this compiler.
    `Instruction` | `generate(Instruction inst)`
    `Instruction` | `generate(PushScope pushScope, Expression body)`
    `void` | `generateStackPop(byte sort)`
    `void` | `generateUnwrapper(byte sort)`
    `void` | `generateWrapper(byte sort)`
    `void` | `inline(Instruction[] code)`
    `boolean` | `isCompilingDefinition()` Return `true` iff this is compiling a definition.
    `boolean` | `isShowingCode()`
    `Instruction` | `lastInstruction()`
    `int` | `nextCodeAddress()` Returns the next available index in `_codeList` to use as the address of the next instruction.
    `void` | `setCodeEntry(DefinedEntry entry)` Sets the `_codeEntry` of this compiler to the specified `DefinedEntry`.
    `void` | `showCode()`
    `int` | `targetAddress()` Returns the next available index in `_codeList` marking as a target address.
    `void` | `toggleShowCode()`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### LCO_IS_EFFECTIVE

          public static boolean LCO_IS_EFFECTIVE

      When this flag is set to `true`, last call optimization is made effective.

  - ### Constructor Detail

    - #### Compiler

          public Compiler()

      Creates and returns a new Compiler.

  - ### Method Detail

    - #### code

          public final Instruction[] code()

      Returns the extracted code array of this compiler's latest complete compilation.

    - #### nextCodeAddress

          public final int nextCodeAddress()

      Returns the next available index in `_codeList` to use as the address of the next instruction.

    - #### targetAddress

          public final int targetAddress()

      Returns the next available index in `_codeList` marking as a target address.

    - #### setCodeEntry

          public final void setCodeEntry(DefinedEntry entry)

      Sets the `_codeEntry` of this compiler to the specified `DefinedEntry`. This is called by the `compile` method of a `Definition`.

    - #### codeEntry

          public final DefinedEntry codeEntry()

      When compiling a definition, this returns the `DefinedEntry` of the symbol being defined; `null` otherwise.

    - #### isCompilingDefinition

          public final boolean isCompilingDefinition()

      Return `true` iff this is compiling a definition.

    - #### compile

          public final void compile(Expression exp)

      Compiles the specified expression in the context of this compiler. This method is (must be, in fact) the topmost entry point when compiling a top-level (e.g., non-nested) expression as it unnests all inner scopes into straightline code (which is what the `_backpatch` method does) and manages code dependencies for incremental compiling of forward definitions (which is what the `releaseCodeEntry` method does).

    - #### lastInstruction

          public final Instruction lastInstruction()

    - #### toggleShowCode

          public final void toggleShowCode()

    - #### isShowingCode

          public final boolean isShowingCode()

    - #### showCode

          public final void showCode()

    - #### generate

          public final Instruction generate(Instruction inst)

    - #### generate

          public final Instruction generate(PushScope pushScope,
                             Expression body)

    - #### inline

          public final void inline(Instruction[] code)

    - #### generateStackPop

          public final void generateStackPop(byte sort)

    - #### generateWrapper

          public final void generateWrapper(byte sort)

    - #### generateUnwrapper

          public final void generateUnwrapper(byte sort)