From 82c67768fa6b56689f22b7ba5f1e4bcf620aaa7d Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 21 Mar 2017 17:08:19 +0100 Subject: doc: Replace "For Vim ... Last change ..." headers (#6328) --- runtime/doc/api.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 122ab37e72..2bcc996d8b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1,4 +1,4 @@ -*api.txt* {Nvim} +*api.txt* Nvim NVIM REFERENCE MANUAL by Thiago de Arruda -- cgit From 6bc6d94ec8c8f7e291454ebc888c0fa8435908c8 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 17 Apr 2017 23:52:38 +0200 Subject: doc: api-contract, CONTRIBUTING.md --- runtime/doc/api.txt | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 2bcc996d8b..a118690876 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -9,8 +9,7 @@ Nvim API *API* *api* Nvim exposes a powerful API that can be used by plugins and external processes via |msgpack-rpc|, Lua and VimL (|eval-api|). -Nvim can also be embedded in C applications as libnvim, so the application -can control the embedded instance by calling the C API directly. +Applications can also embed libnvim to work with the C API directly. ============================================================================== API Types *api-types* @@ -54,6 +53,28 @@ 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" in order to receive rich events, +described at |rpc-remote-ui|. + +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* -- cgit From 45ef3d9d0c5f09e735b984fb6bbb25b27848408c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 1 May 2017 17:09:29 +0200 Subject: doc: Replace hardcoded TOCs with advice. --- runtime/doc/api.txt | 2 ++ 1 file changed, 2 insertions(+) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index a118690876..9b2795863b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -11,6 +11,8 @@ via |msgpack-rpc|, Lua and VimL (|eval-api|). Applications can also embed libnvim to work with the C API directly. + Type to see the table of contents. + ============================================================================== API Types *api-types* -- cgit From 62ab040fa4fc8746b926f1cc89883bad049007ed Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 1 May 2017 18:52:56 +0200 Subject: doc: api --- runtime/doc/api.txt | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 9b2795863b..8db35c4590 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -270,7 +270,7 @@ nvim_get_option({name}) *nvim_get_option()* {name} Option name Return:~ - Option value + Option value (global) nvim_set_option({name}, {value}) *nvim_set_option()* Sets an option value @@ -370,6 +370,17 @@ nvim_get_color_by_name({name}) *nvim_get_color_by_name()* nvim_get_color_map() *nvim_get_color_map()* TODO: Documentation +nvim_get_mode() *nvim_get_mode()* + Gets the current mode. + mode: Mode string. |mode()| + blocking: true if Nvim is waiting for input. + + Attributes:~ + {async} + + Return:~ + Dictionary { "mode": String, "blocking": Boolean } + nvim_get_api_info() *nvim_get_api_info()* TODO: Documentation @@ -514,15 +525,6 @@ nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* {name} Option name {value} Option value -nvim_buf_get_number({buffer}) *nvim_buf_get_number()* - Gets the buffer number - - Parameters:~ - {buffer} Buffer handle - - Return:~ - Buffer number - nvim_buf_get_name({buffer}) *nvim_buf_get_name()* Gets the full file name for the buffer -- cgit From e82cb5de4adc8a88e8213d0aca85400362df4bd1 Mon Sep 17 00:00:00 2001 From: Björn Linse Date: Sun, 30 Apr 2017 14:35:36 +0200 Subject: api: add metadata for ui events --- runtime/doc/api.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 8db35c4590..ebc2a40561 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -48,6 +48,7 @@ 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 |rpc-remote-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 -- cgit From 0b88bf256d629cfe53c94896e140511e7f312b25 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 2 Jul 2017 13:46:41 +0200 Subject: doc: api.txt; deprecate --- runtime/doc/api.txt | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 102 insertions(+), 3 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index ebc2a40561..7c6b8a3c1a 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -165,7 +165,16 @@ nvim_input({keys}) *nvim_input()* *nvim_replace_termcodes()* nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) - Replaces any terminal codes with the internal representation + Replaces terminal codes and |keycodes| (, , ...) in a + string with the internal representation. + + Parameters:~ + {str} String to be converted. + {from_part} Legacy Vim parameter. Usually true. + {do_lt} Also translate . Does nothing if + `special` is false. + {special} Replace |keycodes|, e.g. becomes a "\n" + char. nvim_command_output({str}) *nvim_command_output()* TODO: Documentation @@ -182,8 +191,10 @@ nvim_eval({expr}) *nvim_eval()* 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. + 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 @@ -192,6 +203,23 @@ nvim_call_function({fname}, {args}) *nvim_call_function()* Return:~ Result of the function call +nvim_execute_lua({code}, {args}) *nvim_execute_lua()* + Execute lua code. Parameters might be passed, they are + available inside the chunk as `...`. The chunk can return a + value. + + To evaluate an expression, it must be prefixed with "return ". + For instance, to call a lua function with arguments sent in + and get its return value back, use the code "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({str}) *nvim_strwidth()* Calculates the number of display cells occupied by `text`. counts as one cell. @@ -382,6 +410,17 @@ nvim_get_mode() *nvim_get_mode()* Return:~ Dictionary { "mode": String, "blocking": Boolean } +nvim_get_keymap({mode}) *nvim_get_keymap()* + Get a list of dictionaries describing global (i.e. non-buffer) + mappings Note that the "buffer" key will be 0 to represent + false. + + Parameters:~ + {mode} The abbreviation for the mode + + Return:~ + An array of maparg() like dictionaries describing mappings + nvim_get_api_info() *nvim_get_api_info()* TODO: Documentation @@ -414,6 +453,54 @@ nvim_call_atomic({calls}) *nvim_call_atomic()* error ocurred, the values from all preceding calls will still be returned. +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* @@ -492,6 +579,18 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* Return:~ b:changedtickvalue. +nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* + Get a list of dictionaries describing buffer-local mappings + Note that the buffer key in the dictionary will represent the + buffer handle where the mapping is present + + Parameters:~ + {mode} The abbreviation for the mode + {buffer_id} Buffer handle + + Return:~ + An array of maparg() like dictionaries describing mappings + nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* Sets a buffer-scoped (b:) variable -- cgit From b13070ec01844977f10cae38fc6f2a0fd9defad8 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 17 Aug 2017 23:30:28 +0200 Subject: doc/api: nvim_out_write() and friends References #7178 --- runtime/doc/api.txt | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 7c6b8a3c1a..e12cd1cfa9 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -171,8 +171,8 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) Parameters:~ {str} String to be converted. {from_part} Legacy Vim parameter. Usually true. - {do_lt} Also translate . Does nothing if - `special` is false. + {do_lt} Also translate . Ignored if `special` is + false. {special} Replace |keycodes|, e.g. becomes a "\n" char. @@ -309,20 +309,24 @@ nvim_set_option({name}, {value}) *nvim_set_option()* {value} New option value nvim_out_write({str}) *nvim_out_write()* - Writes a message to vim output buffer + 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 vim error buffer + 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 vim error buffer. Appends a linefeed to - ensure all contents are written. + Writes a message to the Vim error buffer. Appends "\n", so the + buffer is flushed (and displayed). Parameters:~ {str} Message -- cgit From 70683705603e8e0e225574f01bc8b6824d5320eb Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 21 Oct 2017 02:33:58 +0200 Subject: help, man.vim: change "outline" map to gO (#7405) --- runtime/doc/api.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index e12cd1cfa9..8aead087db 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -11,7 +11,7 @@ via |msgpack-rpc|, Lua and VimL (|eval-api|). Applications can also embed libnvim to work with the C API directly. - Type to see the table of contents. + Type |gO| to see the table of contents. ============================================================================== API Types *api-types* -- cgit From f640ae0d6e788bb3ca06508d216a397c1ff190d5 Mon Sep 17 00:00:00 2001 From: Björn Linse Date: Sun, 10 Sep 2017 10:01:18 +0200 Subject: docs: breakout ui.txt from msgpack_rpc.txt --- runtime/doc/api.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 8aead087db..159dd93c5e 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -48,7 +48,7 @@ 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 |rpc-remote-ui| +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 -- cgit From 842a54a1bbdd3724ba9283269b3f9899b3844e35 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 19 Aug 2017 14:13:14 +0200 Subject: doc --- runtime/doc/api.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 159dd93c5e..876adf0d72 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -7,7 +7,7 @@ Nvim API *API* *api* Nvim exposes a powerful API that can be used by plugins and external processes -via |msgpack-rpc|, Lua and VimL (|eval-api|). +via |RPC|, |Lua| and VimL (|eval-api|). Applications can also embed libnvim to work with the C API directly. -- cgit From 280943d9b938e95fcf77ef5290576630b84511fb Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 6 Nov 2017 02:00:39 +0100 Subject: doc: API (generated) --- runtime/doc/api.txt | 118 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 69 insertions(+), 49 deletions(-) (limited to 'runtime/doc/api.txt') diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 876adf0d72..ef8b9c7d47 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -135,6 +135,26 @@ nvim_command({command}) *nvim_command()* 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. @@ -151,7 +171,11 @@ nvim_input({keys}) *nvim_input()* Unlike `nvim_feedkeys`, this uses a lower-level input buffer and the call is not deferred. This is the most reliable way to - emulate real user input. + send real user input. + + Note: + |keycodes| like are translated, so "<" is special. To + input a literal "<", send . Attributes:~ {async} @@ -204,14 +228,11 @@ nvim_call_function({fname}, {args}) *nvim_call_function()* Result of the function call nvim_execute_lua({code}, {args}) *nvim_execute_lua()* - Execute lua code. Parameters might be passed, they are - available inside the chunk as `...`. The chunk can return a - value. + Execute lua code. Parameters (if any) are available as `...` + inside the chunk. The chunk can return a value. - To evaluate an expression, it must be prefixed with "return ". - For instance, to call a lua function with arguments sent in - and get its return value back, use the code "return - my_function(...)". + Only statements are executed. To evaluate an expression, + prefix it with `return`: return my_function(...) Parameters:~ {code} lua code to execute @@ -220,7 +241,7 @@ nvim_execute_lua({code}, {args}) *nvim_execute_lua()* Return:~ Return value of lua code if present or NIL. -nvim_strwidth({str}) *nvim_strwidth()* +nvim_strwidth({text}) *nvim_strwidth()* Calculates the number of display cells occupied by `text`. counts as one cell. @@ -347,7 +368,7 @@ nvim_set_current_buf({buffer}) *nvim_set_current_buf()* Sets the current buffer Parameters:~ - {id} Buffer handle + {buffer} Buffer handle nvim_list_wins() *nvim_list_wins()* Gets the current list of window handles @@ -365,7 +386,7 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Sets the current window Parameters:~ - {handle} Window handle + {window} Window handle nvim_list_tabpages() *nvim_list_tabpages()* Gets the current list of tabpage handles @@ -383,7 +404,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* Sets the current tabpage Parameters:~ - {handle} Tabpage handle + {tabpage} Tabpage handle nvim_subscribe({event}) *nvim_subscribe()* Subscribes to event broadcasts @@ -404,26 +425,25 @@ nvim_get_color_map() *nvim_get_color_map()* TODO: Documentation nvim_get_mode() *nvim_get_mode()* - Gets the current mode. - mode: Mode string. |mode()| - blocking: true if Nvim is waiting for input. - - Attributes:~ - {async} + 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()* - Get a list of dictionaries describing global (i.e. non-buffer) - mappings Note that the "buffer" key will be 0 to represent - false. + Gets a list of dictionaries describing global (non-buffer) + mappings. The "buffer" key in the returned dictionary is + always zero. Parameters:~ - {mode} The abbreviation for the mode + {mode} Mode short-name ("n", "i", "v", ...) Return:~ - An array of maparg() like dictionaries describing mappings + Array of maparg()-like dictionaries describing mappings nvim_get_api_info() *nvim_get_api_info()* TODO: Documentation @@ -584,16 +604,16 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* b:changedtickvalue. nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* - Get a list of dictionaries describing buffer-local mappings - Note that the buffer key in the dictionary will represent the - buffer handle where the mapping is present + 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} The abbreviation for the mode - {buffer_id} Buffer handle + {mode} Mode short-name ("n", "i", "v", ...) + {buffer} Buffer handle Return:~ - An array of maparg() like dictionaries describing mappings + Array of maparg()-like dictionaries describing mappings nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* Sets a buffer-scoped (b:) variable @@ -670,24 +690,24 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, {col_start}, {col_end}) Adds a highlight to buffer. - This can be used for plugins which 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. Succesive calls can pass in it as - "src_id" to add new highlights to the same source group. All - highlights in the same group can then be cleared with - nvim_buf_clear_highlight. If the highlight never will be - manually deleted pass in -1 for "src_id". - - 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 + 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. @@ -696,7 +716,7 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line}, {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 + {line} Line to highlight (zero-indexed) {col_start} Start of range of columns to highlight {col_end} End of range of columns to highlight, or -1 to highlight to end of line @@ -948,4 +968,4 @@ nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* TODO: Documentation - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:ft=help:norl: \ No newline at end of file -- cgit