All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.eclipse.jface.text.IDocument Maven / Gradle / Ivy

Go to download 

/*******************************************************************************
 * 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;
}




© 2015 - 2024 Weber Informatics LLC | Privacy Policy