All Superinterfaces:

AutoCloseable, Closeable
```
public interface TextDocument
extends Closeable
```
Represents a textual document, providing methods to edit it incrementally and address regions of text. A text document delegates IO operations to a TextFile. It reflects some in-memory snapshot of the file, though the file may still be edited externally.
TextDocument is meant to replace CPD's SourceCode and PMD's DataSource, though the abstraction level of DataSource is the TextFile.
Note that the backing TextFile is purposefully not accessible from a text document. Exposing it here could lead to files being written to from within rules, while we want to eventually build an API that allows file edition based on AST manipulation.
Coordinates in TextDocument
This interface is an abstraction over a piece of text, which might not correspond to the backing source file. This allows the document to be a view on a piece of a larger document (eg, a Javadoc comment, or a string in which a language is injected). Another use case is to perform escape translation, while preserving the line breaks of the original source.
This complicates addressing within a text document. To explain it, consider that there is always *one* text document that corresponds to the backing text file, which we call the root text document. Logical documents built on top of it are called views. Text documents use offsets and TextRegion to address their contents. These are always relative to the text of the document. Line and column information are provided by FileLocation (see toLocation(TextRegion)), and are always absolute (ie, represent actual source lines in the file).
For instance, say you have the following file (and root text document):
```
 l1
 l2 (* comment *)
 l3
 
```
and you create a view for just the section (* comment *). Then, that view's offset 0 (start of the document) will map to the ( character, while the root document's offset 0 maps to the start of l1. When calling toLocation(caretAt(0)), the view will however return line 2, column 4, ie, a line/column that can be found when inspecting the file.
To reduce the potential for mistakes, views do not provide access to their underlying text document. That way, nodes only have access to a single document, and their offsets can be assumed to be in the coordinate system of that document.
This interface does not provide a way to obtain line/column coordinates that are relative to a view's coordinate system. This would complicate the construction of views significantly.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`void`	`close()`	Closing a document closes the underlying `TextFile`.
`static TextDocument`	`create(TextFile textFile)`	Create a new text document for the given text file.
`TextRegion`	`createLineRange(int startLineInclusive, int endLineInclusive)`	Returns a region that spans the text of all the given lines.
`long`	`getCheckSum()`	Returns a checksum for the contents of the file.
`String`	`getDisplayName()`	Returns `TextFile.getDisplayName()` for the text file backing this document.
`default TextRegion`	`getEntireRegion()`	Returns a text region that corresponds to the entire document, in the coordinate system of this document.
`LanguageVersion`	`getLanguageVersion()`	Returns the language version that should be used to parse this file.
`default int`	`getLength()`	Returns the length in characters of the text.
`String`	`getPathId()`	Returns `TextFile.getPathId()` for the text file backing this document.
`Chars`	`getText()`	Returns the current text of this document.
`default TextPos2d`	`lineColumnAtOffset(int offset)`	Returns the line and column at the given offset (inclusive).
`TextPos2d`	`lineColumnAtOffset(int offset, boolean inclusive)`	Returns the line and column at the given offset.
`default Reader`	`newReader()`	Returns a reader over the text of this document.
`static TextDocument`	`readOnlyString(@NonNull CharSequence source, @NonNull String filename, @NonNull LanguageVersion lv)`	Returns a read-only document for the given text.
`static TextDocument`	`readOnlyString(CharSequence source, LanguageVersion lv)`	Returns a read-only document for the given text.
`Chars`	`sliceOriginalText(TextRegion region)`	Returns a slice of the original text.
`default Chars`	`sliceTranslatedText(TextRegion region)`	Returns a slice of the source text.
`FileLocation`	`toLocation(TextRegion region)`	Turn a text region into a `FileLocation`.

- Method Detail
  - getLanguageVersion
```
LanguageVersion getLanguageVersion()
```
    Returns the language version that should be used to parse this file.
  - getPathId
```
String getPathId()
```
    Returns TextFile.getPathId() for the text file backing this document.
  - getDisplayName
```
String getDisplayName()
```
    Returns TextFile.getDisplayName() for the text file backing this document.
  - getText
```
Chars getText()
```
    Returns the current text of this document. Note that this doesn't take external modifications to the TextFile into account.
    Line endings are normalized to TextFileContent.NORMALIZED_LINE_TERM.
    
    See Also:
    
    TextFileContent.getNormalizedText()
  - sliceOriginalText
```
Chars sliceOriginalText(TextRegion region)
```
    Returns a slice of the original text. Note that this is not the same as getText().subsequence, as if this document has translated escapes, the returned char slice will contain the untranslated escapes, whereas getText() would return the translated characters.
    
    Parameters:
    
    region - A region, in the coordinate system of this document
    
    Returns:
    
    The slice of the original text that corresponds to the region
    
    Throws:
    
    IndexOutOfBoundsException - If the region is not a valid range
  - sliceTranslatedText
```
default Chars sliceTranslatedText(TextRegion region)
```
    Returns a slice of the source text. This is always equal to getText().slice(region), as the text is the translated text.
    
    Parameters:
    
    region - A region, in the coordinate system of this document
    
    Returns:
    
    The slice of the original text that corresponds to the region
    
    Throws:
    
    IndexOutOfBoundsException - If the region is not a valid range
  - getCheckSum
```
long getCheckSum()
```
    Returns a checksum for the contents of the file.
    
    See Also:
    
    TextFileContent.getCheckSum()
  - newReader
```
default Reader newReader()
```
    Returns a reader over the text of this document.
  - getLength
```
default int getLength()
```
    Returns the length in characters of the text.
  - getEntireRegion
```
default TextRegion getEntireRegion()
```
    Returns a text region that corresponds to the entire document, in the coordinate system of this document.
  - createLineRange
```
TextRegion createLineRange(int startLineInclusive,
                           int endLineInclusive)
```
    Returns a region that spans the text of all the given lines. This is intended to provide a replacement for SourceCode.getSlice(int, int).
    Note that, as line numbers may only be obtained from toLocation(TextRegion), and hence are line numbers of the original source, both parameters must be line numbers of the source text and not the translated text that this represents.
    
    Parameters:
    
    startLineInclusive - Inclusive start line number (1-based)
    
    endLineInclusive - Inclusive end line number (1-based)
    
    Throws:
    
    IndexOutOfBoundsException - If the arguments do not identify a valid region in the source document
  - toLocation
```
FileLocation toLocation(TextRegion region)
```
    Turn a text region into a FileLocation. This computes the line/column information for both start and end offset of the region.
    
    Parameters:
    
    region - A region, in the coordinate system of this document
    
    Returns:
    
    A new file position, with absolute coordinates
    
    Throws:
    
    IndexOutOfBoundsException - If the argument is not a valid region in this document
  - lineColumnAtOffset
```
default TextPos2d lineColumnAtOffset(int offset)
```
    Returns the line and column at the given offset (inclusive). Note that the line/column cannot be converted back. They are absolute in the coordinate system of the original document.
    
    Parameters:
    
    offset - A source offset (0-based), can range in [0, length].
    
    Throws:
    
    IndexOutOfBoundsException - if the offset is out of bounds
  - lineColumnAtOffset
```
TextPos2d lineColumnAtOffset(int offset,
                             boolean inclusive)
```
    Returns the line and column at the given offset. Both the input offset and the output range are in the coordinates of this document.
    
    Parameters:
    
    offset - A source offset (0-based), can range in [0, length].
    
    inclusive - If the offset falls right after a line terminator, two behaviours are possible. If the parameter is true, choose the position at the start of the next line, otherwise choose the position at the end of the line.
    
    Returns:
    
    A position, in the coordinate system of the root document
    
    Throws:
    
    IndexOutOfBoundsException - if the offset is out of bounds
  - close
```
void close()
    throws IOException
```
    Closing a document closes the underlying TextFile. New editors cannot be produced after that, and the document otherwise remains in its current state.
    
    Specified by:
    
    close in interface AutoCloseable
    
    Specified by:
    
    close in interface Closeable
    
    Throws:
    
    IOException - If TextFile.close() throws
    
    IllegalStateException - If an editor is currently open. In this case the editor is rendered ineffective before the exception is thrown. This indicates a programming mistake.
  - create
```
static TextDocument create(TextFile textFile)
                    throws IOException
```
    Create a new text document for the given text file. The document's coordinate system is the same as the original text file.
    
    Parameters:
    
    textFile - A text file
    
    Returns:
    
    A new text document
    
    Throws:
    
    IOException - If the file cannot be read (TextFile.readContents())
    
    NullPointerException - If the parameter is null
  - readOnlyString
```
static TextDocument readOnlyString(CharSequence source,
                                   LanguageVersion lv)
```
    Returns a read-only document for the given text.
    
    See Also:
    
    TextFile.forCharSeq(CharSequence, String, LanguageVersion)
  - readOnlyString
```
static TextDocument readOnlyString(@NonNull CharSequence source,
                                   @NonNull String filename,
                                   @NonNull LanguageVersion lv)
```
    Returns a read-only document for the given text. This works as if by calling create(TextFile) on a textfile produced by forString, but doesn't throw IOException, as such text files will not throw.
    
    See Also:
    
    TextFile.forCharSeq(CharSequence, String, LanguageVersion)

Interface TextDocument

Coordinates in TextDocument

Method Summary

Method Detail

getLanguageVersion

getPathId

getDisplayName

getText

sliceOriginalText

sliceTranslatedText

getCheckSum

newReader

getLength

getEntireRegion

createLineRange

toLocation

lineColumnAtOffset

lineColumnAtOffset

close

create

readOnlyString

readOnlyString