Class 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
    • Method Detail

      • make

        public static Expression make​(java.lang.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 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
        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 javax.xml.transform.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.
      • 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 boolean 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:
        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

        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 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
      • 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,
                                                     java.util.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,
                                                 java.util.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
      • 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.