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.

### Nested Class Summary

Nested Classes
`static class` `ASTRewrite.CommentPosition` Defines the positions of the comment.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `addComment​(IASTNode node, IASTComment comment, ASTRewrite.CommentPosition pos)` Assigns the comment to the node.
`static ASTRewrite` `create​(IASTTranslationUnit node)` Creates a rewriter for a translation unit.
`IASTNode` `createLiteralNode​(String code)` Creates and returns a node for a source string that is to be inserted into the output document.
`List<IASTComment>` `getComments​(IASTNode node, ASTRewrite.CommentPosition pos)` Returns comments for the given node.
`ASTRewrite` `insertBefore​(IASTNode parent, IASTNode insertionPoint, IASTNode newNode, org.eclipse.text.edits.TextEditGroup editGroup)` Inserts the given node in this rewriter.
`void` `remove​(IASTNode node, org.eclipse.text.edits.TextEditGroup editGroup)` Removes the given node in this rewriter.
`void` `removeAllComments​(IASTNode node)` Removes all comments of a node.
`void` `removeComment​(IASTNode node, IASTComment comment)` Removes the given `comment` from the `node`.
`void` `removeComments​(IASTNode node, ASTRewrite.CommentPosition pos)` Removes all comments of a node at a given position.
`ASTRewrite` `replace​(IASTNode node, IASTNode replacement, org.eclipse.text.edits.TextEditGroup editGroup)` Replaces the given node in this rewriter.
`org.eclipse.ltk.core.refactoring.Change` `rewriteAST()` Converts all modifications recorded by this rewriter into the change object required by the refactoring framework.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Method Detail

#### 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