feat: add labels to surrounds (#449)

Add labels to surrounds. This will be useful to plugins that show key
hints. For discussion, see
#447.

Author: gregorias

doc/nvim-surround.txt

@@ -401,6 +401,7 @@ surrounds, for example setting up a `$` surround, but only in bash files:
                 add = { "${", "}" },
                 find = "$%b{}",
                 delete = "^(..)().-(.)()$",
+                label = "${…}",
             },
         },
     })
@@ -540,6 +541,9 @@ containing the following keys:
     are directly used as the replacement pair. For example, when changing HTML
     tag types, only `cst` is needed, instead of `cstt`.
 
+                                         *nvim-surround.setup.surrounds.label*
+    label: ~
+        An optional string that represents the label for the surround.
 
                           *nvim-surround.setup.surrounds.invalid_key_behavior*
 `invalid_key_behavior` is a special key in the `surrounds` table that defines

lua/nvim-surround/annotations.lua

@@ -29,6 +29,7 @@
 ---@field find find_func
 ---@field delete delete_func
 ---@field change change_table
+---@field label? string
 
 ---@class options
 ---@field surrounds table<string, surround>
@@ -51,6 +52,7 @@
 ---@field find? user_find
 ---@field delete? user_delete
 ---@field change? user_change
+---@field label? string
 
 ---@class user_options
 ---@field surrounds? table<string, false|user_surround>

lua/nvim-surround/config.lua

@@ -9,76 +9,87 @@ M.default_opts = {
                 return M.get_selection({ motion = "a(" })
             end,
             delete = "^(. ?)().-( ?.)()$",
+            label = "( ... )",
         },
         [")"] = {
             add = { "(", ")" },
             find = function()
                 return M.get_selection({ motion = "a)" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "(...)",
         },
         ["{"] = {
             add = { "{ ", " }" },
             find = function()
                 return M.get_selection({ motion = "a{" })
             end,
             delete = "^(. ?)().-( ?.)()$",
+            label = "{ ... }",
         },
         ["}"] = {
             add = { "{", "}" },
             find = function()
                 return M.get_selection({ motion = "a}" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "{...}",
         },
         ["<"] = {
             add = { "< ", " >" },
             find = function()
                 return M.get_selection({ motion = "a<" })
             end,
             delete = "^(. ?)().-( ?.)()$",
+            label = "< ... >",
         },
         [">"] = {
             add = { "<", ">" },
             find = function()
                 return M.get_selection({ motion = "a>" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "<...>",
         },
         ["["] = {
             add = { "[ ", " ]" },
             find = function()
                 return M.get_selection({ motion = "a[" })
             end,
             delete = "^(. ?)().-( ?.)()$",
+            label = "[ ... ]",
         },
         ["]"] = {
             add = { "[", "]" },
             find = function()
                 return M.get_selection({ motion = "a]" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "[...]",
         },
         ["'"] = {
             add = { "'", "'" },
             find = function()
                 return M.get_selection({ motion = "a'" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "'...'",
         },
         ['"'] = {
             add = { '"', '"' },
             find = function()
                 return M.get_selection({ motion = 'a"' })
             end,
             delete = "^(.)().-(.)()$",
+            label = '"..."',
         },
         ["`"] = {
             add = { "`", "`" },
             find = function()
                 return M.get_selection({ motion = "a`" })
             end,
             delete = "^(.)().-(.)()$",
+            label = "`...`",
         },
         ["i"] = { -- TODO: Add find/delete/change functions
             add = function()
@@ -90,6 +101,7 @@ M.default_opts = {
             end,
             find = function() end,
             delete = function() end,
+            label = "?...?",
         },
         ["t"] = {
             add = function()
@@ -123,6 +135,7 @@ M.default_opts = {
                     end
                 end,
             },
+            label = "<tag>...</tag>",
         },
         ["T"] = {
             add = function()
@@ -156,6 +169,7 @@ M.default_opts = {
                     end
                 end,
             },
+            label = "<tag>...</tag>",
         },
         ["f"] = {
             add = function()
@@ -188,6 +202,7 @@ M.default_opts = {
                     end
                 end,
             },
+            label = "function(...)",
         },
         invalid_key_behavior = {
             -- By default, we ignore control characters for adding/finding because they are more likely typos than
@@ -485,6 +500,7 @@ M.translate_surround = function(char, user_surround)
         find = M.translate_find(user_surround.find),
         delete = M.translate_delete(char, user_surround.delete),
         change = M.translate_change(char, user_surround.change),
+        label = user_surround.label,
     }
 end