net.sf.saxon.expr
Class ExpressionTool

java.lang.Object
  net.sf.saxon.expr.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 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	NO_EVALUATION_NEEDED
static int	PROCESS
static int	RETURN_EMPTY_SEQUENCE
static int	SHARED_APPEND_EXPRESSION
static int	UNDECIDED

Method Summary

static int	allocateSlots(Expression exp, int nextFree, SlotManager frame) Allocate slot numbers to range variables
static boolean	callsFunction(Expression exp, int fp) Determine whether an expression contains a call on the function with a given fingerprint
static void	copyLocationInfo(Expression from, Expression to) Copy location information (the line number) from one expression to another
static boolean	dependsOnVariable(Expression e, Binding[] bindingList) Determine whether an expression depends on any one of a set of variables
static ValueRepresentation	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(String reason)
static boolean	effectiveBooleanValue(SequenceIterator iterator) Determine the effective boolean value of a sequence, given an iterator over the sequence
static 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 directly
static void	gatherReferencedVariables(Expression e, List list) Gather a list of all the variable bindings on which a given expression depends
static SourceLocator	getLocator(Expression exp) Get location information for an expression in the form of a SourceLocator
static String	indent(int level) Construct indent string, for diagnostic output
static boolean	isRepeatedSubexpression(Expression parent, Expression child, StaticContext env) Determine whether an expression is a repeatedly-evaluated subexpression of a parent expression.
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.
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	lazyEvaluationMode(Expression exp) 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, boolean compileWithTracing) Parse an expression.
static void	makeParentReferences(Expression top) Establish the links from subexpressions to their parent expressions, by means of a recursive tree walk.
static int	markTailFunctionCalls(Expression exp, int nameCode, int arity) Scan an expression to find and mark any recursive tail function calls
static Expression	resolveCallsToCurrentFunction(Expression exp, Configuration config) Resolve calls to the current() function within an expression
static Expression	unsorted(Optimizer opt, Expression exp, boolean eliminateDuplicates) Remove unwanted sorting from an expression, at compile time
static 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).

Methods inherited from class java.lang.Object

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

Method Detail

make

public static Expression make(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 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 -

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) from one expression to another

makeParentReferences

public static void makeParentReferences(Expression top)

Establish the links from subexpressions to their parent expressions, by means of a recursive tree walk.

getLocator

public static SourceLocator getLocator(Expression exp)

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

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:

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 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 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 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 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,
                                        int nameCode,
                                        int arity)

Scan an expression to find and mark any recursive tail function calls

Parameters:

exp - the expression to be analyzed

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

ebvError

public static void ebvError(String reason)
                     throws XPathException

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

callsFunction

public static boolean callsFunction(Expression exp,
                                    int fp)

Determine whether an expression contains a call on the function with a given fingerprint

Parameters:

exp - The expression being tested

fp - The fingerprint of the name of the function

Returns:

true if the expression contains a call on the function

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

resolveCallsToCurrentFunction

public static Expression resolveCallsToCurrentFunction(Expression exp,
                                                       Configuration config)
                                                throws XPathException

Resolve calls to the current() function within an expression

Throws:

XPathException

isVariableReplaceableByDot

public 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 ".". This is true of there are no references to the variable within a filter predicate or on the rhs of a "/" operator.

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.

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.