ExpressionTool

java.lang.Object
- net.sf.saxon.expr.parser.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

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`ExpressionTool.ExpressionPredicate`
`static interface`	`ExpressionTool.ExpressionSelector` Callback for selecting expressions in the tree

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CALL_EVALUATE_ITEM`
`static int`	`EVALUATE_AND_MATERIALIZE_VARIABLE`
`static int`	`EVALUATE_SUPPLIED_PARAMETER`
`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`	`STREAMING_ARGUMENT`
`static int`	`UNDECIDED`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static int`	`allocateSlots(Expression exp, int nextFree, SlotManager frame)` Allocate slot numbers to range variables
`static boolean`	`callsFunction(Expression exp, StructuredQName qName, boolean sameFocusOnly)` Determine whether an expression contains a call on the function with a given name
`static boolean`	`changesXsltContext(Expression exp)` Determine whether an expression possible calls (directly or indirectly) xsl:result-document, or has other context dependencies that prevent function inlining, which we assume is true if it contains a template call.
`static void`	`clearStreamabilityData(Expression exp)` Clear all computed streamability properties for an expression and its contained subtree
`static void`	`computeEvaluationModesForUserFunctionCalls(Expression exp)` Compute argument evaluation modes for all calls on user defined functions with a specified expression
`static boolean`	`contains(Expression exp, boolean sameFocusOnly, ExpressionTool.ExpressionPredicate predicate)` Test whether a given expression is, or contains, at any depth, an expression that satisfies a supplied condition
`static boolean`	`contains(Expression a, Expression b)` Ask whether one expression is a subexpression of another
`static boolean`	`containsLocalParam(Expression exp)` Determine whether an expression contains a LocalParamSetter subexpression
`static boolean`	`containsLocalVariableReference(Expression exp)` Determine whether an expression contains a local variable reference, other than a reference to a local variable whose binding occurs within this expression
`static boolean`	`containsSubexpression(Expression exp, java.lang.Class<? extends Expression> subClass)` Determine whether an expression has a subexpression of a given implementation class
`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`	`dependsOnFocus(Expression exp)` Ask whether an expression has a dependency on the focus
`static boolean`	`dependsOnVariable(Expression exp, Binding[] bindingList)` Determine whether an expression depends on any one of a set of variables
`static Sequence`	`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(Item item)` Determine the effective boolean value of a single item
`static boolean`	`effectiveBooleanValue(SequenceIterator iterator)` Determine the effective boolean value of a sequence, given an iterator over the sequence
`static boolean`	`equalOrNull(java.lang.Object x, java.lang.Object y)` Return true if two objects are equal or if both are null
`static Sequence`	`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 boolean`	`factorOutDot(Expression exp, Binding variable)` Replace references to the context item with references to a variable
`static Operand`	`findOperand(Expression parentExpression, Expression childExpression)` Find the operand corresponding to a particular child expression
`static void`	`gatherCalledFunctionNames(Expression e, java.util.List<SymbolicName> 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<UserFunction> list)` Gather a list of all the user-defined functions which a given expression calls directly
`static void`	`gatherReferencedVariables(Expression e, java.util.List<Binding> 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<VariableReference> list)` Get a list of all references to a particular variable within a subtree
`static java.net.URI`	`getBaseURI(StaticContext env, javax.xml.transform.SourceLocator locator, boolean fail)` Determine the base URI of an expression, so that it can be saved on the expression tree for use when the expression is evaluated
`static Expression`	`getContextDocumentSettingContainer(Expression exp)` Get the context-document-setting container of an expression.
`static java.lang.String`	`getCurrentDirectory()`
`static Expression`	`getFocusSettingContainer(Expression exp)` Get the focus-setting container of an expression *
`static Item`	`getItemFromProcessMethod(Expression exp, XPathContext context)` Helper method to construct an item representing the results of the expression when all that the expression itself offers is a process() method.
`static SequenceIterator`	`getIteratorFromProcessMethod(Expression exp, XPathContext context)` Helper method to construct an iterator over the results of the expression when all that the expression itself offers is a process() method.
`static int`	`getReferenceCount(Expression exp, Binding binding, boolean inLoop)` Determine how often a variable is referenced.
`static boolean`	`hasLoopingSubexpression(Expression parent, Expression child)`
`static java.lang.String`	`indent(int level)` Construct indent string, for diagnostic output
`static boolean`	`inlineVariableReferences(Expression expr, Binding binding, Expression replacement)` Inline variable references.
`static boolean`	`inlineVariableReferencesInternal(Expression expr, Binding binding, Expression replacement)`
`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`	`isLocalConstructor(Expression child)` Ask whether a supplied expression is a nested node constructor.
`static boolean`	`isLoopingReference(VariableReference reference, Binding binding)`
`static boolean`	`isLoopingSubexpression(Expression child, Expression ancestor)` Return true if a given expression is evaluated repeatedly when a given ancestor expression is evaluated once
`static Sequence`	`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, CodeInjector codeInjector)` Parse an XPath expression.
`static Expression`	`makePathExpression(Expression start, Expression step, boolean sortAndDeduplicate)` Make a mapping expression.
`static Expression`	`makeRawPathExpression(Expression start, Expression step, boolean sortAndDeduplicate)`
`static int`	`markTailFunctionCalls(Expression exp, StructuredQName qName, int arity)` Scan an expression to find and mark any recursive tail function calls
`static Expression`	`optimizeComponentBody(Expression body, Compilation compilation, ExpressionVisitor visitor, ContextItemStaticInfo cit, boolean extractGlobals)` Optimize the implementation of a component such as a function, template, or global variable
`static java.lang.String`	`parenthesize(Expression exp)` Display an expression adding parentheses if it is possible they are necessary because the expression has sub-expressions
`static java.lang.String`	`parenthesizeShort(Expression exp)`
`static boolean`	`processExpressionTree(Expression root, java.lang.Object result, ExpressionAction action)` Process every node on a subtree of the expression tree using a supplied action.
`static void`	`rebindVariableReferences(Expression exp, Binding oldBinding, Binding newBinding)` Rebind all variable references to a binding
`static boolean`	`refersToVariableOrFunction(Expression exp)` Determine whether the expression contains any variable references or calls to user-written functions
`static boolean`	`replaceCallsToCurrent(Expression expr, LocalBinding binding)` Replace calls to current() by a variable reference.
`static boolean`	`replaceSelectedSubexpressions(Expression exp, ExpressionTool.ExpressionSelector selector, Expression replacement, boolean mustCopy)` Replace all selected subexpressions within a subtree
`static boolean`	`replaceTrivialCallsToCurrent(Expression expr)` Replace trivial calls to current() by a context item expression (`.`).
`static void`	`replaceVariableReferences(Expression exp, Binding binding, Expression replacement, boolean mustCopy)` Replace all references to a particular variable within a subtree
`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 void`	`resetStaticProperties(Expression exp)` Reset the static properties for the current expression and for all its containing expressions.
`static Expression`	`resolveCallsToCurrentFunction(Expression exp)` Resolve calls to the XSLT current() function within an expression
`static void`	`setDeepRetainedStaticContext(Expression exp, RetainedStaticContext rsc)` Ensure that every node in the expression tree has a retained static context.
`static Expression`	`tryToFactorOutDot(Expression exp, ItemType contextItemType)` Try to factor out dependencies on the context item, by rewriting an expression f(.) as let $dot := .
`static Expression`	`unfilteredExpression(Expression exp, boolean allowPositional)` Get the expression that remains after removing any filter predicates
`static Expression`	`unsortedIfHomogeneous(Expression exp, boolean forStreaming)` 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).
`static void`	`validateTree(Expression exp)`

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
  - EVALUATE_SUPPLIED_PARAMETER
```
public static final int EVALUATE_SUPPLIED_PARAMETER
```
    See Also:
    
    Constant Field Values
  - STREAMING_ARGUMENT
```
public static final int STREAMING_ARGUMENT
```
    See Also:
    
    Constant Field Values
- Method Detail
  - make
```
public static Expression make(java.lang.String expression,
                              StaticContext env,
                              int start,
                              int terminator,
                              CodeInjector codeInjector)
                       throws XPathException
```
    Parse an XPath 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 Token.EOF, but may for example be a right curly brace
    
    codeInjector - true allows injection of tracing, debugging, or performance monitoring code; null if not required
    
    Returns:
    
    an object of type Expression
    
    Throws:
    
    XPathException - if the expression contains a static error
  - setDeepRetainedStaticContext
```
public static void setDeepRetainedStaticContext(Expression exp,
                                                RetainedStaticContext rsc)
```
    Ensure that every node in the expression tree has a retained static context. A node that already has a retained static context will propagate it to its children.
    
    Parameters:
    
    exp - the root of the expression tree
    
    rsc - the retained static context to be applied to nodes that do not already have one, and that do not have an ancestor with an existing retained static context.
  - 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
  - unsortedIfHomogeneous
```
public static Expression unsortedIfHomogeneous(Expression exp,
                                               boolean forStreaming)
                                        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:
    
    exp - the expression to be optimized
    
    forStreaming - true if streamed evaluation of the expression is required
    
    Returns:
    
    the expression after rewriting
    
    Throws:
    
    XPathException - if a static error is found while doing the rewrite
  - 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 Sequence 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 Sequence 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 Sequence 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
  - contains
```
public static boolean contains(Expression a,
                               Expression b)
```
    Ask whether one expression is a subexpression of another
    
    Parameters:
    
    a - the containing expression
    
    b - the putative contained expression
    
    Returns:
    
    true if and only if b is a subexpression (at some level) of a
  - containsLocalParam
```
public static boolean containsLocalParam(Expression exp)
```
    Determine whether an expression contains a LocalParamSetter subexpression
    
    Parameters:
    
    exp - the expression to be tested
    
    Returns:
    
    true if the exprssion contains a local parameter setter
  - containsLocalVariableReference
```
public static boolean containsLocalVariableReference(Expression exp)
```
    Determine whether an expression contains a local variable reference, other than a reference to a local variable whose binding occurs within this expression
    
    Parameters:
    
    exp - the expression to be tested
    
    Returns:
    
    true if the expression contains a local variable reference to a local variable declared outside this expression.
  - contains
```
public static boolean contains(Expression exp,
                               boolean sameFocusOnly,
                               ExpressionTool.ExpressionPredicate predicate)
```
    Test whether a given expression is, or contains, at any depth, an expression that satisfies a supplied condition
    
    Parameters:
    
    exp - the given expression
    
    sameFocusOnly - if true, only subexpressions evaluated in the same focus are searched. If false, all subexpressions are searched
    
    predicate - the condition to be satisfied
    
    Returns:
    
    true if the given expression is or contains an expression that satisfies the condition.
  - changesXsltContext
```
public static boolean changesXsltContext(Expression exp)
```
    Determine whether an expression possible calls (directly or indirectly) xsl:result-document, or has other context dependencies that prevent function inlining, which we assume is true if it contains a template call. A call on result-document disqualifies the function from being inlined, because error XTDE1480 would then not be detected. We don't have to worry about functions containing further function calls because they are disqualified from inlining anyway.
    
    Parameters:
    
    exp - the expression to be tested
    
    Returns:
    
    true if there is any possibility that calling the function might result in a call on xsl:result-document
  - isLoopingSubexpression
```
public static boolean isLoopingSubexpression(Expression child,
                                             Expression ancestor)
```
    Return true if a given expression is evaluated repeatedly when a given ancestor expression is evaluated once
    
    Parameters:
    
    child - the expression to be tested
    
    ancestor - the ancestor expression. May be null, in which case the search goes all the way to the base of the stack.
    
    Returns:
    
    true if the current expression is evaluated repeatedly
  - isLoopingReference
```
public static boolean isLoopingReference(VariableReference reference,
                                         Binding binding)
```
  - hasLoopingSubexpression
```
public static boolean hasLoopingSubexpression(Expression parent,
                                              Expression child)
```
  - getFocusSettingContainer
```
public static Expression getFocusSettingContainer(Expression exp)
```
    Get the focus-setting container of an expression *
    Note, this always returns an expression or null. Unlike the like-named concept in the spec, it can't return a component such as a template or an attribute set.
    
    Parameters:
    
    exp - the expression whose focus-setting container is required
    
    Returns:
    
    the focus-setting container, or null if the focus for the expression is the same as the focus for the containing component as a whole
  - getContextDocumentSettingContainer
```
public static Expression getContextDocumentSettingContainer(Expression exp)
```
    Get the context-document-setting container of an expression. This is the same as the focus-setting container, except when the context-setting operand is a single-document node-set, in which case we can go up one more level. For example, given /a/b[/d/e = 3], the predicate /d/e = 3 can be loop-lifted from the filter expression, because it is known that the base expression /a/b is a single-document node-set.
    
    Parameters:
    
    exp - the expression whose document-context-setting container is required
    
    Returns:
    
    the context-document-setting container, or null if the focus for the expression is the same as the focus for the containing component as a whole
  - resetStaticProperties
```
public static void resetStaticProperties(Expression exp)
```
    Reset the static properties for the current expression and for all its containing expressions. This should be done whenever the expression is changed in a way that might affect the properties. It causes the properties to be recomputed next time they are needed.
    
    Parameters:
    
    exp - the expression whose properties are to be reset; the method also resets local properties for all its ancestor expressions.
  - equalOrNull
```
public static boolean equalOrNull(java.lang.Object x,
                                  java.lang.Object y)
```
    Return true if two objects are equal or if both are null
    
    Parameters:
    
    x - the first object
    
    y - the second object
    
    Returns:
    
    true if both x and y are null or if x.equals(y)
  - getIteratorFromProcessMethod
```
public static SequenceIterator getIteratorFromProcessMethod(Expression exp,
                                                            XPathContext context)
                                                     throws XPathException
```
    Helper method to construct an iterator over the results of the expression when all that the expression itself offers is a process() method. This builds the entire results of the expression as a sequence in memory and then iterates over it.
    
    Parameters:
    
    context - the dynamic evaluation context
    
    Returns:
    
    an iterator over the results of the expression
    
    Throws:
    
    XPathException - if a dynamic error occurs
  - getItemFromProcessMethod
```
public static Item getItemFromProcessMethod(Expression exp,
                                            XPathContext context)
                                     throws XPathException
```
    Helper method to construct an item representing the results of the expression when all that the expression itself offers is a process() method.
    
    Parameters:
    
    context - the dynamic evaluation context
    
    Returns:
    
    an iterator over the results of the expression
    
    Throws:
    
    XPathException - if a dynamic error occurs
  - 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
  - effectiveBooleanValue
```
public static boolean effectiveBooleanValue(Item item)
                                     throws XPathException
```
    Determine the effective boolean value of a single item
    
    Parameters:
    
    item - the item 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 - always
  - dependsOnFocus
```
public static boolean dependsOnFocus(Expression exp)
```
    Ask whether an expression has a dependency on the focus
    
    Parameters:
    
    exp - the expression
    
    Returns:
    
    true if the value of the expression depends on the context item, position, or size
  - dependsOnVariable
```
public static boolean dependsOnVariable(Expression exp,
                                        Binding[] bindingList)
```
    Determine whether an expression depends on any one of a set of variables
    
    Parameters:
    
    exp - 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<Binding> 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
  - refersToVariableOrFunction
```
public static boolean refersToVariableOrFunction(Expression exp)
```
    Determine whether the expression contains any variable references or calls to user-written functions
    
    Parameters:
    
    exp - the expression being tested
    
    Returns:
    
    true if the expression includes a variable reference or function call, or an XSLT construct equivalent to a function call (e.g call-template). Also returns true if the expression includes a variable binding element, as (a) this is likely to mean it also contains a reference, and (b) it also needs to be caught on the same paths.
  - callsFunction
```
public static boolean callsFunction(Expression exp,
                                    StructuredQName qName,
                                    boolean sameFocusOnly)
```
    Determine whether an expression contains a call on the function with a given name
    
    Parameters:
    
    exp - The expression being tested
    
    qName - The name of the function
    
    sameFocusOnly - If true, only expressions with the same (top-level) focus are searched
    
    Returns:
    
    true if the expression contains a call on the function
  - containsSubexpression
```
public static boolean containsSubexpression(Expression exp,
                                            java.lang.Class<? extends Expression> subClass)
```
    Determine whether an expression has a subexpression of a given implementation class
    
    Parameters:
    
    exp - The expression being tested
    
    subClass - The impementation class of the sought subexpression
    
    Returns:
    
    true if the expression contains a subexpression that is an instance of the specified class
  - gatherCalledFunctions
```
public static void gatherCalledFunctions(Expression e,
                                         java.util.List<UserFunction> 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<SymbolicName> 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"
  - optimizeComponentBody
```
public static Expression optimizeComponentBody(Expression body,
                                               Compilation compilation,
                                               ExpressionVisitor visitor,
                                               ContextItemStaticInfo cit,
                                               boolean extractGlobals)
                                        throws XPathException
```
    Optimize the implementation of a component such as a function, template, or global variable
    
    Parameters:
    
    body - the expression forming the body of the component
    
    compilation - the current compilation
    
    visitor - the expression visitor
    
    cit - information about the context item for evaluation of the component body
    
    extractGlobals - true if constant expressions are to be extracted as global variables
    
    Returns:
    
    the optimized expression body
    
    Throws:
    
    XPathException - if anything goes wrong
  - computeEvaluationModesForUserFunctionCalls
```
public static void computeEvaluationModesForUserFunctionCalls(Expression exp)
                                                       throws XPathException
```
    Compute argument evaluation modes for all calls on user defined functions with a specified expression
    
    Throws:
    
    XPathException
  - clearStreamabilityData
```
public static void clearStreamabilityData(Expression exp)
                                   throws XPathException
```
    Clear all computed streamability properties for an expression and its contained subtree
    
    Parameters:
    
    exp - the expression whose streamability data is to be reset
    
    Throws:
    
    XPathException - should not happen
  - 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)
                                                throws XPathException
```
    Resolve calls to the XSLT current() function within an expression
    
    Parameters:
    
    exp - the expression within which calls to current() should be resolved
    
    Returns:
    
    the expression after resolving calls to current()
    
    Throws:
    
    XPathException - if a static error is detected
  - gatherVariableReferences
```
public static void gatherVariableReferences(Expression exp,
                                            Binding binding,
                                            java.util.List<VariableReference> 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
  - processExpressionTree
```
public static boolean processExpressionTree(Expression root,
                                            java.lang.Object result,
                                            ExpressionAction action)
                                     throws XPathException
```
    Process every node on a subtree of the expression tree using a supplied action.
    
    Parameters:
    
    root - the root of the subtree to be processed
    
    result - an arbitrary object that is passed to each action call and that can be updated to gather results of the processing
    
    action - an action to be performed on each node of the expression tree. Processing stops if any action returns the value true
    
    Returns:
    
    true if any call on the action operand returned true
    
    Throws:
    
    XPathException
  - replaceSelectedSubexpressions
```
public static boolean replaceSelectedSubexpressions(Expression exp,
                                                    ExpressionTool.ExpressionSelector selector,
                                                    Expression replacement,
                                                    boolean mustCopy)
```
    Replace all selected subexpressions within a subtree
    
    Parameters:
    
    exp - the expression at the root of the subtree
    
    selector - callback to determine whether a subexpression is selected
    
    replacement - the expression to be used in place of the variable reference
    
    mustCopy - if true, the replacement expression must be copied before use
    
    Returns:
    
    true if a replacement has been performed (in which case the replacement expression must be copied before being used again).
  - replaceVariableReferences
```
public static void replaceVariableReferences(Expression exp,
                                             Binding binding,
                                             Expression replacement,
                                             boolean mustCopy)
```
    Replace 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
    
    replacement - the expression to be used in place of the variable reference
    
    mustCopy - true if the replacement expression must be copied before use
  - 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.
  - 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
  - makePathExpression
```
public static Expression makePathExpression(Expression start,
                                            Expression step,
                                            boolean sortAndDeduplicate)
```
    Make a mapping expression. The resulting expression will include logic to check that the first operand returns nodes, and that the expression as a whole is homogeneous, unless the caller requests otherwise.
    
    Parameters:
    
    start - the start expression (the first operand of "/")
    
    step - the step expression (the second operand of "/")
    
    sortAndDeduplicate - set to true if this is a path expression ("/") where the result needs to be homogenous, and needs to be sorted and deduplicated if it consists of nodes. Set to false if the caller knows that this is not necessary (typically because it has already been checked).
    
    Returns:
    
    the resulting expression.
  - makeRawPathExpression
```
public static Expression makeRawPathExpression(Expression start,
                                               Expression step,
                                               boolean sortAndDeduplicate)
```
  - findOperand
```
public static Operand findOperand(Expression parentExpression,
                                  Expression childExpression)
```
    Find the operand corresponding to a particular child expression
    
    Parameters:
    
    parentExpression - the parent expression
    
    childExpression - the child expression
    
    Returns:
    
    the relevant operand, or null if not found
  - unfilteredExpression
```
public static Expression unfilteredExpression(Expression exp,
                                              boolean allowPositional)
```
    Get the expression that remains after removing any filter predicates
    
    Parameters:
    
    exp - the expression to be examined
    
    allowPositional - true if positional predicates are allowed
    
    Returns:
    
    the expression underlying exp after removing any predicates
  - tryToFactorOutDot
```
public static Expression tryToFactorOutDot(Expression exp,
                                           ItemType contextItemType)
```
    Try to factor out dependencies on the context item, by rewriting an expression f(.) as let $dot := . return f($dot). This is not always possible, for example where f() is an extension function call that uses XPathContext as an implicit argument. However, doing this increases the chances of distributing a "where" condition in a FLWOR expression to the individual input sequences selected by the "for" clauses.
    
    Parameters:
    
    exp - the expression from which references to "." should be factored out if possible
    
    contextItemType - the static type of the context item
    
    Returns:
    
    either the expression, after binding "." to a local variable and replacing all references to it; or null, if no changes were made.
  - factorOutDot
```
public static boolean factorOutDot(Expression exp,
                                   Binding variable)
```
    Replace references to the context item with references to a variable
    
    Parameters:
    
    exp - the expression in which the replacement is to take place
    
    variable - the declaration of the variable
    
    Returns:
    
    true if replacement has taken place (at any level)
  - inlineVariableReferences
```
public static boolean inlineVariableReferences(Expression expr,
                                               Binding binding,
                                               Expression replacement)
```
    Inline variable references.
    
    Parameters:
    
    expr - the expression containing the variable references to be inlined
    
    binding - the variable binding to be inlined
    
    replacement - the expression to be used as a replacement for the variable reference
    
    Returns:
    
    true if any replacement was carried out within the subtree of this expression
  - inlineVariableReferencesInternal
```
public static boolean inlineVariableReferencesInternal(Expression expr,
                                                       Binding binding,
                                                       Expression replacement)
```
  - replaceTrivialCallsToCurrent
```
public static boolean replaceTrivialCallsToCurrent(Expression expr)
```
    Replace trivial calls to current() by a context item expression (.).
    
    Parameters:
    
    expr - the expression potentially containing the calls to be replaced
    
    Returns:
    
    true if any replacement was carried out within the subtree of this expression
  - replaceCallsToCurrent
```
public static boolean replaceCallsToCurrent(Expression expr,
                                            LocalBinding binding)
```
    Replace calls to current() by a variable reference.
    
    Parameters:
    
    expr - the expression potentially containing the calls to be replaced
    
    binding - the variable binding to be referenced
    
    Returns:
    
    true if any replacement was carried out within the subtree of this expression
  - 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()
  - getCurrentDirectory
```
public static java.lang.String getCurrentDirectory()
```
  - getBaseURI
```
public static java.net.URI getBaseURI(StaticContext env,
                                      javax.xml.transform.SourceLocator locator,
                                      boolean fail)
                               throws XPathException
```
    Determine the base URI of an expression, so that it can be saved on the expression tree for use when the expression is evaluated
    
    Parameters:
    
    env - the static context
    
    locator - location of the expression for error messages
    
    fail - if true, the method throws an exception when there is no absolute base URI; otherwise, the method returns null
    
    Returns:
    
    the absolute base URI of the expression
    
    Throws:
    
    XPathException - if an error occurs
  - parenthesize
```
public static java.lang.String parenthesize(Expression exp)
```
    Display an expression adding parentheses if it is possible they are necessary because the expression has sub-expressions
    
    Parameters:
    
    exp - the expression to be displayed
    
    Returns:
    
    a representation of the expression in parentheses
  - parenthesizeShort
```
public static java.lang.String parenthesizeShort(Expression exp)
```
  - validateTree
```
public static void validateTree(Expression exp)
```
  - isLocalConstructor
```
public static boolean isLocalConstructor(Expression child)
```
    Ask whether a supplied expression is a nested node constructor. That is, return true if the child expression creates nodes that will only be used as children of some parent node (meaning that they never need to be copied).
    
    Parameters:
    
    child - child expression to be tested
    
    Returns:
    
    true if the node constructed by the child expression does not need to be copied.

Class ExpressionTool

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

UNDECIDED

NO_EVALUATION_NEEDED

EVALUATE_VARIABLE

MAKE_CLOSURE

MAKE_MEMO_CLOSURE

RETURN_EMPTY_SEQUENCE

EVALUATE_AND_MATERIALIZE_VARIABLE

CALL_EVALUATE_ITEM

ITERATE_AND_MATERIALIZE

PROCESS

LAZY_TAIL_EXPRESSION

SHARED_APPEND_EXPRESSION

MAKE_INDEXED_VARIABLE

MAKE_SINGLETON_CLOSURE

EVALUATE_SUPPLIED_PARAMETER

STREAMING_ARGUMENT

Method Detail

make

setDeepRetainedStaticContext

copyLocationInfo

unsortedIfHomogeneous

lazyEvaluationMode

eagerEvaluationMode

evaluate

lazyEvaluate

eagerEvaluate

markTailFunctionCalls

indent

contains

containsLocalParam

containsLocalVariableReference

contains

changesXsltContext

isLoopingSubexpression

isLoopingReference

hasLoopingSubexpression

getFocusSettingContainer

getContextDocumentSettingContainer

resetStaticProperties

equalOrNull

getIteratorFromProcessMethod

getItemFromProcessMethod

allocateSlots

effectiveBooleanValue

effectiveBooleanValue

ebvError

dependsOnFocus

dependsOnVariable

gatherReferencedVariables

refersToVariableOrFunction

callsFunction

containsSubexpression

gatherCalledFunctions

gatherCalledFunctionNames

optimizeComponentBody

computeEvaluationModesForUserFunctionCalls

clearStreamabilityData

resetPropertiesWithinSubtree

resolveCallsToCurrentFunction

gatherVariableReferences

processExpressionTree

replaceSelectedSubexpressions

replaceVariableReferences

getReferenceCount

expressionSize

rebindVariableReferences

makePathExpression

makeRawPathExpression

findOperand

unfilteredExpression

tryToFactorOutDot

factorOutDot

inlineVariableReferences

inlineVariableReferencesInternal