# _M.textadept.editing

Editing features for Textadept.

- - -

## Fields

- - -

<a id="AUTOINDENT"></a>
### `AUTOINDENT` (bool)

Match the indentation level of the previous line when inserting a new line.
  The default value is `true`.

- - -

<a id="AUTOPAIR"></a>
### `AUTOPAIR` (bool)

Automatically close opening '(', '[', '{', '&quot;', or '&apos;'
  characters.
  The default value is `true`.
  Auto-paired characters are defined in the [`char_matches`](#char_matches)
  table.

- - -

<a id="HIGHLIGHT_BRACES"></a>
### `HIGHLIGHT_BRACES` (bool)

Highlight matching brace characters like "()[]{}".
  The default value is `true`.
  Matching braces are defined in the [`braces`](#braces) table.

- - -

<a id="INDIC_HIGHLIGHT_BACK"></a>
### `INDIC_HIGHLIGHT_BACK` (number)

The color, in "0xBBGGRR" format, used for an indicator for the
  [highlighted word](#highlight_word).

- - -

<a id="STRIP_WHITESPACE_ON_SAVE"></a>
### `STRIP_WHITESPACE_ON_SAVE` (bool)

Strip trailing whitespace on file save.
  The default value is `true`.

- - -

<a id="TYPEOVER_CHARS"></a>
### `TYPEOVER_CHARS` (bool)

Move over the typeover character under the caret when typing it instead of
  inserting it.
  The default value is `true`.
  Typeover characters are defined in the [`typeover_chars`](#typeover_chars)
  table.

- - -


## Functions

- - -

<a id="autocomplete_word"></a>
### `autocomplete_word`(*default\_words*)

Displays an autocompletion list, built from the set of *default_words* and
existing words in the buffer, for the word behind the caret, returning `true`
if completions were found.

Parameters:

* *`default_words`*: Optional list of words considered to be in the buffer,
  even if they are not. Words may contain [registered images][].

[registered images]: buffer.html#register_image

Return:

* `true` if there were completions to show; `false` otherwise.

See also:

* [`buffer.word_chars`](buffer.html#word_chars)

- - -

<a id="block_comment"></a>
### `block_comment`(*prefix*)

Comments or uncomments the selected lines with line comment prefix string
*prefix* or the prefix from the `comment_string` table for the current lexer.
As long as any part of a line is selected, the entire line is eligible for
commenting/uncommenting.

Parameters:

* *`prefix`*: Optional prefix string inserted or removed from the beginning
  of each line in the selection. The default value is the prefix in the
  `comment_string` table for the current lexer.

See also:

* [`comment_string`](#comment_string)

- - -

<a id="convert_indentation"></a>
### `convert_indentation`()

Converts indentation between tabs and spaces depending on the buffer's
indentation settings.
If `buffer.use_tabs` is `true`, `buffer.tab_width` indenting spaces are
converted to tabs. Otherwise, all indenting tabs are converted to
`buffer.tab_width` spaces.

See also:

* [`buffer.use_tabs`](buffer.html#use_tabs)

- - -

<a id="enclose"></a>
### `enclose`(*left, right*)

Encloses the selected text or the word behind the caret within strings *left*
and *right*.

Parameters:

* *`left`*: The left part of the enclosure.
* *`right`*: The right part of the enclosure.

- - -

<a id="filter_through"></a>
### `filter_through`(*cmd*)

Passes selected or all buffer text to string shell command *cmd* as standard
input (stdin) and replaces the input text with the command's standard output
(stdout).
Standard input is as follows:

1. If text is selected and spans multiple lines, all text on the lines
containing the selection is used. However, if the end of the selection is at
the beginning of a line, only the EOL (end of line) characters from the
previous line are included as input. The rest of the line is excluded.
2. If text is selected and spans a single line, only the selected text is
used.
3. If no text is selected, the entire buffer is used.

Parameters:

* *`cmd`*: The Linux, BSD, Mac OSX, or Windows shell command to filter text
  through.

- - -

<a id="goto_line"></a>
### `goto_line`(*line*)

Goes to line number *line* or the user-specified line in the buffer.

Parameters:

* *`line`*: Optional line number to go to. If `nil`, the user is prompted for
  one.

- - -

<a id="highlight_word"></a>
### `highlight_word`()

Highlights all occurrences of the selected text or the current word.

See also:

* [`buffer.word_chars`](buffer.html#word_chars)

- - -

<a id="join_lines"></a>
### `join_lines`()

Joins the currently selected lines or the current line with the line below
it.
As long as any part of a line is selected, the entire line is eligible for
joining.

- - -

<a id="match_brace"></a>
### `match_brace`(*select*)

Goes to the current character's matching brace, selecting the text in-between
if *select* is `true`.

Parameters:

* *`select`*: Optional flag indicating whether or not to select the text
  between matching braces. The default value is `false`.

- - -

<a id="select_enclosed"></a>
### `select_enclosed`(*left, right*)

Selects the text in-between strings *left* and *right* containing the caret.
If already selected, toggles between selecting the *left* and *right*
enclosures too.

Parameters:

* *`left`*: The left part of the enclosure.
* *`right`*: The right part of the enclosure.

- - -

<a id="select_indented_block"></a>
### `select_indented_block`()

Selects indented text blocks intelligently.
If no block of text is selected, all text with the current level of
indentation is selected. If a block of text is selected and the lines
immediately above and below it are one indentation level lower, they are
added to the selection. In all other cases, the behavior is the same as if no
text is selected.

- - -

<a id="select_line"></a>
### `select_line`()

Selects the current line.

- - -

<a id="select_paragraph"></a>
### `select_paragraph`()

Selects the current paragraph.
Paragraphs are surrounded by one or more blank lines.

- - -

<a id="select_word"></a>
### `select_word`()

Selects the current word.

See also:

* [`buffer.word_chars`](buffer.html#word_chars)

- - -

<a id="transpose_chars"></a>
### `transpose_chars`()

Transposes characters intelligently.
If the caret is at the end of a line, the two characters before the caret are
transposed. Otherwise, the characters to the left and right are.

- - -


## Tables

- - -

<a id="braces"></a>
### `braces`

Table of brace characters to highlight, with language-specific brace
character tables assigned to a lexer name key.
The ASCII values of brace characters are keys and are assigned non-`nil`
values. The default brace characters are '(', ')', '[', ']', '{', and '}'.

Usage:

* `_M.textadept.editing.braces.hypertext = {..., [60] = 1, [62] = 1}`

See also:

* [`HIGHLIGHT_BRACES`](#HIGHLIGHT_BRACES)

- - -

<a id="char_matches"></a>
### `char_matches`

Map of auto-paired characters like parentheses, brackets, braces, and quotes,
with language-specific auto-paired character maps assigned to a lexer name
key.
The ASCII values of opening characters are assigned to strings containing
complement characters. The default auto-paired characters are "()", "[]",
"{}", "&apos;&apos;", and "&quot;&quot;".

Usage:

* `_M.textadept.editing.char_matches.hypertext = {..., [60] = '>'}`

See also:

* [`AUTOPAIR`](#AUTOPAIR)

- - -

<a id="comment_string"></a>
### `comment_string`

Map of lexer names to line comment prefix strings for programming languages,
used by the `block_comment()` function.
Keys are lexer names and values are the line comment prefixes for the
language. This table is typically populated by [language-specific modules][].

[language-specific modules]: _M.html#Block.Comment

See also:

* [`block_comment`](#block_comment)

- - -

<a id="typeover_chars"></a>
### `typeover_chars`

Table of characters to move over when typed, with language-specific typeover
character tables assigned to a lexer name key.
The ASCII values of characters are keys and are assigned non-`nil` values.
The default characters are ')', ']', '}', '&apos;', and '&quot;'.

Usage:

* `_M.textadept.editing.typeover_chars.hypertext = {..., [62] = 1}`

See also:

* [`TYPEOVER_CHARS`](#TYPEOVER_CHARS)

- - -

