KDevelop::AbstractContextBuilder< T, NameT > Class Template Reference

#include <abstractcontextbuilder.h>

Public Member Functions
	AbstractContextBuilder ()
virtual	~AbstractContextBuilder ()
virtual ReferencedTopDUContext	build (const IndexedString &url, T *node, const ReferencedTopDUContext &updateContext=ReferencedTopDUContext())

Protected Member Functions
DUContext *	buildSubContexts (T *node, DUContext *parent)
void	clearLastContext ()
void	clearQualifiedIdentifier ()
virtual void	closeContext ()
void	closeInjectedContext ()
bool	compilingContexts () const
virtual DUContext *	contextFromNode (T *node)=0
const Stack< DUContext * > &	contextStack () const
DUContext *	currentContext () const
void	deleteContextOnNode (T *node)
IndexedString	document () const
virtual RangeInRevision	editorFindRange (T *fromNode, T *toNode)=0
virtual RangeInRevision	editorFindRangeForContext (T *fromNode, T *toNode)
virtual QualifiedIdentifier	identifierForNode (NameT *node)=0
void	injectContext (DUContext *ctx)
DUContext *	lastContext () const
virtual DUContext *	newContext (const RangeInRevision &range)
virtual TopDUContext *	newTopContext (const RangeInRevision &range, ParsingEnvironmentFile *file=nullptr)
int &	nextContextIndex ()
virtual void	openContext (DUContext *newContext)
DUContext *	openContext (T *fromRange, T *toRange, DUContext::ContextType type, const QualifiedIdentifier &identifier=QualifiedIdentifier())
DUContext *	openContext (T *node, const RangeInRevision &range, DUContext::ContextType type, const QualifiedIdentifier &id)
DUContext *	openContext (T *node, const RangeInRevision &range, DUContext::ContextType type, NameT *identifier=nullptr)
DUContext *	openContext (T *rangeNode, DUContext::ContextType type, const QualifiedIdentifier &identifier)
DUContext *	openContext (T *rangeNode, DUContext::ContextType type, NameT *identifier=nullptr)
virtual DUContext *	openContextInternal (const RangeInRevision &range, DUContext::ContextType type, const QualifiedIdentifier &identifier)
QualifiedIdentifier	qualifiedIdentifier () const
bool	recompiling () const
void	setCompilingContexts (bool compilingContexts)
virtual void	setContextOnNode (T *node, DUContext *context)=0
void	setEncountered (DUChainBase *item)
void	setIdentifier (const QString &id)
virtual void	setInSymbolTable (DUContext *context)
void	setLastContext (DUContext *context)
void	setRecompiling (bool recomp)
virtual void	startVisiting (T *node)=0
virtual void	supportBuild (T *node, DUContext *context=nullptr)
TopDUContext *	topContext () const
bool	wasEncountered (DUChainBase *item)

Detailed Description

template<typename T, typename NameT>
class KDevelop::AbstractContextBuilder< T, NameT >

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[email protected]@kde[email protected].org>

Definition at line 71 of file abstractcontextbuilder.h.

Constructor & Destructor Documentation

AbstractContextBuilder()

template<typename T , typename NameT >

KDevelop::AbstractContextBuilder< T, NameT >::AbstractContextBuilder ( )

inline

Constructor.

Definition at line 94 of file abstractcontextbuilder.h.

~AbstractContextBuilder()

template<typename T , typename NameT >

virtual KDevelop::AbstractContextBuilder< T, NameT >::~AbstractContextBuilder ( )

inlinevirtual

Definition at line 100 of file abstractcontextbuilder.h.

Member Function Documentation

build()

template<typename T , typename NameT >

virtual ReferencedTopDUContext KDevelop::AbstractContextBuilder< T, NameT >::build ( const IndexedString &  url, T *  node, const ReferencedTopDUContext &  updateContext = ReferencedTopDUContext()  )

inlinevirtual

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.

Parameters

url	Url of the document being parsed.
node	AST node to start building from.
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.

Definition at line 116 of file abstractcontextbuilder.h.

buildSubContexts()

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::buildSubContexts ( T *  node, DUContext *  parent  )

inlineprotected

Create child contexts for only a portion of the document.

Parameters

node	The AST node which corresponds to the context to parse
parent	The DUContext which encompasses the node.

Returns

The DUContext which was reparsed, ie. parent.

Definition at line 318 of file abstractcontextbuilder.h.

clearLastContext()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::clearLastContext ( )

inlineprotected

Clears the last closed context.

Definition at line 265 of file abstractcontextbuilder.h.

clearQualifiedIdentifier()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::clearQualifiedIdentifier ( )

inlineprotected

Clears the current identifier.

Definition at line 565 of file abstractcontextbuilder.h.

closeContext()

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::closeContext ( )

inlineprotectedvirtual

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.

Definition at line 505 of file abstractcontextbuilder.h.

closeInjectedContext()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::closeInjectedContext ( )

inlineprotected

Use this to close the context previously injected with injectContext.

Definition at line 494 of file abstractcontextbuilder.h.

compilingContexts()

template<typename T , typename NameT >

bool KDevelop::AbstractContextBuilder< T, NameT >::compilingContexts ( ) const

inlineprotected

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.

Definition at line 302 of file abstractcontextbuilder.h.

contextFromNode()

template<typename T , typename NameT >

virtual DUContext* KDevelop::AbstractContextBuilder< T, NameT >::contextFromNode ( T *  node )

protectedpure virtual

Retrieve an associated DUContext from the given node.

Used on second and subsequent passes of the context builder (for supporting other builds)

Parameters

node	AST node which was previously associated

Returns

the DUContext which was previously associated

contextStack()

template<typename T , typename NameT >

const Stack<DUContext*>& KDevelop::AbstractContextBuilder< T, NameT >::contextStack ( ) const

inlineprotected

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.

Definition at line 577 of file abstractcontextbuilder.h.

currentContext()

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::currentContext ( ) const

inlineprotected

Determine the currently open context.

Returns

the current context.

Definition at line 261 of file abstractcontextbuilder.h.

deleteContextOnNode()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::deleteContextOnNode ( T *  node )

inlineprotected

Delete the DUContext which is associated with the given node, and remove the association.

Parameters

node	Node which is associated with the context to delete.

Definition at line 347 of file abstractcontextbuilder.h.

document()

template<typename T , typename NameT >

IndexedString KDevelop::AbstractContextBuilder< T, NameT >::document ( ) const

inlineprotected

Returns

the current url/path ot the document we are parsing

Definition at line 683 of file abstractcontextbuilder.h.

editorFindRange()

template<typename T , typename NameT >

virtual RangeInRevision KDevelop::AbstractContextBuilder< T, NameT >::editorFindRange ( T *  fromNode, T *  toNode  )

protectedpure virtual

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.

Parameters

fromNode	the AST node to start from (on the start boundary)
toNode	the AST node to end at (on the end boundary)

Returns

the text range encompassing the given AST node(s)

editorFindRangeForContext()

template<typename T , typename NameT >

virtual RangeInRevision KDevelop::AbstractContextBuilder< T, NameT >::editorFindRangeForContext ( T *  fromNode, T *  toNode  )

inlineprotectedvirtual

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.

Parameters

fromNode	the AST node to start from (on the start boundary)
toNode	the AST node to end at (on the end boundary)

Returns

the text range encompassing the given AST node(s)

Definition at line 220 of file abstractcontextbuilder.h.

identifierForNode()

template<typename T , typename NameT >

virtual QualifiedIdentifier KDevelop::AbstractContextBuilder< T, NameT >::identifierForNode ( NameT *  node )

protectedpure virtual

Determine the QualifiedIdentifier which corresponds to the given ast node.

Parameters

node	ast node which represents an identifier

Returns

the qualified identifier determined from node

injectContext()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::injectContext ( DUContext *  ctx )

inlineprotected

This can be used to temporarily change the current context.

Parameters

ctx	The context to be injected

Definition at line 486 of file abstractcontextbuilder.h.

lastContext()

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::lastContext ( ) const

inlineprotected

Determine the last closed context.

Returns

the last closed context.

Definition at line 263 of file abstractcontextbuilder.h.

newContext()

template<typename T , typename NameT >

virtual DUContext* KDevelop::AbstractContextBuilder< T, NameT >::newContext ( const RangeInRevision &  range )

inlineprotectedvirtual

Create a new DUContext from the given range.

This exists so that you can create custom DUContext subclasses for your language if you need to.

Parameters

range

range for the new context to encompass

Returns

the newly created context

Definition at line 242 of file abstractcontextbuilder.h.

newTopContext()

template<typename T , typename NameT >

virtual TopDUContext* KDevelop::AbstractContextBuilder< T, NameT >::newTopContext ( const RangeInRevision &  range, ParsingEnvironmentFile *  file = nullptr  )

inlineprotectedvirtual

Create a new TopDUContext from the given range.

This exists so that you can create custom TopDUContext subclasses for your language if you need to.

Returns

the newly created context

Definition at line 255 of file abstractcontextbuilder.h.

nextContextIndex()

template<typename T , typename NameT >

int& KDevelop::AbstractContextBuilder< T, NameT >::nextContextIndex ( )

inlineprotected

Access the index of the child context which has been encountered.

Todo:

further delineate the role of this function and rename / document better.

make private again?

Definition at line 588 of file abstractcontextbuilder.h.

openContext() [1/6]

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::openContext ( DUContext *  newContext )

inlineprotectedvirtual

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

Parameters

newContext

Context to open.

Definition at line 476 of file abstractcontextbuilder.h.

openContext() [2/6]

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContext ( T *  fromRange, T *  toRange, DUContext::ContextType  type, const QualifiedIdentifier &  identifier = QualifiedIdentifier()  )

inlineprotected

Open a context, and create / update it if necessary.

Parameters

fromRange	The range which starts the context.
toRange	The range which ends the context.
type	The type of context to open.
identifier	The identifier which corresponds to the context.

Returns

the opened context.

Definition at line 451 of file abstractcontextbuilder.h.

openContext() [3/6]

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContext ( T *  node, const RangeInRevision &  range, DUContext::ContextType  type, const QualifiedIdentifier &  id  )

inlineprotected

Open a context, and create / update it if necessary.

Parameters

node	The range to associate with the context.
range	A custom range which the context should encompass.
type	The type of context to open.
id	The identifier for this context

Returns

the opened context.

Definition at line 408 of file abstractcontextbuilder.h.

openContext() [4/6]

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContext ( T *  node, const RangeInRevision &  range, DUContext::ContextType  type, NameT *  identifier = nullptr  )

inlineprotected

Open a context, and create / update it if necessary.

Parameters

node	The range to associate with the context.
range	A custom range which the context should encompass.
type	The type of context to open.
identifier	The range which encompasses the name of this context, if one exists.

Returns

the opened context.

Definition at line 385 of file abstractcontextbuilder.h.

openContext() [5/6]

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContext ( T *  rangeNode, DUContext::ContextType  type, const QualifiedIdentifier &  identifier  )

inlineprotected

Open a context, and create / update it if necessary.

Parameters

rangeNode	The range which encompasses the context.
type	The type of context to open.
identifier	The identifier which corresponds to the context.

Returns

the opened context.

Definition at line 429 of file abstractcontextbuilder.h.

openContext() [6/6]

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContext ( T *  rangeNode, DUContext::ContextType  type, NameT *  identifier = nullptr  )

inlineprotected

Open a context, and create / update it if necessary.

Parameters

rangeNode	The range which encompasses the context.
type	The type of context to open.
identifier	The range which encompasses the name of this context, if one exists.

Returns

the opened context.

Definition at line 361 of file abstractcontextbuilder.h.

openContextInternal()

template<typename T , typename NameT >

virtual DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContextInternal ( const RangeInRevision &  range, DUContext::ContextType  type, const QualifiedIdentifier &  identifier  )

inlineprotectedvirtual

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()).

Parameters

range	The range of the context.
type	The type of context to create.
identifier	The identifier which corresponds to the context.

Returns

the opened context.

Todo:

We should also somehow make sure we don't get quadratic worst-case effort while updating.

Definition at line 603 of file abstractcontextbuilder.h.

qualifiedIdentifier()

template<typename T , typename NameT >

QualifiedIdentifier KDevelop::AbstractContextBuilder< T, NameT >::qualifiedIdentifier ( ) const

inlineprotected

Determine the current identifier.

Returns

the current identifier.

Definition at line 557 of file abstractcontextbuilder.h.

recompiling()

template<typename T , typename NameT >

bool KDevelop::AbstractContextBuilder< T, NameT >::recompiling ( ) const

inlineprotected

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.

Definition at line 280 of file abstractcontextbuilder.h.

setCompilingContexts()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setCompilingContexts ( bool  compilingContexts )

inlineprotected

Sets whether we need to create ducontexts, ie.

if this is the first pass.

See also

compilingContexts()

Definition at line 309 of file abstractcontextbuilder.h.

setContextOnNode()

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::setContextOnNode ( T *  node, DUContext *  context  )

protectedpure virtual

Associate a context with a given AST node.

Once called on a node, the contextFromNode() function should return this context when called.

Parameters

node	AST node to associate
context	DUContext to associate

setEncountered()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setEncountered ( DUChainBase *  item )

inlineprotected

Remember that a specific item has been encoutered while parsing.

All items that are not encountered will be deleted at some stage.

Parameters

item	duchain item that was encountered.

Definition at line 527 of file abstractcontextbuilder.h.

setIdentifier()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setIdentifier ( const QString &  id )

inlineprotected

Set the current identifier to id.

Parameters

id	the new current identifier.

Definition at line 547 of file abstractcontextbuilder.h.

setInSymbolTable()

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::setInSymbolTable ( DUContext *  context )

inlineprotectedvirtual

This function should call context->setInSymbolTable(..) with an appropriate decision. The duchain is write-locked when this is called.

Definition at line 670 of file abstractcontextbuilder.h.

setLastContext()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setLastContext ( DUContext *  context )

inlineprotected

Definition at line 267 of file abstractcontextbuilder.h.

setRecompiling()

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setRecompiling ( bool  recomp )

inlineprotected

Tell the context builder whether we are recompiling an existing definition-use chain, or if a new chain is being created from scratch.

Parameters

recomp

set to true if an existing duchain is being updated, otherwise false.

Definition at line 288 of file abstractcontextbuilder.h.

startVisiting()

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::startVisiting ( T *  node )

protectedpure virtual

Entry point to your visitor.

Reimplement and call the appropriate visit function.

Parameters

node	AST node to visit.

supportBuild()

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::supportBuild ( T *  node, DUContext *  context = nullptr  )

inlineprotectedvirtual

Support another builder by tracking the current context.

Parameters

node	the given node.
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.

Definition at line 155 of file abstractcontextbuilder.h.

topContext()

template<typename T , typename NameT >

TopDUContext* KDevelop::AbstractContextBuilder< T, NameT >::topContext ( ) const

inlineprotected

Definition at line 269 of file abstractcontextbuilder.h.

wasEncountered()

template<typename T , typename NameT >

bool KDevelop::AbstractContextBuilder< T, NameT >::wasEncountered ( DUChainBase *  item )

inlineprotected

Determine whether the given item is in the set of encountered items.

Returns

true if the item has been encountered, otherwise false.

Definition at line 537 of file abstractcontextbuilder.h.

---

The documentation for this class was generated from the following file:

• abstractcontextbuilder.h