8000 mini.nvim/lua/mini/init.lua at main · tonyrt2/mini.nvim · GitHub
[go: up one dir, main page]
Skip to content
7FFF

init.lua

Latest commit

 

History

History
421 lines (416 loc) · 23 KB

init.lua

File metadata and controls

421 lines (416 loc) · 23 KB
Raw
--- *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.9 and higher) experience. Each
--- module can be considered as a separate sub-plugin.
---
--- Table of contents:
--- General overview ............................................... |mini.nvim|
--- Disabling recipes ............................ |mini.nvim-disabling-recipes|
--- Buffer-local config ........................ |mini.nvim-buffer-local-config|
--- Plugin color schemes ............................. |mini.nvim-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|
--- Special key mappings ......................................... |mini.keymap|
--- 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|
--- Manage and expand snippets ................................. |mini.snippets|
--- 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()`).
---
--- - If module works best with some specific non-default option value, it
--- is set during `setup()`. If the value is not essential to module's
--- functionality, it is done only if user or another plugin hasn't set
--- it beforehand (no matter the value).
---
--- - <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.
---
--- - <Buffer names>. All module-related buffers are named according to the
--- following format: `mini<module-name>://<buffer-number>/<useful-info>`
--- (forward slashes are used on any platform; `<useful-info>` may be empty).
--- This structure allows creating identifiable, reasonably unique, and useful
--- buffer names. For example, |MiniFiles| buffers are created per displayed
--- directory/file with names like `minifiles://10/path/to/displayed/directory`.
---
--- - <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.
---
--- - <Not filetype/language specific>. Including functionality which needs
--- several filetype/language specific implementations is an explicit no-goal
--- of this project. This is mostly due to the potential increase in maintenance
--- to keep implementation up to date. However, any part which might need
--- filetype/language specific tuning should be designed to allow it by letting
--- user set proper buffer options and/or local configuration.
---
--- # 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.
---
--- - |MiniKeymap| - utilities to make special key mappings: multi-step actions
--- (with built-in steps for "smart" <Tab>, <S-Tab>, <CR>, <BS>),
--- combos (more general version of "better escape" like behavior).
---
--- - |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.
---
--- - |MiniSnippets| - manage and expand snippets. Supports only syntax from LSP
--- specification. Provides flexible loaders to manage snippet files, exact and
--- fuzzy prefix matching, interactive selection, and rich interactive snippet
--- session experience with dynamic tabstop visualization.
---
--- - |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.
--- 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 })
--- <
---@tag mini.nvim-disabling-recipes
--- Buffer local config
---
--- Each module can be additionally configured locally to buffer by creating
--- appropriate buffer-scoped variable with values to override. It affects only
--- runtime options and not those used once during setup (like most `mappings`).
---
--- 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|.
---@tag mini.nvim-buffer-local-config
--- Plugin color schemes
---
--- - Color schemes based on |mini.hues|: |MiniHues-color-schemes|.
--- - Color schemes based on |mini.base16|: |MiniBase16-color-schemes|.
---@tag mini.nvim-color-schemes
vim.notify([[Do not `require('mini')` directly. Setup every module separately.]])
return {}
0