PSI Files

PSI File represents file content as a hierarchy of elements in a particular programming language.

A PSI (Program Structure Interface) file is the root of a structure representing a file's contents as a hierarchy of elements in a particular programming language.

The PsiFile 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 class represents a Java file, and the XmlFile class represents an XML file.

Unlike and , which have application scope (even if multiple projects are open, each file is represented by the same VirtualFile instance), PSI has 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 a PSI file?

Context	API
Action	`AnActionEvent.getData(CommonDataKeys.PSI_FILE)`
Document	`PsiDocumentManager.getPsiFile()`
PSI Element	`PsiElement.getContainingFile()` (may return `null` if the PSI element is not contained in a file)
Virtual File	`PsiManager.findFile()`, `PsiUtilCore.toPsiFiles()`
File Name	`FilenameIndex.getVirtualFilesByName()` and locate via `PsiManager.findFile()` or `PsiUtilCore.toPsiFiles()`

What can I do with a PSI file?

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() {
  // visitor implementation ...
});

Where does a PSI file come from?

As PSI is language-dependent, PSI files are created using the Language instance:

LanguageParserDefinitions.INSTANCE
    .forLanguage(MyLanguage.INSTANCE)
    .createFile(fileViewProvider);

Like , PSI files are created on-demand when the PSI is accessed for a particular file.

How long do PSI files persist?

Like , PSI files are weakly referenced from the corresponding VirtualFile instances and can be garbage-collected if not referenced by anyone.

How do I create a PSI file?

PsiFileFactory.createFileFromText() creates an in-memory PSI file with the specified contents.

To save the PSI file to disk, use its parent directory's PsiDirectory.add().

How do I get notified when PSI files change?

PsiManager.addPsiTreeChangeListener() allows you to receive notifications about all changes to the PSI tree of a project. Alternatively, register PsiTreeChangeListener in .

Please see PsiTreeChangeEvent Javadoc for common problems when dealing with PSI events.

{style="note"}

How do I extend PSI?

PSI can be extended to support additional languages through custom language plugins. For more details on developing custom language plugins, see the reference guide.

What are the rules for working with PSI?

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.

6.1 KiB Raw Blame History