Textadept
- Home |
- Download |
- Lua API |
- Source |
- Language Modules |
- Stats |
- Wiki |
- Mailing List
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:
- A string snippet trigger word and its expanded text.
- A string lexer language name and its associated
snippets
-like table.
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:
text
: Optional snippet text. If none is specified, the snippet text is determined from the trigger and lexer.
Return:
false
if no snippet was expanded;true
otherwise.
_previous
()
Goes back to the previous placeholder, reverting any changes from the current one.
Return:
false
if no snippet is active;nil
otherwise.
_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
.