Package org.eclipse.cdt.core.dom.rewrite

Class ASTRewrite

java.lang.Object
org.eclipse.cdt.core.dom.rewrite.ASTRewrite
public final class ASTRewrite extends Object
Infrastructure for modifying code by describing changes to AST nodes. The AST rewriter collects descriptions of modifications to nodes and translates these descriptions into text edits that can then be applied to the original source. This is all done without actually modifying the original AST. The rewrite infrastructure tries to generate minimal text changes, preserve existing comments and indentation, and follow code formatter settings. A IASTComment can be removed from or added to a node.

The initial implementation does not support nodes that implement IASTPreprocessorStatement or IASTProblem.

EXPERIMENTAL. This class or interface has been added as part of a work in progress. There is no guarantee that this API will work or that it will remain the same. Please do not use this API without consulting with the CDT team.

Since:
5.0
Restriction:
This class is not intended to be instantiated by clients.

  • Method Details

    • create

      public static ASTRewrite create(IASTTranslationUnit node)
      Creates a rewriter for a translation unit.

    • createLiteralNode

      public final IASTNode createLiteralNode(String code)
      Creates and returns a node for a source string that is to be inserted into the output document. The string will be inserted without being reformatted beyond correcting the indentation level.
      Parameters:
      code - the string to be inserted; lines should not have extra indentation
      Returns:
      a synthetic node representing the literal code.
      Throws:
      IllegalArgumentException - if the code is null.

    • remove

      public final void remove(IASTNode node, org.eclipse.text.edits.TextEditGroup editGroup)
      Removes the given node in this rewriter. The ast is not modified, the rewriter just records the removal.
      Parameters:
      node - the node being removed
      editGroup - the edit group in which to collect the corresponding text edits, or null
      Throws:
      IllegalArgumentException - if the node is null, the node is not part of this rewriter's AST.

    • replace

      public final ASTRewrite replace(IASTNode node, IASTNode replacement, org.eclipse.text.edits.TextEditGroup editGroup)
      Replaces the given node in this rewriter. The ast is not modified, the rewriter just records the replacement. The replacement node can be part of a translation-unit or it is a synthetic (newly created) node.
      Parameters:
      node - the node being replaced
      replacement - the node replacing the given one
      editGroup - the edit group in which to collect the corresponding text edits, or null
      Returns:
      a rewriter for further rewriting the replacement node.
      Throws:
      IllegalArgumentException - if the node or the replacement is null, or if the node is not part of this rewriter's AST

    • insertBefore

      public final ASTRewrite insertBefore(IASTNode parent, IASTNode insertionPoint, IASTNode newNode, org.eclipse.text.edits.TextEditGroup editGroup)
      Inserts the given node in this rewriter. The ast is not modified, the rewriter just records the insertion. The new node can be part of a translation-unit or it is a synthetic (newly created) node.
      Parameters:
      parent - the parent the new node is added to.
      insertionPoint - the node before which the insertion shall be done, or null for inserting after the last child.
      newNode - the node being inserted
      editGroup - the edit group in which to collect the corresponding text edits, or null
      Returns:
      a rewriter for further rewriting the inserted node.
      Throws:
      IllegalArgumentException - if the parent or the newNode is null, or if the parent is not part of this rewriter's AST, or the insertionPoint is not a child of the parent.

    • rewriteAST

      public org.eclipse.ltk.core.refactoring.Change rewriteAST()
      Converts all modifications recorded by this rewriter into the change object required by the refactoring framework.

      Calling this methods does not discard the modifications on record. Subsequence modifications are added to the ones already on record. If this method is called again later, the resulting text edit object will accurately reflect the net cumulative affect of all those changes.

      Returns:
      Change object describing the changes to the document corresponding to the changes recorded by this rewriter
      Since:
      5.0

    • addComment

      public void addComment(IASTNode node, IASTComment comment, ASTRewrite.CommentPosition pos)
      Assigns the comment to the node.
      Parameters:
      node - the node.
      comment - the comment to be attached to the node at the given position.
      pos - the position of the comment.
      Since:
      5.3

    • removeComment

      public void removeComment(IASTNode node, IASTComment comment)
      Removes the given comment from the node. If the comment is not attached to the node nothing happens.
      Parameters:
      node - the node.
      comment - the comment to be removed from the node.
      Since:
      6.6

    • removeComments

      public void removeComments(IASTNode node, ASTRewrite.CommentPosition pos)
      Removes all comments of a node at a given position.
      Parameters:
      node - the node.
      pos - the position of the comments to be removed from the node.
      Since:
      6.6

    • removeAllComments

      public void removeAllComments(IASTNode node)
      Removes all comments of a node.
      Parameters:
      node - the node.
      Since:
      6.6

    • getComments

      public List<IASTComment> getComments(IASTNode node, ASTRewrite.CommentPosition pos)
      Returns comments for the given node.
      Parameters:
      node - the node
      pos - the position of the comments
      Returns:
      All comments assigned to the node at this position
      Since:
      5.3