language/duchain/declaration.h

   1 /* This file is part of KDevelop
   2     Copyright 2006 Hamish Rodda <rodda@kde.org>
   3     Copyright 2007-2008 David Nolden <david.nolden.kdevelop@art-master.de>
   4
   5    This library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Library General Public
   7    License version 2 as published by the Free Software Foundation.
   8
   9    This library is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12    Library General Public License for more details.
  13
  14    You should have received a copy of the GNU Library General Public License
  15    along with this library; see the file COPYING.LIB.  If not, write to
  16    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17    Boston, MA 02110-1301, USA.
  18 */
  19
  20 #ifndef DECLARATION_H
  21 #define DECLARATION_H
  22
  23 #include <QtCore/QList>
  24 #include <QtCore/QMap>
  25 #include <qcontainerfwd.h>
  26
  27 #include "../editor/documentrangeobject.h"
  28 #include "identifier.h"
  29 #include "indexedstring.h"
  30 #include "types/abstracttype.h"
  31 #include "duchainbase.h"
  32
  33 class QByteArray;
  34
  35 namespace KTextEditor {
  36   class SmartRange;
  37 }
  38
  39 namespace KDevelop
  40 {
  41
  42 class AbstractType;
  43 class DUContext;
  44 class Use;
  45 class ForwardDeclaration;
  46 class DeclarationData;
  47 class DeclarationId;
  48 class Declaration;
  49 class IndexedTopDUContext;
  50
  51 struct ImportTraceItem;
  52
  53
  54 typedef KDevVarLengthArray<ImportTraceItem, 40> ImportTrace;
  55
  56
  57 ///Represents a declaration only by its global indices
  58 class KDEVPLATFORMLANGUAGE_EXPORT IndexedDeclaration {
  59   public:
  60     IndexedDeclaration(Declaration* decl = 0);
  61     IndexedDeclaration(uint topContext, uint declarationIndex);
  62     //Duchain must be read locked
  63     Declaration* declaration() const;
  64
  65     Declaration* data() const {
  66       return declaration();
  67     }
  68
  69     bool operator==(const IndexedDeclaration& rhs) const {
  70       return m_topContext == rhs.m_topContext && m_declarationIndex == rhs.m_declarationIndex;
  71     }
  72     uint hash() const {
  73       return (m_topContext * 53 + m_declarationIndex) * 23;
  74     }
  75
  76     bool isValid() const {
  77       return declaration() != 0;
  78     }
  79
  80     bool operator<(const IndexedDeclaration& rhs) const {
  81       return m_topContext < rhs.m_topContext || (m_topContext == rhs.m_topContext && m_declarationIndex < rhs.m_declarationIndex);
  82     }
  83
  84     ///Index of the Declaration within the top context
  85     uint localIndex() const {
  86       return m_declarationIndex;
  87     }
  88
  89     uint topContextIndex() const {
  90       return m_topContext;
  91     }
  92
  93     IndexedTopDUContext indexedTopContext() const;
  94
  95   private:
  96   uint m_topContext;
  97   uint m_declarationIndex;
  98 };
  99
 100 ///Represents a declaration only by its index within the top-context
 101 class KDEVPLATFORMLANGUAGE_EXPORT LocalIndexedDeclaration {
 102   public:
 103     LocalIndexedDeclaration(Declaration* decl = 0);
 104     LocalIndexedDeclaration(uint declarationIndex);
 105     //Duchain must be read locked
 106
 107     Declaration* data(TopDUContext* top) const;
 108
 109     bool operator==(const LocalIndexedDeclaration& rhs) const {
 110       return m_declarationIndex == rhs.m_declarationIndex;
 111     }
 112     uint hash() const {
 113       return m_declarationIndex * 23;
 114     }
 115
 116     bool isValid() const {
 117       return m_declarationIndex != 0;
 118     }
 119
 120     bool operator<(const LocalIndexedDeclaration& rhs) const {
 121       return m_declarationIndex < rhs.m_declarationIndex;
 122     }
 123
 124     ///Index of the Declaration within the top context
 125     uint localIndex() const {
 126       return m_declarationIndex;
 127     }
 128
 129     bool isLoaded(TopDUContext* top) const;
 130
 131   private:
 132   uint m_declarationIndex;
 133 };
 134
 135 /**
 136  * \short Represents a single declaration in a definition-use chain.
 137  *
 138  * \note A du-context can be freely edited as long as it's parent-context is zero.
 139  * In the moment the parent-context is set, the context may only be edited when it
 140  * is allowed to edited it's top-level context (@see TopLevelContext::inDUChain())
 141  */
 142 class KDEVPLATFORMLANGUAGE_EXPORT Declaration : public DUChainBase
 143 {
 144 public:
 145   /// Access types
 146   enum AccessPolicy {
 147     Public    /**< a public declaration */,
 148     Protected /**< a protected declaration */,
 149     Private   /**< a private declaration */
 150   };
 151   /// Enumeration of the types of declarations
 152   enum Kind {
 153     Type     /**< A type is declared, like a class-declaration or function-declaration, or a typedef("class MyClass {};") */,
 154     Instance /**< An instance of a type is declared("MyClass m;") */,
 155     NamespaceAlias/**< This is a namespace-alias. You can safely cast this object to NamespaceAliasDeclaration. */,
 156     Alias /**<This is an alias-declaration. You can safely cast this object to AliasDeclaration. */
 157   };
 158
 159   /**
 160    * Constructor.
 161    *
 162    * If \a parentContext is in the symbol table, the declaration will automatically be added into the symbol table.
 163    *
 164    * \param url url of the document where this occurred
 165    * \param range range of the alias declaration's identifier
 166    * \param parentContext context in which this declaration occurred
 167    * */
 168   Declaration(const SimpleRange& range, DUContext* parentContext);
 169   ///Copy-constructor for cloning
 170   Declaration(const Declaration& rhs);
 171   /// Destructor
 172   virtual ~Declaration();
 173   /// Uses the given data
 174   Declaration( DeclarationData & dd );
 175
 176   virtual TopDUContext* topContext() const;
 177
 178   /// Determine whether this declaration is a forward declaration. \returns true if this is a forward declaration, otherwise returns false.
 179   virtual bool isForwardDeclaration() const;
 180   /// Returns this declaration as a forward declaration, if it is one. \returns this declaration as a forward declaration if it is one, otherwise null.
 181   ForwardDeclaration* toForwardDeclaration();
 182   /// Returns this declaration as a forward declaration, if it is one. \returns this declaration as a forward declaration if it is one, otherwise null.
 183   const ForwardDeclaration* toForwardDeclaration() const;
 184
 185   /// Determine whether this declaration is a function declaration. \returns true if this is a function declaration, otherwise returns false.
 186   virtual bool isFunctionDeclaration() const;
 187
 188   /**
 189    * Determine whether this declaration is accessible through the du-chain.
 190    * If it is, it cannot be edited without holding the du-chain write lock.
 191    *
 192    * \sa DUChain::lock()
 193    * \sa DUChainWriteLocker
 194    *
 195    * \returns true if the Declaration is already inserted into a duchain.
 196    */
 197   virtual bool inDUChain() const;
 198
 199   /// Access whether this declaration is also a definition. \returns true if this declaration is also a definition, otherwise false.
 200   bool isDefinition() const;
 201   /// Set whether this declaration is also a definition. \param dd set to true if this declaration is also a definition, otherwise false.
 202   void setDeclarationIsDefinition(bool dd);
 203
 204   /// Determine if this declaration is a type-alias (in c++ typedef).  \returns true if the declaration is a type alias, otherwise false.
 205   bool isTypeAlias() const;
 206   /// Set whether this declaration is a type alias. \param typeAlias true if the declaration is a type alias, otherwise false.
 207   void setIsTypeAlias(bool typeAlias);
 208
 209   /**
 210    * Retrieve the declaration which is specialized with the given \a specialization index as seen from \a topContext.
 211    *
 212    * \param specialization the specialization index (see DeclarationId)
 213    * \param topContext the top context to search from
 214    * \param upDistance upwards distance in the context-structure of the
 215    *                   given specialization-info. This allows specializing children.
 216    * */
 217   virtual Declaration* specialize(uint specialization, const TopDUContext* topContext, int upDistance = 0);
 218
 219   /**
 220    * Retrieve the context that is opened by this declaration, if one exists.
 221    *
 222    * For example, a class will have a declaration which is contained within the context in which
 223    * it is declared, and a new context will be created to hold class members.  This function returns
 224    * that context.
 225    * The declaration has to be part of the same top-context.
 226    *
 227    * \returns the internal context for this declaration
 228    * */
 229   DUContext * internalContext() const;
 230
 231   /**
 232    * Set the internal \a context for this declaration.
 233    *
 234    * \param context the internal context
 235    */
 236   void setInternalContext(DUContext* context);
 237
 238   /**
 239    * Determine the logical internal context for the resolved form of this declaration.
 240    *
 241    * * If this declaration has a definition, and the definition is resolved, it returns the internal context of the definition.
 242    * * If this declaration is a forward-declaration, the forward-declaration is resolved, it returns the internal context of the resolved declaration.
 243    * * If this is a type-alias, it returns the internal context of the actual type.
 244    * * Otherwise, it returns the same as internalContext().
 245    *
 246    * \param topContext Needed to resolve forward-declarations.
 247    * \returns the resolved internal context, as described above
 248    * */
 249   virtual DUContext * logicalInternalContext(const TopDUContext* topContext) const;
 250
 251   /**
 252    * This is a convenience function to determine the resolved declaration, if this is a forward declaration.
 253    * Otherwise, it just returns this declaration.
 254    * \param topContext Context within which to search for the resolved declaration.
 255    * \returns the resolved declaration if one was found, otherwise this declaration.
 256    * */
 257   const Declaration* logicalDeclaration(const TopDUContext* topContext) const;
 258
 259   /// \copydoc
 260   Declaration* logicalDeclaration(const TopDUContext* topContext);
 261
 262   /**
 263    * Access the parent context of this declaration.
 264    * \returns the parent context of this declaration.
 265    * */
 266   DUContext* context() const;
 267
 268   /**
 269    * Set the context in which this declaration occurs.
 270    *
 271    * When setContext() is called, this declaration is inserted into the given context.
 272    * You only need to be able to write this declaration. You do not need write-privileges
 273    * for the context, because addDeclaration(..) works separately to that.
 274    *
 275    * If the given context is not in the symbol-table, or if the declaration is inserted anonymously,
 276    *  or if the context is zero, this declaration is removed from the symbol-table.
 277    * Else it is added to the symbol table with the new scope. See TopDUContext for information about the symbol table.
 278    *
 279    * \param context New context which contains this declaration. The context must have a top-context if it is not zero.
 280    * \param anonymous If this is set, this declaration will be added anonymously into the parent-context.
 281    *                  This way it can never be found through any of the context's functions, and will
 282    *                  not be deleted when the context is deleted, so it must be deleted from elsewhere.
 283    * */
 284   void setContext(DUContext* context, bool anonymous = false);
 285
 286   /// Convenience function to return this declaration's type dynamically casted to \a T. \returns this declaration's type as \a T, or null if there is no type or it is not of type \a T.
 287   template <class T>
 288   TypePtr<T> type() const { return TypePtr<T>::dynamicCast(abstractType()); }
 289
 290   /**
 291    * Access this declaration's type.
 292    *
 293    * \note You should not compare or permanently store instances of AbstractType::Ptr. Use IndexedType instead.
 294    * \returns this declaration's type, or null if none has been assigned.
 295    */
 296   AbstractType::Ptr abstractType() const;
 297
 298   /**
 299    * Set this declaration's type.
 300    * \param type the type to assign.
 301    */
 302   template <class T>
 303   void setType(TypePtr<T> type) { setAbstractType(AbstractType::Ptr::staticCast(type)); }
 304
 305   /**
 306    * Set this declaration's \a type.
 307    *
 308    * \param type this declaration's new type.
 309    */
 310   virtual void setAbstractType(AbstractType::Ptr type);
 311
 312   /**
 313    * Return an indexed form of this declaration's type.
 314    * Should be preferred, this is the fastest way, and the correct way for doing equality-comparsion.
 315    *
 316    * \returns the declaration's type.
 317    */
 318   IndexedType indexedType() const;
 319
 320   /**
 321    * Set this declaration's \a identifier.
 322    *
 323    * \param identifier this declaration's new identifier
 324    */
 325   void setIdentifier(const Identifier& identifier);
 326
 327   /**
 328    * Access this declaration's \a identifier.
 329    *
 330    * \returns this declaration's identifier.
 331    */
 332   Identifier identifier() const;
 333
 334   /**
 335    * Access this declaration's \a identifier.
 336    *
 337    * \return this declaration's identifier in indexed form. This is faster than identifier(), because it
 338    *         equals the internal representation. Use this for example to do equality-comparison.
 339    */
 340   IndexedIdentifier indexedIdentifier() const;
 341
 342   /**
 343    * Determine the global qualified identifier of this declaration.
 344    *
 345    * \note This function is expensive, equalQualifiedIdentifier() is preferred if you
 346    *       just want to compare equality.
 347    */
 348   QualifiedIdentifier qualifiedIdentifier() const;
 349
 350   /**
 351    * Compares the qualified identifier of this declaration with the other one, without needing to compute it.
 352    * This is more efficient than comparing the results of qualifiedIdentifier().
 353    *
 354    * \param rhs declaration to compare identifiers with
 355    * \returns true if the identifiers are equal, otherwise false.
 356    */
 357   bool equalQualifiedIdentifier(const Declaration* rhs) const;
 358
 359   /**
 360    * Returns the kind of this declaration. @see Kind
 361    * */
 362   Kind kind() const;
 363
 364   /**
 365    * Set the kind.
 366    *
 367    * \param kind new kind
 368    * */
 369   void setKind(Kind kind);
 370
 371   /**
 372    * Returns the comment associated to this declaration in the source-code, or an invalid string if there is none.
 373    * Stored in utf-8 encoding.
 374    * */
 375   QByteArray comment() const;
 376
 377   /**
 378    * Sets the comment for this declaration. Should be utf-8 encoded.
 379    * */
 380   void setComment(const QByteArray& str);
 381   /// Sets the comment for this declaration.
 382   void setComment(const QString& str);
 383
 384   /**
 385    * Access whether this declaration is in the symbol table.
 386    *
 387    * \returns true if this declaration is in the symbol table, otherwise false.
 388    */
 389   bool inSymbolTable() const;
 390
 391   /**
 392    * Adds or removes this declaration to/from the symbol table.
 393    *
 394    * \param inSymbolTable true to add this declaration to the symbol table, false to remove it.
 395    */
 396   void setInSymbolTable(bool inSymbolTable);
 397
 398   /**
 399    * Equivalence operator.
 400    * \param other Other declaration to compare.
 401    * \returns true if the declarations are equal, otherwise false.
 402    */
 403   bool operator==(const Declaration& other) const;
 404
 405   /**
 406    * Determine this declaration as a string. \returns this declaration as a string.
 407    */
 408   virtual QString toString() const;
 409
 410   ///@todo The following two are convenience-functions. Think whether they should stay here, or be moved out.
 411
 412   /**
 413    * Returns a list of pairs:
 414    * An url of a file, paired together with all use-ranges of this declaration in that file.
 415    * The uses are unique, no 2 uses are returend that have the same range within the same file.
 416    *
 417    * This is a non-trivial operation.
 418    * */
 419   QMap<IndexedString, QList<SimpleRange> > uses() const;
 420
 421   /**
 422    * Collects the smart-ranges for all uses. Uses that do not have smart ranges are not represented
 423    * in the result.
 424    * */
 425   QList<KTextEditor::SmartRange*> smartUses() const;
 426
 427   /**
 428     * This hash-value should differentiate between multiple different
 429     * declarations that have the same qualifiedIdentifier, but should have a different
 430     * identity, and thus own Definitions and own Uses assigned.
 431     *
 432     * Affected by function-arguments, whether this is a template-declaration, etc..
 433     * */
 434   virtual uint additionalIdentity() const;
 435
 436   /**
 437    *
 438    * */
 439   virtual uint specialization() const;
 440
 441   /**
 442    * @see DeclarationId
 443    * @param forceDirect When this is true, the DeclarationId is force to be direct, and can be resolved without a symbol-table and top-context
 444    * */
 445   virtual DeclarationId id(bool forceDirect = false) const;
 446
 447   /**
 448    * Returns an index that uniquely identifies this declaration within its surrounding top-context. That index can be passed
 449    * to TopDUContext::declarationFromIndex(index) to get the declaration.
 450    * This is only valid when the declaration is not a specialization (specialization() returns 0), and if it is not anonymous in its context.
 451    *
 452    * \note for this to be valid, allocateOwnIndex() must have been called first.
 453    * \note the highest big of the index is always zero!
 454    * \returns the index of the declaration within its TopDUContext.
 455    */
 456   uint ownIndex() const;
 457
 458   /**
 459    * Clear the index for this declaration in the top context that was allocated with allocateOwnIndex().
 460    */
 461   void clearOwnIndex();
 462
 463   /**
 464    * Create an index to this declaration from the topContext().  Needed to be able to retrieve ownIndex().
 465    */
 466   void allocateOwnIndex();
 467
 468   /**
 469    * Returns a clone of this declaration, with the difference that:
 470    * - context will be zero
 471    *
 472    * The declaration will not be registered anywhere, so you must care about its deletion.
 473    *
 474    * This declaration's text-range will be referenced from the clone, so the clone must not live longer than the original.
 475    *
 476    * */
 477   Declaration* clone() const;
 478
 479   /**
 480    * Signalized that among multiple possible specializations, this one should be used in the UI from now on.
 481    * Currently mainly used in C++ for template support. The default-implementation registers the current specialization
 482    * of this declaration to SpecializationStore if it is nonzero.
 483    */
 484   virtual void activateSpecialization();
 485
 486   enum {
 487     Identity = 7
 488   };
 489
 490 protected:
 491
 492   /**
 493     * Constructor for copy constructors in subclasses.
 494     *
 495     * \param dd data to copy.
 496     * \param url document url in which this object is located.
 497     * \param range text range which this object covers.
 498     */
 499   Declaration( DeclarationData & dd, const SimpleRange& range );
 500
 501   DUCHAIN_DECLARE_DATA(Declaration)
 502 private:
 503    /**
 504    * Sub-classes should implement this and should copy as much information into the clone as possible without breaking the du-chain.
 505    * Sub-classes should also implement a public copy-constructor that can be used for cloning by sub-classes.
 506    *
 507    * \note You do not have to implement this for your language if you are not going to use it(the du-chain itself does not and should not depend on it).
 508     * */
 509   virtual Declaration* clonePrivate() const;
 510
 511   void updateCodeModel();
 512
 513   void rebuildDynamicData(DUContext* parent, uint ownIndex);
 514
 515   friend class DUContext;
 516   friend class IndexedDeclaration;
 517   friend class LocalIndexedDeclaration;
 518   friend class TopDUContextDynamicData;
 519   DUContext* m_context;
 520   TopDUContext* m_topContext;
 521   int m_indexInTopContext;
 522 };
 523
 524 }
 525
 526 #endif // DECLARATION_H
 527
 528 // kate: space-indent on; indent-width 2; tab-width 4; replace-tabs on; auto-insert-doxygen on