Home • Explore • Blog • CI
☰



neovim
9th chunk of `runtime/doc/develop.txt`
84f2759932c538f745c894a410f8dc3ab3f660f99d3f2bc10000000100000a18
 documentation, tests, boilerplate, and interfaces, which users must
comprehend, maintainers must maintain, etc. Thus the following is NOT
recommended (compare these 12(!) functions to the above 3 functions): >

    nvim_add_ns(…)
    nvim_buf_add_ns(…)
    nvim_win_add_ns(…)
    nvim_tabpage_add_ns(…)
    nvim_del_ns(…)
    nvim_buf_del_ns(…)
    nvim_win_del_ns(…)
    nvim_tabpage_del_ns(…)
    nvim_get_ns(…)
    nvim_buf_get_ns(…)
    nvim_win_get_ns(…)
    nvim_tabpage_get_ns(…)

API-CLIENT                                              *dev-api-client*

                                                        *api-client*
API clients wrap the Nvim |API| to provide idiomatic "SDKs" for their
respective platforms (see |jargon|). You can build a new API client for your
favorite platform or programming language.

List of API clients:
    https://github.com/neovim/neovim/wiki/Related-projects#api-clients

                                                        *node-client* *pynvim*
These clients can be considered the "reference implementation" for API clients:
- https://github.com/neovim/node-client
- https://github.com/neovim/pynvim

Standard Features ~

- API clients exist to hide msgpack-rpc details. The wrappers can be
  automatically generated by reading the |api-metadata| from Nvim. |api-mapping|
- Clients should call |nvim_set_client_info()| after connecting, so users and
  plugins can detect the client by handling the |ChanInfo| event. This avoids
  the need for special variables or other client hints.
- Clients should handle |nvim_error_event| notifications, which will be sent
  if an async request to nvim was rejected or caused an error.

Package Naming ~

API client packages should NOT be named something ambiguous like "neovim" or
"python-client".  Use "nvim" as a prefix/suffix to some other identifier
following ecosystem conventions.

For example, Python packages tend to have "py" in the name, so "pynvim" is
a good name: it's idiomatic and unambiguous. If the package is named "neovim",
it confuses users, and complicates documentation and discussions.

Examples of API-client package names:
- ✅ OK: nvim-racket
- ✅ OK: pynvim
- ❌ NO: python-client
- ❌ NO: neovim_

API client implementation guidelines ~

- Separate the transport layer from the rest of the library. |rpc-connecting|
- Use a MessagePack library that implements at least version 5 of the
  MessagePack spec, which supports the BIN and EXT types used by Nvim.
- Use a single-threaded event loop library/pattern.
- Use a fiber/coroutine library
Title: API Clients: Wrapping the Neovim API
Summary
This section discourages creating separate functions for 'nvim_xx', 'nvim_buf_xx', 'nvim_win_xx', and 'nvim_tabpage_xx' for the same topic, as it leads to increased complexity. It then introduces API clients, which wrap the Neovim API to provide idiomatic SDKs for various platforms. It lists reference implementations and outlines standard features such as hiding msgpack-rpc details, calling 'nvim_set_client_info()', and handling 'nvim_error_event' notifications. The section also provides guidelines for package naming and implementation, emphasizing the importance of unambiguous naming conventions and recommending separation of the transport layer, using a MessagePack library that implements at least version 5, and employing a single-threaded event loop.