Package ca.spatial.parser

Class Expression

java.lang.Object
ca.spatial.parser.Expression
All Implemented Interfaces:
Closeable, AutoCloseable
public class Expression extends Object implements Closeable
A general expression parser and evaluator. This class supports two different syntax styles. The first is the Patchworks Query Language syntax, containing basic math (+, -, *, /), comparison (>, <, =, <=, >=, ne), boolean (or, and, not) and a few C-style bit operators (|, &, <<, >>, >>>, ~, ^). Many functions are available for math, string and logical operations.

The second syntax style is similar to JSP, ASP, or PHP where the body of the expression is treated as literal string data (i.e. copied verbatim to the output, but escaped sections are interpreted and substituted by the standard PQL-style parser. The escape tags are <% %>.

The syntax specifiers are JSP_SYNTAX and PQL_SYNTAX.

Here are a few sample expression:

Sample expressions
ExpressionDescription
1integer value 1
1.5double precision value 1.5
'a'String value "a"
'a'+'b'String value "ab"
'a'+1String value "a1"
if(1 lt 10,'a','b')String value "a"
substring('abcde',0,1)String value "a"
Expression object also have access to the variables in the data set that the expression is compiled against, and these can be used in place of literal values in the above examples.

The language is described in an appendix of the User Guide. Please refer to this for more details.

  • Field Details

    • JSP_SYNTAX

      public static final int JSP_SYNTAX
      A constant that is used as a parameter to the constructor to indicate that the JSP-style syntax should be parsed out.
      See Also:
      Constant Field Values

    • PQL_SYNTAX

      public static final int PQL_SYNTAX
      A constant that is used as a parameter to the constructor to indicate that the PQL-style syntax should be parsed out.
      See Also:
      Constant Field Values

    • SQL_SYNTAX

      public static final int SQL_SYNTAX
      See Also:
      Constant Field Values

  • Constructor Details

    • Expression

      public Expression​(String expression, AttributeStore as) throws ParseException
      This constructor compiles the expression and prepares the parser for immediate evaluation. This constructor defaults to an PQL-like syntax.

      This constructor has the same meaning as 

       new Expression(expresson, as, PQL_SYNTAX)
      Parameters:
      expression - The expression to compile
      as - the AttributeStore to compile the expression against
      Throws:
      ParseException

    • Expression

      public Expression​(String expression, AttributeStore as, int syntax) throws ParseException
      This constructor compiles the expression and prepares the parser for immediate evaluation. This constructor requires that you specify a syntax.
      Parameters:
      expression - The expression to compile
      as - the AttributeStore to compile the expression against
      syntax - the sytax to be used in this expression (one of PQL_SYNTAX or JSP_SYNTAX)
      Throws:
      ParseException

    • Expression

      public Expression​(String expression, GridAnalysis ga) throws ParseException
      This constructor compiles a grid expression and prepares the parser for immediate evaluation.
      Parameters:
      expression - The expression to compile
      ga - the GridAnalysis context for the expression
      Throws:
      ParseException

  • Method Details

    • getAttributeStore

      public AttributeStore getAttributeStore()

    • getSyntax

      public int getSyntax()
      Return the syntax used to define this expression. Valid values are JSP_SYNTAX or PQL_SYNTAX.
      Returns:
      JSP_SYNTAX or PQL_SYNTAX

    • getRoot

      public ca.spatial.parser.ExpressionNode getRoot()
      Return the root of the abstract syntax tree for this expression

    • isLiteral

      public boolean isLiteral()
      Tests if the value is invariant across rows and periods. A literal expression can be reduced to a constant at compile time.
      Returns:
      true if the expression is invariant

    • isDynamic

      public boolean isDynamic()
      Tests if the value can potentially vary across periods. A dynamic expression depends on dynamic database variables or uses the offset() function.

      Database variables that do not change by period are not dynamic.

      Returns:
      true if the expression is dynamic

    • isOperable

      public boolean isOperable()
      Test if the expression requires operability info
      Returns:
      true if the expression requires operability info

    • hasSelectionContext

      public boolean hasSelectionContext()
      Test if the expression uses a selection context
      Returns:
      true if the expression uses a selection context

    • resetSelectionContext

      public void resetSelectionContext()
      Discard context information for this expression

    • setUserData

      public void setUserData​(Object userData)
      Add user specified data

    • getUserData

      public Object getUserData()
      Retrieve user specified data

    • ignoreMissing

      public void ignoreMissing​(boolean state)
      Specify that during evaluation that missing attribute references are ignored and replaced by default values.
      Parameters:
      state - true to ignore missing

    • setCacheSize

      public static void setCacheSize​(int size)
      Set the raster calculator grid-block LRU cache size

    • getCacheSize

      public static int getCacheSize()
      Get the raster calculator grid-block LRU cache size

    • accept

      public void accept​(ca.spatial.parser.NodeVisitor visitor)
      Invoke methods to walk the parse tree with the NodeVisitor object
      Parameters:
      visitor - the visitor object

    • getType

      public Class getType()
      Return the object class of the result of the expression.
      Returns:
      a class value that will be returned by the evaluation of the expression

    • getAttributeType

      public int getAttributeType()
      Return the type of the result of expression. Types are defined as constants in AttributeFormat.
      Returns:
      the type of the expression

    • getDefaultFormat

      public AttributeFormat getDefaultFormat​(String name)

    • getDependingColumns

      public int[] getDependingColumns()
      Return the indices in the base table of the columns that this expression depends on

    • resolveForRow

      public Expression resolveForRow​(int row)
      Resolve this expression by substituting database variables with literals values for the current row of the expression. This will optimize for curve and operability expressions.
      Parameters:
      row - the row to resolve
      Returns:
      a new Expression object with database references resolved for this row

    • resolve

      public void resolve()
      Resolve this expression by folding literals.

    • resolveAndNormalize

      public void resolveAndNormalize()
      Resolve this expression by folding literals and update the input

    • evaluate

      public Object evaluate​(int row) throws SemanticException
      Evaluate the expression for a specific row and the default period of the attribute store.
      Parameters:
      row - the row to evaluate
      Returns:
      the result of the evaluation
      Throws:
      SemanticException - if the expression reveals an incorrect mix of data types during evaluation

    • evaluate

      public Object evaluate​(int row, int period) throws SemanticException
      Evaluate the expression for a specific row and period.
      Parameters:
      row - the row to evaluate
      period - the period to evaluate
      Returns:
      the result of the evaluation
      Throws:
      SemanticException - if the expression reveals an incorrect mix of data types during evaluation

    • evaluate

      public Object evaluate​(int row, int col, int period) throws SemanticException
      Evaluate the expression for a specific row and period.
      Parameters:
      row - the row to evaluate
      period - the period to evaluate
      Returns:
      the result of the evaluation
      Throws:
      SemanticException - if the expression reveals an incorrect mix of data types during evaluation

    • evaluateAtOffset

      public Object evaluateAtOffset​(int row, float offset) throws SemanticException
      Evaluate the expression for a specific row and offset (for curves).
      Parameters:
      row - the row to evaluate
      offset - the year to evaluate
      Returns:
      the result of the evaluation
      Throws:
      SemanticException - if the expression reveals an incorrect mix of data types during evaluation

    • setCurveMaps

      public void setCurveMaps​(AttributeResolver attributes, HashMap<String,​AttributeDef> attributeRefs, CurveMatchCache curveRefs, double future, boolean isSeries, Track track, String ftag, String mtag)
      This method is used by the Matrix Builder and passes in HashMap structures that contain references to Attributes and Curves. These references are used in the Attributeid and Curveid functions to retrive curve values.
      Parameters:
      attributes - a database of current attributes
      attributeRefs - a database of defined attributes
      curveRefs - a database of defined curves
      future - the future value for this attribute
      isSeries - is this attribute a series?
      track - the current track that the Matrix Builder is processing
      ftag - the current feature tag
      mtag - the current management status tag

    • setParameters

      public Expression setParameters​(Map<String,​Object> params)
      Set a map containing parameters. These can be retrieved by expressions at run time.
      Parameters:
      params - the map of parameters
      Returns:
      the current expression (this)

    • getParameter

      public Object getParameter​(String key)
      Get a parameter by key value. The parameters may come from a user provided map (see setParameters(java.util.Map<java.lang.String, java.lang.Object>)). If the key is prefixed with "script." then value is obtained from the global interpreter namespace (see IProperties.getGlobal(java.lang.String)). If the key is prefixed with "repeat." then value is obtained from the repeat block namespace. If the key is prefixed with "env." then value is obtained from the operating system environment variables. If the key is prefixed with "report." then value is obtained from the map of parameters that are passed in from the containing report.
      Parameters:
      key - the prefix and key used to look up the variable.
      Returns:
      the value of the named parameter

    • setRepeatVariable

      public static void setRepeatVariable​(String key, Object val, Class type)
      Set a value in the repeat variable namespace

    • getRepeatVariable

      public static ca.spatial.parser.Expression.RepeatType getRepeatVariable​(String key)
      Get a value in the repeat variable namespace

    • removeRepeatVariable

      public static Object removeRepeatVariable​(String key)
      Remove a value in the repeat variable namespace

    • removeRepeatVariables

      public static void removeRepeatVariables​(String key)
      Remove a value in the repeat variable namespace

    • setTableData

      public static void setTableData​(String name, AttributeStore as)

    • getTableData

      public static AttributeStore getTableData​(String name)

    • getTableData

      public static HashMap<String,​AttributeStore> getTableData()

    • removeTableData

      public static AttributeStore removeTableData​(String name)

    • getInput

      public String getInput()
      Return the original expression string that was used to construct this object.
      Returns:
      the original expression in string format

    • getNormalizedInput

      public String getNormalizedInput()
      Return the normalized version an the expression that will recrete this expression.
      Returns:
      the expression in normalized string format

    • getTokenType

      public static ParsedToken getTokenType​(String token)
      Return a ParsedToken object that describes the type of the passed in expression. The ParsedToken object contains a field named 'kind' that describes the value type (INTEGER, STRING, NUMBER, BOOLEAN, etc).
      Parameters:
      token - the token to evaluate
      Returns:
      the type of the token

    • getStore

      public AttributeStore getStore()
      Return a reference to the AttributeStore that this expression will be compiled and run against.
      Returns:
      a reference to the base AttributeStore

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • tempName

      public static File tempName​(String prefix)

    • getGridType

      public static ca.spatial.gis.raster.grid.GridFile.DataType getGridType​(Class clz)

    • getGridType

      public ca.spatial.gis.raster.grid.GridFile.DataType getGridType()

    • save

      public void save​(String outName, boolean permanent, int period)
      Save a grid for a given period
      Parameters:
      outName - the name that the grid will saved as
      permanent - indicate if a temporary file or not
      period - the period that the expressions will be evaluated in

    • save

      public void save​(String outName, boolean permanent)
      Save a grid. Expressions will be evauated in the default period
      Parameters:
      outName - the name that the grid will saved as
      permanent - indicate if a temporary file or not

    • close

      public void close()
      Close the expression and release resources
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable