diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 295 |
1 files changed, 267 insertions, 28 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 8fb6290e50..fe5f9eaf35 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -45,7 +45,7 @@ start with a TCP/IP socket instead, use |--listen| with a TCP-style address: > More endpoints can be started with |serverstart()|. Note that localhost TCP sockets are generally less secure than named pipes, -and can lead to vunerabilities like remote code execution. +and can lead to vulnerabilities like remote code execution. Connecting to the socket is the easiest way a programmer can test the API, which can be done through any msgpack-rpc client library or full-featured @@ -186,7 +186,7 @@ About the `functions` map: a type name, e.g. `nvim_buf_get_lines` is the `get_lines` method of a Buffer instance. |dev-api| - Global functions have the "method=false" flag and are prefixed with just - `nvim_`, e.g. `nvim_get_buffers`. + `nvim_`, e.g. `nvim_list_bufs`. *api-mapping* External programs (clients) can use the metadata to discover the API, using @@ -198,7 +198,7 @@ any of these approaches: 2. Start Nvim with |--api-info|. Useful for statically-compiled clients. Example (requires Python "pyyaml" and "msgpack-python" modules): > - nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' + 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. > :lua print(vim.inspect(vim.fn.api_info())) @@ -361,7 +361,7 @@ UTF-32 and UTF-16 sizes of the deleted region is also passed as additional arguments {old_utf32_size} and {old_utf16_size}. "on_changedtick" is invoked when |b:changedtick| was incremented but no text -was changed. The parameters recieved are ("changedtick", {buf}, {changedtick}). +was changed. The parameters received are ("changedtick", {buf}, {changedtick}). *api-lua-detach* In-process Lua callbacks can detach by returning `true`. This will detach all @@ -468,7 +468,7 @@ extmark position and enter some text, the extmark migrates forward. > f o o z|b a r line (| = cursor) 4 extmark (after typing "z") -If an extmark is on the last index of a line and you inputsa newline at that +If an extmark is on the last index of a line and you inputs a newline at that point, the extmark will accordingly migrate to the next line: > f o o z b a r| line (| = cursor) @@ -626,6 +626,62 @@ nvim__stats() *nvim__stats()* Return: ~ Map of various internal stats. + *nvim_add_user_command()* +nvim_add_user_command({name}, {command}, {*opts}) + Create a new user command |user-commands| + + {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. + + Example: > + :call nvim_add_user_command('SayHello', 'echo "Hello world!"', {}) + :SayHello + Hello world! +< + + Parameters: ~ + {name} Name of the new user command. Must begin with + an uppercase letter. + {command} Replacement command to execute when this user + command is executed. When called from Lua, the + command can also be a Lua function. The + function is called with a single table argument + that contains the following keys: + • args: (string) The args passed to the + command, if any |<args>| + • fargs: (table) The args split by unescaped + whitespace (when more than one argument is + allowed), if any |<f-args>| + • bang: (boolean) "true" if the command was + executed with a ! modifier |<bang>| + • line1: (number) The starting line of the + command range |<line1>| + • line2: (number) The final line of the command + range |<line2>| + • range: (number) The number of items in the + command range: 0, 1, or 2 |<range>| + • count: (number) Any count supplied |<count>| + • reg: (string) The optional register, if + specified |<reg>| + • mods: (string) Command modifiers, if any + |<mods>| + {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. + nvim_call_atomic({calls}) *nvim_call_atomic()* Calls many API methods atomically. @@ -634,7 +690,7 @@ nvim_call_atomic({calls}) *nvim_call_atomic()* atomically, i.e. without interleaving redraws, RPC requests from other clients, or user interactions (however API methods may trigger autocommands or event processing which - have such side-effects, e.g. |:sleep| may wake timers). + have such side effects, e.g. |:sleep| may wake timers). 2. To minimize RPC overhead (roundtrips) of a sequence of many requests. @@ -656,8 +712,8 @@ nvim_chan_send({chan}, {data}) *nvim_chan_send()* Send data to channel `id` . For a job, it writes it to the stdin of the process. For the stdio channel |channel-stdio|, it writes to Nvim's stdout. For an internal terminal instance - (|nvim_open_term()|) it writes directly to terimal output. See - |channel-bytes| for more information. + (|nvim_open_term()|) it writes directly to terminal output. + See |channel-bytes| for more information. This function writes raw data, not RPC messages. If the channel was created with `rpc=true` then the channel expects @@ -698,7 +754,7 @@ nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* |nvim_set_keymap()| nvim_del_mark({name}) *nvim_del_mark()* - Deletes a uppercase/file named mark. See |mark-motions|. + Deletes an uppercase/file named mark. See |mark-motions|. Note: fails with error if a lowercase or buffer local named mark @@ -714,6 +770,12 @@ nvim_del_mark({name}) *nvim_del_mark()* |nvim_buf_del_mark()| |nvim_get_mark()| +nvim_del_user_command({name}) *nvim_del_user_command()* + Delete a user-defined command. + + Parameters: ~ + {name} Name of the command to delete. + nvim_del_var({name}) *nvim_del_var()* Removes a global (g:) variable. @@ -796,7 +858,7 @@ nvim_exec_lua({code}, {args}) *nvim_exec_lua()* Return: ~ Return value of Lua code if present or NIL. -nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* +nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()* Sends input-keys to Nvim, subject to various quirks controlled by `mode` flags. This is a blocking call, unlike |nvim_input()|. @@ -804,23 +866,25 @@ nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* On execution error: does not fail, but updates v:errmsg. To input sequences like <C-o> use |nvim_replace_termcodes()| - (typically with escape_csi=true) to replace |keycodes|, then + (typically with escape_ks=false) to replace |keycodes|, then pass the result to nvim_feedkeys(). Example: > :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true) - :call nvim_feedkeys(key, 'n', v:true) + :call nvim_feedkeys(key, 'n', v:false) < Parameters: ~ - {keys} to be typed - {mode} behavior flags, see |feedkeys()| - {escape_csi} If true, escape K_SPECIAL/CSI bytes in - `keys` + {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. See also: ~ feedkeys() - vim_strsave_escape_csi + vim_strsave_escape_ks nvim_get_all_options_info() *nvim_get_all_options_info()* Gets the option information for all options. @@ -1061,7 +1125,7 @@ nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* Parameters: ~ {name} Option name {opts} Optional parameters - • scope: One of 'global' or 'local'. Analagous to + • scope: One of 'global' or 'local'. Analogous to |:setglobal| and |:setlocal|, respectively. Return: ~ @@ -1346,7 +1410,7 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) {from_part} Legacy Vim parameter. Usually true. {do_lt} Also translate <lt>. Ignored if `special` is false. - {special} Replace |keycodes|, e.g. <CR> becomes a "\n" + {special} Replace |keycodes|, e.g. <CR> becomes a "\r" char. See also: ~ @@ -1479,14 +1543,13 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Parameters: ~ {window} Window handle -nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()* +nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* Set a highlight group. - TODO: ns_id = 0, should modify :highlight namespace TODO val - should take update vs reset flag - Parameters: ~ - {ns_id} number of namespace for this highlight + {ns_id} number of namespace for this highlight. Use value + 0 to set a highlight group in the global ( + `:highlight` ) namespace. {name} highlight group name, like ErrorMsg {val} highlight definition map, like |nvim_get_hl_by_name|. in addition the following @@ -1524,8 +1587,11 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* {rhs} Right-hand-side |{rhs}| of the mapping. {opts} Optional parameters map. Accepts all |:map-arguments| as keys excluding |<buffer>| but - including |noremap|. Values are Booleans. Unknown - key is an error. + including |noremap| and "desc". "desc" can be used + to give a description to keymap. When called from + Lua, also accepts a "callback" key that takes a + Lua function to call when the mapping is executed. + Values are Booleans. Unknown key is an error. nvim_set_option({name}, {value}) *nvim_set_option()* Sets the global value of an option. @@ -1545,7 +1611,7 @@ nvim_set_option_value({name}, {value}, {*opts}) {name} Option name {value} New option value {opts} Optional parameters - • scope: One of 'global' or 'local'. Analagous to + • scope: One of 'global' or 'local'. Analogous to |:setglobal| and |:setlocal|, respectively. nvim_set_var({name}, {value}) *nvim_set_var()* @@ -1790,6 +1856,16 @@ nvim__buf_redraw_range({buffer}, {first}, {last}) nvim__buf_stats({buffer}) *nvim__buf_stats()* TODO: Documentation + *nvim_buf_add_user_command()* +nvim_buf_add_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. + + See also: ~ + nvim_add_user_command + nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua callbacks. @@ -1925,6 +2001,18 @@ nvim_buf_del_mark({buffer}, {name}) *nvim_buf_del_mark()* |nvim_buf_set_mark()| |nvim_del_mark()| + *nvim_buf_del_user_command()* +nvim_buf_del_user_command({buffer}, {name}) + Delete a buffer-local user-defined command. + + Only commands created with |:command-buffer| or + |nvim_buf_add_user_command()| can be deleted with this + function. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer. + {name} Name of the command to delete. + nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* Removes a buffer-scoped (b:) variable @@ -2067,6 +2155,29 @@ nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* Return: ~ Option value + *nvim_buf_get_text()* +nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, + {opts}) + Gets a range from the buffer. + + This differs from |nvim_buf_get_lines()| in that it allows + retrieving only portions of a line. + + Indexing is zero-based. Column indices are end-exclusive. + + Prefer |nvim_buf_get_lines()| when retrieving entire lines. + + Parameters: ~ + {buffer} Buffer handle, or 0 for current buffer + {start_row} First line index + {start_col} Starting byte offset of first line + {end_row} Last line index + {end_col} Ending byte offset of last line (exclusive) + {opts} Optional parameters. Currently unused. + + Return: ~ + Array of lines, or empty array for unloaded buffer. + nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()* Gets a buffer-scoped (b:) variable. @@ -2464,6 +2575,10 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) • priority: a priority value for the highlight group. For example treesitter highlighting uses a value of 100. + • strict: boolean that indicates extmark should + not be placed if the line or column value is + past the end of the buffer or end of the line + respectively. Defaults to true. Return: ~ Id of the created/updated extmark @@ -2687,7 +2802,7 @@ nvim_win_is_valid({window}) *nvim_win_is_valid()* true if the window is valid, false otherwise nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* - Sets the current buffer in a window, without side-effects + Sets the current buffer in a window, without side effects Attributes: ~ not allowed when |textlock| is active @@ -2994,6 +3109,130 @@ nvim_tabpage_set_var({tabpage}, {name}, {value}) ============================================================================== +Autocmd Functions *api-autocmd* + +nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* + Create or get an augroup. + + To get an existing augroup ID, do: > + local id = vim.api.nvim_create_augroup(name, { + clear = false + }) +< + + Parameters: ~ + {name} String: The name of the augroup to create + {opts} Parameters + • clear (bool): Whether to clear existing commands + or not. Defaults to true. See |autocmd-groups| + + Return: ~ + opaque value to use with nvim_del_augroup_by_id + +nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* + Create an autocmd. + + Examples: + • event: "pat1,pat2,pat3", + • event: "pat1" + • event: { "pat1" } + • event: { "pat1", "pat2", "pat3" } + + Parameters: ~ + {event} The event or events to register this autocmd + Required keys: event: string | ArrayOf(string) + + Parameters: ~ + {opts} Optional Parameters: + • callback: (string|function) + • (string): The name of the viml function to + execute when triggering this autocmd + • (function): The lua function to execute when + triggering this autocmd + • NOTE: Cannot be used with {command} + + • command: (string) command + • vimscript command + • NOTE: Cannot be used with {callback} Eg. + command = "let g:value_set = v:true" + + • pattern: (string|table) + • pattern or patterns to match against + • defaults to "*". + • NOTE: Cannot be used with {buffer} + + • buffer: (bufnr) + • create a |autocmd-buflocal| autocmd. + • NOTE: Cannot be used with {pattern} + + • group: (string) The augroup name + • once: (boolean) - See |autocmd-once| + • nested: (boolean) - See |autocmd-nested| + • desc: (string) - Description of the autocmd + + Return: ~ + opaque value to use with nvim_del_autocmd + +nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()* + Delete an augroup by {id}. {id} can only be returned when + augroup was created with |nvim_create_augroup|. + + NOTE: behavior differs from augroup-delete. + + When deleting an augroup, autocmds contained by this augroup + will also be deleted and cleared. This augroup will no longer + exist + +nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()* + Delete an augroup by {name}. + + NOTE: behavior differs from augroup-delete. + + When deleting an augroup, autocmds contained by this augroup + will also be deleted and cleared. This augroup will no longer + exist + +nvim_del_autocmd({id}) *nvim_del_autocmd()* + Delete an autocmd by {id}. Autocmds only return IDs when + created via the API. Will not error if called and no autocmds + match the {id}. + + Parameters: ~ + {id} Integer The ID returned by nvim_create_autocmd + +nvim_do_autocmd({event}, {*opts}) *nvim_do_autocmd()* + Do one autocmd. + + Parameters: ~ + {event} The event or events to execute + {opts} Optional Parameters: + • buffer (number) - buffer number + • NOTE: Cannot be used with {pattern} + + • pattern (string|table) - optional, defaults to + "*". + • NOTE: Cannot be used with {buffer} + + • group (string) - autocmd group name + • modeline (boolean) - Default true, see + |<nomodeline>| + +nvim_get_autocmds({*opts}) *nvim_get_autocmds()* + Get autocmds that match the requirements passed to {opts}. + + Parameters: ~ + {opts} Optional Parameters: + • event : Name or list of name of events to match + against + • group (string): Name of group to match against + • pattern: Pattern or list of patterns to match + against + + Return: ~ + A list of autocmds that match + + +============================================================================== UI Functions *api-ui* nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* |