feat!: <Plug> mappings (#98)

Following are the plug mappings that are now available

`<Plug>(comment_toggle_linewise_count)` - Toggles line comment with count
`<Plug>(comment_toggle_blockwise_count)` - Toggles block comment with count
`<Plug>(comment_toggle_current_linewise)` - Toggles line comment on the current line
`<Plug>(comment_toggle_current_blockwise)` - Toggles block comment on the current line
`<Plug>(comment_toggle_linewise)` - Toggles line comment via Operator pending mode
`<Plug>(comment_toggle_blockwise)` - Toggles block comment via Operator pending mode
`<Plug>(comment_toggle_linewise_visual)` - Toggles line comment in VISUAL mode
`<Plug>(comment_toggle_blockwise_visual)` - Toggles block comment in VISUAL mode

Read https://github.com/numToStr/Comment.nvim/blob/master/doc/plugs.md

---

This is a breaking change for nvim 0.6 users. So If you are using 0.6 please follow https://github.com/numToStr/Comment.nvim/releases/tag/v0.6

Author: numToStr

README.md

@@ -111,7 +111,8 @@ Following are the **default** config for the [`setup()`](#setup). If you want to
     },
 
     ---Create basic (operator-pending) and extended mappings for NORMAL + VISUAL mode
-    ---@type table
+    ---NOTE: If `mappings = false` then the plugin won't create any mappings
+    ---@type boolean|table
     mappings = {
         ---Operator-pending mapping
         ---Includes `gcc`, `gbc`, `gc[count]{motion}` and `gb[count]{motion}`
@@ -225,7 +226,9 @@ These mappings are disabled by default. (config: `mappings.extended`)
 
 ### ⚙️ API
 
-Read [doc/API.md](./doc/API.md) to see all the API/functions that are exported from the plugin.
+- [Plug Mappings](./doc/plugs.md) - Excellent for creating custom keybindings
+
+- [Lua API](./doc/API.md) - Details the Lua API. Great for making custom comment function.
 
 <a id="treesitter"></a>
 

after/plugin/Comment.lua

@@ -0,0 +1,41 @@
+local K = vim.keymap.set
+
+-- Count mappings
+K(
+    'n',
+    '<Plug>(comment_toggle_linewise_count)',
+    '<CMD>lua require("Comment.api").call("toggle_linewise_count_op")<CR>g@$'
+)
+K(
+    'n',
+    '<Plug>(comment_toggle_blockwise_count)',
+    '<CMD>lua require("Comment.api").call("toggle_blockwise_count_op")<CR>g@$'
+)
+
+-- Toggle mappings
+K(
+    'n',
+    '<Plug>(comment_toggle_current_linewise)',
+    '<CMD>lua require("Comment.api").call("toggle_current_linewise_op")<CR>g@$'
+)
+K(
+    'n',
+    '<Plug>(comment_toggle_current_blockwise)',
+    '<CMD>lua require("Comment.api").call("toggle_current_blockwise_op")<CR>g@$'
+)
+
+-- Operator-Pending mappings
+K('n', '<Plug>(comment_toggle_linewise)', '<CMD>lua require("Comment.api").call("toggle_linewise_op")<CR>g@')
+K('n', '<Plug>(comment_toggle_blockwise)', '<CMD>lua require("Comment.api").call("toggle_blockwise_op")<CR>g@')
+
+-- Visual-Mode mappings
+K(
+    'x',
+    '<Plug>(comment_toggle_linewise_visual)',
+    '<ESC><CMD>lua require("Comment.api").locked.toggle_linewise_op(vim.fn.visualmode())<CR>'
+)
+K(
+    'x',
+    '<Plug>(comment_toggle_blockwise_visual)',
+    '<ESC><CMD>lua require("Comment.api").locked.toggle_blockwise_op(vim.fn.visualmode())<CR>'
+)

doc/API.md

@@ -63,23 +63,23 @@ These APIs powers the [extra-mappings](../README.md#extra-mappings) and also pro
 ---@param cfg? Config
 require('Comment.api').insert_linewise_below(cfg)
 
----Insert a blockwise-comment below
----@param cfg? Config
-require('Comment.api').insert_blockwise_below(cfg)
-
 ---Insert a linewise-comment above
 ---@param cfg? Config
 require('Comment.api').insert_linewise_above(cfg)
 
+---Insert a linewise-comment at the end-of-line
+---@param cfg? Config
+require('Comment.api').insert_linewise_eol(cfg)
+
 --######### BLOCKWISE #########--
 
----Insert a blockwise-comment above
+---Insert a blockwise-comment below
 ---@param cfg? Config
-require('Comment.api').insert_blockwise_above(cfg)
+require('Comment.api').insert_blockwise_below(cfg)
 
----Insert a linewise-comment at the end-of-line
+---Insert a blockwise-comment above
 ---@param cfg? Config
-require('Comment.api').insert_linewise_eol(cfg)
+require('Comment.api').insert_blockwise_above(cfg)
 
 ---Insert a blockwise-comment at the end-of-line
 ---@param cfg? Config
@@ -158,37 +158,31 @@ require('Comment.api').call(cb)
 Following are some example keybindings using the APIs.
 
 ```lua
-local function map(mode, lhs, rhs)
-    vim.api.nvim_set_keymap(mode, lhs, rhs, { noremap = true, silent = true })
-end
-
----
-
 -- # NORMAL mode
 
 -- Linewise toggle current line using C-/
-map('n', '<C-_>', '<CMD>lua require("Comment.api").toggle_current_linewise()<CR>')
+vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").toggle_current_linewise()<CR>')
 -- or with dot-repeat support
--- map('n', '<C-_>', '<CMD>lua require("Comment.api").call("toggle_current_linewise_op")<CR>g@$')
+-- vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").call("toggle_current_linewise_op")<CR>g@$')
 
 -- Blockwise toggle current line using C-\
-map('n', '<C-\\>', '<CMD>lua require("Comment.api").toggle_current_blockwise()<CR>')
+vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").toggle_current_blockwise()<CR>')
 -- or with dot-repeat support
--- map('n', '<C-\\>', '<CMD>lua require("Comment.api").call("toggle_current_blockwise_op")<CR>g@$')
+-- vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").call("toggle_current_blockwise_op")<CR>g@$')
 
 -- Linewise toggle multiple line using <leader>gc with dot-repeat support
 -- Example: <leader>gc3j will comment 4 lines
-map('n', '<leader>gc', '<CMD>lua require("Comment.api").call("toggle_linewise_op")<CR>g@')
+vim.keymap.set('n', '<leader>gc', '<CMD>lua require("Comment.api").call("toggle_linewise_op")<CR>g@')
 
 -- Blockwise toggle multiple line using <leader>gc with dot-repeat support
 -- Example: <leader>gb3j will comment 4 lines
-map('n', '<leader>gb', '<CMD>lua require("Comment.api").call("toggle_blockwise_op")<CR>g@')
+vim.keymap.set('n', '<leader>gb', '<CMD>lua require("Comment.api").call("toggle_blockwise_op")<CR>g@')
 
 -- # VISUAL mode
 
 -- Linewise toggle using C-/
-map('x', '<C-_>', '<ESC><CMD>lua require("Comment.api").toggle_linewise_op(vim.fn.visualmode())<CR>')
+vim.keymap.set('x', '<C-_>', '<ESC><CMD>lua require("Comment.api").toggle_linewise_op(vim.fn.visualmode())<CR>')
 
 -- Blockwise toggle using <leader>gb
-map('x', '<leader>gb', '<ESC><CMD>lua require("Comment.api").toggle_blockwise_op(vim.fn.visualmode())<CR>')
+vim.keymap.set('x', '<leader>gb', '<ESC><CMD>lua require("Comment.api").toggle_blockwise_op(vim.fn.visualmode())<CR>')
 ```

doc/plugs.md

@@ -0,0 +1,34 @@
+## 🔌 Plug Mappings
+
+Following are the `<Plug>` mappings which you can use to quickly setup your custom keybindings
+
+- `<Plug>(comment_toggle_linewise_count)` - Toggles line comment with count
+- `<Plug>(comment_toggle_blockwise_count)` - Toggles block comment with count
+- `<Plug>(comment_toggle_current_linewise)` - Toggles line comment on the current line
+- `<Plug>(comment_toggle_current_blockwise)` - Toggles block comment on the current line
+- `<Plug>(comment_toggle_linewise)` - Toggles line comment via Operator pending mode
+- `<Plug>(comment_toggle_blockwise)` - Toggles block comment via Operator pending mode
+- `<Plug>(comment_toggle_linewise_visual)` - Toggles line comment in VISUAL mode
+- `<Plug>(comment_toggle_blockwise_visual)` - Toggles block comment in VISUAL mode
+
+> NOTE: There are only meant for custom keybindings but If you want to create a custom comment function then be sure to check out all the [API](./API.md).
+
+#### Usage
+
+Following snippets is same as the default mappings set by the plugin.
+
+```lua
+local opt = { expr = true, remap = true }
+
+-- Toggle using count
+vim.keymap.set('n', 'gcc', "v:count == 0 ? '<Plug>(comment_toggle_current_linewise)' : '<Plug>(comment_toggle_linewise_count)'", opt)
+vim.keymap.set('n', 'gbc', "v:count == 0 ? '<Plug>(comment_toggle_current_blockwise)' : '<Plug>(comment_toggle_blockwise_count)'", opt)
+
+-- Toggle in Op-pending mode
+vim.keymap.set('n', 'gc', '<Plug>(comment_toggle_linewise)')
+vim.keymap.set('n', 'gb', '<Plug>(comment_toggle_blockwise)')
+
+-- Toggle in VISUAL mode
+vim.keymap.set('x', 'gc', '<Plug>(comment_toggle_linewise_visual)')
+vim.keymap.set('x', 'gb', '<Plug>(comment_toggle_blockwise_visual)')
+```

dump.lua

@@ -20,9 +20,10 @@
 -- [x] Disable `extra` mapping by default
 -- [x] Provide more arguments to pre and post hooks
 -- [x] `ignore` as a function
+-- [x] Return the operator's starting and ending position in pre and post hook
+-- [x] Restore cursor position in some motion operator (try `gcip`)
 -- [ ] Doc comment ie. /** */ (for js)
 -- [ ] Header comment
--- [ ] Dot support for `[count]gcc`
 
 -- FIXME
 -- [x] visual mode not working correctly
@@ -37,20 +38,19 @@
 -- [x] Optimize blockwise mode (just modifiy the start and end line)
 -- [x] Weird commenting when the first line is empty and the whole is indented
 -- [x] no padding support in block-x
--- [ ] Dot repeat support for visual mode mappings
--- [ ] Weird comments, if you do comments on already commented lines incl. an extra empty line
 
 -- THINK:
--- [x] Should i return the operator's starting and ending position in pre-hook
--- [x] Restore cursor position in some motion operator (try `gcip`)
--- 3. It is possible that, commentstring is updated inside pre-hook as we want to use it but we can't
---    bcz the filetype is also present in the lang-table (and it has high priority than vim.bo.commentstring)
--- 4. When there is an uncommented empty line b/w two commented blocks. It should uncomment instead of commenting again in toggle.
--- 5. Conflict when uncommenting interchangebly with line/block wise comment
--- 6. `ignore` is missing in blockwise and blockwise_x but on the other hand this doesn't make much sense
--- 7. Parse `comments` if block comment is missing in the plugin
+-- [ ] Dot support for `[count]gcc` and `[count]gbc`
+-- [ ] Parse `comments` if block comment is missing in the plugin
+
+-- ITS_OK:
+-- 1. Weird comments, if you do comments on already commented lines incl. an extra empty line
+-- 2. Conflict when uncommenting interchangebly with line/block wise comment
+-- 3. `ignore` doesn't work in blockwise and blockwise_x
+-- 4. When a empty line is b/w two commented blocks then it should uncomment instead of commenting again in toggle.
 
 -- DROPPED:
--- Insert mode mapping (also move the cursor after commentstring)
--- Use `nvim_buf_get_text` instead of `nvim_buf_get_lines`. Blocked by https://github.com/neovim/neovim/pull/15181
--- Use `nvim_buf_set_text` instead of `nvim_buf_set_lines`
+-- 1. Insert mode mapping (also move the cursor after commentstring)
+-- 2. Use `nvim_buf_get_text` instead of `nvim_buf_get_lines`. Blocked by https://github.com/neovim/neovim/pull/15181
+-- 3. Use `nvim_buf_set_text` instead of `nvim_buf_set_lines`
+-- 4. Dot repeat support for visual mode mappings (Doesn't make sense)

lua/Comment/api.lua

@@ -234,74 +234,53 @@ function C.setup(config)
     local cfg = Config:set(config):get()
 
     if cfg.mappings then
-        local map = A.nvim_set_keymap
-        local map_opt = { noremap = true, silent = true }
+        local K = vim.keymap.set
 
         -- Basic Mappings
         if cfg.mappings.basic then
-            local expr = { noremap = true, silent = true, expr = true }
             -- NORMAL mode mappings
-            map(
+            K(
                 'n',
                 cfg.toggler.line,
-                [[v:count == 0 ? '<CMD>lua require("Comment.api").call("toggle_current_linewise_op")<CR>g@$' : '<CMD>lua require("Comment.api").call("toggle_linewise_count_op")<CR>g@$']],
-                expr
+                "v:count == 0 ? '<Plug>(comment_toggle_current_linewise)' : '<Plug>(comment_toggle_linewise_count)'",
+                { expr = true, remap = true }
             )
-            map(
+            K(
                 'n',
                 cfg.toggler.block,
-                [[v:count == 0 ? '<CMD>lua require("Comment.api").call("toggle_current_blockwise_op")<CR>g@$' : '<CMD>lua require("Comment.api").call("toggle_blockwise_count_op")<CR>g@$']],
-                expr
+                "v:count == 0 ? '<Plug>(comment_toggle_current_blockwise)' : '<Plug>(comment_toggle_blockwise_count)'",
+                { expr = true, remap = true }
             )
-            map('n', cfg.opleader.line, '<CMD>lua require("Comment.api").call("toggle_linewise_op")<CR>g@', map_opt)
-            map('n', cfg.opleader.block, '<CMD>lua require("Comment.api").call("toggle_blockwise_op")<CR>g@', map_opt)
+
+            K('n', cfg.opleader.line, '<Plug>(comment_toggle_linewise)')
+            K('n', cfg.opleader.block, '<Plug>(comment_toggle_blockwise)')
 
             -- VISUAL mode mappings
-            map(
-                'x',
-                cfg.opleader.line,
-                '<ESC><CMD>lua require("Comment.api").locked.toggle_linewise_op(vim.fn.visualmode())<CR>',
-                map_opt
-            )
-            map(
-                'x',
-                cfg.opleader.block,
-                '<ESC><CMD>lua require("Comment.api").locked.toggle_blockwise_op(vim.fn.visualmode())<CR>',
-                map_opt
-            )
+            K('x', cfg.opleader.line, '<Plug>(comment_toggle_linewise_visual)')
+            K('x', cfg.opleader.block, '<Plug>(comment_toggle_blockwise_visual)')
         end
 
         -- Extra Mappings
         if cfg.mappings.extra then
-            map('n', cfg.extra.below, '<CMD>lua require("Comment.api").locked.insert_linewise_below()<CR>', map_opt)
-            map('n', cfg.extra.above, '<CMD>lua require("Comment.api").locked.insert_linewise_above()<CR>', map_opt)
-            map('n', cfg.extra.eol, '<CMD>lua require("Comment.api").locked.insert_linewise_eol()<CR>', map_opt)
+            K('n', cfg.extra.below, '<CMD>lua require("Comment.api").locked.insert_linewise_below()<CR>')
+            K('n', cfg.extra.above, '<CMD>lua require("Comment.api").locked.insert_linewise_above()<CR>')
+            K('n', cfg.extra.eol, '<CMD>lua require("Comment.api").locked.insert_linewise_eol()<CR>')
         end
 
         -- Extended Mappings
         if cfg.mappings.extended then
             -- NORMAL mode extended
-            map('n', 'g>', '<CMD>lua require("Comment.api").call("comment_linewise_op")<CR>g@', map_opt)
-            map('n', 'g>c', '<CMD>lua require("Comment.api").call("comment_current_linewise_op")<CR>g@$', map_opt)
-            map('n', 'g>b', '<CMD>lua require("Comment.api").call("comment_current_blockwise_op")<CR>g@$', map_opt)
+            K('n', 'g>', '<CMD>lua require("Comment.api").call("comment_linewise_op")<CR>g@')
+            K('n', 'g>c', '<CMD>lua require("Comment.api").call("comment_current_linewise_op")<CR>g@$')
+            K('n', 'g>b', '<CMD>lua require("Comment.api").call("comment_current_blockwise_op")<CR>g@$')
 
-            map('n', 'g<', '<CMD>lua require("Comment.api").call("uncomment_linewise_op")<CR>g@', map_opt)
-            map('n', 'g<c', '<CMD>lua require("Comment.api").call("uncomment_current_linewise_op")<CR>g@$', map_opt)
-            map('n', 'g<b', '<CMD>lua require("Comment.api").call("uncomment_current_blockwise_op")<CR>g@$', map_opt)
+            K('n', 'g<', '<CMD>lua require("Comment.api").call("uncomment_linewise_op")<CR>g@')
+            K('n', 'g<c', '<CMD>lua require("Comment.api").call("uncomment_current_linewise_op")<CR>g@$')
+            K('n', 'g<b', '<CMD>lua require("Comment.api").call("uncomment_current_blockwise_op")<CR>g@$')
 
             -- VISUAL mode extended
-            map(
-                'x',
-                'g>',
-                '<ESC><CMD>lua require("Comment.api").locked.comment_linewise_op(vim.fn.visualmode())<CR>',
-                map_opt
-            )
-            map(
-                'x',
-                'g<',
-                '<ESC><CMD>lua require("Comment.api").locked.uncomment_linewise_op(vim.fn.visualmode())<CR>',
-                map_opt
-            )
+            K('x', 'g>', '<ESC><CMD>lua require("Comment.api").locked.comment_linewise_op(vim.fn.visualmode())<CR>')
+            K('x', 'g<', '<ESC><CMD>lua require("Comment.api").locked.uncomment_linewise_op(vim.fn.visualmode())<CR>')
         end
     end
 

lua/Comment/config.lua

@@ -37,7 +37,7 @@
 ---Could be a regex string or a function that returns a regex string.
 ---Example: Use '^$' to ignore empty lines
 ---@field ignore string|fun():string
----@field mappings Mappings
+---@field mappings boolean|Mappings
 ---@field toggler Toggler
 ---@field opleader Opleader
 ---@field extra ExtraMapping