| /* |
| * Copyright (c) 2011, the Dart project authors. |
| * |
| * Licensed under the Eclipse Public License v1.0 (the "License"); you may not use this file except |
| * in compliance with the License. You may obtain a copy of the License at |
| * |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Unless required by applicable law or agreed to in writing, software distributed under the License |
| * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express |
| * or implied. See the License for the specific language governing permissions and limitations under |
| * the License. |
| */ |
| package com.google.dart.tools.core.buffer; |
| |
| import com.google.dart.engine.ast.CompilationUnit; |
| import com.google.dart.tools.core.model.DartModelException; |
| import com.google.dart.tools.core.model.DartModelStatusConstants; |
| |
| import org.eclipse.core.resources.IResource; |
| import org.eclipse.core.runtime.IProgressMonitor; |
| import org.eclipse.text.edits.TextEdit; |
| import org.eclipse.text.edits.UndoEdit; |
| |
| /** |
| * The interface <code>Buffer</code> defines the behavior of objects that contain the contents of a |
| * resource. It is not language-specific. The contents of the buffer might be in the process of |
| * being edited, differing from the actual contents of the underlying resource. If a buffer does not |
| * have an underlying resource, saving the buffer has no effect. Buffers can be read-only. |
| * <p> |
| * Note that Dart model operations that manipulate a <code>Buffer</code> (for example, |
| * <code>Type.createMethod(...)</code>) ensure that the same line delimiter (either |
| * <code>"\n"</code> or <code>"\r"</code> or <code>"\r\n"</code>) is used across the whole buffer. |
| * Thus these operations may change the line delimiter(s) included in the string to be append, or |
| * replaced. However, implementers of this interface should be aware that other clients of |
| * <code>Buffer</code> might not do such transformations beforehand. |
| * <p> |
| * This interface may be implemented by clients. |
| * </p> |
| * |
| * @coverage dart.tools.core.buffer |
| */ |
| public interface Buffer { |
| /** |
| * Implementors of {@link Buffer} can additionally implement {@link Buffer.TextEditCapability}. |
| * This adds the capability to apply text edits to the buffer and will be used by |
| * {@link CompilationUnit#applyTextEdit(TextEdit, IProgressMonitor)}. |
| * <p> |
| * This interface may be implemented by clients. |
| */ |
| public interface TextEditCapability { |
| /** |
| * Apply the given text edit to this underlying buffer. |
| * |
| * @param edit the edit to apply |
| * @param monitor the progress monitor to use or <code>null</code> if no progress should be |
| * reported |
| * @return the undo edit |
| * @throws DartModelException if this edit cannot be applied to the buffer. Reasons include: |
| * <ul> |
| * <li>The provided edit can not be applied as there is a problem with the text edit |
| * locations ( {@link DartModelStatusConstants#BAD_TEXT_EDIT_LOCATION})}.</li> |
| * </ul> |
| */ |
| public UndoEdit applyTextEdit(TextEdit edit, IProgressMonitor monitor) |
| throws DartModelException; |
| } |
| |
| /** |
| * Adds the given listener for changes to this buffer. Has no effect if an identical listener is |
| * already registered or if the buffer is closed. |
| * |
| * @param listener the listener of buffer changes |
| */ |
| public void addBufferChangedListener(BufferChangedListener listener); |
| |
| /** |
| * Appends the given character array to the contents of the buffer. This buffer will now have |
| * unsaved changes. Any client can append to the contents of the buffer, not just the owner of the |
| * buffer. Reports a buffer changed event. |
| * <p> |
| * Has no effect if this buffer is read-only or if the buffer is closed. |
| * |
| * @param text the given character array to append to contents of the buffer |
| */ |
| public void append(char[] text); |
| |
| /** |
| * Appends the given string to the contents of the buffer. This buffer will now have unsaved |
| * changes. Any client can append to the contents of the buffer, not just the owner of the buffer. |
| * Reports a buffer changed event. |
| * <p> |
| * Has no effect if this buffer is read-only or if the buffer is closed. |
| * |
| * @param text the <code>String</code> to append to the contents of the buffer |
| */ |
| public void append(String text); |
| |
| /** |
| * Closes the buffer. Any unsaved changes are lost. Reports a buffer changed event with a 0 offset |
| * and a 0 length. When this event is fired, the buffer should already be closed. |
| * <p> |
| * Further operations on the buffer are not allowed, except for close. If an attempt is made to |
| * close an already closed buffer, the second attempt has no effect. |
| */ |
| public void close(); |
| |
| /** |
| * Returns the character at the given position in this buffer. |
| * <p> |
| * The returned value is undefined if the buffer is closed. |
| * |
| * @param position a zero-based source offset in this buffer |
| * @return the character at the given position in this buffer |
| */ |
| public char getChar(int position); |
| |
| /** |
| * Returns the contents of this buffer as a character array, or <code>null</code> if the buffer |
| * has not been initialized. |
| * <p> |
| * Callers should make no assumption about whether the returned character array is or is not the |
| * genuine article or a copy. In other words, if the client wishes to change this array, they |
| * should make a copy. Likewise, if the client wishes to hang on to the array in its current |
| * state, they should make a copy. |
| * </p> |
| * <p> |
| * The returned value is undefined if the buffer is closed. |
| * |
| * @return the characters contained in this buffer |
| */ |
| public char[] getCharacters(); |
| |
| /** |
| * Returns the contents of this buffer as a <code>String</code>. Like all strings, the result is |
| * an immutable value object., It can also answer <code>null</code> if the buffer has not been |
| * initialized. |
| * <p> |
| * The returned value is undefined if the buffer is closed. |
| * |
| * @return the contents of this buffer as a <code>String</code> |
| */ |
| public String getContents(); |
| |
| /** |
| * Returns number of characters stored in this buffer. |
| * <p> |
| * The returned value is undefined if the buffer is closed. |
| * |
| * @return the number of characters in this buffer |
| */ |
| public int getLength(); |
| |
| /** |
| * Returns the given range of text in this buffer. |
| * <p> |
| * The returned value is undefined if the buffer is closed. |
| * |
| * @param offset the zero-based starting offset |
| * @param length the number of characters to retrieve |
| * @return the given range of text in this buffer |
| */ |
| public String getText(int offset, int length); |
| |
| /** |
| * Returns the underlying resource for which this buffer was opened, or <code>null</code> if this |
| * buffer was not opened on a resource. |
| * |
| * @return the underlying resource for this buffer, or <code>null</code> if none. |
| */ |
| public IResource getUnderlyingResource(); |
| |
| /** |
| * Returns whether this buffer has been modified since it was opened or since it was last saved. |
| * If a buffer does not have an underlying resource, this method always returns <code>true</code>. |
| * <p> |
| * NOTE: when a buffer does not have unsaved changes, the model may decide to close it to claim |
| * some memory back. If the associated element needs to be reopened later on, its buffer factory |
| * will be requested to create a new buffer. |
| * </p> |
| * |
| * @return a <code>boolean</code> indicating presence of unsaved changes (in the absence of any |
| * underlying resource, it will always return <code>true</code>). |
| */ |
| public boolean hasUnsavedChanges(); |
| |
| /** |
| * Returns whether this buffer has been closed. |
| * |
| * @return a <code>boolean</code> indicating whether this buffer is closed. |
| */ |
| public boolean isClosed(); |
| |
| /** |
| * Returns whether this buffer is read-only. |
| * |
| * @return a <code>boolean</code> indicating whether this buffer is read-only |
| */ |
| public boolean isReadOnly(); |
| |
| /** |
| * Removes the given listener from this buffer. Has no affect if an identical listener is not |
| * registered or if the buffer is closed. |
| * |
| * @param listener the listener |
| */ |
| public void removeBufferChangedListener(BufferChangedListener listener); |
| |
| /** |
| * Replaces the given range of characters in this buffer with the given text. |
| * <code>position</code> and <code>position + length</code> must be in the range [0, getLength()]. |
| * <code>length</code> must not be negative. |
| * <p> |
| * Has no effect if this buffer is read-only or if the buffer is closed. |
| * |
| * @param position the zero-based starting position of the affected text range in this buffer |
| * @param length the length of the affected text range in this buffer |
| * @param text the replacing text as a character array |
| */ |
| public void replace(int position, int length, char[] text); |
| |
| /** |
| * Replaces the given range of characters in this buffer with the given text. |
| * <code>position</code> and <code>position + length</code> must be in the range [0, getLength()]. |
| * <code>length</code> must not be negative. |
| * <p> |
| * Has no effect if this buffer is read-only or if the buffer is closed. |
| * |
| * @param position the zero-based starting position of the affected text range in this buffer |
| * @param length the length of the affected text range in this buffer |
| * @param text the replacing text as a <code>String</code> |
| */ |
| public void replace(int position, int length, String text); |
| |
| /** |
| * Saves the contents of this buffer to its underlying resource. If successful, this buffer will |
| * have no unsaved changes. The buffer is left open. Saving a buffer with no unsaved changes has |
| * no effect - the underlying resource is not changed. If the buffer does not have an underlying |
| * resource or is read-only, this has no effect. |
| * <p> |
| * The <code>force</code> parameter controls how this method deals with cases where the workbench |
| * is not completely in sync with the local file system. If <code>false</code> is specified, this |
| * method will only attempt to overwrite a corresponding file in the local file system provided it |
| * is in sync with the workbench. This option ensures there is no unintended data loss; it is the |
| * recommended setting. However, if <code>true</code> is specified, an attempt will be made to |
| * write a corresponding file in the local file system, overwriting any existing one if need be. |
| * In either case, if this method succeeds, the resource will be marked as being local (even if it |
| * wasn't before). |
| * <p> |
| * Has no effect if this buffer is read-only or if the buffer is closed. |
| * |
| * @param progress the progress monitor to notify |
| * @param force a <code> boolean </code> flag indicating how to deal with resource |
| * inconsistencies. |
| * @throws DartModelException if an error occurs writing the buffer to the underlying resource |
| * @see org.eclipse.core.resources.IFile#setContents(java.io.InputStream, boolean, boolean, |
| * org.eclipse.core.runtime.IProgressMonitor) |
| */ |
| public void save(IProgressMonitor progress, boolean force) throws DartModelException; |
| |
| /** |
| * Sets the contents of this buffer to the given character array. This buffer will now have |
| * unsaved changes. Any client can set the contents of the buffer, not just the owner of the |
| * buffer. Reports a buffer changed event. |
| * <p> |
| * Equivalent to <code>replace(0,getLength(),contents)</code>. |
| * </p> |
| * <p> |
| * Has no effect if this buffer is read-only or if the buffer is closed. |
| * |
| * @param contents the new contents of this buffer as a character array |
| */ |
| public void setContents(char[] contents); |
| |
| /** |
| * Sets the contents of this buffer to the given <code>String</code>. This buffer will now have |
| * unsaved changes. Any client can set the contents of the buffer, not just the owner of the |
| * buffer. Reports a buffer changed event. |
| * <p> |
| * Equivalent to <code>replace(0,getLength(),contents)</code>. |
| * </p> |
| * <p> |
| * Has no effect if this buffer is read-only or if the buffer is closed. |
| * |
| * @param contents the new contents of this buffer as a <code>String</code> |
| */ |
| public void setContents(String contents); |
| } |