| /* |
| * Copyright 2000-2014 JetBrains s.r.o. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.intellij.lang; |
| |
| import com.intellij.openapi.util.Key; |
| import com.intellij.openapi.util.TextRange; |
| import com.intellij.openapi.util.UserDataHolder; |
| import com.intellij.psi.PsiElement; |
| import com.intellij.psi.tree.IElementType; |
| import com.intellij.psi.tree.TokenSet; |
| import org.jetbrains.annotations.NotNull; |
| import org.jetbrains.annotations.Nullable; |
| |
| /** |
| * A node in the AST tree. The AST is an intermediate parsing tree created by {@link PsiBuilder}, |
| * out of which a PSI tree is then created. |
| * |
| * @author max |
| * @see PsiElement |
| */ |
| |
| public interface ASTNode extends UserDataHolder { |
| ASTNode[] EMPTY_ARRAY = new ASTNode[0]; |
| |
| /** |
| * Returns the type of this node. |
| * |
| * @return the element type. |
| */ |
| IElementType getElementType(); |
| |
| /** |
| * Returns the text of this node. |
| * |
| * @return the node text. |
| */ |
| String getText(); |
| |
| /** |
| * Returns same text getText() returns but might be more effective eliminating toString() transformation from internal CharSequence representation |
| * |
| * @return the node text. |
| */ |
| CharSequence getChars(); |
| |
| /** |
| * Checks if the specified character is present in the text of this node. |
| * |
| * @param c the character to search for. |
| * @return true if the character is found, false otherwise. |
| */ |
| boolean textContains(char c); |
| |
| /** |
| * Returns the starting offset of the node text in the document. |
| * |
| * @return the start offset. |
| */ |
| int getStartOffset(); |
| |
| /** |
| * Returns the length of the node text. |
| * |
| * @return the text length. |
| */ |
| int getTextLength(); |
| |
| /** |
| * Returns the text range (a combination of starting offset in the document and length) for this node. |
| * |
| * @return the text range. |
| */ |
| TextRange getTextRange(); |
| |
| /** |
| * Returns the parent of this node in the tree. |
| * |
| * @return the parent node. |
| */ |
| ASTNode getTreeParent(); |
| |
| /** |
| * Returns the first child of this node in the tree. |
| * |
| * @return the first child node. |
| */ |
| ASTNode getFirstChildNode(); |
| |
| /** |
| * Returns the last child of this node in the tree. |
| * |
| * @return the last child node. |
| */ |
| ASTNode getLastChildNode(); |
| |
| /** |
| * Returns the next sibling of this node in the tree. |
| * |
| * @return the next sibling node. |
| */ |
| ASTNode getTreeNext(); |
| |
| /** |
| * Returns the previous sibling of this node in the tree. |
| * |
| * @return the previous sibling node. |
| */ |
| ASTNode getTreePrev(); |
| |
| /** |
| * Returns the list of children of the specified node, optionally filtered by the |
| * specified token type filter. |
| * |
| * @param filter the token set used to filter the returned children, or null if |
| * all children should be returned. |
| * @return the children array. |
| */ |
| ASTNode[] getChildren(@Nullable TokenSet filter); |
| |
| /** |
| * Adds the specified child node as the last child of this node. |
| * |
| * @param child the child node to add. |
| */ |
| void addChild(@NotNull ASTNode child); |
| |
| /** |
| * Adds the specified child node at the specified position in the child list. |
| * |
| * @param child the child node to add. |
| * @param anchorBefore the node before which the child node is inserted (<code>null</code> to add a child as a last node). |
| */ |
| void addChild(@NotNull ASTNode child, @Nullable ASTNode anchorBefore); |
| |
| /** |
| * Add leaf element with specified type and text in the child list. |
| * @param leafType type of leaf element to add. |
| * @param leafText text of added leaf. |
| * @param anchorBefore the node before which the child node is inserted. |
| * @since 7.0 |
| */ |
| void addLeaf(@NotNull IElementType leafType, CharSequence leafText, @Nullable ASTNode anchorBefore); |
| |
| /** |
| * Removes the specified node from the list of children of this node. |
| * |
| * @param child the child node to remove. |
| */ |
| void removeChild(@NotNull ASTNode child); |
| |
| /** |
| * Removes a range of nodes from the list of children, starting with <code>firstNodeToRemove</code>, |
| * up to and not including <code>firstNodeToKeep</code>. |
| * |
| * @param firstNodeToRemove the first child node to remove from the tree. |
| * @param firstNodeToKeep the first child node to keep in the tree. |
| */ |
| void removeRange(@NotNull ASTNode firstNodeToRemove, ASTNode firstNodeToKeep); |
| |
| /** |
| * Replaces the specified child node with another node. |
| * |
| * @param oldChild the child node to replace. |
| * @param newChild the node to replace with. |
| */ |
| void replaceChild(@NotNull ASTNode oldChild, @NotNull ASTNode newChild); |
| |
| /** |
| * Replaces all child nodes with the children of the specified node. |
| * |
| * @param anotherParent the parent node whose children are used for replacement. |
| */ |
| void replaceAllChildrenToChildrenOf(ASTNode anotherParent); |
| |
| /** |
| * Adds a range of nodes belonging to the same parent to the list of children of this node, |
| * starting with <code>firstChild</code>, up to and not including <code>firstChildToNotAdd</code>. |
| * |
| * @param firstChild the first node to add. |
| * @param firstChildToNotAdd the first child node following firstChild which will not be added to the tree. |
| * @param anchorBefore the node before which the child nodes are inserted. |
| */ |
| void addChildren(ASTNode firstChild, ASTNode firstChildToNotAdd, ASTNode anchorBefore); |
| |
| /** |
| * Creates and returns a deep copy of the AST tree part starting at this node. |
| * |
| * @return the top node of the copied tree (as an ASTNode object) |
| */ |
| Object clone(); |
| |
| /** |
| * Creates a copy of the entire AST tree containing this node and returns a counterpart |
| * of this node in the resulting tree. |
| * |
| * @return the counterpart of this node in the copied tree. |
| */ |
| ASTNode copyElement(); |
| |
| /** |
| * Finds a leaf child node at the specified offset from the start of the text range of this node. |
| * |
| * @param offset the relative offset for which the child node is requested. |
| * @return the child node, or null if none is found. |
| */ |
| @Nullable |
| ASTNode findLeafElementAt(int offset); |
| |
| /** |
| * Returns a copyable user data object attached to this node. |
| * |
| * @param key the key for accessing the user data object. |
| * @return the user data object, or null if no such object is found in the current node. |
| * @see #putCopyableUserData(com.intellij.openapi.util.Key, Object) |
| */ |
| @Nullable |
| <T> T getCopyableUserData(Key<T> key); |
| |
| /** |
| * Attaches a copyable user data object to this node. Copyable user data objects are copied |
| * when the AST tree nodes are copied. |
| * |
| * @param key the key for accessing the user data object. |
| * @param value the user data object to attach. |
| * @see #getCopyableUserData(com.intellij.openapi.util.Key) |
| */ |
| <T> void putCopyableUserData(Key<T> key, T value); |
| |
| /** |
| * Returns the first child of the specified node which has the specified type. |
| * |
| * @param type the type of the node to return. |
| * @return the found node, or null if none was found. |
| */ |
| @Nullable |
| ASTNode findChildByType(IElementType type); |
| |
| /** |
| * Returns the first child after anchor of the specified node which has the specified type. |
| * |
| * @param type the type of the node to return. |
| * @param anchor to start search from |
| * @return the found node, or null if none was found. |
| */ |
| @Nullable |
| ASTNode findChildByType(IElementType type, @Nullable ASTNode anchor); |
| |
| /** |
| * Returns the first child of the specified node which has type from specified set. |
| * |
| * @param typesSet the token set used to filter the returned children. |
| * @return the found node, or null if none was found. |
| */ |
| @Nullable |
| ASTNode findChildByType(@NotNull TokenSet typesSet); |
| |
| /** |
| * Returns the first child after anchor of the specified node which has type from specified set. |
| * |
| * @param typesSet the token set used to filter the returned children. |
| * @param anchor to start search from |
| * @return the found node, or null if none was found. |
| */ |
| @Nullable |
| ASTNode findChildByType(@NotNull TokenSet typesSet, @Nullable ASTNode anchor); |
| |
| /** |
| * Returns the PSI element for this node. |
| * |
| * @return the PSI element. |
| */ |
| PsiElement getPsi(); |
| |
| /** |
| * Checks and returns the PSI element for this node. |
| * |
| * @param clazz expected psi class |
| * @return the PSI element. |
| */ |
| <T extends PsiElement> T getPsi(@NotNull Class<T> clazz); |
| } |