diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 175 |
1 files changed, 92 insertions, 83 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index ed6e4905b4..3d95dd58f7 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -670,38 +670,39 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* current window) {config} Dictionary for the window configuration accepts these keys: - - `relative` : If set, the window becomes a floating + • `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 + • "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. + used by default. + • "cursor" the cursor position in current + window. - - `win` : When using relative='win', window id + • `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 + • `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 + • "NW" north-west (default) + • "NE" north-east + • "SW" south-west + • "SE" south-east - - `height` : window height (in character cells). + • `height` : window height (in character cells). Minimum of 1. - - `width` : window width (in character cells). + • `width` : window width (in character cells). Minimum of 1. - - `row` : row position. Screen cell height are + • `row` : row position. Screen cell height are used as unit. Can be floating point. - - `col` : column position. Screen cell width is + • `col` : column position. Screen cell width is used as unit. Can be floating point. - - `focusable` : Whether window can be focused by + • `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 + • `external` : GUI should display the window as an external top-level window. Currently accepts no other positioning configuration together with this. @@ -869,35 +870,43 @@ nvim_get_api_info() *nvim_get_api_info()* *nvim_set_client_info()* nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) - 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) + Self-identifies the client. + + The client/plugin/application should call this after + connecting, to provide hints about its identity and purpose, + for debugging and orchestration. + + Can be called more than once; the caller should merge old info + if 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 fields. Parameters: ~ {name} Short name for the connected client {version} Dictionary describing the version, with these (optional) keys: - - "major" major version (defaults to 0 if + • "major" major version (defaults to 0 if not set, for no release yet) - - "minor" minor version - - "patch" patch number - - "prerelease" string describing a + • "minor" minor version + • "patch" patch number + • "prerelease" string describing a prerelease, like "dev" or "beta1" - - "commit" hash or similar identifier of + • "commit" hash or similar identifier of commit {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 + • "remote" remote client connected to Nvim. + • "ui" gui frontend + • "embedder" application using Nvim as a component (for example, IDE/editor implementing a vim mode). - - "host" plugin host, typically started by + • "host" plugin host, typically started by nvim - - "plugin" single plugin, started by nvim + • "plugin" single plugin, started by nvim {methods} Builtin methods in the client. For a host, this does not include plugin methods which will be discovered later. The key should be @@ -907,19 +916,19 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, unknown keys are ignored. Clients must only use keys defined in this or later versions of Nvim): - - "async" if true, send as a notification. + • "async" if true, send as a notification. If false or unspecified, use a blocking request - - "nargs" Number of arguments. Could be a + • "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 properties. Suggested keys: - - "website": Client homepage URL (e.g. + • "website": Client homepage URL (e.g. GitHub repository) - - "license": License description ("Apache + • "license": License description ("Apache 2", "GPLv3", "MIT", …) - - "logo": URI or path to image, preferably + • "logo": URI or path to image, preferably small logo or icon. .png or .svg format is preferred. @@ -928,26 +937,26 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* Return: ~ 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 receive raw bytes - - "terminal" a |terminal| instance interprets ASCII + • "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 receive raw bytes + • "terminal" a |terminal| instance interprets ASCII sequences - - "rpc" |RPC| communication on the channel is active + • "rpc" |RPC| communication on the channel is active - - "pty" Name of pseudoterminal, if one is used (optional). + • "pty" Name of pseudoterminal, if one is used (optional). On a POSIX system, this will be a device path like /dev/pts/1. Even if the name is unknown, the key will still be present to indicate a pty is used. This is currently the case when using winpty on windows. - - "buffer" buffer with connected |terminal| instance + • "buffer" buffer with connected |terminal| instance (optional) - - "client" information about the client on the other end + • "client" information about the client on the other end of the RPC channel, if it has added it using |nvim_set_client_info()|. (optional) @@ -995,21 +1004,21 @@ nvim_parse_expression({expr}, {flags}, {highlight}) {expr} Expression to parse. Always treated as a single line. {flags} Flags: - - "m" if multiple expressions in a row are + • "m" if multiple expressions in a row are allowed (only the first one will be parsed), - - "E" if EOC tokens are not allowed + • "E" if EOC tokens are not allowed (determines whether they will stop parsing process or be recognized as an operator/space, though also yielding an error). - - "l" when needing to start parsing with + • "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>=". - - empty string for ":call". - - "lm" to parse for ":let". + • "m" to parse like for ":echo". + • "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 containing array of 4-tuples (arrays) (Integer, Integer, Integer, String), @@ -1021,64 +1030,64 @@ nvim_parse_expression({expr}, {flags}, {highlight}) Return: ~ - - AST: top-level dictionary with these keys: - - "error": Dictionary with error, present only if parser + • 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, + • "message": String, error message in printf format, translated. Must contain exactly one "%.*s". - - "arg": String, error message argument. + • "arg": String, error message argument. - - "len": Amount of bytes successfully parsed. With flags + • "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 + • "ast": AST, either nil or a dictionary with these keys: - - "type": node type, one of the value names from + • "type": node type, one of the value names from ExprASTNodeType stringified without "kExprNode" prefix. - - "start": a pair [line, column] describing where node + • "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 + • "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". + • "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 + • 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 + • "ident": identifier (without scope, if any), present for "Option", "PlainIdentifier", "PlainKey" and "Environment" nodes. - - "name": Integer, register name (one character) or -1. + • "name": Integer, register name (one character) or -1. Only present for "Register" nodes. - - "cmp_type": String, comparison type, one of the value + • "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 + • "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 + • "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 + • "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" + • "ivalue": Integer, integer value for "Integer" nodes. + • "fvalue": Float, floating-point value for "Float" nodes. - - "svalue": String, value for "SingleQuotedString" and + • "svalue": String, value for "SingleQuotedString" and "DoubleQuotedString" nodes. nvim__id({obj}) *nvim__id()* @@ -1140,12 +1149,12 @@ nvim_list_uis() *nvim_list_uis()* Return: ~ Array of UI dictionaries, each with these keys: - - "height" Requested height of the UI - - "width" Requested width of the UI - - "rgb" true if the UI uses RGB colors (false implies + • "height" Requested height of the UI + • "width" Requested width of the UI + • "rgb" true if the UI uses RGB colors (false implies |cterm-colors|) - - "ext_..." Requested UI extensions, see |ui-option| - - "chan" Channel id of remote UI (not present for TUI) + • "ext_..." Requested UI extensions, see |ui-option| + • "chan" Channel id of remote UI (not present for TUI) nvim_get_proc_children({pid}) *nvim_get_proc_children()* Gets the immediate children of process `pid` . |