Renamed _m.textadept.lsnippets to _m.textadept.snippets.

1 files changed, 480 insertions, 0 deletions

diff --git a/modules/textadept/snippets.lua b/modules/textadept/snippets.lua
new file mode 100644
index 00000000..07ab0c8f
--- /dev/null
+++ b/modules/textadept/snippets.lua
@@ -0,0 +1,480 @@
+-- Copyright 2007-2010 Mitchell mitchell<att>caladbolg.net. See LICENSE.
+
+local textadept = _G.textadept
+local locale = _G.locale
+
+---
+-- Provides Lua-style snippets for Textadept.
+module('_m.textadept.snippets', package.seeall)
+
+-- Markdown:
+-- ## 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][scintilla_color] used for the
+--   line that marks the end of the snippet.
+--
+-- [scintilla_color]: http://scintilla.org/ScintillaDoc.html#colour
+--
+-- ## 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 &#96;.
+-- 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()`][io_popen].
+--
+-- [io_popen]: http://www.lua.org/manual/5.1/manual.html#pdf-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][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.
+--
+-- [lua_pattern]: http://www.lua.org/manual/5.1/manual.html#5.4.1
+--
+-- 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 = 4
+MARK_SNIPPET_COLOR = 0x4D9999
+-- end settings
+
+---
+-- Global container that holds all snippet definitions.
+-- @class table
+-- @name _G.snippets
+_G.snippets = {}
+
+_G.snippets.file = "%(buffer.filename)"
+_G.snippets.path = "%((buffer.filename or ''):match('^.+/'))"
+_G.snippets.tab  = "%%%1(1)(%2(default))"
+_G.snippets.key  = "['%1'] = { %2(func)%3(, %4(arg)) }"
+
+-- The current snippet.
+local snippet = {}
+
+-- The stack of currently running snippets.
+local snippet_stack = {}
+
+-- Replaces escaped characters with their octal equivalents in a given string.
+-- @param s The string to handle escapes in.
+-- @return string with escapes handled.
+local function handle_escapes(s)
+  return s:gsub('%%([%%`%)|#])',
+    function(char) return ("\\%03d"):format(char:byte()) end)
+end
+
+-- Replaces octal characters with their escaped equivalents in a given string.
+-- @param s The string to unhandle escapes in.
+-- @return string with escapes unhandled.
+local function unhandle_escapes(s)
+  local char = string.char
+  return s:gsub('\\(%d%d%d)', function(byte) return '%'..char(byte) end)
+end
+
+-- Replaces escaped characters with the actual characters in a given string.
+-- This is used when escape sequences are no longer needed.
+-- @param s The string to unescape escapes in.
+-- @return string with escapes unescaped.
+local function unescape(s) return s:gsub('%%([%%`%)|#])', '%1') end
+
+-- Gets the start position, end position, and text of the currently running
+-- snippet.
+-- @return start pos, end pos, and snippet text.
+local function snippet_info()
+  local buffer = buffer
+  local s = snippet.start_pos
+  local e =
+    buffer:position_from_line(
+      buffer:marker_line_from_handle(snippet.end_marker)) - 1
+  if e >= s then return s, e, buffer:text_range(s, e) end
+end
+
+-- Runs the given Lua code.
+-- @param code The Lua code to run.
+-- @return string result from the code run.
+local function run_lua_code(code)
+  code = unhandle_escapes(code)
+  local env =
+    setmetatable({ selected_text = buffer:get_sel_text() }, { __index = _G })
+  local _, val = pcall(setfenv(loadstring('return '..code), env))
+  return val or ''
+end
+
+-- 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.
+-- @return false if no snippet was expanded; nil otherwise
+local function next_tab_stop()
+  if not snippet.index then return false end -- no snippet active
+  local buffer = buffer
+  local s_start, s_end, s_text = snippet_info()
+  if not s_text then
+    cancel_current()
+    return
+  end
+
+  local index = snippet.index
+  snippet.snapshots[index] = s_text
+  if index > 0 then
+    buffer:begin_undo_action()
+    local caret = math.max(buffer.anchor, buffer.current_pos)
+    local ph_text = buffer:text_range(snippet.ph_pos, caret)
+
+    -- Transform mirror.
+    s_text =
+      s_text:gsub('%%'..index..'(%b())',
+        function(mirror)
+          local pattern, replacement = mirror:match('^%(([^|]+)|(.+)%)$')
+          if not pattern and not replacement then return ph_text end
+          return ph_text:gsub(unhandle_escapes(pattern),
+            function(...)
+              local arg = {...}
+              local repl = replacement:gsub('%%(%d+)',
+                function(i) return arg[tonumber(i)] or '' end)
+              return repl:gsub('#(%b())', run_lua_code)
+            end, 1)
+        end)
+
+    -- Regular mirror.
+    s_text = s_text:gsub('()%%'..index,
+      function(pos)
+        for mirror, e in s_text:gmatch('%%%d+(%b())()') do
+          local s = mirror:find('|')
+          if s and pos > s and pos < e then return nil end -- inside transform
+        end
+        return ph_text
+      end)
+
+    buffer:set_sel(s_start, s_end)
+    buffer:replace_sel(s_text)
+    s_start, s_end = snippet_info()
+    buffer:end_undo_action()
+  end
+
+  buffer:begin_undo_action()
+  index = index + 1
+  if index <= snippet.max_index then
+    -- Find the next tab stop.
+    local s, e, next_item
+    repeat -- ignore replacement mirrors
+      s, e, next_item = s_text:find('%%'..index..'(%b())', e)
+    until not s or next_item and not next_item:find('|')
+    if next_item then -- placeholder
+      buffer.target_start, buffer.target_end = s_start, buffer.length
+      buffer.search_flags = 0
+      buffer:search_in_target('%'..index..next_item)
+      next_item = next_item:gsub('#(%b())', run_lua_code)
+      next_item = unhandle_escapes(next_item:sub(2, -2))
+      buffer:replace_target(next_item)
+      buffer:set_sel(buffer.target_start, buffer.target_start + #next_item)
+      snippet.ph_pos = buffer.target_start
+    else
+      repeat -- ignore placeholders
+        local found = true
+        s, e = (s_text..' '):find('%%'..index..'[^(]', e)
+        if not s then
+          snippet.index = index + 1
+          next_tab_stop()
+          return
+        end
+        for p_s, p_e in s_text:gmatch('%%%d+()%b()()') do
+          if s > p_s and s < p_e then
+            found = false
+            break
+          end
+        end
+      until found
+      buffer:set_sel(s_start + s - 1, s_start + e - 1)
+      buffer:replace_sel('') -- replace_target() doesn't place caret
+      snippet.ph_pos = s_start + s - 1
+    end
+    -- Place additional carets at mirrors.
+    local _, _, text = snippet_info()
+    text = text:gsub('(%%%d+%b())',
+      function(mirror)
+        -- Lua code in replacement mirrors may contain '%' sequences; do not
+        -- treat as mirrors
+        if mirror:find('|') then return string.rep('_', #mirror) end
+      end)
+    for s, e in text:gmatch('()%%'..index..'()[^(]') do
+      buffer:add_selection(s_start + s - 1, s_start + e - 1)
+    end
+    buffer.main_selection = 0 -- original placeholder/mirror
+    -- Done.
+    snippet.index = index
+  else
+    -- Finished. Find '%0' and place the caret there.
+    s_text = unescape(unhandle_escapes(s_text))
+    buffer:set_sel(s_start, s_end)
+    buffer:replace_sel(s_text)
+    s_start, s_end = snippet_info()
+    if s_end then
+      buffer:goto_pos(s_end + 1)
+      buffer:delete_back()
+    end
+    local s, e = s_text:find('%%0')
+    if s and e then
+      buffer:set_sel(s_start + s - 1, s_start + e)
+      buffer:replace_sel('')
+    end
+    buffer:marker_delete_handle(snippet.end_marker)
+    snippet = #snippet_stack > 0 and table.remove(snippet_stack) or {}
+  end
+  buffer:end_undo_action()
+end
+
+---
+-- Begins expansion of a snippet.
+-- The text inserted has escape sequences handled.
+-- @param 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 false if no snippet was expanded; true otherwise.
+function insert(s_text)
+  local buffer = buffer
+  local anchor, caret = buffer.anchor, buffer.current_pos
+  local lexer, style, start, s_name
+  if not s_text then
+    lexer = buffer:get_lexer_language()
+    style = buffer:get_style_name(buffer.style_at[caret])
+    buffer:word_left_extend()
+    start = buffer.current_pos
+    s_name = buffer:get_sel_text()
+  end
+  if s_name then
+    local function try_get_snippet(...)
+      local table = _G.snippets
+      for _, idx in ipairs{...} do table = table[idx] end
+      return type(table) == 'string' and table or error()
+    end
+    local ret
+    ret, s_text = pcall(try_get_snippet, lexer, style, s_name)
+    if not ret then ret, s_text = pcall(try_get_snippet, lexer, s_name) end
+    if not ret then ret, s_text = pcall(try_get_snippet, s_name) end
+    if not ret then buffer:set_sel(anchor, caret) end -- restore caret
+  end
+
+  if s_text then
+    buffer:begin_undo_action()
+    s_text = handle_escapes(s_text)
+
+    -- Take into account tab settings.
+    if not buffer.use_tabs then
+      s_text = s_text:gsub('\t', string.rep(' ', buffer.tab_width))
+    end
+
+    -- Execute Lua and shell code.
+    s_text = s_text:gsub('%%(%b())', run_lua_code)
+    s_text =
+      s_text:gsub('`([^`]+)`',
+        function(code)
+          local p = io.popen(code)
+          local out = p:read('*all'):sub(1, -2)
+          p:close()
+          return out
+        end)
+
+    -- Initialize the new snippet. If one is running, push it onto the stack.
+    if snippet.index then snippet_stack[#snippet_stack + 1] = snippet end
+    snippet = {}
+    snippet.snapshots = {}
+    snippet.start_pos = start or caret
+    snippet.prev_sel_text = buffer:get_sel_text()
+    snippet.index, snippet.max_index = 0, 0
+    for i in s_text:gsub('(%%%d+)%b()', '%1'):gmatch('%%(%d+)') do
+      -- placeholders may contain Lua code that has %n sequences that mess up
+      -- this calculation; the above gsub accounts for this
+      i = tonumber(i)
+      if i > snippet.max_index then snippet.max_index = i end
+    end
+
+    -- Insert the snippet and set a mark defining the end of it.
+    buffer:replace_sel(s_text)
+    buffer:add_text('\n')
+    local line = buffer:line_from_position(buffer.current_pos)
+    snippet.end_marker = buffer:marker_add(line, MARK_SNIPPET)
+    buffer:marker_set_back(MARK_SNIPPET, MARK_SNIPPET_COLOR)
+
+    -- Indent all lines inserted.
+    buffer.current_pos = snippet.start_pos
+    local count = 0
+    for _ in s_text:gmatch('\n') do count = count + 1 end
+    if count > 0 then
+      local ref_line = buffer:line_from_position(start)
+      local isize, ibase = buffer.indent, buffer.line_indentation[ref_line]
+      local inum = ibase / isize -- number of indents needed to match
+      for i = 1, count do
+        local linei = buffer.line_indentation[ref_line + i]
+        buffer.line_indentation[ref_line + i] = linei + isize * inum
+      end
+    end
+    buffer:end_undo_action()
+  end
+
+  return next_tab_stop() ~= false
+end
+
+---
+-- Goes back to the previous placeholder or tab stop, reverting changes made to
+-- subsequent ones.
+-- @return false if no snippet is active; nil otherwise
+function prev()
+  if not snippet.index then return false end -- no snippet active
+  local buffer = buffer
+  local index = snippet.index
+  if index > 1 then
+    local s_start, s_end = snippet_info()
+    local s_text = snippet.snapshots[index - 2]
+    buffer:set_sel(s_start, s_end)
+    buffer:replace_sel(s_text)
+    snippet.index = index - 2
+    next_tab_stop()
+  else
+    cancel_current()
+  end
+end
+
+---
+-- Cancels the active snippet, reverting to the state before its activation,
+-- and restores the previous running snippet (if any).
+function cancel_current()
+  if not snippet.index then return end
+  local buffer = buffer
+  local s_start, s_end = snippet_info()
+  buffer:begin_undo_action()
+  if s_start and s_end then
+    buffer:set_sel(s_start, s_end)
+    buffer:replace_sel('')
+    s_start, s_end = snippet_info()
+    buffer:goto_pos(s_end + 1)
+    buffer:delete_back()
+  end
+  if snippet.prev_sel_text then buffer:add_text(snippet.prev_sel_text) end
+  buffer:end_undo_action()
+  buffer:marker_delete_handle(snippet.end_marker)
+  snippet = #snippet_stack > 0 and table.remove(snippet_stack) or {}
+end
+
+---
+-- Lists available snippets in an autocompletion list.
+-- Global snippets and snippets in the current lexer and style are used.
+function list()
+  local buffer = buffer
+  local list = {}
+  local function add_snippets(snippets)
+    for s_name in pairs(snippets) do list[#list + 1] = s_name end
+  end
+  local snippets = _G.snippets
+  add_snippets(snippets)
+  local lexer = buffer:get_lexer_language()
+  local style = buffer:get_style_name(buffer.style_at[buffer.current_pos])
+  if snippets[lexer] and type(snippets[lexer]) == 'table' then
+    add_snippets(snippets[lexer])
+    if snippets[lexer][style] then add_snippets(snippets[lexer][style]) end
+  end
+  table.sort(list)
+  local caret = buffer.current_pos
+  buffer:auto_c_show(caret - buffer:word_start_position(caret, true),
+                     table.concat(list, string.char(buffer.auto_c_separator)))
+end
+
+---
+-- Shows the style at the current caret position in a call tip.
+function show_style()
+  local buffer = buffer
+  local lexer = buffer:get_lexer_language()
+  local style_num = buffer.style_at[buffer.current_pos]
+  local style = buffer:get_style_name(style_num)
+  local text =
+    string.format(locale.M_TEXTADEPT_SNIPPETS_SHOW_STYLE, lexer, style,
+                  style_num)
+  buffer:call_tip_show(buffer.current_pos, text)
+end
+
+textadept.user_dofile('snippets.lua') -- load user snippets