Package net.sf.saxon.expr.parser
Class 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
-
-
Field Summary
Fields Modifier and Type Field 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
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 boolean
containsLocalParam(Expression exp)
Determine whether an expression contains a LocalParamSetter subexpressionstatic void
copyLocationInfo(Expression from, Expression to)
Copy location information (the line number and reference to the container) from one expression to anotherstatic boolean
dependsOnFocus(Expression exp)
Ask whether an expression has a dependency on the focusstatic 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(Item item)
Determine the effective boolean value of a single itemstatic boolean
effectiveBooleanValue(SequenceIterator<? extends Item> iterator)
Determine the effective boolean value of a sequence, given an iterator over the sequencestatic ValueRepresentation<? extends Item>
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<UserFunction> list)
Gather a list of all the user-defined functions which a given expression calls directlystatic void
gatherReferencedVariables(Expression e, java.util.List<Binding> list)
Gather a list of all the variable bindings on which a given expression dependsstatic void
gatherVariableReferences(Expression exp, Binding binding, java.util.List<VariableReference> list)
Get a list of all references to a particular variable within a subtreestatic 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 evaluatedstatic java.lang.String
getCurrentDirectory()
static int
getReferenceCount(Expression exp, Binding binding, boolean inLoop)
Determine how often a variable is referenced.static java.lang.String
indent(int level)
Construct indent string, for diagnostic 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 ValueRepresentation<? extends Item>
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, Container container, int start, int terminator, int lineNumber, CodeInjector codeInjector)
Parse an XPath expression.static Expression
makePathExpression(Expression start, Expression step, boolean sortAndDeduplicate)
Make a mapping expression.static int
markTailFunctionCalls(Expression exp, StructuredQName qName, int arity)
Scan an expression to find and mark any recursive tail function callsstatic java.util.Stack<Expression>
pathToContainedExpression(Expression ancestor, Expression child, java.util.Stack<Expression> expressionStack)
Check if child expression is a sub-expression of a expressionstatic void
rebindVariableReferences(Expression exp, Binding oldBinding, Binding newBinding)
Rebind all variable references to a bindingstatic boolean
refersToVariableOrFunction(Expression e)
Determine whether the expression contains any variable references or calls to user-written functionsstatic void
replaceNthSubexpression(Expression target, int n, Expression replacement)
Replace the Nth subexpression of an expressionstatic boolean
replaceVariableReferences(Expression exp, Binding binding, Expression replacement)
Replace all references to a particular variable within a subtreestatic 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 boolean
selectsOutwards(Expression e)
Tests whether an expression performs navigation downwards or sidewaysstatic boolean
selectsSideways(Expression e)
Tests whether an expression performs navigation downwards or sidewaysstatic 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
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
-
EVALUATE_SUPPLIED_PARAMETER
public static final int EVALUATE_SUPPLIED_PARAMETER
- See Also:
- Constant Field Values
-
-
Method Detail
-
make
public static Expression make(java.lang.String expression, StaticContext env, Container container, int start, int terminator, int lineNumber, 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 expressioncontainer
- The expression's containerstart
- position of the first significant character in the expressionterminator
- The token that marks the end of this expression; typically Token.EOF, but may for example be a right curly bracelineNumber
- the line number of the start of the expressioncodeInjector
- 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
-
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
- if a static error is found while doing the rewrite
-
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
- 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 ValueRepresentation<? extends Item> 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<? extends Item> 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
-
containsLocalParam
public static boolean containsLocalParam(Expression exp)
Determine whether an expression contains a LocalParamSetter subexpression- Parameters:
exp
- the expression to be tested
-
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<? extends Item> 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
-
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 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<Binding> 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
-
refersToVariableOrFunction
public static boolean refersToVariableOrFunction(Expression e)
Determine whether the expression contains any variable references or calls to user-written functions- Parameters:
e
- 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)
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<UserFunction> 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
- 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 subtreebinding
- the variable binding whose references are soughtlist
- a list to be populated with the references to this variable
-
replaceVariableReferences
public static boolean replaceVariableReferences(Expression exp, Binding binding, Expression replacement)
Replace 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 soughtreplacement
- the expression to be used in place of the variable reference- Returns:
- true if the expression has been changed, at any level
-
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.
-
pathToContainedExpression
public static java.util.Stack<Expression> pathToContainedExpression(Expression ancestor, Expression child, java.util.Stack<Expression> expressionStack)
Check if child expression is a sub-expression of a expression- Parameters:
ancestor
- the ancestor expressionchild
- the child expressions.
-
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
-
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.
-
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 possiblecontextItemType
- 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.
-
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()
-
replaceNthSubexpression
public static void replaceNthSubexpression(Expression target, int n, Expression replacement)
Replace the Nth subexpression of an expression- Parameters:
target
- the parent expression whose subexpression is to be replacedn
- the index of the subexpression to be replaced (starting at zero)replacement
- the replacement subexpression
-
selectsOutwards
public static boolean selectsOutwards(Expression e)
Tests whether an expression performs navigation downwards or sideways- Parameters:
e
- the expression- Returns:
- true if the expression uses a downwards or sideways axis
-
selectsSideways
public static boolean selectsSideways(Expression e)
Tests whether an expression performs navigation downwards or sideways- Parameters:
e
- the expression- Returns:
- true if the expression uses a downwards or sideways axis
-
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 contextlocator
- location of the expression for error messagesfail
- if true, the method throws an exception when there is no absolute base URI; otherwise, the method returns null @return the absolute base URI of the expression- Throws:
XPathException
-
-