# Document

Contains the text of the document. Document can be attached to several `EditSession`s.

At its core, `Document`s are just an array of strings, with each row in the document matching up to the array index.

### Constructors

- - new Document(String | Array text)

Creates a new `Document`. If `text` is included, the `Document` contains those strings; otherwise, it's empty.

Creates a new `Document`. If `text` is included, the `Document` contains those strings; otherwise, it's empty.

#### Arguments

text | String | Array | Required. The starting text

### Events

- - Document.on("change", function( Object e))

Fires whenever the document changes.

Fires whenever the document changes.

Several methods trigger different `"change"` events. Below is a list of each action type, followed by each property that's also available:

- `"insertLines"` (emitted by `Document.insertLines()`)
- `range`: the `Range` of the change within the document
- `lines`: the lines in the document that are changing
- `"insertText"` (emitted by `Document.insertNewLine()`)
- `range`: the `Range` of the change within the document
- `text`: the text that's being added
- `"removeLines"` (emitted by `Document.insertLines()`)
- `range`: the `Range` of the change within the document
- `lines`: the lines in the document that were removed
- `nl`: the new line character (as defined by `Document.getNewLineCharacter()`)
- `"removeText"` (emitted by `Document.removeInLine()` and `Document.removeNewLine()`)
- `range`: the `Range` of the change within the document
- `text`: the text that's being removed

#### Arguments

e | Object | Required. Contains at least one property called `"action"`. `"action"` indicates the action that triggered the change. Each action also has a set of additional properties.

### Methods

- - Document.applyDeltas(Object deltas)

Applies all the changes previously accumulated. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.

Applies all the changes previously accumulated. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.

#### Arguments

deltas | Object | Required.

- - Document.createAnchor(Number row, Number column)

Creates a new `Anchor` to define a floating point in the document.

Creates a new `Anchor` to define a floating point in the document.

#### Arguments

row | Number | Required. The row number to use
column | Number | Required. The column number to use

- - Document.getAllLines()

Returns all lines in the document as string array.

Returns all lines in the document as string array. Warning: The caller should not modify this array!

- - Document.getLength()

Returns the number of rows in the document.

Returns the number of rows in the document.

- - Document.getLine(Number row)

Returns a verbatim copy of the given line as it is in the document

Returns a verbatim copy of the given line as it is in the document

#### Arguments

row | Number | Required. The row index to retrieve

- - Document.getLines(Number firstRow, Number lastRow)

Returns an array of strings of the rows between `firstRow` and `lastRow`. This function is inclusive of `lastRow`.

Returns an array of strings of the rows between `firstRow` and `lastRow`. This function is inclusive of `lastRow`.

#### Arguments

firstRow | Number | Required. The first row index to retrieve
lastRow | Number | Required. The final row index to retrieve

- - Document.getNewLineCharacter()
  - - String

Returns the newline character that's being used, depending on the value of `newLineMode`.

Returns the newline character that's being used, depending on the value of `newLineMode`.

- - Document.getNewLineMode()
  - - String

Returns the type of newlines being used; either `windows`, `unix`, or `auto`

Returns the type of newlines being used; either `windows`, `unix`, or `auto`

- - Document.getTextRange(Range range)

Given a range within the document, this function returns all the text within that range as a single string.

Given a range within the document, this function returns all the text within that range as a single string.

#### Arguments

range | Range | Required. The range to work with

- - Document.getValue()

Returns all the lines in the document as a single string, split by the new line character.

Returns all the lines in the document as a single string, split by the new line character.

- - Document.indexToPosition(Number index, Number startRow)
  - - Object

Converts an index position in a document to a `{row, column}` object.

Converts an index position in a document to a `{row, column}` object.

Index refers to the "absolute position" of a character in the document. For example:

    var x = 0; // 10 characters, plus one for newline
    var y = -1;

Here, `y` is an index 15: 11 characters for the first row, and 5 characters until `y` in the second.

#### Arguments

index | Number | Required. An index to convert
startRow | Number | Required. =0 The row from which to start the conversion

- - Document.insert(Object position, String text)
  - - Object

Inserts a block of `text` and the indicated `position`.

Inserts a block of `text` and the indicated `position`.

#### Arguments

position | Object | Required. The position to start inserting at
text | String | Required. A chunk of text to insert

- - Document.insertInLine(Object position, String text)
  - - Object

Inserts `text` into the `position` at the current row. This method also triggers the `'change'` event.

Inserts `text` into the `position` at the current row. This method also triggers the `'change'` event.

#### Arguments

position | Object | Required. The position to insert at
text | String | Required. A chunk of text

- - Document.insertLines(Number row, Array lines)
  - - Object

Inserts the elements in `lines` into the document, starting at the row index given by `row`. This method also triggers the `'change'` event.

Inserts the elements in `lines` into the document, starting at the row index given by `row`. This method also triggers the `'change'` event.

#### Arguments

row | Number | Required. The index of the row to insert at
lines | Array | Required. An array of strings

- - Document.insertNewLine(Object position)
  - - Object

Inserts a new line into the document at the current row's `position`. This method also triggers the `'change'` event.

Inserts a new line into the document at the current row's `position`. This method also triggers the `'change'` event.

#### Arguments

position | Object | Required. The position to insert at

- - Document.isNewLine(String text)

Returns `true` if `text` is a newline character (either `\r\n`, `\r`, or `\n`).

Returns `true` if `text` is a newline character (either `\r\n`, `\r`, or `\n`).

#### Arguments

text | String | Required. The text to check

- - Document.positionToIndex(Object pos, Number startRow)
  - - Number

Converts the `{row, column}` position in a document to the character's index.

Converts the `{row, column}` position in a document to the character's index.

Index refers to the "absolute position" of a character in the document. For example:

    var x = 0; // 10 characters, plus one for newline
    var y = -1;

Here, `y` is an index 15: 11 characters for the first row, and 5 characters until `y` in the second.

#### Arguments

pos | Object | Required. The `{row, column}` to convert
startRow | Number | Required. =0 The row from which to start the conversion

- - Document.remove(Range range)
  - - Object

Removes the `range` from the document.

Removes the `range` from the document.

#### Arguments

range | Range | Required. A specified Range to remove

- - Document.removeInLine(Number row, Number startColumn, Number endColumn)
  - - Object

Removes the specified columns from the `row`. This method also triggers the `'change'` event.

Removes the specified columns from the `row`. This method also triggers the `'change'` event.

#### Arguments

row | Number | Required. The row to remove from
startColumn | Number | Required. The column to start removing at
endColumn | Number | Required. The column to stop removing at

- - Document.removeLines(Number firstRow, Number lastRow)
  - - String

Removes a range of full lines. This method also triggers the `'change'` event.

Removes a range of full lines. This method also triggers the `'change'` event.

#### Arguments

firstRow | Number | Required. The first row to be removed
lastRow | Number | Required. The last row to be removed

- - Document.removeNewLine(Number row)

Removes the new line between `row` and the row immediately following it. This method also triggers the `'change'` event.

Removes the new line between `row` and the row immediately following it. This method also triggers the `'change'` event.

#### Arguments

row | Number | Required. The row to check

- - Document.replace(Range range, String text)
  - - Object

Replaces a range in the document with the new `text`.

Replaces a range in the document with the new `text`.

#### Arguments

range | Range | Required. A specified Range to replace
text | String | Required. The new text to use as a replacement

- - Document.revertDeltas(Object deltas)

Reverts any changes previously applied. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.

Reverts any changes previously applied. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.

#### Arguments

deltas | Object | Required.

- - Document.setNewLineMode(String newLineMode)

Sets the new line mode.

Sets the new line mode.

#### Arguments

newLineMode | String | Required. The newline mode to use; can be either `windows`, `unix`, or `auto`

- - Document.setValue(String text)

Replaces all the lines in the current `Document` with the value of `text`.

Replaces all the lines in the current `Document` with the value of `text`.

#### Arguments

text | String | Required. The text to use