Package org.eclipse.text.edits

Class TextEdit

java.lang.Object
org.eclipse.text.edits.TextEdit
Direct Known Subclasses:
CopyingRangeMarker, CopySourceEdit, CopyTargetEdit, DeleteEdit, InsertEdit, MoveSourceEdit, MoveTargetEdit, MultiTextEdit, RangeMarker, ReplaceEdit, UndoEdit
public abstract class TextEdit extends Object
A text edit describes an elementary text manipulation operation. Edits are executed by applying them to a document (e.g. an instance of IDocument ).

Text edits form a tree. Clients can navigate the tree upwards, from child to parent, as well as downwards. Newly created edits are un-parented. New edits are added to the tree by calling one of the add methods on a parent edit.

An edit tree is well formed in the following sense:

  • a parent edit covers all its children
  • children don't overlap
  • an edit with length 0 can't have any children

Any manipulation of the tree that violates one of the above requirements results in a MalformedTreeException.

Insert edits are represented by an edit of length 0. If more than one insert edit exists at the same offset then the edits are executed in the order in which they have been added to a parent. The following code example: 

    IDocument document= new Document("org");
          MultiTextEdit edit= new MultiTextEdit();
    edit.addChild(new InsertEdit(0, "www."));
    edit.addChild(new InsertEdit(0, "eclipse."));
    edit.apply(document);

therefore results in string: "www.eclipse.org".

Text edits can be executed in a mode where the edit's region is updated to reflect the edit's position in the changed document. Region updating is enabled by default or can be requested by passing UPDATE_REGIONS to the apply(IDocument, int) method. In the above example the region of the InsertEdit(0, "eclipse.") edit after executing the root edit is [3, 8]. If the region of an edit got deleted during change execution the region is set to [-1, -1] and the method isDeleted returns true.

This class isn't intended to be subclassed outside of the edit framework. Clients are only allowed to subclass MultiTextEdit.
Since:
3.0
Restriction:
This class is not intended to be subclassed by clients.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    CREATE_UNDO
    Flags indicating that applying an edit tree to a document is supposed to create a corresponding undo edit.
    static final int
    NONE
    Flags indicating that neither CREATE_UNDO nor UPDATE_REGIONS is set.
    static final int
    UPDATE_REGIONS
    Flag indicating that the edit's region will be updated to reflect its position in the changed document.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    TextEdit(int offset, int length)
    Create a new text edit.
    protected
    TextEdit(TextEdit source)
    Copy constructor

  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    accept(TextEditVisitor visitor)
    Accepts the given visitor on a visit of the current edit.
    protected abstract void
    accept0(TextEditVisitor visitor)
    Accepts the given visitor on a type-specific visit of the current edit.
    protected final void
    acceptChildren(TextEditVisitor visitor)
    Accepts the given visitor on the edits children.
    final void
    addChild(TextEdit child)
    Adds the given edit child to this edit.
    final void
    addChildren(TextEdit[] edits)
    Adds all edits in edits to this edit.
    final UndoEdit
    apply(IDocument document)
    Applies the edit tree rooted by this edit to the given document.
    final UndoEdit
    apply(IDocument document, int style)
    Applies the edit tree rooted by this edit to the given document.
    protected boolean
    canZeroLengthCover()
    Returns true if an edit with length zero can cover another edit.
    protected void
    childDocumentUpdated()
    Hook method called when the document updating of a child edit has been completed.
    protected void
    childRegionUpdated()
    Hook method called when the region updating of a child edit has been completed.
    final TextEdit
    copy()
    Creates a deep copy of the edit tree rooted at this edit.
    boolean
    covers(TextEdit other)
    Returns true if the edit covers the given edit other.
    protected abstract TextEdit
    doCopy()
    Creates and returns a copy of this edit.
    final boolean
    equals(Object obj)
    The Edit implementation of this Object method uses object identity (==).
    final TextEdit[]
    getChildren()
    Returns the edit's children.
    final int
    getChildrenSize()
    Returns the size of the managed children.
    static IRegion
    getCoverage(TextEdit[] edits)
    Returns the text range spawned by the given array of text edits.
    final int
    getExclusiveEnd()
    Returns the exclusive end position of this edit.
    final int
    getInclusiveEnd()
    Returns the inclusive end position of this edit.
    int
    getLength()
    Returns the length of the edit.
    int
    getOffset()
    Returns the offset of the edit.
    final TextEdit
    getParent()
    Returns the edit's parent.
    final IRegion
    getRegion()
    Returns the range that this edit is manipulating.
    final TextEdit
    getRoot()
    Returns the root edit of the edit tree.
    final boolean
    hasChildren()
    Returns true if this edit has children.
    final int
    hashCode()
    The Edit implementation of this Object method calls uses Object#hashCode() to compute its hash code.
    final boolean
    isDeleted()
    Returns whether this edit has been deleted or not.
    final void
    moveTree(int delta)
    Move all offsets in the tree by the given delta.
    protected void
    postProcessCopy(TextEditCopier copier)
    This method is called on every edit of the copied tree to do some post-processing like connected an edit to a different edit in the tree.
    final TextEdit
    removeChild(int index)
    Removes the edit specified by the given index from the list of children.
    final boolean
    removeChild(TextEdit child)
    Removes the first occurrence of the given child from the list of children.
    final TextEdit[]
    removeChildren()
    Removes all child edits from and returns them.
    String
    toString()
     

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • NONE

      public static final int NONE
      Flags indicating that neither CREATE_UNDO nor UPDATE_REGIONS is set.
      See Also:

    • CREATE_UNDO

      public static final int CREATE_UNDO
      Flags indicating that applying an edit tree to a document is supposed to create a corresponding undo edit. If not specified null is returned from method apply.
      See Also:

    • UPDATE_REGIONS

      public static final int UPDATE_REGIONS
      Flag indicating that the edit's region will be updated to reflect its position in the changed document. If not specified when applying an edit tree to a document the edit's region will be arbitrary. It is even not guaranteed that the tree is still well formed.
      See Also:

  • Constructor Details

    • TextEdit

      protected TextEdit(int offset, int length)
      Create a new text edit. Parent is initialized to null and the edit doesn't have any children.
      Parameters:
      offset - the edit's offset
      length - the edit's length

    • TextEdit

      protected TextEdit(TextEdit source)
      Copy constructor
      Parameters:
      source - the source to copy form

  • Method Details

    • getRegion

      public final IRegion getRegion()
      Returns the range that this edit is manipulating. The returned IRegion contains the edit's offset and length at the point in time when this call is made. Any subsequent changes to the edit's offset and length aren't reflected in the returned region object.

      Creating a region for a deleted edit will result in an assertion failure.

      Returns:
      the manipulated region

    • getOffset

      public int getOffset()
      Returns the offset of the edit. An offset is a 0-based character index. Returns -1 if the edit is marked as deleted.
      Returns:
      the offset of the edit

    • getLength

      public int getLength()
      Returns the length of the edit. Returns -1 if the edit is marked as deleted.
      Returns:
      the length of the edit

    • getInclusiveEnd

      public final int getInclusiveEnd()
      Returns the inclusive end position of this edit. The inclusive end position denotes the last character of the region manipulated by this edit. The returned value is the result of the following calculation: 
         getOffset() + getLength() - 1;
      Returns:
      the inclusive end position

    • getExclusiveEnd

      public final int getExclusiveEnd()
      Returns the exclusive end position of this edit. The exclusive end position denotes the next character of the region manipulated by this edit. The returned value is the result of the following calculation: 
         getOffset() + getLength();
      Returns:
      the exclusive end position

    • isDeleted

      public final boolean isDeleted()
      Returns whether this edit has been deleted or not.
      Returns:
      true if the edit has been deleted; otherwise false is returned.

    • moveTree

      public final void moveTree(int delta)
      Move all offsets in the tree by the given delta. This node must be a root node. The resulting offsets must be greater or equal to zero.
      Parameters:
      delta - the delta
      Since:
      3.1

    • covers

      public boolean covers(TextEdit other)
      Returns true if the edit covers the given edit other. It is up to the concrete text edit to decide if a edit of length zero can cover another edit.
      Parameters:
      other - the other edit
      Returns:
      true if the edit covers the other edit; otherwise false is returned.

    • canZeroLengthCover

      protected boolean canZeroLengthCover()
      Returns true if an edit with length zero can cover another edit. Returns false otherwise.
      Returns:
      whether an edit of length zero can cover another edit

    • getParent

      public final TextEdit getParent()
      Returns the edit's parent. The method returns null if this edit hasn't been add to another edit.
      Returns:
      the edit's parent

    • getRoot

      public final TextEdit getRoot()
      Returns the root edit of the edit tree.
      Returns:
      the root edit of the edit tree
      Since:
      3.1

    • addChild

      public final void addChild(TextEdit child) throws MalformedTreeException
      Adds the given edit child to this edit.
      Parameters:
      child - the child edit to add
      Throws:
      MalformedTreeException - is thrown if the child edit can't be added to this edit. This is the case if the child overlaps with one of its siblings or if the child edit's region isn't fully covered by this edit.

    • addChildren

      public final void addChildren(TextEdit[] edits) throws MalformedTreeException
      Adds all edits in edits to this edit.
      Parameters:
      edits - the text edits to add
      Throws:
      MalformedTreeException - is thrown if one of the given edits can't be added to this edit.
      See Also:

    • removeChild

      public final TextEdit removeChild(int index)
      Removes the edit specified by the given index from the list of children. Returns the child edit that was removed from the list of children. The parent of the returned edit is set to null.
      Parameters:
      index - the index of the edit to remove
      Returns:
      the removed edit
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • removeChild

      public final boolean removeChild(TextEdit child)
      Removes the first occurrence of the given child from the list of children.
      Parameters:
      child - the child to be removed
      Returns:
      true if the edit contained the given child; otherwise false is returned

    • removeChildren

      public final TextEdit[] removeChildren()
      Removes all child edits from and returns them. The parent of the removed edits is set to null.
      Returns:
      an array of the removed edits

    • hasChildren

      public final boolean hasChildren()
      Returns true if this edit has children. Otherwise false is returned.
      Returns:
      true if this edit has children; otherwise false is returned

    • getChildren

      public final TextEdit[] getChildren()
      Returns the edit's children. If the edit doesn't have any children an empty array is returned.
      Returns:
      the edit's children

    • getChildrenSize

      public final int getChildrenSize()
      Returns the size of the managed children.
      Returns:
      the size of the children

    • getCoverage

      public static IRegion getCoverage(TextEdit[] edits)
      Returns the text range spawned by the given array of text edits. The method requires that the given array contains at least one edit. If all edits passed are deleted the method returns null.
      Parameters:
      edits - an array of edits
      Returns:
      the text range spawned by the given array of edits or null if all edits are marked as deleted

    • equals

      public final boolean equals(Object obj)
      The Edit implementation of this Object method uses object identity (==).
      Overrides:
      equals in class Object
      Parameters:
      obj - the other object
      Returns:
      true iff this == obj; otherwise false is returned
      See Also:

    • hashCode

      public final int hashCode()
      The Edit implementation of this Object method calls uses Object#hashCode() to compute its hash code.
      Overrides:
      hashCode in class Object
      Returns:
      the object's hash code value
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • copy

      public final TextEdit copy()
      Creates a deep copy of the edit tree rooted at this edit.
      Returns:
      a deep copy of the edit tree
      See Also:

    • doCopy

      protected abstract TextEdit doCopy()
      Creates and returns a copy of this edit. The copy method should be implemented in a way so that the copy can executed without causing any harm to the original edit. Implementors of this method are responsible for creating deep or shallow copies of referenced object to fulfill this requirement.

      Implementers of this method should use the copy constructor Edit#Edit(Edit source) to initialize the edit part of the copy. Implementors aren't responsible to actually copy the children or to set the right parent.

      This method should not be called from outside the framework. Please use copy to create a copy of a edit tree.
      Returns:
      a copy of this edit.
      See Also:

    • postProcessCopy

      protected void postProcessCopy(TextEditCopier copier)
      This method is called on every edit of the copied tree to do some post-processing like connected an edit to a different edit in the tree.

      This default implementation does nothing

      Parameters:
      copier - the copier that manages a map between original and copied edit.
      See Also:

    • accept

      public final void accept(TextEditVisitor visitor)
      Accepts the given visitor on a visit of the current edit.
      Parameters:
      visitor - the visitor object
      Throws:
      IllegalArgumentException - if the visitor is null

    • accept0

      protected abstract void accept0(TextEditVisitor visitor)
      Accepts the given visitor on a type-specific visit of the current edit. This method must be implemented in all concrete text edits.

      General template for implementation on each concrete TextEdit class: 

       
 boolean visitChildren= visitor.visit(this);
 if (visitChildren) {
    acceptChildren(visitor);
 }
      Note that the caller (accept) takes care of invoking visitor.preVisit(this) and visitor.postVisit(this).
      Parameters:
      visitor - the visitor object

    • acceptChildren

      protected final void acceptChildren(TextEditVisitor visitor)
      Accepts the given visitor on the edits children.

      This method must be used by the concrete implementations of accept to traverse list-values properties; it encapsulates the proper handling of on-the-fly changes to the list.

      Parameters:
      visitor - the visitor object

    • apply

      public final UndoEdit apply(IDocument document, int style) throws MalformedTreeException, BadLocationException
      Applies the edit tree rooted by this edit to the given document. To check if the edit tree can be applied to the document either catch MalformedTreeException or use TextEditProcessor to execute an edit tree.
      Parameters:
      document - the document to be manipulated
      style - flags controlling the execution of the edit tree. Valid flags are: CREATE_UNDO and UPDATE_REGIONS.
      Returns:
      a undo edit, if CREATE_UNDO is specified. Otherwise null is returned.
      Throws:
      MalformedTreeException - is thrown if the tree isn't in a valid state. This exception is thrown before any edit is executed. So the document is still in its original state.
      BadLocationException - is thrown if one of the edits in the tree can't be executed. The state of the document is undefined if this exception is thrown.
      See Also:

    • apply

      public final UndoEdit apply(IDocument document) throws MalformedTreeException, BadLocationException
      Applies the edit tree rooted by this edit to the given document. This method is a convenience method for apply(document, CREATE_UNDO | UPDATE_REGIONS)
      Parameters:
      document - the document to which to apply this edit
      Returns:
      a undo edit, if CREATE_UNDO is specified. Otherwise null is returned.
      Throws:
      MalformedTreeException - is thrown if the tree isn't in a valid state. This exception is thrown before any edit is executed. So the document is still in its original state.
      BadLocationException - is thrown if one of the edits in the tree can't be executed. The state of the document is undefined if this exception is thrown.
      See Also:

    • childDocumentUpdated

      protected void childDocumentUpdated()
      Hook method called when the document updating of a child edit has been completed. When a client calls apply(IDocument) or apply(IDocument, int) this method is called getChildrenSize() times.

      May be overridden by subclasses of MultiTextEdit.

      Since:
      3.1

    • childRegionUpdated

      protected void childRegionUpdated()
      Hook method called when the region updating of a child edit has been completed. When a client calls apply(IDocument) this method is called getChildrenSize() times. When calling apply(IDocument, int) this method is called getChildrenSize() times, when the style parameter contains the UPDATE_REGIONS flag.

      May be overridden by subclasses of MultiTextEdit.

      Since:
      3.1