feat: Allow using setup to generate the keymaps

README.md

@@ -16,7 +16,7 @@ Impairative does provide, though, [an helper function that can be used to easily
 SETUP
 =====
 
-Install Impairative with your plugin manager of choice. There is no need to call `require'impairative'.setup`.
+Install Impairative with your plugin manager of choice. There is no need to call `require'impairative'.setup`, [but it can still be used as an entry point](#configuring-with-setup).
 
 CONTROLING OPTIONS
 ------------------
@@ -318,6 +318,66 @@ Impairative's version of the keymaps has several differences from unimpaired's b
 * unimpaired's `[n` and `]n` work as a text object when used after an operator. Imerative's version of them works as one would expect - regular motions.
 * Impairative, unlike unimpaired, has a `[N` and `]N` version that jumps to the first and last conflict markers.
 
+CONFIGURING WITH SETUP
+----------------------
+
+To support lazy.vim's `opts =` configuration style, Impairative's `setup` function can be used to set up the keymaps:
+
+```lua
+--- ***********************************
+--- *     I M P O R T A N T ! ! !     * 
+--- *                                 *
+--- * These are **NOT** the defaults! *
+--- * The defaults are to do nothing. *
+--- ***********************************
+require'impairative'.setup {
+    -- Configure toggling using an helper
+    enable = '[o',
+    disable = ']o',
+    toggle = 'yo',
+    toggling = function(h)
+        h:option {
+            key = 'n',
+            option = 'number',
+        }
+        h:option {
+            key = 'r',
+            option = 'relativenumber',
+        }
+        h:option {
+            key = 's',
+            option = 'spell',
+        }
+    end,
+
+    -- Configure operations using an helper
+    backward = '[',
+    forward = ']',
+    operations = function(h)
+        h:command_pair {
+            key = 'b',
+            backward = 'bprevious',
+            forward = 'bnext',
+        }
+        h:command_pair {
+            key = 'B',
+            backward = 'bfirst',
+            forward = 'blast',
+        }
+    end,
+
+    -- Defaults to false
+    replicate_unimpaired = true,
+}
+```
+
+The settings are grouped into three:
+
+1. `enable`, `disable`, `toggle`, and `toggling` - create a [toggling helper](#controling-options) and pass it to the function. If the mapping leaders are not specified, they'll default to `[o`, `]o`, and `yo`.
+2. `backward`, `forward`, and `operations` - create an [operations helper](#operation-pairs) and pass it to the function. If the mapping leaders are not specified, they'll default to `[` and `]`.
+3. `replicate_unimpaired` - [generate the keymaps from unimpaired](#usage-as-unimpaired-replacement).
+
+
 CONTRIBUTION GUIDELINES
 =======================
 

lua/impairative/init.lua

@@ -1,8 +1,36 @@
 ---@mod impairative Impairative - Pairs of complementing keybinds
 local M = {}
 
+---@class ImpairativeSetupArgs
+---@field enable? string Leader keys for turning settings on in `toggling` keymaps
+---@field disable? string Leader keys for turning settings off in `toggling` keymaps
+---@field toggle? string Leader keys for toggling settings in `toggling` keymaps
+---@field toggling? fun(helper: ImpairativeToggling)
+---@field backward? string Leader keys for turning the operation backward in `operations` keymaps
+---@field forward? string Leader keys for running the operation forward in `operations` keymaps
+---@field operations? fun(helper: ImpairativeOperations)
+---@field replicate_unimpaired? boolean
+local ImpairativeSetupArgs
+
 ---Doesn't do anything, but some plugins managers expect all plugins to have one.
-function M.setup()
+---@param args ImpairativeSetupArgs
+function M.setup(args)
+    if args.toggling then
+        args.toggling(M.toggling {
+            enable = args.enable or '[o',
+            disable = args.disable or ']o',
+            toggle = args.toggle or 'yo',
+        })
+    end
+    if args.operations then
+        args.operations(M.operations {
+            backward = args.backward or '[',
+            forward = args.forward or ']',
+        })
+    end
+    if args.replicate_unimpaired then
+        require'impairative.replicate-unimpaired'()
+    end
 end
 
 ---@param opts ImpairativeTogglingOptions

tests/impairative_setup_spec.lua

@@ -0,0 +1,102 @@
+describe('Impairative operations', function()
+    it('default leaders', function()
+        local data = {
+            field = false,
+            operations = {},
+        }
+
+        require'impairative'.setup {
+            toggling = function(h)
+                h:field {
+                    key = '!',
+                    table = data,
+                    field = 'field',
+                }
+            end,
+            operations = function(h)
+                h:unified_function {
+                    key = '!',
+                    fun = function(direction)
+                        table.insert(data.operations, direction)
+                    end,
+                }
+            end,
+        }
+
+        vim.api.nvim_feedkeys('[o!', 'mix', false)
+        assert.equal(data.field, true)
+        vim.api.nvim_feedkeys('[o!', 'mix', false)
+        assert.equal(data.field, true)
+
+        vim.api.nvim_feedkeys(']o!', 'mix', false)
+        assert.equal(data.field, false)
+        vim.api.nvim_feedkeys(']o!', 'mix', false)
+        assert.equal(data.field, false)
+
+        vim.api.nvim_feedkeys('yo!', 'mix', false)
+        assert.equal(data.field, true)
+        vim.api.nvim_feedkeys('yo!', 'mix', false)
+        assert.equal(data.field, false)
+
+        vim.api.nvim_feedkeys('[!', 'mix', false)
+        assert.are.same(data.operations, {'backward'})
+
+        vim.api.nvim_feedkeys(']!', 'mix', false)
+        assert.are.same(data.operations, {'backward', 'forward'})
+    end)
+
+    it('custom leaders', function()
+        local data = {
+            field = false,
+            operations = {},
+        }
+
+        require'impairative'.setup {
+            enable = '<M-[>o',
+            disable = '<M-]>o',
+            toggle = '<M-y>o',
+            toggling = function(h)
+                h:field {
+                    key = '@',
+                    table = data,
+                    field = 'field',
+                }
+            end,
+            backward = '<M-[>',
+            forward = '<M-]>',
+            operations = function(h)
+                h:unified_function {
+                    key = '@',
+                    fun = function(direction)
+                        table.insert(data.operations, direction)
+                    end,
+                }
+            end,
+        }
+
+        local function feedkeys(keys)
+            vim.api.nvim_feedkeys(vim.api.nvim_replace_termcodes(keys, true, false, true), 'mix', true)
+        end
+
+        feedkeys('<M-[>o@')
+        assert.equal(data.field, true)
+        feedkeys('<M-[>o@')
+         assert.equal(data.field, true)
+
+        feedkeys('<M-]>o@')
+        assert.equal(data.field, false)
+        feedkeys('<M-]>o@')
+        assert.equal(data.field, false)
+
+        feedkeys('<M-y>o@')
+        assert.equal(data.field, true)
+        feedkeys('<M-y>o@')
+        assert.equal(data.field, false)
+
+        feedkeys('<M-[>@')
+        assert.are.same(data.operations, {'backward'})
+
+        feedkeys('<M-]>@')
+        assert.are.same(data.operations, {'backward', 'forward'})
+    end)
+end)