` (first make split by `_`): >
a _b_c
aa_bb_cc
<
Ignore some split matches. It modifies `split_exclude_patterns` option by
adding commonly wanted patterns. See more details in
|MiniAlign.gen_step.ignore_split()|.
Before: >
/* This_is_assumed_to_be_comment */
a"_"_b
aa_bb
<
After typing `_i` (first make split by `_`): >
/* This_is_assumed_to_be_comment */
a"_"_b
aa _bb
<
Pair neighboring parts.
Before: >
a_b_c
aaa_bbb_ccc
<
After typing `_p` (first make split by `_`): >
a_ b_ c
aaa_bbb_ccc
<
Trim parts from whitespace on both sides (keeping indentation).
Before: >
a _ b _ c
aa _bb _cc
<
After typing `_t` (first make split by `_`): >
a _b _c
aa_bb_cc
<
# Delete some last pre-step ~
Delete one of the pre-steps. If there is only one kind of pre-steps,
remove its latest added one. If not, prompt user to choose pre-step kind
by entering single character: `s`plit, `j`ustify, `m`erge.
Examples:
- `tp` results in only "trim" step to be left.
- `it` prompts to choose which step to delete (pre-split or
pre-justify in this case).
# Special configurations for common splits ~
<=> Use special pattern to align by a group of consecutive "=". It can be
preceded by any number of punctuation marks and followed by some sommon
punctuation characters. Trim whitespace and merge with single space.
Before: >
a=b
aa<=bb
aaa===bbb
aaaa = cccc
<
After typing `=`: >
a = b
aa <= bb
aaa === bbb
aaaa = cccc
<
<,> Besides splitting by "," character, trim whitespace, pair neighboring
parts and merge with single space.
Before: >
a,b
aa,bb
aaa , bbb
<
After typing `,`: >
a, b
aa, bb
aaa, bbb
<
<|> Split by "|" character, trim whitespace, merge with single space.
Before: >
|a|b|
|aa|bb|
|aaa | bbb |
<
After typing `|`: >
| a | b |
| aa | bb |
| aaa | bbb |
<
(Space bar) Squash consecutive whitespace into single space (except
possible indentation) and split by `%s+` pattern (keeps indentation).
Before: >
a b c
aa bb cc
<
After typing ``: >
a b c
aa bb cc
<
------------------------------------------------------------------------------
*MiniAlign-examples*
Copy lines in modifiable buffer, initiate alignment with preview (`gAip`)
and try typing suggested key sequences.
These are modified examples taken from 'junegunn/vim-easy-align'.
# Equal sign ~
Lines: >
# This=is=assumed=to be a comment
"a ="
a =
a = 1
bbbb = 2
ccccccc = 3
ccccccccccccccc
ddd = 4
eeee === eee = eee = eee=f
fff = ggg += gg &&= gg
g != hhhhhhhh == 888
i := 5
i %= 5
i *= 5
j =~ 5
j >= 5
aa => 123
aa <<= 123
aa >>= 123
bbb => 123
c => 1233123
d => 123
dddddd &&= 123
dddddd ||= 123
dddddd /= 123
gg <=> ee
<
Key sequences:
- `=`
- `=jc`
- `=jr`
- `=m!`
- `=p`
- `=i` (execute `:lua vim.o.commentstring = '# %s'` for full experience)
- `=`
- `=p`
- `=fn==1`
- `=fn==1t`
- `=frow>7`
------------------------------------------------------------------------------
*MiniAlign.setup()*
`MiniAlign.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniAlign.config|.
Usage ~
>lua
require('mini.align').setup() -- use default config
-- OR
require('mini.align').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniAlign.config*
`MiniAlign.config`
Defaults ~
>lua
MiniAlign.config = {
-- Module mappings. Use `''` (empty string) to disable one.
mappings = {
start = 'ga',
start_with_preview = 'gA',
},
-- Modifiers changing alignment steps and/or options
modifiers = {
-- Main option modifiers
['s'] = --,
['j'] = --,
['m'] = --,
-- Modifiers adding pre-steps
['f'] = --,
['i'] = --,
['p'] = --,
['t'] = --,
-- Delete some last pre-step
[''] = --,
-- Special configurations for common splits
['='] = --,
['|'] = --,
[' '] = --,
},
-- Default options controlling alignment process
options = {
split_pattern = '',
justify_side = 'left',
merge_delimiter = '',
},
-- Default steps performing alignment (if `nil`, default is used)
steps = {
pre_split = {},
split = nil,
pre_justify = {},
justify = nil,
pre_merge = {},
merge = nil,
},
-- Whether to disable showing non-error feedback
-- This also affects (purely informational) helper messages shown after
-- idle time if user input is required.
silent = false,
}
<
# Modifiers ~
`MiniAlign.config.modifiers` is used to define interactive user experience
of managing alignment process. It is a table with single character keys and
modifier function values.
Each modifier function:
- Is called when corresponding modifier key is pressed.
- Has signature `(steps, opts)` and should modify any of its input in place.
Examples:
- Modifier function used for default 'i' modifier: >lua
function(steps, _)
table.insert(steps.pre_split, MiniAlign.gen_step.ignore_split())
end
<
- Tweak 't' modifier to use highest indentation instead of keeping it: >lua
require('mini.align').setup({
modifiers = {
t = function(steps, _)
local trim_high = MiniAlign.gen_step.trim('both', 'high')
table.insert(steps.pre_justify, trim_high)
end
}
})
<
- Tweak `j` modifier to cycle through available "justify_side" option
values (like in 'junegunn/vim-easy-align'): >lua
require('mini.align').setup({
modifiers = {
j = function(_, opts)
local next_option = ({
left = 'center', center = 'right', right = 'none', none = 'left',
})[opts.justify_side]
opts.justify_side = next_option or 'left'
end,
},
})
<
# Options ~
`MiniAlign.config.options` defines default values of options used to control
behavior of steps.
Examples:
- Set `justify_side = 'center'` to center align at initialization.
For more details about options see |MiniAlign.align_strings()| and entries of
|MiniAlign.gen_step| for default main steps.
# Steps ~
`MiniAlign.config.steps` defines default steps to be applied during
alignment process.
Examples:
- Align by default only first pair of columns: >lua
local align = require('mini.align')
align.setup({
steps = {
pre_justify = { align.gen_step.filter('n == 1') }
},
})
<
------------------------------------------------------------------------------
*MiniAlign.align_strings()*
`MiniAlign.align_strings`({strings}, {opts}, {steps})
Align strings
For details about alignment process see |MiniAlign-algorithm|.
Parameters ~
{strings} `(table)` Array of strings.
{opts} `(table|nil)` Options. Its copy will be passed to steps as second
argument. Extended with `MiniAlign.config.options`.
This is a place to control default main steps:
- `opts.split_pattern` - Lua pattern(s) used to make split parts.
- `opts.split_exclude_patterns` - which split matches should be ignored.
- `opts.justify_side` - which direction(s) alignment should be done.
- `opts.justify_offsets` - offsets tweaking width of first column
- `opts.merge_delimiter` - which delimiter(s) to use when merging.
For more information see |MiniAlign.gen_step| entry for corresponding
default step.
{steps} `(table|nil)` Steps. Extended with `MiniAlign.config.steps`.
Possible `nil` values are replaced with corresponding default steps:
- `split` - |MiniAlign.gen_step.default_split()|.
- `justify` - |MiniAlign.gen_step.default_justify()|.
- `merge` - |MiniAlign.gen_step.default_merge()|.
------------------------------------------------------------------------------
*MiniAlign.align_user()*
`MiniAlign.align_user`({mode})
Align current region with user-supplied steps
Mostly designed to be used inside mappings.
Will use |MiniAlign.align_strings()| and set the following options in `opts`:
- `justify_offsets` - array of offsets used to achieve actual alignment of
a region. It is non-trivial (not array of zeros) only for charwise
selection: offset of first string is computed as width of prefix to the
left of region start.
- `region` - current affected region (see |MiniAlign-glossary|). Can be
used to create more advanced steps.
- `mode` - mode of selection (see |MiniAlign-glossary|).
Parameters ~
{mode} `(string)` Selection mode. One of "char", "line", "block".
------------------------------------------------------------------------------
*MiniAlign.as_parts()*
`MiniAlign.as_parts`({arr2d})
Convert 2d array of strings to parts
This function verifies if input is a proper 2d array of strings and adds
methods to its copy.
Class ~
{parts}
Fields ~
{apply} `(function)` Takes callable `f` and applies it to every part.
Callable should have signature `(s, data)`: `s` is a string part,
`data` - table with its data ( has row number, has column number).
Returns new 2d array.
{apply_inplace} `(function)` Takes callable `f` and applies it to every part.
Should have same signature as in `apply` method. Outputs (should all be
strings) are assigned in place to a corresponding parts element. Returns
parts itself to enable method chaining.
{get_dims} `(function)` Return dimensions of parts array: a table with
and keys having number of rows and number of columns (maximum
number of elements across all rows).
{group} `(function)` Concatenate neighboring strings based on supplied
boolean mask and direction (one of "left", default, or "right"). Has
signature `(mask, direction)` and modifies parts in place. Returns parts
itself to enable method chaining.
Example:
- Parts: `{ { "a", "b", "c" }, { "d", "e" }, { "f" } }`
- Mask: `{ { false, false, true }, { true, false }, { false } }`
- Result for direction "left": `{ { "abc" }, { "d", "e" }, { "f" } }`
- Result for direction "right": `{ { "ab","c" }, { "de" }, { "f" } }`
{pair} `(function)` Concatenate neighboring element pairs. Takes
`direction` as input (one of "left", default, or "right") and applies
`group()` for an alternating mask.
Example:
- Parts: `{ { "a", "b", "c" }, { "d", "e" }, { "f" } }`
- Result for direction "left": `{ { "ab", "c" }, { "de" }, { "f" } }`
- Result for direction "right": `{ { "a", "bc" }, { "de" }, { "f" } }`
{slice_col} `(function)` Return column with input index `j`. Note: it might
not be an array if rows have unequal number of columns.
{slice_row} `(function)` Return row with input index `i`.
{trim} `(function)` Trim elements whitespace. Has signature `(direction, indent)`
and modifies parts in place. Returns parts itself to enable method chaining.
- Possible values of `direction`: "both" (default), "left", "right",
"none". Defines from which side whitespaces should be removed.
- Possible values of `indent`: "keep" (default), "low", "high", "remove".
Defines what to do with possible indent (left whitespace of first string
in a row). Value "keep" keeps it; "low" makes all indent equal to the
lowest across rows; "high" - highest across rows; "remove" - removes indent.
Usage ~
>lua
parts = MiniAlign.as_parts({ { 'a', 'b' }, { 'c' } })
print(vim.inspect(parts.get_dims())) -- Should be { row = 2, col = 2 }
parts.apply_inplace(function(s, data)
return ' ' .. data.row .. s .. data.col .. ' '
end)
print(vim.inspect(parts)) -- Should be { { ' 1a1 ', ' 1b2 ' }, { ' 2c1 ' } }
parts.trim('both', 'remove').pair()
print(vim.inspect(parts)) -- Should be { { '1a11b2' }, { '2c1' } }
<
------------------------------------------------------------------------------
*MiniAlign.new_step()*
`MiniAlign.new_step`({name}, {action})
Create step
A step is basically a named callable object. Having a name bundled with
some action powers helper status message during interactive alignment process.
Parameters ~
{name} `(string)` Step name.
{action} `(function|table)` Step action. Should be a callable object
(see |vim.is_callable()|).
Return ~
`(table)` A table with keys: with `name` argument, with `action`.
------------------------------------------------------------------------------
*MiniAlign.gen_step*
`MiniAlign.gen_step`
Generate common action steps
This is a table with function elements. Call to actually get step.
Each step action is a function that has signature `(object, opts)`, where
`object` is either parts or array of strings (depends on which stage of
alignment process it is assumed to be applied) and `opts` is table of options.
Outputs of elements named `default_*` are used as default corresponding main
step (split, justify, merge). Behavior of all of them depend on values from
supplied options (second argument).
Outputs of other elements depend on both step generator input values and
options supplied at execution. This design is mostly because their output
can be used several times in pre-steps.
Usage ~
>lua
local align = require('mini.align')
align.setup({
modifiers = {
-- Use 'T' modifier to remove both whitespace and indent
T = function(steps, _)
table.insert(steps.pre_justify, align.gen_step.trim('both', 'remove'))
end,
},
options = {
-- By default align "right", "left", "right", "left", ...
justify_side = { 'right', 'left' },
},
steps = {
-- Align by default only first pair of columns
pre_justify = { align.gen_step.filter('n == 1') },
},
})
<
------------------------------------------------------------------------------
*MiniAlign.gen_step.default_split()*
`MiniAlign.gen_step.default_split`()
Generate default split step
Output splits strings using matches of Lua pattern(s) from `split_pattern`
option which are not dismissed by `split_exclude_patterns` option.
Outline of how single string is split:
- Convert `split_pattern` option to array of strings (string is converted
as one-element array). This array will be recycled in case there are more
split matches than in converted `split_pattern` array (which almost always).
- Find all forbidden spans (intervals inside string) - all matches of all
patterns in `split_exclude_patterns`.
- Find match for the next pattern. If it is not inside any forbidden span,
add preceding unmatched substring and matched split as two parts. Repeat
with the next pattern.
- If no pattern match is found, add the rest of string as final part.
Output uses following options (as part second argument, `opts` table):
- - string or array of strings used to detect split matches
and create parts. Default: `''` meaning no matches (whole string is used
as part). Examples: `'%s+'`, `{ '<', '>' }`.
- - array of strings defining which regions to
exclude from being matched. Default: `{}`. Examples: `{ '".-"', '^%s*#.*' }`.
Return ~
`(table)` A step named "split" and with appropriate callable action.
See also ~
|MiniAlign.gen_step.ignore_split()| heavily uses `split_exclude_patterns`.
------------------------------------------------------------------------------
*MiniAlign.gen_step.default_justify()*
`MiniAlign.gen_step.default_justify`()
Generate default justify step
Output makes column elements of string parts have equal width by adding
left and/or right whitespace padding. Which side(s) to pad is defined by
`justify_side` option. Width of first column can be tweaked with `justify_offsets`
option.
Outline of how parts are justified:
- Convert `justify_side` option to array of strings (single string is
converted as one-element array). Recycle this array to have length equal
to number of columns in parts.
- For all columns compute maximum width of strings from it (add offsets from
`justify_offsets` to first column widths). Note: for left alignment, width
of last row element does not affect column width. This is mainly because
it won't be padded and helps dealing with "no single match" lines.
- Make all elements have same width inside column by adding appropriate
amount of whitespace. Which side(s) to add is controlled by the corresponding
`justify_side` array element. Note: padding is done with spaces which
might conflict with tab indentation.
Output uses following options (as part second argument, `opts` table):
- - string or array of strings. Each element can be one of
"left" (pad right side), "center" (pad both sides equally), "right" (pad
left side), "none" (no padding). Default: "left".
- - array of numeric left offsets of rows. Used to adjust
for possible not equal indents, like in case of charwise selection when
left edge is not on the first column. Default: array of zeros. Set
automatically during interactive alignment in charwise mode.
Return ~
`(table)` A step named "justify" and with appropriate callable action.
------------------------------------------------------------------------------
*MiniAlign.gen_step.default_merge()*
`MiniAlign.gen_step.default_merge`()
Generate default merge step
Output merges rows of parts into strings by placing merge delimiter(s)
between them.
Outline of how parts are converted to array of strings:
- Convert `merge_delimiter` option to array of strings (single string is
converted as one-element array). Recycle this array to have length equal
to number of columns in parts minus 1. Also possibly trim leading whitespace
in first merge character to not affect indentation.
- Exclude empty strings from parts. They add nothing to output except extra
usage of merge delimiter.
- Concatenate each row interleaving with array of merge delimiters.
Output uses following options (as part second argument, `opts` table):
- - string or array of strings. Default: `''`.
Examples: `' '`, `{ '', ' ' }`.
Return ~
`(table)` A step named "merge" and with appropriate callable action.
------------------------------------------------------------------------------
*MiniAlign.gen_step.filter()*
`MiniAlign.gen_step.filter`({expr})
Generate filter step
Construct function predicate from supplied Lua string expression and make
step evaluating it on every part element.
Outline of how filtering is done:
- Convert Lua filtering expression into function predicate which can be
evaluated in manually created context (some specific variables being set).
- Compute boolean mask for parts by applying predicate to each element of
2d array with special variables set to specific values (see next section).
- Group parts with computed mask. See `group()` method of parts in
|MiniAlign.as_parts()|.
Special variables which can be used in expression:
- - row number of current element.
- - total number of rows in parts.
- - column number of current element.
- - total number of columns in current row.
- - string value of current element.
- - column pair number of current element. Useful when filtering by
result of pattern splitting.
- - total number of column pairs in current row.
- All variables from global table `_G`.
Tips:
- This general filtering approach can be used to both include and exclude
certain parts from alignment. Examples:
- Use `row ~= 2` to align all parts except from second row.
- Use `n == 1` to align only by first pair of columns.
- Filtering by last equal sign usually can be done with `n >= (N - 1)`
(because there is usually something to the right of it).
Parameters ~
{expr} `(string)` Lua expression as a string which will be used as predicate.
Return ~
`(table|nil)` A step named "filter" and with appropriate callable action.
------------------------------------------------------------------------------
*MiniAlign.gen_step.ignore_split()*
`MiniAlign.gen_step.ignore_split`({patterns}, {exclude_comment})
Generate ignore step
Output adds certain values to `split_exclude_patterns` option. Should be
used as pre-split step.
Parameters ~
{patterns} `(table)` Array of patterns to be added to
`split_exclude_patterns` as is. Default: `{ [[".-"]] }` (excludes strings
for most cases).
{exclude_comment} `(boolean|nil)` Whether to add comment pattern to
`split_exclude_patterns`. Comment pattern is derived from 'commentstring'
option. Default: `true`.
Return ~
`(table)` A step named "ignore" and with appropriate callable action.
See also ~
|MiniAlign.gen_step.default_split()| for details about
`split_exclude_patterns` option.
------------------------------------------------------------------------------
*MiniAlign.gen_step.pair()*
`MiniAlign.gen_step.pair`({direction})
Generate pair step
Output calls `pair()` method of parts (see |MiniAlign.as_parts()|) with
supplied `direction` argument.
Parameters ~
{direction} `(string)` Which direction to pair. One of "left" (default) or
Return ~
`(table)` A step named "pair" and with appropriate callable action.
------------------------------------------------------------------------------
*MiniAlign.gen_step.trim()*
`MiniAlign.gen_step.trim`({direction}, {indent})
Generate trim step
Output calls `trim()` method of parts (see |MiniAlign.as_parts()|) with
supplied `direction` and `indent` arguments.
Parameters ~
{direction} `(string|nil)` Which sides to trim whitespace. One of "both"
(default), "left", "right", "none".
{indent} `(string|nil)` What to do with possible indent (left whitespace
of first string in a row). One of "keep" (default), "low", "high", "remove".
Return ~
`(table)` A step named "trim" and with appropriate callable action.
vim:tw=78:ts=8:noet:ft=help:norl:
================================================
FILE: doc/mini-animate.txt
================================================
*mini.animate* Animate common Neovim actions
MIT License Copyright (c) 2022 Evgeni Chasnovski
------------------------------------------------------------------------------
*MiniAnimate*
Features:
- Works out of the box with a single `require('mini.animate').setup()`.
No extra mappings or commands needed.
- Animate cursor movement inside same buffer by showing customizable path.
See |MiniAnimate.config.cursor| for more details.
- Animate scrolling with a series of subscrolls ("smooth scrolling").
See |MiniAnimate.config.scroll| for more details.
- Animate window resize by gradually changing sizes of all windows.
See |MiniAnimate.config.resize| for more details.
- Animate window open/close with visually updating floating window.
See |MiniAnimate.config.open| and |MiniAnimate.config.close| for more details.
- Timings for all actions can be customized independently.
See |MiniAnimate-timing| for more details.
- Action animations can be enabled/disabled independently.
- All animations are asynchronous/non-blocking and trigger a targeted event
which can be used to perform actions after animation is done.
- |MiniAnimate.animate()| function which can be used to perform own animations.
Notes:
- Cursor movement is animated inside same window and buffer, not as cursor
moves across the screen.
- Scroll and resize animations are done with "side effects": they actually
change the state of what is animated (window view and sizes
respectively). This has a downside of possibly needing extra work to
account for asynchronous nature of animation (like adjusting certain
mappings, etc.). See |MiniAnimate.config.scroll| and
|MiniAnimate.config.resize| for more details.
# Setup ~
This module needs a setup with `require('mini.animate').setup({})` (replace
`{}` with your `config` table). It will create global Lua table `MiniAnimate`
which you can use for scripting or manually (with `:lua MiniAnimate.*`).
See |MiniAnimate.config| for available config settings.
You can override runtime config settings (like `config.modifiers`) locally
to buffer inside `vim.b.minianimate_config` which should have same structure
as `MiniAnimate.config`. See |mini.nvim-buffer-local-config| for more details.
# Comparisons ~
- [Neovide](https://neovide.dev/):
- Neovide is a standalone GUI which has more control over its animations.
While 'mini.animate' works inside terminal emulator (with all its
limitations, like lack of pixel-size control over animations).
- Neovide animates cursor movement across screen, while 'mini.animate' -
as it moves across same buffer.
- Neovide has fixed number of animation effects per action, while
'mini.animate' is fully customizable.
- 'mini.animate' implements animations for window open/close, while
Neovide does not.
- [edluffy/specs.nvim](https://github.com/edluffy/specs.nvim):
- 'mini.animate' approaches cursor movement visualization via
customizable path function (uses extmarks), while 'specs.nvim' can
customize within its own visual effects (shading and floating
window resizing).
- [karb94/neoscroll.nvim](https://github.com/karb94/neoscroll.nvim):
- Scroll animation is triggered only inside dedicated mappings.
'mini.animate' animates scroll resulting from any window view change.
- [anuvyklack/windows.nvim](https://github.com/anuvyklack/windows.nvim):
- Resize animation is done only within custom commands and mappings,
while 'mini.animate' animates any resize with appropriate values of
'winheight' / 'winwidth' and 'winminheight' / 'winminwidth').
# Highlight groups ~
- `MiniAnimateCursor` - highlight of cursor during its animated movement.
- `MiniAnimateNormalFloat` - highlight of floating window for `open` and
`close` animations.
To change any highlight group, set it directly with |nvim_set_hl()|.
# Disabling ~
To disable, set `vim.g.minianimate_disable` (globally) or
`vim.b.minianimate_disable` (for a buffer) to `true`. Considering high
number of different scenarios and customization intentions, writing exact
rules for disabling module's functionality is left to user. See
|mini.nvim-disabling-recipes| for common recipes.
------------------------------------------------------------------------------
*MiniAnimate.setup()*
`MiniAnimate.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniAnimate.config|.
Usage ~
>lua
require('mini.animate').setup() -- use default config
-- OR
require('mini.animate').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniAnimate.config*
`MiniAnimate.config`
Defaults ~
>lua
MiniAnimate.config = {
-- Cursor path
cursor = {
-- Whether to enable this animation
enable = true,
-- Timing of animation (how steps will progress in time)
timing = --,
-- Path generator for visualized cursor movement
path = --,
},
-- Vertical scroll
scroll = {
-- Whether to enable this animation
enable = true,
-- Timing of animation (how steps will progress in time)
timing = --,
-- Subscroll generator based on total scroll
subscroll = --,
},
-- Window resize
resize = {
-- Whether to enable this animation
enable = true,
-- Timing of animation (how steps will progress in time)
timing = --,
-- Subresize generator for all steps of resize animations
subresize = --,
},
-- Window open
open = {
-- Whether to enable this animation
enable = true,
-- Timing of animation (how steps will progress in time)
timing = --,
-- Floating window config generator visualizing specific window
winconfig = --,
-- 'winblend' (window transparency) generator for floating window
winblend = --,
},
-- Window close
close = {
-- Whether to enable this animation
enable = true,
-- Timing of animation (how steps will progress in time)
timing = --,
-- Floating window config generator visualizing specific window
winconfig = --,
-- 'winblend' (window transparency) generator for floating window
winblend = --,
},
}
<
# General ~
- *MiniAnimate-timing* Every animation is a non-blockingly scheduled series of
specific actions. They are executed in a sequence of timed steps controlled
by `timing` option. It is a callable which, given next and total step numbers,
returns wait time (in ms).
See |MiniAnimate.gen_timing| for builtin timing functions.
See |MiniAnimate.animate()| for more details about animation process.
- Every animation can be enabled/disabled independently by setting `enable`
option to `true`/`false`.
- *MiniAnimate-done-event* Every animation triggers custom |User| event when it
is finished. It is named `MiniAnimateDoneXxx` with `Xxx` replaced by capitalized
supported animation action name (like `MiniAnimateDoneCursor`). Use it to
schedule some action after certain animation is completed. Alternatively,
you can use |MiniAnimate.execute_after()| (usually preferred in mappings).
- Each animation has its main step generator which defines how particular
animation is done. They all are callables which take some input data and
return an array of step data. Length of that array determines number of
animation steps. Outputs `nil` and empty table result in no animation.
# Cursor ~
*MiniAnimate.config.cursor*
This animation is triggered for each movement of cursor inside same window
and buffer. Its visualization step consists from placing single extmark (see
|extmarks|) at certain position. This extmark contains single space and is
highlighted with `MiniAnimateCursor` highlight group.
Exact places of extmark and their number is controlled by `path` option. It
is a callable which takes `destination` argument (2d integer point in
`(line, col)` coordinates) and returns array of relative to `(0, 0)` places
for extmark to be placed. Example:
- Input `(2, -3)` means cursor jumped 2 lines forward and 3 columns backward.
- Output `{ {0, 0 }, { 0, -1 }, { 0, -2 }, { 0, -3 }, { 1, -3 } }` means
that path is first visualized along the initial line and then along final
column.
See |MiniAnimate.gen_path| for builtin path generators.
Notes:
- Input `destination` value is computed ignoring folds. This is by design
as it helps better visualize distance between two cursor positions.
- Outputs of path generator resulting in a place where extmark can't be
placed are silently omitted during animation: this step won't show any
visualization.
Configuration example: >lua
local animate = require('mini.animate')
animate.setup({
cursor = {
-- Animate for 200 milliseconds with linear easing
timing = animate.gen_timing.linear({ duration = 200, unit = 'total' }),
-- Animate with shortest line for any cursor move
path = animate.gen_path.line({
predicate = function() return true end,
}),
}
})
<
After animation is done, `MiniAnimateDoneCursor` event is triggered.
# Scroll ~
*MiniAnimate.config.scroll*
This animation is triggered for each vertical scroll of current window.
Its visualization step consists from performing a small subscroll which all
in total will result into needed total scroll.
Exact subscroll values and their number is controlled by `subscroll` option.
It is a callable which takes `total_scroll` argument (single non-negative
integer) and returns array of non-negative integers each representing the
amount of lines needed to be scrolled inside corresponding step. All
subscroll values should sum to input `total_scroll`.
Example:
- Input `5` means that total scroll consists from 5 lines (either up or down,
which doesn't matter).
- Output of `{ 1, 1, 1, 1, 1 }` means that there are 5 equal subscrolls.
See |MiniAnimate.gen_subscroll| for builtin subscroll generators.
Notes:
- Input value of `total_scroll` is computed taking folds into account.
- As scroll animation is essentially a precisely scheduled non-blocking
subscrolls, this has two important interconnected consequences:
- If another scroll is attempted during the animation, it is done based
on the **currently visible** window view. Example: if user presses
|CTRL-D| and then |CTRL-U| when animation is half done, window will not
display the previous view half of 'scroll' above it. This especially
affects mouse wheel scrolling, as each its turn results in a new scroll
for number of lines defined by 'mousescroll'. Tweak it to your liking.
- It breaks the use of several relative scrolling commands in the same
command. Use |MiniAnimate.execute_after()| to schedule action after
reaching target window view.
Example: a useful `nnoremap n nzvzz` mapping (consecutive application
of |n|, |zv|, and |zz|) should be expressed in the following way: >lua
'lua vim.cmd("normal! n"); ' ..
'MiniAnimate.execute_after("scroll", "normal! zvzz")'
<
- Default timing might conflict with scrolling via holding a key (like `j` or `k`
with 'wrap' enabled) due to high key repeat rate: next scroll is done before
first step of current one finishes. Resolve this by not scrolling like that
or by ensuring maximum value of step duration to be lower than between
repeated keys: set timing like `function(_, n) return math.min(250/n, 10) end`
or use timing with constant step duration.
Configuration example: >lua
local animate = require('mini.animate')
animate.setup({
scroll = {
-- Animate for 200 milliseconds with linear easing
timing = animate.gen_timing.linear({ duration = 200, unit = 'total' }),
-- Animate equally but with at most 120 steps instead of default 60
subscroll = animate.gen_subscroll.equal({ max_output_steps = 120 }),
}
})
<
After animation is done, `MiniAnimateDoneScroll` event is triggered.
# Resize ~
*MiniAnimate.config.resize*
This animation is triggered for window resize while having same layout of
same windows. For example, it won't trigger when window is opened/closed or
after something like |CTRL-W_K|. Its visualization step consists from setting
certain sizes to all visible windows (last step being for "true" final sizes).
Exact window step sizes and their number is controlled by `subresize` option.
It is a callable which takes `sizes_from` and `sizes_to` arguments (both
tables with window id as keys and dimension table as values) and returns
array of same shaped data.
Example:
- Input: >lua
-- First
{ [1000] = {width = 7, height = 5}, [1001] = {width = 7, height = 10} }
-- Second
{ [1000] = {width = 9, height = 5}, [1001] = {width = 5, height = 10} }
-- Means window 1000 increased its width by 2 in expense of window 1001
<
- The following output demonstrates equal resizing: >lua
{
{ [1000] = {width = 8, height = 5}, [1001] = {width = 6, height = 10} },
{ [1000] = {width = 9, height = 5}, [1001] = {width = 5, height = 10} },
}
<
See |MiniAnimate.gen_subresize| for builtin subresize generators.
Notes:
- As resize animation is essentially a precisely scheduled non-blocking
subresizes, this has two important interconnected consequences:
- If another resize is attempted during the animation, it is done based
on the **currently visible** window sizes. This might affect relative
resizing.
- It breaks the use of several relative resizing commands in the same
command. Use |MiniAnimate.execute_after()| to schedule action after
reaching target window sizes.
Configuration example: >lua
local is_many_wins = function(sizes_from, sizes_to)
return vim.tbl_count(sizes_from) >= 3
end
local animate = require('mini.animate')
animate.setup({
resize = {
-- Animate for 200 milliseconds with linear easing
timing = animate.gen_timing.linear({ duration = 200, unit = 'total' }),
-- Animate only if there are at least 3 windows
subresize = animate.gen_subscroll.equal({ predicate = is_many_wins }),
}
})
<
After animation is done, `MiniAnimateDoneResize` event is triggered.
# Window open/close ~
*MiniAnimate.config.open*
*MiniAnimate.config.close*
These animations are similarly triggered for regular (non-floating) window
open/close. Their visualization step consists from drawing empty floating
window with customizable config and transparency.
Exact window visualization characteristics are controlled by `winconfig`
and `winblend` options.
The `winconfig` option is a callable which takes window id (|window-ID|) as
input and returns an array of floating window configs (as in `config`
argument of |nvim_open_win()|). Its length determines number of animation steps.
Example:
- The following output results into two animation steps with second being
upper left quarter of a first: >lua
{
{
row = 0, col = 0,
width = 10, height = 10,
relative = 'editor', anchor = 'NW', focusable = false,
zindex = 1, border = 'none', style = 'minimal',
},
{
row = 0, col = 0,
width = 5, height = 5,
relative = 'editor', anchor = 'NW', focusable = false,
zindex = 1, border = 'none', style = 'minimal',
},
}
<
The `winblend` option is similar to `timing` option: it is a callable
which, given current and total step numbers, returns value of floating
window's 'winblend' option. Note, that it is called for current step (so
starts from 0), as opposed to `timing` which is called before step.
Example:
- Function `function(s, n) return 80 + 20 * s / n end` results in linear
transition from `winblend` value of 80 to 100.
See |MiniAnimate.gen_winconfig| for builtin window config generators.
See |MiniAnimate.gen_winblend| for builtin window transparency generators.
Configuration example: >lua
local animate = require('mini.animate')
animate.setup({
open = {
-- Animate for 400 milliseconds with linear easing
timing = animate.gen_timing.linear({ duration = 400, unit = 'total' }),
-- Animate with wiping from nearest edge instead of default static one
winconfig = animate.gen_winconfig.wipe({ direction = 'from_edge' }),
-- Make bigger windows more transparent
winblend = animate.gen_winblend.linear({ from = 80, to = 100 }),
},
close = {
-- Animate for 400 milliseconds with linear easing
timing = animate.gen_timing.linear({ duration = 400, unit = 'total' }),
-- Animate with wiping to nearest edge instead of default static one
winconfig = animate.gen_winconfig.wipe({ direction = 'to_edge' }),
-- Make bigger windows more transparent
winblend = animate.gen_winblend.linear({ from = 100, to = 80 }),
},
})
<
After animation is done, `MiniAnimateDoneOpen` or `MiniAnimateDoneClose`
event is triggered for `open` and `close` animation respectively.
------------------------------------------------------------------------------
*MiniAnimate.is_active()*
`MiniAnimate.is_active`({animation_type})
Check animation activity
Parameters ~
{animation_type} `(string)` One of supported animation types
(entries of |MiniAnimate.config|, like `'cursor'`, etc.).
Return ~
`(boolean)` Whether the animation is currently active.
------------------------------------------------------------------------------
*MiniAnimate.execute_after()*
`MiniAnimate.execute_after`({animation_type}, {action})
Execute action after some animation is done
Execute action immediately if animation is not active (checked with
|MiniAnimate.is_active()|). Else, schedule its execution until after
animation is done (on corresponding "done event", see
|MiniAnimate-done-event|).
Mostly meant to be used inside mappings.
Example:
A useful `nnoremap n nzvzz` mapping (consecutive application of |n|, |zv|, and |zz|)
should be expressed in the following way: >lua
'lua vim.cmd("normal! n"); ' ..
'MiniAnimate.execute_after("scroll", "normal! zvzz")'
<
Parameters ~
{animation_type} `(string)` One of supported animation types
(as in |MiniAnimate.is_active()|).
{action} `(string|function)` Action to be executed. If string, executed as
command (via |vim.cmd()|).
------------------------------------------------------------------------------
*MiniAnimate.animate()*
`MiniAnimate.animate`({step_action}, {step_timing}, {opts})
Animate action
This is equivalent to asynchronous execution of the following algorithm:
- Call `step_action(0)` immediately after calling this function. Stop if
action returned `false` or `nil`.
- Wait `step_timing(1)` milliseconds.
- Call `step_action(1)`. Stop if it returned `false` or `nil`.
- Wait `step_timing(2)` milliseconds.
- Call `step_action(2)`. Stop if it returned `false` or `nil`.
- ...
Notes:
- Animation is also stopped on action error or if maximum number of steps
is reached.
- Asynchronous execution is done with |uv.new_timer()|. It only allows
integer parts as repeat value. This has several implications:
- Outputs of `step_timing()` are accumulated in order to preserve total
execution time.
- Any wait time less than 1 ms means that action will be executed
immediately.
Parameters ~
{step_action} `(function|table)` Callable which takes `step` (integer 0, 1, 2,
etc. indicating current step) and executes some action. Its return value
defines when animation should stop: values `false` and `nil` (equivalent
to no explicit return) stop animation timer; any other continues it.
{step_timing} `(function|table)` Callable which takes `step` (integer 1, 2, etc.
indicating next step) and returns how many milliseconds to wait before
executing this step action.
{opts} `(table|nil)` Options. Possible fields:
- - Maximum value of allowed step to execute. Default: 10000000.
------------------------------------------------------------------------------
*MiniAnimate.gen_timing*
`MiniAnimate.gen_timing`
Generate animation timing
Each field corresponds to one family of progression which can be customized
further by supplying appropriate arguments.
This is a table with function elements. Call to actually get timing function.
Example: >lua
local animate = require('mini.animate')
animate.setup({
cursor = {
timing = animate.gen_timing.linear({ duration = 100, unit = 'total' })
},
})
<
See also ~
|MiniIndentscope.gen_animation| for similar concept in 'mini.indentscope'.
------------------------------------------------------------------------------
*MiniAnimate.gen_timing.none()*
`MiniAnimate.gen_timing.none`()
Generate timing with no animation
Show final result immediately. Usually better to use `enable` field in `config`
if you want to disable animation.
------------------------------------------------------------------------------
*MiniAnimate.gen_timing.linear()*
`MiniAnimate.gen_timing.linear`({opts})
Generate timing with linear progression
Parameters ~
{opts} `(table|nil)` Options that control progression. Possible keys:
- `(string)` - a subtype of progression. One of "in"
(accelerating from zero speed), "out" (decelerating to zero speed),
"in-out" (default; accelerating halfway, decelerating after).
- `(number)` - duration (in ms) of a unit. Default: 20.
- `(string)` - which unit's duration `opts.duration` controls. One
of "step" (default; ensures average duration of step to be `opts.duration`)
or "total" (ensures fixed total duration regardless of scope's range).
Return ~
`(function)` Timing function (see |MiniAnimate-timing|).
------------------------------------------------------------------------------
*MiniAnimate.gen_timing.quadratic()*
`MiniAnimate.gen_timing.quadratic`({opts})
Generate timing with quadratic progression
Parameters ~
{opts} `(table|nil)` Options that control progression. Possible keys:
- `(string)` - a subtype of progression. One of "in"
(accelerating from zero speed), "out" (decelerating to zero speed),
"in-out" (default; accelerating halfway, decelerating after).
- `(number)` - duration (in ms) of a unit. Default: 20.
- `(string)` - which unit's duration `opts.duration` controls. One
of "step" (default; ensures average duration of step to be `opts.duration`)
or "total" (ensures fixed total duration regardless of scope's range).
Return ~
`(function)` Timing function (see |MiniAnimate-timing|).
------------------------------------------------------------------------------
*MiniAnimate.gen_timing.cubic()*
`MiniAnimate.gen_timing.cubic`({opts})
Generate timing with cubic progression
Parameters ~
{opts} `(table|nil)` Options that control progression. Possible keys:
- `(string)` - a subtype of progression. One of "in"
(accelerating from zero speed), "out" (decelerating to zero speed),
"in-out" (default; accelerating halfway, decelerating after).
- `(number)` - duration (in ms) of a unit. Default: 20.
- `(string)` - which unit's duration `opts.duration` controls. One
of "step" (default; ensures average duration of step to be `opts.duration`)
or "total" (ensures fixed total duration regardless of scope's range).
Return ~
`(function)` Timing function (see |MiniAnimate-timing|).
------------------------------------------------------------------------------
*MiniAnimate.gen_timing.quartic()*
`MiniAnimate.gen_timing.quartic`({opts})
Generate timing with quartic progression
Parameters ~
{opts} `(table|nil)` Options that control progression. Possible keys:
- `(string)` - a subtype of progression. One of "in"
(accelerating from zero speed), "out" (decelerating to zero speed),
"in-out" (default; accelerating halfway, decelerating after).
- `(number)` - duration (in ms) of a unit. Default: 20.
- `(string)` - which unit's duration `opts.duration` controls. One
of "step" (default; ensures average duration of step to be `opts.duration`)
or "total" (ensures fixed total duration regardless of scope's range).
Return ~
`(function)` Timing function (see |MiniAnimate-timing|).
------------------------------------------------------------------------------
*MiniAnimate.gen_timing.exponential()*
`MiniAnimate.gen_timing.exponential`({opts})
Generate timing with exponential progression
Parameters ~
{opts} `(table|nil)` Options that control progression. Possible keys:
- `(string)` - a subtype of progression. One of "in"
(accelerating from zero speed), "out" (decelerating to zero speed),
"in-out" (default; accelerating halfway, decelerating after).
- `(number)` - duration (in ms) of a unit. Default: 20.
- `(string)` - which unit's duration `opts.duration` controls. One
of "step" (default; ensures average duration of step to be `opts.duration`)
or "total" (ensures fixed total duration regardless of scope's range).
Return ~
`(function)` Timing function (see |MiniAnimate-timing|).
------------------------------------------------------------------------------
*MiniAnimate.gen_path*
`MiniAnimate.gen_path`
Generate cursor animation path
For more information see |MiniAnimate.config.cursor|.
This is a table with function elements. Call to actually get generator.
Example: >lua
local animate = require('mini.animate')
animate.setup({
cursor = {
-- Animate with line-column angle instead of shortest line
path = animate.gen_path.angle(),
}
})
<
------------------------------------------------------------------------------
*MiniAnimate.gen_path.line()*
`MiniAnimate.gen_path.line`({opts})
Generate path as shortest line
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(function)` - a callable which takes `destination` as input and
returns boolean value indicating whether animation should be done.
Default: `false` if `destination` is within one line of origin (reduces
flickering), `true` otherwise.
- `(number)` - maximum number of steps in output.
Default: 1000.
Return ~
`(function)` Path function (see |MiniAnimate.config.cursor|).
------------------------------------------------------------------------------
*MiniAnimate.gen_path.angle()*
`MiniAnimate.gen_path.angle`({opts})
Generate path as line/column angle
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(function)` - a callable which takes `destination` as input and
returns boolean value indicating whether animation should be done.
Default: `false` if `destination` is within one line of origin (reduces
flickering), `true` otherwise.
- `(number)` - maximum number of steps per side in output.
Default: 1000.
- `(string)` - one of `"horizontal"` (default; animates
across initial line first) or `"vertical"` (animates across initial
column first).
Return ~
`(function)` Path function (see |MiniAnimate.config.cursor|).
------------------------------------------------------------------------------
*MiniAnimate.gen_path.walls()*
`MiniAnimate.gen_path.walls`({opts})
Generate path as closing walls at final position
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(function)` - a callable which takes `destination` as input and
returns boolean value indicating whether animation should be done.
Default: `false` if `destination` is within one line of origin (reduces
flickering), `true` otherwise.
- `(number)` - initial width of left and right walls. Default: 10.
Return ~
`(function)` Path function (see |MiniAnimate.config.cursor|).
------------------------------------------------------------------------------
*MiniAnimate.gen_path.spiral()*
`MiniAnimate.gen_path.spiral`({opts})
Generate path as diminishing spiral at final position
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(function)` - a callable which takes `destination` as input and
returns boolean value indicating whether animation should be done.
Default: `false` if `destination` is within one line of origin (reduces
flickering), `true` otherwise.
- `(number)` - initial width of spiral. Default: 2.
Return ~
`(function)` Path function (see |MiniAnimate.config.cursor|).
------------------------------------------------------------------------------
*MiniAnimate.gen_subscroll*
`MiniAnimate.gen_subscroll`
Generate scroll animation subscroll
For more information see |MiniAnimate.config.scroll|.
This is a table with function elements. Call to actually get generator.
Example: >lua
local animate = require('mini.animate')
animate.setup({
scroll = {
-- Animate equally but with 120 maximum steps instead of default 60
subscroll = animate.gen_subscroll.equal({ max_output_steps = 120 }),
}
})
<
------------------------------------------------------------------------------
*MiniAnimate.gen_subscroll.equal()*
`MiniAnimate.gen_subscroll.equal`({opts})
Generate subscroll with equal steps
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(function)` - a callable which takes `total_scroll` as
input and returns boolean value indicating whether animation should be
done. Default: `false` if `total_scroll` is 1 or less (reduces
unnecessary waiting), `true` otherwise.
- `(number)` - maximum number of subscroll steps in output.
Adjust this to reduce computations in expense of reduced smoothness.
Default: 60.
Return ~
`(function)` Subscroll function (see |MiniAnimate.config.scroll|).
------------------------------------------------------------------------------
*MiniAnimate.gen_subresize*
`MiniAnimate.gen_subresize`
Generate resize animation subresize
For more information see |MiniAnimate.config.resize|.
This is a table with function elements. Call to actually get generator.
Example: >lua
local is_many_wins = function(sizes_from, sizes_to)
return vim.tbl_count(sizes_from) >= 3
end
local animate = require('mini.animate')
animate.setup({
resize = {
-- Animate only if there are at least 3 windows
subresize = animate.gen_subresize.equal({ predicate = is_many_wins }),
}
})
<
------------------------------------------------------------------------------
*MiniAnimate.gen_subresize.equal()*
`MiniAnimate.gen_subresize.equal`({opts})
Generate subresize with equal steps
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(function)` - a callable which takes `sizes_from` and
`sizes_to` as input and returns boolean value indicating whether
animation should be done. Default: always `true`.
Return ~
`(function)` Subresize function (see |MiniAnimate.config.resize|).
------------------------------------------------------------------------------
*MiniAnimate.gen_winconfig*
`MiniAnimate.gen_winconfig`
Generate open/close animation winconfig
For more information see |MiniAnimate.config.open| or |MiniAnimate.config.close|.
This is a table with function elements. Call to actually get generator.
Example: >lua
local is_not_single_window = function(win_id)
local tabpage_id = vim.api.nvim_win_get_tabpage(win_id)
return #vim.api.nvim_tabpage_list_wins(tabpage_id) > 1
end
local animate = require('mini.animate')
animate.setup({
open = {
-- Animate with wiping from nearest edge instead of default static one
-- and only if it is not a single window in tabpage
winconfig = animate.gen_winconfig.wipe({
predicate = is_not_single_window,
direction = 'from_edge',
}),
},
close = {
-- Animate with wiping to nearest edge instead of default static one
-- and only if it is not a single window in tabpage
winconfig = animate.gen_winconfig.wipe({
predicate = is_not_single_window,
direction = 'to_edge',
}),
},
})
<
------------------------------------------------------------------------------
*MiniAnimate.gen_winconfig.static()*
`MiniAnimate.gen_winconfig.static`({opts})
Generate winconfig for static floating window
This will result into floating window statically covering whole target
window.
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(function)` - a callable which takes `win_id` as input and
returns boolean value indicating whether animation should be done.
Default: always `true`.
- `(number)` - number of output steps, all with same config.
Useful to tweak smoothness of transparency animation (done inside
`winblend` config option). Default: 25.
Return ~
`(function)` Winconfig function (see |MiniAnimate.config.open|
or |MiniAnimate.config.close|).
------------------------------------------------------------------------------
*MiniAnimate.gen_winconfig.center()*
`MiniAnimate.gen_winconfig.center`({opts})
Generate winconfig for center-focused animated floating window
This will result into floating window growing from or shrinking to the
target window center.
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(function)` - a callable which takes `win_id` as input and
returns boolean value indicating whether animation should be done.
Default: always `true`.
- `(string)` - one of `"to_center"` (default; window will
shrink from full coverage to center) or `"from_center"` (window will
grow from center to full coverage).
Return ~
`(function)` Winconfig function (see |MiniAnimate.config.open|
or |MiniAnimate.config.close|).
------------------------------------------------------------------------------
*MiniAnimate.gen_winconfig.wipe()*
`MiniAnimate.gen_winconfig.wipe`({opts})
Generate winconfig for wiping animated floating window
This will result into floating window growing from or shrinking to the
nearest edge. This also takes into account the split type of target window:
vertically split window will progress towards vertical edge; horizontally -
towards horizontal.
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(function)` - a callable which takes `win_id` as input and
returns boolean value indicating whether animation should be done.
Default: always `true`.
- `(string)` - one of `"to_edge"` (default; window will
shrink from full coverage to nearest edge) or `"from_edge"` (window
will grow from edge to full coverage).
Return ~
`(function)` Winconfig function (see |MiniAnimate.config.open|
or |MiniAnimate.config.close|).
------------------------------------------------------------------------------
*MiniAnimate.gen_winblend*
`MiniAnimate.gen_winblend`
Generate open/close animation `winblend` progression
For more information see |MiniAnimate.config.open| or |MiniAnimate.config.close|.
This is a table with function elements. Call to actually get transparency
function.
Example: >lua
local animate = require('mini.animate')
animate.setup({
open = {
-- Change transparency from 60 to 80 instead of default 80 to 100
winblend = animate.gen_winblend.linear({ from = 60, to = 80 }),
},
close = {
-- Change transparency from 60 to 80 instead of default 80 to 100
winblend = animate.gen_winblend.linear({ from = 60, to = 80 }),
},
})
<
------------------------------------------------------------------------------
*MiniAnimate.gen_winblend.linear()*
`MiniAnimate.gen_winblend.linear`({opts})
Generate linear `winblend` progression
Parameters ~
{opts} `(table|nil)` Options that control generator. Possible keys:
- `(number)` - initial value of 'winblend'.
- `(number)` - final value of 'winblend'.
Return ~
`(function)` Winblend function (see |MiniAnimate.config.open|
or |MiniAnimate.config.close|).
vim:tw=78:ts=8:noet:ft=help:norl:
================================================
FILE: doc/mini-base16.txt
================================================
*mini.base16* Base16 colorscheme creation
MIT License Copyright (c) 2021 Evgeni Chasnovski
------------------------------------------------------------------------------
*MiniBase16*
Fast implementation of [chriskempson/base16](https://github.com/chriskempson/base16)
color scheme (with Copyright (C) 2012 Chris Kempson) adapted for modern Neovim
Lua plugins. Extra features:
- Configurable automatic support of cterm colors (see |highlight-cterm|).
- Opinionated palette generator based only on background and foreground
colors.
Supported highlight groups:
- Built-in Neovim LSP and diagnostic.
- Plugins (either with explicit definition or by verification that default
highlighting works appropriately):
- [nvim-mini/mini.nvim](https://nvim-mini.org/mini.nvim)
- [akinsho/bufferline.nvim](https://github.com/akinsho/bufferline.nvim)
- [anuvyklack/hydra.nvim](https://github.com/anuvyklack/hydra.nvim)
- [DanilaMihailov/beacon.nvim](https://github.com/DanilaMihailov/beacon.nvim)
- [folke/lazy.nvim](https://github.com/folke/lazy.nvim)
- [folke/noice.nvim](https://github.com/folke/noice.nvim)
- [folke/snacks.nvim](https://github.com/folke/snacks.nvim)
- [folke/todo-comments.nvim](https://github.com/folke/todo-comments.nvim)
- [folke/trouble.nvim](https://github.com/folke/trouble.nvim)
- [folke/which-key.nvim](https://github.com/folke/which-key.nvim)
- [ggandor/leap.nvim](https://github.com/ggandor/leap.nvim)
- [ggandor/lightspeed.nvim](https://github.com/ggandor/lightspeed.nvim)
- [glepnir/dashboard-nvim](https://github.com/glepnir/dashboard-nvim)
- [glepnir/lspsaga.nvim](https://github.com/glepnir/lspsaga.nvim)
- [HiPhish/rainbow-delimiters.nvim](https://github.com/HiPhish/rainbow-delimiters.nvim)
- [hrsh7th/nvim-cmp](https://github.com/hrsh7th/nvim-cmp)
- [justinmk/vim-sneak](https://github.com/justinmk/vim-sneak)
- [ibhagwan/fzf-lua](https://github.com/ibhagwan/fzf-lua)
- [kevinhwang91/nvim-bqf](https://github.com/kevinhwang91/nvim-bqf)
- [kevinhwang91/nvim-ufo](https://github.com/kevinhwang91/nvim-ufo)
- [lewis6991/gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim)
- [lukas-reineke/indent-blankline.nvim](https://github.com/lukas-reineke/indent-blankline.nvim)
- [MeanderingProgrammer/render-markdown.nvim](https://github.com/MeanderingProgrammer/render-markdown.nvim)
- [neoclide/coc.nvim](https://github.com/neoclide/coc.nvim)
- [NeogitOrg/neogit](https://github.com/NeogitOrg/neogit)
- [nvim-lualine/lualine.nvim](https://github.com/nvim-lualine/lualine.nvim)
- [nvim-neo-tree/neo-tree.nvim](https://github.com/nvim-neo-tree/neo-tree.nvim)
- [nvim-telescope/telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
- [nvim-tree/nvim-tree.lua](https://github.com/nvim-tree/nvim-tree.lua)
- [OXY2DEV/helpview.nvim](https://github.com/OXY2DEV/helpview.nvim)
- [OXY2DEV/markview.nvim](https://github.com/OXY2DEV/markview.nvim)
- [phaazon/hop.nvim](https://github.com/phaazon/hop.nvim)
- [rcarriga/nvim-dap-ui](https://github.com/rcarriga/nvim-dap-ui)
- [rcarriga/nvim-notify](https://github.com/rcarriga/nvim-notify)
- [rlane/pounce.nvim](https://github.com/rlane/pounce.nvim)
- [romgrk/barbar.nvim](https://github.com/romgrk/barbar.nvim)
- [stevearc/aerial.nvim](https://github.com/stevearc/aerial.nvim)
- [williamboman/mason.nvim](https://github.com/williamboman/mason.nvim)
# 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.*`).
See |MiniBase16.config| for `config` structure and default values.
This module doesn't have runtime options, so using `vim.b.minibase16_config`
will have no effect here.
Example: >lua
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,
plugins = {
default = false,
['nvim-mini/mini.nvim'] = true,
},
})
<
# Notes ~
1. This is used to create some of plugin's color schemes
(see |MiniBase16-color-schemes|).
2. Using `setup()` doesn't actually create a |:colorscheme|. It basically
creates a coordinated set of |highlight-groups|. 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-color-schemes*
# Base16 colorschemes ~
This module comes with several pre-built color schemes. Each of them is
a |mini.base16| theme created with faster version of the following Lua code: >lua
require('mini.base16').setup({ palette = palette, use_cterm = true })
<
Activate them as regular |:colorscheme| (for example, `:colorscheme minischeme`).
## minischeme ~
*minischeme*
Blue and yellow main colors with high contrast and saturation palette.
Palettes are: >lua
-- For dark 'background':
MiniBase16.mini_palette('#112641', '#e2e98f', 75)
-- For light 'background':
MiniBase16.mini_palette('#e2e5ca', '#002a83', 75)
<
## minicyan ~
*minicyan*
Cyan and grey main colors with moderate contrast and saturation palette.
Palettes are: >lua
-- For dark 'background':
MiniBase16.mini_palette('#0A2A2A', '#D0D0D0', 50)
-- For light 'background':
MiniBase16.mini_palette('#C0D2D2', '#262626', 80)
<
------------------------------------------------------------------------------
*MiniBase16.setup()*
`MiniBase16.setup`({config})
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. See |MiniBase16.config|.
Usage ~
>lua
require('mini.base16').setup({}) -- replace {} with your config table
-- needs `palette` field present
<
------------------------------------------------------------------------------
*MiniBase16.config*
`MiniBase16.config`
Defaults ~
>lua
MiniBase16.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,
-- Plugin integrations. Use `default = false` to disable all integrations.
-- Also can be set per plugin (see |MiniBase16.config|).
plugins = { default = true },
}
<
# Plugin integrations ~
`config.plugins` defines for which supported plugins highlight groups will
be created. Limiting number of integrations slightly decreases startup time.
It is a table with boolean (`true`/`false`) values which are applied as follows:
- If plugin name (as listed in |mini.base16|) has entry, it is used.
- Otherwise `config.plugins.default` is used.
Example which will load only "mini.nvim" integration: >lua
require('mini.base16').setup({
palette = require('mini.base16').mini_palette('#112641', '#e2e98f', 75),
plugins = {
default = false,
['nvim-mini/mini.nvim'] = true,
}
})
<
------------------------------------------------------------------------------
*MiniBase16.mini_palette()*
`MiniBase16.mini_palette`({background}, {foreground}, {accent_chroma})
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
degrees). 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 ~
>lua
local p = require('mini.base16').mini_palette('#112641', '#e2e98f', 75)
require('mini.base16').setup({ palette = p })
<
------------------------------------------------------------------------------
*MiniBase16.rgb_palette_to_cterm_palette()*
`MiniBase16.rgb_palette_to_cterm_palette`({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|.
vim:tw=78:ts=8:noet:ft=help:norl:
================================================
FILE: doc/mini-basics.txt
================================================
*mini.basics* Common configuration presets
MIT License Copyright (c) 2023 Evgeni Chasnovski
------------------------------------------------------------------------------
*MiniBasics*
Install, create 'init.lua', add `require('mini.basics').setup()`, and you
are good to go.
Features:
- Presets for common options. It will only change option if it wasn't
manually set before. See more in |MiniBasics.config.options|.
- Presets for common mappings. It will only add a mapping if it wasn't
manually created before. See more in |MiniBasics.config.mappings|.
- Presets for common autocommands. See more in |MiniBasics.config.autocommands|.
- Reverse compatibility is a high priority. Any decision to change already
present behavior will be made with great care.
Notes:
- Main goal of this module is to provide a relatively easier way for
new-ish Neovim users to have better "works out of the box" experience
while having documented relevant options/mappings/autocommands to study.
It is based partially on survey among Neovim users and partially is
coming from personal preferences.
However, more seasoned users almost surely will find something useful.
Still, it is recommended to read about used options/mappings/autocommands
and decide if they are needed. The main way to do that is by reading
Neovim's help pages (linked in help file) and this module's source code
(thoroughly documented for easier comprehension).
# Setup ~
This module needs a setup with `require('mini.basics').setup({})` (replace
`{}` with your `config` table). It will create global Lua table `MiniBasics`
which you can use for scripting or manually (with `:lua MiniBasics.*`).
See |MiniBasics.config| for available config settings.
To stop module from showing non-error feedback, set `config.silent = true`.
# Comparisons ~
- [tpope/vim-sensible](https://github.com/tpope/vim-sensible):
- Most of 'tpope/vim-sensible' is already incorporated as default
options in Neovim (see |nvim-defaults|). This module has a much
broader effect.
- [tpope/vim-unimpaired](https://github.com/tpope/vim-unimpaired):
- The 'tpope/vim-unimpaired' has mapping for toggling options with `yo`
prefix. This module implements similar functionality with `\` prefix
(see |MiniBasics.config.mappings|).
------------------------------------------------------------------------------
*MiniBasics.setup()*
`MiniBasics.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniBasics.config|.
Usage ~
>lua
require('mini.basics').setup() -- use default config
-- OR
require('mini.basics').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniBasics.config*
`MiniBasics.config`
Defaults ~
>lua
MiniBasics.config = {
-- Options. Set field to `false` to disable.
options = {
-- Basic options ('number', 'ignorecase', and many more)
basic = true,
-- Extra UI features ('winblend', 'listchars', 'pumheight', ...)
extra_ui = false,
-- Presets for window borders ('single', 'double', ...)
-- Default 'auto' infers from 'winborder' option
win_borders = 'auto',
},
-- Mappings. Set field to `false` to disable.
mappings = {
-- Basic mappings (better 'jk', save with Ctrl+S, ...)
basic = true,
-- Prefix for mappings that toggle common options ('wrap', 'spell', ...).
-- Supply empty string to not create these mappings.
option_toggle_prefix = [[\]],
-- Window navigation with , resize with
windows = false,
-- Move cursor in Insert, Command, and Terminal mode with
move_with_alt = false,
},
-- Autocommands. Set field to `false` to disable
autocommands = {
-- Basic autocommands (highlight on yank, start Insert in terminal, ...)
basic = true,
-- Set 'relativenumber' only in linewise and blockwise Visual mode
relnum_in_visual_mode = false,
},
-- Whether to disable showing non-error feedback
silent = false,
}
<
# Options ~
*MiniBasics.config.options*
Usage example: >lua
require('mini.basics').setup({
options = {
basic = true,
extra_ui = true,
win_borders = 'double',
}
})
<
## options.basic ~
The `config.options.basic` sets certain options to values which are quite
commonly used (judging by study of available Neovim pre-configurations,
public dotfiles, and surveys).
Any option is changed only if it was not set manually beforehand.
For exact changes, please see source code ('lua/mini/basics.lua').
Here is the list of affected options (put cursor on it and press |CTRL-]|):
- General:
- Sets || key to ||. Be sure to make all Leader mappings
after this (otherwise they are made with default ).
- Runs `:filetype plugin indent on` (see |:filetype-overview|)
- |'backup'|
- |'mouse'|
- |'undofile'|
- |'writebackup'|
- Appearance
- |'breakindent'|
- |'cursorline'|
- |'fillchars'|
- |'linebreak'|
- |'number'|
- |'ruler'|
- |'showmode'|
- |'signcolumn'|
- |'shortmess'|
- |'splitbelow'|
- |'splitkeep'|
- |'splitright'|
- |'termguicolors'| (on Neovim<0.10; later versions have it smartly enabled)
- |'wrap'|
- Editing
- |'completeopt'|
- |'formatoptions'|
- |'ignorecase'|
- |'incsearch'|
- |'infercase'|
- |'smartcase'|
- |'smartindent'|
- |'virtualedit'|
## options.extra_ui ~
The `config.options.extra_ui` sets certain options for visual appearance
which might not be aligned with common preferences, but still worth trying.
Any option is changed only if it was not set manually beforehand.
For exact changes, please see source code ('lua/mini/basics.lua').
List of affected options:
- |'list'|
- |'listchars'|
- |'pumblend'|
- |'pumheight'|
- |'winblend'|
- Runs `:syntax on` (see |:syntax-on|)
## options.win_borders ~
The `config.options.win_borders` updates |'fillchars'| to have a consistent set
of characters for window border (`vert`, `horiz`, `msgsep`, etc.).
Available values:
- `'auto'` - infer from |'winborder'|. On Neovim<0.11 do nothing.
- `'bold'` - bold lines.
- `'dot'` - dot in every cell.
- `'double'` - double line.
- `'single'` - single line.
- `'solid'` - no symbol, only background.
# Mappings ~
*MiniBasics.config.mappings*
Usage example: >lua
require('mini.basics').setup({
mappings = {
basic = true,
option_toggle_prefix = [[\]],
windows = true,
move_with_alt = true,
}
})
<
If you want some mappings to be different or not made at all, set or delete
them after calling |MiniBasics.setup()|.
## mappings.basic ~
The `config.mappings.basic` creates mappings for certain commonly mapped actions
(judging by study of available Neovim pre-configurations and public dotfiles).
Some of the mappings override built-in ones to either improve their
behavior or override its default not very useful action.
It will only add a mapping if it wasn't manually created before.
Here is a table with created mappings : >
|Keys | Modes | Description |
|-------|-----------------|-----------------------------------------------|
| j | Normal, Visual | Move down by visible lines with no [count] |
| k | Normal, Visual | Move up by visible lines with no [count] |
| go | Normal | Add [count] empty lines after cursor |
| gO | Normal | Add [count] empty lines before cursor |
| gy | Normal, Visual | Copy to system clipboard |
| gp | Normal, Visual | Paste from system clipboard |
| gV | Normal | Visually select latest changed or yanked text |
| g/ | Visual | Search inside current visual selection |
| * | Visual | Search forward for current visual selection |
| # | Visual | Search backward for current visual selection |
| | Normal, Visual, | Save and go to Normal mode |
| | Insert | |
<
Notes:
- See |[count]| for its meaning.
- On Neovim>=0.10 mappings for `#` and `*` are not created as their
enhanced variants are made built-in. See |v_star-default| and |v_#-default|.
- On Neovim>=0.11 there are |[| / |]
