Textadept
- Home |
- Download |
- Lua API |
- Source |
- Language Modules |
- Stats |
- Wiki |
- Mailing List
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:
text
: Optional snippet text to insert. Ifnil
, 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:
_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.