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

hlt.language.design.kernel

## Class Comprehension

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

- All Implemented Interfaces:
    Locatable

      public class Comprehension
      extends ProtoExpression

  This class represents a monoid comprehension whose actual form is interpreted as a construct involving the parts of the syntactic form of the comprehension. The syntax of a monoid comprehension is given by an expression of the form:

       [op,id] { e | q1, ..., qn }

  where `[op,id]` define a monoid, `e` is an expression, and the `qi`s are qualifiers. A qualifier is either a boolean expression or a pair `p <- e`, where `p` is a pattern (any expression) and `e` is an expression. The sequence of qualifiers may also be empty. Such a monoid comprehension is syntactic sugar that is in fact translated into a combination of homomorphisms and/or filtering tests, possibly wrapped inside a let factoring out some computation.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Comprehension.IndexedExpression`
    `class` | `Comprehension.Qualifier`
    `class` | `Comprehension.RawInfo`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `boolean` | `_doLetWrapping`
    `static boolean` | `OPAQUE_PARAMETERS`

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

      `VOID_ASSIGNMENTS`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Comprehension(java.util.AbstractList parameters, java.util.AbstractList values, Expression body)` Constructs an already translated comprehension as a let.
    `Comprehension(Tables tables, Expression operation, Expression identity, Expression expression, java.util.AbstractList patterns, java.util.AbstractList expressions)` Constructs a raw comprehension with the specifed arguments and assuming the default in-place mode for performing the monoid operation.
    `Comprehension(Tables tables, Expression operation, Expression identity, Expression expression, java.util.AbstractList patterns, java.util.AbstractList expressions, byte inPlace)` Constructs a raw comprehension with the specifed arguments.

  - ### 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` | `identity()`
    `int` | `numberOfSubexpressions()` Returns the number of subexpressions
    `Expression` | `operation()`
    `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` | `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.
    `Comprehension` | `setNoLetWrapping()`
    `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` | `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 comprehension obtained after applying the specified substitution to the subexpressions of this.
    `Tables` | `tables()`
    `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.

    - ### 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, setCheckedTypeLocked, setEnd, setExtent, setOtherTypes, setStart, shiftOffsets, shiftOffsets, sort, typeCheck, typeCheck, typeCheckLocked`

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

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

- - ### Field Detail

    - #### OPAQUE_PARAMETERS

          public static boolean OPAQUE_PARAMETERS

    - #### _doLetWrapping

          public boolean _doLetWrapping

  - ### Constructor Detail

    - #### Comprehension

          public Comprehension(java.util.AbstractList parameters,
                       java.util.AbstractList values,
                       Expression body)

      Constructs an already translated comprehension as a let. This is provided as a public constructor but should be used with care as it trusts that the specified arguments are correctly set up.

    - #### Comprehension

          public Comprehension(Tables tables,
                       Expression operation,
                       Expression identity,
                       Expression expression,
                       java.util.AbstractList patterns,
                       java.util.AbstractList expressions)

      Constructs a raw comprehension with the specifed arguments and assuming the default in-place mode for performing the monoid operation.

    - #### Comprehension

          public Comprehension(Tables tables,
                       Expression operation,
                       Expression identity,
                       Expression expression,
                       java.util.AbstractList patterns,
                       java.util.AbstractList expressions,
                       byte inPlace)

      Constructs a raw comprehension with the specifed arguments. A comprehension is raw as long as it has not been translated into a meaningful expression. Translation will happen automatically as soon as the meaning expresssion is needed.

  - ### Method Detail

    - #### setNoLetWrapping

          public final Comprehension setNoLetWrapping()

    - #### tables

          public final Tables tables()

    - #### operation

          public final Expression operation()

    - #### identity

          public final Expression identity()

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

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

    - #### substitute

          public Expression substitute(java.util.HashMap substitution)

      Returns the comprehension obtained after applying the specified substitution to the subexpressions of this. If this comprehension is already translated, this simply amounts to setting the construct to the substituted construct. If this is a raw comprehension, care must be taken to proceed from left to right over the qualifiers and preventing generator variables from being substituted inside expressions to their right (including the main expression of the comprehension).
      Overrides:
        `substitute` in class `Expression`

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

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