hxuanyu/intellij-sdk-code-samples
1
0
Fork 0
mirror of https://github.com/JetBrains/intellij-sdk-code-samples.git synced 2025-07-30 18:27:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

[md] "psi files" extracted from "architectural overview"

Browse Source
This commit is contained in:
Anna Bulenkova 2015-04-13 15:04:15 +02:00
parent 31db71daa1
commit 86b92f3269
3 changed files with 64 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_SUMMARY.md
View File

@ -25,7 +25,7 @@
* [General Threading Rules](general_threading_rules.html)
* [Virtual Files](virtual_file.html)
* [Documents](documents.html)
* [PSI Files](TODO)
* [PSI Files](psi_files.html)
* [File View Providers](TODO)
* [Psi Elements](TODO)
* [Structure of Project](project_structure.html)

59
architectural_overview.md
View File

@ -29,65 +29,6 @@ This topic covers the following subjects:
* Psi Elements
## PSI Files
A PSI (Program Structure Interface) file is the root of a structure representing the contents of a file as a hierarchy of elements in a particular programming language. The
[PsiFile](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiFile.java)
class is the common base class for all PSI files, while files in a specific language are usually represented by its subclasses.
For example, the
[PsiJavaFile](https://github.com/JetBrains/intellij-community/blob/master/java/java-psi-api/src/com/intellij/psi/PsiJavaFile.java)
class represents a Java file, and the
[XmlFile](https://github.com/JetBrains/intellij-community/blob/master/xml/openapi/src/com/intellij/psi/xml/XmlFile.java)
class represents an XML file.
Unlike ```VirtualFile``` and ```Document```, which have application scope (even if multiple projects are open, each file is represented by the same ```VirtualFile``` instance), PSI has project scope (the same file is represented by multiple PsiFile instances if the file belongs to multiple projects open at the same time).
#### How do I get one?
* From an action: ```e.getData(LangDataKeys.PSI_FILE)```.
* From a VirtualFile: ```PsiManager.getInstance(project).findFile()```
* From a Document: ```PsiDocumentManager.getInstance(project).getPsiFile()```
* From an element inside the file: ```psiElement.getContainingFile()```
* To find files with a specific name anywhere in the project, use ```FilenameIndex.getFilesByName(project, name, scope)```
#### What can I do with one?
Most interesting modification operations are performed on the level of individual PSI elements, not files as a whole.
To iterate over the elements in a file, use ```psiFile.accept(new PsiRecursiveElementWalkingVisitor()...);```
#### Where does it come from?
As the PSI is language-dependent, PSI files are created through the (link: https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/Language.java text: Language ) object, using the ```LanguageParserDefinitions.INSTANCE.forLanguage(language).createFile(fileViewProvider)``` method.
Like documents, PSI files are created on demand when the PSI is accessed for a particular file.
#### How long does it live?
Again, like documents, PSI files are weakly referenced from the corresponding ```VirtualFile``` instances and can be garbage collected if not referenced by anyone.
#### How do I create one?
The
[PsiFileFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiFileFactory.java).
```getInstance(project).createFileFromText()``` method creates an in-memory PSI file with the specified contents.
To save the PSI file to disk, use the
[PsiDirectory](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiDirectory.java).
```add()``` method.
#### How do I get notified when it changes?
```PsiManager.getInstance(project).addPsiTreeChangeListener()``` allows you to receive notifications about all changes to the PSI tree of a project.
#### How do I extend it?
The PSI can be extended to support additional languages through custom language plugins. Developing such plugins is extensively documented in [another article] (Developing Custom Language Plugins for IntelliJ IDEA).
#### What are the rules for working with it?
Any changes done to the content of PSI files are reflected in documents, so all rules for working with documents (read/write actions, commands, read-only status handling) are in effect.
## File View Providers
A file view provider (see the [FileViewProvider](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/FileViewProvider.java) class) is a new concept in IntelliJ IDEA beginning with version 6.0. Its main purpose is managing access to multiple PSI trees within a single file. For example, a JSPX page has a separate PSI tree for the Java code in it (```PsiJavaFile```), a separate tree for the XML code (```XmlFile```), and a separate tree for JSP as a whole

63
psi_files.md Normal file
View File

@ -0,0 +1,63 @@
---
layout: editable
title: PSI Files
---
A PSI (Program Structure Interface) file is the root of a structure representing the contents of a file as a hierarchy of elements in a particular programming language.
The
[PsiFile](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiFile.java)
class is the common base class for all PSI files, while files in a specific language are usually represented by its subclasses.
For example, the
[PsiJavaFile](https://github.com/JetBrains/intellij-community/blob/master/java/java-psi-api/src/com/intellij/psi/PsiJavaFile.java)
class represents a Java file, and the
[XmlFile](https://github.com/JetBrains/intellij-community/blob/master/xml/openapi/src/com/intellij/psi/xml/XmlFile.java)
class represents an XML file.
Unlike ```VirtualFile``` and ```Document```, which have application scope (even if multiple projects are open, each file is represented by the same ```VirtualFile``` instance), PSI has project scope (the same file is represented by multiple PsiFile instances if the file belongs to multiple projects open at the same time).
## How do I get one?
* From an action: ```e.getData(LangDataKeys.PSI_FILE)```.
* From a VirtualFile: ```PsiManager.getInstance(project).findFile()```
* From a Document: ```PsiDocumentManager.getInstance(project).getPsiFile()```
* From an element inside the file: ```psiElement.getContainingFile()```
* To find files with a specific name anywhere in the project, use ```FilenameIndex.getFilesByName(project, name, scope)```
## What can I do with one?
Most interesting modification operations are performed on the level of individual PSI elements, not files as a whole.
To iterate over the elements in a file, use ```psiFile.accept(new PsiRecursiveElementWalkingVisitor()...);```
## Where does it come from?
As the PSI is language-dependent, PSI files are created through the (link: https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/lang/Language.java text: Language ) object, using the ```LanguageParserDefinitions.INSTANCE.forLanguage(language).createFile(fileViewProvider)``` method.
Like documents, PSI files are created on demand when the PSI is accessed for a particular file.
## How long does it live?
Again, like documents, PSI files are weakly referenced from the corresponding ```VirtualFile``` instances and can be garbage collected if not referenced by anyone.
## How do I create one?
The
[PsiFileFactory](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiFileFactory.java).
```getInstance(project).createFileFromText()``` method creates an in-memory PSI file with the specified contents.
To save the PSI file to disk, use the
[PsiDirectory](https://github.com/JetBrains/intellij-community/blob/master/platform/core-api/src/com/intellij/psi/PsiDirectory.java).
```add()``` method.
## How do I get notified when it changes?
```PsiManager.getInstance(project).addPsiTreeChangeListener()``` allows you to receive notifications about all changes to the PSI tree of a project.
## How do I extend it?
The PSI can be extended to support additional languages through custom language plugins.
Developing such plugins is extensively documented in [another article] (Developing Custom Language Plugins for IntelliJ IDEA).
## What are the rules for working with it?
Any changes done to the content of PSI files are reflected in documents, so all rules for working with documents (read/write actions, commands, read-only status handling) are in effect.