*completor.txt*    For Vim version 8.0.    Last change: 2016 Oct 12


Async completion framework made ease.                   *completor*

1. Intro                        |completor-intro|
2. Install                      |completor-install|
3. Completers                   |completor-completers|
4. Options                      |completor-options|
5. Write a new completer        |completor-writing|

==============================================================================
1. Intro                                                *completor-intro*

Completor is an asynchronous code completion framework for vim8. New features
of vim8 are used to implement the fast completion engine with low overhead.
For using semantic completion, external completion tools should be installed.

Completor uses python to implement the completers, so vim should be compiled
with `python` or `python3`.

==============================================================================
2. Install                                              *completor-install*

Using vim8 builtin package manager:
>
    mkdir -p ~/.vim/pack/completor/start
    cd ~/.vim/pack/completor/start
    git clone https://github.com/maralla/completor.vim.git
<

Using vim-plug:
>
    Plug 'maralla/completor.vim'
<
==============================================================================
3. Completers                                           *completor-completers*


Filename                                                *completor-filename*
        When the input matches a file path pattern the file name will be
        automatically completed.

Buffer                                                  *completor-buffer*
        This is the fallback completer. When no semantic completer found the
        buffer completer will be used and will complete based on the current
        buffers.

Python                                                  *completor-python*
        Use jedi for completion. jedi should be installed for semantic
        completion.

        Install jedi to global environment or in virtualenv:
>
            pip install jedi
<
        The python executable can be specified using:
>
            let g:completor_python_binary = '/path/to/python/with/jedi/installed'
<
Rust                                                    *completor-rust*
        Use racer for completion.

        Install racer according to this:
        https://github.com/phildawes/racer#installation

        To specify the racer executable path:
>
           let g:completor_racer_binary = '/path/to/racer'
<
Javascript                                              *completor-javascript*
        Use tern for completion.

        To install tern you must have node and npm installed. Then run:
>
            make js
<
        The node executable path can be specified using:
>
            let g:completor_node_binary = '/path/to/node'
<
c/c++                                                   *completor-cpp*
        Use clang for completion. Clang should be installed first.

        To specify clang path:
>
            let g:completor_clang_binary = '/path/to/clang'
<
        To pass extra clang arguments, you can create a file named
        .clang_complete under the project root directory or any parent
        directories. Every argument should be in a single line in the file.
        This is an example file:
>
            -std=c++11
            -I/Users/maralla/Workspace/src/dji-sdk/Onboard-SDK/lib/inc
            -I/Users/maralla/Workspace/src/dji-sdk/Onboard-SDK/sample/Linux/inc
<
        The key mapping `<Plug>CompletorCppJumpToPlaceholder` can be defined
        to jump to placeholders:
>
            map <tab> <Plug>CompletorCppJumpToPlaceholder
            imap <tab> <Plug>CompletorCppJumpToPlaceholder
<
        To disable generation of placeholders on completion, use:
>
            let g:completor_clang_disable_placeholders = 1
<
go                                                      *completor-go*
        Use [gocode](https://github.com/nsf/gocode) to provide omni completions.
        To specify the gocode executable path:
>
            let g:completor_gocode_binary = '/path/to/gocode'
<
Other                                                   *completor-other*
        For other omni completions completor not natively implemented, auto
        completion can still be used if an omni function is defined for the
        file type. But an option should be defined to specify the trigger
        for triggering auto completion. The option name pattern:
>
            let g:completor_{filetype}_omni_trigger = '<python regex>'
<
        For example to use css omnifunc:
>
            let g:completor_css_omni_trigger = '([\w-]+|@[\w-]*|[\w-]+:\s*[\w-]*)$'
<
==============================================================================
4. Options                                              *completor-options*

*g:completor_auto_close_doc* (0/1)
        Completion may trigger a preview window. This option controls whether
        to auto close the window when the completion finished.

        Default: 1.

*g:completor_blacklist* (list)
        Explicitly ignore completions for file types specified in this list.

        Default: ['tagbar', 'qf', 'netrw', 'unite', 'vimwiki'].

*g:completor_whitelist* (list)
        Explicitly allow completions for file types in this list. If this
        option is set, only file types in this list can be allowed for
        completion.

        Default: unset.

*g:completor_filesize_limit* (in KB)
        If the file size of the current buffer if larger than the
        filesize_limit completion will be ignored.

        Default: 1024

*g:completor_disable_filename*
*g:completor_disable_buffer*
*g:completor_disable_ultisnips*
        Used to disable filename/buffer/ultisnips completions. To disable for
        specified file types, assign a list to these variables:

        For example disable filename completion for vim:
>
            let g:completor_disable_filename = ['vim']
<
        To disable for all file types:
>
            let g:completor_disable_{filename/buffer/ultisnips} = 1
<
        Default: unset

*g:completor_enable_{filetype}*
        Used to explicitly allow {filetype} completions. If this
        option is set, only file types in this list can be allowd for
        {filetype} completion.

        For example enable neosnippet completion for only vim:
>
            let g:completor_enable_neosnippet = ['vim']
<
        Default: unset

*g:completor_min_chars*
        Set the minimum characters to trigger completions for buffer and
        ultisnips completers.

        Default: 2

*g:completor_auto_trigger*
        Whether to auto trigger the completion popup.

        Default: 1

*g:completor_completion_delay*
        Time (in milliseconds) to wait before auto triggering completion
        popup.

        Default: 80

*g:completor_complete_options*
        Set complete options for completor. The config `completeopt` will be 
        overwritten by the value when the completion is triggered and restored
        after completion done.

        Defaut: menuone,noselect,preview

*g:completor_refresh_always*
        Set to 1 to refresh the completion menu whenever a key is pressed. If
        the value is 0 the list will not be refreshed when it has items with
        the prefix of the inputted characters.

        Default: 1

*g:completor_debug*
        There is log file under `<completor_root>/pythonx/completor.log`. When
        set to 1 debug messages defined in python codes will be logged to this
        file.

        Default: 0

*g:completor_doc_position*
        This option controls the position of the doc window triggered by
        executing `:call completor#do('doc')`.

        Available values:

            bottom: Open the doc window at bottom. (Default)
            top: Open the doc window at top.

        Default: bottom

*g:completor_def_split*
        Show definition result in split window, default in current window.

        Available values:

            split:  same as :split.
            vsplit: same as :vsplit.
            tab:    same as :tab split

*g:completor_filename_completion_in_only_comment*
        This option allows filename completion in only comment or strings.

        Default: 1
==============================================================================
5. Write a new completer                                *completor-writing*


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