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

hlt.language.design.kernel

## Class Expression

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

- All Implemented Interfaces:
    Locatable
  Direct Known Subclasses:
    AndOr, Dummy, Local, Loop, ProtoExpression, Sequence

      public abstract class Expression
      extends java.lang.Object
      implements Locatable

  This class is the mother of all expressions in the kernel language. It specifies the prototypes of the methods that must be implemented by all expression subclasses. The subclasses of `Expression` are:

  - `Constant`: constant (void, boolean, `integer`, `real number`, `object`);

  - `Abstraction`: functional abstraction (à la lambda-calculus);

  - `Application`: functional application;

  - `Local`: local name;

  - `Global`: global name;

  - `IfThenElse`: conditional;

  - `AndOr`: non-strict boolean conjunction and disjunction;

  - `Sequence`: sequence of expressions (presumably with side-effects);

  - `Let`: lexical scoping construct;

  - `Loop`: conditional iteration construct;

  - `Definition`: definition of a global name with an expression defining it in a global store;

  - `Parameter`: a function's formal parameter (really a pseudo-expression as it is not fully processed as a real expression and is used as a shared type information repository for all occurrences in a function's body of the variable it stands for);

  - `Assignment`: construct to set the value of a `local` or a `global` variable;

  - `NewObject`: construct to create a new object;

  - `FieldUpdate`: construct to update the value of an object's field;

  - `NewArray`: construct to create a new (multidimensional) array;

  - `ArraySlot`: construct to access the element of an array;

  - `ArraySlotUpdate`: construct to update the element of an array;

  - `Tuple`: construct to create a new position-indexed tuple;

  - `NamedTuple`: construct to create a new name-indexed tuple;

  - `TupleProjection`: construct to access the component of a tuple;

  - `TupleUpdate`: construct to update the component of a tuple;

  - `Dummy`: temporary place holder in lieu of a name prior to being discriminated into a local or global one.
  Typically, upon being read, an `Expression` will be:

  1. "name-sanitized" - in the context of a `Sanitizer` to discriminate between local names and global names, and establish pointers from the local variable occurrences to the abstraction that introduces them, and from global names to entries in the global symbol table;

  2. type-checked - in the context of a `TypeChecker` to discover whether it has a type at all, or several possible ones (only expressions that have a unique unambiguous type are further processed);

  3. "sort-sanitized" - in the context of a `Sanitizer` to discriminate between those local variables that are of primitive Java types (`int` or `double`) or of `Object` type (this is necessary because the set-up means to use unboxed values for primitive types for efficiency reasons); this second "sanitization" phase is also used to compute offsets for local names (i.e., so-called de Bruijn indices) for each type sort;

  4. compiled - in the context of a `Compiler` to generate the sequence of instructions whose execution in an appropriate runtime environment will evaluate the expression;

  5. executed - in the context of a `Runtime` to execute its sequence of instructions.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `VOID_ASSIGNMENTS` When this is `true`, all assignments have a `void` type (and return no value); otherwise, they have the same type as the assigned value (which is also the value they return).

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Expression()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Expression` | `addType(Type newType)` This adds the specified type as another type for this expression.
    `Expression` | `addTypes(Expression expression)` Adds all the types prescribed for the specified expression to this one.
    `byte` | `boxSort()` This returns the runtime sort for this expression unless its type has been marked as boxed - in which case it returns `OBJECT_SORT`.
    `abstract Type` | `checkedType()` This method returns the final unambiguously checked type of this expression.
    `abstract void` | `compile(Compiler compiler)` This method compiles this expression in the context of the specified `Compiler`.
    `boolean` | `containsFreeName(java.lang.String name)` Returns `true` iff the specified name occurs free in this expression.
    `abstract Expression` | `copy()` Returns a deep copy of this expression.
    `Expression` | `enclosingScope()` Returns this expression enclosing scope (if it has been computed by `linkScopeTree`); `null` otherwise.
    `Locatable` | `extent()`
    `Location` | `getEnd()` Returns the end of this expressions's extent as a `Location`.
    `Location` | `getStart()` Returns the start of this expressions's extent as a `Location`.
    `boolean` | `isConstant()` Returns `true` iff this expression is a `Constant`.
    `boolean` | `isEquality(Tables tables)`
    `boolean` | `isFalse()` Returns `true` iff this expression denotes the constant `false`.
    `boolean` | `isHiddenSlicing(Tables tables, Parameter parameter)` Returns `true` iff this expression is a "hidden" slicing filter for the specified parameter; i.e., one that uses accessor projections rather than explicit tuple projections.
    `boolean` | `isNull()` Returns `true` iff this expression denotes the constant `null`.
    `boolean` | `isSelector(Tables tables, Parameter parameter)` Returns `true` iff this expression is a selector filter for the specified parameter.
    `boolean` | `isSlicing(Tables tables, Parameter parameter)` Returns `true` iff this expression is a slicing filter for the specified parameter.
    `boolean` | `isTrue()` Returns `true` iff this expression denotes the constant `true`.
    `boolean` | `isVoid()` Returns `true` iff this expression denotes the constant `void`.
    `java.lang.String` | `locationString()` Returns an explicit string for this expression's extent's location.
    `int` | `numberOfSubexpressions()` Returns the number of subexpressions
    `java.util.HashSet` | `otherTypes()`
    `Parameter[]` | `parameters()` This is only to enable uniform visitors on expressions.
    `Expression` | `sanitizeNames(ParameterStack parameters)` This method returns the actual expression corresponding to this one after eliminating all the `Dummy` expressions that occur in it where names where read.
    `void` | `sanitizeSorts(Enclosure enclosure)` This method walks down the expression gathering information relating each `Local` object to the `Scope` containing the corresponding `Parameter` in its array of formal parameters.
    `abstract void` | `setCheckedType()` This method sets the final unambiguously checked type of this expression, possibly along with other final information that may be needed by the compiler for generating code.
    `abstract void` | `setCheckedType(Type type)` This method sets the final unambiguously checked type of this expression to the specified type.
    `boolean` | `setCheckedTypeLocked()`
    `Locatable` | `setEnd(Location location)` Sets the end of this expressions's extent to the specified `Location` and returns this.
    `Expression` | `setExtent(Locatable extent)`
    `Expression` | `setOtherTypes(java.util.HashSet otherTypes)`
    `Locatable` | `setStart(Location location)` Sets the start of this expressions's extent to the specified `Location` and returns this.
    `Expression` | `setSubexpression(int n, Expression expression)` Returns this expression after setting its n-th subexpression to the specified expression; if there is no subexpression at the given position, this throws a `NoSuchSubexpressionException`
    `abstract void` | `setType(Type type)` This method forcibly sets this expression's type field, if it has one, to the specified type.
    `Expression` | `shiftOffsets(int intShift, int realShift, int objectShift)`
    `Expression` | `shiftOffsets(int intShift, int realShift, int objectShift, int intDepth, int realDepth, int objectDepth)` This methods visits this expression shifting the offset of all the `Local`s it encounters by the specified amount (per sort) as long as the offset it sees is referencing a parameter within the specified scope depth (per sort); This method is used when the compiler needs to synthesize an scope from an already typechecked expression (i.e., for currying or un/boxing - e.g., see the `pad` method below).
    `byte` | `sort()` Returns the sort of this expression's type after it has been checked.
    `Expression` | `subexpression(int n)` Returns the n-th subexpression of this expression; if there is no subexpression at the given position, this throws a `NoSuchSubexpressionException`
    `Expression` | `substitute(java.util.HashMap substitution)` Returns the expression resulting from substituting all the free occurrences of the parameters's names as specified by the given substitution.
    `abstract Type` | `type()` This method returns the current type of this expression.
    `void` | `typeCheck(Global filter, TypeChecker typeChecker)` This method type-checks this expression in the context of the specified typechecker, using the type of the specified `Global` as a filter.
    `abstract void` | `typeCheck(TypeChecker typeChecker)` This method type-checks this expression in the context of the specified `TypeChecker`.
    `void` | `typeCheck(Type type, TypeChecker typeChecker)` This method ascertains that this expression has the specified type in the context of the specified `TypeChecker`.
    `boolean` | `typeCheckLocked()`
    `abstract Expression` | `typedCopy()` Returns a deep copy of this expression this and all its subexpressions share the same type as their copy's counterparts.
    `abstract Type` | `typeRef()` This method returns this expression's undereferenced type field if it has one.

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

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

- - ### Field Detail

    - #### VOID_ASSIGNMENTS

          public static boolean VOID_ASSIGNMENTS

      When this is `true`, all assignments have a `void` type (and return no value); otherwise, they have the same type as the assigned value (which is also the value they return). This is useful for, e.g., overloading the equal sign '`=`' to mean something else besign assignment depending on the type. The kernel expressions that are assigments are:
      - `LocalAssignment```,
      - `GlobalAssignment```,
      - `ArraySlotUpdate```,
      - `FieldUpdate```,
      - `TupleUpdate```.
      Each of these will use this flag to alter they type-cehcking and compiling rules accordingly.

  - ### Constructor Detail

    - #### Expression

          public Expression()

  - ### Method Detail

    - #### copy

          public abstract Expression copy()

      Returns a deep copy of this expression. The types are not not copied. NB: This is a convenience for building expressions that should be used exclusively before any processing (in particular sanitizing), is done on this expression.

    - #### typedCopy

          public abstract Expression typedCopy()

      Returns a deep copy of this expression this and all its subexpressions share the same type as their copy's counterparts. NB: This is a convenience for building expressions that should be used exclusively before any processing (in particular sanitizing), is done on this expression.

    - #### typeCheckLocked

          public final boolean typeCheckLocked()

    - #### setCheckedTypeLocked

          public final boolean setCheckedTypeLocked()

    - #### isSlicing

          public boolean isSlicing(Tables tables,
                          Parameter parameter)

      Returns `true` iff this expression is a slicing filter for the specified parameter.

    - #### isHiddenSlicing

          public boolean isHiddenSlicing(Tables tables,
                                Parameter parameter)

      Returns `true` iff this expression is a "hidden" slicing filter for the specified parameter; i.e., one that uses accessor projections rather than explicit tuple projections.

    - #### isSelector

          public boolean isSelector(Tables tables,
                           Parameter parameter)

      Returns `true` iff this expression is a selector filter for the specified parameter.

    - #### isEquality

          public final boolean isEquality(Tables tables)
                                   throws UndefinedEqualityException

      Throws:
        `UndefinedEqualityException`

    - #### isConstant

          public final boolean isConstant()

      Returns `true` iff this expression is a `Constant`.

    - #### isVoid

          public final boolean isVoid()

      Returns `true` iff this expression denotes the constant `void`.

    - #### isTrue

          public boolean isTrue()

      Returns `true` iff this expression denotes the constant `true`.

    - #### isFalse

          public boolean isFalse()

      Returns `true` iff this expression denotes the constant `false`.

    - #### isNull

          public boolean isNull()

      Returns `true` iff this expression denotes the constant `null`.

    - #### type

          public abstract Type type()

      This method returns the current type of this expression. It will typically, but not necessarily, be the dereferenced value of a `TypeParameter` field. A notable exception is a `Local` since its type method will always return the type of the `Parameter` it stands for.

    - #### setType

          public abstract void setType(Type type)

      This method forcibly sets this expression's type field, if it has one, to the specified type. It will be an empty method otherwise.

    - #### typeRef

          public abstract Type typeRef()

      This method returns this expression's undereferenced type field if it has one. It will return `null` otherwise.

    - #### checkedType

          public abstract Type checkedType()

      This method returns the final unambiguously checked type of this expression.

    - #### setCheckedType

          public abstract void setCheckedType()

      This method sets the final unambiguously checked type of this expression, possibly along with other final information that may be needed by the compiler for generating code.

    - #### setCheckedType

          public abstract void setCheckedType(Type type)

      This method sets the final unambiguously checked type of this expression to the specified type. This is used when expression are synthesized on the fly after the type-checking phase and prior to the compiling phase.

    - #### substitute

          public Expression substitute(java.util.HashMap substitution)

      Returns the expression resulting from substituting all the free occurrences of the parameters's names as specified by the given substitution.

    - #### enclosingScope

          public Expression enclosingScope()

      Returns this expression enclosing scope (if it has been computed by `linkScopeTree`); `null` otherwise.

    - #### containsFreeName

          public boolean containsFreeName(java.lang.String name)

      Returns `true` iff the specified name occurs free in this expression.

    - #### sanitizeNames

          public Expression sanitizeNames(ParameterStack parameters)

      This method returns the actual expression corresponding to this one after eliminating all the `Dummy` expressions that occur in it where names where read. It takes as an argument the stack of parameters it encounters along the way of visiting all its components. A `ParameterStack` is simply a `Stack` of `Parameter` objects along with a method to retrieve the latest one with a given name.

    - #### sanitizeSorts

          public void sanitizeSorts(Enclosure enclosure)

      This method walks down the expression gathering information relating each `Local` object to the `Scope` containing the corresponding `Parameter` in its array of formal parameters. It takes as an argument an `Enclosure`, which is a `Stack` containing all `Scope`s encountered along the way, equipped with a method to compute all the information necessary in computing the local's offset.

    - #### shiftOffsets

          public Expression shiftOffsets(int intShift,
                                int realShift,
                                int objectShift,
                                int intDepth,
                                int realDepth,
                                int objectDepth)

      This methods visits this expression shifting the offset of all the `Local`s it encounters by the specified amount (per sort) as long as the offset it sees is referencing a parameter within the specified scope depth (per sort); This method is used when the compiler needs to synthesize an scope from an already typechecked expression (i.e., for currying or un/boxing - e.g., see the `pad` method below).

    - #### shiftOffsets

          public final Expression shiftOffsets(int intShift,
                                int realShift,
                                int objectShift)

    - #### typeCheck

          public abstract void typeCheck(TypeChecker typeChecker)
                                  throws TypingErrorException

      This method type-checks this expression in the context of the specified `TypeChecker`.
      Throws:
        `TypingErrorException`

    - #### typeCheck

          public void typeCheck(Type type,
                       TypeChecker typeChecker)
                         throws TypingErrorException

      This method ascertains that this expression has the specified type in the context of the specified `TypeChecker`. It amounts to first type-checking this expression in the type-checker, then making sure the type found for it by the type-checker agrees (i.e.unifies) with the specified type.
      Throws:
        `TypingErrorException`

    - #### typeCheck

          public final void typeCheck(Global filter,
                       TypeChecker typeChecker)
                               throws TypingErrorException

      This method type-checks this expression in the context of the specified typechecker, using the type of the specified `Global` as a filter.
      Throws:
        `TypingErrorException`

    - #### compile

          public abstract void compile(Compiler compiler)

      This method compiles this expression in the context of the specified `Compiler`.

    - #### numberOfSubexpressions

          public int numberOfSubexpressions()

      Returns the number of subexpressions

    - #### subexpression

          public Expression subexpression(int n)
                                   throws NoSuchSubexpressionException

      Returns the n-th subexpression of this expression; if there is no subexpression at the given position, this throws a `NoSuchSubexpressionException`
      Throws:
        `NoSuchSubexpressionException`

    - #### setSubexpression

          public Expression setSubexpression(int n,
                                    Expression expression)
                                      throws NoSuchSubexpressionException

      Returns this expression after setting its n-th subexpression to the specified expression; if there is no subexpression at the given position, this throws a `NoSuchSubexpressionException`
      Throws:
        `NoSuchSubexpressionException`

    - #### parameters

          public Parameter[] parameters()

      This is only to enable uniform visitors on expressions. It will return non-null only for scopes.

    - #### sort

          public final byte sort()

      Returns the sort of this expression's type after it has been checked. Sorts are of three kinds and defined as global constants in `Type`: `Type.INT_SORT`, `Type.REAL_SORT`, and `Type.OBJECT_SORT`.

    - #### boxSort

          public byte boxSort()

      This returns the runtime sort for this expression unless its type has been marked as boxed - in which case it returns `OBJECT_SORT`.

    - #### addType

          public final Expression addType(Type newType)

      This adds the specified type as another type for this expression. NB: This method must never be used on an expression, or with a type, that has been (even partially) type-checked. This is because, rather than making different type parameters separate types for this expression, it hard-binds them together or to the original type if there is one. It is meant to be used exclusively at expression construction time prior to type-checking anything.

    - #### otherTypes

          public final java.util.HashSet otherTypes()

    - #### setOtherTypes

          public final Expression setOtherTypes(java.util.HashSet otherTypes)

    - #### addTypes

          public final Expression addTypes(Expression expression)

      Adds all the types prescribed for the specified expression to this one.

    - #### extent

          public final Locatable extent()

    - #### setExtent

          public final Expression setExtent(Locatable extent)

    - #### getStart

          public final Location getStart()

      Returns the start of this expressions's extent as a `Location`.
      Specified by:
        `getStart` in interface `Locatable`

    - #### getEnd

          public final Location getEnd()

      Returns the end of this expressions's extent as a `Location`.
      Specified by:
        `getEnd` in interface `Locatable`

    - #### setStart

          public final Locatable setStart(Location location)

      Sets the start of this expressions's extent to the specified `Location` and returns this.
      Specified by:
        `setStart` in interface `Locatable`

    - #### setEnd

          public final Locatable setEnd(Location location)

      Sets the end of this expressions's extent to the specified `Location` and returns this.
      Specified by:
        `setEnd` in interface `Locatable`

    - #### locationString

          public final java.lang.String locationString()

      Returns an explicit string for this expression's extent's location.
      Specified by:
        `locationString` in interface `Locatable`