Module _m.textadept.lsnippets

Provides Lua-centric snippets for Textadept. Snippets are basically pieces of text inserted into a document, but can execute code, contain placeholders a user can enter in dynamic text for, and make transformations on that text. This is much more powerful than standard text templating. There are several option variables used: MARK_SNIPPET: The integer mark used to identify the line that marks the end of a snippet. MARK_SNIPPET_COLOR: The Scintilla color used for the line that marks the end of the snippet.

Usage

Snippets are defined in the global table 'snippets'. Keys in that table are
snippet trigger words, and values are the snippet's text to insert. The
exceptions are language names and style names. Language names have table
values of either snippets or style keys with table values of snippets.
See /lexers/lexer.lua for some default style names. Each lexer's 'add_style'
function adds additional styles, the string argument being the style's name.
For example:
  snippets = {
    file = '%(buffer.filename)',
    lua = {
      f = 'function %1(name)(%2(args))\n  %0\nend',
      string = { [string-specific snippets here] }
    }
  }
Style and lexer insensitive snippets should be placed in the lexer and
snippets tables respectively.

When searching for a snippet to expand in the snippets table, snippets in the
current style have priority, then the ones in the current lexer, and finally
the ones in the global table.

As mentioned, snippets are key-value pairs, the key being the trigger word
and the value being the snippet text: ['trigger'] = 'text'.
Snippet text however can contain more than just text.

Insert-time Lua and shell code: %(lua_code), `shell_code`
  The code is executed the moment the snippet is inserted. For Lua code, the
  result of the code execution is inserted, so print statements are useless.
  All global variables and a 'selected_text' variable are available.

Tab stops/Mirrors: %num
  These are visited in numeric order with %0 being the final position of the
  caret, the end of the snippet if not specified. If there is a placeholder
  (described below) with the specified num, its text is mirrored here.

Placeholders: %num(text)
  These are also visited in numeric order, having precedence over tab stops,
  and inserting the specified text. If no placeholder is available, the tab
  stop is visited instead. The specified text can contain Lua code executed
  at run-time: #(lua_code).

Transformations: %num(pattern|replacement)
  These act like mirrors, but transform the text that would be inserted using
  a given Lua pattern and replacement. The replacement can contain Lua code
  executed at run-time: #(lua_code), as well as the standard Lua capture
  sequences: %n where 1 <= n <= 9.
  See the Lua documentation for using patterns and replacements.

To escape any of the special characters '%', '`', ')', '|', or '#', prepend
the standard Lua escape character '%'. Note:
  * Only '`' needs to be escaped in shell code.
  * '|'s after the first in transformations do not need to be escaped.
  * Only unmatched ')'s need to be escaped. Nested ()s are ignored.

Functions

cancel_current () Cancels the active snippet, reverting to the state before its activation, and restores the previous running snippet (if any).
handle_escapes (s) [Local function] Replaces escaped characters with their octal equivalents in a given string.
insert (s_text) Begins expansion of a snippet.
list () Lists available snippets in an autocompletion list.
next () If previously at a placeholder or tab stop, attempts to mirror and/or transform the entered text at all appropriate mirrors before moving on to the next placeholder or tab stop.
prev () Goes back to the previous placeholder or tab stop, reverting changes made to subsequent ones.
run_lua_code (code) [Local function] Runs the given Lua code.
show_style () Shows the style at the current caret position in a call tip.
snippet_info () [Local function] Gets the start position, end position, and text of the currently running snippet.
unescape (s) [Local function] Replaces escaped characters with the actual characters in a given string.
unhandle_escapes (s) [Local function] Replaces octal characters with their escaped equivalents in a given string.

Tables

snippet [Local table] The current snippet.
snippet_stack [Local table] The stack of currently running snippets.
snippets Global container that holds all snippet definitions.


Functions

cancel_current ()
Cancels the active snippet, reverting to the state before its activation, and restores the previous running snippet (if any).
handle_escapes (s)
[Local function] Replaces escaped characters with their octal equivalents in a given string. '%%' is the escape character used.

Parameters

  • s:
insert (s_text)
Begins expansion of a snippet. The text inserted has escape sequences handled.

Parameters

  • s_text: Optional snippet to expand. If none is specified, the snippet is determined from the trigger word (left of the caret), lexer, and style.
list ()
Lists available snippets in an autocompletion list. Global snippets and snippets in the current lexer and style are used.
next ()
If previously at a placeholder or tab stop, attempts to mirror and/or transform the entered text at all appropriate mirrors before moving on to the next placeholder or tab stop.
prev ()
Goes back to the previous placeholder or tab stop, reverting changes made to subsequent ones.
run_lua_code (code)
[Local function] Runs the given Lua code.

Parameters

  • code:
show_style ()
Shows the style at the current caret position in a call tip.
snippet_info ()
[Local function] Gets the start position, end position, and text of the currently running snippet.

Return value:

start pos, end pos, and snippet text.
unescape (s)
[Local function] Replaces escaped characters with the actual characters in a given string. This is used when escape sequences are no longer needed.

Parameters

  • s:
unhandle_escapes (s)
[Local function] Replaces octal characters with their escaped equivalents in a given string.

Parameters

  • s:

Tables

snippet
[Local table] The current snippet.
snippet_stack
[Local table] The stack of currently running snippets.
snippets
Global container that holds all snippet definitions.

Valid XHTML 1.0!