_M.textadept.snippets - Textadept API

# Textadept

- Home |
- Download |
- Lua API |
- Source |
- Language Modules |
- Stats |
- Wiki |
- Mailing List

# _M.textadept.snippets

Snippets for Textadept.

## Overview

Snippets are defined in the global table `snippets`. Each key-value pair in `snippets` consists of either a string trigger word and its snippet text, or a string lexer language (from the lexers/ directory) with a table of trigger words and snippet texts. When searching for a snippet to insert based on a trigger word, snippets in the current lexer have priority, followed by the ones in the global table. This means if there are two snippets with the same trigger word, the one specific to the current lexer is inserted, not the global one.

## Snippet Syntax

Any plain text characters may be used with the exception of ‘%’. Just like in Lua patterns, ‘%’ is an escape character. The sequence “%%” stands for a single ‘%’. Also, it is recommended to use “\t” characters for indentation because they can be converted to spaces based on the current indentation settings. In addition to plain text, snippets can contain placeholders for further user input, can mirror or transform those user inputs, and/or execute arbitrary code.

### Placeholders

`%``n``(``text``)` sequences are called placeholders, where `n` is an integer and `text` is the default text inserted into the placeholder. Placeholders are visited in numeric order each time `_insert()` is called with an active snippet. When no more placeholders are left, the caret is placed at the `%0` placeholder (if it exists), or at the end of the snippet. Examples are

    snippets['foo'] = 'foobar%1(baz)'
    snippets['bar'] = 'start\n\t%0\nend'

### Mirrors

`%``n` sequences are called mirrors, where `n` is an integer. Mirrors with the same `n` as a placeholder mirror any user input in the placeholder. If no placeholder exists for `n`, the first occurrence of that mirror in the snippet becomes the placeholder, but with no default text. Examples are

    snippets['foo'] = '%1(mirror), %1, on the wall'
    snippets['q'] = '"%1"'

### Transforms

`%``n``<``Lua code``>` and `%``n``[``Shell code``]` sequences are called transforms, where `n` is an integer, `Lua code` is arbitrary Lua code, and `Shell code` is arbitrary Shell code. The `n` is optional, and for transforms that omit it, their code is executed the moment the snippet is inserted. Otherwise, the code is executed as placeholders are visited.

Lua code is run in Textadept’s Lua State with with an additional `selected_text` global variable that contains the current selection in the buffer. The transform is replaced with the return value of the executed code. An example is

    snippets['foo'] = [[
    %2<('%1'):gsub('^.', function(c)
      return c:upper() -- capitalize the word
    end)>, %1(mirror) on the wall.]]

Shell code is executed using Lua’s `io.popen()`. The transform is replaced with the process' standard output (stdout). An example is

    snippets['foo'] = '$%1(HOME) = %2[echo $%1]'

## Functions

### `_cancel_current`()

Cancels insertion of the active snippet.

### `_insert`(text)

Inserts snippet text text or the snippet associated with the trigger behind the caret as a snippet, or goes to the next placeholder of the active snippet, ultimately only returning `false` if no action was taken.

Parameters:

- `text`: Optional snippet text to insert. If `nil`, attempts to insert a new snippet based on the trigger, the word behind caret, and the current lexer.

Return:

- `false` if no action was taken; `nil` otherwise.

See also:

- `buffer.word_chars`

### `_previous`()

Goes back to the previous snippet placeholder, reverting any changes from the current one, but returns `false` only if no snippet is active.

Return:

- `false` if no snippet is active; `nil` otherwise.

### `_select`()

Prompts the user for a snippet to insert from a list of global and language-specific snippets.

## Tables

### `_G.snippets`

Map of snippet triggers with their snippet text, with language-specific snippets tables assigned to a lexer name key. This table also contains the `_M.textadept.snippets` module.