src/xmlpatterns/expr/qexpression_p.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  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 <private/qcppcastinghelper_p.h>
  59 #include <private/qdebug_p.h>
  60 #include <private/qdynamiccontext_p.h>
  61 #include <private/qexpressiondispatch_p.h>
  62 #include <private/qitem_p.h>
  63 #include <private/qsequencetype_p.h>
  64 #include <private/qsourcelocationreflection_p.h>
  65 #include <private/qstaticcontext_p.h>
  66
  67 QT_BEGIN_HEADER
  68
  69 QT_BEGIN_NAMESPACE
  70
  71 template<typename T> class QList;
  72 template<typename T> class QVector;
  73
  74 namespace 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 <frans.englich@nokia.com>
 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
 903 Q_DECLARE_TYPEINFO(QPatternist::Expression::Ptr, Q_MOVABLE_TYPE);
 904
 905 QT_END_NAMESPACE
 906
 907 QT_END_HEADER
 908
 909 #endif