Package net.sf.saxon.expr
Class ExpressionTool
java.lang.Object
net.sf.saxon.expr.ExpressionTool
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
FieldsModifier and TypeFieldDescriptionstatic final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
static final int
-
Method Summary
Modifier and TypeMethodDescriptionstatic int
allocateSlots
(Expression exp, int nextFree, SlotManager frame) Allocate slot numbers to range variablesstatic boolean
callsFunction
(Expression exp, int fp) 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) 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
Determine the method of evaluation to be used when lazy evaluation of an expression is preferred.static void
static 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 void
gatherCalledFunctions
(Expression e, List list) Gather a list of all the user-defined functions which a given expression calls directlystatic void
gatherReferencedVariables
(Expression e, List list) Gather a list of all the variable bindings on which a given expression dependsstatic SourceLocator
getLocator
(Expression exp) Get location information for an expression in the form of a SourceLocatorstatic String
indent
(int level) Construct indent string, for diagnostic outputstatic boolean
isRepeatedSubexpression
(Expression parent, Expression child, StaticContext env) Determine whether an expression is a repeatedly-evaluated subexpression of a parent expression.static boolean
Determine whether an expression can be evaluated without reference to the part of the context document outside the subtree rooted at the context node.static boolean
isVariableReplaceableByDot
(Expression exp, Binding[] binding) Determine whether it is possible to rearrange an expression so that all references to a given variable are replaced by a reference to ".".static ValueRepresentation
lazyEvaluate
(Expression exp, XPathContext context, int ref) Do lazy evaluation of an expression.static int
Determine the method of evaluation to be used when lazy evaluation of an expression is preferred.static Expression
make
(String expression, StaticContext env, int start, int terminator, int lineNumber) Parse an expression.static void
Establish the links from subexpressions to their parent expressions, by means of a recursive tree walk.static boolean
markTailFunctionCalls
(Expression exp, int nameCode, int arity) Scan an expression to find and mark any recursive tail function callsstatic Expression
resolveCallsToCurrentFunction
(Expression exp, Configuration config) Resolve calls to the current() function within an expressionstatic Expression
unsorted
(Optimizer opt, Expression exp, boolean eliminateDuplicates) Remove unwanted sorting from an expression, at compile timestatic Expression
unsortedIfHomogeneous
(Optimizer opt, Expression exp, boolean eliminateDuplicates) 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 Details
-
UNDECIDED
public static final int UNDECIDED- See Also:
-
NO_EVALUATION_NEEDED
public static final int NO_EVALUATION_NEEDED- See Also:
-
EVALUATE_VARIABLE
public static final int EVALUATE_VARIABLE- See Also:
-
MAKE_CLOSURE
public static final int MAKE_CLOSURE- See Also:
-
MAKE_MEMO_CLOSURE
public static final int MAKE_MEMO_CLOSURE- See Also:
-
RETURN_EMPTY_SEQUENCE
public static final int RETURN_EMPTY_SEQUENCE- See Also:
-
EVALUATE_AND_MATERIALIZE_VARIABLE
public static final int EVALUATE_AND_MATERIALIZE_VARIABLE- See Also:
-
CALL_EVALUATE_ITEM
public static final int CALL_EVALUATE_ITEM- See Also:
-
ITERATE_AND_MATERIALIZE
public static final int ITERATE_AND_MATERIALIZE- See Also:
-
PROCESS
public static final int PROCESS- See Also:
-
LAZY_TAIL_EXPRESSION
public static final int LAZY_TAIL_EXPRESSION- See Also:
-
SHARED_APPEND_EXPRESSION
public static final int SHARED_APPEND_EXPRESSION- See Also:
-
-
Method Details
-
make
public static Expression make(String expression, StaticContext env, int start, int terminator, int lineNumber) 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 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 expression- Returns:
- an object of type Expression
- Throws:
XPathException
- if the expression contains a static error
-
copyLocationInfo
Copy location information (the line number) from one expression to another -
makeParentReferences
Establish the links from subexpressions to their parent expressions, by means of a recursive tree walk. -
getLocator
Get location information for an expression in the form of a SourceLocator -
isRepeatedSubexpression
public static boolean isRepeatedSubexpression(Expression parent, Expression child, StaticContext env) Determine whether an expression is a repeatedly-evaluated subexpression of a parent expression. For example, the predicate in a filter expression is a repeatedly-evaluated subexpression of the filter expression. -
unsorted
public static Expression unsorted(Optimizer opt, Expression exp, boolean eliminateDuplicates) throws XPathException Remove unwanted sorting from an expression, at compile time- Throws:
XPathException
-
unsortedIfHomogeneous
public static Expression unsortedIfHomogeneous(Optimizer opt, Expression exp, boolean eliminateDuplicates) 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.- Throws:
XPathException
-
lazyEvaluationMode
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
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:
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 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:
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 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
Scan an expression to find and mark any recursive tail function calls- Parameters:
exp
- the expression to be analyzednameCode
- the name of the containing functionarity
- the arity of the containing function- Returns:
- true if a tail function call to the specified function was found. In this case the UserFunctionCall object representing the tail function call will also have been marked as tail-recursive.
-
indent
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
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
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
- Throws:
XPathException
-
dependsOnVariable
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
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
Determine whether an expression contains a call on the function with a given fingerprint- Parameters:
exp
- The expression being testedfp
- The fingerprint of the name of the function- Returns:
- true if the expression contains a call on the function
-
gatherCalledFunctions
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
-
resolveCallsToCurrentFunction
public static Expression resolveCallsToCurrentFunction(Expression exp, Configuration config) throws XPathException Resolve calls to the current() function within an expression- Throws:
XPathException
-
isVariableReplaceableByDot
Determine whether it is possible to rearrange an expression so that all references to a given variable are replaced by a reference to ".". This is true of there are no references to the variable within a filter predicate or on the rhs of a "/" operator. -
isSubtreeExpression
Determine whether an expression can be evaluated without reference to the part of the context document outside the subtree rooted at the context node.- 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.
-