/NRefactory/ICSharpCode.NRefactory/Editor/ITextSource.cs

  1// Copyright (c) 2010-2013 AlphaSierraPapa for the SharpDevelop Team
  2// 
  3// Permission is hereby granted, free of charge, to any person obtaining a copy of this
  4// software and associated documentation files (the "Software"), to deal in the Software
  5// without restriction, including without limitation the rights to use, copy, modify, merge,
  6// publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
  7// to whom the Software is furnished to do so, subject to the following conditions:
  8// 
  9// The above copyright notice and this permission notice shall be included in all copies or
 10// substantial portions of the Software.
 11// 
 12// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
 13// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 14// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
 15// FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 16// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 17// DEALINGS IN THE SOFTWARE.
 18
 19using System;
 20using System.Collections.Generic;
 21using System.IO;
 22
 23namespace ICSharpCode.NRefactory.Editor
 24{
 25	/// <summary>
 26	/// A read-only view on a (potentially mutable) text source.
 27	/// The IDocument interface derives from this interface.
 28	/// </summary>
 29	public interface ITextSource
 30	{
 31		/// <summary>
 32		/// Gets a version identifier for this text source.
 33		/// Returns null for unversioned text sources.
 34		/// </summary>
 35		ITextSourceVersion Version { get; }
 36		
 37		/// <summary>
 38		/// Creates an immutable snapshot of this text source.
 39		/// Unlike all other methods in this interface, this method is thread-safe.
 40		/// </summary>
 41		ITextSource CreateSnapshot();
 42		
 43		/// <summary>
 44		/// Creates an immutable snapshot of a part of this text source.
 45		/// Unlike all other methods in this interface, this method is thread-safe.
 46		/// </summary>
 47		ITextSource CreateSnapshot(int offset, int length);
 48		
 49		/// <summary>
 50		/// Creates a new TextReader to read from this text source.
 51		/// </summary>
 52		TextReader CreateReader();
 53		
 54		/// <summary>
 55		/// Creates a new TextReader to read from this text source.
 56		/// </summary>
 57		TextReader CreateReader(int offset, int length);
 58		
 59		/// <summary>
 60		/// Gets the total text length.
 61		/// </summary>
 62		/// <returns>The length of the text, in characters.</returns>
 63		/// <remarks>This is the same as Text.Length, but is more efficient because
 64		///  it doesn't require creating a String object.</remarks>
 65		int TextLength { get; }
 66		
 67		/// <summary>
 68		/// Gets the whole text as string.
 69		/// </summary>
 70		[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1721:PropertyNamesShouldNotMatchGetMethods")]
 71		string Text { get; }
 72		
 73		/// <summary>
 74		/// Gets a character at the specified position in the document.
 75		/// </summary>
 76		/// <paramref name="offset">The index of the character to get.</paramref>
 77		/// <exception cref="ArgumentOutOfRangeException">Offset is outside the valid range (0 to TextLength-1).</exception>
 78		/// <returns>The character at the specified position.</returns>
 79		/// <remarks>This is the same as Text[offset], but is more efficient because
 80		///  it doesn't require creating a String object.</remarks>
 81		char GetCharAt(int offset);
 82		
 83		/// <summary>
 84		/// Retrieves the text for a portion of the document.
 85		/// </summary>
 86		/// <exception cref="ArgumentOutOfRangeException">offset or length is outside the valid range.</exception>
 87		/// <remarks>This is the same as Text.Substring, but is more efficient because
 88		///  it doesn't require creating a String object for the whole document.</remarks>
 89		string GetText(int offset, int length);
 90		
 91		/// <summary>
 92		/// Retrieves the text for a portion of the document.
 93		/// </summary>
 94		/// <exception cref="ArgumentOutOfRangeException">offset or length is outside the valid range.</exception>
 95		string GetText(ISegment segment);
 96		
 97		/// <summary>
 98		/// Writes the text from this document into the TextWriter.
 99		/// </summary>
100		void WriteTextTo(TextWriter writer);
101		
102		/// <summary>
103		/// Writes the text from this document into the TextWriter.
104		/// </summary>
105		void WriteTextTo(TextWriter writer, int offset, int length);
106		
107		/// <summary>
108		/// Gets the index of the first occurrence of the character in the specified array.
109		/// </summary>
110		/// <param name="c">Character to search for</param>
111		/// <param name="startIndex">Start index of the area to search.</param>
112		/// <param name="count">Length of the area to search.</param>
113		/// <returns>The first index where the character was found; or -1 if no occurrence was found.</returns>
114		int IndexOf(char c, int startIndex, int count);
115		
116		/// <summary>
117		/// Gets the index of the first occurrence of any character in the specified array.
118		/// </summary>
119		/// <param name="anyOf">Characters to search for</param>
120		/// <param name="startIndex">Start index of the area to search.</param>
121		/// <param name="count">Length of the area to search.</param>
122		/// <returns>The first index where any character was found; or -1 if no occurrence was found.</returns>
123		int IndexOfAny(char[] anyOf, int startIndex, int count);
124		
125		/// <summary>
126		/// Gets the index of the first occurrence of the specified search text in this text source.
127		/// </summary>
128		/// <param name="searchText">The search text</param>
129		/// <param name="startIndex">Start index of the area to search.</param>
130		/// <param name="count">Length of the area to search.</param>
131		/// <param name="comparisonType">String comparison to use.</param>
132		/// <returns>The first index where the search term was found; or -1 if no occurrence was found.</returns>
133		int IndexOf(string searchText, int startIndex, int count, StringComparison comparisonType);
134		
135		/// <summary>
136		/// Gets the index of the last occurrence of the specified character in this text source.
137		/// </summary>
138		/// <param name="c">The search character</param>
139		/// <param name="startIndex">Start index of the area to search.</param>
140		/// <param name="count">Length of the area to search.</param>
141		/// <returns>The last index where the search term was found; or -1 if no occurrence was found.</returns>
142		/// <remarks>The search proceeds backwards from (startIndex+count) to startIndex.
143		/// This is different than the meaning of the parameters on string.LastIndexOf!</remarks>
144		int LastIndexOf(char c, int startIndex, int count);
145		
146		/// <summary>
147		/// Gets the index of the last occurrence of the specified search text in this text source.
148		/// </summary>
149		/// <param name="searchText">The search text</param>
150		/// <param name="startIndex">Start index of the area to search.</param>
151		/// <param name="count">Length of the area to search.</param>
152		/// <param name="comparisonType">String comparison to use.</param>
153		/// <returns>The last index where the search term was found; or -1 if no occurrence was found.</returns>
154		/// <remarks>The search proceeds backwards from (startIndex+count) to startIndex.
155		/// This is different than the meaning of the parameters on string.LastIndexOf!</remarks>
156		int LastIndexOf(string searchText, int startIndex, int count, StringComparison comparisonType);
157		
158		/* What about:
159		void Insert (int offset, string value);
160		void Remove (int offset, int count);
161		void Remove (ISegment segment);
162		
163		void Replace (int offset, int count, string value);
164		
165		Or more search operations:
166		
167		IEnumerable<int> SearchForward (string pattern, int startIndex);
168		IEnumerable<int> SearchForwardIgnoreCase (string pattern, int startIndex);
169		
170		IEnumerable<int> SearchBackward (string pattern, int startIndex);
171		IEnumerable<int> SearchBackwardIgnoreCase (string pattern, int startIndex);
172		 */
173	}
174	
175	/// <summary>
176	/// Represents a version identifier for a text source.
177	/// </summary>
178	/// <remarks>
179	/// Verions can be used to efficiently detect whether a document has changed and needs reparsing;
180	/// or even to implement incremental parsers.
181	/// It is a separate class from ITextSource to allow the GC to collect the text source while
182	/// the version checkpoint is still in use.
183	/// </remarks>
184	public interface ITextSourceVersion
185	{
186		/// <summary>
187		/// Gets whether this checkpoint belongs to the same document as the other checkpoint.
188		/// </summary>
189		/// <remarks>
190		/// Returns false when given <c>null</c>.
191		/// </remarks>
192		bool BelongsToSameDocumentAs(ITextSourceVersion other);
193		
194		/// <summary>
195		/// Compares the age of this checkpoint to the other checkpoint.
196		/// </summary>
197		/// <remarks>This method is thread-safe.</remarks>
198		/// <exception cref="ArgumentException">Raised if 'other' belongs to a different document than this version.</exception>
199		/// <returns>-1 if this version is older than <paramref name="other"/>.
200		/// 0 if <c>this</c> version instance represents the same version as <paramref name="other"/>.
201		/// 1 if this version is newer than <paramref name="other"/>.</returns>
202		int CompareAge(ITextSourceVersion other);
203		
204		/// <summary>
205		/// Gets the changes from this checkpoint to the other checkpoint.
206		/// If 'other' is older than this checkpoint, reverse changes are calculated.
207		/// </summary>
208		/// <remarks>This method is thread-safe.</remarks>
209		/// <exception cref="ArgumentException">Raised if 'other' belongs to a different document than this checkpoint.</exception>
210		IEnumerable<TextChangeEventArgs> GetChangesTo(ITextSourceVersion other);
211		
212		/// <summary>
213		/// Calculates where the offset has moved in the other buffer version.
214		/// </summary>
215		/// <exception cref="ArgumentException">Raised if 'other' belongs to a different document than this checkpoint.</exception>
216		int MoveOffsetTo(ITextSourceVersion other, int oldOffset, AnchorMovementType movement = AnchorMovementType.Default);
217	}
218}