mirror of
https://github.com/neovim/neovim.git
synced 2024-12-21 03:35:02 -07:00
1766 lines
75 KiB
Plaintext
1766 lines
75 KiB
Plaintext
*api.txt* Nvim
|
|
|
|
|
|
NVIM REFERENCE MANUAL by Thiago de Arruda
|
|
|
|
|
|
Nvim API *API* *api*
|
|
|
|
Nvim exposes a powerful API that can be used by plugins and external processes
|
|
via |RPC|, |Lua| and VimL (|eval-api|).
|
|
|
|
Applications can also embed libnvim to work with the C API directly.
|
|
|
|
Type |gO| to see the table of contents.
|
|
|
|
==============================================================================
|
|
API Types *api-types*
|
|
|
|
The Nvim C API defines custom types for all function parameters. Some are just
|
|
typedefs around C99 standard types, others are Nvim-defined data structures.
|
|
|
|
Boolean -> bool
|
|
Integer (signed 64-bit integer) -> int64_t
|
|
Float (IEEE 754 double precision) -> double
|
|
String -> {char* data, size_t size} struct
|
|
Array
|
|
Dictionary
|
|
Object
|
|
|
|
The following handle types are defined as integer typedefs, but are
|
|
discriminated as separate types in an Object:
|
|
|
|
Buffer -> enum value kObjectTypeBuffer
|
|
Window -> enum value kObjectTypeWindow
|
|
Tabpage -> enum value kObjectTypeTabpage
|
|
|
|
==============================================================================
|
|
API metadata *api-metadata*
|
|
|
|
Nvim exposes API metadata as a Dictionary. Some items are described below:
|
|
|
|
version Nvim version, API level/compatibility
|
|
version.api_level API version integer *api-level*
|
|
version.api_compatible API is backwards-compatible with this level
|
|
version.api_prerelease Declares the API as unstable/unreleased >
|
|
(version.api_prerelease && fn.since == version.api_level)
|
|
functions API function signatures
|
|
ui_events UI event signatures |ui|
|
|
ui_options Supported |ui-options|
|
|
{fn}.since API level where function {fn} was introduced
|
|
{fn}.deprecated_since API level where function {fn} was deprecated
|
|
types Custom handle types defined by Nvim
|
|
error_types Possible error types returned by API functions
|
|
|
|
External programs ("clients") can use the metadata to discover the |rpc-api|.
|
|
|
|
==============================================================================
|
|
API contract *api-contract*
|
|
|
|
The Nvim API is composed of functions and events.
|
|
|
|
- Clients call functions like those described at |api-global|.
|
|
- Clients can subscribe to |ui-events|, |api-buffer-updates|, etc.
|
|
- API function names are prefixed with "nvim_".
|
|
- API event names are prefixed with "nvim_" and suffixed with "_event".
|
|
|
|
As Nvim evolves the API may change in compliance with this CONTRACT:
|
|
|
|
- New functions and events may be added.
|
|
- Any such extensions are OPTIONAL: old clients may ignore them.
|
|
- Function signatures will NOT CHANGE (after release).
|
|
- Functions introduced in the development (unreleased) version MAY CHANGE.
|
|
(Clients can dynamically check `api_prerelease`, etc. |api-metadata|)
|
|
- Event parameters will not be removed or reordered (after release).
|
|
- Events may be EXTENDED: new parameters may be added.
|
|
- New items may be ADDED to map/list parameters/results of functions and
|
|
events.
|
|
- Any such new items are OPTIONAL: old clients may ignore them.
|
|
- Existing items will not be removed (after release).
|
|
- Deprecated functions will not be removed until Nvim version 2.0
|
|
|
|
==============================================================================
|
|
Global events *api-global-events*
|
|
|
|
When a client invokes an API request as an async notification, it is not
|
|
possible for Nvim to send an error response. Instead, in case of error, the
|
|
following notification will be sent to the client:
|
|
|
|
*nvim_error_event*
|
|
nvim_error_event[{type}, {message}]
|
|
|
|
{type} is a numeric id as defined by `api_info().error_types`, and {message} is
|
|
a string with the error message.
|
|
|
|
==============================================================================
|
|
Buffer update events *api-buffer-updates*
|
|
|
|
API clients can "attach" to Nvim buffers to subscribe to buffer update events.
|
|
This is similar to |TextChanged| but more powerful and granular.
|
|
|
|
Call |nvim_buf_attach()| to receive these events on the channel:
|
|
|
|
*nvim_buf_lines_event*
|
|
nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, {more}]
|
|
|
|
When the buffer text between {firstline} and {lastline} (end-exclusive,
|
|
zero-indexed) were changed to the new text in the {linedata} list. The
|
|
granularity is a line, i.e. if a single character is changed in the editor,
|
|
the entire line is sent.
|
|
|
|
When {changedtick} is |v:null| this means the screen lines (display) changed
|
|
but not the buffer contents. {linedata} contains the changed screen lines.
|
|
This happens when 'inccommand' shows a buffer preview.
|
|
|
|
Properties:~
|
|
{buf} API buffer handle (buffer number)
|
|
|
|
{changedtick} value of |b:changedtick| for the buffer. If you send an API
|
|
command back to nvim you can check the value of |b:changedtick| as part of
|
|
your request to ensure that no other changes have been made.
|
|
|
|
{firstline} integer line number of the first line that was replaced.
|
|
Zero-indexed: if line 1 was replaced then {firstline} will be 0, not 1.
|
|
{firstline} is always less than or equal to the number of lines that were
|
|
in the buffer before the lines were replaced.
|
|
|
|
{lastline} integer line number of the first line that was not replaced
|
|
(i.e. the range {firstline}, {lastline} is end-exclusive).
|
|
Zero-indexed: if line numbers 2 to 5 were replaced, this will be 5 instead
|
|
of 6. {lastline} is always be less than or equal to the number of lines
|
|
that were in the buffer before the lines were replaced. {lastline} will be
|
|
-1 if the event is part of the initial update after attaching.
|
|
|
|
{linedata} list of strings containing the contents of the new buffer
|
|
lines. Newline characters are omitted; empty lines are sent as empty
|
|
strings.
|
|
|
|
{more} boolean, true for a "multipart" change notification: the current
|
|
change was chunked into multiple |nvim_buf_lines_event| notifications
|
|
(e.g. because it was too big).
|
|
|
|
nvim_buf_changedtick_event[{buf}, {changedtick}] *nvim_buf_changedtick_event*
|
|
|
|
When |b:changedtick| was incremented but no text was changed. Relevant for
|
|
undo/redo.
|
|
|
|
Properties:~
|
|
{buf} API buffer handle (buffer number)
|
|
{changedtick} new value of |b:changedtick| for the buffer
|
|
|
|
nvim_buf_detach_event[{buf}] *nvim_buf_detach_event*
|
|
|
|
When buffer is detached (i.e. updates are disabled). Triggered explicitly by
|
|
|nvim_buf_detach()| or implicitly in these cases:
|
|
- Buffer was |abandon|ed and 'hidden' is not set.
|
|
- Buffer was reloaded, e.g. with |:edit| or an external change triggered
|
|
|:checktime| or 'autoread'.
|
|
- Generally: whenever the buffer contents are unloaded from memory.
|
|
|
|
Properties:~
|
|
{buf} API buffer handle (buffer number)
|
|
|
|
|
|
EXAMPLE ~
|
|
|
|
Calling |nvim_buf_attach()| with send_buffer=true on an empty buffer, emits: >
|
|
nvim_buf_lines_event[{buf}, {changedtick}, 0, -1, [""], v:false]
|
|
|
|
User adds two lines to the buffer, emits: >
|
|
nvim_buf_lines_event[{buf}, {changedtick}, 0, 0, ["line1", "line2"], v:false]
|
|
|
|
User moves to a line containing the text "Hello world" and inserts "!", emits: >
|
|
nvim_buf_lines_event[{buf}, {changedtick}, {linenr}, {linenr} + 1,
|
|
["Hello world!"], v:false]
|
|
|
|
User moves to line 3 and deletes 20 lines using "20dd", emits: >
|
|
nvim_buf_lines_event[{buf}, {changedtick}, 2, 22, [], v:false]
|
|
|
|
User selects lines 3-5 using |linewise-visual| mode and then types "p" to
|
|
paste a block of 6 lines, emits: >
|
|
nvim_buf_lines_event[{buf}, {changedtick}, 2, 5,
|
|
['pasted line 1', 'pasted line 2', 'pasted line 3', 'pasted line 4',
|
|
'pasted line 5', 'pasted line 6'],
|
|
v:false
|
|
]
|
|
|
|
User reloads the buffer with ":edit", emits: >
|
|
nvim_buf_detach_event[{buf}]
|
|
|
|
==============================================================================
|
|
Buffer highlighting *api-highlights*
|
|
|
|
Nvim allows plugins to add position-based highlights to buffers. This is
|
|
similar to |matchaddpos()| but with some key differences. The added highlights
|
|
are associated with a buffer and adapts to line insertions and deletions,
|
|
similar to signs. It is also possible to manage a set of highlights as a group
|
|
and delete or replace all at once.
|
|
|
|
The intended use case are linter or semantic highlighter plugins that monitor
|
|
a buffer for changes, and in the background compute highlights to the buffer.
|
|
Another use case are plugins that show output in an append-only buffer, and
|
|
want to add highlights to the outputs. Highlight data cannot be preserved
|
|
on writing and loading a buffer to file, nor in undo/redo cycles.
|
|
|
|
Highlights are registered using the |nvim_buf_add_highlight()| function. If an
|
|
external highlighter plugin wants to add many highlights in a batch,
|
|
performance can be improved by calling |nvim_buf_add_highlight()| as an
|
|
asynchronous notification, after first (synchronously) reqesting a source id.
|
|
Example using the Nvim python-client:
|
|
>
|
|
src = vim.new_highlight_source()
|
|
|
|
buf = vim.current.buffer
|
|
for i in range(5):
|
|
buf.add_highlight("String",i,0,-1,src_id=src)
|
|
|
|
# some time later
|
|
|
|
buf.clear_highlight(src)
|
|
<
|
|
If the highlights don't need to be deleted or updated, just pass -1 as
|
|
src_id (this is the default in python). Use |nvim_buf_clear_namespace()| to
|
|
clear highlights from a specific source, in a specific line range or the
|
|
entire buffer by passing in the line range 0, -1 (the latter is the default in
|
|
python as used above).
|
|
|
|
An example of calling the api from vimscript: >
|
|
|
|
call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"])
|
|
let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4)
|
|
call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1)
|
|
|
|
" later
|
|
call nvim_buf_clear_namespace(0, src, 0, -1)
|
|
|
|
|
|
==============================================================================
|
|
Floating windows *api-floatwin*
|
|
|
|
Nvim supports floating windows, windows that are displayed on top of ordinary
|
|
windows. This is useful to implement simple widgets, such as tooltips
|
|
displaying information next to cursor text. Floating windows are fully
|
|
functional buffer windows and support user editing. They support the standard
|
|
|api-window| calls and almost all window options (with some exceptions such as
|
|
'statusline' is not supported currently).
|
|
|
|
Floating windows are created either by |nvim_open_win()| to open a new window,
|
|
or |nvim_win_set_config()| to reconfigure a normal window into a float.
|
|
Currently the position can either be grid coordinates relative to the top-left
|
|
of some window, or a position relative to the current window cursor. The
|
|
parameters for positioning are described in detail at |nvim_open_win()|.
|
|
|
|
|nvim_open_win()| assumes an existing buffer to display in the window. To create
|
|
a scratch buffer for the float, |nvim_create_buf()| can be used. The text in
|
|
the buffer can be highlighted using standard functionality, such as syntax
|
|
highlighting, or |api-highlights|.
|
|
|
|
By default, floats will use |hl-NormalFloat| as normal highlight, which
|
|
links to |hl-Pmenu| in the builtin color scheme. The 'winhighlight' option can
|
|
be used to override it. Currently, floating windows don't support any visual
|
|
decorations like a border or additional widgets like scrollbar.
|
|
|
|
Here is an example for creating a float with scratch buffer: >
|
|
|
|
let buf = nvim_create_buf(v:false, v:true)
|
|
call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"])
|
|
let opts = {'relative': 'cursor', 'width': 10, 'height': 2, 'col': 0,
|
|
\ 'row': 1, 'anchor': 'NW'}
|
|
let win = nvim_open_win(buf, 0, opts)
|
|
" optional: change highlight, otherwise Pmenu is used
|
|
call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
|
|
>
|
|
To close the float, |nvim_win_close()| can be used.
|
|
==============================================================================
|
|
Global Functions *api-global*
|
|
|
|
nvim_command({command}) *nvim_command()*
|
|
Executes an ex-command.
|
|
|
|
On execution error: fails with VimL error, does not update
|
|
v:errmsg.
|
|
|
|
Parameters: ~
|
|
{command} Ex-command string
|
|
|
|
nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()*
|
|
Gets a highlight definition by name.
|
|
|
|
Parameters: ~
|
|
{name} Highlight group name
|
|
{rgb} Export RGB colors
|
|
|
|
Return: ~
|
|
Highlight definition map
|
|
|
|
See also: ~
|
|
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()|
|
|
|
|
Parameters: ~
|
|
{hl_id} Highlight id as returned by |hlID()|
|
|
{rgb} Export RGB colors
|
|
|
|
Return: ~
|
|
Highlight definition map
|
|
|
|
See also: ~
|
|
nvim_get_hl_by_name
|
|
|
|
nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()*
|
|
Sends input-keys to Nvim, subject to various quirks controlled
|
|
by `mode` flags. This is a blocking call, unlike
|
|
|nvim_input()|.
|
|
|
|
On execution error: does not fail, but updates v:errmsg.
|
|
|
|
Parameters: ~
|
|
{keys} to be typed
|
|
{mode} behavior flags, see |feedkeys()|
|
|
{escape_csi} If true, escape K_SPECIAL/CSI bytes in
|
|
`keys`
|
|
|
|
See also: ~
|
|
feedkeys()
|
|
vim_strsave_escape_csi
|
|
|
|
nvim_input({keys}) *nvim_input()*
|
|
Queues raw user-input. Unlike |nvim_feedkeys()|, this uses a
|
|
low-level input buffer and the call is non-blocking (input is
|
|
processed asynchronously by the eventloop).
|
|
|
|
On execution error: does not fail, but updates v:errmsg.
|
|
|
|
Note:
|
|
|keycodes| like <CR> are translated, so "<" is special. To
|
|
input a literal "<", send <LT>.
|
|
Note:
|
|
For mouse events use |nvim_input_mouse()|. The pseudokey
|
|
form "<LeftMouse><col,row>" is deprecated since
|
|
|api-level| 6.
|
|
|
|
Attributes: ~
|
|
{async}
|
|
|
|
Parameters: ~
|
|
{keys} to be typed
|
|
|
|
Return: ~
|
|
Number of bytes actually written (can be fewer than
|
|
requested if the buffer becomes full).
|
|
|
|
*nvim_input_mouse()*
|
|
nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
|
|
Send mouse event from GUI.
|
|
|
|
Non-blocking: does not wait on any result, but queues the
|
|
event to be processed soon by the event loop.
|
|
|
|
Note:
|
|
Currently this doesn't support "scripting" multiple mouse
|
|
events by calling it multiple times in a loop: the
|
|
intermediate mouse positions will be ignored. It should be
|
|
used to implement real-time mouse input in a GUI. The
|
|
deprecated pseudokey form ("<LeftMouse><col,row>") of
|
|
|nvim_input()| has the same limitiation.
|
|
|
|
Attributes: ~
|
|
{async}
|
|
|
|
Parameters: ~
|
|
{button} Mouse button: one of "left", "right",
|
|
"middle", "wheel".
|
|
{action} For ordinary buttons, one of "press", "drag",
|
|
"release". For the wheel, one of "up", "down",
|
|
"left", "right".
|
|
{modifier} String of modifiers each represented by a
|
|
single char. The same specifiers are used as
|
|
for a key press, except that the "-" separator
|
|
is optional, so "C-A-", "c-a" and "CA" can all
|
|
be used to specify Ctrl+Alt+click.
|
|
{grid} Grid number if the client uses |ui-multigrid|,
|
|
else 0.
|
|
{row} Mouse row-position (zero-based, like redraw
|
|
events)
|
|
{col} Mouse column-position (zero-based, like redraw
|
|
events)
|
|
|
|
*nvim_replace_termcodes()*
|
|
nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
|
|
Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a
|
|
string with the internal representation.
|
|
|
|
Parameters: ~
|
|
{str} String to be converted.
|
|
{from_part} Legacy Vim parameter. Usually true.
|
|
{do_lt} Also translate <lt>. Ignored if `special` is
|
|
false.
|
|
{special} Replace |keycodes|, e.g. <CR> becomes a "\n"
|
|
char.
|
|
|
|
See also: ~
|
|
replace_termcodes
|
|
cpoptions
|
|
|
|
nvim_command_output({command}) *nvim_command_output()*
|
|
Executes an ex-command and returns its (non-error) output.
|
|
Shell |:!| output is not captured.
|
|
|
|
On execution error: fails with VimL error, does not update
|
|
v:errmsg.
|
|
|
|
Parameters: ~
|
|
{command} Ex-command string
|
|
|
|
nvim_eval({expr}) *nvim_eval()*
|
|
Evaluates a VimL expression (:help expression). Dictionaries
|
|
and Lists are recursively expanded.
|
|
|
|
On execution error: fails with VimL error, does not update
|
|
v:errmsg.
|
|
|
|
Parameters: ~
|
|
{expr} VimL expression string
|
|
|
|
Return: ~
|
|
Evaluation result or expanded object
|
|
|
|
nvim_execute_lua({code}, {args}) *nvim_execute_lua()*
|
|
Execute lua code. Parameters (if any) are available as `...`
|
|
inside the chunk. The chunk can return a value.
|
|
|
|
Only statements are executed. To evaluate an expression,
|
|
prefix it with `return` : return my_function(...)
|
|
|
|
Parameters: ~
|
|
{code} lua code to execute
|
|
{args} Arguments to the code
|
|
|
|
Return: ~
|
|
Return value of lua code if present or NIL.
|
|
|
|
nvim_call_function({fn}, {args}) *nvim_call_function()*
|
|
Calls a VimL function with the given arguments.
|
|
|
|
On execution error: fails with VimL error, does not update
|
|
v:errmsg.
|
|
|
|
Parameters: ~
|
|
{fn} Function to call
|
|
{args} Function arguments packed in an Array
|
|
|
|
Return: ~
|
|
Result of the function call
|
|
|
|
nvim_call_dict_function({dict}, {fn}, {args}) *nvim_call_dict_function()*
|
|
Calls a VimL |Dictionary-function| with the given arguments.
|
|
|
|
On execution error: fails with VimL error, does not update
|
|
v:errmsg.
|
|
|
|
Parameters: ~
|
|
{dict} Dictionary, or String evaluating to a VimL |self|
|
|
dict
|
|
{fn} Name of the function defined on the VimL dict
|
|
{args} Function arguments packed in an Array
|
|
|
|
Return: ~
|
|
Result of the function call
|
|
|
|
nvim_strwidth({text}) *nvim_strwidth()*
|
|
Calculates the number of display cells occupied by `text` .
|
|
<Tab> counts as one cell.
|
|
|
|
Parameters: ~
|
|
{text} Some text
|
|
|
|
Return: ~
|
|
Number of cells
|
|
|
|
nvim_list_runtime_paths() *nvim_list_runtime_paths()*
|
|
Gets the paths contained in 'runtimepath'.
|
|
|
|
Return: ~
|
|
List of paths
|
|
|
|
nvim_set_current_dir({dir}) *nvim_set_current_dir()*
|
|
Changes the global working directory.
|
|
|
|
Parameters: ~
|
|
{dir} Directory path
|
|
|
|
nvim_get_current_line() *nvim_get_current_line()*
|
|
Gets the current line.
|
|
|
|
Parameters: ~
|
|
|
|
Return: ~
|
|
Current line string
|
|
|
|
nvim_set_current_line({line}) *nvim_set_current_line()*
|
|
Sets the current line.
|
|
|
|
Parameters: ~
|
|
{line} Line contents
|
|
|
|
nvim_del_current_line() *nvim_del_current_line()*
|
|
Deletes the current line.
|
|
|
|
Parameters: ~
|
|
|
|
nvim_get_var({name}) *nvim_get_var()*
|
|
Gets a global (g:) variable.
|
|
|
|
Parameters: ~
|
|
{name} Variable name
|
|
|
|
Return: ~
|
|
Variable value
|
|
|
|
nvim_set_var({name}, {value}) *nvim_set_var()*
|
|
Sets a global (g:) variable.
|
|
|
|
Parameters: ~
|
|
{name} Variable name
|
|
{value} Variable value
|
|
|
|
nvim_del_var({name}) *nvim_del_var()*
|
|
Removes a global (g:) variable.
|
|
|
|
Parameters: ~
|
|
{name} Variable name
|
|
|
|
nvim_get_vvar({name}) *nvim_get_vvar()*
|
|
Gets a v: variable.
|
|
|
|
Parameters: ~
|
|
{name} Variable name
|
|
|
|
Return: ~
|
|
Variable value
|
|
|
|
nvim_set_vvar({name}, {value}) *nvim_set_vvar()*
|
|
Sets a v: variable, if it is not readonly.
|
|
|
|
Parameters: ~
|
|
{name} Variable name
|
|
{value} Variable value
|
|
|
|
nvim_get_option({name}) *nvim_get_option()*
|
|
Gets an option value string.
|
|
|
|
Parameters: ~
|
|
{name} Option name
|
|
|
|
Return: ~
|
|
Option value (global)
|
|
|
|
nvim_set_option({name}, {value}) *nvim_set_option()*
|
|
Sets an option value.
|
|
|
|
Parameters: ~
|
|
{name} Option name
|
|
{value} New option value
|
|
|
|
nvim_out_write({str}) *nvim_out_write()*
|
|
Writes a message to the Vim output buffer. Does not append
|
|
"\n", the message is buffered (won't display) until a linefeed
|
|
is written.
|
|
|
|
Parameters: ~
|
|
{str} Message
|
|
|
|
nvim_err_write({str}) *nvim_err_write()*
|
|
Writes a message to the Vim error buffer. Does not append
|
|
"\n", the message is buffered (won't display) until a linefeed
|
|
is written.
|
|
|
|
Parameters: ~
|
|
{str} Message
|
|
|
|
nvim_err_writeln({str}) *nvim_err_writeln()*
|
|
Writes a message to the Vim error buffer. Appends "\n", so the
|
|
buffer is flushed (and displayed).
|
|
|
|
Parameters: ~
|
|
{str} Message
|
|
|
|
See also: ~
|
|
nvim_err_write()
|
|
|
|
nvim_list_bufs() *nvim_list_bufs()*
|
|
Gets the current list of buffer handles
|
|
|
|
Includes unlisted (unloaded/deleted) buffers, like `:ls!` .
|
|
Use |nvim_buf_is_loaded()| to check if a buffer is loaded.
|
|
|
|
Return: ~
|
|
List of buffer handles
|
|
|
|
nvim_get_current_buf() *nvim_get_current_buf()*
|
|
Gets the current buffer.
|
|
|
|
Return: ~
|
|
Buffer handle
|
|
|
|
nvim_set_current_buf({buffer}) *nvim_set_current_buf()*
|
|
Sets the current buffer.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle
|
|
|
|
nvim_list_wins() *nvim_list_wins()*
|
|
Gets the current list of window handles.
|
|
|
|
Return: ~
|
|
List of window handles
|
|
|
|
nvim_get_current_win() *nvim_get_current_win()*
|
|
Gets the current window.
|
|
|
|
Return: ~
|
|
Window handle
|
|
|
|
nvim_set_current_win({window}) *nvim_set_current_win()*
|
|
Sets the current window.
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
nvim_create_buf({listed}, {scratch}) *nvim_create_buf()*
|
|
Creates a new, empty, unnamed buffer.
|
|
|
|
Parameters: ~
|
|
{listed} Sets 'buflisted'
|
|
{scratch} Creates a "throwaway" |scratch-buffer| for
|
|
temporary work (always 'nomodified')
|
|
|
|
Return: ~
|
|
Buffer handle, or 0 on error
|
|
|
|
See also: ~
|
|
buf_open_scratch
|
|
|
|
nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
|
|
Open a new window.
|
|
|
|
Currently this is used to open floating and external windows.
|
|
Floats are windows that are drawn above the split layout, at
|
|
some anchor position in some other window. Floats can be draw
|
|
internally or by external GUI with the |ui-multigrid|
|
|
extension. External windows are only supported with multigrid
|
|
GUIs, and are displayed as separate top-level windows.
|
|
|
|
For a general overview of floats, see |api-floatwin|.
|
|
|
|
Exactly one of `external` and `relative` must be specified.
|
|
|
|
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. Floating point values are allowed,
|
|
but the builtin implementation (used by TUI and GUIs without
|
|
multigrid support) will always round down to nearest integer.
|
|
|
|
Out-of-bounds values, and configurations that make the float
|
|
not fit inside the main editor, are allowed. The builtin
|
|
implementation will truncate values so floats are completely
|
|
within the main screen grid. External GUIs could let floats
|
|
hover outside of the main window like a tooltip, but this
|
|
should not be used to specify arbitrary WM screen positions.
|
|
|
|
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: ~
|
|
Window handle, or 0 on error
|
|
|
|
nvim_list_tabpages() *nvim_list_tabpages()*
|
|
Gets the current list of tabpage handles.
|
|
|
|
Return: ~
|
|
List of tabpage handles
|
|
|
|
nvim_get_current_tabpage() *nvim_get_current_tabpage()*
|
|
Gets the current tabpage.
|
|
|
|
Return: ~
|
|
Tabpage handle
|
|
|
|
nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
|
|
Sets the current tabpage.
|
|
|
|
Parameters: ~
|
|
{tabpage} Tabpage handle
|
|
|
|
nvim_create_namespace({name}) *nvim_create_namespace()*
|
|
Creates a new namespace, or gets an existing one.
|
|
|
|
Namespaces are used for buffer highlights and virtual text,
|
|
see |nvim_buf_add_highlight()| and
|
|
|nvim_buf_set_virtual_text()|.
|
|
|
|
Namespaces can be named or anonymous. If `name` matches an
|
|
existing namespace, the associated id is returned. If `name`
|
|
is an empty string a new, anonymous namespace is created.
|
|
|
|
Parameters: ~
|
|
{name} Namespace name or empty string
|
|
|
|
Return: ~
|
|
Namespace id
|
|
|
|
nvim_get_namespaces() *nvim_get_namespaces()*
|
|
Gets existing, non-anonymous namespaces.
|
|
|
|
Return: ~
|
|
dict that maps from names to namespace ids.
|
|
|
|
nvim_subscribe({event}) *nvim_subscribe()*
|
|
Subscribes to event broadcasts.
|
|
|
|
Parameters: ~
|
|
{event} Event type string
|
|
|
|
nvim_unsubscribe({event}) *nvim_unsubscribe()*
|
|
Unsubscribes to event broadcasts.
|
|
|
|
Parameters: ~
|
|
{event} Event type string
|
|
|
|
nvim_get_color_by_name({name}) *nvim_get_color_by_name()*
|
|
TODO: Documentation
|
|
|
|
nvim_get_color_map() *nvim_get_color_map()*
|
|
TODO: Documentation
|
|
|
|
nvim_get_mode() *nvim_get_mode()*
|
|
Gets the current mode. |mode()| "blocking" is true if Nvim is
|
|
waiting for input.
|
|
|
|
Return: ~
|
|
Dictionary { "mode": String, "blocking": Boolean }
|
|
|
|
Attributes: ~
|
|
{async}
|
|
|
|
nvim_get_keymap({mode}) *nvim_get_keymap()*
|
|
Gets a list of global (non-buffer-local) |mapping|
|
|
definitions.
|
|
|
|
Parameters: ~
|
|
{mode} Mode short-name ("n", "i", "v", ...)
|
|
|
|
Return: ~
|
|
Array of maparg()-like dictionaries describing mappings.
|
|
The "buffer" key is always zero.
|
|
|
|
nvim_get_commands({opts}) *nvim_get_commands()*
|
|
Gets a map of global (non-buffer-local) Ex commands.
|
|
|
|
Currently only |user-commands| are supported, not builtin Ex
|
|
commands.
|
|
|
|
Parameters: ~
|
|
{opts} Optional parameters. Currently only supports
|
|
{"builtin":false}
|
|
|
|
Return: ~
|
|
Map of maps describing commands.
|
|
|
|
nvim_get_api_info() *nvim_get_api_info()*
|
|
Returns a 2-tuple (Array), where item 0 is the current channel
|
|
id and item 1 is the |api-metadata| map (Dictionary).
|
|
|
|
Return: ~
|
|
2-tuple [{channel-id}, {api-metadata}]
|
|
|
|
Attributes: ~
|
|
{async}
|
|
|
|
*nvim_set_client_info()*
|
|
nvim_set_client_info({name}, {version}, {type}, {methods},
|
|
{attributes})
|
|
Identifies the client. Can be called more than once;
|
|
subsequent calls remove earlier info, which should be included
|
|
by the caller if it is still valid. (E.g. if a library first
|
|
identifies the channel, then a plugin using that library later
|
|
overrides that info)
|
|
|
|
Parameters: ~
|
|
{name} Short name for the connected client
|
|
{version} Dictionary describing the version, with
|
|
these (optional) keys:
|
|
- "major" major version (defaults to 0 if
|
|
not set, for no release yet)
|
|
- "minor" minor version
|
|
- "patch" patch number
|
|
- "prerelease" string describing a
|
|
prerelease, like "dev" or "beta1"
|
|
- "commit" hash or similar identifier of
|
|
commit
|
|
{type} Must be one of the following values. Client
|
|
libraries should default to "remote" unless
|
|
overridden by the user.
|
|
- "remote" remote client connected to Nvim.
|
|
- "ui" gui frontend
|
|
- "embedder" application using Nvim as a
|
|
component (for example, IDE/editor
|
|
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,
|
|
this does not include plugin methods which
|
|
will be discovered later. The key should be
|
|
the method name, the values are dicts with
|
|
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, use a blocking
|
|
request
|
|
- "nargs" Number of arguments. Could be a
|
|
single integer or an array of two
|
|
integers, minimum and maximum inclusive.
|
|
{attributes} Arbitrary string:string map of informal
|
|
client properties. Suggested keys:
|
|
- "website": Client homepage URL (e.g.
|
|
GitHub repository)
|
|
- "license": License description ("Apache
|
|
2", "GPLv3", "MIT", …)
|
|
- "logo": URI or path to image, preferably
|
|
small logo or icon. .png or .svg format is
|
|
preferred.
|
|
|
|
nvim_get_chan_info({chan}) *nvim_get_chan_info()*
|
|
Get information about a channel.
|
|
|
|
Return: ~
|
|
Dictionary describing a channel, with these 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
|
|
|
|
- "mode" how data received on the channel is interpreted
|
|
- "bytes" send and receive raw bytes
|
|
- "terminal" a |terminal| instance interprets ASCII
|
|
sequences
|
|
- "rpc" |RPC| communication on the channel is active
|
|
|
|
- "pty" Name of pseudoterminal, if one is used (optional).
|
|
On a POSIX system, this will be a device path like
|
|
/dev/pts/1. Even if the name is unknown, the key will
|
|
still be present to indicate a pty is used. This is
|
|
currently the case when using winpty on windows.
|
|
- "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()*
|
|
Get information about all open channels.
|
|
|
|
Return: ~
|
|
Array of Dictionaries, each describing a channel with the
|
|
format specified at |nvim_get_chan_info()|.
|
|
|
|
nvim_call_atomic({calls}) *nvim_call_atomic()*
|
|
Calls many API methods atomically.
|
|
|
|
This has two main usages:
|
|
1. To perform several requests from an async context
|
|
atomically, i.e. without interleaving redraws, RPC requests
|
|
from other clients, or user interactions (however API
|
|
methods may trigger autocommands or event processing which
|
|
have such side-effects, e.g. |:sleep| may wake timers).
|
|
2. To minimize RPC overhead (roundtrips) of a sequence of many
|
|
requests.
|
|
|
|
Parameters: ~
|
|
{calls} an array of calls, where each call is described
|
|
by an array with two elements: the request name,
|
|
and an array of arguments.
|
|
|
|
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 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 error
|
|
occurred, the values from all preceding calls will still
|
|
be returned.
|
|
|
|
*nvim_parse_expression()*
|
|
nvim_parse_expression({expr}, {flags}, {highlight})
|
|
Parse a VimL expression.
|
|
|
|
Attributes: ~
|
|
{async}
|
|
|
|
Parameters: ~
|
|
{expr} Expression to parse. Always treated as a
|
|
single line.
|
|
{flags} Flags:
|
|
- "m" if multiple expressions in a row are
|
|
allowed (only the first one will be
|
|
parsed),
|
|
- "E" if EOC tokens are not allowed
|
|
(determines whether they will stop parsing
|
|
process or be recognized as an
|
|
operator/space, though also yielding an
|
|
error).
|
|
- "l" when needing to start parsing with
|
|
lvalues for ":let" or ":for". Common flag
|
|
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" key containing array of 4-tuples
|
|
(arrays) (Integer, Integer, Integer, String),
|
|
where first three numbers define the
|
|
highlighted region and represent line,
|
|
starting column and ending column (latter
|
|
exclusive: one should highlight region
|
|
[start_col, end_col)).
|
|
|
|
Return: ~
|
|
|
|
- AST: top-level dictionary with these keys:
|
|
- "error": Dictionary with error, present only if parser
|
|
saw some error. Contains the following keys:
|
|
- "message": String, error message in printf format,
|
|
translated. Must contain exactly one "%.*s".
|
|
- "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. (“Sucessfully parsed” here means “participated
|
|
in AST creation”, not “till the first error”.)
|
|
- "ast": AST, either nil or a dictionary with these
|
|
keys:
|
|
- "type": node type, one of the value names from
|
|
ExprASTNodeType stringified without "kExprNode"
|
|
prefix.
|
|
- "start": a pair [line, column] describing where node
|
|
is "started" 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 present yet). Both elements
|
|
are Integers.
|
|
- "len": “length” of the node. This and "start" are
|
|
there for debugging purposes primary (debugging
|
|
parser and providing debug information).
|
|
- "children": a list of nodes described in top/"ast".
|
|
There always is zero, one or two children, key will
|
|
not be present if node has no children. Maximum
|
|
number of children may be found in node_maxchildren
|
|
array.
|
|
|
|
- Local values (present only for certain nodes):
|
|
- "scope": a single Integer, specifies scope for
|
|
"Option" and "PlainIdentifier" nodes. For "Option" it
|
|
is one of ExprOptScope values, for "PlainIdentifier"
|
|
it is one of ExprVarScope values.
|
|
- "ident": identifier (without scope, if any), present
|
|
for "Option", "PlainIdentifier", "PlainKey" and
|
|
"Environment" nodes.
|
|
- "name": Integer, register name (one character) or -1.
|
|
Only present for "Register" nodes.
|
|
- "cmp_type": String, comparison type, one of the value
|
|
names from ExprComparisonType, stringified without
|
|
"kExprCmp" prefix. Only present for "Comparison"
|
|
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()*
|
|
Returns object given as argument.
|
|
|
|
This API function is used for testing. One should not rely on
|
|
its presence in plugins.
|
|
|
|
Parameters: ~
|
|
{obj} Object to return.
|
|
|
|
Return: ~
|
|
its argument.
|
|
|
|
nvim__id_array({arr}) *nvim__id_array()*
|
|
Returns array given as argument.
|
|
|
|
This API function is used for testing. One should not rely on
|
|
its presence in plugins.
|
|
|
|
Parameters: ~
|
|
{arr} Array to return.
|
|
|
|
Return: ~
|
|
its argument.
|
|
|
|
nvim__id_dictionary({dct}) *nvim__id_dictionary()*
|
|
Returns dictionary given as argument.
|
|
|
|
This API function is used for testing. One should not rely on
|
|
its presence in plugins.
|
|
|
|
Parameters: ~
|
|
{dct} Dictionary to return.
|
|
|
|
Return: ~
|
|
its argument.
|
|
|
|
nvim__id_float({flt}) *nvim__id_float()*
|
|
Returns floating-point value given as argument.
|
|
|
|
This API function is used for testing. One should not rely on
|
|
its presence in plugins.
|
|
|
|
Parameters: ~
|
|
{flt} Value to return.
|
|
|
|
Return: ~
|
|
its argument.
|
|
|
|
nvim__stats() *nvim__stats()*
|
|
Gets internal stats.
|
|
|
|
Return: ~
|
|
Map of various internal stats.
|
|
|
|
nvim_list_uis() *nvim_list_uis()*
|
|
Gets a list of dictionaries representing attached UIs.
|
|
|
|
Return: ~
|
|
Array of UI dictionaries, each with these keys:
|
|
- "height" requested height of the UI
|
|
- "width" requested width of the UI
|
|
- "rgb" true if the UI uses RGB colors (false implies
|
|
|cterm-colors|)
|
|
- "ext_..." Requested UI extensions, see |ui-options|
|
|
- "chan" Channel id of remote UI (not present for TUI)
|
|
|
|
nvim_get_proc_children({pid}) *nvim_get_proc_children()*
|
|
Gets the immediate children of process `pid` .
|
|
|
|
Return: ~
|
|
Array of child process ids, empty if process not found.
|
|
|
|
nvim_get_proc({pid}) *nvim_get_proc()*
|
|
Gets info describing process `pid` .
|
|
|
|
Return: ~
|
|
Map of process properties, or NIL if process not found.
|
|
|
|
*nvim_select_popupmenu_item()*
|
|
nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
|
|
Selects an item in the completion popupmenu.
|
|
|
|
If |ins-completion| is not active this API call is silently
|
|
ignored. Useful for an external UI using |ui-popupmenu| to
|
|
control the popupmenu with the mouse. Can also be used in a
|
|
mapping; use <cmd> |:map-cmd| to ensure the mapping doesn't
|
|
end completion mode.
|
|
|
|
Parameters: ~
|
|
{item} Index (zero-based) of the item to select. Value
|
|
of -1 selects nothing and restores the original
|
|
text.
|
|
{insert} Whether the selection should be inserted in the
|
|
buffer.
|
|
{finish} Finish the completion and dismiss the popupmenu.
|
|
Implies `insert` .
|
|
{opts} Optional parameters. Reserved for future use.
|
|
|
|
nvim__inspect_cell({row}, {col}) *nvim__inspect_cell()*
|
|
TODO: Documentation
|
|
|
|
|
|
==============================================================================
|
|
Buffer Functions *api-buffer*
|
|
|
|
Unloaded Buffers:~
|
|
|
|
Buffers may be unloaded by the |:bunload| command or the
|
|
buffer's |'bufhidden'| option. When a buffer is unloaded its
|
|
file contents are freed from memory and vim cannot operate on
|
|
the buffer lines until it is reloaded (usually by opening the
|
|
buffer again in a new window). API methods such as
|
|
|nvim_buf_get_lines()| and |nvim_buf_line_count()| will be
|
|
affected.
|
|
|
|
You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()|
|
|
to check whether a buffer is loaded.
|
|
|
|
nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
|
|
Gets the buffer line count
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
|
|
Return: ~
|
|
Line count, or 0 for unloaded buffer. |api-buffer|
|
|
|
|
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
|
|
Activate updates from this buffer to the current channel.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{send_buffer} Set to true if the initial notification
|
|
should contain the whole buffer. If so, the
|
|
first notification will be a
|
|
`nvim_buf_lines_event` . Otherwise, the
|
|
first notification will be a
|
|
`nvim_buf_changedtick_event`
|
|
{opts} Optional parameters. Reserved for future
|
|
use.
|
|
|
|
Return: ~
|
|
False when updates couldn't be enabled because the buffer
|
|
isn't loaded or `opts` contained an invalid key; otherwise
|
|
True.
|
|
|
|
nvim_buf_detach({buffer}) *nvim_buf_detach()*
|
|
Deactivate updates from this buffer to the current channel.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
|
|
Return: ~
|
|
False when updates couldn't be disabled because the buffer
|
|
isn't loaded; otherwise True.
|
|
|
|
*nvim_buf_get_lines()*
|
|
nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
|
|
Gets a line-range from the buffer.
|
|
|
|
Indexing is zero-based, end-exclusive. Negative indices are
|
|
interpreted as length+1+index: -1 refers to the index past the
|
|
end. So to get the last element use start=-2 and end=-1.
|
|
|
|
Out-of-bounds indices are clamped to the nearest valid value,
|
|
unless `strict_indexing` is set.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{start} First line index
|
|
{end} Last line index (exclusive)
|
|
{strict_indexing} Whether out-of-bounds should be an
|
|
error.
|
|
|
|
Return: ~
|
|
Array of lines, or empty array for unloaded buffer.
|
|
|
|
*nvim_buf_set_lines()*
|
|
nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing},
|
|
{replacement})
|
|
Sets (replaces) a line-range in the buffer.
|
|
|
|
Indexing is zero-based, end-exclusive. Negative indices are
|
|
interpreted as length+1+index: -1 refers to the index past the
|
|
end. So to change or delete the last element use start=-2 and
|
|
end=-1.
|
|
|
|
To insert lines at a given index, set `start` and `end` to the
|
|
same index. To delete a range of lines, set `replacement` to
|
|
an empty array.
|
|
|
|
Out-of-bounds indices are clamped to the nearest valid value,
|
|
unless `strict_indexing` is set.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{start} First line index
|
|
{end} Last line index (exclusive)
|
|
{strict_indexing} Whether out-of-bounds should be an
|
|
error.
|
|
{replacement} Array of lines to use as replacement
|
|
|
|
nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()*
|
|
Returns the byte offset for a line.
|
|
|
|
Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is
|
|
one byte. 'fileformat' and 'fileencoding' are ignored. The
|
|
line index just after the last line gives the total byte-count
|
|
of the buffer. A final EOL byte is counted if it would be
|
|
written, see 'eol'.
|
|
|
|
Unlike |line2byte()|, throws error for out-of-bounds indexing.
|
|
Returns -1 for unloaded buffer.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{index} Line index
|
|
|
|
Return: ~
|
|
Integer byte offset, or -1 for unloaded buffer.
|
|
|
|
nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()*
|
|
Gets a buffer-scoped (b:) variable.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{name} Variable name
|
|
|
|
Return: ~
|
|
Variable value
|
|
|
|
nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()*
|
|
Gets a changed tick of a buffer
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
|
|
Return: ~
|
|
`b:changedtick` value.
|
|
|
|
nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()*
|
|
Gets a list of buffer-local |mapping| definitions.
|
|
|
|
Parameters: ~
|
|
{mode} Mode short-name ("n", "i", "v", ...)
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
|
|
Return: ~
|
|
Array of maparg()-like dictionaries describing mappings.
|
|
The "buffer" key holds the associated buffer handle.
|
|
|
|
nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()*
|
|
Gets a map of buffer-local |user-commands|.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{opts} Optional parameters. Currently not used.
|
|
|
|
Return: ~
|
|
Map of maps describing commands.
|
|
|
|
nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
|
|
Sets a buffer-scoped (b:) variable
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{name} Variable name
|
|
{value} Variable value
|
|
|
|
nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()*
|
|
Removes a buffer-scoped (b:) variable
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{name} Variable name
|
|
|
|
nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()*
|
|
Gets a buffer option value
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{name} Option name
|
|
|
|
Return: ~
|
|
Option value
|
|
|
|
nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()*
|
|
Sets a buffer option value. Passing 'nil' as value deletes the
|
|
option (only works if there's a global fallback)
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{name} Option name
|
|
{value} Option value
|
|
|
|
nvim_buf_get_name({buffer}) *nvim_buf_get_name()*
|
|
Gets the full file name for the buffer
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
|
|
Return: ~
|
|
Buffer name
|
|
|
|
nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()*
|
|
Sets the full file name for a buffer
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{name} Buffer name
|
|
|
|
nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()*
|
|
Checks if a buffer is valid and loaded. See |api-buffer| for
|
|
more info about unloaded buffers.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
|
|
Return: ~
|
|
true if the buffer is valid and loaded, false otherwise.
|
|
|
|
nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()*
|
|
Checks if a buffer is valid.
|
|
|
|
Note:
|
|
Even if a buffer is valid it may have been unloaded. See
|
|
|api-buffer| for more info about unloaded buffers.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
|
|
Return: ~
|
|
true if the buffer is valid, false otherwise.
|
|
|
|
nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
|
|
Return a tuple (row,col) representing the position of the
|
|
named mark
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{name} Mark name
|
|
|
|
Return: ~
|
|
(row, col) tuple
|
|
|
|
*nvim_buf_add_highlight()*
|
|
nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
|
|
{col_start}, {col_end})
|
|
Adds a highlight to buffer.
|
|
|
|
Useful for plugins that dynamically generate highlights to a
|
|
buffer (like a semantic highlighter or linter). The function
|
|
adds a single highlight to a buffer. Unlike |matchaddpos()|
|
|
highlights follow changes to line numbering (as lines are
|
|
inserted/removed above the highlighted line), like signs and
|
|
marks do.
|
|
|
|
Namespaces are used for batch deletion/updating of a set of
|
|
highlights. To create a namespace, use |nvim_create_namespace|
|
|
which returns a namespace id. Pass it in to this function as
|
|
`ns_id` to add highlights to the namespace. All highlights in
|
|
the same namespace can then be cleared with single call to
|
|
|nvim_buf_clear_namespace|. If the highlight never will be
|
|
deleted by an API call, pass `ns_id = -1` .
|
|
|
|
As a shorthand, `ns_id = 0` can be used to create a new
|
|
namespace for the highlight, the allocated id is then
|
|
returned. If `hl_group` is the empty string no highlight is
|
|
added, but a new `ns_id` is still returned. This is supported
|
|
for backwards compatibility, new code should use
|
|
|nvim_create_namespace| to create a new empty namespace.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{ns_id} namespace to use or -1 for ungrouped
|
|
highlight
|
|
{hl_group} Name of the highlight group to use
|
|
{line} Line to highlight (zero-indexed)
|
|
{col_start} Start of (byte-indexed) column range to
|
|
highlight
|
|
{col_end} End of (byte-indexed) column range to
|
|
highlight, or -1 to highlight to end of line
|
|
|
|
Return: ~
|
|
The ns_id that was used
|
|
|
|
*nvim_buf_clear_namespace()*
|
|
nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
|
|
Clears namespaced objects, highlights and virtual text, from a
|
|
line range
|
|
|
|
To clear the namespace in the entire buffer, pass in 0 and -1
|
|
to line_start and line_end respectively.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{ns_id} Namespace to clear, or -1 to clear all
|
|
namespaces.
|
|
{line_start} Start of range of lines to clear
|
|
{line_end} End of range of lines to clear (exclusive)
|
|
or -1 to clear to end of buffer.
|
|
|
|
*nvim_buf_set_virtual_text()*
|
|
nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
|
|
Set the virtual text (annotation) for a buffer line.
|
|
|
|
By default (and currently the only option) the text will be
|
|
placed after the buffer text. Virtual text will never cause
|
|
reflow, rather virtual text will be truncated at the end of
|
|
the screen line. The virtual text will begin one cell
|
|
(|lcs-eol| or space) after the ordinary text.
|
|
|
|
Namespaces are used to support batch deletion/updating of
|
|
virtual text. To create a namespace, use
|
|
|nvim_create_namespace|. Virtual text is cleared using
|
|
|nvim_buf_clear_namespace|. The same `ns_id` can be used for
|
|
both virtual text and highlights added by
|
|
|nvim_buf_add_highlight|, both can then be cleared with a
|
|
single call to |nvim_buf_clear_namespace|. If the virtual text
|
|
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
|
|
namespace for the virtual text, the allocated id is then
|
|
returned.
|
|
|
|
Parameters: ~
|
|
{buffer} Buffer handle, or 0 for current buffer
|
|
{ns_id} Namespace to use or 0 to create a namespace, or
|
|
-1 for a ungrouped annotation
|
|
{line} Line to annotate with virtual text
|
|
(zero-indexed)
|
|
{chunks} A list of [text, hl_group] arrays, each
|
|
representing a text chunk with specified
|
|
highlight. `hl_group` element can be omitted for
|
|
no highlight.
|
|
{opts} Optional parameters. Currently not used.
|
|
|
|
Return: ~
|
|
The ns_id that was used
|
|
|
|
|
|
==============================================================================
|
|
Window Functions *api-window*
|
|
|
|
nvim_win_get_buf({window}) *nvim_win_get_buf()*
|
|
Gets the current buffer in a window
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
Return: ~
|
|
Buffer handle
|
|
|
|
nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()*
|
|
Sets the current buffer in a window, without side-effects
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{buffer} Buffer handle
|
|
|
|
nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
|
|
Gets the cursor position in the window
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
Return: ~
|
|
(row, col) tuple
|
|
|
|
nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()*
|
|
Sets the cursor position in the window
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{pos} (row, col) tuple representing the new position
|
|
|
|
nvim_win_get_height({window}) *nvim_win_get_height()*
|
|
Gets the window height
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
Return: ~
|
|
Height as a count of rows
|
|
|
|
nvim_win_set_height({window}, {height}) *nvim_win_set_height()*
|
|
Sets the window height. This will only succeed if the screen
|
|
is split horizontally.
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{height} Height as a count of rows
|
|
|
|
nvim_win_get_width({window}) *nvim_win_get_width()*
|
|
Gets the window width
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
Return: ~
|
|
Width as a count of columns
|
|
|
|
nvim_win_set_width({window}, {width}) *nvim_win_set_width()*
|
|
Sets the window width. This will only succeed if the screen is
|
|
split vertically.
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{width} Width as a count of columns
|
|
|
|
nvim_win_get_var({window}, {name}) *nvim_win_get_var()*
|
|
Gets a window-scoped (w:) variable
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{name} Variable name
|
|
|
|
Return: ~
|
|
Variable value
|
|
|
|
nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()*
|
|
Sets a window-scoped (w:) variable
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{name} Variable name
|
|
{value} Variable value
|
|
|
|
nvim_win_del_var({window}, {name}) *nvim_win_del_var()*
|
|
Removes a window-scoped (w:) variable
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{name} Variable name
|
|
|
|
nvim_win_get_option({window}, {name}) *nvim_win_get_option()*
|
|
Gets a window option value
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{name} Option name
|
|
|
|
Return: ~
|
|
Option value
|
|
|
|
nvim_win_set_option({window}, {name}, {value}) *nvim_win_set_option()*
|
|
Sets a window option value. Passing 'nil' as value deletes the
|
|
option(only works if there's a global fallback)
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{name} Option name
|
|
{value} Option value
|
|
|
|
nvim_win_get_position({window}) *nvim_win_get_position()*
|
|
Gets the window position in display cells. First position is
|
|
zero.
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
Return: ~
|
|
(row, col) tuple with the window position
|
|
|
|
nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()*
|
|
Gets the window tabpage
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
Return: ~
|
|
Tabpage that contains the window
|
|
|
|
nvim_win_get_number({window}) *nvim_win_get_number()*
|
|
Gets the window number
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
Return: ~
|
|
Window number
|
|
|
|
nvim_win_is_valid({window}) *nvim_win_is_valid()*
|
|
Checks if a window is valid
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
Return: ~
|
|
true if the window is valid, false otherwise
|
|
|
|
nvim_win_set_config({window}, {config}) *nvim_win_set_config()*
|
|
Configure window position. Currently this is only used to
|
|
configure floating and external windows (including changing a
|
|
split window to these types).
|
|
|
|
See documentation at |nvim_open_win()|, for the meaning of
|
|
parameters.
|
|
|
|
When reconfiguring a floating window, absent option keys will
|
|
not be changed. The following restriction apply: `row` , `col`
|
|
and `relative` must be reconfigured together. Only changing a
|
|
subset of these is an error.
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{config} Dictionary of window configuration
|
|
|
|
nvim_win_get_config({window}) *nvim_win_get_config()*
|
|
Return window configuration.
|
|
|
|
Return a dictionary containing the same config that can be
|
|
given to |nvim_open_win()|.
|
|
|
|
`relative` will be an empty string for normal windows.
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
|
|
Return: ~
|
|
Window configuration
|
|
|
|
nvim_win_close({window}, {force}) *nvim_win_close()*
|
|
Close a window.
|
|
|
|
This is equivalent to |:close| with count except that it takes
|
|
a window id.
|
|
|
|
Parameters: ~
|
|
{window} Window handle
|
|
{force} Behave like `:close!` The last window of a
|
|
buffer with unwritten changes can be closed. The
|
|
buffer will become hidden, even if 'hidden' is
|
|
not set.
|
|
|
|
|
|
==============================================================================
|
|
Tabpage Functions *api-tabpage*
|
|
|
|
nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()*
|
|
Gets the windows in a tabpage
|
|
|
|
Parameters: ~
|
|
{tabpage} Tabpage
|
|
|
|
Return: ~
|
|
List of windows in `tabpage`
|
|
|
|
nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()*
|
|
Gets a tab-scoped (t:) variable
|
|
|
|
Parameters: ~
|
|
{tabpage} Tabpage handle
|
|
{name} Variable name
|
|
|
|
Return: ~
|
|
Variable value
|
|
|
|
nvim_tabpage_set_var({tabpage}, {name}, {value}) *nvim_tabpage_set_var()*
|
|
Sets a tab-scoped (t:) variable
|
|
|
|
Parameters: ~
|
|
{tabpage} Tabpage handle
|
|
{name} Variable name
|
|
{value} Variable value
|
|
|
|
nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()*
|
|
Removes a tab-scoped (t:) variable
|
|
|
|
Parameters: ~
|
|
{tabpage} Tabpage handle
|
|
{name} Variable name
|
|
|
|
nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()*
|
|
Gets the current window in a tabpage
|
|
|
|
Parameters: ~
|
|
{tabpage} Tabpage handle
|
|
|
|
Return: ~
|
|
Window handle
|
|
|
|
nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()*
|
|
Gets the tabpage number
|
|
|
|
Parameters: ~
|
|
{tabpage} Tabpage handle
|
|
|
|
Return: ~
|
|
Tabpage number
|
|
|
|
nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()*
|
|
Checks if a tabpage is valid
|
|
|
|
Parameters: ~
|
|
{tabpage} Tabpage handle
|
|
|
|
Return: ~
|
|
true if the tabpage is valid, false otherwise
|
|
|
|
|
|
==============================================================================
|
|
UI Functions *api-ui*
|
|
|
|
nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()*
|
|
TODO: Documentation
|
|
|
|
nvim_ui_detach() *nvim_ui_detach()*
|
|
TODO: Documentation
|
|
|
|
nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()*
|
|
TODO: Documentation
|
|
|
|
nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()*
|
|
TODO: Documentation
|
|
|
|
*nvim_ui_try_resize_grid()*
|
|
nvim_ui_try_resize_grid({grid}, {width}, {height})
|
|
Tell Nvim to resize a grid. Triggers a grid_resize event with
|
|
the requested grid size or the maximum size if it exceeds size
|
|
limits.
|
|
|
|
On invalid grid handle, fails with error.
|
|
|
|
Parameters: ~
|
|
{grid} The handle of the grid to be changed.
|
|
{width} The new requested width.
|
|
{height} The new requested height.
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|