Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse JDT Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.jdt.core.dom.rewrite
Class ASTRewrite

    java.lang.Object
      org.eclipse.jdt.core.dom.rewrite.ASTRewrite

public class ASTRewrite
extends Object

Infrastucture 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. The key thing is that this is all done without actually modifying the original AST, which has the virtue of allowing one to entertain several alternate sets of changes on the same AST (e.g., for calculating quick fix proposals). The rewrite infrastructure tries to generate minimal text changes, preserve existing comments and indentation, and follow code formatter settings. If the freedom to explore multiple alternate changes is not required, consider using the AST's built-in rewriter (see `CompilationUnit.rewrite(IDocument, Map)`).

The following code snippet illustrated usage of this class:

     Document doc = new Document("import java.util.List;\nclass X {}\n");
     ASTParser parser = ASTParser.newParser(AST.JLS2);
     parser.setSource(doc.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);
     ListRewriter lrw = rewriter.getListRewrite(cu,
                           CompilationUnit.IMPORTS_PROPERTY);
     lrw.insertLast(id, null);
     TextEdit edits = rewriter.rewriteAST(document, null);
     UndoEdit undo = edits.apply(document);
     assert "import java.util.List;\nimport java.util.Set;\nclass X {}"
       .equals(doc.get().toCharArray());
     // tdLocation.getStartPosition() and tdLocation.getLength()
     // are new source range for "class X {}" in doc.get()

This class is not intended to be subclassed.

Since:
  3.0

Constructor Summary
`protected` | `ASTRewrite(AST ast)` Internal constructor.

Method Summary
`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` | `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.
`AST` | `getAST()` Returns the AST the rewrite was set up on.
`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.
`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(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.
`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.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### ASTRewrite

    protected ASTRewrite(AST ast)

  Internal constructor. Creates a new instance for the given AST. Clients should use `create(AST)` to create instances.

Parameters:
  `ast` - the AST being rewritten

Method Detail

### create

    public static ASTRewrite create(AST ast)

  Creates a new instance for describing manipulations of the given AST.

  Parameters:
    `ast` - the AST whose nodes will be rewritten
  Returns:
    the new rewriter instance

### getAST

    public final AST getAST()

  Returns the AST the rewrite was set up on.

  Returns:
    the AST the rewrite was set up on

### getRewriteEventStore

    protected final org.eclipse.jdt.internal.core.dom.rewrite.RewriteEventStore getRewriteEventStore()

  Internal method. Returns the internal event store. Clients should not use.

  Returns:
    Returns the internal event store. Clients should not use.

### getNodeStore

    protected final org.eclipse.jdt.internal.core.dom.rewrite.NodeInfoStore getNodeStore()

  Internal method. Returns the internal node info store. Clients should not use.

  Returns:
    Returns the internal info store. Clients should not use.

### rewriteAST

    public TextEdit rewriteAST(IDocument document,
                               Map options)
                        throws IllegalArgumentException

  Converts all modifications recorded by this rewriter into an object representing the corresponding text edits to the given document containing the original source code. The document itself is not modified.

  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.

  Parameters:
    `document` - original document containing source code
    `options` - the table of formatter options (key type: `String`; value type: `String`); or `null` to use the standard global options `JavaCore.getOptions()`
  Returns:
    text edit object describing the changes to the document corresponding to the changes recorded by this rewriter
  Throws:
    `IllegalArgumentException` - An `IllegalArgumentException` is thrown if the document passed does not correspond to the AST that is rewritten.

### remove

    public final void remove(ASTNode node,
                             TextEditGroup editGroup)

  Removes the given node from its parent in this rewriter. The AST itself is not actually modified in any way; rather, the rewriter just records a note that this node should not be there.

  Parameters:
    `node` - the node being removed
    `editGroup` - the edit group in which to collect the corresponding text edits, or `null` if ungrouped
  Throws:
    `IllegalArgumentException` - 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)

### replace

    public final void replace(ASTNode node,
                              ASTNode replacement,
                              TextEditGroup editGroup)

  Replaces the given node in this rewriter. The replacement node must either be brand new (not part of the original AST) or a placeholder node (for example, one created by `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.

  Parameters:
    `node` - the node being replaced
    `replacement` - the replacement node, or `null` if no replacement
    `editGroup` - the edit group in which to collect the corresponding text edits, or `null` if ungrouped
  Throws:
    `IllegalArgumentException` - 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 invalid

### set

    public final void set(ASTNode node,
                          StructuralPropertyDescriptor property,
                          Object value,
                          TextEditGroup editGroup)

  Sets the given property of the given node. If the given property is a child property, the value must be a replacement node that is either be brand new (not part of the original AST) or a placeholder node (for example, one created by `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.

  Parameters:
    `node` - the node
    `property` - the node's property; either a simple property or a child property
    `value` - the replacement child or new value, or `null` if none
    `editGroup` - the edit group in which to collect the corresponding text edits, or `null` if ungrouped
  Throws:
    `IllegalArgumentException` - 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 invalid

### getListRewrite

    public final ListRewrite getListRewrite(ASTNode node,
                                            ChildListPropertyDescriptor property)

  Creates and returns a new rewriter for describing modifications to the given list property of the given node.

  Parameters:
    `node` - the node
    `property` - the node's property; the child list property
  Returns:
    a new list rewriter object
  Throws:
    `IllegalArgumentException` - 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 invalid

### track

    public final ITrackedNodePosition track(ASTNode node)

  Returns an object that tracks the source range of the given node across the rewrite to its AST. Upon return, the result object reflects the given node's current source range in the AST. After `rewrite` is called, the result object is updated to reflect the given node's source range in the rewritten AST.

  Parameters:
    `node` - the node to track
  Returns:
    an object that tracks the source range of `node`
  Throws:
    `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 tracked

### createStringPlaceholder

    public final 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. The string will be inserted without being reformatted beyond correcting the indentation level. The placeholder node can either be inserted as new or used to replace an existing node.

  Parameters:
    `code` - the string to be inserted; lines should should not have extra indentation
    `nodeType` - the ASTNode type that corresponds to the passed code.
  Returns:
    the new placeholder node
  Throws:
    `IllegalArgumentException` - if the code is null, or if the node type is invalid

### createCopyTarget

    public final ASTNode createCopyTarget(ASTNode node)

  Creates and returns a placeholder node for a true copy of the given node. The placeholder node can either be inserted as new or used to replace an existing node. When the document is rewritten, a copy of the source code for the given node is inserted into the output document at the position corresponding to the placeholder (indentation is adjusted).

  Parameters:
    `node` - the node to create a copy placeholder for
  Returns:
    the new placeholder node
  Throws:
    `IllegalArgumentException` - if the node is null, or if the node is not part of this rewriter's AST

### createMoveTarget

    public final ASTNode createMoveTarget(ASTNode node)

  Creates and returns a placeholder node for the new locations of the given node. After obtaining a placeholder, the node should then to be removed or replaced. The placeholder node can either be inserted as new or used to replace an existing node. When the document is rewritten, the source code for the given node is inserted into the output document at the position corresponding to the placeholder (indentation is adjusted).

  Parameters:
    `node` - the node to create a move placeholder for
  Returns:
    the new placeholder node
  Throws:
    `IllegalArgumentException` - if the node is null, or if the node is not part of this rewriter's AST

### toString

    public String toString()

  Returns a string suitable for debugging purposes (only).

  Returns:
    a debug string

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse JDT Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) IBM Corp. and others 2000, 2004. All Rights Reserved.