Patternist: Patternist::Expression Class Reference

More specifically, ExpressionFactory::createExpression() is called with a pointer to a static context, and the string for the expression. This is subsequently tokenized by a Flex scanner. Mistakes detected at this stage is syntax errors, as well as a few semantical errors. Syntax errors can be divided in two types:

Apart from the syntax errors, the actions in the parser also detects errors when creating the corresponding expressions. This is for example that no namespace binding for a prefix could be found, or that a function call was used which no function implementation could be found for.

When the parser has finished, the result is an AST. That is, a hierarchical structure consisting of Expression sub-classes. The individual expressions haven't at this point done anything beyond receiving their child-expressions(if any), and hence reminds of a "construction scaffold". In other words, a tree for the expression 'string' + 1 and xs:date('2001-03-13') could have been created, even if that expression contains errors(one can't add a xs:integer to a xs:string, and the Effective Boolean Value cannot be extracted for date types).

Type Checking

Compressing -- Optimization and Fixup

One such is const folding, which while being an efficient optimization, also is a necessity for many XSL-T constructs. Another important step is that functions which had an evaluation dependency on the static context(as opposed to the dynamic) performs their "fixup".

In other words, this stage potentially performs AST re-writes. For example, the expression 3 + 3, concat('foo', '-', 'bar'), true() and false() would result in an AST corresponding to 6, 'foo-bar', false(). This process is done backwards; each expression asks its operands to compress before it performs its own compression(and so forth, until the root expression's call returns to the caller).

Member Typedef Documentation

typedef QList<Expression::Ptr> Patternist::Expression::List

A list of Expression instances, each wrapped in a smart pointer.

Reimplemented in Patternist::UserFunctionCallsite, and Patternist::VariableReference.

Definition at line 133 of file Expression.h.

typedef QFlags<Property> Patternist::Expression::Properties

A QFlags template for type-safe handling of ExpressionProperty values. If Expression::Property flags needs to be stored in a class, declared the variable to be of type Expression::Properties.

See also:: QFlags

Definition at line 280 of file Expression.h.

typedef PlainSharedPtr<Expression> Patternist::Expression::Ptr

A smart pointer wrapping Expression instances.

Reimplemented in Patternist::AxisStep, Patternist::PositionalVariableReference, Patternist::UserFunctionCallsite, Patternist::VariableReference, and Patternist::FunctionCall.

Definition at line 128 of file Expression.h.

typedef QVector<Expression::Ptr> Patternist::Expression::Vector

A vector of Expression instances, each wrapped in a smart pointer.

Definition at line 138 of file Expression.h.

Member Enumeration Documentation

enum Patternist::Expression::ID

Enumerators that identifies Expression sub-classes.

See also:: id()

Enumerator:

IDBooleanValue	Identifies Boolean.
IDCountFN	Identifies CountFN.
IDEmptyFN	Identifies EmptyFN.
IDExistsFN	Identifies ExistsFN.
IDExpressionSequence	Identifies ExpressionSequence and LiteralSequence.
IDGeneralComparison	Identifies GeneralComparison.
IDIfThenClause	Identifies IfThenClause.
IDIgnorableExpression	Identifies nothing in particular. The default implementation of id() returns this, which is suitable for Expression instances which never needs to be identified in this aspect.
IDIntegerValue	Identifies Integer.
IDPositionFN	Identifies PositionFN.
IDStringValue	Identifies String, AnyURI, and UntypedAtomic.
IDValueComparison	Identifies ValueComparison.
IDRangeVariableReference	Identifies VariableReference.
IDContextItem	Identifies ContextItem.
IDUserFunctionCallsite	Identifies UserFunctionCallsite.
IDExpressionVariableReference	Identifies ExpressionVariableReference.
IDAttributeConstructor	Identifies ExpressionVariableReference.
IDUpperCaseFN	Identifies UpperCaseFN.
IDLowerCaseFN	Identifies LowerCaseFN.
IDFirstItemPredicate	Identifies FirstItemPredicate.

Definition at line 287 of file Expression.h.

enum Patternist::Expression::Property

Enum flags describing the characteristics of the expression.

See also:: Expression::properties()

Enumerator:

UseContextItem	This flag applies for functions, and results in the expression `.` being appended to its operands if its operand count is lower than the maximum amount of arguments. In effect, it result in a modification of the function's arguments to have appended the context item. One function which has this property is `fn:number()`. See also: ContextItem XQuery 1.0 and XPath 2.0 Functions and Operators, 1.3 Function Signatures and Descriptions
DisableElimination	Disables compression(evaluation at compile time), such that the Expression isn't const-folded, but ensured to be run at runtime. The operands are still attempted to be compressed, unless they override compression as well. See also: compress()
IsEvaluated	Signals that the expression is already evaluated and can be considered a constant value. For example, atomic values return this flag in their implementations of the properties() functions. See also: isEvaluated()
DisableTypingDeduction	Signals that the expression cannot be optimized away by judging its static type. This is currently used for properly handling the `none` type, in the `fn:error()` function. In type operations, the none type doesn't show up and that can make expressions, such as InstanceOf, believe it is safe to const fold, while it in fact is not.
EmptynessFollowsChild	This property affects the static type -- staticType() -- of an expression. It is implemented in FunctionCall::staticType() and therefore only work for FunctionCall sub-classes and when that function is not re-implemented in an inhibiting way. When set, the cardinality of the static type is zero if the Expression's first operand allows an empty sequence, otherwise it is the cardinality of the Expression's static type modulo Cardinality::empty(). This is used for specifying proper static type inference for functions that have "If $arg is the empty sequence, the empty sequence is returned." However, before setting this property one must be aware that no other conditions can lead to the empty sequence, since otherwise the static type would be wrong.
RewriteToEmptyOnEmpty	This is similar to EmptynessFollowsChild, and also implemented in FunctionCall. When set, it makes FunctionCall::typeCheck() rewrite itself into an empty sequence if the first operand is the empty sequence. This property is often used together with EmptynessFollowsChild.
RequiresFocus	When set, it signals that the focus cannot be undefined. For example, the `fn:position()` function extracts information from the focus. Setting this flag ensures type checking is carried out appropriately. However, setting RequiresFocus does not imply this Expression requires the context item to be defined. It only means the focus, of somekind, needs to be defined. See also: RequiresContextItem
IsNodeConstructor	Signals that the Expression constructs nodes, either directly or computationally. For example, AttributeConstructor has this property set.
AffectsOrderOnly	An Expression with this Property set, signals that it only affects the order of its return value.
RequiresContextItem	When set, signals that the context item, must be defined for this Expression. When setting this property, expectedContextItemType() must be re-implemented. Setting this property also sets RequiresFocus. See also: DynamicContext::contextItem()
CreatesFocusForLast	When set, signals that this expression creates a focus for its last operand. When set, newContextItemType() must be overriden to return the static type of the context item.
LastOperandIsCollation	Signals that the last operand is a collation argument. This ensures that the necessary code is generated for checking that the collation is supported. This only applies to sub-classes of FunctionCall

Definition at line 148 of file Expression.h.

Member Function Documentation

Expression::Ptr Expression::compress ( const StaticContext::Ptr & context ) [virtual]

compress() is the last stage performs in compiling an expression, done after the initial AST build and calling typeCheck(). compress() performs crucial simplifications, either by having drastic performance implications or that some expressions depend on it for proper behavior.

The default implementation performs a sparse conditional constant propagation. In short, a recursive process is performed in the AST which examines if the Expression's operands are constant values, and if so, performs a const fold(AST rewrite) into the result of evaluating the expression in question. This default behavior can be disabled by letting properties() return DisableElimination.

This compress() stage can be relative effective due to the design of XPath, in part because intrinsic functions are heavily used. Many Expressions override compress() and do optimizations specific to what they do. Also, many Expressions performs optimizations in the typeCheck().

Parameters:

context

the static context. Supplies compile time information, and is the channel for communicating error messages.

Wikipedia, the free encyclopedia, Intrinsic function

Wikipedia, the free encyclopedia, Compiler optimization

Definition at line 240 of file Expression.cpp.

References compressOperands(), DisableElimination, and has().

Here is the call graph for this function:

Here is the caller graph for this function:

virtual bool Patternist::Expression::compressOperands ( const StaticContext::Ptr & ) [protected, pure virtual]

Returns:: true if all operands are constant values of somekind, and are already evaluated. A string literal, is a typical example.

Referenced by compress().

Here is the caller graph for this function:

bool Expression::evaluateEBV ( const DynamicContext::Ptr & context ) const [virtual]

Determines the Effective Boolean Value of the expression.

The Effective Boolean Value of a value is not necessarily the same as converting the value to a new value of type xs:boolean.

The default implementation results in a type error. Hence, this function must be overriden if such behavior is not of interest.

See also:: XML Path Language (XPath) 2.0, 2.4.3 Effective Boolean Value

Definition at line 329 of file Expression.cpp.

References Patternist::Boolean::evaluateEBV(), and evaluateSequence().

Referenced by evaluateSingleton().

Here is the call graph for this function:

Here is the caller graph for this function:

Item::Iterator::Ptr Expression::evaluateSequence ( const DynamicContext::Ptr & context ) const [virtual]

Evaluate this Expression by iterating over it. This is a central function for evaluating expressions.

Expressions must always always return a valid Iterator and may never return 0. If an empty result is of interest to be returned, the EmptyIterator should be returned.

The default implementation returns a SingletonIterator over the item returned from evaluateSingleton().

Definition at line 314 of file Expression.cpp.

References Patternist::CommonValues::emptyIterator, and evaluateSingleton().

Referenced by evaluateEBV(), and evaluateToSequenceReceiver().

Here is the call graph for this function:

Here is the caller graph for this function:

Item::Ptr Expression::evaluateSingleton ( const DynamicContext::Ptr & context ) const [virtual]

Todo:: Docs

Definition at line 324 of file Expression.cpp.

References evaluateEBV(), and Patternist::Boolean::fromValue().

Referenced by evaluateSequence().

Here is the call graph for this function:

Here is the caller graph for this function:

void Expression::evaluateToSequenceReceiver ( const DynamicContext::Ptr & context ) const [virtual]

Evaluates this Expression by sending its output to DynamicContext::outputReceiver().

Definition at line 334 of file Expression.cpp.

References evaluateSequence().

Here is the call graph for this function:

ItemType::Ptr Expression::expectedContextItemType ( ) const [virtual]

Returns the required type the context item must be an instance of.

If this Expression requires a focus, meaning its properties() function returns RequiresContextItem, it must return a type from this function. If any type is ok, BuiltinTypes::item should be returned.

In other words, this function must only be re-implemented if the focus is used. The default implementation performs an assert crash.

Reimplemented in Patternist::AxisStep, Patternist::ContextItem, and Patternist::ParentNodeAxis.

Definition at line 347 of file Expression.cpp.

virtual SequenceType::List Patternist::Expression::expectedOperandTypes ( ) const [pure virtual]

Returns a list of Sequence Types, describing the type of each of the expression's operands. Hence, this function has a relationship to the operands() function:

The lengths of the lists returned by expectedOperandTypes() and operands() should always be equal in length, since one cannot describe the type of an non-existant operand(and all operands must have type information).
A significant difference between the two functions is that while the type of objects in the list returned by operands() may vary between compilations/static context, simply because the particular Expression is part of different XPath expressions, the types in the list returned by expectedOperandTypes is always the same since the function/operator signature never changes.

This function should not be confused with staticType(), which returns the static type of the expression itself, not its operands. The function call is an expression where this is clear: the type of the return value is not the same as the arguments' types. The static type of the operands supplied to the expression can be determined via the staticType() function of the instances returned by operands().

If the expression has no operands, an empty list should be returned.

Referenced by typeCheckOperands().

Here is the caller graph for this function:

bool Patternist::Expression::has ( const Property prop ) const [inline]

Determines whether this Expression has Property prop set.

Calling expr->has(MyProperty) is semantically equivalent to (expr->properties() & MyProperty) == MyProperty. In other words, has(), as well as is(), provides syntacti sugar and makes code more readable.

Note:: Do not attempt to re-implement this function. Instead, return the appropriate flag by re-implementing the properties() function.

Definition at line 691 of file Expression.h.

References properties().

Referenced by compress(), Patternist::FunctionCall::staticType(), Patternist::FunctionCall::typeCheck(), and typeCheckOperands().

Here is the call graph for this function:

Here is the caller graph for this function:

Expression::ID Expression::id ( ) const [virtual]

This property, which has no setter, returns an enum value that uniquely identifies this Expression. Patternist makes no use of C++'s dynamic_cast feature, but uses this polymorphic function instead.

Returns:: always IgnorableExpression.

Reimplemented in Patternist::AttributeConstructor, Patternist::ContextItem, Patternist::ExpressionSequence, Patternist::ExpressionVariableReference, Patternist::FirstItemPredicate, Patternist::GeneralComparison, Patternist::IfThenClause, Patternist::Literal, Patternist::LiteralSequence, Patternist::RangeVariableReference, Patternist::UserFunctionCallsite, Patternist::ValueComparison, and Patternist::FunctionCall.

Definition at line 359 of file Expression.cpp.

References IDIgnorableExpression.

bool Patternist::Expression::is ( const ID id ) const [inline]

This function is a utility function, syntactic sugar for determining whether this Expression is id. For example, calling is(IDIfThenClause) is equivalent to id() == IDIfThenClause

Note:: Do not attempt to re-implement this function. Instead, return the appropriate flag in the virtual id() function.

Definition at line 681 of file Expression.h.

Referenced by Patternist::NodeComparison::evaluateEBV().

Here is the caller graph for this function:

bool Patternist::Expression::isEvaluated ( ) const [inline]

This function is a utility function, which performs bitwise logic on properties() in order to find out whether the Expression::IsEvaluated flag is set.

Note:: Do not attempt to re-implement this function. Instead, return the IsEvaluated flag by re-implementing the properties() function.

Definition at line 686 of file Expression.h.

References IsEvaluated, and properties().

Here is the call graph for this function:

ItemType::Ptr Expression::newContextItemType ( ) const [protected, virtual]

If an Expression creates a focus because it has set the property CreatesFocusForLast, it should override this function and make it return the ItemType that the context item in the focus has.

Returns:: never null.

Reimplemented in Patternist::GenericPredicate, and Patternist::Path.

Definition at line 369 of file Expression.cpp.

virtual Expression::List Patternist::Expression::operands ( ) const [pure virtual]

Returns:: the expression's child expressions. For example, a function's arguments is returned here.

If this Expression has no operands, an empty list should be returned.

Implemented in Patternist::EmptyContainer, Patternist::PairContainer, Patternist::SingleContainer, Patternist::TripleContainer, and Patternist::UnlimitedContainer.

Referenced by typeCheckOperands().

Here is the caller graph for this function:

OptimizationPass::List Expression::optimizationPasses ( ) const [virtual]

Returns the OptimizationPasses that applies for this Expression. The default implementation returns an empty list. Sub-classes can re-implement this function and return actual OptimizationPasses.

Returns:: always an empty list.

Reimplemented in Patternist::ForClause, Patternist::GeneralComparison, Patternist::IfThenClause, Patternist::ValueComparison, and Patternist::NotFN.

Definition at line 364 of file Expression.cpp.

Expression::Properties Expression::properties ( ) const [virtual]

Returns:: a bitwise OR'd value of properties, describing the characteristics of the expression. These properties affects how this Expression is treated in for example type checking stages.

The default implementation returns 0. Override and let the function return a different value, if that's of interest.

Returns:: Expression::None, meaning no special properties

Reimplemented in Patternist::AttributeConstructor, Patternist::AxisStep, Patternist::CommentConstructor, Patternist::ContextItem, Patternist::DocumentConstructor, Patternist::ElementConstructor, Patternist::ExpressionSequence, Patternist::ExternalVariableReference, Patternist::GenericPredicate, Patternist::Literal, Patternist::ParentNodeAxis, Patternist::Path, Patternist::ProcessingInstructionConstructor, Patternist::RangeExpression, Patternist::TextNodeConstructor, Patternist::UserFunctionCallsite, Patternist::VariableReference, and Patternist::FunctionCall.

Definition at line 354 of file Expression.cpp.

Referenced by has(), and isEvaluated().

Here is the caller graph for this function:

void Expression::rewrite	(	Expression::Ptr &	old,
		const Expression::Ptr &	New
	)			const

This function take the two Expression pointers old and New, and in a safe way, by handling reference counting and being aware of whether the two pointers actually are different, switches the two. When compiling in debug mode, informative debug messages are printed.

This function can be said to be similar to Qt's qSwap() function.

Definition at line 302 of file Expression.cpp.

Referenced by Patternist::UnlimitedContainer::compressOperands(), Patternist::TripleContainer::compressOperands(), Patternist::SingleContainer::compressOperands(), and Patternist::PairContainer::compressOperands().

Here is the caller graph for this function:

virtual SequenceType::Ptr Patternist::Expression::staticType ( ) const [pure virtual]

Returns:: the static type of this Expression. For example, an 'and' expression have as static type xs:boolean

Expression::Ptr Expression::typeCheck	(	const StaticContext::Ptr &	context,
		const SequenceType::Ptr &	reqType
	)			`[virtual]`

This implementation guarantees to never rewrite away this Expression, but at most rewrite it as a child of another expression(that presumably have a type checking role). It is therefore always safe to override this function and call this implementation and not worry about that this Expression becomes deleted.

Many Expressions override typeCheck() and performs optimizations, as opposed to doing it in the compress() stage. This is due to that the design of those Expressions often are tied to that certain simplifications are done at the typeCheck() stage of the compilation process or that it in some other way is related to what the typeCheck() do. Also, the earlier the AST can be simplified, the better the chances are for subsequent optimizations.

A typical typeCheck() reimplementation looks like this:

Expression::Ptr MyExpression::typeCheck(const StaticContext::Ptr &context,
                                        const SequenceType::Ptr &reqType)
{
    // Here we call the super class's typeCheck() function. In this example
    // it is SingleContainer.
    const Expression::Ptr me(EmptyContainer::typeCheck(context, reqType));

    // Do type checks specific to MyExpression

     return me;
}

It is important that the super class's typeCheck() is called before doing any custom type checking, since the call can change the children(notably, the childrens' static types). For example, if the Expression, MyExpression in the example, does not match the required type, typeCheck returns the Expression wrapped in for example ItemVerifier, CardinalityVerifier, or both.

typeCheck() may be called many times. typeCheck() must either raise an error if this Expression is an invalid expression. Thus, it is guaranteed that an Expression is valid after typeCheck() is called.

Parameters:

	context	supplies information, such as namespace bindings and available function signatures, that can be needed at compilation time. `context` is never null.
	reqType	the static type that this Expression must match when evaluated. `reqType` is never null.

Returns:: an Expression that can be this Expression, or another expression, which somehow is necessary for making this Expression conforming to reqType

Definition at line 54 of file Expression.cpp.

References Patternist::TypeChecker::applyFunctionConversion(), and typeCheckOperands().

Here is the call graph for this function:

Here is the caller graph for this function:


Public Types
enum	ID { IDBooleanValue = 1, IDCountFN = 2, IDEmptyFN = 4, IDExistsFN = 8, IDExpressionSequence = 16, IDGeneralComparison = 32, IDIfThenClause = 64, IDIgnorableExpression = 128, IDIntegerValue = 256, IDPositionFN = 512, IDStringValue = 1024, IDValueComparison = 2048, IDRangeVariableReference = 4096, IDContextItem = 8192, IDUserFunctionCallsite = 16384, IDExpressionVariableReference = 32768, IDAttributeConstructor = 65536, IDUpperCaseFN = 131072, IDLowerCaseFN = 262144, IDFirstItemPredicate = 524288 }
typedef QFlags< ID >	IDs
typedef Iterator< Expression::Ptr >	Iterator
typedef QList< Expression::Ptr >	List
typedef ListIterator< Expression::Ptr >	ListIterator
typedef QFlags< Property >	Properties
enum	Property { UseContextItem = 1, DisableElimination = 2, IsEvaluated = 4, DisableTypingDeduction = 8, EmptynessFollowsChild = 16, RewriteToEmptyOnEmpty = 32, RequiresFocus = 64, IsNodeConstructor = 128, AffectsOrderOnly = 256, RequiresContextItem = 512 \| RequiresFocus, CreatesFocusForLast = 1024, LastOperandIsCollation = 2048 }
typedef PlainSharedPtr< Expression >	Ptr
typedef QVector< Expression::Ptr >	Vector
Public Member Functions
virtual ExpressionVisitorResult::Ptr	accept (const ExpressionVisitor::Ptr &visitor) const=0
virtual Expression::Ptr	compress (const StaticContext::Ptr &context)
virtual bool	evaluateEBV (const DynamicContext::Ptr &context) const
virtual Item::Iterator::Ptr	evaluateSequence (const DynamicContext::Ptr &context) const
virtual Item::Ptr	evaluateSingleton (const DynamicContext::Ptr &context) const
virtual void	evaluateToSequenceReceiver (const DynamicContext::Ptr &context) const
virtual ItemType::Ptr	expectedContextItemType () const
virtual SequenceType::List	expectedOperandTypes () const=0
	Expression ()
bool	has (const Property prop) const
virtual ID	id () const
bool	is (const ID id) const
bool	isEvaluated () const
virtual Expression::List	operands () const=0
virtual QList< PlainSharedPtr< OptimizationPass > >	optimizationPasses () const
virtual Properties	properties () const
void	rewrite (Expression::Ptr &old, const Expression::Ptr &New) const
virtual void	setOperands (const Expression::List &operands)=0
virtual SequenceType::Ptr	staticType () const=0
virtual Expression::Ptr	typeCheck (const StaticContext::Ptr &context, const SequenceType::Ptr &reqType)
virtual	~Expression ()
Protected Member Functions
virtual bool	compressOperands (const StaticContext::Ptr &)=0
virtual ItemType::Ptr	newContextItemType () const
virtual void	typeCheckOperands (const StaticContext::Ptr &context)

Patternist::Expression Class Reference
[Expressions]

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Expression Compilation

The process of creating an Expression

Type Checking

Compressing -- Optimization and Fixup

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation

Patternist::Expression Class Reference [Expressions]

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Expression Compilation

The process of creating an Expression

Type Checking

Compressing -- Optimization and Fixup

Member Typedef Documentation

Member Enumeration Documentation

Member Function Documentation

Patternist::Expression Class Reference
[Expressions]