christoph/flake-nixinator
1
Fork 0
Code Activity

Update generated neovim config

Browse Source
This commit is contained in:
Christoph Urlacher
2024-08-15 14:28:54 +02:00
parent 07409c223d
commit 25cfcf2941
3809 changed files with 351157 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

496
config/neovim/store/lazy-plugins/mini.nvim/doc/mini-jump2d.txt Normal file
View File

@ -0,0 +1,496 @@
*mini.jump2d* Jump within visible lines
*MiniJump2d*
MIT License Copyright (c) 2022 Evgeni Chasnovski
==============================================================================
Jump within visible lines via iterative label filtering.
Features:
- Make jump by iterative filtering of possible, equally considered jump
spots until there is only one. Filtering is done by typing a label
character that is visualized at jump spot.
- Customizable (see |MiniJump2d.config|):
- Way of computing possible jump spots with opinionated default.
- Characters used to label jump spots during iterative filtering.
- Visual effects: how many steps ahead to show; dim lines with spots.
- Action hooks to be executed at certain events during jump.
- Allowed windows: current and/or not current.
- Allowed lines: whether to process blank or folded lines, lines
before/at/after cursor line, etc. Example: user can configure to look
for spots only inside current window at or after cursor line.
Example: user can configure to look for word starts only inside current
window at or after cursor line with 'j' and 'k' labels performing some
action after jump.
- Works in Visual and Operator-pending (with dot-repeat) modes.
- Preconfigured ways of computing jump spots (see |MiniJump2d.builtin_opts|):
- Starts of lines.
- Starts of words.
- Single character from user input.
- Variable length query from user input.
- Works with multibyte characters.
General overview of how jump is intended to be performed:
- Lock eyes on desired location ("spot") recognizable by future jump.
Should be within visible lines at place where cursor can be placed.
- Initiate jump. Either by custom keybinding or with a call to
|MiniJump2d.start()| (allows customization options). This will highlight
all possible jump spots with their labels (letters from "a" to "z" by
default). For more details, read |MiniJump2d.start()| and |MiniJump2d.config|.
- Type character that appeared over desired location. If its label was
unique, jump is performed. If it wasn't unique, possible jump spots are
filtered to those having the same label character.
- Repeat previous step until there is only one possible jump spot or type <CR>
to jump to first available jump spot. Typing anything else stops jumping
without moving cursor.
# Setup ~
This module needs a setup with `require('mini.jump2d').setup({})` (replace
`{}` with your `config` table). It will create global Lua table
`MiniJump2d` which you can use for scripting or manually (with
`:lua MiniJump2d.*`).
See |MiniJump2d.config| for available config settings.
You can override runtime config settings locally to buffer inside
`vim.b.minijump2d_config` which should have same structure as
`MiniJump2d.config`. See |mini.nvim-buffer-local-config| for more details.
To stop module from showing non-error feedback, set `config.silent = true`.
# Example usage ~
- Modify default jumping to use only current window at or after cursor line: >lua
require('mini.jump2d').setup({
allowed_lines = { cursor_before = false },
allowed_windows = { not_current = false },
})
<
- Jump to word start using combination of options supplied in
|MiniJump2d.config| and |MiniJump2d.builtin_opts.line_start|: >vim
:lua MiniJump2d.start(MiniJump2d.builtin_opts.line_start)
<
- Jump to a single character typed after executing this command: >vim
:lua MiniJump2d.start(MiniJump2d.builtin_opts.single_character)
<
- See more examples in |MiniJump2d.start| and |MiniJump2d.builtin_opts|.
# Comparisons ~
- 'phaazon/hop.nvim':
- Both are fast, customizable, and extensible (user can write their own
ways to define jump spots).
- 'hop.nvim' visualizes all steps at once. While this module can show
configurable number of steps ahead.
- Both have several builtin ways to specify type of jump (word start,
line start, one character or query based on user input). 'hop.nvim'
does that by exporting many targeted Neovim commands, while this
module has preconfigured basic options leaving others to
customization with Lua code (see |MiniJump2d.builtin_opts|).
- 'hop.nvim' computes labels (called "hints") differently. Contrary to
this module deliberately not having preference of one jump spot over
another, 'hop.nvim' uses specialized algorithm that produces sequence
of keys in a slightly biased manner: some sequences are intentionally
shorter than the others (leading to fewer average keystrokes). They
are put near cursor (by default) and highlighted differently. Final
order of sequences is based on distance to the cursor.
- 'mini.jump2d' has opinionated default algorithm of computing jump
spots. See |MiniJump2d.default_spotter|.
# Highlight groups ~
* `MiniJump2dSpot` - highlighting of jump spot's next step. By default it
uses label with highest contrast while not being too visually demanding:
white on black for dark 'background', black on white for light. If it
doesn't suit your liking, try couple of these alternatives (or choose
your own, of course): >lua
-- Reverse underlying colors (mostly *very* visible in any colorscheme)
vim.api.nvim_set_hl(0, 'MiniJump2dSpot', { reverse = true })
-- Bold italic
vim.api.nvim_set_hl(0, 'MiniJump2dSpot', { bold = true, italic = true })
-- Red undercurl
vim.api.nvim_set_hl(0, 'MiniJump2dSpot', { sp = 'Red', undercurl = true })
<
* `MiniJump2dSpotUnique` - highlighting of jump spot's next step if it has
unique label. By default links to `MiniJump2dSpot`.
* `MiniJump2dSpotAhead` - highlighting of jump spot's future steps. By default
similar to `MiniJump2dSpot` but with less contrast and visibility.
* `MiniJump2dDim` - highlighting of lines with at least one jump spot.
Make it non-bright in order for jump spot labels to be more visible.
By default linked to `Comment` highlight group.
To change any highlight group, modify it directly with |:highlight|.
# Disabling ~
To disable, set `vim.g.minijump2d_disable` (globally) or
`vim.b.minijump2d_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.
------------------------------------------------------------------------------
*MiniJump2d.setup()*
`MiniJump2d.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniJump2d.config|.
Usage ~
>lua
require('mini.jump2d').setup() -- use default config
-- OR
require('mini.jump2d').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniJump2d.config*
`MiniJump2d.config`
Module config
Default values:
>lua
MiniJump2d.config = {
-- Function producing jump spots (byte indexed) for a particular line.
-- For more information see |MiniJump2d.start|.
-- If `nil` (default) - use |MiniJump2d.default_spotter|
spotter = nil,
-- Characters used for labels of jump spots (in supplied order)
labels = 'abcdefghijklmnopqrstuvwxyz',
-- Options for visual effects
view = {
-- Whether to dim lines with at least one jump spot
dim = false,
-- How many steps ahead to show. Set to big number to show all steps.
n_steps_ahead = 0,
},
-- Which lines are used for computing spots
allowed_lines = {
blank = true, -- Blank line (not sent to spotter even if `true`)
cursor_before = true, -- Lines before cursor line
cursor_at = true, -- Cursor line
cursor_after = true, -- Lines after cursor line
fold = true, -- Start of fold (not sent to spotter even if `true`)
},
-- Which windows from current tabpage are used for visible lines
allowed_windows = {
current = true,
not_current = true,
},
-- Functions to be executed at certain events
hooks = {
before_start = nil, -- Before jump start
after_jump = nil, -- After jump was actually done
},
-- Module mappings. Use `''` (empty string) to disable one.
mappings = {
start_jumping = '<CR>',
},
-- Whether to disable showing non-error feedback
silent = false,
}
<
# Options ~
## Spotter function ~
Actual computation of possible jump spots is done through spotter function.
It should have the following arguments:
- `line_num` is a line number inside buffer.
- `args` - table with additional arguments:
- {win_id} - identifier of a window where input line number is from.
- {win_id_init} - identifier of a window which was current when
`MiniJump2d.start()` was called.
Its output is a list of byte-indexed positions that should be considered as
possible jump spots for this particular line in this particular window.
Note: for a more aligned visualization this list should be (but not
strictly necessary) sorted increasingly.
Note: spotter function is always called with `win_id` window being
"temporary current" (see |nvim_win_call|). This allows using builtin
Vimscript functions that operate only inside current window.
## View ~
Option `view.n_steps_ahead` controls how many steps ahead to show along
with the currently required label. Those future steps are showed with
different (less visible) highlight group ("MiniJump2dSpotAhead"). Usually
it is a good idea to use this with a spotter which doesn't result into many
jump spots (like, for example, |MiniJump2d.builtin_opts.word_start|).
Default is 0 to not show anything ahead as it reduces visual noise.
Option `view.dim` controls whether to dim lines with at least one jump spot.
Dimming is done by applying "MiniJump2dDim" highlight group to the whole line.
## Allowed lines ~
Option `allowed_lines` controls which lines will be used for computing
possible jump spots:
- If `blank` or `fold` is `true`, it is possible to jump to first column of blank
line (determined by |prevnonblank|) or first folded one (determined by
|foldclosed|) respectively. Otherwise they are skipped. These lines are
not processed by spotter function even if the option is `true`.
- If `cursor_before`, (`cursor_at`, `cursor_after`) is `true`, lines before
(at, after) cursor line of all processed windows are forwarded to spotter
function. Otherwise, they don't. This allows control of jump "direction".
## Hooks ~
Following hook functions can be used to further tweak jumping experience:
- `before_start` - called without arguments first thing when jump starts.
One of the possible use cases is to ask for user input and update spotter
function with it.
- `after_jump` - called after jump was actually done. Useful to make
post-adjustments (like move cursor to first non-whitespace character).
------------------------------------------------------------------------------
*MiniJump2d.start()*
`MiniJump2d.start`({opts})
Start jumping
Compute possible jump spots, visualize them and wait for iterative filtering.
First computation of possible jump spots ~
- Process allowed windows (current and/or not current; controlled by
`allowed_windows` option) by visible lines from top to bottom. For each
one see if it is allowed (controlled by `allowed_lines` option). If not
allowed, then do nothing. If allowed and should be processed by
`spotter`, process it.
- Apply spotter function from `spotter` option for each appropriate line
and concatenate outputs. This means that eventual order of jump spots
aligns with lexicographical order within "window id" - "line number" -
"position in `spotter` output" tuples.
- For each possible jump compute its label: a single character from
`labels` option used to filter jump spots. Each possible label character
might be used more than once to label several "consecutive" jump spots.
It is done in an optimal way under assumption of no preference of one
spot over another. Basically, it means "use all labels at each step of
iterative filtering as equally as possible".
Visualization ~
Current label for each possible jump spot is shown at that position
overriding everything underneath it.
Iterative filtering ~
Labels of possible jump spots are computed in order to use them as equally
as possible.
Example:
- With `abc` as `labels` option, initial labels for 10 possible jumps
are "aaaabbbccc". As there are 10 spots which should be "coded" with 3
symbols, at least 2 symbols need 3 steps to filter them out. With current
implementation those are always the "first ones".
- After typing `a`, it filters first four jump spots and recomputes its
labels to be "aabc".
- After typing `a` again, it filters first two spots and recomputes its
labels to be "ab".
- After typing either `a` or `b` it filters single spot and makes jump.
With default 26 labels for most real-world cases 2 steps is enough for
default spotter function. Rarely 3 steps are needed with several windows.
Parameters ~
{opts} `(table|nil)` Configuration of jumping, overriding global and buffer
local values.config|. Has the same structure as |MiniJump2d.config|
without <mappings> field. Extra allowed fields:
- <hl_group> - which highlight group to use for first step.
Default: "MiniJump2dSpot".
- <hl_group_ahead> - which highlight group to use for second step and later.
Default: "MiniJump2dSpotAhead".
- <hl_group_dim> - which highlight group to use dimming used lines.
Default: "MiniJump2dSpotDim".
Usage ~
>lua
-- Start default jumping
MiniJump2d.start()
-- Jump to word start
MiniJump2d.start(MiniJump2d.builtin_opts.word_start)
-- Jump to single character from user input (follow by typing one character)
MiniJump2d.start(MiniJump2d.builtin_opts.single_character)
-- Jump to first character of punctuation group only inside current window
-- which is placed at cursor line; visualize with `Search`
MiniJump2d.start({
spotter = MiniJump2d.gen_pattern_spotter('%p+'),
allowed_lines = { cursor_before = false, cursor_after = false },
allowed_windows = { not_current = false },
hl_group = 'Search'
})
See also ~
|MiniJump2d.config|
------------------------------------------------------------------------------
*MiniJump2d.stop()*
`MiniJump2d.stop`()
Stop jumping
------------------------------------------------------------------------------
*MiniJump2d.gen_pattern_spotter()*
`MiniJump2d.gen_pattern_spotter`({pattern}, {side})
Generate spotter for Lua pattern
Parameters ~
{pattern} `(string|nil)` Lua pattern. Default: `'[^%s%p]+'` which matches group
of "non-whitespace non-punctuation characters" (basically a way of saying
"group of alphanumeric characters" that works with multibyte characters).
{side} `(string|nil)` Which side of pattern match should be considered as
jumping spot. Should be one of 'start' (start of match, default), 'end'
(inclusive end of match), or 'none' (match for spot is done manually
inside pattern with plain `()` matching group).
Return ~
`(function)` Spotter function.
Usage ~
>lua
-- Match any punctuation
MiniJump2d.gen_pattern_spotter('%p')
-- Match first from line start non-whitespace character
MiniJump2d.gen_pattern_spotter('^%s*%S', 'end')
-- Match start of last word
MiniJump2d.gen_pattern_spotter('[^%s%p]+[%s%p]-$', 'start')
-- Match letter followed by another letter (example of manual matching
-- inside pattern)
MiniJump2d.gen_pattern_spotter('%a()%a', 'none')
<
------------------------------------------------------------------------------
*MiniJump2d.gen_union_spotter()*
`MiniJump2d.gen_union_spotter`({...})
Generate union of spotters
Parameters ~
{...} `(any)` Each argument should be a valid spotter.
See |MiniJump2d.config| for more details.
Return ~
`(function)` Spotter producing union of spots.
Usage ~
>lua
-- Match start and end of non-blank character groups:
local nonblank_start = MiniJump2d.gen_pattern_spotter('%S+', 'start')
local nonblank_end = MiniJump2d.gen_pattern_spotter('%S+', 'end')
local spotter = MiniJump2d.gen_union_spotter(nonblank_start, nonblank_end)
<
------------------------------------------------------------------------------
*MiniJump2d.default_spotter*
`MiniJump2d.default_spotter`
Default spotter function
Spot is possible for jump if it is one of the following:
- Start or end of non-whitespace character group.
- Alphanumeric character followed or preceded by punctuation (useful for
snake case names).
- Start of uppercase character group (useful for camel case names). Usually
only Latin alphabet is recognized due to Lua patterns shortcomings.
These rules are derived in an attempt to balance between two intentions:
- Allow as much useful jumping spots as possible.
- Make labeled jump spots easily distinguishable.
Usually takes from 2 to 3 keystrokes to get to destination.
------------------------------------------------------------------------------
*MiniJump2d.builtin_opts*
`MiniJump2d.builtin_opts`
Table with builtin `opts` values for |MiniJump2d.start()|
Each element of table is itself a table defining one or several options for
`MiniJump2d.start()`. Read help description to see which options it defines
(like in |MiniJump2d.builtin_opts.line_start|).
Usage ~
>lua
-- Using `MiniJump2d.builtin_opts.line_start` as example:
-- Command
:lua MiniJump2d.start(MiniJump2d.builtin_opts.line_start)
-- Custom mapping
vim.keymap.set(
'n', '<CR>',
'<Cmd>lua MiniJump2d.start(MiniJump2d.builtin_opts.line_start)<CR>'
)
-- Inside `MiniJump2d.setup()` (make sure to use all defined options)
local jump2d = require('mini.jump2d')
local jump_line_start = jump2d.builtin_opts.line_start
jump2d.setup({
spotter = jump_line_start.spotter,
hooks = { after_jump = jump_line_start.hooks.after_jump }
})
<
------------------------------------------------------------------------------
*MiniJump2d.builtin_opts.default*
`MiniJump2d.builtin_opts.default`
Jump with |MiniJump2d.default_spotter()|
Defines `spotter`.
------------------------------------------------------------------------------
*MiniJump2d.builtin_opts.line_start*
`MiniJump2d.builtin_opts.line_start`
Jump to line start
Defines `spotter` and `hooks.after_jump`.
------------------------------------------------------------------------------
*MiniJump2d.builtin_opts.word_start*
`MiniJump2d.builtin_opts.word_start`
Jump to word start
Defines `spotter`.
------------------------------------------------------------------------------
*MiniJump2d.builtin_opts.single_character*
`MiniJump2d.builtin_opts.single_character`
Jump to single character taken from user input
Defines `spotter`, `allowed_lines.blank`, `allowed_lines.fold`, and
`hooks.before_start`.
------------------------------------------------------------------------------
*MiniJump2d.builtin_opts.query*
`MiniJump2d.builtin_opts.query`
Jump to query taken from user input
Defines `spotter`, `allowed_lines.blank`, `allowed_lines.fold`, and
`hooks.before_start`.
vim:tw=78:ts=8:noet:ft=help:norl: