Repository navigation
Expand file tree
/
Copy pathmini-basics.txt
More file actions
358 lines (286 loc) · 12.6 KB
/
Copy pathmini-basics.txt
File metadata and controls
358 lines (286 loc) · 12.6 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
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
*mini.basics* Common configuration presets
MIT License Copyright (c) 2023 Evgeni Chasnovski
------------------------------------------------------------------------------
*MiniBasics*
Install, create 'init.lua', add `require('mini.basics').setup()`, and you
are good to go.
Features:
- Presets for common options. It will only change option if it wasn't
manually set before. See more in |MiniBasics.config.options|.
- Presets for common mappings. It will only add a mapping if it wasn't
manually created before. See more in |MiniBasics.config.mappings|.
- Presets for common autocommands. See more in |MiniBasics.config.autocommands|.
- Reverse compatibility is a high priority. Any decision to change already
present behavior will be made with great care.
Notes:
- Main goal of this module is to provide a relatively easier way for
new-ish Neovim users to have better "works out of the box" experience
while having documented relevant options/mappings/autocommands to study.
It is based partially on survey among Neovim users and partially is
coming from personal preferences.
However, more seasoned users almost surely will find something useful.
Still, it is recommended to read about used options/mappings/autocommands
and decide if they are needed. The main way to do that is by reading
Neovim's help pages (linked in help file) and this module's source code
(thoroughly documented for easier comprehension).
# Setup ~
This module needs a setup with `require('mini.basics').setup({})` (replace
`{}` with your `config` table). It will create global Lua table `MiniBasics`
which you can use for scripting or manually (with `:lua MiniBasics.*`).
See |MiniBasics.config| for available config settings.
To stop module from showing non-error feedback, set `config.silent = true`.
# Comparisons ~
- [tpope/vim-sensible](https://github.com/tpope/vim-sensible):
- Most of 'tpope/vim-sensible' is already incorporated as default
options in Neovim (see |nvim-defaults|). This module has a much
broader effect.
- [tpope/vim-unimpaired](https://github.com/tpope/vim-unimpaired):
- The 'tpope/vim-unimpaired' has mapping for toggling options with `yo`
prefix. This module implements similar functionality with `\` prefix
(see |MiniBasics.config.mappings|).
------------------------------------------------------------------------------
*MiniBasics.setup()*
`MiniBasics.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniBasics.config|.
Usage ~
>lua
require('mini.basics').setup() -- use default config
-- OR
require('mini.basics').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniBasics.config*
`MiniBasics.config`
Defaults ~
>lua
MiniBasics.config = {
-- Options. Set field to `false` to disable.
options = {
-- Basic options ('number', 'ignorecase', and many more)
basic = true,
-- Extra UI features ('winblend', 'listchars', 'pumheight', ...)
extra_ui = false,
-- Presets for window borders ('single', 'double', ...)
-- Default 'auto' infers from 'winborder' option
win_borders = 'auto',
},
-- Mappings. Set field to `false` to disable.
mappings = {
-- Basic mappings (better 'jk', save with Ctrl+S, ...)
basic = true,
-- Prefix for mappings that toggle common options ('wrap', 'spell', ...).
-- Supply empty string to not create these mappings.
option_toggle_prefix = [[\]],
-- Window navigation with <C-hjkl>, resize with <C-arrow>
windows = false,
-- Move cursor in Insert, Command, and Terminal mode with <M-hjkl>
move_with_alt = false,
},
-- Autocommands. Set field to `false` to disable
autocommands = {
-- Basic autocommands (highlight on yank, start Insert in terminal, ...)
basic = true,
-- Set 'relativenumber' only in linewise and blockwise Visual mode
relnum_in_visual_mode = false,
},
-- Whether to disable showing non-error feedback
silent = false,
}
<
# Options ~
*MiniBasics.config.options*
Usage example: >lua
require('mini.basics').setup({
options = {
basic = true,
extra_ui = true,
win_borders = 'double',
}
})
<
## options.basic ~
The `config.options.basic` sets certain options to values which are quite
commonly used (judging by study of available Neovim pre-configurations,
public dotfiles, and surveys).
Any option is changed only if it was not set manually beforehand.
For exact changes, please see source code ('lua/mini/basics.lua').
Here is the list of affected options (put cursor on it and press |CTRL-]|):
- General:
- Sets |<Leader>| key to |<Space>|. Be sure to make all Leader mappings
after this (otherwise they are made with default <Leader>).
- Runs `:filetype plugin indent on` (see |:filetype-overview|)
- |'backup'|
- |'mouse'|
- |'undofile'|
- |'writebackup'|
- Appearance
- |'breakindent'|
- |'cursorline'|
- |'fillchars'|
- |'linebreak'|
- |'number'|
- |'ruler'|
- |'showmode'|
- |'signcolumn'|
- |'shortmess'|
- |'splitbelow'|
- |'splitkeep'|
- |'splitright'|
- |'termguicolors'| (on Neovim<0.10; later versions have it smartly enabled)
- |'wrap'|
- Editing
- |'completeopt'|
- |'formatoptions'|
- |'ignorecase'|
- |'incsearch'|
- |'infercase'|
- |'smartcase'|
- |'smartindent'|
- |'virtualedit'|
## options.extra_ui ~
The `config.options.extra_ui` sets certain options for visual appearance
which might not be aligned with common preferences, but still worth trying.
Any option is changed only if it was not set manually beforehand.
For exact changes, please see source code ('lua/mini/basics.lua').
List of affected options:
- |'list'|
- |'listchars'|
- |'pumblend'|
- |'pumheight'|
- |'winblend'|
- Runs `:syntax on` (see |:syntax-on|)
## options.win_borders ~
The `config.options.win_borders` updates |'fillchars'| to have a consistent set
of characters for window border (`vert`, `horiz`, `msgsep`, etc.).
Available values:
- `'auto'` - infer from |'winborder'|. On Neovim<0.11 do nothing.
- `'
D4C0
;bold'` - bold lines.
- `'dot'` - dot in every cell.
- `'double'` - double line.
- `'single'` - single line.
- `'solid'` - no symbol, only background.
# Mappings ~
*MiniBasics.config.mappings*
Usage example: >lua
require('mini.basics').setup({
mappings = {
basic = true,
option_toggle_prefix = [[\]],
windows = true,
move_with_alt = true,
}
})
<
If you want some mappings to be different or not made at all, set or delete
them after calling |MiniBasics.setup()|.
## mappings.basic ~
The `config.mappings.basic` creates mappings for certain commonly mapped actions
(judging by study of available Neovim pre-configurations and public dotfiles).
Some of the mappings override built-in ones to either improve their
behavior or override its default not very useful action.
It will only add a mapping if it wasn't manually created before.
Here is a table with created mappings : >
|Keys | Modes | Description |
|-------|-----------------|-----------------------------------------------|
| j | Normal, Visual | Move down by visible lines with no [count] |
| k | Normal, Visual | Move up by visible lines with no [count] |
| go | Normal | Add [count] empty lines after cursor |
| gO | Normal | Add [count] empty lines before cursor |
| gy | Normal, Visual | Copy to system clipboard |
| gp | Normal, Visual | Paste from system clipboard |
| gV | Normal | Visually select latest changed or yanked text |
| g/ | Visual | Search inside current visual selection |
| * | Visual | Search forward for current visual selection |
| # | Visual | Search backward for current visual selection |
| <C-s> | Normal, Visual, | Save and go to Normal mode |
| | Insert | |
<
Notes:
- See |[count]| for its meaning.
- On Neovim>=0.10 mappings for `#` and `*` are not created as their
enhanced variants are made built-in. See |v_star-default| and |v_#-default|.
- On Neovim>=0.11 there are |[<Space>| / |]<Space>| for adding empty lines.
The `gO` and `go` mappings are still created as they are more aligned with
similarly purposed |O| and |o| keys (although sometimes conflict with |gO|).
## mappings.option_toggle_prefix ~
The `config.mappings.option_toggle_prefix` defines a prefix used for
creating mappings that toggle common options. The result mappings will be
`<prefix> + <suffix>`. For example, with default value, `\w` will toggle |'wrap'|.
Other viable choices for prefix are
- `,` (as a mnemonic for several values to toggle).
- `|` (as a same mnemonic).
- `yo` (used in 'tpope/vim-unimpaired')
- Something with |<Leader>| key, like `<Leader>t` (`t` for "toggle"). Note:
if your prefix contains `<Leader>` key, make sure to set it before
calling |MiniBasics.setup()| (as is done with default `basic` field of
|MiniBasics.config.options|).
After toggling, there will be a feedback about the current option value if
prior to `require('mini.basics').setup()` module wasn't silenced (see
"Silencing" section in |mini.basics|).
It will only add a mapping if it wasn't manually created before.
Here is a list of suffixes for created toggling mappings (all in Normal mode):
- `b` - |'background'|.
- `c` - |'cursorline'|.
- `C` - |'cursorcolumn'|.
- `d` - diagnostic (via |vim.diagnostic| functions).
- `h` - |'hlsearch'| (or |v:hlsearch| to be precise).
- `i` - |'ignorecase'|.
- `l` - |'list'|.
- `n` - |'number'|.
- `r` - |'relativenumber'|.
- `s` - |'spell'|.
- `w` - |'wrap'|.
## mappings.windows ~
The `config.mappings.windows` creates mappings for easiere window manipulation.
It will only add a mapping if it wasn't manually created before.
Here is a list with created Normal mode mappings (all respect |[count]|):
- Window navigation:
- `<C-h>` - focus on left window (see |CTRL-W_H|).
- `<C-j>` - focus on below window (see |CTRL-W_J|).
- `<C-k>` - focus on above window (see |CTRL-W_K|).
- `<C-l>` - focus on right window (see |CTRL-W_L|).
- Window resize (all use arrow keys; variants of |:resize|; respect |[count]|):
- `<C-left>` - decrease window width.
- `<C-down>` - decrease window height.
- `<C-up>` - increase window height.
- `<C-right>` - increase window width.
## mappings.move_with_alt ~
The `config.mappings.move_with_alt` creates mappings for a more consistent
cursor move in Insert, Command, and Terminal modes. For example, it proves
useful in combination of autopair plugin (like |mini.pairs|) to move right
outside of inserted pairs (no matter what the pair is).
It will only add a mapping if it wasn't manually created before.
Here is a list of created mappings (`<M-x>` means `Alt`/`Meta` plus `x`):
- `<M-h>` - move cursor left. Modes: Insert, Terminal, Command.
- `<M-j>` - move cursor down. Modes: Insert, Terminal.
- `<M-k>` - move cursor up. Modes: Insert, Terminal.
- `<M-l>` - move cursor right. Modes: Insert, Terminal, Command.
# Autocommands ~
*MiniBasics.config.autocommands*
Usage example: >lua
require('mini.basics').setup({
autocommands = {
basic = true,
relnum_in_visual_mode = true,
}
})
<
## autocommands.basic ~
The `config.autocommands.basic` creates some common autocommands:
- Starts insert mode when opening terminal (see |:startinsert| and |TermOpen|).
- Highlights yanked text for a brief period of time (see |vim.hl.on_yank()|;
on Neovim<0.11 - |vim.hl.on_yank()|) and |TextYankPost|).
## autocommands.relnum_in_visual_mode ~
The `config.autocommands.relnum_in_visual_mode` creates autocommands that
enable |'relativenumber'| in linewise and blockwise Visual modes and disable
otherwise. See |ModeChanged|.
------------------------------------------------------------------------------
*MiniBasics.toggle_diagnostic()*
`MiniBasics.toggle_diagnostic`()
Toggle diagnostic for current buffer
This uses |vim.diagnostic| functions per buffer.
Return ~
`(string)` String indicator for new state. Similar to what |:set| `{option}?` shows.
vim:tw=78:ts=8:noet:ft=help:norl: