diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 774 |
1 files changed, 403 insertions, 371 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index a388592981..f92ef26399 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -83,6 +83,7 @@ and |rpcnotify()|: let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true}) echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"') call jobstop(nvim) +< ============================================================================== API Definitions *api-definitions* @@ -92,7 +93,7 @@ The Nvim C API defines custom types for all function parameters. Some are just typedefs around C99 standard types, others are Nvim-defined data structures. Basic types ~ - +> API Type C type ------------------------------------------------------------------------ Nil @@ -103,7 +104,7 @@ Basic types ~ Array Dictionary (msgpack: map) Object - +< Note: empty Array is accepted as a valid argument for Dictionary parameter. Special types (msgpack EXT) ~ @@ -115,13 +116,13 @@ Special types (msgpack EXT) ~ The EXT object data is the (integer) object handle. The EXT type codes given in the |api-metadata| `types` key are stable: they will not change and are thus forward-compatible. - +> EXT Type C type Data ------------------------------------------------------------------------ Buffer enum value kObjectTypeBuffer |bufnr()| Window enum value kObjectTypeWindow |window-ID| Tabpage enum value kObjectTypeTabpage internal handle - +< *api-indexing* Most of the API uses 0-based indices, and ranges are end-exclusive. For the @@ -130,19 +131,19 @@ end of a range, -1 denotes the last line/column. Exception: the following API functions use "mark-like" indexing (1-based lines, 0-based columns): - |nvim_get_mark()| - |nvim_buf_get_mark()| - |nvim_buf_set_mark()| - |nvim_win_get_cursor()| - |nvim_win_set_cursor()| +- |nvim_get_mark()| +- |nvim_buf_get_mark()| +- |nvim_buf_set_mark()| +- |nvim_win_get_cursor()| +- |nvim_win_set_cursor()| Exception: the following API functions use |extmarks| indexing (0-based indices, end-inclusive): - |nvim_buf_del_extmark()| - |nvim_buf_get_extmark_by_id()| - |nvim_buf_get_extmarks()| - |nvim_buf_set_extmark()| +- |nvim_buf_del_extmark()| +- |nvim_buf_get_extmark_by_id()| +- |nvim_buf_get_extmarks()| +- |nvim_buf_set_extmark()| *api-fast* Most API functions are "deferred": they are queued on the main loop and @@ -162,19 +163,19 @@ and return values. Nvim exposes its API metadata as a Dictionary with these items: -version Nvim version, API level/compatibility -version.api_level API version integer *api-level* -version.api_compatible API is backwards-compatible with this level -version.api_prerelease Declares the API as unstable/unreleased > - (version.api_prerelease && fn.since == version.api_level) -functions API function signatures, containing |api-types| info - describing the return value and parameters. -ui_events |UI| event signatures -ui_options Supported |ui-option|s -{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 +- version Nvim version, API level/compatibility +- version.api_level API version integer *api-level* +- version.api_compatible API is backwards-compatible with this level +- version.api_prerelease Declares the API as unstable/unreleased + `(version.api_prerelease && fn.since == version.api_level)` +- functions API function signatures, containing |api-types| info + describing the return value and parameters. +- ui_events |UI| event signatures +- ui_options Supported |ui-option|s +- {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 About the `functions` map: @@ -230,6 +231,15 @@ As Nvim evolves the API may change in compliance with this CONTRACT: - Existing items will not be removed (after release). - Deprecated functions will not be removed until Nvim version 2.0 +"Private" interfaces are NOT covered by this contract: + +- Undocumented (not in :help) functions or events of any kind +- nvim__x ("double underscore") functions + +The idea is "versionless evolution", in the words of Rich Hickey: +- Relaxing a requirement should be a compatible change. +- Strengthening a promise should be a compatible change. + ============================================================================== Global events *api-global-events* @@ -345,7 +355,7 @@ LUA ~ 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). +|vim.schedule()| to defer such operations to the main loop instead). |nvim_buf_attach()| will take keyword args for the callbacks. "on_lines" will receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline}, @@ -433,7 +443,7 @@ its config is non-empty: > if vim.api.nvim_win_get_config(window_id).relative ~= '' then -- window with this window_id is floating end -> +< Buffer text can be highlighted by typical mechanisms (syntax highlighting, |api-highlights|). The |hl-NormalFloat| group highlights normal text; @@ -455,7 +465,7 @@ Example: create a float with scratch buffer: > let win = nvim_open_win(buf, 0, opts) " optional: change highlight, otherwise Pmenu is used call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') -> +< ============================================================================== Extended marks *api-extended-marks* *extmarks* @@ -499,8 +509,8 @@ Let's set an extmark at the first row (row=0) and third column (column=2). 01 2345678 0 ex|ample.. -< ^ extmark position -> + ^ extmark position + let g:mark_ns = nvim_create_namespace('myplugin') let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {}) < @@ -519,8 +529,8 @@ use |nvim_buf_del_extmark()|. Deleting "x" in our example: > 0 12345678 0 e|ample.. -< ^ extmark position -> + ^ extmark position + echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {}) => [0, 1] < @@ -544,9 +554,9 @@ nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* |api-fast| 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 + • {pat} pattern of files to search for + • {all} whether to return all matches or only the first + • {opts} is_lua: only search lua subdirs Return: ~ list of absolute paths to the found files @@ -558,7 +568,7 @@ nvim__id({obj}) *nvim__id()* in plugins. Parameters: ~ - {obj} Object to return. + • {obj} Object to return. Return: ~ its argument. @@ -570,7 +580,7 @@ nvim__id_array({arr}) *nvim__id_array()* in plugins. Parameters: ~ - {arr} Array to return. + • {arr} Array to return. Return: ~ its argument. @@ -582,7 +592,7 @@ nvim__id_dictionary({dct}) *nvim__id_dictionary()* in plugins. Parameters: ~ - {dct} Dictionary to return. + • {dct} Dictionary to return. Return: ~ its argument. @@ -594,7 +604,7 @@ nvim__id_float({flt}) *nvim__id_float()* in plugins. Parameters: ~ - {flt} Value to return. + • {flt} Value to return. Return: ~ its argument. @@ -624,7 +634,7 @@ nvim_call_atomic({calls}) *nvim_call_atomic()* |RPC| only Parameters: ~ - {calls} an array of calls, where each call is described by an array + • {calls} an array of calls, where each call is described by an array with two elements: the request name, and an array of arguments. @@ -648,18 +658,18 @@ nvim_chan_send({chan}, {data}) *nvim_chan_send()* Attributes: ~ |RPC| only - |vim.api| only + Lua |vim.api| only Parameters: ~ - {chan} id of the channel - {data} data to write. 8-bit clean: can contain NUL bytes. + • {chan} id of the channel + • {data} data to write. 8-bit clean: can contain NUL bytes. nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* Creates a new, empty, unnamed buffer. Parameters: ~ - {listed} Sets 'buflisted' - {scratch} Creates a "throwaway" |scratch-buffer| for temporary work + • {listed} Sets 'buflisted' + • {scratch} Creates a "throwaway" |scratch-buffer| for temporary work (always 'nomodified'). Also sets 'nomodeline' on the buffer. @@ -690,7 +700,7 @@ nvim_del_mark({name}) *nvim_del_mark()* fails with error if a lowercase or buffer local named mark is used. Parameters: ~ - {name} Mark name + • {name} Mark name Return: ~ true if the mark was deleted, else false. @@ -703,31 +713,31 @@ nvim_del_var({name}) *nvim_del_var()* Removes a global (g:) variable. Parameters: ~ - {name} Variable name + • {name} Variable name nvim_echo({chunks}, {history}, {opts}) *nvim_echo()* Echo a message. Parameters: ~ - {chunks} A list of [text, hl_group] arrays, each representing a text + • {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. - {history} if true, add to |message-history|. - {opts} Optional parameters. Reserved for future use. + • {history} if true, add to |message-history|. + • {opts} Optional parameters. Reserved for future use. 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 + • {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 + • {str} Message See also: ~ nvim_err_write() @@ -739,8 +749,8 @@ nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* |api-fast| Parameters: ~ - {str} Statusline string (see 'statusline'). - {opts} Optional parameters. + • {str} Statusline string (see 'statusline'). + • {opts} Optional parameters. • winid: (number) |window-ID| of the window to use as context for statusline. • maxwidth: (number) Maximum width of statusline. @@ -750,7 +760,7 @@ nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* • highlights: (boolean) Return highlight information. • use_winbar: (boolean) Evaluate winbar instead of statusline. • use_tabline: (boolean) Evaluate tabline instead of - statusline. When |TRUE|, {winid} is ignored. Mutually + statusline. When true, {winid} is ignored. Mutually exclusive with {use_winbar}. Return: ~ @@ -759,7 +769,7 @@ nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* • width: (number) Display width of the statusline. • highlights: Array containing highlight information of the statusline. Only included when the "highlights" key in {opts} is - |TRUE|. Each element of the array is a |Dictionary| with these keys: + true. Each element of the array is a |Dictionary| with these keys: • start: (number) Byte index (0-based) of first character that uses the highlight. • group: (string) Name of highlight group. @@ -775,8 +785,8 @@ nvim_exec_lua({code}, {args}) *nvim_exec_lua()* |RPC| only Parameters: ~ - {code} Lua code to execute - {args} Arguments to the code + • {code} Lua code to execute + • {args} Arguments to the code Return: ~ Return value of Lua code if present or NIL. @@ -797,9 +807,9 @@ nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()* < Parameters: ~ - {keys} to be typed - {mode} behavior flags, see |feedkeys()| - {escape_ks} If true, escape K_SPECIAL bytes in `keys` This should be + • {keys} to be typed + • {mode} behavior flags, see |feedkeys()| + • {escape_ks} If true, escape K_SPECIAL bytes in `keys` This should be false if you already used |nvim_replace_termcodes()|, and true otherwise. @@ -853,7 +863,7 @@ nvim_get_color_by_name({name}) *nvim_get_color_by_name()* < Parameters: ~ - {name} Color name or "#rrggbb" string + • {name} Color name or "#rrggbb" string Return: ~ 24-bit RGB value, or -1 for invalid argument. @@ -871,7 +881,7 @@ nvim_get_context({*opts}) *nvim_get_context()* Gets a map of the current editor state. Parameters: ~ - {opts} Optional parameters. + • {opts} Optional parameters. • types: List of |context-types| ("regs", "jumps", "bufs", "gvars", …) to gather, or empty for "all". @@ -906,8 +916,8 @@ 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 + • {hl_id} Highlight id as returned by |hlID()| + • {rgb} Export RGB colors Return: ~ Highlight definition map @@ -919,8 +929,8 @@ 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 + • {name} Highlight group name + • {rgb} Export RGB colors Return: ~ Highlight definition map @@ -937,7 +947,7 @@ nvim_get_keymap({mode}) *nvim_get_keymap()* Gets a list of global (non-buffer-local) |mapping| definitions. Parameters: ~ - {mode} Mode short-name ("n", "i", "v", ...) + • {mode} Mode short-name ("n", "i", "v", ...) Return: ~ Array of |maparg()|-like dictionaries describing mappings. The @@ -953,8 +963,8 @@ nvim_get_mark({name}, {opts}) *nvim_get_mark()* fails with error if a lowercase or buffer local named mark is used. Parameters: ~ - {name} Mark name - {opts} Optional parameters. Reserved for future use. + • {name} Mark name + • {opts} Optional parameters. Reserved for future use. Return: ~ 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is @@ -989,7 +999,7 @@ nvim_get_proc_children({pid}) *nvim_get_proc_children()* nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()* Find files in runtime directories - 'name' can contain wildcards. For example + "name" can contain wildcards. For example nvim_get_runtime_file("colors/*.vim", true) will return all color scheme files. Always use forward slashes (/) in the search pattern for subdirectories regardless of platform. @@ -1000,8 +1010,8 @@ nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()* |api-fast| Parameters: ~ - {name} pattern of files to search for - {all} whether to return all matches or only the first + • {name} pattern of files to search for + • {all} whether to return all matches or only the first Return: ~ list of absolute paths to the found files @@ -1010,7 +1020,7 @@ nvim_get_var({name}) *nvim_get_var()* Gets a global (g:) variable. Parameters: ~ - {name} Variable name + • {name} Variable name Return: ~ Variable value @@ -1019,7 +1029,7 @@ nvim_get_vvar({name}) *nvim_get_vvar()* Gets a v: variable. Parameters: ~ - {name} Variable name + • {name} Variable name Return: ~ Variable value @@ -1043,7 +1053,7 @@ nvim_input({keys}) *nvim_input()* |api-fast| Parameters: ~ - {keys} to be typed + • {keys} to be typed Return: ~ Number of bytes actually written (can be fewer than requested if the @@ -1067,16 +1077,18 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) |api-fast| Parameters: ~ - {button} Mouse button: one of "left", "right", "middle", "wheel". - {action} For ordinary buttons, one of "press", "drag", "release". + • {button} Mouse button: one of "left", "right", "middle", "wheel", + "move". + • {action} For ordinary buttons, one of "press", "drag", "release". For the wheel, one of "up", "down", "left", "right". - {modifier} String of modifiers each represented by a single char. The + Ignored for "move". + • {modifier} String of modifiers each represented by a single char. The same specifiers are used as for a key press, except that the "-" separator is optional, so "C-A-", "c-a" and "CA" can all be used to specify Ctrl+Alt+click. - {grid} Grid number if the client uses |ui-multigrid|, else 0. - {row} Mouse row-position (zero-based, like redraw events) - {col} Mouse column-position (zero-based, like redraw events) + • {grid} Grid number if the client uses |ui-multigrid|, else 0. + • {row} Mouse row-position (zero-based, like redraw events) + • {col} Mouse column-position (zero-based, like redraw events) nvim_list_bufs() *nvim_list_bufs()* Gets the current list of buffer handles @@ -1127,7 +1139,7 @@ nvim_load_context({dict}) *nvim_load_context()* Sets the current editor state from the given |context| map. Parameters: ~ - {dict} |Context| map. + • {dict} |Context| map. nvim_notify({msg}, {log_level}, {opts}) *nvim_notify()* Notify the user with a message @@ -1136,9 +1148,9 @@ nvim_notify({msg}, {log_level}, {opts}) *nvim_notify()* echo area but can be overridden to trigger desktop notifications. Parameters: ~ - {msg} Message to display to the user - {log_level} The log level - {opts} Reserved for future use. + • {msg} Message to display to the user + • {log_level} The log level + • {opts} Reserved for future use. nvim_open_term({buffer}, {opts}) *nvim_open_term()* Open a terminal instance in a buffer @@ -1156,13 +1168,13 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* virtual terminal having the intended size. Parameters: ~ - {buffer} the buffer to use (expected to be empty) - {opts} Optional parameters. + • {buffer} the buffer to use (expected to be empty) + • {opts} Optional parameters. • 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 - is possible to call |nvim_chan_send| directly in the + is possible to call |nvim_chan_send()| directly in the callback however. ["input", term, bufnr, data] Return: ~ @@ -1173,7 +1185,7 @@ nvim_out_write({str}) *nvim_out_write()* message is buffered (won't display) until a linefeed is written. Parameters: ~ - {str} Message + • {str} Message nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* Pastes at cursor, in any mode. @@ -1190,9 +1202,9 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* not allowed when |textlock| is active Parameters: ~ - {data} Multiline input. May be binary (containing NUL bytes). - {crlf} Also break lines at CR and CRLF. - {phase} -1: paste in a single call (i.e. without streaming). To + • {data} Multiline input. May be binary (containing NUL bytes). + • {crlf} Also break lines at CR and CRLF. + • {phase} -1: paste in a single call (i.e. without streaming). To "stream" a paste, call `nvim_paste` sequentially with these `phase` values: • 1: starts the paste (exactly once) • 2: continues the paste (zero or more times) @@ -1212,15 +1224,15 @@ nvim_put({lines}, {type}, {after}, {follow}) *nvim_put()* not allowed when |textlock| is active Parameters: ~ - {lines} |readfile()|-style list of lines. |channel-lines| - {type} Edit behavior: any |getregtype()| result, or: + • {lines} |readfile()|-style list of lines. |channel-lines| + • {type} Edit behavior: any |getregtype()| result, or: • "b" |blockwise-visual| mode (may include width, e.g. "b3") • "c" |charwise| mode • "l" |linewise| mode • "" guess by contents, see |setreg()| - {after} If true insert after cursor (like |p|), or before (like + • {after} If true insert after cursor (like |p|), or before (like |P|). - {follow} If true place cursor at end of inserted text. + • {follow} If true place cursor at end of inserted text. *nvim_replace_termcodes()* nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) @@ -1228,10 +1240,10 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) 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 "\r" char. + • {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 "\r" char. See also: ~ replace_termcodes @@ -1247,12 +1259,12 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) ensure the mapping doesn't end completion mode. Parameters: ~ - {item} Index (zero-based) of the item to select. Value of -1 + • {item} Index (zero-based) of the item to select. Value of -1 selects nothing and restores the original text. - {insert} Whether the selection should be inserted in the buffer. - {finish} Finish the completion and dismiss the popupmenu. Implies + • {insert} Whether the selection should be inserted in the buffer. + • {finish} Finish the completion and dismiss the popupmenu. Implies `insert`. - {opts} Optional parameters. Reserved for future use. + • {opts} Optional parameters. Reserved for future use. *nvim_set_client_info()* nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) @@ -1274,8 +1286,8 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) |RPC| only Parameters: ~ - {name} Short name for the connected client - {version} Dictionary describing the version, with these (optional) + • {name} Short name for the connected client + • {version} Dictionary describing the version, with these (optional) keys: • "major" major version (defaults to 0 if not set, for no release yet) @@ -1284,7 +1296,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) • "prerelease" string describing a prerelease, like "dev" or "beta1" • "commit" hash or similar identifier of commit - {type} Must be one of the following values. Client libraries + • {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. @@ -1293,7 +1305,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) example, IDE/editor implementing a vim mode). • "host" plugin host, typically started by nvim • "plugin" single plugin, started by nvim - {methods} Builtin methods in the client. For a host, this does not + • {methods} Builtin methods in the client. For a host, this does not include plugin methods which will be discovered later. The key should be the method name, the values are dicts with these (optional) keys (more keys may be added in @@ -1305,7 +1317,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) • "nargs" Number of arguments. Could be a single integer or an array of two integers, minimum and maximum inclusive. - {attributes} Arbitrary string:string map of informal client + • {attributes} Arbitrary string:string map of informal client properties. Suggested keys: • "website": Client homepage URL (e.g. GitHub repository) @@ -1321,13 +1333,13 @@ nvim_set_current_buf({buffer}) *nvim_set_current_buf()* not allowed when |textlock| is active Parameters: ~ - {buffer} Buffer handle + • {buffer} Buffer handle nvim_set_current_dir({dir}) *nvim_set_current_dir()* Changes the global working directory. Parameters: ~ - {dir} Directory path + • {dir} Directory path nvim_set_current_line({line}) *nvim_set_current_line()* Sets the current line. @@ -1336,7 +1348,7 @@ nvim_set_current_line({line}) *nvim_set_current_line()* not allowed when |textlock| is active Parameters: ~ - {line} Line contents + • {line} Line contents nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* Sets the current tabpage. @@ -1345,7 +1357,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* not allowed when |textlock| is active Parameters: ~ - {tabpage} Tabpage handle + • {tabpage} Tabpage handle nvim_set_current_win({window}) *nvim_set_current_win()* Sets the current window. @@ -1354,7 +1366,7 @@ nvim_set_current_win({window}) *nvim_set_current_win()* not allowed when |textlock| is active Parameters: ~ - {window} Window handle + • {window} Window handle nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* Sets a highlight group. @@ -1372,10 +1384,10 @@ nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* using these values results in an error. Parameters: ~ - {ns_id} Namespace id for this highlight |nvim_create_namespace()|. + • {ns_id} Namespace id for this highlight |nvim_create_namespace()|. Use 0 to set a highlight group globally |:highlight|. - {name} Highlight group name, e.g. "ErrorMsg" - {val} Highlight definition map, accepts the following keys: + • {name} Highlight group name, e.g. "ErrorMsg" + • {val} Highlight definition map, accepts the following keys: • fg (or foreground): color name or "#RRGGBB", see note. • bg (or background): color name or "#RRGGBB", see note. • sp (or special): color name or "#RRGGBB" @@ -1394,31 +1406,31 @@ nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* • link: name of another highlight group to link to, see |:hi-link|. • default: Don't override existing definition |:hi-default| - • ctermfg: Sets foreground of cterm color |highlight-ctermfg| - • ctermbg: Sets background of cterm color |highlight-ctermbg| + • ctermfg: Sets foreground of cterm color |ctermfg| + • ctermbg: Sets background of cterm color |ctermbg| • cterm: cterm attribute map, like |highlight-args|. If not set, cterm attributes will match those from the attribute map documented above. 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|. + see |nvim_win_set_hl_ns()|. Parameters: ~ - {ns_id} the namespace to use + • {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. This function meant to be called while redrawing, primarily from - |nvim_set_decoration_provider| on_win and on_line callbacks, which are + |nvim_set_decoration_provider()| on_win and on_line callbacks, which are allowed to change the namespace during a redraw cycle. Attributes: ~ |api-fast| Parameters: ~ - {ns_id} the namespace to activate + • {ns_id} the namespace to activate nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* Sets a global |mapping| for the given mode. @@ -1437,13 +1449,13 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* < Parameters: ~ - {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or + • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or "!" for |:map!|, or empty string for |:map|. - {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 + • {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". + 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 @@ -1456,22 +1468,22 @@ nvim_set_var({name}, {value}) *nvim_set_var()* Sets a global (g:) variable. Parameters: ~ - {name} Variable name - {value} Variable value + • {name} Variable name + • {value} Variable value nvim_set_vvar({name}, {value}) *nvim_set_vvar()* Sets a v: variable, if it is not readonly. Parameters: ~ - {name} Variable name - {value} Variable value + • {name} Variable name + • {value} Variable value nvim_strwidth({text}) *nvim_strwidth()* Calculates the number of display cells occupied by `text`. Control characters including <Tab> count as one cell. Parameters: ~ - {text} Some text + • {text} Some text Return: ~ Number of cells @@ -1483,7 +1495,7 @@ nvim_subscribe({event}) *nvim_subscribe()* |RPC| only Parameters: ~ - {event} Event type string + • {event} Event type string nvim_unsubscribe({event}) *nvim_unsubscribe()* Unsubscribes to event broadcasts. @@ -1492,7 +1504,7 @@ nvim_unsubscribe({event}) *nvim_unsubscribe()* |RPC| only Parameters: ~ - {event} Event type string + • {event} Event type string ============================================================================== @@ -1505,9 +1517,9 @@ nvim_call_dict_function({dict}, {fn}, {args}) On execution error: fails with VimL 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 - {args} Function arguments packed in an Array + • {dict} Dictionary, or String evaluating to a VimL |self| dict + • {fn} Name of the function defined on the VimL dict + • {args} Function arguments packed in an Array Return: ~ Result of the function call @@ -1518,8 +1530,8 @@ nvim_call_function({fn}, {args}) *nvim_call_function()* On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ - {fn} Function to call - {args} Function arguments packed in an Array + • {fn} Function to call + • {args} Function arguments packed in an Array Return: ~ Result of the function call @@ -1536,7 +1548,7 @@ nvim_command({command}) *nvim_command()* |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. Parameters: ~ - {command} Ex command string + • {command} Ex command string nvim_eval({expr}) *nvim_eval()* Evaluates a VimL |expression|. Dictionaries and Lists are recursively @@ -1545,7 +1557,7 @@ nvim_eval({expr}) *nvim_eval()* On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ - {expr} VimL expression string + • {expr} VimL expression string Return: ~ Evaluation result or expanded object @@ -1560,8 +1572,8 @@ nvim_exec({src}, {output}) *nvim_exec()* On execution error: fails with VimL error, updates v:errmsg. Parameters: ~ - {src} Vimscript code - {output} Capture and return all (non-error, non-shell |:!|) output + • {src} Vimscript code + • {output} Capture and return all (non-error, non-shell |:!|) output Return: ~ Output (non-error, non-shell |:!|) if `output` is true, else empty @@ -1580,8 +1592,8 @@ nvim_parse_expression({expr}, {flags}, {highlight}) |api-fast| Parameters: ~ - {expr} Expression to parse. Always treated as a single line. - {flags} Flags: + • {expr} Expression to parse. Always treated as a single line. + • {flags} Flags: • "m" if multiple expressions in a row are allowed (only the first one will be parsed), • "E" if EOC tokens are not allowed (determines whether @@ -1593,7 +1605,7 @@ nvim_parse_expression({expr}, {flags}, {highlight}) • "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 + • {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 @@ -1661,7 +1673,7 @@ nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts}) Create a new user command |user-commands| in the given buffer. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer. + • {buffer} Buffer handle, or 0 for current buffer. See also: ~ nvim_create_user_command @@ -1674,15 +1686,15 @@ nvim_buf_del_user_command({buffer}, {name}) |nvim_buf_create_user_command()| can be deleted with this function. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer. - {name} Name of the command to delete. + • {buffer} Buffer handle, or 0 for current buffer. + • {name} Name of the command to delete. nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* Gets a map of buffer-local |user-commands|. Parameters: ~ - {buffer} Buffer handle, or 0 for current buffer - {opts} Optional parameters. Currently not used. |