Package 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
Fields Modifier and Type Field Description 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
All Methods Static Methods Concrete Methods Modifier and Type Method Description static int
allocateSlots(Expression exp, int nextFree, SlotManager frame)
Allocate slot numbers to range variablesstatic boolean
callsFunction(Expression exp, StructuredQName qName)
Determine whether an expression contains a call on the function with a given fingerprintstatic void
copyLocationInfo(Expression from, Expression to)
Copy location information (the line number and reference to the container) from one expression to anotherstatic boolean
dependsOnVariable(Expression e, Binding[] bindingList)
Determine whether an expression depends on any one of a set of variablesstatic ValueRepresentation
eagerEvaluate(Expression exp, XPathContext context)
Evaluate an expression now; lazy evaluation is not permitted in this casestatic 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 expressionstatic boolean
effectiveBooleanValue(SequenceIterator iterator)
Determine the effective boolean value of a sequence, given an iterator over the sequencestatic 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 directlystatic void
gatherCalledFunctions(Expression e, java.util.List list)
Gather a list of all the user-defined functions which a given expression calls directlystatic void
gatherReferencedVariables(Expression e, java.util.List list)
Gather a list of all the variable bindings on which a given expression dependsstatic void
gatherVariableReferences(Expression exp, Binding binding, java.util.List list)
Get a list of all references to a particular variable within a subtreestatic 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 outputstatic 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 allowedstatic 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 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 callsstatic void
rebindVariableReferences(Expression exp, Binding oldBinding, Binding newBinding)
Rebind all variable references to a bindingstatic void
resetPropertiesWithinSubtree(Expression exp)
Reset cached static properties within a subtree, meaning that they have to be recalulated next time they are requiredstatic Expression
resolveCallsToCurrentFunction(Expression exp, Configuration config)
Resolve calls to the XSLT current() function within an expressionstatic Expression
unsorted(Optimizer opt, Expression exp, boolean retainAllNodes)
Remove unwanted sorting from an expression, at compile timestatic 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).
-
-
-
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 expressionstart
- position of the first significant character in the expressionterminator
- The token that marks the end of this expression; typically Tokenizer.EOF, but may for example be a right curly bracelineNumber
- the line number of the start of the expressioncompileWithTracing
- 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 informationto
- 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 optimizerexp
- the expression to be optimizedretainAllNodes
- 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 optimizerexp
- 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 evaluatedevaluationMode
- the evaluation mode for this expressioncontext
- 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 Closureref
- 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 evaluatedcontext
- 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 Closureref
- 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 evaluatedcontext
- 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 analyzedqName
- the name of the containing functionarity
- 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 assignednextFree
- the next slot number that is available for allocationframe
- 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 testedbindingList
- 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 testedlist
- a list to which the bindings are to be added. The items in this list must implementBinding
-
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 testedqName
- 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 testedlist
- a list of the functions that are called. The items in this list must be objects of classUserFunction
-
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 testedlist
- 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 resolvedconfig
- the Saxon configuration- Returns:
- the expression after resolving calls to current()
- Throws:
XPathException
-
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 subtreebinding
- the variable binding whose references are soughtlist
- 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 countedbinding
- identifies the variable of interestinLoop
- 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 expressionset
- 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 reboundoldBinding
- the old binding for the variable referencesnewBinding
- 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()
-
-