Contents

_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:

Return:

See also:


_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:


_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.