net.sf.saxon.expr

Class ExpressionTool

public class ExpressionTool extends 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 intCALL_EVALUATE_ITEM
static intEVALUATE_AND_MATERIALIZE_VARIABLE
static intEVALUATE_SUPPLIED_PARAMETER
static intEVALUATE_VARIABLE
static intITERATE_AND_MATERIALIZE
static intLAZY_TAIL_EXPRESSION
static intMAKE_CLOSURE
static intMAKE_INDEXED_VARIABLE
static intMAKE_MEMO_CLOSURE
static intMAKE_SINGLETON_CLOSURE
static intNO_EVALUATION_NEEDED
static intPROCESS
static intRETURN_EMPTY_SEQUENCE
static intSHARED_APPEND_EXPRESSION
static intUNDECIDED
Method Summary
static intallocateSlots(Expression exp, int nextFree, SlotManager frame)
Allocate slot numbers to range variables
static booleancallsFunction(Expression exp, StructuredQName qName)
Determine whether an expression contains a call on the function with a given fingerprint
static voidcopyLocationInfo(Expression from, Expression to)
Copy location information (the line number and reference to the container) from one expression to another
static booleandependsOnFocus(Expression exp)
Ask whether an expression has a dependency on the focus
static booleandependsOnVariable(Expression e, Binding[] bindingList)
Determine whether an expression depends on any one of a set of variables
static ValueRepresentationeagerEvaluate(Expression exp, XPathContext context)
Evaluate an expression now; lazy evaluation is not permitted in this case
static inteagerEvaluationMode(Expression exp)
Determine the method of evaluation to be used when lazy evaluation of an expression is preferred.
static voidebvError(String reason)
Report an error in computing the effective boolean value of an expression
static booleaneffectiveBooleanValue(SequenceIterator iterator)
Determine the effective boolean value of a sequence, given an iterator over the sequence
static booleaneffectiveBooleanValue(Item item)
Determine the effective boolean value of a single item
static ValueRepresentationevaluate(Expression exp, int evaluationMode, XPathContext context, int ref)
Do lazy evaluation of an expression.
static intexpressionSize(Expression exp)
Get the size of an expression tree (the number of subexpressions it contains)
static voidgatherAllSubExpressions(Expression exp, HashSet set)
Gather the set of all the subexpressions of an expression (the transitive closure)
static voidgatherCalledFunctionNames(Expression e, List list)
Gather a list of the names of the user-defined functions which a given expression calls directly
static voidgatherCalledFunctions(Expression e, List list)
Gather a list of all the user-defined functions which a given expression calls directly
static voidgatherReferencedVariables(Expression e, List list)
Gather a list of all the variable bindings on which a given expression depends
static voidgatherVariableReferences(Expression exp, Binding binding, List list)
Get a list of all references to a particular variable within a subtree
static intgetReferenceCount(Expression exp, Binding binding, boolean inLoop)
Determine how often a variable is referenced.
static Stringindent(int level)
Construct indent string, for diagnostic output
static booleanisAllowedInUpdatingContext(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 ValueRepresentationlazyEvaluate(Expression exp, XPathContext context, int ref)
Do lazy evaluation of an expression.
static intlazyEvaluationMode(Expression exp)
Determine the method of evaluation to be used when lazy evaluation of an expression is preferred.
static Expressionmake(String expression, StaticContext env, int start, int terminator, int lineNumber, boolean compileWithTracing)
Parse an expression.
static intmarkTailFunctionCalls(Expression exp, StructuredQName qName, int arity)
Scan an expression to find and mark any recursive tail function calls
static voidrebindVariableReferences(Expression exp, Binding oldBinding, Binding newBinding)
Rebind all variable references to a binding
static voidresetPropertiesWithinSubtree(Expression exp)
Reset cached static properties within a subtree, meaning that they have to be recalulated next time they are required
static ExpressionresolveCallsToCurrentFunction(Expression exp, Configuration config)
Resolve calls to the XSLT current() function within an expression
static ExpressiontryToFactorOutDot(Expression exp, ItemType contextItemType)
Try to factor out dependencies on the context item, by rewriting an expression f(.) as let $dot := . return f($dot).
static Expressionunsorted(Optimizer opt, Expression exp, boolean retainAllNodes)
Remove unwanted sorting from an expression, at compile time
static ExpressionunsortedIfHomogeneous(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).

Field Detail

CALL_EVALUATE_ITEM

public static final int CALL_EVALUATE_ITEM

EVALUATE_AND_MATERIALIZE_VARIABLE

public static final int EVALUATE_AND_MATERIALIZE_VARIABLE

EVALUATE_SUPPLIED_PARAMETER

public static final int EVALUATE_SUPPLIED_PARAMETER

EVALUATE_VARIABLE

public static final int EVALUATE_VARIABLE

ITERATE_AND_MATERIALIZE

public static final int ITERATE_AND_MATERIALIZE

LAZY_TAIL_EXPRESSION

public static final int LAZY_TAIL_EXPRESSION

MAKE_CLOSURE

public static final int MAKE_CLOSURE

MAKE_INDEXED_VARIABLE

public static final int MAKE_INDEXED_VARIABLE

MAKE_MEMO_CLOSURE

public static final int MAKE_MEMO_CLOSURE

MAKE_SINGLETON_CLOSURE

public static final int MAKE_SINGLETON_CLOSURE

NO_EVALUATION_NEEDED

public static final int NO_EVALUATION_NEEDED

PROCESS

public static final int PROCESS

RETURN_EMPTY_SEQUENCE

public static final int RETURN_EMPTY_SEQUENCE

SHARED_APPEND_EXPRESSION

public static final int SHARED_APPEND_EXPRESSION

UNDECIDED

public static final int UNDECIDED

Method Detail

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.

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

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

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

eagerEvaluate

public static ValueRepresentation eagerEvaluate(Expression exp, XPathContext context)
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: net.sf.saxon.trans.XPathException if any dynamic error occurs evaluating the expression

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

ebvError

public static void ebvError(String reason)
Report an error in computing the effective boolean value of an expression

Parameters: reason the nature of the error

Throws: XPathException

effectiveBooleanValue

public static boolean effectiveBooleanValue(SequenceIterator iterator)
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)
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

evaluate

public static ValueRepresentation evaluate(Expression exp, int evaluationMode, XPathContext context, int ref)
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

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

gatherAllSubExpressions

public static void gatherAllSubExpressions(Expression exp, 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.

gatherCalledFunctionNames

public static void gatherCalledFunctionNames(Expression e, 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"

gatherCalledFunctions

public static void gatherCalledFunctions(Expression e, 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

gatherReferencedVariables

public static void gatherReferencedVariables(Expression e, 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

gatherVariableReferences

public static void gatherVariableReferences(Expression exp, Binding binding, 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.

indent

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

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()

lazyEvaluate

public static ValueRepresentation lazyEvaluate(Expression exp, XPathContext context, int ref)
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

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

make

public static Expression make(String expression, StaticContext env, int start, int terminator, int lineNumber, boolean compileWithTracing)
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

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.

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

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)
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()

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.

unsorted

public static Expression unsorted(Optimizer opt, Expression exp, boolean retainAllNodes)
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

unsortedIfHomogeneous

public 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). 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