public class ASTRewrite extends Object
The following code snippet illustrated usage of this class:
Document document = new Document("import java.util.List;\nclass X {}\n"); ASTParser parser = ASTParser.newParser(AST.JLS3); parser.setSource(document.get().toCharArray()); CompilationUnit cu = (CompilationUnit) parser.createAST(null); AST ast = cu.getAST(); ImportDeclaration id = ast.newImportDeclaration(); id.setName(ast.newName(new String[] {"java", "util", "Set"})); ASTRewrite rewriter = ASTRewrite.create(ast); TypeDeclaration td = (TypeDeclaration) cu.types().get(0); ITrackedNodePosition tdLocation = rewriter.track(td); ListRewrite lrw = rewriter.getListRewrite(cu, CompilationUnit.IMPORTS_PROPERTY); lrw.insertLast(id, null); TextEdit edits = rewriter.rewriteAST(document, null); UndoEdit undo = null; try { undo = edits.apply(document); } catch(MalformedTreeException e) { e.printStackTrace(); } catch(BadLocationException e) { e.printStackTrace(); } assert "import java.util.List;\nimport java.util.Set;\nclass X {}\n".equals(document.get()); // tdLocation.getStartPosition() and tdLocation.getLength() // are new source range for "class X {}" in document.get()
If you are sure you never have to explore multiple alternate changes and you never need
to create copies
or string placeholders
,
then you can also try CompilationUnit.recordModifications()
instead.
ASTRewrite
cannot rewrite (non-Javadoc) comments from
CompilationUnit.getCommentList()
, since those comment nodes
are not part of the normal node hierarchy.
This class is not intended to be subclassed.
Modifier | Constructor and Description |
---|---|
protected |
ASTRewrite(AST ast)
Internal constructor.
|
Modifier and Type | Method and Description |
---|---|
static ASTRewrite |
create(AST ast)
Creates a new instance for describing manipulations of
the given AST.
|
ASTNode |
createCopyTarget(ASTNode node)
Creates and returns a placeholder node for a true copy of the given node.
|
ASTNode |
createGroupNode(ASTNode[] targetNodes)
Creates and returns a node that represents a sequence of nodes.
|
ASTNode |
createMoveTarget(ASTNode node)
Creates and returns a placeholder node for the new locations of the given node.
|
ASTNode |
createStringPlaceholder(String code,
int nodeType)
Creates and returns a placeholder node for a source string that is to be inserted into
the output document at the position corresponding to the placeholder.
|
Object |
get(ASTNode node,
StructuralPropertyDescriptor property)
Returns the value of the given property as managed by this rewriter.
|
AST |
getAST()
Returns the AST the rewrite was set up on.
|
TargetSourceRangeComputer |
getExtendedSourceRangeComputer()
Returns the extended source range computer for this AST rewriter.
|
ListRewrite |
getListRewrite(ASTNode node,
ChildListPropertyDescriptor property)
Creates and returns a new rewriter for describing modifications to the
given list property of the given node.
|
protected org.eclipse.jdt.internal.core.dom.rewrite.NodeInfoStore |
getNodeStore()
Internal method.
|
Object |
getProperty(String propertyName)
Returns the value of the named property of this rewrite, or
null if none. |
protected org.eclipse.jdt.internal.core.dom.rewrite.RewriteEventStore |
getRewriteEventStore()
Internal method.
|
void |
remove(ASTNode node,
TextEditGroup editGroup)
Removes the given node from its parent in this rewriter.
|
void |
replace(ASTNode node,
ASTNode replacement,
TextEditGroup editGroup)
Replaces the given node in this rewriter.
|
TextEdit |
rewriteAST()
Converts all modifications recorded by this rewriter into an object representing the the corresponding text
edits to the source of a
ITypeRoot from which the AST was created from. |
TextEdit |
rewriteAST(IDocument document,
Map options)
Converts all modifications recorded by this rewriter
into an object representing the corresponding text
edits to the given document containing the original source
code.
|
void |
set(ASTNode node,
StructuralPropertyDescriptor property,
Object value,
TextEditGroup editGroup)
Sets the given property of the given node.
|
void |
setProperty(String propertyName,
Object data)
Sets the named property of this rewrite to the given value,
or to
null to clear it. |
void |
setTargetSourceRangeComputer(TargetSourceRangeComputer computer)
Sets a custom target source range computer for this AST rewriter.
|
String |
toString()
Returns a string suitable for debugging purposes (only).
|
ITrackedNodePosition |
track(ASTNode node)
Returns an object that tracks the source range of the given node
across the rewrite to its AST.
|
protected ASTRewrite(AST ast)
create(AST)
to create instances.ast
- the AST being rewrittenpublic static ASTRewrite create(AST ast)
ast
- the AST whose nodes will be rewrittenpublic final AST getAST()
protected final org.eclipse.jdt.internal.core.dom.rewrite.RewriteEventStore getRewriteEventStore()
protected final org.eclipse.jdt.internal.core.dom.rewrite.NodeInfoStore getNodeStore()
public TextEdit rewriteAST(IDocument document, Map options) throws IllegalArgumentException
For nodes in the original that are being replaced or deleted,
this rewriter computes the adjusted source ranges
by calling getExtendedSourceRangeComputer().computeSourceRange(node)
.
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 effect of all those changes.
document
- original document containing source codeoptions
- the table of formatter options
(key type: String
; value type: String
);
or null
to use the standard global options
JavaCore.getOptions()
IllegalArgumentException
- An IllegalArgumentException
is thrown if the document passed does not correspond to the AST that is rewritten.public TextEdit rewriteAST() throws JavaModelException, IllegalArgumentException
ITypeRoot
from which the AST was created from.
The type root's source itself is not modified by this method call.
Important: This API can only be used if the modified AST has been created from a
ITypeRoot
with source. That means ASTParser.setSource(ICompilationUnit)
,
ASTParser.setSource(IClassFile)
or ASTParser.setSource(ITypeRoot)
has been used when initializing the ASTParser
. A IllegalArgumentException
is thrown
otherwise. An IllegalArgumentException
is also thrown when the type roots buffer does not correspond
anymore to the AST. Use rewriteAST(IDocument, Map)
for all ASTs created from other content.
For nodes in the original that are being replaced or deleted,
this rewriter computes the adjusted source ranges
by calling getExtendedSourceRangeComputer().computeSourceRange(node)
.
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 effect of all those changes.
JavaModelException
- A JavaModelException
is thrown when
the underlying compilation units buffer could not be accessed.IllegalArgumentException
- An IllegalArgumentException
is thrown if the document passed does not correspond to the AST that is rewritten.public final void remove(ASTNode node, TextEditGroup editGroup)
node
- the node being removed. The node can either be an original node in the AST
or (since 3.4) a new node already inserted or used as replacement in this AST rewriter.editGroup
- the edit group in which to collect the corresponding
text edits, or null
if ungroupedIllegalArgumentException
- if the node is null, or if the node is not
part of this rewriter's AST, or if the described modification is invalid
(such as removing a required node)public final void replace(ASTNode node, ASTNode replacement, TextEditGroup editGroup)
createCopyTarget(ASTNode)
or createStringPlaceholder(String, int)
). The AST itself
is not actually modified in any way; rather, the rewriter just records
a note that this node has been replaced.node
- the node being replaced. The node can either be an original node in the AST
or (since 3.4) a new node already inserted or used as replacement in this AST rewriter.replacement
- the replacement node, or null
if no
replacementeditGroup
- the edit group in which to collect the corresponding
text edits, or null
if ungroupedIllegalArgumentException
- if the node is null, or if the node is not part
of this rewriter's AST, or if the replacement node is not a new node (or
placeholder), or if the described modification is otherwise invalidpublic final void set(ASTNode node, StructuralPropertyDescriptor property, Object value, TextEditGroup editGroup)
createCopyTarget(ASTNode)
or createStringPlaceholder(String, int)
); or it must be
null
, indicating that the child should be deleted.
If the given property is a simple property, the value must be the new
value (primitive types must be boxed) or null
.
The AST itself is not actually modified in any way; rather, the rewriter
just records a note that this node has been changed in the specified way.node
- the nodeproperty
- the node's property; either a simple property or a child propertyvalue
- the replacement child or new value, or null
if noneeditGroup
- the edit group in which to collect the corresponding
text edits, or null
if ungroupedIllegalArgumentException
- if the node or property is null, or if the node
is not part of this rewriter's AST, or if the property is not a node property,
or if the described modification is invalidpublic Object get(ASTNode node, StructuralPropertyDescriptor property)
null
is returned. If it has been replaced, the replacing value
is returned. If the property has not been changed yet, the original value is returned.
For child list properties use ListRewrite.getRewrittenList()
to get access to the
rewritten nodes in a list.
node
- the nodeproperty
- the node's propertypublic final ListRewrite getListRewrite(ASTNode node, ChildListPropertyDescriptor property)
node
- the nodeproperty
- the node's property; the child list propertyIllegalArgumentException
- if the node or property is null, or if the node
is not part of this rewriter's AST, or if the property is not a node property,
or if the described modification is invalidpublic final Object getProperty(String propertyName)
null
if none.propertyName
- the property namenull
if noneIllegalArgumentException
- if the given property name is null
setProperty(String,Object)
public final ITrackedNodePosition track(ASTNode node)
rewrite
is called, the result object is updated to
reflect the given node's source range in the rewritten AST.node
- the node to tracknode
IllegalArgumentException
- if the node is null, or if the node
is not part of this rewriter's AST, or if the node is already being
trackedpublic final ASTNode createStringPlaceholder(String code, int nodeType)
code
- the string to be inserted; lines should should not have extra indentationnodeType
- the ASTNode type that corresponds to the passed code.IllegalArgumentException
- if the code is null, or if the node
type is invalidpublic final ASTNode createGroupNode(ASTNode[] targetNodes)
createCopyTarget(ASTNode)
or createStringPlaceholder(String, int)
), or another group node.
The type of the returned node is unspecified. The returned node can be used
to replace an existing node (or as an element of another group node).
When the document is rewritten, the source code for each of the given nodes is
inserted, in order, into the output document at the position corresponding to the
group (indentation is adjusted).targetNodes
- the nodes to go in the groupIllegalArgumentException
- if the targetNodes is null
or emptypublic final ASTNode createCopyTarget(ASTNode node)
node
- the node to create a copy placeholder forIllegalArgumentException
- if the node is null, or if the node
is not part of this rewriter's ASTpublic final ASTNode createMoveTarget(ASTNode node)
node
- the node to create a move placeholder forIllegalArgumentException
- if the node is null, or if the node
is not part of this rewriter's ASTpublic final TargetSourceRangeComputer getExtendedSourceRangeComputer()
new TargetSourceRangeComputer()
.setTargetSourceRangeComputer(TargetSourceRangeComputer)
public final void setProperty(String propertyName, Object data)
null
to clear it.
Clients should employ property names that are sufficiently unique to avoid inadvertent conflicts with other clients that might also be setting properties on the same rewrite.
Note that modifying a property is not considered a modification to the AST itself. This is to allow clients to decorate existing rewrites with their own properties without jeopardizing certain things (like the validity of bindings), which rely on the underlying tree remaining static.
propertyName
- the property namedata
- the new property value, or null
if noneIllegalArgumentException
- if the given property name is null
getProperty(String)
public final void setTargetSourceRangeComputer(TargetSourceRangeComputer computer)
computer
- a target source range computer,
or null
to restore the default value of
new TargetSourceRangeComputer()
getExtendedSourceRangeComputer()
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.