org.eclipse.cdt.core.dom.rewrite

Class ASTRewrite

java.lang.Object

org.eclipse.cdt.core.dom.rewrite.ASTRewrite

public final class ASTRewrite
extends java.lang.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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ASTRewrite.CommentPosition Defines the positions of the comment.

Method Summary

Modifier and Type	Method and Description
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(java.lang.String code) Creates and returns a node for a source string that is to be inserted into the output document.
java.util.List<IASTComment>	getComments(IASTNode node, ASTRewrite.CommentPosition pos) Returns comments for the given node.
ASTRewrite	insertBefore(IASTNode parent, IASTNode insertionPoint, IASTNode newNode, TextEditGroup editGroup) Inserts the given node in this rewriter.
void	remove(IASTNode node, TextEditGroup editGroup) Removes the given node in this rewriter.
ASTRewrite	replace(IASTNode node, IASTNode replacement, TextEditGroup editGroup) Replaces the given node in this rewriter.
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(java.lang.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:

java.lang.IllegalArgumentException - if the code is null.

remove

public final void remove(IASTNode node,
                         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:

java.lang.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,
                                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:

java.lang.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,
                                     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:

java.lang.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 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

getComments

public java.util.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