*mini.pick* Pick anything

*MiniPick*

MIT License Copyright (c) 2023 Evgeni Chasnovski

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

Features:

- Single window general purpose interface for picking element from any array.

- On demand toggleable preview and info views.

- Interactive query matching (filter+sort) with fast non-blocking default

which does fuzzy matching and allows other modes (|MiniPick.default_match()|).

- Built-in pickers (see |MiniPick.builtin|):

- Files.

- Pattern match (for fixed pattern and with live feedback).

- Buffers.

- Help tags.

- CLI output.

- Resume latest picker.

- |:Pick| command to work with extensible |MiniPick.registry|.

- |vim.ui.select()| wrapper (see |MiniPick.ui_select()|).

- Rich and customizable built-in |MiniPick-actions| when picker is active:

- Manually change currently focused item.

- Scroll vertically and horizontally.

- Toggle preview or info view.

- Mark/unmark items to choose later.

- Refine current matches (make them part of a new picker).

- And many more.

- Minimal yet flexible |MiniPick-source| specification with:

- Items (array, callable, or manually set later).

- Source name.

- Working directory.

- Matching algorithm.

- Way matches are shown in main window.

- Item preview.

- "On choice" action for current and marked items.

- Custom actions/keys can be configured globally, per buffer, or per picker.

- Out of the box support for 'ignorecase' and 'smartcase'.

- Match caching to increase responsiveness on repeated prompts.

Notes:

- Works on all supported versions but using Neovim>=0.9 is recommended.

Neovim>=0.10 will give more visual feedback in floating window footer.

- For more pickers see |MiniExtra.pickers|.

Sources with more details:

- |MiniPick-overview|

- |MiniPick-source|

- |MiniPick-actions|

- |MiniPick-examples|

- |MiniPick.builtin|

# Dependencies ~

Suggested dependencies (provide extra functionality, will work without them):

- Plugin 'nvim-tree/nvim-web-devicons' for filetype icons near the items

representing actual paths. If missing, default or no icons will be used.

*MiniPick-cli-tools*

- CLI tool(s) to power |MiniPick.builtin.files()|, |MiniPick.builtin.grep()|, and

|MiniPick.builtin.grep_live()| built-in pickers:

- `rg` (github.com/BurntSushi/ripgrep; enough for all three; recommended).

- `fd` (github.com/sharkdp/fd; for `files` only).

- `git` (github.com/git/git; enough for all three).

Note: CLI tools are called only with basic arguments needed to get items.

To customize the output, use their respective configuration approaches.

Here are some examples of where to start:

- github.com/BurntSushi/ripgrep/blob/master/GUIDE.md#configuration-file

- github.com/sharkdp/fd#excluding-specific-files-or-directories

- git-scm.com/docs/gitignore

# Setup ~

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

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

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

See |MiniPick.config| for available config settings.

You can override runtime config settings locally to buffer inside

`vim.b.minipick_config` which should have same structure as `MiniPick.config`.

See |mini.nvim-buffer-local-config| for more details.

# Comparisons ~

- 'nvim-telescope/telescope.nvim':

- The main inspiration for this module, so there is significant overlap.

- Has three (or two) window UI (prompt, matches, preview), while this

module combines everything in one window. It allows more straightforward

customization for unusual scenarios.

- Default match algorithm is somewhat slow, while this module should

match relatively lag-free for at least 100K+ items.

- Has many built-in pickers, while this module has handful at its core

relying on other 'mini.nvim' modules to provide more (see |MiniExtra|).

- 'ibhagwan/fzf-lua':

- Mostly same comparison as with 'nvim-telescope/telescope.nvim'.

- Requires 'junegunn/fzf' installed to power fuzzy matching, while this

module provides built-in Lua matching.

# Highlight groups ~

* `MiniPickBorder` - window border.

* `MiniPickBorderBusy` - window border while picker is busy processing.

* `MiniPickBorderText` - non-prompt on border.

* `MiniPickIconDirectory` - default icon for directory.

* `MiniPickIconFile` - default icon for file.

* `MiniPickHeader` - headers in info buffer and previews.

* `MiniPickMatchCurrent` - current matched item.

* `MiniPickMatchMarked` - marked matched items.

* `MiniPickMatchRanges` - ranges matching query elements.

* `MiniPickNormal` - basic foreground/background highlighting.

* `MiniPickPreviewLine` - target line in preview.

* `MiniPickPreviewRegion` - target region in preview.

* `MiniPickPrompt` - prompt.

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

------------------------------------------------------------------------------

*MiniPick-events*

Events ~

To allow user customization and integration of external tools, certain |User|

autocommand events are triggered under common circumstances:

- `MiniPickStart` - just after picker has started.

- `MiniPickStop` - just before picker is stopped.

------------------------------------------------------------------------------

*MiniPick-overview*

# Overview ~

General idea is to take array of objects, display them with interactive

filter/sort/navigate/preview, and allow to choose one or more items.

## How to start a picker ~

- Use |MiniPick.start()| with `opts.source` defining |MiniPick-source|.

Example: `MiniPick.start({ source = { items = vim.fn.readdir('.') } })`

- Use any of |MiniPick.builtin| pickers directly.

Example: `MiniPick.builtin.files({ tool = 'git' })`

- Use |:Pick| command which uses customizable pickers from |MiniPick.registry|.

Example: `:Pick files tool='git'`

## User interface ~

UI consists from a single window capable of displaying three different views:

- "Main" - where current query matches are shown.

- "Preview" - preview of current item (toggle with `<Tab>`).

- "Info" - general info about picker and its state (toggle with `<S-Tab>`).

Current prompt is displayed (in Neovim>=0.9) at the top left of the window

border with vertical line indicating caret (current input position).

Bottom part of window border displays (in Neovim>=0.10) extra visual feedback:

- Left part is a picker name.

- Right part contains information in the format >

<current index in matches> | <match count> | <marked count> / <total count>

When picker is busy (like if there are no items yet set or matching is active)

window border changes color to be `MiniPickBorderBusy` after `config.delay.busy`

milliseconds of idle time.

## Life cycle ~

- Type characters to filter and sort matches. It uses |MiniPick.default_match()|

with `query` being an array of pressed characters.

Overview of how it matches:

- If query starts with `'`, the match is exact.

- If query starts with `^`, the match is exact at start.

- If query ends with `$`, the match is exact at end.

- If query starts with `*`, the match is forced to be fuzzy.

- Otherwise match is fuzzy.

- Sorting is done to first minimize match width and then match start.

Nothing more: no favoring certain places in string, etc.

- Type special keys to perform |MiniPick-actions|. Here are some basic ones:

- `<C-n>` / `<Down>` moves down; `<C-p>` / `<Up>` moves up.

- `<Left>` / `<Right>` moves prompt caret left / right.

- `<S-Tab>` toggles information window with all available mappings.

- `<Tab>` toggles preview.

- `<C-x>` / `<C-a>` toggles current / all item(s) as (un)marked.

- `<C-Space>` / `<M-Space>` makes all matches or marked items as new picker.

- `<CR>` / `<M-CR>` chooses current/marked item(s).

- `<Esc>` / `<C-c>` stops picker.

## Implementation details ~

- Any picker is non-blocking but waits to return the chosen item. Example:

`file = MiniPick.builtin.files()` allows other actions to be executed when

picker is shown while still assigning `file` with value of the chosen item.

------------------------------------------------------------------------------

*MiniPick-source*

Source is defined as a `source` field inside one of (in increasing priority):

- |MiniPick.config| - has global effect.

- |vim.b.minipick_config| - has buffer-local effect.

- `opts.source` in picker call - has effect for that particular call.

Example of source to choose from |arglist|: >

{ items = vim.fn.argv, name = 'Arglist' }

<

Note: this is mostly useful for writing pickers. Can safely skip if you

want to just use provided pickers.

*MiniPick-source.items*

# Items ~

`source.items` defines items to choose from. It should be one of the following:

- Array of objects which can have different types. Any type is allowed.

- `nil`. Picker waits for explicit |MiniPick.set_picker_items()| call.

- Callable returning any of the previous types. Will be called once on start.

*MiniPick-source.items-stritems*

Matching is done for items array based on the string representation of its

elements (here called "stritems"). For single item it is computed as follows:

- Callable is called once with output used in next steps.

- String item is used as is.

- String <text> field of table item is used (if present).

- Use output of |vim.inspect()|.

Example: >

items = { 'aaa.txt', { text = 'bbb' }, function() return 'ccc' end }

-- corresponding stritems are { 'aaa.txt', 'bbb', 'ccc' }

Default value is `nil`, assuming it always be supplied by the caller.

*MiniPick-source.items-common*

There are some recommendations for common item types in order for them to work

out of the box with |MiniPick.default_show()|, |MiniPick.default_preview()|,

|MiniPick.default_choose()|, |MiniPick.default_choose_marked()|:

- Path (file or directory). Use string or `path` field of a table. Path can

be either absolute or relative to the `source.cwd`.

Examples: `'aaa.txt'`, `{ path = 'aaa.txt' }`

- Buffer. Use buffer id as number, string, or `bufnr` / `buf_id` / `buf`

field of a table (any name is allowed).

Examples: `1`, `'1'`, `{ bufnr = 1 }`, `{ buf_id = 1 }`, `{ buf = 1 }`

- Line in file or buffer. Use table representation with `lnum` field with line

number (starting from 1). Files can use string in "<path>:<line>" format.

Examples: >

{ path = 'aaa.txt', lnum = 2 }, 'aaa.txt:2', { path = 'aaa.txt:2' },

{ bufnr = 1, lnum = 3 }

- Position in file or buffer. Use table representation with `lnum` and `col`

fields with line and column numbers (starting from 1). Files can use string

in "<path>:<line>:<col>" format.

Examples: >

{ path = 'aaa.txt', lnum = 2, col = 3 }, 'aaa.txt:2:3',

{ path = 'aaa.txt:2:3' }, { bufnr = 1, lnum = 3, col = 4 }

- Region in file or buffer. Use table representation with `lnum`, `col`,

`end_lnum`, `end_col` fields for start and end line/column. All numbers

start from 1, end line is inclusive, end column is exclusive.

This naming is similar to |getqflist()| and |diagnostic-structure|.

Examples: >

{ path = 'aaa.txt', lnum = 2, col = 3, end_lnum = 4, end_col = 5 },

{ bufnr = 1, lnum = 3, col = 4, end_lnum = 5, end_col = 6 }

Note: all table items will benefit from having `text` field for better matching.

*MiniPick-source.name*

# Name ~

`source.name` defines the name of the picker to be used for visual feedback.

Default value is "<No name>".

*MiniPick-source.cwd*

# Current working directory ~

`source.cwd` is a string defining the current working directory in which

picker operates. It should point to a valid actually present directory path.

This is a part of source to allow persistent way to use relative paths,

i.e. not depend on current directory being constant after picker start.

It also makes the |MiniPick.builtin.resume()| picker more robust.

Default value is |current-directory|.

*MiniPick-source.match*

# Match ~

`source.match` is a callable defining how stritems

(see |MiniPick-source.items-stritems|) are matched (filetered and sorted) based

on the query.

It will be called with the following arguments:

- `stritems` - all available stritems for current picker.

- `inds` - array of `stritems` indexes usually pointing at current matches.

It does point to current matches in the case of interactively appending

character at the end of the query. It assumes that matches for such bigger

query is a subset of previous matches (implementation can ignore it).

This can be utilized to increase performance by checking fewer stritems.

- `query` - array of strings. Usually (like is common case of user interactively

typing query) each string represents one character. However, any strings are

allowed, as query can be set with |MiniPick.set_picker_query()|.

It should either return array of match indexes for stritems elements matching

the query (synchronous) or explicitly use |MiniPick.set_picker_match_inds()|

to set them (may be asynchronous).

Notes:

- The result can be any array of `stritems` indexes, i.e. not necessarily

a subset of input `inds`.

- Both `stritems` and `query` depend on values of 'ignorecase' and 'smartcase'.

If query shows "ignore case" properties (only 'ignorecase' is set or both

'ignorecase' / 'smartcase' are set and query has only lowercase characters),

then `stritems` and `query` will have only lowercase characters.

This allows automatic support for case insensitive matching while being

faster and having simpler match function implementation.

- Writing custom `source.match` usually means also changing |MiniPick-source.show|

because it is used to highlight stritems parts actually matching the query.

Example of simple "exact" `match()` preserving initial order: >

local match_exact = function(stritems, inds, query)

local prompt_pattern = vim.pesc(table.concat(query))

local f = function(i) return stritems[i]:find(prompt_pattern) ~= nil end

return vim.tbl_filter(f, inds)

end

<

For non-blocking version see |MiniPick.poke_is_picker_active()|.

Default value is |MiniPick.default_match()|.

*MiniPick-source.show*

# Show ~

`source.show` is a callable defining how matched items are shown in the window.

It will be called with the following arguments:

- `buf_id` - identifier of the target buffer.

- `items_to_show` - array of actual items to be shown in `buf_id`. This is

a subset of currently matched items computed to fit in current window view.

- `query` - array of strings. Same as in `source.match`.

It should update buffer `buf_id` to visually represent `items_to_show`

__one item per line starting from line one__ (it shouldn't depend on

`options.content_from_bottom`). This also includes possible visualization

of which parts of stritem actually matched query.

Example (assuming string items; without highlighting): >

local show_prepend = function(buf_id, items_arr, query)

local lines = vim.tbl_map(function(x) return 'Item: ' .. x end, items_arr)

vim.api.nvim_buf_set_lines(buf_id, 0, -1, false, lines)

end

Default value is |MiniPick.default_show()|.

*MiniPick-source.preview*

# Preview ~

`source.preview` is a callable defining how item preview is done.

It will be called with the following arguments:

- `buf_id` - identifier of the target buffer. Note: for every separate instance

of item previewing new scratch buffer is be created.

- `item` - item to preview.

It should update buffer `buf_id` to visually represent `item`.

Example: >

local preview_inspect = function(buf_id, item)

local lines = vim.split(vim.inspect(item), '\n')

vim.api.nvim_buf_set_lines(buf_id, 0, -1, false, lines)

end

Default value is |MiniPick.default_preview()|.

*MiniPick-source.choose*

# Choose an item ~

`source.choose` is a callable defining what to do when an item is chosen.

It will be called with the following arguments:

- `item` - chosen item. Always non-`nil`.

It should perform any intended "choose" action for an item and return

a value indicating whether picker should continue (i.e. not stop):

`nil` and `false` will stop picker, other values will continue.

Notes:

- It is called when picker window is still current. Use `windows.target` value

from |MiniPick.get_picker_state()| output to do something with target window.

Example: >

local choose_file_continue = function(item)

if vim.fn.filereadable(item) == 0 then return end

vim.api.nvim_win_call(

MiniPick.get_picker_state().windows.main,

function() vim.cmd('edit ' .. item) end

)

return true

end

Default value is |MiniPick.default_choose()|.

*MiniPick-source.choose_marked*

# Choose marked items ~

`source.choose_marked` is a callable defining what to do when marked items

(see |MiniPick-actions-mark|) are chosen. Serves as a companion to

`source.choose` which can choose several items.

It will be called with the following arguments:

- `items_marked` - array of marked items. Can be empty.

It should perform any intended "choose" action for several items and return

a value indicating whether picker should continue (i.e. not stop):

`nil` and `false` will stop picker, other values will continue.

Notes:

- It is called when picker window is still current. Use `windows.target` value

from |MiniPick.get_picker_state()| output to do something with target window.

Example: >

local choose_marked_print = function(items) print(vim.inspect(items)) end

Default value is |MiniPick.default_choose_marked()|.

------------------------------------------------------------------------------

*MiniPick-actions*

When picker is active, `mappings` table defines a set of special keys which when

pressed will execute certain actions. Those can be of two types:

- Built-in: actions present in default `config.mappings`. Can be only overridden

with a different key.

- Custom: user defined actions. Should be a table with `char` and `func` fields.

# Built-in ~

*MiniPick-actions-caret*

## Caret ~

User can add character not only at query end, but more generally at caret.

- `mappings.caret_left` - move caret to left.

- `mappings.caret_right` - move caret to right.

*MiniPick-actions-choose*

## Choose ~

Choose is a fundamental action that actually implements the intent of

calling a picker, i.e. pick an item.

- `mappings.choose` - choose as is, i.e. apply `source.choose` for current item.

- `mappings.choose_in_split` - make horizontal split at target window, update

target window to the new split, and choose.

- `mappings.choose_in_tabpage` - same as `choose_in_split`, but create tabpage.

- `mappings.choose_in_vsplit` - same as `choose_in_split`, but split vertically.

- `mappings.choose_marked` - choose marked items as is, i.e.

apply `source.choose_marked` at current marked items.

*MiniPick-actions-delete*

## Delete ~

Delete actions are for deleting elements from query.

- `mappings.delete_char` - delete one character to the left.

- `mappings.delete_char_right` - delete one character to the right.

- `mappings.delete_left` - delete everything to the left (like |i_CTRL-U|).

- `mappings.delete_word` - delete word to the left (like |i_CTRL-W|).

*MiniPick-actions-mark*

## Mark ~

Marking is an action of adding certain items to a separate list which then can

be chosen with `mappings.choose_marked` (for example, sent to quickfix list).

This is a companion to a regular choosing which can pick only one item.

- `mappings.mark` - toggle marked/unmarked state of current item.

- `mappings.mark_all` - toggle marked/unmarked state (mark all if not all

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

Example of `execute` custom mapping: >

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

local pick = require('mini.pick')

pick.setup({ source = { show = pick.default_show } })

- Mappings to switch `toggle_{preview,info}` and `move_{up,down}`: >

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

mappings = {

toggle_info = '<C-k>',

toggle_preview = '<C-p>',

move_down = '<Tab>',

move_up = '<S-Tab>',

}

})

- Different window styles: >

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

:Pick files tool='git'

:Pick grep pattern='<cword>'

Parameters~

{config} `(table|nil)` Module config table. See |MiniPick.config|.

Usage~

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

------------------------------------------------------------------------------

*MiniPick.config*

`MiniPick.config`

Module config

Default values:

>

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,

},

}

<

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

------------------------------------------------------------------------------

*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})

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

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.

Return~

`(table|nil)` Depending of whether there is an active picker:

- If yes, `nil` is returned with |MiniPick.set_picker_match_inds()| used later.

- If no, array of `stritems` indexes matching the `query` (from best to worst).

------------------------------------------------------------------------------

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

Default: `false`. Note: |MiniPick.builtin| pickers showing file/directory

paths use `true` by default.

- <icons> `(table)` - table with fallback icons. 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.

One of "top", "center", "bottom". Default: "top".

------------------------------------------------------------------------------

*MiniPick.default_choose()*

`MiniPick.default_choose`({item})

Default choose

Choose item. Logic follows the rules in |MiniPick-source.items-common|:

- File and directory are called with |:edit| in the target window, possibly

followed by setting cursor at the start of line/position/region.

- Buffer is set as current in target window.

- Others have the output of |vim.inspect()| printed in Command line.

Implements default value for |MiniPick-source.choose|.

Parameters~

{item} `(any)` Item to choose.

------------------------------------------------------------------------------

*MiniPick.default_choose_marked()*

`MiniPick.default_choose_marked`({items}, {opts})

Default choose marked items

Choose marked items. Logic follows the rules in |MiniPick-source.items-common|:

- If among items there is at least one file or buffer, quickfix list is opened

with all file or buffer lines/positions/regions.

- Otherwise, picker's `source.choose` is called on the first item.

Implements default value for |MiniPick-source.choose_marked|.