*inccomplete.txt*       For Vim version 7.3.  Last change: 2020 Jan 9


                  inccomplete plugin documentation    by xaizek


inccomplete plugin                                      *inccomplete*

1. Description                  |inccomplete-description|
2. Configuration                |inccomplete-configuration|
3. ToDo                         |inccomplete-todo|

Author:  xaizek <xaizek@posteo.net>                     *inccomplete-author*
License: Same terms as Vim itself (see |license|)

==============================================================================
1. Description                                  *inccomplete-description*

This is a completion plugin for C/C++/ObjC/ObjC++ preprocessors include
directive.  It can be used along with clang_complete plugin
(https://www.vim.org/scripts/script.php?script_id=3302).
And maybe with some others that haven't been tested.  clang_complete
dependency is optional, though even if you don't use it you still can set its
options so that they affect this plugin.

It has been reported to work with neocomplete plugin as is and for
neovim+deoplete these conditions might need to be met:
 * g:inccomplete_showdirs is set
 * g:deoplete#omni#input_patterns.cpp is set to >
   ['[^. *\t]\.\w*', '[^. *\t]\::\w*', '[^. *\t]\->\w*', '[<"].*/']
<   I.e., add the last item to trigger omnifunc on `<../` and `"../` patterns.
(see
https://github.com/Rip-Rip/clang_complete/issues/466#issuecomment-167975065
and
https://github.com/xaizek/vim-inccomplete/issues/5#issuecomment-259419371).

It can complete both "" and <> forms of #include.

"" Completion~

By default gets all header files in the current directory or any directory
relative to it.  Can be configured with |b:inccomplete_root| and
|g:inccomplete_localsources|.

<> Completion~

For <> it gets all files that have hpp or h extensions or don't have any.

Sources for <> completion are:
- 'path' option (on *nix it's set to '/usr/include' by default, but on Windows
  you should set it to right directories manually)
- g:clang_user_options ('-I' keys)
- b:clang_user_options ('-I' keys)

Note: current directory won't be used even if it present in one of sources.

Completion of subdirectories~

When |g:inccomplete_showdirs| is false, only files of include directories are
displayed in completion list, but you can complete files in subdirectories
of include directories too.  All you need is to call completion again after
typing subdirectory name and a slash (and optionally beginning of file name).

When |g:inccomplete_showdirs| is true, completion list contains directories
and it will popup after hitting forward or backward slash key.  Directories
can be distinguished by the ending slash.  Directories which names start with
a dot are ignored.  Closing bracket is never added to directory completion
items.

==============================================================================
2. Configuration                                *inccomplete-configuration*

Whether to autoselect the first entry           *inccomplete-autoselect*
                                                *g:inccomplete_autoselect*
If equal to 0, nothing is selected.
If equal to 1, automatically select the first entry in the popup menu, but
without inserting it into the code.
If equal to 2, automatically select the first entry in the popup menu, and
insert it into the code.
Default: 1

command to run GNU find program                 *inccomplete-findcmd*
                                                *g:inccomplete_findcmd*
                                                 type: string
                                                 default: ""

When it's empty, plugin will use VimL functions to search files, otherwise it
will use given external program.

Note: On Windows you need to have Cygwin installed and to set full path to
      find utility. For example, like this: >
      let g:inccomplete_findcmd = 'c:/cygwin/bin/find'
<     Or it can be any find utility that accepts the following
      parameters and multiple search paths: >
      -maxdepth 1 -type f -type d -or -L
<

how to add close bracket                        *inccomplete-addclosebracket*
                                                *g:inccomplete_addclosebracket*
                                                 type: string
                                                 default: "always"

When this option equals "always" close bracket will be added right after open
bracket was pressed. Otherwise it will be added after completion is over.

how to sort completion list                     *inccomplete-sort*
                                                *g:inccomplete_sort*
                                                 type: string
                                                 default: ""

When this option equals "ignorecase" the case of letters of filenames will be
ignored.

add directories to completion list              *inccomplete-showdirs*
                                                *g:inccomplete_showdirs*
                                                 type: bool
                                                 default: false

If value of this option evaluates to true, plugin will search for
directories and add it to completion list.

append a slash to directory names               *inccomplete-appendslash*
                                                *g:inccomplete_appendslash*
                                                 type: bool
                                                 default: false

If value of this option evaluates to true, the plugin will append a slash
to directory name completion items. Otherwise slashes will be added in the
menu only.

extra sources for local includes                *inccomplete-roots*
                                                *b:inccomplete_roots*
                                                 type: list
                                                 default: []

If this option is set for current buffer, the plugin uses paths specified via
it as additional directory to search for local completion.

root for local includes                         *inccomplete-root*
                                                *b:inccomplete_root*
                                                 type: string
                                                 default: not set

Use |b:inccomplete-roots| instead.
If this option is set for current buffer, the plugin uses it as base
directory for local completion.

list of sources for "" completion               *inccomplete-localsources*
                                                *g:inccomplete_localsources*
                                                 type: list
                                                 default: [ 'relative-paths' ]

Specifies what appears in "" completion.  List can include the following
items:
- 'relative-paths' to complete paths relative to location of current buffer
- 'clang-buffer' to complete paths from '-I' keys in b:clang_user_options
- 'clang-global' to complete paths from '-I' keys in g:clang_user_options
- paths to directories to complete from (the path needs to include slash
  somewhere and be an existing directory)

==============================================================================
3. ToDo                                         *inccomplete-todo*

- Maybe 'path' option should be replaced with some global variable like
  g:inccomplete_incpath?
- Maybe '.' in path should be automatically replaced with the path to current
  buffer instead of assuming that working directory is correct?
- Add optional caching for local includes (ones in the double quotes).
- Maybe filter out includes that already present in the buffer.
- Can we follow symbolic links on completion?

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