mini.txt

*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 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|
  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.

- |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.

------------------------------------------------------------------------------
                                                   *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 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|.


 vim:tw=78:ts=8:noet:ft=help:norl: