File indexing completed on 2024-06-16 04:23:13

 /*
     SPDX-FileCopyrightText: 2008 Andreas Pakulat <apaku@gmx.de>
     SPDX-FileCopyrightText: 2006 Roberto Raggi <roberto@kdevelop.org>
     SPDX-FileCopyrightText: 2006-2008 Hamish Rodda <rodda@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef KDEVPLATFORM_ABSTRACTABSTRACTCONTEXTBUILDER_H
 #define KDEVPLATFORM_ABSTRACTABSTRACTCONTEXTBUILDER_H
 
 #include <climits>
 
 #include "../topducontext.h"
 #include "../duchainpointer.h"
 #include "../duchainlock.h"
 #include "../duchain.h"
 #include "../ducontext.h"
 #include "../identifier.h"
 #include "../parsingenvironment.h"
 
 #include <serialization/indexedstring.h>
 #include <util/stack.h>
 
 namespace KDevelop {
 /**
  * \short Abstract definition-use chain context builder class
  *
  * The AbstractContextBuilder is a convenience class template for creating customized
  * definition-use chain context builders from an AST.  It simplifies:
  * - creating or modifying an existing DUContext tree
  * - following a DUContext tree for second and subsequent passes, if required
  * - opening and closing DUContext instances
  * - tracking which DUContext instances are still present when recompiling, and removing DUContexts which no longer exist in the source code.
  *
  * \author Hamish Rodda \<rodda@kde.org\>
  */
 template <typename T, typename NameT>
 class AbstractContextBuilder
 {
 public:
     /// Constructor.
     AbstractContextBuilder() : m_compilingContexts(false)
         , m_recompiling(false)
         , m_lastContext(nullptr)
     {
     }
 
     virtual ~AbstractContextBuilder()
     {
     }
 
     /**
      * Entry point for building a definition-use chain with this builder.
      *
      * This function determines whether we are updating a chain, or creating a new one.  If we are
      * creating a new chain, a new TopDUContext is created and registered with DUChain.
      *
      * \param url Url of the document being parsed.
      * \param node AST node to start building from.
      * \param updateContext TopDUContext to update if a duchain was previously created for this url, otherwise pass a null pointer.
      *
      * \returns the newly created or updated TopDUContext pointer.
      */
     virtual ReferencedTopDUContext build(const IndexedString& url, T* node,
                                          const ReferencedTopDUContext& updateContext
                                              = ReferencedTopDUContext())
     {
         m_compilingContexts = true;
         m_url = url;
 
         ReferencedTopDUContext top;
         {
             DUChainWriteLocker lock(DUChain::lock());
             top = updateContext.data();
 
             if (top) {
                 m_recompiling = true;
                 Q_ASSERT(top->type() == DUContext::Global);
                 Q_ASSERT(DUChain::self()->chainForIndex(top->ownIndex()) == top);
             } else
             {
                 top = newTopContext(RangeInRevision(CursorInRevision(0, 0), CursorInRevision(INT_MAX, INT_MAX)));
                 DUChain::self()->addDocumentChain(top);
                 top->setType(DUContext::Global);
             }
 
             setEncountered(top);
             setContextOnNode(node, top);
         }
 
         supportBuild(node, top);
 
         m_compilingContexts = false;
         return top;
     }
 
 protected:
     /**
      * Support another builder by tracking the current context.
      * @param node the given node.
      * @param context the context to use. Must be set when the given node has no context. When it has one attached, this parameter is not needed.
      */
     virtual void supportBuild(T* node, DUContext* context = nullptr)
     {
         if (!context)
             context = contextFromNode(node);
 
         Q_ASSERT(context);
 
         openContext(context);
 
         startVisiting(node);
 
         closeContext();
 
         Q_ASSERT(m_contextStack.isEmpty());
     }
 
     /**
      * Entry point to your visitor.  Reimplement and call the appropriate visit function.
      *
      * \param node AST node to visit.
      */
     virtual void startVisiting(T* node) = 0;
 
     /**
      * Associate a \a context with a given AST \a node.  Once called on a \a node, the
      * contextFromNode() function should return this \a context when called.
      *
      * \param node AST node to associate
      * \param context DUContext to associate
      */
     virtual void setContextOnNode(T* node, DUContext* context) = 0;
 
     /**
      * Retrieve an associated DUContext from the given \a node.  Used on second and
      * subsequent passes of the context builder (for supporting other builds)
      *
      * \param node AST node which was previously associated
      * \returns the DUContext which was previously associated
      */
     virtual DUContext* contextFromNode(T* node) = 0;
 
     /**
      * Retrieves a text range from the given nodes.
      *
      * As editor integrators have to be extended to determine ranges from AST nodes,
      * this function must be reimplemented to allow generic retrieving of rangs from nodes.
      *
      * \param fromNode the AST node to start from (on the start boundary)
      * \param toNode the AST node to end at (on the end boundary)
      *
      * \returns the text range encompassing the given AST node(s)
      */
     virtual RangeInRevision editorFindRange(T* fromNode, T* toNode) = 0;
 
     /**
      * Retrieve a text range for the given nodes.  This is a special function required
      * by c++ support as a different range may need to be retrieved depending on
      * whether macros are involved.  It is not usually required to implement this
      * function separately to editorFindRange() for other languages.
      *
      * \param fromNode the AST node to start from (on the start boundary)
      * \param toNode the AST node to end at (on the end boundary)
      *
      * \returns the text range encompassing the given AST node(s)
      */
     virtual RangeInRevision editorFindRangeForContext(T* fromNode, T* toNode)
     {
         return editorFindRange(fromNode, toNode);
     }
 
     /**
      * Determine the QualifiedIdentifier which corresponds to the given ast \a node.
      *
      * \param node ast node which represents an identifier
      * \return the qualified identifier determined from \a node
      */
     virtual QualifiedIdentifier identifierForNode(NameT* node) = 0;
 
     /**
      * Create a new DUContext from the given \a range.
      *
      * This exists so that you can create custom DUContext subclasses for your
      * language if you need to.
      *
      * \param range range for the new context to encompass
      * \returns the newly created context
      */
     virtual DUContext* newContext(const RangeInRevision& range)
     {
         return new DUContext(range, currentContext());
     }
 
     /**
      * Create a new TopDUContext from the given \a range.
      *
      * This exists so that you can create custom TopDUContext subclasses for your
      * language if you need to.
      *
      * \returns the newly created context
      */
     virtual TopDUContext* newTopContext(const RangeInRevision& range, ParsingEnvironmentFile* file = nullptr)
     {
         return new TopDUContext(m_url, range, file);
     }
 
     /// Determine the currently open context. \returns the current context.
     inline DUContext* currentContext() const { return m_contextStack.top(); }
     /// Determine the last closed context. \returns the last closed context.
     inline DUContext* lastContext() const { return m_lastContext; }
     /// Clears the last closed context.
     inline void clearLastContext() { m_lastContext = nullptr; }
 
     inline void setLastContext(DUContext* context) { m_lastContext = context; }
 
     TopDUContext* topContext() const
     {
         return currentContext()->topContext();
     }
 
     /**
      * Determine if we are recompiling an existing definition-use chain, or if
      * a new chain is being created from scratch.
      *
      * \returns true if an existing duchain is being updated, otherwise false.
      */
     inline bool recompiling() const { return m_recompiling; }
 
     /**
      * Tell the context builder whether we are recompiling an existing definition-use chain, or if
      * a new chain is being created from scratch.
      *
      * \param recomp set to true if an existing duchain is being updated, otherwise false.
      */
     inline void setRecompiling(bool recomp) { m_recompiling = recomp; }
 
     /**
      * Determine whether this pass will create DUContext instances.
      *
      * On the first pass of definition-use chain compiling, DUContext instances
      * are created to represent contexts in the source code.  These contexts are
      * associated with their AST nodes at the time (see setContextOnNode()).
      *
      * On second and subsequent passes, the contexts already exist and thus can be
      * retrieved through contextFromNode().
      *
      * \returns true if compiling contexts (ie. 1st pass), otherwise false.
      */
     inline bool compilingContexts() const { return m_compilingContexts; }
 
     /**
      * Sets whether we need to create ducontexts, ie. if this is the first pass.
      *
      * \sa compilingContexts()
      */
     inline void setCompilingContexts(bool compilingContexts) { m_compilingContexts = compilingContexts; }
 
     /**
      * Create child contexts for only a portion of the document.
      *
      * \param node The AST node which corresponds to the context to parse
      * \param parent The DUContext which encompasses the \a node.
      * \returns The DUContext which was reparsed, ie. \a parent.
      */
     DUContext* buildSubContexts(T* node, DUContext* parent)
     {
         //     m_compilingContexts = true;
         //     m_recompiling = false;
         setContextOnNode(node, parent);
         {
             openContext(contextFromNode(node));
             startVisiting(node);
             closeContext();
         }
 
         m_compilingContexts = false;
 
         if (contextFromNode(node) == parent) {
             qDebug() <<
                 "Error in AbstractContextBuilder::buildSubContexts(...): du-context was not replaced with new one";
             DUChainWriteLocker lock(DUChain::lock());
             deleteContextOnNode(node);
         }
 
         return contextFromNode(node);
     }
 
     /**
      * Delete the DUContext which is associated with the given \a node,
      * and remove the association.
      *
      * \param node Node which is associated with the context to delete.
      */
     void deleteContextOnNode(T* node)
     {
         delete contextFromNode(node);
         setContextOnNode(node, nullptr);
     }
 
     /**
      * Open a context, and create / update it if necessary.
      *
      * \param rangeNode The range which encompasses the context.
      * \param type The type of context to open.
      * \param identifier The range which encompasses the name of this context, if one exists.
      * \returns the opened context.
      */
     DUContext* openContext(T* rangeNode, DUContext::ContextType type, NameT* identifier = nullptr)
     {
         if (m_compilingContexts) {
             DUContext* ret = openContextInternal(editorFindRangeForContext(rangeNode,
                                                                            rangeNode), type,
                                                  identifier ? identifierForNode(identifier) : QualifiedIdentifier());
             setContextOnNode(rangeNode, ret);
             return ret;
         } else
         {
             openContext(contextFromNode(rangeNode));
             return currentContext();
         }
     }
 
     /**
      * Open a context, and create / update it if necessary.
      *
      * \param node The range to associate with the context.
      * \param range A custom range which the context should encompass.
      * \param type The type of context to open.
      * \param identifier The range which encompasses the name of this context, if one exists.
      * \returns the opened context.
      */
     DUContext* openContext(T* node, const RangeInRevision& range, DUContext::ContextType type,
                            NameT* identifier = nullptr)
     {
         if (m_compilingContexts) {
             DUContext* ret = openContextInternal(range, type, identifier ? identifierForNode(
                                                      identifier) : QualifiedIdentifier());
             setContextOnNode(node, ret);
             return ret;
         } else {
             openContext(contextFromNode(node));
             return currentContext();
         }
     }
 
     /**
      * Open a context, and create / update it if necessary.
      *
      * \param node The range to associate with the context.
      * \param range A custom range which the context should encompass.
      * \param type The type of context to open.
      * \param id The identifier for this context
      * \returns the opened context.
      */
     DUContext* openContext(T* node, const RangeInRevision& range, DUContext::ContextType type,
                            const QualifiedIdentifier& id)
     {
         if (m_compilingContexts) {
             DUContext* ret = openContextInternal(range, type, id);
             setContextOnNode(node, ret);
             return ret;
         } else {
             openContext(contextFromNode(node));
             return currentContext();
         }
     }
 
     /**
      * Open a context, and create / update it if necessary.
      *
      * \param rangeNode The range which encompasses the context.
      * \param type The type of context to open.
      * \param identifier The identifier which corresponds to the context.
      * \returns the opened context.
      */
     DUContext* openContext(T* rangeNode, DUContext::ContextType type, const QualifiedIdentifier& identifier)
     {
         if (m_compilingContexts) {
             DUContext* ret = openContextInternal(editorFindRangeForContext(rangeNode, rangeNode), type, identifier);
             setContextOnNode(rangeNode, ret);
             return ret;
         } else
         {
             openContext(contextFromNode(rangeNode));
             return currentContext();
         }
     }
 
     /**
      * Open a context, and create / update it if necessary.
      *
      * \param fromRange The range which starts the context.
      * \param toRange The range which ends the context.
      * \param type The type of context to open.
      * \param identifier The identifier which corresponds to the context.
      * \returns the opened context.
      */
     DUContext* openContext(T* fromRange, T* toRange, DUContext::ContextType type,
                            const QualifiedIdentifier& identifier = QualifiedIdentifier())
     {
         if (m_compilingContexts) {
             DUContext* ret = openContextInternal(editorFindRangeForContext(fromRange, toRange), type, identifier);
             setContextOnNode(fromRange, ret);
             return ret;
         } else
         {
             openContext(contextFromNode(fromRange));
             return currentContext();
         }
     }
 
     /**
      * Open a newly created or previously existing context.
      *
      * The open context is put on the context stack, and becomes the new
      * currentContext().
      *
      * \warning When you call this, you also have to open a range! If you want to re-use
      * the range associated to the context, use injectContext
      *
      * \param newContext Context to open.
      */
     virtual void openContext(DUContext* newContext)
     {
         m_contextStack.push(newContext);
         m_nextContextStack.push(0);
     }
 
     /**
      * This can be used to temporarily change the current context.
      * \param ctx The context to be injected
      * */
     void injectContext(DUContext* ctx)
     {
         openContext(ctx);
     }
 
     /**
      * Use this to close the context previously injected with injectContext.
      * */
     void closeInjectedContext()
     {
         m_contextStack.pop();
         m_nextContextStack.pop();
     }
 
     /**
      * Close the current DUContext.  When recompiling, this function will remove any
      * contexts that were not encountered in this passing run.
      * \note The DUChain write lock is already held here.
      */
     virtual void closeContext()
     {
         {
             DUChainWriteLocker lock(DUChain::lock());
             //Remove all slaves that were not encountered while parsing
             if (m_compilingContexts)
                 currentContext()->cleanIfNotEncountered(m_encountered);
             setEncountered(currentContext());
 
             m_lastContext = currentContext();
         }
 
         m_contextStack.pop();
         m_nextContextStack.pop();
     }
 
     /**
      * Remember that a specific item has been encountered while parsing.
      * All items that are not encountered will be deleted at some stage.
      *
      * \param item duchain item that was encountered.
      * */
     void setEncountered(DUChainBase* item)
     {
         m_encountered.insert(item);
     }
 
     /**
      * Determine whether the given \a item is in the set of encountered items.
      *
      * @return true if the \a item has been encountered, otherwise false.
      * */
     bool wasEncountered(DUChainBase* item)
     {
         return m_encountered.contains(item);
     }
 
     /**
      * Set the current identifier to \a id.
      *
      * \param id the new current identifier.
      */
     void setIdentifier(const QString& id)
     {
         m_identifier = Identifier(id);
         m_qIdentifier.push(m_identifier);
     }
 
     /**
      * Determine the current identifier.
      * \returns the current identifier.
      */
     QualifiedIdentifier qualifiedIdentifier() const
     {
         return m_qIdentifier;
     }
 
     /**
      * Clears the current identifier.
      */
     void clearQualifiedIdentifier()
     {
         m_qIdentifier.clear();
     }
 
     /**
      * Retrieve the current context stack.  This function is not expected
      * to be used often and may be phased out.
      *
      * \todo Audit whether access to the context stack is still required, and provide
      *       replacement functionality if possible.
      */
     const Stack<DUContext*>& contextStack() const
     {
         return m_contextStack;
     }
 
     /**
      * Access the index of the child context which has been encountered.
      *
      * \todo further delineate the role of this function and rename / document better.
      * \todo make private again?
      */
     int& nextContextIndex()
     {
         return m_nextContextStack.top();
     }
 
     /**
      * Open a context, either creating it if it does not exist, or referencing a previously existing
      * context if already encountered in a previous duchain parse run (when recompiling()).
      *
      * \param range The range of the context.
      * \param type The type of context to create.
      * \param identifier The identifier which corresponds to the context.
      * \returns the opened context.
      */
 
     virtual DUContext* openContextInternal(const RangeInRevision& range, DUContext::ContextType type,
                                            const QualifiedIdentifier& identifier)
     {
         Q_ASSERT(m_compilingContexts);
         DUContext* ret = nullptr;
 
         {
             if (recompiling()) {
                 DUChainReadLocker readLock(DUChain::lock());
                 const QVector<DUContext*>& childContexts = currentContext()->childContexts();
 
                 int currentIndex = nextContextIndex();
                 const auto indexedIdentifier = IndexedQualifiedIdentifier(identifier);
 
                 for (; currentIndex < childContexts.count(); ++currentIndex) {
                     DUContext* child = childContexts.at(currentIndex);
                     RangeInRevision childRange = child->range();
 
                     if (child->type() != type) {
                         continue;
                     }
                     // We cannot update a contexts local scope identifier, that will break many other parts, like e.g.
                     // the CodeModel of child contexts or declarations.
                     // For unnamed child-ranges, we still do range-comparison, because we cannot distinguish them in other ways
                     if ((!identifier.isEmpty() && child->indexedLocalScopeIdentifier() == indexedIdentifier)
                         || (identifier.isEmpty() && child->indexedLocalScopeIdentifier().isEmpty() &&
                             !childRange.isEmpty() && childRange == range)) {
                         // Match
                         ret = child;
                         readLock.unlock();
                         DUChainWriteLocker writeLock(DUChain::lock());
 
                         ret->clearImportedParentContexts();
                         ++currentIndex;
                         break;
                     }
                 }
 
                 if (ret)
                     nextContextIndex() = currentIndex; //If we had a match, jump forward to that position
                 ///@todo We should also somehow make sure we don't get quadratic worst-case effort while updating.
             }
 
             if (!ret) {
                 DUChainWriteLocker writeLock(DUChain::lock());
 
                 ret = newContext(range);
                 ret->setType(type);
 
                 if (!identifier.isEmpty())
                     ret->setLocalScopeIdentifier(identifier);
 
                 setInSymbolTable(ret);
             } else {
                 DUChainWriteLocker writeLock(DUChain::lock());
                 Q_ASSERT(ret->localScopeIdentifier() == identifier);
                 if (ret->parentContext())
                     ret->setRange(range);
             }
         }
 
         m_encountered.insert(ret);
         openContext(ret);
         return ret;
     }
 
     ///This function should call context->setInSymbolTable(..) with an appropriate decision. The duchain is write-locked when this is called.
     virtual void setInSymbolTable(DUContext* context)
     {
         if (!context->parentContext()->inSymbolTable()) {
             context->setInSymbolTable(false);
             return;
         }
         DUContext::ContextType type = context->type();
         context->setInSymbolTable(
             type == DUContext::Class || type == DUContext::Namespace || type == DUContext::Global || type == DUContext::Helper ||
             type == DUContext::Enum);
     }
 
     /// @returns the current url/path ot the document we are parsing
     IndexedString document() const
     {
         return m_url;
     }
 
 private:
 
     Identifier m_identifier;
     IndexedString m_url;
     QualifiedIdentifier m_qIdentifier;
     bool m_compilingContexts : 1;
     bool m_recompiling : 1;
     Stack<int> m_nextContextStack;
     DUContext* m_lastContext;
     //Here all valid declarations/uses/... will be collected
     QSet<DUChainBase*> m_encountered;
     Stack<DUContext*> m_contextStack;
 };
 }
 
 #endif