org.eclipse.xtext.scoping
Interface IScope

All Known Implementing Classes:
AbstractConstructorScope, AbstractScope, AbstractTypeScope, BestMatchingJvmFeatureScope, ClasspathBasedConstructorScope, ClasspathBasedTypeScope, DelegatingScope, FilteringScope, ImportedNamesAdapter.WrappingScope, ImportScope, JdtBasedConstructorScope, JdtBasedSimpleTypeScope, JvmFeatureScope, MapBasedScope, MultimapBasedScope, SelectableBasedScope, SimpleScope, SingletonScope

public interface IScope

A scope defines which elements IEObjectDescription can be seen in a certain area within a model/program.

In other words: A scope is a kind of container structure that provides access to all objects that can be reached from a given reference. These objects may be invalid from a semantic point of view, e.g. a scope may expose private fields of a class if there is no better candidate. This allows for better error messages instead of broken cross references.

Scopes are used to resolve cross references during linking, content assist, serialization of models, etc.

Scopes are constructed and provided by an IScopeProvider for a given pair of a context object and a cross reference.

Clients can use several different query operations to select elements from a scope. They are free to filter the result further to a set of valid or interesting depending on the actual use case. A linker may want to create links to invalid objects to provide while content assist should filter these instances.

Each concrete query can be used to obtain a single element (which is usually the first that matches the criteria) or all elements from the scope that are suitable. The wildcard query can be used to obtain the complete content of a scope.

Scopes are usually nested (see AbstractScope#getParent and descriptions from nested scopes can shadow descriptions from parent scopes. Usually the name of a description is used as the shadowing criteria.

Clients should usually inherit from AbstractScope to implement own scopes.

Clients are free to extend the interface and introduce further query operations like prefix search or fuzzy name matching.

Author:
Sven Efftinge - Initial contribution and API, Sebastian Zarnekow

Field Summary
static IScope NULLSCOPE
          a NO-OP implementation.
 
Method Summary
 java.lang.Iterable<IEObjectDescription> getAllElements()
          Obtain all elements from the scope.
 java.lang.Iterable<IEObjectDescription> getElements(org.eclipse.emf.ecore.EObject object)
          Find all descriptions that match the given instance.
 java.lang.Iterable<IEObjectDescription> getElements(QualifiedName name)
          Find all descriptions that match the given name.
 IEObjectDescription getSingleElement(org.eclipse.emf.ecore.EObject object)
          Find the first description that matches the given instance.
 IEObjectDescription getSingleElement(QualifiedName name)
          Find the first description that matches the given name.
 

Field Detail

NULLSCOPE

static final IScope NULLSCOPE
a NO-OP implementation.

Method Detail

getSingleElement

IEObjectDescription getSingleElement(QualifiedName name)
Find the first description that matches the given name.

Parameters:
name - the name of the to-be-found element. May not be null.
Returns:
the first element that matches the name. May be null.

getElements

java.lang.Iterable<IEObjectDescription> getElements(QualifiedName name)
Find all descriptions that match the given name.

Parameters:
name - the name of the to-be-found elements. May not be null.
Returns:
all elements that match the name. Never null.

getSingleElement

IEObjectDescription getSingleElement(org.eclipse.emf.ecore.EObject object)
Find the first description that matches the given instance.

Parameters:
object - the instance whose description should be obtained. May not be null.
Returns:
the first element that matches the instance. May be null.

getElements

java.lang.Iterable<IEObjectDescription> getElements(org.eclipse.emf.ecore.EObject object)
Find all descriptions that match the given instance.

Parameters:
object - the instance whose descriptions should be obtained. May not be null.
Returns:
all elements that match the instance. Never null.

getAllElements

java.lang.Iterable<IEObjectDescription> getAllElements()
Obtain all elements from the scope. Implementors a free to throw an UnsupportedOperationException if the scope cannot be enumerated.

Returns:
all elements of the scope. Never null.
Throws:
java.lang.UnsupportedOperationException - if the scope cannot be enumerated.