Contents

_M.textadept.snippets

Provides Lua-style snippets for Textadept.

Overview

Snippets are dynamic pieces of text inserted into a document that contain placeholders for further input, mirror or transform that input, and execute code.

Snippets are defined in the global table snippets. Each key-value pair in snippets consists of either:

Language names are the names of the lexer files in lexers/ such as cpp and lua.

By default, the Tab key expands a snippet and tabs through placeholders while Shift+Tab tabs backwards through them. Snippets can also be expanded inside one another.

Snippet Precedence

When searching for a snippet to expand in the snippets table, snippets in the current lexer have priority, followed by the ones in the global table.

Snippet Syntax

A snippet to insert may contain any of the following:

Plain Text

Any plain text characters may be used with the exception of % followed immediately by a digit (0-9), (, ), >, or ] character. These are “escape sequences” for the more complicated features of snippets. If you want to use % followed by one of the before-mentioned characters, prepend another % to the first %. For example, %%> in the snippet inserts a literal %> into the document.

Placeholders

Textadept’s snippets provide a number of different placeholders. The simplest ones are of the form

%num

where num is a number. Placeholders are visited in numeric order (1, 2, 3, etc.) with the Tab key after the snippet is inserted and can be used to enter in additional text. When no more placeholders are left, the caret is placed at either the end of the snippet or the %0 placeholder if it exists.

A placeholder can specify default text. It is of the form

%num(default text)

where, again, num is a number. These kinds of placeholders take precedence over the simpler placeholders described above. If a snippet contains more than one placeholder with the same num, the one containing default text is visited first and the others become mirrors. Mirrors simply mirror the text typed into the current placeholder.

The last kind of placeholder executes either Lua or Shell code.

%<lua_code>
%num<lua_code>
%[shell_code]
%num[shell_code]

For placeholders that omit num, their code is executed the moment the snippet is inserted. Otherwise the code is executed as placeholders are visited.

For Lua code, the global Lua state is available as well as a selected_text variable (containing the current selection in the buffer). After execution, the placeholder contains the return value of the code that was run.

Shell code is executed using Lua’s io.popen() which reads from the process' standard output (STDOUT). After execution, the placeholder will contain the STDOUT of the process.

These kinds of placeholders can be used to transform mirrored text. For example, %2<([[%1]]):gsub('^.', function(c) return c:upper() end)> will capitalize a mirrored %1 placeholder.

Important Note

It is very important that any %, (, ), >, or ] characters within placeholders be escaped with a % as necessary. Otherwise, unexpected results will occur. %s only need to be escaped if they are proceeded by a digit, (s and )s only need to be escaped directly after a %num sequence or inside default text placeholders if and only if there is no matching parenthesis (thus, nested parentheses do not need to be escaped), ]s only need to be escaped inside Shell code placeholders, and >s only need to be escaped inside Lua code placeholders.

Example

snippets.snippet = 'snippets.%1 = \'%0\''
snippets.file = '%<buffer.filename>'
snippets.lua = {
  f = 'function %1(name)(%2(args))\n\t%0\nend'
}

The first two snippets are global. The first is quite simple to understand. The second runs Lua code to determine the current buffer’s filename and inserts it. The last snippet expands only when editing Lua code.

It is recommended to use tab characters instead of spaces like in the last example. Tabs will be converted to spaces as necessary.


Functions


_cancel_current ()

Cancels the active snippet, reverting to the state before its activation, and restores the previously running snippet (if any).


_insert (text)

Inserts a snippet.

Parameters:

Return:


_previous ()

Goes back to the previous placeholder, reverting any changes from the current one.

Return:


_select ()

Prompts the user to select a snippet to insert from a filtered list dialog. Global snippets and snippets in the current lexer are shown.


Tables


_G.snippets

Provides access to snippets from _G.