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

Abstract definition-use chain context builder class. More...

#include <abstractcontextbuilder.h>

List of all members.

Public Member Functions
	AbstractContextBuilder ()
virtual	~AbstractContextBuilder ()
virtual ReferencedTopDUContext	build (const IndexedString &url, T *node, ReferencedTopDUContext updateContext=ReferencedTopDUContext(), bool useSmart=true)
void	setEditor (EditorIntegrator *editor, bool ownsEditorIntegrator)
Protected Member Functions
DUContext *	buildSubContexts (const KUrl &url, T *node, DUContext *parent)
void	clearLastContext ()
void	clearQualifiedIdentifier ()
virtual void	closeContext ()
void	closeInjectedContext (const LockedSmartInterface &iface)
bool	compilingContexts () const
virtual DUContext *	contextFromNode (T *node)=0
const QStack< DUContext * > &	contextStack () const
DUContext *	currentContext () const
void	deleteContextOnNode (T *node)
EditorIntegrator *	editor () const
virtual KTextEditor::Range	editorFindRange (T *fromNode, T *toNode)=0
virtual KTextEditor::Range	editorFindRangeForContext (T *fromNode, T *toNode)
virtual QualifiedIdentifier	identifierForNode (NameT *node)=0
void	injectContext (const LockedSmartInterface &iface, DUContext *ctx, KTextEditor::SmartRange *range=0)
DUContext *	lastContext () const
virtual DUContext *	newContext (const SimpleRange &range)
virtual TopDUContext *	newTopContext (const SimpleRange &range, ParsingEnvironmentFile *file=0)
int &	nextContextIndex ()
virtual void	openContext (DUContext *newContext)
DUContext *	openContext (T *fromRange, T *toRange, DUContext::ContextType type, const QualifiedIdentifier &identifier=QualifiedIdentifier())
DUContext *	openContext (T *rangeNode, DUContext::ContextType type, const QualifiedIdentifier &identifier)
DUContext *	openContext (T *node, const KDevelop::SimpleRange &range, DUContext::ContextType type, QualifiedIdentifier id)
DUContext *	openContext (T *node, const KDevelop::SimpleRange &range, DUContext::ContextType type, NameT *identifier=0)
DUContext *	openContext (T *rangeNode, DUContext::ContextType type, NameT *identifier=0)
virtual DUContext *	openContextInternal (const SimpleRange &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=0)
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:

• use of your editor integrator
• 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>

Definition at line 62 of file abstractcontextbuilder.h.

---

Constructor & Destructor Documentation

template<typename T , typename NameT >

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

(

)

[inline]

Constructor.

Definition at line 66 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

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

(

)

[inline, virtual]

Destructor. Deletes the editor integrator, if one was created specifically for this builder only.

Definition at line 76 of file abstractcontextbuilder.h.

---

Member Function Documentation

template<typename T , typename NameT >

virtual ReferencedTopDUContext KDevelop::AbstractContextBuilder< T, NameT >::build	(	const IndexedString &	url,
		T *	node,
		ReferencedTopDUContext	updateContext = ReferencedTopDUContext(),
		bool	useSmart = true
	)			[inline, virtual]

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 107 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::buildSubContexts	(	const KUrl &	url,
		T *	node,
		DUContext *	parent
	)			[inline, protected]

Create child contexts for only a portion of the document at url.

Parameters:

	url	The url of the document to parse
	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 351 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

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

(

)

[inline, protected]

Clears the last closed context.

Definition at line 302 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

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

(

)

[inline, protected]

Clears the current identifier.

Definition at line 648 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

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

(

)

[inline, protected, virtual]

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 586 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

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

(

const LockedSmartInterface &

iface

)

[inline, protected]

Use this to close the context previously injected with injectContext.

Definition at line 574 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

bool KDevelop::AbstractContextBuilder< T, NameT >::compilingContexts

(

)

const [inline, protected]

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 334 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

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

(

T *

node

)

[protected, pure 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

template<typename T , typename NameT >

const QStack<DUContext*>& KDevelop::AbstractContextBuilder< T, NameT >::contextStack

(

)

const [inline, protected]

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 670 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::currentContext

(

)

const [inline, protected]

Determine the currently open context.

Returns:

the current context.

Definition at line 298 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::deleteContextOnNode

(

T *

node

)

[inline, protected]

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 389 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

EditorIntegrator* KDevelop::AbstractContextBuilder< T, NameT >::editor

(

)

const [inline, protected]

Retrieve the associated editor integrator.

Returns:

the editor integrator being used by this builder.

Definition at line 658 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

virtual KTextEditor::Range KDevelop::AbstractContextBuilder< T, NameT >::editorFindRange	(	T *	fromNode,
		T *	toNode
	)			[protected, pure 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)

template<typename T , typename NameT >

virtual KTextEditor::Range KDevelop::AbstractContextBuilder< T, NameT >::editorFindRangeForContext	(	T *	fromNode,
		T *	toNode
	)			[inline, protected, virtual]

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 257 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

virtual QualifiedIdentifier KDevelop::AbstractContextBuilder< T, NameT >::identifierForNode

(

NameT *

node

)

[protected, pure 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

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::injectContext	(	const LockedSmartInterface &	iface,
		DUContext *	ctx,
		KTextEditor::SmartRange *	range = 0
	)			[inline, protected]

This can be used to temporarily change the current context.

Parameters:

range

The range that will be used as new current range, or zero(then the range associated to the context is used)

Definition at line 566 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::lastContext

(

)

const [inline, protected]

Determine the last closed context.

Returns:

the last closed context.

Definition at line 300 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

virtual DUContext* KDevelop::AbstractContextBuilder< T, NameT >::newContext

(

const SimpleRange &

range

)

[inline, protected, virtual]

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 279 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

virtual TopDUContext* KDevelop::AbstractContextBuilder< T, NameT >::newTopContext	(	const SimpleRange &	range,
		ParsingEnvironmentFile *	file = 0
	)			[inline, protected, virtual]

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 292 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

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

(

)

[inline, protected]

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 681 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::openContext

(

DUContext *

newContext

)

[inline, protected, virtual]

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 556 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

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

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 523 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

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

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 491 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContext	(	T *	node,
		const KDevelop::SimpleRange &	range,
		DUContext::ContextType	type,
		QualifiedIdentifier	id
	)			[inline, protected]

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 identifier for this context

Returns:

the opened context.

Definition at line 463 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContext	(	T *	node,
		const KDevelop::SimpleRange &	range,
		DUContext::ContextType	type,
		NameT *	identifier = 0
	)			[inline, protected]

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 434 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContext	(	T *	rangeNode,
		DUContext::ContextType	type,
		NameT *	identifier = 0
	)			[inline, protected]

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 403 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

virtual DUContext* KDevelop::AbstractContextBuilder< T, NameT >::openContextInternal	(	const SimpleRange &	range,
		DUContext::ContextType	type,
		const QualifiedIdentifier &	identifier
	)			[inline, protected, virtual]

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.

Definition at line 695 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

QualifiedIdentifier KDevelop::AbstractContextBuilder< T, NameT >::qualifiedIdentifier

(

)

const [inline, protected]

Determine the current identifier.

Returns:

the current identifier.

Definition at line 640 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

bool KDevelop::AbstractContextBuilder< T, NameT >::recompiling

(

)

const [inline, protected]

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 312 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setCompilingContexts

(

bool

compilingContexts

)

[inline, protected]

Sets whether we need to create ducontexts, ie.

if this is the first pass.

See also:

compilingContexts()

Definition at line 341 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::setContextOnNode	(	T *	node,
		DUContext *	context
	)			[protected, pure 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

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setEditor	(	EditorIntegrator *	editor,
		bool	ownsEditorIntegrator
	)			[inline]

Associates an editor integrator with this builder.

Parameters:

	editor	EditorIntegrator instance to use
	ownsEditorIntegrator	set to true if this builder created the editor integrator (and should thus delete it later), or false if the editor integrator is owned by another object.

Definition at line 89 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setEncountered

(

DUChainBase *

item

)

[inline, protected]

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 610 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setIdentifier

(

const QString &

id

)

[inline, protected]

Set the current identifier to id.

Parameters:

id

the new current identifier.

Definition at line 630 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::setInSymbolTable

(

DUContext *

context

)

[inline, protected, virtual]

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

Definition at line 804 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

void KDevelop::AbstractContextBuilder< T, NameT >::setRecompiling

(

bool

recomp

)

[inline, protected]

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 320 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::startVisiting

(

T *

node

)

[protected, pure virtual]

Entry point to your visitor.

Reimplement and call the appropriate visit function.

Parameters:

node

AST node to visit.

template<typename T , typename NameT >

virtual void KDevelop::AbstractContextBuilder< T, NameT >::supportBuild	(	T *	node,
		DUContext *	context = 0
	)			[inline, protected, virtual]

Support another builder by tracking the current context.

Parameters:

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 184 of file abstractcontextbuilder.h.

template<typename T , typename NameT >

bool KDevelop::AbstractContextBuilder< T, NameT >::wasEncountered

(

DUChainBase *

item

)

[inline, protected]

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 620 of file abstractcontextbuilder.h.

---

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

• abstractcontextbuilder.h