## Package net.sf.saxon.expr

This package provides classes associated with XPath expression handling.

See:
Description

Interface Summary
Binding: Binding is a interface used to represent the run-time properties and methods associated with a variable: specifically, a method to get the value of the variable.
BindingReference: BindingReference is a interface used to mark references to a variable declaration.
Container: A Container is something that can act as the parent of an expression.
Expression: Interface supported by an XPath expression.
LastPositionFinder: A LastPositionFinder is an interface implemented by any SequenceIterator that is able to return the position of the last item in the sequence.
MappingFunction: MappingFunction is an interface that must be satisfied by an object passed to a MappingIterator.
ReversibleIterator: A ReversibleIterator is an interface implemented by any SequenceIterator that is able to deliver items in reverse order (or to supply another iterator that can do so).
StaticContext: A StaticContext contains the information needed while an expression or pattern is being parsed.
VariableDeclaration: Generic interface representing a variable declaration in the static context of an XPath expression.
XPathContext: This class represents a context in which an XPath expression is evaluated.

Class Summary
AppendIterator: Iterator that concatenates the results of two supplied iterators
ArithmeticExpression.DateAndDuration: Inner class to handle addition or subtraction of a Date (or Time, or DateTime) and a Duration
ArithmeticExpression.DateDifference: Inner class to handle subtraction of a Date (or Time, or DateTime) from another, to return a Duration
ArithmeticExpression.DurationAddition: Inner class to handle addition and subtraction of two durations
ArithmeticExpression.DurationDivision: Inner class to handle division of two durations to give a number
ArithmeticExpression.DurationMultiplication: Inner class to handle multiplication (or division) of a duration by a number
ArithmeticExpression.NumericArithmetic: Inner class to handle numeric arithmetic expressions
Assignation: Assignation is an abstract superclass for the kinds of expression that declare range variables: for, some, and every.
AtomicSequenceConverter: An AtomicSequenceConverter is an expression that performs a cast on each member of a supplied sequence
Atomizer: An Atomizer is an expression corresponding essentially to the fn:data() function: it maps a sequence by replacing nodes with their typed values
Atomizer.AtomizingFunction: Implement the mapping function
AxisExpression: An AxisExpression is always obtained by simplifying a PathExpression.
BinaryExpression: Binary Expression: a numeric or boolean expression consisting of the two operands and an operator
CardinalityChecker: A CardinalityChecker implements the cardinality checking of "treat as": that is, it returns the supplied sequence, checking that its cardinality is correct
CastableExpression: Castable Expression: implements "Expr castable as atomic-type?".
CastAsQName: This class supports casting a string to a QName or a notation.
CastExpression: Cast Expression: implements "cast as data-type ( expression )".
ComputedExpression: This class is an abstract superclass for different kinds of expression.
ContextItemExpression: This class represents the expression "(dot)", which always returns the context item.
DifferenceEnumeration: An enumeration representing a nodeset that is teh difference of two other NodeSets.
EagerLetExpression: An EagerLetExpression is the same as a LetExpression except that the variable is evaluated using eager evaluation rather than lazy evaluation.
ErrorExpression: Error expression: this expression is generated when the supplied expression cannot be parsed, and the containing element enables forwards-compatible processing.
ExpressionLocation: Class to hold details of the location of an expression, of an error in a source file, etc.
ExpressionParser: Parser for XPath expressions and XSLT patterns.
ExpressionParser.ForClause
ExpressionTool: This class, ExpressionTool, contains a number of useful static methods for manipulating expressions.
FilterExpression: A FilterExpression contains a base expression and a filter predicate, which may be an integer expression (positional filter), or a boolean expression (qualifier)
FilterIterator: A FilterIterator filters an input sequence using a filter expression.
FilterIterator.Leading: Subclass to support the extension function saxon:leading, which terminates the iteration at the first item whose predicate is false
FilterIterator.NonNumeric: Subclass to handle the common special case where it is statically known that the filter cannot return a numeric value
FirstItemExpression: A FirstItemExpression returns the first item in the sequence returned by a given base expression
ForExpression: A ForExpression maps an expression over a sequence.
FunctionCall: Abstract superclass for calls to system-defined and user-defined functions
GeneralComparison: GeneralComparison: a boolean expression that compares two expressions for equals, not-equals, greater-than or less-than.
GeneralComparison10: GeneralComparison10: a boolean expression that compares two expressions for equals, not-equals, greater-than or less-than.
IdentityComparison: IdentityComparison: a boolean expression that compares two nodes for equals, not-equals, greater-than or less-than based on identity and document ordering
IfExpression: An IfExpression returns the value of either the "then" part or the "else" part, depending on the value of the condition
InstanceOfExpression: InstanceOf Expression: implements "Expr instance of data-type"
IntegerRangeTest: An IntegerRangeTest is an expression of the form E = N to M where E, N, and M are all expressions of type integer.
IntersectionEnumeration: An enumeration representing a nodeset that is an intersection of two other NodeSets.
IsLastExpression: A position() eq last() expression, generated by the optimizer.
ItemChecker: A ItemChecker implements the item type checking of "treat as": that is, it returns the supplied sequence, checking that all its items are of the correct type
LetExpression: A LetExpression is modelled on the XQuery syntax let $x := expr return expr.
MappingIterator: MappingIterator merges a sequence of sequences into a single flat sequence.
MinimaxComparison: Class to handle many-to-many A less-than B comparisons by evaluating min(A) < max(B), and similarly for greater-than, etc.
MonoIterator: An iterator over a single object (typically a sub-expression of an expression)
MultiIterator: An iterator that combines the results of a sequence of iterators
NumericPromoter: A NumericPromoter performs numeric promotion on each item in a supplied sequence
Optimizer: This class doesn't actually do any optimization itself, despite the name.
PairIterator: An iterator over a pair of objects (typically sub-expressions of an expression)
ParentNodeExpression: Class ParentNodeExpression represents the XPath expression ".." or "parent::node()"
PathExpression: An expression that establishes a set of nodes by following relationships between nodes in the document.
PositionIterator: A PositionIterator selects a subsequence of a sequence
PositionRange: PositionRange: a boolean expression that tests whether the position() is within a certain range.
PromotionOffer: PromotionOffer is an object used transiently during compilation of an expression.
RangeExpression: A RangeExpression is an expression that represents an integer sequence as a pair of end-points (for example "x to y").
RangeExpression.RangeIterator: Iterator that produces numeric values in a monotonic sequence, ascending or descending
RangeVariableDeclaration: Represents the defining occurrence of a variable declared for local use within an expression, for example the $x in "for $x in ...".
RoleLocator: A RoleLocator identifies the role in which an expression is used, for example as the third argument of the concat() function.
RootExpression: An expression whose value is always a set of nodes containing a single node, the document root.
SimpleExpression: An abstract implementation of Expression designed to make it easy to implement new expressions, in particular, expressions to support extension instructions.
SimpleMappingExpression: A simple mapping expression is an expression A/B where B has a static type that is an atomic type.
SingleNodeExpression: A node set expression that will always return zero or one nodes
SingletonComparison: Class to handle comparisons of singletons.
StackFrame: This class represents a stack frame holding details of the variables used in a function or in an XSLT template.
StaticProperty: This class contains constants identifying dependencies that an XPath expression might have on its context.
StringTokenIterator: StringTokenIterator: breaks a string up into tokens, and returns the tokens as a sequence of strings.
SuppliedParameterReference: Supplied parameter reference: this is an internal expression used to refer to the value of the n'th parameter supplied on a template call (apply-templates).
TailExpression: A TailExpression represents a FilterExpression of the form EXPR[position() > n] Here n is usually 2, but we allow other values
TailExpression.TailIterator
Token: This class holds static constants and methods defining the lexical tokens used in XPath and XQuery, and associated keywords.
Tokenizer: Tokenizer for expressions and inputs.
TreatExpression: Treat Expression: implements "treat as data-type ( expression )".
TypeChecker: This class provides Saxon's type checking capability.
UnaryExpression: Unary Expression: an expression taking a single operand expression
UnionEnumeration: An enumeration representing a nodeset that is a union of two other NodeSets.
UntypedAtomicConverter: An UntypedAtomicConverter is an expression that converts any untypedAtomic items in a sequence to a specified type
UserFunctionCall: This class represents a call to a function defined in the stylesheet or query.
ValueComparison: ValueComparison: a boolean expression that compares two atomic values for equals, not-equals, greater-than or less-than.
VariableReference: Variable reference: a reference to a variable.
VennExpression: An expression representing a nodeset that is a union, difference, or intersection of two other NodeSets
XPathContextMajor: This class represents a "major context" in which an XPath expression is evaluated: a "major context" object allows all aspects of the dynamic context to change, whereas a "minor context" only allows changes to the focus and the destination for push output.
XPathContextMajor.XSLTContext: An XSLTContext object holds all the additional dynamic context items used in XSLT.
XPathContextMinor: This class represents a minor change in the dynamic context in which an XPath expression is evaluated: a "major context" object allows all aspects of the dynamic context to change, whereas a "minor context" only allows changes to the focus and the destination for push output.

## Package net.sf.saxon.expr Description

This package provides classes associated with XPath expression handling. Generally, these classes are not intended to be used directly by user-written applications; the API for XPath evaluation is now provided by classes in the package `net.sf.saxon.xpath`

The principal classes are:

Expression:
This represents an XPath Expression. There is a static method Expression.make() which is used to construct an Expression from a String (it is a factory method rather than a constructor, because it typically returns some subclass of Expression according to the syntax supplied). Subclasses of Expression represent different kinds of expression such as StringExpression and BooleanExpression. What they all have in common is an evaluate() method, which evaluates the expression in a given context to yield a Value, and an iterate() method, which treats the result of the expression as a sequence, and iterates over the items in the sequence.

ExpressionParser:
This class does the work of parsing both Expressions and Patterns. Applications should not call it directly. It uses the class Tokenizer for lexical analysis.

StaticContext:
This interface defines the information available at the time an expression is being parsed. This includes the names of variables, the bindings of namespace prefixes, the functions that are available, the names of collating sequences, and so on. When an XPath expression appears in a stylesheet, the class `net.sf.saxon.style.ExpressionContext` provides the StaticContext. For a free-standing XPath expression, the class `net.sf.saxon.xpath.StandaloneContext` is available, though a user-written class that implements `StaticContext` can also be used.

XPathContext:
This class defines the context information available at run-time, for example the context node, position, and size. (It actually does this by wrapping a SequenceIterator that represents the current sequence.) When expressions are used during an XSLT transformation, the XPathContext also provides access to the Controller, which contains all the context information about XSLT processing (for example the current template, the current group, and so on).

Most of the classes in this package represent individual syntactic constructs found in XPath or XQuery expressions: for example `ValueComparison`, `UserFunctionCall`, and `RootExpression`. The objects that instantiate these classes form the nodes on the Abstract Syntax Tree constructed by the compiler and modified by the optimizer; at run-time their methods are used to drive a pipelined evaluation of the expression.

The distinction between the compiled form of XSLT instructions and the compiled form of XPath expressions has become blurred. Generally, the compiled form of instructions is in the package `net.sf.saxon.instruct` (this includes expressions in XQuery that are equivalent to XSLT instructions, for example element constructors). However, some constructs such as conditional expressions now exist in both languages and may generate the same run-time constructs.

Michael H. Kay
Saxonica Limited
9 February 2005