8000 mini.nvim/doc/mini-map.txt at main · jrwrigh/mini.nvim · GitHub
[go: up one dir, main page]
Skip to content

mini-map.txt

Latest commit

 

History

History
716 lines (585 loc) · 30.4 KB

mini-map.txt

File metadata and controls

716 lines (585 loc) · 30.4 KB
Raw
width = 10,
-- Value of 'winblend' option
winblend = 25,
-- Z-index
zindex = 10,
},
}
<
# Symbols ~
Options in `config.symbols` define characters used to display various
information in map window.
## Encode symbols ~
The `config.symbols.encode` option defines which characters are used to
encode source buffer lines. For details of encode algorithm, see
|MiniMap.encode_strings()|.
This option should be a table with the following structure:
- <resolution> field - table containing <row> and <col> elements with row
and column resolution of each symbol. This defines encoding structure and
number of needed encode symbols.
- Numerical fields 1, 2, ..., 2^(row_resolution * col_resolution). Each symbol
represents a `(row_resolution, col_resolution)` boolean mask (`true` for
non-whitespace, `false` for whitespace), created as (reversed) binary digit:
`true` as 1; `false` as 0. Traversing left-right, top-bottom (top-left is
lowest bit, bottom-right - highest). So first symbol encodes a complete
whitespace, last - complete non-whitespace.
If `nil` (default), output of |MiniMap.gen_encode_symbols.block()| with `'3x2'`
identifier is used.
Example: { '1', '2', '3', '4', resolution = { row = 1, col = 2 } }. This
will encode two characters in each input row. So a string `' a aaa'` will
be encoded as `'1234'`.
There are pre-built generators of encode symbols:
- |MiniMap.gen_encode_symbols.block()|
- |MiniMap.gen_encode_symbols.dot()|
- |MiniMap.gen_encode_symbols.shade()|
## Scrollbar symbols ~
Options `config.symbols.scroll_line` and `config.symbols.scroll_view` define
strings used to represent current line and current view inside map window.
Can have any length, map window content will adjust.
If supplied window width is small enough so that only (part of) of
scrollbar can be shown, it is called a "pure scrollbar". The behavior differs
slightly from normal map window. See "Pure scrollbar config" later section.
Some suggestions for scrollbar symbols:
- View-line pairs: '▒' and '█'.
- Line - '🮚', '▶'.
- View - '╎', '┋', '┋'.
# Integrations ~
Option `config.integrations` is an array of integrations. Each one is used
to define map line highlights representing some important lines in source
buffer. If `nil` (default), no integrations are used.
Each integration should be a callable returning an array with data about
**source buffer** lines it wants to highlight. Each array element should be
a table with <line> (source buffer line number) and <hl_group> (string with
highlight group name) keys. Note: line number outside of source buffer
count will be converted to a nearest appropriate one.
Example output of single integration: >lua
{
{ line = 1, hl_group = 'Search' },
{ line = 2, hl_group = 'Operator' },
{ line = 9, hl_group = 'Search'}
}
<
Conversion to map highlights is done on a "first seen" basis: actual
highlight group applied to a map line is taken from the first integration
output convertible to that map line. Other outputs with same map line
(after conversion) contribute to integration count shown between scrollbar
and encoded lines (if `config.window.show_integration_count` is `true`).
Previous example output with default `'3x2'` resolution will add |hl-Search|
highlight on map lines 1 and 3, and show integration count 2 on first line.
Every element of integrations array is called one by one from start to end
with their outputs appended to end of single array. This means that more
important integrations should be placed in the beginning of an array, as
this will make them have higher priority in case other integrations will
highlight same map line.
Example of using `config.integrations`: >lua
local map = require('mini.map')
map.setup({
integrations = {
map.gen_integration.builtin_search(),
map.gen_integration.diff(),
map.gen_integration.diagnostic(),
},
})
<
# Window config ~
Option `config.window` defines some properties of map window.
`window.focusable` - whether to allow focusing on map window with other
methods beside |MiniMap.toggle_focus()| (like |:wincmd|, |CTRL-W|, or mouse).
Default: `false`.
`window.side` - which side to stick map window: `'left'` or `'right'` (default).
`window.show_integration_count` - whether to show integration count between
scrollbar and encoded lines. Integration count is a number of integration
outputs which were converted to same map line. When `true`, adds single
cell column with numbers from 2 to 9 and character '+' indicating count
greater than 9. Count 1 is not shown, because it is redundant to highlighted
map line. Default: `true`.
`window.width` - width of floating window, including scrollbar and
integration 8000 count column. Default: 10.
`window.winblend` - value of 'winblend' of floating window. Value 0 makes it
completely non-transparent, 100 - completely transparent (content is still
visible, but with slightly different highlights).
`window.zindex` - z-index of floating window. Default: 10.
# Pure scrollbar config ~
"Pure scrollbar" is a configuration when window width is not enough to show
encoded content. It has following differences from default "map" approach:
- It doesn't perform line encoding with |MiniMap.encode_strings()|
but instead uses encoding with fixed number of lines (equal to window
height).
- Integration highlights are not computed.
Config: >lua
require('mini.map').setup({
-- Customize `symbols` to your liking
window = {
-- Set this to the maximum width of your scroll symbols
width = 1,
-- Set this to your liking. Try values 0, 25, 50, 75, 100
winblend = 100,
-- Don't need extra column
show_integration_count = false,
}
})
<
------------------------------------------------------------------------------
*MiniMap.current*
`MiniMap.current`
Table with information about current state of map
At least these keys are supported:
- <buf_data> - table with buffer identifiers. Field <map> contains
identifier of a buffer used to display map. Field <source> - buffer
identifier which content map is displaying (i.e. source buffer).
- <win_data> - table of window identifiers used to display map in certain
tabpage. Keys: tabpage identifier. Values: window identifier.
- <opts> - current options used to control map display. Same structure
as |MiniMap.config|. Takes precedence over global and buffer-local configs.
Is reset when last map window is closed with |MiniMap.close()|.
------------------------------------------------------------------------------
*MiniMap.encode_strings()*
`MiniMap.encode_strings`({strings}, {opts})
Encode strings
This takes arbitrary array of strings and computes its non-whitespace
outline. Output is an array of strings with configurable array length, string
width, and symbols representing encoding.
Each encode symbol is assumed to have resolution within which it can convey
binary information. For example, resolution `3x2` (row resolution 3,
column - 2) means that each symbol can encode 3 rows and 2 columns of
binary data. Here it is used to encode non-whitespace mask. See more in
"Encode symbols" section of |MiniMap.config|.
Encoding has the following steps:
- Convert strings to boolean mask: 2d boolean array with each row
representing a string. Element in every row subarray is `true` if
respective (possibly multibyte) character in a string is not a whitespace,
`false` otherwise. Note: tabs are expanded into 'tabstop' spaces.
- Rescale to appropriate dimensions:
- Each output dimension is just enough to encode all input strings, but
not more than supplied dimensions (`opts.n_rows * resolution.row` and
`opts.n_cols * resolution.col` respectively).
- If input dimensions are too big to fit inside output, perform grid
downscaling with loss of information. Input boolean mask is divided
into 2d-bins with as equal as possible dimensions. Each bin then
converted into single boolean value: `true` if bin contains at least
one `true` element, `false` otherwise. This leads to a whitespace
output meaning that **all** entries in a bin are whitespace, while
non-whitespace output means that **some** entry is non-whitespace.
- Convert boolean mask to symbol strings:
- Input rescaled boolean mask is divided into bins with dimensions of
symbol resolution (assuming `false` outer padding).
- Each bin with resolution dimensions is transformed into encode symbol.
Single convertible `(resolution.row, resolution.col)` boolean
mask is treated as (reversed) binary digit: `true` as 1; `false` as 0.
Traversing left-right, top-bottom (top-left is lowest bit,
bottom-right - highest).
Example:
Assume the output should have 3 rows of symbols each with width 2. Encode
symbols are ' ', '▌', '▐', '█' with `1x2` resolution.
Assume input strings: >
aaaaa
b b
d d
e e
<
Steps:
- Convert to boolean mask (each row is a boolean array, "t"/"f" ~ `true`/`false`,
empty spots are equivalent to being `false`): >
ttttt
ftft
ftft
tft
<
- Rescale. Output dimensions are `n_rows * resolution.row = 3 * 1 = 3` rows and
`n_cols * resolution.col = 2 * 2 = 4`. It creates as equal as possible grid
with 3 rows and 4 columns and converts bins to single booleans. Result: >
tttt
tftf
ttff
<
- Convert to symbols. It makes `1x2` bins, treats their input as (reversed)
binary digits (`ff=00=0`, `tf=10=1`, `ft=01=2`, `tt=11=3`) and takes
corresponding symbols from supplied options (value plus 1). Result: >
██
▌▌
█
<
Parameters ~
{strings} `(table)` Array of arbitrary strings.
{opts} `(table|nil)` Options. Possible fields:
- <n_rows> - number of rows in output encoding. If too big, will be
truncated to be maximum needed to encode all input strings (taking into
account symbols row resolution). Default: `math.huge`.
- <n_cols> - width of every encoding string. If too big, will be truncated
to be maximum needed to encode all input strings (taking into account
symbols column resolution). Default: `math.huge`.
- <symbols> - array of symbols with extra `resolution` field. See "Encode
symbols" section of |MiniMap.config| for more details. Default: output
of |MiniMap.gen_encode_symbols.block()| with `'3x2'` identifier.
Return ~
`(table)` Array of encoded strings.
------------------------------------------------------------------------------
*MiniMap.open()*
`MiniMap.open`({opts})
Open map window
This creates and shows map window in current tabpage. It basically has
two steps:
- If not already done, create map buffer (used to set lines and other
visual indicators) and map window.
- Call |MiniMap.refresh()|.
Parameters ~
{opts} `(table|nil)` Options used to define map configuration. Same structure
as |MiniMap.config|. Will have effect until at least one tabpage has opened
map window. Default values are taken in the following order:
- From `opts` field of |MiniMap.current|.
- From `vim.b.minimap_config`.
- From |MiniMap.config|.
------------------------------------------------------------------------------
*MiniMap.refresh()*
`MiniMap.refresh`({opts}, {parts})
Refresh map window
This function serves two purposes:
- Update current map configuration via `opts`.
- Update parts of displayed content via `parts`.
Parameters ~
{opts} `(table|nil)` Options used to define map configuration. Same structure
as |MiniMap.config|. Will have effect until at least one tabpage has opened
map window. Default values are taken in the following order:
- From `opts` field of |MiniMap.current|.
- From `vim.b.minimap_config`.
- From |MiniMap.config|.
{parts} `(table|nil)` Which parts to update. Recognised keys with boolean
values (all `true` by default):
- <integrations> - whether to update integration highlights.
- <lines> - whether to update map lines.
- <scrollbar> - whether to update scrollbar.
------------------------------------------------------------------------------
*MiniMap.close()*
`MiniMap.close`()
Close map window
Also resets `opts` field of |MiniMap.current| after closing last map window
(among possibly several tabpages).
------------------------------------------------------------------------------
*MiniMap.toggle()*
`MiniMap.toggle`({opts})
Toggle map window
Open if not shown in current tabpage, close otherwise.
Parameters ~
{opts} `(table|nil)` Input for |MiniMap.open()|.
------------------------------------------------------------------------------
*MiniMap.toggle_focus()*
`MiniMap.toggle_focus`({use_previous_cursor})
Toggle focus to/from map window
When not inside map window, put cursor inside map window; otherwise put
cursor in previous window with source buffer.
When cursor is moving inside map window (but not just after focusing), view of
source window is updated to show first line convertible to current map line.
This allows quick targeted source buffer exploration.
There are at least these extra methods to focus back from map window:
- Press `<CR>` to accept current explored position in source buffer.
Equivalent to calling this function with `false` argument.
- Press `<Esc>` to go back to original position prior focusing on map window.
Equivalent to calling this function with `true` argument.
Parameters ~
{use_previous_cursor} `(boolean|nil)` Whether to focus on source window at
original cursor position (the one prior focusing on map window).
------------------------------------------------------------------------------
*MiniMap.toggle_side()*
`MiniMap.toggle_side`()
Toggle side of map window
A small convenience wrapper for calling |MiniMap.refresh()| to change the
side of map window.
------------------------------------------------------------------------------
*MiniMap.gen_encode_symbols*
`MiniMap.gen_encode_symbols`
Generate encode symbols
This is a table with function elements. Call to actually get encode symbols.
Each element takes a string resolution identifier of a form `'rxc'` (like `'3x2'`)
where `r` is a row resolution of each symbol (how many rows of binary data it
can encode) and `c` is a column resolution (how many columns it can encode).
------------------------------------------------------------------------------
*MiniMap.gen_encode_symbols.block()*
`MiniMap.gen_encode_symbols.block`({id})
Generate block encode symbols
Outputs use solid block to encode binary data. Example: '🬗', '▟', '█'.
Parameters ~
{id} `(string)` Resolution identifier.
Available values: `'1x2'`, `'2x1'`, `'2x2'`, `'3x2'` (default in 'mini.map').
------------------------------------------------------------------------------
*MiniMap.gen_encode_symbols.dot()*
`MiniMap.gen_encode_symbols.dot`({id})
Generate dot encode symbols
Outputs use dots to encode binary data. Example: '⡪', '⣼', '⣿'.
Parameters ~
{id} `(string)` Resolution identifier. Available values: `'4x2'`, `'3x2'`.
------------------------------------------------------------------------------
*MiniMap.gen_encode_symbols.shade()*
`MiniMap.gen_encode_symbols.shade`({id})
Generate shade encode symbols
Outputs use whole cell shades to encode binary data. They use same set of
characters ('░', '▒', '▒', '▓), but with different resolution.
Parameters ~
{id} `(string)` Resolution identifier. Available values: `'1x2'`, `'2x1'`.
------------------------------------------------------------------------------
*MiniMap.gen_integration*
`MiniMap.gen_integration`
Generate integrations
This is a table with function elements. Call to actually get encode symbols.
Each element takes a table defining highlight groups used for to highlight
map lines.
------------------------------------------------------------------------------
*MiniMap.gen_integration.builtin_search()*
`MiniMap.gen_integration.builtin_search`({hl_groups})
Builtin search
Highlight lines with matches of current builtin search (like with |/|, |?|, etc.).
Integration count reflects number of actual matches.
It prompts integration highlighting update on every change of |'hlsearch'|
(see |OptionSet|) or |v:hlsearch|. Note that it is not happening for some keys:
- After starting search with |n|, |N|, |star|, or |#|.
To enable highlight update on this keys, make custom mappings. Like this: >lua
for _, key in ipairs({ 'n', 'N', '*', '#' }) do
local rhs = key ..
'<Cmd>lua MiniMap.refresh({}, {lines = false, scrollbar = false})<CR>'
vim.keymap.set('n', key, rhs)
end
<
Parameters ~
{hl_groups} `(table|nil)` Table defining highlight groups. Can have the
following fields:
- <search> - highlight group for search matches. Default: |hl-Search|.
------------------------------------------------------------------------------
*MiniMap.gen_integration.diagnostic()*
`MiniMap.gen_integration.diagnostic`({hl_groups})
Builtin diagnostic
Highlight lines with matches of current diagnostic items. Items are computed
with |vim.diagnostic.get()| for current (source) buffer.
It prompts integration highlighting update on every |DiagnosticChanged| event.
Diagnostic items with higher severity (see |vim.diagnostic.severity|) have
higher highlight priority (errors will be shown over all others, etc.).
Parameters ~
{hl_groups} `(table|nil)` Table defining highlight groups. Supplied fields
also define which diagnostic severity to highlight.
Can have the following fields:
- <error> - highlight group for error items.
Default: |hl-DiagnosticFloatingError|.
- <warn> - highlight group for warning items. Default: `nil` (not shown).
- <info> - highlight group for info items. Default: `nil` (not shown).
- <hint> - highlight group for hint items. Default: `nil` (not shown).
Usage ~
>lua
-- Show all diagnostic levels
local map = require('mini.map')
local diagnostic_integration = map.gen_integration.diagnostic({
error = 'DiagnosticFloatingError',
warn = 'DiagnosticFloatingWarn',
info = 'DiagnosticFloatingInfo',
hint = 'DiagnosticFloatingHint',
})
map.setup({ integrations = { diagnostic_integration } })
<
------------------------------------------------------------------------------
*MiniMap.gen_integration.diff()*
`MiniMap.gen_integration.diff`({hl_groups})
General diff hunks from |mini.diff|
Highlight lines which are part of current diff.
Requires 'mini.diff' as dependency.
Parameters ~
{hl_groups} `(table|nil)` Table defining highlight groups. If `nil` (not
supplied), this status is not highlighted. Can have the following fields:
- <add> - group name for "add" hunks. Default: "MiniDiffSignAdd".
- <change> - group name for "change" hunks. Default: "MiniDiffSignChange".
- <delete> - group name for "delete" hunks. Default: "MiniDiffSignDelete".
------------------------------------------------------------------------------
*MiniMap.gen_integration.gitsigns()*
`MiniMap.gen_integration.gitsigns`({hl_groups})
Hunks from 'lewis6991/gitsigns.nvim'
Highlight lines which have non-trivial Git status.
Requires [lewis6991/gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim).
Parameters ~
{hl_groups} `(table|nil)` Table defining highlight groups. If `nil` (not
supplied), this status is not highlighted. Can have the following fields:
- <add> - group name for added lines. Default: "GitSignsAdd".
- <change> - group name for changed lines. Default: "GitSignsChange".
- <delete> - group name for deleted lines. Default: "GitSignsDelete".
vim:tw=78:ts=8:noet:ft=help:norl:
0