#include <ducontext.h>

Inheritance diagram for KDevelop::DUContext:

Classes
struct	Import

struct	SearchItem

Public Types
enum	{ Identity = 2 }

enum	ContextType : quint8 { Global, Namespace, Class, Function, Template, Enum, Helper, Other }

using	DeclarationList = QList< Declaration * >

enum	SearchFlag { NoSearchFlags = 0, InImportedParentContext = 1, OnlyContainerTypes = 2, DontSearchInParent, NoUndefinedTemplateParams, DirectQualifiedLookup, NoFiltering, OnlyFunctions, NoImportsCheck, NoSelfLookUp, DontResolveAliases = 512, LastSearchFlag = 1024 }

Public Types inherited from KDevelop::DUChainBase
enum	{ Identity = 1 }

Public Member Functions
	DUContext (const RangeInRevision &range, DUContext *parent=nullptr, bool anonymous=false)

	DUContext (DUContextData &)

	~DUContext () override

virtual void	addImportedParentContext (DUContext *context, const CursorInRevision &position=CursorInRevision::invalid(), bool anonymous=false, bool temporary=false)

bool	addIndirectImport (const DUContext::Import &import)

QVector< QPair< Declaration *, int > >	allDeclarations (const CursorInRevision &position, const TopDUContext *topContext, bool searchInParents=true) const

void	changeUseRange (int useIndex, const RangeInRevision &range)

QVector< DUContext * >	childContexts () const

void	cleanIfNotEncountered (const QSet< DUChainBase * > &encountered)

virtual void	clearImportedParentContexts ()

QVector< Declaration * >	clearLocalDeclarations ()

virtual AbstractNavigationWidget *	createNavigationWidget (Declaration decl=nullptr, TopDUContext topContext=nullptr, AbstractNavigationWidget::DisplayHints hints=AbstractNavigationWidget::NoHints) const

int	createUse (int declarationIndex, const RangeInRevision &range, int insertBefore=-1)

void	deleteChildContextsRecursively ()

void	deleteLocalDeclarations ()

void	deleteUse (int index)

virtual void	deleteUses ()

virtual void	deleteUsesRecursively ()

int	depth () const

bool	equalScopeIdentifier (const DUContext *rhs) const

DUContext *	findContext (const CursorInRevision &position, DUContext *parent=nullptr) const

DUContext *	findContextAt (const CursorInRevision &position, bool includeBorders=false) const

DUContext *	findContextIncluding (const RangeInRevision &range) const

Declaration *	findDeclarationAt (const CursorInRevision &position) const

QList< Declaration * >	findDeclarations (const Identifier &identifier, const CursorInRevision &position=CursorInRevision::invalid(), const TopDUContext *topContext=nullptr, SearchFlags flags=NoSearchFlags) const

QList< Declaration * >	findDeclarations (const IndexedIdentifier &identifier, const CursorInRevision &position=CursorInRevision::invalid(), const TopDUContext *topContext=nullptr, SearchFlags flags=NoSearchFlags) const

QList< Declaration * >	findDeclarations (const QualifiedIdentifier &identifier, const CursorInRevision &position=CursorInRevision::invalid(), const AbstractType::Ptr &dataType=AbstractType::Ptr(), const TopDUContext *topContext=nullptr, SearchFlags flags=NoSearchFlags) const

virtual bool	findDeclarationsInternal (const SearchItem::PtrList &identifiers, const CursorInRevision &position, const AbstractType::Ptr &dataType, DeclarationList &ret, const TopDUContext *source, SearchFlags flags, uint depth) const

QList< Declaration * >	findLocalDeclarations (const Identifier &identifier, const CursorInRevision &position=CursorInRevision::invalid(), const TopDUContext *topContext=nullptr, const AbstractType::Ptr &dataType=AbstractType::Ptr(), SearchFlags flags=NoSearchFlags) const

QList< Declaration * >	findLocalDeclarations (const IndexedIdentifier &identifier, const CursorInRevision &position=CursorInRevision::invalid(), const TopDUContext *topContext=nullptr, const AbstractType::Ptr &dataType=AbstractType::Ptr(), SearchFlags flags=NoSearchFlags) const

int	findUseAt (const CursorInRevision &position) const

QVector< QualifiedIdentifier >	fullyApplyAliases (const QualifiedIdentifier &id, const TopDUContext *source) const

virtual QVector< Import >	importedParentContexts () const

virtual QVector< DUContext * >	importers () const

virtual CursorInRevision	importPosition (const DUContext *target) const

virtual bool	imports (const DUContext *origin, const CursorInRevision &position=CursorInRevision::invalid()) const

KDevVarLengthArray< IndexedDUContext >	indexedImporters () const

IndexedQualifiedIdentifier	indexedLocalScopeIdentifier () const

virtual bool	inDUChain () const

bool	inSymbolTable () const

bool	isPropagateDeclarations () const

virtual QVector< Declaration * >	localDeclarations (const TopDUContext *source=nullptr) const

QualifiedIdentifier	localScopeIdentifier () const

DUContext &	operator= (const DUContext &rhs)=delete

Declaration *	owner () const

DUContext *	parentContext () const

bool	parentContextOf (DUContext *context) const

virtual void	removeImportedParentContext (DUContext *context)

void	resortChildContexts ()

void	resortLocalDeclarations ()

QualifiedIdentifier	scopeIdentifier (bool includeClasses=false) const

void	setInSymbolTable (bool inSymbolTable)

void	setLocalScopeIdentifier (const QualifiedIdentifier &identifier)

void	setOwner (Declaration *decl)

void	setPropagateDeclarations (bool propagate)

void	setType (ContextType type)

void	setUseDeclaration (int useIndex, int declarationIndex)

virtual DUContext *	specialize (const IndexedInstantiationInformation &specialization, const TopDUContext *topContext, int upDistance=0)

TopDUContext *	topContext () const override

ContextType	type () const

const Use *	uses () const

int	usesCount () const

virtual void	visit (DUChainVisitor &visitor)

Public Member Functions inherited from KDevelop::DUChainBase
	DUChainBase (const RangeInRevision &range)

	DUChainBase (DUChainBaseData &dd)

virtual	~DUChainBase ()

PersistentMovingRange::Ptr	createRangeMoving () const

void	makeDynamic ()

DUChainBase &	operator= (const DUChainBase &rhs)=delete

RangeInRevision	range () const

KTextEditor::Range	rangeInCurrentRevision () const

virtual void	setData (DUChainBaseData *, bool constructorCalled=true)

void	setRange (const RangeInRevision &range)

KTextEditor::Cursor	transformFromLocalRevision (const CursorInRevision &cursor) const

KTextEditor::Range	transformFromLocalRevision (const RangeInRevision &range) const

CursorInRevision	transformToLocalRevision (const KTextEditor::Cursor &cursor) const

RangeInRevision	transformToLocalRevision (const KTextEditor::Range &range) const

virtual IndexedString	url () const

const QExplicitlySharedDataPointer< DUChainPointerData > &	weakPointer () const

Static Public Member Functions
static bool	declarationHasUses (Declaration *decl)

Protected Member Functions
	DUContext (DUContext &useDataFrom)

	DUContext (DUContextData &dd, const RangeInRevision &range, DUContext *parent=nullptr, bool anonymous=false)

void	applyAliases (const SearchItem::PtrList &identifiers, SearchItem::PtrList &targetIdentifiers, const CursorInRevision &position, bool canBeNamespace, bool onlyImports=false) const

virtual void	applyUpwardsAliases (SearchItem::PtrList &identifiers, const TopDUContext *source) const

void	findLocalDeclarationsInternal (const Identifier &identifier, const CursorInRevision &position, const AbstractType::Ptr &dataType, DeclarationList &ret, const TopDUContext *source, SearchFlags flags) const

virtual void	findLocalDeclarationsInternal (const IndexedIdentifier &identifier, const CursorInRevision &position, const AbstractType::Ptr &dataType, DeclarationList &ret, const TopDUContext *source, SearchFlags flags) const

virtual bool	foundEnough (const DeclarationList &decls, SearchFlags flags) const

bool	isAnonymous () const

virtual void	mergeDeclarationsInternal (QVector< QPair< Declaration , int >> &definitions, const CursorInRevision &position, QHash< const DUContext , bool > &hadContexts, const TopDUContext *source, bool searchInParents=true, int currentDepth=0) const

virtual bool	shouldSearchInParent (SearchFlags flags) const

Protected Member Functions inherited from KDevelop::DUChainBase
	DUChainBase (DUChainBase &rhs)

	DUChainBase (DUChainBaseData &dd, const RangeInRevision &range)

Additional Inherited Members
Protected Attributes inherited from KDevelop::DUChainBase
DUChainBaseData *	d_ptr

Detailed Description

A single context in source code, represented as a node in a directed acyclic graph.

Access to context objects must be serialised by holding the chain lock, ie. DUChain::lock().

NOTE: A du-context can be freely edited as long as it's parent-context is zero. In the moment the parent-context is set, the context may only be edited when it is allowed to edited it's top-level context(

See also: TopLevelContext::inDUChain()

Todo:: change child relationships to a linked list within the context?

Definition at line 72 of file ducontext.h.

Member Typedef Documentation

◆ DeclarationList

using KDevelop::DUContext::DeclarationList = QList<Declaration*>

Declaration search implementation.

Todo:: Should be protected, moved here temporarily until I have figured out why the gcc 4.1.3 fails in cppducontext.h:212, which should work (within kdevelop)

Definition at line 769 of file ducontext.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
Identity

Definition at line 688 of file ducontext.h.

◆ ContextType

enum KDevelop::DUContext::ContextType : quint8

Enumerator
Global	A context that declares functions, namespaces or classes.
Namespace	A context that declares namespace members.
Class	A context that declares class members.
Function	A context that declares function-arguments.
Template	A context that declares template-parameters.
Enum	A context that contains a list of enumerators.
Helper	A helper context. This context is treated specially during search: when searching within the imports of a context, and that context's parent is a context of type DUContext::Helper, then the upwards search is continued into that helper(The decision happens in shouldSearchInParent)
Other	Represents executable code, like for example within a compound-statement.

Definition at line 102 of file ducontext.h.

◆ SearchFlag

enum KDevelop::DUContext::SearchFlag

Enumerator
NoSearchFlags	Searching for everything.
InImportedParentContext	Internal, do not use from outside.
OnlyContainerTypes	Not implemented yet.
DontSearchInParent	IF this flag is set, findDeclarations(..) will not search for the identifier in parent-contexts(which does not include imported parent-contexts)
NoUndefinedTemplateParams	For languages that support templates(like C++). If this is set, the search should fail as soon as undefined template-parameters are involved.
DirectQualifiedLookup	When this flag is used, the searched qualified identifier should NOT be split up into it's components and looked up one by one. Currently only plays a role in C++ specific parts.
NoFiltering	Should be set when no filtering at all is wished, not even filtering that is natural for the underlying language(For example in C++, constructors are filtered out be default)
OnlyFunctions	When this is given, only function-declarations are returned. In case of C++, this also means that constructors can be retrieved, while normally they are filtered out.
NoImportsCheck	With this parameter, a global search will return all matching items, from all contexts, not only from imported ones.
NoSelfLookUp	With this parameter, the special-treatment during search that allows finding the context-class by its name is disabled.
DontResolveAliases	Disables the resolution of alias declarations in the returned list.
LastSearchFlag

Definition at line 116 of file ducontext.h.

Constructor & Destructor Documentation

◆ DUContext() [1/4]

KDevelop::DUContext::DUContext	(	const RangeInRevision &	range,
		DUContext *	parent = `nullptr`,
		bool	anonymous = `false`
	)

explicit

Constructor.

No convenience methods, as the initialisation order is important,

Parameters

anonymous Whether the context should be added as an anonymous context to the parent. That way the context can never be found through any of the parent's member-functions.

If the parent is in the symbol table and the context is not anonymous, it will also be added to the symbol table. You nead a write-lock to the DUChain then

Definition at line 356 of file ducontext.cpp.

◆ DUContext() [2/4]

KDevelop::DUContext::DUContext ( DUContextData & data )

explicit

Definition at line 350 of file ducontext.cpp.

◆ ~DUContext()

KDevelop::DUContext::~DUContext ( )

override

Destructor.

Will delete all child contexts which are defined within the same file as this context.

Definition at line 428 of file ducontext.cpp.

◆ DUContext() [3/4]

KDevelop::DUContext::DUContext	(	DUContextData &	dd,
		const RangeInRevision &	range,
		DUContext *	parent = `nullptr`,
		bool	anonymous = `false`
	)

protected

Definition at line 396 of file ducontext.cpp.

◆ DUContext() [4/4]

KDevelop::DUContext::DUContext ( DUContext & useDataFrom )

protected

Just uses the data from the given context.

Doesn't copy or change anything, and the data will not be deleted on this contexts destruction.

Definition at line 422 of file ducontext.cpp.

Member Function Documentation

◆ addImportedParentContext()

void KDevelop::DUContext::addImportedParentContext	(	DUContext *	context,
		const CursorInRevision &	position = `CursorInRevision::invalid()`,
		bool	anonymous = `false`,
		bool	temporary = `false`
	)

virtual

Adds an imported context.

Parameters

anonymous	If this is true, the import will not be registered at the imported context. This allows du-chain contexts importing without having a write-lock.
position	Position where the context is imported. This is mainly important in C++ with included files.

If the context is already imported, only the position is updated.

Note: Be sure to have set the text location first, so that the chain is sorted correctly.

Reimplemented in KDevelop::TopDUContext.

Definition at line 835 of file ducontext.cpp.

◆ addIndirectImport()

bool KDevelop::DUContext::addIndirectImport ( const DUContext::Import & import )

Adds an imported context, which may be indirect.

Warning: This is only allowed if this context is NOT a top-context.; When using this mechanism, this context will not be registered as importer to the other one.; The given import must be indirect.

Returns: true if the import was already imported before, else false.

Do not sort the imported contexts by their own line-number, it makes no sense. Contexts added first, aka template-contexts, should stay in first place, so they are searched first.

Definition at line 816 of file ducontext.cpp.

◆ allDeclarations()

QVector< QPair< Declaration *, int > > KDevelop::DUContext::allDeclarations	(	const CursorInRevision &	position,
		const TopDUContext *	topContext,
		bool	searchInParents = `true`
	)		const

Return a list of all reachable declarations for a given cursor position in a given url.

Parameters

position	the text position to search for
topContext	the top-context from where a completion is triggered. This is needed so delayed types(templates in C++) can be resolved in the correct context.
searchInParents	should declarations from parent-contexts be listed? If false, only declarations from this and imported contexts will be returned.

The returned declarations are paired together with their inheritance-depth, which is the count of steps to into other contexts that were needed to find the declaration. Declarations reached through a namespace- or global-context are offsetted by 1000.

This also includes Declarations from sub-contexts that were propagated upwards using setPropagateDeclarations(true).

Returns: the requested declarations, if any were active at that location. Declarations propagated into this context(setPropagateDeclarations) are included.

Definition at line 944 of file ducontext.cpp.

◆ applyAliases()

void KDevelop::DUContext::applyAliases	(	const SearchItem::PtrList &	identifiers,
		SearchItem::PtrList &	targetIdentifiers,
		const CursorInRevision &	position,
		bool	canBeNamespace,
		bool	onlyImports = `false`
	)		const

protected

Applies namespace-imports and namespace-aliases and returns possible absolute identifiers that need to be searched.

Parameters

targetIdentifiers	will be filled with all identifiers that should be searched for, instead of identifier.
onlyImports	if this is true, namespace-aliases will not be respected, but only imports. This is faster.

Definition at line 1223 of file ducontext.cpp.

◆ applyUpwardsAliases()

void KDevelop::DUContext::applyUpwardsAliases	(	SearchItem::PtrList &	identifiers,
		const TopDUContext *	source
	)		const

protectedvirtual

Applies the aliases that need to be applied when moving the search from this context up to the parent-context.

The default-implementation adds a set of identifiers with the own local identifier prefixed, if this is a namespace.

For C++, this is needed when searching out of a namespace, so the item can be found within that namespace in another place.

Definition at line 1281 of file ducontext.cpp.

◆ changeUseRange()

void KDevelop::DUContext::changeUseRange	(	int	useIndex,
		const RangeInRevision &	range
	)

Note: The change must not break the ordering

Definition at line 1362 of file ducontext.cpp.

◆ childContexts()

QVector< DUContext * > KDevelop::DUContext::childContexts ( ) const

Returns the list of immediate child contexts for this context.

Note: This is expensive.

Definition at line 472 of file ducontext.cpp.

◆ cleanIfNotEncountered()

void KDevelop::DUContext::cleanIfNotEncountered ( const QSet< DUChainBase * > & encountered )

Delete and remove all slaves (uses, declarations, definitions, contexts) that are not in the given set.

Definition at line 1465 of file ducontext.cpp.

◆ clearImportedParentContexts()

void KDevelop::DUContext::clearImportedParentContexts ( )

virtual

Clear all imported parent contexts.

Reimplemented in KDevelop::TopDUContext.

Definition at line 1451 of file ducontext.cpp.

◆ clearLocalDeclarations()

QVector< Declaration * > KDevelop::DUContext::clearLocalDeclarations ( )

Clears all local declarations.

Does not delete the declaration; the caller assumes ownership.

Definition at line 1065 of file ducontext.cpp.

◆ createNavigationWidget()

AbstractNavigationWidget * KDevelop::DUContext::createNavigationWidget	(	Declaration *	decl = `nullptr`,
		TopDUContext *	topContext = `nullptr`,
		AbstractNavigationWidget::DisplayHints	hints = `AbstractNavigationWidget::NoHints`
	)		const

virtual

Can be specialized by languages to create a navigation/information-widget.

The returned widget will be owned by the caller.

Parameters

decl	A member-declaration of this context the navigation-widget should be created for. Zero to create a widget for this context.
topContext	Top-context from where the navigation-widget is triggered. In C++, this is needed to resolve forward-declarations.

Can return zero which disables the navigation widget.

If you setProperty("DoNotCloseOnCursorMove", true) on the widget returned, then the widget will not close when the cursor moves in the document, which enables you to change the document contents from the widget without immediately closing the widget.

Definition at line 1497 of file ducontext.cpp.

◆ createUse()

int KDevelop::DUContext::createUse	(	int	declarationIndex,
		const RangeInRevision &	range,
		int	insertBefore = `-1`
	)

Creates a new use of the declaration given through declarationIndex.

The index must be retrieved through TopDUContext::indexForUsedDeclaration(..).

Parameters

range	The range of the use
insertBefore	A hint where in the vector of uses to insert the use. Must be correct so the order is preserved(ordered by position), or -1 to automatically choose the position.

Returns: Local index of the created use

Definition at line 1336 of file ducontext.cpp.

◆ declarationHasUses()

bool KDevelop::DUContext::declarationHasUses ( Declaration * decl )

static

Determines whether the given declaration has uses or not.

Definition at line 1321 of file ducontext.cpp.

◆ deleteChildContextsRecursively()

void KDevelop::DUContext::deleteChildContextsRecursively ( )

Clears and deletes all child contexts recursively.

This will not cross file boundaries.

Definition at line 1054 of file ducontext.cpp.

◆ deleteLocalDeclarations()

void KDevelop::DUContext::deleteLocalDeclarations ( )

Clears all local declarations.

Deletes these declarations, as the context has ownership.

Definition at line 1036 of file ducontext.cpp.

◆ deleteUse()

void KDevelop::DUContext::deleteUse ( int index )

Deletes the use number index.

Parameters

index is the position in the vector of uses, not a used declaration index.

Definition at line 1160 of file ducontext.cpp.

◆ deleteUses()

void KDevelop::DUContext::deleteUses ( )

virtual

Clear and delete all uses in this context.

Definition at line 1167 of file ducontext.cpp.

◆ deleteUsesRecursively()

void KDevelop::DUContext::deleteUsesRecursively ( )

virtual

Recursively delete all uses in this context and all its child-contexts.

Reimplemented in KDevelop::TopDUContext.

Definition at line 1175 of file ducontext.cpp.

◆ depth()

int KDevelop::DUContext::depth ( ) const

Calculate the depth of this context, from the top level context in the file.

Definition at line 341 of file ducontext.cpp.

◆ equalScopeIdentifier()

bool KDevelop::DUContext::equalScopeIdentifier ( const DUContext * rhs ) const

Returns true if this context has the same scope identifier as the given one.

Note: This is much more efficient than computing the identifiers through scopeIdentifier(..) and comparing them

Definition at line 1085 of file ducontext.cpp.

◆ findContext()

DUContext * KDevelop::DUContext::findContext	(	const CursorInRevision &	position,
		DUContext *	parent = `nullptr`
	)		const

Searches for the most specific context for the given cursor position in the given url.

Parameters

position	the text position to search for
parent	the parent context to search from (this is mostly an internal detail, but if you only want to search in a subbranch of the chain, you may specify the parent here)

Returns: the requested context if one was found, otherwise null.

Definition at line 912 of file ducontext.cpp.

◆ findContextAt()

DUContext * KDevelop::DUContext::findContextAt	(	const CursorInRevision &	position,
		bool	includeBorders = `false`
	)		const

Find the context which most specifically covers position.

The search is recursive, so the most specific context is found.

Parameters

includeBorders When this is true, contexts will also be found that have the position on their borders.

Warning: This uses the ranges in the local revision of the document (at last parsing time). Use DUChainBase::transformToLocalRevision to transform the cursor into that revision first.

Definition at line 1374 of file ducontext.cpp.

◆ findContextIncluding()

DUContext * KDevelop::DUContext::findContextIncluding ( const RangeInRevision & range ) const

Find the context which most specifically covers range.

Warning: This uses the ranges in the local revision of the document (at last parsing time). Use DUChainBase::transformToLocalRevision to transform the cursor into that revision first.

Definition at line 1411 of file ducontext.cpp.

◆ findDeclarationAt()

Declaration * KDevelop::DUContext::findDeclarationAt ( const CursorInRevision & position ) const

Find a child declaration that has a rang that covers the given position.

The search is local, not recursive.

Warning: This uses the ranges in the local revision of the document (at last parsing time). Use DUChainBase::transformToLocalRevision to transform the cursor into that revision first.

Definition at line 1395 of file ducontext.cpp.

◆ findDeclarations() [1/3]

QList< Declaration * > KDevelop::DUContext::findDeclarations	(	const Identifier &	identifier,
		const CursorInRevision &	position = `CursorInRevision::invalid()`,
		const TopDUContext *	topContext = `nullptr`,
		SearchFlags	flags = `NoSearchFlags`
	)		const

Prefer the version above for speed reasons.

Definition at line 1141 of file ducontext.cpp.

◆ findDeclarations() [2/3]

QList< Declaration * > KDevelop::DUContext::findDeclarations	(	const IndexedIdentifier &	identifier,
		const CursorInRevision &	position = `CursorInRevision::invalid()`,
		const TopDUContext *	topContext = `nullptr`,
		SearchFlags	flags = `NoSearchFlags`
	)		const

Searches for and returns a declaration with a given identifier in this context, which is currently active at the given text position.

Parameters

identifier	the identifier of the definition to search for
topContext	the top-context from where a completion is triggered. This is needed so delayed types(templates in C++) can be resolved in the correct context.
position	the text position to search for

Returns: the requested declaration if one was found, otherwise null.

Warning: this may return declarations which are not in this tree, you may need to lock them too...

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 1147 of file ducontext.cpp.

◆ findDeclarations() [3/3]

QList< Declaration * > KDevelop::DUContext::findDeclarations	(	const QualifiedIdentifier &	identifier,
		const CursorInRevision &	position = `CursorInRevision::invalid()`,
		const AbstractType::Ptr &	dataType = `AbstractType::Ptr()`,
		const TopDUContext *	topContext = `nullptr`,
		SearchFlags	flags = `NoSearchFlags`
	)		const

Searches for and returns a declaration with a given identifier in this context, which is currently active at the given text position, with the given type dataType.

In fact, only items are returned that are declared BEFORE that position.

Parameters

identifier	the identifier of the definition to search for
position	the text position to search for
topContext	the top-context from where a completion is triggered. This is needed so delayed types (templates in C++) can be resolved in the correct context.
dataType	the type to match, or null for no type matching.

Returns: the requested declaration if one was found, otherwise null.

Warning: this may return declarations which are not in this tree, you may need to lock them too...

Definition at line 785 of file ducontext.cpp.

◆ findDeclarationsInternal()

bool KDevelop::DUContext::findDeclarationsInternal	(	const SearchItem::PtrList &	identifiers,
		const CursorInRevision &	position,
		const AbstractType::Ptr &	dataType,
		DeclarationList &	ret,
		const TopDUContext *	source,
		SearchFlags	flags,
		uint	depth
	)		const

virtual

This is a more complex interface to the declaration search engine.

Always prefer findDeclarations(..) when possible.

Advantage of this interface:

You can search multiple identifiers at one time. However, those should be aliased identifiers for one single item, because search might stop as soon as one item is found.
The source top-context is needed to correctly resolve template-parameters

Parameters

position A valid position, if in doubt use textRange().end()

Warning: position must be valid!

Parameters

depth Depth of the search in parents. This is used to prevent endless recursions in endless import loops.

Returns: whether the search was successful. If it is false, it had to be stopped for special reasons (like some flags)

Step 1: Apply namespace-aliases and -imports

Step 2: Give identifiers that are not marked as explicitly-global to imported contexts(explicitly global ones are treatead in TopDUContext)

Step 3: Continue search in parent-context

Definition at line 675 of file ducontext.cpp.

◆ findLocalDeclarations() [1/2]

QList< Declaration * > KDevelop::DUContext::findLocalDeclarations	(	const Identifier &	identifier,
		const CursorInRevision &	position = `CursorInRevision::invalid()`,
		const TopDUContext *	topContext = `nullptr`,
		const AbstractType::Ptr &	dataType = `AbstractType::Ptr()`,
		SearchFlags	flags = `NoSearchFlags`
	)		const

Prefer the version above for speed reasons.

Definition at line 543 of file ducontext.cpp.

◆ findLocalDeclarations() [2/2]

QList< Declaration * > KDevelop::DUContext::findLocalDeclarations	(	const IndexedIdentifier &	identifier,
		const CursorInRevision &	position = `CursorInRevision::invalid()`,
		const TopDUContext *	topContext = `nullptr`,
		const AbstractType::Ptr &	dataType = `AbstractType::Ptr()`,
		SearchFlags	flags = `NoSearchFlags`
	)		const

Returns the type of any identifier defined in this context, or null if one is not found.

Does not search imported parent-contexts(like base-classes).

Definition at line 528 of file ducontext.cpp.

◆ findLocalDeclarationsInternal() [1/2]

void KDevelop::DUContext::findLocalDeclarationsInternal	(	const Identifier &	identifier,
		const CursorInRevision &	position,
		const AbstractType::Ptr &	dataType,
		DeclarationList &	ret,
		const TopDUContext *	source,
		SearchFlags	flags
	)		const

protected

Definition at line 615 of file ducontext.cpp.

◆ findLocalDeclarationsInternal() [2/2]

void KDevelop::DUContext::findLocalDeclarationsInternal	(	const IndexedIdentifier &	identifier,
		const CursorInRevision &	position,
		const AbstractType::Ptr &	dataType,
		DeclarationList &	ret,
		const TopDUContext *	source,
		SearchFlags	flags
	)		const

protectedvirtual

Todo:: Eventually do efficient iteration-free filtering

Definition at line 622 of file ducontext.cpp.

◆ findUseAt()

int KDevelop::DUContext::findUseAt ( const CursorInRevision & position ) const

Find the use which encompasses position, if one exists.

Returns: The local index of the use, or -1

Definition at line 1427 of file ducontext.cpp.

◆ foundEnough()

bool KDevelop::DUContext::foundEnough	(	const DeclarationList &	decls,
		SearchFlags	flags
	)		const

protectedvirtual

After one scope was searched, this function is asked whether more results should be collected.

Override it, for example to collect overloaded functions.

The default-implementation returns true as soon as decls is not empty.

Definition at line 667 of file ducontext.cpp.

◆ fullyApplyAliases()

QVector< QualifiedIdentifier > KDevelop::DUContext::fullyApplyAliases	(	const QualifiedIdentifier &	id,
		const TopDUContext *	source
	)		const

Returns the qualified identifier id with all aliases (for example namespace imports) applied.

Example: If the namespace 'Foo' is imported, and id is 'Bar', then the returned list is 'Bar' and 'Foo::Bar'

Definition at line 757 of file ducontext.cpp.

◆ importedParentContexts()

QVector< DUContext::Import > KDevelop::DUContext::importedParentContexts ( ) const

virtual

Returns the list of imported parent contexts for this context.

Warning: The list may contain objects that are not valid any more, i.e. data() returns zero,

See also: addImportedParentContext)

Warning: The import structure may contain loops if this is a TopDUContext, so be careful when traversing the tree.

Note: This is expensive.

Reimplemented in KDevelop::TopDUContext.

Definition at line 1213 of file ducontext.cpp.

◆ importers()

QVector< DUContext * > KDevelop::DUContext::importers ( ) const

virtual

Returns the list of contexts importing this context.

Note: Very expensive, since the importers top-contexts need to be loaded.

Reimplemented in KDevelop::TopDUContext.

Definition at line 891 of file ducontext.cpp.

◆ importPosition()

CursorInRevision KDevelop::DUContext::importPosition ( const DUContext * target ) const

virtual

If the given context is directly imported into this one, and addImportedParentContext(..) was called with a valid cursor, this will return that position.

Otherwise an invalid cursor is returned.

Reimplemented in KDevelop::TopDUContext.

Definition at line 1201 of file ducontext.cpp.

◆ imports()

bool KDevelop::DUContext::imports	(	const DUContext *	origin,
		const CursorInRevision &	position = `CursorInRevision::invalid()`
	)		const

virtual

Returns true if this context imports.

Parameters

origin at any depth, else false.

Reimplemented in KDevelop::TopDUContext.

Definition at line 807 of file ducontext.cpp.

◆ indexedImporters()

KDevVarLengthArray< IndexedDUContext > KDevelop::DUContext::indexedImporters ( ) const

Returns the list of indexed importers.

Cheap, because nothing needs to be loaded.

Definition at line 879 of file ducontext.cpp.

◆ indexedLocalScopeIdentifier()

IndexedQualifiedIdentifier KDevelop::DUContext::indexedLocalScopeIdentifier ( ) const

Same as localScopeIdentifier(), but faster.

Definition at line 1122 of file ducontext.cpp.

◆ inDUChain()

bool KDevelop::DUContext::inDUChain ( ) const

virtual

Returns true if this declaration is accessible through the du-chain, and thus cannot be edited without a du-chain write lock.

Reimplemented in KDevelop::TopDUContext.

Definition at line 1184 of file ducontext.cpp.

◆ inSymbolTable()

bool KDevelop::DUContext::inSymbolTable ( ) const

Returns whether this context is listed in the symbol table (Namespaces and classes)

Definition at line 1441 of file ducontext.cpp.

◆ isAnonymous()

bool KDevelop::DUContext::isAnonymous ( ) const

protected

Whether this context, or any of its parent contexts, has been inserte anonymously into the du-chain.

See also: DUContext::DUContext

Definition at line 390 of file ducontext.cpp.

◆ isPropagateDeclarations()

bool KDevelop::DUContext::isPropagateDeclarations ( ) const

Definition at line 523 of file ducontext.cpp.

◆ localDeclarations()

QVector< Declaration * > KDevelop::DUContext::localDeclarations ( const TopDUContext * source = nullptr ) const

virtual

Returns all local declarations.

Parameters

source A source-context that is needed to instantiate template-declarations in some cases. If it is zero, that signalizes that missing members should not be instantiated.

Definition at line 960 of file ducontext.cpp.

◆ localScopeIdentifier()

QualifiedIdentifier KDevelop::DUContext::localScopeIdentifier ( ) const

Scope identifier, used to qualify the identifiers occurring in each context.

This is the part relative to the parent context.

Definition at line 1115 of file ducontext.cpp.

◆ mergeDeclarationsInternal()

void KDevelop::DUContext::mergeDeclarationsInternal	(	QVector< QPair< Declaration *, int >> &	definitions,
		const CursorInRevision &	position,
		QHash< const DUContext *, bool > &	hadContexts,
		const TopDUContext *	source,
		bool	searchInParents = `true`,
		int	currentDepth = `0`
	)		const

protectedvirtual

Merges definitions and their inheritance-depth up all branches of the definition-use chain into one hash.

This includes declarations propagated from sub-contexts.

Parameters

hadContexts is used to count together all contexts that already were visited, so they are not visited again.

Only respect the position if the parent-context is not a class(

Todo:: this is language-dependent)

Definition at line 968 of file ducontext.cpp.

◆ operator=()

DUContext& KDevelop::DUContext::operator= ( const DUContext & rhs )

delete

◆ owner()

Declaration * KDevelop::DUContext::owner ( ) const

If this context was opened by a declaration or definition, this returns that item.

The returned declaration/definition will have this context set as internalContext()

Definition at line 479 of file ducontext.cpp.

◆ parentContext()

DUContext * KDevelop::DUContext::parentContext ( ) const

Returns the immediate parent context of this context.

Definition at line 505 of file ducontext.cpp.

◆ parentContextOf()

bool KDevelop::DUContext::parentContextOf ( DUContext * context ) const

Iterates the tree to see if the provided context is a subcontext of this context.

Returns: true if context is a subcontext, otherwise false.

Definition at line 933 of file ducontext.cpp.

◆ removeImportedParentContext()

void KDevelop::DUContext::removeImportedParentContext ( DUContext * context )

virtual

Removes a child context.

Reimplemented in KDevelop::TopDUContext.

Definition at line 859 of file ducontext.cpp.

◆ resortChildContexts()

void KDevelop::DUContext::resortChildContexts ( )

Resort the child contexts by their range.

You must call this when you manually change the range of child contexts in a way that could break the internal range sorting.

Definition at line 1736 of file ducontext.cpp.

◆ resortLocalDeclarations()

void KDevelop::DUContext::resortLocalDeclarations ( )

Resort the local declarations by their range.

You must call this when you manually change the range of declarations in a way that could break the internal range sorting.

Definition at line 1722 of file ducontext.cpp.

◆ scopeIdentifier()

QualifiedIdentifier KDevelop::DUContext::scopeIdentifier ( bool includeClasses = false ) const

Calculate the fully qualified scope identifier.

Definition at line 1075 of file ducontext.cpp.

◆ setInSymbolTable()

void KDevelop::DUContext::setInSymbolTable ( bool inSymbolTable )

Move this object into/out of the symbol table.

Note: You need to have a duchain write lock, unless this is a TopDUContext.

Definition at line 1446 of file ducontext.cpp.

◆ setLocalScopeIdentifier()

void KDevelop::DUContext::setLocalScopeIdentifier ( const QualifiedIdentifier & identifier )

Scope identifier, used to qualify the identifiers occurring in each context This must not be called once this context has children.

Definition at line 1106 of file ducontext.cpp.

◆ setOwner()

void KDevelop::DUContext::setOwner ( Declaration * decl )

Sets the declaration/definition, and also updates it's internal context (they are strictly paired together).

The declaration has to be part of the same top-context.

Definition at line 485 of file ducontext.cpp.

◆ setPropagateDeclarations()

void KDevelop::DUContext::setPropagateDeclarations ( bool propagate )

If this is set to true, all declarations that are added to this context will also be visible in the parent-context.

They will be visible in the parent using findDeclarations(...) and findLocalDeclarations(...), but will not be in the list of localDeclarations(...).

Definition at line 512 of file ducontext.cpp.

◆ setType()

void KDevelop::DUContext::setType ( ContextType type )

Definition at line 1134 of file ducontext.cpp.

◆ setUseDeclaration()

void KDevelop::DUContext::setUseDeclaration	(	int	useIndex,
		int	declarationIndex
	)

Assigns the declaration represented by declarationIndex to the use with index useIndex.

Definition at line 1368 of file ducontext.cpp.

◆ shouldSearchInParent()

bool KDevelop::DUContext::shouldSearchInParent ( SearchFlags flags ) const

protectedvirtual

This is called whenever the search needs to do the decision whether it should be continued in the parent context.

It is not called when the DontSearchInParent flag is set. Else this should be overridden to do language-specific logic.

The default implementation returns false if the flag InImportedParentContext is set.

Definition at line 1308 of file ducontext.cpp.

◆ specialize()

DUContext * KDevelop::DUContext::specialize	(	const IndexedInstantiationInformation &	specialization,
		const TopDUContext *	topContext,
		int	upDistance = `0`
	)

virtual

Retrieve the context which is specialized with the given specialization as seen from the given topContext.

Parameters

specialization	the specialization index (see DeclarationId)
topContext	the top context representing the perspective from which to specialize. if `topContext` is zero, only already existing specializations are returned, and if none exists, zero is returned.
upDistance	upwards distance in the context-structure of the given specialization-info. This allows specializing children.

Definition at line 1193 of file ducontext.cpp.

◆ topContext()

TopDUContext * KDevelop::DUContext::topContext ( ) const

overridevirtual

Find the top context.

Reimplemented from KDevelop::DUChainBase.

Reimplemented in KDevelop::TopDUContext.

Definition at line 1492 of file ducontext.cpp.

◆ type()

DUContext::ContextType KDevelop::DUContext::type ( ) const

Definition at line 1127 of file ducontext.cpp.

◆ uses()

const Use * KDevelop::DUContext::uses ( ) const

Uses: A "Use" represents any position in a document where a Declaration is used literally.

For efficiency, since there can be many many uses, they are managed efficiently by TopDUContext and DUContext. In TopDUContext, the used declarations are registered and assigned a "Declaration-Index" while calling TopDUContext::indexForUsedDeclaration. From such a declaration-index, the declaration can be retrieved back by calling TopDUContext::usedDeclarationForIndex.

The actual uses are stored within DUContext, where each use consists of a range and the declaration-index of the used declaration. Return a vector of all uses which occur in this context.

To get the actual declarations, use TopDUContext::usedDeclarationForIndex(..) with the declarationIndex.

Definition at line 1314 of file ducontext.cpp.

◆ usesCount()

int KDevelop::DUContext::usesCount ( ) const

Returns the count of uses that can be accessed through uses()

Definition at line 1326 of file ducontext.cpp.

◆ visit()

void KDevelop::DUContext::visit ( DUChainVisitor & visitor )

virtual

Visits all duchain objects in the whole duchain.

Classes that hold a unique link to duchain objects like instantiations have to pass the visitor over to those classes.

Definition at line 1702 of file ducontext.cpp.

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

kdevplatform/language/duchain

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ DeclarationList

Member Enumeration Documentation

◆ anonymous enum

◆ ContextType

◆ SearchFlag

Constructor & Destructor Documentation

◆ DUContext() [1/4]

◆ DUContext() [2/4]

◆ ~DUContext()

◆ DUContext() [3/4]

◆ DUContext() [4/4]

Member Function Documentation

◆ addImportedParentContext()

◆ addIndirectImport()

◆ allDeclarations()

◆ applyAliases()

◆ applyUpwardsAliases()

◆ changeUseRange()

◆ childContexts()

◆ cleanIfNotEncountered()

◆ clearImportedParentContexts()

◆ clearLocalDeclarations()

◆ createNavigationWidget()

◆ createUse()

◆ declarationHasUses()

◆ deleteChildContextsRecursively()

◆ deleteLocalDeclarations()

◆ deleteUse()

◆ deleteUses()

◆ deleteUsesRecursively()

◆ depth()

◆ equalScopeIdentifier()

◆ findContext()

◆ findContextAt()

◆ findContextIncluding()

◆ findDeclarationAt()

◆ findDeclarations() [1/3]

◆ findDeclarations() [2/3]

◆ findDeclarations() [3/3]

◆ findDeclarationsInternal()

◆ findLocalDeclarations() [1/2]

◆ findLocalDeclarations() [2/2]

◆ findLocalDeclarationsInternal() [1/2]

◆ findLocalDeclarationsInternal() [2/2]

◆ findUseAt()

◆ foundEnough()

◆ fullyApplyAliases()

◆ importedParentContexts()

◆ importers()

◆ importPosition()

◆ imports()

◆ indexedImporters()

◆ indexedLocalScopeIdentifier()

◆ inDUChain()

◆ inSymbolTable()

◆ isAnonymous()

◆ isPropagateDeclarations()

◆ localDeclarations()

◆ localScopeIdentifier()

◆ mergeDeclarationsInternal()

◆ operator=()

◆ owner()

◆ parentContext()

◆ parentContextOf()

◆ removeImportedParentContext()

◆ resortChildContexts()

◆ resortLocalDeclarations()

◆ scopeIdentifier()

◆ setInSymbolTable()

◆ setLocalScopeIdentifier()

◆ setOwner()