neovim/runtime/doc/develop.txt

*develop.txt*          Nvim


                            NVIM REFERENCE MANUAL


Development of Nvim					*development* *dev*

This reference describes design constraints and guidelines, for developing
Nvim applications or Nvim itself.
Architecture and internal concepts are covered in src/nvim/README.md

Nvim is free and open source.  Everybody is encouraged to contribute.
    https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md

                                      Type |gO| to see the table of contents.

==============================================================================
Design goals						*design-goals*

Most important things come first (roughly).  Some items conflict; this is
intentional.  A balance must be found.


NVIM IS... IMPROVED					*design-improved*

The Neo bits of Nvim should make it a better Vim, without becoming a
completely different editor.
- In matters of taste, prefer Vim/Unix tradition. If there is no relevant
  Vim/Unix tradition, consider the "common case".
- A feature that people do not know about is a useless feature.  Don't add
  obscure features, or at least add hints in documentation that they exist.
- There is no limit to the features that can be added.  Selecting new features
  is based on (1) what users ask for, (2) how much effort it takes to
  implement and (3) someone actually implementing it.
- Backwards compatibility is a feature.  The RPC API in particular should
  never break.


NVIM IS... WELL DOCUMENTED				*design-documented*

- A feature that isn't documented is a useless feature.  A patch for a new
  feature must include the documentation.
- Documentation should be comprehensive and understandable.  Use examples.
- Don't make the text unnecessarily long.  Less documentation means that an
  item is easier to find.


NVIM IS... HIGH SPEED AND SMALL IN SIZE			*design-speed-size*

Keep Nvim small and fast.
- Computers are becoming faster and bigger each year.  Vim can grow too, but
  no faster than computers are growing.  Keep Vim usable on older systems.
- Many users start Vim from a shell very often.  Startup time must be short.
- Commands must work efficiently.  The time they consume must be as small as
  possible.  Useful commands may take longer.
- Don't forget that some people use Vim over a slow connection.  Minimize the
  communication overhead.
- Vim is a component among other components.  Don't turn it into a massive
  application, but have it work well together with other programs.


NVIM IS... MAINTAINABLE					*design-maintain*

- The source code should not become a mess.  It should be reliable code.
- Use comments in a useful way!  Quoting the function name and argument names
  is NOT useful.  Do explain what they are for.
- Porting to another platform should be made easy, without having to change
  too much platform-independent code.
- Use the object-oriented spirit: Put data and code together.  Minimize the
  knowledge spread to other parts of the code.


NVIM IS... NOT						*design-not*

Nvim is not an operating system; instead it should be composed with other
tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
include the kitchen sink... but it's good for plumbing."


==============================================================================
Developer guidelines				        *dev-guidelines*


PROVIDERS 						*dev-provider*

A goal of Nvim is to allow extension of the editor without special knowledge
in the core. But some Vim components are too tightly coupled; in those cases
a "provider" hook is exposed.

Consider two examples of integration with external systems that are
implemented in Vim and are now decoupled from Nvim core as providers:

1. In the Vim source code, clipboard logic accounts for more than 1k lines of
   C source code (ui.c), to perform two tasks that are now accomplished with
   shell commands such as xclip or pbcopy/pbpaste.

2. Python scripting support: Vim has three files dedicated to embedding the
   Python interpreter: if_python.c, if_python3.c and if_py_both.h. Together
   these files sum about 9.5k lines of C source code. In contrast, Nvim Python
   scripting is performed by an external host process implemented in ~2k lines
   of Python.

Ideally we could implement Python and clipboard integration in pure vimscript
and without touching the C code. But this is infeasible without compromising
backwards compatibility with Vim; that's where providers help.

The provider framework helps call vimscript from C. It is composed of two
functions in eval.c:

- eval_call_provider(name, method, arguments): calls provider#(name)#Call
  with the method and arguments.
- eval_has_provider(name): Checks if a provider is implemented. Returns true
  if the provider#(name)#Call function is implemented. Called by |has()|
  (vimscript) to check if features are available.

The provider#(name)#Call function implements integration with an external
system, because shell commands and |RPC| clients are easier to work with in
vimscript.

For example, the Python provider is implemented by the
autoload/provider/python.vim script; the provider#python#Call function is only
defined if a valid external Python host is found. That works well with the
`has('python')` expression (normally used by Python plugins) because if the
Python host isn't installed then the plugin will "think" it is running in
a Vim compiled without the |+python| feature.

DOCUMENTATION						*dev-doc*

- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to document
  differences from Vim; no other distinction is necessary.
- If a Vim feature is removed, delete its help section and move its tag to
  |vim_diff.txt|.
- Move deprecated features to |deprecated.txt|.
- Use consistent language.
    - "terminal" in a help tag always means "the embedded terminal emulator", not
      "the user host terminal".
    - Use "tui-" to prefix help tags related to the host terminal, and "TUI"
      in prose if possible.
- Docstrings: do not start parameter descriptions with "The" or "A" unless it
  is critical to avoid ambiguity.
      GOOD: >
      /// @param dirname Path fragment before `pend`
<      BAD: >
      /// @param dirname The path fragment before `pend`
<

API							*dev-api*

Use this template to name new API functions:
    nvim_{thing}_{action}_{arbitrary-qualifiers}

If the function acts on an object then {thing} is the name of that object
(e.g. "buf" or "win"). If the function operates in a "global" context then
{thing} is usually omitted (but consider "namespacing" your global operations
with a {thing} that groups functions under a common concept).

Use existing common {action} names if possible:
    add   Append to, or insert into, a collection
    get   Get a thing (or subset of things by some query)
    set   Set a thing
    del   Delete a thing (or group of things)
    list  Get all things

Use consistent names for {thing} in all API functions. E.g. a buffer is called
"buf" everywhere, not "buffer" in some places and "buf" in others.

Example: `nvim_get_current_line` acts on the global editor state; the common
{action} "get" is used but {thing} is omitted.

Example: `nvim_buf_add_highlight` acts on a `Buffer` object (the first
parameter) and uses the common {action} "add".

Example: `nvim_list_bufs` operates in a global context (first parameter is
_not_ a Buffer). The common {action} "list" indicates that it lists all
bufs (plural) in the global context.

Use this template to name new API events:
    nvim_{thing}_{event}_event

Example: `nvim_buf_changedtick_event`.


API-CLIENT						*dev-api-client*

Standard Features ~

- 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:
        GOOD: nvim-racket
        GOOD: pynvim
        BAD:  python-client
        BAD:  neovim

Implementation ~

For C/C++ projects, consider libmpack instead of the msgpack.org library.
    https://github.com/libmpack/libmpack/
libmpack is small (no dependencies, can inline into your C/C++ project) and
efficient (no allocations). It also implements msgpack-RPC, the protocol
required by Nvim.
    https://github.com/msgpack-rpc/msgpack-rpc

EXTERNAL UI 						*dev-ui*

External UIs should be aware of the |api-contract|. In particular, future
versions of Nvim may add new items to existing events. The API is strongly
backwards-compatible, but clients must not break if new (optional) fields are
added to existing events.

Standard Features ~

External UIs are expected to implement these common features:

- Call |nvim_set_client_info()| after connecting, so users and plugins can
  detect the UI by handling the |ChanInfo| event. This avoids the need for
  special variables and UI-specific config files (gvimrc, macvimrc, …).
- Cursor style (shape, color) should conform to the 'guicursor' properties
  delivered with the mode_info_set UI event.
- Send the ALT/META ("Option" on macOS) key as a |<M-| chord.
- Send the "super" key (Windows key, Apple key) as a |<D-| chord.
- Avoid mappings that conflict with the Nvim keymap-space; GUIs have many new
  chords (<C-,> <C-Enter> <C-S-x> <D-x>) and patterns ("shift shift") that do
  not potentially conflict with Nvim defaults, plugins, etc.
- Consider the "option_set" |ui-global| event as a hint for other GUI
  behaviors. UI-related options ('guifont', 'ambiwidth', …) are published in
  this event.


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