feat(lsp): add snippet API (#25301)

runtime/doc/lua.txt

@@ -3670,4 +3670,63 @@ totable({f}, {...})                                       *vim.iter.totable()*
     Return: ~
         (table)
 
+
+==============================================================================
+Lua module: vim.snippet                                          *vim.snippet*
+
+active()                                                    *snippet.active()*
+    Returns `true` if there's an active snippet in the current buffer.
+
+    Return: ~
+        (boolean)
+
+exit()                                                        *snippet.exit()*
+    Exits the current snippet.
+
+expand({input})                                             *snippet.expand()*
+    Expands the given snippet text. Refer to https://microsoft.github.io/language-server-protocol/specification/#snippet_syntax for the specification of valid input.
+
+    Tabstops are highlighted with hl-SnippetTabstop.
+
+    Parameters: ~
+      • {input}  (string)
+
+jump({direction})                                             *snippet.jump()*
+    Jumps within the active snippet in the given direction. If the jump isn't
+    possible, the function call does nothing.
+
+    You can use this function to navigate a snippet as follows: >lua
+        vim.keymap.set({ 'i', 's' }, '<Tab>', function()
+           if vim.snippet.jumpable(1) then
+             return '<cmd>lua vim.snippet.jump(1)<cr>'
+           else
+             return '<Tab>'
+           end
+         end, { expr = true })
+<
+
+    Parameters: ~
+      • {direction}  (vim.snippet.Direction) Navigation direction. -1 for
+                     previous, 1 for next.
+
+jumpable({direction})                                     *snippet.jumpable()*
+    Returns `true` if there is an active snippet which can be jumped in the
+    given direction. You can use this function to navigate a snippet as
+    follows: >lua
+        vim.keymap.set({ 'i', 's' }, '<Tab>', function()
+           if vim.snippet.jumpable(1) then
+             return '<cmd>lua vim.snippet.jump(1)<cr>'
+           else
+             return '<Tab>'
+           end
+         end, { expr = true })
+<
+
+    Parameters: ~
+      • {direction}  (vim.snippet.Direction) Navigation direction. -1 for
+                     previous, 1 for next.
+
+    Return: ~
+        (boolean)
+
  vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

runtime/doc/news.txt

@@ -193,6 +193,8 @@ The following new APIs and features were added.
 
 • Added |:fclose| command.
 
+• Added |vim.snippet| for snippet expansion support.
+
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*
 

runtime/lua/vim/_editor.lua

@@ -38,6 +38,7 @@ for k, v in pairs({
   ui = true,
   health = true,
   secure = true,
+  snippet = true,
   _watch = true,
 }) do
   vim._submodules[k] = v

runtime/lua/vim/_meta.lua

@@ -19,6 +19,7 @@ vim.loader = require('vim.loader')
 vim.lsp = require('vim.lsp')
 vim.re = require('vim.re')
 vim.secure = require('vim.secure')
+vim.snippet = require('vim.snippet')
 vim.treesitter = require('vim.treesitter')
 vim.ui = require('vim.ui')
 vim.version = require('vim.version')

runtime/lua/vim/lsp/_snippet_grammar.lua

@@ -81,22 +81,48 @@ local Type = {
 M.NodeType = Type
 
 --- @class vim.snippet.Node<T>: { type: vim.snippet.Type, data: T }
---- @class vim.snippet.TabstopData: { tabstop: number }
+--- @class vim.snippet.TabstopData: { tabstop: integer }
 --- @class vim.snippet.TextData: { text: string }
---- @class vim.snippet.PlaceholderData: { tabstop: vim.snippet.TabstopData, value: vim.snippet.Node<any> }
---- @class vim.snippet.ChoiceData: { tabstop: vim.snippet.TabstopData, values: string[] }
+--- @class vim.snippet.PlaceholderData: { tabstop: integer, value: vim.snippet.Node<any> }
+--- @class vim.snippet.ChoiceData: { tabstop: integer, values: string[] }
 --- @class vim.snippet.VariableData: { name: string, default?: vim.snippet.Node<any>, regex?: string, format?: vim.snippet.Node<vim.snippet.FormatData|vim.snippet.TextData>[], options?: string }
 --- @class vim.snippet.FormatData: { capture: number, modifier?: string, if_text?: string, else_text?: string }
 --- @class vim.snippet.SnippetData: { children: vim.snippet.Node<any>[] }
 
+--- @type vim.snippet.Node<any>
+local Node = {}
+
+--- @return string
+--- @diagnostic disable-next-line: inject-field
+function Node:__tostring()
+  local node_text = {}
+  local type, data = self.type, self.data
+  if type == Type.Snippet then
+    --- @cast data vim.snippet.SnippetData
+    for _, child in ipairs(data.children) do
+      table.insert(node_text, tostring(child))
+    end
+  elseif type == Type.Choice then
+    --- @cast data vim.snippet.ChoiceData
+    table.insert(node_text, data.values[1])
+  elseif type == Type.Placeholder then
+    --- @cast data vim.snippet.PlaceholderData
+    table.insert(node_text, tostring(data.value))
+  elseif type == Type.Text then
+    --- @cast data vim.snippet.TextData
+    table.insert(node_text, data.text)
+  end
+  return table.concat(node_text)
+end
+
 --- Returns a function that constructs a snippet node of the given type.
 ---
 --- @generic T
 --- @param type vim.snippet.Type
 --- @return fun(data: T): vim.snippet.Node<T>
 local function node(type)
   return function(data)
-    return { type = type, data = data }
+    return setmetatable({ type = type, data = data }, Node)
   end
 end
 

runtime/lua/vim/lsp/protocol.lua

@@ -742,7 +742,6 @@ function protocol.make_client_capabilities()
           -- this should be disabled out of the box.
           -- However, users can turn this back on if they have a snippet plugin.
           snippetSupport = false,
-
           commitCharactersSupport = false,
           preselectSupport = false,
           deprecatedSupport = false,

runtime/lua/vim/lsp/util.lua

@@ -616,35 +616,7 @@ function M.parse_snippet(input)
     return input
   end
 
-  --- @param node vim.snippet.Node<any>
-  --- @return string
-  local function node_to_string(node)
-    local insert_text = {}
-    if node.type == snippet.NodeType.Snippet then
-      for _, child in
-        ipairs((node.data --[[@as vim.snippet.SnippetData]]).children)
-      do
-        table.insert(insert_text, node_to_string(child))
-      end
-    elseif node.type == snippet.NodeType.Choice then
-      table.insert(insert_text, (node.data --[[@as vim.snippet.ChoiceData]]).values[1])
-    elseif node.type == snippet.NodeType.Placeholder then
-      table.insert(
-        insert_text,
-        node_to_string((node.data --[[@as vim.snippet.PlaceholderData]]).value)
-      )
-    elseif node.type == snippet.NodeType.Text then
-      table.insert(
-        insert_text,
-        node
-          .data --[[@as vim.snippet.TextData]]
-          .text
-      )
-    end
-    return table.concat(insert_text)
-  end
-
-  return node_to_string(parsed)
+  return tostring(parsed)
 end
 
 --- Sorts by CompletionItem.sortText.