diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 745 |
1 files changed, 439 insertions, 306 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 95a929b808..ba3b7c0915 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 |RPC|, |Lua| and VimL (|eval-api|). +via |RPC|, |Lua| and Vimscript (|eval-api|). Applications can also embed libnvim to work with the C API directly. @@ -17,8 +17,15 @@ Applications can also embed libnvim to work with the C API directly. API Usage *api-rpc* *RPC* *rpc* *msgpack-rpc* -RPC is the typical way to control Nvim programmatically. Nvim implements the -MessagePack-RPC protocol: +RPC is the main way to control Nvim programmatically. Nvim implements the +MessagePack-RPC protocol with these extra (out-of-spec) constraints: + +1. Responses must be given in reverse order of requests (like "unwinding + a stack"). +2. Nvim processes all messages (requests and notifications) in the order they + are received. + +MessagePack-RPC specification: https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md @@ -202,7 +209,7 @@ any of these approaches: nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)' < 3. Use the |api_info()| Vimscript function. >vim - :lua print(vim.inspect(vim.fn.api_info())) + :lua vim.print(vim.fn.api_info()) < Example using |filter()| to exclude non-deprecated API functions: >vim :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name') @@ -273,7 +280,7 @@ nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, changed but not the buffer contents. {linedata} contains the changed screen lines. This happens when 'inccommand' shows a buffer preview. - Properties:~ + Properties: ~ {buf} API buffer handle (buffer number) {changedtick} value of |b:changedtick| for the buffer. If you send an @@ -306,7 +313,7 @@ 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:~ + Properties: ~ {buf} API buffer handle (buffer number) {changedtick} new value of |b:changedtick| for the buffer @@ -319,7 +326,7 @@ nvim_buf_detach_event[{buf}] *nvim_buf_detach_event* |:checktime| or 'autoread'. - Generally: whenever the buffer contents are unloaded from memory. - Properties:~ + Properties: ~ {buf} API buffer handle (buffer number) @@ -356,6 +363,7 @@ In-process Lua plugins can receive buffer updates in the form of Lua callbacks. These callbacks are called frequently in various contexts; |textlock| prevents changing buffer contents and window layout (use |vim.schedule()| to defer such operations to the main loop instead). +Moving the cursor is allowed, but it is restored afterwards. |nvim_buf_attach()| will take keyword args for the callbacks. "on_lines" will receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline}, @@ -399,6 +407,23 @@ 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) requesting a source id. +|nvim_buf_add_highlight()| adds highlights as |extmarks|. If highlights need to +be tracked or manipulated after adding them, it is better to use +|nvim_buf_set_extmark()| directly, as this function returns the placed |extmark| +id. Thus, instead of >lua + vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end) +< +use >lua + -- create the highlight through an extmark + extid = vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = hl_group}) + + -- example: modify the extmark's highlight group + vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid}) + + -- example: change the highlight's position + vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid}) +< + Example using the Python API client (|pynvim|): >python src = vim.new_highlight_source() @@ -451,6 +476,11 @@ Buffer text can be highlighted by typical mechanisms (syntax highlighting, options from the current window; specify `style=minimal` in |nvim_open_win()| to disable various visual features such as the 'number' column. +Other highlight groups specific to floating windows: +- |hl-FloatBorder| for window's border +- |hl-FloatTitle| for window's title +- |hl-FloatFooter| for window's footer + Currently, floating windows don't support some widgets like scrollbar. The output of |:mksession| does not include commands for restoring floating @@ -464,7 +494,7 @@ Example: create a float with scratch buffer: >vim \ 'row': 1, 'anchor': 'NW', 'style': 'minimal'} let win = nvim_open_win(buf, 0, opts) " optional: change highlight, otherwise Pmenu is used - call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') + call nvim_set_option_value('winhl', 'Normal:MyHighlight', {'win': win}) < ============================================================================== @@ -558,7 +588,7 @@ nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* Parameters: ~ • {pat} pattern of files to search for • {all} whether to return all matches or only the first - • {opts} is_lua: only search lua subdirs + • {opts} is_lua: only search Lua subdirs Return: ~ list of absolute paths to the found files @@ -615,6 +645,10 @@ nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* NB: if your UI doesn't use hlstate, this will not return hlstate first time. +nvim__invalidate_glyph_cache() *nvim__invalidate_glyph_cache()* + For testing. The condition in schar_cache_clear_if_full is hard to reach, + so this function can be used to force a cache clear in a test. + nvim__stats() *nvim__stats()* Gets internal stats. @@ -679,7 +713,7 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* Buffer handle, or 0 on error See also: ~ - buf_open_scratch + • buf_open_scratch nvim_del_current_line() *nvim_del_current_line()* Deletes the current line. @@ -693,13 +727,13 @@ nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. See also: ~ - |nvim_set_keymap()| + • |nvim_set_keymap()| nvim_del_mark({name}) *nvim_del_mark()* Deletes an uppercase/file named mark. See |mark-motions|. - Note: - fails with error if a lowercase or buffer local named mark is used. + Note: ~ + • Lowercase name (or other buffer-local mark) is an error. Parameters: ~ • {name} Mark name @@ -708,8 +742,8 @@ nvim_del_mark({name}) *nvim_del_mark()* true if the mark was deleted, else false. See also: ~ - |nvim_buf_del_mark()| - |nvim_get_mark()| + • |nvim_buf_del_mark()| + • |nvim_get_mark()| nvim_del_var({name}) *nvim_del_var()* Removes a global (g:) variable. @@ -746,7 +780,7 @@ nvim_err_writeln({str}) *nvim_err_writeln()* • {str} Message See also: ~ - nvim_err_write() + • nvim_err_write() nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* Evaluates statusline string. @@ -768,6 +802,8 @@ nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* • use_tabline: (boolean) Evaluate tabline instead of statusline. When true, {winid} is ignored. Mutually exclusive with {use_winbar}. + • use_statuscol_lnum: (number) Evaluate statuscolumn for this + line number instead of statusline. Return: ~ Dictionary containing statusline information, with these keys: @@ -820,8 +856,8 @@ nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()* true otherwise. See also: ~ - feedkeys() - vim_strsave_escape_ks + • feedkeys() + • vim_strsave_escape_ks nvim_get_api_info() *nvim_get_api_info()* Returns a 2-tuple (Array), where item 0 is the current channel id and item @@ -918,37 +954,48 @@ nvim_get_current_win() *nvim_get_current_win()* Return: ~ Window handle -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_get_hl({ns_id}, {*opts}) *nvim_get_hl()* + Gets all or specific highlight groups in a namespace. -nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* - Gets a highlight definition by name. + Note: ~ + • When the `link` attribute is defined in the highlight definition map, + other attributes will not be taking effect (see |:hi-link|). Parameters: ~ - • {name} Highlight group name - • {rgb} Export RGB colors + • {ns_id} Get highlight groups for namespace ns_id + |nvim_get_namespaces()|. Use 0 to get global highlight groups + |:highlight|. + • {opts} Options dict: + • name: (string) Get a highlight definition by name. + • id: (integer) Get a highlight definition by id. + • link: (boolean, default true) Show linked group name + instead of effective definition |:hi-link|. + • create: (boolean, default true) When highlight group + doesn't exist create it. Return: ~ - Highlight definition map - - See also: ~ - nvim_get_hl_by_id + Highlight groups as a map from group name to a highlight definition + map as in |nvim_set_hl()|, or only a single highlight definition map + if requested by name or id. nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* Gets a highlight group by name similar to |hlID()|, but allocates a new ID if not present. +nvim_get_hl_ns({*opts}) *nvim_get_hl_ns()* + Gets the active highlight namespace. + + Parameters: ~ + • {opts} Optional parameters + • winid: (number) |window-ID| for retrieving a window's + highlight namespace. A value of -1 is returned when + |nvim_win_set_hl_ns()| has not been called for the window + (or was called with a namespace of -1). + + Return: ~ + Namespace id, or -1 + nvim_get_keymap({mode}) *nvim_get_keymap()* Gets a list of global (non-buffer-local) |mapping| definitions. @@ -960,13 +1007,14 @@ nvim_get_keymap({mode}) *nvim_get_keymap()* "buffer" key is always zero. nvim_get_mark({name}, {opts}) *nvim_get_mark()* - Return a tuple (row, col, buffer, buffername) representing the position of - the uppercase/file named mark. See |mark-motions|. + Returns a `(row, col, buffer, buffername)` tuple representing the position + of the uppercase/file named mark. "End of line" column position is + returned as |v:maxcol| (big number). See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| - Note: - fails with error if a lowercase or buffer local named mark is used. + Note: ~ + • Lowercase name (or other buffer-local mark) is an error. Parameters: ~ • {name} Mark name @@ -977,8 +1025,8 @@ nvim_get_mark({name}, {opts}) *nvim_get_mark()* not set. See also: ~ - |nvim_buf_set_mark()| - |nvim_del_mark()| + • |nvim_buf_set_mark()| + • |nvim_del_mark()| nvim_get_mode() *nvim_get_mode()* Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for @@ -1047,12 +1095,10 @@ nvim_input({keys}) *nvim_input()* On execution error: does not fail, but updates v:errmsg. - Note: - |keycodes| like <CR> are translated, so "<" is special. To input a + 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 + • For mouse events use |nvim_input_mouse()|. The pseudokey form "<LeftMouse><col,row>" is deprecated since |api-level| 6. Attributes: ~ @@ -1072,8 +1118,8 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) 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 + 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 @@ -1113,7 +1159,7 @@ nvim_list_chans() *nvim_list_chans()* specified at |nvim_get_chan_info()|. nvim_list_runtime_paths() *nvim_list_runtime_paths()* - Gets the paths contained in 'runtimepath'. + Gets the paths contained in |runtime-search-path|. Return: ~ List of paths @@ -1173,10 +1219,13 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* |nvim_chan_send()| can be called immediately to process sequences in a virtual terminal having the intended size. + Attributes: ~ + not allowed when |textlock| is active + Parameters: ~ • {buffer} the buffer to use (expected to be empty) • {opts} Optional parameters. - • on_input: lua callback for input sent, i e keypresses in + • on_input: Lua callback for input sent, i e keypresses in terminal mode. Note: keypresses are sent raw as they would be to the pty master end. For instance, a carriage return is sent as a "\r", not as a "\n". |textlock| applies. It @@ -1252,8 +1301,8 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) • {special} Replace |keycodes|, e.g. <CR> becomes a "\r" char. See also: ~ - replace_termcodes - cpoptions + • replace_termcodes + • cpoptions *nvim_select_popupmenu_item()* nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) @@ -1286,8 +1335,8 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) appropriate. Example: library first identifies the channel, then a plugin using that library later identifies itself. - Note: - "Something is better than nothing". You don't need to include all the + Note: ~ + • "Something is better than nothing". You don't need to include all the fields. Attributes: ~ @@ -1307,7 +1356,11 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) • {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. + • "remote" remote client connected "Nvim flavored" + MessagePack-RPC (responses must be in reverse order of + requests). |msgpack-rpc| + • "msgpack-rpc" remote client connected to Nvim via + fully MessagePack-RPC compliant protocol. • "ui" gui frontend • "embedder" application using Nvim as a component (for example, IDE/editor implementing a vim mode). @@ -1338,7 +1391,7 @@ nvim_set_current_buf({buffer}) *nvim_set_current_buf()* Sets the current buffer. Attributes: ~ - not allowed when |textlock| is active + not allowed when |textlock| is active or in the |cmdwin| Parameters: ~ • {buffer} Buffer handle @@ -1362,7 +1415,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* Sets the current tabpage. Attributes: ~ - not allowed when |textlock| is active + not allowed when |textlock| is active or in the |cmdwin| Parameters: ~ • {tabpage} Tabpage handle @@ -1371,7 +1424,7 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Sets the current window. Attributes: ~ - not allowed when |textlock| is active + not allowed when |textlock| is active or in the |cmdwin| Parameters: ~ • {window} Window handle @@ -1379,21 +1432,24 @@ nvim_set_current_win({window}) *nvim_set_current_win()* nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* Sets a highlight group. - Note: - Unlike the `:highlight` command which can update a highlight group, - this function completely replaces the definition. For example: + Note: ~ + • Unlike the `:highlight` command which can update a highlight group, this + function completely replaces the definition. For example: `nvim_set_hl(0, 'Visual', {})` will clear the highlight group 'Visual'. - - Note: - The fg and bg keys also accept the string values `"fg"` or `"bg"` - which act as aliases to the corresponding foreground and background - values of the Normal group. If the Normal group has not been defined, - using these values results in an error. + • The fg and bg keys also accept the string values `"fg"` or `"bg"` which + act as aliases to the corresponding foreground and background values + of the Normal group. If the Normal group has not been defined, using + these values results in an error. + • If `link` is used in combination with other attributes; only the `link` + will take effect (see |:hi-link|). Parameters: ~ • {ns_id} Namespace id for this highlight |nvim_create_namespace()|. Use 0 to set a highlight group globally |:highlight|. + Highlights from non-global namespaces are not active by + default, use |nvim_set_hl_ns()| or |nvim_win_set_hl_ns()| to + activate them. • {name} Highlight group name, e.g. "ErrorMsg" • {val} Highlight definition map, accepts the following keys: • fg (or foreground): color name or "#RRGGBB", see note. @@ -1419,16 +1475,19 @@ nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* • cterm: cterm attribute map, like |highlight-args|. If not set, cterm attributes will match those from the attribute map documented above. + • force: if true force update the highlight group when it + exists. nvim_set_hl_ns({ns_id}) *nvim_set_hl_ns()* - Set active namespace for highlights. This can be set for a single window, - see |nvim_win_set_hl_ns()|. + Set active namespace for highlights defined with |nvim_set_hl()|. This can + be set for a single window, see |nvim_win_set_hl_ns()|. Parameters: ~ • {ns_id} the namespace to use nvim_set_hl_ns_fast({ns_id}) *nvim_set_hl_ns_fast()* - Set active namespace for highlights while redrawing. + Set active namespace for highlights defined with |nvim_set_hl()| while + redrawing. This function meant to be called while redrawing, primarily from |nvim_set_decoration_provider()| on_win and on_line callbacks, which are @@ -1458,19 +1517,20 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* Parameters: ~ • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or - "!" for |:map!|, or empty string for |:map|. + "!" for |:map!|, or empty string for |:map|. "ia", "ca" or + "!a" for abbreviation in Insert mode, Cmdline mode, or both, + respectively • {lhs} Left-hand-side |{lhs}| of the mapping. • {rhs} Right-hand-side |{rhs}| of the mapping. - • {opts} Optional parameters map: keys are |:map-arguments|, values are - booleans (default false). Accepts all |:map-arguments| as keys - excluding |<buffer>| but including |:noremap| and "desc". - Unknown key is an error. "desc" can be used to give a - description to the mapping. When called from Lua, also accepts - a "callback" key that takes a Lua function to call when the - mapping is executed. When "expr" is true, "replace_keycodes" - (boolean) can be used to replace keycodes in the resulting - string (see |nvim_replace_termcodes()|), and a Lua callback - returning `nil` is equivalent to returning an empty string. + • {opts} Optional parameters map: Accepts all |:map-arguments| as keys + except |<buffer>|, values are booleans (default false). Also: + • "noremap" disables |recursive_mapping|, like |:noremap| + • "desc" human-readable description. + • "callback" Lua function called in place of {rhs}. + • "replace_keycodes" (boolean) When "expr" is true, replace + keycodes in the resulting string (see + |nvim_replace_termcodes()|). Returning nil from the Lua + "callback" is equivalent to returning an empty string. nvim_set_var({name}, {value}) *nvim_set_var()* Sets a global (g:) variable. @@ -1520,22 +1580,22 @@ Vimscript Functions *api-vimscript* *nvim_call_dict_function()* nvim_call_dict_function({dict}, {fn}, {args}) - Calls a VimL |Dictionary-function| with the given arguments. + Calls a Vimscript |Dictionary-function| with the given arguments. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ - • {dict} Dictionary, or String evaluating to a VimL |self| dict - • {fn} Name of the function defined on the VimL dict + • {dict} Dictionary, or String evaluating to a Vimscript |self| dict + • {fn} Name of the function defined on the Vimscript dict • {args} Function arguments packed in an Array Return: ~ Result of the function call nvim_call_function({fn}, {args}) *nvim_call_function()* - Calls a VimL function with the given arguments. + Calls a Vimscript function with the given arguments. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ • {fn} Function to call @@ -1547,54 +1607,56 @@ nvim_call_function({fn}, {args}) *nvim_call_function()* nvim_command({command}) *nvim_command()* Executes an Ex command. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. - Prefer using |nvim_cmd()| or |nvim_exec()| over this. To evaluate multiple - lines of Vim script or an Ex command directly, use |nvim_exec()|. To - construct an Ex command using a structured format and then execute it, use - |nvim_cmd()|. To modify an Ex command before evaluating it, use - |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. + Prefer using |nvim_cmd()| or |nvim_exec2()| over this. To evaluate + multiple lines of Vim script or an Ex command directly, use + |nvim_exec2()|. To construct an Ex command using a structured format and + then execute it, use |nvim_cmd()|. To modify an Ex command before + evaluating it, use |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. Parameters: ~ • {command} Ex command string nvim_eval({expr}) *nvim_eval()* - Evaluates a VimL |expression|. Dictionaries and Lists are recursively + Evaluates a Vimscript |expression|. Dictionaries and Lists are recursively expanded. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ - • {expr} VimL expression string + • {expr} Vimscript expression string Return: ~ Evaluation result or expanded object -nvim_exec({src}, {output}) *nvim_exec()* +nvim_exec2({src}, {*opts}) *nvim_exec2()* Executes Vimscript (multiline block of Ex commands), like anonymous |:source|. Unlike |nvim_command()| this function supports heredocs, script-scope (s:), etc. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ - • {src} Vimscript code - • {output} Capture and return all (non-error, non-shell |:!|) output + • {src} Vimscript code + • {opts} Optional parameters. + • output: (boolean, default false) Whether to capture and + return all (non-error, non-shell |:!|) output. Return: ~ - Output (non-error, non-shell |:!|) if `output` is true, else empty - string. + Dictionary containing information about execution, with these keys: + • output: (string|nil) Output if `opts.output` is true. See also: ~ - |execute()| - |nvim_command()| - |nvim_cmd()| + • |execute()| + • |nvim_command()| + • |nvim_cmd()| *nvim_parse_expression()* nvim_parse_expression({expr}, {flags}, {highlight}) - Parse a VimL expression. + Parse a Vimscript expression. Attributes: ~ |api-fast| @@ -1638,8 +1700,8 @@ nvim_parse_expression({expr}, {flags}, {highlight}) 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. + using this API 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). @@ -1678,13 +1740,13 @@ Command Functions *api-command* *nvim_buf_create_user_command()* nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts}) - Create a new user command |user-commands| in the given buffer. + Creates a buffer-local command |user-commands|. Parameters: ~ • {buffer} Buffer handle, or 0 for current buffer. See also: ~ - nvim_create_user_command + • nvim_create_user_command *nvim_buf_del_user_command()* nvim_buf_del_user_command({buffer}, {name}) @@ -1722,7 +1784,7 @@ nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* example, instead of `vim.cmd.bdelete{ count = 2 }`, you may do `vim.cmd.bdelete(2)`. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ • {cmd} Command to execute. Must be a Dictionary that can contain the @@ -1738,22 +1800,19 @@ nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* empty string. See also: ~ - |nvim_exec()| - |nvim_command()| + • |nvim_exec2()| + • |nvim_command()| *nvim_create_user_command()* nvim_create_user_command({name}, {command}, {*opts}) - Create a new user command |user-commands| + Creates a global |user-commands| command. - {name} is the name of the new command. The name must begin with an - uppercase letter. - - {command} is the replacement text or Lua function to execute. + For Lua usage see |lua-guide-commands-create|. Example: >vim - :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {}) - :SayHello - Hello world! + :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true}) + :SayHello + Hello world! < Parameters: ~ @@ -1769,6 +1828,7 @@ nvim_create_user_command({name}, {command}, {*opts}) • fargs: (table) The args split by unescaped whitespace (when more than one argument is allowed), if any |<f-args>| + • nargs: (string) Number of arguments |:command-nargs| • bang: (boolean) "true" if the command was executed with a ! modifier |<bang>| • line1: (number) The starting line of the command range @@ -1783,19 +1843,20 @@ nvim_create_user_command({name}, {command}, {*opts}) • smods: (table) Command modifiers in a structured format. Has the same structure as the "mods" key of |nvim_parse_cmd()|. - • {opts} Optional command attributes. See |command-attributes| for - more details. To use boolean attributes (such as - |:command-bang| or |:command-bar|) set the value to "true". - In addition to the string options listed in - |:command-complete|, the "complete" key also accepts a Lua - function which works like the "customlist" completion mode - |:command-completion-customlist|. Additional parameters: - • desc: (string) Used for listing the command when a Lua - function is used for {command}. - • force: (boolean, default true) Override any previous - definition. - • preview: (function) Preview callback for 'inccommand' - |:command-preview| + • {opts} Optional |command-attributes|. + • Set boolean attributes such as |:command-bang| or + |:command-bar| to true (but not |:command-buffer|, use + |nvim_buf_create_user_command()| instead). + • "complete" |:command-complete| also accepts a Lua + function which works like + |:command-completion-customlist|. + • Other parameters: + • desc: (string) Used for listing the command when a Lua + function is used for {command}. + • force: (boolean, default true) Override any previous + definition. + • preview: (function) Preview callback for 'inccommand' + |:command-preview| nvim_del_user_command({name}) *nvim_del_user_command()* Delete a user-defined command. @@ -1814,6 +1875,9 @@ nvim_get_commands({*opts}) *nvim_get_commands()* Return: ~ Map of maps describing commands. + See also: ~ + • |nvim_get_all_options_info()| + nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* Parse command line. @@ -1889,45 +1953,20 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* ============================================================================== Options Functions *api-options* -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_get_all_options_info() *nvim_get_all_options_info()* Gets the option information for all options. The dictionary has the full option names as keys and option metadata - dictionaries as detailed at |nvim_get_option_info()|. + dictionaries as detailed at |nvim_get_option_info2()|. Return: ~ dictionary of all options -nvim_get_option({name}) *nvim_get_option()* - Gets the global value of an option. - - Parameters: ~ - • {name} Option name - - Return: ~ - Option value (global) + See also: ~ + • |nvim_get_commands()| -nvim_get_option_info({name}) *nvim_get_option_info()* - Gets the option information for one option +nvim_get_option_info2({name}, {*opts}) *nvim_get_option_info2()* + Gets the option information for one option from arbitrary buffer or window Resulting dictionary has keys: • name: Name of the option (like 'filetype') @@ -1943,8 +1982,19 @@ nvim_get_option_info({name}) *nvim_get_option_info()* • commalist: List of comma separated values • flaglist: List of single char flags + When {scope} is not provided, the last set information applies to the + local value in the current buffer or window if it is available, otherwise + the global value information is returned. This behavior can be disabled by + explicitly specifying {scope} in the {opts} table. + Parameters: ~ • {name} Option name + • {opts} Optional parameters + • scope: One of "global" or "local". Analogous to |:setglobal| + and |:setlocal|, respectively. + • win: |window-ID|. Used for getting window local options. + • buf: Buffer number. Used for getting buffer local options. + Implies {scope} is "local". Return: ~ Option Information @@ -1963,17 +2013,14 @@ nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* • win: |window-ID|. Used for getting window local options. • buf: Buffer number. Used for getting buffer local options. Implies {scope} is "local". + • filetype: |filetype|. Used to get the default option for a + specific filetype. Cannot be used with any other option. + Note: this will trigger |ftplugin| and all |FileType| + autocommands for the corresponding filetype. Return: ~ Option value -nvim_set_option({name}, {value}) *nvim_set_option()* - Sets the global value of an option. - - Parameters: ~ - • {name} Option name - • {value} New option value - *nvim_set_option_value()* nvim_set_option_value({name}, {value}, {*opts}) Sets the value of an option. The behavior of this function matches that of @@ -1991,25 +2038,6 @@ nvim_set_option_value({name}, {value}, {*opts}) • win: |window-ID|. Used for setting window local option. • buf: Buffer number. Used for setting buffer local option. -nvim_win_get_option({window}, {name}) *nvim_win_get_option()* - Gets a window option value - - Parameters: ~ - • {window} Window handle, or 0 for current window - • {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, or 0 for current window - • {name} Option name - • {value} Option value - ============================================================================== Buffer Functions *api-buffer* @@ -2017,7 +2045,7 @@ Buffer Functions *api-buffer* For more information on buffers, see |buffers|. -Unloaded Buffers:~ +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 @@ -2032,10 +2060,14 @@ whether a buffer is loaded. nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua callbacks. - Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua - events = {} - vim.api.nvim_buf_attach(0, false, { - on_lines=function(...) table.insert(events, {...}) end}) + Example (Lua): capture buffer updates in a global `events` variable (use + "vim.print(events)" to see its contents): >lua + events = {} + vim.api.nvim_buf_attach(0, false, { + on_lines = function(...) + table.insert(events, {...}) + end, + }) < Parameters: ~ @@ -2057,7 +2089,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • deleted_codepoints (if `utf_sizes` is true) |