IntenseFinance/neovim
3
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-02-25 18:55:25 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge #9600 'doc, gen_vimdoc.py'

Browse Source
This commit is contained in:
Justin M. Keyes 2019-03-26 21:36:33 +01:00 committed by GitHub
commit be676eccf1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 778 additions and 621 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@ -2,9 +2,8 @@
[Wiki](https://github.com/neovim/neovim/wiki) | [Wiki](https://github.com/neovim/neovim/wiki) |
[Documentation](https://neovim.io/doc) | [Documentation](https://neovim.io/doc) |
[Twitter](https://twitter.com/Neovim) | [Chat/Discussion](https://gitter.im/neovim/neovim) |
[Community](https://neovim.io/community/) | [Twitter](https://twitter.com/Neovim)
[Gitter **Chat**](https://gitter.im/neovim/neovim)
[![Travis build status](https://travis-ci.org/neovim/neovim.svg?branch=master)](https://travis-ci.org/neovim/neovim) [![Travis build status](https://travis-ci.org/neovim/neovim.svg?branch=master)](https://travis-ci.org/neovim/neovim)
[![AppVeyor build status](https://ci.appveyor.com/api/projects/status/urdqjrik5u521fac/branch/master?svg=true)](https://ci.appveyor.com/project/neovim/neovim/branch/master) [![AppVeyor build status](https://ci.appveyor.com/api/projects/status/urdqjrik5u521fac/branch/master?svg=true)](https://ci.appveyor.com/project/neovim/neovim/branch/master)
@ -34,9 +33,8 @@ Features
- Modern [GUIs](https://github.com/neovim/neovim/wiki/Related-projects#gui) - Modern [GUIs](https://github.com/neovim/neovim/wiki/Related-projects#gui)
- [API access](https://github.com/neovim/neovim/wiki/Related-projects#api-clients) - [API access](https://github.com/neovim/neovim/wiki/Related-projects#api-clients)
from any language including C/C++, C#, Clojure, D, Elixir, Lisp, Go, from any language including C/C++, C#, Clojure, D, Elixir, Go, Haskell, Java,
Haskell, Java, JavaScript/Node.js, Julia, Lisp, Lua, Perl, Python, Racket, JavaScript/Node.js, Julia, Lisp, Lua, Perl, Python, Racket, Ruby, Rust
Ruby, Rust
- Embedded, scriptable [terminal emulator](https://neovim.io/doc/user/nvim_terminal_emulator.html) - Embedded, scriptable [terminal emulator](https://neovim.io/doc/user/nvim_terminal_emulator.html)
- Asynchronous [job control](https://github.com/neovim/neovim/pull/2247) - Asynchronous [job control](https://github.com/neovim/neovim/pull/2247)
- [Shared data (shada)](https://github.com/neovim/neovim/pull/2506) among multiple editor instances - [Shared data (shada)](https://github.com/neovim/neovim/pull/2506) among multiple editor instances
@ -51,8 +49,8 @@ Install from package
Pre-built packages for Windows, macOS, and Linux are found on the Pre-built packages for Windows, macOS, and Linux are found on the
[Releases](https://github.com/neovim/neovim/releases/) page. [Releases](https://github.com/neovim/neovim/releases/) page.
Managed packages are in [Homebrew], [Debian], [Ubuntu], [Fedora], [Arch Linux], [Gentoo], [Managed packages] are in Homebrew, [Debian], [Ubuntu], [Fedora], [Arch Linux],
and [more](https://github.com/neovim/neovim/wiki/Installing-Neovim)! [Gentoo], and more!
Install from source Install from source
------------------- -------------------
@ -144,7 +142,7 @@ See `LICENSE` for details.
[nvim-features]: https://neovim.io/doc/user/vim_diff.html#nvim-features [nvim-features]: https://neovim.io/doc/user/vim_diff.html#nvim-features
[Roadmap]: https://neovim.io/roadmap/ [Roadmap]: https://neovim.io/roadmap/
[advanced UIs]: https://github.com/neovim/neovim/wiki/Related-projects#gui [advanced UIs]: https://github.com/neovim/neovim/wiki/Related-projects#gui
[Homebrew]: https://github.com/neovim/homebrew-neovim#installation [Managed packages]: https://github.com/neovim/neovim/wiki/Installing-Neovim#install-from-package
[Debian]: https://packages.debian.org/testing/neovim [Debian]: https://packages.debian.org/testing/neovim
[Ubuntu]: http://packages.ubuntu.com/search?keywords=neovim [Ubuntu]: http://packages.ubuntu.com/search?keywords=neovim
[Fedora]: https://apps.fedoraproject.org/packages/neovim [Fedora]: https://apps.fedoraproject.org/packages/neovim

499
runtime/doc/api.txt
View File

@ -293,6 +293,9 @@ nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()*
Return: ~ Return: ~
Highlight definition map Highlight definition map
See also: ~
nvim_get_hl_by_id
nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()*
Gets a highlight definition by id. |hlID()| Gets a highlight definition by id. |hlID()|
@ -303,6 +306,9 @@ nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()*
Return: ~ Return: ~
Highlight definition map Highlight definition map
See also: ~
nvim_get_hl_by_name
nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()*
Sends input-keys to Nvim, subject to various quirks controlled Sends input-keys to Nvim, subject to various quirks controlled
by `mode` flags. This is a blocking call, unlike by `mode` flags. This is a blocking call, unlike
@ -316,6 +322,10 @@ nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()*
{escape_csi} If true, escape K_SPECIAL/CSI bytes in {escape_csi} If true, escape K_SPECIAL/CSI bytes in
`keys` `keys`
See also: ~
feedkeys()
vim_strsave_escape_csi
nvim_input({keys}) *nvim_input()* nvim_input({keys}) *nvim_input()*
Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a
low-level input buffer and the call is non-blocking (input is low-level input buffer and the call is non-blocking (input is
@ -326,7 +336,6 @@ nvim_input({keys}) *nvim_input()*
Note: Note:
|keycodes| like <CR> are translated, so "<" is special. To |keycodes| like <CR> are translated, so "<" is special. To
input a literal "<", send <LT>. input a literal "<", send <LT>.
Note: Note:
For mouse events use |nvim_input_mouse()|. The pseudokey For mouse events use |nvim_input_mouse()|. The pseudokey
form "<LeftMouse><col,row>" is deprecated since form "<LeftMouse><col,row>" is deprecated since
@ -346,9 +355,8 @@ nvim_input({keys}) *nvim_input()*
nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
Send mouse event from GUI. Send mouse event from GUI.
The call is non-blocking. It doesn't wait on any resulting Non-blocking: does not wait on any result, but queues the
action, but queues the event to be processed soon by the event event to be processed soon by the event loop.
loop.
Note: Note:
Currently this doesn't support "scripting" multiple mouse Currently this doesn't support "scripting" multiple mouse
@ -392,6 +400,10 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
{special} Replace |keycodes|, e.g. <CR> becomes a "\n" {special} Replace |keycodes|, e.g. <CR> becomes a "\n"
char. char.
See also: ~
replace_termcodes
cpoptions
nvim_command_output({command}) *nvim_command_output()* nvim_command_output({command}) *nvim_command_output()*
Executes an ex-command and returns its (non-error) output. Executes an ex-command and returns its (non-error) output.
Shell |:!| output is not captured. Shell |:!| output is not captured.
@ -420,7 +432,7 @@ nvim_execute_lua({code}, {args}) *nvim_execute_lua()*
inside the chunk. The chunk can return a value. inside the chunk. The chunk can return a value.
Only statements are executed. To evaluate an expression, Only statements are executed. To evaluate an expression,
prefix it with `return`: return my_function(...) prefix it with `return` : return my_function(...)
Parameters: ~ Parameters: ~
{code} lua code to execute {code} lua code to execute
@ -458,7 +470,7 @@ nvim_call_dict_function({dict}, {fn}, {args}) *nvim_call_dict_function()*
Result of the function call Result of the function call
nvim_strwidth({text}) *nvim_strwidth()* nvim_strwidth({text}) *nvim_strwidth()*
Calculates the number of display cells occupied by `text`. Calculates the number of display cells occupied by `text` .
<Tab> counts as one cell. <Tab> counts as one cell.
Parameters: ~ Parameters: ~
@ -575,11 +587,14 @@ nvim_err_writeln({str}) *nvim_err_writeln()*
Parameters: ~ Parameters: ~
{str} Message {str} Message
See also: ~
nvim_err_write()
nvim_list_bufs() *nvim_list_bufs()* nvim_list_bufs() *nvim_list_bufs()*
Gets the current list of buffer handles Gets the current list of buffer handles
Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use Includes unlisted (unloaded/deleted) buffers, like `:ls!` .
|nvim_buf_is_loaded()| to check if a buffer is loaded. Use |nvim_buf_is_loaded()| to check if a buffer is loaded.
Return: ~ Return: ~
List of buffer handles List of buffer handles
@ -618,13 +633,16 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()*
Creates a new, empty, unnamed buffer. Creates a new, empty, unnamed buffer.
Parameters: ~ Parameters: ~
{listed} Controls 'buflisted' {listed} Sets 'buflisted'
{scratch} Creates a "throwaway" |scratch-buffer| for {scratch} Creates a "throwaway" |scratch-buffer| for
temporary work (always 'nomodified') temporary work (always 'nomodified')
Return: ~ Return: ~
Buffer handle, or 0 on error Buffer handle, or 0 on error
See also: ~
buf_open_scratch
nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
Open a new window. Open a new window.
@ -639,51 +657,6 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
Exactly one of `external` and `relative` must be specified. Exactly one of `external` and `relative` must be specified.
Parameters: ~
{buffer} handle of buffer to be displayed in the window
{enter} whether the window should be entered (made the
current window)
{config} Dictionary for the window configuration accepts
these keys:
`relative`: If set, the window becomes a
floating window. The window will be placed with
row,col coordinates relative to one of the
following:
"editor" the global editor grid
"win" a window. Use `win` to specify window id,
or current window will be used by default.
"cursor" the cursor position in current window.
`win`: when using `relative='win'`, window id of the window
where the position is defined.
`anchor`: the corner of the float that the row,col
position defines
"NW" north-west (default)
"NE" north-east
"SW" south-west
"SE" south-east
`focusable`: Whether window can be focused by wincmds and
mouse events. Defaults to true. Even if set to false,
the window can still be entered using
|nvim_set_current_win()| API call.
`height`: Window height in character cells. Minimum of 1.
`width`: Window width in character cells. Minimum of 2.
`row`: row position. Screen cell height are used as unit.
Can be floating point.
`col`: column position. Screen cell width is used as
unit. Can be floating point.
`external`: GUI should display the window as an external
top-level window. Currently accepts no other
positioning configuration together with this.
With editor positioning row=0, col=0 refers to the top-left With editor positioning row=0, col=0 refers to the top-left
corner of the screen-grid and row=Lines-1, Columns-1 refers to corner of the screen-grid and row=Lines-1, Columns-1 refers to
the bottom-right corner. Floating point values are allowed, the bottom-right corner. Floating point values are allowed,
@ -698,9 +671,49 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
should not be used to specify arbitrary WM screen positions. should not be used to specify arbitrary WM screen positions.
Parameters: ~ Parameters: ~
{buffer} handle of buffer to be displayed in the window
{enter} whether the window should be entered (made the
current window)
{config} Dictionary for the window configuration accepts
these keys:
- `relative` : If set, the window becomes a floating
window. The window will be placed with row,col
coordinates relative to one of the following:
- "editor" the global editor grid
- "win" a window. Use `win` to specify a
window id, or the current window will be
used by default. "cursor" the cursor
position in current window.
- `win` : When using relative='win', window id
of the window where the position is defined.
- `anchor` : The corner of the float that the row,col
position defines:
- "NW" north-west (default)
- "NE" north-east
- "SW" south-west
- "SE" south-east
- `height` : window height (in character cells).
Minimum of 1.
- `width` : window width (in character cells).
Minimum of 2.
- `row` : row position. Screen cell height are
used as unit. Can be floating point.
- `col` : column position. Screen cell width is
used as unit. Can be floating point.
- `focusable` : Whether window can be focused by
wincmds and mouse events. Defaults to true.
Even if set to false, the window can still be
entered using |nvim_set_current_win()| API
call.
- `external` : GUI should display the window as
an external top-level window. Currently
accepts no other positioning configuration
together with this.
Return: ~ Return: ~
the window handle or 0 when error Window handle, or 0 on error
nvim_list_tabpages() *nvim_list_tabpages()* nvim_list_tabpages() *nvim_list_tabpages()*
Gets the current list of tabpage handles. Gets the current list of tabpage handles.
@ -808,86 +821,87 @@ nvim_get_api_info() *nvim_get_api_info()*
*nvim_set_client_info()* *nvim_set_client_info()*
nvim_set_client_info({name}, {version}, {type}, {methods}, nvim_set_client_info({name}, {version}, {type}, {methods},
{attributes}) {attributes})
Identify the client for nvim. Can be called more than once, Identifies the client. Can be called more than once;
but subsequent calls will remove earlier info, which should be subsequent calls remove earlier info, which should be included
resent if it is still valid. (This could happen if a library by the caller if it is still valid. (E.g. if a library first
first identifies the channel, and a plugin using that library identifies the channel, then a plugin using that library later
later overrides that info) overrides that info)
Parameters: ~ Parameters: ~
{name} short name for the connected client {name} Short name for the connected client
{version} Dictionary describing the version, with the {version} Dictionary describing the version, with
following possible keys (all optional) these (optional) keys:
"major" major version (defaults to 0 if not - "major" major version (defaults to 0 if
set, for no release yet) "minor" minor not set, for no release yet)
version "patch" patch number "prerelease" - "minor" minor version
string describing a prerelease, like "dev" - "patch" patch number
or "beta1" "commit" hash or similar - "prerelease" string describing a
identifier of commit prerelease, like "dev" or "beta1"
{type} Must be one of the following values. A - "commit" hash or similar identifier of
client library should use "remote" if the commit
library user hasn't specified other value. {type} Must be one of the following values. Client
"remote" remote client that connected to libraries should default to "remote" unless
nvim. "ui" gui frontend "embedder" overridden by the user.
application using nvim as a component, for - "remote" remote client connected to Nvim.
instance IDE/editor implementing a vim mode. - "ui" gui frontend
"host" plugin host, typically started by - "embedder" application using Nvim as a
nvim "plugin" single plugin, started by component (for example, IDE/editor
nvim implementing a vim mode).
- "host" plugin host, typically started by
nvim
- "plugin" single plugin, started by nvim
{methods} Builtin methods in the client. For a host, {methods} Builtin methods in the client. For a host,
this does not include plugin methods which this does not include plugin methods which
will be discovered later. The key should be will be discovered later. The key should be
the method name, the values are dicts with the method name, the values are dicts with
the following (optional) keys: "async" if these (optional) keys (more keys may be
true, send as a notification. If false or added in future versions of Nvim, thus
unspecified, use a blocking request "nargs" unknown keys are ignored. Clients must only
Number of arguments. Could be a single use keys defined in this or later versions
integer or an array two integers, minimum of Nvim):
and maximum inclusive. Further keys might be - "async" if true, send as a notification.
added in later versions of nvim and unknown If false or unspecified, use a blocking
keys are thus ignored. Clients must only use request
keys defined in this or later versions of - "nargs" Number of arguments. Could be a
nvim! single integer or an array of two
{attributes} Informal attributes describing the client. integers, minimum and maximum inclusive.
Clients might define their own keys, but the {attributes} Arbitrary string:string map of informal
following are suggested: "website" Website client properties. Suggested keys:
of client (for instance github repository) - "website": Client homepage URL (e.g.
"license" Informal description of the GitHub repository)
license, such as "Apache 2", "GPLv3" or - "license": License description ("Apache
"MIT" "logo" URI or path to image, 2", "GPLv3", "MIT", …)
preferably small logo or icon. .png or .svg - "logo": URI or path to image, preferably
format is preferred. small logo or icon. .png or .svg format is
preferred.
nvim_get_chan_info({chan}) *nvim_get_chan_info()* nvim_get_chan_info({chan}) *nvim_get_chan_info()*
Get information about a channel. Get information about a channel.
Return: ~ Return: ~
a Dictionary, describing a channel with the following Dictionary describing a channel, with these keys:
keys: - "stream" the stream underlying the channel
- "stdio" stdin and stdout of this Nvim instance
- "stderr" stderr of this Nvim instance
- "socket" TCP/IP socket or named pipe
- "job" job with communication over its stdio
`stream`: the stream underlying the channel: - "mode" how data received on the channel is interpreted
"stdio" stdin and stdout of this Nvim instance. - "bytes" send and receive raw bytes
"stderr" stderr of this Nvim instance. - "terminal" a |terminal| instance interprets ASCII
"socket" TCP/IP socket or named pipe. sequences
"job" job with communication over its stdio. - "rpc" |RPC| communication on the channel is active
`mode`: how data received on the channel is interpreted: - "pty" Name of pseudoterminal, if one is used (optional).
"bytes" send and recieve raw bytes. On a POSIX system, this will be a device path like
"terminal" a |terminal| instance interprets ASCII sequences /dev/pts/1. Even if the name is unknown, the key will
"rpc" |RPC| communication on the channel is active still be present to indicate a pty is used. This is
currently the case when using winpty on windows.
`pty`: Name of pseudoterminal, if one is used (optional). - "buffer" buffer with connected |terminal| instance
On a POSIX system, this will be a device path like (optional)
/dev/pts/1. Even if the name is unknown, the key will - "client" information about the client on the other end
still be present to indicate a pty is used. This is of the RPC channel, if it has added it using
currently the case when using winpty on windows. |nvim_set_client_info()|. (optional)
`buffer`: buffer with connected |terminal|
instance (optional).
`client`: information about the client on the other end of
the RPC channel, if it has added it using
|nvim_set_client_info()| (optional).
nvim_list_chans() *nvim_list_chans()* nvim_list_chans() *nvim_list_chans()*
Get information about all open channels. Get information about all open channels.
@ -901,12 +915,12 @@ nvim_call_atomic({calls}) *nvim_call_atomic()*
This has two main usages: This has two main usages:
1. To perform several requests from an async context 1. To perform several requests from an async context
atomically, i.e. without interleaving redraws, RPC requests atomically, i.e. without interleaving redraws, RPC requests
from other clients, or user interactions (however API methods from other clients, or user interactions (however API
may trigger autocommands or event processing which have such methods may trigger autocommands or event processing which
side-effects, e.g. |:sleep| may wake timers). have such side-effects, e.g. |:sleep| may wake timers).
2. To minimize RPC overhead (roundtrips) of a sequence of many 2. To minimize RPC overhead (roundtrips) of a sequence of many
requests. requests.
Parameters: ~ Parameters: ~
{calls} an array of calls, where each call is described {calls} an array of calls, where each call is described
@ -914,13 +928,13 @@ nvim_call_atomic({calls}) *nvim_call_atomic()*
and an array of arguments. and an array of arguments.
Return: ~ Return: ~
an array with two elements. The first is an array of Array of two elements. The first is an array of return
return values. The second is NIL if all calls succeeded. values. The second is NIL if all calls succeeded. If a
If a call resulted in an error, it is a three-element call resulted in an error, it is a three-element array
array with the zero-based index of the call which resulted with the zero-based index of the call which resulted in an
in an error, the error type and the error message. If an error, the error type and the error message. If an error
error occurred, the values from all preceding calls will occurred, the values from all preceding calls will still
still be returned. be returned.
*nvim_parse_expression()* *nvim_parse_expression()*
nvim_parse_expression({expr}, {flags}, {highlight}) nvim_parse_expression({expr}, {flags}, {highlight})
@ -930,20 +944,24 @@ nvim_parse_expression({expr}, {flags}, {highlight})
{async} {async}
Parameters: ~ Parameters: ~
{expr} Expression to parse. Is always treated as a {expr} Expression to parse. Always treated as a
single line. single line.
{flags} Flags: - "m" if multiple expressions in a {flags} Flags:
row are allowed (only the first one will be - "m" if multiple expressions in a row are
parsed), - "E" if EOC tokens are not allowed allowed (only the first one will be
(determines whether they will stop parsing parsed),
process or be recognized as an - "E" if EOC tokens are not allowed
operator/space, though also yielding an (determines whether they will stop parsing
error). - "l" when needing to start parsing process or be recognized as an
with lvalues for ":let" or ":for". Common operator/space, though also yielding an
flag sets: - "m" to parse like for ":echo". - error).
"E" to parse like for "<C-r>=". - empty - "l" when needing to start parsing with
string for ":call". - "lm" to parse for lvalues for ":let" or ":for". Common flag
":let". sets:
- "m" to parse like for ":echo".
- "E" to parse like for "<C-r>=".
- empty string for ":call".
- "lm" to parse for ":let".
{highlight} If true, return value will also include {highlight} If true, return value will also include
"highlight" key containing array of 4-tuples "highlight" key containing array of 4-tuples
(arrays) (Integer, Integer, Integer, String), (arrays) (Integer, Integer, Integer, String),
@ -954,51 +972,66 @@ nvim_parse_expression({expr}, {flags}, {highlight})
[start_col, end_col)). [start_col, end_col)).
Return: ~ Return: ~
AST: top-level dictionary with these keys: "error":
Dictionary with error, present only if parser saw some - AST: top-level dictionary with these keys:
error. Contains the following keys: "message": String, - "error": Dictionary with error, present only if parser
error message in printf format, translated. Must contain saw some error. Contains the following keys:
exactly one "%.*s". "arg": String, error message argument. - "message": String, error message in printf format,
"len": Amount of bytes successfully parsed. With flags translated. Must contain exactly one "%.*s".
equal to "" that should be equal to the length of expr - "arg": String, error message argument.
string. @note: “Sucessfully parsed” here means
“participated in AST creation”, not “till the first - "len": Amount of bytes successfully parsed. With flags
error”. "ast": AST, either nil or a dictionary with these equal to "" that should be equal to the length of expr
keys: "type": node type, one of the value names from string. (“Sucessfully parsed” here means “participated
ExprASTNodeType stringified without "kExprNode" prefix. in AST creation”, not “till the first error”.)
"start": a pair [line, column] describing where node is - "ast": AST, either nil or a dictionary with these
“started” where "line" is always 0 (will not be 0 if you keys:
will be using nvim_parse_viml() on e.g. ":let", but that - "type": node type, one of the value names from
is not present yet). Both elements are Integers. "len": ExprASTNodeType stringified without "kExprNode"
“length” of the node. This and "start" are there for prefix.
debugging purposes primary (debugging parser and providing - "start": a pair [line, column] describing where node
debug information). "children": a list of nodes described is "started" where "line" is always 0 (will not be 0
in top/"ast". There always is zero, one or two children, if you will be using nvim_parse_viml() on e.g.
key will not be present if node has no children. Maximum ":let", but that is not present yet). Both elements
number of children may be found in node_maxchildren array. are Integers.
Local values (present only for certain nodes): "scope": a - "len": “length” of the node. This and "start" are
single Integer, specifies scope for "Option" and there for debugging purposes primary (debugging
"PlainIdentifier" nodes. For "Option" it is one of parser and providing debug information).
ExprOptScope values, for "PlainIdentifier" it is one of - "children": a list of nodes described in top/"ast".
ExprVarScope values. "ident": identifier (without scope, There always is zero, one or two children, key will
if any), present for "Option", "PlainIdentifier", not be present if node has no children. Maximum
"PlainKey" and "Environment" nodes. "name": Integer, number of children may be found in node_maxchildren
register name (one character) or -1. Only present for array.
"Register" nodes. "cmp_type": String, comparison type, one
of the value names from ExprComparisonType, stringified - Local values (present only for certain nodes):
without "kExprCmp" prefix. Only present for "Comparison" - "scope": a single Integer, specifies scope for
nodes. "ccs_strategy": String, case comparison strategy, "Option" and "PlainIdentifier" nodes. For "Option" it
one of the value names from ExprCaseCompareStrategy, is one of ExprOptScope values, for "PlainIdentifier"
stringified without "kCCStrategy" prefix. Only present for it is one of ExprVarScope values.
"Comparison" nodes. "augmentation": String, augmentation - "ident": identifier (without scope, if any), present
type for "Assignment" nodes. Is either an empty string, for "Option", "PlainIdentifier", "PlainKey" and
"Add", "Subtract" or "Concat" for "=", "+=", "-=" or ".=" "Environment" nodes.
respectively. "invert": Boolean, true if result of - "name": Integer, register name (one character) or -1.
comparison needs to be inverted. Only present for Only present for "Register" nodes.
"Comparison" nodes. "ivalue": Integer, integer value for - "cmp_type": String, comparison type, one of the value
"Integer" nodes. "fvalue": Float, floating-point value for names from ExprComparisonType, stringified without
"Float" nodes. "svalue": String, value for "kExprCmp" prefix. Only present for "Comparison"
"SingleQuotedString" and "DoubleQuotedString" nodes. nodes.
- "ccs_strategy": String, case comparison strategy, one
of the value names from ExprCaseCompareStrategy,
stringified without "kCCStrategy" prefix. Only present
for "Comparison" nodes.
- "augmentation": String, augmentation type for
"Assignment" nodes. Is either an empty string, "Add",
"Subtract" or "Concat" for "=", "+=", "-=" or ".="
respectively.
- "invert": Boolean, true if result of comparison needs
to be inverted. Only present for "Comparison" nodes.
- "ivalue": Integer, integer value for "Integer" nodes.
- "fvalue": Float, floating-point value for "Float"
nodes.
- "svalue": String, value for "SingleQuotedString" and
"DoubleQuotedString" nodes.
nvim__id({obj}) *nvim__id()* nvim__id({obj}) *nvim__id()*
Returns object given as argument. Returns object given as argument.
@ -1058,23 +1091,22 @@ nvim_list_uis() *nvim_list_uis()*
Gets a list of dictionaries representing attached UIs. Gets a list of dictionaries representing attached UIs.
Return: ~ Return: ~
Array of UI dictionaries. Each dictionary has the Array of UI dictionaries, each with these keys:
following keys: - "height" requested height of the UI
`height`: requested height of the UI - "width" requested width of the UI
`width`: requested width of the UI - "rgb" whether the UI uses rgb colors (false implies
`rgb`: whether the UI uses rgb colors cterm colors)
(false implies cterm colors) - "ext_..." Requested UI extensions, see |ui-options|
`ext_...`: Requested UI extensions, see |ui-options| - "chan" Channel id of remote UI (not present for TUI)
`chan`: Channel id of remote UI (not present for TUI)
nvim_get_proc_children({pid}) *nvim_get_proc_children()* nvim_get_proc_children({pid}) *nvim_get_proc_children()*
Gets the immediate children of process `pid`. Gets the immediate children of process `pid` .
Return: ~ Return: ~
Array of child process ids, empty if process not found. Array of child process ids, empty if process not found.
nvim_get_proc({pid}) *nvim_get_proc()* nvim_get_proc({pid}) *nvim_get_proc()*
Gets info describing process `pid`. Gets info describing process `pid` .
Return: ~ Return: ~
Map of process properties, or NIL if process not found. Map of process properties, or NIL if process not found.
@ -1096,7 +1128,7 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
{insert} Whether the selection should be inserted in the {insert} Whether the selection should be inserted in the
buffer. buffer.
{finish} Finish the completion and dismiss the popupmenu. {finish} Finish the completion and dismiss the popupmenu.
Implies `insert`. Implies `insert` .
{opts} Optional parameters. Reserved for future use. {opts} Optional parameters. Reserved for future use.
nvim__inspect_cell({row}, {col}) *nvim__inspect_cell()* nvim__inspect_cell({row}, {col}) *nvim__inspect_cell()*
@ -1123,7 +1155,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
Gets the buffer line count Gets the buffer line count
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
Return: ~ Return: ~
Line count, or 0 for unloaded buffer. |api-buffer| Line count, or 0 for unloaded buffer. |api-buffer|
@ -1132,11 +1164,11 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Activate updates from this buffer to the current channel. Activate updates from this buffer to the current channel.
Parameters: ~ Parameters: ~
{buffer} The buffer handle {buffer} Buffer handle, or 0 for current buffer
{send_buffer} Set to true if the initial notification {send_buffer} Set to true if the initial notification
should contain the whole buffer. If so, the should contain the whole buffer. If so, the
first notification will be a first notification will be a
`nvim_buf_lines_event`. Otherwise, the `nvim_buf_lines_event` . Otherwise, the
first notification will be a first notification will be a
`nvim_buf_changedtick_event` `nvim_buf_changedtick_event`
{opts} Optional parameters. Reserved for future {opts} Optional parameters. Reserved for future
@ -1144,14 +1176,14 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Return: ~ Return: ~
False when updates couldn't be enabled because the buffer False when updates couldn't be enabled because the buffer
isn't loaded or optscontained an invalid key; otherwise isn't loaded or `opts` contained an invalid key; otherwise
True. True.
nvim_buf_detach({buffer}) *nvim_buf_detach()* nvim_buf_detach({buffer}) *nvim_buf_detach()*
Deactivate updates from this buffer to the current channel. Deactivate updates from this buffer to the current channel.
Parameters: ~ Parameters: ~
{buffer} The buffer handle {buffer} Buffer handle, or 0 for current buffer
Return: ~ Return: ~
False when updates couldn't be disabled because the buffer False when updates couldn't be disabled because the buffer
@ -1169,7 +1201,7 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
unless `strict_indexing` is set. unless `strict_indexing` is set.
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{start} First line index {start} First line index
{end} Last line index (exclusive) {end} Last line index (exclusive)
{strict_indexing} Whether out-of-bounds should be an {strict_indexing} Whether out-of-bounds should be an
@ -1196,7 +1228,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing},
unless `strict_indexing` is set. unless `strict_indexing` is set.
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{start} First line index {start} First line index
{end} Last line index (exclusive) {end} Last line index (exclusive)
{strict_indexing} Whether out-of-bounds should be an {strict_indexing} Whether out-of-bounds should be an
@ -1216,7 +1248,7 @@ nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()*
Returns -1 for unloaded buffer. Returns -1 for unloaded buffer.
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{index} Line index {index} Line index
Return: ~ Return: ~
@ -1226,7 +1258,7 @@ nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()*
Gets a buffer-scoped (b:) variable. Gets a buffer-scoped (b:) variable.
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{name} Variable name {name} Variable name
Return: ~ Return: ~
@ -1236,17 +1268,17 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()*
Gets a changed tick of a buffer Gets a changed tick of a buffer
Parameters: ~ Parameters: ~
{buffer} Buffer handle. {buffer} Buffer handle, or 0 for current buffer
Return: ~ Return: ~
b:changedtickvalue. `b:changedtick` value.
nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()*
Gets a list of buffer-local |mapping| definitions. Gets a list of buffer-local |mapping| definitions.
Parameters: ~ Parameters: ~
{mode} Mode short-name ("n", "i", "v", ...) {mode} Mode short-name ("n", "i", "v", ...)
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
Return: ~ Return: ~
Array of maparg()-like dictionaries describing mappings. Array of maparg()-like dictionaries describing mappings.
@ -1256,7 +1288,7 @@ nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()*
Gets a map of buffer-local |user-commands|. Gets a map of buffer-local |user-commands|.
Parameters: ~ Parameters: ~
{buffer} Buffer handle. {buffer} Buffer handle, or 0 for current buffer
{opts} Optional parameters. Currently not used. {opts} Optional parameters. Currently not used.
Return: ~ Return: ~
@ -1266,7 +1298,7 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
Sets a buffer-scoped (b:) variable Sets a buffer-scoped (b:) variable
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{name} Variable name {name} Variable name
{value} Variable value {value} Variable value
@ -1274,14 +1306,14 @@ nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()*
Removes a buffer-scoped (b:) variable Removes a buffer-scoped (b:) variable
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{name} Variable name {name} Variable name
nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()*
Gets a buffer option value Gets a buffer option value
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{name} Option name {name} Option name
Return: ~ Return: ~
@ -1292,7 +1324,7 @@ nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()*
option (only works if there's a global fallback) option (only works if there's a global fallback)
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{name} Option name {name} Option name
{value} Option value {value} Option value
@ -1300,7 +1332,7 @@ nvim_buf_get_name({buffer}) *nvim_buf_get_name()*
Gets the full file name for the buffer Gets the full file name for the buffer
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
Return: ~ Return: ~
Buffer name Buffer name
@ -1309,7 +1341,7 @@ nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()*
Sets the full file name for a buffer Sets the full file name for a buffer
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{name} Buffer name {name} Buffer name
nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()* nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()*
@ -1317,7 +1349,7 @@ nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()*
more info about unloaded buffers. more info about unloaded buffers.
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
Return: ~ Return: ~
true if the buffer is valid and loaded, false otherwise. true if the buffer is valid and loaded, false otherwise.
@ -1330,7 +1362,7 @@ nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()*
|api-buffer| for more info about unloaded buffers. |api-buffer| for more info about unloaded buffers.
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
Return: ~ Return: ~
true if the buffer is valid, false otherwise. true if the buffer is valid, false otherwise.
@ -1340,7 +1372,7 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
named mark named mark
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{name} Mark name {name} Mark name
Return: ~ Return: ~
@ -1364,7 +1396,7 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
`ns_id` to add highlights to the namespace. All highlights in `ns_id` to add highlights to the namespace. All highlights in
the same namespace can then be cleared with single call to the same namespace can then be cleared with single call to
|nvim_buf_clear_namespace|. If the highlight never will be |nvim_buf_clear_namespace|. If the highlight never will be
deleted by an API call, pass `ns_id = -1`. deleted by an API call, pass `ns_id = -1` .
As a shorthand, `ns_id = 0` can be used to create a new As a shorthand, `ns_id = 0` can be used to create a new
namespace for the highlight, the allocated id is then namespace for the highlight, the allocated id is then
@ -1374,7 +1406,7 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
|nvim_create_namespace| to create a new empty namespace. |nvim_create_namespace| to create a new empty namespace.
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{ns_id} namespace to use or -1 for ungrouped {ns_id} namespace to use or -1 for ungrouped
highlight highlight
{hl_group} Name of the highlight group to use {hl_group} Name of the highlight group to use
@ -1396,7 +1428,7 @@ nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
to line_start and line_end respectively. to line_start and line_end respectively.
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{ns_id} Namespace to clear, or -1 to clear all {ns_id} Namespace to clear, or -1 to clear all
namespaces. namespaces.
{line_start} Start of range of lines to clear {line_start} Start of range of lines to clear
@ -1420,14 +1452,14 @@ nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
both virtual text and highlights added by both virtual text and highlights added by
|nvim_buf_add_highlight|, both can then be cleared with a |nvim_buf_add_highlight|, both can then be cleared with a
single call to |nvim_buf_clear_namespace|. If the virtual text single call to |nvim_buf_clear_namespace|. If the virtual text
never will be cleared by an API call, pass `ns_id = -1`. never will be cleared by an API call, pass `ns_id = -1` .
As a shorthand, `ns_id = 0` can be used to create a new As a shorthand, `ns_id = 0` can be used to create a new
namespace for the virtual text, the allocated id is then namespace for the virtual text, the allocated id is then
returned. returned.
Parameters: ~ Parameters: ~
{buffer} Buffer handle {buffer} Buffer handle, or 0 for current buffer
{ns_id} Namespace to use or 0 to create a namespace, or {ns_id} Namespace to use or 0 to create a namespace, or
-1 for a ungrouped annotation -1 for a ungrouped annotation
{line} Line to annotate with virtual text {line} Line to annotate with virtual text
@ -1601,7 +1633,7 @@ nvim_win_set_config({window}, {config}) *nvim_win_set_config()*
parameters. parameters.
When reconfiguring a floating window, absent option keys will When reconfiguring a floating window, absent option keys will
not be changed. The following restriction apply: `row`, `col` not be changed. The following restriction apply: `row` , `col`
and `relative` must be reconfigured together. Only changing a and `relative` must be reconfigured together. Only changing a
subset of these is an error. subset of these is an error.
@ -1636,9 +1668,6 @@ nvim_win_close({window}, {force}) *nvim_win_close()*
buffer will become hidden, even if 'hidden' is buffer will become hidden, even if 'hidden' is
not set. not set.
Return: ~
Window number
============================================================================== ==============================================================================
Tabpage Functions *api-tabpage* Tabpage Functions *api-tabpage*
@ -1650,7 +1679,7 @@ nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()*
{tabpage} Tabpage {tabpage} Tabpage
Return: ~ Return: ~
List of windows in tabpage List of windows in `tabpage`
nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()*
Gets a tab-scoped (t:) variable Gets a tab-scoped (t:) variable

43
runtime/doc/autocmd.txt
View File

@ -43,7 +43,7 @@ effects. Be careful not to destroy your text.
:au[tocmd] [group] {event} {pat} [++once] [++nested] {cmd} :au[tocmd] [group] {event} {pat} [++once] [++nested] {cmd}
Add {cmd} to the list of commands that Vim will Add {cmd} to the list of commands that Vim will
execute automatically on {event} for a file matching execute automatically on {event} for a file matching
{pat} |autocmd-patterns|. {pat} |autocmd-pattern|.
Note: A quote character is seen as argument to the Note: A quote character is seen as argument to the
:autocmd and won't start a comment. :autocmd and won't start a comment.
Nvim always adds {cmd} after existing autocommands so Nvim always adds {cmd} after existing autocommands so
@ -358,7 +358,7 @@ Name triggered by ~
|CompleteDone| after Insert mode completion is done |CompleteDone| after Insert mode completion is done
|User| to be used in combination with ":doautocmd" |User| to be used in combination with ":doautocmd"
|Signal| after the nvim process received a signal |Signal| after Nvim receives a signal
@ -870,27 +870,27 @@ MenuPopupChanged *MenuPopupChanged*
It is not allowed to change the text |textlock|. It is not allowed to change the text |textlock|.
*OptionSet* *OptionSet*
OptionSet After setting an option. The pattern is OptionSet After setting an option (except during
matched against the long option name. |startup|). The |autocmd-pattern| is matched
The |v:option_old| variable indicates the against the long option name.
old option value, |v:option_new| variable |v:option_old| indicates the old option value,
indicates the newly set value, the |v:option_new| indicates the new value,
|v:option_type| variable indicates whether |v:option_type| indicates whether it's global
it's global or local scoped and |<amatch>| or local scoped and |<amatch>| indicates which
indicates what option has been set. option was set.
Usage example: Check for the existence of the Usage example: Check for the existence of the
directory in the 'backupdir' and 'undodir' directory in the 'backupdir' and 'undodir'
options, create the directory if it doesn't options, create the directory if it doesn't
exist yet. exist yet.
Note: It's a bad idea to reset an option Note: Do not reset the same option during this
during this autocommand, this may break a autocommand, that may break plugins. You can
plugin. You can always use `:noa` to prevent always use |:noautocmd| to prevent triggering
triggering this autocommand. OptionSet.
When using |:set| in the autocommand the event Recursion is ignored, thus |:set| in the
is not triggered again. autocommand does not trigger OptionSet again.
*QuickFixCmdPre* *QuickFixCmdPre*
QuickFixCmdPre Before a quickfix command is run (|:make|, QuickFixCmdPre Before a quickfix command is run (|:make|,
@ -943,10 +943,11 @@ ShellCmdPost After executing a shell command with |:!cmd|,
For non-blocking shell commands, see For non-blocking shell commands, see
|job-control|. |job-control|.
*Signal* *Signal*
Signal After the nvim process received a signal. Signal After Nvim receives a signal. The pattern is
The pattern is matched against the name of the matched against the signal name. Only
received signal. Only "SIGUSR1" is supported. "SIGUSR1" is supported. Example: >
*ShellFilterPost* autocmd Signal SIGUSR1 call some#func()
< *ShellFilterPost*
ShellFilterPost After executing a shell command with ShellFilterPost After executing a shell command with
":{range}!cmd", ":w !cmd" or ":r !cmd". ":{range}!cmd", ":w !cmd" or ":r !cmd".
Can be used to check for any changed files. Can be used to check for any changed files.
@ -1123,7 +1124,7 @@ WinNew When a new window was created. Not done for
Before a WinEnter event. Before a WinEnter event.
============================================================================== ==============================================================================
6. Patterns *autocmd-patterns* *{pat}* 6. Patterns *autocmd-pattern* *{pat}*
The {pat} argument can be a comma separated list. This works as if the The {pat} argument can be a comma separated list. This works as if the
command was given with each pattern separately. Thus this command: > command was given with each pattern separately. Thus this command: >

9
runtime/doc/deprecated.txt
View File

@ -63,6 +63,15 @@ Options ~
*'vi'* *'vi'*
*'viminfo'* Deprecated alias to 'shada' option. *'viminfo'* Deprecated alias to 'shada' option.
UI extensions~
*ui-wildmenu* Use `ext_cmdline` and `ext_popupmenu` instead.
Enabled by `ext_wildmenu` |ui-options|.
If `ext_wildmenu` is set, these events are emitted for
backwards-compatibility:
["wildmenu_show", items]
["wildmenu_select", selected]
["wildmenu_hide"]
Variables~ Variables~
*b:terminal_job_pid* PID of the top-level process in a |:terminal|. *b:terminal_job_pid* PID of the top-level process in a |:terminal|.
Use `jobpid(&channel)` instead. Use `jobpid(&channel)` instead.

2
runtime/doc/eval.txt
View File

@ -3782,7 +3782,7 @@ function({name} [, {arglist}] [, {dict}])
same function. same function.
When {arglist} or {dict} is present this creates a partial. When {arglist} or {dict} is present this creates a partial.
That mans the argument list and/or the dictionary is stored in That means the argument list and/or the dictionary is stored in
the Funcref and will be used when the Funcref is called. the Funcref and will be used when the Funcref is called.
The arguments are passed to the function in front of other The arguments are passed to the function in front of other

16
runtime/doc/if_lua.txt
View File

@ -16,11 +16,11 @@ an idea of what lurks beneath: >
:lua print(vim.inspect(package.loaded)) :lua print(vim.inspect(package.loaded))
Nvim includes a "standard library" |lua-stdlib| for Lua. This library Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the
complements the Nvim editor |functions| and Ex commands (the editor "stdlib"), "editor stdlib" (|functions| and Ex commands) and the |API|, all of which can
which can also be used from Lua code. be used from Lua code.
Nvim resolves module conflicts by "last wins". For example if both of these Module conflicts are resolved by "last wins". For example if both of these
are on 'runtimepath': are on 'runtimepath':
runtime/lua/foo.lua runtime/lua/foo.lua
~/.config/nvim/lua/foo.lua ~/.config/nvim/lua/foo.lua
@ -260,9 +260,9 @@ position are restricted when the command is executed in the |sandbox|.
============================================================================== ==============================================================================
vim.* *lua-vim* *lua-stdlib* vim.* *lua-vim* *lua-stdlib*
The "standard library" (stdlib) of Nvim Lua is the `vim` module, which exposes The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes
various functions and sub-modules. The module is implicitly loaded, thus various functions and sub-modules. It is always loaded, thus require("vim")
require("vim") is unnecessary. is unnecessary.
You can peek at the module properties: > You can peek at the module properties: >
@ -288,7 +288,7 @@ To find documentation on e.g. the "deepcopy" function: >
:help vim.deepcopy :help vim.deepcopy
Note: Underscore-prefixed functions (e.g. "_os_proc_children") are Note that underscore-prefixed functions (e.g. "_os_proc_children") are
internal/private and must not be used by plugins. internal/private and must not be used by plugins.
------------------------------------------------------------------------------ ------------------------------------------------------------------------------

26
runtime/doc/map.txt
View File

@ -227,14 +227,14 @@ should not either insert or change the v:char.
Be very careful about side effects! The expression is evaluated while Be very careful about side effects! The expression is evaluated while
obtaining characters, you may very well make the command dysfunctional. obtaining characters, you may very well make the command dysfunctional.
For this reason the following is blocked: Therefore the following is blocked for <expr> mappings:
- Changing the buffer text |textlock|. - Changing the buffer text |textlock|.
- Editing another buffer. - Editing another buffer.
- The |:normal| command. - The |:normal| command.
- Moving the cursor is allowed, but it is restored afterwards. - Moving the cursor is allowed, but it is restored afterwards.
- If the cmdline is changed, the old text and cursor position are restored. - If the cmdline is changed, the old text and cursor position are restored.
If you want the mapping to do any of these let the returned characters do If you want the mapping to do any of these let the returned characters do
that. Or use a |<Cmd>| mapping (which doesn't have these restrictions). that. (Or use a |<Cmd>| mapping instead.)
You can use getchar(), it consumes typeahead if there is any. E.g., if you You can use getchar(), it consumes typeahead if there is any. E.g., if you
have these mappings: > have these mappings: >
@ -274,9 +274,9 @@ Using 0x80 as a single byte before other text does not work, it will be seen
as a special key. as a special key.
*<Cmd>* *:map-cmd* *<Cmd>* *:map-cmd*
The <Cmd> pseudokey may be used to define a "command mapping", which executes The <Cmd> pseudokey begins a "command mapping", which executes the command
the command directly (without changing modes, etc.). Where you might use directly (without changing modes). Where you might use ":...<CR>" in the
":...<CR>" in the {lhs} of a mapping, you can instead use "<Cmd>...<CR>". {lhs} of a mapping, you can instead use "<Cmd>...<CR>".
Example: > Example: >
noremap x <Cmd>echo mode(1)<cr> noremap x <Cmd>echo mode(1)<cr>
< <
@ -284,17 +284,21 @@ This is more flexible than `:<C-U>` in visual and operator-pending mode, or
`<C-O>:` in insert-mode, because the commands are executed directly in the `<C-O>:` in insert-mode, because the commands are executed directly in the
current mode (instead of always going to normal-mode). Visual-mode is current mode (instead of always going to normal-mode). Visual-mode is
preserved, so tricks with |gv| are not needed. Commands can be invoked preserved, so tricks with |gv| are not needed. Commands can be invoked
directly in cmdline-mode (which otherwise would require timer hacks). directly in cmdline-mode (which would otherwise 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> Unlike <expr> mappings, there are no special restrictions on the <Cmd>
command: it is executed as if an (unrestricted) |autocmd| was invoked or an command: it is executed as if an (unrestricted) |autocmd| was invoked or an
async event event was processed. async event event was processed.
In select-mode, |:map| and |:vmap| command mappings are executed in Note:
visual-mode. Use |:smap| to handle select-mode. - Because <Cmd> avoids mode-changes (unlike ":") it does not trigger
|CmdlineEnter| and |CmdlineLeave| events. This helps performance.
- For the same reason, |keycodes| like <C-R><C-W> are interpreted in the
context of the current mode, not cmdline-mode! Thus <C-R><C-W> in a
:nnoremap (normal-mode) mapping does the normal-mode function of <C-R> and
<C-W> rather than the cmdline-mode <C-R><C-W> chord.
- In select-mode, |:map| and |:vmap| command mappings are executed in
visual-mode. Use |:smap| to handle select-mode.
*E5520* *E5520*
<Cmd> commands must terminate, that is, they must be followed by <CR> in the <Cmd> commands must terminate, that is, they must be followed by <CR> in the

10
runtime/doc/nvim.txt
View File

@ -8,14 +8,14 @@ Nvim *nvim* *nvim-intro*
Nvim is based on Vim by Bram Moolenaar. Nvim is based on Vim by Bram Moolenaar.
If you already use Vim see |nvim-from-vim| for a quickstart.
If you are new to Vim, try the 30-minute tutorial: > If you are new to Vim, try the 30-minute tutorial: >
:Tutor<Enter> :Tutor<Enter>
If you already use Vim see |nvim-from-vim| for a quickstart. Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim
(especially editor and VimL features) is maintained where possible. See
Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim is |vim-differences| for the complete reference of differences from Vim.
maintained where possible. See |vim_diff.txt| for the complete reference of
differences from Vim.
Type |gO| to see the table of contents. Type |gO| to see the table of contents.

19
runtime/doc/options.txt
View File

@ -694,8 +694,9 @@ A jump table for the options with a short description can be found at |Q_op|.
*'background'* *'bg'* *'background'* *'bg'*
'background' 'bg' string (default "dark") 'background' 'bg' string (default "dark")
global global
When set to "dark" or "light", Nvim will adjust the default color When set to "dark" or "light", adjusts the default color groups for
groups for a dark or light background, respectively. that background type. The |TUI| or other UI sets this on startup
(triggering |OptionSet|) if it can detect the background color.
This option does NOT change the background color, it tells Nvim what This option does NOT change the background color, it tells Nvim what
the "inherited" (terminal/GUI) background looks like. the "inherited" (terminal/GUI) background looks like.
@ -878,7 +879,7 @@ A jump table for the options with a short description can be found at |Q_op|.
A list of file patterns. When one of the patterns matches with the A list of file patterns. When one of the patterns matches with the
name of the file which is written, no backup file is created. Both name of the file which is written, no backup file is created. Both
the specified file name and the full path name of the file are used. the specified file name and the full path name of the file are used.
The pattern is used like with |:autocmd|, see |autocmd-patterns|. The pattern is used like with |:autocmd|, see |autocmd-pattern|.
Watch out for special characters, see |option-backslash|. Watch out for special characters, see |option-backslash|.
When $TMPDIR, $TMP or $TEMP is not defined, it is not used for the When $TMPDIR, $TMP or $TEMP is not defined, it is not used for the
default value. "/tmp/*" is only used for Unix. default value. "/tmp/*" is only used for Unix.
@ -1831,9 +1832,9 @@ A jump table for the options with a short description can be found at |Q_op|.
name. See |option-backslash| about using backslashes. name. See |option-backslash| about using backslashes.
This has nothing to do with the |Dictionary| variable type. This has nothing to do with the |Dictionary| variable type.
Where to find a list of words? Where to find a list of words?
- On FreeBSD, there is the file "/usr/share/dict/words". - BSD/macOS include the "/usr/share/dict/words" file.
- In the Simtel archive, look in the "msdos/linguist" directory. - Try "apt install spell" to get the "/usr/share/dict/words" file on
- In "miscfiles" of the GNU collection. apt-managed systems (Debian/Ubuntu).
The use of |:set+=| and |:set-=| is preferred when adding or removing The use of |:set+=| and |:set-=| is preferred when adding or removing
directories from the list. This avoids problems when a future version directories from the list. This avoids problems when a future version
uses another default. uses another default.
@ -4693,6 +4694,7 @@ A jump table for the options with a short description can be found at |Q_op|.
pack/ packages |:packadd| pack/ packages |:packadd|
plugin/ plugin scripts |write-plugin| plugin/ plugin scripts |write-plugin|
print/ files for printing |postscript-print-encoding| print/ files for printing |postscript-print-encoding|
rplugin/ |remote-plugin| scripts
spell/ spell checking files |spell| spell/ spell checking files |spell|
syntax/ syntax files |mysyntaxfile| syntax/ syntax files |mysyntaxfile|
tutor/ tutorial files |:Tutor| tutor/ tutorial files |:Tutor|
@ -6127,8 +6129,7 @@ A jump table for the options with a short description can be found at |Q_op|.
global global
When set: Add 's' flag to 'shortmess' option (this makes the message When set: Add 's' flag to 'shortmess' option (this makes the message
for a search that hits the start or end of the file not being for a search that hits the start or end of the file not being
displayed). When reset: Remove 's' flag from 'shortmess' option. {Vi displayed). When reset: Remove 's' flag from 'shortmess' option.
shortens a lot of messages}
*'textwidth'* *'tw'* *'textwidth'* *'tw'*
'textwidth' 'tw' number (default 0) 'textwidth' 'tw' number (default 0)
@ -6506,7 +6507,7 @@ A jump table for the options with a short description can be found at |Q_op|.
patterns is ignored when expanding |wildcards|, completing file or patterns is ignored when expanding |wildcards|, completing file or
directory names, and influences the result of |expand()|, |glob()| and directory names, and influences the result of |expand()|, |glob()| and
|globpath()| unless a flag is passed to disable this. |globpath()| unless a flag is passed to disable this.
The pattern is used like with |:autocmd|, see |autocmd-patterns|. The pattern is used like with |:autocmd|, see |autocmd-pattern|.
Also see 'suffixes'. Also see 'suffixes'.
Example: > Example: >
:set wildignore=*.o,*.obj :set wildignore=*.o,*.obj

46
runtime/doc/provider.txt
View File

@ -26,29 +26,34 @@ Nvim supports Python |remote-plugin|s and the Vim legacy |python2| and
Note: Only the Vim 7.3 legacy interface is supported, not later features such Note: Only the Vim 7.3 legacy interface is supported, not later features such
as |python-bindeval| (Vim 7.4); use the Nvim API instead. as |python-bindeval| (Vim 7.4); use the Nvim API instead.
PYTHON QUICKSTART ~ PYTHON QUICKSTART ~
Install the "pynvim" Python package: To use Python plugins, you need the "pynvim" module. Run |:checkhealth| to see
if you already have it (some package managers install the module with Nvim
itself).
- Run |:checkhealth| to see if you already have the package (some package For Python 3 plugins:
managers install the "pynvim" Python package with Nvim itself). 1. Make sure Python 3.4+ is available in your $PATH.
2. Install the module (try "pip" if "pip3" is missing): >
pip3 install --user --upgrade pynvim
- For Python 2 plugins, make sure Python 2.7 is available in your $PATH, then For Python 2 plugins:
install the package systemwide: > 1. Make sure Python 2.7 is available in your $PATH.
sudo pip2 install --upgrade pynvim 2. Install the module (try "pip" if "pip2" is missing): >
< or for the current user: > pip2 install --user --upgrade pynvim
pip2 install --user --upgrade pynvim
< If "pip2" is missing, try "pip".
- For Python 3 plugins, make sure Python 3.4+ is available in your $PATH, then The pip `--upgrade` flag ensures that you get the latest version even if
install the package systemwide: > a previous version was already installed.
sudo pip3 install --upgrade pynvim
< or for the current user: > See also |python-virtualenv|.
pip3 install --user --upgrade pynvim
< If "pip3" is missing, try "pip". Note: The old "neovim" module was renamed to "pynvim".
https://github.com/neovim/neovim/wiki/Following-HEAD#20181118
If you run into problems, uninstall _both_ then install "pynvim" again: >
pip uninstall neovim pynvim
pip install pynvim
- The `--upgrade` flag ensures you have the latest version even if a previous
version was already installed.
PYTHON PROVIDER CONFIGURATION ~ PYTHON PROVIDER CONFIGURATION ~
*g:python_host_prog* *g:python_host_prog*
@ -69,8 +74,9 @@ To disable Python 2 support: >
To disable Python 3 support: > To disable Python 3 support: >
let g:loaded_python3_provider = 1 let g:loaded_python3_provider = 1
PYTHON VIRTUALENVS ~
PYTHON VIRTUALENVS ~
*python-virtualenv*
If you plan to use per-project virtualenvs often, you should assign one If you plan to use per-project virtualenvs often, you should assign one
virtualenv for Neovim and hard-code the interpreter path via virtualenv for Neovim and hard-code the interpreter path via
|g:python3_host_prog| (or |g:python_host_prog|) so that the "pynvim" package |g:python3_host_prog| (or |g:python_host_prog|) so that the "pynvim" package
@ -93,6 +99,7 @@ Ruby integration *provider-ruby*
Nvim supports Ruby |remote-plugin|s and the Vim legacy |ruby-vim| interface Nvim supports Ruby |remote-plugin|s and the Vim legacy |ruby-vim| interface
(which is itself implemented as a Nvim remote-plugin). (which is itself implemented as a Nvim remote-plugin).
RUBY QUICKSTART ~ RUBY QUICKSTART ~
To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: > To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: >
@ -100,6 +107,7 @@ To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: >
Run |:checkhealth| to see if your system is up-to-date. Run |:checkhealth| to see if your system is up-to-date.
RUBY PROVIDER CONFIGURATION ~ RUBY PROVIDER CONFIGURATION ~
*g:loaded_ruby_provider* *g:loaded_ruby_provider*
To disable Ruby support: > To disable Ruby support: >
@ -122,6 +130,7 @@ Node.js integration *provider-nodejs*
Nvim supports Node.js |remote-plugin|s. Nvim supports Node.js |remote-plugin|s.
https://github.com/neovim/node-client/ https://github.com/neovim/node-client/
NODEJS QUICKSTART~ NODEJS QUICKSTART~
To use javascript remote-plugins with Nvim, install the "neovim" npm package: > To use javascript remote-plugins with Nvim, install the "neovim" npm package: >
@ -129,6 +138,7 @@ To use javascript remote-plugins with Nvim, install the "neovim" npm package: >
Run |:checkhealth| to see if your system is up-to-date. Run |:checkhealth| to see if your system is up-to-date.
NODEJS PROVIDER CONFIGURATION~ NODEJS PROVIDER CONFIGURATION~
*g:loaded_node_provider* *g:loaded_node_provider*
To disable Node.js support: > To disable Node.js support: >

8
runtime/doc/remote_plugin.txt
View File

@ -122,10 +122,10 @@ the example, say the Java plugin is a semantic completion engine for Java code.
If it defines the autocommand "BufEnter *.java", then the Java host is spawned If it defines the autocommand "BufEnter *.java", then the Java host is spawned
only when Nvim loads a buffer matching "*.java". only when Nvim loads a buffer matching "*.java".
If the explicit call to |:UpdateRemotePlugins| seems incovenient, try to see it If the explicit call to |:UpdateRemotePlugins| seems inconvenient, try to see
like this: It's a way to provide IDE capabilities in Nvim while still keeping it like this: It's a way to provide IDE capabilities in Nvim while still
it fast and lightweight for general use. It's also analogous to the |:helptags| keeping it fast and lightweight for general use. It's also analogous to the
command. |:helptags| command.
*$NVIM_RPLUGIN_MANIFEST* *$NVIM_RPLUGIN_MANIFEST*
Unless $NVIM_RPLUGIN_MANIFEST is set the manifest will be written to a file Unless $NVIM_RPLUGIN_MANIFEST is set the manifest will be written to a file

22
runtime/doc/ui.txt
View File

@ -648,28 +648,6 @@ compatibility).
["cmdline_block_hide"] ["cmdline_block_hide"]
Hide the block. Hide the block.
==============================================================================
Wildmenu Events *ui-wildmenu*
Only sent if `ext_wildmenu` option is set in |ui-options|
Deprecated. When `ext_cmdline` and `ext_popupmenu` are both set,
|ui-popupmenu| events will be used for command-line completion. But if
`ext_wildmenu` is also set, these events are still used for backwards
compatibility. New clients should use `ext_popupmenu` instead.
["wildmenu_show", items]
Activate the wildmenu (command-line completion). `items` is an array
with the completion items.
["wildmenu_select", selected]
Select an item in the current wildmenu. `selected` is a zero-based
index into the array of items from the last wildmenu_show event, or -1
if no item is selected.
["wildmenu_hide"]
Hide the wildmenu.
============================================================================== ==============================================================================
Message Events *ui-messages* Message Events *ui-messages*

2
runtime/doc/usr_43.txt
View File

@ -94,7 +94,7 @@ unless it was set already. This will make sure that 'filetype' isn't set
twice. twice.
You can use many different patterns to match the name of your file. Directory You can use many different patterns to match the name of your file. Directory
names can also be included. See |autocmd-patterns|. For example, the files names can also be included. See |autocmd-pattern|. For example, the files
under "/usr/share/scripts/" are all "ruby" files, but don't have the expected under "/usr/share/scripts/" are all "ruby" files, but don't have the expected
file name extension. Adding this to the example above: > file name extension. Adding this to the example above: >

5
runtime/doc/vim_diff.txt
View File

@ -6,8 +6,9 @@
Differences between Nvim and Vim *vim-differences* Differences between Nvim and Vim *vim-differences*
Nvim differs from Vim in many ways, big and small. This document is Nvim differs from Vim in many ways, although editor and VimL features are
a complete and centralized reference of those differences. mostly identical. This document is a complete and centralized reference of
the differences.
Type |gO| to see the table of contents. Type |gO| to see the table of contents.

303
scripts/gen_api_vimdoc.py → scripts/gen_vimdoc.py
View File

@ -1,5 +1,5 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
"""Parses Doxygen XML output to generate Neovim's API documentation. """Generates Nvim help docs from C docstrings, by parsing Doxygen XML.
This would be easier using lxml and XSLT, but: This would be easier using lxml and XSLT, but:
@ -35,6 +35,8 @@ import sys
import shutil import shutil
import textwrap import textwrap
import subprocess import subprocess
import collections
import pprint
from xml.dom import minidom from xml.dom import minidom
@ -42,6 +44,10 @@ if sys.version_info[0] < 3:
print("use Python 3") print("use Python 3")
sys.exit(1) sys.exit(1)
DEBUG = ('DEBUG' in os.environ)
INCLUDE_C_DECL = ('INCLUDE_C_DECL' in os.environ)
INCLUDE_DEPRECATED = ('INCLUDE_DEPRECATED' in os.environ)
doc_filename = 'api.txt' doc_filename = 'api.txt'
# String used to find the start of the generated part of the doc. # String used to find the start of the generated part of the doc.
section_start_token = '*api-global*' section_start_token = '*api-global*'
@ -83,6 +89,12 @@ seen_funcs = set()
# deprecated functions. # deprecated functions.
xrefs = set() xrefs = set()
def debug_this(s, n):
o = n if isinstance(n, str) else n.toprettyxml(indent=' ', newl='\n')
name = '' if isinstance(n, str) else n.nodeName
if s in o:
raise RuntimeError('xxx: {}\n{}'.format(name, o))
# XML Parsing Utilities {{{ # XML Parsing Utilities {{{
def find_first(parent, name): def find_first(parent, name):
@ -123,6 +135,10 @@ def clean_lines(text):
return re.sub(r'\A\n\s*\n*|\n\s*\n*\Z', '', re.sub(r'(\n\s*\n+)+', '\n\n', text)) return re.sub(r'\A\n\s*\n*|\n\s*\n*\Z', '', re.sub(r'(\n\s*\n+)+', '\n\n', text))
def is_blank(text):
return '' == clean_lines(text)
def get_text(parent): def get_text(parent):
"""Combine all text in a node.""" """Combine all text in a node."""
if parent.nodeType == parent.TEXT_NODE: if parent.nodeType == parent.TEXT_NODE:
@ -137,16 +153,43 @@ def get_text(parent):
return out return out
def doc_wrap(text, prefix='', width=70, func=False): # Gets the length of the last line in `text`, excluding newline ("\n") char.
def len_lastline(text):
lastnl = text.rfind('\n')
if -1 == lastnl:
return len(text)
if '\n' == text[-1]:
return lastnl - (1+ text.rfind('\n', 0, lastnl))
return len(text) - (1 + lastnl)
def len_lastline_withoutindent(text, indent):
n = len_lastline(text)
return (n - len(indent)) if n > len(indent) else 0
# Returns True if node `n` contains only inline (not block-level) elements.
def is_inline(n):
for c in n.childNodes:
if c.nodeType != c.TEXT_NODE and c.nodeName != 'computeroutput':
return False
if not is_inline(c):
return False
return True
def doc_wrap(text, prefix='', width=70, func=False, indent=None):
"""Wraps text to `width`. """Wraps text to `width`.
The first line is prefixed with `prefix`, and subsequent lines are aligned. First line is prefixed with `prefix`, subsequent lines are aligned.
If `func` is True, only wrap at commas. If `func` is True, only wrap at commas.
""" """
if not width: if not width:
# return prefix + text
return text return text
indent_space = ' ' * len(prefix) # Whitespace used to indent all lines except the first line.
indent = ' ' * len(prefix) if indent is None else indent
indent_only = (prefix == '' and indent is not None)
if func: if func:
lines = [prefix] lines = [prefix]
@ -154,27 +197,37 @@ def doc_wrap(text, prefix='', width=70, func=False):
if part[-1] not in ');': if part[-1] not in ');':
part += ', ' part += ', '
if len(lines[-1]) + len(part) > width: if len(lines[-1]) + len(part) > width:
lines.append(indent_space) lines.append(indent)
lines[-1] += part lines[-1] += part
return '\n'.join(x.rstrip() for x in lines).rstrip() return '\n'.join(x.rstrip() for x in lines).rstrip()
# XXX: Dummy prefix to force TextWrapper() to wrap the first line.
if indent_only:
prefix = indent
tw = textwrap.TextWrapper(break_long_words = False, tw = textwrap.TextWrapper(break_long_words = False,
break_on_hyphens = False, break_on_hyphens = False,
width=width, width=width,
initial_indent=prefix, initial_indent=prefix,
subsequent_indent=indent_space) subsequent_indent=indent)
return '\n'.join(tw.wrap(text.strip())) result = '\n'.join(tw.wrap(text.strip()))
# XXX: Remove the dummy prefix.
if indent_only:
result = result[len(indent):]
return result
def parse_params(parent, width=62): def render_params(parent, width=62):
"""Parse Doxygen `parameterlist`.""" """Renders Doxygen <parameterlist> tag as Vim help text."""
name_length = 0 name_length = 0
items = [] items = []
for child in parent.childNodes: for node in parent.childNodes:
if child.nodeType == child.TEXT_NODE: if node.nodeType == node.TEXT_NODE:
continue continue
name_node = find_first(child, 'parametername') name_node = find_first(node, 'parametername')
if name_node.getAttribute('direction') == 'out': if name_node.getAttribute('direction') == 'out':
continue continue
@ -184,79 +237,152 @@ def parse_params(parent, width=62):
name = '{%s}' % name name = '{%s}' % name
name_length = max(name_length, len(name) + 2) name_length = max(name_length, len(name) + 2)
items.append((name.strip(), node))
out = ''
for name, node in items:
name = ' {}'.format(name.ljust(name_length))
desc = '' desc = ''
desc_node = get_child(child, 'parameterdescription') desc_node = get_child(node, 'parameterdescription')
if desc_node: if desc_node:
desc = parse_parblock(desc_node, width=None) desc = parse_parblock(desc_node, width=width,
items.append((name.strip(), desc.strip())) indent=(' ' * len(name)))
out = 'Parameters: ~\n' out += '{}{}\n'.format(name, desc)
for name, desc in items: return out.rstrip()
name = ' %s' % name.ljust(name_length)
out += doc_wrap(desc, prefix=name, width=width) + '\n'
return out.strip()
# Renders a node as Vim help text, recursively traversing all descendants.
def render_node(n, text, prefix='', indent='', width=62):
text = ''
# space_preceding = (len(text) > 0 and ' ' == text[-1][-1])
# text += (int(not space_preceding) * ' ')
def parse_para(parent, width=62): if n.nodeType == n.TEXT_NODE:
"""Parse doxygen `para` tag. # `prefix` is NOT sent to doc_wrap, it was already handled by now.
text += doc_wrap(n.data, indent=indent, width=width)
elif n.nodeName == 'computeroutput':
text += ' `{}` '.format(get_text(n))
elif is_inline(n):
for c in n.childNodes:
text += render_node(c, text)
text = doc_wrap(text, indent=indent, width=width)
elif n.nodeName == 'verbatim':
# TODO: currently we don't use this. The "[verbatim]" hint is there as
# a reminder that we must decide how to format this if we do use it.
text += ' [verbatim] {}'.format(get_text(n))
elif n.nodeName == 'listitem':
for c in n.childNodes:
text += indent + prefix + render_node(c, text, indent=indent+(' ' * len(prefix)), width=width)
elif n.nodeName == 'para':
for c in n.childNodes:
text += render_node(c, text, indent=indent, width=width)
if is_inline(n):
text = doc_wrap(text, indent=indent, width=width)
elif n.nodeName == 'itemizedlist':
for c in n.childNodes:
text += '{}\n'.format(render_node(c, text, prefix='- ',
indent=indent, width=width))
elif n.nodeName == 'orderedlist':
i = 1
for c in n.childNodes:
if is_blank(get_text(c)):
text += '\n'
continue
text += '{}\n'.format(render_node(c, text, prefix='{}. '.format(i),
indent=indent, width=width))
i = i + 1
elif n.nodeName == 'simplesect' and 'note' == n.getAttribute('kind'):
text += 'Note:\n '
for c in n.childNodes:
text += render_node(c, text, indent=' ', width=width)
text += '\n'
elif n.nodeName == 'simplesect' and 'warning' == n.getAttribute('kind'):
text += 'Warning:\n '
for c in n.childNodes:
text += render_node(c, text, indent=' ', width=width)
text += '\n'
elif (n.nodeName == 'simplesect'
and n.getAttribute('kind') in ('return', 'see')):
text += ' '
for c in n.childNodes:
text += render_node(c, text, indent=' ', width=width)
else:
raise RuntimeError('unhandled node type: {}\n{}'.format(
n.nodeName, n.toprettyxml(indent=' ', newl='\n')))
return text
I assume <para> is a paragraph block or "a block of text". It can contain def render_para(parent, indent='', width=62):
text nodes, or other tags. """Renders Doxygen <para> containing arbitrary nodes.
NB: Blank lines in a docstring manifest as <para> tags.
""" """
line = '' if is_inline(parent):
lines = [] return clean_lines(doc_wrap(render_node(parent, ''),
indent=indent, width=width).strip())
# Ordered dict of ordered lists.
groups = collections.OrderedDict([
('params', []),
('return', []),
('seealso', []),
('xrefs', []),
])
# Gather nodes into groups. Mostly this is because we want "parameterlist"
# nodes to appear together.
text = ''
kind = ''
last = ''
for child in parent.childNodes: for child in parent.childNodes:
if child.nodeType == child.TEXT_NODE: if child.nodeName == 'parameterlist':
line += child.data groups['params'].append(child)
elif child.nodeName == 'computeroutput': elif child.nodeName == 'xrefsect':
line += '`%s`' % get_text(child) groups['xrefs'].append(child)
else: elif child.nodeName == 'simplesect':
if line: last = kind
lines.append(doc_wrap(line, width=width)) kind = child.getAttribute('kind')
line = '' if kind == 'return' or (kind == 'note' and last == 'return'):
groups['return'].append(child)
if child.nodeName == 'parameterlist': elif kind == 'see':
lines.append(parse_params(child, width=width)) groups['seealso'].append(child)
elif child.nodeName == 'xrefsect': elif kind in ('note', 'warning'):
title = get_text(get_child(child, 'xreftitle')) text += render_node(child, text, indent=indent, width=width)
xrefs.add(title)
xrefdesc = parse_para(get_child(child, 'xrefdescription'))
lines.append(doc_wrap(xrefdesc, prefix='%s: ' % title,
width=width) + '\n')
elif child.nodeName == 'simplesect':
kind = child.getAttribute('kind')
if kind == 'note':
lines.append('Note:')
lines.append(doc_wrap(parse_para(child),
prefix=' ',
width=width))
elif kind == 'return':
lines.append('%s: ~' % kind.title())
lines.append(doc_wrap(parse_para(child),
prefix=' ',
width=width))
else: else:
lines.append(get_text(child)) raise RuntimeError('unhandled simplesect: {}\n{}'.format(
child.nodeName, child.toprettyxml(indent=' ', newl='\n')))
else:
text += render_node(child, text, indent=indent, width=width)
if line: chunks = [text]
lines.append(doc_wrap(line, width=width)) # Generate text from the gathered items.
return clean_lines('\n'.join(lines).strip()) if len(groups['params']) > 0:
chunks.append('\nParameters: ~')
for child in groups['params']:
chunks.append(render_params(child, width=width))
if len(groups['return']) > 0:
chunks.append('\nReturn: ~')
for child in groups['return']:
chunks.append(render_node(child, chunks[-1][-1], indent=indent, width=width))
if len(groups['seealso']) > 0:
chunks.append('\nSee also: ~')
for child in groups['seealso']:
chunks.append(render_node(child, chunks[-1][-1], indent=indent, width=width))
for child in groups['xrefs']:
title = get_text(get_child(child, 'xreftitle'))
xrefs.add(title)
xrefdesc = render_para(get_child(child, 'xrefdescription'), width=width)
chunks.append(doc_wrap(xrefdesc, prefix='{}: '.format(title),
width=width) + '\n')
return clean_lines('\n'.join(chunks).strip())
def parse_parblock(parent, width=62): def parse_parblock(parent, prefix='', width=62, indent=''):
"""Parses a nested block of `para` tags. """Renders a nested block of <para> tags as Vim help text."""
Named after the \parblock command, but not directly related.
"""
paragraphs = [] paragraphs = []
for child in parent.childNodes: for child in parent.childNodes:
if child.nodeType == child.TEXT_NODE: paragraphs.append(render_para(child, width=width, indent=indent))
paragraphs.append(doc_wrap(child.data, width=width))
elif child.nodeName == 'para':
paragraphs.append(parse_para(child, width=width))
else:
paragraphs.append(doc_wrap(get_text(child), width=width))
paragraphs.append('') paragraphs.append('')
return clean_lines('\n'.join(paragraphs).strip()) return clean_lines('\n'.join(paragraphs).strip())
# }}} # }}}
@ -292,7 +418,7 @@ def parse_source_xml(filename):
if return_type.startswith(('ArrayOf', 'DictionaryOf')): if return_type.startswith(('ArrayOf', 'DictionaryOf')):
parts = return_type.strip('_').split('_') parts = return_type.strip('_').split('_')
return_type = '%s(%s)' % (parts[0], ', '.join(parts[1:])) return_type = '{}({})'.format(parts[0], ', '.join(parts[1:]))
name = get_text(get_child(member, 'name')) name = get_text(get_child(member, 'name'))
@ -306,37 +432,37 @@ def parse_source_xml(filename):
annotations = filter(None, map(lambda x: annotation_map.get(x), annotations = filter(None, map(lambda x: annotation_map.get(x),
annotations.split())) annotations.split()))
vimtag = '*%s()*' % name vimtag = '*{}()*'.format(name)
args = [] params = []
type_length = 0 type_length = 0
for param in get_children(member, 'param'): for param in get_children(member, 'param'):
arg_type = get_text(get_child(param, 'type')).strip() param_type = get_text(get_child(param, 'type')).strip()
arg_name = '' param_name = ''
declname = get_child(param, 'declname') declname = get_child(param, 'declname')
if declname: if declname:
arg_name = get_text(declname).strip() param_name = get_text(declname).strip()
if arg_name in param_exclude: if param_name in param_exclude:
continue continue
if arg_type.endswith('*'): if param_type.endswith('*'):
arg_type = arg_type.strip('* ') param_type = param_type.strip('* ')
arg_name = '*' + arg_name param_name = '*' + param_name
type_length = max(type_length, len(arg_type)) type_length = max(type_length, len(param_type))
args.append((arg_type, arg_name)) params.append((param_type, param_name))
c_args = [] c_args = []
for arg_type, arg_name in args: for param_type, param_name in params:
c_args.append(' ' + ( c_args.append(' ' + (
'%s %s' % (arg_type.ljust(type_length), arg_name)).strip()) '%s %s' % (param_type.ljust(type_length), param_name)).strip())
c_decl = textwrap.indent('%s %s(\n%s\n);' % (return_type, name, c_decl = textwrap.indent('%s %s(\n%s\n);' % (return_type, name,
',\n'.join(c_args)), ',\n'.join(c_args)),
' ') ' ')
prefix = '%s(' % name prefix = '%s(' % name
suffix = '%s)' % ', '.join('{%s}' % a[1] for a in args suffix = '%s)' % ', '.join('{%s}' % a[1] for a in params
if a[0] not in ('void', 'Error')) if a[0] not in ('void', 'Error'))
# Minimum 8 chars between signature and vimtag # Minimum 8 chars between signature and vimtag
@ -354,7 +480,7 @@ def parse_source_xml(filename):
desc = find_first(member, 'detaileddescription') desc = find_first(member, 'detaileddescription')
if desc: if desc:
doc = parse_parblock(desc) doc = parse_parblock(desc)
if 'DEBUG' in os.environ: if DEBUG:
print(textwrap.indent( print(textwrap.indent(
re.sub(r'\n\s*\n+', '\n', re.sub(r'\n\s*\n+', '\n',
desc.toprettyxml(indent=' ', newl='\n')), ' ' * 16)) desc.toprettyxml(indent=' ', newl='\n')), ' ' * 16))
@ -372,7 +498,7 @@ def parse_source_xml(filename):
else: else:
doc = doc[:i] + annotations + '\n\n' + doc[i:] doc = doc[:i] + annotations + '\n\n' + doc[i:]
if 'INCLUDE_C_DECL' in os.environ: if INCLUDE_C_DECL:
doc += '\n\nC Declaration: ~\n>\n' doc += '\n\nC Declaration: ~\n>\n'
doc += c_decl doc += c_decl
doc += '\n<' doc += '\n<'
@ -464,7 +590,7 @@ def gen_docs(config):
if functions: if functions:
doc += '\n\n' + functions doc += '\n\n' + functions
if 'INCLUDE_DEPRECATED' in os.environ and deprecated: if INCLUDE_DEPRECATED and deprecated:
doc += '\n\n\nDeprecated %s Functions: ~\n\n' % name doc += '\n\n\nDeprecated %s Functions: ~\n\n' % name
doc += deprecated doc += deprecated
@ -551,6 +677,7 @@ XML_PROGRAMLISTING = NO
ENABLE_PREPROCESSING = YES ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = NO EXPAND_ONLY_PREDEF = NO
MARKDOWN_SUPPORT = YES
''' '''
# }}} # }}}

59
src/nvim/api/buffer.c
View File

@ -49,7 +49,7 @@
/// Gets the buffer line count /// Gets the buffer line count
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Line count, or 0 for unloaded buffer. |api-buffer| /// @return Line count, or 0 for unloaded buffer. |api-buffer|
Integer nvim_buf_line_count(Buffer buffer, Error *err) Integer nvim_buf_line_count(Buffer buffer, Error *err)
@ -99,7 +99,8 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
/// Activate updates from this buffer to the current channel. /// Activate updates from this buffer to the current channel.
/// ///
/// @param buffer The buffer handle /// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param send_buffer Set to true if the initial notification should contain /// @param send_buffer Set to true if the initial notification should contain
/// the whole buffer. If so, the first notification will be a /// the whole buffer. If so, the first notification will be a
/// `nvim_buf_lines_event`. Otherwise, the first notification will be /// `nvim_buf_lines_event`. Otherwise, the first notification will be
@ -131,7 +132,8 @@ Boolean nvim_buf_attach(uint64_t channel_id,
// //
/// Deactivate updates from this buffer to the current channel. /// Deactivate updates from this buffer to the current channel.
/// ///
/// @param buffer The buffer handle /// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Details of an error that may have occurred /// @param[out] err Details of an error that may have occurred
/// @return False when updates couldn't be disabled because the buffer /// @return False when updates couldn't be disabled because the buffer
/// isn't loaded; otherwise True. /// isn't loaded; otherwise True.
@ -221,7 +223,8 @@ ArrayOf(String) buffer_get_line_slice(Buffer buffer,
/// Out-of-bounds indices are clamped to the nearest valid value, unless /// Out-of-bounds indices are clamped to the nearest valid value, unless
/// `strict_indexing` is set. /// `strict_indexing` is set.
/// ///
/// @param buffer Buffer handle /// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param start First line index /// @param start First line index
/// @param end Last line index (exclusive) /// @param end Last line index (exclusive)
/// @param strict_indexing Whether out-of-bounds should be an error. /// @param strict_indexing Whether out-of-bounds should be an error.
@ -290,7 +293,7 @@ end:
/// newend = end + int(include_end) + int(end < 0) /// newend = end + int(include_end) + int(end < 0)
/// int(bool) = 1 if bool is true else 0 /// int(bool) = 1 if bool is true else 0
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param start First line index /// @param start First line index
/// @param end Last line index /// @param end Last line index
/// @param include_start True if the slice includes the `start` parameter /// @param include_start True if the slice includes the `start` parameter
@ -324,7 +327,8 @@ void buffer_set_line_slice(Buffer buffer,
/// Out-of-bounds indices are clamped to the nearest valid value, unless /// Out-of-bounds indices are clamped to the nearest valid value, unless
/// `strict_indexing` is set. /// `strict_indexing` is set.
/// ///
/// @param buffer Buffer handle /// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param start First line index /// @param start First line index
/// @param end Last line index (exclusive) /// @param end Last line index (exclusive)
/// @param strict_indexing Whether out-of-bounds should be an error. /// @param strict_indexing Whether out-of-bounds should be an error.
@ -491,7 +495,7 @@ end:
/// Unlike |line2byte()|, throws error for out-of-bounds indexing. /// Unlike |line2byte()|, throws error for out-of-bounds indexing.
/// Returns -1 for unloaded buffer. /// Returns -1 for unloaded buffer.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param index Line index /// @param index Line index
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Integer byte offset, or -1 for unloaded buffer. /// @return Integer byte offset, or -1 for unloaded buffer.
@ -518,7 +522,7 @@ Integer nvim_buf_get_offset(Buffer buffer, Integer index, Error *err)
/// Gets a buffer-scoped (b:) variable. /// Gets a buffer-scoped (b:) variable.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name /// @param name Variable name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Variable value /// @return Variable value
@ -536,7 +540,7 @@ Object nvim_buf_get_var(Buffer buffer, String name, Error *err)
/// Gets a changed tick of a buffer /// Gets a changed tick of a buffer
/// ///
/// @param[in] buffer Buffer handle. /// @param[in] buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// ///
/// @return `b:changedtick` value. /// @return `b:changedtick` value.
@ -555,7 +559,7 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
/// Gets a list of buffer-local |mapping| definitions. /// Gets a list of buffer-local |mapping| definitions.
/// ///
/// @param mode Mode short-name ("n", "i", "v", ...) /// @param mode Mode short-name ("n", "i", "v", ...)
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @returns Array of maparg()-like dictionaries describing mappings. /// @returns Array of maparg()-like dictionaries describing mappings.
/// The "buffer" key holds the associated buffer handle. /// The "buffer" key holds the associated buffer handle.
@ -573,7 +577,7 @@ ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
/// Gets a map of buffer-local |user-commands|. /// Gets a map of buffer-local |user-commands|.
/// ///
/// @param buffer Buffer handle. /// @param buffer Buffer handle, or 0 for current buffer
/// @param opts Optional parameters. Currently not used. /// @param opts Optional parameters. Currently not used.
/// @param[out] err Error details, if any. /// @param[out] err Error details, if any.
/// ///
@ -613,7 +617,7 @@ Dictionary nvim_buf_get_commands(Buffer buffer, Dictionary opts, Error *err)
/// Sets a buffer-scoped (b:) variable /// Sets a buffer-scoped (b:) variable
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name /// @param name Variable name
/// @param value Variable value /// @param value Variable value
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -631,7 +635,7 @@ void nvim_buf_set_var(Buffer buffer, String name, Object value, Error *err)
/// Removes a buffer-scoped (b:) variable /// Removes a buffer-scoped (b:) variable
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name /// @param name Variable name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_buf_del_var(Buffer buffer, String name, Error *err) void nvim_buf_del_var(Buffer buffer, String name, Error *err)
@ -650,7 +654,7 @@ void nvim_buf_del_var(Buffer buffer, String name, Error *err)
/// ///
/// @deprecated /// @deprecated
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name /// @param name Variable name
/// @param value Variable value /// @param value Variable value
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -673,7 +677,7 @@ Object buffer_set_var(Buffer buffer, String name, Object value, Error *err)
/// ///
/// @deprecated /// @deprecated
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name /// @param name Variable name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Old value /// @return Old value
@ -691,7 +695,7 @@ Object buffer_del_var(Buffer buffer, String name, Error *err)
/// Gets a buffer option value /// Gets a buffer option value
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param name Option name /// @param name Option name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Option value /// @return Option value
@ -710,7 +714,8 @@ Object nvim_buf_get_option(Buffer buffer, String name, Error *err)
/// Sets a buffer option value. Passing 'nil' as value deletes the option (only /// Sets a buffer option value. Passing 'nil' as value deletes the option (only
/// works if there's a global fallback) /// works if there's a global fallback)
/// ///
/// @param buffer Buffer handle /// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Option name /// @param name Option name
/// @param value Option value /// @param value Option value
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -732,7 +737,7 @@ void nvim_buf_set_option(uint64_t channel_id, Buffer buffer,
/// @deprecated The buffer number now is equal to the object id, /// @deprecated The buffer number now is equal to the object id,
/// so there is no need to use this function. /// so there is no need to use this function.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Buffer number /// @return Buffer number
Integer nvim_buf_get_number(Buffer buffer, Error *err) Integer nvim_buf_get_number(Buffer buffer, Error *err)
@ -751,7 +756,7 @@ Integer nvim_buf_get_number(Buffer buffer, Error *err)
/// Gets the full file name for the buffer /// Gets the full file name for the buffer
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Buffer name /// @return Buffer name
String nvim_buf_get_name(Buffer buffer, Error *err) String nvim_buf_get_name(Buffer buffer, Error *err)
@ -769,7 +774,7 @@ String nvim_buf_get_name(Buffer buffer, Error *err)
/// Sets the full file name for a buffer /// Sets the full file name for a buffer
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param name Buffer name /// @param name Buffer name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_buf_set_name(Buffer buffer, String name, Error *err) void nvim_buf_set_name(Buffer buffer, String name, Error *err)
@ -801,7 +806,7 @@ void nvim_buf_set_name(Buffer buffer, String name, Error *err)
/// Checks if a buffer is valid and loaded. See |api-buffer| for more info /// Checks if a buffer is valid and loaded. See |api-buffer| for more info
/// about unloaded buffers. /// about unloaded buffers.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @return true if the buffer is valid and loaded, false otherwise. /// @return true if the buffer is valid and loaded, false otherwise.
Boolean nvim_buf_is_loaded(Buffer buffer) Boolean nvim_buf_is_loaded(Buffer buffer)
FUNC_API_SINCE(5) FUNC_API_SINCE(5)
@ -817,7 +822,7 @@ Boolean nvim_buf_is_loaded(Buffer buffer)
/// @note Even if a buffer is valid it may have been unloaded. See |api-buffer| /// @note Even if a buffer is valid it may have been unloaded. See |api-buffer|
/// for more info about unloaded buffers. /// for more info about unloaded buffers.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @return true if the buffer is valid, false otherwise. /// @return true if the buffer is valid, false otherwise.
Boolean nvim_buf_is_valid(Buffer buffer) Boolean nvim_buf_is_valid(Buffer buffer)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)
@ -849,7 +854,7 @@ void buffer_insert(Buffer buffer,
/// Return a tuple (row,col) representing the position of the named mark /// Return a tuple (row,col) representing the position of the named mark
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param name Mark name /// @param name Mark name
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return (row, col) tuple /// @return (row, col) tuple
@ -914,7 +919,7 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
/// supported for backwards compatibility, new code should use /// supported for backwards compatibility, new code should use
/// |nvim_create_namespace| to create a new empty namespace. /// |nvim_create_namespace| to create a new empty namespace.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param ns_id namespace to use or -1 for ungrouped highlight /// @param ns_id namespace to use or -1 for ungrouped highlight
/// @param hl_group Name of the highlight group to use /// @param hl_group Name of the highlight group to use
/// @param line Line to highlight (zero-indexed) /// @param line Line to highlight (zero-indexed)
@ -964,7 +969,7 @@ Integer nvim_buf_add_highlight(Buffer buffer,
/// To clear the namespace in the entire buffer, pass in 0 and -1 to /// To clear the namespace in the entire buffer, pass in 0 and -1 to
/// line_start and line_end respectively. /// line_start and line_end respectively.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param ns_id Namespace to clear, or -1 to clear all namespaces. /// @param ns_id Namespace to clear, or -1 to clear all namespaces.
/// @param line_start Start of range of lines to clear /// @param line_start Start of range of lines to clear
/// @param line_end End of range of lines to clear (exclusive) or -1 to clear /// @param line_end End of range of lines to clear (exclusive) or -1 to clear
@ -997,7 +1002,7 @@ void nvim_buf_clear_namespace(Buffer buffer,
/// ///
/// @deprecated use |nvim_buf_clear_namespace|. /// @deprecated use |nvim_buf_clear_namespace|.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param ns_id Namespace to clear, or -1 to clear all. /// @param ns_id Namespace to clear, or -1 to clear all.
/// @param line_start Start of range of lines to clear /// @param line_start Start of range of lines to clear
/// @param line_end End of range of lines to clear (exclusive) or -1 to clear /// @param line_end End of range of lines to clear (exclusive) or -1 to clear
@ -1031,7 +1036,7 @@ void nvim_buf_clear_highlight(Buffer buffer,
/// As a shorthand, `ns_id = 0` can be used to create a new namespace for the /// As a shorthand, `ns_id = 0` can be used to create a new namespace for the
/// virtual text, the allocated id is then returned. /// virtual text, the allocated id is then returned.
/// ///
/// @param buffer Buffer handle /// @param buffer Buffer handle, or 0 for current buffer
/// @param ns_id Namespace to use or 0 to create a namespace, /// @param ns_id Namespace to use or 0 to create a namespace,
/// or -1 for a ungrouped annotation /// or -1 for a ungrouped annotation
/// @param line Line to annotate with virtual text (zero-indexed) /// @param line Line to annotate with virtual text (zero-indexed)

12
src/nvim/api/ui.c
View File

@ -29,8 +29,8 @@ typedef struct {
uint64_t channel_id; uint64_t channel_id;
Array buffer; Array buffer;
int hl_id; // current higlight for legacy put event int hl_id; // Current highlight for legacy put event.
Integer cursor_row, cursor_col; // Intended visibule cursor position Integer cursor_row, cursor_col; // Intended visible cursor position.
// Position of legacy cursor, used both for drawing and visible user cursor. // Position of legacy cursor, used both for drawing and visible user cursor.
Integer client_row, client_col; Integer client_row, client_col;
@ -264,20 +264,22 @@ static void ui_set_option(UI *ui, bool init, String name, Object value,
/// ///
/// On invalid grid handle, fails with error. /// On invalid grid handle, fails with error.
/// ///
/// @param channel_id
/// @param grid The handle of the grid to be changed. /// @param grid The handle of the grid to be changed.
/// @param width The new requested width. /// @param width The new requested width.
/// @param height The new requested height. /// @param height The new requested height.
/// @param[out] err Error details, if any
void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width, void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width,
Integer height, Error *error) Integer height, Error *err)
FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY
{ {
if (!pmap_has(uint64_t)(connected_uis, channel_id)) { if (!pmap_has(uint64_t)(connected_uis, channel_id)) {
api_set_error(error, kErrorTypeException, api_set_error(err, kErrorTypeException,
"UI not attached to channel: %" PRId64, channel_id); "UI not attached to channel: %" PRId64, channel_id);
return; return;
} }
ui_grid_resize((handle_T)grid, (int)width, (int)height, error); ui_grid_resize((handle_T)grid, (int)width, (int)height, err);
} }
/// Pushes data into UI.UIData, to be consumed later by remote_ui_flush(). /// Pushes data into UI.UIData, to be consumed later by remote_ui_flush().

269
src/nvim/api/vim.c
View File

@ -214,8 +214,8 @@ Integer nvim_input(String keys)
/// Send mouse event from GUI. /// Send mouse event from GUI.
/// ///
/// The call is non-blocking. It doesn't wait on any resulting action, but /// Non-blocking: does not wait on any result, but queues the event to be
/// queues the event to be processed soon by the event loop. /// processed soon by the event loop.
/// ///
/// @note Currently this doesn't support "scripting" multiple mouse events /// @note Currently this doesn't support "scripting" multiple mouse events
/// by calling it multiple times in a loop: the intermediate mouse /// by calling it multiple times in a loop: the intermediate mouse
@ -233,6 +233,7 @@ Integer nvim_input(String keys)
/// @param grid Grid number if the client uses |ui-multigrid|, else 0. /// @param grid Grid number if the client uses |ui-multigrid|, else 0.
/// @param row Mouse row-position (zero-based, like redraw events) /// @param row Mouse row-position (zero-based, like redraw events)
/// @param col Mouse column-position (zero-based, like redraw events) /// @param col Mouse column-position (zero-based, like redraw events)
/// @param[out] err Error details, if any
void nvim_input_mouse(String button, String action, String modifier, void nvim_input_mouse(String button, String action, String modifier,
Integer grid, Integer row, Integer col, Error *err) Integer grid, Integer row, Integer col, Error *err)
FUNC_API_SINCE(6) FUNC_API_ASYNC FUNC_API_SINCE(6) FUNC_API_ASYNC
@ -756,9 +757,9 @@ void nvim_del_var(String name, Error *err)
/// @deprecated /// @deprecated
/// @see nvim_set_var /// @see nvim_set_var
/// @return Old value or nil if there was no previous value.
/// @warning May return nil if there was no previous value /// @warning May return nil if there was no previous value
/// OR if previous value was `v:null`. /// OR if previous value was `v:null`.
/// @return Old value or nil if there was no previous value.
Object vim_set_var(String name, Object value, Error *err) Object vim_set_var(String name, Object value, Error *err)
{ {
return dict_set_var(&globvardict, name, value, false, true, err); return dict_set_var(&globvardict, name, value, false, true, err);
@ -806,6 +807,7 @@ Object nvim_get_option(String name, Error *err)
/// Sets an option value. /// Sets an option value.
/// ///
/// @param channel_id
/// @param name Option name /// @param name Option name
/// @param value New option value /// @param value New option value
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -938,6 +940,7 @@ Window nvim_get_current_win(void)
/// Sets the current window. /// Sets the current window.
/// ///
/// @param window Window handle /// @param window Window handle
/// @param[out] err Error details, if any
void nvim_set_current_win(Window window, Error *err) void nvim_set_current_win(Window window, Error *err)
FUNC_API_SINCE(1) FUNC_API_SINCE(1)
{ {
@ -959,7 +962,7 @@ void nvim_set_current_win(Window window, Error *err)
/// Creates a new, empty, unnamed buffer. /// Creates a new, empty, unnamed buffer.
/// ///
/// @param listed Controls 'buflisted' /// @param listed Sets 'buflisted'
/// @param scratch Creates a "throwaway" |scratch-buffer| for temporary work /// @param scratch Creates a "throwaway" |scratch-buffer| for temporary work
/// (always 'nomodified') /// (always 'nomodified')
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -1002,37 +1005,6 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
/// ///
/// Exactly one of `external` and `relative` must be specified. /// Exactly one of `external` and `relative` must be specified.
/// ///
/// @param buffer handle of buffer to be displayed in the window
/// @param enter whether the window should be entered (made the current window)
/// @param config Dictionary for the window configuration accepts these keys:
///
/// `relative`: If set, the window becomes a floating window. The window
/// will be placed with row,col coordinates relative to one of the
/// following:
/// "editor" the global editor grid
/// "win" a window. Use `win` to specify a window id,
/// or the current window will be used by default.
/// "cursor" the cursor position in current window.
/// `win`: When using relative='win', window id of the window where the
/// position is defined.
/// `anchor`: The corner of the float that the row,col position defines:
/// "NW" north-west (default)
/// "NE" north-east
/// "SW" south-west
/// "SE" south-east
/// `height`: window height (in character cells). Minimum of 1.
/// `width`: window width (in character cells). Minimum of 2.
/// `row`: row position. Screen cell height are used as unit. Can be
/// floating point.
/// `col`: column position. Screen cell width is used as unit. Can be
/// floating point.
/// `focusable`: Whether window can be focused by wincmds and
/// mouse events. Defaults to true. Even if set to false, the window
/// can still be entered using |nvim_set_current_win()| API call.
/// `external`: GUI should display the window as an external
/// top-level window. Currently accepts no other positioning
/// configuration together with this.
///
/// With editor positioning row=0, col=0 refers to the top-left corner of the /// With editor positioning row=0, col=0 refers to the top-left corner of the
/// screen-grid and row=Lines-1, Columns-1 refers to the bottom-right corner. /// screen-grid and row=Lines-1, Columns-1 refers to the bottom-right corner.
/// Floating point values are allowed, but the builtin implementation (used by /// Floating point values are allowed, but the builtin implementation (used by
@ -1045,8 +1017,38 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
/// could let floats hover outside of the main window like a tooltip, but /// could let floats hover outside of the main window like a tooltip, but
/// this should not be used to specify arbitrary WM screen positions. /// this should not be used to specify arbitrary WM screen positions.
/// ///
/// @param buffer handle of buffer to be displayed in the window
/// @param enter whether the window should be entered (made the current window)
/// @param config Dictionary for the window configuration accepts these keys:
/// - `relative`: If set, the window becomes a floating window. The window
/// will be placed with row,col coordinates relative to one of the
/// following:
/// - "editor" the global editor grid
/// - "win" a window. Use `win` to specify a window id,
/// or the current window will be used by default.
/// "cursor" the cursor position in current window.
/// - `win`: When using relative='win', window id of the window where the
/// position is defined.
/// - `anchor`: The corner of the float that the row,col position defines:
/// - "NW" north-west (default)
/// - "NE" north-east
/// - "SW" south-west
/// - "SE" south-east
/// - `height`: window height (in character cells). Minimum of 1.
/// - `width`: window width (in character cells). Minimum of 2.
/// - `row`: row position. Screen cell height are used as unit. Can be
/// floating point.
/// - `col`: column position. Screen cell width is used as unit. Can be
/// floating point.
/// - `focusable`: Whether window can be focused by wincmds and
/// mouse events. Defaults to true. Even if set to false, the window
/// can still be entered using |nvim_set_current_win()| API call.
/// - `external`: GUI should display the window as an external
/// top-level window. Currently accepts no other positioning
/// configuration together with this.
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return the window handle or 0 when error ///
/// @return Window handle, or 0 on error
Window nvim_open_win(Buffer buffer, Boolean enter, Dictionary config, Window nvim_open_win(Buffer buffer, Boolean enter, Dictionary config,
Error *err) Error *err)
FUNC_API_SINCE(6) FUNC_API_SINCE(6)
@ -1273,47 +1275,48 @@ Array nvim_get_api_info(uint64_t channel_id)
return rv; return rv;
} }
/// Identify the client for nvim. Can be called more than once, but subsequent /// Identifies the client. Can be called more than once; subsequent calls
/// calls will remove earlier info, which should be resent if it is still /// remove earlier info, which should be included by the caller if it is
/// valid. (This could happen if a library first identifies the channel, and a /// still valid. (E.g. if a library first identifies the channel, then a
/// plugin using that library later overrides that info) /// plugin using that library later overrides that info)
/// ///
/// @param name short name for the connected client /// @param channel_id
/// @param version Dictionary describing the version, with the following /// @param name Short name for the connected client
/// possible keys (all optional) /// @param version Dictionary describing the version, with these
/// (optional) keys:
/// - "major" major version (defaults to 0 if not set, for no release yet) /// - "major" major version (defaults to 0 if not set, for no release yet)
/// - "minor" minor version /// - "minor" minor version
/// - "patch" patch number /// - "patch" patch number
/// - "prerelease" string describing a prerelease, like "dev" or "beta1" /// - "prerelease" string describing a prerelease, like "dev" or "beta1"
/// - "commit" hash or similar identifier of commit /// - "commit" hash or similar identifier of commit
/// @param type Must be one of the following values. A client library should /// @param type Must be one of the following values. Client libraries should
/// use "remote" if the library user hasn't specified other value. /// default to "remote" unless overridden by the user.
/// - "remote" remote client that connected to nvim. /// - "remote" remote client connected to Nvim.
/// - "ui" gui frontend /// - "ui" gui frontend
/// - "embedder" application using nvim as a component, for instance /// - "embedder" application using Nvim as a component (for example,
/// IDE/editor implementing a vim mode. /// IDE/editor implementing a vim mode).
/// - "host" plugin host, typically started by nvim /// - "host" plugin host, typically started by nvim
/// - "plugin" single plugin, started by nvim /// - "plugin" single plugin, started by nvim
/// @param methods Builtin methods in the client. For a host, this does not /// @param methods Builtin methods in the client. For a host, this does not
/// include plugin methods which will be discovered later. /// include plugin methods which will be discovered later.
/// The key should be the method name, the values are dicts with /// The key should be the method name, the values are dicts with
/// the following (optional) keys: /// these (optional) keys (more keys may be added in future
/// versions of Nvim, thus unknown keys are ignored. Clients
/// must only use keys defined in this or later versions of
/// Nvim):
/// - "async" if true, send as a notification. If false or unspecified, /// - "async" if true, send as a notification. If false or unspecified,
/// use a blocking request /// use a blocking request
/// - "nargs" Number of arguments. Could be a single integer or an array /// - "nargs" Number of arguments. Could be a single integer or an array
/// two integers, minimum and maximum inclusive. /// of two integers, minimum and maximum inclusive.
/// Further keys might be added in later versions of nvim and unknown keys
/// are thus ignored. Clients must only use keys defined in this or later
/// versions of nvim!
/// ///
/// @param attributes Informal attributes describing the client. Clients might /// @param attributes Arbitrary string:string map of informal client properties.
/// define their own keys, but the following are suggested: /// Suggested keys:
/// - "website" Website of client (for instance github repository) /// - "website": Client homepage URL (e.g. GitHub repository)
/// - "license" Informal description of the license, such as "Apache 2", /// - "license": License description ("Apache 2", "GPLv3", "MIT", …)
/// "GPLv3" or "MIT" /// - "logo": URI or path to image, preferably small logo or icon.
/// - "logo" URI or path to image, preferably small logo or icon. /// .png or .svg format is preferred.
/// .png or .svg format is preferred.
/// ///
/// @param[out] err Error details, if any
void nvim_set_client_info(uint64_t channel_id, String name, void nvim_set_client_info(uint64_t channel_id, String name,
Dictionary version, String type, Dictionary version, String type,
Dictionary methods, Dictionary attributes, Dictionary methods, Dictionary attributes,
@ -1345,15 +1348,14 @@ void nvim_set_client_info(uint64_t channel_id, String name,
/// Get information about a channel. /// Get information about a channel.
/// ///
/// @returns a Dictionary, describing a channel with the /// @returns Dictionary describing a channel, with these keys:
/// following keys: /// - "stream" the stream underlying the channel
/// - "stream" the stream underlying the channel
/// - "stdio" stdin and stdout of this Nvim instance /// - "stdio" stdin and stdout of this Nvim instance
/// - "stderr" stderr of this Nvim instance /// - "stderr" stderr of this Nvim instance
/// - "socket" TCP/IP socket or named pipe /// - "socket" TCP/IP socket or named pipe
/// - "job" job with communication over its stdio /// - "job" job with communication over its stdio
/// - "mode" how data received on the channel is interpreted /// - "mode" how data received on the channel is interpreted
/// - "bytes" send and recieve raw bytes /// - "bytes" send and receive raw bytes
/// - "terminal" a |terminal| instance interprets ASCII sequences /// - "terminal" a |terminal| instance interprets ASCII sequences
/// - "rpc" |RPC| communication on the channel is active /// - "rpc" |RPC| communication on the channel is active
/// - "pty" Name of pseudoterminal, if one is used (optional). /// - "pty" Name of pseudoterminal, if one is used (optional).
@ -1394,13 +1396,13 @@ Array nvim_list_chans(void)
/// processing which have such side-effects, e.g. |:sleep| may wake timers). /// processing which have such side-effects, e.g. |:sleep| may wake timers).
/// 2. To minimize RPC overhead (roundtrips) of a sequence of many requests. /// 2. To minimize RPC overhead (roundtrips) of a sequence of many requests.
/// ///
/// @param channel_id
/// @param calls an array of calls, where each call is described by an array /// @param calls an array of calls, where each call is described by an array
/// with two elements: the request name, and an array of arguments. /// with two elements: the request name, and an array of arguments.
/// @param[out] err Details of a validation error of the nvim_multi_request call /// @param[out] err Validation error details (malformed `calls` parameter),
/// itself, i.e. malformed `calls` parameter. Errors from called methods will /// if any. Errors from batched calls are given in the return value.
/// be indicated in the return value, see below.
/// ///
/// @return an array with two elements. The first is an array of return /// @return Array of two elements. The first is an array of return
/// values. The second is NIL if all calls succeeded. If a call resulted in /// values. The second is NIL if all calls succeeded. If a call resulted in
/// an error, it is a three-element array with the zero-based index of the call /// an error, it is a three-element array with the zero-based index of the call
/// which resulted in an error, the error type and the error message. If an /// which resulted in an error, the error type and the error message. If an
@ -1491,9 +1493,8 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
/// Parse a VimL expression. /// Parse a VimL expression.
/// ///
/// @param[in] expr Expression to parse. Is always treated as a single line. /// @param[in] expr Expression to parse. Always treated as a single line.
/// @param[in] flags Flags: /// @param[in] flags Flags:
///
/// - "m" if multiple expressions in a row are allowed (only /// - "m" if multiple expressions in a row are allowed (only
/// the first one will be parsed), /// the first one will be parsed),
/// - "E" if EOC tokens are not allowed (determines whether /// - "E" if EOC tokens are not allowed (determines whether
@ -1501,7 +1502,6 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
/// operator/space, though also yielding an error). /// operator/space, though also yielding an error).
/// - "l" when needing to start parsing with lvalues for /// - "l" when needing to start parsing with lvalues for
/// ":let" or ":for". /// ":let" or ":for".
///
/// Common flag sets: /// Common flag sets:
/// - "m" to parse like for ":echo". /// - "m" to parse like for ":echo".
/// - "E" to parse like for "<C-r>=". /// - "E" to parse like for "<C-r>=".
@ -1514,63 +1514,57 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
/// starting column and ending column (latter exclusive: /// starting column and ending column (latter exclusive:
/// one should highlight region [start_col, end_col)). /// one should highlight region [start_col, end_col)).
/// ///
/// @return AST: top-level dictionary with these keys: /// @return
/// /// - AST: top-level dictionary with these keys:
/// "error": Dictionary with error, present only if parser saw some /// - "error": Dictionary with error, present only if parser saw some
/// error. Contains the following keys: /// error. Contains the following keys:
/// /// - "message": String, error message in printf format, translated.
/// "message": String, error message in printf format, translated. /// Must contain exactly one "%.*s".
/// Must contain exactly one "%.*s". /// - "arg": String, error message argument.
/// "arg": String, error message argument. /// - "len": Amount of bytes successfully parsed. With flags equal to ""
/// /// that should be equal to the length of expr string.
/// "len": Amount of bytes successfully parsed. With flags equal to "" /// (“Sucessfully parsed” here means “participated in AST
/// that should be equal to the length of expr string. /// creation”, not “till the first error”.)
/// /// - "ast": AST, either nil or a dictionary with these keys:
/// @note: “Sucessfully parsed” here means “participated in AST /// - "type": node type, one of the value names from ExprASTNodeType
/// creation”, not “till the first error”. /// stringified without "kExprNode" prefix.
/// /// - "start": a pair [line, column] describing where node is "started"
/// "ast": AST, either nil or a dictionary with these keys: /// where "line" is always 0 (will not be 0 if you will be
/// /// using nvim_parse_viml() on e.g. ":let", but that is not
/// "type": node type, one of the value names from ExprASTNodeType /// present yet). Both elements are Integers.
/// stringified without "kExprNode" prefix. /// - "len": “length” of the node. This and "start" are there for
/// "start": a pair [line, column] describing where node is “started” /// debugging purposes primary (debugging parser and providing
/// where "line" is always 0 (will not be 0 if you will be /// debug information).
/// using nvim_parse_viml() on e.g. ":let", but that is not /// - "children": a list of nodes described in top/"ast". There always
/// present yet). Both elements are Integers. /// is zero, one or two children, key will not be present
/// "len": “length” of the node. This and "start" are there for /// if node has no children. Maximum number of children
/// debugging purposes primary (debugging parser and providing /// may be found in node_maxchildren array.
/// debug information). /// - Local values (present only for certain nodes):
/// "children": a list of nodes described in top/"ast". There always /// - "scope": a single Integer, specifies scope for "Option" and
/// is zero, one or two children, key will not be present /// "PlainIdentifier" nodes. For "Option" it is one of
/// if node has no children. Maximum number of children /// ExprOptScope values, for "PlainIdentifier" it is one of
/// may be found in node_maxchildren array. /// ExprVarScope values.
/// /// - "ident": identifier (without scope, if any), present for "Option",
/// Local values (present only for certain nodes): /// "PlainIdentifier", "PlainKey" and "Environment" nodes.
/// /// - "name": Integer, register name (one character) or -1. Only present
/// "scope": a single Integer, specifies scope for "Option" and /// for "Register" nodes.
/// "PlainIdentifier" nodes. For "Option" it is one of /// - "cmp_type": String, comparison type, one of the value names from
/// ExprOptScope values, for "PlainIdentifier" it is one of /// ExprComparisonType, stringified without "kExprCmp"
/// ExprVarScope values. /// prefix. Only present for "Comparison" nodes.
/// "ident": identifier (without scope, if any), present for "Option", /// - "ccs_strategy": String, case comparison strategy, one of the
/// "PlainIdentifier", "PlainKey" and "Environment" nodes. /// value names from ExprCaseCompareStrategy,
/// "name": Integer, register name (one character) or -1. Only present /// stringified without "kCCStrategy" prefix. Only
/// for "Register" nodes. /// present for "Comparison" nodes.
/// "cmp_type": String, comparison type, one of the value names from /// - "augmentation": String, augmentation type for "Assignment" nodes.
/// ExprComparisonType, stringified without "kExprCmp" /// Is either an empty string, "Add", "Subtract" or
/// prefix. Only present for "Comparison" nodes. /// "Concat" for "=", "+=", "-=" or ".=" respectively.
/// "ccs_strategy": String, case comparison strategy, one of the /// - "invert": Boolean, true if result of comparison needs to be
/// value names from ExprCaseCompareStrategy, /// inverted. Only present for "Comparison" nodes.
/// stringified without "kCCStrategy" prefix. Only /// - "ivalue": Integer, integer value for "Integer" nodes.
/// present for "Comparison" nodes. /// - "fvalue": Float, floating-point value for "Float" nodes.
/// "augmentation": String, augmentation type for "Assignment" nodes. /// - "svalue": String, value for "SingleQuotedString" and
/// Is either an empty string, "Add", "Subtract" or /// "DoubleQuotedString" nodes.
/// "Concat" for "=", "+=", "-=" or ".=" respectively. /// @param[out] err Error details, if any
/// "invert": Boolean, true if result of comparison needs to be
/// inverted. Only present for "Comparison" nodes.
/// "ivalue": Integer, integer value for "Integer" nodes.
/// "fvalue": Float, floating-point value for "Float" nodes.
/// "svalue": String, value for "SingleQuotedString" and
/// "DoubleQuotedString" nodes.
Dictionary nvim_parse_expression(String expr, String flags, Boolean highlight, Dictionary nvim_parse_expression(String expr, String flags, Boolean highlight,
Error *err) Error *err)
FUNC_API_SINCE(4) FUNC_API_ASYNC FUNC_API_SINCE(4) FUNC_API_ASYNC
@ -2035,15 +2029,13 @@ Dictionary nvim__stats(void)
/// Gets a list of dictionaries representing attached UIs. /// Gets a list of dictionaries representing attached UIs.
/// ///
/// @return Array of UI dictionaries /// @return
/// /// Array of UI dictionaries, each with these keys:
/// Each dictionary has the following keys: /// - "height" requested height of the UI
/// - "height" requested height of the UI /// - "width" requested width of the UI
/// - "width" requested width of the UI /// - "rgb" whether the UI uses rgb colors (false implies cterm colors)
/// - "rgb" whether the UI uses rgb colors (false implies cterm colors) /// - "ext_..." Requested UI extensions, see |ui-options|
/// - "ext_..." Requested UI extensions, see |ui-options| /// - "chan" Channel id of remote UI (not present for TUI)
/// - "chan" Channel id of remote UI (not present for TUI)
///
Array nvim_list_uis(void) Array nvim_list_uis(void)
FUNC_API_SINCE(4) FUNC_API_SINCE(4)
{ {
@ -2146,6 +2138,7 @@ Object nvim_get_proc(Integer pid, Error *err)
/// @param finish Finish the completion and dismiss the popupmenu. Implies /// @param finish Finish the completion and dismiss the popupmenu. Implies
/// `insert`. /// `insert`.
/// @param opts Optional parameters. Reserved for future use. /// @param opts Optional parameters. Reserved for future use.
/// @param[out] err Error details, if any
void nvim_select_popupmenu_item(Integer item, Boolean insert, Boolean finish, void nvim_select_popupmenu_item(Integer item, Boolean insert, Boolean finish,
Dictionary opts, Error *err) Dictionary opts, Error *err)
FUNC_API_SINCE(6) FUNC_API_SINCE(6)

3
src/nvim/api/window.c
View File

@ -345,6 +345,7 @@ Object nvim_win_get_option(Window window, String name, Error *err)
/// Sets a window option value. Passing 'nil' as value deletes the option(only /// Sets a window option value. Passing 'nil' as value deletes the option(only
/// works if there's a global fallback) /// works if there's a global fallback)
/// ///
/// @param channel_id
/// @param window Window handle /// @param window Window handle
/// @param name Option name /// @param name Option name
/// @param value Option value /// @param value Option value
@ -527,9 +528,7 @@ Dictionary nvim_win_get_config(Window window, Error *err)
/// @param force Behave like `:close!` The last window of a buffer with /// @param force Behave like `:close!` The last window of a buffer with
/// unwritten changes can be closed. The buffer will become /// unwritten changes can be closed. The buffer will become
/// hidden, even if 'hidden' is not set. /// hidden, even if 'hidden' is not set.
///
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Window number
void nvim_win_close(Window window, Boolean force, Error *err) void nvim_win_close(Window window, Boolean force, Error *err)
FUNC_API_SINCE(6) FUNC_API_SINCE(6)
{ {

4
src/nvim/event/stream.h
View File

@ -13,7 +13,7 @@ typedef struct stream Stream;
/// Type of function called when the Stream buffer is filled with data /// Type of function called when the Stream buffer is filled with data
/// ///
/// @param stream The Stream instance /// @param stream The Stream instance
/// @param rbuffer The associated RBuffer instance /// @param buf The associated RBuffer instance
/// @param count Number of bytes that was read. /// @param count Number of bytes that was read.
/// @param data User-defined data /// @param data User-defined data
/// @param eof If the stream reached EOF. /// @param eof If the stream reached EOF.
@ -23,7 +23,7 @@ typedef void (*stream_read_cb)(Stream *stream, RBuffer *buf, size_t count,
/// Type of function called when the Stream has information about a write /// Type of function called when the Stream has information about a write
/// request. /// request.
/// ///
/// @param wstream The Stream instance /// @param stream The Stream instance
/// @param data User-defined data /// @param data User-defined data
/// @param status 0 on success, anything else indicates failure /// @param status 0 on success, anything else indicates failure
typedef void (*stream_write_cb)(Stream *stream, void *data, int status); typedef void (*stream_write_cb)(Stream *stream, void *data, int status);

2
src/nvim/ex_docmd.c
View File

@ -78,7 +78,7 @@
static int quitmore = 0; static int quitmore = 0;
static int ex_pressedreturn = FALSE; static int ex_pressedreturn = FALSE;
/* whether ":lcd" was produced for a session */ /// Whether ":lcd" or ":tcd" was produced for a session.
static int did_lcd; static int did_lcd;
typedef struct ucmd { typedef struct ucmd {

5
src/nvim/ui_compositor.c
View File

@ -3,6 +3,8 @@
// Compositor: merge floating grids with the main grid for display in // Compositor: merge floating grids with the main grid for display in
// TUI and non-multigrid UIs. // TUI and non-multigrid UIs.
//
// Layer-based compositing: https://en.wikipedia.org/wiki/Digital_compositing
#include <assert.h> #include <assert.h>
#include <stdbool.h> #include <stdbool.h>
@ -104,6 +106,9 @@ bool ui_comp_should_draw(void)
return composed_uis != 0 && valid_screen; return composed_uis != 0 && valid_screen;
} }
/// Places `grid` at (col,row) position with (width * height) size.
/// Adds `grid` as the top layer if it is a new layer.
///
/// TODO(bfredl): later on the compositor should just use win_float_pos events, /// TODO(bfredl): later on the compositor should just use win_float_pos events,
/// though that will require slight event order adjustment: emit the win_pos /// though that will require slight event order adjustment: emit the win_pos
/// events in the beginning of update_screen(0), rather than in ui_flush() /// events in the beginning of update_screen(0), rather than in ui_flush()

2
src/nvim/ui_compositor.h
View File

@ -1,5 +1,3 @@
// Bridge for communication between a UI thread and nvim core.
// Used by the built-in TUI and libnvim-based UIs.
#ifndef NVIM_UI_COMPOSITOR_H #ifndef NVIM_UI_COMPOSITOR_H
#define NVIM_UI_COMPOSITOR_H #define NVIM_UI_COMPOSITOR_H

17
test/functional/ui/screen.lua
View File

@ -259,22 +259,19 @@ local ext_keys = {
'messages', 'showmode', 'showcmd', 'ruler', 'float_pos', 'messages', 'showmode', 'showcmd', 'ruler', 'float_pos',
} }
-- Asserts that the screen state eventually matches an expected state -- Asserts that the screen state eventually matches an expected state.
-- --
-- This function can either be called with the positional forms -- Can be called with positional args:
-- -- screen:expect(grid, [attr_ids, attr_ignore])
-- screen:expect(grid, [attr_ids, attr_ignore]) -- screen:expect(condition)
-- screen:expect(condition) -- or keyword args (supports more options):
-- -- screen:expect{grid=[[...]], cmdline={...}, condition=function() ... end}
-- or to use additional arguments (or grid and condition at the same time)
-- the keyword form has to be used:
--
-- screen:expect{grid=[[...]], cmdline={...}, condition=function() ... end}
-- --
-- --
-- grid: Expected screen state (string). Each line represents a screen -- grid: Expected screen state (string). Each line represents a screen
-- row. Last character of each row (typically "|") is stripped. -- row. Last character of each row (typically "|") is stripped.
-- Common indentation is stripped. -- Common indentation is stripped.
-- Lines containing only "{IGNORE}|" are skipped.
-- attr_ids: Expected text attributes. Screen rows are transformed according -- attr_ids: Expected text attributes. Screen rows are transformed according
-- to this table, as follows: each substring S composed of -- to this table, as follows: each substring S composed of
-- characters having the same attributes will be substituted by -- characters having the same attributes will be substituted by