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

hlt.language.design.kernel

## Class UndecidedExpression

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

- All Implemented Interfaces:
    Locatable

      public class UndecidedExpression
      extends ProtoExpression

  This class denotes an expression as a yet undecided choice between two expressions. It is used for an expression that may be either of two options depending of their types when their respective types can be determined only from the syntactic nature of these expressions. Therefore, this construct is only safe to use on two expressions that may not be simultaneously well-typed based on their internal structures (as opposed to the preceding typing context). The semantics of this construct is simply that of the first expression if it can be type-checked without backtracking to an earlier state; otherwise it is that of the second expression.

  If more than two options are to be considered, this expression may be nested within similar expressions. The typechecker maintains a stack of cut-point states to ensure that the correct typing context is recovered for each such undecided expression choice.

- - ### Field Summary

    - ### Fields inherited from class hlt.language.design.kernel.Expression

      `VOID_ASSIGNMENTS`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `UndecidedExpression(Expression first, Expression second)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `compile(Compiler compiler)` This method compiles this expression in the context of the specified `Compiler`.
    `Expression` | `copy()` Returns a deep copy of this expression.
    `Expression` | `getActualChoice()` Returns the selected option.
    `int` | `getActualChoiceIndicator()` Returns an indicator of the subexpression selected: 0 if this is the first option expression, 1 if this is the second option expression, -1 otherwise (no choice yet)
    `int` | `numberOfSubexpressions()` Returns the number of subexpressions
    `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.
    `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.
    `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`
    `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).
    `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`
    `java.lang.String` | `toString()`
    `void` | `typeCheck(TypeChecker typeChecker)` Type-checking an `UndecidedExpression` works as follows: a `TypingState` is pushed on the typechecker's cut-point stack in order to inhibit backtracking before this point; the first option expression is typechecked; if type-checking succeeds, the typechecker's cut-point stack is popped; if it fails: all the typechecker's goals trailed after the latest cut-point are thrown away; all the other typechecker's trails are unwound up to the points indicated by the latest cut-point; the cut-point stack is popped; the second option is typechecked as the actual expression.
    `Expression` | `typedCopy()` Returns a deep copy of this expression this and all its subexpressions share the same type as their copy's counterparts.

    - ### Methods inherited from class hlt.language.design.kernel.ProtoExpression

      `checkedType, setCheckedType, setType, type, typeRef`

    - ### Methods inherited from class hlt.language.design.kernel.Expression

      `addType, addTypes, boxSort, containsFreeName, enclosingScope, extent, getEnd, getStart, isConstant, isEquality, isFalse, isHiddenSlicing, isNull, isSelector, isSlicing, isTrue, isVoid, locationString, otherTypes, parameters, sanitizeNames, setCheckedTypeLocked, setEnd, setExtent, setOtherTypes, setStart, shiftOffsets, sort, substitute, typeCheck, typeCheck, typeCheckLocked`

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

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

- - ### Constructor Detail

    - #### UndecidedExpression

          public UndecidedExpression(Expression first,
                             Expression second)

  - ### Method Detail

    - #### copy

          public final Expression copy()

      Description copied from class: `Expression`
      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.
      Specified by:
        `copy` in class `Expression`

    - #### typedCopy

          public final Expression typedCopy()

      Description copied from class: `Expression`
      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.
      Specified by:
        `typedCopy` in class `Expression`

    - #### numberOfSubexpressions

          public final int numberOfSubexpressions()

      Description copied from class: `Expression`
      Returns the number of subexpressions
      Overrides:
        `numberOfSubexpressions` in class `Expression`

    - #### subexpression

          public final Expression subexpression(int n)
                                         throws NoSuchSubexpressionException

      Description copied from class: `Expression`
      Returns the n-th subexpression of this expression; if there is no subexpression at the given position, this throws a `NoSuchSubexpressionException`
      Overrides:
        `subexpression` in class `Expression`
      Throws:
        `NoSuchSubexpressionException`

    - #### setSubexpression

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

      Description copied from class: `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`
      Overrides:
        `setSubexpression` in class `Expression`
      Throws:
        `NoSuchSubexpressionException`

    - #### getActualChoiceIndicator

          public final int getActualChoiceIndicator()

      Returns an indicator of the subexpression selected:
      - 0 if this is the first option expression,
      - 1 if this is the second option expression,
      - -1 otherwise (no choice yet)

    - #### getActualChoice

          public final Expression getActualChoice()

      Returns the selected option.

    - #### setCheckedType

          public final void setCheckedType()

      Description copied from class: `Expression`
      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.
      Specified by:
        `setCheckedType` in class `Expression`

    - #### sanitizeSorts

          public final void sanitizeSorts(Enclosure enclosure)

      Description copied from class: `Expression`
      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.
      Overrides:
        `sanitizeSorts` in class `Expression`

    - #### shiftOffsets

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

      Description copied from class: `Expression`
      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).
      Overrides:
        `shiftOffsets` in class `Expression`

    - #### typeCheck

          public final void typeCheck(TypeChecker typeChecker)
                               throws TypingErrorException

      Type-checking an `UndecidedExpression` works as follows:
      1. a `TypingState` is pushed on the typechecker's cut-point stack in order to inhibit backtracking before this point;
      2. the first option expression is typechecked;
      3. if type-checking succeeds, the typechecker's cut-point stack is popped;
      4. if it fails:
         1. all the typechecker's goals trailed after the latest cut-point are thrown away;
         2. all the other typechecker's trails are unwound up to the points indicated by the latest cut-point;
         3. the cut-point stack is popped;
         4. the second option is typechecked as the actual expression.
      Note that if later bactracking comes back before this expression, only the previously selected option will be considered. This is fine for this construct's purpose since the decision to choose between the two options must depend only on the syntactic nature of the two expressions, and not the preceding typing context. Hence, a second pass of type-checking is bound to give the same choice.
      Specified by:
        `typeCheck` in class `Expression`
      Throws:
        `TypingErrorException`

    - #### compile

          public final void compile(Compiler compiler)

      Description copied from class: `Expression`
      This method compiles this expression in the context of the specified `Compiler`.
      Specified by:
        `compile` in class `Expression`

    - #### toString

          public final java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`