clang_complete.txt

*clang_complete.txt*	For Vim version 7.3.  Last change: 2016 Sep 24


		  clang_complete plugin documentation


clang_complete plugin		      		*clang_complete*

1. Description		|clang_complete-description|
2. Key bindings		|clang_complete-keybindings|
3. Completion kinds    	|clang_complete-compl_kinds|
4. Configuration	|clang_complete-configuration|
5. Options		|clang_complete-options|
6. Known issues		|clang_complete-issues|
7. cc_args.py script	|clang_complete-cc_args|
8. To do		|clang_complete-todo|
9. FAQ			|clang_complete-faq|
10. License		|clang_complete-license|

Author: Xavier Deguillard <deguilx@gmail.com>	*clang_complete-author*

==============================================================================
1. Description 					*clang_complete-description*

This plugin use clang for accurately completing C and C++ code.

Note: This plugin is incompatible with omnicppcomplete due to the
unconditionnaly set mapping done by omnicppcomplete. So don't forget to
suppress it before using this plugin. Also it's possible to keep
omnicppcomplete plugin enabled by setting |g:clang_omnicppcomplete_compliance|.
in this case it will be possible to use omnicppcomplete in parallel with
clang_complete, though functionality of the latter will be reduced to
<C-X><C-U> only.

==============================================================================
2. Key bindings					*clang_complete-keybindings*

Completion is started with CTRL-X CTRL-U |i_CTRL-X_CTRL-U|, or automatically
depending on the value of |clang_complete-auto|.

You can also jump to the declaration of the symbol under the cursor with
<CTRL-]>. Jumping back is done with <CTRL-T>. Since clang_complete uses
|jumplist|, you can navigate through the jumps with <CTRL-O> and <CTRL-I>

==============================================================================
3. Completion kinds    				*clang_complete-compl_kinds*

Because libclang provides a lot of information about completion, there are
some additional kinds of completion along with standard ones (see
|complete-items| for details):
 '+' - constructor
 '~' - destructor
 'e' - enumerator constant
 'a' - parameter ('a' from "argument") of a function, method or template
 'u' - unknown or buildin type (int, float, ...)
 'n' - namespace or its alias
 'p' - template ('p' from "pattern")

==============================================================================
4. Configuration				*clang_complete-configuration*

Each project can have a .clang_complete at its root, containing the compiler
options. This is useful if you're using some non-standard include paths or
need to specify particular architecture type, frameworks to use, path to
precompiled headers, precompiler definitions etc.

Note that as with other option sources, .clang_complete file is loaded and
parsed by the plugin only on buffer loading (or reloading, for example with
:edit! command). Thus no changes made to .clang_complete file after loading
source file into Vim's buffer will take effect until buffer will be closed and
opened again, reloaded or Vim is restarted.

Compiler options should go on individual lines (multiple options on one line
can work sometimes too, but since there are some not obvious conditions for
that, it's better to have one option per line).

Linking isn't performed during completion, so one doesn't need to specify any
of linker arguments in .clang_complete file. They will lead to completion
failure when using clang executable and will be completely ignored by
libclang.

Example .clang_complete file: >
 -DDEBUG
 -include ../config.h
 -I../common
 -I/usr/include/c++/4.5.3/
 -I/usr/include/c++/4.5.3/x86_64-slackware-linux/
<
==============================================================================
5. Options					*clang_complete-options*

					*clang_complete-loaded*
					*g:clang_complete_loaded*
If set, clang_complete won't be loaded.
Default: unset.

       				       	*clang_complete-auto_select*
				       	*g:clang_auto_select*
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: 0

       				       	*clang_complete-complete_auto*
       				       	*g:clang_complete_auto*
If equal to 1, automatically complete after ->, ., ::
Default: 1

       				       	*clang_complete-copen*
       				       	*g:clang_complete_copen*
If equal to 1, open quickfix window on error.
Default: 0

       				       	*clang_complete-hl_errors*
       				       	*g:clang_hl_errors*
If equal to 1, it will highlight the warnings and errors the same way clang
does it.
Default: 1

       				       	*clang_complete-periodic_quickfix*
       				       	*g:clang_periodic_quickfix*
If equal to 1, it will periodically update the quickfix window.
Default: 0
Note: You could use the g:ClangUpdateQuickFix() to do the same with a mapping.

       				       	*clang_complete-snippets*
       				       	*g:clang_snippets*
If equal to 1, it will do some snippets magic on code placeholders like
function argument, template parameters, etc.
Default: 0

				       	*clang_complete-snippets_engine*
				       	*g:clang_snippets_engine*
The snippets engine (clang_complete, ultisnips... see the snippets
subdirectory).
Default: "clang_complete"

       				       	*clang_complete-conceal_snippets*
       				       	*g:clang_conceal_snippets*
Note: This option is specific to clang_complete snippets engine.
If equal to 1, clang_complete will use vim 7.3 conceal feature to hide the
snippet placeholders.

Example of conceal configuration (see |'concealcursor'| and |'conceallevel'|
for details): >
 " conceal in insert (i), normal (n) and visual (v) modes
 set concealcursor=inv
 " hide concealed text completely unless replacement character is defined
 set conceallevel=2

Default: 1 (0 if conceal not available)

       				       	*clang_complete-optional_args_in_snippets*
       				       	*g:clang_complete_optional_args_in_snippets*
If equal to 1, it will add optional arguments to the function call snippet.
Snippet replaceable object will not be only the argument, but the preceding
comma will be included as well, so you can press backspace to delete the
optional argument, while the replaceable is selected.
Example: foo($`T param1`, $`T param2`$`, T optional_param`)
Default: 0

       				       	*clang_complete-clang_trailing_placeholder*
       				       	*g:clang_trailing_placeholder*
Note: This option is specific to clang_complete snippets engine.
If equal to 1, clang_complete will add a trailing placeholder after functions
to let you add you continue writing code faster.
Default: 0

       				       	*clang_complete-clang_restore_cr_imap*
       				       	*g:clang_restore_cr_imap*
This option is used for versions of Vim without the Dictionary version of
|maparg()| introduced in 7.3.32. The variable is executed after completion to
restore the insert-mode map of <CR>. Occurrences of "<SID>" in the variable
are replaced with the appropriate "<SNR>" code based on the original map.
Default: 'iunmap <buffer> <CR>'

       				       	*clang_close-preview*
       				       	*g:clang_close_preview*
If equal to 1, the preview window will be close automatically after a
completion.
Default: 0

       				      	*clang_complete-user_options*
       				       	*g:clang_user_options*
Additional compilation argument passed to libclang.

Example: >
 " compile all sources as c++11 (just for example, use .clang_complete for
 " setting version of the language per project)
 let g:clang_user_options = '-std=c++11'
<
Default: ""

       				       	*clang_complete-auto_user_options*
       				       	*g:clang_auto_user_options*
Set sources for user options passed to clang. Available sources are:
- path - use &path content as list of include directories (relative paths are
  ignored);
- .clang_complete - use information from .clang_complete file Multiple options
  are separated by comma;
- compile_commands.json - get the compilation arguments for the sources from a
  compilation database. For example, recent versions of CMake (>=2.8.7) can
  output this information. clang_complete will search upwards from where vi
  was started for a database named 'compile_commands.json'.
  Note : compilation databases can only be used when 'g:clang_use_library'
  equals 1 and the clang libraries are recent enough (clang>=3.2). The 
  compilation database only contains information for the C/C++ sources files,
  so when editing a header, clang_complete will reuse the compilation
  arguments from the last file found in the database.
- {anything} else will be treaded as a custom option source in the following
  manner: clang_complete will try to load the autoload-function named
  getopts#{anything}#getopts, which then will be able to modify
  b:clang_user_options variable. See help on |autoload| if you don't know
  what it is.

This option is processed and all sources are used on buffer loading, not each
time before doing completion.

Default: ".clang_complete, path"

                                        *clang_complete-compilation_database*
                                        *g:clang_compilation_database*
By default, clang_complete will search upwards from where it was started to
find a compilation database. In case this behaviour does not match your needs,
you can set |g:clang_compilation_database| to the directory where the database
can be loaded from.

       				       	*clang_complete-use_library*
       				       	*g:clang_use_library*
Instead of calling the clang/clang++ tool use libclang directly. This gives
access to many more clang features. Furthermore it automatically caches all
includes in memory. Updates after changes in the same file will therefore be a
lot faster.
Note: This version doesn't support calling clang binary for completion. If you
cannot use libclang, you should download clang_complete from vim.org website.
Default: 1

       				       	*clang_complete-library_path*
       				       	*g:clang_library_path*
If libclang is not in the library search path of your system, you should set
this variable to the absolute path of either directory containing
libclang.{dll,so,dylib} (for Windows, Unix variants and OS X respectively) or
to that file itself.
Default: ""

Example: >
 " path to directory where library can be found
 let g:clang_library_path='/usr/lib/llvm-3.8/lib'
 " or path directly to the library file
 let g:clang_library_path='/usr/lib64/libclang.so.3.8'
<
					*clang_complete-sort_algo*
					*g:clang_sort_algo*
How results are sorted (alpha, priority, none). Currently only works with
libclang.
Default: "priority"

					*clang_complete-complete_macros*
					*g:clang_complete_macros*
If clang should complete preprocessor macros and constants.
Default: 0

					*clang_complete-complete_patterns*
					*g:clang_complete_patterns*
If clang should complete code patterns, i.e loop constructs etc.
Default: 0

					*clang_complete-jumpto_declaration_key*
					*g:clang_jumpto_declaration_key*
Set the key used to jump to declaration.
Default: "<C-]>"
Note: You could use the g:ClangGotoDeclaration() to do the same with a mapping.

					*clang_complete-jumpto_declaration_in_preview_key*
					*g:clang_jumpto_declaration_in_preview_key*
Set the key used to jump to declaration in a preview window.
Default: "<C-W>]"
Note: You could use the g:ClangGotoDeclarationPreview() to do the same with a mapping.

					*clang_complete-jumpto_back_key*
					*g:clang_jumpto_back_key*
Set the key used to jump back.
Note: Effectively this will be remapped to <C-O>. The default value is chosen
to be coherent with ctags implementation.
Default: "<C-T>"

					*clang_complete-make_default_keymappings*
					*g:clang_make_default_keymappings*
If this option is set, the default keymappings will be set by clang_complete.
Otherwise none are set and the user will have to provide those keymappings.
Default: 1

					*clang_complete-omnicppcomplete_compliance*
					*g:clang_omnicppcomplete_compliance*
Omnicppcomplete compatibility mode. Keeps omni auto-completion in control of
omnicppcomplete, disables clang's auto-completion (|g:clang_complete_auto|)
and enables only <C-X><C-U> as main clang completion function.
Default: 0

==============================================================================
6. Known issues					*clang_complete-issues*

If you get following error message while trying to complete anything: >
 E121: Undefined variable: b:should_overload
it means that your version of Vim is too old (this is an old bug and it has
been fixed with one of patches for Vim 7.2) and you need to update it.

Ubuntu users may need to install libclang-dev: >
 apt-get install libclang-dev

==============================================================================
7. cc_args.py script				*clang_complete-cc_args*

This script, installed at ~/.vim/bin/cc_args.py, could be used to generate or
update the .clang_complete file. It works similar to gccsence's gccrec and
simply stores -I and -D arguments passed to the compiler in the
.clang_complete file.  Just add the cc_args.py script as the first argument of
the compile command. You should do that every time compile options have
changed.

Example (we need -B flag to force compiling even if project is up to date): >
 make CC='~/.vim/bin/cc_args.py gcc' CXX='~/.vim/bin/cc_args.py g++' -B
After running this command, .clang_complete will be created or updated with
new options. If you don't want to update an existing configuration file,
delete it before running make.

==============================================================================
8. To do					*clang_complete-todo*

- Write some unit tests
- Explore "jump to declaration/definition" with libclang FGJ
- Think about supertab (<C-X><C-U> with supertab and clang_auto_select)

==============================================================================
9. FAQ						*clang_complete-faq*

*) clang_complete doesn't work! I always get the message "pattern not found".

This can have multiple reasons. You can try to open the quickfix window
(:copen) that displays the error messages from clang to get a better idea what
goes on. It might be that you need to update your .clang_complete file. If
this does not help, keep in mind that clang_complete can cause clang to search
for header files first in the system-wide paths and then in the ones specified
locally in .clang_complete. Therefore you might have to add "-nostdinc" and
the system include paths in the right order to .clang_complete.

*) Only function names get completed but not the parentheses/parameters.

Enable the snippets-support by adding the following lines to your .vimrc,
for example:

let g:clang_snippets = 1
let g:clang_snippets_engine = 'clang_complete'

If you have ultisnips installed, you can use

let g:clang_snippets = 1
let g:clang_snippets_engine = 'ultisnips'

instead. After a completetion you can use <Tab> in normal mode to jump to the
next parameter.

*) Can I configure clang_complete to insert the text automatically when there
   is only one possibility?

You can configure vim to complete automatically the longest common match by
adding the following line to your vimrc:

set completeopt=menu,longest

==============================================================================
10. License					*clang_complete-license*

Copyright (c) 2010, 2011, 2012, 2013 Xavier Deguillard, Tobias Grosser
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the copyright holders nor the names of their
      contributors may be used to endorse or promote products derived from
      this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Note: This license does not cover the files that come from the LLVM project,
namely, cindex.py and __init__.py, which are covered by the LLVM license.

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