org.eclipse.jface.text.IDocument Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2000, 2016 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jface.text;
/**
* An IDocument represents text providing support for
*
* - text manipulation
*
- positions
*
- partitions
*
- line information
*
- document change listeners
*
- document partition change listeners
*
*
* A document allows to set its content and to manipulate it. For manipulation
* a document provides the replace method which substitutes a given
* string for a specified text range in the document. On each document change, all
* registered document listeners are informed exactly once.
*
* Positions are stickers to the document's text that are updated when the
* document is changed. Positions are updated by {@link org.eclipse.jface.text.IPositionUpdater}s. Position
* updaters are managed as a list. The list defines the sequence in which position
* updaters are invoked. This way, position updaters may rely on each other.
* Positions are grouped into categories. A category is a ordered list of positions.
* the document defines the order of position in a category based on the position's offset
* based on the implementation of the method computeIndexInCategory.
* Each document must support a default position category whose name is specified by this
* interface.
*
* A document can be considered consisting of a sequence of not overlapping partitions.
* A partition is defined by its offset, its length, and its type. Partitions are
* updated on every document manipulation and ensured to be up-to-date when the document
* listeners are informed. A document uses an IDocumentPartitioner to
* manage its partitions. A document may be unpartitioned which happens when there is no
* partitioner. In this case, the document is considered as one single partition of a
* default type. The default type is specified by this interface. If a document change
* changes the document's partitioning all registered partitioning listeners are
* informed exactly once. The extension interface {@link org.eclipse.jface.text.IDocumentExtension3}
* introduced in version 3.0 extends the concept of partitions and allows a document to
* not only manage one but multiple partitioning. Each partitioning has an id which must
* be used to refer to a particular partitioning.
*
* An IDocument provides methods to map line numbers and character
* positions onto each other based on the document's line delimiters. When moving text
* between documents using different line delimiters, the text must be converted to
* use the target document's line delimiters.
*
* An IDocument does not care about mixed line delimiters. Clients who
* want to ensure a single line delimiter in their document should use the line
* delimiter returned by {@link org.eclipse.jface.text.TextUtilities#getDefaultLineDelimiter(IDocument)}.
*
* IDocument throws BadLocationException if the parameters of
* queries or manipulation requests are not inside the bounds of the document. The purpose
* of this style of exception handling is
*
* - prepare document for multi-thread access
*
- allow clients to implement backtracking recovery methods
*
- prevent clients from up-front contract checking when dealing with documents.
*
*
* A document support for searching has deprecated since version 3.0. The recommended way
* for searching is to use a {@link org.eclipse.jface.text.FindReplaceDocumentAdapter}.
*
* In order to provide backward compatibility for clients of IDocument, extension
* interfaces are used to provide a means of evolution. The following extension interfaces
* exist:
*
* - {@link org.eclipse.jface.text.IDocumentExtension} since version 2.0 introducing the concept
* of post notification replaces in order to allow document listeners to manipulate the document
* while receiving a document change notification
* - {@link org.eclipse.jface.text.IDocumentExtension2} since version 2.1 introducing configuration
* methods for post notification replaces and document change notification.
* - {@link org.eclipse.jface.text.IDocumentExtension3} since version 3.0 replacing the original
* partitioning concept by allowing multiple partitionings at the same time and introducing zero-
* length partitions in conjunction with the distinction between open and closed partitions.
* - {@link org.eclipse.jface.text.IDocumentExtension4} since version 3.1 introducing the
* concept of rewrite sessions. A rewrite session is a sequence of document replace operations
* that form a semantic unit. It also introduces a modification stamp and the ability to
* set the initial line delimiter and to query the default line delimiter.
*
*
* Clients may implement this interface and its extension interfaces or use the default
* implementation provided by AbstractDocument and Document.
*
* @see org.eclipse.jface.text.IDocumentExtension
* @see org.eclipse.jface.text.IDocumentExtension2
* @see org.eclipse.jface.text.IDocumentExtension3
* @see org.eclipse.jface.text.IDocumentExtension4
* @see org.eclipse.jface.text.Position
* @see org.eclipse.jface.text.IPositionUpdater
* @see org.eclipse.jface.text.IDocumentPartitioner
* @see org.eclipse.jface.text.ILineTracker
* @see org.eclipse.jface.text.IDocumentListener
* @see org.eclipse.jface.text.IDocumentPartitioningListener
*/
public interface IDocument {
/**
* The identifier of the default position category.
*/
final static String DEFAULT_CATEGORY= "__dflt_position_category"; //$NON-NLS-1$
/**
* The identifier of the default partition content type.
*/
final static String DEFAULT_CONTENT_TYPE= "__dftl_partition_content_type"; //$NON-NLS-1$
/* --------------- text access and manipulation --------------------------- */
/**
* Returns the character at the given document offset in this document.
*
* @param offset a document offset
* @return the character at the offset
* @exception BadLocationException if the offset is invalid in this document
*/
char getChar(int offset) throws BadLocationException;
/**
* Returns the number of characters in this document.
*
* @return the number of characters in this document
*/
int getLength();
/**
* Returns this document's complete text.
*
* @return the document's complete text
*/
String get();
/**
* Returns this document's text for the specified range.
*
* @param offset the document offset
* @param length the length of the specified range
* @return the document's text for the specified range
* @exception BadLocationException if the range is invalid in this document
*/
String get(int offset, int length) throws BadLocationException;
/**
* Replaces the content of the document with the given text.
* Sends a DocumentEvent to all registered IDocumentListener.
* This method is a convenience method for replace(0, getLength(), text).
*
* @param text the new content of the document
*
* @see DocumentEvent
* @see IDocumentListener
*/
void set(String text);
/**
* Substitutes the given text for the specified document range.
* Sends a DocumentEvent to all registered IDocumentListener.
*
* @param offset the document offset
* @param length the length of the specified range
* @param text the substitution text
* @exception BadLocationException if the offset is invalid in this document
*
* @see DocumentEvent
* @see IDocumentListener
*/
void replace(int offset, int length, String text) throws BadLocationException;
/**
* Registers the document listener with the document. After registration
* the IDocumentListener is informed about each change of this document.
* If the listener is already registered nothing happens.
* An IDocumentListener may call back to this method
* when being inside a document notification.
*
* @param listener the listener to be registered
*/
void addDocumentListener(IDocumentListener listener);
/**
* Removes the listener from the document's list of document listeners.
* If the listener is not registered with the document nothing happens.
* An IDocumentListener may call back to this method
* when being inside a document notification.
*
* @param listener the listener to be removed
*/
void removeDocumentListener(IDocumentListener listener);
/**
* Adds the given document listener as one which is notified before
* those document listeners added with addDocumentListener
* are notified. If the given listener is also registered using
* addDocumentListener it will be notified twice.
* If the listener is already registered nothing happens.
*
* This method is not for public use.
*
* @param documentAdapter the listener to be added as pre-notified document listener
*
* @see #removePrenotifiedDocumentListener(IDocumentListener)
*/
void addPrenotifiedDocumentListener(IDocumentListener documentAdapter);
/**
* Removes the given document listener from the document's list of
* pre-notified document listeners. If the listener is not registered
* with the document nothing happens.
*
* This method is not for public use.
*
* @param documentAdapter the listener to be removed
*
* @see #addPrenotifiedDocumentListener(IDocumentListener)
*/
void removePrenotifiedDocumentListener(IDocumentListener documentAdapter);
/* -------------------------- positions ----------------------------------- */
/**
* Adds a new position category to the document. If the position category
* already exists nothing happens.
*
* @param category the category to be added
*/
void addPositionCategory(String category);
/**
* Deletes the position category from the document. All positions
* in this category are thus deleted as well.
*
* @param category the category to be removed
* @exception BadPositionCategoryException if category is undefined in this document
*/
void removePositionCategory(String category) throws BadPositionCategoryException;
/**
* Returns all position categories of this document. This
* includes the default position category.
*
* @return the document's position categories
*/
String[] getPositionCategories();
/**
* Checks the presence of the specified position category.
*
* @param category the category to check
* @return true if category is defined
*/
boolean containsPositionCategory(String category);
/**
* Adds the position to the document's default position category.
* This is a convenience method for addPosition(DEFAULT_CATEGORY, position).
*
* @param position the position to be added
* @exception BadLocationException if position describes an invalid range in this document
*/
void addPosition(Position position) throws BadLocationException;
/**
* Removes the given position from the document's default position category.
* This is a convenience method for removePosition(DEFAULT_CATEGORY, position).
*
* @param position the position to be removed
*/
void removePosition(Position position);
/**
* Adds the position to the specified position category of the document.
* Positions may be added multiple times. The order of the category is
* maintained.
*
* Note: The position is only updated on each change
* applied to the document if a {@link IPositionUpdater} has been
* registered that handles the given category.
*
*
* @param category the category to which to add
* @param position the position to be added
* @throws BadLocationException if position describes an invalid range in this document
* @throws BadPositionCategoryException if the category is undefined in this document
*/
void addPosition(String category, Position position) throws BadLocationException, BadPositionCategoryException;
/**
* Removes the given position from the specified position category.
* If the position is not part of the specified category nothing happens.
* If the position has been added multiple times, only the first occurrence is deleted.
*
* @param category the category from which to delete
* @param position the position to be deleted
* @exception BadPositionCategoryException if category is undefined in this document
*/
void removePosition(String category, Position position) throws BadPositionCategoryException;
/**
* Returns all positions of the given position category.
* The positions are ordered according to the category's order.
* Manipulating this list does not affect the document, but manipulating the
* position does affect the document.
*
* @param category the category
* @return the list of all positions
* @exception BadPositionCategoryException if category is undefined in this document
*/
Position[] getPositions(String category) throws BadPositionCategoryException;
/**
* Determines whether a position described by the parameters is managed by this document.
*
* @param category the category to check
* @param offset the offset of the position to find
* @param length the length of the position to find
* @return true if position is found
*/
boolean containsPosition(String category, int offset, int length);
/**
* Computes the index at which a Position with the
* specified offset would be inserted into the given category. As the
* ordering inside a category only depends on the offset, the index must be
* chosen to be the first of all positions with the same offset.
*
* @param category the category in which would be added
* @param offset the position offset to be considered
* @return the index into the category
* @exception BadLocationException if offset is invalid in this document
* @exception BadPositionCategoryException if category is undefined in this document
*/
int computeIndexInCategory(String category, int offset) throws BadLocationException, BadPositionCategoryException;
/**
* Appends a new position updater to the document's list of position updaters.
* Position updaters may be added multiple times.
* An IPositionUpdater may call back to this method
* when being inside a document notification.
*
* @param updater the updater to be added
*/
void addPositionUpdater(IPositionUpdater updater);
/**
* Removes the position updater from the document's list of position updaters.
* If the position updater has multiple occurrences only the first occurrence is
* removed. If the position updater is not registered with this document, nothing
* happens.
* An IPositionUpdater may call back to this method
* when being inside a document notification.
*
* @param updater the updater to be removed
*/
void removePositionUpdater(IPositionUpdater updater);
/**
* Inserts the position updater at the specified index in the document's
* list of position updaters. Positions updaters may be inserted multiple times.
* An IPositionUpdater may call back to this method
* when being inside a document notification.
*
* @param updater the updater to be inserted
* @param index the index in the document's updater list
*/
void insertPositionUpdater(IPositionUpdater updater, int index);
/**
* Returns the list of position updaters attached to the document.
*
* @return the list of position updaters
*/
IPositionUpdater[] getPositionUpdaters();
/* -------------------------- partitions ---------------------------------- */
/**
* Returns the set of legal content types of document partitions.
* This set can be empty. The set can contain more content types than
* contained by the result of getPartitioning(0, getLength()).
*
* Use {@link IDocumentExtension3#getLegalContentTypes(String)} when the document
* supports multiple partitionings. In that case this method is equivalent to:
*
* IDocumentExtension3 extension= (IDocumentExtension3) document;
* return extension.getLegalContentTypes(IDocumentExtension3.DEFAULT_PARTITIONING);
*
*
* @return the set of legal content types
*/
String[] getLegalContentTypes();
/**
* Returns the type of the document partition containing the given offset.
* This is a convenience method for getPartition(offset).getType().
*
* Use {@link IDocumentExtension3#getContentType(String, int, boolean)} when
* the document supports multiple partitionings. In that case this method is
* equivalent to:
*
* IDocumentExtension3 extension= (IDocumentExtension3) document;
* return extension.getContentType(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false);
*
*
* @param offset the document offset
* @return the partition type
* @exception BadLocationException if offset is invalid in this document
*/
String getContentType(int offset) throws BadLocationException;
/**
* Returns the document partition in which the position is located.
*
* Use {@link IDocumentExtension3#getPartition(String, int, boolean)} when
* the document supports multiple partitionings. In that case this method is
* equivalent:
*
* IDocumentExtension3 extension= (IDocumentExtension3) document;
* return extension.getPartition(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false);
*
*
* @param offset the document offset
* @return a specification of the partition
* @exception BadLocationException if offset is invalid in this document
*/
ITypedRegion getPartition(int offset) throws BadLocationException;
/**
* Computes the partitioning of the given document range using the
* document's partitioner.
*
* Use {@link IDocumentExtension3#computePartitioning(String, int, int, boolean)} when
* the document supports multiple partitionings. In that case this method is
* equivalent:
*
* IDocumentExtension3 extension= (IDocumentExtension3) document;
* return extension.computePartitioning(IDocumentExtension3.DEFAULT_PARTITIONING, offset, length, false);
*
*
* @param offset the document offset at which the range starts
* @param length the length of the document range
* @return a specification of the range's partitioning
* @exception BadLocationException if the range is invalid in this document
*/
ITypedRegion[] computePartitioning(int offset, int length) throws BadLocationException;
/**
* Registers the document partitioning listener with the document. After registration
* the document partitioning listener is informed about each partition change
* cause by a document manipulation or by changing the document's partitioner.
* If a document partitioning listener is also
* a document listener, the following notification sequence is guaranteed if a
* document manipulation changes the document partitioning:
*
* - listener.documentAboutToBeChanged(DocumentEvent);
*
- listener.documentPartitioningChanged();
*
- listener.documentChanged(DocumentEvent);
*
* If the listener is already registered nothing happens.
* An IDocumentPartitioningListener may call back to this method
* when being inside a document notification.
*
* @param listener the listener to be added
*/
void addDocumentPartitioningListener(IDocumentPartitioningListener listener);
/**
* Removes the listener from this document's list of document partitioning
* listeners. If the listener is not registered with the document nothing
* happens.
* An IDocumentPartitioningListener may call back to this method
* when being inside a document notification.
*
* @param listener the listener to be removed
*/
void removeDocumentPartitioningListener(IDocumentPartitioningListener listener);
/**
* Sets this document's partitioner. The caller of this method is responsible for
* disconnecting the document's old partitioner from the document and to
* connect the new partitioner to the document. Informs all document partitioning
* listeners about this change.
*
* Use {@link IDocumentExtension3#setDocumentPartitioner(String, IDocumentPartitioner)} when
* the document supports multiple partitionings. In that case this method is equivalent to:
*
* IDocumentExtension3 extension= (IDocumentExtension3) document;
* extension.setDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING, partitioner);
*
*
* @param partitioner the document's new partitioner
*
* @see IDocumentPartitioningListener
*/
void setDocumentPartitioner(IDocumentPartitioner partitioner);
/**
* Returns this document's partitioner.
*
* Use {@link IDocumentExtension3#getDocumentPartitioner(String)} when
* the document supports multiple partitionings. In that case this method is
* equivalent to:
*
* IDocumentExtension3 extension= (IDocumentExtension3) document;
* return extension.getDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING);
*
*
* @return this document's partitioner
*/
IDocumentPartitioner getDocumentPartitioner();
/* ---------------------- line information -------------------------------- */
/**
* Returns the length of the given line including the line's delimiter.
*
* @param line the line of interest
* @return the length of the line
* @exception BadLocationException if the line number is invalid in this document
*/
int getLineLength(int line) throws BadLocationException;
/**
* Returns the number of the line at which the character of the specified position is located.
* The first line has the line number 0. A new line starts directly after a line
* delimiter. (offset == document length) is a valid argument although there is no
* corresponding character.
*
* @param offset the document offset
* @return the number of the line
* @exception BadLocationException if the offset is invalid in this document
*/
int getLineOfOffset(int offset) throws BadLocationException;
/**
* Determines the offset of the first character of the given line.
*
* @param line the line of interest
* @return the document offset
* @exception BadLocationException if the line number is invalid in this document
*/
int getLineOffset(int line) throws BadLocationException;
/**
* Returns a description of the specified line. The line is described by its
* offset and its length excluding the line's delimiter.
*
* @param line the line of interest
* @return a line description
* @exception BadLocationException if the line number is invalid in this document
*/
IRegion getLineInformation(int line) throws BadLocationException;
/**
* Returns a description of the line at the given offset.
* The description contains the offset and the length of the line
* excluding the line's delimiter.
*
* @param offset the offset whose line should be described
* @return a region describing the line
* @exception BadLocationException if offset is invalid in this document
*/
IRegion getLineInformationOfOffset(int offset) throws BadLocationException;
/**
* Returns the number of lines in this document.
*
* Note that a document always has at least one line.
*
*
* @return the number of lines in this document.
*/
int getNumberOfLines();
/**
* Returns the number of lines which are occupied by a given text range.
*
* @param offset the offset of the specified text range
* @param length the length of the specified text range
* @return the number of lines occupied by the specified range
* @exception BadLocationException if specified range is invalid in this tracker
*/
int getNumberOfLines(int offset, int length) throws BadLocationException;
/**
* Computes the number of lines in the given text. For a given
* implementer of this interface this method returns the same
* result as set(text); getNumberOfLines().
*
* @param text the text whose number of lines should be computed
* @return the number of lines in the given text
*/
int computeNumberOfLines(String text);
/* ------------------ line delimiter conversion --------------------------- */
/**
* Returns the document's legal line delimiters.
*
* @return the document's legal line delimiters
*/
String[] getLegalLineDelimiters();
/**
* Returns the line delimiter of that line or null if the
* line is not closed with a line delimiter.
*
* @param line the line of interest
* @return the line's delimiter or null if line does not have a delimiter
* @exception BadLocationException if the line number is invalid in this document
*/
String getLineDelimiter(int line) throws BadLocationException;
/* ---------------------------- search ------------------------------------ */
/**
* Returns the offset of a given search string in the document based on a set of search criteria.
*
* @param startOffset document offset at which search starts
* @param findString the string to find
* @param forwardSearch the search direction
* @param caseSensitive indicates whether lower and upper case should be distinguished
* @param wholeWord indicates whether the findString should be limited by white spaces as
* defined by Character.isWhiteSpace
* @return the offset of the first occurrence of findString based on the parameters or -1 if no match is found
* @exception BadLocationException if startOffset is an invalid document offset
* @deprecated as of 3.0 search is provided by {@link FindReplaceDocumentAdapter}
*/
@Deprecated
int search(int startOffset, String findString, boolean forwardSearch, boolean caseSensitive, boolean wholeWord) throws BadLocationException;
}