mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-10-08 19:06:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc [ci skip]

Browse Source 
closes #9719
This commit is contained in:
Justin M. Keyes
2019-02-04 13:21:35 +01:00
parent 2d50bf3498
commit fbaee922d1
19 changed files with 262 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
src/nvim/api/buffer.c
View File

@@ -49,7 +49,7 @@
/// Gets the buffer line count
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any
/// @return Line count, or 0 for unloaded buffer. |api-buffer|
Integer nvim_buf_line_count(Buffer buffer, Error *err)
@@ -99,7 +99,8 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
/// Activate updates from this buffer to the current channel.
///
/// @param buffer The buffer handle
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param send_buffer Set to true if the initial notification should contain
/// the whole buffer. If so, the first notification will be a
/// `nvim_buf_lines_event`. Otherwise, the first notification will be
@@ -131,7 +132,8 @@ Boolean nvim_buf_attach(uint64_t channel_id,
//
/// Deactivate updates from this buffer to the current channel.
///
/// @param buffer The buffer handle
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Details of an error that may have occurred
/// @return False when updates couldn't be disabled because the buffer
/// isn't loaded; otherwise True.
@@ -221,7 +223,8 @@ ArrayOf(String) buffer_get_line_slice(Buffer buffer,
/// Out-of-bounds indices are clamped to the nearest valid value, unless
/// `strict_indexing` is set.
///
/// @param buffer Buffer handle
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param start First line index
/// @param end Last line index (exclusive)
/// @param strict_indexing Whether out-of-bounds should be an error.
@@ -290,7 +293,7 @@ end:
/// newend = end + int(include_end) + int(end < 0)
/// int(bool) = 1 if bool is true else 0
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param start First line index
/// @param end Last line index
/// @param include_start True if the slice includes the `start` parameter
@@ -324,7 +327,8 @@ void buffer_set_line_slice(Buffer buffer,
/// Out-of-bounds indices are clamped to the nearest valid value, unless
/// `strict_indexing` is set.
///
/// @param buffer Buffer handle
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param start First line index
/// @param end Last line index (exclusive)
/// @param strict_indexing Whether out-of-bounds should be an error.
@@ -491,7 +495,7 @@ end:
/// Unlike |line2byte()|, throws error for out-of-bounds indexing.
/// Returns -1 for unloaded buffer.
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param index Line index
/// @param[out] err Error details, if any
/// @return Integer byte offset, or -1 for unloaded buffer.
@@ -518,7 +522,7 @@ Integer nvim_buf_get_offset(Buffer buffer, Integer index, Error *err)
/// Gets a buffer-scoped (b:) variable.
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name
/// @param[out] err Error details, if any
/// @return Variable value
@@ -536,7 +540,7 @@ Object nvim_buf_get_var(Buffer buffer, String name, Error *err)
/// Gets a changed tick of a buffer
///
/// @param[in] buffer Buffer handle.
/// @param[in] buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any
///
/// @return `b:changedtick` value.
@@ -555,7 +559,7 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
/// Gets a list of buffer-local |mapping| definitions.
///
/// @param mode Mode short-name ("n", "i", "v", ...)
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any
/// @returns Array of maparg()-like dictionaries describing mappings.
/// The "buffer" key holds the associated buffer handle.
@@ -573,7 +577,7 @@ ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
/// Gets a map of buffer-local |user-commands|.
///
/// @param buffer Buffer handle.
/// @param buffer Buffer handle, or 0 for current buffer
/// @param opts Optional parameters. Currently not used.
/// @param[out] err Error details, if any.
///
@@ -613,7 +617,7 @@ Dictionary nvim_buf_get_commands(Buffer buffer, Dictionary opts, Error *err)
/// Sets a buffer-scoped (b:) variable
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name
/// @param value Variable value
/// @param[out] err Error details, if any
@@ -631,7 +635,7 @@ void nvim_buf_set_var(Buffer buffer, String name, Object value, Error *err)
/// Removes a buffer-scoped (b:) variable
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name
/// @param[out] err Error details, if any
void nvim_buf_del_var(Buffer buffer, String name, Error *err)
@@ -650,7 +654,7 @@ void nvim_buf_del_var(Buffer buffer, String name, Error *err)
///
/// @deprecated
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name
/// @param value Variable value
/// @param[out] err Error details, if any
@@ -673,7 +677,7 @@ Object buffer_set_var(Buffer buffer, String name, Object value, Error *err)
///
/// @deprecated
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Variable name
/// @param[out] err Error details, if any
/// @return Old value
@@ -691,7 +695,7 @@ Object buffer_del_var(Buffer buffer, String name, Error *err)
/// Gets a buffer option value
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Option name
/// @param[out] err Error details, if any
/// @return Option value
@@ -710,7 +714,8 @@ Object nvim_buf_get_option(Buffer buffer, String name, Error *err)
/// Sets a buffer option value. Passing 'nil' as value deletes the option (only
/// works if there's a global fallback)
///
/// @param buffer Buffer handle
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Option name
/// @param value Option value
/// @param[out] err Error details, if any
@@ -732,7 +737,7 @@ void nvim_buf_set_option(uint64_t channel_id, Buffer buffer,
/// @deprecated The buffer number now is equal to the object id,
/// so there is no need to use this function.
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any
/// @return Buffer number
Integer nvim_buf_get_number(Buffer buffer, Error *err)
@@ -751,7 +756,7 @@ Integer nvim_buf_get_number(Buffer buffer, Error *err)
/// Gets the full file name for the buffer
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any
/// @return Buffer name
String nvim_buf_get_name(Buffer buffer, Error *err)
@@ -769,7 +774,7 @@ String nvim_buf_get_name(Buffer buffer, Error *err)
/// Sets the full file name for a buffer
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Buffer name
/// @param[out] err Error details, if any
void nvim_buf_set_name(Buffer buffer, String name, Error *err)
@@ -801,7 +806,7 @@ void nvim_buf_set_name(Buffer buffer, String name, Error *err)
/// Checks if a buffer is valid and loaded. See |api-buffer| for more info
/// about unloaded buffers.
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @return true if the buffer is valid and loaded, false otherwise.
Boolean nvim_buf_is_loaded(Buffer buffer)
FUNC_API_SINCE(5)
@@ -817,7 +822,7 @@ Boolean nvim_buf_is_loaded(Buffer buffer)
/// @note Even if a buffer is valid it may have been unloaded. See |api-buffer|
/// for more info about unloaded buffers.
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @return true if the buffer is valid, false otherwise.
Boolean nvim_buf_is_valid(Buffer buffer)
FUNC_API_SINCE(1)
@@ -849,7 +854,7 @@ void buffer_insert(Buffer buffer,
/// Return a tuple (row,col) representing the position of the named mark
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param name Mark name
/// @param[out] err Error details, if any
/// @return (row, col) tuple
@@ -914,7 +919,7 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
/// supported for backwards compatibility, new code should use
/// |nvim_create_namespace| to create a new empty namespace.
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param ns_id namespace to use or -1 for ungrouped highlight
/// @param hl_group Name of the highlight group to use
/// @param line Line to highlight (zero-indexed)
@@ -964,7 +969,7 @@ Integer nvim_buf_add_highlight(Buffer buffer,
/// To clear the namespace in the entire buffer, pass in 0 and -1 to
/// line_start and line_end respectively.
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param ns_id Namespace to clear, or -1 to clear all namespaces.
/// @param line_start Start of range of lines to clear
/// @param line_end End of range of lines to clear (exclusive) or -1 to clear
@@ -997,7 +1002,7 @@ void nvim_buf_clear_namespace(Buffer buffer,
///
/// @deprecated use |nvim_buf_clear_namespace|.
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param ns_id Namespace to clear, or -1 to clear all.
/// @param line_start Start of range of lines to clear
/// @param line_end End of range of lines to clear (exclusive) or -1 to clear
@@ -1031,7 +1036,7 @@ void nvim_buf_clear_highlight(Buffer buffer,
/// As a shorthand, `ns_id = 0` can be used to create a new namespace for the
/// virtual text, the allocated id is then returned.
///
/// @param buffer Buffer handle
/// @param buffer Buffer handle, or 0 for current buffer
/// @param ns_id Namespace to use or 0 to create a namespace,
/// or -1 for a ungrouped annotation
/// @param line Line to annotate with virtual text (zero-indexed)

12
src/nvim/api/ui.c
View File

@@ -29,8 +29,8 @@ typedef struct {
uint64_t channel_id;
Array buffer;
int hl_id; // current higlight for legacy put event
Integer cursor_row, cursor_col; // Intended visibule cursor position
int hl_id; // Current highlight for legacy put event.
Integer cursor_row, cursor_col; // Intended visible cursor position.
// Position of legacy cursor, used both for drawing and visible user cursor.
Integer client_row, client_col;
@@ -264,20 +264,22 @@ static void ui_set_option(UI *ui, bool init, String name, Object value,
///
/// On invalid grid handle, fails with error.
///
/// @param channel_id
/// @param grid The handle of the grid to be changed.
/// @param width The new requested width.
/// @param height The new requested height.
/// @param[out] err Error details, if any
void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width,
Integer height, Error *error)
Integer height, Error *err)
FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY
{
if (!pmap_has(uint64_t)(connected_uis, channel_id)) {
api_set_error(error, kErrorTypeException,
api_set_error(err, kErrorTypeException,
"UI not attached to channel: %" PRId64, channel_id);
return;
}
ui_grid_resize((handle_T)grid, (int)width, (int)height, error);
ui_grid_resize((handle_T)grid, (int)width, (int)height, err);
}
/// Pushes data into UI.UIData, to be consumed later by remote_ui_flush().

269
src/nvim/api/vim.c
View File

@@ -214,8 +214,8 @@ Integer nvim_input(String keys)
/// Send mouse event from GUI.
///
/// The call is non-blocking. It doesn't wait on any resulting action, but
/// queues the event to be processed soon by the event loop.
/// 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 calling it multiple times in a loop: the intermediate mouse
@@ -233,6 +233,7 @@ Integer nvim_input(String keys)
/// @param grid Grid number if the client uses |ui-multigrid|, else 0.
/// @param row Mouse row-position (zero-based, like redraw events)
/// @param col Mouse column-position (zero-based, like redraw events)
/// @param[out] err Error details, if any
void nvim_input_mouse(String button, String action, String modifier,
Integer grid, Integer row, Integer col, Error *err)
FUNC_API_SINCE(6) FUNC_API_ASYNC
@@ -756,9 +757,9 @@ void nvim_del_var(String name, Error *err)
/// @deprecated
/// @see nvim_set_var
/// @return Old value or nil if there was no previous value.
/// @warning May return nil if there was no previous value
/// OR if previous value was `v:null`.
/// @return Old value or nil if there was no previous value.
Object vim_set_var(String name, Object value, Error *err)
{
return dict_set_var(&globvardict, name, value, false, true, err);
@@ -806,6 +807,7 @@ Object nvim_get_option(String name, Error *err)
/// Sets an option value.
///
/// @param channel_id
/// @param name Option name
/// @param value New option value
/// @param[out] err Error details, if any
@@ -938,6 +940,7 @@ Window nvim_get_current_win(void)
/// Sets the current window.
///
/// @param window Window handle
/// @param[out] err Error details, if any
void nvim_set_current_win(Window window, Error *err)
FUNC_API_SINCE(1)
{
@@ -959,7 +962,7 @@ void nvim_set_current_win(Window window, Error *err)
/// Creates a new, empty, unnamed buffer.
///
/// @param listed Controls 'buflisted'
/// @param listed Sets 'buflisted'
/// @param scratch Creates a "throwaway" |scratch-buffer| for temporary work
/// (always 'nomodified')
/// @param[out] err Error details, if any
@@ -1002,37 +1005,6 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
///
/// Exactly one of `external` and `relative` must be specified.
///
/// @param buffer handle of buffer to be displayed in the window
/// @param enter whether the window should be entered (made the current window)
/// @param config Dictionary for the window configuration accepts these keys:
///
/// `relative`: If set, the window becomes a floating window. The window
/// will be placed with row,col coordinates relative to one of the
/// following:
/// "editor" the global editor grid
/// "win" a window. Use `win` to specify a window id,
/// or the current window will be used by default.
/// "cursor" the cursor position in current window.
/// `win`: When using relative='win', window id of the window where the
/// position is defined.
/// `anchor`: The corner of the float that the row,col position defines:
/// "NW" north-west (default)
/// "NE" north-east
/// "SW" south-west
/// "SE" south-east
/// `height`: window height (in character cells). Minimum of 1.
/// `width`: window width (in character cells). Minimum of 2.
/// `row`: row position. Screen cell height are used as unit. Can be
/// floating point.
/// `col`: column position. Screen cell width is used as unit. Can be
/// floating point.
/// `focusable`: Whether window can be focused by wincmds and
/// mouse events. Defaults to true. Even if set to false, the window
/// can still be entered using |nvim_set_current_win()| API call.
/// `external`: GUI should display the window as an external
/// top-level window. Currently accepts no other positioning
/// configuration together with this.
///
/// With editor positioning row=0, col=0 refers to the top-left corner of the
/// screen-grid and row=Lines-1, Columns-1 refers to the bottom-right corner.
/// Floating point values are allowed, but the builtin implementation (used by
@@ -1045,8 +1017,38 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
/// could let floats hover outside of the main window like a tooltip, but
/// this should not be used to specify arbitrary WM screen positions.
///
/// @param buffer handle of buffer to be displayed in the window
/// @param enter whether the window should be entered (made the current window)
/// @param config Dictionary for the window configuration accepts these keys:
/// - `relative`: If set, the window becomes a floating window. The window
/// will be placed with row,col coordinates relative to one of the
/// following:
/// - "editor" the global editor grid
/// - "win" a window. Use `win` to specify a window id,
/// or the current window will be used by default.
/// "cursor" the cursor position in current window.
/// - `win`: When using relative='win', window id of the window where the
/// position is defined.
/// - `anchor`: The corner of the float that the row,col position defines:
/// - "NW" north-west (default)
/// - "NE" north-east
/// - "SW" south-west
/// - "SE" south-east
/// - `height`: window height (in character cells). Minimum of 1.
/// - `width`: window width (in character cells). Minimum of 2.
/// - `row`: row position. Screen cell height are used as unit. Can be
/// floating point.
/// - `col`: column position. Screen cell width is used as unit. Can be
/// floating point.
/// - `focusable`: Whether window can be focused by wincmds and
/// mouse events. Defaults to true. Even if set to false, the window
/// can still be entered using |nvim_set_current_win()| API call.
/// - `external`: GUI should display the window as an external
/// top-level window. Currently accepts no other positioning
/// configuration together with this.
/// @param[out] err Error details, if any
/// @return the window handle or 0 when error
///
/// @return Window handle, or 0 on error
Window nvim_open_win(Buffer buffer, Boolean enter, Dictionary config,
Error *err)
FUNC_API_SINCE(6)
@@ -1273,47 +1275,48 @@ Array nvim_get_api_info(uint64_t channel_id)
return rv;
}
/// Identify the client for nvim. Can be called more than once, but subsequent
/// calls will remove earlier info, which should be resent if it is still
/// valid. (This could happen if a library first identifies the channel, and a
/// Identifies the client. Can be called more than once; subsequent calls
/// remove earlier info, which should be included by the caller if it is
/// still valid. (E.g. if a library first identifies the channel, then a
/// plugin using that library later overrides that info)
///
/// @param name short name for the connected client
/// @param version Dictionary describing the version, with the following
/// possible keys (all optional)
/// @param channel_id
/// @param name Short name for the connected client
/// @param version Dictionary describing the version, with these
/// (optional) keys:
/// - "major" major version (defaults to 0 if not set, for no release yet)
/// - "minor" minor version
/// - "patch" patch number
/// - "prerelease" string describing a prerelease, like "dev" or "beta1"
/// - "commit" hash or similar identifier of commit
/// @param type Must be one of the following values. A client library should
/// use "remote" if the library user hasn't specified other value.
/// - "remote" remote client that connected to nvim.
/// @param 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.
/// - "ui" gui frontend
/// - "embedder" application using nvim as a component, for instance
/// IDE/editor implementing a vim mode.
/// - "embedder" application using Nvim as a component (for example,
/// IDE/editor implementing a vim mode).
/// - "host" plugin host, typically started by nvim
/// - "plugin" single plugin, started by nvim
/// @param 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
/// the following (optional) keys:
/// these (optional) keys (more keys may be added in future
/// versions of Nvim, thus unknown keys are ignored. Clients
/// must only use keys defined in this or later versions of
/// Nvim):
/// - "async" if true, send as a notification. If false or unspecified,
/// use a blocking request
/// - "nargs" Number of arguments. Could be a single integer or an array
/// two integers, minimum and maximum inclusive.
/// Further keys might be added in later versions of nvim and unknown keys
/// are thus ignored. Clients must only use keys defined in this or later
/// versions of nvim!
/// of two integers, minimum and maximum inclusive.
///
/// @param attributes Informal attributes describing the client. Clients might
/// define their own keys, but the following are suggested:
/// - "website" Website of client (for instance github repository)
/// - "license" Informal description of the license, such as "Apache 2",
/// "GPLv3" or "MIT"
/// - "logo" URI or path to image, preferably small logo or icon.
/// .png or .svg format is preferred.
/// @param attributes Arbitrary string:string map of informal client properties.
/// Suggested keys:
/// - "website": Client homepage URL (e.g. GitHub repository)
/// - "license": License description ("Apache 2", "GPLv3", "MIT", …)
/// - "logo": URI or path to image, preferably small logo or icon.
/// .png or .svg format is preferred.
///
/// @param[out] err Error details, if any
void nvim_set_client_info(uint64_t channel_id, String name,
Dictionary version, String type,
Dictionary methods, Dictionary attributes,
@@ -1345,15 +1348,14 @@ void nvim_set_client_info(uint64_t channel_id, String name,
/// Get information about a channel.
///
/// @returns a Dictionary, describing a channel with the
/// following keys:
/// - "stream" the stream underlying the channel
/// @returns Dictionary describing a channel, with these keys:
/// - "stream" the stream underlying the channel
/// - "stdio" stdin and stdout of this Nvim instance
/// - "stderr" stderr of this Nvim instance
/// - "socket" TCP/IP socket or named pipe
/// - "job" job with communication over its stdio
/// - "mode" how data received on the channel is interpreted
/// - "bytes" send and recieve raw bytes
/// - "bytes" send and receive raw bytes
/// - "terminal" a |terminal| instance interprets ASCII sequences
/// - "rpc" |RPC| communication on the channel is active
/// - "pty" Name of pseudoterminal, if one is used (optional).
@@ -1394,13 +1396,13 @@ Array nvim_list_chans(void)
/// processing which have such side-effects, e.g. |:sleep| may wake timers).
/// 2. To minimize RPC overhead (roundtrips) of a sequence of many requests.
///
/// @param channel_id
/// @param calls an array of calls, where each call is described by an array
/// with two elements: the request name, and an array of arguments.
/// @param[out] err Details of a validation error of the nvim_multi_request call
/// itself, i.e. malformed `calls` parameter. Errors from called methods will
/// be indicated in the return value, see below.
/// with two elements: the request name, and an array of arguments.
/// @param[out] err Validation error details (malformed `calls` parameter),
/// if any. Errors from batched calls are given in the return value.
///
/// @return an array with two elements. The first is an array of return
/// @return Array of two elements. The first is an array of return
/// values. The second is NIL if all calls succeeded. If a call resulted in
/// an error, it is a three-element array with the zero-based index of the call
/// which resulted in an error, the error type and the error message. If an
@@ -1491,9 +1493,8 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
/// Parse a VimL expression.
///
/// @param[in] expr Expression to parse. Is always treated as a single line.
/// @param[in] flags Flags:
///
/// @param[in] expr Expression to parse. Always treated as a single line.
/// @param[in] 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
@@ -1501,7 +1502,6 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
/// operator/space, though also yielding an error).
/// - "l" when needing to start parsing with lvalues for
/// ":let" or ":for".
///
/// Common flag sets:
/// - "m" to parse like for ":echo".
/// - "E" to parse like for "<C-r>=".
@@ -1514,63 +1514,57 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
/// starting column and ending column (latter exclusive:
/// one should highlight region [start_col, end_col)).
///
/// @return AST: top-level dictionary with these keys:
///
/// "error": Dictionary with error, present only if parser saw some
/// error. Contains the following keys:
///
/// "message": String, error message in printf format, translated.
/// Must contain exactly one "%.*s".
/// "arg": String, error message argument.
///
/// "len": Amount of bytes successfully parsed. With flags equal to ""
/// that should be equal to the length of expr string.
///
/// @note: “Sucessfully parsed” here means “participated in AST
/// creation”, not “till the first error”.
///
/// "ast": AST, either nil or a dictionary with these keys:
///
/// "type": node type, one of the value names from ExprASTNodeType
/// 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.
/// "len": “length” of the node. This and "start" are there for
/// debugging purposes primary (debugging parser and providing
/// debug information).
/// "children": a list of nodes described in top/"ast". There always
/// is zero, one or two children, key will not be present
/// if node has no children. Maximum number of children
/// may be found in node_maxchildren array.
///
/// Local values (present only for certain nodes):
///
/// "scope": a single Integer, specifies scope for "Option" and
/// "PlainIdentifier" nodes. For "Option" it is one of
/// ExprOptScope values, for "PlainIdentifier" it is one of
/// ExprVarScope values.
/// "ident": identifier (without scope, if any), present for "Option",
/// "PlainIdentifier", "PlainKey" and "Environment" nodes.
/// "name": Integer, register name (one character) or -1. Only present
/// for "Register" nodes.
/// "cmp_type": String, comparison type, one of the value names from
/// ExprComparisonType, stringified without "kExprCmp"
/// prefix. Only present for "Comparison" nodes.
/// "ccs_strategy": String, case comparison strategy, one of the
/// value names from ExprCaseCompareStrategy,
/// stringified without "kCCStrategy" prefix. Only
/// present for "Comparison" nodes.
/// "augmentation": String, augmentation type for "Assignment" nodes.
/// Is either an empty string, "Add", "Subtract" or
/// "Concat" for "=", "+=", "-=" or ".=" respectively.
/// "invert": Boolean, true if result of comparison needs to be
/// inverted. Only present for "Comparison" nodes.
/// "ivalue": Integer, integer value for "Integer" nodes.
/// "fvalue": Float, floating-point value for "Float" nodes.
/// "svalue": String, value for "SingleQuotedString" and
/// "DoubleQuotedString" nodes.
/// @return
/// - AST: top-level dictionary with these keys:
/// - "error": Dictionary with error, present only if parser saw some
/// error. Contains the following keys:
/// - "message": String, error message in printf format, translated.
/// Must contain exactly one "%.*s".
/// - "arg": String, error message argument.
/// - "len": Amount of bytes successfully parsed. With flags equal to ""
/// that should be equal to the length of expr string.
/// (“Sucessfully parsed” here means “participated in AST
/// creation”, not “till the first error”.)
/// - "ast": AST, either nil or a dictionary with these keys:
/// - "type": node type, one of the value names from ExprASTNodeType
/// 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.
/// - "len": “length” of the node. This and "start" are there for
/// debugging purposes primary (debugging parser and providing
/// debug information).
/// - "children": a list of nodes described in top/"ast". There always
/// is zero, one or two children, key will not be present
/// if node has no children. Maximum number of children
/// may be found in node_maxchildren array.
/// - Local values (present only for certain nodes):
/// - "scope": a single Integer, specifies scope for "Option" and
/// "PlainIdentifier" nodes. For "Option" it is one of
/// ExprOptScope values, for "PlainIdentifier" it is one of
/// ExprVarScope values.
/// - "ident": identifier (without scope, if any), present for "Option",
/// "PlainIdentifier", "PlainKey" and "Environment" nodes.
/// - "name": Integer, register name (one character) or -1. Only present
/// for "Register" nodes.
/// - "cmp_type": String, comparison type, one of the value names from
/// ExprComparisonType, stringified without "kExprCmp"
/// prefix. Only present for "Comparison" nodes.
/// - "ccs_strategy": String, case comparison strategy, one of the
/// value names from ExprCaseCompareStrategy,
/// stringified without "kCCStrategy" prefix. Only
/// present for "Comparison" nodes.
/// - "augmentation": String, augmentation type for "Assignment" nodes.
/// Is either an empty string, "Add", "Subtract" or
/// "Concat" for "=", "+=", "-=" or ".=" respectively.
/// - "invert": Boolean, true if result of comparison needs to be
/// inverted. Only present for "Comparison" nodes.
/// - "ivalue": Integer, integer value for "Integer" nodes.
/// - "fvalue": Float, floating-point value for "Float" nodes.
/// - "svalue": String, value for "SingleQuotedString" and
/// "DoubleQuotedString" nodes.
/// @param[out] err Error details, if any
Dictionary nvim_parse_expression(String expr, String flags, Boolean highlight,
Error *err)
FUNC_API_SINCE(4) FUNC_API_ASYNC
@@ -2035,15 +2029,13 @@ Dictionary nvim__stats(void)
/// Gets a list of dictionaries representing attached UIs.
///
/// @return Array of UI dictionaries
///
/// Each dictionary has the following keys:
/// - "height" requested height of the UI
/// - "width" requested width of the UI
/// - "rgb" whether the UI uses rgb colors (false implies cterm colors)
/// - "ext_..." Requested UI extensions, see |ui-options|
/// - "chan" Channel id of remote UI (not present for TUI)
///
/// @return
/// Array of UI dictionaries, each with these keys:
/// - "height" requested height of the UI
/// - "width" requested width of the UI
/// - "rgb" whether the UI uses rgb colors (false implies cterm colors)
/// - "ext_..." Requested UI extensions, see |ui-options|
/// - "chan" Channel id of remote UI (not present for TUI)
Array nvim_list_uis(void)
FUNC_API_SINCE(4)
{
@@ -2146,6 +2138,7 @@ Object nvim_get_proc(Integer pid, Error *err)
/// @param finish Finish the completion and dismiss the popupmenu. Implies
/// `insert`.
/// @param opts Optional parameters. Reserved for future use.
/// @param[out] err Error details, if any
void nvim_select_popupmenu_item(Integer item, Boolean insert, Boolean finish,
Dictionary opts, Error *err)
FUNC_API_SINCE(6)

3
src/nvim/api/window.c
View File

@@ -345,6 +345,7 @@ Object nvim_win_get_option(Window window, String name, Error *err)
/// Sets a window option value. Passing 'nil' as value deletes the option(only
/// works if there's a global fallback)
///
/// @param channel_id
/// @param window Window handle
/// @param name Option name
/// @param value Option value
@@ -527,9 +528,7 @@ Dictionary nvim_win_get_config(Window window, Error *err)
/// @param force Behave like `:close!` The last window of a buffer with
/// unwritten changes can be closed. The buffer will become
/// hidden, even if 'hidden' is not set.
///
/// @param[out] err Error details, if any
/// @return Window number
void nvim_win_close(Window window, Boolean force, Error *err)
FUNC_API_SINCE(6)
{