*mini.input* Get user input

MIT License Copyright (c) 2026 Evgeni Chasnovski

------------------------------------------------------------------------------
                                                                     *MiniInput*
Features:

- Get user input with fully customizable key and view handling.

- Built-in configurable views as floating window, statusline/tabline/winbar,
  virtual line/text.

- Implementation is non-blocking but waits to return the input. It also works
  in any mode without requiring mode change. See |MiniInput-lifecycle|.

- |vim.ui.input()| implementation. To adjust, use |MiniInput.ui_input()| or
  save-restore `vim.ui.input` manually after calling |MiniInput.setup()|.

Sources with more details:
- |MiniInput.get()|
- |MiniInput.default_key()|
- |MiniInput-state|
- |MiniInput-examples|
- |MiniInput-in-other-plugins| (for plugin authors)

# Setup ~

This module needs a setup with `require('mini.input').setup({})` (replace `{}`
with your `config` table). It will create global Lua table `MiniInput` which
you can use for scripting or manually (with `:lua MiniInput.*`).

See |MiniInput.config| for `config` structure and default values.

You can override runtime config settings locally to buffer inside
`vim.b.miniinput_config` which should have same structure as
`MiniInput.config`. See |mini.nvim-buffer-local-config| for more details.

# Comparisons ~

- [folke/snacks.nvim#input](https://github.com/folke/snacks.nvim):
    - Both provide |vim.ui.input()| implementation.
    - Has asynchronous implementation (i.e. does not wait for user to finish
      input), while this module has synchronous non-blocking implementation.
    - Uses floating window and forced Insert mode. This module allows more
      view customizations and can be used in any mode without interruptions.

- |input()|:
    - Both are synchronous.
    - Both allow custom highlight and completion.
    - This module also allows supplying input scope and visibility,
      customizing keys and view.

# Highlight groups ~
*MiniInput-hl-groups*

- `MiniInputAdded`   - added text during completion navigation.
- `MiniInputBorder`  - border of a |MiniInput.gen_view.floatwin()| handler.
- `MiniInputCaret`   - caret symbol shown in a prompt area.
- `MiniInputHide`    - input is hidden, usually used instead of `MiniInputPrompt`.
- `MiniInputHint`    - hints shown during completion navigation.
- `MiniInputNormal`  - basic foreground/background.
- `MiniInputPrompt`  - input prompt (intention of the input).
- `MiniInputSpecial` - special keys (like literal `\t`, `\n`, etc.) in input.

# Using in other plugins ~
*MiniInput-in-other-plugins*

- Prefer using |vim.ui.input()| for more user coverage. Use |MiniInput.get()|
  only when getting input synchronously is absolutely necessary.

- Perform a `_G.MiniInput ~= nil` check before using any feature. This ensures
  that user explicitly set up the module.

------------------------------------------------------------------------------
                                                               *MiniInput-state*
Information about the state of the input. It is passed as a handler argument.
Use |MiniInput.get_state()| to get information about the current state (if any).
A table with the following fields:

- <caret> `(number)` - character (not byte) index at which to modify input.
  Should be from 1 (prepend input) to "input width plus 1" (append input).

- <complete> `(table|nil)` - information about active completion navigation.
  If present, it means that completion navigation is in action.
  Its fields describe the state of navigation:
    - <base> `(string)` - reference text to the left of caret at the start
      of completion. Used to compute candidates. Can be empty string.
    - <id> `(number)` - identifier of current completion item. Can be zero to
      mean that the base is shown. If not zero, must mean that a `items[id]`
      candidate is now shown to the left of caret as the part of the input.
    - <items> `(table)` - string array of completion candidates. May be empty.
      Are intended to fully replace <base>, so should contain it in any sense.
    - <method> `(string)` - completion method. Like `"default"`, `"history"`, etc.
      Can be `""` (empty string) to mean "default method of complete handler".

- <data> `(table)` - any information to be reused within the same input session.
  Note: handlers should not change fields that they don't "own".

- <errmsg> `(errmsg)` - first error message caught during input process.

- <highlight> `(table|nil)` - information about current input highlighting.
  If absent, the whole input is highlighted using `MiniInputNormal` group.
  Should be an array of highlight ranges. They might be not ordered, overlap,
  go outside of input width. It is up to the view handler to decide how to
  interpret them. See |MiniInput.state_to_chunks()| for a helper.
  Fields of a single highlight range:
    - <from> `(number)` - character index (one-indexed) of range start.
    - <to> `(number)` - character index (one-indexed) of range end (inclusive).
      Should not be smaller than <from>. Can be |math.huge|.
    - <hl> `(string)` - highlight group to use for highlighting.

- <input> `(string)` - current user input. Returned by |MiniInput.get()|.

- <opts> `(table)` - input options, same as in |MiniInput.get()|.

- <prompt> `(string)` - intention of the input. May be empty.

- <status> `(string)` - one of `"start"`, `"progress"`, `"accept"`, `"cancel"`.

------------------------------------------------------------------------------
                                                            *MiniInput-examples*
# General ~

## Initial input ~

Use `opts.init_keys` to imitate the initial state of the input: >lua

  MiniInput.get({ init_keys = { 'Default' } })
<
## Custom mappings ~

Override `handlers.key` in |MiniInput.config|: >lua

  local key_handler = function(state, key)
    -- <C-a> - move caret to start of line
    if key == '\1' then
      state.caret = 1
    -- <S-BS> - clear all input
    elseif key == vim.keycode('<S-BS>') then
      state.input, state.caret = '', 1
    else
      -- IMPORTANT: Fall back to processing as usual
      return MiniInput.default_key(state, key)
    end
  end

  require('mini.input').setup({ handlers = { key = key_handler } })
<
## Basic command line ~

An alternative |Command-line| with highlighting and completion: >lua

  -- Construct reusable `MiniInput.get()` options
  local cmdline_opts = { prompt = 'Command', scope = 'editor' }
  -- - Highlight using bundled Vim tree-sitter parser and default handler
  local highlight_vim = MiniInput.gen_highlight.treesitter('vim')
  local highlight_cmdline = function(state)
    state = highlight_vim(state) or state
    return MiniInput.default_highlight(state) or state
  end
  cmdline_opts.handlers = { highlight = highlight_cmdline }
  -- - Complete as if it is Command line input
  cmdline_opts.completion = 'cmdline'

  -- Create a mapping for `:`
  local input_cmdline = function()
    local cmd = MiniInput.get(cmdline_opts)
    if cmd ~= nil then vim.cmd(cmd) end
  end
  vim.keymap.set('n', ':', input_cmdline)
<
# Handlers ~

## Key ~

Perform custom actions based on arbitrary conditions: >lua

  local key_handler = function(state, key)
    -- Adjust prompt
    state.opts.prompt = state.opts.prompt:gsub('[?:]%s*$', '')

    -- Adjust scope
    if state.opts.prompt == 'Editor action' then
      state.opts.scope = 'editor'
    end

    -- Hide from view and history
    if state.opts.prompt:find('[Pp]assword') ~= nil then
      state.opts.hide = true
    end

    -- IMPORTANT: Process as usual
    state = MiniInput.default_key(state, key) or state

    -- Auto fill and accept
    if state.input == 'AF' then
      state.input, state.status = 'Autofilled input', 'accept'
    end
  end
  require('mini.input').setup({ handlers = { key = key_handler } })
<
## View ~

Show no view: >lua

  require('mini.input').setup({ handlers = { view = function() end } })
<
Compute initial style depending on scope: >lua

  local input = require('mini.input')
  local view_virtline = input.gen_view.virtual({ style = 'above' })
  local view_tabline = input.gen_view.uiline({ style = 'tabline' })
  local view_winbar = input.gen_view.uiline({ style = 'winbar' })
  local view_handler = function(state)
    -- NOTE: does not support interactive scope change
    local scope, view = state.opts.scope, view_tabline
    if scope == 'buffer' or scope == 'window' then view = view_winbar end
    if scope == 'cursor' or scope == 'line' then view = view_virtline end
    return view(state)
  end

  input.setup({ handlers = { view = view_handler } })
<
Change symbols for caret and hidden input: see |MiniInput.gen_view|.

------------------------------------------------------------------------------
                                                             *MiniInput.setup()*
                          `MiniInput.setup`({config})
Module setup

Parameters ~
{config} `(table|nil)` Module config table. See |MiniInput.config|.

Usage ~
>lua
  require('mini.input').setup() -- use default config
  -- OR
  require('mini.input').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
                                                              *MiniInput.config*
                               `MiniInput.config`
Defaults ~
>lua
  MiniInput.config = {
    -- Functions that control input lifecycle
    handlers = {
      -- Compute completion candidates
      complete = nil,

      -- Compute highlighting of current input
      highlight = nil,

      -- Handle input start, every key press, and input end
      key = nil,

      -- Show current input state
      view = nil,
    },

    -- Default input scope: cursor/line/buffer/window/tabpage/editor/project
    scope = 'editor',
  }
<
# Handlers ~
*MiniInput.config.handlers*

`config.handlers` defines functions that are applied during |MiniInput-lifecycle|.
Every handler takes |MiniInput-state| as the first argument and is expected to
either modify it in place or return a new state table.

Use |MiniInput.apply_handler()| to apply a handler for a given |MiniInput-state|.
They can be set up as part of the config (will be used as default) or passed
directly as a part of |MiniInput.get()| call.

## Complete ~

`handlers.complete` is a handler intended to compute completion suggestions.
Takes |MiniInput-state| and `method` as arguments and is expected to modify
<complete> field. Default: |MiniInput.default_complete()|.

Only `complete.base` and `complete.items` are expected to be set by a complete
handler. Setting and modifying other fields (`complete.id` and `complete.method`)
is done in other handlers and as part of |MiniInput.apply_handler()|. Actually
showing completion information is up to the view handler.

This handler is usually applied manually inside a key handler via using
`MiniInput.apply_handler(state, 'complete', method)`. Like, for example,
in |MiniInput.default_key()| after <Tab> or <Up>.

Here is an example of a simple demo complete handler: >lua

  local complete_handler = function(state, method)
    if method == '' or method == 'xy' then
      local text = vim.fn.strcharpart(state.input, 0, state.caret - 1)
      local base = text:match('%S*$')
      state.complete = { base = base, items = { base .. 'x', base .. 'y' } }
      return
    end
    return MiniInput.default_complete(state, method)
  end

  require('mini.input').setup({ handlers = { complete = complete_handler } })
<
## Key ~

`handlers.key` is a handler intended to process every user key press.
Takes |MiniInput-state| and `key` as arguments. Argument `key` represents a key
that needs to be processed: a string if from the user input or `nil` if input
needs to be set up, refreshed, or torn down. Default: |MiniInput.default_key()|.

A string `key` can be two kinds:
- Forwarded from |getcharstr()| verbatim as a result of interactive key press.
  Meaning it will be in escaped form and not as a |key-notation|: i.e. `"\r"`
  and not `"<CR>"`. It also means that all kinds of combos (`<M-...>`, `<C-S-...>`),
  mouse clicks, and wheel scrolls are also forwarded to key handler.
- Any string as part of `opts.init_keys` in |MiniInput.get()|. If a string
  doesn't look like it came from |getcharstr()|, it is usually a good idea
  to insert this string at caret as is.

The suggested overall approach for custom key handler is "if `key` is special -
act on it, if can be used in the input - insert at caret, ignore otherwise".
It is also important to never change the current mode (as in |vim-modes|)
for |MiniInput.get()| to work as expected.

Here is an example of a basic custom key handler: >lua

  local custom_actions = {
    [vim.keycode('<Left>')] = function(state)
      state.caret = math.max(state.caret - 1, 1)
    end,
    [vim.keycode('<Right>')] = function(state)
      local input_width = vim.fn.strchars(state.input)
      state.caret = math.min(state.caret + 1, input_width + 1)
    end,
    [vim.keycode('<CR>')] = function(state) state.status = 'accept' end,
    [vim.keycode('<Esc>')] = function(state) state.status = 'cancel' end,
  }

  local key_handler = function(state, key)
    -- No need for special setup or teardown
    if key == nil then return end

    -- If key is special - act on it
    if custom_actions[key] then return custom_actions[key](state) end

    -- If key is not printable - do nothing
    if vim.fn.match(key, '^[[:print:]]\\+$') < 0 then return end

    -- Insert at caret
    local caret, input = state.caret, state.input
    local before_caret = vim.fn.strcharpart(input, 0, caret - 1)
    local after_caret = vim.fn.strcharpart(input, caret - 1)
    state.input = before_caret .. key .. after_caret
    state.caret = caret + vim.fn.strchars(key)

    -- No need to return anything as `state` is modified in place
  end

  require('mini.input').setup({ handlers = { key = key_handler } })
<
## Highlight ~

`handlers.highlight` is a handler intended to compute and set highlight info
about the current input. Takes |MiniInput-state| as the only argument and is
expected to modify <highlight> field. Default: |MiniInput.default_highlight()|.

See |MiniInput.gen_highlight| for built-in highlight handler generators.

It is usually a good idea to append to a <highlight> if it already exists.
This makes it work more robustly when combining highlights.

Here is a basic example that highlights all letters `a`: >lua

  local hl_handler = function(state)
    local highlight = {}
    for col in string.gmatch(state.input, '()a') do
      -- NOTE: range should use character (not byte) indexes
      local char_col = vim.fn.charidx(state.input, col)
      local range = { from = char_col, to = char_col, hl = 'Special' }
      table.insert(highlight, range)
    end

    state.highlight = vim.list_extend(state.highlight or {}, highlight)

    -- Possibly also apply default handler afterwards
    return MiniInput.default_highlight(state)
  end

  require('mini.input').setup({ handlers = { highlight = hl_handler } })
<
## View ~

`handlers.view` is a handler intended to show the input state on screen.
Takes |MiniInput-state| as the only argument. Default: |MiniInput.default_view()|.

See |MiniInput.gen_view| for built-in view handler generators.

Example of view that uses |nvim_echo()| to show the input: >lua

  local view_handler = function(state)
    -- Process start and end of the input lifecycle
    local is_start = state.status == 'start'
    local is_end = state.status == 'accept' or state.status == 'cancel'
    if is_start or is_end then vim.cmd('mode') end
    if is_end then return end

    -- Compute text-hl chunks that fit and show them
    local chunks = MiniInput.state_to_chunks(state, vim.v.echospace)
    vim.api.nvim_echo(chunks, false, {})
  end

  require('mini.input').setup({ handlers = { view = view_handler } })
<
# Scope ~

`config.scope` is a string that defines an input scope. It is meant as an extra
information for handlers to tweak their behavior (`view` style, etc.). Possible
values: `"cursor"`, `"line"`, `"buffer"`, `"window"`, `"tabpage"`, `"editor"`, `"project"`.

------------------------------------------------------------------------------
                                                               *MiniInput.get()*
                            `MiniInput.get`({opts})
Get input from the user

# Lifecycle ~
*MiniInput-lifecycle*

This module implements custom lifecycle to interact with the user. It starts
when calling |MiniInput.get()| and ends when a value is returned.
Only one active input is allowed simultaneously.

The basic cycle unit is a step that processes a `key` (string or `nil`). It is
done by calling relevant handlers in order: key handler with `key` as a second
argument, highlight handler, view handler. |MiniInput.apply_handler()| is used
to apply each handler and the output of one is used as the input for the next.

During a step some state fields are automatically removed:
- <highlight> is removed before applying a key handler to always have the most
  up to date highlighting.
- <complete> is removed if it was not changed after applying a key handler but
  something else in the state besides <highlight> did change. This is meant as
  an automatic stop of completion when it is not advancing.

If a step sets an ending state <status> (i.e. `"accept"` or `"cancel"`), the input
is finished by extra finishing step (see below).

The order of operations is as follows:
- Create initial |MiniInput-state| based on the input `opts`, with defaults
  inferred from |MiniInput.config|, and `vim.b.miniinput_config`.
- Set <status> to `"start"`.
- Advance one step with `key=nil`. This is meant as a "setup" step for handlers.
- Set <status> to `"progress"`.
- Process `opts.init_keys` one item per step with `key` set to the string item.
- Wait for user to press a key (via |getcharstr()|). The key string (in escaped
  form and not as a |key-notation|; i.e. `"\r"` and not `"<CR>"`) is then used
  to advance a step. Note: <C-c> is hard coded to cancel the input.
- Repeat previous step until the ending <status> (`"accept"` or `"cancel"`).
- Finish the input:
    - Perform a "teardown" step with `key=nil`.
    - If <errmsg> is set, throw an |error()|.
    - If input is accepted (even if empty) and not hidden, add <input> to
      the history. Get the whole history with |MiniInput.get_history()|.
    - Return <input> if <status> is `"accept"`, `nil` otherwise.

Parameters ~
{opts} `(table|nil)` Options. Possible fields:
  - <completion> `(string)` - completion method. Default: `''` to use default
    completion method of the `complete` handler.
  - <handlers> `(table)` - same as in |MiniInput.config.handlers|, used only for
    the duration of the current input.
  - <hide> `(boolean)` - whether input should be hidden. Default: `false`.
    Note: this does not guarantee a total security of the input, only that
    the typed characters are expected to not be shown on screen and not added
    to the history. If set:
      - The `view` handler is expected to not directly show current input.
        Like replace characters with pre-defined string or fully not show.
      - The `complete` and `highlight` handlers are not called.
      - Accepted input will not be added to the history.
  - <init_keys> `(table)` - array of string keys that are emulated before asking
    for the user input. Using values that can be an output of |getcharstr()|
    should be preferred, but a key handler should work with any string.
    Default: `{}`.
  - <prompt> `(string)` - intention of the input, same as in |input()|.
    Default: `"Input"`.
  - <scope> `(string)` - same as in |MiniInput.config|. Default: the value from
    `MiniInput.config` with some hard coded exceptions (on Neovim<0.12.3):
      - |vim.lsp.buf.rename()| will use `"cursor"` if no `new_name` is supplied.

Return ~
`(string|nil)` User input (from the <input> state field) if accepted, even if
  empty. `nil` if canceled or there was an active input.

Usage ~
>lua
  local input = MiniInput.get({
    -- Intention of the input
    prompt = 'New value',
    -- The input is for something at cursor
    scope = 'cursor',
    -- Emulate pressing `a`, `<BS>`, and `b`
    init_keys = { 'a', vim.keycode('<BS>'), 'b' },
  })
<
------------------------------------------------------------------------------
                                                          *MiniInput.ui_input()*
                   `MiniInput.ui_input`({opts}, {on_confirm})
A |vim.ui.input()| implementation

Function which can be used to directly override |vim.ui.input()| to use this
module functionality. Set automatically in |MiniInput.setup()|.

Usage ~
To preserve original `vim.ui.input()`: >lua

  local ui_input_orig = vim.ui.input
  require('mini.input').setup()
  vim.ui.input = ui_input_orig
<
------------------------------------------------------------------------------
                                                         *MiniInput.get_state()*
                            `MiniInput.get_state`()
Get current input state

Return ~
`(table|nil)` Current |MiniInput-state| if input is active, `nil` otherwise. Notes:
  - For hidden input (`state.opts.hide=true`), both <caret> and <input> are `nil`
    to actually hide the input.

------------------------------------------------------------------------------
                                                       *MiniInput.get_history()*
                           `MiniInput.get_history`()
Get input history

Return ~
`(table)` Array with data about all previous non-hidden inputs (from earliest
  to latest). Each element is a table with the following fields:
  - <cwd> `(string)` - |current-directory| at the time of input's end.
  - <input> `(string)` - input result.
  - <prompt> `(string)` - `opts.prompt` supplied in |MiniInput.get()|.
  - <scope> `(string)` - `opts.scope` supplied in |MiniInput.get()|.

------------------------------------------------------------------------------
                                                       *MiniInput.set_history()*
                       `MiniInput.set_history`({history})
Set input history

Parameters ~
{history} `(table)` Array describing all previous inputs. Same structure
  as |MiniInput.get_history()| output.

------------------------------------------------------------------------------
                                                           *MiniInput.refresh()*
                             `MiniInput.refresh`()
Refresh active input

Performs one step of |MiniInput-lifecycle| with `key=nil`.

------------------------------------------------------------------------------
                                                       *MiniInput.gen_highlight*
                           `MiniInput.gen_highlight`
Highlight generators

This is a table with function elements. Call to actually get a view function.

------------------------------------------------------------------------------
                                          *MiniInput.gen_highlight.treesitter()*
                  `MiniInput.gen_highlight.treesitter`({lang})
Highlight with tree-sitter

Parameters ~
{lang} `(string)` A language of tree-sitter parser to use.

Return ~
`(function)` A highlight handler. Seem |MiniInput.config.handlers|.

------------------------------------------------------------------------------
                                                            *MiniInput.gen_view*
                              `MiniInput.gen_view`
View generators

This is a table with function elements. Call to actually get a view function.

Each element accepts <style> option which fine tunes the input view.
With default key handler (|MiniInput.default_key()|) it can be adjusted
interactively by pressing <C-s>.

Each element also accepts <to_chunks> option. It is a function that takes
a |MiniInput-state| and `max_width` arguments and returns an array of `{ text, hl }`
chunks that fit into `max_width` display width (as in |strdisplaywidth()|).

This is a way to adjust how input is shown. Like caret/hide symbols, etc.
By default uses |MiniInput.state_to_chunks()|, which also means:
- All control characters (like literal `\t`, `\n`, etc.) will be translated
  via |keytrans()|.

Example: >lua

  local input = require('mini.input')

  -- Adjust how state is converted to text-hl chunks
  local to_chunks_opts = {
    symbol_caret = '_',
    symbol_hide = '*',
    -- Do not include prompt and hint in `floatwin` handler
    include_prompt = false,
    include_hint = false,
  }
  local to_chunks = function(state, max_width)
    return MiniInput.state_to_chunks(state, max_width, to_chunks_opts)
  end

  -- Supply custom `to_chunks` as an option
  local view_opts = { to_chunks = to_chunks }
  input.setup({ handlers = { view = input.gen_view.floatwin(view_opts) } })
<
------------------------------------------------------------------------------
                                                 *MiniInput.gen_view.floatwin()*
                     `MiniInput.gen_view.floatwin`({opts})
Floating window view

Show input inside a floating window. Prompt and completion hints are shown
in title and footer.

Window position and dimensions are computed based on state's <scope> and
`opts.style`:
- `scope="cursor"` is shown near the cursor. For example, `style="BL"` will
  have bottom left corner at nearest top right cell relative to the cursor.
- `scope="line"` is shown near the current line. For example, `style="BL"` will
  have bottom left corner at left side above the line.
- `scope="buffer"` and `scope="window"` will be shown relative to the current
  window. For example, `style="BL"` will be shown in the bottom left corner.
- `scope="tabpage"`, `scope="editor"`, `scope="project"` will be shown relative to
  the overall Neovim instance. For example, `style="BL"` will be shown in the
  bottom left corner.

Identifiers of floating window and its buffer are stored as `floatwin_win_id`
and `floatwin_buf_id` in |MiniInput-state| <data> field. Floating window is
not focused and cursor position is not the same as caret position.

Parameters ~
{opts} `(table|nil)` Options. Possible fields:
  - <adjust_config> `(function)` - function to adjust default config. Will be
    called with two arguments: current |MiniInput-state| and a window config
    (always with `relative="editor"` and `anchor="NW"`) computed based
    on `opts.style`. Should return an adjusted window config.
    Default: `function(state, config) return config end`.

  - <style> `(string)` - a two character description of how to show the window.
    Default: `"BL"`.

      First character describes vertical position:
      - `"T"` - top window border will be at scope's reference top border.
      - `"M"` - middle between top and bottom window borders will be at the
        middle of scope's reference top and bottom borders.
      - `"B"` - bottom window border will be at scope's reference bottom border.

      Second character describes horizontal position:
      - `"L"` - left window border will be at scope's reference left border.
      - `"M"` - middle between left and right window borders will be at the
        middle of scope's reference left and right borders.
      - `"R"` - right window border will be at scope's reference right border.

  - <to_chunks> `(function)` - a function that takes |MiniInput-state| and
    `max_width` arguments and returns an array of `{ text, hl }` chunks that fit
    into `max_width` display width. See |MiniInput.state_to_chunks()|.

Usage ~
>lua
  local input = require('mini.input')

  -- Use border different from 'winborder'
  local adjust_config = function(_, config)
    config.border = 'double'
    return config
  end

  -- Choose initial style based on the scope
  local floatwin = input.gen_view.floatwin
  local view_tm = floatwin({ style = 'TM', adjust_config = adjust_config })
  local view_bl = floatwin({ style = 'BL', adjust_config = adjust_config })
  local view_handler = function(state)
    local scope, view = state.opts.scope, view_tm
    if scope == 'cursor' or scope == 'line' then view = view_bl end
    return view(state)
  end

  input.setup({ handlers = { view = view_handler } })
<
------------------------------------------------------------------------------
                                                   *MiniInput.gen_view.uiline()*
                      `MiniInput.gen_view.uiline`({opts})
UI line (statusline, tabline, winbar) view

Parameters ~
{opts} `(table|nil)` Options. Possible fields:
  - <style> `(string)` - which UI line to use. One of `"statusline"`,
    `"tabline"`, `"winbar"`. Default: `"statusline"`.

  - <to_chunks> `(function)` - a function that takes |MiniInput-state| and
    `max_width` arguments and returns an array of `{ text, hl }` chunks that fit
    into `max_width` display width. See |MiniInput.state_to_chunks()|.

Usage ~
>lua
  local input = require('mini.input')

  -- Choose initial style based on the scope
  local view_tabline = input.gen_view.uiline({ style = 'tabline' })
  local view_winbar = input.gen_view.uiline({ style = 'winbar' })
  local view_handler = function(state)
    local scope, view = state.opts.scope, view_winbar
    if scope == 'tabpage' or scope == 'editor' or scope == 'project' then
      view = view_tabline
    end
    return view(state)
  end

  input.setup({ handlers = { view = view_handler } })
<
------------------------------------------------------------------------------
                                                  *MiniInput.gen_view.virtual()*
                      `MiniInput.gen_view.virtual`({opts})
Virtual (line, text) view

Parameters ~
{opts} `(table|nil)` Options. Possible fields:
  - <style> `(string)` - how to display virtual text. One of `"above"`, `"below"`,
    `"inline"`. Default: `"above"`.

  - <to_chunks> `(function)` - a function that takes |MiniInput-state| and
    `max_width` arguments and returns an array of `{ text, hl }` chunks that fit
    into `max_width` display width. See |MiniInput.state_to_chunks()|.

Usage ~
>lua
  -- Choose different initial style
  local input = require('mini.input')
  local view_handler = input.gen_view.virtual({ style = 'inline' })
  input.setup({ handlers = { view = view_handler } })
<
------------------------------------------------------------------------------
                                                       *MiniInput.default_key()*
                `MiniInput.default_key`({state}, {key}, {opts})
Default key handler

Emulates most of |Command-line-mode| editing (|cmdline-editing|):

- Accept: <CR>. To insert literal newline, type `<C-j>`.

- Cancel: <Esc> or <C-c>.

- Move caret:
    - <Left>, <Right> - one character to left / right.
    - <M-h>, <M-l> - one character to left / right.
    - <S-Left>, <S-Right> - one word to left / right.
    - <C-b>, <C-e> (if no completion) - to start / end of input.
    - <Home>, <End> - to start / end of input.

- Delete:
    - <BS> / <C-h> - to caret's left. If `opts.autopair` is enabled, also delete
      a character to caret's right if it formed a respected character pair.
      See "Autopair".
    - <Del> - at caret.
    - <C-u> - from start to caret. As |c_CTRL-U|.
    - <C-w> - contiguous keyword or non-keyword to caret's left. As |c_CTRL-W|.

- Insert at caret:
    - <C-k> - digraph based on the next two pressed keys. As |c_CTRL-K|.
    - <C-r> - content of a register. As |c_CTRL-R| including support for
      special <C-a>, <C-f>, <C-l>, <C-w> keys for a register.
    - <C-v>, <C-q> - next key literally. As |c_CTRL-V| and |i_CTRL-V_digit|
      (all digits must be typed in full or stopped with <C-c>).
    - Pasting from system |clipboard| is supported for "non-streaming" paste (as
      described in |vim.paste()|).

- Autopair (if `opts.autopair` is set) is similar to |mini.pairs|:
    - Opening characters `(`, `[`, `{` always insert a `()`, `[]`, `{}` pair and places
      caret inside of it.
    - Closing characters `)`, `]`, `}` move caret to the right if there is the same
      character to the right.
    - Closeopen characters single+double quotes and backtick perform "close"
      action if possible and "open" action if not.
    - In all cases press <C-v> before special character to insert it verbatim.

- Completion:
    - <Tab>, <S-Tab> - start with `state.opts.completion` method if not active
      and advance through active completion (i.e. replace currently displayed
      at caret item with the next one).
      Note: type `<C-v><Tab>` to insert literal `\t`.
    - <C-n>, <C-p>, <Up>, <Down> - start with `"history"` method if not active
      and advance through active completion.
    - <C-e> - cancel and return to initial input and caret.
    - <C-y> - accept current candidate. Note: it will also be accepted after
      any key that doesn't advance completion.

- Miscellaneous:
    - <C-o> - change scope of the input. Cycles through all available ones.
    - <C-s> - change view style. Works only with |MiniInput.gen_view| view
      handlers. Cycles through all available ones.
    - <C-x> - toggle hide/unhide of the input.

- Special keys (combo, mouse, but not whitespace) not listed above - ignored.
  Anything else (even more than a single character) - inserted at caret.

Parameters ~
{state} `(table)` Current |MiniInput-state|.
{key} `(string|nil)` A key to process. Should be escaped (`"\r"`, not `"<CR>"`).
  See |vim.keycode()|.
{opts} `(table|nil)` Options. Possible fields:
  - <autopair> `(boolean)` - whether perform add autopair. Default: `false`.

------------------------------------------------------------------------------
                                                 *MiniInput.default_highlight()*
                     `MiniInput.default_highlight`({state})
Default highlight handler

During active completion highlights added (computed via |matchfuzzy()|)
characters with `MiniInputAdded` group.

Parameters ~
{state} `(table)` Current |MiniInput-state|.

------------------------------------------------------------------------------
                                                      *MiniInput.default_view()*
                       `MiniInput.default_view`({state})
Default view handler

Same as |MiniInput.gen_view.floatwin()| with default options.

Parameters ~
{state} `(table)` Current |MiniInput-state|.

------------------------------------------------------------------------------
                                                  *MiniInput.default_complete()*
            `MiniInput.default_complete`({state}, {method}, {opts})
Default complete handler

Supported methods:
- `""` (default) - complete with buffer keywords (|'iskeyword'|) that match
  a keyword at caret's left.
- `"history"` - complete with |MiniInput.get_history()| inputs that have current
  input to caret's left as a prefix. If `opts.precise_history`, only use history
  entries that have all info fields same as the current state. Orders from
  earliest to latest. To initiate with the latest history match, press
  <Up> or <C-p> with default key handler.
- `"cmdline"` - treat input as |Command-line| text and show completions at caret.
  Note: as there is no |getcmdcomplpat()| variant to use outside of Command-line
  mode, the base is inferred from |getcompletion()| output as the widest text to
  caret's left that matches all candidates: fuzzily if |'wildoptions'| contains
  `fuzzy`, as a prefix otherwise (respecting |'ignorecase'| and |'smartcase'|).
  If none - use empty string. There are limitations, but this is good enough.
- Every method supported by |getcompletion()|. Base is computed as the keyword
  at caret's left.

Parameters ~
{state} `(table)` Current |MiniInput-state|.
{method} `(string)` Completion method.
{opts} `(table|nil)` Options. Possible fields:
  - <precise_history> `(boolean)` - whether for `method='history'` try to match
    only entries that have <cwd> as |current-directory|, same <scope> and
    <prompt> as in current state. Default: `true`.

Usage ~
>lua
  -- Do not match history precisely
  local complete_opts = { precise_history = false }
  local complete_handler = function(state, method)
    return MiniInput.default_complete(state, method, complete_opts)
  end
  require('mini.input').setup({ handlers = { complete = complete_handler } })
<
------------------------------------------------------------------------------
                                                   *MiniInput.state_to_chunks()*
           `MiniInput.state_to_chunks`({state}, {max_width}, {opts})
Convert state into text-hl chunks

- Treat `state.highlight` elements in increasing priority, i.e. later ones
  are placed "on top" of the previous ones if they overlap.
- Uses |MiniInput-hl-groups|.
- Multiline input (i.e. with newline characters `\n`) is shown as a single line.
- Treats `max_width` as display width (|strdisplaywidth()|).
- Truncates output chunks trying to center the caret.

Parameters ~
{state} `(table)` A |MiniInput-state|.
{max_width} `(number|nil)` Maximum allowed display width. Can be |math.huge|.
{opts} `(table|nil)` Options. Possible fields:
  - <keytrans> `(boolean)` - whether to translate control characters (escaped
    version of `<C-...>`). Default: `true`.
  - <include_prompt> `(boolean)` - whether to start chunks with state prompt.
    Default: `true`.
  - <include_hint> `(boolean)` - whether to show complete hint to caret's right.
    Default: `true`.
  - <symbol_caret> `(string)` - string to use for caret. Default: `"▏"`.
  - <symbol_hide> `(string)` - string to use for each input character when
    input is hidden. Default: `"•"`.

Return ~
`(table)` An array of text-hl chunks that fit `max_width` display width.

------------------------------------------------------------------------------
                                                     *MiniInput.apply_handler()*
               `MiniInput.apply_handler`({state}, {name}, {arg})
Apply state's handler

Given |MiniInput-state|, apply its handler (from `state.opts.handlers`) and
return the modified state.

Notes:
- Nothing is done for highlight and complete handlers when input is hidden.
- Applying complete handler ensures that <complete> state field has <id> set
  to 0 (as it assumes new completion) and <method> to the input argument
  (empty string if there was no argument).
- Error during handler application is stored as <errmsg> field of output state
  if there is an active input. It is propagated via |error()| otherwise.
- Handler output is validated to be a valid |MiniInput-state|. If not - return
  input `state`. Note: it still could be changed if handler modified in place.

Parameters ~
{state} `(table)` A |MiniInput-state|.
{name} `(string)` Valid handler name.
{arg} `(any)` Extra handler argument: like `key` for key handler and `method`
  for complete handler.

Return ~
`(table)` A |MiniInput-state| as a result of applied handler. If handler returned
  nothing, the input `state` is returned (assumes it was modified in place).


 vim:tw=78:ts=8:noet:ft=help:norl: