Package org.eclipse.xtext.scoping

Interface IScope

  • All Known Implementing Classes:
    AbstractScope, FilteringScope, ImportedNamesAdapter.WrappingScope, ImportScope, MapBasedScope, MultimapBasedScope, SelectableBasedScope, SimpleScope, SingletonScope, SuperCallScope
    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 elements depending on the actual use case. A linker may want to create links to invalid objects to provide better error messages while content assist should filter these instances.

    • Query by name: Scopes can be queried by name. Implementations should answer this query fast.
    • Query by object: Scopes can be queried by objects. Implementations should consider the uri of the object, too.
    • Wildcard query: All elements of the scope should be returned.

    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.

    • 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.