Module modules.scite.snippets

Provides Textmate-like snippets for the scite module. There are several option variables used: PLATFORM: OS platform (linux or windows). MARK_SNIPPET: The integer mark used to identify the line that marks the end of a snippet. SCOPES_ENABLED: Flag indicating whether scopes/styles can be used for snippets. FILE_IN: Location of the temporary file used as STDIN for regex mirrors. FILE_OUT: Location of the temporary file that will contain output for regex mirrors. REDIRECT: The command line symbol used for redirecting STDOUT to a file. RUBY_CMD: The command that executes the Ruby interpreter. MARK_SNIPPET_COLOR: The Scintilla color used for the line that marks the end of the snippet.

Usage

Basically, snippets are pieces of text inserted into a document, but can
execute shell code at run-time, contain placeholders for additional
information to be added, and make simple transforms on that information.
This is much more powerful than SciTE's abbreviation expansion system.

Syntax:
  Snippets are defined in a user-defined table 'snippets'. Scopes (discussed
  below) are numeric indices of the snippets table and are tables themselves.
  Each string index in each scope table is the snippet trigger text. The
  expanded text is equated to this trigger.

  For example:
  snippets = {
    file = "$(FileNameExt)",
    [SCLEX_RUBY] = {
      ['def'] = "def ${1:initialize}(${2:})\n  ${0}\nend"
      [SCE_RB_STRING] = {
        ['c'] = "#{${0}}"
      }
    }
  }

  The top-level snippets are global, the SCLEX_RUBY snippets are global to a
  buffer with Ruby syntax highlighting enabled, and the SCLEX_RUBY
  SCE_RB_STRING snippet is expanded in that buffer only when currently in
  Ruby's string scope.

  Scopes and Lexers:
    In the previous example, SCLEX_RUBY is a constant defining the Ruby lexer
    and has the value in Scintilla.iface (22). SCE_RB_STRING is the string
    scope in SCLEX_RUBY whose definition is also in Scintilla.iface (6).

    Scope-insensitive snippets should be placed in the lexer table, and
    lexer-insensitive key commands should be placed in the keys table.

  By default scopes are enabled. To disable them, set the SCOPES_ENABLED
  variable to false.

  Order of expansion precidence: Scope, Lexer, Global.
    Snippets in the current scope have the first priority, snippets in the
    current lexer have the second, and global snippets have the last
    priority.

  Declaring snippets: ['snippet_trigger'] = "snippet_text"
    ( e.g. ['file'] = "$(FileNameExt)" )
    snippet_trigger is the text used to trigger snippet expansion and
    snippet_text is the body of the snippet shown upon expansion.
    snippet_text can contain more than just text:

    Placeholders/tab stops: ${num:text} (e.g. ${1:text})
      These are visited in numeric order with ${0} being the final cursor
      position. If the final cursor position is not specified, the cursor is
      placed at the end of the snippet.

    Mirrors: ${num} (e.g. ${1})
      ${1} would be mirrored by whatever value ${1:text} is in the above
      example. Note that mirrors are not updated as text is typed, only after
      the next item is moved to.

    Transformations: ${num/pattern/replacement/options}
      (e.g. ${1/text/other $0/})
      Transformations are like mirrors, only they modify the text to mirror.
      In this case, 'text' would be replaced with 'other text' if the value
      of ${1:text} in the example above matched the pattern. The regular
      expressions are Ruby's regexps. Captures groups are referenced with the
      prefix '$' and $0 is the entire match. Ruby code can be executed inside
      the replacement text using #{}. (e.g. ${1/text/#{$0.capitalize}/})

    SciTE variables: $(variable) (e.g. $(FileNameExt))
      These are expanded like in .properties files.

    Interpolated shell code: `shell_code` (e.g. `date`)

    The '$', '/', '}', and '`' characters can be escaped with the '\'
    character. Keep in mind that this follows Lua syntax, so in literal
    strings (" " or ' '), '\\' is equivalent to one '\' character, but in
    strings like [[ ]], a single '\' is used.

To expand a trigger word, call the snippets module's 'insert' function.

Be sure to set the PLATFORM, RUBY_CMD, FILE_IN and FILE_OUT variables as
appropriate. Regexps use Ruby, so Ruby must be installed. That, or you can
modify the code to use another language's regexps.
(Get Ruby at http://ruby-lang.org)

You can declare snippets in separate lua files and use them. For example, I
have a ruby.lua file with snippets specific to Ruby that is loaded whenever I
open or switch to a Ruby file, but are otherwise invisible to non-Ruby files.

Unlike Textmate, you CAN have nested snippets.

Limitations:
  Shell code inside regexps is executed the moment a snippet is inserted, not
    as placeholders are filled.
  Calling undo or performing other text operations outside the snippet WILL
    probably cause unexpected behavior.
  I don't recommend using the TAB key as the trigger word expander. I've
    tried with mixed success to keep the key's original functionality along
    with snippet expansion. I happen to use Ctrl+I instead.
  Apparently you cannot call module functions from a command defined in a
    SciTE properties file without prepending 'dostring ' first. So something
    like
      command.0.*=dostring modules.scite.snippets.insert()
    will function as expected.

Bugs:
  If you come across a bug, please turn the DEBUG variable on and send me
  both the snippet text and output text.

Testing:
  To run the test suite, change the RUN_TESTS flag and reload snippets.lua.
  Remember to reset the flag when you are finished!

Functions

_DEBUG (text) [Local function] Called for printing debug text if DEBUG flag is set.
cancel_current () Cancels active snippet, reverting to the state before the snippet was activated.
escape (text) [Local function] Replace escaped snippet characters with their octal equivalents.
insert (snippet_arg) Begins expansion of a snippet.
join_lines () [Local function] Joins current line with the line below it, eliminating whitespace.
list () List available snippet triggers as an autocompletion list.
match_indention (ref_line, num_lines) [Local function] When snippets are inserted, match their indentation level with their surroundings.
next_snippet_item () [Local function] Mirror or transform most recently modified field in the current snippet and move on to the next field.
prev () Goes back to the previous placeholder or tab stop, reverting changes made to subsequent ones.
remove_escapes (text) [Local function] Remove escaping forward-slashes from escaped snippet characters.
show_scope () Show the scope/style at the current caret position as a calltip.
snippet_text () [Local function] Gets the text of the snippet.
unescape (text) [Local function] Replace octal snippet characters with their escaped equivalents.

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

_DEBUG (text)
[Local function] Called for printing debug text if DEBUG flag is set.

Parameters

  • text: Debug text to print.
cancel_current ()
Cancels active snippet, reverting to the state before the snippet was activated.
escape (text)
[Local function] Replace escaped snippet characters with their octal equivalents.

Parameters

  • text:
insert (snippet_arg)
Begins expansion of a snippet.

Parameters

  • snippet_arg: Optional snippet to expand. If none is specified, the snippet is determined from the trigger word to the left of the caret, the lexer, and scope.
join_lines ()
[Local function] Joins current line with the line below it, eliminating whitespace. This is used to remove the empty line containing the end of snippet marker.
list ()
List available snippet triggers as an autocompletion list. Global snippets and snippets in the current lexer and scope are used.
match_indention (ref_line, num_lines)
[Local function] When snippets are inserted, match their indentation level with their surroundings.

Parameters

  • ref_line:
  • num_lines:
next_snippet_item ()
[Local function] Mirror or transform most recently modified field in the current snippet and move on to the next field.
prev ()
Goes back to the previous placeholder or tab stop, reverting changes made to subsequent ones.
remove_escapes (text)
[Local function] Remove escaping forward-slashes from escaped snippet characters. At this point, they are no longer necessary.

Parameters

  • text:
show_scope ()
Show the scope/style at the current caret position as a calltip.
snippet_text ()
[Local function] Gets the text of the snippet. This is the text bounded by the start of the trigger word to the end snippet marker on the line after the snippet's end.
unescape (text)
[Local function] Replace octal snippet characters with their escaped equivalents.

Parameters

  • text:

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!