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,
                                      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 expression
        container - The expression's container
        start - position of the first significant character in the expression
        terminator - The token that marks the end of this expression; typically Token.EOF, but may for example be a right curly brace
        lineNumber - the line number of the start of the expression
        codeInjector - 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 information
        to - 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 optimizer
        exp - the expression to be optimized
        retainAllNodes - 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 optimizer
        exp - 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 evaluated
        evaluationMode - the evaluation mode for this expression
        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<? 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 evaluated
        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,
                                                StructuredQName qName,
                                                int arity)
        Scan an expression to find and mark any recursive tail function calls
        Parameters:
        exp - the expression to be analyzed
        qName - 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 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 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<? 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 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<Binding> 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
      • 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 tested
        qName - 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 tested
        list - a list of the functions that are called. The items in this list must be objects of class UserFunction
      • 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 tested
        list - 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 resolved
        config - 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 subtree
        binding - the variable binding whose references are sought
        list - 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 subtree
        binding - the variable binding whose references are sought
        replacement - 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 counted
        binding - identifies the variable of interest
        inLoop - 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 expression
        set - 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 expression
        child - 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 rebound
        oldBinding - the old binding for the variable references
        newBinding - 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 possible
        contextItemType - 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 replaced
        n - 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 context
        locator - location of the expression for error messages
        fail - 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