mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-20 02:08:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc

Browse Source 
- develop.txt is for design/guidelines; architecture/concepts should
  live elsewhere (currently src/nvim/README.md)
- move dev-jargon to intro.txt
- replace https://neovim.io/community (deprecated) with
  https://neovim.io/#chat
- <Cmd> avoids CmdlineEnter/Leave
  https://github.com/vim/vim/issues/2889
This commit is contained in:
Justin M. Keyes
2018-11-16 02:00:04 +01:00
parent 3348eea429
commit 30857030e8
12 changed files with 134 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
runtime/doc/api.txt
View File

@@ -478,6 +478,9 @@ nvim_err_writeln({str}) *nvim_err_writeln()*
nvim_list_bufs() *nvim_list_bufs()*
Gets the current list of buffer handles
Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use
|nvim_buf_is_loaded()| to check if a buffer is loaded.
Return: ~
List of buffer handles
@@ -529,6 +532,30 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
Parameters: ~
{tabpage} Tabpage handle
nvim_create_namespace({name}) *nvim_create_namespace()*
create a new namespace, or get one with an exisiting name
Namespaces are currently used for buffer highlighting and
virtual text, see |nvim_buf_add_highlight| and
|nvim_buf_set_virtual_text|.
Namespaces can have a name of be anonymous. If `name` is a
non-empty string, and a namespace already exists with that
name,the existing namespace id is returned. If an empty string
is used, a new anonymous namespace is returned.
Parameters: ~
{name} Name of the namespace or empty string
Return: ~
the namespace id
nvim_get_namespaces() *nvim_get_namespaces()*
Get existing named namespaces
Return: ~
dict that maps from names to namespace ids.
nvim_subscribe({event}) *nvim_subscribe()*
Subscribes to event broadcasts
@@ -1082,35 +1109,36 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
(row, col) tuple
*nvim_buf_add_highlight()*
nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
{col_start}, {col_end})
Adds a highlight to buffer.
Useful for plugins that dynamically generate highlights to a
buffer (like a semantic highlighter or linter). The function
adds a single highlight to a buffer. Unlike matchaddpos()
adds a single highlight to a buffer. Unlike |matchaddpos()|
highlights follow changes to line numbering (as lines are
inserted/removed above the highlighted line), like signs and
marks do.
`src_id` is useful for batch deletion/updating of a set of
highlights. When called with `src_id = 0`, an unique source id
is generated and returned. Successive calls can pass that
`src_id` to associate new highlights with the same source
group. All highlights in the same group can be cleared with
`nvim_buf_clear_highlight`. If the highlight never will be
manually deleted, pass `src_id = -1`.
Namespaces are used for batch deletion/updating of a set of
highlights. To create a namespace, use |nvim_create_namespace|
which returns a namespace id. Pass it in to this function as
`ns_id` to add highlights to the namespace. All highlights in
the same namespace can then be cleared with single call to
|nvim_buf_clear_highlight|. If the highlight never will be
deleted by an API call, pass `ns_id = -1`.
If `hl_group` is the empty string no highlight is added, but a
new `src_id` is still returned. This is useful for an external
plugin to synchrounously request an unique `src_id` at
initialization, and later asynchronously add and clear
highlights in response to buffer changes.
As a shorthand, `ns_id = 0` can be used to create a new
namespace for the highlight, the allocated id is then
returned. If `hl_group` is the empty string no highlight is
added, but a new `ns_id` is still returned. This is supported
for backwards compatibility, new code should use
|nvim_create_namespace| to create a new empty namespace.
Parameters: ~
{buffer} Buffer handle
{src_id} Source group to use or 0 to use a new group,
or -1 for ungrouped highlight
{ns_id} namespace to use or -1 for ungrouped
highlight
{hl_group} Name of the highlight group to use
{line} Line to highlight (zero-indexed)
{col_start} Start of (byte-indexed) column range to
@@ -1119,10 +1147,10 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
highlight, or -1 to highlight to end of line
Return: ~
The src_id that was used
The ns_id that was used
*nvim_buf_clear_highlight()*
nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
nvim_buf_clear_highlight({buffer}, {ns_id}, {line_start}, {line_end})
Clears highlights and virtual text from a given source id and
range of lines
@@ -1131,15 +1159,13 @@ nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
Parameters: ~
{buffer} Buffer handle
{src_id} Highlight source group to clear, or -1 to
clear all.
{ns_id} Namespace to clear, or -1 to clear all.
{line_start} Start of range of lines to clear
{line_end} End of range of lines to clear (exclusive)
or -1 to clear to end of file.
*nvim_buf_set_virtual_text()*
nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
{opts})
nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
Set the virtual text (annotation) for a buffer line.
By default (and currently the only option) the text will be
@@ -1149,13 +1175,22 @@ nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
the right of the ordinary text, this will contain the |lcs-
eol| char if set, otherwise just be a space.
The same src_id can be used for both virtual text and
highlights added by nvim_buf_add_highlight. Virtual text is
cleared using nvim_buf_clear_highlight.
Namespaces are used to support batch deletion/updating of
virtual text. To create a namespace, use
|nvim_create_namespace|. Virtual text is cleared using
|nvim_buf_clear_highlight|. The same `ns_id` can be used for
both virtual text and highlights added by
|nvim_buf_add_highlight|, both can then be cleared with a
single call to |nvim_buf_clear_highlight|. If the virtual text
never will be cleared by an API call, pass `src_id = -1`.
As a shorthand, `ns_id = 0` can be used to create a new
namespace for the virtual text, the allocated id is then
returned.
Parameters: ~
{buffer} Buffer handle
{src_id} Source group to use or 0 to use a new group, or
{ns_id} Namespace to use or 0 to create a namespace, or
-1 for a ungrouped annotation
{line} Line to annotate with virtual text (zero-
indexed)
@@ -1166,7 +1201,7 @@ nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
{opts} Optional parameters. Currently not used.
Return: ~
The src_id that was used
The ns_id that was used
==============================================================================
@@ -1181,6 +1216,13 @@ nvim_win_get_buf({window}) *nvim_win_get_buf()*
Return: ~
Buffer handle
nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()*
Sets the current buffer in a window, without side-effects
Parameters: ~
{window} Window handle
{buffer} Buffer handle
nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
Gets the cursor position in the window

18
runtime/doc/autocmd.txt
View File

@@ -526,20 +526,18 @@ CmdlineChanged After a change was made to the text in the
command line. Be careful not to mess up
the command line, it may cause Vim to lock up.
*CmdlineEnter*
CmdlineEnter After moving the cursor to the command line,
where the user can type a command or search
string.
<afile> is set to a single character,
indicating the type of command-line.
|cmdline-char|
CmdlineEnter After entering the command-line (including
non-interactive use of ":" in a mapping: use
|<Cmd>| instead to avoid this).
<afile> is set to the |cmdline-char|.
Sets these |v:event| keys:
cmdlevel
cmdtype
*CmdlineLeave*
CmdlineLeave Before leaving the command line.
<afile> is set to a single character,
indicating the type of command-line.
|cmdline-char|
CmdlineLeave Before leaving the command-line (including
non-interactive use of ":" in a mapping: use
|<Cmd>| instead to avoid this).
<afile> is set to the |cmdline-char|.
Sets these |v:event| keys:
abort (mutable)
cmdlevel

48
runtime/doc/develop.txt
View File

@@ -6,19 +6,20 @@
Development of Nvim *development*
Nvim is open source software. Everybody is encouraged to contribute.
https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
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
See src/nvim/README.md for an overview of the source code.
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).
Note that some items conflict; this is intentional. A balance must be found.
Most important things come first (roughly). Some items conflict; this is
intentional. A balance must be found.
NVIM IS... IMPROVED *design-improved*
@@ -81,41 +82,6 @@ include the kitchen sink... but it's good for plumbing."
Developer guidelines *dev*
JARGON *dev-jargon*
API client ~
All external UIs and remote plugins (as opposed to regular Vim plugins) are
"clients" in general; but we call something an "API client" if its purpose is
to abstract or wrap the RPC API for the convenience of other applications
(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
using an HTTP client like curl, but boto3 wraps that in a convenient python
interface). For example, the Nvim lua-client is an API client:
https://github.com/neovim/lua-client
Host ~
A plugin "host" is both a client (of the Nvim API) and a server (of an
external platform, e.g. python). It is a remote plugin that hosts other
plugins.
Remote plugin ~
Arbitrary code registered via |:UpdateRemotePlugins|, that runs in a separate
process and communicates with Nvim via the |api|.
Window ~
The word "window" is commonly used for several things: A window on the screen,
the xterm window, a window inside Vim to view a buffer.
To avoid confusion, other items that are sometimes called window have been
given another name. Here is an overview of the related items:
screen The whole display.
shell The Vim application. This can cover the whole screen (e.g.,
when running in a console) or part of it (xterm or GUI).
window View on a buffer. There can be several windows in Vim,
together with the command line, menubar, toolbar, etc. they
fit in the shell.
frame Windows are kept in a tree of frames. Each frame contains
a column, row, or window ("leaf" frame).
PROVIDERS *dev-provider*
A goal of Nvim is to allow extension of the editor without special knowledge

1
runtime/doc/help.txt
View File

@@ -150,6 +150,7 @@ GUI ~
Interfaces ~
|if_cscop.txt| using Cscope with Vim
|if_lua.txt| Lua interface
|if_pyth.txt| Python interface
|if_ruby.txt| Ruby interface
|sign.txt| debugging signs

39
runtime/doc/intro.txt
View File

@@ -94,7 +94,7 @@ For the most recent information about sponsoring look on the Vim web site:
Neovim development is funded separately from Vim:
https://neovim.io/sponsors/
https://neovim.io/#sponsor
==============================================================================
Credits *credits* *author* *Bram* *Moolenaar*
@@ -702,18 +702,15 @@ window. You may make the window as small as you like, but if it gets too
small not a single line will fit in it. Make it at least 40 characters wide
to be able to read most messages on the last line.
On most Unix systems, resizing the window is recognized and handled correctly
by Vim.
==============================================================================
Definitions *definitions*
Definitions *definitions* *jargon*
buffer Contains lines of text, usually read from a file.
screen The whole area that Vim uses to work in. This can be
a terminal emulator window. Also called "the Vim
window".
buffer Contains lines of text, usually from a file.
screen The whole area that Nvim uses to display things.
window A view on a buffer. There can be multiple windows for
one buffer.
frame Windows are kept in a tree of frames. Each frame
contains a column, row, or window ("leaf" frame).
A screen contains one or more windows, separated by status lines and with the
command line at the bottom.
@@ -746,7 +743,7 @@ A difference is made between four types of lines:
lines with wrapping, line breaks, etc. applied. They
can only be as long as the width of the window allows,
longer lines are wrapped or truncated.
screen lines The lines of the screen that Vim uses. Consists of
screen lines The lines of the screen that Nvim uses. Consists of
the window lines of all windows, with status lines
and the command line added. They can only be as long
as the width of the screen allows. When the command
@@ -770,5 +767,27 @@ buffer lines logical lines window lines screen lines ~
5. ddd 13. (command line)
6. ~
API client ~
All external UIs and remote plugins (as opposed to regular Vim plugins) are
"clients" in general; but we call something an "API client" if its purpose is
to abstract or wrap the RPC API for the convenience of other applications
(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
using an HTTP client like curl, but boto3 wraps that in a convenient python
interface). For example, the Nvim lua-client is an API client:
https://github.com/neovim/lua-client
Host ~
A plugin "host" is both a client (of the Nvim API) and a server (of an
external platform, e.g. python). It is a remote plugin that hosts other
plugins.
Remote plugin ~
Arbitrary code registered via |:UpdateRemotePlugins|, that runs in a separate
process and communicates with Nvim via the |api|.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

3
runtime/doc/map.txt
View File

@@ -286,6 +286,9 @@ current mode (instead of always going to normal-mode). Visual-mode is
preserved, so tricks with |gv| are not needed. Commands can be invoked
directly in cmdline-mode (which otherwise would require timer hacks).
Because <Cmd> avoids mode-changes (unlike ":") it does not trigger
|CmdlineEnter| and |CmdlineLeave| events. This helps performance.
Unlike <expr> mappings, there are no special restrictions on the <Cmd>
command: it is executed as if an (unrestricted) |autocmd| was invoked or an
async event event was processed.