Module _m.textadept.lsnippets

Provides Lua-style snippets for Textadept.

Settings

  • MARK_SNIPPET: The unique 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.

Overview

Snippets are basically pieces of text inserted into a document, but can execute code, contain placeholders you can enter dynamic text for, and perform transformations on that text. This is much more powerful than standard text templating.

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

  • A string snippet trigger word and its expanded text.
  • A string language name and its associated snippets-like table.
  • A string style name and its associated snippets-like table.

Language names are the names of the lexer files in lexers/ such as cpp and lua. Style names are different lexer styles, most of which are in lexers/lexer.lua; examples are whitespace, comment, and string.

Snippet Precedence

When searching for a snippet to expand in the snippets table, snippets in the current style have priority, followed by the ones in the current lexer, and finally 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 % and `. These are special characters and must be "escaped" by prefixing one with a %. As an example, %% inserts a single % in the snippet.

Lua and Shell Code

%(lua_code)
`shell_code`

The code is executed the moment the snippet is inserted.

For Lua code, the global Lua state is available as well as a selected_text variable (containing the current selection in the buffer) for convenience. Only the return value of the code execution is inserted, not standard out. Therefore any print() statements are meaningless.

Shell code is run via Lua's io.popen().

Tab Stops and Mirrors

%num

These are visited in numeric order (1, 2, 3, etc.) with %0 being the final position of the caret, or the end of the snippet if %0 is 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, but have precedence over tab stops, and insert the specified text at the current position upon entry. text can contain Lua code executed at run-time:

%num(#(lua_code))

The global Lua state is available as well as a selected_text variable (containing the current selection in the buffer) for convenience.

#'s will have to be escaped with % for plain text. Any mis-matched )'s must also be escaped, but balanced ()'s need not be.

Transformations

%num(pattern|replacement)

These act like mirrors, but transform the text that would be inserted using a given Lua pattern and replacement. Like in placeholders, replacement can contain Lua code executed at run-time as well as the standard Lua capture sequences: %n where 1 <= n <= 9.

Any |'s after the first one do not need to be escaped.

Example

snippets = {
  file = '%(buffer.filename)',
  lua = {
    f = 'function %1(name)(%2(args))\n  %0\nend',
    string = { [string-specific snippets here] }
  }
}

The first snippet is global and runs the Lua code to determine the current buffer's filename and inserts it. The other snippets apply only in the lua lexer. Any snippets in the string table are available only when the current style is string in the lua lexer.

Settings

  • MARK_SNIPPET: The unique 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.

Overview

Snippets are basically pieces of text inserted into a document, but can execute code, contain placeholders you can enter dynamic text for, and perform transformations on that text. This is much more powerful than standard text templating.

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

  • A string snippet trigger word and its expanded text.
  • A string language name and its associated snippets-like table.
  • A string style name and its associated snippets-like table.

Language names are the names of the lexer files in lexers/ such as cpp and lua. Style names are different lexer styles, most of which are in lexers/lexer.lua; examples are whitespace, comment, and string.

Snippet Precedence

When searching for a snippet to expand in the snippets table, snippets in the current style have priority, followed by the ones in the current lexer, and finally 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 % and `. These are special characters and must be "escaped" by prefixing one with a %. As an example, %% inserts a single % in the snippet.

Lua and Shell Code

%(lua_code)
`shell_code`

The code is executed the moment the snippet is inserted.

For Lua code, the global Lua state is available as well as a selected_text variable (containing the current selection in the buffer) for convenience. Only the return value of the code execution is inserted, not standard out. Therefore any print() statements are meaningless.

Shell code is run via Lua's io.popen().

Tab Stops and Mirrors

%num

These are visited in numeric order (1, 2, 3, etc.) with %0 being the final position of the caret, or the end of the snippet if %0 is 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, but have precedence over tab stops, and insert the specified text at the current position upon entry. text can contain Lua code executed at run-time:

%num(#(lua_code))

The global Lua state is available as well as a selected_text variable (containing the current selection in the buffer) for convenience.

#'s will have to be escaped with % for plain text. Any mis-matched )'s must also be escaped, but balanced ()'s need not be.

Transformations

%num(pattern|replacement)

These act like mirrors, but transform the text that would be inserted using a given Lua pattern and replacement. Like in placeholders, replacement can contain Lua code executed at run-time as well as the standard Lua capture sequences: %n where 1 <= n <= 9.

Any |'s after the first one do not need to be escaped.

Example

snippets = {
  file = '%(buffer.filename)',
  lua = {
    f = 'function %1(name)(%2(args))\n  %0\nend',
    string = { [string-specific snippets here] }
  }
}

The first snippet is global and runs the Lua code to determine the current buffer's filename and inserts it. The other snippets apply only in the lua lexer. Any snippets in the string table are available only when the current style is string in the lua lexer.

Settings

  • MARK_SNIPPET: The unique 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.

Overview

Snippets are basically pieces of text inserted into a document, but can execute code, contain placeholders you can enter dynamic text for, and perform transformations on that text. This is much more powerful than standard text templating.

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

  • A string snippet trigger word and its expanded text.
  • A string language name and its associated snippets-like table.
  • A string style name and its associated snippets-like table.

Language names are the names of the lexer files in lexers/ such as cpp and lua. Style names are different lexer styles, most of which are in lexers/lexer.lua; examples are whitespace, comment, and string.

Snippet Precedence

When searching for a snippet to expand in the snippets table, snippets in the current style have priority, followed by the ones in the current lexer, and finally 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 % and `. These are special characters and must be "escaped" by prefixing one with a %. As an example, %% inserts a single % in the snippet.

Lua and Shell Code

%(lua_code)
`shell_code`

The code is executed the moment the snippet is inserted.

For Lua code, the global Lua state is available as well as a selected_text variable (containing the current selection in the buffer) for convenience. Only the return value of the code execution is inserted, not standard out. Therefore any print() statements are meaningless.

Shell code is run via Lua's io.popen().

Tab Stops and Mirrors

%num

These are visited in numeric order (1, 2, 3, etc.) with %0 being the final position of the caret, or the end of the snippet if %0 is 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, but have precedence over tab stops, and insert the specified text at the current position upon entry. text can contain Lua code executed at run-time:

%num(#(lua_code))

The global Lua state is available as well as a selected_text variable (containing the current selection in the buffer) for convenience.

#'s will have to be escaped with % for plain text. Any mis-matched )'s must also be escaped, but balanced ()'s need not be.

Transformations

%num(pattern|replacement)

These act like mirrors, but transform the text that would be inserted using a given Lua pattern and replacement. Like in placeholders, replacement can contain Lua code executed at run-time as well as the standard Lua capture sequences: %n where 1 <= n <= 9.

Any |'s after the first one do not need to be escaped.

Example

snippets = {
  file = '%(buffer.filename)',
  lua = {
    f = 'function %1(name)(%2(args))\n  %0\nend',
    string = { [string-specific snippets here] }
  }
}

The first snippet is global and runs the Lua code to determine the current buffer's filename and inserts it. The other snippets apply only in the lua lexer. Any snippets in the string table are available only when the current style is string in the lua lexer.

Functions

cancel_current () Cancels the active snippet, reverting to the state before its activation, and restores the previous running snippet (if any).
insert (s_text) Begins expansion of a snippet.
list () Lists available snippets in an autocompletion list.
prev () Goes back to the previous placeholder or tab stop, reverting changes made to subsequent ones.
show_style () Shows the style at the current caret position in a call tip.

Tables

_G.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).
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.

Return value:

false if no snippet was expanded; true otherwise.
list ()
Lists available snippets in an autocompletion list. Global snippets and snippets in the current lexer and style are used.
prev ()
Goes back to the previous placeholder or tab stop, reverting changes made to subsequent ones.

Return value:

false if no snippet is active; nil otherwise
show_style ()
Shows the style at the current caret position in a call tip.

Tables

_G.snippets
Global container that holds all snippet definitions.

Valid XHTML 1.0!