===============================================================================
CONTENTS                                                 *clap-provider-contents*

 Provider.............................|clap-provider|
    Non-pure-async Providers..........|clap-non-pure-async-providers|
    Pure async Providers..............|clap-pure-async-providers|
    Registering Providers.............|clap-registering-providers|

===============================================================================
Clap Provider                                                    *clap-provider*
                                                           *write-clap-provider*


The provider of vim-clap is actually a |Dict| that specifies the action of your
move in the input window. The idea is simple, every time you typed something,
the `source` will be filtered or a job `source_async` will be spawned, and then
the result retrived later will be shown in the dispaly window.

There are generally two kinds of providers in vim-clap.

1. Non-pure-async provider: suitable for these which are able to collect all
   the items in a short time, e.g., open buffers, command history. It will run
   in synchoronous if the source size is not large.

   But it's also able to deal with the list that is potentially huge, let's say
   100,000+ lines/items, in which case vim-clap will try to run the external filter
   asynchronously. In a word, vim-clap can always be fast responsive.

   What's more, it's extremely easy to introduce a new non-pure-async clap provider
   as vim-clap provides the default implementation of `on_typed` and `source_async`.

2. Pure async provider: suitable for the time-consuming jobs, e.g.,
   grep a word in a directory.


-------------------------------------------------------------------------------
4.1. Non-pure-async Providers                     *clap-non-pure-async-providers*


  `sink`                 |String|  - vim command to handle the selected entry.
                       |Funcref| - reference to function to process the selected entry.

                       This field is mandatory.


  `sink*`                |Funcref| - similar to `sink*`, but takes the list of multiple
                                 selected entries as input.

                       This field is optional.


  `source`               |List|    - vim List as input to vim-clap.
                       |String|  - external command to generate input to vim-clap,
                                 e.g. `find .` .
                       |Funcref| - reference to function that returns a List to
                                 generate input to vim-clap.

                       This field is mandatory.


  `source_async`         |String| - job command to filter the items of `source` based
                                on the external tools. The default implementation
                                is to feed the output of `source` into the external
                                fuzzy filters and then display the filtered result,
                                which could have some limitations, e.g., the
                                matched indices is unable to be highlighted.

                       This field is optional.


  `filter`               |Funcref| - given what you have typed, use `filter(entry)` to
                                 evaluate each entry in the display window, when
                                 the result is zero remove the item from the current
                                 result list. The default implementation is to
                                 match the input using vim's regex.

                       This field is mandatory.


  `on_typed`             |Funcref| - reference to function to filter the `source`.

                       This field is mandatory.


  `on_move`              |Funcref| - can be used for the preview purpose, when navigating
                                 the result list, see clap/provider/colors.vim.

                                 It won't be called if you merely input some characters
                                 and do not scroll the list.

                       This field is optional.


  `on_enter`             |Funcref| - when entering the clap window, can be used
                                 for recording the current state.

                       This field is optional.


  `on_exit`              |Funcref| - can be used for restoring the state on start.

                       This field is optional.


  `enable_rooter`        |Bool|

                       This field is optional.


  `support_open_action`  |Bool|

                       This field is optional.


  `syntax`               |String|
                       for setting the syntax highlight for the display buffer easier.
                       `let s:provider.syntax = 'provider_syntax'` is equal to
                       `let s:provider.syon_enter = { -> g:clap.display.setbufvar('&syntax', 'provider_syntax')}` .

                       This field is optional.

-------------------------------------------------------------------------------
4.2 Pure async Providers                              *clap-pure-async-providers*


  `sink`                   |Funcref| - reference to function to process the selected
                                   entry.

                         This field is mandatory and has no default
                         implementation.


  `on_typed`               |Funcref| - reference to function to spawn an async job.

                         This field is mandatory.


  `on_move`                |Funcref|

                         This field is optional.


  `on_enter`               |Funcref|

                         This field is optional.


  `on_exit`                |Funcref|

                         This field is optional.


  `converter`              |Funcref| - reference to function to convert the raw output
                                   of job to another form, e.g., prepend an icon
                                   to the grep result.

                         This field is optional.


  `jobstop`                |Funcref| - Stop the current job.

                         This field is mandatory.


  `enable_rooter`          |Bool|

                         This field is optional.


  `support_open_action`    |Bool|

                         This field is optional.


-------------------------------------------------------------------------------
4.3 Registering Providers                            *clap-registering-providers*


Vim-clap will load the providers automatically when neccessary if it's defined
properly.

- vimrc

Define `g:clap_provider_{provider_id}` in your vimrc, e.g.,

>
  " `:Clap quick_open` to open some dotfiles quickly.
  let g:clap_provider_quick_open = {
      \ 'source': ['~/.vimrc', '~/.spacevim', '~/.bashrc', '~/.tmux.conf'],
      \ 'sink': 'e',
      \ }
<

- autoload

`g:clap#provider#{provider_id}#`. See `:h autoload` and autoload/clap/provider.vim.

                                                    *clap-provider-description*

Each autoload provider should start with these two comment lines, the
Description line will be extracted as the brief introduction when displaying
all the avaliable providers via `:Clap` .
>
  " Author: liuchengxu <xuliuchengxlc@gmail.com>
  " Description: List the windows.

===============================================================================
  vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl:
