doc/vim-erlang-omnicomplete.txt

*vim-erlang-omnicomplete.txt* Erlang autocompletion

CONTENTS                                             *vim-erlang-omnicomplete*

    1. Introduction.....................|vim-erlang-omnicomplete-intro|
    2. Commands.........................|vim-erlang-omnicomplete-commands|
    3. Configuration....................|vim-erlang-omnicomplete-config|
      3.1 Configuration Rebar3..........|vim-erlang-omnicomplete-config-rebar3|
    4. Errors...........................|vim-erlang-omnicomplete-errors|
    5. Credits..........................|vim-erlang-omnicomplete-credits|
    6. Contributing.....................|vim-erlang-omnicomplete-contributing|

==============================================================================
INTRODUCTION                                   *vim-erlang-omnicomplete-intro*

vim-erlang-omnicomplete is an Erlang autocompletion plugin (or "omni
completion" in Vim's terminology).

Vim's autocompletion is accessible by hitting |i_CTRL-X_CTRL-O|. After
installing this plugin, if an Erlang file is edited, these keys will provide
Erlang autocompletion.

The plugin completes the followings:

1. Local functions. E.g. if a module contains a "myfun" function, then "my" is
   completed as: >

       +----------+
       | myfun  f |
       +----------+

2. Auto-imported BIFs, e.g. "list_to" is completed as: >

       +-----------------------------------------+
       | list_to_atom(String) -> atom()        f |
       | list_to_binary(IoList) -> binary()    f |
       | ...                                     |
       +-----------------------------------------+

3. Modules, e.g. "gen_" is completed as: >

       +--------------+
       | gen_event  m |
       | gen_fsm    m |
       | ...        m |
       +--------------+

4. Exported functions from other modules, e.g. "lists:mem" is completed as: >

       +-----------------------------------------+
       | lists:member(Elem, List) -> boolean() f |
       +-----------------------------------------+

Type specs and EDoc information are also used when showing completion for
functions in other modules.

If you use rebar, the plugin will find the rebar.config file corresponding to
the module being edited, and uses the directories in rebar.config to find the
possible module and function names. The plugin does not support rebar.script
files though.

The plugin has a basic support for rebar3. It is aware of rebar3 when a
rebar.lock is found inside the project. In the moment of syntax check, the
plugin discovers all the dependencies invoking the "rebar3 as default path"
command in background. The rebar executable is looked up inside the root
directory of the project and, if it's not found, through the current execution
path.

==============================================================================
COMMANDS                                    *vim-erlang-omnicomplete-commands*

                                                *:ErlangCompleteClearAllCache*
:ErlangCompleteClearAllCache
        Clear the completion cache. This can be used if a module has changed
        but the plugin have not noticed that and still completes the previous
        function names.

==============================================================================
CONFIGURATION                                 *vim-erlang-omnicomplete-config*

The vim-erlang-omnicomplete plugin's behaviour can be configured by setting
the global variables below from the |vimrc| file and restarting Vim.

CONFIGURATION OPTIONS                        *vim-erlang-omnicomplete-options*

g:erlang_completion_cache                          *g:erlang_completion_cache*
        Determines whether the functions exported from available modules
        should be cached. If `1`, caching is enabled; if `0`, caching is
        disabled. The default value is `1`.

g:erlang_completion_preview_help            *g:erlang_completion_preview_help*
        Determines whether a help message about the preview window should
        appear in the preview window after the completion information. If `1`,
        the help message appears; if `0`, it does not appear. The default
        value is `1`.

                                        *g:erlang_completion_zero_arity_paren*
g:erlang_completion_zero_arity_paren
        Determines which additional string to insert after completing a
        zero-arity function. The default value is "()".

        An example scenario:

        1. Type "se" in an Erlang buffer.

        2. Hit |i_CTRL-X_CTRL-O|.

        3. The first element in the completion list is: >

              self() -> pid()

<        4. Vim inserts the function name "self".

        5. Vim also inserts the value of
           |g:erlang_completion_zero_arity_paren|. With the default value,
           this means that the inserted text will be: >

               self()
<
                                     *g:erlang_completion_nonzero_arity_paren*
g:erlang_completion_nonzero_arity_paren
        Determines which additional string to insert after completing a
        function with non-zero arity (or unknown arity). The default value is
        "(".

        An example scenario:

        1. Type "list_to_a" in an Erlang buffer.

        2. Hit |i_CTRL-X_CTRL-O|.

        3. The first element in the completion list is: >

               list_to_atom(String) -> atom()

<        4. Vim inserts the function name list_to_atom.

        5. Vim also inserts the value of
           |g:erlang_completion_nonzero_arity_paren|. With the default value,
           this means that the inserted text will be: >

               list_to_atom(
<
g:erlang_completion_extend_arity            g:erlang_completion_extend_arity
        Determines how to display functions where only the arity is known.

        a. If set to `0`, such functions will be displayed with their arity,
           for example: >

               module_info/1

<        b. If set to `1`, a type spec will be generated for such functions,
           for example: >

               module_info(T1) -> any()

<        The default value is `1`.

==============================================================================
CONFIGURATION REBAR3                   *vim-erlang-omnicomplete-config-rebar3*

If you want to make the syntax check of the current project under a different
profile (see rebar3 profiles), you can easily instruct rebar3 by adding a
special configuration item in your rebar.config file.

By default, if nothing is specified, the plugin will assume you chose the
`default` profile.

E.g. to use the "test" profile: >

    {vim_erlang_compiler, [
      {profile, "test"}
    ]}.
<
==============================================================================
ERRORS                                        *vim-erlang-omnicomplete-errors*

The plugin can encounter various errors when trying to execute a completion.
For example:

- The plugin cannot find the module whose functions should be completed.
- The plugin finds the module's source code but cannot parse it.
- There is an uncaught exception is the plugin's Erlang code
  (erlang_complete.erl).

In case of an error:

- The plugin displays "Completion error" and a short help message in the
  completion popup (unless 'completeopt' contains neither "menu" nor
  "menuone").
- The plugin displays the error itself in the preview window (if 'completeopt'
  contains "preview"), or as a popup (if 'completeopt' contains "popup").

Since the default 'completeopt' value is "menu,preview", both of the above are
shown by default.

==============================================================================
CREDITS                                      *vim-erlang-omnicomplete-credits*

Developed by the vim-erlang community. Distributed under Vim's |license|.

vim-erlang-omnicomplete's original source code comes from vimerl
(https://github.com/jimenezrick/vimerl).

Author:       Oscar Hellström <oscar@oscarh.net>
Contributors: Pawel 'kTT' Salata (https://github.com/kTT)
              Ricardo Catalinas Jiménez <jimenezrick@gmail.com>
              Eduardo Lopez (https://github.com/tapichu)
              Ignas Vyšniauskas (https://github.com/yfyf)
              Adam Rutkowski <hq@mtod.org>
              Csaba Hoch <csaba.hoch@gmail.com>
              Zengda <zengda@yunba.io>
License:      Vim License (see |license|)

==============================================================================
CONTRIBUTING                            *vim-erlang-omnicomplete-contributing*

Bug reports, suggestions and improvements encouraged at the project's GitHub:

    https://github.com/vim-erlang/vim-erlang-omnicomplete

==============================================================================