liuchengxu/vim-clap

Vim-clap is a modern generic performant finder using the floating_win of neovim or popup of vim, powered by an external backend written in Rust.

>>>> More screenshots

Table of Contents

• Features
• Caveats
• Requirement
• Installation
  • vim-plug
• Usage
  • Commands
    • Providers
  • Global variables
  • Keybindings
    • Insert mode
    • NeoVim only
      • Normal mode
      • Cmdline mode
  • Execute some code during the process
  • Change highlights
  • Search syntax
    • Fzf search syntax
    • Extended search syntax
  • Config file
• How to define your own provider
• Disable auto-completion plugin in clap input window
• Contribution
• Credit
• License

Features

• Pure vimscript.
  • Pin to some early version of vim-clap if you prefer the pure vimscript plugin.
• Work out of the box, without any extra dependency.
  • The Rust binary is now a must-have to make everything work smoothly.
• Blazingly fast thanks to the powerful Rust backend.
• Consistent command interface with clap-rs/clap
• Support writing new providers in both Vimscript and Rust.
• Support the search syntax borrowed from fzf and more.
• Flexible UI layout.
• Support searching by multiple providers simultaneously.

Caveats

• Vim-clap is in a very early stage, breaking changes and bugs are expected.

• The Windows support is not fully tested. The providers without using any system related command should work smoothly, that is to say, most sync providers are just able to work. Please create an issue if you run into any error in Windows. And any help would be appreciated.

• Although a lot of effort has been made to unify the behavior of vim-clap between vim and neovim, and most part works in the same way, it just can't be exactly the same, for floating_win and popup are actually two different things anyway.

Requirement

• Vim: :echo has('patch-8.1.2114').
• NeoVim: :echo has('nvim-0.4.2').

Installation

vim-plug

" Build the Rust binary if `cargo` exists on your system.
Plug 'liuchengxu/vim-clap', { 'do': ':Clap install-binary' }

" The bang version will try to download the prebuilt binary if `cargo` does not exist.
Plug 'liuchengxu/vim-clap', { 'do': ':Clap install-binary!' }

" `:Clap install-binary[!]` will always try to compile the binary locally.
" If you do care about the disk used for the compilation, use the way of force download,
" which will directly download the prebuilt binary even if `cargo` is available.
Plug 'liuchengxu/vim-clap', { 'do': { -> clap#installer#force_download() } }

" `:Clap install-binary[!]` will run using the terminal feature which is inherently async.
" If you don't want that and hope to run the hook synchorously:
Plug 'liuchengxu/vim-clap', { 'do': has('win32') ? 'cargo build --release' : 'make' }

It's recommended to install the Rust binary automatically via the do hook. If that does not work for you, please refer to INSTALL.md for installing it manually.

Usage

Vim-clap is utterly easy to use, just type, press Ctrl-J/K to locate the wanted entry, and press Enter to apply and exit. The default settings should work well for most people in most cases, but it's absolutely hackable too.

Commands

The paradigm is Clap [provider_id_or_alias] {provider_args}, where the provider_id_or_alias is obviously either the name or alias of provider. Technically the provider_id can be anything that can be used a key of a Dict, but I recommend you using an identifier like name as the provider id, and use the alias rule if you prefer a special name.

Providers

• The command with a superscript ! means that it is not yet implemented or not tested.
• The command with a superscript + means that it supports multi-selection via Tab.
• :Clap grep
  • Use :Clap grep --query=<cword> to grep the word under cursor.
  • Use :Clap grep --query=@visual to grep the visual selection.
  • cwd will be searched by default, specify the extra paths in the end to search multiple directories.
    • :Clap grep --path ~/.vim/plugged/ale with cwd is ~/.vim/plugged/vim-clap will both search vim-clap and ale.

Send a pull request if you want to get your provider listed here.

Global variables

• g:clap_layout: Dict, { 'width': '67%', 'height': '33%', 'row': '33%', 'col': '17%' } by default. This variable controls the size and position of vim-clap window. By default, the vim-clap window is placed relative to the currently active window. To make it relative to the whole editor modify this variable as shown below:

  let g:clap_layout = { 'relative': 'editor' }

• g:clap_open_action: Dict, { 'ctrl-t': 'tab split', 'ctrl-x': 'split', 'ctrl-v': 'vsplit' }, extra key bindings for opening the selected file in a different way. NOTE: do not define a key binding which is conflicted with the other default bindings of vim-clap, and only ctrl-* is supported for now.

• g:clap_provider_alias: Dict, if you don't want to invoke some clap provider by its id(name), as it's too long or somehow, you can add an alias for that provider.

  " The provider name is `command_history`, with the following alias config,
  " now you can call it via both `:Clap command_history` and `:Clap hist:`.
  let g:clap_provider_alias = {'hist:': 'command_history'}

• g:clap_selected_sign: Dict, { 'text': ' >', 'texthl': "ClapSelectedSign", "linehl": "ClapSelected"}.

• g:clap_current_selection_sign: Dict, { 'text': '>>', 'texthl': "ClapCurrentSelectionSign", "linehl": "ClapCurrentSelection"}.

• g:clap_no_matches_msg: String, 'NO MATCHES FOUND', message to show when there is no matches found.

• g:clap_popup_input_delay: Number, 200ms by default, delay for actually responsing to the input, vim only.

• g:clap_disable_run_rooter: Bool, v:false, vim-clap by default will try to run from the project root by changing cwd temporarily. Set it to v:true to run from the origin cwd. The project root here means the git base directory. Create an issue if you want to see more support about the project root.

The option naming convention for provider is g:clap_provider_{provider_id}_{opt}.

• g:clap_provider_grep_blink: [2, 100] by default, blink 2 times with 100ms timeout when jumping the result. Set it to [0, 0] to disable the blink.

• g:clap_provider_grep_opts: An empty string by default, allows you to enable flags such as '--hidden -g "!.git/"'.

See :help clap-options for more information.

Keybindings

Insert mode

• Use Ctrl-j/Down or Ctrl-k/Up to navigate the result list up and down linewise.
• Use PageDown/PageUp to scroll the result list down and up.
• Use Ctrl-a/Home to go to the start of the input.
• Use Ctrl-e/End to go to the end of the input.
• Use Ctrl-c, Ctrl-g, Ctrl-[ or Esc(vim) to exit.
• Use Ctrl-h/BS to delete previous character.
• Use Ctrl-d to delete next character.
• Use Ctrl-b to move cursor left one character.
• Use Ctrl-f to move cursor right one character.
• Use Ctrl-n for next input in the history.
• Use Ctrl-p for previous input in the history.
• Use Enter to select the entry and exit.
  • Use Enter to expand the directory or edit the file for :Clap filer.
• By default Alt-u does nothing.
  • Use Alt-u to go up one directory in :Clap filer.
• Use Tab to select multiple entries and open them using the quickfix window.(Need the provider has sink* support)
  • Use Tab to expand the directory for :Clap filer.
• Use Ctrl-t or Ctrl-x, Ctrl-v to open the selected entry in a new tab or a new split.
• Use Ctrl-u to clear inputs.
• Use Ctrl-l to launch the whole provider list panel for invoking another provider at any time.
• Use Shift-Tab to invoke the action dialog(vim only).
• Use Shift-up and Shift-down to scroll the preview.

NeoVim only

Normal mode

• Use j/Down or k/Up to navigate the result list up and down linewise.
• By default Alt-u does nothing.
  • Use Alt-u to go up one directory in :Clap filer.
• Use Ctrl-c, Ctrl-g or Esc to exit.
• Use Ctrl-d/Ctrl-u/PageDown/PageUp to scroll the result list down and up.
• Use Ctrl-l to launch the whole provider list panel for invoking another provider at any time.
• Use Ctrl-n for next input in the history.
• Use Ctrl-p for previous input in the history.
• Use Shift-up and Shift-down to scroll the preview.
• Use gg and G to scroll to the first and last item.
• Use Enter to select the entry and exit.
• Use Shift-Tab to invoke the action dialog.
• Actions defined by g:clap_open_action.

Cmdline mode

• Use :q to exit.

See :help clap-keybindings for more information. Note that the keybindings are not consistent due to discrepancies between Vim/Neovim and different providers.

Execute some code during the process

augroup YourGroup
  autocmd!
  autocmd User ClapOnEnter   call YourFunction()
  autocmd User ClapOnExit    call YourFunction()
augroup END

Change highlights

By default vim-clap will use the colors extracted from your colorscheme, which is not guaranteed to suitable for all the colorschemes. Then you can try the built-in material_design_dark theme then:

let g:clap_theme = 'material_design_dark'

You could also set g:clap_theme to be a Dict to specify the palette:

" Change the CamelCase of related highlight group name to under_score_case.
let g:clap_theme = { 'search_text': {'guifg': 'red', 'ctermfg': 'red'} }

ClapDisplay and ClapPreview are the most basic highlight groups for the display and preview window, which can be overrided if the provider has its own syntax highlight, then checkout the related syntax file for more granular highlights directly.

If you want to write your own clap theme, take autoload/clap/themes/material_design_dark.vim as a reference.

See :help clap-highlights for more information.

Search syntax

Fzf search syntax

vim-clap adopts the almost all fzf search syntax, please refer to the search syntax section of fzf's README for more details. Note that the OR operator defined by a single bar character is not yet implemented, but you can achieve that by using multiple exact matches.

Extended search syntax

Apart from the basic fzf search syntax, more search syntax are supported:

Config file

User config file is loaded from:

• Linux: ~/.config/vimclap/config.toml
• macOS: ~/Library/Application\ Support/org.vim.Vim-Clap/config.toml
• Windows: C:\Users\Alice\AppData\Roaming\Vim\Vim Clap\config\config.toml

[log]
# Note that the log file path must be an absolute path.
log-file = "/tmp/clap.log"
max-level = "debug"

[matcher]
# There are four sort keys for results: score, begin, end, length,
# you can specify how the records are sorted using `tiebreak`.
tiebreak = "score,-begin,-end,-length"

How to define your own provider

" `:Clap quick_open` to open some dotfiles quickly.
" `description` is actually optional, but if you want to show this provider
" when you call `:Clap`, the `description` is neccessary.
let g:clap_provider_quick_open = {
      \ 'source': ['~/.vimrc', '~/.spacevim', '~/.bashrc', '~/.tmux.conf'],
      \ 'sink': 'e',
      \ 'description': 'Quick open some dotfiles',
      \ }

Find more examples at wiki/Examples.

For complete guide about writing a clap provider please see PROVIDER.md.

Disable auto-completion plugin in clap input window

Some of the auto-completion engines need to turn off to prevent bizarre behaviors(#580)

For nvim-completion, add autocmd to your init.vim:

autocmd FileType clap_input let g:completion_enable_auto_pop = 0

For nvim-compe:

autocmd FileType clap_input call compe#setup({ 'enabled': v:false }, 0)

Contribution

Vim-clap is still in beta. Any kinds of contributions are highly welcome.

If you would like to see support for more providers or share your own provider, please create an issue or create a pull request.

If you'd liked to discuss the project more directly, check out .

Credit

• Vim-clap is initially enlightened by snails.
• Some providers' idea and code are borrowed from fzf.vim.
• The built-in fzy python implementation is based on sweep.py.

License

MIT