reference_contributor.md

title
10. Reference Contributor

References is one of the most important and tricky parts in the implementation of a custom language support. Resolving references means the ability to go from the usage of an element to its declaration, completion, rename refactoring, find usages, etc.

Every element which can be renamed or referenced needs to implement com.intellij.psi.PsiNamedElement interface.

10.1. Define a base named element class

{% include /code_samples/simple_language_plugin/src/com/simpleplugin/psi/SimpleNamedElement.java %}

{% include /code_samples/simple_language_plugin/src/com/simpleplugin/psi/impl/SimpleNamedElementImpl.java %}

10.2. Define helper methods for generated PSI elements

Since we need to implement new methods in PSI class, we should define them in our utility.

public static String getName(SimpleProperty element) {
    return getKey(element);
}

public static PsiElement setName(SimpleProperty element, String newName) {
    ASTNode keyNode = element.getNode().findChildByType(SimpleTypes.KEY);
    if (keyNode != null) {

        SimpleProperty property = SimpleElementFactory.createProperty(element.getProject(), newName);
        ASTNode newKeyNode = property.getFirstChild().getNode();
        element.getNode().replaceChild(keyNode, newKeyNode);
    }
    return element;
}

public static PsiElement getNameIdentifier(SimpleProperty element) {
    ASTNode keyNode = element.getNode().findChildByType(SimpleTypes.KEY);
    if (keyNode != null) {
        return keyNode.getPsi();
    } else {
        return null;
    }
}

10.3. Define an element factory

{% include /code_samples/simple_language_plugin/src/com/simpleplugin/psi/SimpleElementFactory.java %}

10.4. Update grammar and regenerate the parser

Now we need to make corresponding changes to the grammar file and regenerate parser and PSI classes.

property ::= (KEY? SEPARATOR VALUE?) | KEY {mixin="com.simpleplugin.psi.impl.SimpleNamedElementImpl"
  implements="com.simpleplugin.psi.SimpleNamedElement" methods=[getKey getValue getName setName getNameIdentifier]}

10.5. Define a reference

Now we need to define a reference class to resolve a property from it's usage.

{% include /code_samples/simple_language_plugin/src/com/simpleplugin/SimpleReference.java %}

10.6. Define a reference contributor

A reference contributor allows you to provide references from elements in other languages such as Java to elements in your language. Let's contribute a reference to each usage of a property.

{% include /code_samples/simple_language_plugin/src/com/simpleplugin/SimpleReferenceContributor.java %}

10.7. Register the reference contributor

<psi.referenceContributor implementation="com.simpleplugin.SimpleReferenceContributor"/>

10.8. Run the project

As you see the IDE now resolves the property and provides completion.

Rename refactoring available from definition and usages.

10.9. Define a refactoring support provider

To allow in-place refactoring we should specify it explicitly in a refactoring support provider.

{% include /code_samples/simple_language_plugin/src/com/simpleplugin/SimpleRefactoringSupportProvider.java %}

10.10. Register the refactoring support provider

<lang.refactoringSupport language="Simple" implementationClass="com.simpleplugin.SimpleRefactoringSupportProvider"/>

10.11. Run the project

Previous Top Next