Skip to content

Commit cd1c381

Browse files
numToStrnumToStr
authored
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
1 parent fe9bbdb commit cd1c381

File tree

9 files changed

+357
-141
lines changed

9 files changed

+357
-141
lines changed

‎README.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,8 @@ Following are the **default** config for the [`setup()`](#setup). If you want to
9191
block = 'gbc',
9292
},
9393

94-
---LHS of operator-pending mappings in NORMAL + VISUAL mode
94+
---LHS of operator-pending mappings in NORMAL mode
95+
---LHS of mapping in VISUAL mode
9596
---@type table
9697
opleader = {
9798
---Line-comment keymap
@@ -265,11 +266,11 @@ There are two hook methods i.e `pre_hook` and `post_hook` which are called befor
265266
local U = require('Comment.utils')
266267

267268
-- Determine whether to use linewise or blockwise commentstring
268-
local type = ctx.ctype == U.ctype.line and '__default' or '__multiline'
269+
local type = ctx.ctype == U.ctype.linewise and '__default' or '__multiline'
269270

270271
-- Determine the location where to calculate commentstring from
271272
local location = nil
272-
if ctx.ctype == U.ctype.block then
273+
if ctx.ctype == U.ctype.blockwise then
273274
location = require('ts_context_commentstring.utils').get_cursor_location()
274275
elseif ctx.cmotion == U.cmotion.v or ctx.cmotion == U.cmotion.V then
275276
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
433434
`CommentType`, `CommentMode` and `CommentMotion` all of them are exported from the plugin's utils for reuse
434435

435436
```lua
436-
require('Comment.utils').ctype.{line,block}
437+
require('Comment.utils').ctype.{linewise,blockwise}
437438

438439
require('Comment.utils').cmode.{toggle,comment,uncomment}
439440

‎after/plugin/Comment.lua‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,57 @@
11
local K = vim.keymap.set
22

3-
-- Count mappings
3+
-- Operator-Pending mappings
44
K(
55
'n',
6-
'<Plug>(comment_toggle_linewise_count)',
7-
'<CMD>lua require("Comment.api").call("toggle_linewise_count_op")<CR>g@$',
8-
{ desc = 'Comment toggle linewise with count' }
6+
'<Plug>(comment_toggle_linewise)',
7+
'<CMD>lua require("Comment.api").call("toggle.linewise")<CR>g@',
8+
{ desc = 'Comment toggle linewise' }
99
)
1010
K(
1111
'n',
12-
'<Plug>(comment_toggle_blockwise_count)',
13-
'<CMD>lua require("Comment.api").call("toggle_blockwise_count_op")<CR>g@$',
14-
{ desc = 'Comment toggle blockwise with count' }
12+
'<Plug>(comment_toggle_blockwise)',
13+
'<CMD>lua require("Comment.api").call("toggle.blockwise")<CR>g@',
14+
{ desc = 'Comment toggle blockwise' }
1515
)
1616

1717
-- Toggle mappings
1818
K(
1919
'n',
20-
'<Plug>(comment_toggle_current_linewise)',
21-
'<CMD>lua require("Comment.api").call("toggle_current_linewise_op")<CR>g@$',
20+
'<Plug>(comment_toggle_linewise_current)',
21+
'<CMD>lua require("Comment.api").call("toggle.linewise.current")<CR>g@$',
2222
{ desc = 'Comment toggle current line' }
2323
)
2424
K(
2525
'n',
26-
'<Plug>(comment_toggle_current_blockwise)',
27-
'<CMD>lua require("Comment.api").call("toggle_current_blockwise_op")<CR>g@$',
26+
'<Plug>(comment_toggle_blockwise_current)',
27+
'<CMD>lua require("Comment.api").call("toggle.blockwise.current")<CR>g@$',
2828
{ desc = 'Comment toggle current block' }
2929
)
3030

31-
-- Operator-Pending mappings
31+
-- Count mappings
3232
K(
3333
'n',
34-
'<Plug>(comment_toggle_linewise)',
35-
'<CMD>lua require("Comment.api").call("toggle_linewise_op")<CR>g@',
36-
{ desc = 'Comment toggle linewise' }
34+
'<Plug>(comment_toggle_linewise_count)',
35+
'<CMD>lua require("Comment.api").call("toggle.linewise.count_repeat")<CR>g@$',
36+
{ desc = 'Comment toggle linewise with count' }
3737
)
3838
K(
3939
'n',
40-
'<Plug>(comment_toggle_blockwise)',
41-
'<CMD>lua require("Comment.api").call("toggle_blockwise_op")<CR>g@',
42-
{ desc = 'Comment toggle blockwise' }
40+
'<Plug>(comment_toggle_blockwise_count)',
41+
'<CMD>lua require("Comment.api").call("toggle.blockwise.count_repeat")<CR>g@$',
42+
{ desc = 'Comment toggle blockwise with count' }
4343
)
4444

4545
-- Visual-Mode mappings
4646
K(
4747
'x',
4848
'<Plug>(comment_toggle_linewise_visual)',
49-
'<ESC><CMD>lua require("Comment.api").locked.toggle_linewise_op(vim.fn.visualmode())<CR>',
49+
'<ESC><CMD>lua require("Comment.api").locked("toggle.linewise")(vim.fn.visualmode())<CR>',
5050
{ desc = 'Comment toggle linewise (visual)' }
5151
)
5252
K(
5353
'x',
5454
'<Plug>(comment_toggle_blockwise_visual)',
55-
'<ESC><CMD>lua require("Comment.api").locked.toggle_blockwise_op(vim.fn.visualmode())<CR>',
55+
'<ESC><CMD>lua require("Comment.api").locked("toggle.blockwise")(vim.fn.visualmode())<CR>',
5656
{ desc = 'Comment toggle blockwise (visual)' }
5757
)

‎doc/API.md‎

Lines changed: 48 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# ⚙️ API
22

3-
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)
3+
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)
4+
5+
<details>
6+
<summary>Deprecated API</summary>
47

58
```lua
69
---@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)
142145
require('Comment.api').uncomment_current_blockwise_op(opmode, cfg)
143146
```
144147

148+
</details>
149+
150+
### Core
151+
152+
> **NOTE**:
153+
>
154+
> 1. All API functions are dot-repeatable except `*.count()`
155+
> 2. For the `*.current()` functions, `{motion}` argument is optional
156+
> 3. `{cfg}` is optional for all the API functions
157+
158+
```lua
159+
require('Comment.api').toggle.linewise(motion, cfg)
160+
require('Comment.api').toggle.linewise.current(motion, cfg)
161+
require('Comment.api').toggle.linewise.count(count, cfg)
162+
163+
require('Comment.api').toggle.blockwise(motion, cfg)
164+
require('Comment.api').toggle.blockwise.current(motion, cfg)
165+
require('Comment.api').toggle.blockwise.count(count, cfg)
166+
167+
require('Comment.api').comment.linewise(motion, cfg)
168+
require('Comment.api').comment.linewise.current(motion, cfg)
169+
require('Comment.api').comment.linewise.count(count, cfg)
170+
171+
require('Comment.api').comment.blockwise(motion, cfg)
172+
require('Comment.api').comment.blockwise.current(motion, cfg)
173+
require('Comment.api').comment.blockwise.count(count, cfg)
174+
175+
require('Comment.api').uncomment.linewise(motion, cfg)
176+
require('Comment.api').uncomment.linewise.current(motion, cfg)
177+
require('Comment.api').uncomment.linewise.count(count, cfg)
178+
179+
require('Comment.api').uncomment.blockwise(motion, cfg)
180+
require('Comment.api').uncomment.blockwise.current(motion, cfg)
181+
require('Comment.api').uncomment.blockwise.count(count, cfg)
182+
```
183+
145184
### Additional
146185

147186
```lua
@@ -161,28 +200,28 @@ Following are some example keybindings using the APIs.
161200
-- # NORMAL mode
162201

163202
-- Linewise toggle current line using C-/
164-
vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").toggle_current_linewise()<CR>')
203+
vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").toggle.linewise.current()<CR>')
165204
-- or with dot-repeat support
166-
-- vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").call("toggle_current_linewise_op")<CR>g@$')
205+
-- vim.keymap.set('n', '<C-_>', '<CMD>lua require("Comment.api").call("toggle.linewise.current")<CR>g@$')
167206

168207
-- Blockwise toggle current line using C-\
169-
vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").toggle_current_blockwise()<CR>')
208+
vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").toggle.blockwise.current()<CR>')
170209
-- or with dot-repeat support
171-
-- vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").call("toggle_current_blockwise_op")<CR>g@$')
210+
-- vim.keymap.set('n', '<C-\\>', '<CMD>lua require("Comment.api").call("toggle.blockwise.current")<CR>g@$')
172211

173212
-- Linewise toggle multiple line using <leader>gc with dot-repeat support
174213
-- Example: <leader>gc3j will comment 4 lines
175-
vim.keymap.set('n', '<leader>gc', '<CMD>lua require("Comment.api").call("toggle_linewise_op")<CR>g@')
214+
vim.keymap.set('n', '<leader>gc', '<CMD>lua require("Comment.api").call("toggle.linewise")<CR>g@')
176215

177216
-- Blockwise toggle multiple line using <leader>gc with dot-repeat support
178217
-- Example: <leader>gb3j will comment 4 lines
179-
vim.keymap.set('n', '<leader>gb', '<CMD>lua require("Comment.api").call("toggle_blockwise_op")<CR>g@')
218+
vim.keymap.set('n', '<leader>gb', '<CMD>lua require("Comment.api").call("toggle.blockwise")<CR>g@')
180219

181220
-- # VISUAL mode
182221

183222
-- Linewise toggle using C-/
184-
vim.keymap.set('x', '<C-_>', '<ESC><CMD>lua require("Comment.api").toggle_linewise_op(vim.fn.visualmode())<CR>')
223+
vim.keymap.set('x', '<C-_>', '<ESC><CMD>lua require("Comment.api").toggle.linewise(vim.fn.visualmode())<CR>')
185224

186225
-- Blockwise toggle using <leader>gb
187-
vim.keymap.set('x', '<leader>gb', '<ESC><CMD>lua require("Comment.api").toggle_blockwise_op(vim.fn.visualmode())<CR>')
226+
vim.keymap.set('x', '<leader>gb', '<ESC><CMD>lua require("Comment.api").toggle.blockwise(vim.fn.visualmode())<CR>')
188227
```

‎doc/plugs.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
Following are the `<Plug>` mappings which you can use to quickly setup your custom keybindings
44

5-
- `<Plug>(comment_toggle_linewise_count)` - Toggles line comment with count
6-
- `<Plug>(comment_toggle_blockwise_count)` - Toggles block comment with count
7-
- `<Plug>(comment_toggle_current_linewise)` - Toggles line comment on the current line
8-
- `<Plug>(comment_toggle_current_blockwise)` - Toggles block comment on the current line
95
- `<Plug>(comment_toggle_linewise)` - Toggles line comment via Operator pending mode
106
- `<Plug>(comment_toggle_blockwise)` - Toggles block comment via Operator pending mode
7+
- `<Plug>(comment_toggle_linewise_current)` - Toggles line comment on the current line
8+
- `<Plug>(comment_toggle_blockwise_current)` - Toggles block comment on the current line
9+
- `<Plug>(comment_toggle_linewise_count)` - Toggles line comment with count
10+
- `<Plug>(comment_toggle_blockwise_count)` - Toggles block comment with count
1111
- `<Plug>(comment_toggle_linewise_visual)` - Toggles line comment in VISUAL mode
1212
- `<Plug>(comment_toggle_blockwise_visual)` - Toggles block comment in VISUAL mode
1313

@@ -21,8 +21,8 @@ Following snippets is same as the default mappings set by the plugin.
2121
local opt = { expr = true, remap = true, replace_keycodes = false }
2222

2323
-- Toggle using count
24-
vim.keymap.set('n', 'gcc', "v:count == 0 ? '<Plug>(comment_toggle_current_linewise)' : '<Plug>(comment_toggle_linewise_count)'", opt)
25-
vim.keymap.set('n', 'gbc', "v:count == 0 ? '<Plug>(comment_toggle_current_blockwise)' : '<Plug>(comment_toggle_blockwise_count)'", opt)
24+
vim.keymap.set('n', 'gcc', "v:count == 0 ? '<Plug>(comment_toggle_linewise_current)' : '<Plug>(comment_toggle_linewise_count)'", opt)
25+
vim.keymap.set('n', 'gbc', "v:count == 0 ? '<Plug>(comment_toggle_blockwise_current)' : '<Plug>(comment_toggle_blockwise_count)'", opt)
2626

2727
-- Toggle in Op-pending mode
2828
vim.keymap.set('n', 'gc', '<Plug>(comment_toggle_linewise)')

0 commit comments

Comments
 (0)