*api.txt*               Nvim


                 NVIM REFERENCE MANUAL    by Thiago de Arruda


Nvim API                                                           *API* *api*

Nvim exposes a powerful API that can be used by plugins and external processes
via |RPC|, |Lua| and Vimscript (|eval-api|).

Applications can also embed libnvim to work with the C API directly.

                                      Type |gO| to see the table of contents.

==============================================================================
API Usage                                               *api-rpc* *RPC* *rpc*

                                                        *msgpack-rpc*
RPC is the main way to control Nvim programmatically.  Nvim implements the
MessagePack-RPC protocol with these extra (out-of-spec) constraints:

1. Responses must be given in reverse order of requests (like "unwinding
   a stack").
2. Nvim processes all messages (requests and notifications) in the order they
   are received.

MessagePack-RPC specification:
  https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md
  https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md

Many clients use the API: user interfaces (GUIs), remote plugins, scripts like
"nvr" (https://github.com/mhinz/neovim-remote).  Even Nvim itself can control
other Nvim instances.  API clients can:

  - Call any API function
  - Listen for events
  - Receive remote calls from Nvim

The RPC API is like a more powerful version of Vim's "clientserver" feature.

CONNECTING                                              *rpc-connecting*

See |channel-intro| for various ways to open a channel. Channel-opening
functions take an `rpc` key in the options dict. RPC channels can also be
opened by other processes connecting to TCP/IP sockets or named pipes listened
to by Nvim.

Nvim creates a default RPC socket at |startup|, given by |v:servername|. To
start with a TCP/IP socket instead, use |--listen| with a TCP-style address: >
    nvim --listen 127.0.0.1:6666
More endpoints can be started with |serverstart()|.

Note that localhost TCP sockets are generally less secure than named pipes,
and can lead to vulnerabilities like remote code execution.

Connecting to the socket is the easiest way a programmer can test the API,
which can be done through any msgpack-rpc client library or full-featured
|api-client|. Here's a Ruby script that prints "hello world!" in the current
Nvim instance:
>ruby
    #!/usr/bin/env ruby
    # Requires msgpack-rpc: gem install msgpack-rpc
    #
    # To run this script, execute it from a running Nvim instance (notice the
    # trailing '&' which is required since Nvim won't process events while
    # running a blocking command):
    #
    #   :!./hello.rb &
    #
    # Or from another shell by setting NVIM_LISTEN_ADDRESS:
    # $ NVIM_LISTEN_ADDRESS=[address] ./hello.rb

    require 'msgpack/rpc'
    require 'msgpack/rpc/transport/unix'

    nvim = MessagePack::RPC::Client.new(MessagePack::RPC::UNIXTransport.new, ENV['NVIM_LISTEN_ADDRESS'])
    result = nvim.call(:nvim_command, 'echo "hello world!"')
<
A better way is to use the Python REPL with the "pynvim" package, where API
functions can be called interactively:
>
    >>> from pynvim import attach
    >>> nvim = attach('socket', path='[address]')
    >>> nvim.command('echo "hello world!"')
<
You can also embed Nvim via |jobstart()|, and communicate using |rpcrequest()|
and |rpcnotify()|:
>vim
    let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true})
    echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"')
    call jobstop(nvim)
<

==============================================================================
API Definitions                                         *api-definitions*

                                                        *api-types*
The Nvim C API defines custom types for all function parameters. Some are just
typedefs around C99 standard types, others are Nvim-defined data structures.

Basic types ~