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

mini-pick.txt

Latest commit

 

History

History
1460 lines (1131 loc) · 56.6 KB

mini-pick.txt

File metadata and controls

1460 lines (1131 loc) · 56.6 KB
Raw
marked; unmark all otherwise) of all currently matched items.
Notes:
- Marks persist across queries and matches. For example, user can make a query
with marking all matches several times and marked items from all queries
will be preserved.
*MiniPick-actions-move*
## Move ~
Move is a fundamental action of changing which item is current.
- `mappings.move_down` - change focus to the item below.
- `mappings.move_start` change focus to the first currently matched item
- `mappings.move_up` - change focus to the item above.
Notes:
- Up and down wrap around edges: `move_down` on last item moves to first,
`move_up` on first moves to last.
- Moving when preview or info view is shown updates the view with new item.
- These also work with non-overridable alternatives:
- `<Down>` moves down.
- `<Home>` moves to first matched.
- `<Up>` moves up.
*MiniPick-actions-paste*
## Paste ~
Paste is an action to paste content of |registers| at caret.
- `mappings.paste` - paste from register defined by the next key press.
Notes:
- Does not support expression register `=`.
*MiniPick-actions-refine*
## Refine ~
Refine is an action that primarily executes the following:
- Takes certain items and makes them be all items (in order they are present).
- Resets query.
- Updates `source.match` to be the one from config.
- `mappings.refine` - refine currently matched items.
- `mappings.refin_marked` - refine currently marked items.
This action is useful in at least two cases:
- Perform consecutive "narrowing" queries. Example: to get items that contain
both "hello" and "world" exact matches (in no particular order) with default
matching, type "'hello" (notice "'" at the start) followed by `<C-Space>` and
another "'world".
- Reset `match` to default. Particularly useful in |MiniPick.builtin.grep_live()|.
*MiniPick-actions-scroll*
## Scroll ~
Scroll is an action to either move current item focus further than to the
neighbor item or adjust window view to see more information.
- `mappings.scroll_down` - when matches are shown, go down by the amount of
visible matches. In preview and info view - scroll down as with |CTRL-F|.
- `mappings.scroll_left` - scroll left as with |zH|.
- `mappings.scroll_right` - scroll right as with |zL|.
- `mappings.scroll_up` - when matches are shown, go up by the amount of
visible matches. In preview and info view - scroll up as with |CTRL-B|.
*MiniPick-actions-stop*
## Stop ~
`mappings.stop` stops the picker. <C-c> also always stops the picker.
*MiniPick-actions-toggle*
## Toggle ~
Toggle action is a way to change view: show if target is not shown, reset to
main view otherwise.
- `mappings.toggle_info` - toggle info view.
- `mappings.toggle_preview` - toggle preview.
Note:
- Updating query in any way resets window view to show matches.
- Moving current item focus keeps preview or info view with updated item.
*MiniPick-actions-custom*
# Custom ~
Along with built-in actions, users can define custom actions. This can be
done by supplying custom elements to `mappings` table. The field defines action
name (used to infer an action description in info view). The value is a table
with the following fields:
- <char> `(string)` - single character acting as action trigger.
- <func> `(function)` - callable to be executed without arguments after
user presses <char>. Its return value is treated as "should stop picker
after execution", i.e. returning nothing, `nil`, or `false` continues
picker while everything else (prefer `true`) stops it.
Example of `execute` custom mapping: >lua
execute = {
char = '<C-e>',
func = function() vim.cmd(vim.fn.input('Execute: ')) end,
}
<
------------------------------------------------------------------------------
*MiniPick-examples*
Common configuration examples ~
- Disable icons in |MiniPick.builtin| pickers related to paths: >lua
local pick = require('mini.pick')
pick.setup({ source = { show = pick.default_show } })
<
- Mappings to switch `toggle_{preview,info}` and `move_{up,down}`: >lua
require('mini.pick').setup({
mappings = {
toggle_info = '<C-k>',
toggle_preview = '<C-p>',
move_down = '<Tab>',
move_up = '<S-Tab>',
}
})
<
- Different window styles: >lua
-- Different border
{ window = { config = { border = 'double' } } }
-- "Cursor tooltip"
{
window = {
config = {
relative = 'cursor', anchor = 'NW',
row = 0, col = 0, width = 40, height = 20,
},
},
}
-- Centered on screen
local win_config = function()
height = math.floor(0.618 * vim.o.lines)
width = math.floor(0.618 * vim.o.columns)
return {
anchor = 'NW', height = height, width = width,
row = math.floor(0.5 * (vim.o.lines - height)),
col = math.floor(0.5 * (vim.o.columns - width)),
}
end
{ window = { config = win_config } }
<
------------------------------------------------------------------------------
*MiniPick.setup()*
`MiniPick.setup`({config})
Module setup
*:Pick*
Calling this function creates a `:Pick` user command. It takes picker name
from |MiniPick.registry| as mandatory first argument and executes it with
following (expanded, |expandcmd()|) |<f-args>| combined in a single table.
To add custom pickers, update |MiniPick.registry|.
Example: >vim
:Pick files tool='git'
:Pick grep pattern='<cword>'
<
Parameters ~
{config} `(table|nil)` Module config table. See |MiniPick.config|.
Usage ~
>lua
require('mini.pick').setup() -- use default config
-- OR
require('mini.pick').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniPick.config*
`MiniPick.config`
Module config
Default values:
>lua
MiniPick.config = {
-- Delays (in ms; should be at least 1)
delay = {
-- Delay between forcing asynchronous behavior
async = 10,
-- Delay between computation start and visual feedback about it
busy = 50,
},
-- Keys for performing actions. See `:h MiniPick-actions`.
mappings = {
caret_left = '<Left>',
caret_right = '<Right>',
choose = '<CR>',
choose_in_split = '<C-s>',
choose_in_tabpage = '<C-t>',
choose_in_vsplit = '<C-v>',
choose_marked = '<M-CR>',
delete_char = '<BS>',
delete_char_right = '<Del>',
delete_left = '<C-u>',
delete_word = '<C-w>',
mark = '<C-x>',
mark_all = '<C-a>',
move_down = '<C-n>',
move_start = '<C-g>',
move_up = '<C-p>',
paste = '<C-r>',
refine = '<C-Space>',
refine_marked = '<M-Space>',
scroll_down = '<C-f>',
scroll_left = '<C-h>',
scroll_right = '<C-l>',
scroll_up = '<C-b>',
stop = '<Esc>',
toggle_info = '<S-Tab>',
toggle_preview = '<Tab>',
},
-- General options
options = {
-- Whether to show content from bottom to top
content_from_bottom = false,
-- Whether to cache matches (more speed and memory on repeated prompts)
use_cache = false,
},
-- Source definition. See `:h MiniPick-source`.
source = {
items = nil,
name = nil,
cwd = nil,
match = nil,
show = nil,
preview = nil,
choose = nil,
choose_marked = nil,
},
-- Window related options
window = {
-- Float window config (table or callable returning it)
config = nil,
-- String to use as cursor in prompt
prompt_cursor = '▏',
-- String to use as prefix in prompt
prompt_prefix = '> ',
},
}
<
# Delays ~
`config.delay` defines plugin delays (in ms). All should be strictly positive.
`delay.async` is a delay between forcing asynchronous behavior. This usually
means making screen redraws and utilizing |MiniPick.poke_is_picker_active()|
(for example, to stop current matching if query has updated).
Smaller values give smoother user experience at the cost of more computations.
`delay.busy` is a delay between when some computation starts and showing
visual feedback about it by making window border to have `MiniPickBorderBusy`
highlight group.
Smaller values will give feedback faster at the cost of feeling like flicker.
# Mappings ~
`config.mappings` defines keys for special actions to be triggered after certain
keys. See |MiniPick-actions| for more information.
# Options ~
`config.options` contains some general purpose options.
`options.content_from_bottom` is a boolean indicating whether content should be
shown from bottom to top. That means that best matches will be shown at
the bottom. Note: for better experience use Neovim>=0.10, which has floating
window footer capability. Default: `false`.
`options.use_cache` is a boolean indicating whether match results should be
cached per prompt (i.e. concatenated query). This results into faster response
on repeated prompts (like when deleting query entries) at the cost of using
more memory. Default: `false`.
# Source ~
`config.source` defines fallbacks for source specification. For example, this
can be used to change default `match` to use different implementation or `show`
to not show icons for some |MiniPick.builtin| pickers (see |MiniPick-examples|).
See |MiniPick-source| for more information.
# Window ~
`config.window` contains window specific configurations.
`window.config` defines a (parts of) default floating window config for the main
picker window. This can be either a table overriding some parts or a callable
returning such table. See |MiniPick-examples| for some examples.
`window.prompt_cursor` defines how cursor is displayed in window's prompt.
Default: '▏'.
`window.prompt_prefix` defines what prefix is used in window's prompt.
Default: '> '.
------------------------------------------------------------------------------
*MiniPick.start()*
`MiniPick.start`({opts})
Start picker
Notes:
- If there is currently an active picker, it is properly stopped and new one
is started "soon" in the main event-loop (see |vim.schedule()|).
- Current window at the moment of this function call is treated as "target".
See |MiniPick.get_picker_state()| and |MiniPick.set_picker_target_window()|.
Parameters ~
{opts} `(table|nil)` Options. Should have same structure as |MiniPick.config|.
Default values are inferred from there.
Usually should have proper |MiniPick-source.items| defined.
Return ~
`(any)` Item which was current when picker is stopped; `nil` if aborted.
------------------------------------------------------------------------------
*MiniPick.stop()*
`MiniPick.stop`()
Stop active picker
------------------------------------------------------------------------------
*MiniPick.refresh()*
`MiniPick.refresh`()
Refresh active picker
------------------------------------------------------------------------------
*MiniPick.default_match()*
`MiniPick.default_match`({stritems}, {inds}, {query}, {opts})
Default match
Filter target stritems to contain query and sort from best to worst matches.
Implements default value for |MiniPick-source.match|.
By default (if no special modes apply) it does the following fuzzy matching:
- Stritem contains query if it contains all its elements verbatim in the same
order (possibly with gaps, i.e. not strictly one after another).
Note: empty query and empty string element is contained in any string.
- Sorting is done with the following ordering (same as in |mini.fuzzy|):
- The smaller the match width (end column minus start column) the better.
- Among same match width, the smaller start column the better.
- Among same match width and start column, preserve original order.
Notes:
- Most common interactive usage results into `query` containing one typed
character per element.
# Special modes ~
- Forced modes:
- Query starts with "*": match the rest fuzzy (without other modes).
- Query starts with "'": match the rest exactly (without gaps).
- Place modes:
- Query starts with '^': match the rest exactly at start.
- Query ends with '$': match the rest exactly at end.
- Both modes can be used simultaneously.
- Grouped: query contains at least one whitespace element. Output is computed
as if query is split at whitespace indexes with concatenation between them.
Precedence of modes:
"forced exact" = "forced fuzzy" > "place start/end" > "grouped" > "default"
# Examples ~
Assuming `stritems` are `{ '_abc', 'a_bc', 'ab_c', 'abc_' }`, here are some
example matches based on prompt (concatenated query): >
| Prompt | Matches |
|--------|------------------------|
| abc | All |
| *abc | All |
| | |
| 'abc | abc_, _abc |
| *'abc | None (no "'" in items) |
| | |
| ^abc | abc_ |
| *^abc | None (no "^" in items) |
| | |
| abc$ | _abc |
| *abc$ | None (no "$" in items) |
| | |
| ab c | abc_, _abc, ab_c |
| *ab c | None (no " " in items) |
Having query `{ 'ab', 'c' }` is the same as "ab c" prompt.
You can have a feel of how this works with this command: >lua
MiniPick.start({ source = { items = { '_abc', 'a_bc', 'ab_c', 'abc_' } } })
<
Parameters ~
{stritems} `(table)` Array of all stritems.
{inds} `(table)` Array of `stritems` indexes to match. All of them should point
at string elements of `stritems`. No check is done for performance reasons.
{query} `(table)` Array of strings.
{opts} `(table|nil)` Options. Possible fields:
- <sync> `(boolean)` - Whether to match synchronously. Default: `false`.
- <preserve_order> `(boolean)` - Whether to skip sort step. Default: `false`.
Return ~
`(table|nil)` Depending on whether computation is synchronous (either `opts.sync`
is `true` or there is an active picker):
- If yes, array of `stritems` indexes matching the `query` (from best to worst).
- If no, `nil` is returned with |MiniPick.set_picker_match_inds()| used later.
------------------------------------------------------------------------------
*MiniPick.default_show()*
`MiniPick.default_show`({buf_id}, {items}, {query}, {opts})
Default show
Show items in a buffer and highlight parts that actually match query (assuming
match is done with |MiniPick.default_match()|). Lines are computed based on
the |MiniPick-source.items-stritems|.
Implements default value for |MiniPick-source.show|.
Uses the following highlight groups (see |MiniPick| for their description):
* `MiniPickIconDirectory`
* `MiniPickIconFile`
* `MiniPickMatchCurrent`
* `MiniPickMatchMarked`
* `MiniPickMatchRanges`
Parameters ~
{buf_id} `(number)` Identifier of target buffer.
{items} `(table)` Array of items to show.
{query} `(table)` Array of strings representing query.
{opts} `(table|nil)` Options. Possible fields:
- <show_icons> `(boolean)` - whether to show icons for entries recognized as
valid actually present paths on disk (see |MiniPick-source.items-common|),
empty space otherwise. Tries to use `text` field as fallback for path.
Default: `false`. Note: |MiniPick.builtin| pickers showing file/directory
paths use `true` by default.
- <icons> `(table)` - table with fallback icons used if icon provider
does not itself supply default icons for category. Can have fields:
- <directory> `(string)` - icon for directory. Default: " ".
- <file> `(string)` - icon for file. Default: " ".
- <none> `(string)` - icon for non-valid path. Default: " ".
------------------------------------------------------------------------------
*MiniPick.default_preview()*
`MiniPick.default_preview`({buf_id}, {item}, {opts})
Default preview
Preview item. Logic follows the rules in |MiniPick-source.items-common|:
- File and buffer are shown at the start.
- Directory has its content listed.
- Line/position/region in file or buffer is shown at start.
- Others are shown directly with |vim.inspect()|.
Implements default value for |MiniPick-source.preview|.
Uses the following highlight groups (see |MiniPick| for their description):
* `MiniPickPreviewLine`
* `MiniPickPreviewRegion`
Parameters ~
{buf_id} `(number)` Identifier of target buffer.
{item} `(any)` Item to preview.
{opts} `(table|nil)` Options. Possible values:
- <n_context_lines> `(number)` - number of lines to load past target position
when reading from disk. Useful to explore context. Default: 'lines' twice.
- <line_position> `(string)` - where in the window to show item position.
View remainder of file in raw view
0