hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-29 01:37:51 +08:00
Code Issues Packages Projects Releases Wiki Activity
intellij-sdk-code-samples/reference_guide/custom_language_support/symbols.md
Daniil Ovchinnikov 5d32cbcfeb
Symbol API part 1 (#317) 
* LAB-21 Symbols, Declarations and References, Completion 2020.3

* LAB-21 Go to Declaration or Usages 2020.3

* fixes (squash with LAB-21 Symbols, Declarations and References, Completion 2020.3)

* fixes (squash with LAB-21 Go to Declaration or Usages 2020.3)

* new PsiCompletableReference location (squash with LAB-21 Symbols, Declarations and References, Completion 2020.3)

* Apply suggestions from code review

Co-authored-by: John Hake <39627202+JohnHake@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: John Hake <39627202+JohnHake@users.noreply.github.com>

* "Own reference", "External reference", "Implicit reference"

* move examples before api links

* IDE -> IntelliJ Platform

* articles

* explicit upsource link

* linebreaks

* element -> symbol

* remove jvm package example

* parent links (squash with LAB-21 Symbols, Declarations and References, Completion 2020.3)

* parent links (squash with LAB-21 Go to Declaration or Usages 2020.3)

* platform -> IntelliJ Platform

* reword symbol navigation a bit

Co-authored-by: John Hake <39627202+JohnHake@users.noreply.github.com>
2020-09-21 17:04:27 +02:00

2.1 KiB
Raw Blame History

title
Symbols

Warning

This API is available starting from 2020.3 and currently in development and thus in experimental state.

A symbol is a semantic element in some model, e.g., language model or framework model. The IntelliJ Platform uses Symbol to represent symbols, and Symbol serves as a link between Platform APIs, such as navigation, finding usages, or renaming. The platform obtains the target symbol from a declaration or by resolving a reference, and then uses it to perform an action. The PsiElement is considered as an element in the source tree (enhanced ASTNode). Symbol decouples semantic actions from PSI.

A Symbol is not required to be backed by a PsiElement, and it is incorrect to try to obtain the PsiElement from a Symbol.
Symbol is not required to be bound to a Project as well, meaning the same instance might be shared between projects.

Examples:

  • Java local variable is a symbol in Java language model, it's backed by a PsiVariable element;
  • Compiled class is a symbol in JVM model, it's backed by JDK library stubs, and it's not bound to any project;
  • Spring Bean is a symbol in Spring framework model, it's defined on-the-fly by framework support (not backed by a PsiElement) and bound to a Project;
  • Database column is a symbol defined by data source (not backed by a PsiElement) and not bound to a Project since DB elements might be shared between projects.

Lifecycle

The Symbol instance is expected to stay valid within a single read action, which means it's safe to pass the instance to different APIs. A Symbol instance should not be referenced between read actions. One should create a pointer via Symbol.createPointer() in the current read action, and then call Pointer.dereference() to obtain a Symbol instance in the subsequent read action.