diff options
Diffstat (limited to 'runtime/doc')
49 files changed, 6966 insertions, 3731 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index ba3b7c0915..87269ad147 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -579,7 +579,7 @@ created for extmark changes. ============================================================================== Global Functions *api-global* -nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* +nvim__get_runtime({pat}, {all}, {opts}) *nvim__get_runtime()* Find files in runtime directories Attributes: ~ @@ -700,6 +700,21 @@ nvim_chan_send({chan}, {data}) *nvim_chan_send()* • {chan} id of the channel • {data} data to write. 8-bit clean: can contain NUL bytes. +nvim_complete_set({index}, {opts}) *nvim_complete_set()* + Set info for the completion candidate index. if the info was shown in a + window, then the window and buffer ids are returned for further + customization. If the text was not shown, an empty dict is returned. + + Parameters: ~ + • {index} the completion candidate index + • {opts} Optional parameters. + • info: (string) info text. + + Return: ~ + Dictionary containing these keys: + • winid: (number) floating window id + • bufnr: (number) buffer id in floating window + nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* Creates a new, empty, unnamed buffer. @@ -751,13 +766,13 @@ nvim_del_var({name}) *nvim_del_var()* Parameters: ~ • {name} Variable name -nvim_echo({chunks}, {history}, {*opts}) *nvim_echo()* +nvim_echo({chunks}, {history}, {opts}) *nvim_echo()* Echo a message. Parameters: ~ - • {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. + • {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. • verbose: Message was printed as a result of 'verbose' @@ -782,7 +797,7 @@ nvim_err_writeln({str}) *nvim_err_writeln()* See also: ~ • nvim_err_write() -nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* +nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()* Evaluates statusline string. Attributes: ~ @@ -863,16 +878,19 @@ nvim_get_api_info() *nvim_get_api_info()* Returns a 2-tuple (Array), where item 0 is the current channel id and item 1 is the |api-metadata| map (Dictionary). - Return: ~ - 2-tuple [{channel-id}, {api-metadata}] - Attributes: ~ |api-fast| |RPC| only + Return: ~ + 2-tuple `[{channel-id}, {api-metadata}]` + nvim_get_chan_info({chan}) *nvim_get_chan_info()* Gets information about a channel. + Parameters: ~ + • {chan} channel_id, or 0 for current channel + Return: ~ Dictionary describing a channel, with these keys: • "id" Channel id. @@ -882,12 +900,10 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* • "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" |terminal| instance interprets ASCII sequences. • "rpc" |RPC| communication on the channel is active. - • "pty" (optional) Name of pseudoterminal. On a POSIX system this is a device path like "/dev/pts/1". If the name is unknown, the key will still be present if a pty is used (e.g. for conpty on Windows). @@ -919,7 +935,7 @@ nvim_get_color_map() *nvim_get_color_map()* Return: ~ Map of color names and RGB values. -nvim_get_context({*opts}) *nvim_get_context()* +nvim_get_context({opts}) *nvim_get_context()* Gets a map of the current editor state. Parameters: ~ @@ -954,7 +970,7 @@ nvim_get_current_win() *nvim_get_current_win()* Return: ~ Window handle -nvim_get_hl({ns_id}, {*opts}) *nvim_get_hl()* +nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()* Gets all or specific highlight groups in a namespace. Note: ~ @@ -983,7 +999,7 @@ nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* similar to |hlID()|, but allocates a new ID if not present. -nvim_get_hl_ns({*opts}) *nvim_get_hl_ns()* +nvim_get_hl_ns({opts}) *nvim_get_hl_ns()* Gets the active highlight namespace. Parameters: ~ @@ -1032,12 +1048,12 @@ nvim_get_mode() *nvim_get_mode()* Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for input. - Return: ~ - Dictionary { "mode": String, "blocking": Boolean } - Attributes: ~ |api-fast| + Return: ~ + Dictionary { "mode": String, "blocking": Boolean } + nvim_get_proc({pid}) *nvim_get_proc()* Gets info describing process `pid`. @@ -1099,7 +1115,7 @@ nvim_input({keys}) *nvim_input()* • |keycodes| like <CR> are translated, so "<" is special. To input a literal "<", send <LT>. • For mouse events use |nvim_input_mouse()|. The pseudokey form - "<LeftMouse><col,row>" is deprecated since |api-level| 6. + `<LeftMouse><col,row>` is deprecated since |api-level| 6. Attributes: ~ |api-fast| @@ -1122,7 +1138,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) • Currently this doesn't support "scripting" multiple mouse events by calling it multiple times in a loop: the intermediate mouse positions will be ignored. It should be used to implement real-time mouse input - in a GUI. The deprecated pseudokey form ("<LeftMouse><col,row>") of + in a GUI. The deprecated pseudokey form (`<LeftMouse><col,row>`) of |nvim_input()| has the same limitation. Attributes: ~ @@ -1130,7 +1146,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) Parameters: ~ • {button} Mouse button: one of "left", "right", "middle", "wheel", - "move". + "move", "x1", "x2". • {action} For ordinary buttons, one of "press", "drag", "release". For the wheel, one of "up", "down", "left", "right". Ignored for "move". @@ -1230,7 +1246,9 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* 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 - callback however. ["input", term, bufnr, data] + callback however. `["input", term, bufnr, data]` + • force_crlf: (boolean, default true) Convert "\n" to + "\r\n". Return: ~ Channel id, or 0 on error @@ -1260,13 +1278,13 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* • {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: + "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) • 3: ends the paste (exactly once) Return: ~ - • true: Client may continue pasting. • false: Client must cancel the paste. @@ -1429,20 +1447,20 @@ 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()* Sets a highlight group. Note: ~ - • Unlike the `:highlight` command which can update a highlight group, this - function completely replaces the definition. For example: + • Unlike the `:highlight` command which can update a highlight group, + this function completely replaces the definition. For example: `nvim_set_hl(0, 'Visual', {})` will clear the highlight group 'Visual'. - • The fg and bg keys also accept the string values `"fg"` or `"bg"` which - act as aliases to the corresponding foreground and background values - of the Normal group. If the Normal group has not been defined, using - these values results in an error. - • If `link` is used in combination with other attributes; only the `link` - will take effect (see |:hi-link|). + • The fg and bg keys also accept the string values `"fg"` or `"bg"` + which act as aliases to the corresponding foreground and background + values of the Normal group. If the Normal group has not been defined, + using these values results in an error. + • If `link` is used in combination with other attributes; only the + `link` will take effect (see |:hi-link|). Parameters: ~ • {ns_id} Namespace id for this highlight |nvim_create_namespace()|. @@ -1452,9 +1470,9 @@ nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* activate them. • {name} Highlight group name, e.g. "ErrorMsg" • {val} Highlight definition map, accepts the following keys: - • fg (or foreground): color name or "#RRGGBB", see note. - • bg (or background): color name or "#RRGGBB", see note. - • sp (or special): color name or "#RRGGBB" + • fg: color name or "#RRGGBB", see note. + • bg: color name or "#RRGGBB", see note. + • sp: color name or "#RRGGBB" • blend: integer between 0 and 100 • bold: boolean • standout: boolean @@ -1499,13 +1517,13 @@ nvim_set_hl_ns_fast({ns_id}) *nvim_set_hl_ns_fast()* Parameters: ~ • {ns_id} the namespace to activate -nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* +nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* Sets a global |mapping| for the given mode. To set a buffer-local mapping, use |nvim_buf_set_keymap()|. Unlike |:map|, leading/trailing whitespace is accepted as part of the - {lhs} or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual. + {lhs} or {rhs}. Empty {rhs} is <Nop>. |keycodes| are replaced as usual. Example: >vim call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true}) @@ -1516,14 +1534,14 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* < Parameters: ~ - • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or - "!" for |:map!|, or empty string for |:map|. "ia", "ca" or + • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) + or "!" for |:map!|, or empty string for |:map|. "ia", "ca" or "!a" for abbreviation in Insert mode, Cmdline mode, or both, respectively • {lhs} Left-hand-side |{lhs}| of the mapping. • {rhs} Right-hand-side |{rhs}| of the mapping. • {opts} Optional parameters map: Accepts all |:map-arguments| as keys - except |<buffer>|, values are booleans (default false). Also: + except <buffer>, values are booleans (default false). Also: • "noremap" disables |recursive_mapping|, like |:noremap| • "desc" human-readable description. • "callback" Lua function called in place of {rhs}. @@ -1630,7 +1648,7 @@ nvim_eval({expr}) *nvim_eval()* Return: ~ Evaluation result or expanded object -nvim_exec2({src}, {*opts}) *nvim_exec2()* +nvim_exec2({src}, {opts}) *nvim_exec2()* Executes Vimscript (multiline block of Ex commands), like anonymous |:source|. @@ -1671,8 +1689,8 @@ nvim_parse_expression({expr}, {flags}, {highlight}) 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>=". + • "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 @@ -1683,22 +1701,20 @@ nvim_parse_expression({expr}, {flags}, {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. (“Successfully - parsed” here means “participated in AST creation”, not “till the - first error”.) + that should be equal to the length of expr string. ("Successfully + 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 + • "start": a pair `[line, column]` describing where node is "started" where "line" is always 0 (will not be 0 if you will be using this API on e.g. ":let", but that is not present yet). Both elements are Integers. @@ -1709,7 +1725,6 @@ nvim_parse_expression({expr}, {flags}, {highlight}) 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 @@ -1739,11 +1754,11 @@ nvim_parse_expression({expr}, {flags}, {highlight}) Command Functions *api-command* *nvim_buf_create_user_command()* -nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts}) +nvim_buf_create_user_command({buffer}, {name}, {command}, {opts}) Creates a buffer-local command |user-commands|. Parameters: ~ - • {buffer} Buffer handle, or 0 for current buffer. + • {buffer} Buffer handle, or 0 for current buffer. See also: ~ • nvim_create_user_command @@ -1759,7 +1774,7 @@ nvim_buf_del_user_command({buffer}, {name}) • {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()* +nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* Gets a map of buffer-local |user-commands|. Parameters: ~ @@ -1769,7 +1784,7 @@ nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* Return: ~ Map of maps describing commands. -nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* +nvim_cmd({cmd}, {opts}) *nvim_cmd()* Executes an Ex command. Unlike |nvim_command()| this command takes a structured Dictionary instead @@ -1804,7 +1819,7 @@ nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* • |nvim_command()| *nvim_create_user_command()* -nvim_create_user_command({name}, {command}, {*opts}) +nvim_create_user_command({name}, {command}, {opts}) Creates a global |user-commands| command. For Lua usage see |lua-guide-commands-create|. @@ -1824,22 +1839,21 @@ nvim_create_user_command({name}, {command}, {*opts}) argument that contains the following keys: • name: (string) Command name • args: (string) The args passed to the command, if any - |<args>| + <args> • fargs: (table) The args split by unescaped whitespace - (when more than one argument is allowed), if any - |<f-args>| + (when more than one argument is allowed), if any <f-args> • nargs: (string) Number of arguments |:command-nargs| • bang: (boolean) "true" if the command was executed with a - ! modifier |<bang>| + ! modifier <bang> • line1: (number) The starting line of the command range - |<line1>| + <line1> • line2: (number) The final line of the command range - |<line2>| + <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>| + 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> • smods: (table) Command modifiers in a structured format. Has the same structure as the "mods" key of |nvim_parse_cmd()|. @@ -1864,7 +1878,7 @@ nvim_del_user_command({name}) *nvim_del_user_command()* Parameters: ~ • {name} Name of the command to delete. -nvim_get_commands({*opts}) *nvim_get_commands()* +nvim_get_commands({opts}) *nvim_get_commands()* Gets a map of global (non-buffer-local) Ex commands. Currently only |user-commands| are supported, not builtin Ex commands. @@ -1893,16 +1907,15 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* Return: ~ Dictionary containing command information, with these keys: • cmd: (string) Command name. - • range: (array) (optional) Command range (|<line1>| |<line2>|). - Omitted if command doesn't accept a range. Otherwise, has no - elements if no range was specified, one element if only a single - range item was specified, or two elements if both range items were - specified. - • count: (number) (optional) Command |<count>|. Omitted if command + • range: (array) (optional) Command range (<line1> <line2>). Omitted + if command doesn't accept a range. Otherwise, has no elements if no + range was specified, one element if only a single range item was + specified, or two elements if both range items were specified. + • count: (number) (optional) Command <count>. Omitted if command cannot take a count. - • reg: (string) (optional) Command |<register>|. Omitted if command + • reg: (string) (optional) Command <register>. Omitted if command cannot take a register. - • bang: (boolean) Whether command contains a |<bang>| (!) modifier. + • bang: (boolean) Whether command contains a <bang> (!) modifier. • args: (array) Command arguments. • addr: (string) Value of |:command-addr|. Uses short name or "line" for -addr=lines. @@ -1916,13 +1929,11 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* • bar: (boolean) The "|" character is treated as a command separator and the double quote character (") is treated as the start of a comment. - • mods: (dictionary) |:command-modifiers|. • filter: (dictionary) |:filter|. • pattern: (string) Filter pattern. Empty string if there is no filter. • force: (boolean) Whether filter is inverted or not. - • silent: (boolean) |:silent|. • emsg_silent: (boolean) |:silent!|. • unsilent: (boolean) |:unsilent|. @@ -1965,7 +1976,7 @@ nvim_get_all_options_info() *nvim_get_all_options_info()* See also: ~ • |nvim_get_commands()| -nvim_get_option_info2({name}, {*opts}) *nvim_get_option_info2()* +nvim_get_option_info2({name}, {opts}) *nvim_get_option_info2()* Gets the option information for one option from arbitrary buffer or window Resulting dictionary has keys: @@ -1999,7 +2010,7 @@ nvim_get_option_info2({name}, {*opts}) *nvim_get_option_info2()* Return: ~ Option Information -nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* +nvim_get_option_value({name}, {opts}) *nvim_get_option_value()* Gets the value of an option. The behavior of this function matches that of |:set|: the local value of an option is returned if it exists; otherwise, the global value is returned. Local values always correspond to the @@ -2022,7 +2033,7 @@ nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* Option value *nvim_set_option_value()* -nvim_set_option_value({name}, {value}, {*opts}) +nvim_set_option_value({name}, {value}, {opts}) Sets the value of an option. The behavior of this function matches that of |:set|: for global-local options, both the global and local value are set unless otherwise specified with {scope}. @@ -2048,15 +2059,15 @@ For more information on buffers, see |buffers|. Unloaded Buffers: ~ Buffers may be unloaded by the |:bunload| command or the buffer's -|'bufhidden'| option. When a buffer is unloaded its file contents are -freed from memory and vim cannot operate on the buffer lines until it is -reloaded (usually by opening the buffer again in a new window). API -methods such as |nvim_buf_get_lines()| and |nvim_buf_line_count()| will be -affected. +|'bufhidden'| option. When a buffer is unloaded its file contents are freed +from memory and vim cannot operate on the buffer lines until it is reloaded +(usually by opening the buffer again in a new window). API methods such as +|nvim_buf_get_lines()| and |nvim_buf_line_count()| will be affected. You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check whether a buffer is loaded. + nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua callbacks. @@ -2078,7 +2089,8 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* will be `nvim_buf_changedtick_event`. Not for Lua callbacks. • {opts} Optional parameters. - • on_lines: Lua callback invoked on change. Return `true` to detach. Args: + • on_lines: Lua callback invoked on change. Return a + truthy value (not `false` or `nil`) to detach. Args: • the string "lines" • buffer handle • b:changedtick @@ -2088,10 +2100,10 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • byte count of previous contents • deleted_codepoints (if `utf_sizes` is true) • deleted_codeunits (if `utf_sizes` is true) - • on_bytes: Lua callback invoked on change. This callback receives more granular information about the - change compared to on_lines. Return `true` to detach. Args: + change compared to on_lines. Return a truthy value + (not `false` or `nil`) to detach. Args: • the string "bytes" • buffer handle • b:changedtick @@ -2099,28 +2111,28 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • start column of the changed text • byte offset of the changed text (from the start of the buffer) - • old end row of the changed text - • old end column of the changed text + • old end row of the changed text (offset from start + row) + • old end column of the changed text (if old end row + = 0, offset from start column) • old end byte length of the changed text - • new end row of the changed text - • new end column of the changed text + • new end row of the changed text (offset from start + row) + • new end column of the changed text (if new end row + = 0, offset from start column) • new end byte length of the changed text - • on_changedtick: Lua callback invoked on changedtick increment without text change. Args: • the string "changedtick" • buffer handle • b:changedtick - • on_detach: Lua callback invoked on detach. Args: • the string "detach" • buffer handle - • on_reload: Lua callback invoked on reload. The entire buffer content should be considered changed. Args: • the string "reload" • buffer handle - • utf_sizes: include UTF-32 and UTF-16 size of the replaced region, as args to `on_lines`. • preview: also attach to command preview (i.e. @@ -2156,8 +2168,7 @@ nvim_buf_call({buffer}, {fun}) *nvim_buf_call()* only) Return: ~ - Return value of function. NB: will deepcopy Lua values currently, use - upvalues to send Lua references in and out. + Return value of function. nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* Unmaps a buffer-local |mapping| for the given mode. @@ -2235,8 +2246,8 @@ nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Gets a list of buffer-local |mapping| definitions. Parameters: ~ - • {mode} Mode short-name ("n", "i", "v", ...) • {buffer} Buffer handle, or 0 for current buffer + • {mode} Mode short-name ("n", "i", "v", ...) Return: ~ Array of |maparg()|-like dictionaries describing mappings. The @@ -2375,7 +2386,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Line count, or 0 for unloaded buffer. |api-buffer| *nvim_buf_set_keymap()* -nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {*opts}) +nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) Sets a buffer-local |mapping| for the given mode. Parameters: ~ @@ -2454,9 +2465,9 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, Indexing is zero-based. Row indices are end-inclusive, and column indices are end-exclusive. - To insert text at a given `(row, column)` location, use `start_row = - end_row = row` and `start_col = end_col = col`. To delete the text in a - range, use `replacement = {}`. + To insert text at a given `(row, column)` location, use + `start_row = end_row = row` and `start_col = end_col = col`. To delete the + text in a range, use `replacement = {}`. Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire lines. @@ -2569,9 +2580,9 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) 0-indexed (row, col) tuple or empty list () if extmark id was absent *nvim_buf_get_extmarks()* -nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts}) - Gets |extmarks| (including |signs|) in "traversal order" from a |charwise| - region defined by buffer positions (inclusive, 0-indexed |api-indexing|). +nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) + Gets |extmarks| in "traversal order" from a |charwise| region defined by + buffer positions (inclusive, 0-indexed |api-indexing|). Region can be given as (row,col) tuples, or valid extmark ids (whose positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) @@ -2587,6 +2598,10 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts}) the `overlap` option might be useful. Otherwise only the start position of an extmark will be considered. + Note: legacy signs placed through the |:sign| commands are implemented as + extmarks and will show up here. Their details array will contain a + `sign_name` field. + Example: >lua local api = vim.api local pos = api.nvim_win_get_cursor(0) @@ -2622,10 +2637,10 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts}) "virt_text" and "virt_lines" Return: ~ - List of [extmark_id, row, col] tuples in "traversal order". + List of `[extmark_id, row, col]` tuples in "traversal order". *nvim_buf_set_extmark()* -nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) +nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) Creates or updates an |extmark|. By default a new extmark is created when no id is passed in, but it is @@ -2657,7 +2672,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) EOL of a line, continue the highlight for the rest of the screen line (just like for diff and cursorline highlight). • virt_text : virtual text to link to this mark. A list of - [text, highlight] tuples, each representing a text chunk + `[text, highlight]` tuples, each representing a text chunk with specified highlight. `highlight` element can either be a single highlight group, or an array of multiple highlight groups that will be stacked (highest priority @@ -2671,7 +2686,6 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) • "right_align": display right aligned in the window. • "inline": display at the specified column, and shift the buffer text to the right as needed. - • virt_text_win_col : position the virtual text at a fixed window column (starting from the first text column of the screen line) instead of "virt_text_pos". @@ -2679,6 +2693,8 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) text is selected or hidden because of scrolling with 'nowrap' or 'smoothscroll'. Currently only affects "overlay" virt_text. + • virt_text_repeat_linebreak : repeat the virtual text on + wrapped lines. • hl_mode : control how highlights are combined with the highlights of the text. Currently only affects virt_text highlights, but might affect `hl_group` in later versions. @@ -2687,16 +2703,16 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) • "combine": combine with background text color. • "blend": blend with background text color. Not supported for "inline" virt_text. - • virt_lines : virtual lines to add next to this mark This should be an array over lines, where each line in turn is - an array over [text, highlight] tuples. In general, buffer - and window options do not affect the display of the text. - In particular 'wrap' and 'linebreak' options do not take - effect, so the number of extra screen lines will always - match the size of the array. However the 'tabstop' buffer - option is still used for hard tabs. By default lines are - placed below the buffer line containing the mark. + an array over `[text, highlight]` tuples. In general, + buffer and window options do not affect the display of the + text. In particular 'wrap' and 'linebreak' options do not + take effect, so the number of extra screen lines will + always match the size of the array. However the 'tabstop' + buffer option is still used for hard tabs. By default + lines are placed below the buffer line containing the + mark. • virt_lines_above: place virtual lines above instead. • virt_lines_leftcol: Place extmarks in the leftmost column of the window, bypassing sign and number columns. @@ -2715,30 +2731,28 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) text around the mark was deleted and then restored by undo. Defaults to true. • invalidate : boolean that indicates whether to hide the - extmark if the entirety of its range is deleted. If + extmark if the entirety of its range is deleted. For + hidden marks, an "invalid" key is added to the "details" + array of |nvim_buf_get_extmarks()| and family. If "undo_restore" is false, the extmark is deleted instead. - • priority: a priority value for the highlight group or sign - attribute. For example treesitter highlighting uses a - value of 100. + • priority: a priority value for the highlight group, sign + attribute or virtual text. For virtual text, item with + highest priority is drawn last. 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. • sign_text: string of length 1-2 used to display in the - sign column. Note: ranges are unsupported and decorations - are only applied to start_row + sign column. • sign_hl_group: name of the highlight group used to - highlight the sign column text. Note: ranges are - unsupported and decorations are only applied to start_row + highlight the sign column text. • number_hl_group: name of the highlight group used to - highlight the number column. Note: ranges are unsupported - and decorations are only applied to start_row + highlight the number column. • line_hl_group: name of the highlight group used to - highlight the whole line. Note: ranges are unsupported and - decorations are only applied to start_row + highlight the whole line. • cursorline_hl_group: name of the highlight group used to - highlight the line when the cursor is on the same line as - the mark and 'cursorline' is enabled. Note: ranges are - unsupported and decorations are only applied to start_row + highlight the sign column text when the cursor is on the + same line as the mark and 'cursorline' is enabled. • conceal: string which should be either empty or a single character. Enable concealing similar to |:syn-conceal|. When a character is supplied it is used as |:syn-cchar|. @@ -2750,6 +2764,11 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) drawn by a UI. When set, the UI will receive win_extmark events. Note: the mark is positioned by virt_text attributes. Can be used together with virt_text. + • url: A URL to associate with this extmark. In the TUI, the + OSC 8 control sequence is used to generate a clickable + hyperlink to this URL. + • scoped: boolean that indicates that the extmark should + only be displayed in the namespace scope. (experimental) Return: ~ Id of the created/updated extmark @@ -2777,7 +2796,7 @@ nvim_get_namespaces() *nvim_get_namespaces()* dict that maps from names to namespace ids. *nvim_set_decoration_provider()* -nvim_set_decoration_provider({ns_id}, {*opts}) +nvim_set_decoration_provider({ns_id}, {opts}) Set or change decoration provider for a |namespace| This is a very general purpose interface for having Lua callbacks being @@ -2813,18 +2832,52 @@ nvim_set_decoration_provider({ns_id}, {*opts}) Parameters: ~ • {ns_id} Namespace id from |nvim_create_namespace()| • {opts} Table of callbacks: - • on_start: called first on each screen redraw ["start", - tick] + • on_start: called first on each screen redraw > + ["start", tick] +< • on_buf: called for each buffer being redrawn (before window - callbacks) ["buf", bufnr, tick] - • on_win: called when starting to redraw a specific window. - botline_guess is an approximation that does not exceed the - last line number. ["win", winid, bufnr, topline, - botline_guess] + callbacks) > + ["buf", bufnr, tick] +< + • on_win: called when starting to redraw a specific window. > + ["win", winid, bufnr, topline, botline] +< • on_line: called for each buffer line being redrawn. (The - interaction with fold lines is subject to change) ["win", - winid, bufnr, row] - • on_end: called at the end of a redraw cycle ["end", tick] + interaction with fold lines is subject to change) > + ["line", winid, bufnr, row] +< + • on_end: called at the end of a redraw cycle > + ["end", tick] +< + +nvim_win_add_ns({window}, {ns_id}) *nvim_win_add_ns()* + Adds the namespace scope to the window. + + Parameters: ~ + • {window} Window handle, or 0 for current window + • {ns_id} the namespace to add + + Return: ~ + true if the namespace was added, else false + +nvim_win_get_ns({window}) *nvim_win_get_ns()* + Gets all the namespaces scopes associated with a window. + + Parameters: ~ + • {window} Window handle, or 0 for current window + + Return: ~ + a list of namespaces ids + +nvim_win_remove_ns({window}, {ns_id}) *nvim_win_remove_ns()* + Removes the namespace scope from the window. + + Parameters: ~ + • {window} Window handle, or 0 for current window + • {ns_id} the namespace to remove + + Return: ~ + true if the namespace was removed, else false ============================================================================== @@ -2842,8 +2895,7 @@ nvim_win_call({window}, {fun}) *nvim_win_call()* only) Return: ~ - Return value of function. NB: will deepcopy Lua values currently, use - upvalues to send Lua references in and out. + Return value of function. See also: ~ • |win_execute()| @@ -3002,7 +3054,7 @@ nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()* This takes precedence over the 'winhighlight' option. Parameters: ~ - • {ns_id} the namespace to use + • {ns_id} the namespace to use nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* Sets a window-scoped (w:) variable @@ -3020,7 +3072,7 @@ nvim_win_set_width({window}, {width}) *nvim_win_set_width()* • {window} Window handle, or 0 for current window • {width} Width as a count of columns -nvim_win_text_height({window}, {*opts}) *nvim_win_text_height()* +nvim_win_text_height({window}, {opts}) *nvim_win_text_height()* Computes the number of screen lines occupied by a range of text in a given window. Works for off-screen text and takes folds into account. @@ -3056,21 +3108,31 @@ nvim_win_text_height({window}, {*opts}) *nvim_win_text_height()* ============================================================================== -Win_Config Functions *api-win_config* +Win_config Functions *api-win_config* -nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* - Open a new window. +nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* + Opens a new split window, or a floating window if `relative` is specified, + or an external window (managed by the UI) if `external` is specified. - Currently this is used to open floating and external windows. Floats are - windows that are drawn above the split layout, at some anchor position in - some other window. Floats can be drawn internally or by external GUI with - the |ui-multigrid| extension. External windows are only supported with - multigrid GUIs, and are displayed as separate top-level windows. + Floats are windows that are drawn above the split layout, at some anchor + position in some other window. Floats can be drawn internally or by + external GUI with the |ui-multigrid| extension. External windows are only + supported with multigrid GUIs, and are displayed as separate top-level + windows. For a general overview of floats, see |api-floatwin|. - Exactly one of `external` and `relative` must be specified. The `width` - and `height` of the new window must be specified. + The `width` and `height` of the new window must be specified when opening + a floating window, but are optional for normal windows. + + If `relative` and `external` are omitted, a normal "split" window is + created. The `win` property determines which window will be split. If no + `win` is provided or `win == 0`, a window will be created adjacent to the + current window. If -1 is provided, a top-level split will be created. + `vertical` and `split` are only valid for normal windows, and are used to + control split direction. For `vertical`, the exact direction is determined + by |'splitright'| and |'splitbelow'|. Split windows cannot have + `bufpos`/`row`/`col`/`border`/`title`/`footer` properties. With relative=editor (row=0,col=0) refers to the top-left corner of the screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right @@ -3091,6 +3153,12 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua vim.api.nvim_open_win(0, false, {relative='win', width=12, height=3, bufpos={100,10}}) +< + + Example (Lua): vertical split left of the current window >lua + vim.api.nvim_open_win(0, false, { + split = 'left', + win = 0 }) < @@ -3108,25 +3176,23 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* window. • "cursor" Cursor position in current window. • "mouse" Mouse position - - • win: |window-ID| for relative="win". + • win: |window-ID| window to split, or relative window when + creating a float (relative="win"). • anchor: Decides which corner of the float to place at (row,col): • "NW" northwest (default) • "NE" northeast • "SW" southwest • "SE" southeast - • width: Window width (in character cells). Minimum of 1. • height: Window height (in character cells). Minimum of 1. • bufpos: Places float relative to buffer text (only when - relative="win"). Takes a tuple of zero-indexed [line, - column]. `row` and `col` if given are applied relative to this position, else they - default to: + relative="win"). Takes a tuple of zero-indexed + `[line, column]`. `row` and `col` if given are applied + relative to this position, else they default to: • `row=1` and `col=0` if `anchor` is "NW" or "NE" • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus like a tooltip near the buffer text). - • row: Row position in units of "screen cell height", may be fractional. • col: Column position in units of "screen cell width", may @@ -3137,8 +3203,9 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* • external: GUI should display the window as an external top-level window. Currently accepts no other positioning configuration together with this. - • zindex: Stacking order. floats with higher `zindex` go on top on floats with lower indices. Must be larger - than zero. The following screen elements have hard-coded + • zindex: Stacking order. floats with higher `zindex` go on + top on floats with lower indices. Must be larger than + zero. The following screen elements have hard-coded z-indices: • 100: insert completion popupmenu • 200: message scrollback @@ -3146,7 +3213,6 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* wildoptions+=pum) The default value for floats are 50. In general, values below 100 are recommended, unless there is a good reason to overshadow builtin elements. - • style: (optional) Configure the appearance of the window. Currently only supports one value: • "minimal" Nvim will display the window with many UI @@ -3159,14 +3225,13 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* empty. The end-of-buffer region is hidden by setting `eob` flag of 'fillchars' to a space char, and clearing the |hl-EndOfBuffer| region in 'winhighlight'. - • border: Style of (optional) window border. This can either be a string or an array. The string values are • "none": No border (default). • "single": A single line box. • "double": A double line box. - • "rounded": Like "single", but with rounded corners ("╭" - etc.). + • "rounded": Like "single", but with rounded corners + ("╭" etc.). • "solid": Adds padding by a single whitespace cell. • "shadow": A drop shadow effect by blending with the background. @@ -3174,19 +3239,26 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* any divisor of eight. The array will specify the eight chars building up the border in a clockwise fashion starting with the top-left corner. As an example, the - double box style could be specified as [ "╔", "═" ,"╗", - "║", "╝", "═", "╚", "║" ]. If the number of chars are - less than eight, they will be repeated. Thus an ASCII - border could be specified as [ "/", "-", "\\", "|" ], or - all chars the same as [ "x" ]. An empty string can be - used to turn off a specific border, for instance, [ "", - "", "", ">", "", "", "", "<" ] will only make vertical - borders but not horizontal ones. By default, - `FloatBorder` highlight is used, which links to - `WinSeparator` when not defined. It could also be - specified by character: [ ["+", "MyCorner"], ["x", - "MyBorder"] ]. - + double box style could be specified as: > + [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. +< + If the number of chars are less than eight, they will be + repeated. Thus an ASCII border could be specified as > + [ "/", "-", \"\\\\\", "|" ], +< + or all chars the same as > + [ "x" ]. +< + An empty string can be used to turn off a specific border, + for instance, > + [ "", "", "", ">", "", "", "", "<" ] +< + will only make vertical borders but not horizontal ones. + By default, `FloatBorder` highlight is used, which links + to `WinSeparator` when not defined. It could also be + specified by character: > + [ ["+", "MyCorner"], ["x", "MyBorder"] ]. +< • title: Title (optional) in window border, string or list. List should consist of `[text, highlight]` tuples. If string, the default highlight group is `FloatTitle`. @@ -3205,6 +3277,8 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* • fixed: If true when anchor is NW or SW, the float window would be kept fixed even if the window would be truncated. • hide: If true the floating window will be hidden. + • vertical: Split vertically |:vertical|. + • split: Split direction: "left", "right", "above", "below". Return: ~ Window handle, or 0 on error @@ -3222,7 +3296,7 @@ nvim_win_get_config({window}) *nvim_win_get_config()* Return: ~ Map defining the window configuration, see |nvim_open_win()| -nvim_win_set_config({window}, {*config}) *nvim_win_set_config()* +nvim_win_set_config({window}, {config}) *nvim_win_set_config()* Configures window layout. Currently only for floating and external windows (including changing a split window to those layouts). @@ -3302,11 +3376,18 @@ nvim_tabpage_set_var({tabpage}, {name}, {value}) • {name} Variable name • {value} Variable value +nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()* + Sets the current window in a tabpage + + Parameters: ~ + • {tabpage} Tabpage handle, or 0 for current tabpage + • {win} Window handle, must already belong to {tabpage} + ============================================================================== Autocmd Functions *api-autocmd* -nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()* +nvim_clear_autocmds({opts}) *nvim_clear_autocmds()* Clears all autocommands selected by {opts}. To delete autocmds see |nvim_del_autocmd()|. @@ -3316,24 +3397,21 @@ nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()* • event: "pat1" • event: { "pat1" } • event: { "pat1", "pat2", "pat3" } - • pattern: (string|table) • pattern or patterns to match exactly. • For example, if you have `*.py` as that pattern for the autocmd, you must pass `*.py` exactly to clear it. `test.py` will not match the pattern. - • defaults to clearing all patterns. • NOTE: Cannot be used with {buffer} - • buffer: (bufnr) • clear only |autocmd-buflocal| autocommands. • NOTE: Cannot be used with {pattern} - • group: (string|int) The augroup name or id. - • NOTE: If not passed, will only delete autocmds not in any group. + • NOTE: If not passed, will only delete autocmds not in any + group. -nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* +nvim_create_augroup({name}, {opts}) *nvim_create_augroup()* Create or get an autocommand group |autocmd-groups|. To get an existing group id, do: >lua @@ -3354,8 +3432,10 @@ nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* See also: ~ • |autocmd-groups| -nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* - Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string). +nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* + Creates an |autocommand| event handler, defined by `callback` (Lua + function or Vimscript function name string) or `command` (Ex command + string). Example using Lua callback: >lua vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { @@ -3393,19 +3473,18 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* troubleshooting). • callback (function|string) optional: Lua function (or Vimscript function name, if string) called when the - event(s) is triggered. Lua callback can return true to - delete the autocommand, and receives a table argument with - these keys: + event(s) is triggered. Lua callback can return a truthy + value (not `false` or `nil`) to delete the autocommand. + Receives a table argument with these keys: • id: (number) autocommand id • event: (string) name of the triggered event |autocmd-events| • group: (number|nil) autocommand group id, if any - • match: (string) expanded value of |<amatch>| - • buf: (number) expanded value of |<abuf>| - • file: (string) expanded value of |<afile>| + • match: (string) expanded value of <amatch> + • buf: (number) expanded value of <abuf> + • file: (string) expanded value of <afile> • data: (any) arbitrary data passed from |nvim_exec_autocmds()| - • command (string) optional: Vim command to execute on event. Cannot be used with {callback} • once (boolean) optional: defaults to false. Run the @@ -3455,7 +3534,7 @@ nvim_del_autocmd({id}) *nvim_del_autocmd()* Parameters: ~ • {id} Integer Autocommand id returned by |nvim_create_autocmd()| -nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* +nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()* Execute all autocommands for {event} that match the corresponding {opts} |autocmd-execute|. @@ -3469,14 +3548,14 @@ nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* • buffer (integer) optional: buffer number |autocmd-buflocal|. Cannot be used with {pattern}. • modeline (bool) optional: defaults to true. Process the - modeline after the autocommands |<nomodeline>|. + modeline after the autocommands <nomodeline>. • data (any): arbitrary data to send to the autocommand callback. See |nvim_create_autocmd()| for details. See also: ~ • |:doautocmd| -nvim_get_autocmds({*opts}) *nvim_get_autocmds()* +nvim_get_autocmds({opts}) *nvim_get_autocmds()* Get all autocommands that match the corresponding {opts}. These examples will get autocommands matching ALL the given criteria: >lua @@ -3590,13 +3669,12 @@ nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* • {height} Popupmenu height, must be greater than zero. nvim_ui_set_focus({gained}) *nvim_ui_set_focus()* - Tells the nvim server if focus was gained or lost by the GUI. + Tells the nvim server if focus was gained or lost by the GUI Attributes: ~ |RPC| only nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* - TODO: Documentation Attributes: ~ |RPC| only @@ -3605,7 +3683,6 @@ nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()* Tells Nvim when a terminal event has occurred The following terminal events are supported: - • "termresponse": The terminal sent an OSC or DCS response sequence to Nvim. The payload is the received response. Sets |v:termresponse| and fires |TermResponse|. @@ -3614,11 +3691,10 @@ nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()* |RPC| only Parameters: ~ - • {event} Event name - • {payload} Event payload + • {event} Event name + • {value} Event payload nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* - TODO: Documentation Attributes: ~ |RPC| only @@ -3638,4 +3714,5 @@ nvim_ui_try_resize_grid({grid}, {width}, {height}) • {width} The new requested width. • {height} The new requested height. + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index c6f6559e37..8890872e1a 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -784,9 +784,6 @@ OptionSet After setting an option (except during are not global-local it is the old local value. - OptionSet is not triggered on startup and for - the 'key' option for obvious reasons. - Usage example: Check for the existence of the directory in the 'backupdir' and 'undodir' options, create the directory if it doesn't @@ -800,6 +797,8 @@ OptionSet After setting an option (except during Non-recursive: |:set| in the autocommand does not trigger OptionSet again. + Not triggered on startup. + *QuickFixCmdPre* QuickFixCmdPre Before a quickfix command is run (|:make|, |:lmake|, |:grep|, |:lgrep|, |:grepadd|, @@ -874,7 +873,7 @@ SafeState When nothing is pending, going to wait for the - Command line completion is active You can use `mode()` to find out what state Vim is in. That may be: - - VIsual mode + - Visual mode - Normal mode - Insert mode - Command-line mode @@ -986,6 +985,11 @@ TermLeave After leaving |Terminal-mode|. TermClose When a |terminal| job ends. Sets these |v:event| keys: status + *TermRequest* +TermRequest When a |terminal| job emits an OSC or DCS + sequence. Sets |v:termrequest|. When used from + Lua, the request string is included in the + "data" field of the autocommand callback. *TermResponse* TermResponse When Nvim receives an OSC or DCS response from the terminal. Sets |v:termresponse|. When used @@ -1001,10 +1005,10 @@ TermResponse When Nvim receives an OSC or DCS response from once = true, callback = function(args) local resp = args.data - local r, g, b = resp:match("\x1b%]4;1;rgb:(%w+)/(%w+)/(%w+)") + local r, g, b = resp:match("\027%]4;1;rgb:(%w+)/(%w+)/(%w+)") end, }) - io.stdout:write("\x1b]4;1;?\x1b\\") + io.stdout:write("\027]4;1;?\027\\") < *TextChanged* TextChanged After a change was made to the text in the diff --git a/runtime/doc/backers.txt b/runtime/doc/backers.txt new file mode 100644 index 0000000000..d0cbd94978 --- /dev/null +++ b/runtime/doc/backers.txt @@ -0,0 +1,656 @@ +*backers.txt* Nvim + + + NVIM REFERENCE MANUAL + + +============================================================================== +Fundraiser Backers + +Thank you to everyone who backed the original Neovim Fundraiser. + +LIST OF BACKERS + +- [Bob Breznak](http://brez.io) +- [Tim Uruski](http://timuruski.net) +- @mikker (http://brnbw.com) +- Aaron J. [@metaxis](http://twitter.com/metaxis) Peterson +- Adam George http://www.adamgeorge.com +- Adam Lindberg (http://alind.io) +- Adam McLain http://twitter.com/adammclain +- Adam Piper http://ahri.net +- Adrian Philipp http://adrian-philipp.com +- Alexander Quine +- Alexandru Dabija +- Alexis Hildebrandt http://surryhill.net +- Andrew M. Farrell http://amfarrell.com +- Anton Beloglazov http://beloglazov.info/ +- Arthur Axel fREW Schmidt - https://blog.afoolishmanifesto.com +- Ben Thouret http://benjamin.thouret.com +- Benedikt Böhm http://bb.xnull.de +- bfredl, http://bfredl.github.io +- Brandon Smith, http://reardencode.com +- Brandon Wang, http://brandonwang.me +- Brennen Bearnes http://p1k3.com +- Brock Wilcox (awwaiid) http://thelackthereof.org/ +- Cameron Eagans http://cweagans.net +- Carl Myers http://cmyers.org/ +- Carlos Alves http://www.carlosalves.info +- Chris Chernesky, http://www.tinderglow.com +- Chris Hartjes +- Christoffer Holmstedt (http://www.christofferholmstedt.se) +- Ciaran Downey <http://ciarand.me> +- Craig Bane http://standardizedways.co.uk +- Dane Summers http://pinedesk.biz +- Daniel Collin https://twitter.com/daniel_collin +- Daniel Rogers http://remotecodelist.com +- Darshan Sawardekar http://pressing-matters.io +- David Gabriel http://wiki.dest-unreachable.net +- Deepak Kumar www.kreatio.com +- Derek Rodger http://devslant.com +- ebene fünf GmbH www.ebenefuenf.de +- Ehtesh Choudhury +- Emil Hernvall http://emilhernvall.github.io/ +- Eric Siegel https://github.com/esiegel +- Ethan Schoonover http://ethanschoonover.com +- FFunction http://ffctn.com +- Frank http://duckpun.ch +- Gabriele Lana http://github.com/gabrielelana +- Gavin Rogers http://praxeology.co.uk +- Geoff Greer https://floobits.com/ +- Glenn Strauss https://github.com/gstrauss/ +- Gustav Buchholtz http://grod.se +- Henri Bourcereau http://bourcereau.fr +- http://jaredforsyth.com +- http://www.1bsyl.com +- Johann Dahm (http://johanndahm.com) +- Ian Farmer http://farmernet.net +- iauns - http://www.noobtube.com +- Jacob Jewell www.immersiveapplications.com +- James A. Overton http://james.overton.ca +- James Tomasino - http://jamestomasino.com +- Jamiel Almeida http://slashfoo.com +- Jan Christoph Ebersbach http://www.e-jc.de/ +- Jason Peacock http://jasonpeacock.com +- Jason Weathered http://jasoncodes.com/ +- Javier Maestro +- Jeff Craig http://blog.foxxtrot.net/ +- Jeremy Huffman http://jeremyhuffman.com +- Jeremy Morrell http://rathercurio.us +- Jesper Kjeldgaard (thejspr) - http://thejspr.com +- Jim Hester (http://jimhester.com) +- Joe Moon http://joe.xoxomoon.com +- Johan Simonsson, http://fun-tech.se +- John P. Kiffmeyer (http://jpk.is) +- John Szakmeister http://www.szakmeister.net/ +- John W. Long http://wiseheartdesign.com Twitter: @johnwlong GitHub: @jlong +- Jon Yurek http://thoughtbot.com +- jonaias http://jonaias.info +- Josh Davis, http://joshldavis.com +- Joshua Levesque (www.jandyco.com) +- Justin M. Keyes https://github.com/justinmk +- Justin Russell http://jrussell.me +- kbussell +- Kevin Sjöberg, http://kevinsjoberg.com +- Kevin Sumner http://kevinsumner.com +- Kevin Wu http://kevinformatics.com +- Ley Missailidis, http://polymet.is +- Loa https://github.com/loa +- Lowe Schmidt http://loweschmidt.se +- Marcello Barnaba http://sindro.me/ +- Marcin Kulik - http://ku1ik.com +- Marius Rieder http://www.durchmesser.ch/ +- Mark Allen [@bytemeorg](http://twitter.com/bytemeorg) +- Mark Percival http://markpercival.us +- Mark Sprevak +- Martin Ansdell-Smith https://ansdell.net/ +- Martin Kopischke http://martin.kopischke.net +- masukomi http://masukomi.org +- Matt Greer -- http://mattgreer.org +- MetaCosm | #Vim on Freenode +- Michael Ulm www.mulm.at +- Mikael Jansson http://mikaelj.se +- Mikkel Høgh http://mikkel.hoegh.org/ +- Ming Liu http://ming.codes +- Holger Peters http://www.holger-peters.de +- Alexander Myshov http://myshov.com/ +- Darren Cheng http://sanguinerane.com/ +- Felix Rath www.0fx.eu +- Hong Xu http://www.topbug.net +- Slava Kim https://www.meteor.com +- Nate Soares (So8res) http://so8r.es +- neektza http://pltconfusion.com +- Niclas Nilsson, http://niclasnilsson.se +- Nikolay Bachiyski http://extrapolate.me/ +- Nikush Patel http://nikush.co.uk +- Norman Köhring https://koehr.in +- Osamu Komagata +- Øystein E. Krog https://github.com/oysteinkrog +- Pablo Brasero Moreno http://pablobm.com +- Peter Souter http://www.petersouter.co.uk +- Phil Levchenko (http://philslair.com) +- Pierre Douyon https://github.com/pgdouyon +- Prateek Rungta +- Przemysław Pietrzkiewicz, http://ppi.sh +- Rasmus Mattsson http://zzm.se +- Reed Esau https://github.com/reedes +- Richard Harding https://bmark.us +- Rob Warner http://grailbox.com +- Runar Balstad Jensen, http://stdout.no/ +- Ryan Paul http://seg.phault.net +- Saad Malik - https://github.com/saamalik +- Saggi Malachi - http://sagg.im +- Scott Wessels (http://www.usgn.net) +- Sean DuBois (Sean-Der) http://siobud.com +- Sebastian Vetter (http://www.roadside-developer.com) +- Simen Endsjø, http://simendsjo.me +- Stanley Chan (Happy-Dude) +- Stefan Penner +- Steve Vermeulen https://github.com/svermeulen +- Steven Myint (https://github.com/myint) +- Tae Sandoval Murgan <taecilla.github.io> +- The Kompanee http://thekompanee.com +- Thomas Cannon <http://thomascannon.net> +- Tim Oxley http://campjs.com/ +- Timo Schmiade +- Timothy Dahlin +- Tiziano Santoro +- Toban Wiebe http://tobanwiebe.com +- Tobias Sjösten http://vvv.tobiassjosten.net/ +- Tom Cammann http://github.com/takac +- Val Markovic http://val.markovic.io/ +- Víðir Valberg Guðmundsson http://rabotnik.coop +- Weiyi Lou http://parlseygardens.net +- Wesley Moore http://wezm.net/ +- Woody Peterson, http://www.bitsofsignal.com +- Zach Kelling, http://zeekay.io + +### Your name in BACKERS.md. + +- @a13xb +- @d1eg0 +- @derkha +- @georgebashi +- @tmcw +- @xpayn +- Adam Baxter (voltagex) +- Adam Miller (maxamillion) +- Adam Sunderland/iterion +- Adon Metcalfe (adonm) +- Adrian Duyzer +- Aidan Stein +- ak47 +- Aketzu +- Alessandro Gangemi +- Alessandro Pagnin +- Alessandro Proscia +- Alex Genco (alexgenco) +- Alex Heeton +- Alex Roper +- Alex Soto (apsoto@gmail.com) +- Alexander Flatter +- Alexander Jeurissen +- Alexander Shabalin +- Alexander Woerndle +- Alexandru Keszeg +- Allan Hudgins +- Ami Chayun +- Amit Beka +- Anders Fuzz +- Andre Azzolini +- Andre da Palma +- André Santos/andrefs +- Andrea Michi +- Andreas Heider +- Andreas Lappe +- andrej ocenas / aocenas +- Andrew Arminio @5thWall +- Andrew DeMaria ~ muff1nman +- Andrew Fallows +- Andrew Fecheyr (@andruby) +- Andrew Hartford +- Andrey Tarantsov +- Andrey Yurovsky +- Andy Dirnberger +- Andy Gayton +- Andy Lindeman +- Andy Webster +- AngelLeliel +- Anton Egorov / satyrius +- Anton Shemerey +- Arnaud Bétrémieux +- Arne Ehrlich +- Arseny Zarechnev +- Arvind Deshpande +- Astro Jetson Jr +- Attila Maczak +- Avétis KAZARIAN (avetisk) +- BarryKay +- bbinet +- BenBergman +- Bengt Lüers +- Benjamin Bryant +- Bèr "berkes" Kessels +- Bernd Homuth +- Bheesham Persaud +- Bilal Quadri +- Bjorn Tipling +- Bojan Zivanovic +- Boris Searles +- Braden Bruington +- Brandon Liu/thenovices +- Brandon Mathis - @imathis +- Brett Ritter +- Brian Shaver (shakerlxxv) +- Bryan Grohman +- Bryn Edwards +- Calin Iorgulescu +- calind +- Cameron Wood / cewood +- Chris Lopes +- Chris Lord +- Chris Porter +- Chris Sims (@jcsims) +- Christian Anton / fibbs +- Christian Delahousse cdelahousse +- Christian Lange +- Christian Wellenbrock +- Christophe Badoit +- Christopher Lübbemeier +- Christopher Mullins +- Chungha Kim +- ckromero +- Claas-Thido Pfaff +- Claes Mogren +- Clayton Drazner +- claytron +- Colin Cooper +- corytheboyd +- Cristián Alberto Arenas Ulloa / NiñoScript +- Cyril LEPAGNOT/cyrill62 +- D3 Designs +- DAddYE (github: DAddYE) +- Dan Webb +- Daniel C. Henning / danielsdesk +- Daniel Egeberg +- Daniel Egger +- Daniel Hodan/czertbytes +- Daniel Latzer +- Daniel Riti +- Daniel Weisser +- Daniele Polencic +- Dave Dixon +- David Collie +- David Galeano +- David Newell +- David Rappo, Bountysource.com +- David Rasch +- David Stensland - terite +- Davit Samvelyan +- Dean Morin +- deffi420 +- defrex +- Deraen +- Dewdrops +- Dick Seabrook +- Dominik Ritter +- Don Browne +- Donald Walker +- Donna Martz +- dpc +- dperson +- dvidsilva +- Edan Maor +- Eddy Garcia +- Edward Ash/cazador481 +- Elias Tandel Barrionovo +- Elijah Mirecki +- Elliot Winkler (github: mcmire) +- Enric Lluelles +- Eric Fode +- Erik Goldman +- Erik Johnson Github: terminalmage Twitter: @terminalmage +- Erik Nordlund +- Ethan Erchinger/erchn +- Evan Tatarka +- Ewoud van Raamsdonk +- fd0 +- Federico Galassi +- Félix Archambault +- Ferdinand Salis-Samaden +- Florian Bartels +- Florian Sachs +- foca +- forbesmyester +- Frédéric de Villamil +- Fredrik Rambris +- Dapeng Li (luislee818) +- Janko Marohnić (janko-m) +- Jun Wu +- Maurice van der Pot (Griffon26) +- Ory Band (oryband) +- Garrett Dawson +- Gaveen Prabhasara +- George Nikolopoulos +- github username "alandyer" +- Giuseppe Rota +- gkalas +- Gökhan Kocak +- goodgravy +- Göran Gustafsson (GLEG) +- Graham Jans +- Greg Marcil +- Gregory Byrd/GByrd +- Gustavo Barron / Cicloid +- Gyuri Horák +- Harald Hvaal +- Harm Aarts +- Harry Glaser +- Håvard Grimelid +- hencjo +- Henning Hasemann +- Henry "Ingvij" Kupty +- henry4k +- Heryandi +- Hontvári József Levente +- IKEDA, Yoshifumi +- Ilia Choly +- iliis +- Ilya Katz +- Indrek Juhkam / indrekj +- irwand +- Islam Sharabash / ibash +- Ivar Vasara +- Jack Stouffer +- Jacqueline Leykam +- Jakob Landbo +- James Herdman +- James Magness +- James Murty / jmurty +- James Nguyen +- James Orr +- James Pickard +- James Seward +- Jamie Hillman +- Jan Larres +- Jan Weitz +- Janko Luin +- Jannik Nielsen / bitkid +- Jared Tyler Miller +- Jason Imison +- Jason Long / @jasonlong +- Jason Stillwell/dragonfax +- Jasu +- javaguirre +- Jedidiah Hurt +- Jeff Schornick +- Jen Patrick +- Jens Hausherr +- Jess Brown / Jess +- Jesse Cooke/@jc00ke +- Jessica Frazelle/ jfrazelle +- Jesus Alvarez +- Jez Allan +- Jimmie Elvenmark +- Jiří Koten +- JJ Murre +- joe di castro +- Joe Malin/633squadron +- Joel Meyer +- Joey Trapp +- Johan Klokkhammer Helsing +- John Cant +- John K. Paul +- John Krueger +- John Netherdrake +- John Schmidt / schmee +- John Whitley/@jwhitley +- Jon Anhold +- Jon Gosting +- Jonas Rollsby +- Jonathan Buschmann +- Jonathan Gibert +- Jonathan Jacobs +- Jonathan Kinred +- Jorge Gallegos (kad) +- Joris Morger +- Josemar Luedke +- Joshua Brookover +- Joshua Travis +- Jouko Karvonen +- jstemmer +- Juan Campa +- Juan Hernández Babón / jhbabon +- juanolon +- Justin Carter Moy +- Justin Force +- Kamil Slowikowski +- Karl Ove Hufthammer +- Kazuo Teramoto +- Kevin Goslar +- Kevin Hamer +- Kevin Watters +- Kevin Zimmerman / zim44 +- kryft +- Krzysztof Adamski +- Lachlan Brad Easton +- Lance Ulmer +- Larry Riedel (Larry@Riedel.org) +- Lasse Immonen (lasse.immonen@gmail.com) +- Léo Unbekandt / Soulou +- Leszek Swirski +- Levi Brown +- lhl +- linduxed +- Lluis Satorre Gonzalez +- lobachevsky +- Louis Pilfold +- Lucas Stephanou/lucasts +- Lucas Werkmeister +- Luke Sampson +- Luke van der Hoeven / @plukevdh +- Maciej Litwiniuk (@mlitwiniuk) +- Mads Navntoft Noe +- Maik Derstappen / MrTango +- Manuel Salvadores +- Marcus Huntemann/mapclyps +- Marcus Martin/nymaen +- Markus Dobler +- Mat Moore +- Mate Nagy +- Mathias Fußenegger +- Matt Moretti +- Matthew Machuga +- Matthew Sunderland +- Matthias Bilger +- Matthias Lehmann +- Maximilian Gerlach +- Meryn Stol +- Michael "manveru" Fellinger +- Michael "beefsack" Alexander +- Michael Iles +- Michael Irwin/mdi +- Michael Kebe +- Michael Lerch +- Michael R. Jones +- Michael Sanders/msanders +- Michael Schall / schallm +- Michail Denchev +- Michał Bartoszkiewicz +- Mickaël FORTUNATO +- Miguel Santesmases +- Mihir Pendse +- Mike Bissett/paran01d +- Mike Sergio +- Mike Wadsten +- mikedillion +- Mikkel Oscar Lyderik Larsen +- Miles Edland / edlandm +- Miles Frain +- Mirko Grönroos +- Moritz Lotze +- Morten Nygaard Åsnes +- MrException +- Julian Churchill (julianchurchill) +- Nakul Dhotre +- Corey Farwell (frewsxcv) +- Tarrant Rollins (tarrant) +- Naseer Ahmed +- Nate Jones +- Nate Soares (So8res) +- Nate Straz +- Neil Kirsopp +- Nelson Chen/nelsonjchen +- Nicholas Firth-McCoy (nfm) +- Nick Sloan +- Nickolas Means +- Nicolai Ruckel +- Niko Kivelä +- nop +- Nuno Frade +- Olaf Heinemann +- Ole Reifschneider +- Oliver Caldwell +- Olivier Lechevalier +- orangain +- orestis +- pablasso +- Pascal Hartig +- Patrick Berkeley +- Patrick Bihan-Faou, TeamBox SARL +- Patrick Stapfer +- Paul R Alexander +- Pavel Afanasyev +- Pawel Grzech +- Paweł Nowak +- Pedro Rodriguez T +- Per Modin +- Peter Edge +- Peter Fern +- Philipe Farias/philipefarias +- Philipp Millar +- Piotr Mitoraj +- Prithvi Prabhu (prithvi) +- Qingping Hou / houqp +- Quasar Jarosz +- queria +- Rachid Zarouali / Xinity +- Radek Szymczyszyn +- Randy Topliffe / Taar +- Ranko Radonić +- Raphael Henrique Ribas +- Ravi Joseph Pinto +- rekab +- Renato Zannon +- Richard "RichiH" Hartmann +- Richard Mihalovič +- Richard Sotarsh Clark +- Rio Kierkels +- rob allen +- Rob Bevan +- Rob Miller @robmil +- Rob O'Dwyer +- Rodolfo Borges (aka bart9h) +- Rodrigo Souto +- Roland Szabo +- Romans Malinovskis +- Roshan George +- Rostepher +- runar +- Russ Adams / rustushki +- Ryan Phillips +- Ryan Pierce/ fission1110 +- Ryan Schmitt +- Ryan Tarpine +- Sadik Gokhan Caglar +- Sam Stokes +- Sanpi +- Santiago Suarez Ordoñez +- saxman7000 +- Scott D'Aquila +- Scott Mathson +- Sean Copenhaver (@copenhas) +- Sean McCleary +- Sean M. Collins (sc68cal) +- Sean Tegtmeyer +- seanbell +- Sebastian Geiger +- Sergey Alexandrov +- Shane Delmore +- shawndumas +- shazow +- Silvan Jegen +- Simon Ratner (simonratner) +- Song Gao +- Stanimir Angelov Mladenov +- Stanislav B. - zbstof +- Stefan Gojan (hoschi) +- Stefan Hoffmann / stefan991 +- Stefan Wienert +- Steffen Rademacker +- Stephen Oney/soney +- Steve "ryz" Haßenpflug +- Steven Daniel Webb +- Steven Sloss +- Sven Opitz +- Sverre Rabbelier +- Szymon Ząbkiewicz +- Taichi Nakamura +- Takayuki Soga +- Teasp00n +- Terin Stock - @terinjokes +- Thai Pangsakulyanont (dtinth) +- Thameera Senanayaka +- Theo Belaire +- Thomas Ferris Nicolaisen +- Thomas Hirsch +- Thomas Maffia/Szerated +- Thomas Pani +- Thomas Thune Hansen +- Thorbjørn Lindeijer +- Thunder Hu +- Thys Meintjes +- Tim Anema +- Tim Matthews +- Timo Kröger +- Tolstyak +- Tom Panning +- Tom Wadley +- Tony Kemp +- tonyo112 +- Tori "TicViking" Hamblin +- treppo +- Truman Ellis +- Tuomas Vähänen +- Tyler Briles/MrBri +- Tyler Brock +- Tyler Mandry +- Ulf Fischer/ulf +- Vangelis Tsoumenis +- Vítězslav Homolka +- Vladimir Chernis +- Vojtech Jasny +- vvakame +- Vytis Valentinavičius +- Wade Berrier +- warrenv +- whateverhuis +- Will Binns-Smith +- Xavier Antoviaque (xavier@antoviaque.org) +- xsb +- Yann Villessuzanne +- yko +- Youta Harada(cohalz) +- Yrjö Peussa +- Yusuke Kanda(@uskanda) +- Yuval Langer +- zerowidth +- Ziling Zhao +- Zsolt Botykai + +ANONYMOUS SUPPORTERS + +There were also 307 other people who didn't claim any level of reward but +contributed to the fundraiser. Thank you all for the support! + +vim:tw=78:ts=8:et:ft=help:norl: diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 6ffb514487..c5f3946871 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -802,6 +802,8 @@ complete_info([{what}]) *complete_info()* no item is selected when using the <Up> or <Down> keys) inserted Inserted string. [NOT IMPLEMENTED YET] + preview_winid Info floating preview window id. + preview_bufnr Info floating preview buffer id. *complete_info_mode* mode values are: @@ -963,8 +965,8 @@ ctxset({context} [, {index}]) *ctxset()* ctxsize() *ctxsize()* Returns the size of the |context-stack|. -cursor({lnum}, {col} [, {off}]) -cursor({list}) *cursor()* +cursor({lnum}, {col} [, {off}]) *cursor()* +cursor({list}) Positions the cursor at the column (byte count) {col} in the line {lnum}. The first column is one. @@ -1367,6 +1369,7 @@ exists({expr}) *exists()* echo exists("*strftime") echo exists("*s:MyFunc") echo exists("*MyFunc") + echo exists("*v:lua.Func") echo exists("bufcount") echo exists(":Make") echo exists("#CursorHold") @@ -1864,6 +1867,40 @@ foldtextresult({lnum}) *foldtextresult()* line, "'m" mark m, etc. Useful when exporting folded text, e.g., to HTML. +foreach({expr1}, {expr2}) *foreach()* + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. + For each item in {expr1} execute {expr2}. {expr1} is not + modified; its values may be, as with |:lockvar| 1. |E741| + See |map()| and |filter()| to modify {expr1}. + + {expr2} must be a |string| or |Funcref|. + + If {expr2} is a |string|, inside {expr2} |v:val| has the value + of the current item. For a |Dictionary| |v:key| has the key + of the current item and for a |List| |v:key| has the index of + the current item. For a |Blob| |v:key| has the index of the + current byte. For a |String| |v:key| has the index of the + current character. + Examples: >vim + call foreach(mylist, 'let used[v:val] = v:true') +< This records the items that are in the {expr1} list. + + Note that {expr2} is the result of expression and is then used + as a command. Often it is good to use a |literal-string| to + avoid having to double backslashes. + + If {expr2} is a |Funcref| it must take two arguments: + 1. the key or the index of the current item. + 2. the value of the current item. + With a lambda you don't get an error if it only accepts one + argument. + If the function returns a value, it is ignored. + + Returns {expr1} in all cases. + When an error is encountered while executing {expr2} no + further items in {expr1} are processed. + When {expr2} is a Funcref errors inside a function are ignored, + unless it was defined with the "abort" flag. fullcommand({name}) *fullcommand()* Get the full command name from a short abbreviated command @@ -2018,8 +2055,8 @@ get({func}, {what}) "args" The list with arguments Returns zero on error. -getbufinfo([{buf}]) -getbufinfo([{dict}]) *getbufinfo()* +getbufinfo([{buf}]) *getbufinfo()* +getbufinfo([{dict}]) Get information about buffers as a List of Dictionaries. Without an argument information about all the buffers is @@ -2042,6 +2079,8 @@ getbufinfo([{dict}]) *getbufinfo()* bufnr Buffer number. changed TRUE if the buffer is modified. changedtick Number of changes made to the buffer. + command TRUE if the buffer belongs to the + command-line window |cmdwin|. hidden TRUE if the buffer is hidden. lastused Timestamp in seconds, like |localtime()|, when the buffer was @@ -2233,7 +2272,7 @@ getcharmod() *getcharmod()* 32 mouse double click 64 mouse triple click 96 mouse quadruple click (== 32 + 64) - 128 command (Macintosh only) + 128 command (Mac) or super Only the modifiers that have not been included in the character itself are obtained. Thus Shift-a results in "A" without a modifier. Returns 0 if no modifiers are used. @@ -2370,6 +2409,7 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* help help subjects highlight highlight groups history |:history| suboptions + keymap keyboard mappings locale locale names (as output of locale -a) mapclear buffer argument mapping mapping name @@ -2878,6 +2918,57 @@ getreginfo([{regname}]) *getreginfo()* If {regname} is not specified, |v:register| is used. The returned Dictionary can be passed to |setreg()|. +getregion({pos1}, {pos2} [, {opts}]) *getregion()* + Returns the list of strings from {pos1} to {pos2} from a + buffer. + + {pos1} and {pos2} must both be |List|s with four numbers. + See |getpos()| for the format of the list. It's possible + to specify positions from a different buffer, but please + note the limitations at |getregion-notes|. + + The optional argument {opts} is a Dict and supports the + following items: + + type Specify the region's selection type + (default: "v"): + "v" for |charwise| mode + "V" for |linewise| mode + "<CTRL-V>" for |blockwise-visual| mode + + exclusive If |TRUE|, use exclusive selection + for the end position + (default: follow 'selection') + + You can get the last selection type by |visualmode()|. + If Visual mode is active, use |mode()| to get the Visual mode + (e.g., in a |:vmap|). + This function is useful to get text starting and ending in + different columns, such as a |charwise-visual| selection. + + *getregion-notes* + Note that: + - Order of {pos1} and {pos2} doesn't matter, it will always + return content from the upper left position to the lower + right position. + - If 'virtualedit' is enabled and the region is past the end + of the lines, resulting lines are padded with spaces. + - If the region is blockwise and it starts or ends in the + middle of a multi-cell character, it is not included but + its selected part is substituted with spaces. + - If {pos1} and {pos2} are not in the same buffer, an empty + list is returned. + - {pos1} and {pos2} must belong to a |bufloaded()| buffer. + - It is evaluated in current window context, which makes a + difference if the buffer is displayed in a window with + different 'virtualedit' or 'list' values. + + Examples: > + :xnoremap <CR> + \ <Cmd>echom getregion( + \ getpos('v'), getpos('.'), #{ type: mode() })<CR> +< + getregtype([{regname}]) *getregtype()* The result is a String, which is type of register {regname}. The value will be one of: @@ -3873,8 +3964,7 @@ json_decode({expr}) *json_decode()* Vim value. In the following cases it will output |msgpack-special-dict|: 1. Dictionary contains duplicate key. - 2. Dictionary contains empty key. - 3. String contains NUL byte. Two special dictionaries: for + 2. String contains NUL byte. Two special dictionaries: for dictionary and for string will be emitted in case string with NUL byte was a dictionary key. @@ -4272,6 +4362,7 @@ mapnew({expr1}, {expr2}) *mapnew()* don't want that use |deepcopy()| first. mapset({mode}, {abbr}, {dict}) *mapset()* +mapset({dict}) Restore a mapping from a dictionary, possibly returned by |maparg()| or |maplist()|. A buffer mapping, when dict.buffer is true, is set on the current buffer; it is up to the caller @@ -4360,6 +4451,7 @@ match({expr}, {pat} [, {start} [, {count}]]) *match()* Note that when {count} is added the way {start} works changes, see above. + *match-pattern* See |pattern| for the patterns that are accepted. The 'ignorecase' option is used to set the ignore-caseness of the pattern. 'smartcase' is NOT used. The matching is always @@ -4477,6 +4569,50 @@ matcharg({nr}) *matcharg()* Highlighting matches using the |:match| commands are limited to three matches. |matchadd()| does not have this limitation. +matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}]) *matchbufline()* + Returns the |List| of matches in lines from {lnum} to {end} in + buffer {buf} where {pat} matches. + + {lnum} and {end} can either be a line number or the string "$" + to refer to the last line in {buf}. + + The {dict} argument supports following items: + submatches include submatch information (|/\(|) + + For each match, a |Dict| with the following items is returned: + byteidx starting byte index of the match + lnum line number where there is a match + text matched string + Note that there can be multiple matches in a single line. + + This function works only for loaded buffers. First call + |bufload()| if needed. + + See |match-pattern| for information about the effect of some + option settings on the pattern. + + When {buf} is not a valid buffer, the buffer is not loaded or + {lnum} or {end} is not valid then an error is given and an + empty |List| is returned. + + Examples: >vim + " Assuming line 3 in buffer 5 contains "a" + :echo matchbufline(5, '\<\k\+\>', 3, 3) + [{'lnum': 3, 'byteidx': 0, 'text': 'a'}] + " Assuming line 4 in buffer 10 contains "tik tok" + :echo matchbufline(10, '\<\k\+\>', 1, 4) + [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}] +< + If {submatch} is present and is v:true, then submatches like + "\1", "\2", etc. are also returned. Example: >vim + " Assuming line 2 in buffer 2 contains "acd" + :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2 + \ {'submatches': v:true}) + [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] +< The "submatches" List always contains 9 items. If a submatch + is not found, then an empty string is returned for that + submatch. + matchdelete({id} [, {win}]) *matchdelete()* *E802* *E803* Deletes a match with ID {id} previously defined by |matchadd()| or one of the |:match| commands. Returns 0 if successful, @@ -4614,6 +4750,39 @@ matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* When {expr} is a |List| then the matching item is returned. The type isn't changed, it's not necessarily a String. +matchstrlist({list}, {pat} [, {dict}]) *matchstrlist()* + Returns the |List| of matches in {list} where {pat} matches. + {list} is a |List| of strings. {pat} is matched against each + string in {list}. + + The {dict} argument supports following items: + submatches include submatch information (|/\(|) + + For each match, a |Dict| with the following items is returned: + byteidx starting byte index of the match. + idx index in {list} of the match. + text matched string + submatches a List of submatches. Present only if + "submatches" is set to v:true in {dict}. + + See |match-pattern| for information about the effect of some + option settings on the pattern. + + Example: >vim + :echo matchstrlist(['tik tok'], '\<\k\+\>') + [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}] + :echo matchstrlist(['a', 'b'], '\<\k\+\>') + [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}] +< + If "submatches" is present and is v:true, then submatches like + "\1", "\2", etc. are also returned. Example: >vim + :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)', + \ #{submatches: v:true}) + [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] +< The "submatches" List always contains 9 items. If a submatch + is not found, then an empty string is returned for that + submatch. + matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* Same as |matchstr()|, but return the matched string, the start position and the end position of the match. Example: >vim @@ -4640,7 +4809,7 @@ max({expr}) *max()* it returns the maximum of all values in the Dictionary. If {expr} is neither a List nor a Dictionary, or one of the items in {expr} cannot be used as a Number this results in - an error. An empty |List| or |Dictionary| results in zero. + an error. An empty |List| or |Dictionary| results in zero. menu_get({path} [, {modes}]) *menu_get()* Returns a |List| of |Dictionaries| describing |menus| (defined @@ -4954,7 +5123,6 @@ msgpackparse({data}) *msgpackparse()* are binary strings). 2. String with NUL byte inside. 3. Duplicate key. - 4. Empty key. ext |List| with two values: first is a signed integer representing extension type. Second is |readfile()|-style list of strings. @@ -5173,9 +5341,9 @@ printf({fmt}, {expr1} ...) *printf()* < This limits the length of the text used from "line" to "width" bytes. - If the argument to be formatted is specified using a posional - argument specifier, and a '*' is used to indicate that a - number argument is to be used to specify the width or + If the argument to be formatted is specified using a + positional argument specifier, and a '*' is used to indicate + that a number argument is to be used to specify the width or precision, the argument(s) to be used must also be specified using a {n$} positional argument specifier. See |printf-$|. @@ -5630,9 +5798,9 @@ reg_recording() *reg_recording()* Returns the single letter name of the register being recorded. Returns an empty string when not recording. See |q|. -reltime() +reltime() *reltime()* reltime({start}) -reltime({start}, {end}) *reltime()* +reltime({start}, {end}) Return an item that represents a time value. The item is a list with items that depend on the system. The item can be passed to |reltimestr()| to convert it to a @@ -5677,8 +5845,8 @@ reltimestr({time}) *reltimestr()* < Also see |profiling|. If there is an error an empty string is returned -remove({list}, {idx}) -remove({list}, {idx}, {end}) *remove()* +remove({list}, {idx}) *remove()* +remove({list}, {idx}, {end}) Without {end}: Remove the item at {idx} from |List| {list} and return the item. With {end}: Remove items from {idx} to {end} (inclusive) and @@ -6407,8 +6575,8 @@ setcmdpos({pos}) *setcmdpos()* Returns 0 when successful, 1 when not editing the command line. -setcursorcharpos({lnum}, {col} [, {off}]) -setcursorcharpos({list}) *setcursorcharpos()* +setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()* +setcursorcharpos({list}) Same as |cursor()| but uses the specified column number as the character index instead of the byte index in the line. @@ -6834,8 +7002,8 @@ shiftwidth([{col}]) *shiftwidth()* 'vartabstop' feature. If no {col} argument is given, column 1 will be assumed. -sign_define({name} [, {dict}]) -sign_define({list}) *sign_define()* +sign_define({name} [, {dict}]) *sign_define()* +sign_define({list}) Define a new sign named {name} or modify the attributes of an existing sign. This is similar to the |:sign-define| command. @@ -7102,8 +7270,8 @@ sign_placelist({list}) *sign_placelist()* \ ]) < -sign_undefine([{name}]) -sign_undefine({list}) *sign_undefine()* +sign_undefine([{name}]) *sign_undefine()* +sign_undefine({list}) Deletes a previously defined sign {name}. This is similar to the |:sign-undefine| command. If {name} is not supplied, then deletes all the defined signs. @@ -8255,7 +8423,6 @@ test_garbagecollect_now() *test_garbagecollect_now()* internally, and |v:testing| must have been set before calling any function. - timer_info([{id}]) *timer_info()* Return a list with information about timers. When {id} is given only information about this timer is diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index e1bb7c5fc7..703addf51a 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -424,9 +424,12 @@ octal number. Note that when 'nrformats' includes "octal", decimal numbers with leading zeros cause mistakes, because they can be confused with octal numbers. -Note similarly, when 'nrformats' includes "bin", binary numbers with a leading -'0x' or '0X' can be interpreted as hexadecimal rather than binary since '0b' -are valid hexadecimal digits. +Note similarly, when 'nrformats' includes both "bin" and "hex", binary numbers +with a leading '0x' or '0X' can be interpreted as hexadecimal rather than +binary since '0b' are valid hexadecimal digits. CTRL-A on "0x0b11" results in +"0x0b12", not "0x0b100". +When 'nrformats' includes "bin" and doesn't include "hex", CTRL-A on "0b11" in +"0x0b11" results in "0x0b100". When the number under the cursor is too big to fit into 64 bits, it will be rounded off to the nearest number that can be represented, and the @@ -485,7 +488,7 @@ SHIFTING LINES LEFT OR RIGHT *shift-left-right* lines to [indent] (default 0). *:>* -:[range]> [flags] Shift {count} [range] lines one 'shiftwidth' right. +:[range]> [flags] Shift [range] lines one 'shiftwidth' right. Repeat '>' for shifting multiple 'shiftwidth's. See |ex-flags| for [flags]. diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index 8bed8a9ffc..57a4223c53 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -439,9 +439,8 @@ CTRL-T When 'incsearch' is set, entering a search pattern for "/" or keyboard T is above G. The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in -a previous version <Esc> was used). In the pattern standard wildcards "*" and -'?' are accepted when matching file names. "*" matches any string, '?' -matches exactly one character. +a previous version <Esc> was used). In the pattern standard |wildcards| are +accepted when matching file names. When repeating 'wildchar' or CTRL-N you cycle through the matches, eventually ending up back to what was typed. If the first match is not what you wanted, diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 0a07f06c75..5ac4ad4ce2 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -90,7 +90,7 @@ For each of the functions below, use the corresponding function in - *vim.lsp.diagnostic.enable()* - *vim.lsp.diagnostic.get()* - *vim.lsp.diagnostic.get_all()* Use |vim.diagnostic.get()| instead. -- *vim.lsp.diagnostic.get_count()* Use |vim.diagnostic.get()| instead. +- *vim.lsp.diagnostic.get_count()* Use |vim.diagnostic.count()| instead. - *vim.lsp.diagnostic.get_line_diagnostics()* Use |vim.diagnostic.get()| instead. - *vim.lsp.diagnostic.get_next()* - *vim.lsp.diagnostic.get_next_pos()* @@ -116,6 +116,9 @@ internally and are no longer exposed as part of the API. Instead, use - *vim.lsp.diagnostic.set_underline()* - *vim.lsp.diagnostic.set_virtual_text()* +Configuring |diagnostic-signs| with |:sign-define| or |sign_define()| is no +longer supported. Use the "signs" key of |vim.diagnostic.config()| instead. + LSP FUNCTIONS - *vim.lsp.buf.server_ready()* Use |LspAttach| instead, depending on your use-case. "Server ready" is not @@ -138,9 +141,11 @@ LSP FUNCTIONS - *vim.lsp.buf.range_formatting()* Use |vim.lsp.formatexpr()| or |vim.lsp.buf.format()| instead. - *vim.lsp.util.get_progress_messages()* Use |vim.lsp.status()| or access - `progress` of |vim.lsp.client| + `progress` of |vim.lsp.Client| - *vim.lsp.get_active_clients()* Use |vim.lsp.get_clients()| - *vim.lsp.for_each_buffer_client()* Use |vim.lsp.get_clients()| +- *vim.lsp.util.lookup_section()* Use |vim.tbl_get()| and + |vim.split()| with {plain=true} instead. - *vim.lsp.util.trim_empty_lines()* Use |vim.split()| with `trimempty` instead. - *vim.lsp.util.try_trim_markdown_code_blocks()* - *vim.lsp.util.set_lines()* @@ -164,6 +169,7 @@ LUA - vim.register_keystroke_callback() Use |vim.on_key()| instead. - *vim.pretty_print()* Use |vim.print()| instead. - *vim.loop* Use |vim.uv| instead. +- *vim.tbl_add_reverse_lookup()* NORMAL COMMANDS - *]f* *[f* Same as "gf". @@ -171,7 +177,6 @@ NORMAL COMMANDS OPTIONS - *cpo-<* *:menu-<special>* *:menu-special* *:map-<special>* *:map-special* `<>` notation is always enabled. -- 'gdefault' Enables the |:substitute| flag 'g' by default. - *'fe'* 'fenc'+'enc' before Vim 6.0; no longer used. - *'highlight'* *'hl'* Names of builtin |highlight-groups| cannot be changed. - *'langnoremap'* Deprecated alias to 'nolangremap'. diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt index cb28f1a845..85aeddd425 100644 --- a/runtime/doc/dev_style.txt +++ b/runtime/doc/dev_style.txt @@ -41,17 +41,44 @@ All header files should start with `#pragma once` to prevent multiple inclusion. #pragma once < +Headers system ~ -Constants ~ +Nvim uses two types of headers. There are "normal" headers and "defs" headers. +Typically, each normal header will have a corresponding defs header, e.g. +`fileio.h` and `fileio_defs.h`. This distinction is done to minimize +recompilation on change. The reason for this is because adding a function or +modifying a function's signature happens more frequently than changing a type +The goal is to achieve the following: -Do not use macros to define constants in headers. +- All headers (defs and normal) must include only defs headers, system + headers, and generated declarations. In other words, headers must not + include normal headers. -Macro constants in header files cannot be used by unit tests. +- Source (.c) files may include all headers, but should only include normal + headers if they need symbols and not types. -However, you are allowed to define a macro that holds the same value as a -non-enum constant (defined in the same header) if the value of the constant -represents the size of an array. +Use the following guideline to determine what to put where: +Symbols: + - regular function declarations + - `extern` variables (including the `EXTERN` macro) + +Non-symbols: + - macros, i.e. `#define`. + - static inline functions, but only if its function declaration has a + `REAL_FATTR_ALWAYS_INLINE` attribute. + - typedefs + - structs + - enums + +- All symbols must be moved to normal headers. + +- Non-symbols used by multiple headers should be moved to defs headers. This + is to ensure headers only include defs headers. Conversely, non-symbols used + by only a single header should be moved to that header. + +- EXCEPTION: if the macro calls a function, then it must be moved to a normal + header. ============================================================================== Scoping *dev-style-scope* @@ -73,6 +100,24 @@ should be used instead of declaration and assignment, e.g. >c int j = g(); // GOOD: declaration has initialization. +Initialization ~ + +Multiple declarations can be defined in one line if they aren't initialized, +but each initialization should be done on a separate line. + +>c + int i; + int j; // GOOD + + int i, j; // GOOD: multiple declarations, no initialization. + + int i = 0; + int j = 0; // GOOD: one initialization per line. + + int i = 0, j; // BAD: multiple declarations with initialization. + + int i = 0, j = 0; // BAD: multiple declarations with initialization. + ============================================================================== Nvim-Specific Magic @@ -190,7 +235,7 @@ Function declarations ~ Every function must not have a separate declaration. -Function declarations are created by the gendeclarations.lua script. >c +Function declarations are created by the gen_declarations.lua script. >c static void f(void); @@ -773,47 +818,6 @@ example, `"\uFEFF"`, is the Unicode zero-width no-break space character, which would be invisible if included in the source as straight UTF-8. -Function Calls ~ - -On one line if it fits; otherwise, wrap arguments at the parenthesis. - -Function calls have the following format: >c - - bool retval = do_something(argument1, argument2, argument3); - -If the arguments do not all fit on one line, they should be broken up onto -multiple lines, with each subsequent line aligned with the first argument. Do -not add spaces after the open paren or before the close paren: >c - - bool retval = do_something(averyveryveryverylongargument1, - argument2, argument3); - -If the function has many arguments, consider having one per line if this makes -the code more readable: >c - - bool retval = do_something(argument1, - argument2, - argument3, - argument4); - -Arguments may optionally all be placed on subsequent lines, with one line per -argument: >c - - if (...) { - ... - ... - if (...) { - do_something( - argument1, // 4 space indent - argument2, - argument3, - argument4); - } - -In particular, this should be done if the function signature is so long that -it cannot fit within the maximum line length. - - Braced Initializer Lists ~ Format a braced list exactly like you would format a function call in its @@ -915,11 +919,6 @@ Horizontal Whitespace ~ Use of horizontal whitespace depends on location. - General ~ ->c - int x[] = { 0 }; // Spaces inside braces for braced-init-list. -< - Variables ~ >c int long_variable = 0; // Don't align assignments. @@ -936,26 +935,6 @@ Use of horizontal whitespace depends on location. }; < - - Operators ~ ->c - x = 0; // Assignment operators always have spaces around - // them. - x = -5; // No spaces separating unary operators and their - x++; // arguments. - if (x && !y) -< - -Vertical Whitespace ~ - -Minimize use of vertical whitespace. - -The basic principle is: The more code that fits on one screen, the easier it -is to follow and understand the control flow of the program. Of course, -readability can suffer from code being too dense as well as too spread out, so -use your judgment. But in general, minimize use of vertical whitespace. - - ============================================================================== Parting Words diff --git a/runtime/doc/dev_theme.txt b/runtime/doc/dev_theme.txt new file mode 100644 index 0000000000..29a2da0d90 --- /dev/null +++ b/runtime/doc/dev_theme.txt @@ -0,0 +1,121 @@ +*dev_theme.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Nvim theme style guide *dev-theme* + +This is style guide for developers working on Nvim's default color scheme. + +License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/ + + Type |gO| to see the table of contents. + +============================================================================== +Design + +- Be "Neovim branded", i.e. have mostly "green-blue" feel plus one or two + colors reserved for very occasional user attention. + +- Be oriented for 'termguicolors' (true colors) while being extra minimal for + 'notermguicolors' (16 colors) as fallback. + +- Be accessible, i.e. have high enough contrast ratio (as defined in + https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef). + This means to have value at least 7 for |hl-Normal| and 4.5 for some common + cases (|hl-Visual|, `Comment` with set 'cursorline', colored syntax, `Diff*`, + |hl-Search|). + +- Be suitable for dark and light backgrounds via exchange of dark and light + palettes. + +- Be usable, i.e. provide enough visual feedback for common objects. + + +============================================================================== +Palettes + +- There are two separate palettes: dark and light. They all contain the same + set of colors exported as `NvimDark*` and `NvimLight*` colors respectively. + +- The dark palette is used for background in the dark color scheme and for + foreground in the light color scheme; and vice versa. This introduces + recognizable visual system without too standing out. + +- Actual computation of palettes should be done in a perceptually uniform + color space. Oklch is a good choice. + +- Each palette has the following colors (descriptions are for dark background; + reverse for light one): + + - Four shades of colored "cold" greys for general UI. + + - Dark ones (from darkest to lightest) are reserved as background for + |hl-NormalFloat| (considered as "black"), |hl-Normal| (background), + |hl-CursorLine|, |hl-Visual|. + + - Light ones (also from darkest to lightest) are reserved for + `Comment`, |hl-StatusLine|/|hl-TabLine|, |hl-Normal| (foreground), + and color considered as "white". + +- Six colors to provide enough terminal colors: red, yellow, green, cyan, + blue, magenta. + They should have (reasonably) similar lightness and chroma to make them + visually coherent. Lightness should be as equal to the palette's basic grey + (which is used for |hl-Normal|) as possible. They should have (reasonably) + different hues to make them visually separable. + +- For 16 colors: + + - Greys are not used and are replaced with the foreground and background + colors of the terminal emulator. + + - Non-grey colors fall back to terminal colors as ordered in ANSI codes + (https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit), + that is red (1, 9), green (2, 10), yellow (3, 11), blue (4, 12), + magenta (5, 13), cyan (6, 14). + To increase contrast, colors 1-6 are used for light background and 9-14 + for dark background. + + +============================================================================== +Highlight groups + +Use: + +- Grey shades for general UI according to their design. + +- Bold text for keywords (`Statement` highlight group). This is an important + choice to increase accessibility for people with color deficiencies, as it + doesn't rely on actual color. + +- Green for strings, |hl-DiffAdd| (as background), |hl-DiagnosticOk|, and some + minor text UI elements. + +- Cyan as main syntax color, i.e. for function usage (`Function` highlight + group), |hl-DiffText|, |hl-DiagnosticInfo|, and some minor text UI elements. + +- Red to generally mean high user attention, i.e. errors; in particular for + |hl-ErrorMsg|, |hl-DiffDelete|, |hl-DiagnosticError|. + +- Yellow very sparingly to mean mild user attention, i.e. warnings. That is, + |hl-DiagnosticWarn| and |hl-WarningMsg|. + +- Blue very sparingly as |hl-DiagnosticHint| and some additional important + syntax group (like `Identifier`). + +- Magenta very carefully (if at all). + +In case of 16 colors: + +- Rely on the assumption "Background color can be used as background; other + colors can be used as foreground". This means that in any + foreground/background combination there should be background and one + non-background color. + +- Use 0 (black) or 15 (bright white) as foreground for non-grey background, + depending on whether normal background is light or dark. + + + vim:tw=78:ts=8:et:ft=help:norl: diff --git a/runtime/doc/dev_tools.txt b/runtime/doc/dev_tools.txt new file mode 100644 index 0000000000..3ee48bec90 --- /dev/null +++ b/runtime/doc/dev_tools.txt @@ -0,0 +1,192 @@ +*dev_tools.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Tools and techniques for developing Nvim *dev-tools* + +The following advice is helpful when working on or debugging issues with Nvim +itself. See also |debug.txt| for advice that applies to Vim. + + Type |gO| to see the table of contents. + +============================================================================== +Backtraces *dev-tools-backtrace* + +LINUX ~ + +Core dumps are disabled by default on Ubuntu +https://stackoverflow.com/a/18368068, CentOS and others. To enable core dumps: +>bash + ulimit -c unlimited +< +On systemd-based systems getting a backtrace is as easy as: +>bash + coredumpctl -1 gdb +< +It's an optional tool, so you may need to install it: +>bash + sudo apt install systemd-coredump +< + +The full backtrace is most useful, send us the `bt.txt` file: +>bash + 2>&1 coredumpctl -1 gdb | tee -a bt.txt + thread apply all bt full +< +On older systems a `core` file will appear in the current directory. To get +a backtrace from the `core` file: +>bash + gdb build/bin/nvim core 2>&1 | tee backtrace.txt + thread apply all bt full +< + +MACOS + +If `nvim` crashes, you can see the backtrace in `Console.app` (under "Crash +Reports" or "User Diagnostic Reports" for older macOS versions). +>bash + open -a Console +< +You may also want to enable core dumps on macOS. To do this, first make sure +the `/cores/` directory exists and is writable: +>bash + sudo mkdir /cores + sudo chown root:admin /cores + sudo chmod 1775 /cores +< +Then set the core size limit to `unlimited`: +>bash + ulimit -c unlimited +< +Note that this is done per shell process. If you want to make this the default +for all shells, add the above line to your shell's init file (e.g. `~/.bashrc` +or similar). + +You can then open the core file in `lldb`: +>bash + lldb -c /cores/core.12345 +< +Apple's documentation archive has some other useful information +https://developer.apple.com/library/archive/technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391-CH1-SECCOREDUMPS, +but note that some of the things on this page are out of date (such as enabling +core dumps with `/etc/launchd.conf`). + +============================================================================== +Gdb *dev-tools-gdb* + +USING GDB TO STEP THROUGH FUNCTIONAL TESTS ~ + +Use `TEST_TAG` to run tests matching busted tags (of the form `#foo` e.g. +`it("test #foo ...", ...)`): +>bash + GDB=1 TEST_TAG=foo make functionaltest +< +Then, in another terminal: +>bash + gdb build/bin/nvim + target remote localhost:7777 +< +- See also test/functional/helpers.lua https://github.com/neovim/neovim/blob/3098b18a2b63a841351f6d5e3697cb69db3035ef/test/functional/helpers.lua#L38-L44. + + +USING LLDB TO STEP THROUGH UNIT TESTS ~ + +>bash + lldb .deps/usr/bin/luajit -- .deps/usr/bin/busted --lpath="./build/?.lua" test/unit/ +< + +USING GDB ~ + +To attach to a running `nvim` process with a pid of 1234: +>bash + gdb -tui -p 1234 build/bin/nvim +< +The `gdb` interactive prompt will appear. At any time you can: + +- `break foo` to set a breakpoint on the `foo()` function +- `n` to step over the next statement + - `<Enter>` to repeat the last command +- `s` to step into the next statement +- `c` to continue +- `finish` to step out of the current function +- `p zub` to print the value of `zub` +- `bt` to see a backtrace (callstack) from the current location +- `CTRL-x CTRL-a` or `tui enable` to show a TUI view of the source file in the + current debugging context. This can be extremely useful as it avoids the + need for a gdb "frontend". +- `<up>` and `<down>` to scroll the source file view + + +GDB "REVERSE DEBUGGING" ~ + +- `set record full insn-number-max unlimited` +- `continue` for a bit (at least until `main()` is executed +- `record` +- provoke the bug, then use `revert-next`, `reverse-step`, etc. to rewind the + debugger + + +USING GDBSERVER ~ + +You may want to connect multiple `gdb` clients to the same running `nvim` +process, or you may want to connect to a remote `nvim` process with a local +`gdb`. Using `gdbserver`, you can attach to a single process and control it +from multiple `gdb` clients. + +Open a terminal and start `gdbserver` attached to `nvim` like this: +>bash + gdbserver :6666 build/bin/nvim 2> gdbserver.log +< +`gdbserver` is now listening on port 6666. You then need to attach to this +debugging session in another terminal: +>bash + gdb build/bin/nvim +< +Once you've entered `gdb`, you need to attach to the remote session: +> + target remote localhost:6666 +< +In case gdbserver puts the TUI as a background process, the TUI can become +unable to read input from pty (and receives SIGTTIN signal) and/or output data +(SIGTTOU signal). To force the TUI as the foreground process, you can add +> + signal (SIGTTOU, SIG_IGN); + if (!tcsetpgrp(data->input.in_fd, getpid())) { + perror("tcsetpgrp failed"); + } +< +to `tui.c:terminfo_start`. + + +USING GDBSERVER IN TMUX ~ + +Consider using a custom makefile +https://github.com/neovim/neovim/blob/master/BUILD.md#custom-makefile to +quickly start debugging sessions using the `gdbserver` method mentioned above. +This example `local.mk` will create the debugging session when you type `make +debug`. +>make + .PHONY: dbg-start dbg-attach debug build + + build: + @$(MAKE) nvim + + dbg-start: build + @tmux new-window -n 'dbg-neovim' 'gdbserver :6666 ./build/bin/nvim -D' + + dbg-attach: + @tmux new-window -n 'dbg-cgdb' 'cgdb -x gdb_start.sh ./build/bin/nvim' + + debug: dbg-start dbg-attach +< +Here `gdb_start.sh` includes `gdb` commands to be called when the debugger +starts. It needs to attach to the server started by the `dbg-start` rule. For +example: +> + target remote localhost:6666 + br main +< + +vim:tw=78:ts=8:et:ft=help:norl: diff --git a/runtime/doc/dev_vimpatch.txt b/runtime/doc/dev_vimpatch.txt new file mode 100644 index 0000000000..96307dc7df --- /dev/null +++ b/runtime/doc/dev_vimpatch.txt @@ -0,0 +1,303 @@ +*dev_vimpatch.txt* Nvim + + NVIM REFERENCE MANUAL + +Merging patches from Vim *dev-vimpatch* + + +Nvim was forked from Vim 7.4.160; it is kept up-to-date with relevant Vim +patches in order to avoid duplicate work. Run `vim-patch.sh` +https://github.com/neovim/neovim/blob/master/scripts/vim-patch.sh to see the +status of Vim patches: +>bash + ./scripts/vim-patch.sh -l +< +Everyone is welcome to |dev-vimpatch-pull-requests| for relevant Vim +patches, but some types of patches are |dev-vimpatch-not-applicable|. +See |dev-vimpatch-quickstart| to get started immediately. + + + Type |gO| to see the table of contents. + +============================================================================== +QUICKSTART *dev-vimpatch-quickstart* + +1. Pull the Nvim source: +>bash + git clone https://github.com/neovim/neovim.git +< +2. Run `./scripts/vim-patch.sh -l` to see the list of missing Vim patches. + +3. Choose a patch from the list (usually the oldest one), e.g. `8.0.0123`. + + - Check for open vim-patch PRs + https://github.com/neovim/neovim/pulls?q=is%3Apr+is%3Aopen+label%3Avim-patch. + +4. Run `./scripts/vim-patch.sh -p 8.0.0123` + +5. Follow the instructions given by the script. + +NOTES ~ + +- It's strongly recommended to work on the oldest missing patch, because + later patches might depend on the changes. +- Use `git log --grep` or `git log -G` to search the Nvim/Vim source history + (even deleted code). E.g. to find `reset_option_was_set`: >bash + + git log -p -G reset_option_was_set +< +- Pass `git log` options like `--grep` and `-G` to `./scripts/vim-patch.sh -L` + to filter unmerged Vim patches E.g. to find `+quickfix` patches: >bash + + ./scripts/vim-patch.sh -L --grep quickfix -- src +< +============================================================================== +PULL REQUESTS *dev-vimpatch-pull-requests* + +Note: vim-patch.sh automates these steps for you. Use it! + +- Install `gh` (https://cli.github.com/) if you want to use `vim-patch.sh` to + create PRs automatically +- The pull request title should include `vim-patch:8.x.xxxx` (no whitespace) +- The commit message + https://github.com/neovim/neovim/commit/4ccf1125ff569eccfc34abc4ad794044c5ab7455 + should include: + - A token indicating the Vim patch number, formatted as follows: + `vim-patch:8.0.0123` (no whitespace) + - A URL pointing to the Vim commit: + https://github.com/vim/vim/commit/c8020ee825b9d9196b1329c0e097424576fc9b3a + - The original Vim commit message, including author + +Reviewers: hint for reviewing `runtime/` patches +https://github.com/neovim/neovim/pull/1744#issuecomment-68202876 + +============================================================================== +NA (NOT APPLICABLE) PATCHES *dev-vimpatch-not-applicable* + +Many Vim patches are not applicable to Nvim. If you find NA patches, visit an +open "version.c: update" pull request +https://github.com/neovim/neovim/pulls?q=is%3Apr+author%3Aapp%2Fgithub-actions+version.c+is%3Aopen +and mention the NA patches in a comment (please edit/update one comment, +rather than adding a new comment for each patch). + +If there are no open `version.c: update` pull requests, include NA patches in +a commit message in the following format: +> + vim-patch:<version-or-commit> + vim-patch:<version-or-commit> + ... +< +where `<version-or-commit>` is a valid Vim version (like `8.0.0123`) or +commit-id (SHA). Each patch is on a separate line. + +It is preferred to include NA patches by squashing it in applicable Vim +patches, especially if the Vim patches are related. First line of the commit +message should be from the applicable Vim patch. +> + ./scripts/vim-patch -p <na-patch> + ./scripts/vim-patch -p <na-patch> + ... + ./scripts/vim-patch -P <patch> + git rebase -i master +< +Example: +https://github.com/neovim/neovim/commit/00f60c2ce78fc1280e93d5a36bc7b2267d5f4ac6 + +TYPES OF "NOT APPLICABLE" VIM PATCHES ~ + +- Vim9script features, and anything related to `:scriptversion`. (Nvim + supports Vimscript version 1 only.) Be aware that patches labelled `Vim9:` + may still contain applicable fixes to other parts of the codebase, so these + patch need to be checked individually. +- Updates to `testdir/Makefile` are usually NA because the Makefile implicitly + finds + https://github.com/neovim/neovim/commit/8a677f8a4bff6005fa39f090c14e970c3dfdbe6e#diff-b3c6ad6680a25a1b42095879e3a87104R52 + all `test_*.vim` files. +- Compiler warning fixes: Nvim strives to have no warnings at all, and has a + very different build system from Vim. + - Note: Coverity fixes in Vim are relevant to Nvim. +- `*.proto` changes: Nvim autogenerates function prototypes +- `#ifdef` tweaking: For example, Vim decided to enable `FEAT_VISUAL` for all + platforms - but Nvim already does that. Adding new `FEAT_` guards also isn't + relevant to Nvim. +- Legacy system support: Fixes for legacy systems such as Amiga, OS/2 Xenix, + Mac OS 9, Windows older than XP SP2, are not needed because they are not + supported by Nvim. + - NA files: `src/Make_*`, `src/testdir/Make__*` +- `if_*.c` changes: `if_python.c` et. al. were removed. +- `term.c` changes: the Nvim TUI uses `libtermkey` to read terminal sequences; + Vim's `term.c` was removed. +- `job` patches: incompatible API and implementation + - NA files: `src/channel_*`, `src/job_*`, `src/testdir/test_channel_*`, + `src/testdir/test_job_*` +- `:terminal` patches that modify NA files: incompatible API and + implementation + - NA files: `src/terminal_*`, `src/testdir/test_terminal_*` +- `defaults.vim` patches +- Most GUI-related changes: Nvim GUIs are implemented external to the core C + codebase. + - NA files: `src/gui_*`, `src/gvim_*`, `src/GvimExt/*`, `src/testdir/test_gui*` +- `balloon` changes: Nvim does not support balloon feature + - NA files: `src/beval_*`, `src/testdir/test_balloon_*` +- libvterm changes: Nvim does not vendor libvterm in `src/`. +- Screendump tests from `test_popupwin.vim`, `test_popupwin_textprop.vim`: + https://github.com/neovim/neovim/pull/12741#issuecomment-704677141 +- json changes: incompatible API https://github.com/neovim/neovim/pull/4131 + - NA files: `src/json*`, `src/testdir/test_json.vim` +- `test_restricted.vim` restricted mode is removed in + https://github.com/neovim/neovim/pull/11996 +- Many tests in `test_prompt_buffer.vim` require incompatible Vim features + such as `channel`; they should still be included, but skipped +- non-runtime documentation: Moved to https://neovim.io/doc/, + - NA files: `Filelist`, `README`, `INSTALL`, +- Anything else might be relevant; err on the side of caution, and post an + issue if you aren't sure. + +============================================================================== +VERSION.C *dev-vimpatch-version.c* + +The list of Vim patches in `src/nvim/version.c` is automatically updated +https://github.com/neovim/neovim/pull/7780 based on the presence of +`vim-patch:xxx` tokens in the Nvim git log. + +- Don't update `src/nvim/version.c` yourself. + - `scripts/vim-patch.sh -p` intentionally omits `version.c` to avoid merge + conflicts and save time when porting a patch. +- The automation script (`scripts/vimpatch.lua`) only recognizes tokens like + `vim-patch:8.0.1206`, not `vim-patch:<hash>`. + +============================================================================== +CODE DIFFERENCES *dev-vimpatch-code-differences* + +The following functions have been removed or deprecated in favor of newer +alternatives. See `memory.c` +https://github.com/neovim/neovim/blob/master/src/nvim/memory.c for more +information. +> + ----------------------------------------------------------------------- + Deprecated or removed Replacement + ----------------------------------------------------------------------- + vim_free xfree + VIM_CLEAR(&foo) XFREE_CLEAR(foo) + malloc alloc lalloc lalloc_id ALLOC_ONE xmalloc + calloc lalloc_clear xcalloc + realloc vim_realloc xrealloc + mch_memmove memmove + vim_memset copy_chars copy_spaces memset + vim_strbyte strchr + vim_strncpy strncpy xstrlcpy + vim_strcat strncat xstrlcat + VIM_ISWHITE ascii_iswhite + IS_WHITE_OR_NUL ascii_iswhite_or_nul + vim_isalpha mb_isalpha + vim_isNormalIDc ascii_isident + vim_islower vim_isupper mb_islower mb_isupper + vim_tolower vim_toupper mb_tolower mb_toupper + mb_ptr2len utfc_ptr2len + mb_ptr2len_len utfc_ptr2len_len + mb_char2len utf_char2len + mb_char2bytes utf_char2bytes + mb_ptr2cells utf_ptr2cells + mb_ptr2cells_len utf_ptr2cells_len + mb_char2cells utf_char2cells + mb_off2cells utf_off2cells + mb_ptr2char utf_ptr2char + mb_head_off utf_head_off + mb_tail_off utf_cp_bounds + mb_lefthalve grid_lefthalve + mb_fix_col grid_fix_col + utf_off2cells grid_off2cells + ml_get_curline get_cursor_line_ptr + ml_get_cursor get_cursor_pos_ptr + screen_char ui_line + screen_line grid_put_linebuf + screen_* (most functions) grid_* + update_prepare, update_finish #9484 removed; use update_screen only + ARRAY_LENGTH ARRAY_SIZE + vim_strsave_escape_csi vim_strsave_escape_ks + vim_unescape_csi vim_unescape_ks + gettail path_tail + mch_isFullName path_is_absolute + script_do_profile profile_init + + ----------------------------------------------------------------------- +< +Make sure to note the difference between `utf_` and `utfc_` when replacing +`mb_` functions. Also indirect call syntax `(*mb_ptr2len)(...)` should be +replaced with an ordinary function call `utfc_ptr2len(...)`. +> + ----------------------------------------------------------------------- + Data type Format (Vim source) Portable format (Nvim source) + ------------ ----------------------- ---------------------------------- + long long "%lld" "%" PRId64 + size_t "%ld" "%zu" + linenr_T "%ld" "%" PRIdLINENR + ----------------------------------------------------------------------- +< +- See also: https://github.com/neovim/neovim/pull/1729#discussion_r22423779 +- Vim's `ga_init2` was renamed to `ga_init` and the original `ga_init` is + gone. +- "Old style" Vim tests (`src/testdir/*.in`) should be converted to Lua tests + (see #1286 https://github.com/neovim/neovim/issues/1286 and #1328 + https://github.com/neovim/neovim/pull/1328). See Checklist for migrating + legacy tests + https://github.com/neovim/neovim/blob/master/test/README.md#checklist-for-migrating-legacy-tests. + - However, please do not convert "new style" Vim tests + (`src/testdir/*.vim`) to Lua. The "new style" Vim tests are faster than + the old ones, and converting them takes time and effort better spent + elsewhere. Just copy them to `test/old/testdir/*.vim`. +- Conditions that check `enc_utf8` or `has_mbyte` are obsolete (only the + "true" case is applicable). + - `enc_utf8` and `has_mbyte` macros were removed in + https://github.com/neovim/neovim/pull/13293 +- Check for `CSI` in typeahead buffer is only necessary in Vim with + `FEAT_GUI`. `CSI` does not have a special meaning in typeahead buffer in + Nvim. (also see https://github.com/neovim/neovim/pull/16936) + +============================================================================== +LIST MANAGEMENT *dev-vimpatch-list-management* + +Management of lists (types `list_T` and `listitem_T` from vim) was changed in +https://github.com/neovim/neovim/pull/7708/. There is a lint against the "old" +usage, but here are the most important changes. + +Declarations for the table + +- `list_T list`: a list +- `listitem_T li`: an item of `list` +- `int val` a value for `lv_copyID` + +> + -------------------------------------------------------------------------------------- + Old New Comment + ------------------------------- ------------------------------------------------------ + list->lv_first tv_list_first(list) + list->lv_last tv_list_last(list) + li->li_next TV_LIST_ITEM_NEXT(list, li) To be avoided if possible, must use list which li belongs to. + li->li_prev TV_LIST_ITEM_PREV(list, li) To be avoided if possible, must use list which li belongs to. + Suggestion by @ZyX-l: Use TV_LIST_ITER or indexing instead of the previous two calls. + list->lv_len tv_list_len(list) + list->lv_lock tv_list_locked(list) + &li->li_tv TV_LIST_ITEM_TV(li) + list->lv_refcount++ tv_list_ref(list) + val = list->lv_copyID val = tv_list_copyid(list) + list->lv_copyID = val tv_list_set_copyid(list, val) + + for (li = list->lv_first; TV_LIST_ITER_CONST(list, li, Use TV_LIST_ITER(...) if you need to + li != NULL && another_cond; { if (another_cond) {break;} code}) modify list items (note: assigning copyID is also modification and this happens + li = li->li_next) code always when recursively traversing a list). + + -------------------------------------------------------------------------------------- +< +For more details and some more advanced usage, see `typval.h` and `typval.c`. + +============================================================================== +DOCUMENTATION DIFFERENCES *dev-vimpatch-documentation* + +The following should be removed from all imported documentation, and not be +used in new documentation: + +- `{Only when compiled with ...}`: the vast majority of features have been + made non-optional (see https://github.com/neovim/neovim/wiki/Introduction) + +vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index f1d74326c7..767f46ad1e 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -102,11 +102,11 @@ Examples: The provider framework invokes Vimscript from C. It is composed of two functions in eval.c: -- eval_call_provider(name, method, arguments, discard): calls - provider#{name}#Call with the method and arguments. If discard is true, any +- eval_call_provider({name}, {method}, {arguments}, {discard}): Calls + `provider#{name}#Call` with {method} and {arguments}. If {discard} is true, any value returned by the provider will be discarded and empty value will be returned. -- eval_has_provider(name): Checks the `g:loaded_{name}_provider` variable +- eval_has_provider({name}): Checks the `g:loaded_{name}_provider` variable which must be set to 2 by the provider script to indicate that it is "enabled and working". Called by |has()| to check if features are available. @@ -179,19 +179,22 @@ Strict "vimdoc" subset: - Do not use indentation in random places—that prevents the page from using "flow" layout. If you need a preformatted section, put it in a |help-codeblock| starting with ">". +- Parameters and fields are documented as `{foo}`. +- Optional parameters and fields are documented as `{foo}?`. C docstrings ~ -Nvim API documentation lives in the source code, as docstrings (Doxygen +Nvim API documentation lives in the source code, as docstrings (doc comments) on the function definitions. The |api| :help is generated from the docstrings defined in src/nvim/api/*.c. Docstring format: - Lines start with `///` - Special tokens start with `@` followed by the token name: - `@note`, `@param`, `@returns` -- Limited markdown is supported. - - List-items start with `-` (useful to nest or "indent") + `@note`, `@param`, `@return` +- Markdown is supported. +- Tags are written as `[tag]()`. +- References are written as `[tag]` - Use ``` for code samples. Code samples can be annotated as `vim` or `lua` @@ -233,11 +236,35 @@ definitions. The |lua-vim| :help is generated from the docstrings. Docstring format: - Use LuaCATS annotations: https://luals.github.io/wiki/annotations/ -- Limited markdown is supported. - - List-items start with `-` (useful to nest or "indent") +- Markdown is supported. +- Tags are written as `[tag]()`. +- References are written as `[tag]` - Use ``` for code samples. Code samples can be annotated as `vim` or `lua` - Use `@nodoc` to prevent documentation generation. +- Use `@inlinedoc` to inline `@class` blocks into `@param` blocks. + E.g. >lua + --- Object with fields: + --- @class myOpts + --- @inlinedoc + --- + --- Documentation for some field + --- @field somefield? integer + + --- @param opts? myOpts + function foo(opts) + end +< + + Will be rendered as: >vimdoc + + foo({opts}) + + Parameters: + - {opts}? (table) Object with the fields: + - {somefield}? (integer) Documentation + for some field +< - Files which has `@meta` are only used for typing and documentation. Example: the help for |vim.paste()| is generated from a docstring decorating diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 7f5c809ac3..c9e783ca62 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -38,24 +38,6 @@ optionally supplied). A good rule of thumb is that if a method is meant to modify the diagnostics for a buffer (e.g. |vim.diagnostic.set()|) then it requires a namespace. - *diagnostic-structure* -A diagnostic is a Lua table with the following keys. Required keys are -indicated with (+): - - bufnr: Buffer number - lnum(+): The starting line of the diagnostic - end_lnum: The final line of the diagnostic - col(+): The starting column of the diagnostic - end_col: The final column of the diagnostic - severity: The severity of the diagnostic |vim.diagnostic.severity| - message(+): The diagnostic text - source: The source of the diagnostic - code: The diagnostic code - user_data: Arbitrary data plugins or users can add - -Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based -rows and columns). |api-indexing| - *vim.diagnostic.severity* *diagnostic-severity* The "severity" key in a diagnostic is one of the values defined in `vim.diagnostic.severity`: @@ -317,12 +299,24 @@ SIGNS *diagnostic-signs* Signs are defined for each diagnostic severity. The default text for each sign is the first letter of the severity name (for example, "E" for ERROR). Signs -can be customized using the following: >vim +can be customized with |vim.diagnostic.config()|. Example: >lua - sign define DiagnosticSignError text=E texthl=DiagnosticSignError linehl= numhl= - sign define DiagnosticSignWarn text=W texthl=DiagnosticSignWarn linehl= numhl= - sign define DiagnosticSignInfo text=I texthl=DiagnosticSignInfo linehl= numhl= - sign define DiagnosticSignHint text=H texthl=DiagnosticSignHint linehl= numhl= + -- Highlight entire line for errors + -- Highlight the line number for warnings + vim.diagnostic.config({ + signs = { + text = { + [vim.diagnostic.severity.ERROR] = '', + [vim.diagnostic.severity.WARN] = '', + }, + linehl = { + [vim.diagnostic.severity.ERROR] = 'ErrorMsg', + }, + numhl = { + [vim.diagnostic.severity.WARN] = 'WarningMsg', + }, + }, + }) When the "severity_sort" option is set (see |vim.diagnostic.config()|) the priority of each sign depends on the severity of the associated diagnostic. @@ -349,6 +343,236 @@ Example: >lua ============================================================================== Lua module: vim.diagnostic *diagnostic-api* +*vim.Diagnostic* + *diagnostic-structure* + + Diagnostics use the same indexing as the rest of the Nvim API (i.e. + 0-based rows and columns). |api-indexing| + + Fields: ~ + • {bufnr}? (`integer`) Buffer number + • {lnum} (`integer`) The starting line of the diagnostic + (0-indexed) + • {end_lnum}? (`integer`) The final line of the diagnostic (0-indexed) + • {col} (`integer`) The starting column of the diagnostic + (0-indexed) + • {end_col}? (`integer`) The final column of the diagnostic + (0-indexed) + • {severity}? (`vim.diagnostic.Severity`) The severity of the + diagnostic |vim.diagnostic.severity| + • {message} (`string`) The diagnostic text + • {source}? (`string`) The source of the diagnostic + • {code}? (`string|integer`) The diagnostic code + • {_tags}? (`{ deprecated: boolean, unnecessary: boolean}`) + • {user_data}? (`any`) arbitrary data plugins can add + • {namespace}? (`integer`) + +*vim.diagnostic.GetOpts* + A table with the following keys: + + Fields: ~ + • {namespace}? (`integer`) Limit diagnostics to the given namespace. + • {lnum}? (`integer`) Limit diagnostics to the given line number. + • {severity}? (`vim.diagnostic.SeverityFilter`) See + |diagnostic-severity|. + +*vim.diagnostic.GotoOpts* + Extends: |vim.diagnostic.GetOpts| + + Configuration table with the following keys: + + Fields: ~ + • {cursor_position}? (`{[1]:integer,[2]:integer}`, default: current cursor position) + Cursor position as a `(row, col)` tuple. See + |nvim_win_get_cursor()|. + • {wrap}? (`boolean`, default: `true`) Whether to loop + around file or not. Similar to 'wrapscan'. + • {severity} (`vim.diagnostic.Severity`) See + |diagnostic-severity|. + • {float}? (`boolean|vim.diagnostic.Opts.Float`, default: + `true`) If `true`, call + |vim.diagnostic.open_float()| after moving. If a + table, pass the table as the {opts} parameter to + |vim.diagnostic.open_float()|. Unless overridden, + the float will show diagnostics at the new cursor + position (as if "cursor" were passed to the + "scope" option). + • {win_id}? (`integer`, default: `0`) Window ID + +*vim.diagnostic.NS* + + Fields: ~ + • {name} (`string`) + • {opts} (`vim.diagnostic.Opts`) See |vim.diagnostic.Opts|. + • {user_data} (`table`) + • {disabled}? (`boolean`) + +*vim.diagnostic.Opts* + Each of the configuration options below accepts one of the following: + • `false`: Disable this feature + • `true`: Enable this feature, use default settings. + • `table`: Enable this feature with overrides. Use an empty table to use + default values. + • `function`: Function with signature (namespace, bufnr) that returns any + of the above. + + Fields: ~ + • {underline}? (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`) + Use underline for diagnostics. + • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `true`) + Use virtual text for diagnostics. If multiple + diagnostics are set for a namespace, one prefix + per diagnostic + the last diagnostic message are + shown. + • {signs}? (`boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs`, default: `true`) + Use signs for diagnostics |diagnostic-signs|. + • {float}? (`boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float`) + Options for floating windows. See + |vim.diagnostic.Opts.Float|. + • {update_in_insert}? (`boolean`, default: `false`) Update diagnostics + in Insert mode (if `false`, diagnostics are + updated on |InsertLeave|) + • {severity_sort}? (`boolean|{reverse?:boolean}`, default: `false) + Sort diagnostics by severity. This affects the + order in which signs and virtual text are + displayed. When true, higher severities are + displayed before lower severities (e.g. ERROR is + displayed before WARN). Options: + • {reverse}? (boolean) Reverse sort order + +*vim.diagnostic.Opts.Float* + + Fields: ~ + • {bufnr}? (`integer`, default: current buffer) Buffer number + to show diagnostics from. + • {namespace}? (`integer`) Limit diagnostics to the given namespace + • {scope}? (`'line'|'buffer'|'cursor'|'c'|'l'|'b'`, default: + `line`) Show diagnostics from the whole buffer + (`buffer"`, the current cursor line (`line`), or the + current cursor position (`cursor`). Shorthand + versions are also accepted (`c` for `cursor`, `l` + for `line`, `b` for `buffer`). + • {pos}? (`integer|{[1]:integer,[2]:integer}`) If {scope} is + "line" or "cursor", use this position rather than + the cursor position. If a number, interpreted as a + line number; otherwise, a (row, col) tuple. + • {severity_sort}? (`boolean|{reverse?:boolean}`, default: `false`) + Sort diagnostics by severity. Overrides the setting + from |vim.diagnostic.config()|. + • {severity}? (`vim.diagnostic.SeverityFilter`) See + |diagnostic-severity|. Overrides the setting from + |vim.diagnostic.config()|. + • {header}? (`string|{[1]:string,[2]:any}`) String to use as the + header for the floating window. If a table, it is + interpreted as a `[text, hl_group]` tuple. Overrides + the setting from |vim.diagnostic.config()|. + • {source}? (`boolean|'if_many'`) Include the diagnostic source + in the message. Use "if_many" to only show sources + if there is more than one source of diagnostics in + the buffer. Otherwise, any truthy value means to + always show the diagnostic source. Overrides the + setting from |vim.diagnostic.config()|. + • {format}? (`fun(diagnostic:vim.Diagnostic): string`) A + function that takes a diagnostic as input and + returns a string. The return value is the text used + to display the diagnostic. Overrides the setting + from |vim.diagnostic.config()|. + • {prefix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`) + Prefix each diagnostic in the floating window: + • If a `function`, {i} is the index of the + diagnostic being evaluated and {total} is the + total number of diagnostics displayed in the + window. The function should return a `string` + which is prepended to each diagnostic in the + window as well as an (optional) highlight group + which will be used to highlight the prefix. + • If a `table`, it is interpreted as a + `[text, hl_group]` tuple as in |nvim_echo()| + • If a `string`, it is prepended to each diagnostic + in the window with no highlight. Overrides the + setting from |vim.diagnostic.config()|. + • {suffix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`) + Same as {prefix}, but appends the text to the + diagnostic instead of prepending it. Overrides the + setting from |vim.diagnostic.config()|. + • {focus_id}? (`string`) + +*vim.diagnostic.Opts.Signs* + + Fields: ~ + • {severity}? (`vim.diagnostic.SeverityFilter`) Only show virtual text + for diagnostics matching the given severity + |diagnostic-severity| + • {priority}? (`integer`, default: `10`) Base priority to use for + signs. When {severity_sort} is used, the priority of a + sign is adjusted based on its severity. Otherwise, all + signs use the same priority. + • {text}? (`table<vim.diagnostic.Severity,string>`) A table mapping + |diagnostic-severity| to the sign text to display in the + sign column. The default is to use `"E"`, `"W"`, `"I"`, + and `"H"` for errors, warnings, information, and hints, + respectively. Example: >lua + vim.diagnostic.config({ + signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } } + }) +< + • {numhl}? (`table<vim.diagnostic.Severity,string>`) A table mapping + |diagnostic-severity| to the highlight group used for the + line number where the sign is placed. + • {linehl}? (`table<vim.diagnostic.Severity,string>`) A table mapping + |diagnostic-severity| to the highlight group used for the + whole line the sign is placed in. + +*vim.diagnostic.Opts.Underline* + + Fields: ~ + • {severity}? (`vim.diagnostic.SeverityFilter`) Only underline + diagnostics matching the given severity + |diagnostic-severity|. + +*vim.diagnostic.Opts.VirtualText* + + Fields: ~ + • {severity}? (`vim.diagnostic.SeverityFilter`) Only show + virtual text for diagnostics matching the given + severity |diagnostic-severity| + • {source}? (`boolean|"if_many"`) Include the diagnostic + source in virtual text. Use `'if_many'` to only + show sources if there is more than one + diagnostic source in the buffer. Otherwise, any + truthy value means to always show the diagnostic + source. + • {spacing}? (`integer`) Amount of empty spaces inserted at + the beginning of the virtual text. + • {prefix}? (`string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)`) + Prepend diagnostic message with prefix. If a + `function`, {i} is the index of the diagnostic + being evaluated, and {total} is the total number + of diagnostics for the line. This can be used to + render diagnostic symbols or error codes. + • {suffix}? (`string|(fun(diagnostic:vim.Diagnostic): string)`) + Append diagnostic message with suffix. This can + be used to render an LSP diagnostic error code. + • {format}? (`fun(diagnostic:vim.Diagnostic): string`) The + return value is the text used to display the + diagnostic. Example: >lua + function(diagnostic) + if diagnostic.severity == vim.diagnostic.severity.ERROR then + return string.format("E: %s", diagnostic.message) + end + return diagnostic.message + end +< + • {hl_mode}? (`'replace'|'combine'|'blend'`) See + |nvim_buf_set_extmark()|. + • {virt_text}? (`{[1]:string,[2]:any}[]`) See + |nvim_buf_set_extmark()|. + • {virt_text_pos}? (`'eol'|'overlay'|'right_align'|'inline'`) See + |nvim_buf_set_extmark()|. + • {virt_text_win_col}? (`integer`) See |nvim_buf_set_extmark()|. + • {virt_text_hide}? (`boolean`) See |nvim_buf_set_extmark()|. + + config({opts}, {namespace}) *vim.diagnostic.config()* Configure diagnostic options globally or for a specific diagnostic namespace. @@ -368,115 +592,56 @@ config({opts}, {namespace}) *vim.diagnostic.config()* then virtual text will not be enabled for those diagnostics. - Note: ~ - • Each of the configuration options below accepts one of the following: - • `false`: Disable this feature - • `true`: Enable this feature, use default settings. - • `table`: Enable this feature with overrides. Use an empty table to - use default values. - • `function`: Function with signature (namespace, bufnr) that returns - any of the above. + Parameters: ~ + • {opts} (`vim.diagnostic.Opts?`) When omitted or `nil`, retrieve + the current configuration. Otherwise, a configuration + table (see |vim.diagnostic.Opts|). + • {namespace} (`integer?`) Update the options for the given namespace. + When omitted, update the global diagnostic options. + + Return: ~ + (`vim.diagnostic.Opts?`) Current diagnostic config if {opts} is + omitted. See |vim.diagnostic.Opts|. + +count({bufnr}, {opts}) *vim.diagnostic.count()* + Get current diagnostics count. Parameters: ~ - • {opts} (table|nil) When omitted or "nil", retrieve the current - configuration. Otherwise, a configuration table with the - following keys: - • underline: (default true) Use underline for - diagnostics. Options: - • severity: Only underline diagnostics matching the - given severity |diagnostic-severity| - - • virtual_text: (default true) Use virtual text for - diagnostics. If multiple diagnostics are set for a - namespace, one prefix per diagnostic + the last - diagnostic message are shown. In addition to the - options listed below, the "virt_text" options of - |nvim_buf_set_extmark()| may also be used here (e.g. - "virt_text_pos" and "hl_mode"). Options: - • severity: Only show virtual text for diagnostics - matching the given severity |diagnostic-severity| - • source: (boolean or string) Include the diagnostic - source in virtual text. Use "if_many" to only show - sources if there is more than one diagnostic source - in the buffer. Otherwise, any truthy value means to - always show the diagnostic source. - • spacing: (number) Amount of empty spaces inserted at - the beginning of the virtual text. - • prefix: (string or function) prepend diagnostic - message with prefix. If a function, it must have the - signature (diagnostic, i, total) -> string, where - {diagnostic} is of type |diagnostic-structure|, {i} - is the index of the diagnostic being evaluated, and - {total} is the total number of diagnostics for the - line. This can be used to render diagnostic symbols - or error codes. - • suffix: (string or function) Append diagnostic - message with suffix. If a function, it must have the - signature (diagnostic) -> string, where {diagnostic} - is of type |diagnostic-structure|. This can be used - to render an LSP diagnostic error code. - • format: (function) A function that takes a diagnostic - as input and returns a string. The return value is - the text used to display the diagnostic. Example: >lua - - function(diagnostic) - if diagnostic.severity == vim.diagnostic.severity.ERROR then - return string.format("E: %s", diagnostic.message) - end - return diagnostic.message - end -< + • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for + current buffer or nil for all buffers. + • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|. - • signs: (default true) Use signs for diagnostics. - Options: - • severity: Only show signs for diagnostics matching - the given severity |diagnostic-severity| - • priority: (number, default 10) Base priority to use - for signs. When {severity_sort} is used, the priority - of a sign is adjusted based on its severity. - Otherwise, all signs use the same priority. - - • float: Options for floating windows. See - |vim.diagnostic.open_float()|. - • update_in_insert: (default false) Update diagnostics in - Insert mode (if false, diagnostics are updated on - InsertLeave) - • severity_sort: (default false) Sort diagnostics by - severity. This affects the order in which signs and - virtual text are displayed. When true, higher - severities are displayed before lower severities (e.g. - ERROR is displayed before WARN). Options: - • reverse: (boolean) Reverse sort order - • {namespace} (integer|nil) Update the options for the given namespace. - When omitted, update the global diagnostic options. + Return: ~ + (`table`) Table with actually present severity values as keys (see + |diagnostic-severity|) and integer counts as values. disable({bufnr}, {namespace}) *vim.diagnostic.disable()* Disable diagnostics in the given buffer. Parameters: ~ - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. - When omitted, disable diagnostics in all buffers. - • {namespace} (integer|nil) Only disable diagnostics for the given + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When + omitted, disable diagnostics in all buffers. + • {namespace} (`integer?`) Only disable diagnostics for the given namespace. enable({bufnr}, {namespace}) *vim.diagnostic.enable()* Enable diagnostics in the given buffer. Parameters: ~ - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. - When omitted, enable diagnostics in all buffers. - • {namespace} (integer|nil) Only enable diagnostics for the given + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When + omitted, enable diagnostics in all buffers. + • {namespace} (`integer?`) Only enable diagnostics for the given namespace. fromqflist({list}) *vim.diagnostic.fromqflist()* Convert a list of quickfix items to a list of diagnostics. Parameters: ~ - • {list} table[] List of quickfix items from |getqflist()| or + • {list} (`table[]`) List of quickfix items from |getqflist()| or |getloclist()|. Return: ~ - Diagnostic [] array of |diagnostic-structure| + (`vim.Diagnostic[]`) See |vim.Diagnostic|. get({bufnr}, {opts}) *vim.diagnostic.get()* Get current diagnostics. @@ -485,96 +650,79 @@ get({bufnr}, {opts}) *vim.diagnostic.get()* diagnostics in a buffer, use |vim.diagnostic.set()|. Parameters: ~ - • {bufnr} (integer|nil) Buffer number to get diagnostics from. Use 0 - for current buffer or nil for all buffers. - • {opts} (table|nil) A table with the following keys: - • namespace: (number) Limit diagnostics to the given - namespace. - • lnum: (number) Limit diagnostics to the given line number. - • severity: See |diagnostic-severity|. + • {bufnr} (`integer?`) Buffer number to get diagnostics from. Use 0 for + current buffer or nil for all buffers. + • {opts} (`vim.diagnostic.GetOpts?`) See |vim.diagnostic.GetOpts|. Return: ~ - Diagnostic [] table A list of diagnostic items |diagnostic-structure|. Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are guaranteed to be present. + (`vim.Diagnostic[]`) Fields `bufnr`, `end_lnum`, `end_col`, and + `severity` are guaranteed to be present. See |vim.Diagnostic|. get_namespace({namespace}) *vim.diagnostic.get_namespace()* Get namespace metadata. Parameters: ~ - • {namespace} (integer) Diagnostic namespace + • {namespace} (`integer`) Diagnostic namespace Return: ~ - (table) Namespace metadata + (`vim.diagnostic.NS`) Namespace metadata. See |vim.diagnostic.NS|. get_namespaces() *vim.diagnostic.get_namespaces()* Get current diagnostic namespaces. Return: ~ - (table) A list of active diagnostic namespaces |vim.diagnostic|. + (`table<integer,vim.diagnostic.NS>`) List of active diagnostic + namespaces |vim.diagnostic|. get_next({opts}) *vim.diagnostic.get_next()* Get the next diagnostic closest to the cursor position. Parameters: ~ - • {opts} (table|nil) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - Diagnostic|nil Next diagnostic + (`vim.Diagnostic?`) Next diagnostic. See |vim.Diagnostic|. get_next_pos({opts}) *vim.diagnostic.get_next_pos()* Return the position of the next diagnostic in the current buffer. Parameters: ~ - • {opts} (table|nil) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - table|false Next diagnostic position as a (row, col) tuple or false if - no next diagnostic. + (`table|false`) Next diagnostic position as a `(row, col)` tuple or + false if no next diagnostic. get_prev({opts}) *vim.diagnostic.get_prev()* Get the previous diagnostic closest to the cursor position. Parameters: ~ - • {opts} nil|table See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - Diagnostic|nil Previous diagnostic + (`vim.Diagnostic?`) Previous diagnostic. See |vim.Diagnostic|. get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()* Return the position of the previous diagnostic in the current buffer. Parameters: ~ - • {opts} (table|nil) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. Return: ~ - table|false Previous diagnostic position as a (row, col) tuple or - false if there is no prior diagnostic + (`table|false`) Previous diagnostic position as a `(row, col)` tuple + or `false` if there is no prior diagnostic. goto_next({opts}) *vim.diagnostic.goto_next()* Move to the next diagnostic. Parameters: ~ - • {opts} (table|nil) Configuration table with the following keys: - • namespace: (number) Only consider diagnostics from the given - namespace. - • cursor_position: (cursor position) Cursor position as a - (row, col) tuple. See |nvim_win_get_cursor()|. Defaults to - the current cursor position. - • wrap: (boolean, default true) Whether to loop around file or - not. Similar to 'wrapscan'. - • severity: See |diagnostic-severity|. - • float: (boolean or table, default true) If "true", call - |vim.diagnostic.open_float()| after moving. If a table, pass - the table as the {opts} parameter to - |vim.diagnostic.open_float()|. Unless overridden, the float - will show diagnostics at the new cursor position (as if - "cursor" were passed to the "scope" option). - • win_id: (number, default 0) Window ID + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. goto_prev({opts}) *vim.diagnostic.goto_prev()* Move to the previous diagnostic in the current buffer. Parameters: ~ - • {opts} (table|nil) See |vim.diagnostic.goto_next()| + • {opts} (`vim.diagnostic.GotoOpts?`) See |vim.diagnostic.GotoOpts|. hide({namespace}, {bufnr}) *vim.diagnostic.hide()* Hide currently displayed diagnostics. @@ -587,22 +735,22 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()* |vim.diagnostic.disable()|. Parameters: ~ - • {namespace} (integer|nil) Diagnostic namespace. When omitted, hide diagnostics from all - namespaces. - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. - When omitted, hide diagnostics in all buffers. + • {namespace} (`integer?`) Diagnostic namespace. When omitted, hide + diagnostics from all namespaces. + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When + omitted, hide diagnostics in all buffers. is_disabled({bufnr}, {namespace}) *vim.diagnostic.is_disabled()* Check whether diagnostics are disabled in a given buffer. Parameters: ~ - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. - • {namespace} (integer|nil) Diagnostic namespace. When omitted, checks if all diagnostics are - disabled in {bufnr}. Otherwise, only checks if - diagnostics from {namespace} are disabled. + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. + • {namespace} (`integer?`) Diagnostic namespace. When omitted, checks + if all diagnostics are disabled in {bufnr}. Otherwise, + only checks if diagnostics from {namespace} are disabled. Return: ~ - (boolean) + (`boolean`) *vim.diagnostic.match()* match({str}, {pat}, {groups}, {severity_map}, {defaults}) @@ -612,7 +760,7 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) WARNING filename:27:3: Variable 'foo' does not exist < - This can be parsed into a diagnostic |diagnostic-structure| with: >lua + This can be parsed into |vim.Diagnostic| structure with: >lua local s = "WARNING filename:27:3: Variable 'foo' does not exist" local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" local groups = { "severity", "lnum", "col", "message" } @@ -620,75 +768,30 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) < Parameters: ~ - • {str} (string) String to parse diagnostics from. - • {pat} (string) Lua pattern with capture groups. - • {groups} (table) List of fields in a |diagnostic-structure| to - associate with captures from {pat}. - • {severity_map} (table) A table mapping the severity field from + • {str} (`string`) String to parse diagnostics from. + • {pat} (`string`) Lua pattern with capture groups. + • {groups} (`string[]`) List of fields in a |vim.Diagnostic| + structure to associate with captures from {pat}. + • {severity_map} (`table`) A table mapping the severity field from {groups} with an item from |vim.diagnostic.severity|. - • {defaults} (table|nil) Table of default values for any fields not + • {defaults} (`table?`) Table of default values for any fields not listed in {groups}. When omitted, numeric values default to 0 and "severity" defaults to ERROR. Return: ~ - Diagnostic|nil: |diagnostic-structure| or `nil` if {pat} fails to - match {str}. + (`vim.Diagnostic?`) |vim.Diagnostic| structure or `nil` if {pat} fails + to match {str}. -open_float({opts}, {...}) *vim.diagnostic.open_float()* +open_float({opts}) *vim.diagnostic.open_float()* Show diagnostics in a floating window. Parameters: ~ - • {opts} (table|nil) Configuration table with the same keys as - |vim.lsp.util.open_floating_preview()| in addition to the - following: - • bufnr: (number) Buffer number to show diagnostics from. - Defaults to the current buffer. - • namespace: (number) Limit diagnostics to the given namespace - • scope: (string, default "line") Show diagnostics from the - whole buffer ("buffer"), the current cursor line ("line"), - or the current cursor position ("cursor"). Shorthand - versions are also accepted ("c" for "cursor", "l" for - "line", "b" for "buffer"). - • pos: (number or table) If {scope} is "line" or "cursor", use - this position rather than the cursor position. If a number, - interpreted as a line number; otherwise, a (row, col) tuple. - • severity_sort: (default false) Sort diagnostics by severity. - Overrides the setting from |vim.diagnostic.config()|. - • severity: See |diagnostic-severity|. Overrides the setting - from |vim.diagnostic.config()|. - • header: (string or table) String to use as the header for - the floating window. If a table, it is interpreted as a - [text, hl_group] tuple. Overrides the setting from - |vim.diagnostic.config()|. - • source: (boolean or string) Include the diagnostic source in - the message. Use "if_many" to only show sources if there is - more than one source of diagnostics in the buffer. - Otherwise, any truthy value means to always show the - diagnostic source. Overrides the setting from - |vim.diagnostic.config()|. - • format: (function) A function that takes a diagnostic as - input and returns a string. The return value is the text - used to display the diagnostic. Overrides the setting from - |vim.diagnostic.config()|. - • prefix: (function, string, or table) Prefix each diagnostic - in the floating window. If a function, it must have the - signature (diagnostic, i, total) -> (string, string), where - {i} is the index of the diagnostic being evaluated and - {total} is the total number of diagnostics displayed in the - window. The function should return a string which is - prepended to each diagnostic in the window as well as an - (optional) highlight group which will be used to highlight - the prefix. If {prefix} is a table, it is interpreted as a - [text, hl_group] tuple as in |nvim_echo()|; otherwise, if - {prefix} is a string, it is prepended to each diagnostic in - the window with no highlight. Overrides the setting from - |vim.diagnostic.config()|. - • suffix: Same as {prefix}, but appends the text to the - diagnostic instead of prepending it. Overrides the setting - from |vim.diagnostic.config()|. + • {opts} (`vim.diagnostic.Opts.Float?`) See + |vim.diagnostic.Opts.Float|. - Return: ~ - integer|nil, integer|nil: ({float_bufnr}, {win_id}) + Return (multiple): ~ + (`integer?`) float_bufnr + (`integer?`) win_id reset({namespace}, {bufnr}) *vim.diagnostic.reset()* Remove all diagnostics from the given namespace. @@ -699,76 +802,78 @@ reset({namespace}, {bufnr}) *vim.diagnostic.reset()* re-displayed, use |vim.diagnostic.hide()|. Parameters: ~ - • {namespace} (integer|nil) Diagnostic namespace. When omitted, remove diagnostics from all - namespaces. - • {bufnr} (integer|nil) Remove diagnostics for the given buffer. + • {namespace} (`integer?`) Diagnostic namespace. When omitted, remove + diagnostics from all namespaces. + • {bufnr} (`integer?`) Remove diagnostics for the given buffer. When omitted, diagnostics are removed for all buffers. set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()* Set diagnostics for the given namespace and buffer. Parameters: ~ - • {namespace} (integer) The diagnostic namespace - • {bufnr} (integer) Buffer number - • {diagnostics} (table) A list of diagnostic items - |diagnostic-structure| - • {opts} (table|nil) Display options to pass to - |vim.diagnostic.show()| + • {namespace} (`integer`) The diagnostic namespace + • {bufnr} (`integer`) Buffer number + • {diagnostics} (`vim.Diagnostic[]`) See |vim.Diagnostic|. + • {opts} (`vim.diagnostic.Opts?`) Display options to pass to + |vim.diagnostic.show()|. See |vim.diagnostic.Opts|. setloclist({opts}) *vim.diagnostic.setloclist()* Add buffer diagnostics to the location list. Parameters: ~ - • {opts} (table|nil) Configuration table with the following keys: - • namespace: (number) Only add diagnostics from the given + • {opts} (`table?`) Configuration table with the following keys: + • {namespace}? (`integer`) Only add diagnostics from the given namespace. - • winnr: (number, default 0) Window number to set location - list for. - • open: (boolean, default true) Open the location list after - setting. - • title: (string) Title of the location list. Defaults to + • {winnr}? (`integer`, default: `0`) Window number to set + location list for. + • {open}? (`boolean`, default: `true`) Open the location list + after setting. + • {title}? (`string`) Title of the location list. Defaults to "Diagnostics". - • severity: See |diagnostic-severity|. + • {severity}? (`vim.diagnostic.Severity`) See + |diagnostic-severity|. setqflist({opts}) *vim.diagnostic.setqflist()* Add all diagnostics to the quickfix list. Parameters: ~ - • {opts} (table|nil) Configuration table with the following keys: - • namespace: (number) Only add diagnostics from the given + • {opts} (`table?`) Configuration table with the following keys: + • {namespace}? (`integer`) Only add diagnostics from the given namespace. - • open: (boolean, default true) Open quickfix list after - setting. - • title: (string) Title of quickfix list. Defaults to + • {open}? (`boolean`, default: `true`) Open quickfix list + after setting. + • {title}? (`string`) Title of quickfix list. Defaults to "Diagnostics". - • severity: See |diagnostic-severity|. + • {severity}? (`vim.diagnostic.Severity`) See + |diagnostic-severity|. *vim.diagnostic.show()* show({namespace}, {bufnr}, {diagnostics}, {opts}) Display diagnostics for the given namespace and buffer. Parameters: ~ - • {namespace} (integer|nil) Diagnostic namespace. When omitted, show diagnostics from all - namespaces. - • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. + • {namespace} (`integer?`) Diagnostic namespace. When omitted, show + diagnostics from all namespaces. + • {bufnr} (`integer?`) Buffer number, or 0 for current buffer. When omitted, show diagnostics in all buffers. - • {diagnostics} (table|nil) The diagnostics to display. When omitted, - use the saved diagnostics for the given namespace and - buffer. This can be used to display a list of - diagnostics without saving them or to display only a - subset of diagnostics. May not be used when {namespace} - or {bufnr} is nil. - • {opts} (table|nil) Display options. See - |vim.diagnostic.config()|. + • {diagnostics} (`vim.Diagnostic[]?`) The diagnostics to display. When + omitted, use the saved diagnostics for the given + namespace and buffer. This can be used to display a + list of diagnostics without saving them or to display + only a subset of diagnostics. May not be used when + {namespace} or {bufnr} is nil. See |vim.Diagnostic|. + • {opts} (`vim.diagnostic.Opts?`) Display options. See + |vim.diagnostic.Opts|. toqflist({diagnostics}) *vim.diagnostic.toqflist()* Convert a list of diagnostics to a list of quickfix items that can be passed to |setqflist()| or |setloclist()|. Parameters: ~ - • {diagnostics} (table) List of diagnostics |diagnostic-structure|. + • {diagnostics} (`vim.Diagnostic[]`) See |vim.Diagnostic|. Return: ~ - table[] of quickfix list items |setqflist-what| + (`table[]`) Quickfix list items |setqflist-what| + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index 7df2eb9742..1a4572e94a 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -1291,8 +1291,9 @@ b:browsefilter variable. You would most likely set b:browsefilter in a filetype plugin, so that the browse dialog would contain entries related to the type of file you are currently editing. Disadvantage: This makes it difficult to start editing a file of a different type. To overcome this, you -may want to add "All Files\t*.*\n" as the final filter, so that the user can -still access any desired file. +may want to add "All Files (*.*)\t*\n" as the final filter on Windows or "All +Files (*)\t*\n" on other platforms, so that the user can still access any +desired file. To avoid setting browsefilter when Vim does not actually support it, you can use has("browsefilter"): > diff --git a/runtime/doc/editorconfig.txt b/runtime/doc/editorconfig.txt index 7c6e8fb95f..a2281a7b7c 100644 --- a/runtime/doc/editorconfig.txt +++ b/runtime/doc/editorconfig.txt @@ -49,6 +49,8 @@ indent_size A number indicating the size of a single indent. Alternatively, use the value "tab" to use the value of the tab_width property. Sets the 'shiftwidth' and 'softtabstop' options. + If this value is not "tab" and the tab_width property + is not set, 'tabstop' is also set to this value. *editorconfig_insert_final_newline* insert_final_newline "true" or "false" to ensure the file always has a diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index a73932be00..ef416fe56f 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -252,10 +252,15 @@ List concatenation ~ *list-concatenation* Two lists can be concatenated with the "+" operator: > :let longlist = mylist + [5, 6] - :let mylist += [7, 8] + :let longlist = [5, 6] + mylist +To prepend or append an item, turn it into a list by putting [] around it. -To prepend or append an item, turn the item into a list by putting [] around -it. To change a list in-place, refer to |list-modification| below. +A list can be concatenated with another one in-place using |:let+=| or +|extend()|: > + :let mylist += [7, 8] + :call extend(mylist, [7, 8]) +< +See |list-modification| below for more about changing a list in-place. Sublist ~ @@ -374,6 +379,18 @@ To change part of a list you can specify the first and last item to be modified. The value must at least have the number of items in the range: > :let list[3:5] = [3, 4, 5] +To add items to a List in-place, you can use |:let+=| (|list-concatenation|): > + :let listA = [1, 2] + :let listA += [3, 4] +< +When two variables refer to the same List, changing one List in-place will +cause the referenced List to be changed in-place: > + :let listA = [1, 2] + :let listB = listA + :let listB += [3, 4] + :echo listA + [1, 2, 3, 4] +< Adding and removing items from a list is done with functions. Here are a few examples: > :call insert(list, 'a') " prepend item 'a' @@ -682,12 +699,15 @@ This calls Doit() with 0x11, 0x22 and 0x33. Blob concatenation ~ - + *blob-concatenation* Two blobs can be concatenated with the "+" operator: > :let longblob = myblob + 0z4455 + :let longblob = 0z4455 + myblob +< +A blob can be concatenated with another one in-place using |:let+=|: > :let myblob += 0z6677 - -To change a blob in-place see |blob-modification| below. +< +See |blob-modification| below for more about changing a blob in-place. Part of a blob ~ @@ -730,6 +750,18 @@ To change part of a blob you can specify the first and last byte to be modified. The value must have the same number of bytes in the range: > :let blob[3:5] = 0z334455 +To add items to a Blob in-place, you can use |:let+=| (|blob-concatenation|): > + :let blobA = 0z1122 + :let blobA += 0z3344 +< +When two variables refer to the same Blob, changing one Blob in-place will +cause the referenced Blob to be changed in-place: > + :let blobA = 0z1122 + :let blobB = blobA + :let blobB += 0z3344 + :echo blobA + 0z11223344 +< You can also use the functions |add()|, |remove()| and |insert()|. @@ -1765,624 +1797,9 @@ variables for each buffer. Use local buffer variables instead |b:var|. PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:* *E963* -Some variables can be set by the user, but the type cannot be changed. - - *v:argv* *argv-variable* -v:argv The command line arguments Vim was invoked with. This is a - list of strings. The first item is the Vim command. - See |v:progpath| for the command with full path. - - *v:char* *char-variable* -v:char Argument for evaluating 'formatexpr' and used for the typed - character when using <expr> in an abbreviation |:map-<expr>|. - It is also used by the |InsertCharPre| and |InsertEnter| events. - - *v:charconvert_from* *charconvert_from-variable* -v:charconvert_from - The name of the character encoding of a file to be converted. - Only valid while evaluating the 'charconvert' option. - - *v:charconvert_to* *charconvert_to-variable* -v:charconvert_to - The name of the character encoding of a file after conversion. - Only valid while evaluating the 'charconvert' option. - - *v:cmdarg* *cmdarg-variable* -v:cmdarg - The extra arguments ("++p", "++enc=", "++ff=") given to a file - read/write command. This is set before an autocommand event - for a file read/write command is triggered. There is a - leading space to make it possible to append this variable - directly after the read/write command. Note: "+cmd" isn't - included here, because it will be executed anyway. - - *v:collate* *collate-variable* -v:collate The current locale setting for collation order of the runtime - environment. This allows Vim scripts to be aware of the - current locale encoding. Technical: it's the value of - LC_COLLATE. When not using a locale the value is "C". - This variable can not be set directly, use the |:language| - command. - See |multi-lang|. - - *v:cmdbang* *cmdbang-variable* -v:cmdbang Set like v:cmdarg for a file read/write command. When a "!" - was used the value is 1, otherwise it is 0. Note that this - can only be used in autocommands. For user commands |<bang>| - can be used. - - *v:completed_item* *completed_item-variable* -v:completed_item - Dictionary containing the most recent |complete-items| after - |CompleteDone|. Empty if the completion failed, or after - leaving and re-entering insert mode. - Note: Plugins can modify the value to emulate the builtin - |CompleteDone| event behavior. - - *v:count* *count-variable* -v:count The count given for the last Normal mode command. Can be used - to get the count before a mapping. Read-only. Example: > - :map _x :<C-U>echo "the count is " .. v:count<CR> -< Note: The <C-U> is required to remove the line range that you - get when typing ':' after a count. - When there are two counts, as in "3d2w", they are multiplied, - just like what happens in the command, "d6w" for the example. - Also used for evaluating the 'formatexpr' option. - - *v:count1* *count1-variable* -v:count1 Just like "v:count", but defaults to one when no count is - used. - - *v:ctype* *ctype-variable* -v:ctype The current locale setting for characters of the runtime - environment. This allows Vim scripts to be aware of the - current locale encoding. Technical: it's the value of - LC_CTYPE. When not using a locale the value is "C". - This variable can not be set directly, use the |:language| - command. - See |multi-lang|. - - *v:dying* *dying-variable* -v:dying Normally zero. When a deadly signal is caught it's set to - one. When multiple signals are caught the number increases. - Can be used in an autocommand to check if Vim didn't - terminate normally. - Example: > - :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif -< Note: if another deadly signal is caught when v:dying is one, - VimLeave autocommands will not be executed. - - *v:exiting* *exiting-variable* -v:exiting Exit code, or |v:null| before invoking the |VimLeavePre| - and |VimLeave| autocmds. See |:q|, |:x| and |:cquit|. - Example: > - :au VimLeave * echo "Exit value is " .. v:exiting -< - *v:echospace* *echospace-variable* -v:echospace Number of screen cells that can be used for an `:echo` message - in the last screen line before causing the |hit-enter-prompt|. - Depends on 'showcmd', 'ruler' and 'columns'. You need to - check 'cmdheight' for whether there are full-width lines - available above the last line. - - *v:errmsg* *errmsg-variable* -v:errmsg Last given error message. - Modifiable (can be set). - Example: > - :let v:errmsg = "" - :silent! next - :if v:errmsg != "" - : ... handle error -< - *v:errors* *errors-variable* *assert-return* -v:errors Errors found by assert functions, such as |assert_true()|. - This is a list of strings. - The assert functions append an item when an assert fails. - The return value indicates this: a one is returned if an item - was added to v:errors, otherwise zero is returned. - To remove old results make it empty: > - :let v:errors = [] -< If v:errors is set to anything but a list it is made an empty - list by the assert function. - - *v:event* *event-variable* -v:event Dictionary of event data for the current |autocommand|. Valid - only during the event lifetime; storing or passing v:event is - invalid! Copy it instead: > - au TextYankPost * let g:foo = deepcopy(v:event) -< Keys vary by event; see the documentation for the specific - event, e.g. |DirChanged| or |TextYankPost|. - KEY DESCRIPTION ~ - abort Whether the event triggered during - an aborting condition (e.g. |c_Esc| or - |c_CTRL-C| for |CmdlineLeave|). - chan |channel-id| - cmdlevel Level of cmdline. - cmdtype Type of cmdline, |cmdline-char|. - cwd Current working directory. - inclusive Motion is |inclusive|, else exclusive. - scope Event-specific scope name. - operator Current |operator|. Also set for Ex - commands (unlike |v:operator|). For - example if |TextYankPost| is triggered - by the |:yank| Ex command then - `v:event.operator` is "y". - regcontents Text stored in the register as a - |readfile()|-style list of lines. - regname Requested register (e.g "x" for "xyy) - or the empty string for an unnamed - operation. - regtype Type of register as returned by - |getregtype()|. - visual Selection is visual (as opposed to, - e.g., via motion). - completed_item Current selected complete item on - |CompleteChanged|, Is `{}` when no complete - item selected. - height Height of popup menu on |CompleteChanged| - width width of popup menu on |CompleteChanged| - row Row count of popup menu on |CompleteChanged|, - relative to screen. - col Col count of popup menu on |CompleteChanged|, - relative to screen. - size Total number of completion items on - |CompleteChanged|. - scrollbar Is |v:true| if popup menu have scrollbar, or - |v:false| if not. - changed_window Is |v:true| if the event fired while - changing window (or tab) on |DirChanged|. - status Job status or exit code, -1 means "unknown". |TermClose| - - *v:exception* *exception-variable* -v:exception The value of the exception most recently caught and not - finished. See also |v:throwpoint| and |throw-variables|. - Example: > - :try - : throw "oops" - :catch /.*/ - : echo "caught " .. v:exception - :endtry -< Output: "caught oops". - - *v:false* *false-variable* -v:false Special value used to put "false" in JSON and msgpack. See - |json_encode()|. This value is converted to "v:false" when used - as a String (e.g. in |expr5| with string concatenation - operator) and to zero when used as a Number (e.g. in |expr5| - or |expr7| when used with numeric operators). Read-only. - - *v:fcs_reason* *fcs_reason-variable* -v:fcs_reason The reason why the |FileChangedShell| event was triggered. - Can be used in an autocommand to decide what to do and/or what - to set v:fcs_choice to. Possible values: - deleted file no longer exists - conflict file contents, mode or timestamp was - changed and buffer is modified - changed file contents has changed - mode mode of file changed - time only file timestamp changed - - *v:fcs_choice* *fcs_choice-variable* -v:fcs_choice What should happen after a |FileChangedShell| event was - triggered. Can be used in an autocommand to tell Vim what to - do with the affected buffer: - reload Reload the buffer (does not work if - the file was deleted). - edit Reload the buffer and detect the - values for options such as - 'fileformat', 'fileencoding', 'binary' - (does not work if the file was - deleted). - ask Ask the user what to do, as if there - was no autocommand. Except that when - only the timestamp changed nothing - will happen. - <empty> Nothing, the autocommand should do - everything that needs to be done. - The default is empty. If another (invalid) value is used then - Vim behaves like it is empty, there is no warning message. - - *v:fname* *fname-variable* -v:fname When evaluating 'includeexpr': the file name that was - detected. Empty otherwise. - - *v:fname_in* *fname_in-variable* -v:fname_in The name of the input file. Valid while evaluating: - option used for ~ - 'charconvert' file to be converted - 'diffexpr' original file - 'patchexpr' original file - And set to the swap file name for |SwapExists|. - - *v:fname_out* *fname_out-variable* -v:fname_out The name of the output file. Only valid while - evaluating: - option used for ~ - 'charconvert' resulting converted file [1] - 'diffexpr' output of diff - 'patchexpr' resulting patched file - [1] When doing conversion for a write command (e.g., ":w - file") it will be equal to v:fname_in. When doing conversion - for a read command (e.g., ":e file") it will be a temporary - file and different from v:fname_in. - - *v:fname_new* *fname_new-variable* -v:fname_new The name of the new version of the file. Only valid while - evaluating 'diffexpr'. - - *v:fname_diff* *fname_diff-variable* -v:fname_diff The name of the diff (patch) file. Only valid while - evaluating 'patchexpr'. - - *v:folddashes* *folddashes-variable* -v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed - fold. - Read-only in the |sandbox|. |fold-foldtext| - - *v:foldlevel* *foldlevel-variable* -v:foldlevel Used for 'foldtext': foldlevel of closed fold. - Read-only in the |sandbox|. |fold-foldtext| - - *v:foldend* *foldend-variable* -v:foldend Used for 'foldtext': last line of closed fold. - Read-only in the |sandbox|. |fold-foldtext| - - *v:foldstart* *foldstart-variable* -v:foldstart Used for 'foldtext': first line of closed fold. - Read-only in the |sandbox|. |fold-foldtext| - - *v:hlsearch* *hlsearch-variable* -v:hlsearch Variable that indicates whether search highlighting is on. - Setting it makes sense only if 'hlsearch' is enabled. Setting - this variable to zero acts like the |:nohlsearch| command, - setting it to one acts like > - let &hlsearch = &hlsearch -< Note that the value is restored when returning from a - function. |function-search-undo|. - - *v:insertmode* *insertmode-variable* -v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand - events. Values: - i Insert mode - r Replace mode - v Virtual Replace mode - - *v:key* *key-variable* -v:key Key of the current item of a |Dictionary|. Only valid while - evaluating the expression used with |map()| and |filter()|. - Read-only. - - *v:lang* *lang-variable* -v:lang The current locale setting for messages of the runtime - environment. This allows Vim scripts to be aware of the - current language. Technical: it's the value of LC_MESSAGES. - The value is system dependent. - This variable can not be set directly, use the |:language| - command. - It can be different from |v:ctype| when messages are desired - in a different language than what is used for character - encoding. See |multi-lang|. - - *v:lc_time* *lc_time-variable* -v:lc_time The current locale setting for time messages of the runtime - environment. This allows Vim scripts to be aware of the - current language. Technical: it's the value of LC_TIME. - This variable can not be set directly, use the |:language| - command. See |multi-lang|. - - *v:lnum* *lnum-variable* -v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr', - 'indentexpr' and 'statuscolumn' expressions, tab page number - for 'guitablabel' and 'guitabtooltip'. Only valid while one of - these expressions is being evaluated. Read-only when in the - |sandbox|. - - *v:lua* *lua-variable* -v:lua Prefix for calling Lua functions from expressions. - See |v:lua-call| for more information. - - *v:maxcol* *maxcol-variable* -v:maxcol Maximum line length. Depending on where it is used it can be - screen columns, characters or bytes. The value currently is - 2147483647 on all systems. - - *v:mouse_win* *mouse_win-variable* -v:mouse_win Window number for a mouse click obtained with |getchar()|. - First window has number 1, like with |winnr()|. The value is - zero when there was no mouse button click. - - *v:mouse_winid* *mouse_winid-variable* -v:mouse_winid |window-ID| for a mouse click obtained with |getchar()|. - The value is zero when there was no mouse button click. - - *v:mouse_lnum* *mouse_lnum-variable* -v:mouse_lnum Line number for a mouse click obtained with |getchar()|. - This is the text line number, not the screen line number. The - value is zero when there was no mouse button click. - - *v:mouse_col* *mouse_col-variable* -v:mouse_col Column number for a mouse click obtained with |getchar()|. - This is the screen column number, like with |virtcol()|. The - value is zero when there was no mouse button click. - - *v:msgpack_types* *msgpack_types-variable* -v:msgpack_types Dictionary containing msgpack types used by |msgpackparse()| - and |msgpackdump()|. All types inside dictionary are fixed - (not editable) empty lists. To check whether some list is one - of msgpack types, use |is| operator. - - *v:null* *null-variable* -v:null Special value used to put "null" in JSON and NIL in msgpack. - See |json_encode()|. This value is converted to "v:null" when - used as a String (e.g. in |expr5| with string concatenation - operator) and to zero when used as a Number (e.g. in |expr5| - or |expr7| when used with numeric operators). Read-only. - In some places `v:null` can be used for a List, Dict, etc. - that is not set. That is slightly different than an empty - List, Dict, etc. - - *v:numbermax* *numbermax-variable* -v:numbermax Maximum value of a number. - - *v:numbermin* *numbermin-variable* -v:numbermin Minimum value of a number (negative). - - *v:numbersize* *numbersize-variable* -v:numbersize Number of bits in a Number. This is normally 64, but on some - systems it may be 32. - - *v:oldfiles* *oldfiles-variable* -v:oldfiles List of file names that is loaded from the |shada| file on - startup. These are the files that Vim remembers marks for. - The length of the List is limited by the ' argument of the - 'shada' option (default is 100). - When the |shada| file is not used the List is empty. - Also see |:oldfiles| and |c_#<|. - The List can be modified, but this has no effect on what is - stored in the |shada| file later. If you use values other - than String this will cause trouble. - - *v:option_new* -v:option_new New value of the option. Valid while executing an |OptionSet| - autocommand. - *v:option_old* -v:option_old Old value of the option. Valid while executing an |OptionSet| - autocommand. Depending on the command used for setting and the - kind of option this is either the local old value or the - global old value. - *v:option_oldlocal* -v:option_oldlocal - Old local value of the option. Valid while executing an - |OptionSet| autocommand. - *v:option_oldglobal* -v:option_oldglobal - Old global value of the option. Valid while executing an - |OptionSet| autocommand. - *v:option_type* -v:option_type Scope of the set command. Valid while executing an - |OptionSet| autocommand. Can be either "global" or "local" - *v:option_command* -v:option_command - Command used to set the option. Valid while executing an - |OptionSet| autocommand. - value option was set via ~ - "setlocal" |:setlocal| or ":let l:xxx" - "setglobal" |:setglobal| or ":let g:xxx" - "set" |:set| or |:let| - "modeline" |modeline| - *v:operator* *operator-variable* -v:operator The last operator given in Normal mode. This is a single - character except for commands starting with <g> or <z>, - in which case it is two characters. Best used alongside - |v:prevcount| and |v:register|. Useful if you want to cancel - Operator-pending mode and then use the operator, e.g.: > - :omap O <Esc>:call MyMotion(v:operator)<CR> -< The value remains set until another operator is entered, thus - don't expect it to be empty. - v:operator is not set for |:delete|, |:yank| or other Ex - commands. - Read-only. - - *v:prevcount* *prevcount-variable* -v:prevcount The count given for the last but one Normal mode command. - This is the v:count value of the previous command. Useful if - you want to cancel Visual or Operator-pending mode and then - use the count, e.g.: > - :vmap % <Esc>:call MyFilter(v:prevcount)<CR> -< Read-only. - - *v:profiling* *profiling-variable* -v:profiling Normally zero. Set to one after using ":profile start". - See |profiling|. - - *v:progname* *progname-variable* -v:progname The name by which Nvim was invoked (with path removed). - Read-only. - - *v:progpath* *progpath-variable* -v:progpath Absolute path to the current running Nvim. - Read-only. - - *v:register* *register-variable* -v:register The name of the register in effect for the current normal mode - command (regardless of whether that command actually used a - register). Or for the currently executing normal mode mapping - (use this in custom commands that take a register). - If none is supplied it is the default register '"', unless - 'clipboard' contains "unnamed" or "unnamedplus", then it is - "*" or '+'. - Also see |getreg()| and |setreg()| - - *v:relnum* *relnum-variable* -v:relnum Relative line number for the 'statuscolumn' expression. - Read-only. - - *v:scrollstart* *scrollstart-variable* -v:scrollstart String describing the script or function that caused the - screen to scroll up. It's only set when it is empty, thus the - first reason is remembered. It is set to "Unknown" for a - typed command. - This can be used to find out why your script causes the - hit-enter prompt. - - *v:servername* *servername-variable* -v:servername Primary listen-address of Nvim, the first item returned by - |serverlist()|. Usually this is the named pipe created by Nvim - at |startup| or given by |--listen| (or the deprecated - |$NVIM_LISTEN_ADDRESS| env var). - - See also |serverstart()| |serverstop()|. - Read-only. - - *$NVIM* - $NVIM is set by |terminal| and |jobstart()|, and is thus - a hint that the current environment is a subprocess of Nvim. - Example: > - if $NVIM - echo nvim_get_chan_info(v:parent) - endif - -< Note the contents of $NVIM may change in the future. - -v:searchforward *v:searchforward* *searchforward-variable* - Search direction: 1 after a forward search, 0 after a - backward search. It is reset to forward when directly setting - the last search pattern, see |quote/|. - Note that the value is restored when returning from a - function. |function-search-undo|. - Read-write. - - *v:shell_error* *shell_error-variable* -v:shell_error Result of the last shell command. When non-zero, the last - shell command had an error. When zero, there was no problem. - This only works when the shell returns the error code to Vim. - The value -1 is often used when the command could not be - executed. Read-only. - Example: > - :!mv foo bar - :if v:shell_error - : echo 'could not rename "foo" to "bar"!' - :endif -< - *v:statusmsg* *statusmsg-variable* -v:statusmsg Last given status message. - Modifiable (can be set). - - *v:stderr* *stderr-variable* -v:stderr |channel-id| corresponding to stderr. The value is always 2; - use this variable to make your code more descriptive. - Unlike stdin and stdout (see |stdioopen()|), stderr is always - open for writing. Example: > - :call chansend(v:stderr, "error: toaster empty\n") -< - *v:swapname* *swapname-variable* -v:swapname Name of the swapfile found. - Only valid during |SwapExists| event. - Read-only. - - *v:swapchoice* *swapchoice-variable* -v:swapchoice |SwapExists| autocommands can set this to the selected choice - for handling an existing swapfile: - 'o' Open read-only - 'e' Edit anyway - 'r' Recover - 'd' Delete swapfile - 'q' Quit - 'a' Abort - The value should be a single-character string. An empty value - results in the user being asked, as would happen when there is - no SwapExists autocommand. The default is empty. - - *v:swapcommand* *swapcommand-variable* -v:swapcommand Normal mode command to be executed after a file has been - opened. Can be used for a |SwapExists| autocommand to have - another Vim open the file and jump to the right place. For - example, when jumping to a tag the value is ":tag tagname\r". - For ":edit +cmd file" the value is ":cmd\r". - - *v:t_TYPE* *v:t_bool* *t_bool-variable* -v:t_bool Value of |Boolean| type. Read-only. See: |type()| - *v:t_dict* *t_dict-variable* -v:t_dict Value of |Dictionary| type. Read-only. See: |type()| - *v:t_float* *t_float-variable* -v:t_float Value of |Float| type. Read-only. See: |type()| - *v:t_func* *t_func-variable* -v:t_func Value of |Funcref| type. Read-only. See: |type()| - *v:t_list* *t_list-variable* -v:t_list Value of |List| type. Read-only. See: |type()| - *v:t_number* *t_number-variable* -v:t_number Value of |Number| type. Read-only. See: |type()| - *v:t_string* *t_string-variable* -v:t_string Value of |String| type. Read-only. See: |type()| - *v:t_blob* *t_blob-variable* -v:t_blob Value of |Blob| type. Read-only. See: |type()| - - *v:termresponse* *termresponse-variable* -v:termresponse The value of the most recent OSC or DCS escape sequence - received by Nvim from the terminal. This can be read in a - |TermResponse| event handler after querying the terminal using - another escape sequence. - - *v:testing* *testing-variable* -v:testing Must be set before using `test_garbagecollect_now()`. - - *v:this_session* *this_session-variable* -v:this_session Full filename of the last loaded or saved session file. - Empty when no session file has been saved. See |:mksession|. - Modifiable (can be set). - - *v:throwpoint* *throwpoint-variable* -v:throwpoint The point where the exception most recently caught and not - finished was thrown. Not set when commands are typed. See - also |v:exception| and |throw-variables|. - Example: > - :try - : throw "oops" - :catch /.*/ - : echo "Exception from" v:throwpoint - :endtry -< Output: "Exception from test.vim, line 2" - - *v:true* *true-variable* -v:true Special value used to put "true" in JSON and msgpack. See - |json_encode()|. This value is converted to "v:true" when used - as a String (e.g. in |expr5| with string concatenation - operator) and to one when used as a Number (e.g. in |expr5| or - |expr7| when used with numeric operators). Read-only. - - *v:val* *val-variable* -v:val Value of the current item of a |List| or |Dictionary|. Only - valid while evaluating the expression used with |map()| and - |filter()|. Read-only. - - *v:version* *version-variable* -v:version Vim version number: major version times 100 plus minor - version. Vim 5.0 is 500, Vim 5.1 is 501. - Read-only. - Use |has()| to check the Nvim (not Vim) version: > - :if has("nvim-0.2.1") -< - - *v:virtnum* *virtnum-variable* -v:virtnum Virtual line number for the 'statuscolumn' expression. - Negative when drawing the status column for virtual lines, zero - when drawing an actual buffer line, and positive when drawing - the wrapped part of a buffer line. - Read-only. - - *v:vim_did_enter* *vim_did_enter-variable* -v:vim_did_enter 0 during startup, 1 just before |VimEnter|. - Read-only. - - *v:warningmsg* *warningmsg-variable* -v:warningmsg Last given warning message. - Modifiable (can be set). - *v:windowid* *windowid-variable* -v:windowid Application-specific window "handle" which may be set by any - attached UI. Defaults to zero. - Note: For Nvim |windows| use |winnr()| or |win_getid()|, see - |window-ID|. +The alphabetic list of all builtin variables and details are in a separate +help file: |vvars|. ============================================================================== 4. Builtin Functions *vim-function* *functions* @@ -2493,6 +1910,8 @@ This does NOT work: > :let {var} ..= {expr1} Like ":let {var} = {var} .. {expr1}". These fail if {var} was not set yet and when the type of {var} and {expr1} don't fit the operator. + `+=` modifies a |List| or a |Blob| in-place instead of + creating a new one. :let ${env-name} = {expr1} *:let-environment* *:let-$* @@ -4365,7 +3784,7 @@ have Vim execute random executables or may have forbidden to do so for specific filetypes by setting the "<filetype>_exec" variable (|plugin_exec|). It returns |TRUE| or |FALSE| to indicate whether the plugin should run the given -exectuable. It takes the following arguments: +executable. It takes the following arguments: argument type ~ diff --git a/runtime/doc/faq.txt b/runtime/doc/faq.txt new file mode 100644 index 0000000000..09bf829512 --- /dev/null +++ b/runtime/doc/faq.txt @@ -0,0 +1,485 @@ +*faq.txt* Nvim + + NVIM REFERENCE MANUAL + + +Frequently asked Questions *faq* + + Type |gO| to see the table of contents. + +============================================================================== +General Questions *faq-general* + + +WHERE SHOULD I PUT MY CONFIG (VIMRC)? ~ + +See |config|; you can copy (or symlink) your existing vimrc. |nvim-from-vim| + + +HOW STABLE IS THE DEVELOPMENT (PRE-RELEASE) VERSION? ~ + +The unstable (pre-release) +https://github.com/neovim/neovim/releases/tag/nightly version of Nvim +("HEAD", i.e. the `master` branch) is used to aggressively stage new features +and changes. It's usually stable, but will occasionally break your workflow. +We depend on HEAD users to report "blind spots" that were not caught by +automated tests. + +Use the stable (release) https://github.com/neovim/neovim/releases/latest +version for a more predictable experience. + + +CAN I USE RUBY-BASED VIM PLUGINS (E.G. LUSTYEXPLORER)? ~ + +Yes, starting with Nvim 0.1.5 PR #4980 +https://github.com/neovim/neovim/pull/4980 the legacy Vim `if_ruby` interface +is supported. + + +CAN I USE LUA-BASED VIM PLUGINS (E.G. NEOCOMPLETE)? ~ + +No. Starting with Nvim 0.2 PR #4411 +https://github.com/neovim/neovim/pull/4411 Lua is built-in, but the legacy +Vim `if_lua` interface is not supported. + + +HOW CAN I USE "TRUE COLOR" IN THE TERMINAL? ~ + +Truecolor (24bit colors) are enabled by default if a supporting terminal is +detected. If your terminal is not detected but you are sure it supports +truecolor, add this to your |init.vim|: +>vim + set termguicolors +< + +NVIM SHOWS WEIRD SYMBOLS (`�[2 q`) WHEN CHANGING MODES ~ + +This is a bug in your terminal emulator. It happens because Nvim sends +cursor-shape termcodes by default, if the terminal appears to be +xterm-compatible (`TERM=xterm-256color`). + +To workaround the issue, you can: + +- Use a different terminal emulator +- Disable 'guicursor' in your Nvim config: >vim + + :set guicursor= + " Workaround some broken plugins which set guicursor indiscriminately. + :autocmd OptionSet guicursor noautocmd set guicursor= +< +See also |$TERM| for recommended values of `$TERM`. + + +HOW TO CHANGE CURSOR SHAPE IN THE TERMINAL? ~ + +- For Nvim 0.1.7 or older: see the note about `NVIM_TUI_ENABLE_CURSOR_SHAPE` in `man nvim`. +- For Nvim 0.2 or newer: cursor styling is controlled by the 'guicursor' option. + - To _disable_ cursor-styling, set 'guicursor' to empty: >vim + + :set guicursor= + " Workaround some broken plugins which set guicursor indiscriminately. + :autocmd OptionSet guicursor noautocmd set guicursor= +< + - If you want a non-blinking cursor, use `blinkon0`. See 'guicursor'. + - 'guicursor' is enabled by default, unless Nvim thinks your terminal doesn't + support it. If you're sure that your terminal supports cursor-shaping, set + 'guicursor' in your |init.vim|, as described in 'guicursor'. +- The Vim terminal options |t_SI| and `t_EI` are ignored, like all other |t_xx| options. +- Old versions of libvte (gnome-terminal, roxterm, terminator, ...) do not + support cursor style control codes. #2537 + https://github.com/neovim/neovim/issues/2537 + + +HOW TO CHANGE CURSOR COLOR IN THE TERMINAL? ~ + +Cursor styling (shape, color, behavior) is controlled by 'guicursor', even in +the terminal. Cursor color (as opposed to shape) only works if +'termguicolors' is set. + +'guicursor' gives an example, but here's a more complicated example +which sets different colors in insert-mode and normal-mode: +>vim + :set termguicolors + :hi Cursor guifg=green guibg=green + :hi Cursor2 guifg=red guibg=red + :set guicursor=n-v-c:block-Cursor/lCursor,i-ci-ve:ver25-Cursor2/lCursor2,r-cr:hor20,o:hor50 +< + +CURSOR STYLE ISN'T RESTORED AFTER EXITING OR SUSPENDING AND RESUMING NVIM ~ + +Terminals do not provide a way to query the cursor style. Use autocommands to +manage the cursor style: +>vim + au VimEnter,VimResume * set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 + \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor + \,sm:block-blinkwait175-blinkoff150-blinkon175 + + au VimLeave,VimSuspend * set guicursor=a:block-blinkon0 +< + +CURSOR SHAPE DOESN'T CHANGE IN TMUX ~ + +tmux decides that, not Nvim. See |tui-cursor-shape| for a fix. + +See #3165 https://github.com/neovim/neovim/pull/3165 for discussion. + + +CURSOR FLICKER IN TMUX? ~ + +If cursor `_` appears and disappears very quickly when opening nvim without a +document under tmux, and you set |ctermbg| in `EndOfBuffer` and `Normal`, try +setting these to `NONE`: +>vim + hi EndOfBuffer ctermbg=NONE ctermfg=200 cterm=NONE + hi Normal ctermbg=NONE ctermfg=200 cterm=NONE +< + +WHAT HAPPENED TO --remote AND FRIENDS? ~ + +|--remote| is partly supported. |clientserver| + +If you require flags from Vim that are missing in Nvim, you can use +https://github.com/mhinz/neovim-remote instead. + +============================================================================== +Runtime issues *faq-runtime* + + +COPYING TO X11 PRIMARY SELECTION WITH THE MOUSE DOESN'T WORK ~ + +`clipboard=autoselect` is not implemented yet +https://github.com/neovim/neovim/issues/2325. You may find this workaround to +be useful: +>vim + vnoremap <LeftRelease> "*ygv + vnoremap <2-LeftRelease> "*ygv +< + +MY CTRL-H MAPPING DOESN'T WORK ~ + +This was fixed in Nvim 0.2. If you are running Nvim 0.1.7 or older, +adjust your terminal's "kbs" (key_backspace) terminfo entry: +>vim + infocmp $TERM | sed 's/kbs=^[hH]/kbs=\\177/' > $TERM.ti + tic $TERM.ti +< +(Feel free to delete the temporary `*.ti` file created after running the above +commands). + + +<HOME> OR SOME OTHER "SPECIAL" KEY DOESN'T WORK ~ + +Make sure |$TERM| is set correctly. + +- For screen or tmux, `$TERM` should be `screen-256color` (not `xterm-256color`!) +- In other cases if "256" does not appear in the string it's probably wrong. + Try `TERM=xterm-256color`. + + +:! AND SYSTEM() DO WEIRD THINGS WITH INTERACTIVE PROCESSES ~ + +Interactive commands are supported by |:terminal| in Nvim. But |:!| and +|system()| do not support interactive commands, primarily because Nvim UIs use +stdio for msgpack communication, but also for performance, reliability, and +consistency across platforms (see +https://vimhelp.org/gui_x11.txt.html#gui-pty). + +See also #1496 https://github.com/neovim/neovim/issues/1496 and #8217 +https://github.com/neovim/neovim/issues/8217#issuecomment-402152307. + + +PYTHON SUPPORT ISN'T WORKING ~ + +Run |:checkhealth| in Nvim for automatic diagnosis. + +Other hints: + +- The python `neovim` module was renamed to `pynvim` (long ago). +- If you're using pyenv or virtualenv for the `pynvim` module + https://pypi.python.org/pypi/pynvim/, you must set `g:python3_host_prog` to + the virtualenv's interpreter path. +- Read |provider-python|. +- Be sure you have the latest version of the `pynvim` Python module: >bash + + python -m pip install setuptools + python -m pip install --upgrade pynvim + python3 -m pip install --upgrade pynvim +< +- Try with `nvim -u NORC` to make sure your config (|init.vim|) isn't causing a + problem. If you get `E117: Unknown function`, that means there's a runtime + issue: |faq-runtime|. + + +:CHECKHEALTH REPORTS E5009: INVALID $VIMRUNTIME ~ + +This means `health#check()` couldn't load, which suggests that |$VIMRUNTIME| +or 'runtimepath' is broken. + +- |$VIMRUNTIME| must point to Nvim's runtime files, not Vim's. +- The |$VIMRUNTIME| directory contents should be readable by the current user. +- Verify that `:echo &runtimepath` contains the $VIMRUNTIME path. +- Check the output of: >vim + + :call health#check() + :verbose func health#check +< + +NEOVIM CAN'T FIND ITS RUNTIME ~ + +This is the case if `:help nvim` shows `E149: Sorry, no help for nvim`. + +Make sure that |$VIM| and |$VIMRUNTIME| point to Nvim's (as opposed to +Vim's) runtime by checking `:echo $VIM` and `:echo $VIMRUNTIME`. This should +give something like `/usr/share/nvim` resp. `/usr/share/nvim/runtime`. + +Also make sure that you don't accidentally overwrite your runtimepath +(`:set runtimepath?`), which includes the above |$VIMRUNTIME| by default (see +'runtimepath'). + + +NEOVIM IS SLOW ~ + + +Use a fast terminal emulator: + +- kitty https://github.com/kovidgoyal/kitty +- alacritty https://github.com/jwilm/alacritty + + +Use an optimized build: + +`:checkhealth nvim` should report one of these "build types": +> + Build type: RelWithDebInfo + Build type: MinSizeRel + Build type: Release +< +If it reports `Build type: Debug` and you're building Nvim from source, see +https://github.com/neovim/neovim/blob/master/BUILD.md. + + +COLORS AREN'T DISPLAYED CORRECTLY ~ + +Ensure that |$TERM| is set correctly. + +From a shell, run `TERM=xterm-256color nvim`. If colors are displayed +correctly, then export that value of `TERM` in your user profile (usually +`~/.profile`): +>bash + export TERM=xterm-256color +< +If you're using `tmux`, instead add this to your `tmux.conf`: +>bash + set -g default-terminal "tmux-256color" +< + +For GNU `screen`, configure your `.screenrc` +<https://wiki.archlinux.org/index.php/GNU_Screen#Use_256_colors>: +> + term screen-256color +< + +NOTE: Nvim ignores `t_Co` and other |t_xx| terminal codes. + + +NEOVIM CAN'T READ UTF-8 CHARACTERS ~ + +Run the following from the command line: +>bash + locale | grep -E '(LANG|LC_CTYPE|LC_ALL)=(.*\.)?(UTF|utf)-?8' +< +If there's no results, then you might not be using a UTF-8 locale. See the +following issues: +#1601 https://github.com/neovim/neovim/issues/1601 +#1858 https://github.com/neovim/neovim/issues/1858 +#2386 https://github.com/neovim/neovim/issues/2386 + + +ESC IN TMUX OR GNU SCREEN IS DELAYED ~ + +This is a common problem +https://www.google.com/?q=tmux%20vim%20escape%20delay in `tmux` / `screen` +(see also tmux/#131 +https://github.com/tmux/tmux/issues/131#issuecomment-145853211). The +corresponding timeout needs to be tweaked to a low value (10-20ms). + +`.tmux.conf`: +> + set -g escape-time 10 + # Or for tmux >= 2.6 + set -sg escape-time 10 +< +`.screenrc`: +> + maptimeout 10 +< + +"WHY DOESN'T THIS HAPPEN IN VIM?" + +It does happen (try `vim -N -u NONE`), but if you hit a key quickly after +ESC_ then Vim interprets the ESC as ESC instead of ALT (META). You won't +notice the delay unless you closely observe the cursor. The tradeoff is that +Vim won't understand ALT (META) key-chords, so for example `nnoremap <M-a>` +won't work. ALT (META) key-chords always work in Nvim. See also `:help +xterm-cursor-keys` in Vim. + +Nvim 0.3 mimics the Vim behavior while still fully supporting ALT mappings. See +|i_ALT|. + + +ESC IN GNU SCREEN IS LOST WHEN MOUSE MODE IS ENABLED ~ + +This happens because of a bug in screen https://savannah.gnu.org/bugs/?60196: +in mouse mode, screen assumes that `ESC` is part of a mouse sequence and will +wait an unlimited time for the rest of the sequence, regardless of +`maptimeout`. Until it's fixed in screen, there's no known workaround for +this other than double-pressing escape, which causes a single escape to be +passed through to Nvim. + + +CALLING INPUTLIST(), ECHOMSG, ... IN FILETYPE PLUGINS AND AUTOCMD DOES NOT WORK ~ + +#10008 https://github.com/neovim/neovim/issues/10008, +#10116 https://github.com/neovim/neovim/issues/10116, +#12288 https://github.com/neovim/neovim/issues/12288, +# vim/vim#4379 https://github.com/vim/vim/issues/4379. +This is because Nvim sets `shortmess+=F` by default. Vim behaves the same way +with `set shortmes+=F`. There are plans to improve this, but meanwhile as a +workaround, use `set shortmess-=F` or use `unsilent` as follows. +>vim + unsilent let var = inputlist(['1. item1', '2. item2']) + autocmd BufNewFile * unsilent echomsg 'The autocmd has been fired.' +< + +G:CLIPBOARD SETTINGS ARE NOT USED. ~ + +If the clipboard provider is already loaded, you will need to reload it after +configuration. Use the following configuration. +>vim + let g:clipboard = { 'name' : ... } + if exists('g:loaded_clipboard_provider') + unlet g:loaded_clipboard_provider + runtime autoload/provider/clipboard.vim + endif +< + +Or, if you want automatic reloading when assigning to |g:clipboard|, set +|init.vim| as follows. +>vim + function! s:clipboard_changed(...) abort + if exists('g:loaded_clipboard_provider') + unlet g:loaded_clipboard_provider + endif + runtime autoload/provider/clipboard.vim + endfunction + + if !exists('s:loaded") + call dictwatcheradd(g:, 'clipboard', function('s:clipboard_changed')) + endif + let s:loaded = v:true +< + +============================================================================== +Build issues *faq-build* + + +GENERAL BUILD ISSUES ~ + +Run `make distclean && make` to rule out a stale build environment causing the +failure. + + +SETTINGS IN LOCAL.MK DON'T TAKE EFFECT ~ + +CMake caches build settings, so you might need to run `rm -r build && make` +after modifying `local.mk`. + + +CMAKE ERRORS ~ + +`configure_file Problem configuring file` + +This is probably a permissions issue, which can happen if you run `make` as the +root user, then later run an unprivileged `make`. To fix this, run `rm -rf +build` and try again. + + +GENERATING HELPTAGS FAILED ~ + +If re-installation fails with "Generating helptags failed", try removing the +previously installed runtime directory (if `CMAKE_INSTALL_PREFIX` is not set +during building, the default is `/usr/local/share/nvim`): +>bash + rm -r /usr/local/share/nvim +< + +============================================================================== +Design *faq-design* + + +WHY NOT USE JSON FOR RPC? ~ + +- JSON cannot easily/efficiently handle binary data +- JSON specification is ambiguous: https://seriot.ch/parsing_json.php + + +WHY EMBED LUA INSTEAD OF X? ~ + +- Lua is a very small language, ideal for embedding. The biggest advantage of + Python/Ruby/etc is their huge collection of libraries, but that isn't + relevant for Nvim, where Nvim is the "batteries included" library: + introducing another stdlib would be redundant. +- Lua 5.1 is a complete language: the syntax is frozen. This is great for + backwards compatibility. +- Nvim also uses Lua internally as an alternative to C. Extra performance is + useful there, as opposed to a slow language like Python or Vim9script. +- LuaJIT is one of the fastest runtimes on the planet, 10x faster than Python + and "Vim9script" https://vimhelp.org/vim9.txt.html, 100x faster than + Vimscript. +- Python/JS cost more than Lua in terms of size and portability, and there are + already numerous Python/JS-based editors. So Python/JS would make Nvim + bigger and less portable, in exchange for a non-differentiating feature. + +See also: + +- Why Lua https://web.archive.org/web/20150219224654/https://blog.datamules.com/blog/2012/01/30/why-lua/ +- The Design of Lua https://cacm.acm.org/magazines/2018/11/232214-a-look-at-the-design-of-lua/fulltext +- Scripting architecture considerations http://oldblog.antirez.com/post/redis-and-scripting.html +- LuaJIT performance https://julialang.org/benchmarks/ +- Discussion of JavaScript vs Lua https://github.com/vim/vim/pull/5198#issuecomment-554693754 +- Discussion Python embedding https://lobste.rs/s/pnuak4/mercurial_s_journey_reflections_on#c_zshdwy + + +WHY LUA 5.1 INSTEAD OF LUA 5.3+? ~ + +Lua 5.1 is a different language than 5.3. The Lua org makes breaking changes +with every new version, so even if we switched (not upgraded, but switched) to +5.3 we gain nothing when they create the next new language in 5.4, 5.5, etc. +And we would lose LuaJIT, which is far more valuable than Lua 5.3+. + +Lua 5.1 is a complete language. To "upgrade" it, add libraries, not syntax. +Nvim itself already is a pretty good "stdlib" for Lua, and we will continue to +grow and enhance it. Changing the rules of Lua gains nothing in this context. + + +WILL NEOVIM TRANSLATE VIMSCRIPT TO LUA, INSTEAD OF EXECUTING VIMSCRIPT DIRECTLY? ~ + +- We are experimenting with vim9jit https://github.com/tjdevries/vim9jit to + transpile Vim9script (Vim9's Vimscript variant) to Lua and have used this to + port Vim9 plugins https://github.com/neovim/neovim/pull/21662 to Nvim Lua. +- We have no plans for transpiling legacy Vimscript. + + +ARE PLUGIN AUTHORS ENCOURAGED TO PORT THEIR PLUGINS FROM VIMSCRIPT TO LUA? DO YOU PLAN ON SUPPORTING VIMSCRIPT INDEFINITELY? (#1152) ~ + +We don't anticipate any reason to deprecate Vimscript, which is a valuable DSL +https://en.wikipedia.org/wiki/Domain-specific_language for text-editing tasks. +Maintaining Vimscript compatibility is less costly than a mass migration of +existing Vim plugins. + +Porting from Vimscript to Lua just for the heck of it gains nothing. Nvim is +emphatically a fork of Vim in order to leverage the work already spent on +thousands of Vim plugins, while enabling new types of plugins and +integrations. + +vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index ed21dc1c37..071a45c9c3 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -146,6 +146,7 @@ variables can be used to overrule the filetype used for certain extensions: `*.cls` g:filetype_cls `*.csh` g:filetype_csh |ft-csh-syntax| `*.dat` g:filetype_dat + `*.def` g:filetype_def `*.f` g:filetype_f |ft-forth-syntax| `*.frm` g:filetype_frm |ft-form-syntax| `*.fs` g:filetype_fs |ft-forth-syntax| @@ -167,6 +168,7 @@ variables can be used to overrule the filetype used for certain extensions: `*.sh` g:bash_is_sh |ft-sh-syntax| `*.tex` g:tex_flavor |ft-tex-plugin| `*.typ` g:filetype_typ + `*.v` g:filetype_v `*.w` g:filetype_w |ft-cweb-syntax| For a few filetypes the global variable is used only when the filetype could @@ -457,7 +459,7 @@ g:changelog_new_date_format %% insert a single '%' character %d insert the date from above %u insert the user from above - %p insert result of b:changelog_entry_prefix + %p insert result of b:changelog_entry_prefix %c where to position cursor when done The default is "%d %u\n\n\t* %p%c\n\n", which produces something like (| is where cursor will be, unless at @@ -471,7 +473,7 @@ g:changelog_new_entry_format The format used when creating a new entry. The following table describes special tokens in the string: - %p insert result of b:changelog_entry_prefix + %p insert result of b:changelog_entry_prefix %c where to position cursor when done The default is "\t*%c", which produces something similar to > @@ -525,13 +527,26 @@ under it. If not found, a new entry and item is prepended to the beginning of the Changelog. +ASCIIDOC *ft-asciidoc-plugin* + +To enable |folding| use this: > + let g:asciidoc_folding = 1 + +To disable nesting of folded headers use this: > + let g:asciidoc_foldnested = 0 + +To disable folding everything under the title use this: > + let asciidoc_fold_under_title = 0 + + FORTRAN *ft-fortran-plugin* Options: 'expandtab' is switched on to avoid tabs as required by the Fortran standards unless the user has set fortran_have_tabs in vimrc. -'textwidth' is set to 72 for fixed source format as required by the - Fortran standards and to 80 for free source format. +'textwidth' is set to 80 for fixed source format whereas it is set to 132 + for free source format. Setting the fortran_extended_line_length + variable increases the width to 132 for fixed source format. 'formatoptions' is set to break code and comment lines and to preserve long lines. You can format comments with |gq|. For further discussion of fortran_have_tabs and the method used for the @@ -684,7 +699,7 @@ To disable this behavior, set the following variable in your vimrc: > QUERY *ft-query-plugin* -Linting of tree-sitter queries for installed parsers using +Linting of treesitter queries for installed parsers using |vim.treesitter.query.lint()| is enabled by default on `BufEnter` and `BufWrite`. To change the events that trigger linting, use >lua @@ -734,6 +749,14 @@ To enable this behavior, set the following variable in your vimrc: > let g:rst_style = 1 +RNOWEB *ft-rnoweb-plugin* + +The 'formatexpr' option is set dynamically with different values for R code +and for LaTeX code. If you prefer that 'formatexpr' is not set, add to your +|vimrc|: > + let rnw_dynamic_comments = 0 + + RPM SPEC *ft-spec-plugin* Since the text for this plugin is rather long it has been put in a separate diff --git a/runtime/doc/ft_ada.txt b/runtime/doc/ft_ada.txt index 3b7d6a73dd..a9302cde97 100644 --- a/runtime/doc/ft_ada.txt +++ b/runtime/doc/ft_ada.txt @@ -172,7 +172,7 @@ GNAT OBJECT ~ *g:gnat.Make()* g:gnat.Make() Calls |g:gnat.Make_Command| and displays the result inside a - |quickfix| window. + |quickfix| window. *g:gnat.Pretty()* g:gnat.Pretty() diff --git a/runtime/doc/ft_sql.txt b/runtime/doc/ft_sql.txt index 68e26d2a5b..241fa4bd74 100644 --- a/runtime/doc/ft_sql.txt +++ b/runtime/doc/ft_sql.txt @@ -375,7 +375,7 @@ This command breaks down as: > 'sqlKeyword' - Display the items for the sqlKeyword highlight group 'sqlKeyword\w*' - A second option available with Vim 7.4 which - uses a regular expression to determine which + uses a regular expression to determine which syntax groups to use )<CR> - Execute the :let command <C-X><C-O> - Trigger the standard omni completion key stroke. diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index b8526b55e9..7545d2c621 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -47,6 +47,7 @@ ABOUT NVIM *reference_toc* *doc-file-list* *Q_ct* |news| News since the previous release |nvim| Transitioning from Vim |vim-differences| Nvim compared to Vim +|faq| Frequently Asked Questions |user-manual| User manual: How to accomplish editing tasks. |quickref| Overview of common commands |tutor| 30-minute interactive course for beginners @@ -167,7 +168,9 @@ DEVELOPING NVIM |dev| Development of Nvim |dev-style| Development style guidelines -|debug.txt| Debugging Vim itself +|dev-theme| Design guidelines (colorschemes etc.) +|dev-tools| Tools and techniques for developing Nvim +|dev-vimpatch| Merging patches from Vim Standard plugins ~ *standard-plugin-list* diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt index 853facdaa0..c20143bc6e 100644 --- a/runtime/doc/indent.txt +++ b/runtime/doc/indent.txt @@ -708,29 +708,29 @@ clojure-mode.el: FORTRAN *ft-fortran-indent* -Block if, select case, where, and forall constructs are indented. So are -type, interface, associate, block, and enum constructs. The indenting of -subroutines, functions, modules, and program blocks is optional. Comments, -labelled statements and continuation lines are indented if the Fortran is in -free source form, whereas they are not indented if the Fortran is in fixed -source form because of the left margin requirements. Hence manual indent -corrections will be necessary for labelled statements and continuation lines -when fixed source form is being used. For further discussion of the method -used for the detection of source format see |ft-fortran-syntax|. +Block if, select case, select type, select rank, where, forall, type, +interface, associate, block, enum, critical, and change team constructs are +indented. The indenting of subroutines, functions, modules, and program blocks +is optional. Comments, labeled statements, and continuation lines are indented +if the Fortran is in free source form, whereas they are not indented if the +Fortran is in fixed source form because of the left margin requirements. Hence +manual indent corrections will be necessary for labeled statements and +continuation lines when fixed source form is being used. For further +discussion of the method used for the detection of source format see +|ft-fortran-syntax|. Do loops ~ All do loops are left unindented by default. Do loops can be unstructured in -Fortran with (possibly multiple) loops ending on a labelled executable +Fortran with (possibly multiple) loops ending on a labeled executable statement of almost arbitrary type. Correct indentation requires -compiler-quality parsing. Old code with do loops ending on labelled statements -of arbitrary type can be indented with elaborate programs such as Tidy -(https://www.unb.ca/chem/ajit/f_tidy.htm). Structured do/continue loops are -also left unindented because continue statements are also used for purposes -other than ending a do loop. Programs such as Tidy can convert structured -do/continue loops to the do/enddo form. Do loops of the do/enddo variety can -be indented. If you use only structured loops of the do/enddo form, you should -declare this by setting the fortran_do_enddo variable in your vimrc as -follows > +compiler-quality parsing. Old code with do loops ending on labeled statements +of arbitrary type can be indented with elaborate programs such as Tidy. +Structured do/continue loops are also left unindented because continue +statements are used for purposes other than ending a do loop. Programs such +as Tidy can convert structured do/continue loops to the do/enddo form. Do +loops of the do/enddo variety can be indented. If you use only structured +loops of the do/enddo form, you should declare this by setting the +fortran_do_enddo variable in your vimrc as follows > let fortran_do_enddo=1 @@ -744,15 +744,14 @@ to get do loops indented in .f90 files and left alone in Fortran files with other extensions such as .for. Program units ~ -The indenting of program units (subroutines, functions, modules, and program -blocks) is enabled by default but can be suppressed if a lighter, screen-width -preserving indent style is desired. To suppress the indenting of program -units for all fortran files set the global fortran_indent_less variable in -your vimrc as follows > +Indenting of program units (subroutines, functions, modules, and program +blocks) can be increased by setting the variable fortran_indent_more and can +be decreased by setting the variable fortran_indent_less. These variables +can be set for all fortran files in your vimrc as follows > let fortran_indent_less=1 -A finer level of suppression can be achieved by setting the corresponding +A finer level of control can be achieved by setting the corresponding buffer-local variable as follows > let b:fortran_indent_less=1 @@ -1033,8 +1032,8 @@ r_indent_comment_column, as in the example below: let r_indent_comment_column = 30 < Any code after a line that ends with "<-" is indented. Emacs/ESS does not -indent the code if it is a top level function. If you prefer that the -Vim-R-plugin behaves like Emacs/ESS in this regard, put in your |vimrc|: +indent the code if it is a top-level function. If you prefer a behavior like +Emacs/ESS one in this regard, put in your |vimrc|: > let r_indent_ess_compatible = 1 < @@ -1227,5 +1226,11 @@ indent for a continuation line, a line that starts with a backslash: > Three times shiftwidth is the default value. +YAML *ft-yaml-indent* + +By default, the yaml indent script does not try to detect multiline scalars. +If you want to enable this, set the following variable: > + + let g:yaml_indent_multiline_scalar = 1 vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index 75b12fece2..c1a8aec40e 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -1146,6 +1146,8 @@ tag command action ~ |:>| :> shift lines one 'shiftwidth' right |:@| :@ execute contents of a register |:@@| :@@ repeat the previous ":@" +|:2match| :2mat[ch] define a second match to highlight +|:3match| :3mat[ch] define a third match to highlight |:Next| :N[ext] go to previous file in the argument list |:append| :a[ppend] append text |:abbreviate| :ab[breviate] enter abbreviation diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index ce2ec36ca3..34affb22e9 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -160,22 +160,22 @@ CTRL-R CTRL-O {register} *i_CTRL-R_CTRL-O* auto-indent. Does the same as pasting with the mouse |<MiddleMouse>|. When the register is linewise this will insert the text above the current line, like with `P`. - Does not replace characters! The '.' register (last inserted text) is still inserted as typed. After this command, the '.' register contains the command typed and not the text. I.e., the literals "^R^O" and not the text from the register. + Does not replace characters in |Replace-mode|! CTRL-R CTRL-P {register} *i_CTRL-R_CTRL-P* Insert the contents of a register literally and fix the indent, like |[<MiddleMouse>|. - Does not replace characters! The '.' register (last inserted text) is still inserted as typed. After this command, the '.' register contains the command typed and not the text. I.e., the literals "^R^P" and not the text from the register. + Does not replace characters in |Replace-mode|! *i_CTRL-T* CTRL-T Insert one shiftwidth of indent at the start of the current diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index 85115fc22b..c9211291d0 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -49,10 +49,9 @@ For more information try one of these: ============================================================================== Nvim on the interwebs *internet* - *www* *faq* *distribution* *download* + *www* *distribution* *download* Nvim home page: https://neovim.io/ - Nvim FAQ: https://github.com/neovim/neovim/wiki/FAQ Downloads: https://github.com/neovim/neovim/releases Vim FAQ: https://vimhelp.org/vim_faq.txt.html diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 5e97628f42..eb37cb2a6f 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -218,7 +218,7 @@ Each response handler has this signature: > - {ctx} (table) Table of calling state associated with the handler, with these keys: - {method} (string) |lsp-method| name. - - {client_id} (number) |vim.lsp.client| identifier. + - {client_id} (number) |vim.lsp.Client| identifier. - {bufnr} (Buffer) Buffer handle. - {params} (table|nil) Request parameters table. - {version} (number) Document version at time of @@ -366,31 +366,6 @@ https://microsoft.github.io/language-server-protocol/specifications/specificatio LSP notification shape: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage - *lsp-on-list-handler* - -`on_list` receives a table with: - - - `items` table[], structured like |setqflist-what| - - `title` string, title for the list. - - `context` table|nil. `ctx` from |lsp-handler| - -This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.: ->lua - local function on_list(options) - vim.fn.setqflist({}, ' ', options) - vim.api.nvim_command('cfirst') - end - - vim.lsp.buf.definition{on_list=on_list} - vim.lsp.buf.references(nil, {on_list=on_list}) -< -If you prefer loclist do something like this: ->lua - local function on_list(options) - vim.fn.setloclist(0, {}, ' ', options) - vim.api.nvim_command('lopen') - end -< ================================================================================ LSP HIGHLIGHT *lsp-highlight* @@ -480,23 +455,23 @@ Use |LspTokenUpdate| and |vim.lsp.semantic_tokens.highlight_token()| for more complex highlighting. The following groups are linked by default to standard |group-name|s: -> - @lsp.type.class Structure - @lsp.type.decorator Function - @lsp.type.enum Structure - @lsp.type.enumMember Constant - @lsp.type.function Function - @lsp.type.interface Structure - @lsp.type.macro Macro - @lsp.type.method Function - @lsp.type.namespace Structure - @lsp.type.parameter Identifier - @lsp.type.property Identifier - @lsp.type.struct Structure - @lsp.type.type Type - @lsp.type.typeParameter TypeDef - @lsp.type.variable Identifier -< + +@lsp.type.class Structure +@lsp.type.decorator Function +@lsp.type.enum Structure +@lsp.type.enumMember Constant +@lsp.type.function Function +@lsp.type.interface Structure +@lsp.type.macro Macro +@lsp.type.method Function +@lsp.type.namespace Structure +@lsp.type.parameter Identifier +@lsp.type.property Identifier +@lsp.type.struct Structure +@lsp.type.type Type +@lsp.type.typeParameter TypeDef +@lsp.type.variable Identifier + ============================================================================== EVENTS *lsp-events* @@ -557,7 +532,7 @@ LspNotify *LspNotify* LspProgress *LspProgress* Upon receipt of a progress notification from the server. Notifications can - be polled from a `progress` ring buffer of a |vim.lsp.client| or use + be polled from a `progress` ring buffer of a |vim.lsp.Client| or use |vim.lsp.status()| to get an aggregate message If the server sends a "work done progress", the `pattern` is set to `kind` @@ -583,7 +558,7 @@ LspRequest *LspRequest* will trigger with {type} == `cancel`. When used from Lua, the client ID, request ID, and request are sent in - the "data" table. See {requests} in |vim.lsp.client| for details on the + the "data" table. See {requests} in |vim.lsp.Client| for details on the {request} value. If the request type is `complete`, the request will be deleted from the client's pending requests table immediately after calling the event's callbacks. Example: >lua @@ -642,12 +617,12 @@ buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()* Without calling this, the server won't be notified of changes to a buffer. Parameters: ~ - • {bufnr} (integer) Buffer handle, or 0 for current - • {client_id} (integer) Client id + • {bufnr} (`integer`) Buffer handle, or 0 for current + • {client_id} (`integer`) Client id Return: ~ - (boolean) success `true` if client was attached successfully; `false` - otherwise + (`boolean`) success `true` if client was attached successfully; + `false` otherwise buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()* Detaches client from the specified buffer. Note: While the server is @@ -655,26 +630,26 @@ buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()* send notifications should it ignore this notification. Parameters: ~ - • {bufnr} (integer) Buffer handle, or 0 for current - • {client_id} (integer) Client id + • {bufnr} (`integer`) Buffer handle, or 0 for current + • {client_id} (`integer`) Client id buf_is_attached({bufnr}, {client_id}) *vim.lsp.buf_is_attached()* Checks if a buffer is attached for a particular client. Parameters: ~ - • {bufnr} (integer) Buffer handle, or 0 for current - • {client_id} (integer) the client id + • {bufnr} (`integer`) Buffer handle, or 0 for current + • {client_id} (`integer`) the client id buf_notify({bufnr}, {method}, {params}) *vim.lsp.buf_notify()* Send a notification to a server Parameters: ~ - • {bufnr} (integer|nil) The number of the buffer - • {method} (string) Name of the request method - • {params} (any) Arguments to send to the server + • {bufnr} (`integer?`) The number of the buffer + • {method} (`string`) Name of the request method + • {params} (`any`) Arguments to send to the server Return: ~ - (boolean) success true if any client returns true; false otherwise + (`boolean`) success true if any client returns true; false otherwise *vim.lsp.buf_request_all()* buf_request_all({bufnr}, {method}, {params}, {handler}) @@ -682,14 +657,15 @@ buf_request_all({bufnr}, {method}, {params}, {handler}) executes the `handler` callback with the combined result. Parameters: ~ - • {bufnr} (integer) Buffer handle, or 0 for current. - • {method} (string) LSP method name - • {params} (table|nil) Parameters to send to the server - • {handler} (function) Handler called after all requests are completed. - Server results are passed as a `client_id:result` map. + • {bufnr} (`integer`) Buffer handle, or 0 for current. + • {method} (`string`) LSP method name + • {params} (`table?`) Parameters to send to the server + • {handler} (`function`) Handler called after all requests are + completed. Server results are passed as a + `client_id:result` map. Return: ~ - (function) cancel Function that cancels all requests. + (`function`) cancel Function that cancels all requests. *vim.lsp.buf_request_sync()* buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) @@ -697,89 +673,29 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the result. Parameters are the same as |vim.lsp.buf_request_all()| but the - result is different. Waits a maximum of {timeout_ms} (default 1000) ms. + result is different. Waits a maximum of {timeout_ms}. Parameters: ~ - • {bufnr} (integer) Buffer handle, or 0 for current. - • {method} (string) LSP method name - • {params} (table|nil) Parameters to send to the server - • {timeout_ms} (integer|nil) Maximum time in milliseconds to wait for a - result. Defaults to 1000 + • {bufnr} (`integer`) Buffer handle, or 0 for current. + • {method} (`string`) LSP method name + • {params} (`table?`) Parameters to send to the server + • {timeout_ms} (`integer?`, default: `1000`) Maximum time in + milliseconds to wait for a result. Return (multiple): ~ - (table) result Map of client_id:request_result. - (string|nil) err On timeout, cancel, or error, `err` is a string + (`table<integer, {err: lsp.ResponseError, result: any}>?`) result Map + of client_id:request_result. + (`string?`) err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil. -client() *vim.lsp.client* - LSP client object. You can get an active client object via - |vim.lsp.get_client_by_id()| or |vim.lsp.get_clients()|. - - • Methods: - • request(method, params, [handler], bufnr) Sends a request to the - server. This is a thin wrapper around {client.rpc.request} with some - additional checking. If {handler} is not specified, If one is not - found there, then an error will occur. Returns: {status}, - {[client_id]}. {status} is a boolean indicating if the notification - was successful. If it is `false`, then it will always be `false` (the - client has shutdown). If {status} is `true`, the function returns - {request_id} as the second result. You can use this with - `client.cancel_request(request_id)` to cancel the request. - • request_sync(method, params, timeout_ms, bufnr) Sends a request to the - server and synchronously waits for the response. This is a wrapper - around {client.request} Returns: { err=err, result=result }, a - dictionary, where `err` and `result` come from the |lsp-handler|. On - timeout, cancel or error, returns `(nil, err)` where `err` is a string - describing the failure reason. If the request was unsuccessful returns - `nil`. - • notify(method, params) Sends a notification to an LSP server. Returns: - a boolean to indicate if the notification was successful. If it is - false, then it will always be false (the client has shutdown). - • cancel_request(id) Cancels a request with a given request id. Returns: - same as `notify()`. - • stop([force]) Stops a client, optionally with force. By default, it - will just ask the server to shutdown without force. If you request to - stop a client which has previously been requested to shutdown, it will - automatically escalate and force shutdown. - • is_stopped() Checks whether a client is stopped. Returns: true if the - client is fully stopped. - • on_attach(client, bufnr) Runs the on_attach function from the client's - config if it was defined. Useful for buffer-local setup. - - • Members - • {id} (number): The id allocated to the client. - • {name} (string): If a name is specified on creation, that will be - used. Otherwise it is just the client id. This is used for logs and - messages. - • {rpc} (table): RPC client object, for low level interaction with the - client. See |vim.lsp.rpc.start()|. - • {offset_encoding} (string): The encoding used for communicating with - the server. You can modify this in the `config`'s `on_init` method - before text is sent to the server. - • {handlers} (table): The handlers used by the client as described in - |lsp-handler|. - • {requests} (table): The current pending requests in flight to the - server. Entries are key-value pairs with the key being the request ID - while the value is a table with `type`, `bufnr`, and `method` - key-value pairs. `type` is either "pending" for an active request, or - "cancel" for a cancel request. It will be "complete" ephemerally while - executing |LspRequest| autocmds when replies are received from the - server. - • {config} (table): copy of the table that was passed by the user to - |vim.lsp.start_client()|. - • {server_capabilities} (table): Response from the server sent on - `initialize` describing the server's capabilities. - • {progress} A ring buffer (|vim.ringbuf()|) containing progress - messages sent by the server. - client_is_stopped({client_id}) *vim.lsp.client_is_stopped()* Checks whether a client is stopped. Parameters: ~ - • {client_id} (integer) + • {client_id} (`integer`) Return: ~ - (boolean) stopped true if client is stopped, false otherwise. + (`boolean`) stopped true if client is stopped, false otherwise. commands *vim.lsp.commands* Registry for client side commands. This is an extension point for plugins @@ -803,68 +719,67 @@ formatexpr({opts}) *vim.lsp.formatexpr()* Provides an interface between the built-in client and a `formatexpr` function. - Currently only supports a single client. This can be set via `setlocal - formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in - `on_attach` via `vim.bo[bufnr].formatexpr = - 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`. + Currently only supports a single client. This can be set via + `setlocal formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in + `on_attach` via + `vim.bo[bufnr].formatexpr = 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`. Parameters: ~ - • {opts} (table) options for customizing the formatting expression - which takes the following optional keys: - • timeout_ms (default 500ms). The timeout period for the - formatting request. + • {opts} (`table?`) A table with the following fields: + • {timeout_ms} (`integer`, default: 500ms) The timeout period + for the formatting request.. *vim.lsp.get_buffers_by_client_id()* get_buffers_by_client_id({client_id}) Returns list of buffers attached to client_id. Parameters: ~ - • {client_id} (integer) client id + • {client_id} (`integer`) client id Return: ~ - integer[] buffers list of buffer ids + (`integer[]`) buffers list of buffer ids get_client_by_id({client_id}) *vim.lsp.get_client_by_id()* Gets a client by id, or nil if the id is invalid. The returned client may not yet be fully initialized. Parameters: ~ - • {client_id} (integer) client id + • {client_id} (`integer`) client id Return: ~ - (nil|lsp.Client) client rpc object + (`vim.lsp.Client?`) client rpc object get_clients({filter}) *vim.lsp.get_clients()* Get active clients. Parameters: ~ - • {filter} (table|nil) A table with key-value pairs used to filter the - returned clients. The available keys are: - • id (number): Only return clients with the given id - • bufnr (number): Only return clients attached to this + • {filter} (`table?`) Key-value pairs used to filter the returned + clients. + • {id}? (`integer`) Only return clients with the given id + • {bufnr}? (`integer`) Only return clients attached to this buffer - • name (string): Only return clients with the given name - • method (string): Only return clients supporting the given - method + • {name}? (`string`) Only return clients with the given name + • {method}? (`string`) Only return clients supporting the + given method Return: ~ - lsp.Client []: List of |vim.lsp.client| objects + (`vim.lsp.Client[]`) List of |vim.lsp.Client| objects get_log_path() *vim.lsp.get_log_path()* Gets the path of the logfile used by the LSP client. Return: ~ - (string) path to log file + (`string`) path to log file omnifunc({findstart}, {base}) *vim.lsp.omnifunc()* Implements 'omnifunc' compatible LSP completion. Parameters: ~ - • {findstart} (integer) 0 or 1, decides behavior - • {base} (integer) findstart=0, text to match against + • {findstart} (`integer`) 0 or 1, decides behavior + • {base} (`integer`) findstart=0, text to match against Return: ~ - integer|table Decided by {findstart}: + (`integer|table`) Decided by {findstart}: • findstart=0: column where the completion starts, or -2 or -3 • findstart=1: list of matches (actually just calls |complete()|) @@ -883,7 +798,7 @@ set_log_level({level}) *vim.lsp.set_log_level()* Use `lsp.log_levels` for reverse lookup. Parameters: ~ - • {level} (integer|string) the case insensitive level name or number + • {level} (`integer|string`) the case insensitive level name or number See also: ~ • |vim.lsp.log_levels| @@ -903,12 +818,10 @@ start({config}, {opts}) *vim.lsp.start()* See |vim.lsp.start_client()| for all available options. The most important are: - • `name` arbitrary name for the LSP client. Should be unique per language server. - • `cmd` command (in list form) used to start the language server. Must be - absolute, or found on `$PATH`. Shell constructs like `~` are not - expanded. + • `cmd` command string[] or function, described at + |vim.lsp.start_client()|. • `root_dir` path to the project root. By default this is used to decide if an existing client should be re-used. The example above uses |vim.fs.find()| and |vim.fs.dirname()| to detect the root by traversing @@ -928,135 +841,29 @@ start({config}, {opts}) *vim.lsp.start()* `ftplugin/<filetype_name>.lua` (See |ftplugin-name|) Parameters: ~ - • {config} (table) Same configuration as documented in - |vim.lsp.start_client()| - • {opts} (nil|lsp.StartOpts) Optional keyword arguments: - • reuse_client (fun(client: client, config: table): boolean) + • {config} (`vim.lsp.ClientConfig`) Configuration for the server. See + |vim.lsp.ClientConfig|. + • {opts} (`table?`) Optional keyword arguments + • {reuse_client} + (`fun(client: vim.lsp.Client, config: table): boolean`) Predicate used to decide if a client should be re-used. Used on all running clients. The default implementation re-uses a client if name and root_dir matches. - • bufnr (number) Buffer handle to attach to if starting or - re-using a client (0 for current). + • {bufnr} (`integer`) Buffer handle to attach to if starting + or re-using a client (0 for current). Return: ~ - (integer|nil) client_id + (`integer?`) client_id start_client({config}) *vim.lsp.start_client()* Starts and initializes a client with the given configuration. - Field `cmd` in {config} is required. - - Parameters: ~ - • {config} ( lsp.ClientConfig ) Configuration for the server: - • cmd: (string[]|fun(dispatchers: table):table) command a - list of strings treated like |jobstart()|. The command - must launch the language server process. `cmd` can also be - a function that creates an RPC client. The function - receives a dispatchers table and must return a table with - the functions `request`, `notify`, `is_closing` and - `terminate` See |vim.lsp.rpc.request()| and - |vim.lsp.rpc.notify()| For TCP there is a built-in rpc - client factory: |vim.lsp.rpc.connect()| - • cmd_cwd: (string, default=|getcwd()|) Directory to launch - the `cmd` process. Not related to `root_dir`. - • cmd_env: (table) Environment flags to pass to the LSP on - spawn. Must be specified using a table. Non-string values - are coerced to string. Example: > - - { PORT = 8080; HOST = "0.0.0.0"; } -< - • detached: (boolean, default true) Daemonize the server - process so that it runs in a separate process group from - Nvim. Nvim will shutdown the process on exit, but if Nvim - fails to exit cleanly this could leave behind orphaned - server processes. - • workspace_folders: (table) List of workspace folders - passed to the language server. For backwards compatibility - rootUri and rootPath will be derived from the first - workspace folder in this list. See `workspaceFolders` in - the LSP spec. - • capabilities: Map overriding the default capabilities - defined by |vim.lsp.protocol.make_client_capabilities()|, - passed to the language server on initialization. Hint: use - make_client_capabilities() and modify its result. - • Note: To send an empty dictionary use - |vim.empty_dict()|, else it will be encoded as an array. - - • handlers: Map of language server method names to - |lsp-handler| - • settings: Map with language server specific settings. - These are returned to the language server if requested via - `workspace/configuration`. Keys are case-sensitive. - • commands: table Table that maps string of clientside - commands to user-defined functions. Commands passed to - start_client take precedence over the global command - registry. Each key must be a unique command name, and the - value is a function which is called if any LSP action - (code action, code lenses, ...) triggers the command. - • init_options Values to pass in the initialization request - as `initializationOptions`. See `initialize` in the LSP - spec. - • name: (string, default=client-id) Name in log messages. - • get_language_id: function(bufnr, filetype) -> language ID - as string. Defaults to the filetype. - • offset_encoding: (default="utf-16") One of "utf-8", - "utf-16", or "utf-32" which is the encoding that the LSP - server expects. Client does not verify this is correct. - • on_error: Callback with parameters (code, ...), invoked - when the client operation throws an error. `code` is a - number describing the error. Other arguments may be passed - depending on the error kind. See - `vim.lsp.rpc.client_errors` for possible errors. Use - `vim.lsp.rpc.client_errors[code]` to get human-friendly - name. - • before_init: Callback with parameters (initialize_params, - config) invoked before the LSP "initialize" phase, where - `params` contains the parameters being sent to the server - and `config` is the config that was passed to - |vim.lsp.start_client()|. You can use this to modify - parameters before they are sent. - • on_init: Callback (client, initialize_result) invoked - after LSP "initialize", where `result` is a table of - `capabilities` and anything else the server may send. For - example, clangd sends `initialize_result.offsetEncoding` - if `capabilities.offsetEncoding` was sent to it. You can - only modify the `client.offset_encoding` here before any - notifications are sent. Most language servers expect to be - sent client specified settings after initialization. Nvim - does not make this assumption. A - `workspace/didChangeConfiguration` notification should be - sent to the server during on_init. - • on_exit Callback (code, signal, client_id) invoked on - client exit. - • code: exit code of the process - • signal: number describing the signal used to terminate - (if any) - • client_id: client handle - - • on_attach: Callback (client, bufnr) invoked when client - attaches to a buffer. - • trace: ("off" | "messages" | "verbose" | nil) passed - directly to the language server in the initialize request. - Invalid/empty values will default to "off" - • flags: A table with flags for the client. The current - (experimental) flags are: - • allow_incremental_sync (bool, default true): Allow using - incremental sync for buffer edits - • debounce_text_changes (number, default 150): Debounce - didChange notifications to the server by the given - number in milliseconds. No debounce occurs if nil - • exit_timeout (number|boolean, default false): - Milliseconds to wait for server to exit cleanly after - sending the "shutdown" request before sending kill -15. - If set to false, nvim exits immediately after sending - the "shutdown" request to the server. - - • root_dir: (string) Directory where the LSP server will - base its workspaceFolders, rootUri, and rootPath on - initialization. + Parameters: ~ + • {config} (`vim.lsp.ClientConfig`) Configuration for the server. See + |vim.lsp.ClientConfig|. Return: ~ - (integer|nil) client_id. |vim.lsp.get_client_by_id()| Note: client may + (`integer?`) client_id |vim.lsp.get_client_by_id()| Note: client may not be fully initialized. Use `on_init` to do any actions once the client has been initialized. @@ -1065,12 +872,12 @@ status() *vim.lsp.status()* a string. Empty if there are no clients or if no new messages Return: ~ - (string) + (`string`) stop_client({client_id}, {force}) *vim.lsp.stop_client()* Stops a client(s). - You can also use the `stop()` function on a |vim.lsp.client| object. To + You can also use the `stop()` function on a |vim.lsp.Client| object. To stop all clients: >lua vim.lsp.stop_client(vim.lsp.get_clients()) < @@ -1079,9 +886,9 @@ stop_client({client_id}, {force}) *vim.lsp.stop_client()* for this client, then force-shutdown is attempted. Parameters: ~ - • {client_id} integer|table id or |vim.lsp.client| object, or list - thereof - • {force} (boolean|nil) shutdown forcefully + • {client_id} (`integer|vim.lsp.Client`) id or |vim.lsp.Client| object, + or list thereof + • {force} (`boolean?`) shutdown forcefully tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()* Provides an interface between the built-in client and 'tagfunc'. @@ -1092,29 +899,325 @@ tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()* LSP servers, falls back to using built-in tags. Parameters: ~ - • {pattern} (string) Pattern used to find a workspace symbol - • {flags} (string) See |tag-function| + • {pattern} (`string`) Pattern used to find a workspace symbol + • {flags} (`string`) See |tag-function| Return: ~ - table[] tags A list of matching tags + (`table[]`) tags A list of matching tags with({handler}, {override_config}) *vim.lsp.with()* Function to manage overriding defaults for LSP handlers. Parameters: ~ - • {handler} (function) See |lsp-handler| - • {override_config} (table) Table containing the keys to override + • {handler} (`lsp.Handler`) See |lsp-handler| + • {override_config} (`table`) Table containing the keys to override behavior of the {handler} ============================================================================== +Lua module: vim.lsp.client *lsp-client* + +*vim.lsp.Client* + + Fields: ~ + • {id} (`integer`) The id allocated to the client. + • {name} (`string`) If a name is specified on creation, + that will be used. Otherwise it is just the + client id. This is used for logs and messages. + • {rpc} (`vim.lsp.rpc.PublicClient`) RPC client + object, for low level interaction with the + client. See |vim.lsp.rpc.start()|. + • {offset_encoding} (`string`) The encoding used for communicating + with the server. You can modify this in the + `config`'s `on_init` method before text is + sent to the server. + • {handlers} (`table<string,lsp.Handler>`) The handlers + used by the client as described in + |lsp-handler|. + • {requests} (`table<integer,{ type: string, bufnr: integer, method: string}>`) + The current pending requests in flight to the + server. Entries are key-value pairs with the + key being the request id while the value is a + table with `type`, `bufnr`, and `method` + key-value pairs. `type` is either "pending" + for an active request, or "cancel" for a + cancel request. It will be "complete" + ephemerally while executing |LspRequest| + autocmds when replies are received from the + server. + • {config} (`vim.lsp.ClientConfig`) copy of the table + that was passed by the user to + |vim.lsp.start_client()|. See + |vim.lsp.ClientConfig|. + • {server_capabilities} (`lsp.ServerCapabilities?`) Response from the + server sent on `initialize` describing the + server's capabilities. + • {progress} (`vim.lsp.Client.Progress`) A ring buffer + (|vim.ringbuf()|) containing progress messages + sent by the server. See + |vim.lsp.Client.Progress|. + • {initialized} (`true?`) + • {workspace_folders} (`lsp.WorkspaceFolder[]?`) The workspace + folders configured in the client when the + server starts. This property is only available + if the client supports workspace folders. It + can be `null` if the client supports workspace + folders but none are configured. + • {root_dir} (`string`) + • {attached_buffers} (`table<integer,true>`) + • {commands} (`table<string,fun(command: lsp.Command, ctx: table)>`) + Table of command name to function which is + called if any LSP action (code action, code + lenses, ...) triggers the command. Client + commands take precedence over the global + command registry. + • {settings} (`table`) Map with language server specific + settings. These are returned to the language + server if requested via + `workspace/configuration`. Keys are + case-sensitive. + • {flags} (`table`) A table with flags for the client. + The current (experimental) flags are: + • {allow_incremental_sync}? (`boolean`) Allow + using incremental sync for buffer edits + (defailt: `true`) + • {debounce_text_changes} (`integer`, default: + `150`) Debounce `didChange` notifications to + the server by the given number in + milliseconds. No debounce occurs if `nil`. + • {exit_timeout} (`integer|false`, default: + `false`) Milliseconds to wait for server to + exit cleanly after sending the "shutdown" + request before sending kill -15. If set to + false, nvim exits immediately after sending + the "shutdown" request to the server. + • {get_language_id} (`fun(bufnr: integer, filetype: string): string`) + • {capabilities} (`lsp.ClientCapabilities`) The capabilities + provided by the client (editor or tool) + • {dynamic_capabilities} (`lsp.DynamicCapabilities`) + • {request} (`fun(method: string, params: table?, handler: lsp.Handler?, bufnr: integer): boolean, integer?`) + Sends a request to the server. This is a thin + wrapper around {client.rpc.request} with some + additional checking. If {handler} is not + specified and if there's no respective global + handler, then an error will occur. Returns: + {status}, {client_id}?. {status} is a boolean + indicating if the notification was successful. + If it is `false`, then it will always be + `false` (the client has shutdown). If {status} + is `true`, the function returns {request_id} + as the second result. You can use this with + `client.cancel_request(request_id)` to cancel + the request. + • {request_sync} (`fun(method: string, params: table?, timeout_ms: integer?, bufnr: integer): {err: lsp.ResponseError?, result:any}?, string?`) + err # a dictionary, where + • {notify} (`fun(method: string, params: table?): boolean`) + Sends a notification to an LSP server. + Returns: a boolean to indicate if the + notification was successful. If it is false, + then it will always be false (the client has + shutdown). + • {cancel_request} (`fun(id: integer): boolean`) Cancels a + request with a given request id. Returns: same + as `notify()`. + • {stop} (`fun(force?: boolean)`) Stops a client, + optionally with force. By default, it will + just ask the server to shutdown without force. + If you request to stop a client which has + previously been requested to shutdown, it will + automatically escalate and force shutdown. + • {on_attach} (`fun(bufnr: integer)`) Runs the on_attach + function from the client's config if it was + defined. Useful for buffer-local setup. + • {supports_method} (`fun(method: string, opts?: {bufnr: integer?}): boolean`) + Checks if a client supports a given method. + Always returns true for unknown off-spec + methods. {opts} is a optional + `{bufnr?: integer}` table. Some language + server capabilities can be file specific. + • {is_stopped} (`fun(): boolean`) Checks whether a client is + stopped. Returns: true if the client is fully + stopped. + +*vim.lsp.Client.Progress* + Extends: |vim.Ringbuf| + + + Fields: ~ + • {pending} (`table<lsp.ProgressToken,lsp.LSPAny>`) + +*vim.lsp.ClientConfig* + + Fields: ~ + • {cmd} (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient?`) + command string[] that launches the language + server (treated as in |jobstart()|, must be + absolute or on `$PATH`, shell constructs like + "~" are not expanded), or function that creates + an RPC client. Function receives a `dispatchers` + table and returns a table with member functions + `request`, `notify`, `is_closing` and + `terminate`. See |vim.lsp.rpc.request()|, + |vim.lsp.rpc.notify()|. For TCP there is a + builtin RPC client factory: + |vim.lsp.rpc.connect()| + • {cmd_cwd}? (`string`, default: cwd) Directory to launch the + `cmd` process. Not related to `root_dir`. + • {cmd_env}? (`table`) Environment flags to pass to the LSP + on spawn. Must be specified using a table. + Non-string values are coerced to string. + Example: >lua + { PORT = 8080; HOST = "0.0.0.0"; } +< + • {detached}? (`boolean`, default: true) Daemonize the server + process so that it runs in a separate process + group from Nvim. Nvim will shutdown the process + on exit, but if Nvim fails to exit cleanly this + could leave behind orphaned server processes. + • {workspace_folders}? (`lsp.WorkspaceFolder[]`) List of workspace + folders passed to the language server. For + backwards compatibility rootUri and rootPath + will be derived from the first workspace folder + in this list. See `workspaceFolders` in the LSP + spec. + • {capabilities}? (`lsp.ClientCapabilities`) Map overriding the + default capabilities defined by + |vim.lsp.protocol.make_client_capabilities()|, + passed to the language server on initialization. + Hint: use make_client_capabilities() and modify + its result. + • Note: To send an empty dictionary use + |vim.empty_dict()|, else it will be encoded as + an array. + • {handlers}? (`table<string,function>`) Map of language + server method names to |lsp-handler| + • {settings}? (`table`) Map with language server specific + settings. See the {settings} in + |vim.lsp.Client|. + • {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`) + Table that maps string of clientside commands to + user-defined functions. Commands passed to + start_client take precedence over the global + command registry. Each key must be a unique + command name, and the value is a function which + is called if any LSP action (code action, code + lenses, ...) triggers the command. + • {init_options}? (`table`) Values to pass in the initialization + request as `initializationOptions`. See + `initialize` in the LSP spec. + • {name}? (`string`, default: client-id) Name in log + messages. + • {get_language_id}? (`fun(bufnr: integer, filetype: string): string`) + Language ID as string. Defaults to the filetype. + • {offset_encoding}? (`'utf-8'|'utf-16'|'utf-32'`) The encoding that + the LSP server expects. Client does not verify + this is correct. + • {on_error}? (`fun(code: integer, err: string)`) Callback + invoked when the client operation throws an + error. `code` is a number describing the error. + Other arguments may be passed depending on the + error kind. See `vim.lsp.rpc.client_errors` for + possible errors. Use + `vim.lsp.rpc.client_errors[code]` to get + human-friendly name. + • {before_init}? (`fun(params: lsp.InitializeParams, config: vim.lsp.ClientConfig)`) + Callback invoked before the LSP "initialize" + phase, where `params` contains the parameters + being sent to the server and `config` is the + config that was passed to + |vim.lsp.start_client()|. You can use this to + modify parameters before they are sent. + • {on_init}? (`elem_or_list<fun(client: vim.lsp.Client, initialize_result: lsp.InitializeResult)>`) + Callback invoked after LSP "initialize", where + `result` is a table of `capabilities` and + anything else the server may send. For example, + clangd sends `initialize_result.offsetEncoding` + if `capabilities.offsetEncoding` was sent to it. + You can only modify the `client.offset_encoding` + here before any notifications are sent. + • {on_exit}? (`elem_or_list<fun(code: integer, signal: integer, client_id: integer)>`) + Callback invoked on client exit. + • code: exit code of the process + • signal: number describing the signal used to + terminate (if any) + • client_id: client handle + • {on_attach}? (`elem_or_list<fun(client: vim.lsp.Client, bufnr: integer)>`) + Callback invoked when client attaches to a + buffer. + • {trace}? (`'off'|'messages'|'verbose'`, default: "off") + Passed directly to the language server in the + initialize request. Invalid/empty values will + • {flags}? (`table`) A table with flags for the client. The + current (experimental) flags are: + • {allow_incremental_sync}? (`boolean`) Allow + using incremental sync for buffer edits + (defailt: `true`) + • {debounce_text_changes} (`integer`, default: + `150`) Debounce `didChange` notifications to + the server by the given number in + milliseconds. No debounce occurs if `nil`. + • {exit_timeout} (`integer|false`, default: + `false`) Milliseconds to wait for server to + exit cleanly after sending the "shutdown" + request before sending kill -15. If set to + false, nvim exits immediately after sending + the "shutdown" request to the server. + • {root_dir}? (`string`) Directory where the LSP server will + base its workspaceFolders, rootUri, and rootPath + on initialization. + + + +============================================================================== Lua module: vim.lsp.buf *lsp-buf* +*vim.lsp.ListOpts* + + Fields: ~ + • {on_list}? (`fun(t: vim.lsp.LocationOpts.OnList)`) list-handler + replacing the default handler. Called for any non-empty + result. This table can be used with |setqflist()| or + |setloclist()|. E.g.: >lua + local function on_list(options) + vim.fn.setqflist({}, ' ', options) + vim.cmd.cfirst() + end + + vim.lsp.buf.definition({ on_list = on_list }) + vim.lsp.buf.references(nil, { on_list = on_list }) +< + + If you prefer loclist do something like this: >lua + local function on_list(options) + vim.fn.setloclist(0, {}, ' ', options) + vim.cmd.lopen() + end +< + +*vim.lsp.LocationOpts* + Extends: |vim.lsp.ListOpts| + + + Fields: ~ + • {reuse_win}? (`boolean`) Jump to existing window if buffer is already + open. + +*vim.lsp.LocationOpts.OnList* + + Fields: ~ + • {items} (`table[]`) Structured like |setqflist-what| + • {title}? (`string`) Title for the list. + • {context}? (`table`) `ctx` from |lsp-handler| + + *vim.lsp.buf.add_workspace_folder()* add_workspace_folder({workspace_folder}) Add the folder at path to the workspace folders. If {path} is not provided, the user will be prompted for a path using |input()|. + Parameters: ~ + • {workspace_folder} (`string?`) + clear_references() *vim.lsp.buf.clear_references()* Removes document highlights from current buffer. @@ -1122,27 +1225,26 @@ code_action({options}) *vim.lsp.buf.code_action()* Selects a code action available at the current cursor position. Parameters: ~ - • {options} (table|nil) Optional table which holds the following - optional fields: - • context: (table|nil) Corresponds to `CodeActionContext` of the LSP specification: - • diagnostics (table|nil): LSP `Diagnostic[]`. Inferred + • {options} (`table?`) A table with the following fields: + • {context}? (`lsp.CodeActionContext`) Corresponds to + `CodeActionContext` of the LSP specification: + • {diagnostics}? (`table`) LSP `Diagnostic[]`. Inferred from the current position if not provided. - • only (table|nil): List of LSP `CodeActionKind`s used to + • {only}? (`table`) List of LSP `CodeActionKind`s used to filter the code actions. Most language servers support values like `refactor` or `quickfix`. - • triggerKind (number|nil): The reason why code actions + • {triggerKind}? (`integer`) The reason why code actions were requested. - - • filter: (function|nil) Predicate taking an `CodeAction` - and returning a boolean. - • apply: (boolean|nil) When set to `true`, and there is + • {filter}? (`fun(x: lsp.CodeAction|lsp.Command):boolean`) + Predicate taking an `CodeAction` and returning a boolean. + • {apply}? (`boolean`) When set to `true`, and there is just one remaining action (after filtering), the action is applied without user query. - • range: (table|nil) Range for which code actions should be - requested. If in visual mode this defaults to the active - selection. Table must contain `start` and `end` keys with - {row,col} tuples using mark-like indexing. See - |api-indexing| + • {range}? (`{start: integer[], end: integer[]}`) Range for + which code actions should be requested. If in visual mode + this defaults to the active selection. Table must contain + `start` and `end` keys with {row,col} tuples using + mark-like indexing. See |api-indexing| See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction @@ -1153,7 +1255,7 @@ completion({context}) *vim.lsp.buf.completion()* called in Insert mode. Parameters: ~ - • {context} (table) (context support not yet implemented) Additional + • {context} (`table`) (context support not yet implemented) Additional information about the context in which a completion was triggered (how it was triggered, and by which trigger character, if applicable) @@ -1169,21 +1271,13 @@ declaration({options}) *vim.lsp.buf.declaration()* |vim.lsp.buf.definition()| instead. Parameters: ~ - • {options} (table|nil) additional options - • reuse_win: (boolean) Jump to existing window if buffer is - already open. - • on_list: (function) |lsp-on-list-handler| replacing the - default handler. Called for any non-empty result. + • {options} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. definition({options}) *vim.lsp.buf.definition()* Jumps to the definition of the symbol under the cursor. Parameters: ~ - • {options} (table|nil) additional options - • reuse_win: (boolean) Jump to existing window if buffer is - already open. - • on_list: (function) |lsp-on-list-handler| replacing the - default handler. Called for any non-empty result. + • {options} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. document_highlight() *vim.lsp.buf.document_highlight()* Send request to the server to resolve document highlights for the current @@ -1203,15 +1297,13 @@ document_symbol({options}) *vim.lsp.buf.document_symbol()* Lists all symbols in the current buffer in the quickfix window. Parameters: ~ - • {options} (table|nil) additional options - • on_list: (function) handler for list results. See - |lsp-on-list-handler| + • {options} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. execute_command({command_params}) *vim.lsp.buf.execute_command()* Executes an LSP server command. Parameters: ~ - • {command_params} (table) A valid `ExecuteCommandParams` object + • {command_params} (`lsp.ExecuteCommandParams`) See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand @@ -1221,38 +1313,37 @@ format({options}) *vim.lsp.buf.format()* server clients. Parameters: ~ - • {options} (table|nil) Optional table which holds the following - optional fields: - • formatting_options (table|nil): Can be used to specify + • {options} (`table?`) A table with the following fields: + • {formatting_options}? (`table`) Can be used to specify FormattingOptions. Some unspecified options will be - automatically derived from the current Nvim options. See https://microsoft.github.io/language-server-protocol/specification/#formattingOptions - • timeout_ms (integer|nil, default 1000): Time in + automatically derived from the current Nvim options. See + https://microsoft.github.io/language-server-protocol/specification/#formattingOptions + • {timeout_ms}? (`integer`, default: `1000`) Time in milliseconds to block for formatting requests. No effect - if async=true - • bufnr (number|nil): Restrict formatting to the clients - attached to the given buffer, defaults to the current - buffer (0). - • filter (function|nil): Predicate used to filter clients. - Receives a client as argument and must return a boolean. - Clients matching the predicate are included. Example: >lua - - -- Never request typescript-language-server for formatting - vim.lsp.buf.format { - filter = function(client) return client.name ~= "tsserver" end - } + if async=true. + • {bufnr}? (`integer`, default: current buffer) Restrict + formatting to the clients attached to the given buffer. + • {filter}? (`fun(client: vim.lsp.Client): boolean?`) + Predicate used to filter clients. Receives a client as + argument and must return a boolean. Clients matching the + predicate are included. Example: >lua + -- Never request typescript-language-server for formatting + vim.lsp.buf.format { + filter = function(client) return client.name ~= "tsserver" end + } < - • async boolean|nil If true the method won't block. - Defaults to false. Editing the buffer while formatting + • {async}? (`boolean`, default: false) If true the method + won't block. Editing the buffer while formatting asynchronous can lead to unexpected changes. - • id (number|nil): Restrict formatting to the client with + • {id}? (`integer`) Restrict formatting to the client with ID (client.id) matching this field. - • name (string|nil): Restrict formatting to the client with + • {name}? (`string`) Restrict formatting to the client with name (client.name) matching this field. - • range (table|nil) Range to format. Table must contain - `start` and `end` keys with {row,col} tuples using (1,0) - indexing. Defaults to current selection in visual mode - Defaults to `nil` in other modes, formatting the full - buffer + • {range}? (`{start:integer[],end:integer[]}`, default: + current selection in visual mode, `nil` in other modes, + formatting the full buffer) Range to format. Table must + contain `start` and `end` keys with {row,col} tuples + using (1,0) indexing. hover() *vim.lsp.buf.hover()* Displays hover information about the symbol under the cursor in a floating @@ -1263,9 +1354,7 @@ implementation({options}) *vim.lsp.buf.implementation()* quickfix window. Parameters: ~ - • {options} (table|nil) additional options - • on_list: (function) |lsp-on-list-handler| replacing the - default handler. Called for any non-empty result. + • {options} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. incoming_calls() *vim.lsp.buf.incoming_calls()* Lists all the call sites of the symbol under the cursor in the |quickfix| @@ -1285,10 +1374,8 @@ references({context}, {options}) *vim.lsp.buf.references()* window. Parameters: ~ - • {context} (table|nil) Context for the request - • {options} (table|nil) additional options - • on_list: (function) handler for list results. See - |lsp-on-list-handler| + • {context} (`table?`) Context for the request + • {options} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references @@ -1298,18 +1385,23 @@ remove_workspace_folder({workspace_folder}) Remove the folder at path from the workspace folders. If {path} is not provided, the user will be prompted for a path using |input()|. + Parameters: ~ + • {workspace_folder} (`string?`) + rename({new_name}, {options}) *vim.lsp.buf.rename()* Renames all references to the symbol under the cursor. Parameters: ~ - • {new_name} (string|nil) If not provided, the user will be prompted - for a new name using |vim.ui.input()|. - • {options} (table|nil) additional options - • filter (function|nil): Predicate used to filter clients. - Receives a client as argument and must return a boolean. - Clients matching the predicate are included. - • name (string|nil): Restrict clients used for rename to + • {new_name} (`string?`) If not provided, the user will be prompted for + a new name using |vim.ui.input()|. + • {options} (`table?`) Additional options: + • {filter}? (`fun(client: vim.lsp.Client): boolean?`) + Predicate used to filter clients. Receives a client as + argument and must return a boolean. Clients matching the + predicate are included. + • {name}? (`string`) Restrict clients used for rename to ones where client.name matches this field. + • {bufnr}? (`integer`) (default: current buffer) signature_help() *vim.lsp.buf.signature_help()* Displays signature information about the symbol under the cursor in a @@ -1319,11 +1411,7 @@ type_definition({options}) *vim.lsp.buf.type_definition()* Jumps to the definition of the type of the symbol under the cursor. Parameters: ~ - • {options} (table|nil) additional options - • reuse_win: (boolean) Jump to existing window if buffer is - already open. - • on_list: (function) |lsp-on-list-handler| replacing the - default handler. Called for any non-empty result. + • {options} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. workspace_symbol({query}, {options}) *vim.lsp.buf.workspace_symbol()* Lists all symbols in the current workspace in the quickfix window. @@ -1333,10 +1421,8 @@ workspace_symbol({query}, {options}) *vim.lsp.buf.workspace_symbol()* string means no filtering is done. Parameters: ~ - • {query} (string|nil) optional - • {options} (table|nil) additional options - • on_list: (function) handler for list results. See - |lsp-on-list-handler| + • {query} (`string?`) optional + • {options} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. ============================================================================== @@ -1348,8 +1434,8 @@ get_namespace({client_id}, {is_pull}) |vim.diagnostic| for diagnostics Parameters: ~ - • {client_id} (integer) The id of the LSP client - • {is_pull} boolean? Whether the namespace is for a pull or push + • {client_id} (`integer`) The id of the LSP client + • {is_pull} (`boolean?`) Whether the namespace is for a pull or push client. Defaults to push *vim.lsp.diagnostic.on_diagnostic()* @@ -1378,7 +1464,10 @@ on_diagnostic({_}, {result}, {ctx}, {config}) < Parameters: ~ - • {config} (table) Configuration table (see |vim.diagnostic.config()|). + • {result} (`lsp.DocumentDiagnosticReport`) + • {ctx} (`lsp.HandlerContext`) + • {config} (`vim.diagnostic.Opts`) Configuration table (see + |vim.diagnostic.config()|). *vim.lsp.diagnostic.on_publish_diagnostics()* on_publish_diagnostics({_}, {result}, {ctx}, {config}) @@ -1406,7 +1495,10 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config}) < Parameters: ~ - • {config} (table) Configuration table (see |vim.diagnostic.config()|). + • {result} (`lsp.PublishDiagnosticsParams`) + • {ctx} (`lsp.HandlerContext`) + • {config} (`vim.diagnostic.Opts?`) Configuration table (see + |vim.diagnostic.config()|). ============================================================================== @@ -1416,40 +1508,50 @@ clear({client_id}, {bufnr}) *vim.lsp.codelens.clear()* Clear the lenses Parameters: ~ - • {client_id} (integer|nil) filter by client_id. All clients if nil - • {bufnr} (integer|nil) filter by buffer. All buffers if nil + • {client_id} (`integer?`) filter by client_id. All clients if nil + • {bufnr} (`integer?`) filter by buffer. All buffers if nil, 0 for + current buffer display({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.display()* Display the lenses using virtual text Parameters: ~ - • {lenses} lsp.CodeLens[]|nil lenses to display - • {bufnr} (integer) - • {client_id} (integer) + • {lenses} (`lsp.CodeLens[]?`) lenses to display + • {bufnr} (`integer`) + • {client_id} (`integer`) get({bufnr}) *vim.lsp.codelens.get()* Return all lenses for the given buffer Parameters: ~ - • {bufnr} (integer) Buffer number. 0 can be used for the current + • {bufnr} (`integer`) Buffer number. 0 can be used for the current buffer. Return: ~ - lsp.CodeLens[] + (`lsp.CodeLens[]`) - *vim.lsp.codelens.on_codelens()* -on_codelens({err}, {result}, {ctx}, {_}) +on_codelens({err}, {result}, {ctx}) *vim.lsp.codelens.on_codelens()* |lsp-handler| for the method `textDocument/codeLens` -refresh() *vim.lsp.codelens.refresh()* - Refresh the codelens for the current buffer + Parameters: ~ + • {err} (`lsp.ResponseError?`) + • {result} (`lsp.CodeLens[]`) + • {ctx} (`lsp.HandlerContext`) + +refresh({opts}) *vim.lsp.codelens.refresh()* + Refresh the lenses. It is recommended to trigger this using an autocmd or via keymap. Example: >vim - autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh() + autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh({ bufnr = 0 }) < + Parameters: ~ + • {opts} (`table?`) Optional fields + • {bufnr} (`integer?`) filter by buffer. All buffers if nil, 0 + for current buffer + run() *vim.lsp.codelens.run()* Run the code lens in the current line @@ -1457,23 +1559,27 @@ save({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.save()* Store lenses for a specific buffer and client Parameters: ~ - • {lenses} lsp.CodeLens[]|nil lenses to store - • {bufnr} (integer) - • {client_id} (integer) + • {lenses} (`lsp.CodeLens[]?`) lenses to store + • {bufnr} (`integer`) + • {client_id} (`integer`) ============================================================================== Lua module: vim.lsp.inlay_hint *lsp-inlay_hint* enable({bufnr}, {enable}) *vim.lsp.inlay_hint.enable()* - Enable/disable/toggle inlay hints for a buffer + Enables or disables inlay hints for a buffer. + + To "toggle", pass the inverse of `is_enabled()`: >lua + vim.lsp.inlay_hint.enable(0, not vim.lsp.inlay_hint.is_enabled()) +< Note: ~ - This API is pre-release (unstable). + • This API is pre-release (unstable). Parameters: ~ - • {bufnr} (integer|nil) Buffer handle, or 0 or nil for current - • {enable} (boolean|nil) true/nil to enable, false to disable + • {bufnr} (`integer?`) Buffer handle, or 0 or nil for current + • {enable} (`boolean?`) true/nil to enable, false to disable get({filter}) *vim.lsp.inlay_hint.get()* Get the list of inlay hints, (optionally) restricted by buffer or range. @@ -1493,28 +1599,29 @@ get({filter}) *vim.lsp.inlay_hint.get()* < Note: ~ - This API is pre-release (unstable). + • This API is pre-release (unstable). Parameters: ~ - • {filter} vim.lsp.inlay_hint.get.filter ? Optional filters |kwargs|: - • bufnr (integer?): 0 for current buffer - • range (lsp.Range?) + • {filter} (`table?`) Optional filters |kwargs|: + • {bufnr} (`integer?`) + • {range} (`lsp.Range?`) Return: ~ - vim.lsp.inlay_hint.get.ret [] Each list item is a table with the following fields: - • bufnr (integer) - • client_id (integer) - • inlay_hint (lsp.InlayHint) + (`table[]`) A list of objects with the following fields: + • {bufnr} (`integer`) + • {client_id} (`integer`) + • {inlay_hint} (`lsp.InlayHint`) is_enabled({bufnr}) *vim.lsp.inlay_hint.is_enabled()* + Note: ~ - This API is pre-release (unstable). + • This API is pre-release (unstable). Parameters: ~ - • {bufnr} (integer|nil) Buffer handle, or 0 or nil for current + • {bufnr} (`integer?`) Buffer handle, or 0 or nil for current Return: ~ - (boolean) + (`boolean`) ============================================================================== @@ -1527,7 +1634,7 @@ force_refresh({bufnr}) *vim.lsp.semantic_tokens.force_refresh()* highlighting (|vim.lsp.semantic_tokens.start()| has been called for it) Parameters: ~ - • {bufnr} (integer|nil) filter by buffer. All buffers if nil, current + • {bufnr} (`integer?`) filter by buffer. All buffers if nil, current buffer if 0 *vim.lsp.semantic_tokens.get_at_pos()* @@ -1536,12 +1643,12 @@ get_at_pos({bufnr}, {row}, {col}) arguments, returns the token under the cursor. Parameters: ~ - • {bufnr} (integer|nil) Buffer number (0 for current buffer, default) - • {row} (integer|nil) Position row (default cursor position) - • {col} (integer|nil) Position column (default cursor position) + • {bufnr} (`integer?`) Buffer number (0 for current buffer, default) + • {row} (`integer?`) Position row (default cursor position) + • {col} (`integer?`) Position column (default cursor position) Return: ~ - (table|nil) List of tokens at position. Each token has the following + (`table?`) List of tokens at position. Each token has the following fields: • line (integer) line number, 0-based • start_col (integer) start column, 0-based @@ -1549,6 +1656,7 @@ get_at_pos({bufnr}, {row}, {col}) • type (string) token type as string, e.g. "variable" • modifiers (table) token modifiers as a set. E.g., { static = true, readonly = true } + • client_id (integer) *vim.lsp.semantic_tokens.highlight_token()* highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts}) @@ -1560,15 +1668,15 @@ highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts}) use inside |LspTokenUpdate| callbacks. Parameters: ~ - • {token} (table) a semantic token, found as `args.data.token` in + • {token} (`table`) a semantic token, found as `args.data.token` in |LspTokenUpdate|. - • {bufnr} (integer) the buffer to highlight - • {client_id} (integer) The ID of the |vim.lsp.client| - • {hl_group} (string) Highlight group name - • {opts} (table|nil) Optional parameters. - • priority: (integer|nil) Priority for the applied - extmark. Defaults to - `vim.highlight.priorities.semantic_tokens + 3` + • {bufnr} (`integer`) the buffer to highlight + • {client_id} (`integer`) The ID of the |vim.lsp.Client| + • {hl_group} (`string`) Highlight group name + • {opts} (`table?`) Optional parameters: + • {priority}? (`integer`, default: + `vim.highlight.priorities.semantic_tokens + 3`) + Priority for the applied extmark. start({bufnr}, {client_id}, {opts}) *vim.lsp.semantic_tokens.start()* Start the semantic token highlighting engine for the given buffer with the @@ -1583,9 +1691,9 @@ start({bufnr}, {client_id}, {opts}) *vim.lsp.semantic_tokens.start()* < Parameters: ~ - • {bufnr} (integer) - • {client_id} (integer) - • {opts} (nil|table) Optional keyword arguments + • {bufnr} (`integer`) + • {client_id} (`integer`) + • {opts} (`table?`) Optional keyword arguments • debounce (integer, default: 200): Debounce token requests to the server by the given number in milliseconds @@ -1600,8 +1708,8 @@ stop({bufnr}, {client_id}) *vim.lsp.semantic_tokens.stop()* from the buffer. Parameters: ~ - • {bufnr} (integer) - • {client_id} (integer) + • {bufnr} (`integer`) + • {client_id} (`integer`) ============================================================================== @@ -1620,7 +1728,9 @@ hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()* < Parameters: ~ - • {config} (table) Configuration table. + • {result} (`lsp.Hover`) + • {ctx} (`lsp.HandlerContext`) + • {config} (`table`) Configuration table. • border: (default=nil) • Add borders to the floating window • See |vim.lsp.util.open_floating_preview()| for more @@ -1640,9 +1750,9 @@ signature_help({_}, {result}, {ctx}, {config}) < Parameters: ~ - • {result} (table) Response from the language server - • {ctx} (table) Client context - • {config} (table) Configuration table. + • {result} (`lsp.SignatureHelp`) Response from the language server + • {ctx} (`lsp.HandlerContext`) Client context + • {config} (`table`) Configuration table. • border: (default=nil) • Add borders to the floating window • See |vim.lsp.util.open_floating_preview()| for more @@ -1658,9 +1768,10 @@ apply_text_document_edit({text_document_edit}, {index}, {offset_encoding}) document. Parameters: ~ - • {text_document_edit} (table) a `TextDocumentEdit` object - • {index} (integer) Optional index of the edit, if from a - list of edits (or nil, if not from a list) + • {text_document_edit} (`table`) a `TextDocumentEdit` object + • {index} (`integer`) Optional index of the edit, if from + a list of edits (or nil, if not from a list) + • {offset_encoding} (`string?`) See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit @@ -1670,9 +1781,9 @@ apply_text_edits({text_edits}, {bufnr}, {offset_encoding}) Applies a list of text edits to a buffer. Parameters: ~ - • {text_edits} (table) list of `TextEdit` objects - • {bufnr} (integer) Buffer id - • {offset_encoding} (string) utf-8|utf-16|utf-32 + • {text_edits} (`table`) list of `TextEdit` objects + • {bufnr} (`integer`) Buffer id + • {offset_encoding} (`string`) utf-8|utf-16|utf-32 See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit @@ -1682,24 +1793,27 @@ apply_workspace_edit({workspace_edit}, {offset_encoding}) Applies a `WorkspaceEdit`. Parameters: ~ - • {workspace_edit} (table) `WorkspaceEdit` - • {offset_encoding} (string) utf-8|utf-16|utf-32 (required) + • {workspace_edit} (`table`) `WorkspaceEdit` + • {offset_encoding} (`string`) utf-8|utf-16|utf-32 (required) + + See also: ~ + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit buf_clear_references({bufnr}) *vim.lsp.util.buf_clear_references()* Removes document highlights from a buffer. Parameters: ~ - • {bufnr} (integer|nil) Buffer id + • {bufnr} (`integer?`) Buffer id *vim.lsp.util.buf_highlight_references()* buf_highlight_references({bufnr}, {references}, {offset_encoding}) Shows a list of document highlights for a certain buffer. Parameters: ~ - • {bufnr} (integer) Buffer id - • {references} (table) List of `DocumentHighlight` objects to + • {bufnr} (`integer`) Buffer id + • {references} (`table`) List of `DocumentHighlight` objects to highlight - • {offset_encoding} (string) One of "utf-8", "utf-16", "utf-32". + • {offset_encoding} (`string`) One of "utf-8", "utf-16", "utf-32". See also: ~ • https://microsoft.github.io/language-server-protocol/specification/#textDocumentContentChangeEvent @@ -1709,14 +1823,14 @@ character_offset({buf}, {row}, {col}, {offset_encoding}) Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer. Parameters: ~ - • {buf} (integer) buffer number (0 for current) - • {row} 0-indexed line - • {col} 0-indexed byte offset in line - • {offset_encoding} (string) utf-8|utf-16|utf-32 defaults to + • {buf} (`integer`) buffer number (0 for current) + • {row} (`integer`) 0-indexed line + • {col} (`integer`) 0-indexed byte offset in line + • {offset_encoding} (`string`) utf-8|utf-16|utf-32 defaults to `offset_encoding` of first client of `buf` Return: ~ - (integer) `offset_encoding` index of the character in line {row} + (`integer`) `offset_encoding` index of the character in line {row} column {col} in buffer {buf} *vim.lsp.util.convert_input_to_markdown_lines()* @@ -1731,12 +1845,12 @@ convert_input_to_markdown_lines({input}, {contents}) modifications. Parameters: ~ - • {input} (`MarkedString` | `MarkedString[]` | `MarkupContent`) - • {contents} (table|nil) List of strings to extend with converted - lines. Defaults to {}. + • {input} (`lsp.MarkedString|lsp.MarkedString[]|lsp.MarkupContent`) + • {contents} (`table?`) List of strings to extend with converted lines. + Defaults to {}. Return: ~ - string[] extended with lines of converted markdown. + (`string[]`) extended with lines of converted markdown. See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover @@ -1746,15 +1860,15 @@ convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers}) Converts `textDocument/signatureHelp` response to markdown lines. Parameters: ~ - • {signature_help} (table) Response of `textDocument/SignatureHelp` - • {ft} (string|nil) filetype that will be use as the `lang` + • {signature_help} (`table`) Response of `textDocument/SignatureHelp` + • {ft} (`string?`) filetype that will be use as the `lang` for the label markdown code block - • {triggers} (table|nil) list of trigger characters from the lsp + • {triggers} (`table?`) list of trigger characters from the lsp server. used to better determine parameter offsets Return (multiple): ~ - (table|nil) table list of lines of converted markdown. - (table|nil) table of active hl + (`table?`) table list of lines of converted markdown. + (`table?`) table of active hl See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp @@ -1763,10 +1877,10 @@ get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()* Returns indentation size. Parameters: ~ - • {bufnr} (integer|nil) Buffer handle, defaults to current + • {bufnr} (`integer?`) Buffer handle, defaults to current Return: ~ - (integer) indentation size + (`integer`) indentation size See also: ~ • 'shiftwidth' @@ -1776,13 +1890,13 @@ jump_to_location({location}, {offset_encoding}, {reuse_win}) Jumps to a location. Parameters: ~ - • {location} (table) (`Location`|`LocationLink`) - • {offset_encoding} (string|nil) utf-8|utf-16|utf-32 - • {reuse_win} (boolean|nil) Jump to existing window if buffer is + • {location} (`table`) (`Location`|`LocationLink`) + • {offset_encoding} (`string?`) utf-8|utf-16|utf-32 + • {reuse_win} (`boolean?`) Jump to existing window if buffer is already open. Return: ~ - (boolean) `true` if the jump succeeded + (`boolean`) `true` if the jump succeeded *vim.lsp.util.locations_to_items()* locations_to_items({locations}, {offset_encoding}) @@ -1796,23 +1910,18 @@ locations_to_items({locations}, {offset_encoding}) |setloclist()|. Parameters: ~ - • {locations} (table) list of `Location`s or `LocationLink`s - • {offset_encoding} (string) offset_encoding for locations + • {locations} (`lsp.Location[]|lsp.LocationLink[]`) + • {offset_encoding} (`string`) offset_encoding for locations utf-8|utf-16|utf-32 default to first client of buffer Return: ~ - (table) list of items - -lookup_section({settings}, {section}) *vim.lsp.util.lookup_section()* - Helper function to return nested values in language server settings - - Parameters: ~ - • {settings} (table) language server settings - • {section} string indicating the field of the settings table - - Return: ~ - table|string The value of settings accessed via section + (`table[]`) A list of objects with the following fields: + • {filename} (`string`) + • {lnum} (`integer`) 1-indexed line number + • {col} (`integer`) 1-indexed column + • {text} (`string`) + • {user_data} (`lsp.Location|lsp.LocationLink`) *vim.lsp.util.make_floating_popup_options()* make_floating_popup_options({width}, {height}, {opts}) @@ -1820,9 +1929,9 @@ make_floating_popup_options({width}, {height}, {opts}) table can be passed to |nvim_open_win()|. Parameters: ~ - • {width} (integer) window width (in character cells) - • {height} (integer) window height (in character cells) - • {opts} (table) optional + • {width} (`integer`) window width (in character cells) + • {height} (`integer`) window height (in character cells) + • {opts} (`table`) optional • offset_x (integer) offset to add to `col` • offset_y (integer) offset to add to `row` • border (string or table) override `border` @@ -1838,7 +1947,7 @@ make_floating_popup_options({width}, {height}, {opts}) are not enough lines to display the full window height. Return: ~ - (table) Options + (`table`) Options *vim.lsp.util.make_formatting_params()* make_formatting_params({options}) @@ -1846,10 +1955,10 @@ make_formatting_params({options}) cursor position. Parameters: ~ - • {options} (table|nil) with valid `FormattingOptions` entries + • {options} (`table?`) with valid `FormattingOptions` entries Return: ~ - `DocumentFormattingParams` object + (`lsp.DocumentFormattingParams`) object See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting @@ -1860,18 +1969,18 @@ make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding}) similar to |vim.lsp.util.make_range_params()|. Parameters: ~ - • {start_pos} integer[]|nil {row,col} mark-indexed position. + • {start_pos} (`integer[]?`) {row,col} mark-indexed position. Defaults to the start of the last visual selection. - • {end_pos} integer[]|nil {row,col} mark-indexed position. + • {end_pos} (`integer[]?`) {row,col} mark-indexed position. Defaults to the end of the last visual selection. - • {bufnr} (integer|nil) buffer handle or 0 for current, + • {bufnr} (`integer?`) buffer handle or 0 for current, defaults to current - • {offset_encoding} "utf-8"|"utf-16"|"utf-32"|nil defaults to + • {offset_encoding} (`"utf-8"|"utf-16"|"utf-32"?`) defaults to `offset_encoding` of first client of `bufnr` Return: ~ - (table) { textDocument = { uri = `current_file_uri` }, range = { start - = `start_position`, end = `end_position` } } + (`table`) { textDocument = { uri = `current_file_uri` }, range = { + start = `start_position`, end = `end_position` } } *vim.lsp.util.make_position_params()* make_position_params({window}, {offset_encoding}) @@ -1879,14 +1988,14 @@ make_position_params({window}, {offset_encoding}) cursor position. Parameters: ~ - • {window} (integer|nil) window handle or 0 for current, + • {window} (`integer?`) window handle or 0 for current, defaults to current - • {offset_encoding} (string|nil) utf-8|utf-16|utf-32|nil defaults to + • {offset_encoding} (`string?`) utf-8|utf-16|utf-32|nil defaults to `offset_encoding` of first client of buffer of `window` Return: ~ - (table) `TextDocumentPositionParams` object + (`table`) `TextDocumentPositionParams` object See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams @@ -1899,25 +2008,25 @@ make_range_params({window}, {offset_encoding}) `textDocument/rangeFormatting`. Parameters: ~ - • {window} (integer|nil) window handle or 0 for current, + • {window} (`integer?`) window handle or 0 for current, defaults to current - • {offset_encoding} "utf-8"|"utf-16"|"utf-32"|nil defaults to + • {offset_encoding} (`"utf-8"|"utf-16"|"utf-32"?`) defaults to `offset_encoding` of first client of buffer of `window` Return: ~ - (table) { textDocument = { uri = `current_file_uri` }, range = { start - = `current_position`, end = `current_position` } } + (`table`) { textDocument = { uri = `current_file_uri` }, range = { + start = `current_position`, end = `current_position` } } *vim.lsp.util.make_text_document_params()* make_text_document_params({bufnr}) Creates a `TextDocumentIdentifier` object for the current buffer. Parameters: ~ - • {bufnr} (integer|nil) Buffer handle, defaults to current + • {bufnr} (`integer?`) Buffer handle, defaults to current Return: ~ - (table) `TextDocumentIdentifier` + (`table`) `TextDocumentIdentifier` See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier @@ -1927,38 +2036,41 @@ make_workspace_params({added}, {removed}) Create the workspace params Parameters: ~ - • {added} (table) - • {removed} (table) + • {added} (`table`) + • {removed} (`table`) *vim.lsp.util.open_floating_preview()* open_floating_preview({contents}, {syntax}, {opts}) Shows contents in a floating window. Parameters: ~ - • {contents} (table) of lines to show in window - • {syntax} (string) of syntax to set for opened buffer - • {opts} (table) with optional fields (additional keys are filtered - with |vim.lsp.util.make_floating_popup_options()| before - they are passed on to |nvim_open_win()|) - • height: (integer) height of floating window - • width: (integer) width of floating window - • wrap: (boolean, default true) wrap long lines - • wrap_at: (integer) character to wrap at for computing - height when wrap is enabled - • max_width: (integer) maximal width of floating window - • max_height: (integer) maximal height of floating window - • focus_id: (string) if a popup with this id is opened, - then focus it - • close_events: (table) list of events that closes the + • {contents} (`table`) of lines to show in window + • {syntax} (`string`) of syntax to set for opened buffer + • {opts} (`table?`) with optional fields (additional keys are + filtered with |vim.lsp.util.make_floating_popup_options()| + before they are passed on to |nvim_open_win()|) + • {height}? (`integer`) Height of floating window + • {width}? (`integer`) Width of floating window + • {wrap}? (`boolean`, default: `true`) Wrap long lines + • {wrap_at}? (`integer`) Character to wrap at for + computing height when wrap is enabled + • {max_width}? (`integer`) Maximal width of floating + window + • {max_height}? (`integer`) Maximal height of floating + window + • {focus_id}? (`string`) If a popup with this id is + opened, then focus it + • {close_events}? (`table`) List of events that closes the floating window - • focusable: (boolean, default true) Make float focusable - • focus: (boolean, default true) If `true`, and if + • {focusable}? (`boolean`, default: `true`) Make float + focusable. + • {focus}? (`boolean`, default: `true`) If `true`, and if {focusable} is also `true`, focus an existing floating window with the same {focus_id} Return (multiple): ~ - (integer) bufnr of newly created float window - (integer) winid of newly created float window preview window + (`integer`) bufnr of newly created float window + (`integer`) winid of newly created float window preview window preview_location({location}, {opts}) *vim.lsp.util.preview_location()* Previews a location in a floating window @@ -1969,33 +2081,46 @@ preview_location({location}, {opts}) *vim.lsp.util.preview_location()* definition) Parameters: ~ - • {location} (table) a single `Location` or `LocationLink` + • {location} (`table`) a single `Location` or `LocationLink` + • {opts} (`table`) Return (multiple): ~ - (integer|nil) buffer id of float window - (integer|nil) window id of float window + (`integer?`) buffer id of float window + (`integer?`) window id of float window rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()* Rename old_fname to new_fname + Existing buffers are renamed as well, while maintaining their bufnr. + + It deletes existing buffers that conflict with the renamed file name only + when + • `opts` requests overwriting; or + • the conflicting buffers are not loaded, so that deleting thme does not + result in data loss. + Parameters: ~ - • {opts} (table) + • {old_fname} (`string`) + • {new_fname} (`string`) + • {opts} (`table?`) Options: + • {overwrite}? (`boolean`) + • {ignoreIfExists}? (`boolean`) *vim.lsp.util.show_document()* show_document({location}, {offset_encoding}, {opts}) Shows document and optionally jumps to the location. Parameters: ~ - • {location} (table) (`Location`|`LocationLink`) - • {offset_encoding} (string|nil) utf-8|utf-16|utf-32 - • {opts} (table|nil) options + • {location} (`table`) (`Location`|`LocationLink`) + • {offset_encoding} (`string?`) utf-8|utf-16|utf-32 + • {opts} (`table?`) options • reuse_win (boolean) Jump to existing window if buffer is already open. • focus (boolean) Whether to focus/jump to location if possible. Defaults to true. Return: ~ - (boolean) `true` if succeeded + (`boolean`) `true` if succeeded *vim.lsp.util.stylize_markdown()* stylize_markdown({bufnr}, {contents}, {opts}) @@ -2010,8 +2135,9 @@ stylize_markdown({bufnr}, {contents}, {opts}) `open_floating_preview` instead Parameters: ~ - • {contents} (table) of lines to show in window - • {opts} (table) with optional fields + • {bufnr} (`integer`) + • {contents} (`table`) of lines to show in window + • {opts} (`table`) with optional fields • height of floating window • width of floating window • wrap_at character to wrap at for computing height @@ -2020,13 +2146,14 @@ stylize_markdown({bufnr}, {contents}, {opts}) • separator insert separator after code block Return: ~ - (table) stripped content + (`table`) stripped content symbols_to_items({symbols}, {bufnr}) *vim.lsp.util.symbols_to_items()* Converts symbols to quickfix list items. Parameters: ~ - • {symbols} (table) DocumentSymbol[] or SymbolInformation[] + • {symbols} (`table`) DocumentSymbol[] or SymbolInformation[] + • {bufnr} (`integer`) ============================================================================== @@ -2036,127 +2163,167 @@ get_filename() *vim.lsp.log.get_filename()* Returns the log filename. Return: ~ - (string) log filename + (`string`) log filename get_level() *vim.lsp.log.get_level()* Gets the current log level. Return: ~ - (integer) current log level + (`integer`) current log level set_format_func({handle}) *vim.lsp.log.set_format_func()* Sets formatting function used to format logs Parameters: ~ - • {handle} (function) function to apply to logging arguments, pass + • {handle} (`function`) function to apply to logging arguments, pass vim.inspect for multi-line formatting set_level({level}) *vim.lsp.log.set_level()* Sets the current log level. Parameters: ~ - • {level} (string|integer) One of `vim.lsp.log.levels` + • {level} (`string|integer`) One of `vim.lsp.log.levels` should_log({level}) *vim.lsp.log.should_log()* Checks whether the level is sufficient for logging. Parameters: ~ - • {level} (integer) log level + • {level} (`integer`) log level Return: ~ - (bool) true if would log, false if not + (`bool`) true if would log, false if not ============================================================================== Lua module: vim.lsp.rpc *lsp-rpc* +*vim.lsp.rpc.PublicClient* + + Fields: ~ + • {request} (`fun(method: string, params: table?, callback: fun(err: lsp.ResponseError?, result: any), notify_reply_callback: fun(integer)?):boolean,integer?`) + see |vim.lsp.rpc.request()| + • {notify} (`fun(method: string, params: any):boolean`) see + |vim.lsp.rpc.notify()| + • {is_closing} (`fun(): boolean`) + • {terminate} (`fun()`) + + connect({host}, {port}) *vim.lsp.rpc.connect()* Create a LSP RPC client factory that connects via TCP to the given host - and port + and port. + + Return a function that can be passed to the `cmd` field for + |vim.lsp.start_client()| or |vim.lsp.start()|. + + Parameters: ~ + • {host} (`string`) host to connect to + • {port} (`integer`) port to connect to + + Return: ~ + (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) + + *vim.lsp.rpc.domain_socket_connect()* +domain_socket_connect({pipe_path}) + Create a LSP RPC client factory that connects via named pipes (Windows) or + unix domain sockets (Unix) to the given pipe_path (file path on Unix and + name on Windows). + + Return a function that can be passed to the `cmd` field for + |vim.lsp.start_client()| or |vim.lsp.start()|. Parameters: ~ - • {host} (string) - • {port} (integer) + • {pipe_path} (`string`) file path of the domain socket (Unix) or name + of the named pipe (Windows) to connect to Return: ~ - (function) + (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) format_rpc_error({err}) *vim.lsp.rpc.format_rpc_error()* Constructs an error message from an LSP error object. Parameters: ~ - • {err} (table) The error object + • {err} (`table`) The error object Return: ~ - (string) The formatted error message + (`string`) error_message The formatted error message notify({method}, {params}) *vim.lsp.rpc.notify()* Sends a notification to the LSP server. Parameters: ~ - • {method} (string) The invoked LSP method - • {params} (table|nil) Parameters for the invoked LSP method + • {method} (`string`) The invoked LSP method + • {params} (`table?`) Parameters for the invoked LSP method Return: ~ - (boolean) `true` if notification could be sent, `false` if not + (`boolean`) `true` if notification could be sent, `false` if not *vim.lsp.rpc.request()* request({method}, {params}, {callback}, {notify_reply_callback}) Sends a request to the LSP server and runs {callback} upon response. Parameters: ~ - • {method} (string) The invoked LSP method - • {params} (table|nil) Parameters for the invoked LSP + • {method} (`string`) The invoked LSP method + • {params} (`table?`) Parameters for the invoked LSP method - • {callback} fun(err: lsp.ResponseError | nil, result: - any) Callback to invoke - • {notify_reply_callback} (function|nil) Callback to invoke as soon as - a request is no longer pending + • {callback} (`fun(err: lsp.ResponseError?, result: any)`) + Callback to invoke + • {notify_reply_callback} (`fun(message_id: integer)?`) Callback to + invoke as soon as a request is no longer + pending - Return: ~ - (boolean) success, integer|nil request_id true, message_id if request - could be sent, `false` if not + Return (multiple): ~ + (`boolean`) success `true` if request could be sent, `false` if not + (`integer?`) message_id if request could be sent, `nil` if not *vim.lsp.rpc.rpc_response_error()* rpc_response_error({code}, {message}, {data}) - Creates an RPC response object/table. + Creates an RPC response table `error` to be sent to the LSP response. Parameters: ~ - • {code} (integer) RPC error code defined in + • {code} (`integer`) RPC error code defined, see `vim.lsp.protocol.ErrorCodes` - • {message} (string|nil) arbitrary message to send to server - • {data} any|nil arbitrary data to send to server + • {message} (`string?`) arbitrary message to send to server + • {data} (`any?`) arbitrary data to send to server - *vim.lsp.rpc.start()* -start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params}) + Return: ~ + (`lsp.ResponseError`) + + See also: ~ + • lsp.ErrorCodes See `vim.lsp.protocol.ErrorCodes` + +start({cmd}, {dispatchers}, {extra_spawn_params}) *vim.lsp.rpc.start()* Starts an LSP server process and create an LSP RPC client object to interact with it. Communication with the spawned process happens via stdio. For communication via TCP, spawn a process manually and use |vim.lsp.rpc.connect()| Parameters: ~ - • {cmd} (string) Command to start the LSP server. - • {cmd_args} (table) List of additional string arguments to - pass to {cmd}. - • {dispatchers} (table|nil) Dispatchers for LSP message types. - Valid dispatcher names are: - • `"notification"` - • `"server_request"` - • `"on_error"` - • `"on_exit"` - • {extra_spawn_params} (table|nil) Additional context for the LSP - server process. May contain: - • {cwd} (string) Working directory for the LSP - server process - • {env} (table) Additional environment variables - for LSP server process + • {cmd} (`string[]`) Command to start the LSP server. + • {dispatchers} (`table?`) Dispatchers for LSP message types. + • {notification} + (`fun(method: string, params: table)`) + • {server_request} + (`fun(method: string, params: table): any?, lsp.ResponseError?`) + • {on_exit} + (`fun(code: integer, signal: integer)`) + • {on_error} (`fun(code: integer, err: any)`) + • {extra_spawn_params} (`table?`) Additional context for the LSP server + process. + • {cwd}? (`string`) Working directory for the + LSP server process + • {detached}? (`boolean`) Detach the LSP server + process from the current process + • {env}? (`table<string,string>`) Additional + environment variables for LSP server process. + See |vim.system()| Return: ~ - (table|nil) Client RPC object, with these methods: + (`vim.lsp.rpc.PublicClient?`) Client RPC object, with these methods: • `notify()` |vim.lsp.rpc.notify()| • `request()` |vim.lsp.rpc.request()| • `is_closing()` returns a boolean indicating if the RPC is closing. - • `terminate()` terminates the RPC client. + • `terminate()` terminates the RPC client. See + |vim.lsp.rpc.PublicClient|. ============================================================================== @@ -2168,23 +2335,24 @@ make_client_capabilities() capabilities. Return: ~ - lsp.ClientCapabilities + (`lsp.ClientCapabilities`) Methods *vim.lsp.protocol.Methods* LSP method names. See also: ~ - • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#metaModel + • https://microsoft.github.io/language-server-protocol/specification/#metaModel *vim.lsp.protocol.resolve_capabilities()* resolve_capabilities({server_capabilities}) Creates a normalized object describing LSP server capabilities. Parameters: ~ - • {server_capabilities} (table) Table of capabilities supported by the - server + • {server_capabilities} (`table`) Table of capabilities supported by + the server Return: ~ - (table|nil) Normalized table of capabilities + (`lsp.ServerCapabilities?`) Normalized table of capabilities + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index c15b1b0495..e8757a1859 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -157,7 +157,7 @@ its functions if this succeeds and prints an error message otherwise: end < In contrast to |:source|, |require()| not only searches through all `lua/` directories -under |'runtimepath'|, it also cache the module on first use. Calling +under |'runtimepath'|, it also caches the module on first use. Calling `require()` a second time will therefore _not_ execute the script again and instead return the cached file. To rerun the file, you need to remove it from the cache manually first: diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index a35d70cae8..367b5c36d2 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -121,16 +121,14 @@ languages like Python and C#. Example: >lua func_with_opts { foo = true, filename = "hello.world" } < -There's nothing special going on here except that parentheses are treated as -whitespace. But visually, this small bit of sugar gets reasonably close to -a "keyword args" interface. Nvim code tends to prefer this style. - ------------------------------------------------------------------------------- -LUA PATTERNS *lua-patterns* +There's nothing special going on here except that parentheses are implicitly +added. But visually, this small bit of sugar gets reasonably close to a +"keyword args" interface. + *lua-regex* Lua intentionally does not support regular expressions, instead it has limited -"patterns" |lua-pattern| which avoid the performance pitfalls of extended -regex. Lua scripts can also use Vim regex via |vim.regex()|. +|lua-patterns| which avoid the performance pitfalls of extended regex. Lua +scripts can also use Vim regex via |vim.regex()|. Examples: >lua @@ -256,6 +254,14 @@ arguments separated by " " (space) instead of "\t" (tab). < To see the LuaJIT version: >vim :lua =jit.version < +:{range}lua + Executes buffer lines in {range} as Lua code. Unlike |:source|, this + always treats the lines as Lua code. + + Example: select the following code and type ":lua<Enter>" to execute it: >lua + print(string.format( + 'unix time: %s', os.time())) +< *:lua-heredoc* :lua << [trim] [{endmarker}] {script} @@ -268,10 +274,8 @@ arguments separated by " " (space) instead of "\t" (tab). function! CurrentLineInfo() lua << EOF local linenr = vim.api.nvim_win_get_cursor(0)[1] - local curline = vim.api.nvim_buf_get_lines( - 0, linenr - 1, linenr, false)[1] - print(string.format("Current line [%d] has %d bytes", - linenr, #curline)) + local curline = vim.api.nvim_buf_get_lines(0, linenr - 1, linenr, false)[1] + print(string.format('Line [%d] has %d bytes', linenr, #curline)) EOF endfunction < @@ -574,41 +578,30 @@ A subset of the `vim.*` API is available in threads. This includes: like `vim.split`, `vim.tbl_*`, `vim.list_*`, and so on. - `vim.is_thread()` returns true from a non-main thread. ------------------------------------------------------------------------------- -VIM.LPEG *lua-lpeg* - - *vim.lpeg* *vim.re* -The Lpeg library for parsing expression grammars is being included as -`vim.lpeg` (https://www.inf.puc-rio.br/~roberto/lpeg/). In addition, its regex-like -interface is available as `vim.re` (https://www.inf.puc-rio.br/~roberto/lpeg/re.html). ============================================================================== VIM.HIGHLIGHT *vim.highlight* - Nvim includes a function for highlighting a selection on yank. To enable it, add the following to your `init.vim`: >vim au TextYankPost * silent! lua vim.highlight.on_yank() - < -You can customize the highlight group and the duration of the highlight -via: >vim +You can customize the highlight group and the duration of the highlight via: >vim au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150} - < If you want to exclude visual selections from highlighting on yank, use: >vim au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} - < + vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* Highlight the yanked text Parameters: ~ - • {opts} (table|nil) Optional parameters + • {opts} (`table?`) Optional parameters • higroup highlight group for yanked region (default "IncSearch") • timeout time in ms before highlight is cleared (default 150) @@ -622,7 +615,7 @@ vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* vim.highlight.priorities *vim.highlight.priorities* Table with default priorities used for highlighting: • `syntax`: `50`, used for standard syntax highlighting - • `treesitter`: `100`, used for tree-sitter-based highlighting + • `treesitter`: `100`, used for treesitter-based highlighting • `semantic_tokens`: `125`, used for LSP semantic token highlighting • `diagnostics`: `150`, used for code analysis such as diagnostics • `user`: `200`, used for user-triggered highlights such as LSP document @@ -633,14 +626,14 @@ vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) Apply highlight group to range of text. Parameters: ~ - • {bufnr} (integer) Buffer number to apply highlighting to - • {ns} (integer) Namespace to add highlight to - • {higroup} (string) Highlight group to use for highlighting - • {start} integer[]|string Start of region as a (line, column) tuple - or string accepted by |getpos()| - • {finish} integer[]|string End of region as a (line, column) tuple or - string accepted by |getpos()| - • {opts} (table|nil) Optional parameters + • {bufnr} (`integer`) Buffer number to apply highlighting to + • {ns} (`integer`) Namespace to add highlight to + • {higroup} (`string`) Highlight group to use for highlighting + • {start} (`integer[]|string`) Start of region as a (line, column) + tuple or string accepted by |getpos()| + • {finish} (`integer[]|string`) End of region as a (line, column) + tuple or string accepted by |getpos()| + • {opts} (`table?`) Optional parameters • regtype type of range (see |setreg()|, default charwise) • inclusive boolean indicating whether the range is end-inclusive (default false) @@ -649,47 +642,6 @@ vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) ============================================================================== -VIM.REGEX *vim.regex* - - -Vim regexes can be used directly from Lua. Currently they only allow -matching within a single line. - - -vim.regex({re}) *vim.regex()* - Parse the Vim regex {re} and return a regex object. Regexes are "magic" - and case-sensitive by default, regardless of 'magic' and 'ignorecase'. - They can be controlled with flags, see |/magic| and |/ignorecase|. - - Parameters: ~ - • {re} (string) - - Return: ~ - vim.regex - - *regex:match_line()* -vim.regex:match_line({bufnr}, {line_idx}, {start}, {end_}) - Match line {line_idx} (zero-based) in buffer {bufnr}. If {start} and {end} - are supplied, match only this byte index range. Otherwise see - |regex:match_str()|. If {start} is used, then the returned byte indices - will be relative {start}. - - Parameters: ~ - • {bufnr} (integer) - • {line_idx} (integer) - • {start} (integer|nil) - • {end_} (integer|nil) - -vim.regex:match_str({str}) *regex:match_str()* - Match the string against the regex. If the string should match the regex - precisely, surround the regex with `^` and `$` . If there was a match, the byte indices for the beginning and end of the - match are returned. When there is no match, `nil` is returned. Because any integer is "truthy", `regex:match_str()` can be directly used as a condition in an if-statement. - - Parameters: ~ - • {str} (string) - - -============================================================================== VIM.DIFF *vim.diff* vim.diff({a}, {b}, {opts}) *vim.diff()* @@ -712,22 +664,20 @@ vim.diff({a}, {b}, {opts}) *vim.diff()* < Parameters: ~ - • {a} (string) First string to compare - • {b} (string) Second string to compare - • {opts} table<string,any> Optional parameters: - • `on_hunk` (callback): Invoked for each hunk in the diff. Return a - negative number to cancel the callback for any remaining - hunks. Args: + • {a} (`string`) First string to compare + • {b} (`string`) Second string to compare + • {opts} (`table<string,any>`) Optional parameters: + • `on_hunk` (callback): Invoked for each hunk in the diff. + Return a negative number to cancel the callback for any + remaining hunks. Args: • `start_a` (integer): Start line of hunk in {a}. • `count_a` (integer): Hunk size in {a}. • `start_b` (integer): Start line of hunk in {b}. • `count_b` (integer): Hunk size in {b}. - • `result_type` (string): Form of the returned diff: • "unified": (default) String in unified format. • "indices": Array of hunk locations. Note: This option is ignored if `on_hunk` is used. - • `linematch` (boolean|integer): Run linematch on the resulting hunks from xdiff. When integer, only hunks upto this size in lines are run through linematch. Requires @@ -738,7 +688,6 @@ vim.diff({a}, {b}, {opts}) *vim.diff()* possible diff • "patience" patience diff algorithm • "histogram" histogram diff algorithm - • `ctxlen` (integer): Context length • `interhunkctxlen` (integer): Inter hunk context length • `ignore_whitespace` (boolean): Ignore whitespace @@ -753,37 +702,45 @@ vim.diff({a}, {b}, {opts}) *vim.diff()* the internal diff library. Return: ~ - string|table|nil See {opts.result_type}. `nil` if {opts.on_hunk} is + (`string|table?`) See {opts.result_type}. `nil` if {opts.on_hunk} is given. ============================================================================== VIM.MPACK *vim.mpack* - This module provides encoding and decoding of Lua objects to and from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. + vim.mpack.decode({str}) *vim.mpack.decode()* Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. Parameters: ~ - • {str} (string) + • {str} (`string`) + + Return: ~ + (`any`) vim.mpack.encode({obj}) *vim.mpack.encode()* Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. + Parameters: ~ + • {obj} (`any`) + + Return: ~ + (`string`) + ============================================================================== VIM.JSON *vim.json* - This module provides encoding and decoding of Lua objects to and from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. + vim.json.decode({str}, {opts}) *vim.json.decode()* Decodes (or "unpacks") the JSON-encoded {str} to a Lua object. - • Decodes JSON "null" as |vim.NIL| (controllable by {opts}, see below). • Decodes empty object as |vim.empty_dict()|. • Decodes empty array as `{}` (empty Lua table). @@ -794,8 +751,8 @@ vim.json.decode({str}, {opts}) *vim.json.decode()* < Parameters: ~ - • {str} (string) Stringified JSON data. - • {opts} table<string,any>|nil Options table with keys: + • {str} (`string`) Stringified JSON data. + • {opts} (`table<string,any>?`) Options table with keys: • luanil: (table) Table with keys: • object: (boolean) When true, converts `null` in JSON objects to Lua `nil` instead of |vim.NIL|. @@ -803,16 +760,16 @@ vim.json.decode({str}, {opts}) *vim.json.decode()* to Lua `nil` instead of |vim.NIL|. Return: ~ - any + (`any`) vim.json.encode({obj}) *vim.json.encode()* Encodes (or "packs") Lua object {obj} as JSON in a Lua string. Parameters: ~ - • {obj} any + • {obj} (`any`) Return: ~ - (string) + (`string`) ============================================================================== @@ -822,19 +779,19 @@ vim.base64.decode({str}) *vim.base64.decode()* Decode a Base64 encoded string. Parameters: ~ - • {str} (string) Base64 encoded string + • {str} (`string`) Base64 encoded string Return: ~ - (string) Decoded string + (`string`) Decoded string vim.base64.encode({str}) *vim.base64.encode()* Encode {str} using Base64. Parameters: ~ - • {str} (string) String to encode + • {str} (`string`) String to encode Return: ~ - (string) Encoded string + (`string`) Encoded string ============================================================================== @@ -857,10 +814,11 @@ vim.spell.check({str}) *vim.spell.check()* < Parameters: ~ - • {str} (string) + • {str} (`string`) Return: ~ - `{[1]: string, [2]: string, [3]: string}[]` List of tuples with three items: + (`{[1]: string, [2]: string, [3]: string}[]`) List of tuples with + three items: • The badly spelled word. • The type of the spelling error: "bad" spelling mistake "rare" rare word "local" word only valid in another region "caps" word should @@ -872,24 +830,24 @@ vim.spell.check({str}) *vim.spell.check()* VIM *vim.builtin* -vim.api.{func}({...}) *vim.api* +vim.api.{func}({...}) *vim.api* Invokes Nvim |API| function {func} with arguments {...}. Example: call the "nvim_get_current_line()" API function: >lua print(tostring(vim.api.nvim_get_current_line())) -vim.NIL *vim.NIL* +vim.NIL *vim.NIL* Special value representing NIL in |RPC| and |v:null| in Vimscript conversion, and similar cases. Lua `nil` cannot be used as part of a Lua table representing a Dictionary or Array, because it is treated as missing: `{"foo", nil}` is the same as `{"foo"}`. -vim.type_idx *vim.type_idx* +vim.type_idx *vim.type_idx* Type index for use in |lua-special-tbl|. Specifying one of the values from |vim.types| allows typing the empty table (it is unclear whether empty Lua table represents empty list or empty array) and forcing integral numbers to be |Float|. See |lua-special-tbl| for more details. -vim.val_idx *vim.val_idx* +vim.val_idx *vim.val_idx* Value index for tables representing |Float|s. A table representing floating-point value 1.0 looks like this: >lua { @@ -898,7 +856,7 @@ vim.val_idx *vim.val_id } < See also |vim.type_idx| and |lua-special-tbl|. -vim.types *vim.types* +vim.types *vim.types* Table with possible values for |vim.type_idx|. Contains two sets of key-value pairs: first maps possible values for |vim.type_idx| to human-readable strings, second maps human-readable type names to values @@ -927,6 +885,8 @@ Log levels are one of the values defined in `vim.log.levels`: vim.log.levels.WARN vim.log.levels.OFF + + vim.empty_dict() *vim.empty_dict()* Creates a special empty table (marked with a metatable), which Nvim converts to an empty dictionary when translating Lua values to Vimscript @@ -936,6 +896,9 @@ vim.empty_dict() *vim.empty_dict()* Note: If numeric keys are present in the table, Nvim ignores the metatable marker and converts the dict to a list/array anyway. + Return: ~ + (`table`) + vim.iconv({str}, {from}, {to}, {opts}) *vim.iconv()* The result is a String, which is the text {str} converted from encoding {from} to encoding {to}. When the conversion fails `nil` is returned. When @@ -944,13 +907,13 @@ vim.iconv({str}, {from}, {to}, {opts}) *vim.iconv()* ":Man 3 iconv". Parameters: ~ - • {str} (string) Text to convert - • {from} (number) Encoding of {str} - • {to} (number) Target encoding - • {opts} table<string,any>|nil + • {str} (`string`) Text to convert + • {from} (`number`) Encoding of {str} + • {to} (`number`) Target encoding + • {opts} (`table<string,any>?`) Return: ~ - (string|nil) Converted string if conversion succeeds, `nil` otherwise. + (`string?`) Converted string if conversion succeeds, `nil` otherwise. vim.in_fast_event() *vim.in_fast_event()* Returns true if the code is executing as part of a "fast" event handler, @@ -959,19 +922,18 @@ vim.in_fast_event() *vim.in_fast_event()* When this is `false` most API functions are callable (but may be subject to other restrictions such as |textlock|). -vim.rpcnotify({channel}, {method}, {args}, {...}) *vim.rpcnotify()* +vim.rpcnotify({channel}, {method}, {...}) *vim.rpcnotify()* Sends {event} to {channel} via |RPC| and returns immediately. If {channel} is 0, the event is broadcast to all channels. This function also works in a fast callback |lua-loop-callbacks|. Parameters: ~ - • {channel} (integer) - • {method} (string) - • {args} any[]|nil - • {...} any|nil + • {channel} (`integer`) + • {method} (`string`) + • {...} (`any?`) -vim.rpcrequest({channel}, {method}, {args}, {...}) *vim.rpcrequest()* +vim.rpcrequest({channel}, {method}, {...}) *vim.rpcrequest()* Sends a request to {channel} to invoke {method} via |RPC| and blocks until a response is received. @@ -979,17 +941,16 @@ vim.rpcrequest({channel}, {method}, {args}, {...}) *vim.rpcrequest()* special value Parameters: ~ - • {channel} (integer) - • {method} (string) - • {args} any[]|nil - • {...} any|nil + • {channel} (`integer`) + • {method} (`string`) + • {...} (`any?`) vim.schedule({fn}) *vim.schedule()* Schedules {fn} to be invoked soon by the main event-loop. Useful to avoid |textlock| or other temporary restrictions. Parameters: ~ - • {fn} (function) + • {fn} (`function`) vim.str_byteindex({str}, {index}, {use_utf16}) *vim.str_byteindex()* Convert UTF-32 or UTF-16 {index} to byte index. If {use_utf16} is not @@ -1000,9 +961,9 @@ vim.str_byteindex({str}, {index}, {use_utf16}) *vim.str_byteindex()* sequence. Parameters: ~ - • {str} (string) - • {index} (number) - • {use_utf16} any|nil + • {str} (`string`) + • {index} (`number`) + • {use_utf16} (`any?`) vim.str_utf_end({str}, {index}) *vim.str_utf_end()* Gets the distance (in bytes) from the last byte of the codepoint @@ -1019,11 +980,11 @@ vim.str_utf_end({str}, {index}) *vim.str_utf_end()* < Parameters: ~ - • {str} (string) - • {index} (number) + • {str} (`string`) + • {index} (`number`) Return: ~ - (number) + (`number`) vim.str_utf_pos({str}) *vim.str_utf_pos()* Gets a list of the starting byte positions of each UTF-8 codepoint in the @@ -1032,10 +993,10 @@ vim.str_utf_pos({str}) *vim.str_utf_pos()* Embedded NUL bytes are treated as terminating the string. Parameters: ~ - • {str} (string) + • {str} (`string`) Return: ~ - (table) + (`table`) vim.str_utf_start({str}, {index}) *vim.str_utf_start()* Gets the distance (in bytes) from the starting byte of the codepoint @@ -1055,11 +1016,11 @@ vim.str_utf_start({str}, {index}) *vim.str_utf_start()* < Parameters: ~ - • {str} (string) - • {index} (number) + • {str} (`string`) + • {index} (`number`) Return: ~ - (number) + (`number`) vim.str_utfindex({str}, {index}) *vim.str_utfindex()* Convert byte index to UTF-32 and UTF-16 indices. If {index} is not @@ -1071,23 +1032,23 @@ vim.str_utfindex({str}, {index}) *vim.str_utfindex()* that sequence. Parameters: ~ - • {str} (string) - • {index} (number|nil) + • {str} (`string`) + • {index} (`number?`) Return (multiple): ~ - (integer) UTF-32 index - (integer) UTF-16 index + (`integer`) UTF-32 index + (`integer`) UTF-16 index vim.stricmp({a}, {b}) *vim.stricmp()* Compares strings case-insensitively. Parameters: ~ - • {a} (string) - • {b} (string) + • {a} (`string`) + • {b} (`string`) Return: ~ - 0|1|-1 if strings are equal, {a} is greater than {b} or {a} is lesser - than {b}, respectively. + (`0|1|-1`) if strings are equal, {a} is greater than {b} or {a} is + lesser than {b}, respectively. vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()* Attach to ui events, similar to |nvim_ui_attach()| but receive events as @@ -1125,16 +1086,16 @@ vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()* < Parameters: ~ - • {ns} (integer) - • {options} table<string, any> - • {callback} fun() + • {ns} (`integer`) + • {options} (`table<string, any>`) + • {callback} (`fun()`) vim.ui_detach({ns}) *vim.ui_detach()* Detach a callback previously attached with |vim.ui_attach()| for the given namespace {ns}. Parameters: ~ - • {ns} (integer) + • {ns} (`integer`) vim.wait({time}, {callback}, {interval}, {fast_only}) *vim.wait()* Wait for {time} in milliseconds until {callback} returns `true`. @@ -1169,16 +1130,17 @@ vim.wait({time}, {callback}, {interval}, {fast_only}) *vim.wait()* < Parameters: ~ - • {time} (integer) Number of milliseconds to wait - • {callback} fun():|nil boolean Optional callback. Waits until + • {time} (`integer`) Number of milliseconds to wait + • {callback} (`fun(): boolean?`) Optional callback. Waits until {callback} returns true - • {interval} (integer|nil) (Approximate) number of milliseconds to - wait between polls - • {fast_only} (boolean|nil) If true, only |api-fast| events will be + • {interval} (`integer?`) (Approximate) number of milliseconds to wait + between polls + • {fast_only} (`boolean?`) If true, only |api-fast| events will be processed. - Return: ~ - boolean, nil|-1|-2 + Return (multiple): ~ + (`boolean`) + (`-1|-2?`) • If {callback} returns `true` during the {time}: `true, nil` • If {callback} never returns `true` during the {time}: `false, -1` • If {callback} is interrupted during the {time}: `false, -2` @@ -1188,18 +1150,15 @@ vim.wait({time}, {callback}, {interval}, {fast_only}) *vim.wait()* ============================================================================== LUA-VIMSCRIPT BRIDGE *lua-vimscript* - Nvim Lua provides an interface or "bridge" to Vimscript variables and functions, and editor commands and options. Objects passed over this bridge are COPIED (marshalled): there are no -"references". |lua-guide-variables| For example, using `vim.fn.remove()` -on a Lua list copies the list object to Vimscript and does NOT modify the -Lua list: >lua +"references". |lua-guide-variables| For example, using `vim.fn.remove()` on a +Lua list copies the list object to Vimscript and does NOT modify the Lua list: >lua local list = { 1, 2, 3 } vim.fn.remove(list, 0) vim.print(list) --> "{ 1, 2, 3 }" - < vim.call({func}, {...}) *vim.call()* @@ -1280,7 +1239,7 @@ vim.v *vim.v* |v:| variables. Invalid or unset key returns `nil`. -` ` *lua-options* + *lua-options* *lua-vim-options* *lua-vim-set* *lua-vim-setlocal* @@ -1303,9 +1262,10 @@ window-scoped options. Note that this must NOT be confused with |local-options| and |:setlocal|. There is also |vim.go| that only accesses the global value of a |global-local| option, see |:setglobal|. -` ` *vim.opt_local* - *vim.opt_global* - *vim.opt* + *vim.opt_local* + *vim.opt_global* + *vim.opt* + A special interface |vim.opt| exists for conveniently interacting with list- and map-style option from Lua: It allows accessing them as Lua tables and @@ -1366,6 +1326,7 @@ In any of the above examples, to replicate the behavior |:setlocal|, use `vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use `vim.opt_global`. + Option:append({value}) *vim.opt:append()* Append a value to string-style options. See |:set+=| @@ -1375,7 +1336,7 @@ Option:append({value}) *vim.opt:append()* < Parameters: ~ - • {value} (string) Value to append + • {value} (`string`) Value to append Option:get() *vim.opt:get()* Returns a Lua-representation of the option. Boolean, number and string @@ -1421,7 +1382,7 @@ Option:get() *vim.opt:get()* < Return: ~ - string|integer|boolean|nil value of option + (`string|integer|boolean?`) value of option Option:prepend({value}) *vim.opt:prepend()* Prepend a value to string-style options. See |:set^=| @@ -1432,7 +1393,7 @@ Option:prepend({value}) *vim.opt:prepend()* < Parameters: ~ - • {value} (string) Value to prepend + • {value} (`string`) Value to prepend Option:remove({value}) *vim.opt:remove()* Remove a value from string-style options. See |:set-=| @@ -1443,14 +1404,15 @@ Option:remove({value}) *vim.opt:remove()* < Parameters: ~ - • {value} (string) Value to remove + • {value} (`string`) Value to remove vim.bo *vim.bo* - Get or set buffer-scoped |options| for the buffer with number {bufnr}. - Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current - buffer is used. Invalid {bufnr} or key is an error. + Get or set buffer-scoped |options| for the buffer with number {bufnr}. If + {bufnr} is omitted then the current buffer is used. Invalid {bufnr} or key + is an error. - Note: this is equivalent to both `:set` and `:setlocal`. + Note: this is equivalent to `:setlocal` for |global-local| options and + `:set` otherwise. Example: >lua local bufnr = vim.api.nvim_get_current_buf() @@ -1469,9 +1431,6 @@ vim.env *vim.env* print(vim.env.TERM) < - Parameters: ~ - • {var} (string) - vim.go *vim.go* Get or set global |options|. Like `:setglobal`. Invalid key is an error. @@ -1499,9 +1458,10 @@ vim.o *vim.o* vim.wo *vim.wo* Get or set window-scoped |options| for the window with handle {winid} and - buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like - `:set` otherwise. If [{winid}] is omitted then the current window is used. - Invalid {winid}, {bufnr} or key is an error. + buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| + option or if {bufnr} is provided, like `:set` otherwise. If {winid} is + omitted then the current window is used. Invalid {winid}, {bufnr} or key + is an error. Note: only {bufnr} with value `0` (the current buffer in the window) is supported. @@ -1518,7 +1478,7 @@ vim.wo *vim.wo* ============================================================================== Lua module: vim *lua-vim* -vim.cmd *vim.cmd()* +vim.cmd({command}) *vim.cmd()* Executes Vim script commands. Note that `vim.cmd` can be indexed with a command name to return a @@ -1552,12 +1512,12 @@ vim.cmd *vim.cmd()* < Parameters: ~ - • {command} string|table Command(s) to execute. If a string, executes - multiple lines of Vim script at once. In this case, it is - an alias to |nvim_exec2()|, where `opts.output` is set to - false. Thus it works identical to |:source|. If a table, - executes a single command. In this case, it is an alias to - |nvim_cmd()| where `opts` is empty. + • {command} (`string|table`) Command(s) to execute. If a string, + executes multiple lines of Vim script at once. In this + case, it is an alias to |nvim_exec2()|, where `opts.output` + is set to false. Thus it works identical to |:source|. If a + table, executes a single command. In this case, it is an + alias to |nvim_cmd()| where `opts` is empty. See also: ~ • |ex-cmd-index| @@ -1569,33 +1529,34 @@ vim.defer_fn({fn}, {timeout}) *vim.defer_fn()* |vim.schedule_wrap()|ped automatically, so API functions are safe to call. Parameters: ~ - • {fn} (function) Callback to call once `timeout` expires - • {timeout} (integer) Number of milliseconds to wait before calling + • {fn} (`function`) Callback to call once `timeout` expires + • {timeout} (`integer`) Number of milliseconds to wait before calling `fn` Return: ~ - (table) timer luv timer object + (`table`) timer luv timer object *vim.deprecate()* vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) Shows a deprecation message to the user. Parameters: ~ - • {name} string Deprecated feature (function, API, etc.). - • {alternative} (string|nil) Suggested alternative feature. - • {version} string Version when the deprecated function will be removed. - • {plugin} string|nil Name of the plugin that owns the deprecated + • {name} (`string`) Deprecated feature (function, API, etc.). + • {alternative} (`string?`) Suggested alternative feature. + • {version} (`string`) Version when the deprecated function will be + removed. + • {plugin} (`string?`) Name of the plugin that owns the deprecated feature. Defaults to "Nvim". - • {backtrace} boolean|nil Prints backtrace. Defaults to true. + • {backtrace} (`boolean?`) Prints backtrace. Defaults to true. Return: ~ - (string|nil) Deprecated message, or nil if no message was shown. + (`string?`) Deprecated message, or nil if no message was shown. -vim.inspect *vim.inspect()* +vim.inspect() *vim.inspect()* Gets a human-readable representation of the given object. Return: ~ - (string) + (`string`) See also: ~ • |vim.print()| @@ -1611,20 +1572,23 @@ vim.keycode({str}) *vim.keycode()* < Parameters: ~ - • {str} (string) String to be converted. + • {str} (`string`) String to be converted. Return: ~ - (string) + (`string`) See also: ~ • |nvim_replace_termcodes()| -vim.lua_omnifunc({find_start}, {_}) *vim.lua_omnifunc()* +vim.lua_omnifunc({find_start}) *vim.lua_omnifunc()* Omnifunc for completing Lua values from the runtime Lua interpreter, similar to the builtin completion for the `:lua` command. Activate using `set omnifunc=v:lua.vim.lua_omnifunc` in a Lua buffer. + Parameters: ~ + • {find_start} (`1|0`) + vim.notify({msg}, {level}, {opts}) *vim.notify()* Displays a notification to the user. @@ -1633,9 +1597,9 @@ vim.notify({msg}, {level}, {opts}) *vim.notify()* writes to |:messages|. Parameters: ~ - • {msg} (string) Content of the notification to show to the user. - • {level} (integer|nil) One of the values from |vim.log.levels|. - • {opts} (table|nil) Optional parameters. Unused by default. + • {msg} (`string`) Content of the notification to show to the user. + • {level} (`integer?`) One of the values from |vim.log.levels|. + • {opts} (`table?`) Optional parameters. Unused by default. vim.notify_once({msg}, {level}, {opts}) *vim.notify_once()* Displays a notification only one time. @@ -1644,12 +1608,12 @@ vim.notify_once({msg}, {level}, {opts}) *vim.notify_once()* display a notification. Parameters: ~ - • {msg} (string) Content of the notification to show to the user. - • {level} (integer|nil) One of the values from |vim.log.levels|. - • {opts} (table|nil) Optional parameters. Unused by default. + • {msg} (`string`) Content of the notification to show to the user. + • {level} (`integer?`) One of the values from |vim.log.levels|. + • {opts} (`table?`) Optional parameters. Unused by default. Return: ~ - (boolean) true if message was displayed, else false + (`boolean`) true if message was displayed, else false vim.on_key({fn}, {ns_id}) *vim.on_key()* Adds Lua function {fn} with namespace id {ns_id} as a listener to every, @@ -1664,15 +1628,15 @@ vim.on_key({fn}, {ns_id}) *vim.on_key()* • {fn} will receive the keys after mappings have been evaluated Parameters: ~ - • {fn} fun(key: string) Function invoked on every key press. - |i_CTRL-V| Returning nil removes the callback associated with - namespace {ns_id}. - • {ns_id} integer? Namespace ID. If nil or 0, generates and returns a - new |nvim_create_namespace()| id. + • {fn} (`fun(key: string)?`) Function invoked on every key press. + |i_CTRL-V| Passing in nil when {ns_id} is specified removes + the callback associated with namespace {ns_id}. + • {ns_id} (`integer?`) Namespace ID. If nil or 0, generates and returns + a new |nvim_create_namespace()| id. Return: ~ - (integer) Namespace id associated with {fn}. Or count of all callbacks - if on_key() is called without arguments. + (`integer`) Namespace id associated with {fn}. Or count of all + callbacks if on_key() is called without arguments. vim.paste({lines}, {phase}) *vim.paste()* Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the @@ -1691,19 +1655,20 @@ vim.paste({lines}, {phase}) *vim.paste()* < Parameters: ~ - • {lines} string[] # |readfile()|-style list of lines to paste. + • {lines} (`string[]`) |readfile()|-style list of lines to paste. |channel-lines| - • {phase} paste_phase -1: "non-streaming" paste: the call contains all - lines. If paste is "streamed", `phase` indicates the stream state: + • {phase} (`-1|1|2|3`) -1: "non-streaming" paste: the call contains all + lines. If paste is "streamed", `phase` indicates the stream + state: • 1: starts the paste (exactly once) • 2: continues the paste (zero or more times) • 3: ends the paste (exactly once) Return: ~ - (boolean) result false if client should cancel the paste. + (`boolean`) result false if client should cancel the paste. See also: ~ - • |paste| @alias paste_phase -1 | 1 | 2 | 3 + • |paste| vim.print({...}) *vim.print()* "Pretty prints" the given arguments and returns them unmodified. @@ -1712,8 +1677,11 @@ vim.print({...}) *vim.print()* local hl_normal = vim.print(vim.api.nvim_get_hl(0, { name = 'Normal' })) < + Parameters: ~ + • {...} (`any`) + Return: ~ - any given arguments. + (`any`) given arguments. See also: ~ • |vim.inspect()| @@ -1729,17 +1697,17 @@ vim.region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) returned as |v:maxcol| (big number). Parameters: ~ - • {bufnr} (integer) Buffer number, or 0 for current buffer - • {pos1} integer[]|string Start of region as a (line, column) + • {bufnr} (`integer`) Buffer number, or 0 for current buffer + • {pos1} (`integer[]|string`) Start of region as a (line, column) tuple or |getpos()|-compatible string - • {pos2} integer[]|string End of region as a (line, column) tuple - or |getpos()|-compatible string - • {regtype} (string) |setreg()|-style selection type - • {inclusive} (boolean) Controls whether the ending column is inclusive - (see also 'selection'). + • {pos2} (`integer[]|string`) End of region as a (line, column) + tuple or |getpos()|-compatible string + • {regtype} (`string`) |setreg()|-style selection type + • {inclusive} (`boolean`) Controls whether the ending column is + inclusive (see also 'selection'). Return: ~ - (table) region Dict of the form `{linenr = {startcol,endcol}}`. + (`table`) region Dict of the form `{linenr = {startcol,endcol}}`. `endcol` is exclusive, and whole lines are returned as `{startcol,endcol} = {0,-1}`. @@ -1756,10 +1724,10 @@ vim.schedule_wrap({fn}) *vim.schedule_wrap()* < Parameters: ~ - • {fn} (function) + • {fn} (`function`) Return: ~ - (function) + (`function`) See also: ~ • |lua-loop-callbacks| @@ -1789,8 +1757,8 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()* throws an error if {cmd} cannot be run. Parameters: ~ - • {cmd} (string[]) Command to execute - • {opts} (SystemOpts|nil) Options: + • {cmd} (`string[]`) Command to execute + • {opts} (`vim.SystemOpts?`) Options: • cwd: (string) Set the current working directory for the sub-process. • env: table<string,string> Set environment variables for @@ -1820,12 +1788,13 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()* process will still keep the parent's event loop alive unless the parent process calls |uv.unref()| on the child's process handle. - • {on_exit} (function|nil) Called when subprocess exits. When provided, - the command runs asynchronously. Receives SystemCompleted - object, see return of SystemObj:wait(). + • {on_exit} (`fun(out: vim.SystemCompleted)?`) Called when subprocess + exits. When provided, the command runs asynchronously. + Receives SystemCompleted object, see return of + SystemObj:wait(). Return: ~ - vim.SystemObj Object with the fields: + (`vim.SystemObj`) Object with the fields: • pid (integer) Process ID • wait (fun(timeout: integer|nil): SystemCompleted) Wait for the process to complete. Upon timeout the process is sent the KILL @@ -1836,7 +1805,6 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()* • signal: (integer) • stdout: (string), nil if stdout argument is passed • stderr: (string), nil if stderr argument is passed - • kill (fun(signal: integer|string)) • write (fun(data: string|nil)) Requires `stdin=true`. Pass `nil` to close the stream. @@ -1852,24 +1820,24 @@ vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* Can also be pretty-printed with `:Inspect!`. *:Inspect!* Parameters: ~ - • {bufnr} (integer|nil) defaults to the current buffer - • {row} (integer|nil) row to inspect, 0-based. Defaults to the row - of the current cursor - • {col} (integer|nil) col to inspect, 0-based. Defaults to the col - of the current cursor - • {filter} (table|nil) a table with key-value pairs to filter the items - • syntax (boolean): include syntax based highlight groups - (defaults to true) - • treesitter (boolean): include treesitter based highlight - groups (defaults to true) - • extmarks (boolean|"all"): include extmarks. When `all`, - then extmarks without a `hl_group` will also be included - (defaults to true) - • semantic_tokens (boolean): include semantic tokens - (defaults to true) - - Return: ~ - (table) a table with the following key-value pairs. Items are in + • {bufnr} (`integer?`) defaults to the current buffer + • {row} (`integer?`) row to inspect, 0-based. Defaults to the row of + the current cursor + • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of + the current cursor + • {filter} (`table?`) Table with key-value pairs to filter the items + • {syntax} (`boolean`, default: `true`) Include syntax based + highlight groups. + • {treesitter} (`boolean`, default: `true`) Include + treesitter based highlight groups. + • {extmarks} (`boolean|"all"`, default: true) Include + extmarks. When `all`, then extmarks without a `hl_group` + will also be included. + • {semantic_tokens} (`boolean`, default: true) Include + semantic token highlights. + + Return: ~ + (`table`) a table with the following key-value pairs. Items are in "traversal order": • treesitter: a list of treesitter captures • syntax: a list of syntax groups @@ -1885,40 +1853,91 @@ vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* Can also be shown with `:Inspect`. *:Inspect* Parameters: ~ - • {bufnr} (integer|nil) defaults to the current buffer - • {row} (integer|nil) row to inspect, 0-based. Defaults to the row - of the current cursor - • {col} (integer|nil) col to inspect, 0-based. Defaults to the col - of the current cursor - • {filter} (table|nil) see |vim.inspect_pos()| + • {bufnr} (`integer?`) defaults to the current buffer + • {row} (`integer?`) row to inspect, 0-based. Defaults to the row of + the current cursor + • {col} (`integer?`) col to inspect, 0-based. Defaults to the col of + the current cursor + • {filter} (`table?`) A table with the following fields: + • {syntax} (`boolean`, default: `true`) Include syntax based + highlight groups. + • {treesitter} (`boolean`, default: `true`) Include + treesitter based highlight groups. + • {extmarks} (`boolean|"all"`, default: true) Include + extmarks. When `all`, then extmarks without a `hl_group` + will also be included. + • {semantic_tokens} (`boolean`, default: true) Include + semantic token highlights. + + + + +*vim.Ringbuf* + + Fields: ~ + • {clear} (`fun()`) Clear all items + • {push} (`fun(item: T)`) Adds an item, overriding the oldest item if + the buffer is full. + • {pop} (`fun(): T?`) Removes and returns the first unread item + • {peek} (`fun(): T?`) Returns the first unread item without removing + it + + +Ringbuf:clear() *Ringbuf:clear()* + Clear all items + +Ringbuf:peek() *Ringbuf:peek()* + Returns the first unread item without removing it + + Return: ~ + (`any?`) +Ringbuf:pop() *Ringbuf:pop()* + Removes and returns the first unread item + + Return: ~ + (`any?`) +Ringbuf:push({item}) *Ringbuf:push()* + Adds an item, overriding the oldest item if the buffer is full. + Parameters: ~ + • {item} (`any`) vim.deep_equal({a}, {b}) *vim.deep_equal()* Deep compare values for equality - Tables are compared recursively unless they both provide the `eq` metamethod. All other types are compared using the equality `==` operator. + Tables are compared recursively unless they both provide the `eq` + metamethod. All other types are compared using the equality `==` operator. Parameters: ~ - • {a} any First value - • {b} any Second value + • {a} (`any`) First value + • {b} (`any`) Second value Return: ~ - (boolean) `true` if values are equals, else `false` + (`boolean`) `true` if values are equals, else `false` -vim.deepcopy({orig}) *vim.deepcopy()* +vim.deepcopy({orig}, {noref}) *vim.deepcopy()* Returns a deep copy of the given object. Non-table objects are copied as in a typical Lua assignment, whereas table objects are copied recursively. Functions are naively copied, so functions in the copied table point to the same functions as those in the input table. Userdata and threads are not copied and will throw an error. + Note: `noref=true` is much more performant on tables with unique table + fields, while `noref=false` is more performant on tables that reuse table + fields. + Parameters: ~ - • {orig} (table) Table to copy + • {orig} (`table`) Table to copy + • {noref} (`boolean?`) When `false` (default) a contained table is only + copied once and all references point to this single copy. + When `true` every occurrence of a table results in a new + copy. This also means that a cyclic reference can cause + `deepcopy()` to fail. Return: ~ - (table) Table of copied keys and (nested) values. + (`table`) Table of copied keys and (nested) values. vim.defaulttable({createfn}) *vim.defaulttable()* Creates a table whose missing keys are provided by {createfn} (like @@ -1931,21 +1950,21 @@ vim.defaulttable({createfn}) *vim.defaulttable()* < Parameters: ~ - • {createfn} function?(key:any):any Provides the value for a missing + • {createfn} (`fun(key:any):any?`) Provides the value for a missing `key`. Return: ~ - (table) Empty table with `__index` metamethod. + (`table`) Empty table with `__index` metamethod. vim.endswith({s}, {suffix}) *vim.endswith()* Tests if `s` ends with `suffix`. Parameters: ~ - • {s} (string) String - • {suffix} (string) Suffix to match + • {s} (`string`) String + • {suffix} (`string`) Suffix to match Return: ~ - (boolean) `true` if `suffix` is a suffix of `s` + (`boolean`) `true` if `suffix` is a suffix of `s` vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()* Gets an |iterator| that splits a string at each instance of a separator, @@ -1965,15 +1984,16 @@ vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()* < Parameters: ~ - • {s} (string) String to split - • {sep} (string) Separator or pattern - • {opts} (table|nil) Keyword arguments |kwargs|: - • plain: (boolean) Use `sep` literally (as in string.find). - • trimempty: (boolean) Discard empty segments at start and end - of the sequence. + • {s} (`string`) String to split + • {sep} (`string`) Separator or pattern + • {opts} (`table?`) Keyword arguments |kwargs|: + • {plain}? (`boolean`) Use `sep` literally (as in + string.find). + • {trimempty}? (`boolean`) Discard empty segments at start and + end of the sequence. Return: ~ - (function) Iterator over the split components + (`fun():string?`) Iterator over the split components See also: ~ • |string.gmatch()| @@ -1986,20 +2006,20 @@ vim.is_callable({f}) *vim.is_callable()* Returns true if object `f` can be called as a function. Parameters: ~ - • {f} any Any object + • {f} (`any`) Any object Return: ~ - (boolean) `true` if `f` is callable, else `false` + (`boolean`) `true` if `f` is callable, else `false` vim.list_contains({t}, {value}) *vim.list_contains()* Checks if a list-like table (integer keys without gaps) contains `value`. Parameters: ~ - • {t} (table) Table to check (must be list-like, not validated) - • {value} any Value to compare + • {t} (`table`) Table to check (must be list-like, not validated) + • {value} (`any`) Value to compare Return: ~ - (boolean) `true` if `t` contains `value` + (`boolean`) `true` if `t` contains `value` See also: ~ • |vim.tbl_contains()| for checking values in general tables @@ -2010,13 +2030,13 @@ vim.list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* NOTE: This mutates dst! Parameters: ~ - • {dst} (table) List which will be modified and appended to - • {src} (table) List from which values will be inserted - • {start} (integer|nil) Start index on src. Defaults to 1 - • {finish} (integer|nil) Final index on src. Defaults to `#src` + • {dst} (`table`) List which will be modified and appended to + • {src} (`table`) List from which values will be inserted + • {start} (`integer?`) Start index on src. Defaults to 1 + • {finish} (`integer?`) Final index on src. Defaults to `#src` Return: ~ - (table) dst + (`table`) dst See also: ~ • |vim.tbl_extend()| @@ -2026,21 +2046,21 @@ vim.list_slice({list}, {start}, {finish}) *vim.list_slice()* (inclusive) Parameters: ~ - • {list} (list) Table - • {start} (integer|nil) Start range of slice - • {finish} (integer|nil) End range of slice + • {list} (`any[]`) Table + • {start} (`integer?`) Start range of slice + • {finish} (`integer?`) End range of slice Return: ~ - (list) Copy of table sliced from start to finish (inclusive) + (`any[]`) Copy of table sliced from start to finish (inclusive) vim.pesc({s}) *vim.pesc()* Escapes magic chars in |lua-patterns|. Parameters: ~ - • {s} (string) String to escape + • {s} (`string`) String to escape Return: ~ - (string) %-escaped pattern string + (`string`) %-escaped pattern string See also: ~ • https://github.com/rxi/lume @@ -2064,50 +2084,31 @@ vim.ringbuf({size}) *vim.ringbuf()* < Returns a Ringbuf instance with the following methods: - • |Ringbuf:push()| • |Ringbuf:pop()| • |Ringbuf:peek()| • |Ringbuf:clear()| Parameters: ~ - • {size} (integer) - - Return: ~ - (table) - -vim.Ringbuf:clear() *Ringbuf:clear()* - Clear all items. - -vim.Ringbuf:peek() *Ringbuf:peek()* - Returns the first unread item without removing it + • {size} (`integer`) Return: ~ - any?|nil - -vim.Ringbuf:pop() *Ringbuf:pop()* - Removes and returns the first unread item - - Return: ~ - any?|nil - -vim.Ringbuf:push({item}) *Ringbuf:push()* - Adds an item, overriding the oldest item if the buffer is full. - - Parameters: ~ - • {item} any + (`vim.Ringbuf`) ringbuf See |vim.Ringbuf|. vim.spairs({t}) *vim.spairs()* Enumerates key-value pairs of a table, ordered by key. Parameters: ~ - • {t} (table) Dict-like table + • {t} (`table`) Dict-like table - Return: ~ - (function) |for-in| iterator over sorted keys and their values + Return (multiple): ~ + (`fun(table: table<K, V>, index?: K):K, V`) |for-in| iterator over + sorted keys and their values + (`table`) See also: ~ - • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua + • Based on + https://github.com/premake/premake-core/blob/master/src/base/table.lua vim.split({s}, {sep}, {opts}) *vim.split()* Splits a string at each instance of a separator and returns the result as @@ -2121,13 +2122,16 @@ vim.split({s}, {sep}, {opts}) *vim.split()* < Parameters: ~ - • {s} (string) String to split - • {sep} (string) Separator or pattern - • {opts} (table|nil) Keyword arguments |kwargs| accepted by - |vim.gsplit()| + • {s} (`string`) String to split + • {sep} (`string`) Separator or pattern + • {opts} (`table?`) Keyword arguments |kwargs|: + • {plain}? (`boolean`) Use `sep` literally (as in + string.find). + • {trimempty}? (`boolean`) Discard empty segments at start and + end of the sequence. Return: ~ - string[] List of split components + (`string[]`) List of split components See also: ~ • |vim.gsplit()| @@ -2137,23 +2141,11 @@ vim.startswith({s}, {prefix}) *vim.startswith()* Tests if `s` starts with `prefix`. Parameters: ~ - • {s} (string) String - • {prefix} (string) Prefix to match - - Return: ~ - (boolean) `true` if `prefix` is a prefix of `s` - -vim.tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* - Add the reverse lookup values to an existing table. For example: - `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }` - - Note that this modifies the input. - - Parameters: ~ - • {o} (table) Table to add the reverse to + • {s} (`string`) String + • {prefix} (`string`) Prefix to match Return: ~ - (table) o + (`boolean`) `true` if `prefix` is a prefix of `s` vim.tbl_contains({t}, {value}, {opts}) *vim.tbl_contains()* Checks if a table contains a given value, specified either directly or via @@ -2167,14 +2159,14 @@ vim.tbl_contains({t}, {value}, {opts}) *vim.tbl_contains()* < Parameters: ~ - • {t} (table) Table to check - • {value} any Value to compare or predicate function reference - • {opts} (table|nil) Keyword arguments |kwargs|: - • predicate: (boolean) `value` is a function reference to be - checked (default false) + • {t} (`table`) Table to check + • {value} (`any`) Value to compare or predicate function reference + • {opts} (`table?`) Keyword arguments |kwargs|: + • {predicate}? (`boolean`) `value` is a function reference to + be checked (default false) Return: ~ - (boolean) `true` if `t` contains `value` + (`boolean`) `true` if `t` contains `value` See also: ~ • |vim.list_contains()| for checking values in list-like tables @@ -2186,10 +2178,10 @@ vim.tbl_count({t}) *vim.tbl_count()* < Parameters: ~ - • {t} (table) Table + • {t} (`table`) Table Return: ~ - (integer) Number of non-nil values in table + (`integer`) Number of non-nil values in table See also: ~ • https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua @@ -2198,15 +2190,15 @@ vim.tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* Merges recursively two or more tables. Parameters: ~ - • {behavior} (string) Decides what to do if a key is found in more than - one map: + • {behavior} (`"error"|"keep"|"force"`) (string) Decides what to do if + a key is found in more than one map: • "error": raise an error • "keep": use value from the leftmost map • "force": use value from the rightmost map - • {...} (table) Two or more tables + • {...} (`table`) Two or more tables Return: ~ - (table) Merged table + (`table`) Merged table See also: ~ • |vim.tbl_extend()| @@ -2215,15 +2207,15 @@ vim.tbl_extend({behavior}, {...}) *vim.tbl_extend()* Merges two or more tables. Parameters: ~ - • {behavior} (string) Decides what to do if a key is found in more than - one map: + • {behavior} (`string`) Decides what to do if a key is found in more + than one map: • "error": raise an error • "keep": use value from the leftmost map • "force": use value from the rightmost map - • {...} (table) Two or more tables + • {...} (`table`) Two or more tables Return: ~ - (table) Merged table + (`table`) Merged table See also: ~ • |extend()| @@ -2232,24 +2224,25 @@ vim.tbl_filter({func}, {t}) *vim.tbl_filter()* Filter a table using a predicate function Parameters: ~ - • {func} (function) Function - • {t} (table) Table + • {func} (`function`) Function + • {t} (`table`) Table Return: ~ - (table) Table of filtered values + (`any[]`) Table of filtered values vim.tbl_flatten({t}) *vim.tbl_flatten()* Creates a copy of a list-like table such that any nested tables are "unrolled" and appended to the result. Parameters: ~ - • {t} (table) List-like table + • {t} (`table`) List-like table Return: ~ - (table) Flattened copy of the given list-like table + (`table`) Flattened copy of the given list-like table See also: ~ - • From https://github.com/premake/premake-core/blob/master/src/base/table.lua + • From + https://github.com/premake/premake-core/blob/master/src/base/table.lua vim.tbl_get({o}, {...}) *vim.tbl_get()* Index into a table (first argument) via string keys passed as subsequent @@ -2261,15 +2254,16 @@ vim.tbl_get({o}, {...}) *vim.tbl_get()* < Parameters: ~ - • {o} (table) Table to index - • {...} any Optional keys (0 or more, variadic) via which to index the - table + • {o} (`table`) Table to index + • {...} (`any`) Optional keys (0 or more, variadic) via which to index + the table Return: ~ - any Nested value indexed by key (if it exists), else nil + (`any`) Nested value indexed by key (if it exists), else nil vim.tbl_isarray({t}) *vim.tbl_isarray()* - Tests if `t` is an "array": a table indexed only by integers (potentially non-contiguous). + Tests if `t` is an "array": a table indexed only by integers (potentially + non-contiguous). If the indexes start from 1 and are contiguous then the array is also a list. |vim.tbl_islist()| @@ -2279,10 +2273,10 @@ vim.tbl_isarray({t}) *vim.tbl_isarray()* |rpcrequest()| or |vim.fn|. Parameters: ~ - • {t} (table) + • {t} (`table`) Return: ~ - (boolean) `true` if array-like table, else `false`. + (`boolean`) `true` if array-like table, else `false`. See also: ~ • https://github.com/openresty/luajit2#tableisarray @@ -2291,27 +2285,27 @@ vim.tbl_isempty({t}) *vim.tbl_isempty()* Checks if a table is empty. Parameters: ~ - • {t} (table) Table to check + • {t} (`table`) Table to check Return: ~ - (boolean) `true` if `t` is empty + (`boolean`) `true` if `t` is empty See also: ~ • https://github.com/premake/premake-core/blob/master/src/base/table.lua vim.tbl_islist({t}) *vim.tbl_islist()* - Tests if `t` is a "list": a table indexed only by contiguous integers starting from 1 (what |lua-length| calls a "regular - array"). + Tests if `t` is a "list": a table indexed only by contiguous integers + starting from 1 (what |lua-length| calls a "regular array"). Empty table `{}` is a list, unless it was created by |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result, for example from |rpcrequest()| or |vim.fn|. Parameters: ~ - • {t} (table) + • {t} (`table`) Return: ~ - (boolean) `true` if list-like table, else `false`. + (`boolean`) `true` if list-like table, else `false`. See also: ~ • |vim.tbl_isarray()| @@ -2321,42 +2315,43 @@ vim.tbl_keys({t}) *vim.tbl_keys()* return table of keys is not guaranteed. Parameters: ~ - • {t} (table) Table + • {t} (`table`) Table Return: ~ - (list) List of keys + (`any[]`) List of keys See also: ~ - • From https://github.com/premake/premake-core/blob/master/src/base/table.lua + • From + https://github.com/premake/premake-core/blob/master/src/base/table.lua vim.tbl_map({func}, {t}) *vim.tbl_map()* Apply a function to all values of a table. Parameters: ~ - • {func} (function) Function - • {t} (table) Table + • {func} (`fun(value: T): any`) Function + • {t} (`table<any, T>`) Table Return: ~ - (table) Table of transformed values + (`table`) Table of transformed values vim.tbl_values({t}) *vim.tbl_values()* Return a list of all values used in a table. However, the order of the return table of values is not guaranteed. Parameters: ~ - • {t} (table) Table + • {t} (`table`) Table Return: ~ - (list) List of values + (`any[]`) List of values vim.trim({s}) *vim.trim()* Trim whitespace (Lua pattern "%s") from both sides of a string. Parameters: ~ - • {s} (string) String to trim + • {s} (`string`) String to trim Return: ~ - (string) String with whitespace removed from its beginning and end + (`string`) String with whitespace removed from its beginning and end See also: ~ • |lua-patterns| @@ -2396,7 +2391,7 @@ vim.validate({opt}) *vim.validate()* < Parameters: ~ - • {opt} (table) Names of parameters to validate. Each key is a + • {opt} (`table`) Names of parameters to validate. Each key is a parameter name; each value is a tuple in one of these forms: 1. (arg_value, type_name, optional) • arg_value: argument value @@ -2404,7 +2399,6 @@ vim.validate({opt}) *vim.validate()* "string", "s", "number", "n", "boolean", "b", "function", "f", "nil", "thread", "userdata") or list of them. • optional: (optional) boolean, if true, `nil` is valid - 2. (arg_value, fn, msg) • arg_value: argument value • fn: any function accepting one argument, returns true if @@ -2433,32 +2427,32 @@ vim.loader.find({modname}, {opts}) *vim.loader.find()* Finds Lua modules for the given module name. Parameters: ~ - • {modname} (string) Module name, or `"*"` to find the top-level + • {modname} (`string`) Module name, or `"*"` to find the top-level modules instead - • {opts} (table|nil) Options for finding a module: - • rtp: (boolean) Search for modname in the runtime path - (defaults to `true`) - • paths: (string[]) Extra paths to search for modname - (defaults to `{}`) - • patterns: (string[]) List of patterns to use when + • {opts} (`table?`) Options for finding a module: + • {rtp}? (`boolean`, default: `true`) Search for modname in + the runtime path. + • {paths}? (`string[]`, default: `{}`) Extra paths to + search for modname + • {patterns}? (`string[]`, default: + `{"/init.lua", ".lua"}`) List of patterns to use when searching for modules. A pattern is a string added to the - basename of the Lua module being searched. (defaults to - `{"/init.lua", ".lua"}`) - • all: (boolean) Return all matches instead of just the - first one (defaults to `false`) + basename of the Lua module being searched. + • {all}? (`boolean`, default: `false`) Search for all + matches. Return: ~ - (list) A list of results with the following properties: - • modpath: (string) the path to the module - • modname: (string) the name of the module - • stat: (table|nil) the fs_stat of the module path. Won't be returned - for `modname="*"` + (`table[]`) A list of objects with the following fields: + • {modpath} (`string`) Path of the module + • {modname} (`string`) Name of the module + • {stat}? (`uv.uv_fs_t`) The fs_stat of the module path. Won't be + returned for `modname="*"` vim.loader.reset({path}) *vim.loader.reset()* Resets the cache for the path, or all the paths if path is nil. Parameters: ~ - • {path} string? path to reset + • {path} (`string?`) path to reset ============================================================================== @@ -2468,57 +2462,57 @@ vim.uri_decode({str}) *vim.uri_decode()* URI-decodes a string containing percent escapes. Parameters: ~ - • {str} (string) string to decode + • {str} (`string`) string to decode Return: ~ - (string) decoded string + (`string`) decoded string vim.uri_encode({str}, {rfc}) *vim.uri_encode()* URI-encodes a string using percent escapes. Parameters: ~ - • {str} (string) string to encode - • {rfc} "rfc2396" | "rfc2732" | "rfc3986" | nil + • {str} (`string`) string to encode + • {rfc} (`"rfc2396"|"rfc2732"|"rfc3986"?`) Return: ~ - (string) encoded string + (`string`) encoded string vim.uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* Gets a URI from a bufnr. Parameters: ~ - • {bufnr} (integer) + • {bufnr} (`integer`) Return: ~ - (string) URI + (`string`) URI vim.uri_from_fname({path}) *vim.uri_from_fname()* Gets a URI from a file path. Parameters: ~ - • {path} (string) Path to file + • {path} (`string`) Path to file Return: ~ - (string) URI + (`string`) URI vim.uri_to_bufnr({uri}) *vim.uri_to_bufnr()* Gets the buffer for a uri. Creates a new unloaded buffer if no buffer for the uri already exists. Parameters: ~ - • {uri} (string) + • {uri} (`string`) Return: ~ - (integer) bufnr + (`integer`) bufnr vim.uri_to_fname({uri}) *vim.uri_to_fname()* Gets a filename from a URI. Parameters: ~ - • {uri} (string) + • {uri} (`string`) Return: ~ - (string) filename or unchanged URI for non-file URIs + (`string`) filename or unchanged URI for non-file URIs ============================================================================== @@ -2535,7 +2529,7 @@ vim.ui.input({opts}, {on_confirm}) *vim.ui.input()* < Parameters: ~ - • {opts} (table) Additional options. See |input()| + • {opts} (`table?`) Additional options. See |input()| • prompt (string|nil) Text of the prompt • default (string|nil) Default reply to the input • completion (string|nil) Specifies type of completion @@ -2544,7 +2538,7 @@ vim.ui.input({opts}, {on_confirm}) *vim.ui.input()* "-complete=" argument. See |:command-completion| • highlight (function) Function that will be used for highlighting user inputs. - • {on_confirm} (function) ((input|nil) -> ()) Called once the user + • {on_confirm} (`function`) ((input|nil) -> ()) Called once the user confirms or abort the input. `input` is what the user typed (it might be an empty string if nothing was entered), or `nil` if the user aborted the dialog. @@ -2563,11 +2557,11 @@ vim.ui.open({path}) *vim.ui.open()* < Parameters: ~ - • {path} (string) Path or URL to open + • {path} (`string`) Path or URL to open Return (multiple): ~ - vim.SystemCompleted|nil Command result, or nil if not found. - (string|nil) Error message on failure + (`vim.SystemCompleted?`) Command result, or nil if not found. + (`string?`) Error message on failure See also: ~ • |vim.system()| @@ -2592,8 +2586,8 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* < Parameters: ~ - • {items} (table) Arbitrary items - • {opts} (table) Additional options + • {items} (`any[]`) Arbitrary items + • {opts} (`table`) Additional options • prompt (string|nil) Text of the prompt. Defaults to `Select one of:` • format_item (function item -> text) Function to format @@ -2603,8 +2597,8 @@ vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* item shape. Plugins reimplementing `vim.ui.select` may wish to use this to infer the structure or semantics of `items`, or the context in which select() was called. - • {on_choice} (function) ((item|nil, idx|nil) -> ()) Called once the - user made a choice. `idx` is the 1-based index of `item` + • {on_choice} (`fun(item: any?, idx: integer?)`) Called once the user + made a choice. `idx` is the 1-based index of `item` within `items`. `nil` if the user aborted the dialog. @@ -2658,9 +2652,9 @@ vim.filetype.add({filetypes}) *vim.filetype.add()* ['/etc/foo/config'] = 'toml', }, pattern = { - ['.*‍/etc/foo/.*'] = 'fooscript', + ['.*/etc/foo/.*'] = 'fooscript', -- Using an optional priority - ['.*‍/etc/foo/.*%.conf'] = { 'dosini', { priority = 10 } }, + ['.*/etc/foo/.*%.conf'] = { 'dosini', { priority = 10 } }, -- A pattern containing an environment variable ['${XDG_CONFIG_HOME}/foo/git'] = 'git', ['README.(%a+)$'] = function(path, bufnr, ext) @@ -2693,8 +2687,11 @@ vim.filetype.add({filetypes}) *vim.filetype.add()* < Parameters: ~ - • {filetypes} (table) A table containing new filetype maps (see + • {filetypes} (`table`) A table containing new filetype maps (see example). + • {pattern}? (`vim.filetype.mapping`) + • {extension}? (`vim.filetype.mapping`) + • {filename}? (`vim.filetype.mapping`) *vim.filetype.get_option()* vim.filetype.get_option({filetype}, {option}) @@ -2713,11 +2710,11 @@ vim.filetype.get_option({filetype}, {option}) may not reflect later changes. Parameters: ~ - • {filetype} (string) Filetype - • {option} (string) Option name + • {filetype} (`string`) Filetype + • {option} (`string`) Option name Return: ~ - string|boolean|integer: Option value + (`string|boolean|integer`) Option value vim.filetype.match({args}) *vim.filetype.match()* Perform filetype detection. @@ -2749,24 +2746,24 @@ vim.filetype.match({args}) *vim.filetype.match()* < Parameters: ~ - • {args} (table) Table specifying which matching strategy to use. + • {args} (`table`) Table specifying which matching strategy to use. Accepted keys are: - • buf (number): Buffer number to use for matching. Mutually - exclusive with {contents} - • filename (string): Filename to use for matching. When {buf} - is given, defaults to the filename of the given buffer + • {buf}? (`integer`) Buffer number to use for matching. + Mutually exclusive with {contents} + • {filename}? (`string`) Filename to use for matching. When + {buf} is given, defaults to the filename of the given buffer number. The file need not actually exist in the filesystem. When used without {buf} only the name of the file is used for filetype matching. This may result in failure to detect the filetype in cases where the filename alone is not enough to disambiguate the filetype. - • contents (table): An array of lines representing file + • {contents}? (`string[]`) An array of lines representing file contents to use for matching. Can be used with {filename}. Mutually exclusive with {buf}. Return (multiple): ~ - (string|nil) If a match was found, the matched filetype. - (function|nil) A function that modifies buffer state when called (for + (`string?`) If a match was found, the matched filetype. + (`function?`) A function that modifies buffer state when called (for example, to set some filetype specific buffer variables). The function accepts a buffer number as its only argument. @@ -2782,9 +2779,11 @@ vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* < Parameters: ~ - • {opts} (table|nil) A table of optional arguments: - • "buffer": (integer|boolean) Remove a mapping from the given - buffer. When `0` or `true`, use the current buffer. + • {modes} (`string|string[]`) + • {lhs} (`string`) + • {opts} (`table?`) A table of optional arguments: + • "buffer": (integer|boolean) Remove a mapping from the given + buffer. When `0` or `true`, use the current buffer. See also: ~ • |vim.keymap.set()| @@ -2806,16 +2805,15 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* < Parameters: ~ - • {mode} string|table Mode short-name, see |nvim_set_keymap()|. Can + • {mode} (`string|table`) Mode short-name, see |nvim_set_keymap()|. Can also be list of modes to create mapping on multiple modes. - • {lhs} (string) Left-hand side |{lhs}| of the mapping. - • {rhs} string|function Right-hand side |{rhs}| of the mapping, can be - a Lua function. - • {opts} (table|nil) Table of |:map-arguments|. + • {lhs} (`string`) Left-hand side |{lhs}| of the mapping. + • {rhs} (`string|function`) Right-hand side |{rhs}| of the mapping, + can be a Lua function. + • {opts} (`table?`) Table of |:map-arguments|. • Same as |nvim_set_keymap()| {opts}, except: • "replace_keycodes" defaults to `true` if "expr" is `true`. • "noremap": inverse of "remap" (see below). - • Also accepts: • "buffer": (integer|boolean) Creates buffer-local mapping, `0` or `true` for current buffer. @@ -2836,26 +2834,26 @@ vim.fs.basename({file}) *vim.fs.basename()* Return the basename of the given path Parameters: ~ - • {file} (string) Path + • {file} (`string?`) Path Return: ~ - (string|nil) Basename of {file} + (`string?`) Basename of {file} vim.fs.dir({path}, {opts}) *vim.fs.dir()* Return an iterator over the items located in {path} Parameters: ~ - • {path} (string) An absolute or relative path to the directory to + • {path} (`string`) An absolute or relative path to the directory to iterate over. The path is first normalized |vim.fs.normalize()|. - • {opts} (table|nil) Optional keyword arguments: + • {opts} (`table?`) Optional keyword arguments: • depth: integer|nil How deep the traverse (default 1) • skip: (fun(dir_name: string): boolean)|nil Predicate to control traversal. Return false to stop searching the current directory. Only useful when depth > 1 Return: ~ - Iterator over items in {path}. Each iteration yields two values: + (`Iterator`) over items in {path}. Each iteration yields two values: "name" and "type". "name" is the basename of the item relative to {path}. "type" is one of the following: "file", "directory", "link", "fifo", "socket", "char", "block", "unknown". @@ -2864,10 +2862,10 @@ vim.fs.dirname({file}) *vim.fs.dirname()* Return the parent directory of the given path Parameters: ~ - • {file} (string) Path + • {file} (`string?`) Path Return: ~ - (string|nil) Parent directory of {file} + (`string?`) Parent directory of {file} vim.fs.find({names}, {opts}) *vim.fs.find()* Find files or directories (or other items as specified by `opts.type`) in @@ -2903,7 +2901,7 @@ vim.fs.find({names}, {opts}) *vim.fs.find()* < Parameters: ~ - • {names} (string|string[]|fun(name: string, path: string): boolean) + • {names} (`string|string[]|fun(name: string, path: string): boolean`) Names of the items to find. Must be base names, paths and globs are not supported when {names} is a string or a table. If {names} is a function, it is called for each traversed @@ -2911,32 +2909,33 @@ vim.fs.find({names}, {opts}) *vim.fs.find()* • name: base name of the current item • path: full path of the current item The function should return `true` if the given item is considered a match. - • {opts} (table) Optional keyword arguments: - • path (string): Path to begin searching from. If omitted, - the |current-directory| is used. - • upward (boolean, default false): If true, search upward + • {opts} (`table`) Optional keyword arguments: + • {path}? (`string`) Path to begin searching from. If + omitted, the |current-directory| is used. + • {upward}? (`boolean`, default: `false`) Search upward through parent directories. Otherwise, search through child directories (recursively). - • stop (string): Stop searching when this directory is + • {stop}? (`string`) Stop searching when this directory is reached. The directory itself is not searched. - • type (string): Find only items of the given type. If + • {type}? (`string`) Find only items of the given type. If omitted, all items that match {names} are included. - • limit (number, default 1): Stop the search after finding - this many matches. Use `math.huge` to place no limit on the - number of matches. + • {limit}? (`number`, default: `1`) Stop the search after + finding this many matches. Use `math.huge` to place no + limit on the number of matches. Return: ~ - (string[]) Normalized paths |vim.fs.normalize()| of all matching items + (`string[]`) Normalized paths |vim.fs.normalize()| of all matching + items vim.fs.joinpath({...}) *vim.fs.joinpath()* Concatenate directories and/or file paths into a single path with normalization (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`) Parameters: ~ - • {...} (string) + • {...} (`string`) Return: ~ - (string) + (`string`) vim.fs.normalize({path}, {opts}) *vim.fs.normalize()* Normalize a path to a standard format. A tilde (~) character at the @@ -2956,13 +2955,13 @@ vim.fs.normalize({path}, {opts}) *vim.fs.normalize()* < Parameters: ~ - • {path} (string) Path to normalize - • {opts} (table|nil) Options: - • expand_env: boolean Expand environment variables (default: - true) + • {path} (`string`) Path to normalize + • {opts} (`table?`) A table with the following fields: + • {expand_env} (`boolean`, default: `true`) Expand environment + variables. Return: ~ - (string) Normalized path + (`string`) Normalized path vim.fs.parents({start}) *vim.fs.parents()* Iterate over all the parents of the given path. @@ -2982,12 +2981,552 @@ vim.fs.parents({start}) *vim.fs.parents()* < Parameters: ~ - • {start} (string) Initial path. + • {start} (`string`) Initial path. + + Return (multiple): ~ + (`fun(_, dir: string): string?`) Iterator + (`nil`) + (`string?`) + + +============================================================================== +Lua module: vim.glob *vim.glob* + +vim.glob.to_lpeg({pattern}) *vim.glob.to_lpeg()* + Parses a raw glob into an |lua-lpeg| pattern. + + This uses glob semantics from LSP 3.17.0: + https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#pattern + + Glob patterns can have the following syntax: + • `*` to match one or more characters in a path segment + • `?` to match on one character in a path segment + • `**` to match any number of path segments, including none + • `{}` to group conditions (e.g. `*.{ts,js}` matches TypeScript and + JavaScript files) + • `[]` to declare a range of characters to match in a path segment (e.g., + `example.[0-9]` to match on `example.0`, `example.1`, …) + • `[!...]` to negate a range of characters to match in a path segment + (e.g., `example.[!0-9]` to match on `example.a`, `example.b`, but not + `example.0`) + + Parameters: ~ + • {pattern} (`string`) The raw glob pattern + + Return: ~ + (`vim.lpeg.Pattern`) pattern An |lua-lpeg| representation of the + pattern + + +============================================================================== +VIM.LPEG *vim.lpeg* + + +LPeg is a pattern-matching library for Lua, based on +Parsing Expression Grammars (https://bford.info/packrat/) (PEGs). + + *lua-lpeg* + *vim.lpeg.Pattern* +The LPeg library for parsing expression grammars is included as `vim.lpeg` +(https://www.inf.puc-rio.br/~roberto/lpeg/). + +In addition, its regex-like interface is available as |vim.re| +(https://www.inf.puc-rio.br/~roberto/lpeg/re.html). + + + +Pattern:match({subject}, {init}) *Pattern:match()* + Matches the given `pattern` against the `subject` string. If the match + succeeds, returns the index in the subject of the first character after + the match, or the captured values (if the pattern captured any value). An + optional numeric argument `init` makes the match start at that position in + the subject string. As usual in Lua libraries, a negative value counts + from the end. Unlike typical pattern-matching functions, `match` works + only in anchored mode; that is, it tries to match the pattern with a + prefix of the given subject string (at position `init`), not with an + arbitrary substring of the subject. So, if we want to find a pattern + anywhere in a string, we must either write a loop in Lua or write a + pattern that matches anywhere. + + Example: >lua + local pattern = lpeg.R('az') ^ 1 * -1 + assert(pattern:match('hello') == 6) + assert(lpeg.match(pattern, 'hello') == 6) + assert(pattern:match('1 hello') == nil) +< + + Parameters: ~ + • {subject} (`string`) + • {init} (`integer?`) + + Return: ~ + (`integer|vim.lpeg.Capture?`) + +vim.lpeg.B({pattern}) *vim.lpeg.B()* + Returns a pattern that matches only if the input string at the current + position is preceded by `patt`. Pattern `patt` must match only strings + with some fixed length, and it cannot contain captures. Like the `and` + predicate, this pattern never consumes any input, independently of success + or failure. + + Parameters: ~ + • {pattern} (`vim.lpeg.Pattern`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.C({patt}) *vim.lpeg.C()* + Creates a simple capture, which captures the substring of the subject that + matches `patt`. The captured value is a string. If `patt` has other + captures, their values are returned after this one. + + Example: >lua + local function split (s, sep) + sep = lpeg.P(sep) + local elem = lpeg.C((1 - sep) ^ 0) + local p = elem * (sep * elem) ^ 0 + return lpeg.match(p, s) + end + local a, b, c = split('a,b,c', ',') + assert(a == 'a') + assert(b == 'b') + assert(c == 'c') +< + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Carg({n}) *vim.lpeg.Carg()* + Creates an argument capture. This pattern matches the empty string and + produces the value given as the nth extra argument given in the call to + `lpeg.match`. + + Parameters: ~ + • {n} (`integer`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cb({name}) *vim.lpeg.Cb()* + Creates a back capture. This pattern matches the empty string and produces + the values produced by the most recent group capture named `name` (where + `name` can be any Lua value). Most recent means the last complete + outermost group capture with the given name. A Complete capture means that + the entire pattern corresponding to the capture has matched. An Outermost + capture means that the capture is not inside another complete capture. In + the same way that LPeg does not specify when it evaluates captures, it + does not specify whether it reuses values previously produced by the group + or re-evaluates them. + + Parameters: ~ + • {name} (`any`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cc({...}) *vim.lpeg.Cc()* + Creates a constant capture. This pattern matches the empty string and + produces all given values as its captured values. + + Parameters: ~ + • {...} (`any`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cf({patt}, {func}) *vim.lpeg.Cf()* + Creates a fold capture. If `patt` produces a list of captures C1 C2 ... + Cn, this capture will produce the value + `func(...func(func(C1, C2), C3)...,Cn)`, that is, it will fold (or + accumulate, or reduce) the captures from `patt` using function `func`. + This capture assumes that `patt` should produce at least one capture with + at least one value (of any type), which becomes the initial value of an + accumulator. (If you need a specific initial value, you may prefix a + constant captureto `patt`.) For each subsequent capture, LPeg calls `func` + with this accumulator as the first argument and all values produced by the + capture as extra arguments; the first result from this call becomes the + new value for the accumulator. The final value of the accumulator becomes + the captured value. + + Example: >lua + local number = lpeg.R('09') ^ 1 / tonumber + local list = number * (',' * number) ^ 0 + local function add(acc, newvalue) return acc + newvalue end + local sum = lpeg.Cf(list, add) + assert(sum:match('10,30,43') == 83) +< + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern`) + • {func} (`fun(acc, newvalue)`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cg({patt}, {name}) *vim.lpeg.Cg()* + Creates a group capture. It groups all values returned by `patt` into a + single capture. The group may be anonymous (if no name is given) or named + with the given name (which can be any non-nil Lua value). + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern`) + • {name} (`string?`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cmt({patt}, {fn}) *vim.lpeg.Cmt()* + Creates a match-time capture. Unlike all other captures, this one is + evaluated immediately when a match occurs (even if it is part of a larger + pattern that fails later). It forces the immediate evaluation of all its + nested captures and then calls `function`. The given function gets as + arguments the entire subject, the current position (after the match of + `patt`), plus any capture values produced by `patt`. The first value + returned by `function` defines how the match happens. If the call returns + a number, the match succeeds and the returned number becomes the new + current position. (Assuming a subject sand current position `i`, the + returned number must be in the range `[i, len(s) + 1]`.) If the call + returns `true`, the match succeeds without consuming any input (so, to + return true is equivalent to return `i`). If the call returns `false`, + `nil`, or no value, the match fails. Any extra values returned by the + function become the values produced by the capture. + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern`) + • {fn} (`function`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cp() *vim.lpeg.Cp()* + Creates a position capture. It matches the empty string and captures the + position in the subject where the match occurs. The captured value is a + number. + + Example: >lua + local I = lpeg.Cp() + local function anywhere(p) return lpeg.P({I * p * I + 1 * lpeg.V(1)}) end + local match_start, match_end = anywhere('world'):match('hello world!') + assert(match_start == 7) + assert(match_end == 12) +< + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Cs({patt}) *vim.lpeg.Cs()* + Creates a substitution capture. This function creates a substitution + capture, which captures the substring of the subject that matches `patt`, + with substitutions. For any capture inside `patt` with a value, the + substring that matched the capture is replaced by the capture value (which + should be a string). The final captured value is the string resulting from + all replacements. + + Example: >lua + local function gsub (s, patt, repl) + patt = lpeg.P(patt) + patt = lpeg.Cs((patt / repl + 1) ^ 0) + return lpeg.match(patt, s) + end + assert(gsub('Hello, xxx!', 'xxx', 'World') == 'Hello, World!') +< + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.Ct({patt}) *vim.lpeg.Ct()* + Creates a table capture. This capture returns a table with all values from + all anonymous captures made by `patt` inside this table in successive + integer keys, starting at 1. Moreover, for each named capture group + created by `patt`, the first value of the group is put into the table with + the group name as its key. The captured value is only the table. + + Parameters: ~ + • {patt} (`vim.lpeg.Pattern|''`) + + Return: ~ + (`vim.lpeg.Capture`) + +vim.lpeg.locale({tab}) *vim.lpeg.locale()* + Returns a table with patterns for matching some character classes + according to the current locale. The table has fields named `alnum`, + `alpha`, `cntrl`, `digit`, `graph`, `lower`, `print`, `punct`, `space`, + `upper`, and `xdigit`, each one containing a correspondent pattern. Each + pattern matches any single character that belongs to its class. If called + with an argument `table`, then it creates those fields inside the given + table and returns that table. + + Example: >lua + lpeg.locale(lpeg) + local space = lpeg.space ^ 0 + local name = lpeg.C(lpeg.alpha ^ 1) * space + local sep = lpeg.S(',;') * space + local pair = lpeg.Cg(name * '=' * space * name) * sep ^ -1 + local list = lpeg.Cf(lpeg.Ct('') * pair ^ 0, rawset) + local t = list:match('a=b, c = hi; next = pi') + assert(t.a == 'b') + assert(t.c == 'hi') + assert(t.next == 'pi') + local locale = lpeg.locale() + assert(type(locale.digit) == 'userdata') +< + + Parameters: ~ + • {tab} (`table?`) + + Return: ~ + (`vim.lpeg.Locale`) + +vim.lpeg.match({pattern}, {subject}, {init}) *vim.lpeg.match()* + Matches the given `pattern` against the `subject` string. If the match + succeeds, returns the index in the subject of the first character after + the match, or the captured values (if the pattern captured any value). An + optional numeric argument `init` makes the match start at that position in + the subject string. As usual in Lua libraries, a negative value counts + from the end. Unlike typical pattern-matching functions, `match` works + only in anchored mode; that is, it tries to match the pattern with a + prefix of the given subject string (at position `init`), not with an + arbitrary substring of the subject. So, if we want to find a pattern + anywhere in a string, we must either write a loop in Lua or write a + pattern that matches anywhere. + + Example: >lua + local pattern = lpeg.R('az') ^ 1 * -1 + assert(pattern:match('hello') == 6) + assert(lpeg.match(pattern, 'hello') == 6) + assert(pattern:match('1 hello') == nil) +< + + Parameters: ~ + • {pattern} (`vim.lpeg.Pattern`) + • {subject} (`string`) + • {init} (`integer?`) + + Return: ~ + (`integer|vim.lpeg.Capture?`) + +vim.lpeg.P({value}) *vim.lpeg.P()* + Converts the given value into a proper pattern. The following rules are + applied: + • If the argument is a pattern, it is returned unmodified. + • If the argument is a string, it is translated to a pattern that matches + the string literally. + • If the argument is a non-negative number `n`, the result is a pattern + that matches exactly `n` characters. + • If the argument is a negative number `-n`, the result is a pattern that + succeeds only if the input string has less than `n` characters left: + `lpeg.P(-n)` is equivalent to `-lpeg.P(n)` (see the unary minus + operation). + • If the argument is a boolean, the result is a pattern that always + succeeds or always fails (according to the boolean value), without + consuming any input. + • If the argument is a table, it is interpreted as a grammar (see + Grammars). + • If the argument is a function, returns a pattern equivalent to a + match-time capture over the empty string. + + Parameters: ~ + • {value} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.R({...}) *vim.lpeg.R()* + Returns a pattern that matches any single character belonging to one of + the given ranges. Each `range` is a string `xy` of length 2, representing + all characters with code between the codes of `x` and `y` (both + inclusive). As an example, the pattern `lpeg.R('09')` matches any digit, + and `lpeg.R('az', 'AZ')` matches any ASCII letter. + + Example: >lua + local pattern = lpeg.R('az') ^ 1 * -1 + assert(pattern:match('hello') == 6) +< + + Parameters: ~ + • {...} (`string`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.S({string}) *vim.lpeg.S()* + Returns a pattern that matches any single character that appears in the + given string (the `S` stands for Set). As an example, the pattern + `lpeg.S('+-*/')` matches any arithmetic operator. Note that, if `s` is a + character (that is, a string of length 1), then `lpeg.P(s)` is equivalent + to `lpeg.S(s)` which is equivalent to `lpeg.R(s..s)`. Note also that both + `lpeg.S('')` and `lpeg.R()` are patterns that always fail. + + Parameters: ~ + • {string} (`string`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.setmaxstack({max}) *vim.lpeg.setmaxstack()* + Sets a limit for the size of the backtrack stack used by LPeg to track + calls and choices. The default limit is `400`. Most well-written patterns + need little backtrack levels and therefore you seldom need to change this + limit; before changing it you should try to rewrite your pattern to avoid + the need for extra space. Nevertheless, a few useful patterns may + overflow. Also, with recursive grammars, subjects with deep recursion may + also need larger limits. + + Parameters: ~ + • {max} (`integer`) + +vim.lpeg.type({value}) *vim.lpeg.type()* + Returns the string `"pattern"` if the given value is a pattern, otherwise + `nil`. + + Parameters: ~ + • {value} (`vim.lpeg.Pattern|string|integer|boolean|table|function`) + + Return: ~ + (`"pattern"?`) + +vim.lpeg.V({v}) *vim.lpeg.V()* + Creates a non-terminal (a variable) for a grammar. This operation creates + a non-terminal (a variable) for a grammar. The created non-terminal refers + to the rule indexed by `v` in the enclosing grammar. + + Example: >lua + local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'}) + assert(b:match('((string))') == 11) + assert(b:match('(') == nil) +< + + Parameters: ~ + • {v} (`string|integer`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.lpeg.version() *vim.lpeg.version()* + Returns a string with the running version of LPeg. + + Return: ~ + (`string`) + + +============================================================================== +VIM.RE *vim.re* + +The `vim.re` module provides a conventional regex-like syntax for pattern +usage within LPeg |vim.lpeg|. + +See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original +documentation including regex syntax and more concrete examples. + + +vim.re.compile({string}, {defs}) *vim.re.compile()* + Compiles the given {string} and returns an equivalent LPeg pattern. The + given string may define either an expression or a grammar. The optional + {defs} table provides extra Lua values to be used by the pattern. + + Parameters: ~ + • {string} (`string`) + • {defs} (`table?`) + + Return: ~ + (`vim.lpeg.Pattern`) + +vim.re.find({subject}, {pattern}, {init}) *vim.re.find()* + Searches the given {pattern} in the given {subject}. If it finds a match, + returns the index where this occurrence starts and the index where it + ends. Otherwise, returns nil. + + An optional numeric argument {init} makes the search starts at that + position in the subject string. As usual in Lua libraries, a negative + value counts from the end. + + Parameters: ~ + • {subject} (`string`) + • {pattern} (`vim.lpeg.Pattern|string`) + • {init} (`integer?`) Return (multiple): ~ - fun(_, dir: string): string? Iterator - nil - (string|nil) + (`integer?`) the index where the occurrence starts, nil if no match + (`integer?`) the index where the occurrence ends, nil if no match + +vim.re.gsub({subject}, {pattern}, {replacement}) *vim.re.gsub()* + Does a global substitution, replacing all occurrences of {pattern} in the + given {subject} by {replacement}. + + Parameters: ~ + • {subject} (`string`) + • {pattern} (`vim.lpeg.Pattern|string`) + • {replacement} (`string`) + + Return: ~ + (`string`) + +vim.re.match({subject}, {pattern}, {init}) *vim.re.match()* + Matches the given {pattern} against the given {subject}, returning all + captures. + + Parameters: ~ + • {subject} (`string`) + • {pattern} (`vim.lpeg.Pattern|string`) + • {init} (`integer?`) + + Return: ~ + (`integer|vim.lpeg.Capture?`) + + See also: ~ + • vim.lpeg.match() + +vim.re.updatelocale() *vim.re.updatelocale()* + Updates the pre-defined character classes to the current locale. + + +============================================================================== +VIM.REGEX *vim.regex* + +Vim regexes can be used directly from Lua. Currently they only allow matching +within a single line. + + + *regex:match_line()* +regex:match_line({bufnr}, {line_idx}, {start}, {end_}) + Match line {line_idx} (zero-based) in buffer {bufnr}. If {start} and {end} + are supplied, match only this byte index range. Otherwise see + |regex:match_str()|. If {start} is used, then the returned byte indices + will be relative {start}. + + Parameters: ~ + • {bufnr} (`integer`) + • {line_idx} (`integer`) + • {start} (`integer?`) + • {end_} (`integer?`) + +regex:match_str({str}) *regex:match_str()* + Match the string against the regex. If the string should match the regex + precisely, surround the regex with `^` and `$`. If there was a match, the + byte indices for the beginning and end of the match are returned. When + there is no match, `nil` is returned. Because any integer is "truthy", + `regex:match_str()` can be directly used as a condition in an + if-statement. + + Parameters: ~ + • {str} (`string`) + +vim.regex({re}) *vim.regex()* + Parse the Vim regex {re} and return a regex object. Regexes are "magic" + and case-sensitive by default, regardless of 'magic' and 'ignorecase'. + They can be controlled with flags, see |/magic| and |/ignorecase|. + + Parameters: ~ + • {re} (`string`) + + Return: ~ + (`vim.regex`) ============================================================================== @@ -2999,10 +3538,10 @@ vim.secure.read({path}) *vim.secure.read()* $XDG_STATE_HOME/nvim/trust. Parameters: ~ - • {path} (string) Path to a file to read. + • {path} (`string`) Path to a file to read. Return: ~ - (string|nil) The contents of the given file if it exists and is + (`string?`) The contents of the given file if it exists and is trusted, or nil otherwise. See also: ~ @@ -3014,47 +3553,43 @@ vim.secure.trust({opts}) *vim.secure.trust()* The trust database is located at |$XDG_STATE_HOME|/nvim/trust. Parameters: ~ - • {opts} (table) - • action (string): "allow" to add a file to the trust database - and trust it, "deny" to add a file to the trust database and - deny it, "remove" to remove file from the trust database - • path (string|nil): Path to a file to update. Mutually + • {opts} (`table?`) A table with the following fields: + • {action} (`'allow'|'deny'|'remove'`) - `'allow'` to add a + file to the trust database and trust it, + • `'deny'` to add a file to the trust database and deny it, + • `'remove'` to remove file from the trust database + • {path}? (`string`) Path to a file to update. Mutually exclusive with {bufnr}. Cannot be used when {action} is "allow". - • bufnr (number|nil): Buffer number to update. Mutually + • {bufnr}? (`integer`) Buffer number to update. Mutually exclusive with {path}. Return (multiple): ~ - (boolean) success true if operation was successful - (string) msg full path if operation was successful, else error message + (`boolean`) success true if operation was successful + (`string`) msg full path if operation was successful, else error + message ============================================================================== Lua module: vim.version *vim.version* - -The `vim.version` module provides functions for comparing versions and -ranges conforming to the - -https://semver.org - -spec. Plugins, and plugin managers, can use this to check available tools -and dependencies on the current system. +The `vim.version` module provides functions for comparing versions and ranges +conforming to the https://semver.org spec. Plugins, and plugin managers, can +use this to check available tools and dependencies on the current system. Example: >lua local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false}) if vim.version.gt(v, {3, 2, 0}) then -- ... end - < *vim.version()* returns the version of the current Nvim process. -VERSION RANGE SPEC *version-range* +VERSION RANGE SPEC *version-range* -A version "range spec" defines a semantic version range which can be -tested against a version, using |vim.version.range()|. +A version "range spec" defines a semantic version range which can be tested +against a version, using |vim.version.range()|. Supported range specs are shown in the following table. Note: suffixed versions (1.2.3-rc1) are not matched. > @@ -3085,9 +3620,9 @@ versions (1.2.3-rc1) are not matched. > Partial left: missing pieces treated as 0 (1.2 => 1.2.0). 1.2 - 2.3.0 is 1.2.0 - 2.3.0 - < + vim.version.cmp({v1}, {v2}) *vim.version.cmp()* Parses and compares two version objects (the result of |vim.version.parse()|, or specified literally as a `{major, minor, patch}` @@ -3109,50 +3644,71 @@ vim.version.cmp({v1}, {v2}) *vim.version.cmp()* otherwise-equivalent versions. Parameters: ~ - • {v1} Version|number[] Version object. - • {v2} Version|number[] Version to compare with `v1` . + • {v1} (`vim.Version|number[]|string`) Version object. + • {v2} (`vim.Version|number[]|string`) Version to compare with `v1`. Return: ~ - (integer) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`. + (`integer`) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`. vim.version.eq({v1}, {v2}) *vim.version.eq()* - Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage. + Returns `true` if the given versions are equal. See |vim.version.cmp()| + for usage. Parameters: ~ - • {v1} Version|number[] - • {v2} Version|number[] + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) Return: ~ - (boolean) + (`boolean`) + +vim.version.ge({v1}, {v2}) *vim.version.ge()* + Returns `true` if `v1 >= v2`. See |vim.version.cmp()| for usage. + + Parameters: ~ + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) + + Return: ~ + (`boolean`) vim.version.gt({v1}, {v2}) *vim.version.gt()* - Returns `true` if `v1 > v2` . See |vim.version.cmp()| for usage. + Returns `true` if `v1 > v2`. See |vim.version.cmp()| for usage. Parameters: ~ - • {v1} Version|number[] - • {v2} Version|number[] + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) Return: ~ - (boolean) + (`boolean`) vim.version.last({versions}) *vim.version.last()* TODO: generalize this, move to func.lua Parameters: ~ - • {versions} Version [] + • {versions} (`vim.Version[]`) + + Return: ~ + (`vim.Version?`) + +vim.version.le({v1}, {v2}) *vim.version.le()* + Returns `true` if `v1 <= v2`. See |vim.version.cmp()| for usage. + + Parameters: ~ + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) Return: ~ - Version ?|nil + (`boolean`) vim.version.lt({v1}, {v2}) *vim.version.lt()* - Returns `true` if `v1 < v2` . See |vim.version.cmp()| for usage. + Returns `true` if `v1 < v2`. See |vim.version.cmp()| for usage. Parameters: ~ - • {v1} Version|number[] - • {v2} Version|number[] + • {v1} (`vim.Version|number[]|string`) + • {v2} (`vim.Version|number[]|string`) Return: ~ - (boolean) + (`boolean`) vim.version.parse({version}, {opts}) *vim.version.parse()* Parses a semantic version string and returns a version object which can be @@ -3162,18 +3718,19 @@ vim.version.parse({version}, {opts}) *vim.version.parse()* < Parameters: ~ - • {version} (string) Version string to parse. - • {opts} (table|nil) Optional keyword arguments: + • {version} (`string`) Version string to parse. + • {opts} (`table?`) Optional keyword arguments: • strict (boolean): Default false. If `true`, no coercion is attempted on input not conforming to semver v2.0.0. If `false`, `parse()` attempts to coerce input such as "1.0", "0-x", "tmux 3.2a" into valid versions. Return: ~ - (table|nil) parsed_version Version object or `nil` if input is invalid. + (`vim.Version?`) parsed_version Version object or `nil` if input is + invalid. See also: ~ - • # https://semver.org/spec/v2.0.0.html + • https://semver.org/spec/v2.0.0.html vim.version.range({spec}) *vim.version.range()* Parses a semver |version-range| "spec" and returns a range object: > @@ -3194,44 +3751,46 @@ vim.version.range({spec}) *vim.version.range()* print(r:has(vim.version())) -- check against current Nvim version < - Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly: >lua - local r = vim.version.range('1.0.0 - 2.0.0') - print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) + Or use cmp(), le(), lt(), ge(), gt(), and/or eq() to compare a version + against `.to` and `.from` directly: >lua + local r = vim.version.range('1.0.0 - 2.0.0') -- >=1.0, <2.0 + print(vim.version.ge({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) < Parameters: ~ - • {spec} (string) Version range "spec" + • {spec} (`string`) Version range "spec" + + Return: ~ + (`table?`) A table with the following fields: + • {from} (`vim.Version`) + • {to}? (`vim.Version`) + • {has} (`fun(self: vim.VersionRangeversion: string|vim.Version)`) See also: ~ - • # https://github.com/npm/node-semver#ranges + • https://github.com/npm/node-semver#ranges ============================================================================== Lua module: vim.iter *vim.iter* - *vim.iter()* is an interface for |iterable|s: it wraps a table or function argument into an *Iter* object with methods (such as |Iter:filter()| and -|Iter:map()|) that transform the underlying source data. These methods can -be chained to create iterator "pipelines": the output of each pipeline -stage is input to the next stage. The first stage depends on the type -passed to `vim.iter()`: - +|Iter:map()|) that transform the underlying source data. These methods can be +chained to create iterator "pipelines": the output of each pipeline stage is +input to the next stage. The first stage depends on the type passed to +`vim.iter()`: • List tables (arrays, |lua-list|) yield only the value of each element. • Use |Iter:enumerate()| to also pass the index to the next stage. • Or initialize with ipairs(): `vim.iter(ipairs(…))`. - -• Non-list tables (|lua-dict|) yield both the key and value of each - element. -• Function |iterator|s yield all values returned by the underlying - function. +• Non-list tables (|lua-dict|) yield both the key and value of each element. +• Function |iterator|s yield all values returned by the underlying function. • Tables with a |__call()| metamethod are treated as function iterators. -The iterator pipeline terminates when the underlying |iterable| is -exhausted (for function iterators this means it returned nil). +The iterator pipeline terminates when the underlying |iterable| is exhausted +(for function iterators this means it returned nil). -Note: `vim.iter()` scans table input to decide if it is a list or a dict; -to avoid this cost you can wrap the table with an iterator e.g. +Note: `vim.iter()` scans table input to decide if it is a list or a dict; to +avoid this cost you can wrap the table with an iterator e.g. `vim.iter(ipairs({…}))`, but that precludes the use of |list-iterator| operations such as |Iter:rev()|). @@ -3272,26 +3831,26 @@ Examples: >lua rb:push("b") vim.iter(rb):totable() -- { "a", "b" } - < In addition to the |vim.iter()| function, the |vim.iter| module provides convenience functions like |vim.iter.filter()| and |vim.iter.totable()|. -filter({f}, {src}, {...}) *vim.iter.filter()* + +filter({f}, {src}) *vim.iter.filter()* Filters a table or other |iterable|. >lua -- Equivalent to: vim.iter(src):filter(f):totable() < Parameters: ~ - • {f} function(...):bool Filter function. Accepts the current + • {f} (`fun(...):boolean`) Filter function. Accepts the current iterator or table values as arguments and returns true if those values should be kept in the final table - • {src} table|function Table or iterator function to filter + • {src} (`table|function`) Table or iterator function to filter Return: ~ - (table) + (`table`) See also: ~ • |Iter:filter()| @@ -3300,7 +3859,7 @@ Iter:all({pred}) *Iter:all()* Returns true if all items in the iterator match the given predicate. Parameters: ~ - • {pred} function(...):bool Predicate function. Takes all values + • {pred} (`fun(...):boolean`) Predicate function. Takes all values returned from the previous stage in the pipeline as arguments and returns true if the predicate matches. @@ -3309,7 +3868,7 @@ Iter:any({pred}) *Iter:any()* predicate. Parameters: ~ - • {pred} function(...):bool Predicate function. Takes all values + • {pred} (`fun(...):boolean`) Predicate function. Takes all values returned from the previous stage in the pipeline as arguments and returns true if the predicate matches. @@ -3321,7 +3880,7 @@ Iter:each({f}) *Iter:each()* |Iter:map()|. Parameters: ~ - • {f} function(...) Function to execute for each item in the pipeline. + • {f} (`fun(...)`) Function to execute for each item in the pipeline. Takes all of the values returned by the previous stage in the pipeline as arguments. @@ -3340,15 +3899,15 @@ Iter:enumerate() *Iter:enumerate()* Example: >lua local it = vim.iter(vim.gsplit('abc', '')):enumerate() it:next() - -- 1 'a' + -- 1 'a' it:next() - -- 2 'b' + -- 2 'b' it:next() - -- 3 'c' + -- 3 'c' < Return: ~ - Iter + (`Iter`) Iter:filter({f}) *Iter:filter()* Filters an iterator pipeline. @@ -3358,12 +3917,12 @@ Iter:filter({f}) *Iter:filter()* < Parameters: ~ - • {f} function(...):bool Takes all values returned from the previous + • {f} (`fun(...):boolean`) Takes all values returned from the previous stage in the pipeline and returns false or nil if the current iterator element should be removed. Return: ~ - Iter + (`Iter`) Iter:find({f}) *Iter:find()* Find the first value in the iterator that satisfies the given predicate. @@ -3385,8 +3944,33 @@ Iter:find({f}) *Iter:find()* -- 12 < + Parameters: ~ + • {f} (`any`) + + Return: ~ + (`any`) + +Iter:flatten({depth}) *Iter:flatten()* + Flattens a |list-iterator|, un-nesting nested values up to the given + {depth}. Errors if it attempts to flatten a dict-like value. + + Examples: >lua + vim.iter({ 1, { 2 }, { { 3 } } }):flatten():totable() + -- { 1, 2, { 3 } } + + vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable() + -- { 1, { a = 2 }, 3 } + + vim.iter({ 1, { { a = 2 } }, { 3 } }):flatten(math.huge):totable() + -- error: attempt to flatten a dict-like table +< + + Parameters: ~ + • {depth} (`number?`) Depth to which |list-iterator| should be + flattened (defaults to 1) + Return: ~ - any + (`Iter`) Iter:fold({init}, {f}) *Iter:fold()* Folds ("reduces") an iterator into a single value. @@ -3404,11 +3988,24 @@ Iter:fold({init}, {f}) *Iter:fold()* < Parameters: ~ - • {init} any Initial value of the accumulator. - • {f} function(acc:any, ...):A Accumulation function. + • {init} (`any`) Initial value of the accumulator. + • {f} (`fun(acc:A, ...):A`) Accumulation function. Return: ~ - any + (`any`) + +Iter:join({delim}) *Iter:join()* + Collect the iterator into a delimited string. + + Each element in the iterator is joined into a string separated by {delim}. + + Consumes the iterator. + + Parameters: ~ + • {delim} (`string`) Delimiter + + Return: ~ + (`string`) Iter:last() *Iter:last()* Drains the iterator and returns the last item. @@ -3424,7 +4021,7 @@ Iter:last() *Iter:last()* < Return: ~ - any + (`any`) Iter:map({f}) *Iter:map()* Maps the items of an iterator pipeline to the values returned by `f`. @@ -3442,13 +4039,13 @@ Iter:map({f}) *Iter:map()* < Parameters: ~ - • {f} function(...):any Mapping function. Takes all values returned - from the previous stage in the pipeline as arguments and returns - one or more new values, which are used in the next pipeline - stage. Nil return values are filtered from the output. + • {f} (`fun(...):any`) Mapping function. Takes all values returned from + the previous stage in the pipeline as arguments and returns one + or more new values, which are used in the next pipeline stage. + Nil return values are filtered from the output. Return: ~ - Iter + (`Iter`) Iter:next() *Iter:next()* Gets the next value from the iterator. @@ -3464,7 +4061,7 @@ Iter:next() *Iter:next()* < Return: ~ - any + (`any`) Iter:nextback() *Iter:nextback()* "Pops" a value from a |list-iterator| (gets the last value and decrements @@ -3479,7 +4076,7 @@ Iter:nextback() *Iter:nextback()* < Return: ~ - any + (`any`) Iter:nth({n}) *Iter:nth()* Gets the nth value of an iterator (and advances to it). @@ -3493,10 +4090,10 @@ Iter:nth({n}) *Iter:nth()* < Parameters: ~ - • {n} (number) The index of the value to return. + • {n} (`number`) The index of the value to return. Return: ~ - any + (`any`) Iter:nthback({n}) *Iter:nthback()* Gets the nth value from the end of a |list-iterator| (and advances to it). @@ -3510,10 +4107,10 @@ Iter:nthback({n}) *Iter:nthback()* < Parameters: ~ - • {n} (number) The index of the value to return. + • {n} (`number`) The index of the value to return. Return: ~ - any + (`any`) Iter:peek() *Iter:peek()* Gets the next value in a |list-iterator| without consuming it. @@ -3529,7 +4126,7 @@ Iter:peek() *Iter:peek()* < Return: ~ - any + (`any`) Iter:peekback() *Iter:peekback()* Gets the last value of a |list-iterator| without consuming it. @@ -3547,7 +4144,7 @@ Iter:peekback() *Iter:peekback()* < Return: ~ - any + (`any`) Iter:rev() *Iter:rev()* Reverses a |list-iterator| pipeline. @@ -3559,7 +4156,7 @@ Iter:rev() *Iter:rev()* < Return: ~ - Iter + (`Iter`) Iter:rfind({f}) *Iter:rfind()* Gets the first value in a |list-iterator| that satisfies a predicate, @@ -3571,13 +4168,16 @@ Iter:rfind({f}) *Iter:rfind()* Examples: >lua local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate() it:rfind(1) - -- 5 1 + -- 5 1 it:rfind(1) - -- 1 1 + -- 1 1 < + Parameters: ~ + • {f} (`any`) + Return: ~ - any + (`any`) See also: ~ • Iter.find @@ -3592,10 +4192,10 @@ Iter:skip({n}) *Iter:skip()* < Parameters: ~ - • {n} (number) Number of values to skip. + • {n} (`number`) Number of values to skip. Return: ~ - Iter + (`Iter`) Iter:skipback({n}) *Iter:skipback()* Skips `n` values backwards from the end of a |list-iterator| pipeline. @@ -3609,10 +4209,10 @@ Iter:skipback({n}) *Iter:skipback()* < Parameters: ~ - • {n} (number) Number of values to skip. + • {n} (`number`) Number of values to skip. Return: ~ - Iter + (`Iter`) Iter:slice({first}, {last}) *Iter:slice()* Sets the start and end of a |list-iterator| pipeline. @@ -3620,11 +4220,30 @@ Iter:slice({first}, {last}) *Iter:slice()* Equivalent to `:skip(first - 1):skipback(len - last + 1)`. Parameters: ~ - • {first} (number) - • {last} (number) + • {first} (`number`) + • {last} (`number`) Return: ~ - Iter + (`Iter`) + +Iter:take({n}) *Iter:take()* + Transforms an iterator to yield only the first n values. + + Example: >lua + local it = vim.iter({ 1, 2, 3, 4 }):take(2) + it:next() + -- 1 + it:next() + -- 2 + it:next() + -- nil +< + + Parameters: ~ + • {n} (`integer`) + + Return: ~ + (`Iter`) Iter:totable() *Iter:totable()* Collect the iterator into a table. @@ -3650,37 +4269,37 @@ Iter:totable() *Iter:totable()* |Iter:fold()|. Return: ~ - (table) + (`table`) -map({f}, {src}, {...}) *vim.iter.map()* +map({f}, {src}) *vim.iter.map()* Maps a table or other |iterable|. >lua -- Equivalent to: vim.iter(src):map(f):totable() < Parameters: ~ - • {f} function(...):?any Map function. Accepts the current iterator + • {f} (`fun(...): any?`) Map function. Accepts the current iterator or table values as arguments and returns one or more new values. Nil values are removed from the final table. - • {src} table|function Table or iterator function to filter + • {src} (`table|function`) Table or iterator function to filter Return: ~ - (table) + (`table`) See also: ~ • |Iter:map()| -totable({f}, {...}) *vim.iter.totable()* +totable({f}) *vim.iter.totable()* Collects an |iterable| into a table. >lua -- Equivalent to: vim.iter(f):totable() < Parameters: ~ - • {f} (function) Iterator function + • {f} (`function`) Iterator function Return: ~ - (table) + (`table`) ============================================================================== @@ -3690,18 +4309,20 @@ vim.snippet.active() *vim.snippet.active()* Returns `true` if there's an active snippet in the current buffer. Return: ~ - (boolean) + (`boolean`) vim.snippet.exit() *vim.snippet.exit()* Exits the current snippet. vim.snippet.expand({input}) *vim.snippet.expand()* - Expands the given snippet text. Refer to https://microsoft.github.io/language-server-protocol/specification/#snippet_syntax for the specification of valid input. + Expands the given snippet text. Refer to + https://microsoft.github.io/language-server-protocol/specification/#snippet_syntax + for the specification of valid input. Tabstops are highlighted with hl-SnippetTabstop. Parameters: ~ - • {input} (string) + • {input} (`string`) vim.snippet.jump({direction}) *vim.snippet.jump()* Jumps within the active snippet in the given direction. If the jump isn't @@ -3718,7 +4339,7 @@ vim.snippet.jump({direction}) *vim.snippet.jump()* < Parameters: ~ - • {direction} (vim.snippet.Direction) Navigation direction. -1 for + • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for previous, 1 for next. vim.snippet.jumpable({direction}) *vim.snippet.jumpable()* @@ -3735,11 +4356,11 @@ vim.snippet.jumpable({direction}) *vim.snippet.jumpable()* < Parameters: ~ - • {direction} (vim.snippet.Direction) Navigation direction. -1 for + • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for previous, 1 for next. Return: ~ - (boolean) + (`boolean`) ============================================================================== @@ -3749,18 +4370,50 @@ vim.text.hexdecode({enc}) *vim.text.hexdecode()* Hex decode a string. Parameters: ~ - • {enc} (string) String to decode + • {enc} (`string`) String to decode Return: ~ - (string) Decoded string + (`string`) Decoded string vim.text.hexencode({str}) *vim.text.hexencode()* Hex encode a string. Parameters: ~ - • {str} (string) String to encode + • {str} (`string`) String to encode Return: ~ - (string) Hex encoded string + (`string`) Hex encoded string + + +============================================================================== +Lua module: tohtml *vim.tohtml* + + +:TOhtml {file} *:TOhtml* +Converts the buffer shown in the current window to HTML, opens the generated +HTML in a new split window, and saves its contents to {file}. If {file} is not +given, a temporary file (created by |tempname()|) is used. + + +tohtml.tohtml({winid}, {opt}) *tohtml.tohtml.tohtml()* + Converts the buffer shown in the window {winid} to HTML and returns the + output as a list of string. + + Parameters: ~ + • {winid} (`integer?`) Window to convert (defaults to current window) + • {opt} (`table?`) Optional parameters. + • {title}? (`string|false`, default: buffer name) Title tag + to set in the generated HTML code. + • {number_lines}? (`boolean`, default: `false`) Show line + numbers. + • {font}? (`string[]|string`, default: `guifont`) Fonts to + use. + • {width}? (`integer`, default: 'textwidth' if non-zero or + window width otherwise) Width used for items which are + either right aligned or repeat a character infinitely. + + Return: ~ + (`string[]`) + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt index 467b5760cf..e7b62f4c6c 100644 --- a/runtime/doc/luaref.txt +++ b/runtime/doc/luaref.txt @@ -4150,7 +4150,7 @@ string.upper({s}) *string.upper()* locale. ------------------------------------------------------------------------------ -5.4.1 Patterns *lua-patterns +5.4.1 Patterns *lua-patterns* A character class is used to represent a set of characters. The following combinations are allowed in describing a character class: @@ -4811,7 +4811,7 @@ debug.setupvalue({func}, {up}, {value}) *debug.setupvalue()* upvalue with the given index. Otherwise, it returns the name of the upvalue. -debug.traceback([{thread},] [{message}] [,{level}]) *debug.traceback()* +debug.traceback([{thread},] [{message} [,{level}]]) *debug.traceback()* Returns a string with a traceback of the call stack. An optional {message} string is appended at the beginning of the traceback. An optional {level} number tells at which level to start the traceback diff --git a/runtime/doc/luvref.txt b/runtime/doc/luvref.txt index 915b69efe3..2be73f0412 100644 --- a/runtime/doc/luvref.txt +++ b/runtime/doc/luvref.txt @@ -837,7 +837,7 @@ uv.new_prepare() *uv.new_prepare()* Creates and initializes a new |uv_prepare_t|. Returns the Lua userdata wrapping it. - Returns: `uv_prepare_t userdata` or `fail` + Returns: `uv_prepare_t userdata` uv.prepare_start({prepare}, {callback}) *uv.prepare_start()* @@ -882,7 +882,7 @@ uv.new_check() *uv.new_check()* Creates and initializes a new |uv_check_t|. Returns the Lua userdata wrapping it. - Returns: `uv_check_t userdata` or `fail` + Returns: `uv_check_t userdata` uv.check_start({check}, {callback}) *uv.check_start()* @@ -934,7 +934,7 @@ uv.new_idle() *uv.new_idle()* Creates and initializes a new |uv_idle_t|. Returns the Lua userdata wrapping it. - Returns: `uv_idle_t userdata` or `fail` + Returns: `uv_idle_t userdata` uv.idle_start({idle}, {callback}) *uv.idle_start()* @@ -977,15 +977,15 @@ called from another thread. async:send() < -uv.new_async([{callback}]) *uv.new_async()* +uv.new_async({callback}) *uv.new_async()* Parameters: - - `callback`: `callable` or `nil` + - `callback`: `callable` - `...`: `threadargs` passed to/from `uv.async_send(async, ...)` Creates and initializes a new |uv_async_t|. Returns the Lua - userdata wrapping it. A `nil` callback is allowed. + userdata wrapping it. Returns: `uv_async_t userdata` or `fail` @@ -2067,17 +2067,17 @@ uv.pipe({read_flags}, {write_flags}) *uv.pipe()* uv.pipe_bind2({pipe}, {name}, {flags}) *uv.pipe_bind2()* > method form `pipe:pipe_bind(name, flags)` - + Parameters: - `pipe`: `uv_pipe_t userdata` - `name`: `string` - - `flags`: `integer` or `table` or `nil`(default: 0) + - `flags`: `integer` or `table` or `nil` (default: 0) Flags: - If `type(flags)` is `number`, it must be `0` or `uv.constants.PIPE_NO_TRUNCATE`. - If `type(flags)` is `table`, it must be `{}` or - `{ no_trunate = true|false }`. + `{ no_truncate = true|false }`. - If `type(flags)` is `nil`, it use default value `0`. - Returns `EINVAL` for unsupported flags without performing the bind. @@ -2101,7 +2101,7 @@ uv.pipe_connect2(pipe, name, [flags], [callback]) *uv.pipe_connect2()* Parameters: - `pipe`: `uv_pipe_t userdata` - `name`: `string` - - `flags`: `integer` or `table` or `nil`(default: 0) + - `flags`: `integer` or `table` or `nil` (default: 0) - `callback`: `callable` or `nil` - `err`: `nil` or `string` @@ -2110,7 +2110,7 @@ uv.pipe_connect2(pipe, name, [flags], [callback]) *uv.pipe_connect2()* - If `type(flags)` is `number`, it must be `0` or `uv.constants.PIPE_NO_TRUNCATE`. - If `type(flags)` is `table`, it must be `{}` or - `{ no_trunate = true|false }`. + `{ no_truncate = true|false }`. - If `type(flags)` is `nil`, it use default value `0`. - Returns `EINVAL` for unsupported flags without performing the bind operation. @@ -3630,6 +3630,42 @@ uv.thread_getcpu() *uv.thread_getcpu()* Returns: `integer` or `fail` +uv.thread_setpriority({thread}, {priority}) *uv.thread.setpriority()* + + > method form `thread:setpriority(priority)` + + Parameters: + - `thread`: `luv_thread_t userdata` + - `priority`: `number` + + Sets the specified thread's scheduling priority setting. It + requires elevated privilege to set specific priorities on some + platforms. The priority can be set to the following constants: + - `uv.constants.THREAD_PRIORITY_HIGHEST` + - `uv.constants.THREAD_PRIORITY_ABOVE_NORMAL` + - `uv.constants.THREAD_PRIORITY_NORMAL` + - `uv.constants.THREAD_PRIORITY_BELOW_NORMAL` + - `uv.constants.THREAD_PRIORITY_LOWEST` + + Returns: `boolean` or `fail` + +uv.thread_getpriority({thread}) *uv.thread.getpriority()* + + > method form `thread:getpriority()` + + Parameters: + - `thread`: `luv_thread_t userdata` + + Gets the thread's priority setting. + + Retrieves the scheduling priority of the specified thread. The + returned priority value is platform dependent. + + For Linux, when schedule policy is SCHED_OTHER (default), + priority is 0. + + Returns: `number` or `fail` + uv.thread_self() *uv.thread_self()* Returns the handle for the thread in which this is called. diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 6f61259af0..68206dd494 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -849,8 +849,15 @@ For the Meta modifier the "T" character is used. For example, to map Meta-b in Insert mode: > :imap <T-b> terrible +1.12 MAPPING SUPER-KEYS or COMMAND-KEYS *:map-super-keys* *:map-cmd-key* -1.12 MAPPING AN OPERATOR *:map-operator* +The Super / Command modifier is available if the terminal or GUI supports it. +The character "D" is used for the Super / Command modifier. + +For example, to map Command-b in Insert mode: > + :imap <D-b> barritone + +1.13 MAPPING AN OPERATOR *:map-operator* An operator is used before a {motion} command. To define your own operator you must create a mapping that first sets the 'operatorfunc' option and then @@ -1389,6 +1396,7 @@ completion can be enabled: -complete=help help subjects -complete=highlight highlight groups -complete=history :history suboptions + -complete=keymap keyboard mappings -complete=locale locale names (as output of locale -a) -complete=lua Lua expression |:lua| -complete=mapclear buffer argument diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index 9f06e8c931..c3154fc372 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -127,8 +127,6 @@ This happens when an Ex command executes an Ex command that executes an Ex command, etc. The limit is 200 or the value of 'maxfuncdepth', whatever is larger. When it's more there probably is an endless loop. Probably a |:execute| or |:source| command is involved. -Can also happen with a recursive callback function (|channel-callback|). -A limit of 20 is used here. *E254* > Cannot allocate color {name} diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index aa18e44225..e80969c583 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -578,7 +578,8 @@ i] *v_i]* *v_i[* *i]* *i[* i[ "inner [] block", select [count] '[' ']' blocks. This goes backwards to the [count] unclosed '[', and finds the matching ']'. The enclosed text is selected, - excluding the '[' and ']'. The |cpo-M| option flag + excluding the '[' and ']'. It's an error to select an + empty inner block like "[]". The |cpo-M| option flag is used to handle escaped brackets. When used in Visual mode it is made charwise. @@ -596,7 +597,8 @@ i( *vib* *v_ib* *v_i(* *ib* ib "inner block", select [count] blocks, from "[count] [(" to the matching ')', excluding the '(' and ')' (see |[(|). If the cursor is not inside a () block, then - find the next "(". The |cpo-M| option flag + find the next "(". It's an error to select an empty + inner block like "()". The |cpo-M| option flag is used to handle escaped parenthesis. When used in Visual mode it is made charwise. @@ -610,8 +612,9 @@ a< "a <> block", select [count] <> blocks, from the i> *v_i>* *v_i<* *i>* *i<* i< "inner <> block", select [count] <> blocks, from the [count]'th unmatched '<' backwards to the matching - '>', excluding the '<' and '>'. The |cpo-M| option flag - is used to handle escaped '<' and '>'. + '>', excluding the '<' and '>'. It's an error to + select an empty inner block like "<>". The |cpo-M| + option flag is used to handle escaped '<' and '>'. When used in Visual mode it is made charwise. *v_at* *at* @@ -640,7 +643,8 @@ i} *v_i}* *i}* *i{* i{ *v_iB* *v_i{* *iB* iB "inner Block", select [count] Blocks, from `[count] [{` to the matching "}", excluding the "{" and "}" (see - |[{|). The |cpo-M| option flag is used to handle + |[{|). It"s an error to select an empty inner block + like "{}". The |cpo-M| option flag is used to handle escaped braces. When used in Visual mode it is made charwise. @@ -1044,7 +1048,7 @@ CTRL-I Go to [count] newer cursor position in jump list |tui-modifyOtherKeys| or |tui-csiu|, CTRL-I can be mapped separately from <Tab>, on the condition that both keys are mapped, otherwise the mapping applies to - both. + both. Except in tmux: https://github.com/tmux/tmux/issues/2705 *:ju* *:jumps* :ju[mps] Print the jump list (not a motion command). @@ -1292,14 +1296,12 @@ bring you back to the switch statement. ]m Go to [count] next start of a method (for Java or similar structured language). When not before the start of a method, jump to the start or end of the - class. When no '{' is found after the cursor, this is - an error. |exclusive| motion. + class. |exclusive| motion. *]M* ]M Go to [count] next end of a method (for Java or similar structured language). When not before the end of a method, jump to the start or end of the class. - When no '}' is found after the cursor, this is an - error. |exclusive| motion. + |exclusive| motion. *[m* [m Go to [count] previous start of a method (for Java or similar structured language). When not after the diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 825e5ba41f..3029414500 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -15,7 +15,7 @@ BREAKING CHANGES *news-breaking* The following changes may require adaptations in user config or plugins. -• In some cases, the cursor in the Nvim |TUI| would blink even without +• In some cases, the cursor in the Nvim |TUI| used to blink even without configuring 'guicursor' as mentioned in |cursor-blinking|. This was a bug that has now been fixed. If your cursor has stopped blinking, add the following (or similar, adapted to user preference) to your |config| file: >vim @@ -71,9 +71,6 @@ The following changes may require adaptations in user config or plugins. now requires an explicit range argument to be passed. If injections are required, provide an explicit range via `parser:parse({ start_row, end_row })`. -• Float window support hide and show by setting `hide` on `nvim_open_win` and - `nvim_win_set_config`. - • |vim.lsp.util.parse_snippet()| will now strictly follow the snippet grammar defined by LSP, and hence previously parsed snippets might now be considered invalid input. @@ -95,14 +92,59 @@ The following changes may require adaptations in user config or plugins. • Legacy and extmark signs are displayed and listed with the same priority: line number -> priority -> sign id -> recently placed +• Default color scheme has been updated to be "Nvim branded" and accessible. + Use `:colorscheme vim` to revert to the old legacy color scheme. + + Here is a list of Nvim specific highlight groups which are now defined in + a meaningfully different way and might need an update: + • |hl-FloatBorder| is linked to |hl-NormalFloat| instead of |hl-WinSeparator|. + • |hl-NormalFloat| is not linked to |hl-Pmenu|. + • |hl-WinBar| has different background. + • |hl-WinBarNC| is similar to |hl-WinBar| but not bold. + • |hl-WinSeparator| is linked to |hl-Normal| instead of |hl-VertSplit|. + + This also might result into some color schemes looking differently due to + them relying on implicit assumptions about how highlight groups are defined + by default. To account for this, define all attributes of highlight groups + explicitly. Alternatively, use `:colorscheme vim` or `:source + $VIMRUNTIME/colors/vim.lua` to restore previous definitions. + +• 'termguicolors' is enabled by default when Nvim is able to determine that + the host terminal emulator supports 24-bit color. + +• Treesitter highlight groups have been renamed to be more in line with + upstream tree-sitter and Helix to make it easier to share queries. The full + list is documented in |treesitter-highlight-groups|. + +• |vim.lsp.codelens.refresh()| now takes an `opts` argument. With this change, + the default behavior of just refreshing the current buffer has been replaced by + refreshing all buffers. + +• |shm-q| now fully hides macro recording message instead of only shortening it. + +• Returning any truthy value from a callback passed to |nvim_create_autocmd()| + (rather than just `true`) will delete the autocommand. + +• |vim.lsp.util.extract_completion_items()| will no longer return reliable + results, since it does not apply `itemDefaults` when its input is a + `CompletionList`. + Moreover, since support for LSP `completionList.itemDefaults` was added, + some third party plugins might be negatively impacted in case the language + servers support the feature but the plugin does not. + If necessary, the respective capability can be + removed when calling |vim.lsp.protocol.make_client_capabilities()|. + +• |:TOhtml| has been rewritten in Lua to support Neovim-specific decorations, + and many options have been removed. + ============================================================================== BREAKING CHANGES IN HEAD *news-breaking-dev* The following breaking changes were made during the development cycle to unreleased features on Nvim HEAD. -• ... -• ... +• Removed `vim.treesitter.foldtext` as transparent foldtext is now supported + https://github.com/neovim/neovim/pull/20750 ============================================================================== NEW FEATURES *news-features* @@ -115,31 +157,39 @@ The following new APIs and features were added. • Treesitter highlighting now parses injections incrementally during screen redraws only for the line range being rendered. This significantly improves performance in large files with many injections. + • 'breakindent' performance is significantly improved for wrapped lines. + • Cursor movement, insertion with [count] and |screenpos()| are now faster. • |vim.iter()| provides a generic iterator interface for tables and Lua iterators |for-in|. -• Added |vim.ringbuf()| to create ring buffers. +• |vim.ringbuf()| creates ring buffers. -• Added |vim.keycode()| for translating keycodes in a string. +• |vim.keycode()| translates keycodes in a string. • |'smoothscroll'| option to scroll by screen line rather than by text line when |'wrap'| is set. -• Added inline virtual text support to |nvim_buf_set_extmark()|. +• |nvim_buf_set_extmark()| supports inline virtual text. • 'foldtext' now supports virtual text format. |fold-foldtext| +• |'foldtext'| can be set to an empty string to disable and render the line: + as normal with regular highlighting and no line wrapping. + • The terminal buffer now supports reflow (wrapped lines adapt when the buffer is resized horizontally). Note: Lines that are not visible and kept in |'scrollback'| are not reflown. • |vim.system()| for running system commands. -• Added |nvim_win_text_height()| to compute the number of screen lines occupied +• |vim.lpeg| and |vim.re| expose the bundled Lpeg expression grammar parser + and its regex interface. + +• |nvim_win_text_height()| computes the number of screen lines occupied by a range of text in a given window. -• |nvim_set_keymap()| and |nvim_del_keymap()| now support abbreviations. +• Mapping APIs now support abbreviations when mode short-name has suffix "a". • Better cmdline completion for string option value. |complete-set-option| @@ -158,7 +208,7 @@ The following new APIs and features were added. https://microsoft.github.io/language-server-protocol/specification/#textDocument_inlayHint • Implemented pull diagnostic textDocument/diagnostic: |vim.lsp.diagnostic.on_diagnostic()| https://microsoft.github.io/language-server-protocol/specification/#textDocument_diagnostic - • Added |vim.lsp.status()| to consume the last progress messages as a string. + • |vim.lsp.status()| consumes the last progress messages as a string. • LSP client now always saves and restores named buffer marks when applying text edits. • LSP client now supports the `positionEncoding` server capability. If a server @@ -169,26 +219,39 @@ The following new APIs and features were added. indicator to see if a server supports a feature. Instead use `client.supports_method(<method>)`. It considers both the dynamic capabilities and static `server_capabilities`. - • Added a new `anchor_bias` option to |lsp-handlers| to aid in positioning of - floating windows. + • `anchor_bias` option to |lsp-handlers| aids in positioning of floating + windows. + • |vim.lsp.util.locations_to_items()| sets the `user_data` of each item to + the original LSP `Location` or `LocationLink`. + • Added support for connecting to servers using named pipes (Windows) or + unix domain sockets (Unix) via |vim.lsp.rpc.domain_socket_connect()|. + • Added support for `completionList.itemDefaults`, reducing overhead when + computing completion items where properties often share the same value + (e.g. `commitCharacters`). Note that this might affect plugins and + language servers that don't support the feature, and in such cases the + respective capability can be unset. • Treesitter • Bundled parsers and queries (highlight, folds) for Markdown, Python, and Bash. - • Added |vim.treesitter.query.omnifunc()| for treesitter query files (set by + • |vim.treesitter.query.omnifunc()| for treesitter query files (set by default). • |Query:iter_matches()| now has the ability to set the maximum start depth for matches. - • `@injection.language` now has smarter resolution and will now fallback to language aliases and/or attempt lower case variants of the text. - language via aliases (e.g., filetype) registered via - `vim.treesitter.language.register`. - • The `#set!` directive now supports `injection.self` and `injection.parent` for injecting either the current node's language - or the parent LanguageTree's language, respectively. - • Added `vim.treesitter.query.edit()`, for live editing of treesitter + • `@injection.language` now has smarter resolution and will fall back to + language aliases (e.g., filetype or custom shorthands) registered via + |vim.treesitter.language.register()| and/or attempt lower case variants of + the text. + • The `#set!` directive now supports `injection.self` and `injection.parent` + for injecting either the current node's language or the parent + |LanguageTree|'s language, respectively. + • |vim.treesitter.query.edit()| allows live editing of treesitter queries. • Improved error messages for query parsing. - • Added |vim.treesitter.foldtext()| to apply treesitter highlighting to - foldtext. + • |:InspectTree| shows node ranges in 0-based indexing instead of 1-based + indexing. + • |:InspectTree| shows root nodes + • |:InspectTree| now supports |folding| • |vim.ui.open()| opens URIs using the system default handler (macOS `open`, Windows `explorer`, Linux `xdg-open`, etc.) @@ -200,34 +263,35 @@ The following new APIs and features were added. • `vim.*` • `vim.fn.*` • `vim.api.*` + • `vim.v.*` • Improved messages for type errors in `vim.api.*` calls (including `opts` params) • Functions that take a severity as an optional parameter (e.g. |vim.diagnostic.get()|) now also accept a list of severities |vim.diagnostic.severity| -• New RPC client type `msgpack-rpc` is added for `nvim_set_client_info` to +• New RPC client type `msgpack-rpc` is added for |nvim_set_client_info()| to support fully MessagePack-RPC compliant clients. • Floating windows can now show footer with new `footer` and `footer_pos` config fields. Uses |hl-FloatFooter| by default. -• The |:terminal| command now accepts some |:command-modifiers| (specifically - |:horizontal| and those that affect splitting a window). +• Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or + |nvim_win_set_config()|. -• |vim.lsp.util.locations_to_items()| sets the `user_data` of each item to the - original LSP `Location` or `LocationLink`. +• |:terminal| command now accepts some |:command-modifiers| (specifically + |:horizontal| and those that affect splitting a window). • |$NVIM_APPNAME| can be set to a relative path instead of only a name. -• Added |:fclose| command. +• |:fclose| command. -• Added |vim.snippet| for snippet expansion support. +• |vim.snippet| handles expansion of snippets in LSP format. • 'complete' option supports "f" flag for completing buffer names. -• Added |vim.base64.encode()| and |vim.base64.decode()| for encoding and decoding - strings using Base64 encoding. +• |vim.base64.encode()| and |vim.base64.decode()| encode and decode strings + using Base64 encoding. • The |TermResponse| autocommand event can be used with |v:termresponse| to read escape sequence responses from the terminal. @@ -236,11 +300,45 @@ The following new APIs and features were added. clipboard is now bundled by default and will be automatically enabled under certain conditions. |clipboard-osc52| -• The 'termsync' option asks the terminal emulator to buffer screen updates - until the redraw cycle is complete. Requires support from the terminal. +• 'termsync' option asks the terminal emulator to buffer screen updates until + the redraw cycle is complete. Requires support from the terminal. + +• |vim.text.hexencode()| and |vim.text.hexdecode()| convert strings to and + from byte representations. + +• 'completeopt' option supports "popup" flag to show extra information in a + floating window. + +• |nvim_input_mouse()| supports mouse buttons "x1" and "x2". + +• |v_Q-default| and |v_@-default| repeat a register for each line of a visual + selection. + +• |vim.diagnostic.count()| returns the number of diagnostics for a given + buffer and/or namespace, by severity. This is a faster alternative to + |vim.diagnostic.get()| when only the number of diagnostics is needed, but + not the diagnostics themselves. + +• |vim.deepcopy()| has a `noref` argument to avoid hashing table values. + +• Terminal buffers emit a |TermRequest| autocommand event when the child + process emits an OSC or DCS control sequence. -• Added |vim.text.hexencode()| and |vim.text.hexdecode()| to convert strings - to and from byte representations. +• Terminal buffers respond to OSC background and foreground requests. |default-autocmds| + +• |vim.version.le()| and |vim.version.ge()| are added to |vim.version|. + +• |extmarks| can be associated with a URL and URLs are included as a new + highlight attribute. The TUI will display URLs using the OSC 8 control + sequence, enabling clickable text in supporting terminals. + +• Added |nvim_tabpage_set_win()| to set the current window of a tabpage. + +• Clicking on a tabpage in the tabline with the middle mouse button closes it. + +• |namespace| can now have window scopes. |nvim_win_add_ns()| + +• |extmarks| option `scoped`: only show the extmarks in its namespace's scope. ============================================================================== CHANGED FEATURES *news-changed* @@ -253,7 +351,7 @@ The following changes to existing APIs or features add new behavior. • |vim.region()| can use a string accepted by |getpos()| as position. -• vim.diagnostic.config() now accepts a function for the virtual_text.prefix +• |vim.diagnostic.config()| now accepts a function for the virtual_text.prefix option, which allows for rendering e.g., diagnostic severities differently. • Defaults: @@ -266,16 +364,24 @@ The following changes to existing APIs or features add new behavior. vim.g.query_lint_on = {} < • Enabled treesitter highlighting for treesitter query files. + • Enabled treesitter highlighting for help files. + • Enabled treesitter highlighting for Lua files. • The `workspace/didChangeWatchedFiles` LSP client capability is now enabled by default. + • On Mac or Windows, `libuv.fs_watch` is used as the backend. + • On Linux, `fswatch` (recommended) is used as the backend if available, + otherwise `libuv.fs_event` is used on each subdirectory. • |LspRequest| autocmd callbacks now contain additional information about the LSP request status update that occurred. -• `:source` without arguments treats a buffer with its 'filetype' set to "lua" +• |:source| without arguments treats a buffer with its 'filetype' set to "lua" as Lua code regardless of its extension. +• |:lua| with a |[range]| executes that range in the current buffer as Lua code + regardless of its extension. + • |:checkhealth| buffer now implements |folding|. The initial folding status is defined by the 'foldenable' option. @@ -283,6 +389,7 @@ The following changes to existing APIs or features add new behavior. • |gx| now uses |vim.ui.open()| and not netrw. To customize, you can redefine `vim.ui.open` or remap `gx`. To continue using netrw (deprecated): >vim + :call netrw#BrowseX(expand(exists("g:netrw_gx")? g:netrw_gx : '<cfile>'), netrw#CheckIfRemote())<CR> • |vim.lsp.start()| now maps |K| to use |vim.lsp.buf.hover()| if the server @@ -307,11 +414,10 @@ The following changes to existing APIs or features add new behavior. In addition, |nvim_buf_get_extmarks()| has gained an "overlap" option to return such ranges even if they started before the specified position. -• Extmarks can opt-out of precise undo tracking using the new "undo_restore" - flag to |nvim_buf_set_extmark()| - -• Extmarks can be automatically hidden or removed using the new "invalidate" - flag to |nvim_buf_set_extmark()| +• The following flags were added to |nvim_buf_set_extmark()|: + - "undo_restore": opt-out extmarks of precise undo tracking. + - "invalidate": automatically hide or delete extmarks. + - "virt_text_repeat_linebreak": repeat virtual text on wrapped lines. • LSP hover and signature help now use Treesitter for highlighting of Markdown content. @@ -327,17 +433,50 @@ The following changes to existing APIs or features add new behavior. • |vim.wait()| is no longer allowed to be called in |api-fast|. +• Vimscript function |exists()| supports checking |v:lua| functions. + +• Added "force_crlf" option field in |nvim_open_term()|. + +• Attempting to set an invalid keycode option (e.g. `set t_foo=123`) no longer + gives an error. + +• Passing 0 to |nvim_get_chan_info()| gets info about the current channel. + +• |:checkhealth| buffer can now be opened in a split window using modifiers like + |:vertical|, |:horizontal| and |:botright|. + +• |nvim_open_win()| and |nvim_win_set_config()| now support opening normal (split) + windows, and moving floating windows into split windows. + +• 'errorfile' (|-q|) accepts `-` as an alias for stdin. + +• |--startuptime| reports the startup times for both processes (TUI + server) as separate sections. + +• |nvim_buf_call()| and |nvim_win_call()| now preserves any return value (NB: not multiple return values) + +• Treesitter + • |Query:iter_matches()|, |vim.treesitter.query.add_predicate()|, and + |vim.treesitter.query.add_directive()| accept a new `all` option which + ensures that all matching nodes are returned as a table. The default option + `all=false` returns only a single node, breaking captures with quantifiers + like `(comment)+ @comment; it is only provided for backward compatibility + and will be removed after Nvim 0.10. + • |vim.treesitter.query.add_predicate()| and + |vim.treesitter.query.add_directive()| now accept an options table rather + than a boolean "force" argument. To force a predicate or directive to + override an existing predicate or directive, use `{ force = true }`. + ============================================================================== REMOVED FEATURES *news-removed* The following deprecated functions or APIs were removed. -• Vimball support is removed. - - :Vimuntar command removed. +• Vimball support + - :Vimuntar command -• Support for legacy treesitter injection queries is removed. +• Support for legacy treesitter injection queries -• Removed 'shortmess' flags: +• 'shortmess' flags: - |shm-f|. Always uses "(3 of 5)", never "(file 3 of 5)" - |shm-i|. Always use "[noeol]". - |shm-x|. Always use "[dos]", "[unix]" and "[mac]" @@ -349,6 +488,9 @@ DEPRECATIONS *news-deprecations* The following functions are now deprecated and will be removed in a future release. +• Configuring |diagnostic-signs| using |:sign-define| or |sign_define()|. Use + the "signs" key of |vim.diagnostic.config()| instead. + • Checkhealth functions: - |health#report_error|, |vim.health.report_error()| Use |vim.health.error()| instead. - |health#report_info|, |vim.health.report_info()| Use |vim.health.info()| instead. @@ -375,13 +517,16 @@ release. - |vim.lsp.util.parse_snippet()| - |vim.lsp.util.text_document_completion_list_to_complete_items()| -• `vim.loop` has been renamed to `vim.uv`. +• `vim.loop` has been renamed to |vim.uv|. -• vim.treesitter.languagetree functions: +• vim.treesitter functions: - |LanguageTree:for_each_child()| Use |LanguageTree:children()| (non-recursive) instead. • The "term_background" UI option |ui-ext-options| is deprecated and no longer populated. Background color detection is now performed in Lua by the Nvim core, not the TUI. +• vim.shared functions: + - |vim.tbl_add_reverse_lookup()| + vim:tw=78:ts=8:sw=2:et:ft=help:norl: diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index dbc14f5a44..d4e05cee26 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -140,9 +140,9 @@ Example: >vim - |'channel'| Terminal PTY |job-id|. Can be used with |chansend()| to send input to the terminal. - The |TermClose| event gives the terminal job exit code in the |v:event| - "status" field. For example, this autocmd closes terminal buffers if the job - exited without error: >vim - autocmd TermClose * if !v:event.status | exe 'bdelete! '..expand('<abuf>') | endif + "status" field. For example, this autocommand outputs the terminal's exit + code to |:messages|: >vim + autocmd TermClose * echom 'Terminal exited with status '..v:event.status Use |jobwait()| to check if the terminal job has finished: >vim let running = jobwait([&channel], 0)[0] == -1 @@ -240,7 +240,7 @@ gdb window and use a "print" command, e.g.: > If mouse pointer movements are working, Vim will also show a balloon when the mouse rests on text that can be evaluated by gdb. You can also use the "K" mapping that will either use Nvim floating windows -if available to show the results or print below the status bar. +to show the results. Now go back to the source window and put the cursor on the first line after the for loop, then type: > @@ -283,8 +283,13 @@ gdb: `:Run` [args] run the program with [args] or the previous arguments `:Arguments` {args} set arguments for the next `:Run` - *:Break* set a breakpoint at the current line; a sign will be displayed - *:Clear* delete the breakpoint at the current line + *:Break* set a breakpoint at the cursor position + :Break {position} + set a breakpoint at the specified position + *:Tbreak* set a temporary breakpoint at the cursor position + :Tbreak {position} + set a temporary breakpoint at the specified position + *:Clear* delete the breakpoint at the cursor position *:Step* execute the gdb "step" command *:Over* execute the gdb "next" command (`:Next` is a Vim command) @@ -315,6 +320,8 @@ Inspecting variables ~ This is similar to using "print" in the gdb window. You can usually shorten `:Evaluate` to `:Ev`. +The result is displayed in a floating window. +You can move the cursor to this window by running `:Evaluate` (or `K`) again. Navigating stack frames ~ @@ -338,8 +345,8 @@ Other commands ~ *:Asm* jump to the window with the disassembly, create it if there isn't one *:Var* jump to the window with the local and argument variables, - create it if there isn't one. This window updates whenever the - program is stopped + create it if there isn't one. This window updates whenever the + program is stopped Events ~ *termdebug-events* @@ -470,10 +477,6 @@ If the command needs an argument use a List: >vim If there is no g:termdebug_config you can use: >vim let g:termdebugger = ['rr', 'replay', '--'] -To not use Nvim floating windows for previewing variable evaluation, set the -`g:termdebug_useFloatingHover` variable like this: >vim - let g:termdebug_useFloatingHover = 0 - If you are a mouse person, you can also define a mapping using your right click to one of the terminal command like evaluate the variable under the cursor: >vim diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index f47093782c..133b2bc33c 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -30,6 +30,7 @@ achieve special effects. These options come in three forms: *E518* *E519* :se[t] {option}? Show value of {option}. + NOTE: some legacy options were removed. |nvim-removed| :se[t] {option} Toggle option: set, switch it on. Number option: show value. @@ -301,11 +302,24 @@ created, thus they behave slightly differently: For a global option the global value is shown (but that might change in the future). -:setl[ocal] {option}< Set the local value of {option} to its global value by - copying the value. - -:se[t] {option}< For |global-local| options: Remove the local value of - {option}, so that the global value will be used. +:se[t] {option}< Set the effective value of {option} to its global + value. + For string |global-local| options, the local value is + removed, so that the global value will be used. + For all other options, the global value is copied to + the local value. + +:setl[ocal] {option}< Set the effective value of {option} to its global + value. + For number and boolean |global-local| options, the + local value is removed, so that the global value will + be used. + For all other options, including string |global-local| + options, the global value is copied to the local + value. + +Note that the behaviour for |global-local| options is slightly different +between string and number-based options. *:setg* *:setglobal* :setg[lobal][!] ... Like ":set" but set only the global value for a local @@ -731,8 +745,8 @@ A jump table for the options with a short description can be found at |Q_op|. from before it was deleted. When it appears again then it is read. |timestamp| If this option has a local value, use this command to switch back to - using the global value: > - :set autoread< + using the global value: >vim + set autoread< < *'autowrite'* *'aw'* *'noautowrite'* *'noaw'* @@ -773,23 +787,19 @@ A jump table for the options with a short description can be found at |Q_op|. See |:hi-normal| if you want to set the background color explicitly. *g:colors_name* When a color scheme is loaded (the "g:colors_name" variable is set) - setting 'background' will cause the color scheme to be reloaded. If + changing 'background' will cause the color scheme to be reloaded. If the color scheme adjusts to the value of 'background' this will work. However, if the color scheme sets 'background' itself the effect may be undone. First delete the "g:colors_name" variable when needed. Normally this option would be set in the vimrc file. Possibly - depending on the terminal name. Example: > - :if $TERM ==# "xterm" - : set background=dark - :endif -< When this option is set, the default settings for the highlight groups + depending on the terminal name. Example: >vim + if $TERM ==# "xterm" + set background=dark + endif +< When this option is changed, the default settings for the highlight groups will change. To use other settings, place ":highlight" commands AFTER the setting of the 'background' option. - This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file - to select the colors for syntax highlighting. After changing this - option, you must load syntax.vim again to see the result. This can be - done with ":syntax on". *'backspace'* *'bs'* 'backspace' 'bs' string (default "indent,eol,start") @@ -917,12 +927,12 @@ A jump table for the options with a short description can be found at |Q_op|. use '//', instead of '\\'. - Environment variables are expanded |:set_env|. - Careful with '\' characters, type one before a space, type two to - get one in the option (see |option-backslash|), for example: > - :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces + get one in the option (see |option-backslash|), for example: >vim + set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces < See also 'backup' and 'writebackup' options. - If you want to hide your backup files on Unix, consider this value: > - :set backupdir=./.backup,~/.backup,.,/tmp + If you want to hide your backup files on Unix, consider this value: >vim + set backupdir=./.backup,~/.backup,.,/tmp < You must create a ".backup" directory in each directory and in your home directory for this to work properly. The use of |:set+=| and |:set-=| is preferred when adding or removing @@ -943,8 +953,8 @@ A jump table for the options with a short description can be found at |Q_op|. If you like to keep a lot of backups, you could use a BufWritePre autocommand to change 'backupext' just before writing the file to - include a timestamp. > - :au BufWritePre * let &bex = '-' .. strftime("%Y%b%d%X") .. '~' + include a timestamp. >vim + au BufWritePre * let &bex = '-' .. strftime("%Y%b%d%X") .. '~' < Use 'backupdir' to put the backup in a different directory. *'backupskip'* *'bsk'* @@ -967,7 +977,7 @@ A jump table for the options with a short description can be found at |Q_op|. Note that environment variables are not expanded. If you want to use $HOME you must expand it explicitly, e.g.: >vim - :let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*' + let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*' < Note that the default also makes sure that "crontab -e" works (when a backup would be made by renaming the original file crontab won't see @@ -1230,8 +1240,8 @@ A jump table for the options with a short description can be found at |Q_op|. in the current directory first. If the default value taken from $CDPATH is not what you want, include a modified version of the following command in your vimrc file to - override it: > - :let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g') + override it: >vim + let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g') < This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. (parts of 'cdpath' can be passed to the shell to expand file names). @@ -1242,9 +1252,9 @@ A jump table for the options with a short description can be found at |Q_op|. The key used in Command-line Mode to open the command-line window. Only non-printable keys are allowed. The key can be specified as a single character, but it is difficult to - type. The preferred way is to use the <> notation. Examples: > - :exe "set cedit=\<C-Y>" - :exe "set cedit=\<Esc>" + type. The preferred way is to use the <> notation. Examples: >vim + exe "set cedit=\<C-Y>" + exe "set cedit=\<Esc>" < |Nvi| also has this option, but it only uses the first character. See |cmdwin|. @@ -1274,7 +1284,7 @@ A jump table for the options with a short description can be found at |Q_op|. Conversion between "latin1", "unicode", "ucs-2", "ucs-4" and "utf-8" is done internally by Vim, 'charconvert' is not used for this. Also used for Unicode conversion. - Example: > + Example: >vim set charconvert=CharConvert() fun CharConvert() system("recode " @@ -1326,7 +1336,7 @@ A jump table for the options with a short description can be found at |Q_op|. local to buffer Keywords that are interpreted as a C++ scope declaration by |cino-g|. Useful e.g. for working with the Qt framework that defines additional - scope declarations "signals", "public slots" and "private slots": > + scope declarations "signals", "public slots" and "private slots": >vim set cinscopedecls+=signals,public\ slots,private\ slots < @@ -1396,11 +1406,11 @@ A jump table for the options with a short description can be found at |Q_op|. highlighted with ColorColumn |hl-ColorColumn|. Useful to align text. Will make screen redrawing slower. The screen column can be an absolute number, or a number preceded with - '+' or '-', which is added to or subtracted from 'textwidth'. > + '+' or '-', which is added to or subtracted from 'textwidth'. >vim - :set cc=+1 " highlight column after 'textwidth' - :set cc=+1,+2,+3 " highlight three columns after 'textwidth' - :hi ColorColumn ctermbg=lightgrey guibg=lightgrey + set cc=+1 " highlight column after 'textwidth' + set cc=+1,+2,+3 " highlight three columns after 'textwidth' + hi ColorColumn ctermbg=lightgrey guibg=lightgrey < When 'textwidth' is zero then the items with '-' and '+' are not used. A maximum of 256 columns are highlighted. @@ -1417,8 +1427,8 @@ A jump table for the options with a short description can be found at |Q_op|. number of columns of the display, the display may be messed up. For the GUI it is always possible and Vim limits the number of columns to what fits on the screen. You can use this command to get the widest - window possible: > - :set columns=9999 + window possible: >vim + set columns=9999 < Minimum value is 12, maximum value is 10000. *'comments'* *'com'* *E524* *E525* @@ -1450,8 +1460,8 @@ A jump table for the options with a short description can be found at |Q_op|. k scan the files given with the 'dictionary' option kspell use the currently active spell checking |spell| k{dict} scan the file {dict}. Several "k" flags can be given, - patterns are valid too. For example: > - :set cpt=k/usr/dict/*,k~/spanish + patterns are valid too. For example: >vim + set cpt=k/usr/dict/*,k~/spanish < s scan the files given with the 'thesaurus' option s{tsr} scan the file {tsr}. Several "s" flags can be given, patterns are valid too. @@ -1507,14 +1517,18 @@ A jump table for the options with a short description can be found at |Q_op|. completion in the preview window. Only works in combination with "menu" or "menuone". - noinsert Do not insert any text for a match until the user selects + noinsert Do not insert any text for a match until the user selects a match from the menu. Only works in combination with "menu" or "menuone". No effect if "longest" is present. - noselect Do not select a match in the menu, force the user to + noselect Do not select a match in the menu, force the user to select one from the menu. Only works in combination with "menu" or "menuone". + popup Show extra information about the currently selected + completion in a popup window. Only works in combination + with "menu" or "menuone". Overrides "preview". + *'completeslash'* *'csl'* 'completeslash' 'csl' string (default "") local to buffer @@ -1719,9 +1733,6 @@ A jump table for the options with a short description can be found at |Q_op|. when it didn't exist when editing it. This is a protection against a file unexpectedly created by someone else. Vi didn't complain about this. - *cpo-p* - p Vi compatible Lisp indenting. When not present, a - slightly better algorithm is used. *cpo-P* P When included, a ":write" command that appends to a file will set the file name for the current buffer, if @@ -1848,7 +1859,7 @@ A jump table for the options with a short description can be found at |Q_op|. |hl-CursorColumn|. Useful to align text. Will make screen redrawing slower. If you only want the highlighting in the current window you can use - these autocommands: > + these autocommands: >vim au WinLeave * set nocursorline nocursorcolumn au WinEnter * set cursorline cursorcolumn < @@ -1911,7 +1922,7 @@ A jump table for the options with a short description can be found at |Q_op|. < If the function is defined with `func_name : function() {...`: > ^\s*\ze\i\+\s*[:]\s*(*function\s*( < When using the ":set" command, you need to double the backslashes! - To avoid that use `:let` with a single quote string: > + To avoid that use `:let` with a single quote string: >vim let &l:define = '^\s*\ze\k\+\s*=\s*function(' < @@ -2071,11 +2082,11 @@ A jump table for the options with a short description can be found at |Q_op|. patience patience diff algorithm histogram histogram diff algorithm - Examples: > - :set diffopt=internal,filler,context:4 - :set diffopt= - :set diffopt=internal,filler,foldcolumn:3 - :set diffopt-=internal " do NOT use the internal diff parser + Examples: >vim + set diffopt=internal,filler,context:4 + set diffopt= + set diffopt=internal,filler,foldcolumn:3 + set diffopt-=internal " do NOT use the internal diff parser < *'digraph'* *'dg'* *'nodigraph'* *'nodg'* @@ -2118,8 +2129,8 @@ A jump table for the options with a short description can be found at |Q_op|. - A directory name may end in an ':' or '/'. - Environment variables are expanded |:set_env|. - Careful with '\' characters, type one before a space, type two to - get one in the option (see |option-backslash|), for example: > - :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces + get one in the option (see |option-backslash|), for example: >vim + set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces < Editing the same file twice will result in a warning. Using "/tmp" on is discouraged: if the system crashes you lose the swap file. And @@ -2264,8 +2275,8 @@ A jump table for the options with a short description can be found at |Q_op|. A list of autocommand event names, which are to be ignored. When set to "all" or when "all" is one of the items, all autocommand events are ignored, autocommands will not be executed. - Otherwise this is a comma-separated list of event names. Example: > - :set ei=WinEnter,WinLeave + Otherwise this is a comma-separated list of event names. Example: >vim + set ei=WinEnter,WinLeave < *'expandtab'* *'et'* *'noexpandtab'* *'noet'* @@ -2347,7 +2358,7 @@ A jump table for the options with a short description can be found at |Q_op|. will work and the first entry of 'fileencodings' will be used (except "ucs-bom", which requires the BOM to be present). If you prefer another encoding use an BufReadPost autocommand event to test if your - preferred encoding is to be used. Example: > + preferred encoding is to be used. Example: >vim au BufReadPost * if search('\S', 'w') == 0 | \ set fenc=iso-2022-jp | endif < This sets 'fileencoding' to "iso-2022-jp" if the file does not contain @@ -2355,8 +2366,8 @@ A jump table for the options with a short description can be found at |Q_op|. When the |++enc| argument is used then the value of 'fileencodings' is not used. Note that 'fileencodings' is not used for a new file, the global value - of 'fileencoding' is used instead. You can set it with: > - :setglobal fenc=iso-8859-2 + of 'fileencoding' is used instead. You can set it with: >vim + setglobal fenc=iso-8859-2 < This means that a non-existing file may get a different encoding than an empty file. The special value "ucs-bom" can be used to check for a Unicode BOM @@ -2468,11 +2479,11 @@ A jump table for the options with a short description can be found at |Q_op|. this use the ":filetype on" command. |:filetype| Setting this option to a different value is most useful in a modeline, for a file for which the file type is not automatically recognized. - Example, for in an IDL file: > + Example, for in an IDL file: >c /* vim: set filetype=idl : */ < |FileType| |filetypes| When a dot appears in the value then this separates two filetype - names. Example: > + names. Example: >c /* vim: set filetype=c.doxygen : */ < This will use the "c" filetype first, then the "doxygen" filetype. This works both for filetype plugins and for syntax files. More than @@ -2487,7 +2498,7 @@ A jump table for the options with a short description can be found at |Q_op|. Characters to fill the statuslines, vertical separators and special lines in the window. It is a comma-separated list of items. Each item has a name, a colon - and the value of that item: + and the value of that item: |E1511| item default Used for ~ stl ' ' statusline of the current window @@ -2520,12 +2531,12 @@ A jump table for the options with a short description can be found at |Q_op|. "vert", "vertleft", "vertright", "verthoriz", "foldsep" and "fold" default to single-byte alternatives. - Example: > - :set fillchars=stl:\ ,stlnc:\ ,vert:│,fold:·,diff:- + Example: >vim + set fillchars=stl:\ ,stlnc:\ ,vert:│,fold:·,diff:- < For the "stl", "stlnc", "foldopen", "foldclose" and "foldsep" items single-byte and multibyte characters are supported. But double-width - characters are not supported. + characters are not supported. |E1512| The highlighting used for these items: item highlight group ~ @@ -2716,6 +2727,9 @@ A jump table for the options with a short description can be found at |Q_op|. It is not allowed to change text or jump to another window while evaluating 'foldtext' |textlock|. + When set to an empty string, foldtext is disabled, and the line + is displayed normally with highlighting and no line wrapping. + *'formatexpr'* *'fex'* 'formatexpr' 'fex' string (default "") local to buffer @@ -2730,8 +2744,8 @@ A jump table for the options with a short description can be found at |Q_op|. automatic formatting. This can be empty. Don't insert it yet! - Example: > - :set formatexpr=mylang#Format() + Example: >vim + set formatexpr=mylang#Format() < This will invoke the mylang#Format() function in the autoload/mylang.vim file in 'runtimepath'. |autoload| @@ -2745,7 +2759,7 @@ A jump table for the options with a short description can be found at |Q_op|. the internal format mechanism. If the expression starts with s: or |<SID>|, then it is replaced with - the script ID (|local-function|). Example: > + the script ID (|local-function|). Example: >vim set formatexpr=s:MyFormatExpr() set formatexpr=<SID>SomeFormatExpr() < Otherwise, the expression is evaluated in the context of the script @@ -2826,9 +2840,9 @@ A jump table for the options with a short description can be found at |Q_op|. :s///g subst. one subst. all :s///gg subst. all subst. one - DEPRECATED: Setting this option may break plugins that are not aware - of this option. Also, many users get confused that adding the /g flag - has the opposite effect of that it normally does. + NOTE: Setting this option may break plugins that rely on the default + behavior of the 'g' flag. This will also make the 'g' flag have the + opposite effect of that documented in |:s_g|. *'grepformat'* *'gfm'* 'grepformat' 'gfm' string (default "%f:%l:%m,%f:%l%m,%f %l%m") @@ -2847,8 +2861,8 @@ A jump table for the options with a short description can be found at |Q_op|. will be included. Environment variables are expanded |:set_env|. See |option-backslash| about including spaces and backslashes. When your "grep" accepts the "-H" argument, use this to make ":grep" - also work well with a single file: > - :set grepprg=grep\ -nH + also work well with a single file: >vim + set grepprg=grep\ -nH < Special value: When 'grepprg' is set to "internal" the |:grep| command works like |:vimgrep|, |:lgrep| like |:lvimgrep|, |:grepadd| like |:vimgrepadd| and |:lgrepadd| like |:lvimgrepadd|. @@ -2863,11 +2877,11 @@ A jump table for the options with a short description can be found at |Q_op|. Configures the cursor style for each mode. Works in the GUI and many terminals. See |tui-cursor-shape|. - To disable cursor-styling, reset the option: > - :set guicursor= + To disable cursor-styling, reset the option: >vim + set guicursor= -< To enable mode shapes, "Cursor" highlight, and blinking: > - :set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 +< To enable mode shapes, "Cursor" highlight, and blinking: >vim + set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor \,sm:block-blinkwait175-blinkoff150-blinkon175 @@ -2900,8 +2914,8 @@ A jump table for the options with a short description can be found at |Q_op|. the cursor starts blinking, blinkon is the time that the cursor is shown and blinkoff is the time that the cursor is not shown. Times are in msec. When one of - the numbers is zero, there is no blinking. E.g.: > - :set guicursor=n:blinkon0 + the numbers is zero, there is no blinking. E.g.: >vim + set guicursor=n:blinkon0 < - Default is "blinkon0" for each mode. {group-name} Highlight group that decides the color and font of the @@ -2939,9 +2953,9 @@ A jump table for the options with a short description can be found at |Q_op|. to do a common setting for all modes. For example, to switch off blinking: "a:blinkon0" - Examples of cursor highlighting: > - :highlight Cursor gui=reverse guifg=NONE guibg=NONE - :highlight Cursor gui=NONE guifg=bg guibg=fg + Examples of cursor highlighting: >vim + highlight Cursor gui=reverse guifg=NONE guibg=NONE + highlight Cursor gui=NONE guifg=bg guibg=fg < *'guifont'* *'gfn'* *E235* *E596* @@ -2956,8 +2970,8 @@ A jump table for the options with a short description can be found at |Q_op|. Spaces after a comma are ignored. To include a comma in a font name precede it with a backslash. Setting an option requires an extra backslash before a space and a backslash. See also - |option-backslash|. For example: > - :set guifont=Screen15,\ 7x13,font\\,with\\,commas + |option-backslash|. For example: >vim + set guifont=Screen15,\ 7x13,font\\,with\\,commas < will make Vim try to use the font "Screen15" first, and if it fails it will try to use "7x13" and then "font,with,commas" instead. @@ -2968,14 +2982,14 @@ A jump table for the options with a short description can be found at |Q_op|. the case of X). The font names given should be "normal" fonts. Vim will try to find the related bold and italic fonts. - For Win32 and Mac OS: > - :set guifont=* + For Win32 and Mac OS: >vim + set guifont=* < will bring up a font requester, where you can pick the font you want. The font name depends on the GUI used. - For Mac OSX you can use something like this: > - :set guifont=Monaco:h10 + For Mac OSX you can use something like this: >vim + set guifont=Monaco:h10 < *E236* Note that the fonts must be mono-spaced (all characters have the same width). @@ -3000,9 +3014,9 @@ A jump table for the options with a short description can be found at |Q_op|. Use a ':' to separate the options. - A '_' can be used in the place of a space, so you don't need to use backslashes to escape the spaces. - - Examples: > - :set guifont=courier_new:h12:w5:b:cRUSSIAN - :set guifont=Andale_Mono:h7.5:w4.5 + - Examples: >vim + set guifont=courier_new:h12:w5:b:cRUSSIAN + set guifont=Andale_Mono:h7.5:w4.5 < *'guifontwide'* *'gfw'* *E231* *E533* *E534* @@ -3142,8 +3156,8 @@ A jump table for the options with a short description can be found at |Q_op|. When non-empty describes the text to use in a tooltip for the GUI tab pages line. When empty Vim will use a default tooltip. This option is otherwise just like 'guitablabel' above. - You can include a line break. Simplest method is to use |:let|: > - :let &guitabtooltip = "line one\nline two" + You can include a line break. Simplest method is to use |:let|: >vim + let &guitabtooltip = "line one\nline two" < *'helpfile'* *'hf'* @@ -3177,8 +3191,8 @@ A jump table for the options with a short description can be found at |Q_op|. be used as a last resort. You can add "en" to prefer English over another language, but that will only find tags that exist in that language and not in the English help. - Example: > - :set helplang=de,it + Example: >vim + set helplang=de,it < This will first search German, then Italian and finally English help files. When using |CTRL-]| and ":help!" in a non-English help file Vim will @@ -3289,8 +3303,8 @@ A jump table for the options with a short description can be found at |Q_op|. 1 :lmap is ON and IM is off 2 :lmap is off and IM is ON To always reset the option to zero when leaving Insert mode with <Esc> - this can be used: > - :inoremap <ESC> <ESC>:set iminsert=0<CR> + this can be used: >vim + inoremap <ESC> <ESC>:set iminsert=0<CR> < This makes :lmap and IM turn off automatically when leaving Insert mode. Note that this option changes when using CTRL-^ in Insert mode @@ -3348,20 +3362,20 @@ A jump table for the options with a short description can be found at |Q_op|. 'includeexpr' 'inex' string (default "") local to buffer Expression to be used to transform the string found with the 'include' - option to a file name. Mostly useful to change "." to "/" for Java: > - :setlocal includeexpr=substitute(v:fname,'\\.','/','g') + option to a file name. Mostly useful to change "." to "/" for Java: >vim + setlocal includeexpr=substitute(v:fname,'\\.','/','g') < The "v:fname" variable will be set to the file name that was detected. Note the double backslash: the `:set` command first halves them, then one remains in the value, where "\." matches a dot literally. For - simple character replacements `tr()` avoids the need for escaping: > - :setlocal includeexpr=tr(v:fname,'.','/') + simple character replacements `tr()` avoids the need for escaping: >vim + setlocal includeexpr=tr(v:fname,'.','/') < Also used for the |gf| command if an unmodified file name can't be found. Allows doing "gf" on the name after an 'include' statement. Also used for |<cfile>|. If the expression starts with s: or |<SID>|, then it is replaced with - the script ID (|local-function|). Example: > + the script ID (|local-function|). Example: >vim setlocal includeexpr=s:MyIncludeExpr(v:fname) setlocal includeexpr=<SID>SomeIncludeExpr(v:fname) < Otherwise, the expression is evaluated in the context of the script @@ -3395,7 +3409,7 @@ A jump table for the options with a short description can be found at |Q_op|. typing a search command. See also: 'hlsearch'. If you don't want to turn 'hlsearch' on, but want to highlight all matches while searching, you can turn on and off 'hlsearch' with - autocmd. Example: > + autocmd. Example: >vim augroup vimrc-incsearch-highlight autocmd! autocmd CmdlineEnter /,\? :set hlsearch @@ -3423,7 +3437,7 @@ A jump table for the options with a short description can be found at |Q_op|. when the expression is evaluated (but it may be moved around). If the expression starts with s: or |<SID>|, then it is replaced with - the script ID (|local-function|). Example: > + the script ID (|local-function|). Example: >vim set indentexpr=s:MyIndentExpr() set indentexpr=<SID>SomeIndentExpr() < Otherwise, the expression is evaluated in the context of the script @@ -3437,8 +3451,8 @@ A jump table for the options with a short description can be found at |Q_op|. The evaluation of the expression must not have side effects! It must not change the text, jump to another window, etc. Afterwards the cursor position is always restored, thus the cursor may be moved. - Normally this option would be set to call a function: > - :set indentexpr=GetMyIndent() + Normally this option would be set to call a function: >vim + set indentexpr=GetMyIndent() < Error messages will be suppressed, unless the 'debug' option contains "msg". See |indent-expression|. @@ -3635,9 +3649,9 @@ A jump table for the options with a short description can be found at |Q_op|. When "man" or "man -s" is used, Vim will automatically translate a [count] for the "K" command to a section number. See |option-backslash| about including spaces and backslashes. - Example: > - :set keywordprg=man\ -s - :set keywordprg=:Man + Example: >vim + set keywordprg=man\ -s + set keywordprg=:Man < This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -3657,10 +3671,10 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - Example (for Greek, in UTF-8): *greek* > - :set langmap=ΑA,ΒB,ΨC,ΔD,ΕE,ΦF,ΓG,ΗH,ΙI,ΞJ,ΚK,ΛL,ΜM,ΝN,ΟO,ΠP,QQ,ΡR,ΣS,ΤT,ΘU,ΩV,WW,ΧX,ΥY,ΖZ,αa,βb,ψc,δd,εe,φf,γg,ηh,ιi,ξj,κk,λl,μm,νn,οo,πp,qq,ρr,σs,τt,θu,ωv,ςw,χx,υy,ζz -< Example (exchanges meaning of z and y for commands): > - :set langmap=zy,yz,ZY,YZ + Example (for Greek, in UTF-8): *greek* >vim + set langmap=ΑA,ΒB,ΨC,ΔD,ΕE,ΦF,ΓG,ΗH,ΙI,ΞJ,ΚK,ΛL,ΜM,ΝN,ΟO,ΠP,QQ,ΡR,ΣS,ΤT,ΘU,ΩV,WW,ΧX,ΥY,ΖZ,αa,βb,ψc,δd,εe,φf,γg,ηh,ιi,ξj,κk,λl,μm,νn,οo,πp,qq,ρr,σs,τt,θu,ωv,ςw,χx,υy,ζz +< Example (exchanges meaning of z and y for commands): >vim + set langmap=zy,yz,ZY,YZ < The 'langmap' option is a list of parts, separated with commas. Each part can be in one of two forms: @@ -3688,22 +3702,22 @@ A jump table for the options with a short description can be found at |Q_op|. 'langmenu' 'lm' string (default "") global Language to use for menu translation. Tells which file is loaded - from the "lang" directory in 'runtimepath': > + from the "lang" directory in 'runtimepath': >vim "lang/menu_" .. &langmenu .. ".vim" < (without the spaces). For example, to always use the Dutch menus, no - matter what $LANG is set to: > - :set langmenu=nl_NL.ISO_8859-1 + matter what $LANG is set to: >vim + set langmenu=nl_NL.ISO_8859-1 < When 'langmenu' is empty, |v:lang| is used. Only normal file name characters can be used, `/\*?[|<>` are illegal. If your $LANG is set to a non-English language but you do want to use - the English menus: > - :set langmenu=none + the English menus: >vim + set langmenu=none < This option must be set before loading menus, switching on filetype detection or syntax highlighting. Once the menus are defined setting - this option has no effect. But you could do this: > - :source $VIMRUNTIME/delmenu.vim - :set langmenu=de_DE.ISO_8859-1 - :source $VIMRUNTIME/menu.vim + this option has no effect. But you could do this: >vim + source $VIMRUNTIME/delmenu.vim + set langmenu=de_DE.ISO_8859-1 + source $VIMRUNTIME/menu.vim < Warning: This deletes all menus that you defined yourself! *'langremap'* *'lrm'* *'nolangremap'* *'nolrm'* @@ -3759,8 +3773,8 @@ A jump table for the options with a short description can be found at |Q_op|. option will cause the window size to be changed. When you only want to use the size for the GUI, put the command in your |gvimrc| file. Vim limits the number of lines to what fits on the screen. You can - use this command to get the tallest window possible: > - :set lines=999 + use this command to get the tallest window possible: >vim + set lines=999 < Minimum value is 2, maximum value is 1000. *'linespace'* *'lsp'* @@ -3814,8 +3828,8 @@ A jump table for the options with a short description can be found at |Q_op|. The cursor is displayed at the start of the space a Tab character occupies, not at the end as usual in Normal mode. To get this cursor - position while displaying Tabs with spaces, use: > - :set list lcs=tab:\ \ + position while displaying Tabs with spaces, use: >vim + set list lcs=tab:\ \ < Note that list mode will also affect formatting (set with 'textwidth' or 'wrapmargin') when 'cpoptions' includes 'L'. See 'listchars' for @@ -3825,7 +3839,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'listchars' 'lcs' string (default "tab:> ,trail:-,nbsp:+") global or local to window |global-local| Strings to use in 'list' mode and for the |:list| command. It is a - comma-separated list of string settings. + comma-separated list of string settings. *E1511* *lcs-eol* eol:c Character to show at the end of each line. When @@ -3869,8 +3883,8 @@ A jump table for the options with a short description can be found at |Q_op|. lead:c Character to show for leading spaces. When omitted, leading spaces are blank. Overrides the "space" and "multispace" settings for leading spaces. You can - combine it with "tab:", for example: > - :set listchars+=tab:>-,lead:. + combine it with "tab:", for example: >vim + set listchars+=tab:>-,lead:. < *lcs-leadmultispace* leadmultispace:c... @@ -3904,19 +3918,19 @@ A jump table for the options with a short description can be found at |Q_op|. omitted. The characters ':' and ',' should not be used. UTF-8 characters can - be used. All characters must be single width. + be used. All characters must be single width. *E1512* - Each character can be specified as hex: > + Each character can be specified as hex: >vim set listchars=eol:\\x24 set listchars=eol:\\u21b5 set listchars=eol:\\U000021b5 < Note that a double backslash is used. The number of hex characters must be exactly 2 for \\x, 4 for \\u and 8 for \\U. - Examples: > - :set lcs=tab:>-,trail:- - :set lcs=tab:>-,eol:<,nbsp:% - :set lcs=extends:>,precedes:< + Examples: >vim + set lcs=tab:>-,trail:- + set lcs=tab:>-,eol:<,nbsp:% + set lcs=extends:>,precedes:< < |hl-NonText| highlighting will be used for "eol", "extends" and "precedes". |hl-Whitespace| for "nbsp", "space", "tab", "multispace", "lead" and "trail". @@ -3967,8 +3981,8 @@ A jump table for the options with a short description can be found at |Q_op|. This would be mostly useful when you use MS-Windows. If iconv is enabled, setting 'makeencoding' to "char" has the same effect as - setting to the system locale encoding. Example: > - :set makeencoding=char " system locale is used + setting to the system locale encoding. Example: >vim + set makeencoding=char " system locale is used < *'makeprg'* *'mp'* @@ -3982,11 +3996,11 @@ A jump table for the options with a short description can be found at |Q_op|. about including spaces and backslashes. Note that a '|' must be escaped twice: once for ":set" and once for the interpretation of a command. When you use a filter called - "myfilter" do it like this: > - :set makeprg=gmake\ \\\|\ myfilter + "myfilter" do it like this: >vim + set makeprg=gmake\ \\\|\ myfilter < The placeholder "$*" can be given (even multiple times) to specify - where the arguments will be included, for example: > - :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} + where the arguments will be included, for example: >vim + set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*} < This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -3999,12 +4013,12 @@ A jump table for the options with a short description can be found at |Q_op|. jump between two double quotes. The characters must be separated by a colon. The pairs must be separated by a comma. Example for including '<' and - '>' (for HTML): > - :set mps+=<:> + '>' (for HTML): >vim + set mps+=<:> < A more exotic example, to jump between the '=' and ';' in an - assignment, useful for languages like C and Java: > - :au FileType c,cpp,java set mps+==:; + assignment, useful for languages like C and Java: >vim + au FileType c,cpp,java set mps+==:; < For a more advanced way of using "%", see the matchit.vim plugin in the $VIMRUNTIME/plugin directory. |add-local-help| @@ -4026,6 +4040,7 @@ A jump table for the options with a short description can be found at |Q_op|. Increasing this limit above 200 also changes the maximum for Ex command recursion, see |E169|. See also |:function|. + Also used for maximum depth of callback functions. *'maxmapdepth'* *'mmd'* *E223* 'maxmapdepth' 'mmd' number (default 1000) @@ -4090,8 +4105,8 @@ A jump table for the options with a short description can be found at |Q_op|. The languages for which these numbers are important are Italian and Hungarian. The default works for when you have about 512 Mbyte. If - you have 1 Gbyte you could use: > - :set mkspellmem=900000,3000,800 + you have 1 Gbyte you could use: >vim + set mkspellmem=900000,3000,800 < If you have less than 512 Mbyte |:mkspell| may fail for some languages, no matter what you set 'mkspellmem' to. @@ -4165,8 +4180,8 @@ A jump table for the options with a short description can be found at |Q_op|. 'mouse' string (default "nvi") global Enables mouse support. For example, to enable the mouse in Normal mode - and Visual mode: > - :set mouse=nv + and Visual mode: >vim + set mouse=nv < To temporarily disable mouse support, hold the shift key while using the mouse. @@ -4249,19 +4264,19 @@ A jump table for the options with a short description can be found at |Q_op|. Note that you can further refine the meaning of buttons with mappings. See |mouse-overview|. But mappings are NOT used for modeless selection. - Example: > - :map <S-LeftMouse> <RightMouse> - :map <S-LeftDrag> <RightDrag> - :map <S-LeftRelease> <RightRelease> - :map <2-S-LeftMouse> <2-RightMouse> - :map <2-S-LeftDrag> <2-RightDrag> - :map <2-S-LeftRelease> <2-RightRelease> - :map <3-S-LeftMouse> <3-RightMouse> - :map <3-S-LeftDrag> <3-RightDrag> - :map <3-S-LeftRelease> <3-RightRelease> - :map <4-S-LeftMouse> <4-RightMouse> - :map <4-S-LeftDrag> <4-RightDrag> - :map <4-S-LeftRelease> <4-RightRelease> + Example: >vim + map <S-LeftMouse> <RightMouse> + map <S-LeftDrag> <RightDrag> + map <S-LeftRelease> <RightRelease> + map <2-S-LeftMouse> <2-RightMouse> + map <2-S-LeftDrag> <2-RightDrag> + map <2-S-LeftRelease> <2-RightRelease> + map <3-S-LeftMouse> <3-RightMouse> + map <3-S-LeftDrag> <3-RightDrag> + map <3-S-LeftRelease> <3-RightRelease> + map <4-S-LeftMouse> <4-RightMouse> + map <4-S-LeftDrag> <4-RightDrag> + map <4-S-LeftRelease> <4-RightRelease> < Mouse commands requiring the CTRL modifier can be simulated by typing the "g" key before using the mouse: @@ -4293,8 +4308,8 @@ A jump table for the options with a short description can be found at |Q_op|. for vertical scrolling). You can disable mouse scrolling by using a count of 0. - Example: > - :set mousescroll=ver:5,hor:2 + Example: >vim + set mousescroll=ver:5,hor:2 < Will make Nvim scroll 5 lines at a time when scrolling vertically, and scroll 2 columns at a time when scrolling horizontally. @@ -4355,8 +4370,8 @@ A jump table for the options with a short description can be found at |Q_op|. Any modes not specified or shapes not available use the normal mouse pointer. - Example: > - :set mouseshape=s:udsizing,m:no + Example: >vim + set mouseshape=s:udsizing,m:no < will make the mouse turn to a sizing arrow over the status lines and indicate no input when the hit-enter prompt is displayed (since clicking the mouse has no effect in this state.) @@ -4521,30 +4536,30 @@ A jump table for the options with a short description can be found at |Q_op|. provided that the file being searched for has a relative path (not starting with "/", "./" or "../"). The directories in the 'path' option may be relative or absolute. - - Use commas to separate directory names: > - :set path=.,/usr/local/include,/usr/include + - Use commas to separate directory names: >vim + set path=.,/usr/local/include,/usr/include < - Spaces can also be used to separate directory names. To have a space in a directory name, precede it with an extra backslash, and - escape the space: > - :set path=.,/dir/with\\\ space + escape the space: >vim + set path=.,/dir/with\\\ space < - To include a comma in a directory name precede it with an extra - backslash: > - :set path=.,/dir/with\\,comma -< - To search relative to the directory of the current file, use: > - :set path=. + backslash: >vim + set path=.,/dir/with\\,comma +< - To search relative to the directory of the current file, use: >vim + set path=. < - To search in the current directory use an empty string between two - commas: > - :set path=,, + commas: >vim + set path=,, < - A directory name may end in a ':' or '/'. - Environment variables are expanded |:set_env|. - When using |netrw.vim| URLs can be used. For example, adding "https://www.vim.org" will make ":find index.html" work. - Search upwards and downwards in a directory tree using "*", "**" and ";". See |file-searching| for info and syntax. - - Careful with '\' characters, type two to get one in the option: > - :set path=.,c:\\include -< Or just use '/' instead: > - :set path=.,c:/include + - Careful with '\' characters, type two to get one in the option: >vim + set path=.,c:\\include +< Or just use '/' instead: >vim + set path=.,c:/include < Don't forget "." or files won't even be found in the same directory as the file! The maximum length is limited. How much depends on the system, mostly @@ -4553,14 +4568,14 @@ A jump table for the options with a short description can be found at |Q_op|. 'path', see |:checkpath|. The use of |:set+=| and |:set-=| is preferred when adding or removing directories from the list. This avoids problems when a future version - uses another default. To remove the current directory use: > - :set path-= -< To add the current directory use: > - :set path+= + uses another default. To remove the current directory use: >vim + set path-= +< To add the current directory use: >vim + set path+= < To use an environment variable, you probably need to replace the separator. Here is an example to append $INCL, in which directory - names are separated with a semi-colon: > - :let &path = &path .. "," .. substitute($INCL, ';', ',', 'g') + names are separated with a semi-colon: >vim + let &path = &path .. "," .. substitute($INCL, ';', ',', 'g') < Replace the ';' with a ':' or whatever separator is used. Note that this doesn't work when $INCL contains a comma or white space. @@ -4602,10 +4617,10 @@ A jump table for the options with a short description can be found at |Q_op|. It is possible to override the level for individual highlights within the popupmenu using |highlight-blend|. For instance, to enable - transparency but force the current selected element to be fully opaque: > + transparency but force the current selected element to be fully opaque: >vim - :set pumblend=15 - :hi PmenuSel blend=0 + set pumblend=15 + hi PmenuSel blend=0 < UI-dependent. Works best with RGB colors. 'termguicolors' @@ -4828,8 +4843,8 @@ A jump table for the options with a short description can be found at |Q_op|. The default ruler width is 17 characters. To make the ruler 15 characters wide, put "%15(" at the start and "%)" at the end. - Example: > - :set rulerformat=%15(%c%V\ %p%%%) + Example: >vim + set rulerformat=%15(%c%V\ %p%%%) < *'runtimepath'* *'rtp'* *vimfiles* @@ -4907,8 +4922,8 @@ A jump table for the options with a short description can be found at |Q_op|. runtime files. For speed, use as few items as possible and avoid wildcards. See |:runtime|. - Example: > - :set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME + Example: >vim + set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME < This will use the directory "~/vimruntime" first (containing your personal Nvim runtime files), then "/mygroup/vim", and finally "$VIMRUNTIME" (the default runtime files). @@ -4972,7 +4987,7 @@ A jump table for the options with a short description can be found at |Q_op|. in the middle of the window (except at the start or end of the file or when long lines wrap). After using the local value, go back the global value with one of - these two: > + these two: >vim setlocal scrolloff< setlocal scrolloff=-1 < For scrolling horizontally see 'sidescrolloff'. @@ -5181,8 +5196,8 @@ A jump table for the options with a short description can be found at |Q_op|. 2^8 < 10240 < 2^16) + 10240 bytes (requested maximum item contents size) = 10253 bytes. - Example: > - :set shada='50,<1000,s100,:0,n~/nvim/shada + Example: >vim + set shada='50,<1000,s100,:0,n~/nvim/shada < '50 Marks will be remembered for the last 50 files you edited. @@ -5225,12 +5240,12 @@ A jump table for the options with a short description can be found at |Q_op|. Environment variables are expanded |:set_env|. If the name of the shell contains a space, you need to enclose it in - quotes. Example with quotes: > - :set shell=\"c:\program\ files\unix\sh.exe\"\ -f + quotes. Example with quotes: >vim + set shell=\"c:\program\ files\unix\sh.exe\"\ -f < Note the backslash before each quote (to avoid starting a comment) and each space (to avoid ending the option value), so better use |:let-&| - like this: > - :let &shell='"C:\Program Files\unix\sh.exe" -f' + like this: >vim + let &shell='"C:\Program Files\unix\sh.exe" -f' < Also note that the "-f" is not inside the quotes, because it is not part of the command name. *shell-unquoting* @@ -5253,7 +5268,7 @@ A jump table for the options with a short description can be found at |Q_op|. Note that such processing is done after |:set| did its own round of unescaping, so to keep yourself sane use |:let-&| like shown above. *shell-powershell* - To use PowerShell: > + To use PowerShell: >vim let &shell = executable('pwsh') ? 'pwsh' : 'powershell' let &shellcmdflag = '-NoLogo -ExecutionPolicy RemoteSigned -Command [Console]::InputEncoding=[Console]::OutputEncoding=[System.Text.UTF8Encoding]::new();$PSDefaultParameterValues[''Out-File:Encoding'']=''utf8'';Remove-Alias -Force -ErrorAction SilentlyContinue tee;' let &shellredir = '2>&1 | %%{ "$_" } | Out-File %s; exit $LastExitCode' @@ -5363,7 +5378,7 @@ A jump table for the options with a short description can be found at |Q_op|. existing file names, thus this option needs to be set before opening any file for best results. This might change in the future. 'shellslash' only works when a backslash can be used as a path - separator. To test if this is so use: > + separator. To test if this is so use: >vim if exists('+shellslash') < Also see 'completeslash'. @@ -5457,9 +5472,10 @@ A jump table for the options with a short description can be found at |Q_op|. match", "Pattern not found", "Back at original", etc. C don't give messages while scanning for ins-completion *shm-C* items, for instance "scanning tags" - q use "recording" instead of "recording @a" *shm-q* + q do not show "recording @a" when recording a macro *shm-q* F don't give the file info when editing a file, like *shm-F* - `:silent` was used for the command + `:silent` was used for the command; note that this also + affects messages from 'autoread' reloading S do not show search count message when searching, e.g. *shm-S* "[1/5]" @@ -5476,9 +5492,9 @@ A jump table for the options with a short description can be found at |Q_op|. 'showbreak' 'sbr' string (default "") global or local to window |global-local| String to put at the start of lines that have been wrapped. Useful - values are "> " or "+++ ": > - :let &showbreak = "> " - :let &showbreak = '+++ ' + values are "> " or "+++ ": >vim + let &showbreak = "> " + let &showbreak = '+++ ' < Only printable single-cell characters are allowed, excluding <Tab> and comma (in a future version the comma might be used to separate the part that is shown at the end and at the start of a line). @@ -5487,8 +5503,8 @@ A jump table for the options with a short description can be found at |Q_op|. If you want the 'showbreak' to appear in between line numbers, add the "n" flag to 'cpoptions'. A window-local value overrules a global value. If the global value is - set and you want no value in the current window use NONE: > - :setlocal showbreak=NONE + set and you want no value in the current window use NONE: >vim + setlocal showbreak=NONE < *'showcmd'* *'sc'* *'noshowcmd'* *'nosc'* @@ -5592,16 +5608,16 @@ A jump table for the options with a short description can be found at |Q_op|. horizontally centered in the window, as long as one does not come too close to the beginning of the line. After using the local value, go back the global value with one of - these two: > + these two: >vim setlocal sidescrolloff< setlocal sidescrolloff=-1 < Example: Try this together with 'sidescroll' and 'listchars' as in the following example to never allow the cursor to move - onto the "extends" character: > + onto the "extends" character: >vim - :set nowrap sidescroll=1 listchars=extends:>,precedes:< - :set sidescrolloff=1 + set nowrap sidescroll=1 listchars=extends:>,precedes:< + set sidescrolloff=1 < *'signcolumn'* *'scl'* @@ -5727,7 +5743,7 @@ A jump table for the options with a short description can be found at |Q_op|. Name of the word list file where words are added for the |zg| and |zw| commands. It must end in ".{encoding}.add". You need to include the path, otherwise the file is placed in the current directory. - The path may include characters from 'isfname', space, comma and '@'. + The path may include characters from 'isfname', ' ', ',', '@' and ':'. *E765* It may also be a comma-separated list of names. A count before the |zg| and |zw| commands can be used to access each. This allows using @@ -5750,7 +5766,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'spelllang' 'spl' string (default "en") local to buffer A comma-separated list of word list names. When the 'spell' option is - on spellchecking will be done for these languages. Example: > + on spellchecking will be done for these languages. Example: >vim set spelllang=en_us,nl,medical < This means US English, Dutch and medical words are recognized. Words that are not recognized will be highlighted. @@ -5860,8 +5876,8 @@ A jump table for the options with a short description can be found at |Q_op|. 'verbose' option to a non-zero value. Only one of "best", "double" or "fast" may be used. The others may - appear several times in any order. Example: > - :set sps=file:~/.config/nvim/sugg,best,expr:MySuggest() + appear several times in any order. Example: >vim + set sps=file:~/.config/nvim/sugg,best,expr:MySuggest() < This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. @@ -5924,9 +5940,13 @@ A jump table for the options with a short description can be found at |Q_op|. %s sign column for currently drawn line %C fold column for currently drawn line - NOTE: To draw the sign and fold columns, their items must be included in - 'statuscolumn'. Even when they are not included, the status column width - will adapt to the 'signcolumn' and 'foldcolumn' width. + The 'statuscolumn' width follows that of the default columns and + adapts to the |'numberwidth'|, |'signcolumn'| and |'foldcolumn'| option + values (regardless of whether the sign and fold items are present). + Additionally, the 'statuscolumn' grows with the size of the evaluated + format string, up to a point (following the maximum size of the default + fold, sign and number columns). Shrinking only happens when the number + of lines in a buffer changes, or the 'statuscolumn' option is set. The |v:lnum| variable holds the line number to be drawn. The |v:relnum| variable holds the relative line number to be drawn. @@ -5934,6 +5954,9 @@ A jump table for the options with a short description can be found at |Q_op|. when drawing the actual buffer line, and positive when drawing the wrapped part of a buffer line. + When using |v:relnum|, keep in mind that cursor movement by itself will + not cause the 'statuscolumn' to update unless |'relativenumber'| is set. + NOTE: The %@ click execute function item is supported as well but the specified function will be the same for each row in the same column. It cannot be switched out through a dynamic 'statuscolumn' format, the @@ -5941,21 +5964,21 @@ A jump table for the options with a short description can be found at |Q_op|. Examples: >vim " Relative number with bar separator and click handlers: - :set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T + set statuscolumn=%@SignCb@%s%=%T%@NumCb@%r│%T " Right aligned relative cursor line number: - :let &stc='%=%{v:relnum?v:relnum:v:lnum} ' + let &stc='%=%{v:relnum?v:relnum:v:lnum} ' " Line numbers in hexadecimal for non wrapped part of lines: - :let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} ' + let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} ' " Human readable line numbers with thousands separator: - :let &stc='%{substitute(v:lnum,"\\d\\zs\\ze\\' + let &stc='%{substitute(v:lnum,"\\d\\zs\\ze\\' . '%(\\d\\d\\d\\)\\+$",",","g")}' " Both relative and absolute line numbers with different " highlighting for odd and even relative numbers: - :let &stc='%#NonText#%{&nu?v:lnum:""}' . + let &stc='%#NonText#%{&nu?v:lnum:""}' . '%=%{&rnu&&(v:lnum%2)?"\ ".v:relnum:""}' . '%#LineNr#%{&rnu&&!(v:lnum%2)?"\ ".v:relnum:""}' @@ -5975,8 +5998,8 @@ A jump table for the options with a short description can be found at |Q_op|. be given as "%%". When the option starts with "%!" then it is used as an expression, - evaluated and the result is used as the option value. Example: > - :set statusline=%!MyStatusLine() + evaluated and the result is used as the option value. Example: >vim + set statusline=%!MyStatusLine() < The *g:statusline_winid* variable will be set to the |window-ID| of the window that the status line belongs to. The result can contain %{} items that will be evaluated too. @@ -6057,7 +6080,7 @@ A jump table for the options with a short description can be found at |Q_op|. return value of expr contains "%" items they will get expanded. The expression can contain the "}" character, the end of expression is denoted by "%}". - For example: > + For example: >vim func! Stl_filename() abort return "%t" endfunc @@ -6069,16 +6092,17 @@ A jump table for the options with a short description can be found at |Q_op|. ) - End of item group. No width fields allowed. T N For 'tabline': start of tab page N label. Use %T or %X to end the label. Clicking this label with left mouse button switches - to the specified tab page. + to the specified tab page, while clicking it with middle mouse + button closes the specified tab page. X N For 'tabline': start of close tab N label. Use %X or %T to end the label, e.g.: %3Xclose%X. Use %999X for a "close current - tab" label. Clicking this label with left mouse button closes - specified tab page. - @ N Start of execute function label. Use %X or %T to - end the label, e.g.: %10@SwitchBuffer@foo.c%X. Clicking this - label runs specified function: in the example when clicking once - using left mouse button on "foo.c" "SwitchBuffer(10, 1, 'l', - ' ')" expression will be run. Function receives the + tab" label. Clicking this label with left mouse button closes + the specified tab page. + @ N Start of execute function label. Use %X or %T to end the label, + e.g.: %10@SwitchBuffer@foo.c%X. Clicking this label runs the + specified function: in the example when clicking once using left + mouse button on "foo.c", a `SwitchBuffer(10, 1, 'l', ' ')` + expression will be run. The specified function receives the following arguments in order: 1. minwid field value or zero if no N was specified 2. number of mouse clicks to detect multiple clicks @@ -6124,8 +6148,8 @@ A jump table for the options with a short description can be found at |Q_op|. When all items in a group becomes an empty string (i.e. flags that are not set) and a minwid is not set for the group, the whole group will become empty. This will make a group like the following disappear - completely from the statusline when none of the flags are set. > - :set statusline=...%(\ [%M%R%H]%)... + completely from the statusline when none of the flags are set. >vim + set statusline=...%(\ [%M%R%H]%)... < Beware that an expression is evaluated each and every time the status line is displayed. *stl-%{* *g:actual_curbuf* *g:actual_curwin* @@ -6156,23 +6180,23 @@ A jump table for the options with a short description can be found at |Q_op|. edit your vimrc or whatever with "vim --clean" to get it right. Examples: - Emulate standard status line with 'ruler' set > - :set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P -< Similar, but add ASCII value of char under the cursor (like "ga") > - :set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P -< Display byte count and byte value, modified flag in red. > - :set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b' - :hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red -< Display a ,GZ flag if a compressed file is loaded > - :set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h... -< In the |:autocmd|'s: > - :let b:gzflag = 1 -< And: > - :unlet b:gzflag -< And define this function: > - :function VarExists(var, val) - : if exists(a:var) | return a:val | else | return '' | endif - :endfunction + Emulate standard status line with 'ruler' set >vim + set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P +< Similar, but add ASCII value of char under the cursor (like "ga") >vim + set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P +< Display byte count and byte value, modified flag in red. >vim + set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b' + hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red +< Display a ,GZ flag if a compressed file is loaded >vim + set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h... +< In the |:autocmd|'s: >vim + let b:gzflag = 1 +< And: >vim + unlet b:gzflag +< And define this function: >vim + function VarExists(var, val) + if exists(a:var) | return a:val | else | return '' | endif + endfunction < *'suffixes'* *'su'* @@ -6193,8 +6217,8 @@ A jump table for the options with a short description can be found at |Q_op|. 'suffixesadd' 'sua' string (default "") local to buffer Comma-separated list of suffixes, which are used when searching for a - file for the "gf", "[I", etc. commands. Example: > - :set suffixesadd=.java + file for the "gf", "[I", etc. commands. Example: >vim + set suffixesadd=.java < *'swapfile'* *'swf'* *'noswapfile'* *'noswf'* @@ -6266,19 +6290,19 @@ A jump table for the options with a short description can be found at |Q_op|. Otherwise this option does not always reflect the current syntax (the b:current_syntax variable does). This option is most useful in a modeline, for a file which syntax is - not automatically recognized. Example, in an IDL file: > + not automatically recognized. Example, in an IDL file: >c /* vim: set syntax=idl : */ < When a dot appears in the value then this separates two filetype - names. Example: > + names. Example: >c /* vim: set syntax=c.doxygen : */ < This will use the "c" syntax first, then the "doxygen" syntax. Note that the second one must be prepared to be loaded as an addition, otherwise it will be skipped. More than one dot may appear. - To switch off syntax highlighting for the current file, use: > - :set syntax=OFF + To switch off syntax highlighting for the current file, use: >vim + set syntax=OFF < To switch syntax highlighting on according to the current value of the - 'filetype' option: > - :set syntax=ON + 'filetype' option: >vim + set syntax=ON < What actually happens when setting the 'syntax' option is that the Syntax autocommand event is triggered with the value as argument. This option is not copied to another buffer, independent of the 's' or @@ -6495,6 +6519,10 @@ A jump table for the options with a short description can be found at |Q_op|. attributes instead of "cterm" attributes. |guifg| Requires an ISO-8613-3 compatible terminal. + Nvim will automatically attempt to determine if the host terminal + supports 24-bit color and will enable this option if it does + (unless explicitly disabled by the user). + *'termpastefilter'* *'tpf'* 'termpastefilter' 'tpf' string (default "BS,HT,ESC,DEL") global @@ -6628,13 +6656,13 @@ A jump table for the options with a short description can be found at |Q_op|. expanded according to the rules used for 'statusline'. This option cannot be set in a modeline when 'modelineexpr' is off. - Example: > - :auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p") - :set title titlestring=%<%F%=%l/%L-%P titlelen=70 + Example: >vim + auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p") + set title titlestring=%<%F%=%l/%L-%P titlelen=70 < The value of 'titlelen' is used to align items in the middle or right of the available space. - Some people prefer to have the file name first: > - :set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%) + Some people prefer to have the file name first: >vim + set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%) < Note the use of "%{ }" and an expression to get the path of the file, without the file name. The "%( %)" constructs are used to add a separating space only when needed. @@ -6706,13 +6734,13 @@ A jump table for the options with a short description can be found at |Q_op|. is kept in memory, higher numbers will cause more memory to be used. Nevertheless, a single change can already use a large amount of memory. Set to 0 for Vi compatibility: One level of undo and "u" undoes - itself: > + itself: >vim set ul=0 < But you can also get Vi compatibility by including the 'u' flag in 'cpoptions', and still be able to use CTRL-R to repeat undo. Also see |undo-two-ways|. Set to -1 for no undo at all. You might want to do this only for the - current buffer: > + current buffer: >vim setlocal ul=-1 < This helps when you run out of memory for a single change. @@ -6757,6 +6785,57 @@ A jump table for the options with a short description can be found at |Q_op|. written to disk (see |crash-recovery|). Also used for the |CursorHold| autocommand event. + *'userregfunc'* *'urf'* +'userregfunc' 'urf' string (default "") + global + The option specifies a function to be used to handle any registers + that Neovim does not natively handle. This option unlocks all + characters to be used as registers by the user. + + The 'userregfunc' function is called each time a user register is read + from or written to. + + The 'userregfunc' function must take the following parameters: + + {action} The action being done on this register (either 'yank' + or 'put' + + {register} The string holding the name of the register. This + is always a single character, though multi-byte + characters are allowed. + + {content} If the action is 'yank' this is the content being + yanked into the register. The content is a dictionary + with the following items: + + {lines} The lines being yanked, as a list. + + {type} The type of yank, either "line", "char", or + "block" + + {width} The width in case of "block" mode. + + {additional_data} Additional data. (can be returned in + put mode). + + In case the action is 'put', the 'userregfunc' function should return + the content to place in that location. The content can either be a + string, in which case "char" mode is inferred, or it can return a + dictionary of the same template that populates 'content'. + + A very simple example of a 'userregfunc' function that behaves exactly + like traditional registers would look like: > + + let s:contents = {} + function! MyUserregFunction(action, register, content) abort + if a:action == "put" + return get(s:contents, a:register, "") + else + let s:contents[a:register] = a:content + endif + endfunction + set userregfunc=MyUserregFunction +< *'varsofttabstop'* *'vsts'* 'varsofttabstop' 'vsts' string (default "") local to buffer @@ -6768,8 +6847,8 @@ A jump table for the options with a short description can be found at |Q_op|. For example, when editing assembly language files where statements start in the 9th column and comments in the 41st, it may be useful - to use the following: > - :set varsofttabstop=8,32,8 + to use the following: >vim + set varsofttabstop=8,32,8 < This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more for every column thereafter. @@ -6781,8 +6860,8 @@ A jump table for the options with a short description can be found at |Q_op|. local to buffer A list of the number of spaces that a <Tab> in the file counts for, separated by commas. Each value corresponds to one tab, with the - final value applying to all subsequent tabs. For example: > - :set vartabstop=4,20,10,8 + final value applying to all subsequent tabs. For example: >vim + set vartabstop=4,20,10,8 < This will make the first tab 4 spaces wide, the second 20 spaces, the third 10 spaces, and all following tabs 8 spaces. @@ -6794,15 +6873,15 @@ A jump table for the options with a short description can be found at |Q_op|. global Sets the verbosity level. Also set by |-V| and |:verbose|. - Tracing of options in Lua scripts is activated at level 1; Lua scripts - are not traced with verbose=0, for performance. + Tracing of assignments to options, mappings, etc. in Lua scripts is + enabled at level 1; Lua scripts are not traced when 'verbose' is 0, + for performance. If greater than or equal to a given level, Nvim produces the following messages: Level Messages ~ ---------------------------------------------------------------------- - 1 Lua assignments to options, mappings, etc. 2 When a file is ":source"'ed, or |shada| file is read or written. 3 UI info, terminal capabilities. 4 Shell commands. @@ -6911,8 +6990,8 @@ A jump table for the options with a short description can be found at |Q_op|. ~ "~" Normal [ <Left> Insert and Replace ] <Right> Insert and Replace - For example: > - :set ww=<,>,[,] + For example: >vim + set ww=<,>,[,] < allows wrap only when cursor keys are used. When the movement keys are used in combination with a delete or change operator, the <EOL> also counts for a character. This makes "3h" @@ -6936,8 +7015,8 @@ A jump table for the options with a short description can be found at |Q_op|. Some keys will not work, such as CTRL-C, <CR> and Enter. <Esc> can be used, but hitting it twice in a row will still exit command-line as a failsafe measure. - Although 'wc' is a number option, you can set it to a special key: > - :set wc=<Tab> + Although 'wc' is a number option, you can set it to a special key: >vim + set wc=<Tab> < *'wildcharm'* *'wcm'* @@ -6947,9 +7026,9 @@ A jump table for the options with a short description can be found at |Q_op|. recognized when used inside a macro. You can find "spare" command-line keys suitable for this option by looking at |ex-edit-index|. Normally you'll never actually type 'wildcharm', just use it in mappings that - automatically invoke completion mode, e.g.: > - :set wcm=<C-Z> - :cnoremap ss so $vim/sessions/*.vim<C-Z> + automatically invoke completion mode, e.g.: >vim + set wcm=<C-Z> + cnoremap ss so $vim/sessions/*.vim<C-Z> < Then after typing :ss you can use CTRL-P & CTRL-N. *'wildignore'* *'wig'* @@ -6961,8 +7040,8 @@ A jump table for the options with a short description can be found at |Q_op|. |globpath()| unless a flag is passed to disable this. The pattern is used like with |:autocmd|, see |autocmd-pattern|. Also see 'suffixes'. - Example: > - :set wildignore=*.o,*.obj + Example: >vim + set wildignore=*.o,*.obj < The use of |:set+=| and |:set-=| is preferred when adding or removing a pattern from the list. This avoids problems when a future version uses another default. @@ -7010,9 +7089,9 @@ A jump table for the options with a short description can be found at |Q_op|. completion. If you want <Left> and <Right> to move the cursor instead of selecting - a different match, use this: > - :cnoremap <Left> <Space><BS><Left> - :cnoremap <Right> <Space><BS><Right> + a different match, use this: >vim + cnoremap <Left> <Space><BS><Left> + cnoremap <Right> <Space><BS><Right> < |hl-WildMenu| highlights the current match. @@ -7050,16 +7129,16 @@ A jump table for the options with a short description can be found at |Q_op|. and sort buffers by time last used (other than the current buffer). - Examples: > - :set wildmode=full -< Complete first full match, next match, etc. (the default) > - :set wildmode=longest,full -< Complete longest common string, then each full match > - :set wildmode=list:full -< List all matches and complete each full match > - :set wildmode=list,full -< List all matches without completing, then each full match > - :set wildmode=longest,list + Examples: >vim + set wildmode=full +< Complete first full match, next match, etc. (the default) >vim + set wildmode=longest,full +< Complete longest common string, then each full match >vim + set wildmode=list:full +< List all matches and complete each full match >vim + set wildmode=list,full +< List all matches without completing, then each full match >vim + set wildmode=longest,list < Complete longest common string, then list alternatives. More info here: |cmdline-completion|. @@ -7169,7 +7248,7 @@ A jump table for the options with a short description can be found at |Q_op|. Other windows will be only 'winminheight' high. This has the drawback that ":all" will create only two windows. To avoid "vim -o 1 2 3 4" to create only two windows, set the option after startup is done, - using the |VimEnter| event: > + using the |VimEnter| event: >vim au VimEnter * set winheight=999 < Minimum value is 1. The height is not adjusted after one of the commands that change the @@ -7194,7 +7273,7 @@ A jump table for the options with a short description can be found at |Q_op|. the popupmenu are determined by the current window. Highlights in the message area cannot be overridden. - Example: show a different color for non-current windows: > + Example: show a different color for non-current windows: >vim set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC < @@ -7250,9 +7329,9 @@ A jump table for the options with a short description can be found at |Q_op|. horizontally. The line will be broken in the middle of a word if necessary. See 'linebreak' to get the break at a word boundary. - To make scrolling horizontally a bit more useful, try this: > - :set sidescroll=5 - :set listchars+=precedes:<,extends:> + To make scrolling horizontally a bit more useful, try this: >vim + set sidescroll=5 + set listchars+=precedes:<,extends:> < See 'sidescroll', 'listchars' and |wrap-off|. This option can't be set from a |modeline| when the 'diff' option is on. diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt index 85ac290361..d8fcd066a8 100644 --- a/runtime/doc/pi_netrw.txt +++ b/runtime/doc/pi_netrw.txt @@ -639,7 +639,7 @@ additional prompting. work with your ftp client. Otherwise the script will prompt for user-id and password. - (*3) for ftp, "machine" may be machine#port or machine:port + (*3) for ftp, "machine" may be machine#port or machine:port if a different port is needed than the standard ftp port (*4) for http:..., if wget is available it will be used. Otherwise, @@ -785,7 +785,7 @@ below, a {netfile} is a URL to a remote file. (related: |netrw-userpass|) :NetrwSettings This command is described in |netrw-settings| -- used to - display netrw settings and change netrw behavior. + display netrw settings and change netrw behavior. ============================================================================== @@ -1621,10 +1621,8 @@ A further approach is to delete files which match a pattern. This will cause the matching files to be marked. Then, press "D". -If your vim has 7.4 with patch#1107, then |g:netrw_localrmdir| no longer -is used to remove directories; instead, vim's |delete()| is used with -the "d" option. Please note that only empty directories may be deleted -with the "D" mapping. Regular files are deleted with |delete()|, too. +Please note that only empty directories may be deleted with the "D" mapping. +Regular files are deleted with |delete()|, too. The |g:netrw_rm_cmd|, |g:netrw_rmf_cmd|, and |g:netrw_rmdir_cmd| variables are used to control the attempts to remove remote files and directories. The @@ -1643,8 +1641,7 @@ to remove it again using the g:netrw_rmf_cmd variable. Its default value is: |g:netrw_rmf_cmd|: ssh HOSTNAME rm -f Related topics: |netrw-d| -Associated setting variable: |g:netrw_localrmdir| |g:netrw_rm_cmd| - |g:netrw_rmdir_cmd| |g:netrw_ssh_cmd| +Associated setting variable: |g:netrw_rm_cmd| |g:netrw_ssh_cmd| *netrw-explore* *netrw-hexplore* *netrw-nexplore* *netrw-pexplore* @@ -1687,7 +1684,11 @@ DIRECTORY EXPLORATION COMMANDS {{{2 to 2; edits will thus preferentially be made in window#2. The [N] specifies a |g:netrw_winsize| just for the new :Lexplore - window. + window. That means that + if [N] < 0 : use |N| columns for the Lexplore window + if [N] = 0 : a normal split is made + if [N] > 0 : use N% of the current window will be used for the + new window Those who like this method often also like tree style displays; see |g:netrw_liststyle|. @@ -2848,14 +2849,6 @@ your browsing preferences. (see also: |netrw-settings|) =" /c move" Windows Options for |g:netrw_localmovecmd| - *g:netrw_localrmdir* ="rmdir" Linux/Unix/MacOS/Cygwin - =expand("$COMSPEC") Windows - Remove directory command (rmdir) - This variable is only used if your vim is - earlier than 7.4 or if your vim doesn't - have patch#1107. Otherwise, |delete()| - is used with the "d" option. - *g:netrw_maxfilenamelen* =32 by default, selected so as to make long listings fit on 80 column displays. If your screen is wider, and you have file @@ -3766,7 +3759,7 @@ Example: Clear netrw's marked file list via a mapping on gu > Netrw uses several system level commands to do things (see |g:netrw_localcopycmd|, |g:netrw_localmovecmd|, - |g:netrw_localrmdir|, |g:netrw_mkdir_cmd|). + |g:netrw_mkdir_cmd|). You may need to adjust the default commands for one or more of these commands by setting them properly in your .vimrc. Another @@ -3892,8 +3885,13 @@ netrw: ============================================================================== 12. History *netrw-history* {{{1 - v172: Apr 22, 2023 * removed g:netrw_localrmdiropt - removed g:netrw_localrmdir + v172: Sep 02, 2021 * (Bram Moolenaar) Changed "l:go" to "go" + * (Bram Moolenaar) no need for "b" in + netrw-safe guioptions + Nov 15, 2021 * removed netrw_localrm and netrw_localrmdir + references + Aug 18, 2022 * (Miguel Barro) improving compatability with + powershell v171: Oct 09, 2020 * included code in s:NetrwOptionsSafe() to allow |'bh'| to be set to delete when rather than hide when g:netrw_fastbrowse @@ -3981,7 +3979,6 @@ netrw: |g:netrw_localcopydircmdopt| |g:netrw_localmkdiropt| |g:netrw_localmovecmdopt| - g:netrw_localrmdiropt Nov 21, 2016 * (mattn) provided a patch for preview; swapped winwidth() with winheight() Nov 22, 2016 * (glacambre) reported that files containing @@ -4041,7 +4038,7 @@ netrw: refreshes. However, inside a |:map-<expr>|, tab and window changes are disallowed. Fixed. (affects netrw's s:LocalBrowseRefresh()) - * |g:netrw_localrmdir| not used any more, but + * g:netrw_localrmdir not used any more, but the relevant patch that causes |delete()| to take over was #1107 (not #1109). * |expand()| is now used on |g:netrw_home|; diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index 4428ff2f65..9037ecc0f9 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -368,12 +368,12 @@ processing a quickfix or location list command, it will be aborted. :cl[ist]! +{count} List the current and next {count} error lines. This is useful to see unrecognized lines after the current one. For example, if ":clist" shows: - 8384 testje.java:252: error: cannot find symbol ~ + 8384 testje.java:252: error: cannot find symbol ~ Then using ":cl! +3" shows the reason: - 8384 testje.java:252: error: cannot find symbol ~ - 8385: ZexitCode = Fmainx(); ~ - 8386: ^ ~ - 8387: symbol: method Fmainx() ~ + 8384 testje.java:252: error: cannot find symbol ~ + 8385: ZexitCode = Fmainx(); ~ + 8386: ^ ~ + 8387: symbol: method Fmainx() ~ :lli[st] [from] [, [to]] *:lli* *:llist* Same as ":clist", except the location list for the diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index f976eb7464..572dc8a841 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -623,9 +623,9 @@ Short explanation of each option: *option-list* 'aleph' 'al' ASCII code of the letter Aleph (Hebrew) 'allowrevins' 'ari' allow CTRL-_ in Insert and Command-line mode 'ambiwidth' 'ambw' what to do with Unicode chars of ambiguous width -'autochdir' 'acd' change directory to the file in the current window 'arabic' 'arab' for Arabic as a default second language 'arabicshape' 'arshape' do shaping for Arabic characters +'autochdir' 'acd' change directory to the file in the current window 'autoindent' 'ai' take indent for new line from previous line 'autoread' 'ar' autom. read file when changed outside of Vim 'autowrite' 'aw' automatically write file if changed @@ -655,8 +655,8 @@ Short explanation of each option: *option-list* 'cindent' 'cin' do C program indenting 'cinkeys' 'cink' keys that trigger indent when 'cindent' is set 'cinoptions' 'cino' how to do indenting when 'cindent' is set -'cinwords' 'cinw' words where 'si' and 'cin' add an indent 'cinscopedecls' 'cinsd' words that are recognized by 'cino-g' +'cinwords' 'cinw' words where 'si' and 'cin' add an indent 'clipboard' 'cb' use the clipboard as the unnamed register 'cmdheight' 'ch' number of lines to use for the command-line 'cmdwinheight' 'cwh' height of the command-line window @@ -738,10 +738,10 @@ Short explanation of each option: *option-list* 'helpheight' 'hh' minimum height of a new help window 'helplang' 'hlg' preferred help languages 'hidden' 'hid' don't unload buffer when it is |abandon|ed -'hlsearch' 'hls' highlight matches with last search pattern 'history' 'hi' number of command-lines that are remembered 'hkmap' 'hk' Hebrew keyboard mapping 'hkmapp' 'hkp' phonetic Hebrew keyboard mapping +'hlsearch' 'hls' highlight matches with last search pattern 'icon' let Vim set the text of the window icon 'iconstring' string to use for the Vim icon text 'ignorecase' 'ic' ignore case in search patterns @@ -939,10 +939,10 @@ Short explanation of each option: *option-list* 'wildoptions' 'wop' specifies how command line completion is done 'winaltkeys' 'wak' when the windows system handles ALT keys 'window' 'wi' nr of lines to scroll for CTRL-F and CTRL-B -'winheight' 'wh' minimum number of lines for the current window -'winhighlight' 'winhl' window-local highlighting 'winfixheight' 'wfh' keep window height when opening/closing windows 'winfixwidth' 'wfw' keep window width when opening/closing windows +'winheight' 'wh' minimum number of lines for the current window +'winhighlight' 'winhl' window-local highlighting 'winminheight' 'wmh' minimum number of lines for any window 'winminwidth' 'wmw' minimal number of columns for any window 'winwidth' 'wiw' minimal number of columns for current window diff --git a/runtime/doc/recover.txt b/runtime/doc/recover.txt index e6b5b06744..4312716b22 100644 --- a/runtime/doc/recover.txt +++ b/runtime/doc/recover.txt @@ -85,10 +85,10 @@ You can find this in the user manual, section |11.3|. *W325* The default |SwapExists| handler (|default-autocmds|) skips the |E325| prompt -(selects "(E)dit") if the swapfile owner process (1) is still running and (2) -was started by the current user. This presumes that you normally don't want -to be bothered with the |ATTENTION| message just because you happen to edit -the same file from multiple Nvim instances. In the worst case (a system +(and automatically chooses "(E)dit") if the swapfile owner process is still +running and owned by the current user. This presumes that you normally don't +want to be bothered with the |ATTENTION| message just because you happen to +edit the same file from multiple Nvim instances. In the worst case (a system crash) there will be more than one swapfile for the file; use |:recover| to inspect all of its swapfiles. diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index 53f6904170..ae827fa06f 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -148,10 +148,20 @@ q Stops recording. *@@* *E748* @@ Repeat the previous @{0-9a-z":*} [count] times. + *v_@-default* +{Visual}@{0-9a-z".=*+} In Visual mode, execute the contents of the register +{Visual}@@ but for each selected line. + See |visual-repeat|, |default-mappings|. + *Q* Q Repeat the last recorded register [count] times. See |reg_recorded()|. + *v_Q-default* +{Visual}Q In Visual mode, repeat the last recorded register for + each selected line. + See |visual-repeat|, |default-mappings|. + *:@* :[addr]@{0-9a-z".=*+} Execute the contents of register {0-9a-z".=*+} as an Ex command. First set cursor at line [addr] (default is @@ -182,11 +192,11 @@ Using Vim scripts *using-scripts* For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. *:so* *:source* *load-vim-script* -:[range]so[urce] [file] Runs |Ex| commands or Lua code (".lua" files) from +:[range]so[urce] [file] Runs |Ex-commands| or Lua code (".lua" files) from [file]. - If no [file], the current buffer is used, and it is - treated as Lua code if its 'filetype' is "lua" or its - file name ends with ".lua". + If no [file], the current buffer is used and treated + as Lua code if 'filetype' is "lua" or its filename + ends with ".lua". Triggers the |SourcePre| autocommand. *:source!* :[range]so[urce]! {file} diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index e1053b54f1..c02752a2b7 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -196,52 +196,56 @@ be preferred names for highlight groups that are common for many languages. These are the suggested group names (if syntax highlighting works properly you can see the actual color, except for "Ignore"): - Comment any comment +Comment any comment - Constant any constant - String a string constant: "this is a string" - Character a character constant: 'c', '\n' - Number a number constant: 234, 0xff - Boolean a boolean constant: TRUE, false - Float a floating point constant: 2.3e10 +Constant any constant +String a string constant: "this is a string" +Character a character constant: 'c', '\n' +Number a number constant: 234, 0xff +Boolean a boolean constant: TRUE, false +Float a floating point constant: 2.3e10 - Identifier any variable name - Function function name (also: methods for classes) +Identifier any variable name +Function function name (also: methods for classes) - Statement any statement - Conditional if, then, else, endif, switch, etc. - Repeat for, do, while, etc. - Label case, default, etc. - Operator "sizeof", "+", "*", etc. - Keyword any other keyword - Exception try, catch, throw +Statement any statement +Conditional if, then, else, endif, switch, etc. +Repeat for, do, while, etc. +Label case, default, etc. +Operator "sizeof", "+", "*", etc. +Keyword any other keyword +Exception try, catch, throw - PreProc generic Preprocessor - Include preprocessor #include - Define preprocessor #define - Macro same as Define - PreCondit preprocessor #if, #else, #endif, etc. +PreProc generic Preprocessor +Include preprocessor #include +Define preprocessor #define +Macro same as Define +PreCondit preprocessor #if, #else, #endif, etc. - Type int, long, char, etc. - StorageClass static, register, volatile, etc. - Structure struct, union, enum, etc. - Typedef A typedef +Type int, long, char, etc. +StorageClass static, register, volatile, etc. +Structure struct, union, enum, etc. +Typedef a typedef - Special any special symbol - SpecialChar special character in a constant - Tag you can use CTRL-] on this - Delimiter character that needs attention - SpecialComment special things inside a comment - Debug debugging statements +Special any special symbol +SpecialChar special character in a constant +Tag you can use CTRL-] on this +Delimiter character that needs attention +SpecialComment special things inside a comment +Debug debugging statements - Underlined text that stands out, HTML links +Underlined text that stands out, HTML links - Ignore left blank, hidden |hl-Ignore| +Ignore left blank, hidden |hl-Ignore| - Error any erroneous construct +Error any erroneous construct - Todo anything that needs extra attention; mostly the - keywords TODO FIXME and XXX +Todo anything that needs extra attention; mostly the + keywords TODO FIXME and XXX + +Added added line in a diff +Changed changed line in a diff +Removed removed line in a diff The names marked with * are the preferred groups; the others are minor groups. For the preferred groups, the "syntax.vim" file contains default highlighting. @@ -337,443 +341,11 @@ Upon loading a file, Vim finds the relevant syntax file as follows: syntax. ============================================================================== -4. Conversion to HTML *2html.vim* *convert-to-HTML* - -2html is not a syntax file itself, but a script that converts the current -window into HTML. Vim opens a new window in which it builds the HTML file. - -After you save the resulting file, you can view it with any browser. The -colors should be exactly the same as you see them in Vim. With -|g:html_line_ids| you can jump to specific lines by adding (for example) #L123 -or #123 to the end of the URL in your browser's address bar. And with -|g:html_dynamic_folds| enabled, you can show or hide the text that is folded -in Vim. +4. Conversion to HTML *convert-to-HTML* *2html.vim* -You are not supposed to set the 'filetype' or 'syntax' option to "2html"! -Source the script to convert the current file: > - - :runtime! syntax/2html.vim -< -Many variables affect the output of 2html.vim; see below. Any of the on/off -options listed below can be enabled or disabled by setting them explicitly to -the desired value, or restored to their default by removing the variable using -|:unlet|. - -Remarks: -- Some truly ancient browsers may not show the background colors. -- From most browsers you can also print the file (in color)! - -Here is an example how to run the script over all .c and .h files from a -Unix shell: > - for f in *.[ch]; do gvim -f +"syn on" +"run! syntax/2html.vim" +"wq" +"q" $f; done -< - *g:html_start_line* *g:html_end_line* -To restrict the conversion to a range of lines, use a range with the |:TOhtml| -command below, or set "g:html_start_line" and "g:html_end_line" to the first -and last line to be converted. Example, using the last set Visual area: > - - :let g:html_start_line = line("'<") - :let g:html_end_line = line("'>") - :runtime! syntax/2html.vim -< - *:TOhtml* -:[range]TOhtml The ":TOhtml" command is defined in a standard plugin. - This command will source |2html.vim| for you. When a - range is given, this command sets |g:html_start_line| - and |g:html_end_line| to the start and end of the - range, respectively. Default range is the entire - buffer. - - If the current window is part of a |diff|, unless - |g:html_diff_one_file| is set, :TOhtml will convert - all windows which are part of the diff in the current - tab and place them side-by-side in a <table> element - in the generated HTML. With |g:html_line_ids| you can - jump to lines in specific windows with (for example) - #W1L42 for line 42 in the first diffed window, or - #W3L87 for line 87 in the third. - - Examples: > - - :10,40TOhtml " convert lines 10-40 to html - :'<,'>TOhtml " convert current/last visual selection - :TOhtml " convert entire buffer -< - *g:html_diff_one_file* -Default: 0. -When 0, and using |:TOhtml| all windows involved in a |diff| in the current tab -page are converted to HTML and placed side-by-side in a <table> element. When -1, only the current buffer is converted. -Example: > +The old to html converter has ben replaced by a Lua version and the +documentation has been moved to |:TOhtml|. - let g:html_diff_one_file = 1 -< - *g:html_whole_filler* -Default: 0. -When 0, if |g:html_diff_one_file| is 1, a sequence of more than 3 filler lines -is displayed as three lines with the middle line mentioning the total number -of inserted lines. -When 1, always display all inserted lines as if |g:html_diff_one_file| were -not set. -> - :let g:html_whole_filler = 1 -< - *TOhtml-performance* *g:html_no_progress* -Default: 0. -When 0, display a progress bar in the statusline for each major step in the -2html.vim conversion process. -When 1, do not display the progress bar. This offers a minor speed improvement -but you won't have any idea how much longer the conversion might take; for big -files it can take a long time! -Example: > - - let g:html_no_progress = 1 -< -You can obtain better performance improvements by also instructing Vim to not -run interactively, so that too much time is not taken to redraw as the script -moves through the buffer, switches windows, and the like: > - - vim -E -s -c "let g:html_no_progress=1" -c "syntax on" -c "set ft=c" -c "runtime syntax/2html.vim" -cwqa myfile.c -< -Note that the -s flag prevents loading your vimrc and any plugins, so you -need to explicitly source/enable anything that will affect the HTML -conversion. See |-E| and |-s-ex| for details. It is probably best to create a -script to replace all the -c commands and use it with the -u flag instead of -specifying each command separately. - - *hl-TOhtmlProgress* *TOhtml-progress-color* -When displayed, the progress bar will show colored boxes along the statusline -as the HTML conversion proceeds. By default, the background color as the -current "DiffDelete" highlight group is used. If "DiffDelete" and "StatusLine" -have the same background color, TOhtml will automatically adjust the color to -differ. If you do not like the automatically selected colors, you can define -your own highlight colors for the progress bar. Example: > - - hi TOhtmlProgress guifg=#c0ffee ctermbg=7 -< - *g:html_number_lines* -Default: Current 'number' setting. -When 0, buffer text is displayed in the generated HTML without line numbering. -When 1, a column of line numbers is added to the generated HTML with the same -highlighting as the line number column in Vim (|hl-LineNr|). -Force line numbers even if 'number' is not set: > - :let g:html_number_lines = 1 -Force to omit the line numbers: > - :let g:html_number_lines = 0 -Go back to the default to use 'number' by deleting the variable: > - :unlet g:html_number_lines -< - *g:html_line_ids* -Default: 1 if |g:html_number_lines| is set, 0 otherwise. -When 1, adds an HTML id attribute to each line number, or to an empty <span> -inserted for that purpose if no line numbers are shown. This ID attribute -takes the form of L123 for single-buffer HTML pages, or W2L123 for diff-view -pages, and is used to jump to a specific line (in a specific window of a diff -view). Javascript is inserted to open any closed dynamic folds -(|g:html_dynamic_folds|) containing the specified line before jumping. The -javascript also allows omitting the window ID in the url, and the leading L. -For example: > - - page.html#L123 jumps to line 123 in a single-buffer file - page.html#123 does the same - - diff.html#W1L42 jumps to line 42 in the first window in a diff - diff.html#42 does the same -< - *g:html_use_css* -Default: 1. -When 1, generate valid HTML 5 markup with CSS styling, supported in all modern -browsers and many old browsers. -When 0, generate <font> tags and similar outdated markup. This is not -recommended but it may work better in really old browsers, email clients, -forum posts, and similar situations where basic CSS support is unavailable. -Example: > - :let g:html_use_css = 0 -< - *g:html_ignore_conceal* -Default: 0. -When 0, concealed text is removed from the HTML and replaced with a character -from |:syn-cchar| or 'listchars' as appropriate, depending on the current -value of 'conceallevel'. -When 1, include all text from the buffer in the generated HTML, even if it is -|conceal|ed. - -Either of the following commands will ensure that all text in the buffer is -included in the generated HTML (unless it is folded): > - :let g:html_ignore_conceal = 1 - :setl conceallevel=0 -< - *g:html_ignore_folding* -Default: 0. -When 0, text in a closed fold is replaced by the text shown for the fold in -Vim (|fold-foldtext|). See |g:html_dynamic_folds| if you also want to allow -the user to expand the fold as in Vim to see the text inside. -When 1, include all text from the buffer in the generated HTML; whether the -text is in a fold has no impact at all. |g:html_dynamic_folds| has no effect. - -Either of these commands will ensure that all text in the buffer is included -in the generated HTML (unless it is concealed): > - zR - :let g:html_ignore_folding = 1 -< - *g:html_dynamic_folds* -Default: 0. -When 0, text in a closed fold is not included at all in the generated HTML. -When 1, generate javascript to open a fold and show the text within, just like -in Vim. - -Setting this variable to 1 causes 2html.vim to always use CSS for styling, -regardless of what |g:html_use_css| is set to. - -This variable is ignored when |g:html_ignore_folding| is set. -> - :let g:html_dynamic_folds = 1 -< - *g:html_no_foldcolumn* -Default: 0. -When 0, if |g:html_dynamic_folds| is 1, generate a column of text similar to -Vim's foldcolumn (|fold-foldcolumn|) the user can click on to toggle folds -open or closed. The minimum width of the generated text column is the current -'foldcolumn' setting. -When 1, do not generate this column; instead, hovering the mouse cursor over -folded text will open the fold as if |g:html_hover_unfold| were set. -> - :let g:html_no_foldcolumn = 1 -< - *TOhtml-uncopyable-text* *g:html_prevent_copy* -Default: Empty string. -This option prevents certain regions of the generated HTML from being copied, -when you select all text in document rendered in a browser and copy it. Useful -for allowing users to copy-paste only the source text even if a fold column or -line numbers are shown in the generated content. Specify regions to be -affected in this way as follows: - f: fold column - n: line numbers (also within fold text) - t: fold text - d: diff filler - -Example, to make the fold column and line numbers uncopyable: > - :let g:html_prevent_copy = "fn" -< -The method used to prevent copying in the generated page depends on the value -of |g:html_use_input_for_pc|. - - *g:html_use_input_for_pc* -Default: "none" -If |g:html_prevent_copy| is non-empty, then: - -When "all", read-only <input> elements are used in place of normal text for -uncopyable regions. In some browsers, especially older browsers, after -selecting an entire page and copying the selection, the <input> tags are not -pasted with the page text. If |g:html_no_invalid| is 0, the <input> tags have -invalid type; this works in more browsers, but the page will not validate. -Note: This method does NOT work in recent versions of Chrome and equivalent -browsers; the <input> tags get pasted with the text. - -When "fallback" (default value), the same <input> elements are generated for -older browsers, but newer browsers (detected by CSS feature query) hide the -<input> elements and instead use generated content in an ::before pseudoelement -to display the uncopyable text. This method should work with the largest -number of browsers, both old and new. - -When "none", the <input> elements are not generated at all. Only the -generated-content method is used. This means that old browsers, notably -Internet Explorer, will either copy the text intended not to be copyable, or -the non-copyable text may not appear at all. However, this is the most -standards-based method, and there will be much less markup. - - *g:html_no_invalid* -Default: 0. -When 0, if |g:html_prevent_copy| is non-empty and |g:html_use_input_for_pc| is -not "none", an invalid attribute is intentionally inserted into the <input> -element for the uncopyable areas. This prevents pasting the <input> elements -in some applications. Specifically, some versions of Microsoft Word will not -paste the <input> elements if they contain this invalid attribute. When 1, no -invalid markup is inserted, and the generated page should validate. However, -<input> elements may be pasted into some applications and can be difficult to -remove afterward. - - *g:html_hover_unfold* -Default: 0. -When 0, the only way to open a fold generated by 2html.vim with -|g:html_dynamic_folds| set, is to click on the generated fold column. -When 1, use CSS 2.0 to allow the user to open a fold by moving the mouse -cursor over the displayed fold text. This is useful to allow users with -disabled javascript to view the folded text. - -Note that old browsers (notably Internet Explorer 6) will not support this -feature. Browser-specific markup for IE6 is included to fall back to the -normal CSS1 styling so that the folds show up correctly for this browser, but -they will not be openable without a foldcolumn. -> - :let g:html_hover_unfold = 1 -< - *g:html_id_expr* -Default: "" -Dynamic folding and jumping to line IDs rely on unique IDs within the document -to work. If generated HTML is copied into a larger document, these IDs are no -longer guaranteed to be unique. Set g:html_id_expr to an expression Vim can -evaluate to get a unique string to append to each ID used in a given document, -so that the full IDs will be unique even when combined with other content in a -larger HTML document. Example, to append _ and the buffer number to each ID: > - - :let g:html_id_expr = '"_" .. bufnr("%")' -< -To append a string "_mystring" to the end of each ID: > - - :let g:html_id_expr = '"_mystring"' -< -Note: When converting a diff view to HTML, the expression will only be -evaluated for the first window in the diff, and the result used for all the -windows. - - *TOhtml-wrap-text* *g:html_pre_wrap* -Default: Current 'wrap' setting. -When 0, if |g:html_no_pre| is 0 or unset, the text in the generated HTML does -not wrap at the edge of the browser window. -When 1, if |g:html_use_css| is 1, the CSS 2.0 "white-space:pre-wrap" value is -used, causing the text to wrap at whitespace at the edge of the browser -window. -Explicitly enable text wrapping: > - :let g:html_pre_wrap = 1 -Explicitly disable wrapping: > - :let g:html_pre_wrap = 0 -Go back to default, determine wrapping from 'wrap' setting: > - :unlet g:html_pre_wrap -< - *g:html_no_pre* -Default: 0. -When 0, buffer text in the generated HTML is surrounded by <pre>...</pre> -tags. Series of whitespace is shown as in Vim without special markup, and tab -characters can be included literally (see |g:html_expand_tabs|). -When 1 (not recommended), the <pre> tags are omitted, and a plain <div> is -used instead. Whitespace is replaced by a series of character -references, and <br> is used to end each line. This is another way to allow -text in the generated HTML is wrap (see |g:html_pre_wrap|) which also works in -old browsers, but may cause noticeable differences between Vim's display and -the rendered page generated by 2html.vim. -> - :let g:html_no_pre = 1 -< - *g:html_no_doc* -Default: 0. -When 1 it doesn't generate a full HTML document with a DOCTYPE, <head>, -<body>, etc. If |g:html_use_css| is enabled (the default) you'll have to -define the CSS manually. The |g:html_dynamic_folds| and |g:html_line_ids| -settings (off by default) also insert some JavaScript. - - - *g:html_no_links* -Default: 0. -Don't generate <a> tags for text that looks like an URL. - - *g:html_no_modeline* -Default: 0. -Don't generate a modeline disabling folding. - - *g:html_expand_tabs* -Default: 0 if 'tabstop' is 8, 'expandtab' is 0, 'vartabstop' is not in use, - and no fold column or line numbers occur in the generated HTML; - 1 otherwise. -When 1, <Tab> characters in the buffer text are replaced with an appropriate -number of space characters, or references if |g:html_no_pre| is 1. -When 0, if |g:html_no_pre| is 0 or unset, <Tab> characters in the buffer text -are included as-is in the generated HTML. This is useful for when you want to -allow copy and paste from a browser without losing the actual whitespace in -the source document. Note that this can easily break text alignment and -indentation in the HTML, unless set by default. - -Force |2html.vim| to keep <Tab> characters: > - :let g:html_expand_tabs = 0 -< -Force tabs to be expanded: > - :let g:html_expand_tabs = 1 -< - *TOhtml-encoding-detect* *TOhtml-encoding* -It is highly recommended to set your desired encoding with -|g:html_use_encoding| for any content which will be placed on a web server. - -If you do not specify an encoding, |2html.vim| uses the preferred IANA name -for the current value of 'fileencoding' if set, or 'encoding' if not. -'encoding' is always used for certain 'buftype' values. 'fileencoding' will be -set to match the chosen document encoding. - -Automatic detection works for the encodings mentioned specifically by name in -|encoding-names|, but TOhtml will only automatically use those encodings with -wide browser support. However, you can override this to support specific -encodings that may not be automatically detected by default (see options -below). See https://www.iana.org/assignments/character-sets for the IANA names. - -Note: By default all Unicode encodings are converted to UTF-8 with no BOM in -the generated HTML, as recommended by W3C: - - https://www.w3.org/International/questions/qa-choosing-encodings - https://www.w3.org/International/questions/qa-byte-order-mark - - *g:html_use_encoding* -Default: none, uses IANA name for current 'fileencoding' as above. -To overrule all automatic charset detection, set g:html_use_encoding to the -name of the charset to be used. It is recommended to set this variable to -something widely supported, like UTF-8, for anything you will be hosting on a -webserver: > - :let g:html_use_encoding = "UTF-8" -You can also use this option to omit the line that specifies the charset -entirely, by setting g:html_use_encoding to an empty string (NOT recommended): > - :let g:html_use_encoding = "" -To go back to the automatic mechanism, delete the |g:html_use_encoding| -variable: > - :unlet g:html_use_encoding -< - *g:html_encoding_override* -Default: none, autoload/tohtml.vim contains default conversions for encodings - mentioned by name at |encoding-names|. -This option allows |2html.vim| to detect the correct 'fileencoding' when you -specify an encoding with |g:html_use_encoding| which is not in the default -list of conversions. - -This is a dictionary of charset-encoding pairs that will replace existing -pairs automatically detected by TOhtml, or supplement with new pairs. - -Detect the HTML charset "windows-1252" as the encoding "8bit-cp1252": > - :let g:html_encoding_override = {'windows-1252': '8bit-cp1252'} -< - *g:html_charset_override* -Default: none, autoload/tohtml.vim contains default conversions for encodings - mentioned by name at |encoding-names| and which have wide - browser support. -This option allows |2html.vim| to detect the HTML charset for any -'fileencoding' or 'encoding' which is not detected automatically. You can also -use it to override specific existing encoding-charset pairs. For example, -TOhtml will by default use UTF-8 for all Unicode/UCS encodings. To use UTF-16 -and UTF-32 instead, use: > - :let g:html_charset_override = {'ucs-4': 'UTF-32', 'utf-16': 'UTF-16'} - -Note that documents encoded in either UTF-32 or UTF-16 have known -compatibility problems with some major browsers. - - *g:html_font* -Default: "monospace" -You can specify the font or fonts used in the converted document using -g:html_font. If this option is set to a string, then the value will be -surrounded with single quotes. If this option is set to a list then each list -item is surrounded by single quotes and the list is joined with commas. Either -way, "monospace" is added as the fallback generic family name and the entire -result used as the font family (using CSS) or font face (if not using CSS). -Examples: > - - " font-family: 'Consolas', monospace; - :let g:html_font = "Consolas" - - " font-family: 'DejaVu Sans Mono', 'Consolas', monospace; - :let g:html_font = ["DejaVu Sans Mono", "Consolas"] -< - *convert-to-XML* *convert-to-XHTML* *g:html_use_xhtml* -Default: 0. -When 0, generate standard HTML 4.01 (strict when possible). -When 1, generate XHTML 1.0 instead (XML compliant HTML). -> - :let g:html_use_xhtml = 1 -< ============================================================================== 5. Syntax file remarks *:syn-file-remarks* @@ -964,27 +536,29 @@ An alternative is to switch to the C++ highlighting: > Variable Highlight ~ *c_gnu* GNU gcc specific items *c_comment_strings* strings and numbers inside a comment -*c_space_errors* trailing white space and spaces before a <Tab> -*c_no_trail_space_error* ... but no trailing spaces +*c_space_errors* trailing white space and spaces before a <Tab> +*c_no_trail_space_error* ... but no trailing spaces *c_no_tab_space_error* ... but no spaces before a <Tab> *c_no_bracket_error* don't highlight {}; inside [] as errors *c_no_curly_error* don't highlight {}; inside [] and () as errors; - except { and } in first column - Default is to highlight them, otherwise you - can't spot a missing ")". + ...except { and } in first column + Default is to highlight them, otherwise you + can't spot a missing ")". *c_curly_error* highlight a missing } by finding all pairs; this forces syncing from the start of the file, can be slow *c_no_ansi* don't do standard ANSI types and constants -*c_ansi_typedefs* ... but do standard ANSI types +*c_ansi_typedefs* ... but do standard ANSI types *c_ansi_constants* ... but do standard ANSI constants *c_no_utf* don't highlight \u and \U in strings -*c_syntax_for_h* for `*.h` files use C syntax instead of C++ and use objc +*c_syntax_for_h* for `*.h` files use C syntax instead of C++ and use objc syntax instead of objcpp *c_no_if0* don't highlight "#if 0" blocks as comments *c_no_cformat* don't highlight %-formats in strings *c_no_c99* don't highlight C99 standard items *c_no_c11* don't highlight C11 standard items *c_no_bsd* don't highlight BSD specific types +*c_functions* highlight function calls and definitions +*c_function_pointers* highlight function pointers definitions When 'foldmethod' is set to "syntax" then `/* */` comments and { } blocks will become a fold. If you don't want comments to become a fold use: > @@ -1233,7 +807,6 @@ there are very long lines in the file. To disable translations: > Also see |diff-slow|. - DIRCOLORS *dircolors.vim* *ft-dircolors-syntax* The dircolors utility highlighting definition has one option. It exists to @@ -1289,12 +862,15 @@ Stack Overflow - https://stackoverflow.com/questions/12407800/which-comment-style-should-i-use-in-batch-files -To allow the use of the :: idiom for comments in the Windows Command -Interpreter or working with MS-DOS bat files, set the -dosbatch_colons_comment variable to anything: > +To allow the use of the :: idiom for comments in command blocks with the +Windows Command Interpreter set the dosbatch_colons_comment variable to +anything: > :let dosbatch_colons_comment = 1 +If this variable is set then a :: comment that is the last line in a command +block will be highlighted as an error. + There is an option that covers whether `*.btm` files should be detected as type "dosbatch" (MS-DOS batch files) or type "btm" (4DOS batch files). The latter is used by default. You may select the former with the following line: > @@ -1552,21 +1128,26 @@ edit F# or Fortran at all, use this in your startup vimrc: > FORTRAN *fortran.vim* *ft-fortran-syntax* Default highlighting and dialect ~ -Highlighting appropriate for Fortran 2008 is used by default. This choice -should be appropriate for most users most of the time because Fortran 2008 is -almost a superset of previous versions (Fortran 2003, 95, 90, and 77). +Vim highlights according to Fortran 2023 (the most recent standard). This +choice should be appropriate for most users most of the time because Fortran +2023 is almost a superset of previous versions (Fortran 2018, 2008, 2003, 95, +90, 77, and 66). A few legacy constructs deleted or declared obsolescent, +respectively, in recent Fortran standards are highlighted as errors and todo +items. + +The syntax script no longer supports Fortran dialects. The variable +fortran_dialect is now silently ignored. Since computers are much faster now, +the variable fortran_more_precise is no longer needed and is silently ignored. Fortran source code form ~ Fortran code can be in either fixed or free source form. Note that the syntax highlighting will not be correct if the form is incorrectly set. -When you create a new fortran file, the syntax script assumes fixed source +When you create a new Fortran file, the syntax script assumes fixed source form. If you always use free source form, then > :let fortran_free_source=1 -in your vimrc prior to the :syntax on command. If you always use fixed -source form, then > +If you always use fixed source form, then > :let fortran_fixed_source=1 -in your vimrc prior to the :syntax on command. If the form of the source code depends, in a non-standard way, upon the file extension, then it is most convenient to set fortran_free_source in a ftplugin @@ -1575,105 +1156,65 @@ will work only if the "filetype plugin indent on" command precedes the "syntax on" command in your .vimrc file. -When you edit an existing fortran file, the syntax script will assume free +When you edit an existing Fortran file, the syntax script will assume free source form if the fortran_free_source variable has been set, and assumes -fixed source form if the fortran_fixed_source variable has been set. If -neither of these variables have been set, the syntax script attempts to +fixed source form if the fortran_fixed_source variable has been set. Suppose +neither of these variables have been set. In that case, the syntax script attempts to determine which source form has been used by examining the file extension using conventions common to the ifort, gfortran, Cray, NAG, and PathScale compilers (.f, .for, .f77 for fixed-source, .f90, .f95, .f03, .f08 for -free-source). If none of this works, then the script examines the first five -columns of the first 500 lines of your file. If no signs of free source form -are detected, then the file is assumed to be in fixed source form. The -algorithm should work in the vast majority of cases. In some cases, such as a -file that begins with 500 or more full-line comments, the script may -incorrectly decide that the fortran code is in fixed form. If that happens, -just add a non-comment statement beginning anywhere in the first five columns -of the first twenty-five lines, save (:w) and then reload (:e!) the file. - -Tabs in fortran files ~ +free-source). No default is used for the .fpp and .ftn file extensions because +different compilers treat them differently. If none of this works, then the +script examines the first five columns of the first 500 lines of your file. If +no signs of free source form are detected, then the file is assumed to be in +fixed source form. The algorithm should work in the vast majority of cases. +In some cases, such as a file that begins with 500 or more full-line comments, +the script may incorrectly decide that the code is in fixed form. If that +happens, just add a non-comment statement beginning anywhere in the first five +columns of the first twenty-five lines, save (:w), and then reload (:e!) the +file. + +Vendor extensions ~ +Fixed-form Fortran requires a maximum line length of 72 characters but the +script allows a maximum line length of 80 characters as do all compilers +created in the last three decades. An even longer line length of 132 +characters is allowed if you set the variable fortran_extended_line_length +with a command such as > + :let fortran_extended_line_length=1 + +If you want additional highlighting of the CUDA Fortran extensions, you should +set the variable fortran_CUDA with a command such as > + :let fortran_CUDA=1 + +To activate recognition of some common, non-standard, vendor-supplied +intrinsics, you should set the variable fortran_vendor_intrinsics with a +command such as > + :let fortran_vendor_intrinsics=1 + +Tabs in Fortran files ~ Tabs are not recognized by the Fortran standards. Tabs are not a good idea in -fixed format fortran source code which requires fixed column boundaries. +fixed format Fortran source code which requires fixed column boundaries. Therefore, tabs are marked as errors. Nevertheless, some programmers like -using tabs. If your fortran files contain tabs, then you should set the +using tabs. If your Fortran files contain tabs, then you should set the variable fortran_have_tabs in your vimrc with a command such as > :let fortran_have_tabs=1 -placed prior to the :syntax on command. Unfortunately, the use of tabs will -mean that the syntax file will not be able to detect incorrect margins. +Unfortunately, the use of tabs will mean that the syntax file will not be able +to detect incorrect margins. -Syntax folding of fortran files ~ -If you wish to use foldmethod=syntax, then you must first set the variable -fortran_fold with a command such as > +Syntax folding of Fortran files ~ +Vim will fold your file using foldmethod=syntax, if you set the variable +fortran_fold in your .vimrc with a command such as > :let fortran_fold=1 to instruct the syntax script to define fold regions for program units, that is main programs starting with a program statement, subroutines, function -subprograms, block data subprograms, interface blocks, and modules. If you -also set the variable fortran_fold_conditionals with a command such as > +subprograms, modules, submodules, blocks of comment lines, and block data +units. Block, interface, associate, critical, type definition, and change team +constructs will also be folded. If you also set the variable +fortran_fold_conditionals with a command such as > :let fortran_fold_conditionals=1 -then fold regions will also be defined for do loops, if blocks, and select -case constructs. If you also set the variable -fortran_fold_multilinecomments with a command such as > - :let fortran_fold_multilinecomments=1 -then fold regions will also be defined for three or more consecutive comment -lines. Note that defining fold regions can be slow for large files. - -If fortran_fold, and possibly fortran_fold_conditionals and/or -fortran_fold_multilinecomments, have been set, then vim will fold your file if -you set foldmethod=syntax. Comments or blank lines placed between two program -units are not folded because they are seen as not belonging to any program -unit. - -More precise fortran syntax ~ -If you set the variable fortran_more_precise with a command such as > - :let fortran_more_precise=1 -then the syntax coloring will be more precise but slower. In particular, -statement labels used in do, goto and arithmetic if statements will be -recognized, as will construct names at the end of a do, if, select or forall -construct. - -Non-default fortran dialects ~ -The syntax script supports two Fortran dialects: f08 and F. You will probably -find the default highlighting (f08) satisfactory. A few legacy constructs -deleted or declared obsolescent in the 2008 standard are highlighted as todo -items. - -If you use F, the advantage of setting the dialect appropriately is that -other legacy features excluded from F will be highlighted as todo items and -that free source form will be assumed. - -The dialect can be selected in various ways. If all your fortran files use -the same dialect, set the global variable fortran_dialect in your vimrc prior -to your syntax on statement. The case-sensitive, permissible values of -fortran_dialect are "f08" or "F". Invalid values of fortran_dialect are -ignored. - -If the dialect depends upon the file extension, then it is most convenient to -set a buffer-local variable in a ftplugin file. For more information on -ftplugin files, see |ftplugin|. For example, if all your fortran files with -an .f90 extension are written in the F subset, your ftplugin file should -contain the code > - let s:extfname = expand("%:e") - if s:extfname ==? "f90" - let b:fortran_dialect="F" - else - unlet! b:fortran_dialect - endif -Note that this will work only if the "filetype plugin indent on" command -precedes the "syntax on" command in your vimrc file. - -Finer control is necessary if the file extension does not uniquely identify -the dialect. You can override the default dialect, on a file-by-file basis, -by including a comment with the directive "fortran_dialect=xx" (where xx=F or -f08) in one of the first three lines in your file. For example, your older .f -files may be legacy code but your newer ones may be F codes, and you would -identify the latter by including in the first three lines of those files a -Fortran comment of the form > - ! fortran_dialect=F - -For previous versions of the syntax, you may have set fortran_dialect to the -now-obsolete values "f77", "f90", "f95", or "elf". Such settings will be -silently handled as "f08". Users of "elf" may wish to experiment with "F" -instead. +then fold regions will also be defined for do loops, if blocks, select case, +select type, and select rank constructs. Note that defining fold regions can +be slow for large files. The syntax/fortran.vim script contains embedded comments that tell you how to comment and/or uncomment some lines to (a) activate recognition of some @@ -1686,7 +1227,7 @@ Parenthesis checking does not catch too few closing parentheses. Hollerith strings are not recognized. Some keywords may be highlighted incorrectly because Fortran90 has no reserved words. -For further information related to fortran, see |ft-fortran-indent| and +For further information related to Fortran, see |ft-fortran-indent| and |ft-fortran-plugin|. FREEBASIC *freebasic.vim* *ft-freebasic-syntax* @@ -2236,6 +1777,56 @@ have the following in your vimrc: > let filetype_m = "mma" +MODULA2 *modula2.vim* *ft-modula2-syntax* + +Vim will recognise comments with dialect tags to automatically select a given +dialect. + +The syntax for a dialect tag comment is: > + + taggedComment := + '(*!' dialectTag '*)' + ; + + dialectTag := + m2pim | m2iso | m2r10 + ; + + reserved words + m2pim = 'm2pim', m2iso = 'm2iso', m2r10 = 'm2r10' + +A dialect tag comment is recognised by Vim if it occurs within the first 200 +lines of the source file. Only the very first such comment is recognised, any +additional dialect tag comments are ignored. + +Example: > + + DEFINITION MODULE FooLib; (*!m2pim*) + ... + +Variable g:modula2_default_dialect sets the default Modula-2 dialect when the +dialect cannot be determined from the contents of the Modula-2 file: if +defined and set to 'm2pim', the default dialect is PIM. + +Example: > + + let g:modula2_default_dialect = 'm2pim' + + +Highlighting is further configurable for each dialect via the following +variables. + +Variable Highlight ~ +*modula2_iso_allow_lowline* allow low line in identifiers +*modula2_iso_disallow_octals* disallow octal integer literals +*modula2_iso_disallow_synonyms* disallow "@", "&" and "~" synonyms + +*modula2_pim_allow_lowline* allow low line in identifiers +*modula2_pim_disallow_octals* disallow octal integer literals +*modula2_pim_disallow_synonyms* disallow "&" and "~" synonyms + +*modula2_r10_allow_lowline* allow low line in identifiers + MOO *moo.vim* *ft-moo-syntax* If you use C-style comments inside expressions and find it mangles your @@ -2827,10 +2418,20 @@ To highlight R code in knitr chunk headers: > let rmd_syn_hl_chunk = 1 By default, chunks of R code will be highlighted following the rules of R -language. If you want proper syntax highlighting of chunks of other languages, -you should add them to either `markdown_fenced_languages` or -`rmd_fenced_languages`. For example to properly highlight both R and Python, -you may add this to your |vimrc|: > +language. Moreover, whenever the buffer is saved, Vim scans the buffer and +highlights other languages if they are present in new chunks. LaTeX code also +is automatically recognized and highlighted when the buffer is saved. This +behavior can be controlled with the variables `rmd_dynamic_fenced_languages`, +and `rmd_include_latex` whose valid values are: > + let rmd_dynamic_fenced_languages = 0 " No autodetection of languages + let rmd_dynamic_fenced_languages = 1 " Autodetection of languages + let rmd_include_latex = 0 " Don't highlight LaTeX code + let rmd_include_latex = 1 " Autodetect LaTeX code + let rmd_include_latex = 2 " Always include LaTeX highlighting + +If the value of `rmd_dynamic_fenced_languages` is 0, you still can set the +list of languages whose chunks of code should be properly highlighted, as in +the example: > let rmd_fenced_languages = ['r', 'python'] @@ -5163,6 +4764,18 @@ guisp={color-name} *guisp* Black White Orange Purple Violet + Colors which define Nvim's default color scheme: + NvimDarkBlue NvimLightBlue + NvimDarkCyan NvimLightCyan + NvimDarkGreen NvimLightGreen + NvimDarkGrey1 NvimLightGrey1 + NvimDarkGrey2 NvimLightGrey2 + NvimDarkGrey3 NvimLightGrey3 + NvimDarkGrey4 NvimLightGrey4 + NvimDarkMagenta NvimLightMagenta + NvimDarkRed NvimLightRed + NvimDarkYellow NvimLightYellow + You can also specify a color by its RGB (red, green, blue) values. The format is "#rrggbb", where "rr" is the Red value diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 9bdc6b8d24..5f33802ad5 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -17,25 +17,33 @@ changes. This documentation may also not fully reflect the latest changes. ============================================================================== PARSER FILES *treesitter-parsers* -Parsers are the heart of tree-sitter. They are libraries that tree-sitter will +Parsers are the heart of treesitter. They are libraries that treesitter will search for in the `parser` runtime directory. By default, Nvim bundles parsers for C, Lua, Vimscript, Vimdoc and Treesitter query files, but parsers can be -installed manually or via a plugin like -https://github.com/nvim-treesitter/nvim-treesitter. Parsers are searched for -as `parser/{lang}.*` in any 'runtimepath' directory. If multiple parsers for -the same language are found, the first one is used. (This typically implies -the priority "user config > plugins > bundled". +installed via a plugin like https://github.com/nvim-treesitter/nvim-treesitter +or even manually. + +Parsers are searched for as `parser/{lang}.*` in any 'runtimepath' directory. +If multiple parsers for the same language are found, the first one is used. +(NOTE: This typically implies the priority "user config > plugins > bundled".) A parser can also be loaded manually using a full path: >lua vim.treesitter.language.add('python', { path = "/path/to/python.so" }) < +To associate certain |filetypes| with a treesitter language (name of parser), +use |vim.treesitter.language.register()|. For example, to use the `xml` +treesitter parser for buffers with filetype `svg` or `xslt`, use: >lua + + vim.treesitter.language.register('xml', { 'svg', 'xslt' }) +< + ============================================================================== TREESITTER TREES *treesitter-tree* *TSTree* A "treesitter tree" represents the parsed contents of a buffer, which can be used to perform further analysis. It is a |userdata| reference to an object -held by the tree-sitter library. +held by the treesitter library. An instance `TSTree` of a treesitter tree supports the following methods. @@ -51,7 +59,7 @@ TREESITTER NODES *treesitter-node* A "treesitter node" represents one specific element of the parsed contents of a buffer, which can be captured by a |Query| for, e.g., highlighting. It is -a |userdata| reference to an object held by the tree-sitter library. +a |userdata| reference to an object held by the treesitter library. An instance `TSNode` of a treesitter node supports the following methods. @@ -202,33 +210,53 @@ TREESITTER QUERY PREDICATES *treesitter-predicates* Predicates are special scheme nodes that are evaluated to conditionally capture nodes. For example, the `eq?` predicate can be used as follows: >query - ((identifier) @foo (#eq? @foo "foo")) + ((identifier) @variable.builtin + (#eq? @variable.builtin "self")) < -to only match identifier corresponding to the `"foo"` text. +to only match identifier corresponding to the `"self"` text. Such queries can +be used to highlight built-in functions or variables differently, for instance. The following predicates are built in: `eq?` *treesitter-predicate-eq?* Match a string against the text corresponding to a node: >query - ((identifier) @foo (#eq? @foo "foo")) + ((identifier) @variable.builtin (#eq? @variable.builtin "self")) ((node1) @left (node2) @right (#eq? @left @right)) < + `any-eq?` *treesitter-predicate-any-eq?* + Like `eq?`, but for quantified patterns only one captured node must + match. + `match?` *treesitter-predicate-match?* `vim-match?` *treesitter-predicate-vim-match?* Match a |regexp| against the text corresponding to a node: >query ((identifier) @constant (#match? @constant "^[A-Z_]+$")) -< Note: The `^` and `$` anchors will match the start and end of the +< + Note: The `^` and `$` anchors will match the start and end of the node's text. + `any-match?` *treesitter-predicate-any-match?* + `any-vim-match?` *treesitter-predicate-any-vim-match?* + Like `match?`, but for quantified patterns only one captured node must + match. + `lua-match?` *treesitter-predicate-lua-match?* Match |lua-patterns| against the text corresponding to a node, similar to `match?` + `any-lua-match?` *treesitter-predicate-any-lua-match?* + Like `lua-match?`, but for quantified patterns only one captured node + must match. + `contains?` *treesitter-predicate-contains?* Match a string against parts of the text corresponding to a node: >query ((identifier) @foo (#contains? @foo "foo")) ((identifier) @foo-bar (#contains? @foo-bar "foo" "bar")) < + `any-contains?` *treesitter-predicate-any-contains?* + Like `contains?`, but for quantified patterns only one captured node + must match. + `any-of?` *treesitter-predicate-any-of?* Match any of the given strings against the text corresponding to a node: >query @@ -254,6 +282,32 @@ The following predicates are built in: Each predicate has a `not-` prefixed predicate that is just the negation of the predicate. + *lua-treesitter-all-predicate* + *lua-treesitter-any-predicate* +Queries can use quantifiers to capture multiple nodes. When a capture contains +multiple nodes, predicates match only if ALL nodes contained by the capture +match the predicate. Some predicates (`eq?`, `match?`, `lua-match?`, +`contains?`) accept an `any-` prefix to instead match if ANY of the nodes +contained by the capture match the predicate. + +As an example, consider the following Lua code: >lua + + -- TODO: This is a + -- very long + -- comment (just imagine it) +< +using the following predicated query: +>query + (((comment)+ @comment) + (#match? @comment "TODO")) +< +This query will not match because not all of the nodes captured by @comment +match the predicate. Instead, use: +>query + (((comment)+ @comment) + (#any-match? @comment "TODO")) +< + Further predicates can be added via |vim.treesitter.query.add_predicate()|. Use |vim.treesitter.query.list_predicates()| to list all available predicates. @@ -280,11 +334,12 @@ The following directives are built in: Examples: >query ((identifier) @foo (#set! @foo "kind" "parameter")) ((node1) @left (node2) @right (#set! "type" "pair")) + ((codeblock) @markup.raw.block (#set! "priority" 90)) < `offset!` *treesitter-directive-offset!* Takes the range of the captured node and applies an offset. This will - generate a new range object for the captured node as - `metadata[capture_id].range`. + set a new `Range4` object for the captured node with `capture_id` as + `metadata[capture_id].range`. Useful for |treesitter-language-injections|. Parameters: ~ {capture_id} @@ -297,12 +352,13 @@ The following directives are built in: ((identifier) @constant (#offset! @constant 0 1 0 -1)) < `gsub!` *treesitter-directive-gsub!* - Transforms the content of the node using a Lua pattern. This will set + Transforms the content of the node using a |lua-pattern|. This will set a new `metadata[capture_id].text`. Parameters: ~ {capture_id} {pattern} + {replacement} Example: >query (#gsub! @_node ".*%.(.*)" "%1") @@ -344,13 +400,13 @@ currently supported modeline alternatives: Note: These modeline comments must be at the top of the query, but can be repeated, for example, the following two modeline blocks are both valid: >query - ;; inherits: foo,bar + ;; inherits: typescript,jsx ;; extends < >query ;; extends ;; - ;; inherits: baz + ;; inherits: css < ============================================================================== TREESITTER SYNTAX HIGHLIGHTING *treesitter-highlight* @@ -359,30 +415,47 @@ Syntax highlighting is specified through queries named `highlights.scm`, which match a |TSNode| in the parsed |TSTree| to a `capture` that can be assigned a highlight group. For example, the query >query - (parameters (identifier) @parameter) + (parameters (identifier) @variable.parameter) < -matches any `identifier` node inside a function `parameter` node (e.g., the -`bar` in `foo(bar)`) to the capture named `@parameter`. It is also possible to -match literal expressions (provided the parser returns them): >query +matches any `identifier` node inside a function `parameters` node to the +capture named `@variable.parameter`. For example, for a Lua code >lua - "return" @keyword.return + function f(foo, bar) end +< +which will be parsed as (see |:InspectTree|): >query + + (function_declaration ; [1:1 - 24] + name: (identifier) ; [1:10 - 10] + parameters: (parameters ; [1:11 - 20] + name: (identifier) ; [1:12 - 14] + name: (identifier))) ; [1:17 - 19] +< +the above query will highlight `foo` and `bar` as `@variable.parameter`. + +It is also possible to match literal expressions (provided the parser returns +them): +>query + [ + "if" + "else" + ] @keyword.conditional < Assuming a suitable parser and `highlights.scm` query is found in runtimepath, treesitter highlighting for the current buffer can be enabled simply via |vim.treesitter.start()|. *treesitter-highlight-groups* -The capture names, with `@` included, are directly usable as highlight groups. +The capture names, prefixed with `@`, are directly usable as highlight groups. For many commonly used captures, the corresponding highlight groups are linked -to Nvim's standard |highlight-groups| by default but can be overridden in -colorschemes. +to Nvim's standard |highlight-groups| by default (e.g., `@comment` links to +`Comment`) but can be overridden in colorschemes. A fallback system is implemented, so that more specific groups fallback to -more generic ones. For instance, in a language that has separate doc comments, -`@comment.doc` could be used. If this group is not defined, the highlighting -for an ordinary `@comment` is used. This way, existing color schemes already -work out of the box, but it is possible to add more specific variants for -queries that make them available. +more generic ones. For instance, in a language that has separate doc comments +(e.g., c, java, etc.), `@comment.documentation` could be used. If this group +is not defined, the highlighting for an ordinary `@comment` is used. This way, +existing color schemes already work out of the box, but it is possible to add +more specific variants for queries that make them available. As an additional rule, capture highlights can always be specialized by language, by appending the language name after an additional dot. For @@ -390,61 +463,119 @@ instance, to highlight comments differently per language: >vim hi @comment.c guifg=Blue hi @comment.lua guifg=DarkBlue - hi link @comment.doc.java String -< -The following captures are linked by default to standard |group-name|s: -> - @text.literal Comment - @text.reference Identifier - @text.title Title - @text.uri Underlined - @text.underline Underlined - @text.todo Todo - - @comment Comment - @punctuation Delimiter - - @constant Constant - @constant.builtin Special - @constant.macro Define - @define Define - @macro Macro - @string String - @string.escape SpecialChar - @string.special SpecialChar - @character Character - @character.special SpecialChar - @number Number - @boolean Boolean - @float Float - - @function Function - @function.builtin Special - @function.macro Macro - @parameter Identifier - @method Function - @field Identifier - @property Identifier - @constructor Special - - @conditional Conditional - @repeat Repeat - @label Label - @operator Operator - @keyword Keyword - @exception Exception - - @variable Identifier - @type Type - @type.definition Typedef - @storageclass StorageClass - @structure Structure - @namespace Identifier - @include Include - @preproc PreProc - @debug Debug - @tag Tag + hi link @comment.documentation.java String < +The following is a list of standard captures used in queries for Nvim, +highlighted according to the current colorscheme (use |:Inspect| on one to see +the exact definition): + +@variable various variable names +@variable.builtin built-in variable names (e.g. `this` / `self`) +@variable.parameter parameters of a function +@variable.member object and struct fields + +@constant constant identifiers +@constant.builtin built-in constant values +@constant.macro constants defined by the preprocessor + +@module modules or namespaces +@module.builtin built-in modules or namespaces +@label GOTO and other labels (e.g. `label:` in C), including heredoc labels + +@string string literals +@string.documentation string documenting code (e.g. Python docstrings) +@string.regexp regular expressions +@string.escape escape sequences +@string.special other special strings (e.g. dates) +@string.special.symbol symbols or atoms +@string.special.path filenames +@string.special.url URIs (e.g. hyperlinks) + +@character character literals +@character.special special characters (e.g. wildcards) + +@boolean boolean literals +@number numeric literals +@number.float floating-point number literals + +@type type or class definitions and annotations +@type.builtin built-in types +@type.definition identifiers in type definitions (e.g. `typedef <type> <identifier>` in C) +@type.qualifier type qualifiers (e.g. `const`) + +@attribute attribute annotations (e.g. Python decorators) +@property the key in key/value pairs + +@function function definitions +@function.builtin built-in functions +@function.call function calls +@function.macro preprocessor macros + +@function.method method definitions +@function.method.call method calls + +@constructor constructor calls and definitions +@operator symbolic operators (e.g. `+` / `*`) + +@keyword keywords not fitting into specific categories +@keyword.coroutine keywords related to coroutines (e.g. `go` in Go, `async/await` in Python) +@keyword.function keywords that define a function (e.g. `func` in Go, `def` in Python) +@keyword.operator operators that are English words (e.g. `and` / `or`) +@keyword.import keywords for including modules (e.g. `import` / `from` in Python) +@keyword.storage modifiers that affect storage in memory or life-time +@keyword.repeat keywords related to loops (e.g. `for` / `while`) +@keyword.return keywords like `return` and `yield` +@keyword.debug keywords related to debugging +@keyword.exception keywords related to exceptions (e.g. `throw` / `catch`) + +@keyword.conditional keywords related to conditionals (e.g. `if` / `else`) +@keyword.conditional.ternary ternary operator (e.g. `?` / `:`) + +@keyword.directive various preprocessor directives and shebangs +@keyword.directive.define preprocessor definition directives + +@punctuation.delimiter delimiters (e.g. `;` / `.` / `,`) +@punctuation.bracket brackets (e.g. `()` / `{}` / `[]`) +@punctuation.special special symbols (e.g. `{}` in string interpolation) + +@comment line and block comments +@comment.documentation comments documenting code + +@comment.error error-type comments (e.g. `ERROR`, `FIXME`, `DEPRECATED`) +@comment.warning warning-type comments (e.g. `WARNING`, `FIX`, `HACK`) +@comment.todo todo-type comments (e.g. `TODO`, `WIP`, `FIXME`) +@comment.note note-type comments (e.g. `NOTE`, `INFO`, `XXX`) + +@markup.strong bold text +@markup.italic italic text +@markup.strikethrough struck-through text +@markup.underline underlined text (only for literal underline markup!) + +@markup.heading headings, titles (including markers) + +@markup.quote block quotes +@markup.math math environments (e.g. `$ ... $` in LaTeX) +@markup.environment environments (e.g. in LaTeX) + +@markup.link text references, footnotes, citations, etc. +@markup.link.label link, reference descriptions +@markup.link.url URL-style links + +@markup.raw literal or verbatim text (e.g. inline code) +@markup.raw.block literal or verbatim text as a stand-alone block + +@markup.list list markers +@markup.list.checked checked todo-style list markers +@markup.list.unchecked unchecked todo-style list markers + +@diff.plus added text (for diff files) +@diff.minus deleted text (for diff files) +@diff.delta changed text (for diff files) + +@tag XML-style tag names (e.g. in XML, HTML, etc.) +@tag.attribute XML-style tag attributes +@tag.delimiter XML-style tag delimiters + *treesitter-highlight-spell* The special `@spell` capture can be used to indicate that a node should be spell checked by Nvim's builtin |spell| checker. For example, the following @@ -475,7 +606,7 @@ Conceals specified in this way respect 'conceallevel'. *treesitter-highlight-priority* Treesitter uses |nvim_buf_set_extmark()| to set highlights with a default priority of 100. This enables plugins to set a highlighting priority lower or -higher than tree-sitter. It is also possible to change the priority of an +higher than treesitter. It is also possible to change the priority of an individual query pattern manually by setting its `"priority"` metadata attribute: >query @@ -536,17 +667,17 @@ associated with patterns: VIM.TREESITTER *lua-treesitter* The remainder of this document is a reference manual for the `vim.treesitter` -Lua module, which is the main interface for Nvim's tree-sitter integration. +Lua module, which is the main interface for Nvim's treesitter integration. Most of the following content is automatically generated from the function documentation. *vim.treesitter.language_version* -The latest parser ABI version that is supported by the bundled tree-sitter +The latest parser ABI version that is supported by the bundled treesitter library. *vim.treesitter.minimum_language_version* -The earliest parser ABI version that is supported by the bundled tree-sitter +The earliest parser ABI version that is supported by the bundled treesitter library. ============================================================================== @@ -559,30 +690,20 @@ foldexpr({lnum}) *vim.treesitter.foldexpr()* < Parameters: ~ - • {lnum} (integer|nil) Line number to calculate fold level for - - Return: ~ - (string) - -foldtext() *vim.treesitter.foldtext()* - Returns the highlighted content of the first line of the fold or falls - back to |foldtext()| if no treesitter parser is found. Can be set directly - to 'foldtext': >lua - vim.wo.foldtext = 'v:lua.vim.treesitter.foldtext()' -< + • {lnum} (`integer?`) Line number to calculate fold level for Return: ~ - `{ [1]: string, [2]: string[] }[]` | string + (`string`) *vim.treesitter.get_captures_at_cursor()* get_captures_at_cursor({winnr}) Returns a list of highlight capture names under the cursor Parameters: ~ - • {winnr} (integer|nil) Window handle or 0 for current window (default) + • {winnr} (`integer?`) Window handle or 0 for current window (default) Return: ~ - string[] List of capture names + (`string[]`) List of capture names *vim.treesitter.get_captures_at_pos()* get_captures_at_pos({bufnr}, {row}, {col}) @@ -593,12 +714,13 @@ get_captures_at_pos({bufnr}, {row}, {col}) if none are defined). Parameters: ~ - • {bufnr} (integer) Buffer number (0 for current buffer) - • {row} (integer) Position row - • {col} (integer) Position column + • {bufnr} (`integer`) Buffer number (0 for current buffer) + • {row} (`integer`) Position row + • {col} (`integer`) Position column Return: ~ - table[] List of captures `{ capture = "name", metadata = { ... } }` + (`table[]`) List of captures + `{ capture = "name", metadata = { ... } }` get_node({opts}) *vim.treesitter.get_node()* Returns the smallest named node at the given position @@ -610,45 +732,47 @@ get_node({opts}) *vim.treesitter.get_node()* < Parameters: ~ - • {opts} (table|nil) Optional keyword arguments: - • bufnr integer|nil Buffer number (nil or 0 for current + • {opts} (`table?`) Optional keyword arguments: + • {bufnr} (`integer?`) Buffer number (nil or 0 for current buffer) - • pos table|nil 0-indexed (row, col) tuple. Defaults to cursor - position in the current window. Required if {bufnr} is not - the current buffer - • ignore_injections boolean Ignore injected languages (default - true) + • {pos} (`{ [1]: integer, [2]: integer }?`) 0-indexed (row, + col) tuple. Defaults to cursor position in the current + window. Required if {bufnr} is not the current buffer + • {lang} (`string?`) Parser language. (default: from buffer + filetype) + • {ignore_injections} (`boolean?`) Ignore injected languages + (default true) Return: ~ - |TSNode| | nil Node at the given position + (`TSNode?`) Node at the given position get_node_range({node_or_range}) *vim.treesitter.get_node_range()* Returns the node's range or an unpacked range table Parameters: ~ - • {node_or_range} (|TSNode| | table) Node or table of positions + • {node_or_range} (`TSNode|table`) Node or table of positions Return (multiple): ~ - (integer) start_row - (integer) start_col - (integer) end_row - (integer) end_col + (`integer`) start_row + (`integer`) start_col + (`integer`) end_row + (`integer`) end_col *vim.treesitter.get_node_text()* get_node_text({node}, {source}, {opts}) Gets the text corresponding to a given node Parameters: ~ - • {node} |TSNode| - • {source} (integer|string) Buffer or string from which the {node} is + • {node} (`TSNode`) + • {source} (`integer|string`) Buffer or string from which the {node} is extracted - • {opts} (table|nil) Optional parameters. + • {opts} (`table?`) Optional parameters. • metadata (table) Metadata of a specific capture. This would be set to `metadata[capture_id]` when using |vim.treesitter.query.add_directive()|. Return: ~ - (string) + (`string`) get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()* Returns the parser for a specific buffer and attaches it to the buffer @@ -656,39 +780,39 @@ get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()* If needed, this will create the parser. Parameters: ~ - • {bufnr} (integer|nil) Buffer the parser should be tied to (default: + • {bufnr} (`integer?`) Buffer the parser should be tied to (default: current buffer) - • {lang} (string|nil) Filetype of this parser (default: buffer + • {lang} (`string?`) Language of this parser (default: from buffer filetype) - • {opts} (table|nil) Options to pass to the created language tree + • {opts} (`table?`) Options to pass to the created language tree Return: ~ - |LanguageTree| object to use for parsing + (`vim.treesitter.LanguageTree`) object to use for parsing get_range({node}, {source}, {metadata}) *vim.treesitter.get_range()* Get the range of a |TSNode|. Can also supply {source} and {metadata} to get the range with directives applied. Parameters: ~ - • {node} |TSNode| - • {source} integer|string|nil Buffer or string from which the {node} + • {node} (`TSNode`) + • {source} (`integer|string?`) Buffer or string from which the {node} is extracted - • {metadata} TSMetadata|nil + • {metadata} (`vim.treesitter.query.TSMetadata?`) Return: ~ - (table) + (`Range6`) *vim.treesitter.get_string_parser()* get_string_parser({str}, {lang}, {opts}) Returns a string parser Parameters: ~ - • {str} (string) Text to parse - • {lang} (string) Language of this string - • {opts} (table|nil) Options to pass to the created language tree + • {str} (`string`) Text to parse + • {lang} (`string`) Language of this string + • {opts} (`table?`) Options to pass to the created language tree Return: ~ - |LanguageTree| object to use for parsing + (`vim.treesitter.LanguageTree`) object to use for parsing inspect_tree({opts}) *vim.treesitter.inspect_tree()* Open a window that displays a textual representation of the nodes in the @@ -697,15 +821,15 @@ inspect_tree({opts}) *vim.treesitter.inspect_tree()* While in the window, press "a" to toggle display of anonymous nodes, "I" to toggle the display of the source language of each node, "o" to toggle the query editor, and press <Enter> to jump to the node under the cursor - in the source buffer. + in the source buffer. Folding also works (try |zo|, |zc|, etc.). Can also be shown with `:InspectTree`. *:InspectTree* Parameters: ~ - • {opts} (table|nil) Optional options table with the following possible + • {opts} (`table?`) Optional options table with the following possible keys: • lang (string|nil): The language of the source buffer. If - omitted, the filetype of the source buffer is used. + omitted, detect from the filetype of the source buffer. • bufnr (integer|nil): Buffer to draw the tree into. If omitted, a new buffer is created. • winid (integer|nil): Window id to display the tree buffer @@ -722,33 +846,33 @@ is_ancestor({dest}, {source}) *vim.treesitter.is_ancestor()* Determines whether a node is the ancestor of another Parameters: ~ - • {dest} |TSNode| Possible ancestor - • {source} |TSNode| Possible descendant + • {dest} (`TSNode`) Possible ancestor + • {source} (`TSNode`) Possible descendant Return: ~ - (boolean) True if {dest} is an ancestor of {source} + (`boolean`) True if {dest} is an ancestor of {source} *vim.treesitter.is_in_node_range()* is_in_node_range({node}, {line}, {col}) Determines whether (line, col) position is in node range Parameters: ~ - • {node} |TSNode| defining the range - • {line} (integer) Line (0-based) - • {col} (integer) Column (0-based) + • {node} (`TSNode`) defining the range + • {line} (`integer`) Line (0-based) + • {col} (`integer`) Column (0-based) Return: ~ - (boolean) True if the position is in node range + (`boolean`) True if the position is in node range node_contains({node}, {range}) *vim.treesitter.node_contains()* Determines if a node contains a range Parameters: ~ - • {node} |TSNode| - • {range} (table) + • {node} (`TSNode`) + • {range} (`table`) Return: ~ - (boolean) True if the {node} contains the {range} + (`boolean`) True if the {node} contains the {range} start({bufnr}, {lang}) *vim.treesitter.start()* Starts treesitter highlighting for a buffer @@ -769,16 +893,16 @@ start({bufnr}, {lang}) *vim.treesitter.start()* < Parameters: ~ - • {bufnr} (integer|nil) Buffer to be highlighted (default: current + • {bufnr} (`integer?`) Buffer to be highlighted (default: current buffer) - • {lang} (string|nil) Language of the parser (default: buffer + • {lang} (`string?`) Language of the parser (default: from buffer filetype) stop({bufnr}) *vim.treesitter.stop()* Stops treesitter highlighting for a buffer Parameters: ~ - • {bufnr} (integer|nil) Buffer to stop highlighting (default: current + • {bufnr} (`integer?`) Buffer to stop highlighting (default: current buffer) @@ -792,29 +916,30 @@ add({lang}, {opts}) *vim.treesitter.language.add()* {path} Parameters: ~ - • {lang} (string) Name of the parser (alphanumerical and `_` only) - • {opts} (table|nil) Options: - • filetype (string|string[]) Default filetype the parser - should be associated with. Defaults to {lang}. - • path (string|nil) Optional path the parser is located at - • symbol_name (string|nil) Internal symbol name for the + • {lang} (`string`) Name of the parser (alphanumerical and `_` only) + • {opts} (`table?`) Options: + • {filetype}? (`string|string[]`, default: {lang}) Default + filetype the parser should be associated with. + • {path}? (`string`) Optional path the parser is located at + • {symbol_name}? (`string`) Internal symbol name for the language to load get_filetypes({lang}) *vim.treesitter.language.get_filetypes()* Get the filetypes associated with the parser named {lang}. Parameters: ~ - • {lang} (string) Name of parser + • {lang} (`string`) Name of parser Return: ~ - string[] filetypes + (`string[]`) filetypes get_lang({filetype}) *vim.treesitter.language.get_lang()* + Parameters: ~ - • {filetype} (string) + • {filetype} (`string`) Return: ~ - (string|nil) + (`string?`) inspect({lang}) *vim.treesitter.language.inspect()* Inspects the provided language. @@ -823,55 +948,70 @@ inspect({lang}) *vim.treesitter.language.inspect()* names, ... Parameters: ~ - • {lang} (string) Language + • {lang} (`string`) Language Return: ~ - (table) + (`table`) register({lang}, {filetype}) *vim.treesitter.language.register()* Register a parser named {lang} to be used for {filetype}(s). + Note: this adds or overrides the mapping for {filetype}, any existing + mappings from other filetypes to {lang} will be preserved. + Parameters: ~ - • {lang} (string) Name of parser - • {filetype} string|string[] Filetype(s) to associate with lang + • {lang} (`string`) Name of parser + • {filetype} (`string|string[]`) Filetype(s) to associate with lang ============================================================================== Lua module: vim.treesitter.query *lua-treesitter-query* *vim.treesitter.query.add_directive()* -add_directive({name}, {handler}, {force}) +add_directive({name}, {handler}, {opts}) Adds a new directive to be used in queries Handlers can set match level data by setting directly on the metadata - object `metadata.key = value`, additionally, handlers can set node level + object `metadata.key = value`. Additionally, handlers can set node level data by using the capture id on the metadata table `metadata[capture_id].key = value` Parameters: ~ - • {name} (string) Name of the directive, without leading # - • {handler} function(match:table<string,|TSNode|>, pattern:string, - bufnr:integer, predicate:string[], metadata:table) - • match: see |treesitter-query| - • node-level data are accessible via `match[capture_id]` - - • pattern: see |treesitter-query| + • {name} (`string`) Name of the directive, without leading # + • {handler} (`function`) + • match: A table mapping capture IDs to a list of captured + nodes + • pattern: the index of the matching pattern in the query + file • predicate: list of strings containing the full directive being called, e.g. `(node (#set! conceal "-"))` would get the predicate `{ "#set!", "conceal", "-" }` - • {force} (boolean|nil) + • {opts} (`table<string, any>`) Optional options: + • force (boolean): Override an existing predicate of the + same name + • all (boolean): Use the correct implementation of the + match table where capture IDs map to a list of nodes + instead of a single node. Defaults to false (for backward + compatibility). This option will eventually become the + default and removed. *vim.treesitter.query.add_predicate()* -add_predicate({name}, {handler}, {force}) +add_predicate({name}, {handler}, {opts}) Adds a new predicate to be used in queries Parameters: ~ - • {name} (string) Name of the predicate, without leading # - • {handler} function(match:table<string,|TSNode|>, pattern:string, - bufnr:integer, predicate:string[]) + • {name} (`string`) Name of the predicate, without leading # + • {handler} (`function`) • see |vim.treesitter.query.add_directive()| for argument meanings - • {force} (boolean|nil) + • {opts} (`table<string, any>`) Optional options: + • force (boolean): Override an existing predicate of the + same name + • all (boolean): Use the correct implementation of the + match table where capture IDs map to a list of nodes + instead of a single node. Defaults to false (for backward + compatibility). This option will eventually become the + default and removed. edit({lang}) *vim.treesitter.query.edit()* Opens a live editor to query the buffer you started from. @@ -884,31 +1024,33 @@ edit({lang}) *vim.treesitter.query.edit()* `$VIMRUNTIME/queries/`. Parameters: ~ - • {lang} (string|nil) language to open the query editor for. If - omitted, inferred from the current buffer's filetype. + • {lang} (`string?`) language to open the query editor for. If omitted, + inferred from the current buffer's filetype. get({lang}, {query_name}) *vim.treesitter.query.get()* Returns the runtime query {query_name} for {lang}. Parameters: ~ - • {lang} (string) Language to use for the query - • {query_name} (string) Name of the query (e.g. "highlights") + • {lang} (`string`) Language to use for the query + • {query_name} (`string`) Name of the query (e.g. "highlights") Return: ~ - Query|nil Parsed query + (`vim.treesitter.Query?`) Parsed query. `nil` if no query files are + found. *vim.treesitter.query.get_files()* get_files({lang}, {query_name}, {is_included}) Gets the list of files used to make up a query Parameters: ~ - • {lang} (string) Language to get query for - • {query_name} (string) Name of the query to load (e.g., "highlights") - • {is_included} (boolean|nil) Internal parameter, most of the time left + • {lang} (`string`) Language to get query for + • {query_name} (`string`) Name of the query to load (e.g., + "highlights") + • {is_included} (`boolean?`) Internal parameter, most of the time left as `nil` Return: ~ - string[] query_files List of files to load for given query and + (`string[]`) query_files List of files to load for given query and language lint({buf}, {opts}) *vim.treesitter.query.lint()* @@ -916,34 +1058,34 @@ lint({buf}, {opts}) *vim.treesitter.query.lint()* Use |treesitter-parsers| in runtimepath to check the query file in {buf} for errors: - • verify that used nodes are valid identifiers in the grammar. • verify that predicates and directives are valid. • verify that top-level s-expressions are valid. The found diagnostics are reported using |diagnostic-api|. By default, the parser used for verification is determined by the containing folder of the - query file, e.g., if the path ends in `/lua/highlights.scm` , the parser for the `lua` language will be used. + query file, e.g., if the path ends in `/lua/highlights.scm`, the parser + for the `lua` language will be used. Parameters: ~ - • {buf} (integer) Buffer handle - • {opts} (QueryLinterOpts|nil) Optional keyword arguments: - • langs (string|string[]|nil) Language(s) to use for checking + • {buf} (`integer`) Buffer handle + • {opts} (`table?`) Optional keyword arguments: + • {langs}? (`string|string[]`) Language(s) to use for checking the query. If multiple languages are specified, queries are validated for all of them - • clear (boolean) if `true`, just clear current lint errors + • {clear} (`boolean`) Just clear current lint errors list_directives() *vim.treesitter.query.list_directives()* Lists the currently available directives to use in queries. Return: ~ - string[] List of supported directives. + (`string[]`) List of supported directives. list_predicates() *vim.treesitter.query.list_predicates()* Lists the currently available predicates to use in queries. Return: ~ - string[] List of supported predicates. + (`string[]`) List of supported predicates. omnifunc({findstart}, {base}) *vim.treesitter.query.omnifunc()* Omnifunc for completing node names and predicates in treesitter queries. @@ -952,24 +1094,32 @@ omnifunc({findstart}, {base}) *vim.treesitter.query.omnifunc()* vim.bo.omnifunc = 'v:lua.vim.treesitter.query.omnifunc' < + Parameters: ~ + • {findstart} (`0|1`) + • {base} (`string`) + parse({lang}, {query}) *vim.treesitter.query.parse()* Parse {query} as a string. (If the query is in a file, the caller should read the contents into a string before calling). - Returns a `Query` (see |lua-treesitter-query|) object which can be used to search nodes in - the syntax tree for the patterns defined in {query} using `iter_*` methods below. + Returns a `Query` (see |lua-treesitter-query|) object which can be used to + search nodes in the syntax tree for the patterns defined in {query} using + the `iter_captures` and `iter_matches` methods. Exposes `info` and `captures` with additional context about {query}. • `captures` contains the list of unique capture names defined in {query}. - -`info.captures` also points to `captures`. + • `info.captures` also points to `captures`. • `info.patterns` contains information about predicates. Parameters: ~ - • {lang} (string) Language to use for the query - • {query} (string) Query in s-expr syntax + • {lang} (`string`) Language to use for the query + • {query} (`string`) Query in s-expr syntax Return: ~ - Query Parsed query + (`vim.treesitter.Query`) Parsed query + + See also: ~ + • |vim.treesitter.query.get()| *Query:iter_captures()* Query:iter_captures({node}, {source}, {start}, {stop}) @@ -995,15 +1145,17 @@ Query:iter_captures({node}, {source}, {start}, {stop}) < Parameters: ~ - • {node} |TSNode| under which the search will occur - • {source} (integer|string) Source buffer or string to extract text + • {node} (`TSNode`) under which the search will occur + • {source} (`integer|string`) Source buffer or string to extract text from - • {start} (integer) Starting line for the search - • {stop} (integer) Stopping line for the search (end-exclusive) + • {start} (`integer?`) Starting line for the search. Defaults to + `node:start()`. + • {stop} (`integer?`) Stopping line for the search (end-exclusive). + Defaults to `node:end_()`. Return: ~ - (fun(end_line: integer|nil): integer, TSNode, TSMetadata): capture id, - capture node, metadata + (`fun(end_line: integer?): integer, TSNode, vim.treesitter.query.TSMetadata`) + capture id, capture node, metadata *Query:iter_matches()* Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) @@ -1012,35 +1164,48 @@ Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) Iterate over all matches within a {node}. The arguments are the same as for |Query:iter_captures()| but the iterated values are different: an (1-based) index of the pattern in the query, a table mapping capture - indices to nodes, and metadata from any directives processing the match. - If the query has more than one pattern, the capture table might be sparse - and e.g. `pairs()` method should be used over `ipairs`. Here is an example - iterating over all captures in every match: >lua - for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do - for id, node in pairs(match) do - local name = query.captures[id] - -- `node` was captured by the `name` capture in the match + indices to a list of nodes, and metadata from any directives processing + the match. + + WARNING: Set `all=true` to ensure all matching nodes in a match are + returned, otherwise only the last node in a match is returned, breaking + captures involving quantifiers such as `(comment)+ @comment`. The default + option `all=false` is only provided for backward compatibility and will be + removed after Nvim 0.10. - local node_data = metadata[id] -- Node level metadata + Example: >lua + for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, 0, -1, { all = true }) do + for id, nodes in pairs(match) do + local name = query.captures[id] + for _, node in ipairs(nodes) do + -- `node` was captured by the `name` capture in the match - -- ... use the info here ... + local node_data = metadata[id] -- Node level metadata + ... use the info here ... + end end end < Parameters: ~ - • {node} |TSNode| under which the search will occur - • {source} (integer|string) Source buffer or string to search - • {start} (integer) Starting line for the search - • {stop} (integer) Stopping line for the search (end-exclusive) - • {opts} (table|nil) Options: + • {node} (`TSNode`) under which the search will occur + • {source} (`integer|string`) Source buffer or string to search + • {start} (`integer?`) Starting line for the search. Defaults to + `node:start()`. + • {stop} (`integer?`) Stopping line for the search (end-exclusive). + Defaults to `node:end_()`. + • {opts} (`table?`) Optional keyword arguments: • max_start_depth (integer) if non-zero, sets the maximum start depth for each match. This is used to prevent - traversing too deep into a tree. Requires treesitter >= - 0.20.9. + traversing too deep into a tree. + • all (boolean) When set, the returned match table maps + capture IDs to a list of nodes. Older versions of + iter_matches incorrectly mapped capture IDs to a single + node, which is incorrect behavior. This option will + eventually become the default and removed. Return: ~ - (fun(): integer, table<integer,TSNode>, table): pattern id, match, + (`fun(): integer, table<integer, TSNode[]>, table`) pattern id, match, metadata set({lang}, {query_name}, {text}) *vim.treesitter.query.set()* @@ -1050,49 +1215,44 @@ set({lang}, {query_name}, {text}) *vim.treesitter.query.set()* by plugins. Parameters: ~ - • {lang} (string) Language to use for the query - • {query_name} (string) Name of the query (e.g., "highlights") - • {text} (string) Query text (unparsed). + • {lang} (`string`) Language to use for the query + • {query_name} (`string`) Name of the query (e.g., "highlights") + • {text} (`string`) Query text (unparsed). ============================================================================== Lua module: vim.treesitter.languagetree *lua-treesitter-languagetree* - -A *LanguageTree* contains a tree of parsers: the root treesitter parser -for {lang} and any "injected" language parsers, which themselves may -inject other languages, recursively. For example a Lua buffer containing -some Vimscript commands needs multiple parsers to fully understand its -contents. +A *LanguageTree* contains a tree of parsers: the root treesitter parser for +{lang} and any "injected" language parsers, which themselves may inject other +languages, recursively. For example a Lua buffer containing some Vimscript +commands needs multiple parsers to fully understand its contents. To create a LanguageTree (parser object) for a given buffer and language, use: >lua local parser = vim.treesitter.get_parser(bufnr, lang) - < -(where `bufnr=0` means current buffer). `lang` defaults to 'filetype'. -Note: currently the parser is retained for the lifetime of a buffer but -this may change; a plugin should keep a reference to the parser object if -it wants incremental updates. +(where `bufnr=0` means current buffer). `lang` defaults to 'filetype'. Note: +currently the parser is retained for the lifetime of a buffer but this may +change; a plugin should keep a reference to the parser object if it wants +incremental updates. Whenever you need to access the current syntax tree, parse the buffer: >lua local tree = parser:parse({ start_row, end_row }) - < -This returns a table of immutable |treesitter-tree| objects representing -the current state of the buffer. When the plugin wants to access the state -after a (possible) edit it must call `parse()` again. If the buffer wasn't -edited, the same tree will be returned again without extra work. If the -buffer was parsed before, incremental parsing will be done of the changed -parts. +This returns a table of immutable |treesitter-tree| objects representing the +current state of the buffer. When the plugin wants to access the state after a +(possible) edit it must call `parse()` again. If the buffer wasn't edited, the +same tree will be returned again without extra work. If the buffer was parsed +before, incremental parsing will be done of the changed parts. + +Note: To use the parser directly inside a |nvim_buf_attach()| Lua callback, +you must call |vim.treesitter.get_parser()| before you register your callback. +But preferably parsing shouldn't be done directly in the change callback +anyway as they will be very frequent. Rather a plugin that does any kind of +analysis on a tree should use a timer to throttle too frequent updates. -Note: To use the parser directly inside a |nvim_buf_attach()| Lua -callback, you must call |vim.treesitter.get_parser()| before you register -your callback. But preferably parsing shouldn't be done directly in the -change callback anyway as they will be very frequent. Rather a plugin that -does any kind of analysis on a tree should use a timer to throttle too -frequent updates. LanguageTree:children() *LanguageTree:children()* Returns a map of language to child tree. @@ -1101,10 +1261,10 @@ LanguageTree:contains({range}) *LanguageTree:contains()* Determines whether {range} is contained in the |LanguageTree|. Parameters: ~ - • {range} (table) `{ start_line, start_col, end_line, end_col }` + • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }` Return: ~ - (boolean) + (`boolean`) LanguageTree:destroy() *LanguageTree:destroy()* Destroys this |LanguageTree| and all its children. @@ -1120,32 +1280,33 @@ LanguageTree:for_each_tree({fn}) *LanguageTree:for_each_tree()* Note: This includes the invoking tree's child trees as well. Parameters: ~ - • {fn} fun(tree: TSTree, ltree: LanguageTree) + • {fn} (`fun(tree: TSTree, ltree: vim.treesitter.LanguageTree)`) LanguageTree:included_regions() *LanguageTree:included_regions()* - Gets the set of included regions managed by this LanguageTree . This can be different from the regions set by injection query, because a - partial |LanguageTree:parse()| drops the regions outside the requested - range. + Gets the set of included regions managed by this LanguageTree. This can be + different from the regions set by injection query, because a partial + |LanguageTree:parse()| drops the regions outside the requested range. Return: ~ - table<integer, Range6[]> + (`table<integer, Range6[]>`) LanguageTree:invalidate({reload}) *LanguageTree:invalidate()* Invalidates this parser and all its children Parameters: ~ - • {reload} (boolean|nil) + • {reload} (`boolean?`) LanguageTree:is_valid({exclude_children}) *LanguageTree:is_valid()* - Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()| reflects the latest state of the - source. If invalid, user should call |LanguageTree:parse()|. + Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()| + reflects the latest state of the source. If invalid, user should call + |LanguageTree:parse()|. Parameters: ~ - • {exclude_children} (boolean|nil) whether to ignore the validity of + • {exclude_children} (`boolean?`) whether to ignore the validity of children (default `false`) Return: ~ - (boolean) + (`boolean`) LanguageTree:lang() *LanguageTree:lang()* Gets the language of this tree node. @@ -1155,23 +1316,23 @@ LanguageTree:language_for_range({range}) Gets the appropriate language that contains {range}. Parameters: ~ - • {range} (table) `{ start_line, start_col, end_line, end_col }` + • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }` Return: ~ - |LanguageTree| Managing {range} + (`vim.treesitter.LanguageTree`) Managing {range} *LanguageTree:named_node_for_range()* LanguageTree:named_node_for_range({range}, {opts}) Gets the smallest named node that contains {range}. Parameters: ~ - • {range} (table) `{ start_line, start_col, end_line, end_col }` - • {opts} (table|nil) Optional keyword arguments: + • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }` + • {opts} (`table?`) Optional keyword arguments: • ignore_injections boolean Ignore injected languages (default true) Return: ~ - |TSNode| | nil Found node + (`TSNode?`) Found node LanguageTree:parse({range}) *LanguageTree:parse()* Recursively parse all regions in the language tree using @@ -1184,23 +1345,24 @@ LanguageTree:parse({range}) *LanguageTree:parse()* if {range} is `true`). Parameters: ~ - • {range} boolean|Range|nil: Parse this range in the parser's source. + • {range} (`boolean|Range?`) Parse this range in the parser's source. Set to `true` to run a complete parse of the source (Note: Can be slow!) Set to `false|nil` to only parse regions with empty ranges (typically only the root tree without injections). Return: ~ - table<integer, TSTree> + (`table<integer, TSTree>`) *LanguageTree:register_cbs()* LanguageTree:register_cbs({cbs}, {recursive}) Registers callbacks for the |LanguageTree|. Parameters: ~ - • {cbs} (table) An |nvim_buf_attach()|-like table argument with + • {cbs} (`table`) An |nvim_buf_attach()|-like table argument with the following handlers: - • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback. + • `on_bytes` : see |nvim_buf_attach()|, but this will be + called after the parsers callback. • `on_changedtree` : a callback that will be called every time the tree has syntactical changes. It will be passed two arguments: a table of the ranges (as node @@ -1212,7 +1374,7 @@ LanguageTree:register_cbs({cbs}, {recursive}) • `on_detach` : emitted when the buffer is detached, see |nvim_buf_detach_event|. Takes one argument, the number of the buffer. - • {recursive} (boolean|nil) Apply callbacks recursively for all + • {recursive} (`boolean?`) Apply callbacks recursively for all children. Any new children will also inherit the callbacks. @@ -1224,21 +1386,23 @@ LanguageTree:tree_for_range({range}, {opts}) Gets the tree that contains {range}. Parameters: ~ - • {range} (table) `{ start_line, start_col, end_line, end_col }` - • {opts} (table|nil) Optional keyword arguments: + • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }` + • {opts} (`table?`) Optional keyword arguments: • ignore_injections boolean Ignore injected languages (default true) Return: ~ - TSTree|nil + (`TSTree?`) LanguageTree:trees() *LanguageTree:trees()* Returns all trees of the regions parsed by this parser. Does not include child languages. The result is list-like if - • this LanguageTree is the root, in which case the result is empty or a singleton list; or + • this LanguageTree is the root, in which case the result is empty or a + singleton list; or • the root LanguageTree is fully parsed. Return: ~ - table<integer, TSTree> + (`table<integer, TSTree>`) + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index ab99b0446f..b8d47923ca 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -26,12 +26,12 @@ with these (optional) keys: *ui-rgb* - `rgb` Decides the color format. - - true: (default) 24-bit RGB colors - - false: Terminal colors (8-bit, max 256) + - true: (default) 24-bit RGB colors + - false: Terminal colors (8-bit, max 256) *ui-override* - `override` Decides how UI capabilities are resolved. - - true: Enable requested UI capabilities, even if not + - true: Enable requested UI capabilities, even if not supported by all connected UIs (including |TUI|). - false: (default) Disable UI capabilities not supported by all connected UIs (including TUI). @@ -138,7 +138,7 @@ procedure: to set |g:| variables visible to init.vim 3. If the UI wants to do additional setup after user config is loaded, - register a VimEnter autocmd: >vim + register a VimEnter autocmd: >lua nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')") 4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now: @@ -188,7 +188,7 @@ the editor. `attr_id`: Cursor attribute id (defined by `hl_attr_define`). When attr_id is 0, the background and foreground colors should be swapped. - `attr_id_lm`: Cursor attribute id for when 'langmap' is active. + `attr_id_lm`: Cursor attribute id for when |:lmap| is on. `short_name`: Mode code name, see 'guicursor'. `name`: Mode descriptive name. `mouse_shape`: (To be implemented.) @@ -228,6 +228,10 @@ the editor. however a UI might still use such options when rendering raw text sent from Nvim, like for |ui-cmdline|. +["chdir", path] ~ + The |current-directory| of the embedded Nvim process changed to + `path`. + ["mode_change", mode, mode_idx] ~ Editor mode changed. The `mode` parameter is a string representing the current mode. `mode_idx` is an index into the array emitted in @@ -324,9 +328,11 @@ numerical highlight ids to the actual attributes. `underdotted`: underdotted text. The dots have `special` color. `underdashed`: underdashed text. The dashes have `special` color. `altfont`: alternative font. - `blend`: Blend level (0-100). Could be used by UIs to + `blend`: blend level (0-100). Could be used by UIs to support blending floating windows to the background or to signal a transparent cursor. + `url`: a URL associated with this highlight. UIs can + display this URL however they wish. For absent color keys the default color should be used. Don't store the default value in the table, rather a sentinel value, so that @@ -555,7 +561,7 @@ with the following possible keys: `kind`: always present. One of the following values: "ui": Builtin UI highlight. |highlight-groups| "syntax": Highlight applied to a buffer by a syntax declaration or - other runtime/plugin functionality such as + other runtime/plugin functionality such as |nvim_buf_add_highlight()| "terminal": highlight from a process running in a |terminal-emulator|. Contains no further semantic information. diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index e206a804f4..56750420e9 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -610,10 +610,13 @@ String manipulation: *string-functions* toupper() turn a string to uppercase charclass() class of a character match() position where a pattern matches in a string + matchbufline() all the matches of a pattern in a buffer matchend() position where a pattern match ends in a string matchfuzzy() fuzzy matches a string in a list of strings matchfuzzypos() fuzzy matches a string in a list of strings matchstr() match of a pattern in a string + matchstrlist() all the matches of a pattern in a List of + strings matchstrpos() match and positions of a pattern in a string matchlist() like matchstr() and also return submatches stridx() first index of a short string in a long string @@ -662,6 +665,7 @@ List manipulation: *list-functions* filter() remove selected items from a List map() change each List item mapnew() make a new List with changed items + foreach() apply function to List items reduce() reduce a List to a value slice() take a slice of a List sort() sort a List @@ -693,6 +697,7 @@ Dictionary manipulation: *dict-functions* filter() remove selected entries from a Dictionary map() change each Dictionary entry mapnew() make a new Dictionary with changed items + foreach() apply function to Dictionary items keys() get List of Dictionary keys values() get List of Dictionary values items() get List of Dictionary key-value pairs @@ -788,6 +793,7 @@ Cursor and mark position: *cursor-functions* *mark-functions* Working with text in the current buffer: *text-functions* getline() get a line or list of lines from the buffer + getregion() get a region of text from the buffer setline() replace a line in the buffer append() append line or list of lines in the buffer indent() indent of a specific line diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index cf9b3cf0e5..b0caf9fdaf 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -30,6 +30,11 @@ Defaults *nvim-defaults* ":filetype off" to |init.vim|. - Syntax highlighting is enabled by default. This can be disabled by adding ":syntax off" to |init.vim|. +- Default color scheme has been updated. This can result in color schemes + looking differently due to them relying on how highlight groups are defined + by default. Add ":colorscheme vim" to |init.vim| or + ":source $VIMRUNTIME/colors/vim.lua" to your color scheme file to restore + the old default links and colors. - 'autoindent' is enabled - 'autoread' is enabled (works in all UIs, including terminal) @@ -73,6 +78,8 @@ Defaults *nvim-defaults* - 'switchbuf' defaults to "uselast" - 'tabpagemax' defaults to 50 - 'tags' defaults to "./tags;,tags" +- 'termguicolors' is enabled by default if Nvim can detect support from the + host terminal - 'ttimeoutlen' defaults to 50 - 'ttyfast' is always set - 'undodir' defaults to ~/.local/state/nvim/undo// (|xdg|), auto-created @@ -122,6 +129,8 @@ of these in your config by simply removing the mapping, e.g. ":unmap Y". - <C-W> |i_CTRL-W-default| - <C-L> |CTRL-L-default| - & |&-default| +- Q |v_Q-default| +- @ |v_@-default| - # |v_#-default| - * |v_star-default| - Nvim LSP client defaults |lsp-defaults| @@ -136,6 +145,12 @@ nvim_terminal: - BufReadCmd: Treats "term://" buffers as |terminal| buffers. |terminal-start| - TermClose: A |terminal| buffer started with no arguments (which thus uses 'shell') and which exits with no error is closed automatically. +- TermRequest: The terminal emulator responds to OSC background and foreground + requests, indicating (1) a black background and white foreground when Nvim + option 'background' is "dark" or (2) a white background and black foreground + when 'background' is "light". While this may not reflect the actual + foreground/background color, it permits 'background' to be retained for a + nested Nvim instance running in the terminal emulator. nvim_cmdwin: - CmdwinEnter: Limits syntax sync to maxlines=1 in the |cmdwin|. @@ -312,7 +327,8 @@ Options: 'shortmess' "F" flag does not affect output from autocommands 'signcolumn' supports up to 9 dynamic/fixed columns 'statuscolumn' full control of columns using 'statusline' format - 'tabline' %@Func@foo%X can call any function on mouse-click + 'tabline' middle-click on tabpage label closes tabpage, + and %@Func@foo%X can call any function on mouse-click 'termpastefilter' 'ttimeout', 'ttimeoutlen' behavior was simplified 'winblend' pseudo-transparency in floating windows |api-floatwin| @@ -566,6 +582,9 @@ Autocommands: - |TermResponse| is fired for any OSC sequence received from the terminal, instead of the Primary Device Attributes response. |v:termresponse| +Options: +- |shm-q| fully hides macro recording message instead of only shortening it. + ============================================================================== Missing features *nvim-missing* @@ -616,6 +635,7 @@ Commands: :lcscope :scscope :Vimuntar + The old `:TOhtml`, replaced by a Lua version (contains many differences) Compile-time features: Emacs tags support @@ -666,7 +686,7 @@ Options: bioskey (MS-DOS) conskey (MS-DOS) *'cp'* *'nocompatible'* *'nocp'* *'compatible'* (Nvim is always "nocompatible".) - 'cpoptions' (gjkHw<*- and all POSIX flags were removed) + 'cpoptions' (gjpkHw<*- and all POSIX flags were removed) *'cryptmethod'* *'cm'* *'key'* (Vim encryption implementation) cscopepathcomp cscopeprg diff --git a/runtime/doc/visual.txt b/runtime/doc/visual.txt index 0d1ea937c0..a20fb6d31e 100644 --- a/runtime/doc/visual.txt +++ b/runtime/doc/visual.txt @@ -366,6 +366,20 @@ one of the last commands to extend the highlighted text, the repeating will be applied up to the rightmost column of the longest line. Any count passed to the `.` command is not used. +Visual mode |default-mappings| "@" and "Q" can repeat commands in a register +for all selected lines. See |v_@-default| and |v_Q-default| for details. For +example, given the text: + + 123(hello)321 + 456(world)654 + 456(NOT THIS)654 + +With register "x" containing the commands `yi(VP`, Visually selecting the +first two lines and typing `@x` produces: + + hello + world + 456(NOT THIS)654 ============================================================================== 7. Examples *visual-examples* diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt new file mode 100644 index 0000000000..e71e31abf8 --- /dev/null +++ b/runtime/doc/vvars.txt @@ -0,0 +1,735 @@ +*vvars.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Predefined variables *vvars* + +Some variables can be set by the user, but the type cannot be changed. + + Type |gO| to see the table of contents. + + *v:argv* *argv-variable* +v:argv + The command line arguments Vim was invoked with. This is a + list of strings. The first item is the Vim command. + See |v:progpath| for the command with full path. + + *v:char* *char-variable* +v:char + Argument for evaluating 'formatexpr' and used for the typed + character when using <expr> in an abbreviation |:map-<expr>|. + It is also used by the |InsertCharPre| and |InsertEnter| events. + + *v:charconvert_from* *charconvert_from-variable* +v:charconvert_from + The name of the character encoding of a file to be converted. + Only valid while evaluating the 'charconvert' option. + + *v:charconvert_to* *charconvert_to-variable* +v:charconvert_to + The name of the character encoding of a file after conversion. + Only valid while evaluating the 'charconvert' option. + + *v:cmdarg* *cmdarg-variable* +v:cmdarg + The extra arguments ("++p", "++enc=", "++ff=") given to a file + read/write command. This is set before an autocommand event + for a file read/write command is triggered. There is a + leading space to make it possible to append this variable + directly after the read/write command. Note: "+cmd" isn't + included here, because it will be executed anyway. + + *v:cmdbang* *cmdbang-variable* +v:cmdbang + Set like v:cmdarg for a file read/write command. When a "!" + was used the value is 1, otherwise it is 0. Note that this + can only be used in autocommands. For user commands |<bang>| + can be used. + + *v:collate* *collate-variable* +v:collate + The current locale setting for collation order of the runtime + environment. This allows Vim scripts to be aware of the + current locale encoding. Technical: it's the value of + LC_COLLATE. When not using a locale the value is "C". + This variable can not be set directly, use the |:language| + command. + See |multi-lang|. + + *v:completed_item* *completed_item-variable* +v:completed_item + Dictionary containing the most recent |complete-items| after + |CompleteDone|. Empty if the completion failed, or after + leaving and re-entering insert mode. + Note: Plugins can modify the value to emulate the builtin + |CompleteDone| event behavior. + + *v:count* *count-variable* +v:count + The count given for the last Normal mode command. Can be used + to get the count before a mapping. Read-only. Example: >vim + :map _x :<C-U>echo "the count is " .. v:count<CR> +< + Note: The <C-U> is required to remove the line range that you + get when typing ':' after a count. + When there are two counts, as in "3d2w", they are multiplied, + just like what happens in the command, "d6w" for the example. + Also used for evaluating the 'formatexpr' option. + + *v:count1* *count1-variable* +v:count1 + Just like "v:count", but defaults to one when no count is + used. + + *v:ctype* *ctype-variable* +v:ctype + The current locale setting for characters of the runtime + environment. This allows Vim scripts to be aware of the + current locale encoding. Technical: it's the value of + LC_CTYPE. When not using a locale the value is "C". + This variable can not be set directly, use the |:language| + command. + See |multi-lang|. + + *v:dying* *dying-variable* +v:dying + Normally zero. When a deadly signal is caught it's set to + one. When multiple signals are caught the number increases. + Can be used in an autocommand to check if Vim didn't + terminate normally. + Example: >vim + :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif +< + Note: if another deadly signal is caught when v:dying is one, + VimLeave autocommands will not be executed. + + *v:echospace* *echospace-variable* +v:echospace + Number of screen cells that can be used for an `:echo` message + in the last screen line before causing the |hit-enter-prompt|. + Depends on 'showcmd', 'ruler' and 'columns'. You need to + check 'cmdheight' for whether there are full-width lines + available above the last line. + + *v:errmsg* *errmsg-variable* +v:errmsg + Last given error message. + Modifiable (can be set). + Example: >vim + let v:errmsg = "" + silent! next + if v:errmsg != "" + " ... handle error +< + + *v:errors* *errors-variable* *assert-return* +v:errors + Errors found by assert functions, such as |assert_true()|. + This is a list of strings. + The assert functions append an item when an assert fails. + The return value indicates this: a one is returned if an item + was added to v:errors, otherwise zero is returned. + To remove old results make it empty: >vim + let v:errors = [] +< + If v:errors is set to anything but a list it is made an empty + list by the assert function. + + *v:event* *event-variable* +v:event + Dictionary of event data for the current |autocommand|. Valid + only during the event lifetime; storing or passing v:event is + invalid! Copy it instead: >vim + au TextYankPost * let g:foo = deepcopy(v:event) +< + Keys vary by event; see the documentation for the specific + event, e.g. |DirChanged| or |TextYankPost|. + KEY DESCRIPTION ~ + abort Whether the event triggered during + an aborting condition (e.g. |c_Esc| or + |c_CTRL-C| for |CmdlineLeave|). + chan |channel-id| + cmdlevel Level of cmdline. + cmdtype Type of cmdline, |cmdline-char|. + cwd Current working directory. + inclusive Motion is |inclusive|, else exclusive. + scope Event-specific scope name. + operator Current |operator|. Also set for Ex + commands (unlike |v:operator|). For + example if |TextYankPost| is triggered + by the |:yank| Ex command then + `v:event.operator` is "y". + regcontents Text stored in the register as a + |readfile()|-style list of lines. + regname Requested register (e.g "x" for "xyy) + or the empty string for an unnamed + operation. + regtype Type of register as returned by + |getregtype()|. + visual Selection is visual (as opposed to, + e.g., via motion). + completed_item Current selected complete item on + |CompleteChanged|, Is `{}` when no complete + item selected. + height Height of popup menu on |CompleteChanged| + width Width of popup menu on |CompleteChanged| + row Row count of popup menu on |CompleteChanged|, + relative to screen. + col Col count of popup menu on |CompleteChanged|, + relative to screen. + size Total number of completion items on + |CompleteChanged|. + scrollbar Is |v:true| if popup menu have scrollbar, or + |v:false| if not. + changed_window Is |v:true| if the event fired while + changing window (or tab) on |DirChanged|. + status Job status or exit code, -1 means "unknown". |TermClose| + + *v:exception* *exception-variable* +v:exception + The value of the exception most recently caught and not + finished. See also |v:throwpoint| and |throw-variables|. + Example: >vim + try + throw "oops" + catch /.*/ + echo "caught " .. v:exception + endtry +< + Output: "caught oops". + + *v:exiting* *exiting-variable* +v:exiting + Exit code, or |v:null| before invoking the |VimLeavePre| + and |VimLeave| autocmds. See |:q|, |:x| and |:cquit|. + Example: >vim + :au VimLeave * echo "Exit value is " .. v:exiting +< + + *v:false* *false-variable* +v:false + Special value used to put "false" in JSON and msgpack. See + |json_encode()|. This value is converted to "v:false" when used + as a String (e.g. in |expr5| with string concatenation + operator) and to zero when used as a Number (e.g. in |expr5| + or |expr7| when used with numeric operators). Read-only. + + *v:fcs_choice* *fcs_choice-variable* +v:fcs_choice + What should happen after a |FileChangedShell| event was + triggered. Can be used in an autocommand to tell Vim what to + do with the affected buffer: + reload Reload the buffer (does not work if + the file was deleted). + edit Reload the buffer and detect the + values for options such as + 'fileformat', 'fileencoding', 'binary' + (does not work if the file was + deleted). + ask Ask the user what to do, as if there + was no autocommand. Except that when + only the timestamp changed nothing + will happen. + <empty> Nothing, the autocommand should do + everything that needs to be done. + The default is empty. If another (invalid) value is used then + Vim behaves like it is empty, there is no warning message. + + *v:fcs_reason* *fcs_reason-variable* +v:fcs_reason + The reason why the |FileChangedShell| event was triggered. + Can be used in an autocommand to decide what to do and/or what + to set v:fcs_choice to. Possible values: + deleted file no longer exists + conflict file contents, mode or timestamp was + changed and buffer is modified + changed file contents has changed + mode mode of file changed + time only file timestamp changed + + *v:fname* *fname-variable* +v:fname + When evaluating 'includeexpr': the file name that was + detected. Empty otherwise. + + *v:fname_diff* *fname_diff-variable* +v:fname_diff + The name of the diff (patch) file. Only valid while + evaluating 'patchexpr'. + + *v:fname_in* *fname_in-variable* +v:fname_in + The name of the input file. Valid while evaluating: + option used for ~ + 'charconvert' file to be converted + 'diffexpr' original file + 'patchexpr' original file + And set to the swap file name for |SwapExists|. + + *v:fname_new* *fname_new-variable* +v:fname_new + The name of the new version of the file. Only valid while + evaluating 'diffexpr'. + + *v:fname_out* *fname_out-variable* +v:fname_out + The name of the output file. Only valid while + evaluating: + option used for ~ + 'charconvert' resulting converted file [1] + 'diffexpr' output of diff + 'patchexpr' resulting patched file + [1] When doing conversion for a write command (e.g., ":w + file") it will be equal to v:fname_in. When doing conversion + for a read command (e.g., ":e file") it will be a temporary + file and different from v:fname_in. + + *v:folddashes* *folddashes-variable* +v:folddashes + Used for 'foldtext': dashes representing foldlevel of a closed + fold. + Read-only in the |sandbox|. |fold-foldtext| + + *v:foldend* *foldend-variable* +v:foldend + Used for 'foldtext': last line of closed fold. + Read-only in the |sandbox|. |fold-foldtext| + + *v:foldlevel* *foldlevel-variable* +v:foldlevel + Used for 'foldtext': foldlevel of closed fold. + Read-only in the |sandbox|. |fold-foldtext| + + *v:foldstart* *foldstart-variable* +v:foldstart + Used for 'foldtext': first line of closed fold. + Read-only in the |sandbox|. |fold-foldtext| + + *v:hlsearch* *hlsearch-variable* +v:hlsearch + Variable that indicates whether search highlighting is on. + Setting it makes sense only if 'hlsearch' is enabled. Setting + this variable to zero acts like the |:nohlsearch| command, + setting it to one acts like >vim + let &hlsearch = &hlsearch +< + Note that the value is restored when returning from a + function. |function-search-undo|. + + *v:insertmode* *insertmode-variable* +v:insertmode + Used for the |InsertEnter| and |InsertChange| autocommand + events. Values: + i Insert mode + r Replace mode + v Virtual Replace mode + + *v:key* *key-variable* +v:key + Key of the current item of a |Dictionary|. Only valid while + evaluating the expression used with |map()| and |filter()|. + Read-only. + + *v:lang* *lang-variable* +v:lang + The current locale setting for messages of the runtime + environment. This allows Vim scripts to be aware of the + current language. Technical: it's the value of LC_MESSAGES. + The value is system dependent. + This variable can not be set directly, use the |:language| + command. + It can be different from |v:ctype| when messages are desired + in a different language than what is used for character + encoding. See |multi-lang|. + + *v:lc_time* *lc_time-variable* +v:lc_time + The current locale setting for time messages of the runtime + environment. This allows Vim scripts to be aware of the + current language. Technical: it's the value of LC_TIME. + This variable can not be set directly, use the |:language| + command. See |multi-lang|. + + *v:lnum* *lnum-variable* +v:lnum + Line number for the 'foldexpr' |fold-expr|, 'formatexpr', + 'indentexpr' and 'statuscolumn' expressions, tab page number + for 'guitablabel' and 'guitabtooltip'. Only valid while one of + these expressions is being evaluated. Read-only when in the + |sandbox|. + + *v:lua* *lua-variable* +v:lua + Prefix for calling Lua functions from expressions. + See |v:lua-call| for more information. + + *v:maxcol* *maxcol-variable* +v:maxcol + Maximum line length. Depending on where it is used it can be + screen columns, characters or bytes. The value currently is + 2147483647 on all systems. + + *v:mouse_col* *mouse_col-variable* +v:mouse_col + Column number for a mouse click obtained with |getchar()|. + This is the screen column number, like with |virtcol()|. The + value is zero when there was no mouse button click. + + *v:mouse_lnum* *mouse_lnum-variable* +v:mouse_lnum + Line number for a mouse click obtained with |getchar()|. + This is the text line number, not the screen line number. The + value is zero when there was no mouse button click. + + *v:mouse_win* *mouse_win-variable* +v:mouse_win + Window number for a mouse click obtained with |getchar()|. + First window has number 1, like with |winnr()|. The value is + zero when there was no mouse button click. + + *v:mouse_winid* *mouse_winid-variable* +v:mouse_winid + |window-ID| for a mouse click obtained with |getchar()|. + The value is zero when there was no mouse button click. + + *v:msgpack_types* *msgpack_types-variable* +v:msgpack_types + Dictionary containing msgpack types used by |msgpackparse()| + and |msgpackdump()|. All types inside dictionary are fixed + (not editable) empty lists. To check whether some list is one + of msgpack types, use |is| operator. + + *v:null* *null-variable* +v:null + Special value used to put "null" in JSON and NIL in msgpack. + See |json_encode()|. This value is converted to "v:null" when + used as a String (e.g. in |expr5| with string concatenation + operator) and to zero when used as a Number (e.g. in |expr5| + or |expr7| when used with numeric operators). Read-only. + In some places `v:null` can be used for a List, Dict, etc. + that is not set. That is slightly different than an empty + List, Dict, etc. + + *v:numbermax* *numbermax-variable* +v:numbermax Maximum value of a number. + + *v:numbermin* *numbermin-variable* +v:numbermin Minimum value of a number (negative). + + *v:numbersize* *numbersize-variable* +v:numbersize + Number of bits in a Number. This is normally 64, but on some + systems it may be 32. + + *v:oldfiles* *oldfiles-variable* +v:oldfiles + List of file names that is loaded from the |shada| file on + startup. These are the files that Vim remembers marks for. + The length of the List is limited by the ' argument of the + 'shada' option (default is 100). + When the |shada| file is not used the List is empty. + Also see |:oldfiles| and |c_#<|. + The List can be modified, but this has no effect on what is + stored in the |shada| file later. If you use values other + than String this will cause trouble. + + *v:operator* *operator-variable* +v:operator + The last operator given in Normal mode. This is a single + character except for commands starting with <g> or <z>, + in which case it is two characters. Best used alongside + |v:prevcount| and |v:register|. Useful if you want to cancel + Operator-pending mode and then use the operator, e.g.: >vim + :omap O <Esc>:call MyMotion(v:operator)<CR> +< + The value remains set until another operator is entered, thus + don't expect it to be empty. + v:operator is not set for |:delete|, |:yank| or other Ex + commands. + Read-only. + + *v:option_command* *option_command-variable* +v:option_command + Command used to set the option. Valid while executing an + |OptionSet| autocommand. + value option was set via ~ + "setlocal" |:setlocal| or `:let l:xxx` + "setglobal" |:setglobal| or `:let g:xxx` + "set" |:set| or |:let| + "modeline" |modeline| + + *v:option_new* *option_new-variable* +v:option_new + New value of the option. Valid while executing an |OptionSet| + autocommand. + + *v:option_old* *option_old-variable* +v:option_old + Old value of the option. Valid while executing an |OptionSet| + autocommand. Depending on the command used for setting and the + kind of option this is either the local old value or the + global old value. + + *v:option_oldglobal* *option_oldglobal-variable* +v:option_oldglobal + Old global value of the option. Valid while executing an + |OptionSet| autocommand. + + *v:option_oldlocal* *option_oldlocal-variable* +v:option_oldlocal + Old local value of the option. Valid while executing an + |OptionSet| autocommand. + + *v:option_type* *option_type-variable* +v:option_type + Scope of the set command. Valid while executing an + |OptionSet| autocommand. Can be either "global" or "local" + + *v:prevcount* *prevcount-variable* +v:prevcount + The count given for the last but one Normal mode command. + This is the v:count value of the previous command. Useful if + you want to cancel Visual or Operator-pending mode and then + use the count, e.g.: >vim + :vmap % <Esc>:call MyFilter(v:prevcount)<CR> +< + Read-only. + + *v:profiling* *profiling-variable* +v:profiling + Normally zero. Set to one after using ":profile start". + See |profiling|. + + *v:progname* *progname-variable* +v:progname + The name by which Nvim was invoked (with path removed). + Read-only. + + *v:progpath* *progpath-variable* +v:progpath + Absolute path to the current running Nvim. + Read-only. + + *v:register* *register-variable* +v:register + The name of the register in effect for the current normal mode + command (regardless of whether that command actually used a + register). Or for the currently executing normal mode mapping + (use this in custom commands that take a register). + If none is supplied it is the default register '"', unless + 'clipboard' contains "unnamed" or "unnamedplus", then it is + "*" or '+'. + Also see |getreg()| and |setreg()| + + *v:relnum* *relnum-variable* +v:relnum + Relative line number for the 'statuscolumn' expression. + Read-only. + + *v:scrollstart* *scrollstart-variable* +v:scrollstart + String describing the script or function that caused the + screen to scroll up. It's only set when it is empty, thus the + first reason is remembered. It is set to "Unknown" for a + typed command. + This can be used to find out why your script causes the + hit-enter prompt. + + *v:searchforward* *searchforward-variable* +v:searchforward + Search direction: 1 after a forward search, 0 after a + backward search. It is reset to forward when directly setting + the last search pattern, see |quote/|. + Note that the value is restored when returning from a + function. |function-search-undo|. + Read-write. + + *v:servername* *servername-variable* +v:servername + Primary listen-address of Nvim, the first item returned by + |serverlist()|. Usually this is the named pipe created by Nvim + at |startup| or given by |--listen| (or the deprecated + |$NVIM_LISTEN_ADDRESS| env var). + + See also |serverstart()| |serverstop()|. + Read-only. + + *$NVIM* + $NVIM is set by |terminal| and |jobstart()|, and is thus + a hint that the current environment is a subprocess of Nvim. + Example: >vim + if $NVIM + echo nvim_get_chan_info(v:parent) + endif +< + + Note the contents of $NVIM may change in the future. + + *v:shell_error* *shell_error-variable* +v:shell_error + Result of the last shell command. When non-zero, the last + shell command had an error. When zero, there was no problem. + This only works when the shell returns the error code to Vim. + The value -1 is often used when the command could not be + executed. Read-only. + Example: >vim + !mv foo bar + if v:shell_error + echo 'could not rename "foo" to "bar"!' + endif +< + + *v:statusmsg* *statusmsg-variable* +v:statusmsg + Last given status message. + Modifiable (can be set). + + *v:stderr* *stderr-variable* +v:stderr + |channel-id| corresponding to stderr. The value is always 2; + use this variable to make your code more descriptive. + Unlike stdin and stdout (see |stdioopen()|), stderr is always + open for writing. Example: >vim + :call chansend(v:stderr, "error: toaster empty\n") +< + + *v:swapchoice* *swapchoice-variable* +v:swapchoice + |SwapExists| autocommands can set this to the selected choice + for handling an existing swapfile: + 'o' Open read-only + 'e' Edit anyway + 'r' Recover + 'd' Delete swapfile + 'q' Quit + 'a' Abort + The value should be a single-character string. An empty value + results in the user being asked, as would happen when there is + no SwapExists autocommand. The default is empty. + + *v:swapcommand* *swapcommand-variable* +v:swapcommand + Normal mode command to be executed after a file has been + opened. Can be used for a |SwapExists| autocommand to have + another Vim open the file and jump to the right place. For + example, when jumping to a tag the value is ":tag tagname\r". + For ":edit +cmd file" the value is ":cmd\r". + + *v:swapname* *swapname-variable* +v:swapname + Name of the swapfile found. + Only valid during |SwapExists| event. + Read-only. + + *v:t_blob* *t_blob-variable* *v:t_TYPE* +v:t_blob Value of |Blob| type. Read-only. See: |type()| + + *v:t_bool* *t_bool-variable* +v:t_bool Value of |Boolean| type. Read-only. See: |type()| + + *v:t_dict* *t_dict-variable* +v:t_dict Value of |Dictionary| type. Read-only. See: |type()| + + *v:t_float* *t_float-variable* +v:t_float Value of |Float| type. Read-only. See: |type()| + + *v:t_func* *t_func-variable* +v:t_func Value of |Funcref| type. Read-only. See: |type()| + + *v:t_list* *t_list-variable* +v:t_list Value of |List| type. Read-only. See: |type()| + + *v:t_number* *t_number-variable* +v:t_number Value of |Number| type. Read-only. See: |type()| + + *v:t_string* *t_string-variable* +v:t_string Value of |String| type. Read-only. See: |type()| + + *v:termrequest* *termrequest-variable* +v:termrequest + The value of the most recent OSC or DCS control sequence + sent from a process running in the embedded |terminal|. + This can be read in a |TermRequest| event handler to respond + to queries from embedded applications. + + *v:termresponse* *termresponse-variable* +v:termresponse + The value of the most recent OSC or DCS control sequence + received by Nvim from the terminal. This can be read in a + |TermResponse| event handler after querying the terminal using + another escape sequence. + + *v:testing* *testing-variable* +v:testing Must be set before using `test_garbagecollect_now()`. + + *v:this_session* *this_session-variable* +v:this_session + Full filename of the last loaded or saved session file. + Empty when no session file has been saved. See |:mksession|. + Modifiable (can be set). + + *v:throwpoint* *throwpoint-variable* +v:throwpoint + The point where the exception most recently caught and not + finished was thrown. Not set when commands are typed. See + also |v:exception| and |throw-variables|. + Example: >vim + try + throw "oops" + catch /.*/ + echo "Exception from" v:throwpoint + endtry +< + Output: "Exception from test.vim, line 2" + + *v:true* *true-variable* +v:true + Special value used to put "true" in JSON and msgpack. See + |json_encode()|. This value is converted to "v:true" when used + as a String (e.g. in |expr5| with string concatenation + operator) and to one when used as a Number (e.g. in |expr5| or + |expr7| when used with numeric operators). Read-only. + + *v:val* *val-variable* +v:val + Value of the current item of a |List| or |Dictionary|. Only + valid while evaluating the expression used with |map()| and + |filter()|. Read-only. + + *v:version* *version-variable* +v:version + Vim version number: major version times 100 plus minor + version. Vim 5.0 is 500, Vim 5.1 is 501. + Read-only. + Use |has()| to check the Nvim (not Vim) version: >vim + :if has("nvim-0.2.1") +< + + *v:vim_did_enter* *vim_did_enter-variable* +v:vim_did_enter + 0 during startup, 1 just before |VimEnter|. + Read-only. + + *v:virtnum* *virtnum-variable* +v:virtnum + Virtual line number for the 'statuscolumn' expression. + Negative when drawing the status column for virtual lines, zero + when drawing an actual buffer line, and positive when drawing + the wrapped part of a buffer line. + Read-only. + + *v:warningmsg* *warningmsg-variable* +v:warningmsg + Last given warning message. + Modifiable (can be set). + + *v:windowid* *windowid-variable* +v:windowid + Application-specific window "handle" which may be set by any + attached UI. Defaults to zero. + Note: For Nvim |windows| use |winnr()| or |win_getid()|, see + |window-ID|. + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index d6fce89f23..b71e7c80ab 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -242,9 +242,10 @@ and 'winminwidth' are relevant. *:hor* *:horizontal* :hor[izontal] {cmd} Execute {cmd}. Currently only makes a difference for - `horizontal wincmd =`, which will equalize windows only - horizontally, and |:terminal|, which will open a |terminal| - buffer in a split window. + the following commands: + - `:wincmd =`: equalize windows only horizontally. + - |:terminal|: open a |terminal| buffer in a split window. + - |:checkhealth|: open a healthcheck buffer in a split window. :lefta[bove] {cmd} *:lefta* *:leftabove* :abo[veleft] {cmd} *:abo* *:aboveleft* |