source: trunk/src/xmlpatterns/expr/qexpression_p.h

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 36.8 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the QtXmlPatterns module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file. Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights. These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42//
43// W A R N I N G
44// -------------
45//
46// This file is not part of the Qt API. It exists purely as an
47// implementation detail. This header file may change from version to
48// version without notice, or even be removed.
49//
50// We mean it.
51
52#ifndef Patternist_Expression_H
53#define Patternist_Expression_H
54
55#include <QFlags>
56#include <QSharedData>
57
58#include "qcppcastinghelper_p.h"
59#include "qdebug_p.h"
60#include "qdynamiccontext_p.h"
61#include "qexpressiondispatch_p.h"
62#include "qitem_p.h"
63#include "qsequencetype_p.h"
64#include "qsourcelocationreflection_p.h"
65#include "qstaticcontext_p.h"
66
67QT_BEGIN_HEADER
68
69QT_BEGIN_NAMESPACE
70
71template<typename T> class QList;
72template<typename T> class QVector;
73
74namespace QPatternist
75{
76 template<typename T, typename ListType> class ListIterator;
77 class OptimizationPass;
78
79 /**
80 * @short Base class for all AST nodes in an XPath/XQuery/XSL-T expression.
81 *
82 * @section ExpressionCreation Expression Compilation
83 *
84 * @subsection ExpressionCreationParser The process of creating an Expression
85 *
86 * The initial step of creating an internal representation(in some circles
87 * called an IR tree) of the XPath string follows classic compiler design: a scanner
88 * is invoked, resulting in tokens, which sub-sequently are consumed by a parser
89 * which groups the tokens into rules, resulting in the creation of
90 * Abstract Syntax Tree(AST) nodes that are arranged in a hierarchical structure
91 * similar to the EBNF.
92 *
93 * More specifically, ExpressionFactory::createExpression() is called with a
94 * pointer to a static context, and the string for the expression. This is subsequently
95 * tokenized by a Flex scanner. Mistakes detected at this stage is syntax
96 * errors, as well as a few semantical errors. Syntax errors can be divided
97 * in two types:
98 *
99 * - The scanner detects it. An example is the expression "23Eb3" which
100 * is not a valid number literal, or "1prefix:my-element" which is not a
101 * valid QName.
102 * - The parser detects it. This means a syntax error at a
103 * higher level, that a group of tokens couldn't be reduced to a
104 * rule(expression). An example is the expression "if(a = b) 'match' else
105 * 'no match'"; the tokenizer would handle it fine, but the parser would
106 * fail because the tokens could not be reduced to a rule due to the token
107 * for the "then" word was missing.
108 *
109 * Apart from the syntax errors, the actions in the parser also detects
110 * errors when creating the corresponding expressions. This is for example
111 * that no namespace binding for a prefix could be found, or that a function
112 * call was used which no function implementation could be found for.
113 *
114 * When the parser has finished, the result is an AST. That is, a
115 * hierarchical structure consisting of Expression sub-classes. The
116 * individual expressions haven't at this point done anything beyond
117 * receiving their child-expressions(if any), and hence reminds of a
118 * "construction scaffold". In other words, a tree for the expression
119 * <tt>'string' + 1 and xs:date('2001-03-13')</tt> could have been created, even if
120 * that expression contains errors(one can't add a xs:integer to a xs:string,
121 * and the Effective %Boolean Value cannot be extracted for date types).
122 *
123 * @subsection ExpressionCreationTypeChecking Type Checking
124 *
125 * After the AST creation, ExpressionFactory::createExpression continues with
126 * calling the AST node(which is an Expression instance)'s typeCheck()
127 * function. This step ensures that the static types of the operands matches
128 * the operators, and in the cases where it doesn't, modifies the AST such
129 * that the necessary conversions are done -- if possible, otherwise the
130 * result is a type error.
131 *
132 *
133 * This step corresponds roughly to what <a
134 * href="http://www.w3.org/TR/xpath20/#id-static-analysis">2.2.3.1 Static Analysis Phase</a>
135 * labels operation tree normalization; step SQ5.
136 *
137 * @subsection ExpressionCreationCompression Compressing -- Optimization and Fixup
138 *
139 * The last step is calling compress(). This function is not called
140 * 'optimize', 'simplify' or the like, because although it performs all
141 * optimization, it also involves mandatory stages.
142 *
143 * One such is const folding, which while being an efficient optimization,
144 * also is a necessity for many XSL-T constructs. Another important step is
145 * that functions which had an evaluation dependency on the static context(as
146 * opposed to the dynamic) performs their "fixup".
147 *
148 * In other words, this stage potentially performs AST re-writes. For example,
149 * the expression <tt>3 + 3, concat('foo', '-', 'bar'), true() and false()</tt> would
150 * result in an AST corresponding to <tt>6, 'foo-bar', false()</tt>. This process
151 * is done backwards; each expression asks its operands to compress before it
152 * performs its own compression(and so forth, until the root expression's call
153 * returns to the caller).
154 *
155 * @see <a href="http://www.w3.org/TR/xpath20/#id-errors-and-opt">XML Path Language
156 * (XPath) 2.0, 2.3.4 Errors and Optimization</a>
157 * @see <a href="http://www.w3.org/TR/xpath20/#id-expression-processing">XML Path
158 * Language (XPath) 2.0, 2.2.3 Expression Processing</a>
159 * @see <a href="http://www.w3.org/TR/xquery-xpath-parsing/">Building a Tokenizer
160 * for XPath or XQuery</a>
161 * @see ExpressionFactory
162 * @author Frans Englich <[email protected]>
163 * @ingroup Patternist_expressions
164 */
165 class Q_AUTOTEST_EXPORT Expression : public QSharedData
166 , public CppCastingHelper<Expression>
167 , public SourceLocationReflection
168 {
169 public:
170 /**
171 * @short A smart pointer wrapping mutable Expression instances.
172 */
173 typedef QExplicitlySharedDataPointer<Expression> Ptr;
174
175 /**
176 * @short A smart pointer wrapping @c const Expression instances.
177 */
178 typedef QExplicitlySharedDataPointer<const Expression> ConstPtr;
179
180 /**
181 * A list of Expression instances, each wrapped in a smart pointer.
182 */
183 typedef QList<Expression::Ptr> List;
184
185 /**
186 * A vector of Expression instances, each wrapped in a smart pointer.
187 */
188 typedef QVector<Expression::Ptr> Vector;
189
190 typedef QT_PREPEND_NAMESPACE(QAbstractXmlForwardIterator<Expression::Ptr>)
191 QAbstractXmlForwardIterator;
192
193 /**
194 * Enum flags describing the characteristics of the expression.
195 *
196 * @see Expression::properties()
197 */
198 enum Property
199 {
200 /**
201 * This flag applies for functions, and results in the expression <tt>.</tt>
202 * being appended to its operands if its operand count is lower than the
203 * maximum amount of arguments.
204 *
205 * In effect, it result in a modification of the function's arguments to have
206 * appended the context item.
207 *
208 * One function which has this property is <tt>fn:number()</tt>.
209 *
210 * @see ContextItem
211 * @see <a href="http://www.w3.org/TR/xpath-functions/#func-signatures">XQuery 1.0 and
212 * XPath 2.0 Functions and Operators, 1.3 Function Signatures and Descriptions</a>
213 */
214 UseContextItem = 1,
215
216 /**
217 * Disables compression(evaluation at compile time), such that the
218 * Expression isn't const-folded, but ensured to be run at runtime. The
219 * operands are still attempted to be compressed, unless
220 * they override compression as well.
221 *
222 * @see compress()
223 */
224 DisableElimination = 1 << 1,
225
226 /**
227 * Signals that the expression is already evaluated and can be considered
228 * a constant value.
229 * For example, atomic values return this flag in their
230 * implementations of the properties() functions.
231 *
232 * @see isEvaluated()
233 */
234 IsEvaluated = 1 << 2,
235
236 /**
237 * Signals that the expression cannot be optimized away by judging
238 * its static type.
239 *
240 * This is currently used for properly handling the @c none type, in
241 * the <tt>fn:error()</tt> function. In type operations, the none type doesn't show
242 * up and that can make expressions, such as InstanceOf, believe
243 * it is safe to const fold, while it in fact is not.
244 */
245 DisableTypingDeduction = 1 << 3,
246
247 /**
248 * This property affects the static type -- staticType() -- of an expression. It
249 * is implemented in FunctionCall::staticType() and therefore only work for FunctionCall
250 * sub-classes and when that function is not re-implemented in an inhibiting way.
251 *
252 * When set, the cardinality of the static type is zero if the Expression's first
253 * operand allows an empty sequence, otherwise it is the cardinality of the Expression's
254 * static type modulo Cardinality::empty(). This is used for specifying proper static
255 * type inference for functions that have "If $arg is the empty sequence,
256 * the empty sequence is returned." However, before setting this property one
257 * must be aware that no other conditions can lead to the empty sequence, since
258 * otherwise the static type would be wrong.
259 */
260 EmptynessFollowsChild = 1 << 4,
261
262 /**
263 * This is similar to EmptynessFollowsChild, and also implemented in FunctionCall.
264 * When set, it makes FunctionCall::typeCheck() rewrite itself into an empty sequence
265 * if the first operand is the empty sequence.
266 *
267 * This property is often used together with EmptynessFollowsChild.
268 */
269 RewriteToEmptyOnEmpty = 1 << 5,
270
271 /**
272 * When set, it signals that the focus cannot be undefined. For example,
273 * the <tt>fn:position()</tt> function extracts information from the focus. Setting
274 * this flag ensures type checking is carried out appropriately.
275 *
276 * However, setting RequiresFocus does not imply this Expression requires the context
277 * item to be defined. It only means the focus, of somekind, needs to be defined.
278 *
279 * @see RequiresContextItem
280 */
281 RequiresFocus = 1 << 6,
282
283 /**
284 * An Expression with this Property set, signals that it only affects
285 * the order of its return value.
286 */
287 AffectsOrderOnly = 1 << 7,
288
289 /**
290 * When set, signals that the context item, must be defined for this Expression. When
291 * setting this property, expectedContextItemType() must be re-implemented.
292 *
293 * Setting this property also sets RequiresFocus.
294 *
295 * @see DynamicContext::contextItem()
296 */
297 RequiresContextItem = (1 << 8) | RequiresFocus,
298
299 /**
300 * When set, signals that this expression creates a focus for its last operand.
301 * When set, newFocusType() must be overridden to return the static type
302 * of the context item.
303 *
304 * @see announceFocusType()
305 * @see newFocusType()
306 */
307 CreatesFocusForLast = 1 << 9,
308
309 /**
310 * Signals that the last operand is a collation argument. This ensures
311 * that the necessary code is generated for checking that the collation
312 * is supported.
313 *
314 * This only applies to sub-classes of FunctionCall.
315 */
316 LastOperandIsCollation = 1 << 10,
317
318 /**
319 * When set, the Expression depends on local variables such as
320 * those found in @c for expressions. However, this does not
321 * include let bindings.
322 */
323 DependsOnLocalVariable = (1 << 11) | DisableElimination,
324
325 /**
326 * When set, it signals that the Expression does not need
327 * an evaluation cache, despite what other flags might imply.
328 */
329 EvaluationCacheRedundant = (1 << 12),
330
331 /**
332 * Signals that the Expression constructs nodes, either directly
333 * or computationally. For example, AttributeConstructor has this property
334 * set.
335 *
336 * Since node constructors constructs nodes which have node
337 * identities, node constructors are considered creative on
338 * evaluation.
339 */
340 IsNodeConstructor = 1 << 13,
341
342 /**
343 * Whether this expression requires the current item, as returned
344 * from @c fn:current().
345 *
346 * CurrentFN uses this flag.
347 */
348 RequiresCurrentItem = 1 << 14
349 };
350
351 /**
352 * A QFlags template for type-safe handling of ExpressionProperty values. If
353 * Expression::Property flags needs to be stored in a class, declared the variable
354 * to be of type Expression::Properties.
355 *
356 * @see QFlags
357 */
358 typedef QFlags<Property> Properties;
359
360 /**
361 * Enumerators that identifies Expression sub-classes.
362 *
363 * @see id()
364 */
365 enum ID
366 {
367 /**
368 * Identifies Boolean.
369 */
370 IDBooleanValue = 1,
371
372 /**
373 * Identifies CountFN.
374 */
375 IDCountFN,
376
377 /**
378 * Identifies EmptyFN.
379 */
380 IDEmptyFN,
381
382 /**
383 * Identifies ExistsFN.
384 */
385 IDExistsFN,
386
387 /**
388 * Identifies ExpressionSequence and LiteralSequence.
389 */
390 IDExpressionSequence,
391
392 /**
393 * Identifies GeneralComparison.
394 */
395 IDGeneralComparison,
396
397 /**
398 * Identifies IfThenClause.
399 */
400 IDIfThenClause,
401
402 /**
403 * Identifies nothing in particular. The default implementation
404 * of id() returns this, which is suitable for Expression instances
405 * which never needs to be identified in this aspect.
406 */
407 IDIgnorableExpression,
408
409 /**
410 * Identifies Integer.
411 */
412 IDIntegerValue,
413
414 /**
415 * Identifies PositionFN.
416 */
417 IDPositionFN,
418
419 /**
420 * Identifies AtomicString, AnyURI, and UntypedAtomic.
421 */
422 IDStringValue,
423
424 /**
425 * Identifies ValueComparison.
426 */
427 IDValueComparison,
428
429 /**
430 * Identifies VariableReference.
431 */
432 IDRangeVariableReference,
433
434 /**
435 * Identifies ContextItem.
436 */
437 IDContextItem,
438
439 /**
440 * Identifies UserFunctionCallsite.
441 */
442 IDUserFunctionCallsite,
443
444 /**
445 * Identifies ExpressionVariableReference.
446 */
447 IDExpressionVariableReference,
448
449 /**
450 * Identifies ExpressionVariableReference.
451 */
452 IDAttributeConstructor,
453
454 /**
455 * Identifies UpperCaseFN.
456 */
457 IDUpperCaseFN,
458
459 /**
460 * Identifies LowerCaseFN.
461 */
462 IDLowerCaseFN,
463
464 /**
465 * Identifies FirstItemPredicate.
466 */
467 IDFirstItemPredicate,
468 IDEmptySequence,
469 IDReturnOrderBy,
470 IDLetClause,
471 IDForClause,
472 IDPath,
473 IDNamespaceConstructor,
474 IDArgumentReference,
475 IDGenericPredicate,
476 IDAxisStep,
477
478 /**
479 * A literal which is either @c xs:float or
480 * @c xs:double.
481 */
482 IDFloat,
483
484 IDCombineNodes,
485 IDUnresolvedVariableReference,
486 IDCardinalityVerifier
487 };
488
489 inline Expression()
490 {
491 }
492 virtual ~Expression();
493
494 /**
495 * Evaluate this Expression by iterating over it. This is a central function
496 * for evaluating expressions.
497 *
498 * Expressions must always always return a valid QAbstractXmlForwardIterator and may
499 * never return 0. If an empty result is of interest to be returned, the
500 * EmptyIterator should be returned.
501 *
502 * The default implementation returns a SingletonIterator over the
503 * item returned from evaluateSingleton().
504 *
505 * @note This function may raise an exception when calling, not only
506 * when QAbstractXmlForwardIterator::next() is called on the return value. This is because
507 * in some cases evaluateSingleton() is called directly.
508 */
509 virtual Item::Iterator::Ptr evaluateSequence(const DynamicContext::Ptr &context) const;
510
511 /**
512 * @todo Docs
513 */
514 virtual Item evaluateSingleton(const DynamicContext::Ptr &context) const;
515
516 /**
517 * Determines the Effective %Boolean Value of the expression.
518 *
519 * The Effective %Boolean Value of a value is not necessarily the same
520 * as converting the value to a new value of type xs:boolean.
521 *
522 * Note that this function cannot return the empty sequence,
523 * evaluateSingleton() must be overridden in order to be able to do
524 * that.
525 *
526 * The default implementation results in a type error. Hence, this function
527 * must be overridden if such behavior is not of interest.
528 *
529 * @see <a href="http://www.w3.org/TR/xpath20/#id-ebv">XML Path Language (XPath) 2.0,
530 * 2.4.3 Effective Boolean Value</a>
531 */
532 virtual bool evaluateEBV(const DynamicContext::Ptr &context) const;
533
534 /**
535 * Evaluates this Expression by sending its output to DynamicContext::outputReceiver().
536 */
537 virtual void evaluateToSequenceReceiver(const DynamicContext::Ptr &context) const;
538
539 /**
540 * @returns the expression's child expressions. For example, a function's
541 * arguments is returned here.
542 *
543 * If this Expression has no operands, an empty list should be returned.
544 */
545 virtual Expression::List operands() const = 0;
546
547 virtual void setOperands(const Expression::List &operands) = 0;
548
549 /**
550 * @returns the static type of this Expression. For example, an 'and' expression
551 * have as static type xs:boolean
552 */
553 virtual SequenceType::Ptr staticType() const = 0;
554
555 /**
556 * Returns a list of Sequence Types, describing the type of each of the
557 * expression's operands. Hence, this function has a relationship to
558 * the operands() function:
559 *
560 * - The lengths of the lists returned by expectedOperandTypes()
561 * and operands() should always be equal in length, since one
562 * cannot describe the type of a non-existent operand(and all
563 * operands must have type information).
564 * - A significant difference between the two functions is that while
565 * the type of objects in the list returned by operands() may vary
566 * between compilations/static context, simply because the particular
567 * Expression is part of different XPath expressions, the
568 * types in the list returned by expectedOperandTypes is always the same
569 * since the function/operator signature never changes.
570 *
571 * This function should not be confused with staticType(),
572 * which returns the static type of the expression itself, not its operands. The
573 * function call is an expression where this is clear: the type of the return
574 * value is not the same as the arguments' types. The static type of the
575 * operands supplied to the expression can be determined via the staticType()
576 * function of the instances returned by operands().
577 *
578 * If the expression has no operands, an empty list should be returned.
579 */
580 virtual SequenceType::List expectedOperandTypes() const = 0;
581
582 /**
583 * This implementation guarantees to never rewrite away this Expression, but
584 * at most rewrite it as a child of another expression(that presumably have a
585 * type checking role). It is therefore always safe to override this
586 * function and call this implementation and not worry about that this Expression
587 * becomes deleted.
588 *
589 * Many Expressions override typeCheck() and performs optimizations, as opposed
590 * to doing it in the compress() stage. This is due to that the design
591 * of those Expressions often are tied to that certain simplifications
592 * are done at the typeCheck() stage of the compilation process or that
593 * it in some other way is related to what the typeCheck() do. Also, the earlier
594 * the AST can be simplified, the better the chances are for subsequent
595 * optimizations.
596 *
597 * It is important that the super class's typeCheck() is called before doing
598 * any custom type checking, since the call can change the children(notably,
599 * the childrens' static types). For example, if the Expression, MyExpression
600 * in the example, does not match the required type, typeCheck returns the Expression
601 * wrapped in for example ItemVerifier, CardinalityVerifier, or both.
602 *
603 * typeCheck() may be called many times. typeCheck() must either raise an error
604 * if this Expression is an invalid expression. Thus, it is guaranteed that an Expression
605 * is valid after typeCheck() is called.
606 *
607 * @param context supplies information, such as namespace bindings and
608 * available function signatures, that can be needed at compilation time. @p context is
609 * guaranteed by the caller to never null.
610 * @param reqType the static type that this Expression must match when evaluated. @p reqType is
611 * guaranteed by the caller to never null.
612 * @returns an Expression that can be this Expression, or another expression,
613 * which somehow is necessary for making this Expression conforming to
614 * @p reqType
615 */
616 virtual Expression::Ptr typeCheck(const StaticContext::Ptr &context,
617 const SequenceType::Ptr &reqType);
618
619 /**
620 * compress() is the last stage performs in compiling an expression, done after
621 * the initial AST build and calling typeCheck(). compress() performs crucial
622 * simplifications, either by having drastic performance implications or that
623 * some expressions depend on it for proper behavior.
624 *
625 * The default implementation performs a sparse conditional constant
626 * propagation. In short, a recursive process is performed in the AST
627 * which examines if the Expression's operands are constant values, and if so,
628 * performs a const fold(AST rewrite) into the result of evaluating the expression
629 * in question. This default behavior can be disabled by letting properties() return
630 * DisableElimination.
631 *
632 * This compress() stage can be relative effective due to the design of XPath, in
633 * part because intrinsic functions are heavily used. Many Expressions override compress()
634 * and do optimizations specific to what they do. Also, many Expressions performs
635 * optimizations in their typeCheck().
636 *
637 * @param context the static context. Supplies compile time information, and is
638 * the channel for communicating error messages.
639 * @see <a href="http://en.wikipedia.org/wiki/Sparse_conditional_constant_propagation">Wikipedia,
640 * the free encyclopedia, Sparse conditional constant propagation</a>
641 * @see <a href="http://en.wikipedia.org/wiki/Intrinsic_function">Wikipedia,
642 * the free encyclopedia, Intrinsic function</a>
643 * @see <a href="http://en.wikipedia.org/wiki/Compiler_optimization">Wikipedia, the
644 * free encyclopedia, Compiler optimization</a>
645 */
646 virtual Expression::Ptr compress(const StaticContext::Ptr &context);
647
648 /**
649 * @returns a bitwise OR'd value of properties, describing the
650 * characteristics of the expression. These properties affects how
651 * this Expression is treated in for example type checking stages.
652 *
653 * The default implementation returns 0. Override and let the function return
654 * a different value, if that's of interest.
655 *
656 * An important decision when re-implementing properties() is whether
657 * to OR in the properties() of ones operands. For instance, if an
658 * operand has RequiresFocus set, that flag nost likely applies to the
659 * apparent as well, since it depends on its operand.
660 *
661 * @see deepProperties()
662 * @returns Expression::None, meaning no special properties
663 */
664 virtual Properties properties() const;
665
666 /**
667 * Recursively computes through all descendants until a Property
668 * is encount
669 */
670 virtual Properties dependencies() const;
671
672 /**
673 * @short Computes the union of properties for this Expression and all
674 * its descending children.
675 *
676 * @see properties()
677 */
678 Properties deepProperties() const;
679
680 /**
681 * This function is a utility function, which performs bitwise logic
682 * on properties() in order to find out whether the Expression::IsEvaluated
683 * flag is set.
684 *
685 * @note Do not attempt to re-implement this function. Instead, return the
686 * IsEvaluated flag by re-implementing the properties() function.
687 */
688 inline bool isEvaluated() const;
689
690 /**
691 * This function is a utility function, syntactic sugar for determining
692 * whether this Expression is @p id. For example, calling <tt>is(IDIfThenClause)</tt>
693 * is equivalent to <tt>id() == IDIfThenClause</tt>
694 *
695 * @note Do not attempt to re-implement this function. Instead, return the
696 * appropriate flag in the virtual id() function.
697 */
698 inline bool is(const ID id) const;
699
700 /**
701 * Determines whether this Expression has Property @p prop set.
702 *
703 * Calling <tt>expr->has(MyProperty)</tt> is semantically equivalent
704 * to <tt>expr->properties().testFlag(MyProperty)</tt>. In
705 * other words, has(), as well as is(), provides syntacti sugar
706 * and makes code more readable.
707 *
708 * @note Do not attempt to re-implement this function. Instead, return
709 * the appropriate flag by re-implementing the properties() function.
710 */
711 inline bool has(const Property prop) const;
712
713 inline bool hasDependency(const Property prop) const;
714
715 virtual ExpressionVisitorResult::Ptr accept(const ExpressionVisitor::Ptr &visitor) const = 0;
716
717 /**
718 * This property, which has no setter, returns an enum value that uniquely identifies
719 * this Expression. Patternist makes no use of C++'s dynamic_cast feature, but uses this
720 * polymorphic function instead.
721 *
722 * @returns always IgnorableExpression.
723 */
724 virtual ID id() const;
725
726 /**
727 * Returns the OptimizationPasses that applies for this Expression. The
728 * default implementation returns an empty list. Sub-classes can re-implement
729 * this function and return actual OptimizationPasses.
730 *
731 * @returns always an empty list.
732 */
733 virtual QList<QExplicitlySharedDataPointer<OptimizationPass> > optimizationPasses() const;
734
735 /**
736 * Returns the required type the context item must be an instance of.
737 *
738 * If this Expression requires a focus, meaning its properties()
739 * function returns RequiresContextItem,
740 * it must return a type from this function. If any type is ok, BuiltinTypes::item should be
741 * returned.
742 *
743 * In other words, this function must only be re-implemented if the focus is used. The default
744 * implementation performs an assert crash.
745 */
746 virtual ItemType::Ptr expectedContextItemType() const;
747
748 /**
749 * If an Expression creates a focus because it has set the property CreatesFocusForLast,
750 * it should override this function and make it return the ItemType that
751 * the context item in the focus has.
752 *
753 * @returns never @c null.
754 * @see announceFocusType()
755 */
756 virtual ItemType::Ptr newFocusType() const;
757
758 /**
759 * @short Returns @c this.
760 */
761 virtual const SourceLocationReflection *actualReflection() const;
762
763 /**
764 * Reimplementation of SourceLocationReflection::description().
765 */
766 virtual QString description() const;
767
768 /**
769 * When this function is called, it signals that the parent will create
770 * a focus of type @p itemType.
771 *
772 * This type can also be retrieved through StaticContext::contextItemType()
773 * when inside typeCheck(), but in some cases this is too late. For
774 * instance, a parent needs to have the static type of its child
775 * properly reported before it calls its typeCheck()(and the child's
776 * type is inferred from the focus).
777 *
778 * The default implementation delegates the call on to the children.
779 *
780 * This function may be called at arbitrary times, in arbitrary
781 * amounts.
782 *
783 * If the AST node overriding this call has children, it should be
784 * considered whether the default implementation should be called, such
785 * that they type is announced to them too.
786 *
787 * The caller guarantees that @p itemType is not @c null.
788 */
789 virtual void announceFocusType(const ItemType::Ptr &itemType);
790
791 /**
792 * This function take the two Expression pointers @p old and @p New, and
793 * in a safe way, by handling reference counting and being aware of whether
794 * the two pointers actually are different, switches the two. When compiling
795 * in debug mode, informative debug messages are printed.
796 *
797 * This function is conceptually similar to Qt's qSwap(), but has
798 * debugging functionality and also handles source locations.
799 */
800 static inline void rewrite(Expression::Ptr &old,
801 const Expression::Ptr &New,
802 const StaticContext::Ptr &context);
803
804 /**
805 * @short Rewrites this Expression to @p to, and return @p to.
806 *
807 * Source location annotations are adjusted appropriately.
808 */
809 inline const Expression::Ptr &rewrite(const Expression::Ptr &to,
810 const StaticContext::Ptr &context) const;
811
812 /**
813 * By default 0.5 is returned.
814 */
815 virtual PatternPriority patternPriority() const;
816
817 protected:
818
819 /**
820 * @returns @c true if all operands are constant values of somekind, and are already
821 * evaluated. A string literal, is a typical example.
822 */
823 virtual bool compressOperands(const StaticContext::Ptr &) = 0;
824
825 void typeCheckOperands(const StaticContext::Ptr &context);
826
827 private:
828 static Expression::Ptr invokeOptimizers(const Expression::Ptr &expr,
829 const StaticContext::Ptr &context);
830 /**
831 * @return a StaticContext that has adopted the context item type properly
832 * for this Expression.
833 */
834 inline StaticContext::Ptr finalizeStaticContext(const StaticContext::Ptr &context) const;
835
836 /**
837 * @short Performs constant propagation, also called constant folding, on this expression.
838 *
839 * This means that it attempts to evaluate this expression at compile and returns the result value
840 * appropriately as an Expression. For example, for the XPath expression
841 * <tt>1 + 3</tt> would an Integer of value 4 would be returned.
842 *
843 * It is not checked whether constant propagation is possible, the
844 * caller is responsible for this.
845 *
846 * @see <a href="http://en.wikipedia.org/wiki/Constant_propagation">Constant folding,
847 * From Wikipedia, the free encyclopedia</a>
848 */
849 Expression::Ptr constantPropagate(const StaticContext::Ptr &context) const;
850
851 Q_DISABLE_COPY(Expression)
852 };
853
854 Q_DECLARE_OPERATORS_FOR_FLAGS(Expression::Properties)
855
856 inline bool Expression::is(const Expression::ID i) const
857 {
858 return id() == i;
859 }
860
861 inline bool Expression::isEvaluated() const
862 {
863 return has(IsEvaluated);
864 }
865
866 inline bool Expression::has(const Expression::Property prop) const
867 {
868 return properties().testFlag(prop);
869 }
870
871 inline bool Expression::hasDependency(const Expression::Property prop) const
872 {
873 return dependencies().testFlag(prop);
874 }
875
876 inline void Expression::rewrite(Expression::Ptr &old,
877 const Expression::Ptr &New,
878 const StaticContext::Ptr &context)
879 {
880 Q_ASSERT(old);
881 Q_ASSERT(New);
882
883 if(old != New)
884 {
885 pDebug() << "AST REWRITE:" << old.data() << "to" << New.data()
886 << '(' << old->actualReflection() << "to" << New->actualReflection() << ", "
887 << old->description() << "to" << New->description() << ')';
888
889 /* The order of these two lines is significant.. */
890 context->addLocation(New.data(), context->locationFor(old->actualReflection()));
891 old = New;
892 }
893 }
894
895 inline const Expression::Ptr &Expression::rewrite(const Expression::Ptr &to,
896 const StaticContext::Ptr &context) const
897 {
898 context->addLocation(to.data(), context->locationFor(this));
899 return to;
900 }
901}
902
903Q_DECLARE_TYPEINFO(QPatternist::Expression::Ptr, Q_MOVABLE_TYPE);
904
905QT_END_NAMESPACE
906
907QT_END_HEADER
908
909#endif
Note: See TracBrowser for help on using the repository browser.