Package org.basex.query.expr

Class Expr

java.lang.Object

org.basex.query.expr.ExprInfo

org.basex.query.expr.Expr

Direct Known Subclasses:

ParseExpr, Value

public abstract class Expr
extends ExprInfo

Abstract class for representing XQuery expressions. Expression are divided into ParseExpr and Value classes.

Author:

BaseX Team 2005-22, BSD License, Christian Gruen

Constructor Summary

Constructors

Constructor	Description
Expr()

Method Summary

Modifier and Type	Method	Description
abstract boolean	accept(ASTVisitor visitor)	Traverses this expression, notifying the visitor of declared and used variables, and checking the tree for other recursive properties.
Expr	arg(int i)	Returns the specified argument/operand of an expression (function, list, etc).
Expr[]	args()	Returns the arguments/operands of an expression (function, list, etc).
Item	atomItem(QueryContext qc, InputInfo ii)	Evaluates the expression and returns the resulting, atomized item, or Empty.VALUE if the expression yields an empty sequence.
Iter	atomIter(QueryContext qc, InputInfo ii)	Evaluates the expression and returns an iterator on the resulting, atomized items.
abstract Value	atomValue(QueryContext qc, InputInfo ii)	Evaluates the expression and returns the atomized items.
abstract void	checkUp()	Checks if the updating semantics are satisfied.
abstract Expr	compile(CompileContext cc)	Compiles and optimizes the expression, assigns types and cardinalities.
abstract Expr	copy(CompileContext cc, IntObjMap<Var> vm)	Copies an expression.
abstract VarUsage	count(Var var)	Checks how often a variable or context reference is used in this expression.
Data	data()	Returns the data reference bound to this expression.
boolean	ddo()	Indicates if this expression returns items in document order without duplicates.
abstract Item	ebv(QueryContext qc, InputInfo ii)	Checks if the effective boolean value can be computed for this expression:
abstract boolean	equals(Object obj)	This function is e.g.
abstract int	exprSize()	Counts the number of expressions in this expression's subtree.
FuncType	funcType()	Returns the function type of this expression.
abstract boolean	has(Flag... flags)	Indicates if an expression has one of the specified compiler properties.
protected boolean	hasFreeVars()	Checks if this expression has free variables.
boolean	indexAccessible(IndexInfo ii)	Checks if an expression can be rewritten to an index access.
abstract Expr	inline(InlineContext ic)	Inlines an expression into this one, replacing all variable or context references.
abstract boolean	inlineable(InlineContext ic)	Checks if inlining is possible.
boolean	isSimple()	Checks if this expression is deterministic, performs no updates, does not access the context value and position, and calls no higher-order function.
abstract Item	item(QueryContext qc, InputInfo ii)	Evaluates the expression and returns the resulting item, or Empty.VALUE if the expression yields an empty sequence.
abstract Iter	iter(QueryContext qc)	Evaluates the expression and returns an iterator on the resulting items.
void	markTailCalls(CompileContext cc)	Finds and marks tail calls, enabling TCO.
Expr	mergeEbv(Expr expr, boolean or, CompileContext cc)	Tries to merge two expressions that are part of an EBV test.
Expr	optimize(CompileContext cc)	Optimizes an already compiled expression without recompiling its sub-expressions.
Expr	optimizePos(CmpV.OpV op, CompileContext cc)	Optimizes an expression for positional access.
abstract void	refineType(Expr expr)	Refines the expression type.
abstract SeqType	seqType()	Returns the static type of the resulting value.
Expr	simplify(CompileContext.Simplify mode, CompileContext cc)	Simplifies the expression.
Expr	simplifyFor(CompileContext.Simplify mode, CompileContext cc)	Simplifies the expression.
abstract long	size()	Returns the result size, or -1 if the size is unknown.
abstract Item	test(QueryContext qc, InputInfo ii)	Performs a predicate test and returns the item if the test was successful.
protected Expr	typeCheck(TypeCheck tc, CompileContext cc)	Tries to push the given type check inside this expression.
boolean	uses(Var var)	Checks if the given variable is used by this expression.
boolean	vacuous()	Tests if this is a vacuous expression (empty sequence or error function).
abstract Value	value(QueryContext qc)	Evaluates the expression and returns the resulting value.
protected static boolean	visitAll(ASTVisitor visitor, Expr... exprs)	Visit all given expressions with the given visitor.

Methods inherited from class org.basex.query.expr.ExprInfo

description, info, toErrorString, toString, toString, toXml

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Expr

public Expr()

Method Detail

checkUp

public abstract void checkUp()
                      throws QueryException

Checks if the updating semantics are satisfied. This function is only called if any updating expression was found in the query.

Throws:

QueryException - query exception

compile

public abstract Expr compile(CompileContext cc)
                      throws QueryException

Compiles and optimizes the expression, assigns types and cardinalities.

Parameters:

cc - compilation context

Returns:

optimized expression

Throws:

QueryException - query exception

optimize

public Expr optimize(CompileContext cc)
              throws QueryException

Optimizes an already compiled expression without recompiling its sub-expressions.

Parameters:

cc - compilation context

Returns:

optimized expression

Throws:

QueryException - query exception

iter

public abstract Iter iter(QueryContext qc)
                   throws QueryException

Evaluates the expression and returns an iterator on the resulting items. The implementation of this method is optional.

Parameters:

qc - query context

Returns:

iterator

Throws:

QueryException - query exception

value

public abstract Value value(QueryContext qc)
                     throws QueryException

Evaluates the expression and returns the resulting value. If this method is not implemented, item(QueryContext, InputInfo) must be implemented instead.

Parameters:

qc - query context

Returns:

value

Throws:

QueryException - query exception

item

public abstract Item item(QueryContext qc,
                          InputInfo ii)
                   throws QueryException

Evaluates the expression and returns the resulting item, or Empty.VALUE if the expression yields an empty sequence. If this method is not implemented, value(QueryContext) must be implemented instead.

Parameters:

qc - query context

ii - input info (only required by Seq instances, which have no input info)

Returns:

item or Empty.VALUE

Throws:

QueryException - query exception

atomIter

public Iter atomIter(QueryContext qc,
                     InputInfo ii)
              throws QueryException

Evaluates the expression and returns an iterator on the resulting, atomized items.

Parameters:

qc - query context

ii - input info

Returns:

iterator

Throws:

QueryException - query exception

atomItem

public Item atomItem(QueryContext qc,
                     InputInfo ii)
              throws QueryException

Evaluates the expression and returns the resulting, atomized item, or Empty.VALUE if the expression yields an empty sequence.

Parameters:

qc - query context

ii - input info (only required by Seq instances, which have no input info)

Returns:

item or Empty.VALUE

Throws:

QueryException - query exception

atomValue

public abstract Value atomValue(QueryContext qc,
                                InputInfo ii)
                         throws QueryException

Evaluates the expression and returns the atomized items.

Parameters:

qc - query context

ii - input info (only required by Seq instances, which have no input info)

Returns:

atomized item

Throws:

QueryException - query exception

ebv

public abstract Item ebv(QueryContext qc,
                         InputInfo ii)
                  throws QueryException

Checks if the effective boolean value can be computed for this expression:

• If it yields an empty sequence, Bln.FALSE will be returned.
• If it yields a single item, this item will be returned.
• If it yields nodes, the first node will be returned.
• Otherwise, an error will be raised.

A single numeric item may later be evaluated as positional predicate.

Parameters:

qc - query context

ii - input info (required for Seq instances, which have no input info)

Returns:

item

Throws:

QueryException - query exception

test

public abstract Item test(QueryContext qc,
                          InputInfo ii)
                   throws QueryException

Performs a predicate test and returns the item if the test was successful. The returned item is required for full-text scoring.

Parameters:

qc - query context

ii - input info (required for Seq instances, which have no input info)

Returns:

item or null

Throws:

QueryException - query exception

vacuous

public boolean vacuous()

Tests if this is a vacuous expression (empty sequence or error function). This check is needed for updating queries.

Returns:

result of check

data

public Data data()

Returns the data reference bound to this expression. This method is currently overwritten by DBNode, DBNodeSeq, AxisPath and VarRef.

Returns:

data reference (can be null)

size

public abstract long size()

Returns the result size, or -1 if the size is unknown.

Returns:

result of check

has

public abstract boolean has(Flag... flags)

Indicates if an expression has one of the specified compiler properties. This method must only be called at compile time. It is invoked to test properties of sub-expressions. It returns true if at least flag matches an expression.

Parameters:

flags - flags to be checked

Returns:

result of check

uses

public final boolean uses(Var var)

Checks if the given variable is used by this expression.

Parameters:

var - variable to be checked

Returns:

true if the variable is used

inlineable

public abstract boolean inlineable(InlineContext ic)

Checks if inlining is possible. This function is called by InlineContext.inlineable(org.basex.query.expr.Expr...) and: CNode.inlineable(org.basex.query.InlineContext) returns false if the new expression construct new nodes. The following tests might reject inlining if the expression is a context reference:

• Preds.inlineable(org.basex.query.InlineContext)
• Path.inlineable(org.basex.query.InlineContext)
• SimpleMap.inlineable(org.basex.query.InlineContext)
• StaticJavaCall.inlineable(org.basex.query.InlineContext)
• TransformWith.inlineable(org.basex.query.InlineContext)

Parameters:

ic - inlining context

Returns:

result of check

count

public abstract VarUsage count(Var var)

Checks how often a variable or context reference is used in this expression. This function is called by:

• Closure.optimize(org.basex.query.CompileContext)
• GFLWOR.inlineForLet(org.basex.query.CompileContext)
• GFLWOR.optimizePos(org.basex.query.CompileContext)
• GFLWOR.simplify(org.basex.query.CompileContext)
• GFLWOR.unusedVars(org.basex.query.CompileContext)
• SimpleMap.optimize(org.basex.query.CompileContext)
• TypeswitchGroup.optimize(org.basex.query.CompileContext)

Parameters:

var - variable (Var reference) or context (null) to inline

Returns:

number of usages, see VarUsage

inline

public abstract Expr inline(InlineContext ic)
                     throws QueryException

Inlines an expression into this one, replacing all variable or context references. This function is called by InlineContext.inline(Expr) (see invocations of these functions for further inlinings). The variable reference is replaced in:

• OrderBy.inline(org.basex.query.InlineContext)
• VarRef.inline(org.basex.query.InlineContext)

The context is replaced in:

• ContextFn.inline(org.basex.query.InlineContext)
• ContextValue.inline(org.basex.query.InlineContext)
• Arr.inline(org.basex.query.InlineContext)

Parameters:

ic - inlining context

Returns:

resulting expression if something has changed, null otherwise

Throws:

QueryException - query exception

copy

public abstract Expr copy(CompileContext cc,
                          IntObjMap<Var> vm)

Copies an expression. Used for inlining functions, or for copying static queries. It is utilized by VarRef.inline(org.basex.query.InlineContext), FuncItem.inline(org.basex.query.expr.Expr[], org.basex.query.CompileContext), Closure.inline(org.basex.query.InlineContext) and StaticFunc.inline(org.basex.query.expr.Expr[], org.basex.query.CompileContext).

Parameters:

cc - compilation context

vm - mapping from old variable IDs to new variable copies. Required by Closure.copy(org.basex.query.CompileContext, org.basex.util.hash.IntObjMap<org.basex.query.var.Var>) and VarRef.copy(org.basex.query.CompileContext, org.basex.util.hash.IntObjMap<org.basex.query.var.Var>)

Returns:

copied expression

simplifyFor

public Expr simplifyFor(CompileContext.Simplify mode,
                        CompileContext cc)
                 throws QueryException

Simplifies the expression. Overwritten by many expressions; calls simplify(Simplify, CompileContext) otherwise.

Parameters:

mode - mode of simplification

cc - compilation context

Returns:

simplified or original expression

Throws:

QueryException - query exception

See Also:

CompileContext.Simplify

simplify

public final Expr simplify(CompileContext.Simplify mode,
                           CompileContext cc)
                    throws QueryException

Simplifies the expression.

Parameters:

mode - mode of simplification

cc - compilation context

Returns:

simplified or original expression

Throws:

QueryException - query exception

See Also:

CompileContext.Simplify

seqType

public abstract SeqType seqType()

Returns the static type of the resulting value.

Returns:

result of check

funcType

public FuncType funcType()

Returns the function type of this expression.

Returns:

function type, or null if expression yields no functions

ddo

public boolean ddo()

Indicates if this expression returns items in document order without duplicates.

Returns:

result of check

args

public Expr[] args()

Returns the arguments/operands of an expression (function, list, etc).

Returns:

arguments or null

arg

public final Expr arg(int i)

Returns the specified argument/operand of an expression (function, list, etc).

Parameters:

i - index of argument

Returns:

arguments or null

optimizePos

public Expr optimizePos(CmpV.OpV op,
                        CompileContext cc)
                 throws QueryException

Optimizes an expression for positional access. Overwritten by Int, Range, RangeSeq}.

Parameters:

op - comparison operator

cc - compilation context

Returns:

boolean result, optimized or original expression

Throws:

QueryException - query exception

indexAccessible

public boolean indexAccessible(IndexInfo ii)
                        throws QueryException

Checks if an expression can be rewritten to an index access. If so, the index expression will be bound to IndexInfo.expr. This method will be called by the Path expression.

Parameters:

ii - index info

Returns:

true if an index can be used

Throws:

QueryException - query exception

isSimple

public final boolean isSimple()

Checks if this expression is deterministic, performs no updates, does not access the context value and position, and calls no higher-order function.

Returns:

result of check

hasFreeVars

protected boolean hasFreeVars()

Checks if this expression has free variables.

Returns:

true if there are variables which are used but not declared in this expression, false otherwise

mergeEbv

public Expr mergeEbv(Expr expr,
                     boolean or,
                     CompileContext cc)
              throws QueryException

Tries to merge two expressions that are part of an EBV test. Called by And, Or), Step and Filter. Overwritten by CmpG, CmpIR, CmpR, CmpSR, IntPos, SimplePos and others.

Parameters:

expr - second expression

or - union or intersection

cc - compilation context

Returns:

optimized expression or null

Throws:

QueryException - query exception

markTailCalls

public void markTailCalls(CompileContext cc)

Finds and marks tail calls, enabling TCO.

Parameters:

cc - compilation context, null if the changes should not be reported

accept

public abstract boolean accept(ASTVisitor visitor)

Traverses this expression, notifying the visitor of declared and used variables, and checking the tree for other recursive properties.

Parameters:

visitor - visitor

Returns:

if the walk should be continued

visitAll

protected static boolean visitAll(ASTVisitor visitor,
                                  Expr... exprs)

Visit all given expressions with the given visitor.

Parameters:

visitor - visitor

exprs - expressions to visit

Returns:

success flag

exprSize

public abstract int exprSize()

Counts the number of expressions in this expression's subtree. This method is e.g. called by StaticFunc.inline(org.basex.query.expr.Expr[], org.basex.query.CompileContext) to check if an expression is small enough to be inlined.

Returns:

number of expressions

refineType

public abstract void refineType(Expr expr)

Refines the expression type.

Parameters:

expr - original expression

typeCheck

protected Expr typeCheck(TypeCheck tc,
                         CompileContext cc)
                  throws QueryException

Tries to push the given type check inside this expression.

Parameters:

tc - type check to push into the expression

cc - compilation context

Returns:

the resulting expression if successful, null otherwise

Throws:

QueryException - query exception

equals

public abstract boolean equals(Object obj)

This function is e.g. called by:

• If.optimize(CompileContext), Switch.optimize(CompileContext), Typeswitch.optimize(CompileContext), in order to discard identical expressions.
• CmpR.mergeEbv(Expr, boolean, CompileContext) or CmpSR.mergeEbv(Expr, boolean, CompileContext), in order to merge expressions with identical input.
• CmpG.optimize(CompileContext) or CmpV.optimize(CompileContext), in order to pre-evaluate equality tests.
• CmpG.optimize(CompileContext), in order to compare the start and end value.
• PathCache, in order to find identical root values at runtime.

Overrides:

equals in class Object