*merlin.txt*	For Vim version 7.3 	Last change: 2013 March 30

                                Merlin ~

                Context sensitive completion for OCaml. ~

==============================================================================
COMMANDS                                                     *merlin-commands*

:MerlinSourcePath [dir]                                    *:MerlinSourcePath*

When dir is given adds, for the current session, the directory to the list of
directories where merlin looks for ml[i] files.

If no argument is given, it will list those directories.

:MerlinBuildPath [dir]                                      *:MerlinBuildPath*

Same as |:MerlinSourcePath| but for cmi files.

:MerlinUse package [, package]*                                   *:MerlinUse*

Loads findlib packages (with completion) by adjusting buildpath to find files
from packages.

Tab completion on packages name is provided.

:MerlinLocate                                                  *:MerlinLocate*

When called with no arguments tries to jump at the definition of the identifier
under the cursor.

When called with one argument tries to jump at the definition of the given
identifier, using the environment available at the cursor position.

Bound to gd by default in normal mode.

:ML[I]                                                                   *:ML*

Quick switch to a source (resp. interface) file.
For instance, given moduleA.ml and moduleB.mli in source path, use: >
    :ML ModuleA
    :MLI ModuleB
<

:MerlinTypeOf [expr]                                           *:MerlinTypeOf*

If given an expression, returns its type.
Otherwise, highlights the expression under the cursor and prints its type.
Use in conjunction with |:MerlinGrowEnclosing| and |:MerlinShrinkEnclosing|.

Bound to <LocalLeader>t by default in normal mode.

:MerlinTypeOfSel                                            *:MerlinTypeOfSel*

In visual mode, returns the type of the selected expression.

Bound to <LocalLeader>t by default in visual mode.

:MerlinGrowEnclosing                                    *:MerlinGrowEnclosing*

When |:MerlinTypeOf| has been called, select the smallest expression
containing the previously highlighted expression.

Bound to <LocalLeader>n by default in normal mode.

:MerlinShrinkEnclosing                                *:MerlinShrinkEnclosing*

When |:MerlinGrowEnclosing| has been called, revert to the previously selected
expression. (i.e. the largest expression, centered around the position where
|:MerlinTypeOf| was called, which is contained in the currently highlighted
expression).

Bound to <LocalLeader>p by default in normal mode.

["r] :MerlinYankLatestType                             *:MerlinYankLatestType*

Copy the latest shown type into register `"r`, or `""` if unspecified.

:MerlinToggleTypeHistory                            *:MerlinToggleTypeHistory*

Reveals or hides a buffer containing a trace of all computed types.
See |merlin_type_history_height| and |merlin_type_history_auto_open|.

:MerlinOccurrences                                         *:MerlinOccurences*

List all occurrences of identifier under cursor in current buffer.
See |merlin_display_occurrence_list|.
Add these bindings to integrate the results into vim search (see |star|) >
  nmap <LocalLeader>*  <Plug>(MerlinSearchOccurrencesForward)
  nmap <LocalLeader>#  <Plug>(MerlinSearchOccurrencesBackward)
<

:MerlinRename <ident>                                          *:MerlinRename*

Rename all occurrences of identifier under cursor to <ident>.
Add these bindings to rename interactively: >
  nmap <LocalLeader>r  <Plug>(MerlinRename)
  nmap <LocalLeader>R  <Plug>(MerlinRenameAppend)
<

:MerlinDestruct                                              *:MerlinDestruct*

"destructs" the thing under the cursor, i.e.
- if the thing under the cursor is an expression, generates a pattern matching
  on it.
- if the thing under the cursor is a non-exhaustive pattern matching, makes
  the matching exhaustive
- if the thing under the cursor is a pattern variable or a pattern wildcard,
  refines that pattern (if possible).

See https://ocaml.github.io/merlin/destruct.ogv

:MerlinConstruct                                            *:MerlinConstruct*

When called from a hole "_", attempts to construct terms matching the hole's
type. If only one result is found the hole is replaced immediately. If multiple
results are found a list will appear. It is possible to ask for more or less
deep results in that list using the shortcuts  "<c-i>" and "<c-u>".

:MerlinOutline                                                *:MerlinOutline*

Gives an "outline" of the current buffer, i.e. lists all the "definitions"
made in the buffer along with their kind (type definition, value definition,
module, etc.) and allows one to quickly jump at the (interactively) selected
definition.

The rendering (and interactivity) is provided by
[ctrl-p](https://github.com/ctrlpvim/ctrlp.vim).

:MerlinNextHole                                              *:MerlinNextHole*

Moves the cursor forward to the closest hole "_". If there is no hole after the
cursor the search will restart at the beginning of the buffer.

:MerlinPreviousHole                                      *:MerlinPreviousHole*

Moves the cursor backwards to the closest hole "_". If there is no hole before
the cursor the search will restart at the end of the buffer.

:MerlinILocate                                                *:MerlinILocate*

This is an interactive version of |:MerlinLocate|, which relies on
[ctrl-p](https://github.com/ctrlpvim/ctrlp.vim).
It expects some input from the user, and then will list things in the
environment which name matches the user input.

Hitting enter will move you to the definition of the selected element.

:MerlinErrorCheck                                            *:MerlinErrorCheck*

Perform a fast type check of the current file, displaying the error
messages in a new quickfix window.

:MerlinPy                                                    *:MerlinPy*

Act either as *:py* or *:py3* depending on the version of python is used
by the vim plugin.
This is only useful if you want to write custom merlin extensions. 

:MerlinSearch                                                  *:MerlinSearch*

Act either as :MerlinSearchPolarity or :MerlinSearchType depending on the first
character of the query. If the query starts with '-' or '+', then
:MerlinSearchPolarity is used, otherwise, :MerlinSearchType is used.

>
  :MerlinSearch -int +string
  :MerlinSearch int -> string
<

:MerlinSearchPolarity                                  *:MerlinSearchPolarity*

Search for values in the current scope that have a type matching the query.
The results are displayed in a completion menu.

The query language is simply a list of path identifiers prefixed by `+` or `-`,
e.g. `-int`, `-int +string`, `-Hashtbl.t +int`.

`-` is interpreted as "consuming" and `+` as "producing": `-int +string` looks
for functions consuming an `int` and producing a `string`.

>
  :MerlinSearchPolarity -int +string
<

:MerlinSearchType                                          *:MerlinSearchType*

Works similarly to :MerlinSearchPolarity but uses a different query language.
The results are displayed in a completion menu.

The query language is a list of type constructors separated by '->'.
Type parameters and functions are allowed: `('a -> bool) -> 'a list -> bool`.

>
  :MerlinSearchType int -> string
<

==============================================================================
OPTIONS                                                       *merlin-options*


                                                    *'merlin_ignore_warnings'*
Default: false.
If you are using syntastic and don't want warnings notified, set the following
variable to {"true"} >
  let g:merlin_ignore_warnings = "false"
<

                                                         *merlin_highlighting*

The |:TypeEnclosing| commands highlights the expression under the cursor, the
related match group is {EnclosingExpr}. You can customize the highlighting
with the |:highlight| command, e.g. >
    hi EnclosingExpr ctermbg=17 guibg=LightGreen
<

                                                    *'merlin_move_to_project'*

Default: false.
If set to true, merlin will automatically change local directory of an ocaml
buffer to the root of the ".merlin" file. >
  let g:merlin_move_to_project = "true"
<
                                             *'merlin_display_occurrence_list'*

Default: true.
If set to true, merlin automatically displays the list of occurrences in a
separate window after a :MerlinOccurrences command. >
  let g:merlin_display_occurrence_list = 0
<

                                                  *'merlin_display_error_list'*

Default: true.
If set to true, merlin automatically displays the list of errors in a
separate window after a :MerlinErrorCheck command. >
  let g:merlin_display_error_list = 0
<

                                                    *'merlin_close_error_list'*

Default: true.
If set to true, merlin automatically closes the list of errors if no error
was found after a :MerlinErrorCheck command. >
  let g:merlin_close_error_list = 0
<
                                                 *'merlin_type_history_height'*

Default: 5.
The default height of the type history window.  If set to zero, merlin never
records any types in the history buffer. >
  let g:merlin_type_history_height = 0
<
                                              *'merlin_type_history_auto_open'*

Default: 5.
The maximum number of type lines to print in the statusbar before opening the
type history window.  If set to a very large number, merlin will never open
the type history window automatically. >
  let g:merlin_type_history_auto_open = 9999
<

                                                     *'merlin_textobject_grow'*
                                                   *'merlin_textobject_shrink'*
Default: unset.
Binds |text-objects| on the ocaml AST. For example: >
  let g:merlin_textobject_grow   = 'm'
  let g:merlin_textobject_shrink = 'M'
<
On their first call, `M` selects the current node while `m` selects something
bigger than a leaf.  Repeated use of `m` grow the selection and `M` shrinks
it back.  The variants `im` and `aM` behave similarly, but reduce the
selection by avoiding spaces and parenthesis; while `am` and `aM` expand it by
capturing the surrounding spaces.

In the following illustration, the cursor is represented by `[n]`:
>
                       ┌── aM ──┐
                       │ ┌─ M ─┐│
                       ↓ ↓     ↓↓
  let def = outer     (  in[n]er  stuff  )    more
            ↑     ↑   ↑  ↑            ↑  ↑  ↑    ↑
            │     │   │  └─ im ───────┘  │  │    │
            │     │   └────  m ──────────┘  │    │
            │     └──────── am ─────────────┘    │
            └────────────── 2m ──────────────────┘
                        (or mm)
<

                                                     *'merlin_completion_dwim'*
Default: true.
Whether to enable "smart" (a.k.a "do what I mean") completion.
If true, `L.m` will expand to >
  List.map
  List.m...
  ListLabels.map
  ...
<
if `L` doesn't exist.

Disable with: >
  let g:merlin_completion_dwim = 0
<

                                                 *'merlin_completion_arg_type'*
Default: "several".
Whether merlin should print the type of the expected parameter when completing
in an application context.
Possible options are:
>
  " always show the expected type
  let g:merlin_completion_arg_type = "always"

  " only show the expected type when there are more than one candidate
  let g:merlin_completion_arg_type = "several"

  " never show the expected type
  let g:merlin_completion_arg_type = "never"
<


                                                   *'merlin_locate_preference'*
Default: "ml".
Specifies whether you'd prefer |:MerlinLocate| and |:MerlinILocate| to take you
to .ml or .mli files. >
    let g:merlin_locate_preference = 'mli'
<
                                         *'merlin_disable_default_keybindings'*
Default: false.
Specifies whether merlin should skip setting default keybindings.
>
    let g:merlin_disable_default_keybindings = 1
<
                                                        *'merlin_split_method'*
Default: "horizontal".
Specifies how the layout should be adjusted to display the result of a
locate query (the target file and line).
Possible values are:
>
  " Layout is never split, target is displayed in current window
  let g:merlin_split_method = "never"

  " Target is displayed in a new tab
  let g:merlin_split_method = "tab"

  " Target is displayed in a new horizontal split
  let g:merlin_split_method = "horizontal"

  " Target is displayed in a new vertical split
  let g:merlin_split_method = "vertical"

  " If the target is in the same file, the current window is used by default.
  " You can prepend "always" to force a layout split.
  let g:merlin_split_method = "always tab"
  let g:merlin_split_method = "always horizontal"
  let g:merlin_split_method = "always vertical"
< 

==============================================================================
EXTRAS                                                         *merlin-extras*

Type-on-hover~

To display the type of the ocaml expression at the current mouse cursor, use Vim's |ballon-eval|
functionality: >
    au FileType ocaml setlocal balloonexpr=merlin#TypeAtBalloon()
displays the type in a small popup. Alternatively, >
    au FileType ocaml setlocal balloonexpr=merlin#ShowTypeAtBalloon()
displays the type in the status line, similar to |MerlinTypeOf|. To switch
this feature on, use >
    set balloonveval
when using a GUI version of Vim or >
    set balloonvevalterm 
in a terminal.


Syntastic ~

To use merlin with syntastic set the following option: >
    let g:syntastic_ocaml_checkers=['merlin']
<

Neocomplcache ~

(Note that Neocomplcache has been superseded by Neocomplete
    in later versions of Vim)
Integration with [neocomplcache](https://github.com/Shougo/neocomplcache)
for automatic completion can be enabled with: >

    if !exists('g:neocomplcache_force_omni_patterns')
      let g:neocomplcache_force_omni_patterns = {}
    endif
    let g:neocomplcache_force_omni_patterns.ocaml = '[^. *\t]\.\w*\|\h\w*|#'


Neocomplete ~

Integration with [neocomplete](https://github.com/Shougo/neocomplete) for
automatic completion can be enabled with: >

    if !exists('g:neocomplete#sources#omni#input_patterns')
      let g:neocomplete#sources#omni#input_patterns = {}
    endif
    let g:neocomplete#sources#omni#input_patterns.ocaml = '[^. *\t]\.\w*\|\h\w*|#'


Deoplete ~

Integration with [deoplete](https://github.com/Shougo/deoplete.nvim)
for automatic, asynchronous completion with NeoVim can be enabled with: >

    if !exists('g:deoplete#omni_patterns')
      let g:deoplete#omni#input_patterns = {}
    endif
    let g:deoplete#omni#input_patterns.ocaml = '[^. *\t]\.\w*|\s\w*|#'

Supertab ~

People using Supertab can do: >
    au FileType ocaml call SuperTabSetDefaultCompletionType("<c-x><c-o>")
<

As suggested in the Supertab documentation.

CtrlP ~

Some "interactive" commands (|:MerlinIlocate|, |:MerlinOutline|) depend on
[ctrlp](https://github.com/ctrlpvim/ctrlp.vim).
If the plugin is installed, they will work out of the box.

Contact us ~

If you have any comment, question or bug to report, you can contact us through
github : https://github.com/ocaml/merlin/issues

 vim:tw=78:et:ft=help:norl:
