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

hlt.language.design.kernel

## Class Scope

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

- All Implemented Interfaces:
    Locatable
  Direct Known Subclasses:
    Abstraction

      public class Scope
      extends ProtoExpression

  This class represents a scope for local variables. It may be seen as a lambda abstraction that never needs to be lexically closed. It is used for creating a `Let` block as the application of such a `Scope` to its local variable's initial values. As a result, it can never be exported outside its enclosing scope, and therefore it can dispense with the whole machinery of creating and maintaining lexical frames. Also, a scope does not allow non-local exits.

  NB: This class is not meant to be put in unknowing hands: using it without being fully aware of its functionality may cause seriously wrong behavior - if you do not know for sure that this is what you want, then use `Abstraction` instead!

- - ### Field Summary

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

      `VOID_ASSIGNMENTS`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Scope(java.util.AbstractList parameters, Expression body)`
    `Scope(Expression body)`
    `Scope(Parameter[] parameters, Expression body)`
    `Scope(Parameter parameter, Expression body)`
    `Scope(java.lang.String name, Expression body)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `arity()`
    `Expression` | `body()`
    `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.
    `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.
    `int` | `intArity()`
    `int` | `numberOfSubexpressions()` Returns the number of subexpressions
    `int` | `objectArity()`
    `Parameter` | `parameter(int i)`
    `Parameter[]` | `parameters()` This is only to enable uniform visitors on expressions.
    `int` | `realArity()`
    `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.
    `void` | `setBody(Expression body)`
    `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.
    `void` | `setCheckedType(Type type)` NB: this is not `final` because itis overridden in `Abstraction` and `Global`.
    `void` | `setSortedArities()`
    `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`
    `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.
    `java.lang.String` | `toString()`
    `void` | `typeCheck(TypeChecker typeChecker)` This method type-checks this expression in the context of the specified `TypeChecker`.
    `Expression` | `typedCopy()` Returns a deep copy of this expression this and all its subexpressions share the same type as their copy's counterparts.
    `int` | `voidArity()`

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

      `checkedType, setType, type, typeRef`

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

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

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

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

- - ### Constructor Detail

    - #### Scope

          public Scope(Parameter[] parameters,
               Expression body)

    - #### Scope

          public Scope(Parameter parameter,
               Expression body)

    - #### Scope

          public Scope(java.lang.String name,
               Expression body)

    - #### Scope

          public Scope(Expression body)

    - #### Scope

          public Scope(java.util.AbstractList parameters,
               Expression body)

  - ### Method Detail

    - #### copy

          public 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 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`

    - #### arity

          public final int arity()

    - #### intArity

          public final int intArity()

    - #### realArity

          public final int realArity()

    - #### objectArity

          public final int objectArity()

    - #### voidArity

          public final int voidArity()

    - #### setSortedArities

          public final void setSortedArities()

    - #### 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`

    - #### parameters

          public final Parameter[] parameters()

      Description copied from class: `Expression`
      This is only to enable uniform visitors on expressions. It will return non-null only for scopes.
      Overrides:
        `parameters` in class `Expression`

    - #### parameter

          public final Parameter parameter(int i)

    - #### body

          public final Expression body()

    - #### setBody

          public final void setBody(Expression body)

    - #### setCheckedType

          public final void setCheckedType(Type type)

      Description copied from class: `ProtoExpression`
      NB: this is not `final` because itis overridden in `Abstraction` and `Global`.
      Overrides:
        `setCheckedType` in class `ProtoExpression`

    - #### 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`

    - #### typeCheck

          public void typeCheck(TypeChecker typeChecker)
                         throws TypingErrorException

      Description copied from class: `Expression`
      This method type-checks this expression in the context of the specified `TypeChecker`.
      Specified by:
        `typeCheck` in class `Expression`
      Throws:
        `TypingErrorException`

    - #### containsFreeName

          public final boolean containsFreeName(java.lang.String name)

      Description copied from class: `Expression`
      Returns `true` iff the specified name occurs free in this expression.
      Overrides:
        `containsFreeName` in class `Expression`

    - #### enclosingScope

          public final Expression enclosingScope()

      Description copied from class: `Expression`
      Returns this expression enclosing scope (if it has been computed by `linkScopeTree`); `null` otherwise.
      Overrides:
        `enclosingScope` in class `Expression`

    - #### substitute

          public Expression substitute(java.util.HashMap substitution)

      Description copied from class: `Expression`
      Returns the expression resulting from substituting all the free occurrences of the parameters's names as specified by the given substitution.
      Overrides:
        `substitute` in class `Expression`

    - #### sanitizeNames

          public final Expression sanitizeNames(ParameterStack parameters)

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

    - #### sanitizeSorts

          public 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 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`

    - #### 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 java.lang.String toString()

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