================================================================================

*mini.nvim*

|mini.nvim| is a collection of minimal, independent, and fast Lua modules

dedicated to improve Neovim (version 0.5 and higher) experience. Each module

can be considered as a separate sub-plugin.

# 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 (if needed) should be setup separately with

`require(<name of module>).setup({})` (possibly replace {} with your

config table or omit to use defaults). You can supply only values which

differ from defaults, which will be used for the rest ones.

- 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()`).

- <Disabling>. Each module's core functionality can be disabled globally or

buffer-locally by creating appropriate global or buffer-scoped variables with

|v:true| value. For example:

- To disable `MiniSurround` globally run `:let g:minisurround_disable=v:true`.

- To disable `MiniSurround` for current buffer run `:let b:minisurround_disable=v:true`.

- To toggle `MiniSurround` globally (disable if enabled, enable if

disabled) use of Lua is more appropriate:

`:lua vim.g.minisurround_disable = not vim.g.minisurround_disable`.

- <Highlight groups>. Appearance of module's output is controlled by certain

highlight group (see |highlight-groups|). To customize them, use |highlight|

command. Note: currently not many Neovim themes support this plugin's

highlight groups; fixing this situation is highly appreciated. To see a more

calibrated look, use |MiniBase16| or plugin's colorscheme `minischeme`.

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

- |MiniBase16| - fast implementation of base16 theme for manually supplied

palette. Has unique palette generator which needs only background and

foreground colors.

- |MiniBufremove| - buffer removing (unshow, delete, wipeout) while saving

window layout.

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

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

- |MiniJump| - minimal and fast module for smarter jumping to a single

character.

- |MiniMisc| - collection of miscellaneous useful functions. Like `put()` and

`put_text()` which print Lua objects to command line and current buffer

respectively.

- |MiniPairs| - autopairs plugin which has minimal defaults and functionality

to do per-key expression mappings.

- |MiniSessions| - session management (read, write, delete) which works using

|mksession|. Implements both global (from configured directory) and local

(from current directory) sessions.

- |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 [Nerd

font](https://www.nerdfonts.com/),

[gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim) plugin, and

[nvim-web-devicons](https://github.com/kyazdani42/nvim-web-devicons) plugin

(but works without any them).

- |MiniSurround| - fast surround plugin. Add, delete, replace, find, highlight

surrounding (like pair of parenthesis, quotes, etc.). Has special "function

call", "tag", and "interactive" surroundings. Supports dot-repeatability,

textobject, motions.

- |MiniTabline| - minimal tabline which shows listed (see 'buflisted') buffers

in case of one tab and falls back to default otherwise. For full experience

needs [nvim-web-devicons](https://github.com/kyazdani42/nvim-web-devicons).

- |MiniTrailspace| - automatic highlighting of trailing whitespace with

functionality to remove it.

# Plugin colorscheme

This plugin comes with an official colorscheme named `minischeme`. This is a

|MiniBase16| theme created with faster version of the following Lua code:

`require('mini.base16').setup({palette = palette, name = 'minischeme',

use_cterm = true})` where `palette` is:

- For dark 'background': `require('mini.base16').mini_palette('#112641',

'#e2e98f', 75)`

- For light 'background': `require('mini.base16').mini_palette('#e2e5ca',

'#002a83', 75)`

Activate it as a regular |colorscheme|.

================================================================================

*MiniBase16* *mini.base16*

Custom minimal and fast Lua module which implements

[base16](http://chriskempson.com/projects/base16/) color scheme (with Copyright

(C) 2012 Chris Kempson) adapated for modern Neovim 0.5 Lua plugins. Extra

features:

- Configurable automatic support of cterm colors (see |highlight-cterm|).

- Opinionated palette generator based only on background and foreground colors.

# Setup

This module needs a setup with `require('mini.base16').setup({})` (replace `{}`

with your `config` table). It will create global Lua table `MiniBase16` which

you can use for scripting or manually (with `:lua MiniBase16.*`).

Default `config`:

>

{

-- Table with names from `base00` to `base0F` and values being strings of HEX

-- colors with format "#RRGGBB". NOTE: this should be explicitly supplied in

-- `setup()`.

palette = nil,

-- Whether to support cterm colors. Can be boolean, `nil` (same as `false`),

-- or table with cterm colors. See `setup()` documentation for more

-- information.

use_cterm = nil,

}

<

Example:

>

require('mini.base16').setup({

palette = {

base00 = '#112641',

base01 = '#3a475e',

base02 = '#606b81',

base03 = '#8691a7',

base04 = '#d5dc81',

base05 = '#e2e98f',

base06 = '#eff69c',

base07 = '#fcffaa',

base08 = '#ffcfa0',

base09 = '#cc7e46',

base0A = '#46a436',

base0B = '#9ff895',

base0C = '#ca6ecf',

base0D = '#42f7ff',

base0E = '#ffc4ff',

base0F = '#00a5c5',

},

use_cterm = true,

})

<

# Notes

1. This module is used for creating plugin's official colorscheme named

`minischeme` (see |mini.nvim|).

2. Using `setup()` doesn't actually create a |colorscheme|. It basically

creates a coordinated set of |highlight|s. To create your own theme:

- Put "myscheme.lua" file (name after your chosen theme name) inside any

"colors" directory reachable from 'runtimepath' ("colors" inside your

Neovim config directory is usually enough).

- Inside "myscheme.lua" call `require('mini.base16').setup()` with your

palette and only after that set |g:colors_name| to "myscheme".

MiniBase16.setup({config}) *MiniBase16.setup()*

Module setup

Setup is done by applying base16 palette to enable colorscheme. Highlight

groups make an extended set from original

[base16-vim](https://github.com/chriskempson/base16-vim/) plugin. It is a

good idea to have `config.palette` respect the original [styling

principles](https://github.com/chriskempson/base16/blob/master/styling.md).

By default only 'gui highlighting' (see |highlight-gui| and

|termguicolors|) is supported. To support 'cterm highlighting' (see

|highlight-cterm|) supply `config.use_cterm` argument in one of the

formats:

- `true` to auto-generate from `palette` (as closest colors).

- Table with similar structure to `palette` but having terminal colors

(integers from 0 to 255) instead of hex strings.

Parameters: ~

{config} (table) Module config table.

Usage: ~

`require('mini.base16').setup({})` (replace `{}` with your `config`

table; `config.palette` should be a table with colors)

MiniBase16.mini_palette({background}, {foreground}, {accent_chroma}) *MiniBase16.mini_palette()*

Create 'mini' palette

Create base16 palette based on the HEX (string '#RRGGBB') colors of main

background and foreground with optional setting of accent chroma (see

details).

# Algorithm design

- Main operating color space is

[CIELCh(uv)](https://en.wikipedia.org/wiki/CIELUV#Cylindrical_representation_(CIELCh))

which is a cylindrical representation of a perceptually uniform CIELUV

color space. It defines color by three values: lightness L (values from 0

to 100), chroma (positive values), and hue (circular values from 0 to 360

degress). Useful converting tool: https://www.easyrgb.com/en/convert.php

- There are four important lightness values: background, foreground, focus

(around the middle of background and foreground, leaning towards

foreground), and edge (extreme lightness closest to foreground).

- First four colors have the same chroma and hue as `background` but

lightness progresses from background towards focus.

- Second four colors have the same chroma and hue as `foreground` but

lightness progresses from foreground towards edge in such a way that

'base05' color is main foreground color.

- The rest eight colors are accent colors which are created in pairs

- Each pair has same hue from set of hues 'most different' to

background and foreground hues (if respective chorma is positive).

- All colors have the same chroma equal to `accent_chroma` (if not

provided, chroma of foreground is used, as they will appear next to

each other). Note: this means that in case of low foreground chroma,

it is a good idea to set `accent_chroma` manually. Values from 30

(low chorma) to 80 (high chroma) are common.

- Within pair there is base lightness (equal to foreground lightness)

and alternative (equal to focus lightness). Base lightness goes to

colors which will be used more frequently in code: base08

(variables), base0B (strings), base0D (functions), base0E (keywords).

How exactly accent colors are mapped to base16 palette is a result of

trial and error. One rule of thumb was: colors within one hue pair

should be more often seen next to each other. This is because it is

easier to distinguish them and seems to be more visually appealing.

That is why `base0D` and `base0F` have same hues because they usually

represent functions and delimiter (brackets included).

Parameters: ~

{background} (string) Background HEX color (formatted as

`#RRGGBB`).

{foreground} (string) Foreground HEX color (formatted as

`#RRGGBB`).

{accent_chroma} (number) Optional positive number (usually between 0

and 100). Default: chroma of foreground

color.

Return: ~

table: Table with base16 palette.

Usage: ~

`local palette = require('mini.base16').mini_palette('#112641',

'#e2e98f', 75)`

`require('mini.base16').setup({palette = palette})`

MiniBase16.rgb_palette_to_cterm_palette({palette}) *MiniBase16.rgb_palette_to_cterm_palette()*

Converts palette with RGB colors to terminal colors

Useful for caching `use_cterm` variable to increase speed.

Parameters: ~

{palette} (table) Table with base16 palette (same as in

`MiniBase16.config.palette`).

Return: ~

table: Table with base16 palette using |highlight-cterm|.

================================================================================

*MiniBufremove* *mini.bufremove*

Lua module for minimal buffer removing (unshow, delete, wipeout), which saves

window layout (opposite to builtin Neovim's commands). This is mostly a Lua

implementation of

[bclose.vim](https://vim.fandom.com/wiki/Deleting_a_buffer_without_closing_the_window).

Other alternatives:

- [vim-bbye](https://github.com/moll/vim-bbye)

- [vim-sayonara](https://github.com/mhinz/vim-sayonara)

# Setup

This module doesn't need setup, but it can be done to improve usability. Setup

with `require('mini.bufremove').setup({})` (replace `{}` with your `config`

table). It will create global Lua table `MiniBufremove` which you can use for

scripting or manually (with `:lua MiniBufremove.*`).

Default `config`:

>

{

-- Whether to set Vim's settings for buffers (allow hidden buffers)

set_vim_settings = true,

}

<

# Notes

1. Which buffer to show in window(s) after its current buffer is removed is

decided by the algorithm:

- If alternate buffer (see |CTRL-^|) is listed (see |buflisted()|), use it.

- If previous listed buffer (see |bprevious|) is different, use it.

- Otherwise create a scratch one with `nvim_create_buf(true, true)` and use

it.

# Disabling

To disable core functionality, set `g:minibufremove_disable` (globally) or

`b:minibufremove_disable` (for a buffer) to `v:true`.

MiniBufremove.setup({config}) *MiniBufremove.setup()*

Module setup

Parameters: ~

{config} (table) Module config table.

Usage: ~

`require('mini.bufremove').setup({})` (replace `{}` with your `config`

table)

MiniBufremove.delete({buf_id}, {force}) *MiniBufremove.delete()*

Delete buffer `buf_id` with |:bdelete| after unshowing it.

Parameters: ~

{buf_id} (number) Buffer identifier (see |bufnr()|) to use. Default:

0 for current.

{force} (boolean) Whether to ignore unsaved changes (using `!`

version of command). Default: `false`.

Return: ~

boolean: Whether operation was successful.

MiniBufremove.wipeout({buf_id}, {force}) *MiniBufremove.wipeout()*

Wipeout buffer `buf_id` with |:bwipeout| after unshowing it.

Parameters: ~

{buf_id} (number) Buffer identifier (see |bufnr()|) to use. Default:

0 for current.

{force} (boolean) Whether to ignore unsaved changes (using `!`

version of command). Default: `false`.

Return: ~

boolean: Whether operation was successful.

MiniBufremove.unshow({buf_id}) *MiniBufremove.unshow()*

Stop showing buffer `buf_id` in all windows

Parameters: ~

{buf_id} (number) Buffer identifier (see |bufnr()|) to use. Default:

0 for current.

Return: ~

boolean: Whether operation was successful.

MiniBufremove.unshow_in_window({win_id}) *MiniBufremove.unshow_in_window()*

Stop showing current buffer of window `win_id`

Parameters: ~

{win_id} (number) Window identifier (see |win_getid()|) to use.

Default: 0 for current.

Return: ~

boolean: Whether operation was successful.

================================================================================

*MiniComment* *mini.comment*

Custom minimal and fast Lua module for code commenting. This is basically a

reimplementation of "tpope/vim-commentary". Commenting in Normal mode respects

|count| and is dot-repeatable. Comment structure is inferred from

'commentstring'. Handles both tab and space indenting (but not when they are

mixed).

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.

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

Default `config`:

>

{

-- 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',

}

}

<

# Disabling

To disable core functionality, set `g:minicomment_disable` (globally) or

`b:minicomment_disable` (for a buffer) to `v:true`.

MiniComment.setup({config}) *MiniComment.setup()*

Module setup

Parameters: ~

{config} (table) Module config table.

Usage: ~

`require('mini.comment').setup({})` (replace `{}` with your `config`

table)

MiniComment.operator({mode}) *MiniComment.operator()*

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) Optional string with 'operatorfunc' mode (see |g@|).

Return: ~

string: 'g@' if called without argument, '' otherwise (but after

performing action).

MiniComment.toggle_lines({line_start}, {line_end}) *MiniComment.toggle_lines()*

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

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

{line_end} (number) End line number.

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

================================================================================

*MiniCompletion* *mini.completion*

Custom somewhat minimal autocompletion Lua plugin. Key design ideas:

- Have an async (with customizable 'debounce' delay) 'two-stage chain

completion': first try to get completion items from LSP client (if set up)

and if no result, fallback to custom action.

- Managing completion is done as much with Neovim's built-in tools as possible.

Features:

- Two-stage chain completion:

- First stage is an LSP completion implemented via

|MiniCompletion.completefunc_lsp()|. It should be set up as either

|completefunc| or |omnifunc|. It tries to get completion items from LSP

client (via 'textDocument/completion' request). Custom preprocessing of

response items is possible (with

`MiniCompletion.config.lsp_completion.process_items`), for example with

fuzzy matching. By default items which are not snippets and directly

start with completed word are kept and sorted according to LSP

specification.

- If first stage is not set up or resulted into no candidates, fallback

action is executed. The most tested actions are Neovim's built-in insert

completion (see |ins-completion|).

- Automatic display in floating window of completion item info and signature

help (with highlighting of active parameter if LSP server provides such

information). After opening, window for signature help is fixed and is closed

when there is nothing to show, text is different or when leaving Insert mode.

- Automatic actions are done after some configurable amount of delay. This

reduces computational load and allows fast typing (completion and signature

help) and item selection (item info)

- Autoactions are triggered on Neovim's built-in events.

- User can force two-stage completion via |MiniCompletion.complete_twostage()|

(by default is mapped to `<C-Space>`) or fallback completion via

|MiniCompletion.complete_fallback()| (maped to `<M-Space>`).

What it doesn't do:

- Snippet expansion.

- Many configurable sources.

# Setup

This module needs a setup with `require('mini.completion').setup({})` (replace

`{}` with your `config` table). It will create global Lua table

`MiniCompletion` which you can use for scripting or manually (with `:lua

MiniCompletion.*`).

Default `config`:

>

{

-- Delay (debounce type, in ms) between certain Neovim event and action.

-- This can be used to (virtually) disable certain automatic actions by

-- setting very high delay time (like 10^7).

delay = {completion = 100, info = 100, signature = 50},

-- Maximum dimensions of floating windows for certain actions. Action entry

-- should be a table with 'height' and 'width' fields.

window_dimensions = {

info = {height = 25, width = 80},

signature = {height = 25, width = 80}

},

-- Way of how module does LSP completion:

-- - `source_func` should be one of 'completefunc' or 'omnifunc'.

-- - `auto_setup` should be boolean indicating if LSP completion is set up on

-- every `BufEnter` event.

-- - `process_items` should be a function which takes LSP

-- 'textDocument/completion' response items and word to complete. Its

-- output should be a table of the same nature as input items. The most

-- common use-cases are custom filtering and sorting. You can use

-- default `process_items` as `MiniCompletion.default_process_items()`.

lsp_completion = {

source_func = 'completefunc',

auto_setup = true,

process_items = --<function: filters 'not snippets' by prefix and sorts by LSP specification>,

},

-- Fallback action. It will always be run in Insert mode. To use Neovim's

-- built-in completion (see `:h ins-completion`), supply its mapping as

-- string. For example, to use 'whole lines' completion, supply '<C-x><C-l>'.

fallback_action = --<function equivalent to '<C-n>' completion>,

-- Module mappings. Use `''` (empty string) to disable one. Some of them

-- might conflict with system mappings.

mappings = {

force_twostep = '<C-Space>', -- Force two-step completion

force_fallback = '<A-Space>' -- Force fallback completion

}

-- Whether to set Vim's settings for better experience (modifies

-- `shortmess` and `completeopt`)

set_vim_settings = true

}

<

# Notes

- More appropriate, albeit slightly advanced, LSP completion setup is to set it

not on every `BufEnter` event (default), but on every attach of LSP client.

To do that:

- Use in initial config: `lsp_completion = {source_func = 'omnifunc',

auto_setup = false}`.

- In `on_attach()` of every LSP client set 'omnifunc' option to exactly

`v:lua.MiniCompletion.completefunc_lsp`.

# Comparisons

- 'nvim-cmp':

- More complex design which allows multiple sources each in form of

separate plugin. `MiniCompletion` has two built in: LSP and fallback.

- Supports snippet expansion.

- Doesn't have customizable delays for basic actions.

- Doesn't allow fallback action.

- Doesn't provide signature help.

# Helpful key mappings

To use `<Tab>` and `<S-Tab>` for navigation through completion list, make these

key mappings:

`vim.api.nvim_set_keymap('i', [[<Tab>]], [[pumvisible() ? "\<C-n>" : "\<Tab>"]], { noremap = true, expr = true })`

`vim.api.nvim_set_keymap('i', [[<S-Tab>]], [[pumvisible() ? "\<C-p>" : "\<S-Tab>"]], { noremap = true, expr = true })`

# Highlight groups

1. `MiniCompletionActiveParameter` - highlighting of signature active

parameter. Default: plain underline.

To change any highlight group, modify it directly with |:highlight|.

# Disabling

To disable, set `g:minicompletion_disable` (globally) or

`b:minicompletion_disable` (for a buffer) to `v:true`.

MiniCompletion.setup({config}) *MiniCompletion.setup()*

Module setup

Parameters: ~

{config} (table) Module config table.

Usage: ~

`require('mini.completion').setup({})` (replace `{}` with your

`config` table)

MiniCompletion.auto_completion() *MiniCompletion.auto_completion()*

Auto completion

Designed to be used with |autocmd|. No need to use it directly, everything

is setup in |MiniCompletion.setup|.

MiniCompletion.complete_twostage({fallback}, {force}) *MiniCompletion.complete_twostage()*

Run two-stage completion

Parameters: ~

{fallback} (boolean) Whether to use fallback completion.

{force} (boolean) Whether to force update of completion popup.

MiniCompletion.complete_fallback() *MiniCompletion.complete_fallback()*

Run fallback completion

MiniCompletion.auto_info() *MiniCompletion.auto_info()*

Auto completion entry information

Designed to be used with |autocmd|. No need to use it directly, everything

is setup in |MiniCompletion.setup|.

MiniCompletion.auto_signature() *MiniCompletion.auto_signature()*

Auto function signature

Designed to be used with |autocmd|. No need to use it directly, everything

is setup in |MiniCompletion.setup|.

MiniCompletion.stop({actions}) *MiniCompletion.stop()*

Stop actions

This stops currently active (because of module delay or LSP answer delay)

actions.

Designed to be used with |autocmd|. No need to use it directly, everything

is setup in |MiniCompletion.setup|.

Parameters: ~

{actions} (table) Array containing any of 'completion', 'info', or

'signature' string.

MiniCompletion.on_text_changed_i() *MiniCompletion.on_text_changed_i()*

Act on every |TextChangedI|

MiniCompletion.on_text_changed_p() *MiniCompletion.on_text_changed_p()*

Act on every |TextChangedP|

MiniCompletion.completefunc_lsp() *MiniCompletion.completefunc_lsp()*

Module's |complete-function|

This is the main function which enables two-stage completion. It should be

set as one of |completefunc| or |omnifunc|.

No need to use it directly, everything is setup in |MiniCompletion.setup|.

MiniCompletion.default_process_items() *MiniCompletion.default_process_items()*

Default `MiniCompletion.config.lsp_completion.process_items`.

================================================================================

*MiniCursorword* *mini.cursorword*

Custom minimal and fast module for autohighlighting word under cursor with

customizable delay. Current word under cursor can be highlighted differently.

Highlighting is triggered only if current cursor character is a |[:keyword:]|.

"Word under cursor" is meant as in Vim's |<cword>|: something user would get as

'iw' text object. Highlighting stops in insert and terminal modes.

# Setup

This module needs a setup with `require('mini.cursorword').setup({})` (replace

`{}` with your `config` table). It will create global Lua table

`MiniCursorword` which you can use for scripting or manually (with `:lua

MiniCursorword.*`).

Default `config`:

>

{

-- Delay (in ms) between when cursor moved and when highlighting appeared

delay = 100,

}

<

# Highlight groups

1. `MiniCursorword` - highlight group of cursor word. Default: plain underline.

2. `MiniCursorwordCurrent` - highlight group of a current word under cursor. It

will be displayed on top of `MiniCursorword` (so `:hi clear

MiniCursorwordCurrent` will lead to showing `MiniCursorword` highlight

group). Default: link to `MiniCursorword`. Note: To not highlight it, use

`:hi! MiniCursorwordCurrent gui=nocombine guifg=NONE guibg=NONE` .

To change any highlight group, modify it directly with |:highlight|.

# Disabling

To disable core functionality, set `g:minicursorword_disable` (globally) or

`b:minicursorword_disable` (for a buffer) to `v:true`. Note: after disabling

there might be highlighting left; it will be removed after next highlighting

update.

MiniCursorword.setup({config}) *MiniCursorword.setup()*

Module setup

Parameters: ~

{config} (table) Module config table.

Usage: ~

`require('mini.cursorword').setup({})` (replace `{}` with your

`config` table)

MiniCursorword.auto_highlight() *MiniCursorword.auto_highlight()*

Auto highlight word under cursor

Designed to be used with |autocmd|. No need to use it directly, everything

is setup in |MiniCursorword.setup|.

MiniCursorword.auto_unhighlight() *MiniCursorword.auto_unhighlight()*

Auto unhighlight word under cursor

Designed to be used with |autocmd|. No need to use it directly, everything

is setup in |MiniCursorword.setup|.

================================================================================

*MiniFuzzy* *mini.fuzzy*

Lua module which implements minimal and fast fuzzy matching.

# Setup

This module doesn't need setup, but it can be done to improve usability. Setup

with `require('mini.fuzzy').setup({})` (replace `{}` with your `config` table).

It will create global Lua table `MiniFuzzy` which you can use for scripting or

manually (with `:lua MiniFuzzy.*`).

Default `config`:

>

{

-- Maximum allowed value of match features (width and first match). All

-- feature values greater than cutoff can be considered "equally bad".

cutoff = 100,

}

<

# Notes

1. Currently there is no explicit design to work with multibyte symbols, but

simple examples should work.

2. Smart case is used: case insensitive if input word (which is usually a user

input) is all lower ase. Case sensitive otherwise.

# Algorithm design

General design uses only width of found match and index of first letter match.

No special characters or positions (like in fzy and fzf) are used.

Given input `word` and target `candidate`:

- The goal is to find matching between `word`'s letters and letters in

`candidate`, which minimizes certain score. It is assumed that order of

letters in `word` and those matched in `candidate` should be the same.

- Matching is represented by matched positions: an array `positions` of

integers with length equal to number of letter in `word`. The following

should be always true in case of a match: `candidate`'s letter at index

`positions[i]` is letters[i]` for all valid `i`.

- Matched positions are evaluated based only on two features: their width

(number of indexes between first and last positions) and first match (index

of first letter match). There is a global setting `cutoff` for which all

feature values greater than it can be considered "equally bad".

- Score of matched positions is computed with following explicit formula:

`cutoff * min(width, cutoff) + min(first, cutoff)`. It is designed to be

equivalent to first comparing widths (lower is better) and then comparing

first match (lower is better). For example, if `word = 'time'`:

- '_time' (width 4) will have a better match than 't_ime' (width 5).

- 'time_a' (width 4, first 1) will have a better match than 'a_time' (width

4, first 3).

- Final matched positions are those which minimize score among all possible

matched positions of `word` and `candidate`.

MiniFuzzy.setup({config}) *MiniFuzzy.setup()*

Module setup

Parameters: ~

{config} (table) Module config table.

Usage: ~

`require('mini.fuzzy').setup({})` (replace `{}` with your `config`

table)

MiniFuzzy.match({word}, {candidate}) *MiniFuzzy.match()*

Compute match data of input `word` and `candidate` strings

It tries to find best match for input string `word` (usually user input)

and string `candidate`. Returns table with elements:

- `positions` - array with letter indexes inside `candidate` which matched

to corresponding letters in `word`. Or `nil` if no match.

- `score` - positive number representing how good the match is (lower is

better). Or `-1` if no match.

Parameters: ~

{word} (string) Input word (usually user input).

{candidate} (string) Target word (usually with which matching is

done).

Return: ~

table: Table with matching information (see function's description).

MiniFuzzy.filtersort({word}, {candidate_array}) *MiniFuzzy.filtersort()*

Filter string array

This leaves only those elements of input array which matched with `word`

and sorts from best to worst matches (based on score and index in original

array, both lower is better).

Parameters: ~

{word} (string) String which will be searched.

{candidate_array} (table) Lua array of strings inside which word

will be searched.

Return: ~

tuple: Arrays of matched candidates and their indexes in original

input.

MiniFuzzy.process_lsp_items({items}, {base}) *MiniFuzzy.process_lsp_items()*

Fuzzy matching for |MiniCompletion.lsp_completion.process_items|

Parameters: ~

{items} (table) Lua array with LSP 'textDocument/completion'

response items.

{base} (string) Word to complete.

MiniFuzzy.get_telescope_sorter({opts}) *MiniFuzzy.get_telescope_sorter()*

Custom getter for `telescope.nvim` sorter

Designed to be used as value for |telescope.defaults.file_sorter| and

|telescope.defaults.generic_sorter| inside `setup()` call.

Parameters: ~

{opts} (table) Options (currently not used).

Usage: ~

`require('telescope').setup({defaults = {generic_sorter =

require('mini.fuzzy').get_telescope_sorter}})`

================================================================================

*MiniJump* *mini.jump*

Minimal and fast module for smarter jumping to a single character. Inspired by

'rhysd/clever-f.vim'.

Features:

- Extend f, F, t, T to work on multiple lines.

- Repeat jump by pressing f, F, t, T again. It is reset when cursor moved as a

result of not jumping.

- Highlight (after customizable delay) of all possible target characters.

- Normal, Visual, and Operator-pending (with full dot-repeat) modes are

supported.

# Setup

This module needs a setup with `require('mini.jump').setup({})` (replace `{}`

with your `config` table). It will create global Lua table `MiniJump` which you

can use for scripting or manually (with `:lua MiniJump.*`).

Default `config`:

>

{

-- Mappings. Use `''` (empty string) to disable one.

mappings = {

forward = 'f',

backward = 'F',

forward_till = 't',

backward_till = 'T',

repeat_jump = ';',

},

-- Delay (in ms) between jump and highlighting all possible jumps. Set to a

-- very big number (like 10^7) to virtually disable highlighting.

highlight_delay = 250,

}

<

#Highlight groups

- `MiniJump` - all possible cursor positions.

# Disabling

To disable core functionality, set `g:minijump_disable` (globally) or

`b:minijump_disable` (for a buffer) to `v:true`.

MiniJump.setup({config}) *MiniJump.setup()*

Module setup

Parameters: ~

{config} (table) Module config table.

Usage: ~

`require('mini.jump').setup({})` (replace `{}` with your `config`

table)

MiniJump.jump({target}, {backward}, {till}, {n_times}) *MiniJump.jump()*

Jump to target

Takes a string and jumps to its first occurrence in desrired direction.

Parameters: ~

{target} (string) The string to jump to.

{backward} (boolean) Whether to jump backward. Default: latest used

value or `false`.