## net.sf.saxon.expr
Class ExpressionTool

    java.lang.Object
      net.sf.saxon.expr.ExpressionTool

    public class ExpressionTool

extends java.lang.Object

This class, ExpressionTool, contains a number of useful static methods for manipulating expressions. Most importantly, it provides the factory method make() for constructing a new expression

Field Summary
`static int` `CALL_EVALUATE_ITEM`
`static int` `EVALUATE_AND_MATERIALIZE_VARIABLE`
`static int` `EVALUATE_VARIABLE`
`static int` `ITERATE_AND_MATERIALIZE`
`static int` `LAZY_TAIL_EXPRESSION`
`static int` `MAKE_CLOSURE`
`static int` `MAKE_INDEXED_VARIABLE`
`static int` `MAKE_MEMO_CLOSURE`
`static int` `MAKE_SINGLETON_CLOSURE`
`static int` `NO_EVALUATION_NEEDED`
`static int` `PROCESS`
`static int` `RETURN_EMPTY_SEQUENCE`
`static int` `SHARED_APPEND_EXPRESSION`
`static int` `UNDECIDED`

Method Summary
`static int` `allocateSlots(Expression exp, int nextFree, SlotManager frame)` Allocate slot numbers to range variables
`static boolean` `callsFunction(Expression exp, StructuredQName qName)` Determine whether an expression contains a call on the function with a given fingerprint
`static void` `copyLocationInfo(Expression from, Expression to)` Copy location information (the line number and reference to the container) from one expression to another
`static boolean` `dependsOnVariable(Expression e, Binding[] bindingList)` Determine whether an expression depends on any one of a set of variables
`static ValueRepresentation` `eagerEvaluate(Expression exp, XPathContext context)` Evaluate an expression now; lazy evaluation is not permitted in this case
`static int` `eagerEvaluationMode(Expression exp)` Determine the method of evaluation to be used when lazy evaluation of an expression is preferred.
`static void` `ebvError(java.lang.String reason)` Report an error in computing the effective boolean value of an expression
`static boolean` `effectiveBooleanValue(SequenceIterator iterator)` Determine the effective boolean value of a sequence, given an iterator over the sequence
`static ValueRepresentation` `evaluate(Expression exp, int evaluationMode, XPathContext context, int ref)` Do lazy evaluation of an expression.
`static int` `expressionSize(Expression exp)` Get the size of an expression tree (the number of subexpressions it contains)
`static void` `gatherAllSubExpressions(Expression exp, java.util.HashSet set)` Gather the set of all the subexpressions of an expression (the transitive closure)
`static void` `gatherCalledFunctionNames(Expression e, java.util.List list)` Gather a list of the names of the user-defined functions which a given expression calls directly
`static void` `gatherCalledFunctions(Expression e, java.util.List list)` Gather a list of all the user-defined functions which a given expression calls directly
`static void` `gatherReferencedVariables(Expression e, java.util.List list)` Gather a list of all the variable bindings on which a given expression depends
`static void` `gatherVariableReferences(Expression exp, Binding binding, java.util.List list)` Get a list of all references to a particular variable within a subtree
`static int` `getReferenceCount(Expression exp, Binding binding, boolean inLoop)` Determine how often a variable is referenced.
`static java.lang.String` `indent(int level)` Construct indent string, for diagnostic output
`static boolean` `isAllowedInUpdatingContext(Expression exp)` Determine whether the expression is either an updating expression, or an expression that is permitted in a context where updating expressions are allowed
`static boolean` `isSubtreeExpression(Expression exp)` Determine whether an expression can be evaluated without reference to the part of the context document outside the subtree rooted at the context node.
`static boolean` `isVariableReplaceableByDot(Expression exp, Binding[] binding)` Determine whether it is possible to rearrange an expression so that all references to a given variable are replaced by a reference to ".".
`static ValueRepresentation` `lazyEvaluate(Expression exp, XPathContext context, int ref)` Do lazy evaluation of an expression.
`static int` `lazyEvaluationMode(Expression exp)` Determine the method of evaluation to be used when lazy evaluation of an expression is preferred.
`static Expression` `make(java.lang.String expression, StaticContext env, int start, int terminator, int lineNumber, boolean compileWithTracing)` Parse an expression.
`static int` `markTailFunctionCalls(Expression exp, StructuredQName qName, int arity)` Scan an expression to find and mark any recursive tail function calls
`static void` `rebindVariableReferences(Expression exp, Binding oldBinding, Binding newBinding)` Rebind all variable references to a binding
`static void` `resetPropertiesWithinSubtree(Expression exp)` Reset cached static properties within a subtree, meaning that they have to be recalulated next time they are required
`static Expression` `resolveCallsToCurrentFunction(Expression exp, Configuration config)` Resolve calls to the XSLT current() function within an expression
`static Expression` `unsorted(Optimizer opt, Expression exp, boolean retainAllNodes)` Remove unwanted sorting from an expression, at compile time
`static Expression` `unsortedIfHomogeneous(Optimizer opt, Expression exp)` Remove unwanted sorting from an expression, at compile time, if and only if it is known that the result of the expression will be homogeneous (all nodes, or all atomic values).

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### UNDECIDED

    public static final int UNDECIDED

See Also:
  Constant Field Values

### NO_EVALUATION_NEEDED

    public static final int NO_EVALUATION_NEEDED

See Also:
  Constant Field Values

### EVALUATE_VARIABLE

    public static final int EVALUATE_VARIABLE

See Also:
  Constant Field Values

### MAKE_CLOSURE

    public static final int MAKE_CLOSURE

See Also:
  Constant Field Values

### MAKE_MEMO_CLOSURE

    public static final int MAKE_MEMO_CLOSURE

See Also:
  Constant Field Values

### RETURN_EMPTY_SEQUENCE

    public static final int RETURN_EMPTY_SEQUENCE

See Also:
  Constant Field Values

### EVALUATE_AND_MATERIALIZE_VARIABLE

    public static final int EVALUATE_AND_MATERIALIZE_VARIABLE

See Also:
  Constant Field Values

### CALL_EVALUATE_ITEM

    public static final int CALL_EVALUATE_ITEM

See Also:
  Constant Field Values

### ITERATE_AND_MATERIALIZE

    public static final int ITERATE_AND_MATERIALIZE

See Also:
  Constant Field Values

### PROCESS

    public static final int PROCESS

See Also:
  Constant Field Values

### LAZY_TAIL_EXPRESSION

    public static final int LAZY_TAIL_EXPRESSION

See Also:
  Constant Field Values

### SHARED_APPEND_EXPRESSION

    public static final int SHARED_APPEND_EXPRESSION

See Also:
  Constant Field Values

### MAKE_INDEXED_VARIABLE

    public static final int MAKE_INDEXED_VARIABLE

See Also:
  Constant Field Values

### MAKE_SINGLETON_CLOSURE

    public static final int MAKE_SINGLETON_CLOSURE

See Also:
  Constant Field Values

Method Detail

### make

    public static Expression make(java.lang.String expression,
                                  StaticContext env,
                                  int start,
                                  int terminator,
                                  int lineNumber,
                                  boolean compileWithTracing)
                           throws XPathException

  Parse an expression. This performs the basic analysis of the expression against the grammar, it binds variable references and function calls to variable definitions and function definitions, and it performs context-independent expression rewriting for optimization purposes.

  Parameters:
    `expression` - The expression (as a character string)
    `env` - An object giving information about the compile-time context of the expression
    `start` - position of the first significant character in the expression
    `terminator` - The token that marks the end of this expression; typically Tokenizer.EOF, but may for example be a right curly brace
    `lineNumber` - the line number of the start of the expression
    `compileWithTracing` - true if diagnostic tracing during expression parsing is required
  Returns:
    an object of type Expression
  Throws:
    `XPathException` - if the expression contains a static error

### copyLocationInfo

    public static void copyLocationInfo(Expression from,
                                        Expression to)

  Copy location information (the line number and reference to the container) from one expression to another

  Parameters:
    `from` - the expression containing the location information
    `to` - the expression to which the information is to be copied

### unsorted

    public static Expression unsorted(Optimizer opt,
                                      Expression exp,
                                      boolean retainAllNodes)
                               throws XPathException

  Remove unwanted sorting from an expression, at compile time

  Parameters:
    `opt` - the expression optimizer
    `exp` - the expression to be optimized
    `retainAllNodes` - true if there is a need to retain exactly those nodes returned by exp even if there are duplicates; false if the caller doesn't mind whether duplicate nodes are retained or eliminated
  Returns:
    the expression after rewriting
  Throws:
    `XPathException`

### unsortedIfHomogeneous

    public static Expression unsortedIfHomogeneous(Optimizer opt,
                                                   Expression exp)
                                            throws XPathException

  Remove unwanted sorting from an expression, at compile time, if and only if it is known that the result of the expression will be homogeneous (all nodes, or all atomic values). This is done when we need the effective boolean value of a sequence: the EBV of a homogenous sequence does not depend on its order, but this is not true when atomic values and nodes are mixed: (N, AV) is true, but (AV, N) is an error.

  Parameters:
    `opt` - the expression optimizer
    `exp` - the expression to be optimized
  Returns:
    the expression after rewriting
  Throws:
    `XPathException`

### lazyEvaluationMode

    public static int lazyEvaluationMode(Expression exp)

  Determine the method of evaluation to be used when lazy evaluation of an expression is preferred. This method is called at compile time, after all optimizations have been done, to determine the preferred strategy for lazy evaluation, depending on the type of expression.

  Parameters:
    `exp` - the expression to be evaluated
  Returns:
    an integer constant identifying the evaluation mode

### eagerEvaluationMode

    public static int eagerEvaluationMode(Expression exp)

  Determine the method of evaluation to be used when lazy evaluation of an expression is preferred. This method is called at compile time, after all optimizations have been done, to determine the preferred strategy for lazy evaluation, depending on the type of expression.

  Parameters:
    `exp` - the expression to be evaluated
  Returns:
    an integer constant identifying the evaluation mode

### evaluate

    public static ValueRepresentation evaluate(Expression exp,
                                               int evaluationMode,
                                               XPathContext context,
                                               int ref)
                                        throws XPathException

  Do lazy evaluation of an expression. This will return a value, which may optionally be a SequenceIntent, which is a wrapper around an iterator over the value of the expression.

  Parameters:
    `exp` - the expression to be evaluated
    `evaluationMode` - the evaluation mode for this expression
    `context` - the run-time evaluation context for the expression. If the expression is not evaluated immediately, then parts of the context on which the expression depends need to be saved as part of the Closure
    `ref` - an indication of how the value will be used. The value 1 indicates that the value is only expected to be used once, so that there is no need to keep it in memory. A small value >1 indicates multiple references, so the value will be saved when first evaluated. The special value FILTERED indicates a reference within a loop of the form $x[predicate], indicating that the value should be saved in a way that permits indexing.
  Returns:
    a value: either the actual value obtained by evaluating the expression, or a Closure containing all the information needed to evaluate it later
  Throws:
    `XPathException` - if any error occurs in evaluating the expression

### lazyEvaluate

    public static ValueRepresentation lazyEvaluate(Expression exp,
                                                   XPathContext context,
                                                   int ref)
                                            throws XPathException

  Do lazy evaluation of an expression. This will return a value, which may optionally be a SequenceIntent, which is a wrapper around an iterator over the value of the expression.

  Parameters:
    `exp` - the expression to be evaluated
    `context` - the run-time evaluation context for the expression. If the expression is not evaluated immediately, then parts of the context on which the expression depends need to be saved as part of the Closure
    `ref` - an indication of how the value will be used. The value 1 indicates that the value is only expected to be used once, so that there is no need to keep it in memory. A small value >1 indicates multiple references, so the value will be saved when first evaluated. The special value FILTERED indicates a reference within a loop of the form $x[predicate], indicating that the value should be saved in a way that permits indexing.
  Returns:
    a value: either the actual value obtained by evaluating the expression, or a Closure containing all the information needed to evaluate it later
  Throws:
    `XPathException` - if any error occurs in evaluating the expression

### eagerEvaluate

    public static ValueRepresentation eagerEvaluate(Expression exp,
                                                    XPathContext context)
                                             throws XPathException

  Evaluate an expression now; lazy evaluation is not permitted in this case

  Parameters:
    `exp` - the expression to be evaluated
    `context` - the run-time evaluation context
  Returns:
    the result of evaluating the expression
  Throws:
    `XPathException` - if any dynamic error occurs evaluating the expression

### markTailFunctionCalls

    public static int markTailFunctionCalls(Expression exp,
                                            StructuredQName qName,
                                            int arity)

  Scan an expression to find and mark any recursive tail function calls

  Parameters:
    `exp` - the expression to be analyzed
    `qName` - the name of the containing function
    `arity` - the arity of the containing function
  Returns:
    0 if no tail call was found; 1 if a tail call to a different function was found; 2 if a tail call to the specified function was found. In this case the UserFunctionCall object representing the tail function call will also have been marked as a tail call.

### indent

    public static java.lang.String indent(int level)

  Construct indent string, for diagnostic output

  Parameters:
    `level` - the indentation level (the number of spaces to return)
  Returns:
    a string of "level*2" spaces

### allocateSlots

    public static int allocateSlots(Expression exp,
                                    int nextFree,
                                    SlotManager frame)

  Allocate slot numbers to range variables

  Parameters:
    `exp` - the expression whose range variables need to have slot numbers assigned
    `nextFree` - the next slot number that is available for allocation
    `frame` - a SlotManager object that is used to track the mapping of slot numbers to variable names for debugging purposes. May be null.
  Returns:
    the next unallocated slot number.

### effectiveBooleanValue

    public static boolean effectiveBooleanValue(SequenceIterator iterator)
                                         throws XPathException

  Determine the effective boolean value of a sequence, given an iterator over the sequence

  Parameters:
    `iterator` - An iterator over the sequence whose effective boolean value is required
  Returns:
    the effective boolean value
  Throws:
    `XPathException` - if a dynamic error occurs

### ebvError

    public static void ebvError(java.lang.String reason)
                         throws XPathException

  Report an error in computing the effective boolean value of an expression

  Parameters:
    `reason` - the nature of the error
  Throws:
    `XPathException`

### dependsOnVariable

    public static boolean dependsOnVariable(Expression e,
                                            Binding[] bindingList)

  Determine whether an expression depends on any one of a set of variables

  Parameters:
    `e` - the expression being tested
    `bindingList` - the set of variables being tested
  Returns:
    true if the expression depends on one of the given variables

### gatherReferencedVariables

    public static void gatherReferencedVariables(Expression e,
                                                 java.util.List list)

  Gather a list of all the variable bindings on which a given expression depends

  Parameters:
    `e` - the expression being tested
    `list` - a list to which the bindings are to be added. The items in this list must implement `Binding`

### callsFunction

    public static boolean callsFunction(Expression exp,
                                        StructuredQName qName)

  Determine whether an expression contains a call on the function with a given fingerprint

  Parameters:
    `exp` - The expression being tested
    `qName` - The name of the function
  Returns:
    true if the expression contains a call on the function

### gatherCalledFunctions

    public static void gatherCalledFunctions(Expression e,
                                             java.util.List list)

  Gather a list of all the user-defined functions which a given expression calls directly

  Parameters:
    `e` - the expression being tested
    `list` - a list of the functions that are called. The items in this list must be objects of class `UserFunction`

### gatherCalledFunctionNames

    public static void gatherCalledFunctionNames(Expression e,
                                                 java.util.List list)

  Gather a list of the names of the user-defined functions which a given expression calls directly

  Parameters:
    `e` - the expression being tested
    `list` - a list of the functions that are called. The items in this list are strings in the format "{uri}local/arity"

### resetPropertiesWithinSubtree

    public static void resetPropertiesWithinSubtree(Expression exp)

  Reset cached static properties within a subtree, meaning that they have to be recalulated next time they are required

  Parameters:
    `exp` - the root of the subtree within which static properties should be reset

### resolveCallsToCurrentFunction

    public static Expression resolveCallsToCurrentFunction(Expression exp,
                                                           Configuration config)
                                                    throws XPathException

  Resolve calls to the XSLT current() function within an expression

  Parameters:
    `exp` - the expression within which calls to current() should be resolved
    `config` - the Saxon configuration
  Returns:
    the expression after resolving calls to current()
  Throws:
    `XPathException`

### isVariableReplaceableByDot

    public static boolean isVariableReplaceableByDot(Expression exp,
                                                     Binding[] binding)

  Determine whether it is possible to rearrange an expression so that all references to a given variable are replaced by a reference to ".". This is true of there are no references to the variable within a filter predicate or on the rhs of a "/" operator.

  Parameters:
    `exp` - the expression in question
    `binding` - an array of bindings defining range variables; the method tests that there are no references to any of these variables within a predicate or on the rhs of "/"
  Returns:
    true if the variable reference can be replaced

### isSubtreeExpression

    public static boolean isSubtreeExpression(Expression exp)

  Determine whether an expression can be evaluated without reference to the part of the context document outside the subtree rooted at the context node.

  Parameters:
    `exp` - the expression in question
  Returns:
    true if the expression has no dependencies on the context node, or if the only dependencies on the context node are downward selections using the self, child, descendant, attribute, and namespace axes.

### gatherVariableReferences

    public static void gatherVariableReferences(Expression exp,
                                                Binding binding,
                                                java.util.List list)

  Get a list of all references to a particular variable within a subtree

  Parameters:
    `exp` - the expression at the root of the subtree
    `binding` - the variable binding whose references are sought
    `list` - a list to be populated with the references to this variable

### getReferenceCount

    public static int getReferenceCount(Expression exp,
                                        Binding binding,
                                        boolean inLoop)

  Determine how often a variable is referenced. This is the number of times it is referenced at run-time: so a reference in a loop counts as "many". This code currently handles local variables (Let expressions) and function parameters. It is not currently used for XSLT template parameters. It's not the end of the world if the answer is wrong (unless it's wrongly given as zero), but if wrongly returned as 1 then the variable will be repeatedly evaluated.

  Parameters:
    `exp` - the expression within which variable references are to be counted
    `binding` - identifies the variable of interest
    `inLoop` - true if the expression is within a loop, in which case a reference counts as many. This should be set to false on the initial call, it may be set to true on an internal recursive call
  Returns:
    the number of references. The interesting values are 0, 1, "many" (represented by any value >1), and the special value FILTERED, which indicates that there are multiple references and one or more of them is of the form $x[....] indicating that an index might be useful.

### gatherAllSubExpressions

    public static void gatherAllSubExpressions(Expression exp,
                                               java.util.HashSet set)

  Gather the set of all the subexpressions of an expression (the transitive closure)

  Parameters:
    `exp` - the parent expression
    `set` - the set to be populated; on return it will contain all the subexpressions. Beware that testing for membership of a set of expressions relies on the equals() comparison, which does not test identity.

### expressionSize

    public static int expressionSize(Expression exp)

  Get the size of an expression tree (the number of subexpressions it contains)

  Parameters:
    `exp` - the expression whose size is required
  Returns:
    the size of the expression tree, as the number of nodes

### rebindVariableReferences

    public static void rebindVariableReferences(Expression exp,
                                                Binding oldBinding,
                                                Binding newBinding)

  Rebind all variable references to a binding

  Parameters:
    `exp` - the expression whose contained variable references are to be rebound
    `oldBinding` - the old binding for the variable references
    `newBinding` - the new binding to which the variables should be rebound

### isAllowedInUpdatingContext

    public static boolean isAllowedInUpdatingContext(Expression exp)

  Determine whether the expression is either an updating expression, or an expression that is permitted in a context where updating expressions are allowed

  Parameters:
    `exp` - the expression under test
  Returns:
    true if the expression is an updating expression, or an empty sequence, or a call on error()

Copyright (c) Saxonica Limited. All rights reserved.