diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 125 |
1 files changed, 102 insertions, 23 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 21f818cb8d..e16b6b7e75 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -85,7 +85,7 @@ 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: +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}] @@ -97,7 +97,7 @@ nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, 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. + This happens when 'inccommand' shows a buffer preview. Properties:~ {buf} API buffer handle (buffer number) @@ -138,7 +138,7 @@ nvim_buf_changedtick_event[{buf}, {changedtick}] *nvim_buf_changedtick_event* 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: + |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'. @@ -150,7 +150,7 @@ nvim_buf_detach_event[{buf}] *nvim_buf_detach_event* EXAMPLE ~ -Calling |nvim_buf_attach| with send_buffer=true on an empty buffer, emits: > +Calling |nvim_buf_attach()| with send_buffer=true on an empty buffer, emits: > nvim_buf_lines_event[{buf}, {changedtick}, 0, 0, [""], v:false] User adds two lines to the buffer, emits: > @@ -189,12 +189,11 @@ 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: +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() @@ -207,10 +206,10 @@ functions in the python client: 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). +src_id (this is the default in python). Use |nvim_buf_clear_highlight()| 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: > @@ -639,7 +638,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, Clients might define their own keys, but the following are suggested: "website" Website of client (for instance github repository) - "license" Informal descripton of the + "license" Informal description of the license, such as "Apache 2", "GPLv3" or "MIT" "logo" URI or path to image, preferably small logo or icon. .png or .svg @@ -655,14 +654,14 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* 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 recieve 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) + "mode" how data received on the channel is interpreted "bytes" send and recieve 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|. + format specified at |nvim_get_chan_info()|. nvim_call_atomic({calls}) *nvim_call_atomic()* Calls many API methods atomically. @@ -836,10 +835,26 @@ nvim_get_proc({pid}) *nvim_get_proc()* Return: ~ Map of process properties, or NIL if process not found. +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 @@ -847,7 +862,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* {buffer} Buffer handle Return: ~ - Line count + 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. @@ -896,7 +911,7 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) error. Return: ~ - Array of lines + Array of lines, or empty array for unloaded buffer. *nvim_buf_set_lines()* nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, @@ -923,6 +938,25 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, 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 + {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. @@ -1013,14 +1047,28 @@ nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* {buffer} Buffer handle {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 + + 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 + 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 Return: ~ - true if the buffer is valid, false otherwise + 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 @@ -1075,8 +1123,8 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, *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 + Clears highlights and virtual text from a given source id and + range of lines To clear a source group in the entire buffer, pass in 0 and -1 to line_start and line_end respectively. @@ -1089,6 +1137,37 @@ nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end}) {line_end} End of range of lines to clear (exclusive) or -1 to clear to end of file. + *nvim_buf_set_virtual_text()* +nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks}, + {opts}) + 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 after one cell to + the right of the ordinary text, this will contain the |lcs- + eol| char if set, otherwise just be a space. + + The same src_id can be used for both virtual text and + highlights added by nvim_buf_add_highlight. Virtual text is + cleared using nvim_buf_clear_highlight. + + Parameters: ~ + {buffer} Buffer handle + {src_id} Source group to use or 0 to use a new group, 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 src_id that was used + ============================================================================== Window Functions *api-window* |