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.
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.
Document, which have application scope (even if multiple projects are open, each file is represented by the same
A PSI has project scope.
The same file is represented by one
PsiFile instance for each open project to which the file belongs.
VirtualFile and Document have application scope; files are represented by the same VirtualFile instance, even if multiple projects are open.
- From an action:
- From a VirtualFile:
- From a Document:
- From an element inside the file:
- To find files with a specific name anywhere in the project, use
FilenameIndex.getFilesByName(project, name, scope)
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
As PSI is language-dependent, PSI files are created through the
Language object, by using the
Like documents, PSI files are created on-demand when the PSI is accessed for a particular file.
Like documents, PSI files are weakly referenced from the corresponding
VirtualFile instances and can be garbage-collected if not referenced by anyone.
createFileFromText() method creates an in-memory PSI file with the specified contents.
To save the PSI file to disk, use the
PsiManager.getInstance(project).addPsiTreeChangeListener() allows you to receive notifications about all changes to the PSI tree of a project.
PSI can be extended to support additional languages through custom language plugins. For more details on developing custom language plugins, see the Custom Language Support reference guide.
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.