386 lines
20 KiB
Plaintext
386 lines
20 KiB
Plaintext
*mini.nvim* Collection of minimal, independent and fast Lua modules
|
|
|
|
MIT License Copyright (c) 2021 Evgeni Chasnovski
|
|
|
|
==============================================================================
|
|
|
|
|mini.nvim| is a collection of minimal, independent, and fast Lua modules
|
|
dedicated to improve Neovim (version 0.7 and higher) experience. Each
|
|
module can be considered as a separate sub-plugin.
|
|
|
|
Table of contents:
|
|
General overview ............................................... |mini.nvim|
|
|
Disabling recepies ........................... |mini.nvim-disabling-recipes|
|
|
Buffer-local config ........................ |mini.nvim-buffer-local-config|
|
|
Plugin colorschemes ................................... |mini-color-schemes|
|
|
Extend and create a/i textobjects ................................ |mini.ai|
|
|
Align text interactively ...................................... |mini.align|
|
|
Animate common Neovim actions ............................... |mini.animate|
|
|
Base16 colorscheme creation .................................. |mini.base16|
|
|
Common configuration presets ................................. |mini.basics|
|
|
Go forward/backward with square brackets .................. |mini.bracketed|
|
|
Remove buffers ............................................ |mini.bufremove|
|
|
Show next key clues ............................................ |mini.clue|
|
|
Tweak and save any color scheme .............................. |mini.colors|
|
|
Comment lines ............................................... |mini.comment|
|
|
Completion and signature help ............................ |mini.completion|
|
|
Autohighlight word under cursor .......................... |mini.cursorword|
|
|
Plugin manager ................................................. |mini.deps|
|
|
Work with diff hunks ........................................... |mini.diff|
|
|
Generate Neovim help files ...................................... |mini.doc|
|
|
Extra 'mini.nvim' functionality ............................... |mini.extra|
|
|
Navigate and manipulate file system............................ |mini.files|
|
|
Fuzzy matching ................................................ |mini.fuzzy|
|
|
Git integration ................................................. |mini.git|
|
|
Highlight patterns in text ............................... |mini.hipatterns|
|
|
Generate configurable color scheme ............................. |mini.hues|
|
|
Icon provider ................................................. |mini.icons|
|
|
Visualize and work with indent scope .................... |mini.indentscope|
|
|
Jump to next/previous single character ......................... |mini.jump|
|
|
Jump within visible lines .................................... |mini.jump2d|
|
|
Window with buffer text overview ................................ |mini.map|
|
|
Miscellaneous functions ........................................ |mini.misc|
|
|
Move any selection in any direction ............................ |mini.move|
|
|
Show notifications ........................................... |mini.notify|
|
|
Text edit operators ....................................... |mini.operators|
|
|
Autopairs ..................................................... |mini.pairs|
|
|
Pick anything .................................................. |mini.pick|
|
|
Session management ......................................... |mini.sessions|
|
|
Split and join arguments .................................. |mini.splitjoin|
|
|
Start screen ................................................ |mini.starter|
|
|
Statusline ............................................... |mini.statusline|
|
|
Surround actions ........................................... |mini.surround|
|
|
Tabline ..................................................... |mini.tabline|
|
|
Test Neovim plugins ............................................ |mini.test|
|
|
Trailspace (highlight and remove)......................... |mini.trailspace|
|
|
Track and reuse file system visits ........................... |mini.visits|
|
|
|
|
# General principles ~
|
|
|
|
- <Design>. Each module is designed to solve a particular problem targeting
|
|
balance between feature-richness (handling as many edge-cases as
|
|
possible) and simplicity of implementation/support. Granted, not all of
|
|
them ended up with the same balance, but it is the goal nevertheless.
|
|
|
|
- <Independence>. Modules are independent of each other and can be run
|
|
without external dependencies. Although some of them may need
|
|
dependencies for full experience.
|
|
|
|
- <Structure>. Each module is a submodule for a placeholder "mini" module. So,
|
|
for example, "surround" module should be referred to as "mini.surround".
|
|
As later will be explained, this plugin can also be referred to
|
|
as "MiniSurround".
|
|
|
|
- <Setup>:
|
|
- Each module you want to use should be enabled separately with
|
|
`require(<name of module>).setup({})`. Possibly replace `{}` with
|
|
your config table or omit altogether to use defaults. You can supply
|
|
only parts of config, the rest will be inferred from defaults.
|
|
|
|
- Call to module's `setup()` always creates a global Lua object with
|
|
coherent camel-case name: `require('mini.surround').setup()` creates
|
|
`_G.MiniSurround`. This allows for a simpler usage of plugin
|
|
functionality: instead of `require('mini.surround')` use
|
|
`MiniSurround` (or manually `:lua MiniSurround.*` in command line);
|
|
available from `v:lua` like `v:lua.MiniSurround`. Considering this,
|
|
"module" and "Lua object" names can be used interchangeably:
|
|
'mini.surround' and 'MiniSurround' will mean the same thing.
|
|
|
|
- Each supplied `config` table (after extending with default values) is
|
|
stored in `config` field of global object. Like `MiniSurround.config`.
|
|
|
|
- Values of `config`, which affect runtime activity, can be changed on
|
|
the fly to have effect. For example, `MiniSurround.config.n_lines`
|
|
can be changed during runtime; but changing
|
|
`MiniSurround.config.mappings` won't have any effect (as mappings are
|
|
created once during `setup()`).
|
|
|
|
- <Buffer local configuration>. Each module can be additionally configured
|
|
to use certain runtime config settings locally to buffer.
|
|
See |mini.nvim-buffer-local-config| for more information.
|
|
|
|
- <Disabling>. Each module's core functionality can be disabled globally or
|
|
locally to buffer. See "Disabling" section in module's help page for more
|
|
details. See |mini.nvim-disabling-recipes| for common recipes.
|
|
|
|
- <Silencing>. Each module can be configured to not show non-error feedback
|
|
globally or locally to buffer. See "Silencing" section in module's help page
|
|
for more details.
|
|
|
|
- <Highlighting>. Appearance of module's output is controlled by certain set
|
|
of highlight groups (see |highlight-groups|). By default they usually link to
|
|
some semantically close built-in highlight group. Use |:highlight| command
|
|
or |nvim_set_hl()| Lua function to customize highlighting.
|
|
To see a more calibrated look, use |MiniHues|, |MiniBase16|, or plugin's
|
|
colorschemes.
|
|
|
|
- <Stability>. Each module upon release is considered to be relatively
|
|
stable: both in terms of setup and functionality. Any non-bugfix
|
|
backward-incompatible change will be released gradually as much as possible.
|
|
|
|
# List of modules ~
|
|
|
|
- |MiniAi| - extend and create `a`/`i` textobjects (like in `di(` or
|
|
`va"`). It enhances some builtin |text-objects| (like |a(|, |a)|, |a'|,
|
|
and more), creates new ones (like `a*`, `a<Space>`, `af`, `a?`, and
|
|
more), and allows user to create their own (like based on treesitter, and
|
|
more). Supports dot-repeat, `v:count`, different search methods,
|
|
consecutive application, and customization via Lua patterns or functions.
|
|
Has builtins for brackets, quotes, function call, argument, tag, user
|
|
prompt, and any punctuation/digit/whitespace character.
|
|
|
|
- |MiniAlign| - align text interactively (with or without instant preview).
|
|
Allows rich and flexible customization of both alignment rules and user
|
|
interaction. Works with charwise, linewise, and blockwise selections in
|
|
both Normal mode (on textobject/motion; with dot-repeat) and Visual mode.
|
|
|
|
- |MiniAnimate| - animate common Neovim actions. Has "works out of the box"
|
|
builtin animations for cursor movement, scroll, resize, window open and
|
|
close. All of them can be customized and enabled/disabled independently.
|
|
|
|
- |MiniBase16| - fast implementation of base16 theme for manually supplied
|
|
palette. Supports 30+ plugin integrations. Has unique palette generator
|
|
which needs only background and foreground colors.
|
|
|
|
- |MiniBasics| - common configuration presets. Has configurable presets for
|
|
options, mappings, and autocommands. It doesn't change option or mapping
|
|
if it was manually created.
|
|
|
|
- |MiniBracketed| - go forward/backward with square brackets. Among others,
|
|
supports variety of non-trivial targets: comments, files on disk, indent
|
|
changes, tree-sitter nodes, linear undo states, yank history entries.
|
|
|
|
- |MiniBufremove| - buffer removing (unshow, delete, wipeout) while saving
|
|
window layout.
|
|
|
|
- |MiniClue| - show next key clues. Implements custom key query process with
|
|
customizable opt-in triggers, next key descriptions (clues), hydra-like
|
|
submodes, window delay/config. Provides clue sets for some built-in
|
|
concepts: `g`/`z` keys, window commands, etc.
|
|
|
|
- |MiniColors| - tweak and save any color scheme. Can create colorscheme
|
|
object with methods to invert/set/modify/etc.
|
|
lightness/saturation/hue/temperature/etc. of foreground/background/all
|
|
colors, infer cterm attributes, add transparency, save to a file and more.
|
|
Has functionality for interactive experiments and animation of
|
|
transition between color schemes.
|
|
|
|
- |MiniComment| - fast and familiar per-line code commenting.
|
|
|
|
- |MiniCompletion| - async (with customizable 'debounce' delay) 'two-stage
|
|
chain completion': first builtin LSP, then configurable fallback. Also
|
|
has functionality for completion item info and function signature (both
|
|
in floating window appearing after customizable delay).
|
|
|
|
- |MiniCursorword| - automatic highlighting of word under cursor (displayed
|
|
after customizable delay). Current word under cursor can be highlighted
|
|
differently.
|
|
|
|
- |MiniDeps| - plugin manager for plugins outside of 'mini.nvim'. Uses Git and
|
|
built-in packages to install, update, clean, and snapshot plugins.
|
|
|
|
- |MiniDiff| - visualize difference between buffer text and its reference
|
|
interactively (with colored signs or line numbers). Uses Git index as
|
|
default reference. Provides toggleable overview in text area, built-in
|
|
apply/reset/textobject/goto mappings.
|
|
|
|
- |MiniDoc| - generation of help files from EmmyLua-like annotations.
|
|
Allows flexible customization of output via hook functions. Used for
|
|
documenting this plugin.
|
|
|
|
- |MiniExtra| - extra 'mini.nvim' functionality. Contains 'mini.pick' pickers,
|
|
'mini.ai' textobjects, and more.
|
|
|
|
- |MiniFiles| - navigate and manipulate file system. A file explorer with
|
|
column view capable of manipulating file system by editing text. Can
|
|
create/delete/rename/copy/move files/directories inside and across
|
|
directories. For full experience needs enabled |MiniIcons| module (but works
|
|
without it).
|
|
|
|
- |MiniFuzzy| - functions for fast and simple fuzzy matching. It has
|
|
not only functions to perform fuzzy matching of one string to others, but
|
|
also a sorter for |telescope.nvim|.
|
|
|
|
- |MiniGit| - Git integration (https://git-scm.com/). Implements tracking of
|
|
Git related data (root, branch, etc.), |:Git| command for better integration
|
|
with running Neovim instance, and various helpers to explore Git history.
|
|
|
|
- |MiniHipatterns| - highlight patterns in text with configurable highlighters
|
|
(pattern and/or highlight group can be string or callable).
|
|
Works asynchronously with configurable debounce delay.
|
|
|
|
- |MiniHues| - generate configurable color scheme. Takes only background
|
|
and foreground colors as required arguments. Can adjust number of hues
|
|
for non-base colors, saturation, accent color, plugin integration.
|
|
|
|
- |MiniIcons| - icon provider with fixed set of highlight groups.
|
|
Supports various categories, icon and style customizations, caching for
|
|
performance. Integrates with Neovim's filetype matching.
|
|
|
|
- |MiniIndentscope| - visualize and operate on indent scope. Supports
|
|
customization of debounce delay, animation style, and different
|
|
granularity of options for scope computing algorithm.
|
|
|
|
- |MiniJump| - minimal and fast module for smarter jumping to a single
|
|
character.
|
|
|
|
- |MiniJump2d| - minimal and fast Lua plugin for jumping (moving cursor)
|
|
within visible lines via iterative label filtering. Supports custom jump
|
|
targets (spots), labels, hooks, allowed windows and lines, and more.
|
|
|
|
- |MiniMap| - window with buffer text overview, scrollbar, and highlights.
|
|
Allows configurable symbols for line encode and scrollbar, extensible
|
|
highlight integration (with pre-built ones for builtin search, diagnostic,
|
|
git line status), window properties, and more.
|
|
|
|
- |MiniMisc| - collection of miscellaneous useful functions. Like `put()`
|
|
and `put_text()` which print Lua objects to command line and current
|
|
buffer respectively.
|
|
|
|
- |MiniMove| - move any selection in any direction. Supports any Visual
|
|
mode (charwise, linewise, blockwise) and Normal mode (current line) for
|
|
all four directions (left, right, down, up). Respects `count` and undo.
|
|
|
|
- |MiniNotify| - show one or more highlighted notifications in a single window.
|
|
Provides both low-level functions (add, update, remove, clear) and maker
|
|
of |vim.notify()| implementation. Sets up automated LSP progress updates.
|
|
|
|
- |MiniOperators| - various text edit operators: replace, exchange,
|
|
multiply, sort, evaluate. Creates mappings to operate on textobject,
|
|
line, and visual selection. Supports |[count]| and dot-repeat.
|
|
|
|
- |MiniPairs| - autopairs plugin which has minimal defaults and
|
|
functionality to do per-key expression mappings.
|
|
|
|
- |MiniPick| - general purpose interactive non-blocking picker with
|
|
toggleable preview. Has fast default matching with fuzzy/exact/grouped
|
|
modes. Provides most used built-in pickers for files, pattern matches,
|
|
buffers, etc. For full experience needs enabled |MiniIcons| module (but
|
|
works without it).
|
|
|
|
- |MiniSessions| - session management (read, write, delete) which works
|
|
using |mksession|. Implements both global (from configured directory) and
|
|
local (from current directory) sessions.
|
|
|
|
- |MiniSplitjoin| - split and join arguments (regions inside brackets
|
|
between allowed separators). Has customizable pre and post hooks.
|
|
Works inside comments.
|
|
|
|
- |MiniStarter| - minimal, fast, and flexible start screen. Displayed items
|
|
are fully customizable both in terms of what they do and how they look
|
|
(with reasonable defaults). Item selection can be done using prefix query
|
|
with instant visual feedback.
|
|
|
|
- |MiniStatusline| - minimal and fast statusline. Has ability to use custom
|
|
content supplied with concise function (using module's provided section
|
|
functions) along with builtin default. For full experience needs
|
|
enabled |MiniDiff|, |MiniGit|, and |MiniIcons| modules (but works without
|
|
any of them).
|
|
|
|
- |MiniSurround| - fast and feature-rich surround plugin. Add, delete,
|
|
replace, find, highlight surrounding (like pair of parenthesis, quotes,
|
|
etc.). Supports dot-repeat, `v:count`, different search methods,
|
|
"last"/"next" extended mappings, customization via Lua patterns or
|
|
functions, and more. Has builtins for brackets, function call, tag, user
|
|
prompt, and any alphanumeric/punctuation/whitespace character.
|
|
|
|
- |MiniTest| - framework for writing extensive Neovim plugin tests.
|
|
Supports hierarchical tests, hooks, parametrization, filtering (like from
|
|
current file or cursor position), screen tests, "busted-style" emulation,
|
|
customizable reporters, and more. Designed to be used with provided
|
|
wrapper for managing child Neovim processes.
|
|
|
|
- |MiniTabline| - minimal tabline which always shows listed (see 'buflisted')
|
|
buffers. Allows showing extra information section in case of multiple vim
|
|
tabpages. For full experience needs enabled |MiniIcons| module (but works
|
|
without it).
|
|
|
|
- |MiniTrailspace| - automatic highlighting of trailing whitespace with
|
|
functionality to remove it.
|
|
|
|
- |MiniVisits| - track and reuse file system visits. Tracks data about each
|
|
file/directory visit (after delay) and stores it (only) locally. This can be
|
|
used to get a list of "recent"/"frequent"/"frecent" visits.
|
|
Allows persistently adding labels to visits enabling flexible workflow.
|
|
|
|
------------------------------------------------------------------------------
|
|
*mini.nvim-disabling-recipes*
|
|
Common recipes for disabling functionality
|
|
|
|
Each module's core functionality can be disabled globally or buffer-locally
|
|
by creating appropriate global or buffer-scoped variables equal to |v:true|.
|
|
Functionality is disabled if at least one of |g:| or |b:| variables is `v:true`.
|
|
|
|
Variable names have the same structure: `{g,b}:mini*_disable` where `*` is
|
|
module's lowercase name. For example, `g:minianimate_disable` disables
|
|
|mini.animate| globally and `b:minianimate_disable` - for current buffer.
|
|
Note: in this section disabling 'mini.animate' is used as example;
|
|
everything holds for other module variables.
|
|
|
|
Considering high number of different scenarios and customization intentions,
|
|
writing exact rules for disabling module's functionality is left to user.
|
|
|
|
# Manual disabling ~
|
|
>lua
|
|
-- Disable globally
|
|
vim.g.minianimate_disable = true
|
|
|
|
-- Disable for current buffer
|
|
vim.b.minianimate_disable = true
|
|
|
|
-- Toggle (disable if enabled, enable if disabled)
|
|
vim.g.minianimate_disable = not vim.g.minianimate_disable -- globally
|
|
vim.b.minianimate_disable = not vim.b.minianimate_disable -- for buffer
|
|
<
|
|
# Automated disabling ~
|
|
|
|
Automated disabling is suggested to be done inside autocommands: >lua
|
|
|
|
-- Disable for a certain filetype (for example, "lua")
|
|
local f = function(args) vim.b[args.buf].minianimate_disable = true end
|
|
vim.api.nvim_create_autocmd('Filetype', { pattern = 'lua', callback = f })
|
|
|
|
-- Enable only for certain filetypes (for example, "lua" and "help")
|
|
local f = function(args)
|
|
local ft = vim.bo[args.buf].filetype
|
|
if ft == 'lua' or ft == 'help' then return end
|
|
vim.b[args.buf].minianimate_disable = true
|
|
end
|
|
vim.api.nvim_create_autocmd('Filetype', { callback = f })
|
|
|
|
-- Disable in Visual mode
|
|
local f_en = function(args) vim.b[args.buf].minianimate_disable = false end
|
|
local enable_opts = { pattern = '[vV\x16]*:*', callback = f_en }
|
|
vim.api.nvim_create_autocmd('ModeChanged', enable_opts)
|
|
|
|
local f_dis = function(args) vim.b[args.buf].minianimate_disable = true end
|
|
local disable_opts = { pattern = '*:[vV\x16]*', callback = f_dis }
|
|
vim.api.nvim_create_autocmd('ModeChanged', disable_opts)
|
|
|
|
-- Disable in Terminal buffer
|
|
local f = function(args) vim.b[args.buf].minianimate_disable = true end
|
|
vim.api.nvim_create_autocmd('TermOpen', { callback = f })
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*mini.nvim-buffer-local-config*
|
|
Buffer local config
|
|
|
|
Each module can be additionally configured locally to buffer by creating
|
|
appropriate buffer-scoped variable with values you want to override. It
|
|
will affect only runtime options and not those used once during setup (like
|
|
`mappings` or `set_vim_settings`).
|
|
|
|
Variable names have the same structure: `b:mini*_config` where `*` is
|
|
module's lowercase name. For example, `b:minianimate_config` can store
|
|
information about how |mini.animate| will act inside current buffer. Its
|
|
value should be a table with same structure as module's `config`. Example: >lua
|
|
|
|
-- Disable scroll animation in current buffer
|
|
vim.b.minianimate_config = { scroll = { enable = false } }
|
|
<
|
|
Considering high number of different scenarios and customization intentions,
|
|
writing exact rules for module's buffer local configuration is left to
|
|
user. It is done in similar fashion to |mini.nvim-disabling-recipes|.
|
|
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl: |