2017-03-21 17:13:51 -07:00
|
|
|
*develop.txt* Nvim
|
2014-07-10 21:05:51 -07:00
|
|
|
|
|
|
|
|
2016-06-12 23:11:12 -07:00
|
|
|
NVIM REFERENCE MANUAL
|
2014-07-10 21:05:51 -07:00
|
|
|
|
|
|
|
|
2019-01-10 17:20:15 -07:00
|
|
|
Development of Nvim *development* *dev*
|
2014-07-10 21:05:51 -07:00
|
|
|
|
2018-11-15 18:00:04 -07:00
|
|
|
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
|
2014-07-10 21:05:51 -07:00
|
|
|
|
2018-11-15 18:00:04 -07:00
|
|
|
Nvim is free and open source. Everybody is encouraged to contribute.
|
|
|
|
https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
|
2016-06-14 20:12:43 -07:00
|
|
|
|
2017-10-20 17:33:58 -07:00
|
|
|
Type |gO| to see the table of contents.
|
2017-05-01 08:09:29 -07:00
|
|
|
|
2014-07-10 21:05:51 -07:00
|
|
|
==============================================================================
|
2017-04-17 14:52:38 -07:00
|
|
|
Design goals *design-goals*
|
2014-07-10 21:05:51 -07:00
|
|
|
|
2018-11-15 18:00:04 -07:00
|
|
|
Most important things come first (roughly). Some items conflict; this is
|
|
|
|
intentional. A balance must be found.
|
2014-07-10 21:05:51 -07:00
|
|
|
|
|
|
|
|
2016-06-12 23:11:12 -07:00
|
|
|
NVIM IS... IMPROVED *design-improved*
|
2014-07-10 21:05:51 -07:00
|
|
|
|
2018-09-05 15:58:10 -07:00
|
|
|
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".
|
2022-12-11 19:41:26 -07:00
|
|
|
- There is no limit to the features that can be added. Select new features
|
|
|
|
based on (1) what users ask for, (2) how much effort it takes to implement
|
|
|
|
and (3) someone actually implementing it.
|
2018-09-05 15:58:10 -07:00
|
|
|
- Backwards compatibility is a feature. The RPC API in particular should
|
|
|
|
never break.
|
2014-07-10 21:05:51 -07:00
|
|
|
|
|
|
|
|
2016-06-12 23:11:12 -07:00
|
|
|
NVIM IS... WELL DOCUMENTED *design-documented*
|
2014-07-10 21:05:51 -07:00
|
|
|
|
|
|
|
- A feature that isn't documented is a useless feature. A patch for a new
|
|
|
|
feature must include the documentation.
|
2017-04-17 14:52:38 -07:00
|
|
|
- Documentation should be comprehensive and understandable. Use examples.
|
2014-07-10 21:05:51 -07:00
|
|
|
- Don't make the text unnecessarily long. Less documentation means that an
|
|
|
|
item is easier to find.
|
|
|
|
|
|
|
|
|
2021-08-21 18:26:33 -07:00
|
|
|
NVIM IS... FAST AND SMALL *design-speed-size*
|
2014-07-10 21:05:51 -07:00
|
|
|
|
2022-12-11 19:41:26 -07:00
|
|
|
Keep Nvim small and fast. This directly affects versatility and usability.
|
2014-07-10 21:05:51 -07:00
|
|
|
- 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
|
2022-12-11 19:41:26 -07:00
|
|
|
application, but have it work well together with other programs
|
|
|
|
("composability").
|
2014-07-10 21:05:51 -07:00
|
|
|
|
|
|
|
|
2016-06-12 23:11:12 -07:00
|
|
|
NVIM IS... MAINTAINABLE *design-maintain*
|
2014-07-10 21:05:51 -07:00
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
2015-01-14 00:02:39 -07:00
|
|
|
NVIM IS... NOT *design-not*
|
|
|
|
|
2016-06-14 20:12:43 -07:00
|
|
|
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
|
2017-04-17 14:52:38 -07:00
|
|
|
include the kitchen sink... but it's good for plumbing."
|
2015-01-14 00:02:39 -07:00
|
|
|
|
2014-07-10 21:05:51 -07:00
|
|
|
|
|
|
|
==============================================================================
|
2019-01-10 17:20:15 -07:00
|
|
|
Developer guidelines *dev-guidelines*
|
2014-07-10 21:05:51 -07:00
|
|
|
|
2017-04-17 14:52:38 -07:00
|
|
|
|
2023-02-21 09:07:26 -07:00
|
|
|
PROVIDERS *dev-provider*
|
2016-06-14 22:20:08 -07:00
|
|
|
|
2019-08-03 18:54:06 -07:00
|
|
|
A primary goal of Nvim is to allow extension of the editor without special
|
|
|
|
knowledge in the core. Some core functions are delegated to "providers"
|
|
|
|
implemented as external scripts.
|
2016-06-14 22:20:08 -07:00
|
|
|
|
2019-08-03 18:54:06 -07:00
|
|
|
Examples:
|
2016-06-14 22:20:08 -07:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2023-06-22 03:44:51 -07:00
|
|
|
The provider framework invokes Vimscript from C. It is composed of two
|
|
|
|
functions in eval.c:
|
2016-06-14 22:20:08 -07:00
|
|
|
|
2023-12-28 05:49:44 -07:00
|
|
|
- eval_call_provider({name}, {method}, {arguments}, {discard}): Calls
|
|
|
|
`provider#{name}#Call` with {method} and {arguments}. If {discard} is true, any
|
2020-09-01 20:22:42 -07:00
|
|
|
value returned by the provider will be discarded and empty value will be
|
|
|
|
returned.
|
2023-12-28 05:49:44 -07:00
|
|
|
- eval_has_provider({name}): Checks the `g:loaded_{name}_provider` variable
|
2019-08-04 03:06:24 -07:00
|
|
|
which must be set to 2 by the provider script to indicate that it is
|
|
|
|
"enabled and working". Called by |has()| to check if features are available.
|
2016-06-14 22:20:08 -07:00
|
|
|
|
|
|
|
For example, the Python provider is implemented by the
|
2019-08-03 18:54:06 -07:00
|
|
|
"autoload/provider/python.vim" script, which sets `g:loaded_python_provider`
|
2019-08-04 03:06:24 -07:00
|
|
|
to 2 only if a valid external Python host is found. Then `has("python")`
|
2019-08-03 18:54:06 -07:00
|
|
|
reflects whether Python support is working.
|
|
|
|
|
|
|
|
*provider-reload*
|
|
|
|
Sometimes a GUI or other application may want to force a provider to
|
|
|
|
"reload". To reload a provider, undefine its "loaded" flag, then use
|
2022-11-22 10:41:00 -07:00
|
|
|
|:runtime| to reload it: >vim
|
2019-08-03 18:54:06 -07:00
|
|
|
|
|
|
|
:unlet g:loaded_clipboard_provider
|
|
|
|
:runtime autoload/provider/clipboard.vim
|
|
|
|
|
2016-06-14 22:20:08 -07:00
|
|
|
|
2017-03-14 16:12:21 -07:00
|
|
|
DOCUMENTATION *dev-doc*
|
|
|
|
|
2021-08-27 03:59:13 -07:00
|
|
|
- "Just say it". Avoid mushy, colloquial phrasing in all documentation
|
|
|
|
(docstrings, user manual, website materials, newsletters, …). Don't mince
|
|
|
|
words. Personality and flavor, used sparingly, are welcome--but in general,
|
|
|
|
optimize for the reader's time and energy: be "precise yet concise".
|
|
|
|
- Prefer the active voice: "Foo does X", not "X is done by Foo".
|
2023-06-19 02:24:44 -07:00
|
|
|
- "The words you choose are an essential part of the user experience."
|
2023-07-12 10:27:14 -07:00
|
|
|
https://developer.apple.com/design/human-interface-guidelines/writing
|
2023-06-19 02:24:44 -07:00
|
|
|
- "...without being overly colloquial or frivolous."
|
|
|
|
https://developers.google.com/style/tone
|
|
|
|
- Write docstrings (as opposed to inline comments) with present tense ("Gets"),
|
|
|
|
not imperative ("Get"). This tends to reduce ambiguity and improve clarity
|
|
|
|
by describing "What" instead of "How". >
|
2022-12-14 11:58:18 -07:00
|
|
|
GOOD:
|
|
|
|
/// Gets a highlight definition.
|
|
|
|
BAD:
|
|
|
|
/// Get a highlight definition.
|
|
|
|
- Avoid starting docstrings with "The" or "A" unless needed to avoid
|
|
|
|
ambiguity. This is a visual aid and reduces noise. >
|
|
|
|
GOOD:
|
|
|
|
/// @param dirname Path fragment before `pend`
|
|
|
|
BAD:
|
|
|
|
/// @param dirname The path fragment before `pend`
|
2021-08-27 03:59:13 -07:00
|
|
|
- Vim differences:
|
|
|
|
- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
|
|
|
|
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|.
|
|
|
|
- Mention deprecated features in |deprecated.txt| and delete their old doc.
|
2017-03-14 16:12:21 -07:00
|
|
|
- Use consistent language.
|
2021-08-27 03:59:13 -07:00
|
|
|
- "terminal" in a help tag always means "the embedded terminal emulator",
|
|
|
|
not "the user host terminal".
|
2017-03-14 16:12:21 -07:00
|
|
|
- Use "tui-" to prefix help tags related to the host terminal, and "TUI"
|
|
|
|
in prose if possible.
|
2016-06-14 22:20:08 -07:00
|
|
|
|
2022-09-24 17:20:47 -07:00
|
|
|
Documentation format ~
|
|
|
|
|
|
|
|
For Nvim-owned docs, use the following strict subset of "vimdoc" to ensure
|
|
|
|
the help doc renders nicely in other formats (such as HTML:
|
|
|
|
https://neovim.io/doc/user ).
|
|
|
|
|
|
|
|
Strict "vimdoc" subset:
|
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
- Use lists (like this!) prefixed with "-" or "•", for adjacent lines that you
|
|
|
|
don't want to auto-wrap. Lists are always rendered with "flow" layout
|
|
|
|
(soft-wrapped) instead of preformatted (hard-wrapped) layout common in
|
|
|
|
legacy :help docs.
|
2022-10-09 09:19:43 -07:00
|
|
|
- Limitation: currently the parser https://github.com/neovim/tree-sitter-vimdoc
|
|
|
|
does not understand numbered listitems, so use a bullet symbol (- or •)
|
2022-12-14 11:58:18 -07:00
|
|
|
before numbered items, e.g. "• 1." instead of "1.".
|
|
|
|
- Separate blocks (paragraphs) of content by a blank line.
|
2022-09-24 17:20:47 -07:00
|
|
|
- Do not use indentation in random places—that prevents the page from using
|
|
|
|
"flow" layout. If you need a preformatted section, put it in
|
|
|
|
a |help-codeblock| starting with ">".
|
|
|
|
|
2019-10-27 15:05:59 -07:00
|
|
|
C docstrings ~
|
|
|
|
|
|
|
|
Nvim API documentation lives in the source code, as docstrings (Doxygen
|
|
|
|
comments) on the function definitions. The |api| :help is generated
|
|
|
|
from the docstrings defined in src/nvim/api/*.c.
|
|
|
|
|
|
|
|
Docstring format:
|
|
|
|
- Lines start with `///`
|
|
|
|
- Special tokens start with `@` followed by the token name:
|
|
|
|
`@note`, `@param`, `@returns`
|
|
|
|
- Limited markdown is supported.
|
|
|
|
- List-items start with `-` (useful to nest or "indent")
|
2023-09-13 06:38:28 -07:00
|
|
|
- Use ``` for code samples.
|
2022-11-23 04:31:49 -07:00
|
|
|
Code samples can be annotated as `vim` or `lua`
|
2019-10-27 15:05:59 -07:00
|
|
|
|
|
|
|
Example: the help for |nvim_open_win()| is generated from a docstring defined
|
2021-10-04 19:10:07 -07:00
|
|
|
in src/nvim/api/win_config.c like this: >
|
2019-10-27 15:05:59 -07:00
|
|
|
|
|
|
|
/// Opens a new window.
|
|
|
|
/// ...
|
|
|
|
///
|
|
|
|
/// Example (Lua): window-relative float
|
2023-09-13 06:38:28 -07:00
|
|
|
///
|
|
|
|
/// ```lua
|
|
|
|
/// vim.api.nvim_open_win(0, false, {
|
|
|
|
/// relative='win',
|
|
|
|
/// row=3,
|
|
|
|
/// col=3,
|
|
|
|
/// width=12,
|
|
|
|
/// height=3,
|
|
|
|
/// })
|
|
|
|
/// ```
|
2019-10-27 15:05:59 -07:00
|
|
|
///
|
|
|
|
/// @param buffer Buffer to display
|
|
|
|
/// @param enter Enter the window
|
|
|
|
/// @param config Map defining the window configuration. Keys:
|
|
|
|
/// - relative: Sets the window layout, relative to:
|
|
|
|
/// - "editor" The global editor grid.
|
|
|
|
/// - "win" Window given by the `win` field.
|
|
|
|
/// - "cursor" Cursor position in current window.
|
|
|
|
/// ...
|
|
|
|
/// @param[out] err Error details, if any
|
|
|
|
///
|
|
|
|
/// @return Window handle, or 0 on error
|
|
|
|
|
|
|
|
|
|
|
|
Lua docstrings ~
|
|
|
|
*dev-lua-doc*
|
|
|
|
Lua documentation lives in the source code, as docstrings on the function
|
|
|
|
definitions. The |lua-vim| :help is generated from the docstrings.
|
|
|
|
|
|
|
|
Docstring format:
|
2023-09-15 00:43:48 -07:00
|
|
|
- Use LuaCATS annotations: https://luals.github.io/wiki/annotations/
|
2019-10-27 15:05:59 -07:00
|
|
|
- Limited markdown is supported.
|
|
|
|
- List-items start with `-` (useful to nest or "indent")
|
2023-09-14 06:23:01 -07:00
|
|
|
- Use ``` for code samples.
|
2022-11-23 04:31:49 -07:00
|
|
|
Code samples can be annotated as `vim` or `lua`
|
2023-07-18 07:42:30 -07:00
|
|
|
- Use `@nodoc` to prevent documentation generation.
|
|
|
|
- Files which has `@meta` are only used for typing and documentation.
|
2019-10-27 15:05:59 -07:00
|
|
|
|
|
|
|
Example: the help for |vim.paste()| is generated from a docstring decorating
|
2022-03-06 06:16:21 -07:00
|
|
|
vim.paste in runtime/lua/vim/_editor.lua like this: >
|
2019-10-27 15:05:59 -07:00
|
|
|
|
|
|
|
--- Paste handler, invoked by |nvim_paste()| when a conforming UI
|
|
|
|
--- (such as the |TUI|) pastes text into the editor.
|
|
|
|
---
|
|
|
|
--- Example: To remove ANSI color codes when pasting:
|
2023-09-14 06:23:01 -07:00
|
|
|
---
|
|
|
|
--- ```lua
|
2019-10-27 15:05:59 -07:00
|
|
|
--- vim.paste = (function()
|
|
|
|
--- local overridden = vim.paste
|
|
|
|
--- ...
|
|
|
|
--- end)()
|
2023-09-14 06:23:01 -07:00
|
|
|
--- ```
|
2019-10-27 15:05:59 -07:00
|
|
|
---
|
2023-09-27 21:57:22 -07:00
|
|
|
--- @see |paste|
|
2019-10-27 15:05:59 -07:00
|
|
|
---
|
2023-09-27 21:57:22 -07:00
|
|
|
--- @param lines ...
|
|
|
|
--- @param phase ...
|
|
|
|
--- @returns false if client should cancel the paste.
|
2019-10-27 15:05:59 -07:00
|
|
|
|
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
LUA STDLIB DESIGN GUIDELINES *dev-lua*
|
|
|
|
|
|
|
|
See also |dev-naming|.
|
2019-10-27 15:05:59 -07:00
|
|
|
|
|
|
|
- Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
|
2022-12-11 19:41:26 -07:00
|
|
|
pseudo-OOP designs. Plugin authors just want functions to call, not a big,
|
|
|
|
fancy inheritance hierarchy.
|
|
|
|
- Avoid requiring or returning special objects in the Nvim stdlib. Plain
|
|
|
|
tables or values are easier to serialize, easier to construct from literals,
|
|
|
|
easier to inspect and print, and inherently compatible with all Lua plugins.
|
|
|
|
(This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.)
|
2022-12-14 11:58:18 -07:00
|
|
|
- stdlib functions should follow these common patterns:
|
|
|
|
- accept iterable instead of table
|
|
|
|
- exception: in some cases iterable doesn't make sense, e.g. spair() sorts
|
|
|
|
the input by definition, so there is no reason for it to accept an
|
|
|
|
iterable, because the input needs to be "hydrated", it can't operate on
|
|
|
|
a "stream".
|
|
|
|
- return iterable instead of table
|
|
|
|
- mimic the pairs() or ipairs() interface if the function is intended to be
|
|
|
|
used in a "for" loop.
|
|
|
|
|
2023-06-19 02:24:44 -07:00
|
|
|
Interface conventions ~
|
|
|
|
|
|
|
|
- When accepting a buffer id, etc., 0 means "current buffer", nil means "all
|
|
|
|
buffers". Likewise for window id, tabpage id, etc.
|
|
|
|
- Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()|
|
2023-11-25 07:35:31 -07:00
|
|
|
- Any function signature that accepts a callback function should define the
|
|
|
|
callback as the LAST parameter, if possible. This improves readability of
|
|
|
|
calls by placing the less "noisy" arguments near the start. >
|
|
|
|
GOOD:
|
|
|
|
filter(table, opts, function() … end)
|
|
|
|
BAD:
|
|
|
|
filter(function() … end, table, opts)
|
2022-12-14 11:58:18 -07:00
|
|
|
|
|
|
|
API DESIGN GUIDELINES *dev-api*
|
|
|
|
|
|
|
|
See also |dev-naming|.
|
|
|
|
|
|
|
|
- When adding an API, check the following:
|
|
|
|
- What precedents did you draw from? How does your solution compare to them?
|
|
|
|
- Does your new API allow future expansion? How? Or why not?
|
|
|
|
- Is the new API similar to existing APIs? Do we need to deprecate the old ones?
|
|
|
|
- Did you cross-reference related concepts in the docs?
|
2022-12-11 19:41:26 -07:00
|
|
|
- Avoid "mutually exclusive" parameters--via constraints or limitations, if
|
|
|
|
necessary. For example nvim_create_autocmd() has mutually exclusive
|
|
|
|
"callback" and "command" args; but the "command" arg could be eliminated by
|
|
|
|
simply not supporting Vimscript function names, and treating a string
|
|
|
|
"callback" arg as an Ex command (which can call Vimscript functions). The
|
|
|
|
"buffer" arg could also be eliminated by treating a number "pattern" as
|
|
|
|
a buffer number.
|
2022-12-14 11:58:18 -07:00
|
|
|
- Avoid functions that depend on cursor position, current buffer, etc. Instead
|
|
|
|
the function should take a position parameter, buffer parameter, etc.
|
2022-12-11 19:41:26 -07:00
|
|
|
|
2023-09-20 04:15:23 -07:00
|
|
|
Where things go ~
|
|
|
|
|
|
|
|
- API (libnvim/RPC): exposes low-level internals, or fundamental things (such
|
|
|
|
as `nvim_exec_lua()`) needed by clients or C consumers.
|
|
|
|
- Lua stdlib = high-level functionality that builds on top of the API.
|
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
NAMING GUIDELINES *dev-naming*
|
2022-10-09 05:21:52 -07:00
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
Naming is exceedingly important: the name of a thing is the primary interface
|
|
|
|
for uses it, discusses it, searches for it, shares it... Consistent
|
|
|
|
naming in the stdlib, API, and UI helps both users and developers discover and
|
|
|
|
intuitively understand related concepts ("families"), and reduces cognitive
|
|
|
|
burden. Discoverability encourages code re-use and likewise avoids redundant,
|
|
|
|
overlapping mechanisms, which reduces code surface-area, and thereby minimizes
|
|
|
|
bugs...
|
2016-09-16 21:30:36 -07:00
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
Naming conventions ~
|
|
|
|
|
|
|
|
In general, look for precedent when choosing a name, that is, look at existing
|
|
|
|
(non-deprecated) functions. In particular, see below...
|
|
|
|
|
|
|
|
*dev-name-common*
|
|
|
|
Use existing common {verb} names (actions) if possible:
|
|
|
|
- add: Appends or inserts into a collection
|
|
|
|
- attach: Listens to something to get events from it (TODO: rename to "on"?)
|
|
|
|
- call: Calls a function
|
|
|
|
- clear: Clears state but does not destroy the container
|
|
|
|
- create: Creates a new (non-trivial) thing (TODO: rename to "def"?)
|
|
|
|
- del: Deletes a thing (or group of things)
|
|
|
|
- detach: Dispose attached listener (TODO: rename to "un"?)
|
|
|
|
- eval: Evaluates an expression
|
|
|
|
- exec: Executes code
|
|
|
|
- fmt: Formats
|
|
|
|
- get: Gets things (often by a query)
|
|
|
|
- inspect: Presents a high-level, often interactive, view
|
|
|
|
- open: Opens something (a buffer, window, …)
|
|
|
|
- parse: Parses something into a structured form
|
|
|
|
- set: Sets a thing (or group of things)
|
|
|
|
- try_{verb}: Best-effort operation, failure returns null or error obj
|
2022-10-09 05:21:52 -07:00
|
|
|
|
|
|
|
Do NOT use these deprecated verbs:
|
2022-12-14 11:58:18 -07:00
|
|
|
- list: Redundant with "get"
|
|
|
|
- show: Redundant with "print", "echo"
|
|
|
|
- notify: Redundant with "print", "echo"
|
2022-10-09 05:21:52 -07:00
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
Use consistent names for {noun} (nouns) in API functions: buffer is called
|
2016-09-16 21:30:36 -07:00
|
|
|
"buf" everywhere, not "buffer" in some places and "buf" in others.
|
2022-12-14 11:58:18 -07:00
|
|
|
- buf: Buffer
|
|
|
|
- chan: |channel|
|
|
|
|
- cmd: Command
|
|
|
|
- cmdline: Command-line UI or input
|
|
|
|
- fn: Function
|
|
|
|
- hl: Highlight
|
|
|
|
- pos: Position
|
|
|
|
- proc: System process
|
|
|
|
- tabpage: Tabpage
|
|
|
|
- win: Window
|
2022-10-09 05:21:52 -07:00
|
|
|
|
|
|
|
Do NOT use these deprecated nouns:
|
|
|
|
- buffer
|
2023-06-19 02:24:44 -07:00
|
|
|
- callback Use on_foo instead
|
2022-10-09 05:21:52 -07:00
|
|
|
- command
|
|
|
|
- window
|
2016-09-16 21:30:36 -07:00
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
*dev-name-events*
|
|
|
|
Use the "on_" prefix to name event-handling callbacks and also the interface for
|
|
|
|
"registering" such handlers (on_key). The dual nature is acceptable to avoid
|
|
|
|
a confused collection of naming conventions for these related concepts.
|
|
|
|
|
|
|
|
Editor |events| (autocommands) are historically named like: >
|
|
|
|
{Noun}{Event}
|
|
|
|
|
|
|
|
Use this format to name API (RPC) events: >
|
|
|
|
nvim_{noun}_{event-name}_event
|
2016-09-16 21:30:36 -07:00
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
Example: >
|
|
|
|
nvim_buf_changedtick_event
|
|
|
|
<
|
|
|
|
*dev-name-api*
|
|
|
|
Use this format to name new RPC |API| functions: >
|
|
|
|
nvim_{noun}_{verb}_{arbitrary-qualifiers}
|
2016-09-16 21:30:36 -07:00
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
If the function acts on an object then {noun} is the name of that object
|
|
|
|
(e.g. "buf" or "win"). If the function operates in a "global" context then
|
|
|
|
{noun} is usually omitted (but consider "namespacing" your global operations
|
|
|
|
with a {noun} that groups functions under a common concept).
|
2017-12-27 11:30:23 -07:00
|
|
|
|
2022-12-14 11:58:18 -07:00
|
|
|
- Example: `nvim_get_keymap('v')` operates in a global context (first
|
|
|
|
parameter is not a Buffer). The "get" verb indicates that it gets anything
|
|
|
|
matching the given filter parameter. A "list" verb is unnecessary because
|
|
|
|
`nvim_get_keymap('')` (empty filter) returns all items.
|
|
|
|
- Example: `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter)
|
|
|
|
and uses the "del" {verb}.
|
2017-12-27 11:30:23 -07:00
|
|
|
|
2014-07-10 21:05:51 -07:00
|
|
|
|
2017-08-19 05:13:14 -07:00
|
|
|
API-CLIENT *dev-api-client*
|
|
|
|
|
2019-08-25 16:00:58 -07:00
|
|
|
*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
|
|
|
|
|
|
|
|
*pynvim*
|
|
|
|
The Python client is the reference implementation for API clients.
|
|
|
|
https://github.com/neovim/pynvim
|
|
|
|
|
2018-08-04 18:17:08 -07:00
|
|
|
Standard Features ~
|
|
|
|
|
2019-08-25 16:00:58 -07:00
|
|
|
- API clients exist to hide msgpack-rpc details. The wrappers can be
|
|
|
|
automatically generated by reading the |api-metadata| from Nvim. |api-mapping|
|
2018-08-04 18:17:08 -07:00
|
|
|
- Clients should call |nvim_set_client_info()| after connecting, so users and
|
2019-08-25 16:00:58 -07:00
|
|
|
plugins can detect the client by handling the |ChanInfo| event. This avoids
|
|
|
|
the need for special variables or other client hints.
|
2018-12-01 08:44:36 -07:00
|
|
|
- Clients should handle |nvim_error_event| notifications, which will be sent
|
|
|
|
if an async request to nvim was rejected or caused an error.
|
2018-08-04 18:17:08 -07:00
|
|
|
|
2017-08-19 05:13:14 -07:00
|
|
|
Package Naming ~
|
2018-08-04 18:17:08 -07:00
|
|
|
|
2017-08-19 05:13:14 -07:00
|
|
|
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:
|
2022-10-09 05:21:52 -07:00
|
|
|
- GOOD: nvim-racket
|
|
|
|
- GOOD: pynvim
|
|
|
|
- BAD: python-client
|
2023-06-22 03:44:51 -07:00
|
|
|
- BAD: neovim_
|
2017-08-19 05:13:14 -07:00
|
|
|
|
2019-08-25 16:00:58 -07:00
|
|
|
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 for the language being used for implementing
|
|
|
|
a client. These greatly simplify concurrency and allow the library to
|
|
|
|
expose a blocking API on top of a non-blocking event loop without the
|
|
|
|
complexity that comes with preemptive multitasking.
|
|
|
|
- Don't assume anything about the order of responses to RPC requests.
|
|
|
|
- Clients should expect requests, which must be handled immediately because
|
|
|
|
Nvim is blocked while waiting for the client response.
|
|
|
|
- Clients should expect notifications, but these can be handled "ASAP" (rather
|
|
|
|
than immediately) because they won't block Nvim.
|
|
|
|
- For C/C++ projects, consider libmpack instead of the msgpack.org library.
|
2019-01-10 17:20:15 -07:00
|
|
|
https://github.com/libmpack/libmpack/
|
2019-08-25 16:00:58 -07:00
|
|
|
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.
|
2019-01-10 17:20:15 -07:00
|
|
|
https://github.com/msgpack-rpc/msgpack-rpc
|
2017-08-19 05:13:14 -07:00
|
|
|
|
2019-08-25 16:00:58 -07:00
|
|
|
|
2023-02-21 09:07:26 -07:00
|
|
|
EXTERNAL UI *dev-ui*
|
2017-04-17 14:52:38 -07:00
|
|
|
|
|
|
|
External UIs should be aware of the |api-contract|. In particular, future
|
2017-08-19 05:13:14 -07:00
|
|
|
versions of Nvim may add new items to existing events. The API is strongly
|
2018-06-27 15:48:17 -07:00
|
|
|
backwards-compatible, but clients must not break if new (optional) fields are
|
|
|
|
added to existing events.
|
2017-04-17 14:52:38 -07:00
|
|
|
|
2018-08-04 18:17:08 -07:00
|
|
|
Standard Features ~
|
|
|
|
|
2017-08-19 05:13:14 -07:00
|
|
|
External UIs are expected to implement these common features:
|
2018-08-04 18:17:08 -07:00
|
|
|
|
|
|
|
- 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, …).
|
2018-06-27 15:48:17 -07:00
|
|
|
- Cursor style (shape, color) should conform to the 'guicursor' properties
|
2017-08-19 05:13:14 -07:00
|
|
|
delivered with the mode_info_set UI event.
|
2017-12-27 11:30:23 -07:00
|
|
|
- Send the ALT/META ("Option" on macOS) key as a |<M-| chord.
|
2017-08-19 05:13:14 -07:00
|
|
|
- Send the "super" key (Windows key, Apple key) as a |<D-| chord.
|
2018-06-27 15:48:17 -07:00
|
|
|
- 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
|
2019-11-25 09:56:42 -07:00
|
|
|
behaviors. Various UI-related options ('guifont', 'ambiwidth', …) are
|
|
|
|
published in this event. See also "mouse_on", "mouse_off".
|
2023-06-19 08:40:33 -07:00
|
|
|
- UIs generally should NOT set |$NVIM_APPNAME| (unless explicitly requested by
|
|
|
|
the user).
|
2017-04-17 14:52:38 -07:00
|
|
|
|
|
|
|
|
2022-10-09 05:21:52 -07:00
|
|
|
vim:tw=78:ts=8:sw=4:et:ft=help:norl:
|