mirror of
https://github.com/neovim/neovim.git
synced 2025-10-26 12:27:24 +00:00
1050 lines
41 KiB
Plaintext
1050 lines
41 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*
|
|
|
|
Nvim's C API uses custom types for all functions. Some are just typedefs
|
|
around C99 standard types, and some 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
|
|
|
|
Additionally, the following data structures are defined:
|
|
|
|
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 Current API level
|
|
version.api_compatible API is backwards-compatible with this level
|
|
version.api_prerelease Declares the current API level as unstable >
|
|
(version.api_prerelease && fn.since == version.api_level)
|
|
functions API function signatures
|
|
ui_events UI event signatures |ui|
|
|
{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 API is made of functions and events. Clients call functions like those
|
|
described at |api-global|, and may "attach" to receive rich |ui-events|.
|
|
|
|
As Nvim develops, its API may change only according the following "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
|
|
|
|
==============================================================================
|
|
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, see the
|
|
generated API documentation for details. If an external highlighter plugin is
|
|
adding a large number of 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. Here is an example using wrapper
|
|
functions in the 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). |nvim_buf_clear_highlight| can be used
|
|
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_highlight(0, src, 0, -1)
|
|
>
|
|
==============================================================================
|
|
Global Functions *api-global*
|
|
|
|
nvim_command({command}) *nvim_command()*
|
|
Executes an ex-command. On VimL error: Returns the VimL error;
|
|
v:errmsg is not updated.
|
|
|
|
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
|
|
|
|
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
|
|
|
|
nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()*
|
|
Passes input keys to Nvim. On VimL error: Does not fail, but
|
|
updates v:errmsg.
|
|
|
|
Parameters:~
|
|
{keys} to be typed
|
|
{mode} mapping options
|
|
{escape_csi} If true, escape K_SPECIAL/CSI bytes in
|
|
`keys`
|
|
|
|
nvim_input({keys}) *nvim_input()*
|
|
Passes keys to Nvim as raw user-input. On VimL error: Does not
|
|
fail, but updates v:errmsg.
|
|
|
|
Unlike `nvim_feedkeys`, this uses a lower-level input buffer
|
|
and the call is not deferred. This is the most reliable way to
|
|
send real user input.
|
|
|
|
Note:
|
|
|keycodes| like <CR> are translated, so "<" is special. To
|
|
input a literal "<", send <LT>.
|
|
|
|
Attributes:~
|
|
{async}
|
|
|
|
Parameters:~
|
|
{keys} to be typed
|
|
|
|
Return:~
|
|
Number of bytes actually written (can be fewer than
|
|
requested if the buffer becomes full).
|
|
|
|
*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.
|
|
|
|
nvim_command_output({str}) *nvim_command_output()*
|
|
TODO: Documentation
|
|
|
|
nvim_eval({expr}) *nvim_eval()*
|
|
Evaluates a VimL expression (:help expression). Dictionaries
|
|
and Lists are recursively expanded. On VimL error: Returns a
|
|
generic error; v:errmsg is not updated.
|
|
|
|
Parameters:~
|
|
{expr} VimL expression string
|
|
|
|
Return:~
|
|
Evaluation result or expanded object
|
|
|
|
nvim_call_function({fname}, {args}) *nvim_call_function()*
|
|
Calls a VimL function with the given arguments
|
|
|
|
On VimL error: Returns a generic error; v:errmsg is not
|
|
updated.
|
|
|
|
Parameters:~
|
|
{fname} Function to call
|
|
{args} Function arguments packed in an Array
|
|
|
|
Return:~
|
|
Result of the function call
|
|
|
|
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_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_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
|
|
|
|
nvim_list_bufs() *nvim_list_bufs()*
|
|
Gets the current list of buffer handles
|
|
|
|
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_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_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 dictionaries describing global (non-buffer)
|
|
mappings. The "buffer" key in the returned dictionary is
|
|
always zero.
|
|
|
|
Parameters:~
|
|
{mode} Mode short-name ("n", "i", "v", ...)
|
|
|
|
Return:~
|
|
Array of maparg()-like dictionaries describing mappings
|
|
|
|
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_call_atomic({calls}) *nvim_call_atomic()*
|
|
Call many api methods atomically
|
|
|
|
This has two main usages: Firstly, to perform several requests
|
|
from an async context atomically, i.e. without processing
|
|
requests from other rpc clients or redrawing or allowing user
|
|
interaction in between. Note that api methods that could fire
|
|
autocommands or do event processing still might do so. For
|
|
instance invoking the :sleep command might call timer
|
|
callbacks. Secondly, it can be used to reduce rpc overhead
|
|
(roundtrips) when doing many requests in sequence.
|
|
|
|
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:~
|
|
an array with 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 ocurred, 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. Is 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 holds 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.
|
|
@note: “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.
|
|
|
|
|
|
==============================================================================
|
|
Buffer Functions *api-buffer*
|
|
|
|
nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
|
|
Gets the buffer line count
|
|
|
|
Parameters:~
|
|
{buffer} Buffer handle
|
|
|
|
Return:~
|
|
Line count
|
|
|
|
*nvim_buf_get_lines()*
|
|
nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
|
|
Retrieves a line range from the buffer
|
|
|
|
Indexing is zero-based, end-exclusive. Negative indices are
|
|
interpreted as length+1+index, i e -1 refers to the index past
|
|
the end. So to get the last element set 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
|
|
{start} First line index
|
|
{end} Last line index (exclusive)
|
|
{strict_indexing} Whether out-of-bounds should be an
|
|
error.
|
|
|
|
Return:~
|
|
Array of lines
|
|
|
|
*nvim_buf_set_lines()*
|
|
nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing},
|
|
{replacement})
|
|
Replaces line range on the buffer
|
|
|
|
Indexing is zero-based, end-exclusive. Negative indices are
|
|
interpreted as length+1+index, i e -1 refers to the index past
|
|
the end. So to change or delete the last element set start=-2
|
|
and end=-1.
|
|
|
|
To insert lines at a given index, set both 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
|
|
{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_var({buffer}, {name}) *nvim_buf_get_var()*
|
|
Gets a buffer-scoped (b:) variable.
|
|
|
|
Parameters:~
|
|
{buffer} Buffer handle
|
|
{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.
|
|
|
|
Return:~
|
|
b:changedtickvalue.
|
|
|
|
nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()*
|
|
Gets a list of dictionaries describing buffer-local mappings.
|
|
The "buffer" key in the returned dictionary reflects the
|
|
buffer handle where the mapping is present.
|
|
|
|
Parameters:~
|
|
{mode} Mode short-name ("n", "i", "v", ...)
|
|
{buffer} Buffer handle
|
|
|
|
Return:~
|
|
Array of maparg()-like dictionaries describing mappings
|
|
|
|
nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
|
|
Sets a buffer-scoped (b:) variable
|
|
|
|
Parameters:~
|
|
{buffer} Buffer handle
|
|
{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
|
|
{name} Variable name
|
|
|
|
nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()*
|
|
Gets a buffer option value
|
|
|
|
Parameters:~
|
|
{buffer} Buffer handle
|
|
{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
|
|
{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
|
|
|
|
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
|
|
{name} Buffer name
|
|
|
|
nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()*
|
|
Checks if a buffer is valid
|
|
|
|
Parameters:~
|
|
{buffer} Buffer handle
|
|
|
|
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
|
|
{name} Mark name
|
|
|
|
Return:~
|
|
(row, col) tuple
|
|
|
|
*nvim_buf_add_highlight()*
|
|
nvim_buf_add_highlight({buffer}, {src_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.
|
|
|
|
`src_id` is useful for batch deletion/updating of a set of
|
|
highlights. When called with `src_id = 0`, an unique source id
|
|
is generated and returned. Successive calls can pass that
|
|
`src_id` to associate new highlights with the same source
|
|
group. All highlights in the same group can be cleared with
|
|
`nvim_buf_clear_highlight`. If the highlight never will be
|
|
manually deleted, pass `src_id = -1`.
|
|
|
|
If `hl_group` is the empty string no highlight is added, but a
|
|
new `src_id` is still returned. This is useful for an external
|
|
plugin to synchrounously request an unique `src_id` at
|
|
initialization, and later asynchronously add and clear
|
|
highlights in response to buffer changes.
|
|
|
|
Parameters:~
|
|
{buffer} Buffer handle
|
|
{src_id} Source group to use or 0 to use a new group,
|
|
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 src_id that was used
|
|
|
|
*nvim_buf_clear_highlight()*
|
|
nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
|
|
Clears highlights from a given source group and a range of
|
|
lines
|
|
|
|
To clear a source group in the entire buffer, pass in 1 and -1
|
|
to line_start and line_end respectively.
|
|
|
|
Parameters:~
|
|
{buffer} Buffer handle
|
|
{src_id} Highlight source group to clear, or -1 to
|
|
clear all.
|
|
{line_start} Start of range of lines to clear
|
|
{line_end} End of range of lines to clear (exclusive)
|
|
or -1 to clear to end of file.
|
|
|
|
|
|
==============================================================================
|
|
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_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
|
|
|
|
|
|
==============================================================================
|
|
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
|
|
|
|
vim:tw=78:ts=8:ft=help:norl: |