feat!: new lua API (using metatables) (#183)

This deprecates the old Lua API and will be removed in the next
tagged release of the plugin, probably `v0.7.0`.

Currently every Lua API is a function call, which is fine, and they are
similar to one another having few different arguments. This is not
extensible and have slight maintenance burden if we want to create
new mode (ref: #17) or introduce new API functions.

Using `setmetatable` we can build-up the API as we go. This will
be extensible and have less maintenance overhead.

Following is the new Lua API:

> All API functions are dot repeatable except `*.count()`

```lua
require('Comment.api').toggle.linewise()
require('Comment.api').toggle.linewise.current()
require('Comment.api').toggle.linewise.count()

require('Comment.api').toggle.blockwise()
require('Comment.api').toggle.blockwise.current()
require('Comment.api').toggle.blockwise.count()

require('Comment.api').comment.linewise()
require('Comment.api').comment.linewise.current()
require('Comment.api').comment.linewise.count()

require('Comment.api').comment.blockwise()
require('Comment.api').comment.blockwise.current()
require('Comment.api').comment.blockwise.count()

require('Comment.api').uncomment.linewise()
require('Comment.api').uncomment.linewise.current()
require('Comment.api').uncomment.linewise.count()

require('Comment.api').uncomment.blockwise()
require('Comment.api').uncomment.blockwise.current()
require('Comment.api').uncomment.blockwise.count()
```

> _Old API have proper deprecation message which suggests equivalent New API_

---

This also introduces couple of (breaking) changes apart from the lua API:

1. Rename the following `<Plug>` mappings (to be consistent with API)
    - `<Plug>(comment_toggle_current_linewise)` -> `<Plug>(comment_toggle_linewise_current)`
    - `<Plug>(comment_toggle_current_blockwise)` -> `<Plug>(comment_toggle_blockwise_current)`

2. Changed field names of `utils.ctype` object
	- `U.ctype.line` → `U.ctype.linewise`
	- `U.ctype.block` → `U.ctype.blockwise`

3. Now `require('Comment.api').locked` is a function which
   takes the name of the new lua API call (old signature is deprecated)
```lua
-- OLD
require("Comment.api").locked.toggle_current_linewise()
require("Comment.api").locked.comment_linewise_op(vim.fn.visualmode())

-- NEW
require("Comment.api").locked('toggle.linewise.current')()
require("Comment.api").locked('comment.linewise')(vim.fn.visualmode())
```
```vim
" NOTE: `locked` interface is just a wrapper around `lockmarks`
lockmarks lua require("Comment.api").toggle.linewise.current()
```

4. Removed redundant `cmotion` (last) argument from
   `require('Comment.opfunc').opfunc()` function

Author: numToStr

README.md

@@ -91,7 +91,8 @@ Following are the **default** config for the [`setup()`](#setup). If you want to
         block = 'gbc',
     },
 
-    ---LHS of operator-pending mappings in NORMAL + VISUAL mode
+    ---LHS of operator-pending mappings in NORMAL mode
+    ---LHS of mapping in VISUAL mode
     ---@type table
     opleader = {
         ---Line-comment keymap
@@ -265,11 +266,11 @@ There are two hook methods i.e `pre_hook` and `post_hook` which are called befor
             local U = require('Comment.utils')
 
             -- Determine whether to use linewise or blockwise commentstring
-            local type = ctx.ctype == U.ctype.line and '__default' or '__multiline'
+            local type = ctx.ctype == U.ctype.linewise and '__default' or '__multiline'
 
             -- Determine the location where to calculate commentstring from
             local location = nil
-            if ctx.ctype == U.ctype.block then
+            if ctx.ctype == U.ctype.blockwise then
                 location = require('ts_context_commentstring.utils').get_cursor_location()
             elseif ctx.cmotion == U.cmotion.v or ctx.cmotion == U.cmotion.V then
                 location = require('ts_context_commentstring.utils').get_visual_start_location()
@@ -433,7 +434,7 @@ The following object is provided as an argument to `pre_hook` and `post_hook` fu
 `CommentType`, `CommentMode` and `CommentMotion` all of them are exported from the plugin's utils for reuse
 
 ```lua
-require('Comment.utils').ctype.{line,block}
+require('Comment.utils').ctype.{linewise,blockwise}
 
 require('Comment.utils').cmode.{toggle,comment,uncomment}
 

after/plugin/Comment.lua

@@ -1,57 +1,57 @@
 local K = vim.keymap.set
 
--- Count mappings
+-- Operator-Pending mappings
 K(
     'n',
-    '<Plug>(comment_toggle_linewise_count)',
-    '<CMD>lua require("Comment.api").call("toggle_linewise_count_op")<CR>g@$',
-    { desc = 'Comment toggle linewise with count' }
+    '<Plug>(comment_toggle_linewise)',
+    '<CMD>lua require("Comment.api").call("toggle.linewise")<CR>g@',
+    { desc = 'Comment toggle linewise' }
 )
 K(
     'n',
-    '<Plug>(comment_toggle_blockwise_count)',
-    '<CMD>lua require("Comment.api").call("toggle_blockwise_count_op")<CR>g@$',
-    { desc = 'Comment toggle blockwise with count' }
+    '<Plug>(comment_toggle_blockwise)',
+    '<CMD>lua require("Comment.api").call("toggle.blockwise")<CR>g@',
+    { desc = 'Comment toggle blockwise' }
 )
 
 -- Toggle mappings
 K(
     'n',
-    '<Plug>(comment_toggle_current_linewise)',
-    '<CMD>lua require("Comment.api").call("toggle_current_linewise_op")<CR>g@$',
+    '<Plug>(comment_toggle_linewise_current)',
+    '<CMD>lua require("Comment.api").call("toggle.linewise.current")<CR>g@$',
     { desc = 'Comment toggle current line' }
 )
 K(
     'n',
-    '<Plug>(comment_toggle_current_blockwise)',
-    '<CMD>lua require("Comment.api").call("toggle_current_blockwise_op")<CR>g@$',
+    '<Plug>(comment_toggle_blockwise_current)',
+    '<CMD>lua require("Comment.api").call("toggle.blockwise.current")<CR>g@$',
     { desc = 'Comment toggle current block' }
 )
 
--- Operator-Pending mappings
+-- Count mappings
 K(
     'n',
-    '<Plug>(comment_toggle_linewise)',
-    '<CMD>lua require("Comment.api").call("toggle_linewise_op")<CR>g@',
-    { desc = 'Comment toggle linewise' }
+    '<Plug>(comment_toggle_linewise_count)',
+    '<CMD>lua require("Comment.api").call("toggle.linewise.count_repeat")<CR>g@$',
+    { desc = 'Comment toggle linewise with count' }
 )
 K(
     'n',
-    '<Plug>(comment_toggle_blockwise)',
-    '<CMD>lua require("Comment.api").call("toggle_blockwise_op")<CR>g@',
-    { desc = 'Comment toggle blockwise' }
+    '<Plug>(comment_toggle_blockwise_count)',
+    '<CMD>lua require("Comment.api").call("toggle.blockwise.count_repeat")<CR>g@$',
+    { desc = 'Comment toggle blockwise with count' }
 )
 
 -- Visual-Mode mappings
 K(
     'x',
     '<Plug>(comment_toggle_linewise_visual)',
-    '<ESC><CMD>lua require("Comment.api").locked.toggle_linewise_op(vim.fn.visualmode())<CR>',
+    '<ESC><CMD>lua require("Comment.api").locked("toggle.linewise")(vim.fn.visualmode())<CR>',
     { desc = 'Comment toggle linewise (visual)' }
 )
 K(
     'x',
     '<Plug>(comment_toggle_blockwise_visual)',
-    '<ESC><CMD>lua require("Comment.api").locked.toggle_blockwise_op(vim.fn.visualmode())<CR>',
+    '<ESC><CMD>lua require("Comment.api").locked("toggle.blockwise")(vim.fn.visualmode())<CR>',
     { desc = 'Comment toggle blockwise (visual)' }
 )

doc/API.md

@@ -1,6 +1,9 @@
 # ⚙️ API
 
-Following are list of APIs that are exported from the plugin. These can be used to setup [custom keybinding](#usage) or to make your own custom comment function. All API functions can take `opmode` (defined below) and a optional [`cfg`](../README.md#config) argument which can be used to override the [default configuration](../README.md#config)
+Following are list of APIs that are exported from the plugin. These can be used to setup [custom keybinding](#usage) or to make your own custom comment function. All API functions can take a `{motion}` (Read `:h :map-operator`) and a optional [`{cfg}`](../README.md#config) argument which can be used to override the [default configuration](../README.md#config)
+
+<details>
+<summary>Deprecated API</summary>
 
 ```lua
 ---@alias OpMode 'line'|'char'|'v'|'V' Vim operator-mode motions. Read `:h map-operator`
@@ -142,6 +145,42 @@ require('Comment.api').uncomment_current_blockwise(cfg)
 require('Comment.api').uncomment_current_blockwise_op(opmode, cfg)
 ```
 
+</details>
+
+### Core
+
+> **NOTE**:
+>
+> 1. All API functions are dot-repeatable except `*.count()`
+> 2. For the `*.current()` functions, `{motion}` argument is optional
+> 3. `{cfg}` is optional for all the API functions
+
+```lua
+require('Comment.api').toggle.linewise(motion, cfg)
+require('Comment.api').toggle.linewise.current(motion, cfg)
+require('Comment.api').toggle.linewise.count(count, cfg)
+
+require('Comment.api').toggle.blockwise(motion, cfg)
+require('Comment.api').toggle.blockwise.current(motion, cfg)
+require('Comment.api').toggle.blockwise.count(count, cfg)
+
+require('Comment.api').comment.linewise(motion, cfg)
+require('Comment.api').comment.linewise.current(motion, cfg)
+require('Comment.api').comment.linewise.count(count, cfg)
+
+require('Comment.api').comment.blockwise(motion, cfg)
+require('Comment.api').comment.blockwise.current(motion, cfg)
+require('Comment.api').comment.blockwise.count(count, cfg)
+
+require('Comment.api').uncomment.linewise(motion, cfg)
+require('Comment.api').uncomment.linewise.current(motion, cfg)
+require('Comment.api').uncomment.linewise.count(count, cfg)
+
+require('Comment.api').uncomment.blockwise(motion, cfg)
+require('Comment.api').uncomment.blockwise.current(motion, cfg)
+require('Comment.api').uncomment.blockwise.count(count, cfg)
+```
+
 ### Additional
 
 ```lua
@@ -161,28 +200,28 @@ Following are some example keybindings using the APIs.
 -- # NORMAL mode
 
 -- Linewise toggle current line using C-/
-vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").toggle_current_linewise()<CR>')
+vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").toggle.linewise.current()<CR>')
 -- or with dot-repeat support
--- vim.keymap.set('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.linewise.current")<CR>g@$')
 
 -- Blockwise toggle current line using C-\
-vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").toggle_current_blockwise()<CR>')
+vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").toggle.blockwise.current()<CR>')
 -- or with dot-repeat support
--- vim.keymap.set('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.blockwise.current")<CR>g@$')
 
 -- Linewise toggle multiple line using <leader>gc with dot-repeat support
 -- Example: <leader>gc3j will comment 4 lines
-vim.keymap.set('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")<CR>g@')
 
 -- Blockwise toggle multiple line using <leader>gc with dot-repeat support
 -- Example: <leader>gb3j will comment 4 lines
-vim.keymap.set('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")<CR>g@')
 
 -- # VISUAL mode
 
 -- Linewise toggle using C-/
-vim.keymap.set('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(vim.fn.visualmode())<CR>')
 
 -- Blockwise toggle using <leader>gb
-vim.keymap.set('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(vim.fn.visualmode())<CR>')
 ```

doc/plugs.md

@@ -2,12 +2,12 @@
 
 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_current)` - Toggles line comment on the current line
+- `<Plug>(comment_toggle_blockwise_current)` - Toggles block comment on the current line
+- `<Plug>(comment_toggle_linewise_count)` - Toggles line comment with count
+- `<Plug>(comment_toggle_blockwise_count)` - Toggles block comment with count
 - `<Plug>(comment_toggle_linewise_visual)` - Toggles line comment in VISUAL mode
 - `<Plug>(comment_toggle_blockwise_visual)` - Toggles block comment in VISUAL mode
 
@@ -21,8 +21,8 @@ Following snippets is same as the default mappings set by the plugin.
 local opt = { expr = true, remap = true, replace_keycodes = false }
 
 -- 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)
+vim.keymap.set('n', 'gcc', "v:count == 0 ? '<Plug>(comment_toggle_linewise_current)' : '<Plug>(comment_toggle_linewise_count)'", opt)
+vim.keymap.set('n', 'gbc', "v:count == 0 ? '<Plug>(comment_toggle_blockwise_current)' : '<Plug>(comment_toggle_blockwise_count)'", opt)
 
 -- Toggle in Op-pending mode
 vim.keymap.set('n', 'gc', '<Plug>(comment_toggle_linewise)')