Module aya.ij.parsing.core
Package com.intellij.psi

Interface PsiElement

All Known Subinterfaces:
NavigatablePsiElement, PsiBinaryFile, PsiComment, PsiErrorElement, PsiExternalReferenceHost, PsiFile, PsiLanguageInjectionHost, PsiNamedElement, PsiNameIdentifierOwner, PsiPlainText, PsiPlainTextFile, PsiWhiteSpace, UrlReferenceHost
public interface PsiElement
The common base interface for all elements of the PSI tree.

Please see IntelliJ Platform Architectural Overview for high-level overview.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final PsiElement[]
    EMPTY_ARRAY
    The empty array of PSI elements which can be reused to avoid unnecessary allocations.

  • Method Summary

    Modifier and Type
    Method
    Description
    PsiElement
    add(@NotNull PsiElement element)
    Adds a child to this PSI element.
    PsiElement
    addAfter(@NotNull PsiElement element, @Nullable PsiElement anchor)
    Adds a child to this PSI element, after the specified anchor element.
    PsiElement
    addBefore(@NotNull PsiElement element, @Nullable PsiElement anchor)
    Adds a child to this PSI element, before the specified anchor element.
    PsiElement
    addRange(PsiElement first, PsiElement last)
    Adds a range of elements as children to this PSI element.
    PsiElement
    addRangeAfter(PsiElement first, PsiElement last, PsiElement anchor)
    Adds a range of elements as children to this PSI element, after the specified anchor element.
    PsiElement
    addRangeBefore(@NotNull PsiElement first, @NotNull PsiElement last, PsiElement anchor)
    Adds a range of elements as children to this PSI element, before the specified anchor element.
    void
    checkAdd(@NotNull PsiElement element)
    Deprecated.
    not all PSI implementations implement this method correctly.
    void
    checkDelete()
    Deprecated.
    not all PSI implementations implement this method correctly.
    PsiElement
    copy()
    Creates a copy of the file containing the PSI element and returns the corresponding element in the created copy.
    void
    delete()
    Deletes this PSI element from the tree.
    void
    deleteChildRange(PsiElement first, PsiElement last)
    Deletes a range of children of this PSI element from the tree.
    @Nullable PsiElement
    findElementAt(int offset)
    Finds a leaf PSI element at the specified offset from the start of the text range of this node.
    @Nullable PsiReference
    findReferenceAt(int offset)
    Finds a reference at the specified offset from the start of the text range of this node.
    @NotNull PsiElement[]
    getChildren()
    Returns the array of children for the PSI element.
    PsiFile
    getContainingFile()
    Returns the file containing the PSI element.
    @Nullable PsiElement
    getContext()
    Returns the element which should be used as the parent of this element in a tree up walk during a resolve operation.
    PsiElement
    getFirstChild()
    Returns the first child of the PSI element.
    @NotNull Language
    getLanguage()
    Returns the language of the PSI element.
    PsiElement
    getLastChild()
    Returns the last child of the PSI element.
    PsiElement
    getNavigationElement()
    Returns the PSI element which should be used as a navigation target when navigation to this PSI element is requested.
    PsiElement
    getNextSibling()
    Returns the next sibling of the PSI element.
    ASTNode
    getNode()
    Returns the AST node corresponding to the element.
    PsiElement
    getOriginalElement()
    Returns the PSI element which corresponds to this element and belongs to either the project source path or class path.
    PsiElement
    getParent()
    Returns the parent of the PSI element.
    PsiElement
    getPrevSibling()
    Returns the previous sibling of the PSI element.
    @Nullable PsiReference
    getReference()
    Returns the reference from this PSI element to another PSI element (or elements), if one exists.
    int
    getStartOffsetInParent()
    Returns the text offset of the PSI element relative to its parent.
    @NonNls String
    getText()
    Returns the text of the PSI element.
    int
    getTextLength()
    Returns the length of text of the PSI element.
    int
    getTextOffset()
    Returns the offset in the file to which the caret should be placed when performing the navigation to the element.
    com.intellij.openapi.util.TextRange
    getTextRange()
    Returns the text range in the document occupied by the PSI element.
    boolean
    isEquivalentTo(PsiElement another)
    This method shouldn't be called by clients directly, because there are no guarantees of it being symmetric.
    boolean
    isPhysical()
    Checks if an actual source or class file corresponds to the element.
    boolean
    isValid()
    Checks if this PSI element is valid.
    boolean
    isWritable()
    Checks if the contents of the element can be modified (if it belongs to a non-read-only source file.)
    PsiElement
    replace(@NotNull PsiElement newElement)
    Replaces this PSI element (along with all its children) with another element (along with the children).
    boolean
    textContains(char c)
    Checks if the text of this element contains the specified character.
    boolean
    textMatches(@NotNull @NonNls CharSequence text)
    Checks if the text of this PSI element is equal to the specified character sequence.
    boolean
    textMatches(@NotNull PsiElement element)
    Checks if the text of this PSI element is equal to the text of the specified PSI element.
    @org.jetbrains.annotations.NotNull char[]
    textToCharArray()
    Returns the text of the PSI element as a character array.
    @NonNls String
    toString()
    toString() should never be presented to the user.

  • Field Details

    • EMPTY_ARRAY

      static final PsiElement[] EMPTY_ARRAY
      The empty array of PSI elements which can be reused to avoid unnecessary allocations.

  • Method Details

    • getLanguage

      @NotNull @Contract(pure=true) @NotNull Language getLanguage()
      Returns the language of the PSI element.
      Returns:
      the language instance.

    • getChildren

      @NotNull @Contract(pure=true) @NotNull PsiElement[] getChildren()
      Returns the array of children for the PSI element. Important: In some implementations children are only composite elements, i.e. not a leaf elements
      Returns:
      the array of child elements.

    • getParent

      @Contract(pure=true) PsiElement getParent()
      Returns the parent of the PSI element.
      Returns:
      the parent of the element, or null if the element has no parent.

    • getFirstChild

      @Contract(pure=true) PsiElement getFirstChild()
      Returns the first child of the PSI element.
      Returns:
      the first child, or null if the element has no children.

    • getLastChild

      @Contract(pure=true) PsiElement getLastChild()
      Returns the last child of the PSI element.
      Returns:
      the last child, or null if the element has no children.

    • getNextSibling

      @Contract(pure=true) PsiElement getNextSibling()
      Returns the next sibling of the PSI element.
      Returns:
      the next sibling, or null if the node is the last in the list of siblings.

    • getPrevSibling

      @Contract(pure=true) PsiElement getPrevSibling()
      Returns the previous sibling of the PSI element.
      Returns:
      the previous sibling, or null if the node is the first in the list of siblings.

    • getContainingFile

      @Contract(pure=true) PsiFile getContainingFile()
      Returns the file containing the PSI element.
      Returns:
      the file instance, or null if the PSI element is not contained in a file (for example, the element represents a package or directory).
      Throws:
      PsiInvalidElementAccessException - if this element is invalid

    • getTextRange

      @Contract(pure=true) com.intellij.openapi.util.TextRange getTextRange()
      Returns the text range in the document occupied by the PSI element.
      Returns:
      the text range.

    • getStartOffsetInParent

      @Contract(pure=true) int getStartOffsetInParent()
      Returns the text offset of the PSI element relative to its parent.
      Returns:
      the relative offset.

    • getTextLength

      @Contract(pure=true) int getTextLength()
      Returns the length of text of the PSI element.
      Returns:
      the text length.

    • findElementAt

      @Nullable @Contract(pure=true) @Nullable PsiElement findElementAt(int offset)
      Finds a leaf PSI element at the specified offset from the start of the text range of this node.
      Parameters:
      offset - the relative offset for which the PSI element is requested.
      Returns:
      the element at the offset, or null if none is found.

    • findReferenceAt

      @Nullable @Contract(pure=true) @Nullable PsiReference findReferenceAt(int offset)
      Finds a reference at the specified offset from the start of the text range of this node.
      Parameters:
      offset - the relative offset for which the reference is requested.
      Returns:
      the reference at the offset, or null if none is found.

    • getTextOffset

      @Contract(pure=true) int getTextOffset()
      Returns the offset in the file to which the caret should be placed when performing the navigation to the element. (For classes implementing PsiNamedElement, this should return the offset in the file of the name identifier.)
      Returns:
      the offset of the PSI element.

    • getText

      @NonNls @Contract(pure=true) @NonNls String getText()
      Returns the text of the PSI element.
      Returns:
      the element text.

    • textToCharArray

      @NotNull @Contract(pure=true) @org.jetbrains.annotations.NotNull char[] textToCharArray()
      Returns the text of the PSI element as a character array.
      Returns:
      the element text as a character array.

    • getNavigationElement

      @Contract(pure=true) PsiElement getNavigationElement()
      Returns the PSI element which should be used as a navigation target when navigation to this PSI element is requested. The method can either return this or substitute a different element if this element does not have an associated file and offset. (For example, if the source code of a library is attached to a project, the navigation element for a compiled library class is its source class.)
      Returns:
      the navigation target element.

    • getOriginalElement

      @Contract(pure=true) PsiElement getOriginalElement()
      Returns the PSI element which corresponds to this element and belongs to either the project source path or class path. The method can either return this or substitute a different element if this element does not belong to the source path or class path. (For example, the original element for a library source file is the corresponding compiled class file.)
      Returns:
      the original element.

    • textMatches

      @Contract(pure=true) boolean textMatches(@NotNull @NonNls @NotNull @NonNls CharSequence text)
      Checks if the text of this PSI element is equal to the specified character sequence.
      Parameters:
      text - the character sequence to compare with.
      Returns:
      true if the text is equal, false otherwise.

    • textMatches

      @Contract(pure=true) boolean textMatches(@NotNull @NotNull PsiElement element)
      Checks if the text of this PSI element is equal to the text of the specified PSI element.
      Parameters:
      element - the element to compare the text with.
      Returns:
      true if the text is equal, false otherwise.

    • textContains

      @Contract(pure=true) boolean textContains(char c)
      Checks if the text of this element contains the specified character.
      Parameters:
      c - the character to search for.
      Returns:
      true if the character is found, false otherwise.

    • copy

      PsiElement copy()
      Creates a copy of the file containing the PSI element and returns the corresponding element in the created copy. Resolve operations performed on elements in the copy of the file will resolve to elements in the copy, not in the original file.
      Returns:
      the element in the file copy corresponding to this element.

    • add

      PsiElement add(@NotNull @NotNull PsiElement element)
      Adds a child to this PSI element.
      Parameters:
      element - the child element to add.
      Returns:
      the element which was actually added (either element or its copy).
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • addBefore

      PsiElement addBefore(@NotNull @NotNull PsiElement element, @Nullable @Nullable PsiElement anchor)
      Adds a child to this PSI element, before the specified anchor element.
      Parameters:
      element - the child element to add.
      anchor - the anchor before which the child element is inserted (must be a child of this PSI element)
      Returns:
      the element which was actually added (either element or its copy).
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • addAfter

      PsiElement addAfter(@NotNull @NotNull PsiElement element, @Nullable @Nullable PsiElement anchor)
      Adds a child to this PSI element, after the specified anchor element.
      Parameters:
      element - the child element to add.
      anchor - the anchor after which the child element is inserted (must be a child of this PSI element)
      Returns:
      the element which was actually added (either element or its copy).
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • checkAdd

      @Deprecated void checkAdd(@NotNull @NotNull PsiElement element)
      Deprecated.
      not all PSI implementations implement this method correctly.
      Checks if it is possible to add the specified element as a child to this element, and throws an exception if the add is not possible. Does not actually modify anything.
      Parameters:
      element - the child element to check the add possibility.
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • addRange

      PsiElement addRange(PsiElement first, PsiElement last)
      Adds a range of elements as children to this PSI element.
      Parameters:
      first - the first child element to add.
      last - the last child element to add (must have the same parent as first)
      Returns:
      the first child element which was actually added (either first or its copy).
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • addRangeBefore

      PsiElement addRangeBefore(@NotNull @NotNull PsiElement first, @NotNull @NotNull PsiElement last, PsiElement anchor)
      Adds a range of elements as children to this PSI element, before the specified anchor element.
      Parameters:
      first - the first child element to add.
      last - the last child element to add (must have the same parent as first)
      anchor - the anchor before which the child element is inserted (must be a child of this PSI element)
      Returns:
      the first child element which was actually added (either first or its copy).
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • addRangeAfter

      PsiElement addRangeAfter(PsiElement first, PsiElement last, PsiElement anchor)
      Adds a range of elements as children to this PSI element, after the specified anchor element.
      Parameters:
      first - the first child element to add.
      last - the last child element to add (must have the same parent as first)
      anchor - the anchor after which the child element is inserted (must be a child of this PSI element)
      Returns:
      the first child element which was actually added (either first or its copy).
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • delete

      void delete()
      Deletes this PSI element from the tree.
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason (for example, the file containing the element is read-only).

    • checkDelete

      @Deprecated void checkDelete()
      Deprecated.
      not all PSI implementations implement this method correctly.
      Checks if it is possible to delete the specified element from the tree, and throws an exception if the add is not possible. Does not actually modify anything.
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • deleteChildRange

      void deleteChildRange(PsiElement first, PsiElement last)
      Deletes a range of children of this PSI element from the tree.
      Parameters:
      first - the first child to delete (must be a child of this PSI element)
      last - the last child to delete (must be a child of this PSI element)
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • replace

      PsiElement replace(@NotNull @NotNull PsiElement newElement)
      Replaces this PSI element (along with all its children) with another element (along with the children).
      Parameters:
      newElement - the element to replace this element with.
      Returns:
      the element which was actually inserted in the tree (either newElement or its copy)
      Throws:
      IncorrectOperationException - if the modification is not supported or not possible for some reason.

    • isValid

      @Contract(pure=true) boolean isValid()
      Checks if this PSI element is valid. Valid elements and their hierarchy members can be accessed for reading and writing. Valid elements can still correspond to underlying documents whose text is different, when those documents have been changed and not yet committed (PsiDocumentManager#commitDocument(com.intellij.openapi.editor.Document)). (In this case an attempt to change PSI will result in an exception).

      Any access to invalid elements results in PsiInvalidElementAccessException.

      Once invalid, elements can't become valid again.

      Elements become invalid in following cases:

      • They have been deleted via PSI operation (delete())
      • They have been deleted as a result of an incremental reparse (document commit)
      • Their containing file has been changed externally, or renamed so that its PSI had to be rebuilt from scratch
      Returns:
      true if the element is valid, false otherwise.
      See Also:
      • com.intellij.psi.util.PsiUtilCore#ensureValid(PsiElement)

    • isWritable

      @Contract(pure=true) boolean isWritable()
      Checks if the contents of the element can be modified (if it belongs to a non-read-only source file.)
      Returns:
      true if the element can be modified, false otherwise.

    • getReference

      @Nullable @Contract(pure=true) @Nullable PsiReference getReference()
      Returns the reference from this PSI element to another PSI element (or elements), if one exists. If the element has multiple associated references (see #getReferences() for an example), returns the first associated reference.
      Returns:
      the reference instance, or null if the PSI element does not have any associated references.
      See Also:
      • com.intellij.psi.search.searches.ReferencesSearch

    • getContext

      @Nullable @Contract(pure=true) @Nullable PsiElement getContext()
      Returns the element which should be used as the parent of this element in a tree up walk during a resolve operation. For most elements, this returns getParent(), but the context can be overridden for some elements like code fragments (see JavaCodeFragmentFactory#createCodeBlockCodeFragment(String, PsiElement, boolean)).
      Returns:
      the resolve context element.

    • isPhysical

      @Contract(pure=true) boolean isPhysical()
      Checks if an actual source or class file corresponds to the element. Non-physical elements include, for example, PSI elements created for the watch expressions in the debugger. Non-physical elements do not generate tree change events. Also, PsiDocumentManager#getDocument(PsiFile) returns null for non-physical elements. Not to be confused with FileViewProvider#isPhysical().
      Returns:
      true if the element is physical, false otherwise.

    • getNode

      @Contract(pure=true) ASTNode getNode()
      Returns the AST node corresponding to the element.
      Returns:
      the AST node instance.

    • toString

      @NonNls @Contract(pure=true) @NonNls String toString()
      toString() should never be presented to the user.
      Overrides:
      toString in class Object

    • isEquivalentTo

      @Contract(pure=true) boolean isEquivalentTo(PsiElement another)
      This method shouldn't be called by clients directly, because there are no guarantees of it being symmetric. It's called by PsiManager#areElementsEquivalent(PsiElement, PsiElement) internally, which clients should invoke instead.

      Implementations of this method should return true if the parameter is resolve-equivalent to this, i.e. it represents the same entity from the language perspective. See also PsiManager#areElementsEquivalent(PsiElement, PsiElement) documentation.