Repository navigation
Expand file tree
/
Copy pathmini-comment.txt
More file actions
160 lines (117 loc) · 5.73 KB
/
Copy pathmini-comment.txt
File metadata and controls
160 lines (117 loc) · 5.73 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
*mini.comment* Comment lines
*MiniComment*
MIT License Copyright (c) 2021 Evgeni Chasnovski
==============================================================================
Features:
- Commenting in Normal mode respects |count| and is dot-repeatable.
- Comment structure is inferred from 'commentstring'.
- Allows custom hooks before and after successful commenting.
- Configurable options for some nuanced behavior.
What it doesn't do:
- Block and sub-line comments. This will only support per-line commenting.
- Configurable (from module) comment structure. Modify |commentstring|
instead. To enhance support for commenting in multi-language files, see
"JoosepAlviste/nvim-ts-context-commentstring" plugin along with `hooks`
option of this module (see |MiniComment.config|).
- Handle indentation with mixed tab and space.
- Preserve trailing whitespace in empty lines.
# Setup~
This module needs a setup with `require('mini.comment').setup({})` (replace
`{}` with your `config` table). It will create global Lua table
`MiniComment` which you can use for scripting or manually (with
`:lua MiniComment.*`).
See |MiniComment.config| for `config` structure and default values.
You can override runtime config settings locally to buffer inside
`vim.b.minicomment_config` which should have same structure as
`MiniComment.config`. See |mini.nvim-buffer-local-config| for more details.
# Disabling~
To disable core functionality, set `vim.g.minicomment_disable` (globally) or
`vim.b.minicomment_disable` (for a buffer) to `true`. Considering high number
of different scenarios and customization intentions, writing exact rules
for disabling module's functionality is left to user. See
|mini.nvim-disabling-recipes| for common recipes.
------------------------------------------------------------------------------
*MiniComment.setup()*
`MiniComment.setup`({config})
Module setup
Parameters~
{config} `(table|nil)` Module config table. See |MiniComment.config|.
Usage~
`require('mini.comment').setup({})` (replace `{}` with your `config` table)
------------------------------------------------------------------------------
*MiniComment.config*
`MiniComment.config`
Module config
Default values:
>
MiniComment.config = {
-- Options which control module behavior
options = {
-- Whether to ignore blank lines
ignore_blank_line = false,
-- Whether to recognize as comment only lines without indent
start_of_line = false,
-- Whether to ensure single space pad for comment parts
pad_comment_parts = true,
},
-- Module mappings. Use `''` (empty string) to disable one.
mappings = {
-- Toggle comment (like `gcip` - comment inner paragraph) for both
-- Normal and Visual modes
comment = 'gc',
-- Toggle comment on current line
comment_line = 'gcc',
-- Define 'comment' textobject (like `dgc` - delete whole comment block)
textobject = 'gc',
},
-- Hook functions to be executed at certain stage of commenting
hooks = {
-- Before successful commenting. Does nothing by default.
pre = function() end,
-- After successful commenting. Does nothing by default.
post = function() end,
},
}
<
------------------------------------------------------------------------------
*MiniComment.operator()*
`MiniComment.operator`({mode})
Main function to be mapped
It is meant to be used in expression mappings (see |map-<expr>|) to enable
dot-repeatability and commenting on range. There is no need to do this
manually, everything is done inside |MiniComment.setup()|.
It has a somewhat unintuitive logic (because of how expression mapping with
dot-repeatability works): it should be called without arguments inside
expression mapping and with argument when action should be performed.
Parameters~
{mode} `(string|nil)` Optional string with 'operatorfunc' mode (see |g@|).
Return~
`(string)` 'g@' if called without argument, '' otherwise (but after
performing action).
------------------------------------------------------------------------------
*MiniComment.toggle_lines()*
`MiniComment.toggle_lines`({line_start}, {line_end})
Toggle comments between two line numbers
It uncomments if lines are comment (every line is a comment) and comments
otherwise. It respects indentation and doesn't insert trailing
whitespace. Toggle commenting not in visual mode is also dot-repeatable
and respects |count|.
Before successful commenting it executes `config.hooks.pre`.
After successful commenting it executes `config.hooks.post`.
If hook returns `false`, any further action is terminated.
# Notes~
1. Currently call to this function will remove marks inside written range.
Use |lockmarks| to preserve marks.
Parameters~
{line_start} `(number)` Start line number (inclusive from 1 to number of lines).
{line_end} `(number)` End line number (inclusive from 1 to number of lines).
------------------------------------------------------------------------------
*MiniComment.textobject()*
`MiniComment.textobject`()
Comment textobject
This selects all commented lines adjacent to cursor line (if it itself is
commented). Designed to be used with operator mode mappings (see |mapmode-o|).
Before successful textobject usage it executes `config.hooks.pre`.
After successful textobject usage it executes `config.hooks.post`.
If hook returns `false`, any further action is terminated.
vim:tw=78:ts=8:noet:ft=help:norl: