WIP Integrations API Proposal (+ whichkey and mapper integrations)

.gitignore

@@ -1 +1,2 @@
 testdata/
+.DS_Store

Makefile

@@ -0,0 +1,9 @@
+test:
+	nvim --headless --noplugin -u tests/minimal.lua -c "PlenaryBustedDirectory tests/ {minimal_init = 'tests/minimal.lua'}"
+test-head:
+	nvim --noplugin -u tests/minimal.lua
+watch: 
+	onchange "./lua/**/*.lua" -- make run
+watch-test:
+	onchange "./**/*.(lua|scm)" -- make test
+

README.md

@@ -217,6 +217,58 @@ Has the same named fields as `keymapConfig`, with an additional field:
 
 Sets a `string` prefix to be applied to all keymap inputs.
 
+## Plugin Integrations
+
+Nest.nvim can integrate with other plugins.  See `lua/nest/integrations/example.lua` to build your own.
+
+### nvim-mapper
+
+Add `nest.enable(require('nest.integrations.mapper'))` before you run `applyKeymaps`.
+
+#### Additional config
+
+- `[3]|name string` A short name for the keymap or keymap group
+- `[4]|description string` (optional) A longer description for the keymap or keymap group
+  - If not provided the `name` field will be used
+- `uid string` (optional) A unique identifier for the nvim mapper config
+  - If not provided one will be generated from `name`
+- `category string` (optional) A general category for the keymap group
+  - If not provided it will fallback to the `name` of the parent keymap group
+  - If no parent group the category will be `'unknown'`
+
+#### Example
+```lua
+local nest = require('nest')
+nest.enable(require('nest.integrations.mapper'))
+nest.applyKeymaps {
+    { '<leader>', {
+        { 'f', '<cmd>Telescope find_files<cr>', 'Find Files'}, -- Minimal
+        { 'g', '<cmd>Telescope live_grep<cr>', 'Live Grep', 'Searches for a string within project files', uid = 'search_live_grep', category = 'search'}, -- Maximal
+    }},
+}
+```
+
+### which-key.nvim
+
+Add `nest.enable(require('nest.integrations.whichkey'))` before you run `applyKeymaps`.
+
+#### Additional config
+
+- `[3]|name string` A short name for the keymap or keymap group
+
+#### Example
+```lua
+local nest = require('nest')
+nest.enable(require('nest.integrations.whichkey'))
+nest.applyKeymaps {
+    { '<leader>', {
+        { 'f', name = '+File',  { -- Can be used as field
+            { 'f', '<cmd>Telescope find_files<cr>', 'Find Files'}, -- Or as the 3rd element in table
+        }}
+    }},
+}
+```
+
 ## Planned Features
 
 See issues and milestones

lua/nest.lua

@@ -1,7 +1,53 @@
 local module = {}
 
+--[[
+--     TYPES
+--]]
+
+--- Extra options that will be passed to nvim when binding keymaps 
+--- @class NestSettingsOptions
+--- @field noremap boolean
+--- @field silent boolean
+--- @field expr boolean
+
+--- Stores the current keymap state/settings including lhs/prefix
+--- @class NestSettings
+--- @field buffer boolean|number
+--- @field prefix string
+--- @field options NestSettingsOptions
+--- @field mode string
+
+--- Internal type for a node in a nest.nvim config, this is how the end-user will define their config
+--- @class NestNode : NestSettings
+--- @field [1] string|table<number, NestNode>
+--- @field [2] string|function|table<number,NestNode>
+--- @field [3] string|nil Name
+--- @field name string|nil Name
+--- @field [4] string|nil Description
+--- @field description string|nil Description
+
+--- Type definition for nest.nvim integration
+--- @class NestIntegration
+--- @field name string
+--- @field on_init function|nil
+--- @field handler function
+--- @field on_complete function|nil
+
+--- Paramater passed to handler of NestIntegration
+--- @class NestIntegrationNode
+--- @field lhs string
+--- @field rhs table<number, NestNode>|string
+--- @field name string
+--- @field description string
+
+
+--[[
+--     UTILS
+--]]
+
 --- Defaults being applied to `applyKeymaps`
 -- Can be modified to change defaults applied.
+--- @type NestSettings
 module.defaults = {
     mode = 'n',
     prefix = '',
@@ -24,6 +70,10 @@ module._getRhsExpr = function(index)
     return vim.api.nvim_replace_termcodes(keys, true, true, true)
 end
 
+--- Converts a lua function to a string that can be called to execute the function
+--- @param func function
+--- @param expr boolean
+--- @return string
 local function functionToRhs(func, expr)
     table.insert(rhsFns, func)
 
@@ -35,26 +85,17 @@ local function functionToRhs(func, expr)
 end
 
 local function copy(table)
-    local ret = {}
-
-    for key, value in pairs(table) do
-        ret[key] = value
-    end
-
-    return ret
+  return vim.deepcopy(table)
 end
 
 local function mergeTables(left, right)
-    local ret = copy(left)
-
-    for key, value in pairs(right) do
-        ret[key] = value
-    end
-
-    return ret
+  return vim.tbl_extend('force', left, right)
 end
 
-local function mergeOptions(left, right)
+--- @param left NestSettings
+--- @param right NestSettings
+--- @return NestSettings
+local function mergeSettings(left, right)
     local ret = copy(left)
 
     if right == nil then
@@ -80,63 +121,134 @@ local function mergeOptions(left, right)
     return ret
 end
 
---- Applies the given `keymapConfig`, creating nvim keymaps
-module.applyKeymaps = function (config, presets)
-    local mergedPresets = mergeOptions(
-        presets or module.defaults,
-        config
-    )
-
-    local first = config[1]
+--[[
+--     INTEGRATIONS
+--]]
+-- Stores all the different handlers for the nest API
+module.integrations = {}
+
+-- Allows adding extra keymap integrations
+--- @param integration NestIntegration
+module.enable = function(integration)
+  if integration.name ~= nil then
+    module.integrations[integration.name] = integration
+  end
+end
 
-    if type(first) == 'table' then
-        for _, it in ipairs(config) do
-            module.applyKeymaps(it, mergedPresets)
-        end
 
-        return
+--- Default nest integration that binds keymaps
+--- @type NestIntegration
+local default_integration = {}
+default_integration.name = 'nest'
+default_integration.handler = function (node, node_settings)
+  -- Skip tables (keymap groups)
+  if type(node.rhs) == 'table' then
+    return
+  end
+
+  for mode in string.gmatch(node_settings.mode, '.') do
+    local sanitizedMode = mode == '_'
+      and ''
+      or mode
+
+    if node_settings.buffer then
+      local buffer = (node_settings.buffer == true)
+        and 0
+        or node_settings.buffer
+
+      vim.api.nvim_buf_set_keymap(
+        buffer,
+        sanitizedMode,
+        node.lhs,
+        node.rhs,
+        node_settings.options
+      )
+    else
+      vim.api.nvim_set_keymap(
+        sanitizedMode,
+        node.lhs,
+        node.rhs,
+        node_settings.options
+      )
     end
+  end
+end
+-- Bind default_integration keymap handler
+module.enable(default_integration)
+
+--[[
+--     TRAVERSING CONFIG
+--]]
+
+--- @param node NestNode
+--- @param settings NestSettings
+module.traverse = function(node, settings, integrations)
+  local mergedSettings = mergeSettings(settings or module.defaults, node)
+
+  local first = node[1]
+
+  -- Top level of config, just traverse into each keymap/keymap group
+  if type(first) == 'table' then
+      for _, sub_node in ipairs(node) do
+          module.traverse(sub_node, mergedSettings, integrations)
+      end
+      return
+  end
+
+  -- First must be a string, append first to the prefix
+  mergedSettings.prefix = mergedSettings.prefix .. first
+  local second = node[2]
+
+  --- @type string|table<number, NestNode>
+  local rhs = type(second) == 'function'
+    and functionToRhs(second, mergedSettings.options.expr)
+    or second
+
+  -- Populate node.name and node.description if necessary
+  if node.name == nil and #node >= 3 then
+    node.name = node[3]
+  end
+  if node.description == nil and #node>=4 then
+    node.description = node[4]
+  end
+  node.lhs = mergedSettings.prefix
+  node.rhs = rhs
+
+  -- Pass current keymap node to all integrations
+  for _, integration in pairs(integrations) do
+    integration.handler(node, mergedSettings)
+  end
+
+  if type(rhs) == 'table' then
+    module.traverse(rhs, mergedSettings, integrations)
+  end
+end
 
-    local second = config[2]
-
-    mergedPresets.prefix = mergedPresets.prefix .. first
 
-    if type(second) == 'table' then
-        module.applyKeymaps(second, mergedPresets)
+--[[
+--    ENTRY POINT
+--]]
 
-        return
+--- Applies the given `keymapConfig`, creating nvim keymaps
+--- @param nest_config table<number, NestNode>
+--- @param settings NestSettings 
+--- @param integrations table<number, NestIntegration> User can parse the nest config with a subset of integrations
+module.applyKeymaps = function(nest_config, settings, integrations)
+  local ints = integrations or module.integrations
+  -- Run on init for each integration
+  for _, integration in pairs(ints) do
+    if integration.on_init ~= nil then
+      integration.on_init(nest_config, settings)
     end
+  end
+
+  module.traverse(nest_config, settings, ints)
 
-    local rhs = type(second) == 'function'
-        and functionToRhs(second, mergedPresets.options.expr)
-        or second
-
-    for mode in string.gmatch(mergedPresets.mode, '.') do
-        local sanitizedMode = mode == '_'
-            and ''
-            or mode
-
-        if mergedPresets.buffer then
-            local buffer = (mergedPresets.buffer == true)
-                and 0
-                or mergedPresets.buffer
-
-            vim.api.nvim_buf_set_keymap(
-                buffer,
-                sanitizedMode,
-                mergedPresets.prefix,
-                rhs,
-                mergedPresets.options
-            )
-        else
-            vim.api.nvim_set_keymap(
-                sanitizedMode,
-                mergedPresets.prefix,
-                rhs,
-                mergedPresets.options
-            )
-        end
+  for _, integration in pairs(ints) do
+    if integration.on_complete ~= nil then
+      integration.on_complete()
     end
+  end
 end
 
 return module