diff options
Diffstat (limited to 'runtime/doc')
62 files changed, 2912 insertions, 2229 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 87269ad147..2aa147770d 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -112,7 +112,11 @@ Basic types ~ Dictionary (msgpack: map) Object < - Note: empty Array is accepted as a valid argument for Dictionary parameter. + Note: + - Empty Array is accepted as a valid Dictionary parameter. + - Functions cannot cross RPC boundaries. But API functions (e.g. + |nvim_create_autocmd()|) may support Lua function parameters for non-RPC + invocations. Special types (msgpack EXT) ~ @@ -504,8 +508,9 @@ Extended marks (extmarks) represent buffer annotations that track text changes in the buffer. They can represent cursors, folds, misspelled words, anything that needs to track a logical location in the buffer over time. |api-indexing| -Extmark position works like "bar" cursor: it exists between characters. Thus, -the maximum extmark index on a line is 1 more than the character index: > +Extmark position works like a "vertical bar" cursor: it exists between +characters. Thus, the maximum extmark index on a line is 1 more than the +character index: > f o o b a r line contents 0 1 2 3 4 5 character positions (0-based) @@ -579,109 +584,6 @@ created for extmark changes. ============================================================================== Global Functions *api-global* -nvim__get_runtime({pat}, {all}, {opts}) *nvim__get_runtime()* - Find files in runtime directories - - Attributes: ~ - |api-fast| - - Parameters: ~ - • {pat} pattern of files to search for - • {all} whether to return all matches or only the first - • {opts} is_lua: only search Lua subdirs - - Return: ~ - list of absolute paths to the found files - -nvim__id({obj}) *nvim__id()* - Returns object given as argument. - - This API function is used for testing. One should not rely on its presence - in plugins. - - Parameters: ~ - • {obj} Object to return. - - Return: ~ - its argument. - -nvim__id_array({arr}) *nvim__id_array()* - Returns array given as argument. - - This API function is used for testing. One should not rely on its presence - in plugins. - - Parameters: ~ - • {arr} Array to return. - - Return: ~ - its argument. - -nvim__id_dictionary({dct}) *nvim__id_dictionary()* - Returns dictionary given as argument. - - This API function is used for testing. One should not rely on its presence - in plugins. - - Parameters: ~ - • {dct} Dictionary to return. - - Return: ~ - its argument. - -nvim__id_float({flt}) *nvim__id_float()* - Returns floating-point value given as argument. - - This API function is used for testing. One should not rely on its presence - in plugins. - - Parameters: ~ - • {flt} Value to return. - - Return: ~ - its argument. - -nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* - NB: if your UI doesn't use hlstate, this will not return hlstate first - time. - -nvim__invalidate_glyph_cache() *nvim__invalidate_glyph_cache()* - For testing. The condition in schar_cache_clear_if_full is hard to reach, - so this function can be used to force a cache clear in a test. - -nvim__stats() *nvim__stats()* - Gets internal stats. - - Return: ~ - Map of various internal stats. - -nvim_call_atomic({calls}) *nvim_call_atomic()* - Calls many API methods atomically. - - This has two main usages: - 1. To perform several requests from an async context atomically, i.e. - without interleaving redraws, RPC requests from other clients, or user - interactions (however API methods may trigger autocommands or event - processing which have such side effects, e.g. |:sleep| may wake - timers). - 2. To minimize RPC overhead (roundtrips) of a sequence of many requests. - - Attributes: ~ - |RPC| only - - Parameters: ~ - • {calls} an array of calls, where each call is described by an array - with two elements: the request name, and an array of - arguments. - - Return: ~ - Array of two elements. The first is an array of return values. The - second is NIL if all calls succeeded. If a call resulted in an error, - it is a three-element array with the zero-based index of the call - which resulted in an error, the error type and the error message. If - an error occurred, the values from all preceding calls will still be - returned. - nvim_chan_send({chan}, {data}) *nvim_chan_send()* Send data to channel `id`. For a job, it writes it to the stdin of the process. For the stdio channel |channel-stdio|, it writes to Nvim's @@ -700,21 +602,6 @@ 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. @@ -1574,23 +1461,127 @@ nvim_strwidth({text}) *nvim_strwidth()* Return: ~ Number of cells -nvim_subscribe({event}) *nvim_subscribe()* - Subscribes to event broadcasts. +nvim__complete_set({index}, {opts}) *nvim__complete_set()* + EXPERIMENTAL: this API may change in the future. - Attributes: ~ - |RPC| only + Sets info for the completion item at the given index. If the info text was + shown in a window, returns the window and buffer ids, or empty dict if not + shown. Parameters: ~ - • {event} Event type string + • {index} 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_unsubscribe({event}) *nvim_unsubscribe()* - Unsubscribes to event broadcasts. +nvim__get_runtime({pat}, {all}, {opts}) *nvim__get_runtime()* + Find files in runtime directories Attributes: ~ - |RPC| only + |api-fast| + + Parameters: ~ + • {pat} pattern of files to search for + • {all} whether to return all matches or only the first + • {opts} is_lua: only search Lua subdirs + + Return: ~ + list of absolute paths to the found files + +nvim__id({obj}) *nvim__id()* + Returns object given as argument. + + This API function is used for testing. One should not rely on its presence + in plugins. + + Parameters: ~ + • {obj} Object to return. + + Return: ~ + its argument. + +nvim__id_array({arr}) *nvim__id_array()* + Returns array given as argument. + + This API function is used for testing. One should not rely on its presence + in plugins. + + Parameters: ~ + • {arr} Array to return. + + Return: ~ + its argument. + +nvim__id_dictionary({dct}) *nvim__id_dictionary()* + Returns dictionary given as argument. + + This API function is used for testing. One should not rely on its presence + in plugins. + + Parameters: ~ + • {dct} Dictionary to return. + + Return: ~ + its argument. + +nvim__id_float({flt}) *nvim__id_float()* + Returns floating-point value given as argument. + + This API function is used for testing. One should not rely on its presence + in plugins. + + Parameters: ~ + • {flt} Value to return. + + Return: ~ + its argument. + +nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* + NB: if your UI doesn't use hlstate, this will not return hlstate first + time. + +nvim__invalidate_glyph_cache() *nvim__invalidate_glyph_cache()* + For testing. The condition in schar_cache_clear_if_full is hard to reach, + so this function can be used to force a cache clear in a test. + +nvim__redraw({opts}) *nvim__redraw()* + EXPERIMENTAL: this API may change in the future. + + Instruct Nvim to redraw various components. Parameters: ~ - • {event} Event type string + • {opts} Optional parameters. + • win: Target a specific |window-ID| as described below. + • buf: Target a specific buffer number as described below. + • flush: Update the screen with pending updates. + • valid: When present mark `win`, `buf`, or all windows for + redraw. When `true`, only redraw changed lines (useful for + decoration providers). When `false`, forcefully redraw. + • range: Redraw a range in `buf`, the buffer in `win` or the + current buffer (useful for decoration providers). Expects a + tuple `[first, last]` with the first and last line number of + the range, 0-based end-exclusive |api-indexing|. + • cursor: Immediately update cursor position on the screen in + `win` or the current window. + • statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or + all windows. + • statusline: Redraw the 'statusline' in `buf`, `win` or all + windows. + • winbar: Redraw the 'winbar' in `buf`, `win` or all windows. + • tabline: Redraw the 'tabline'. + + See also: ~ + • |:redraw| + +nvim__stats() *nvim__stats()* + Gets internal stats. + + Return: ~ + Map of various internal stats. ============================================================================== @@ -2447,7 +2438,7 @@ nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts}) • |nvim_buf_get_mark()| nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* - Sets the full file name for a buffer + Sets the full file name for a buffer, like |:file_f| Parameters: ~ • {buffer} Buffer handle, or 0 for current buffer @@ -2767,8 +2758,8 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) • 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) + • scoped: boolean (EXPERIMENTAL) enables "scoping" for the + extmark. See |nvim__win_add_ns()| Return: ~ Id of the created/updated extmark @@ -2850,34 +2841,41 @@ nvim_set_decoration_provider({ns_id}, {opts}) ["end", tick] < -nvim_win_add_ns({window}, {ns_id}) *nvim_win_add_ns()* - Adds the namespace scope to the window. +nvim__win_add_ns({window}, {ns_id}) *nvim__win_add_ns()* + EXPERIMENTAL: this API will change in the future. + + Scopes a namespace to the a window, so extmarks in the namespace will be + active only in the given window. Parameters: ~ • {window} Window handle, or 0 for current window - • {ns_id} the namespace to add + • {ns_id} Namespace 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. +nvim__win_del_ns({window}, {ns_id}) *nvim__win_del_ns()* + EXPERIMENTAL: this API will change in the future. + + Unscopes a namespace (un-binds it from the given scope). Parameters: ~ • {window} Window handle, or 0 for current window + • {ns_id} the namespace to remove Return: ~ - a list of namespaces ids + true if the namespace was removed, else false + +nvim__win_get_ns({window}) *nvim__win_get_ns()* + EXPERIMENTAL: this API will change in the future. -nvim_win_remove_ns({window}, {ns_id}) *nvim_win_remove_ns()* - Removes the namespace scope from the window. + Gets the namespace scopes for a given 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 + a list of namespaces ids ============================================================================== @@ -3271,9 +3269,8 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* • footer_pos: Footer position. Must be set with `footer` option. Value can be one of "left", "center", or "right". Default is `"left"`. - • noautocmd: If true then no buffer-related autocommand - events such as |BufEnter|, |BufLeave| or |BufWinEnter| may - fire from calling this function. + • noautocmd: If true then all autocommands are blocked for + the duration of the call. • 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. @@ -3297,11 +3294,11 @@ nvim_win_get_config({window}) *nvim_win_get_config()* Map defining the window configuration, see |nvim_open_win()| 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). + Configures window layout. Cannot be used to move the last window in a + tabpage to a different one. - When reconfiguring a floating window, absent option keys will not be - changed. `row`/`col` and `relative` must be reconfigured together. + When reconfiguring a window, absent option keys will not be changed. + `row`/`col` and `relative` must be reconfigured together. Parameters: ~ • {window} Window handle, or 0 for current window @@ -3475,7 +3472,8 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* Vimscript function name, if string) called when the 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: + Receives one argument, a table with these keys: + *event-args* • id: (number) autocommand id • event: (string) name of the triggered event |autocmd-events| @@ -3484,7 +3482,7 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* • buf: (number) expanded value of <abuf> • file: (string) expanded value of <afile> • data: (any) arbitrary data passed from - |nvim_exec_autocmds()| + |nvim_exec_autocmds()| *event-data* • command (string) optional: Vim command to execute on event. Cannot be used with {callback} • once (boolean) optional: defaults to false. Run the diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 8890872e1a..ca816851dd 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -466,6 +466,16 @@ CompleteDone After Insert mode completion is done. Either CompleteDonePre if you need it. |v:completed_item| gives the completed item. + Sets these |v:event| keys: + reason Reason for completion being + done. Can be one of: + - "accept": completion was + accepted using |complete_CTRL-Y|. + - "cancel": completion was cancelled + using |complete_CTRL-E|, pressing + a non-keyword character, or + triggering a new completion. + *CursorHold* CursorHold When the user doesn't press a key for the time specified with 'updatetime'. Not triggered @@ -884,6 +894,9 @@ SafeState When nothing is pending, going to wait for the *SessionLoadPost* SessionLoadPost After loading the session file created using the |:mksession| command. + *SessionWritePost* +SessionWritePost After writing a session file by calling + the |:mksession| command. *ShellCmdPost* ShellCmdPost After executing a shell command with |:!cmd|, |:make| and |:grep|. Can be used to check for @@ -900,18 +913,18 @@ ShellFilterPost After executing a shell command with ":{range}!cmd", ":w !cmd" or ":r !cmd". Can be used to check for any changed files. *SourcePre* -SourcePre Before sourcing a vim/lua file. |:source| +SourcePre Before sourcing a Vimscript/Lua file. |:source| <afile> is the name of the file being sourced. *SourcePost* -SourcePost After sourcing a vim/lua file. |:source| +SourcePost After sourcing a Vimscript/Lua file. |:source| <afile> is the name of the file being sourced. Not triggered when sourcing was interrupted. Also triggered after a SourceCmd autocommand was triggered. *SourceCmd* -SourceCmd When sourcing a vim/lua file. |:source| +SourceCmd When sourcing a Vimscript/Lua file. |:source| <afile> is the name of the file being sourced. - The autocommand must source this file. + The autocommand must source that file. |Cmd-event| *SpellFileMissing* SpellFileMissing When trying to load a spell checking file and @@ -986,18 +999,16 @@ 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. +TermRequest When a |:terminal| child process emits an OSC + or DCS sequence. Sets |v:termrequest|. The + |event-data| is the request string. *TermResponse* TermResponse When Nvim receives an OSC or DCS response from - the terminal. Sets |v:termresponse|. When used - from Lua, the response string is included in - the "data" field of the autocommand callback. - May be triggered halfway through another event - (file I/O, a shell command, or anything else - that takes time). Example: >lua + the host terminal. Sets |v:termresponse|. The + |event-data| is the response string. May be + triggered during another event (file I/O, + a shell command, or anything else that takes + time). Example: >lua -- Query the terminal palette for the RGB value of color 1 -- (red) using OSC 4 diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index c5f3946871..ff7d5f9ce8 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -1268,7 +1268,6 @@ executable({expr}) *executable()* The result is a Number: 1 exists 0 does not exist - -1 not implemented on this system |exepath()| can be used to get the full path of an executable. execute({command} [, {silent}]) *execute()* @@ -1588,6 +1587,7 @@ feedkeys({string} [, {mode}]) *feedkeys()* 't' Handle keys as if typed; otherwise they are handled as if coming from a mapping. This matters for undo, opening folds, etc. + 'L' Lowlevel input. Other flags are not used. 'i' Insert the string instead of appending (see above). 'x' Execute commands until typeahead is empty. This is similar to using ":normal!". You can call feedkeys() @@ -2196,16 +2196,16 @@ getchangelist([{buf}]) *getchangelist()* position refers to the position in the list. For other buffers, it is set to the length of the list. -getchar([expr]) *getchar()* +getchar([{expr}]) *getchar()* Get a single character from the user or input stream. - If [expr] is omitted, wait until a character is available. - If [expr] is 0, only get a character when one is available. + If {expr} is omitted, wait until a character is available. + If {expr} is 0, only get a character when one is available. Return zero otherwise. - If [expr] is 1, only check if a character is available, it is + If {expr} is 1, only check if a character is available, it is not consumed. Return zero if no character available. If you prefer always getting a string use |getcharstr()|. - Without [expr] and when [expr] is 0 a whole character or + Without {expr} and when {expr} is 0 a whole character or special key is returned. If it is a single character, the result is a Number. Use |nr2char()| to convert it to a String. Otherwise a String is returned with the encoded character. @@ -2215,11 +2215,11 @@ getchar([expr]) *getchar()* also a String when a modifier (shift, control, alt) was used that is not included in the character. - When [expr] is 0 and Esc is typed, there will be a short delay + When {expr} is 0 and Esc is typed, there will be a short delay while Vim waits to see if this is the start of an escape sequence. - When [expr] is 1 only the first byte is returned. For a + When {expr} is 1 only the first byte is returned. For a one-byte character it is the character itself as a number. Use nr2char() to convert it to a String. @@ -2311,13 +2311,13 @@ getcharsearch() *getcharsearch()* nnoremap <expr> , getcharsearch().forward ? ',' : ';' < Also see |setcharsearch()|. -getcharstr([expr]) *getcharstr()* +getcharstr([{expr}]) *getcharstr()* Get a single character from the user or input stream as a string. - If [expr] is omitted, wait until a character is available. - If [expr] is 0 or false, only get a character when one is + If {expr} is omitted, wait until a character is available. + If {expr} is 0 or false, only get a character when one is available. Return an empty string otherwise. - If [expr] is 1 or true, only check if a character is + If {expr} is 1 or true, only check if a character is available, it is not consumed. Return an empty string if no character is available. Otherwise this works like |getchar()|, except that a number @@ -2969,6 +2969,38 @@ getregion({pos1}, {pos2} [, {opts}]) *getregion()* \ getpos('v'), getpos('.'), #{ type: mode() })<CR> < +getregionpos({pos1}, {pos2} [, {opts}]) *getregionpos()* + Same as |getregion()|, but returns a list of positions + describing the buffer text segments bound by {pos1} and + {pos2}. + The segments are a pair of positions for every line: > + [[{start_pos}, {end_pos}], ...] +< + The position is a |List| with four numbers: + [bufnum, lnum, col, off] + "bufnum" is the buffer number. + "lnum" and "col" are the position in the buffer. The first + column is 1. + If the "off" number of a starting position is non-zero, it is + the offset in screen columns from the start of the character. + E.g., a position within a <Tab> or after the last character. + If the "off" number of an ending position is non-zero, it is + the offset of the character's first cell not included in the + selection, otherwise all its cells are included. + + Apart from the options supported by |getregion()|, {opts} also + supports the following: + + eol If |TRUE|, indicate positions beyond + the end of a line with "col" values + one more than the length of the line. + If |FALSE|, positions are limited + within their lines, and if a line is + empty or the selection is entirely + beyond the end of a line, a "col" + value of 0 is used for both positions. + (default: |FALSE|) + getregtype([{regname}]) *getregtype()* The result is a String, which is type of register {regname}. The value will be one of: @@ -3014,7 +3046,7 @@ getscriptinfo([{opts}]) *getscriptinfo()* Examples: >vim echo getscriptinfo({'name': 'myscript'}) - echo getscriptinfo({'sid': 15}).variables + echo getscriptinfo({'sid': 15})[0].variables < gettabinfo([{tabnr}]) *gettabinfo()* @@ -4981,9 +5013,9 @@ mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E73 successful or FALSE if the directory creation failed or partly failed. -mode([expr]) *mode()* +mode([{expr}]) *mode()* Return a string that indicates the current mode. - If [expr] is supplied and it evaluates to a non-zero Number or + If {expr} is supplied and it evaluates to a non-zero Number or a non-empty String (|non-zero-arg|), then the full mode is returned, otherwise only the first letter is returned. Also see |state()|. @@ -5486,6 +5518,9 @@ printf({fmt}, {expr1} ...) *printf()* echo printf("%1$*2$.*3$f", 1.4142135, 6, 2) < 1.41 + You will get an overflow error |E1510|, when the field-width + or precision will result in a string longer than 6400 chars. + *E1500* You cannot mix positional and non-positional arguments: >vim echo printf("%s%1$s", "One", "Two") @@ -6054,6 +6089,7 @@ search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) *search()* When a match has been found its line number is returned. If there is no match a 0 is returned and the cursor doesn't move. No error message is given. + To get the matched string, use |matchbufline()|. {flags} is a String, which can contain these character flags: 'b' search Backward instead of forward @@ -6958,10 +6994,11 @@ shellescape({string} [, {special}]) *shellescape()* Otherwise encloses {string} in single-quotes and replaces all "'" with "'\''". - If {special} is a |non-zero-arg|: - - Special items such as "!", "%", "#" and "<cword>" will be - preceded by a backslash. The backslash will be removed again - by the |:!| command. + The {special} argument adds additional escaping of keywords + used in Vim commands. If it is a |non-zero-arg|: + - Special items such as "!", "%", "#" and "<cword>" (as listed + in |expand()|) will be preceded by a backslash. + The backslash will be removed again by the |:!| command. - The <NL> character is escaped. If 'shell' contains "csh" in the tail: @@ -7407,7 +7444,8 @@ slice({expr}, {start} [, {end}]) *slice()* Similar to using a |slice| "expr[start : end]", but "end" is used exclusive. And for a string the indexes are used as character indexes instead of byte indexes. - Also, composing characters are not counted. + Also, composing characters are treated as a part of the + preceding base character. When {end} is omitted the slice continues to the last item. When {end} is -1 the last item is omitted. Returns an empty value if {start} or {end} are invalid. @@ -7754,8 +7792,8 @@ strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* of byte index and length. When {skipcc} is omitted or zero, composing characters are counted separately. - When {skipcc} set to 1, Composing characters are ignored, - similar to |slice()|. + When {skipcc} set to 1, composing characters are treated as a + part of the preceding base character, similar to |slice()|. When a character index is used where a character does not exist it is omitted and counted as one character. For example: >vim @@ -7769,7 +7807,7 @@ strchars({string} [, {skipcc}]) *strchars()* in String {string}. When {skipcc} is omitted or zero, composing characters are counted separately. - When {skipcc} set to 1, Composing characters are ignored. + When {skipcc} set to 1, composing characters are ignored. |strcharlen()| always does this. Returns zero on error. @@ -7871,10 +7909,10 @@ string({expr}) *string()* for infinite and NaN floating-point values representations which use |str2float()|. Strings are also dumped literally, only single quote is escaped, which does not allow using YAML - for parsing back binary strings. |eval()| should always work for - strings and floats though and this is the only official - method, use |msgpackdump()| or |json_encode()| if you need to - share data with other application. + for parsing back binary strings. |eval()| should always work + for strings and floats though, and this is the only official + method. Use |msgpackdump()| or |json_encode()| if you need to + share data with other applications. strlen({string}) *strlen()* The result is a Number, which is the length of the String @@ -8203,6 +8241,10 @@ synconcealed({lnum}, {col}) *synconcealed()* synconcealed(lnum, 5) [1, 'X', 2] synconcealed(lnum, 6) [0, '', 0] + Note: Doesn't consider |matchadd()| highlighting items, + since syntax and matching highlighting are two different + mechanisms |syntax-vs-match|. + synstack({lnum}, {col}) *synstack()* Return a |List|, which is the stack of syntax items at the position {lnum} and {col} in the current window. {lnum} is @@ -8897,14 +8939,13 @@ win_screenpos({nr}) *win_screenpos()* [1, 1], unless there is a tabline, then it is [2, 1]. {nr} can be the window number or the |window-ID|. Use zero for the current window. - Returns [0, 0] if the window cannot be found in the current - tabpage. + Returns [0, 0] if the window cannot be found. win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* - Move the window {nr} to a new split of the window {target}. - This is similar to moving to {target}, creating a new window - using |:split| but having the same contents as window {nr}, and - then closing {nr}. + Temporarily switch to window {target}, then move window {nr} + to a new split adjacent to {target}. + Unlike commands such as |:split|, no new windows are created + (the |window-ID| of window {nr} is unchanged after the move). Both {nr} and {target} can be window numbers or |window-ID|s. Both must be in the current tab page. @@ -9007,7 +9048,9 @@ winnr([{arg}]) *winnr()* # the number of the last accessed window (where |CTRL-W_p| goes to). If there is no previous window or it is in another tab page 0 is - returned. + returned. May refer to the current window in + some cases (e.g. when evaluating 'statusline' + expressions). {N}j the number of the Nth window below the current window (where |CTRL-W_j| goes to). {N}k the number of the Nth window above the current diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index 703addf51a..9ff16165d7 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -281,6 +281,13 @@ gr{char} Replace the virtual characters under the cursor with that have a special meaning in Insert mode, such as most CTRL-keys, cannot be used. + *gr-default* + Nvim creates default mappings with "gr" as a prefix, + which may inhibit the behavior of |gr|. Use the + following to restore the builtin behavior: > + nnoremap <nowait> gr gr +< + *digraph-arg* The argument for Normal mode commands like |r| and |t| is a single character. When 'cpo' doesn't contain the 'D' flag, this character can also be entered @@ -1291,8 +1298,8 @@ expression (like with the "/" command). The expression must evaluate to a String. A Number is always automatically converted to a String. For the "p" and ":put" command, if the result is a Float it's converted into a String. If the result is a List each element is -turned into a String and used as a line. A Dictionary or FuncRef results in -an error message (use string() to convert). +turned into a String and used as a line. A Dictionary is converted into a +String. A Funcref results in an error message (use string() to convert). If the "= register is used for the "p" command, the String is split up at <NL> characters. If the String ends in a <NL>, it is regarded as a linewise diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index 57a4223c53..f306067a9c 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -274,14 +274,6 @@ CTRL-P command-line completion (see |cmdline-completion|) CTRL-A command-line completion (see |cmdline-completion|) CTRL-L command-line completion (see |cmdline-completion|) - *c_CTRL-_* -CTRL-_ Switch between Hebrew and English keyboard mode, which is - private to the command-line and not related to hkmap. - This is useful when Hebrew text entry is required in the - command-line, searches, abbreviations, etc. Applies only if - the 'allowrevins' option is set. - See |rileft.txt|. - *c_CTRL-^* CTRL-^ Toggle the use of language |:lmap| mappings and/or Input Method. diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 5ac4ad4ce2..646ba72bd8 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -12,21 +12,112 @@ They should not be used in new scripts, and old scripts should be updated. ============================================================================== Deprecated features +------------------------------------------------------------------------------ +DEPRECATED IN 0.11 *deprecated-0.11* + +API +- nvim_subscribe() Plugins must maintain their own "multicast" channels list. +- nvim_unsubscribe() Plugins must maintain their own "multicast" channels list. + + +------------------------------------------------------------------------------ +DEPRECATED IN 0.10 *deprecated-0.10* + +API +• *nvim_buf_get_option()* Use |nvim_get_option_value()| instead. +• *nvim_buf_set_option()* Use |nvim_set_option_value()| instead. +• *nvim_call_atomic()* Use |nvim_exec_lua()| instead. +• *nvim_get_option()* Use |nvim_get_option_value()| instead. +• *nvim_set_option()* Use |nvim_set_option_value()| instead. +• *nvim_win_get_option()* Use |nvim_get_option_value()| instead. +• *nvim_win_set_option()* Use |nvim_set_option_value()| instead. + +CHECKHEALTH +• *health#report_error* *vim.health.report_error()* Use |vim.health.error()| instead. +• *health#report_info* *vim.health.report_info()* Use |vim.health.info()| instead. +• *health#report_ok* *vim.health.report_ok()* Use |vim.health.ok()| instead. +• *health#report_start* *vim.health.report_start()* Use |vim.health.start()| instead. +• *health#report_warn* *vim.health.report_warn()* Use |vim.health.warn()| instead. + +DIAGNOSTICS +• Configuring |diagnostic-signs| using |:sign-define| or |sign_define()|. Use + the "signs" key of |vim.diagnostic.config()| instead. +• vim.diagnostic functions: + • *vim.diagnostic.disable()* Use |vim.diagnostic.enable()| + • *vim.diagnostic.is_disabled()* Use |vim.diagnostic.is_enabled()| + • Legacy signature: `vim.diagnostic.enable(buf:number, namespace:number)` + +LSP +• *vim.lsp.util.get_progress_messages()* Use |vim.lsp.status()| instead. +• *vim.lsp.get_active_clients()* Use |vim.lsp.get_clients()| instead. +• *vim.lsp.for_each_buffer_client()* Use |vim.lsp.get_clients()| 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()* +• *vim.lsp.util.extract_completion_items()* +• *vim.lsp.util.parse_snippet()* +• *vim.lsp.util.text_document_completion_list_to_complete_items()* +• *vim.lsp.util.lookup_section()* Use |vim.tbl_get()| instead: > + local keys = vim.split(section, '.', { plain = true }) + local vim.tbl_get(table, unpack(keys)) + +LUA +• *vim.loop* Use |vim.uv| instead. +• *vim.tbl_add_reverse_lookup()* +• *vim.tbl_flatten()* Use |Iter:flatten()| instead. +• *vim.tbl_islist()* Use |vim.islist()| instead. + +OPTIONS +• 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. + +TREESITTER +• *LanguageTree:for_each_child()* Use |LanguageTree:children()| (non-recursive) instead. + + +------------------------------------------------------------------------------ +DEPRECATED IN 0.9 *deprecated-0.9* + +API +- *nvim_get_hl_by_name()* Use |nvim_get_hl()| instead. +- *nvim_get_hl_by_id()* Use |nvim_get_hl()| instead. + +TREESITTER +- *vim.treesitter.language.require_language()* Use |vim.treesitter.language.add()| instead. +- *vim.treesitter.get_node_at_pos()* Use |vim.treesitter.get_node()| instead. +- *vim.treesitter.get_node_at_cursor()* Use |vim.treesitter.get_node()| + and |TSNode:type()| instead. +• The following top level Treesitter functions have been moved: + - *vim.treesitter.inspect_language()* -> |vim.treesitter.language.inspect()| + - *vim.treesitter.get_query_files()* -> |vim.treesitter.query.get_files()| + - *vim.treesitter.set_query()* -> |vim.treesitter.query.set()| + - *vim.treesitter.query.set_query()* -> |vim.treesitter.query.set()| + - *vim.treesitter.get_query()* -> |vim.treesitter.query.get()| + - *vim.treesitter.query.get_query()* -> |vim.treesitter.query.get()| + - *vim.treesitter.parse_query()* -> |vim.treesitter.query.parse()| + - *vim.treesitter.query.parse_query()* -> |vim.treesitter.query.parse()| + - *vim.treesitter.add_predicate()* -> |vim.treesitter.query.add_predicate()| + - *vim.treesitter.add_directive()* -> |vim.treesitter.query.add_directive()| + - *vim.treesitter.list_predicates()* -> |vim.treesitter.query.list_predicates()| + - *vim.treesitter.list_directives()* -> |vim.treesitter.query.list_directives()| + - *vim.treesitter.query.get_range()* -> |vim.treesitter.get_range()| + - *vim.treesitter.query.get_node_text()* -> |vim.treesitter.get_node_text()| + +LUA + - *nvim_exec()* Use |nvim_exec2()| instead. + - *vim.pretty_print()* Use |vim.print()| instead. + + +------------------------------------------------------------------------------ +DEPRECATED IN 0.8 OR EARLIER + API - *nvim_buf_clear_highlight()* Use |nvim_buf_clear_namespace()| instead. - *nvim_buf_set_virtual_text()* Use |nvim_buf_set_extmark()| instead. - *nvim_command_output()* Use |nvim_exec2()| instead. - *nvim_execute_lua()* Use |nvim_exec_lua()| instead. -- *nvim_get_hl_by_name()* Use |nvim_get_hl()| instead. -- *nvim_get_hl_by_id()* Use |nvim_get_hl()| instead. -- *nvim_exec()* Use |nvim_exec2()| instead. - *nvim_get_option_info()* Use |nvim_get_option_info2()| instead. -- *nvim_buf_get_option()* Use |nvim_get_option_value()| instead. -- *nvim_buf_set_option()* Use |nvim_set_option_value()| instead. -- *nvim_get_option()* Use |nvim_get_option_value()| instead. -- *nvim_set_option()* Use |nvim_set_option_value()| instead. -- *nvim_win_get_option()* Use |nvim_get_option_value()| instead. -- *nvim_win_set_option()* Use |nvim_set_option_value()| instead. COMMANDS - *:rv* *:rviminfo* Deprecated alias to |:rshada| command. @@ -60,11 +151,6 @@ FUNCTIONS - *buffer_name()* Obsolete name for |bufname()|. - *buffer_number()* Obsolete name for |bufnr()|. - *file_readable()* Obsolete name for |filereadable()|. -- *health#report_error* *vim.health.report_error()* Use |vim.health.error()| instead. -- *health#report_info* *vim.health.report_info()* Use |vim.health.info()| instead. -- *health#report_ok* *vim.health.report_ok()* Use |vim.health.ok()| instead. -- *health#report_start* *vim.health.report_start()* Use |vim.health.start()| instead. -- *health#report_warn* *vim.health.report_warn()* Use |vim.health.warn()| instead. - *highlight_exists()* Obsolete name for |hlexists()|. - *highlightID()* Obsolete name for |hlID()|. - *inputdialog()* Use |input()| instead. @@ -85,7 +171,7 @@ For each of the functions below, use the corresponding function in |vim.diagnostic.get()| instead of |vim.lsp.diagnostic.get()|. - *vim.lsp.diagnostic.clear()* Use |vim.diagnostic.hide()| instead. -- *vim.lsp.diagnostic.disable()* +- *vim.lsp.diagnostic.disable()* Use |vim.diagnostic.enable()| instead. - *vim.lsp.diagnostic.display()* Use |vim.diagnostic.show()| instead. - *vim.lsp.diagnostic.enable()* - *vim.lsp.diagnostic.get()* @@ -140,36 +226,9 @@ LSP FUNCTIONS {async=false} instead. - *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| -- *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()* -- *vim.lsp.util.extract_completion_items()* -- *vim.lsp.util.parse_snippet()* -- *vim.lsp.util.text_document_completion_list_to_complete_items()* - -TREESITTER FUNCTIONS -- *vim.treesitter.language.require_language()* Use |vim.treesitter.language.add()| - instead. -- *vim.treesitter.get_node_at_pos()* Use |vim.treesitter.get_node()| - instead. -- *vim.treesitter.get_node_at_cursor()* Use |vim.treesitter.get_node()| - and |TSNode:type()| instead. -- *vim.treesitter.query.get_query()* Use |vim.treesitter.query.get()| - instead. -- *LanguageTree:for_each_child()* Use |LanguageTree:children()| - (non-recursive) instead. 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". @@ -211,8 +270,10 @@ UI EXTENSIONS by the Nvim core directly instead of the TUI. VARIABLES -- *b:terminal_job_pid* PID of the top-level process in a |:terminal|. - Use `jobpid(&channel)` instead. +- *b:terminal_job_pid* Use `jobpid(&channel)` instead. +- *b:terminal_job_id* Use `&channel` instead. To access in non-current buffer: + - Lua: `vim.bo[bufnr].channel` + - Vimscript: `getbufvar(bufnr, '&channel')` vim:noet:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt index 85aeddd425..6c805963a9 100644 --- a/runtime/doc/dev_style.txt +++ b/runtime/doc/dev_style.txt @@ -6,7 +6,7 @@ Nvim style guide *dev-style* -This is style guide for developers working on Nvim's source code. +Style guidelines for developers working Nvim's source code. License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/ diff --git a/runtime/doc/dev_theme.txt b/runtime/doc/dev_theme.txt index 29a2da0d90..532506abcb 100644 --- a/runtime/doc/dev_theme.txt +++ b/runtime/doc/dev_theme.txt @@ -4,9 +4,9 @@ NVIM REFERENCE MANUAL -Nvim theme style guide *dev-theme* +Nvim colorscheme guidelines *dev-theme* -This is style guide for developers working on Nvim's default color scheme. +Style guidelines for developing Nvim's default colorscheme. License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/ @@ -17,19 +17,15 @@ 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. @@ -38,39 +34,29 @@ 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), @@ -78,33 +64,25 @@ Palettes 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: @@ -113,9 +91,7 @@ In case of 16 colors: 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 index 3ee48bec90..52513db31d 100644 --- a/runtime/doc/dev_tools.txt +++ b/runtime/doc/dev_tools.txt @@ -14,10 +14,10 @@ itself. See also |debug.txt| for advice that applies to Vim. ============================================================================== Backtraces *dev-tools-backtrace* -LINUX ~ +LINUX -Core dumps are disabled by default on Ubuntu -https://stackoverflow.com/a/18368068, CentOS and others. To enable core dumps: +Core dumps are disabled by default on Ubuntu, CentOS and others. +To enable core dumps: >bash ulimit -c unlimited < @@ -25,21 +25,29 @@ 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: +`coredumpctl` is 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: +The full backtrace is most useful; please send us the `backtrace.txt` file +when reporting a bug related to a crash: >bash - 2>&1 coredumpctl -1 gdb | tee -a bt.txt - thread apply all bt full + 2>&1 coredumpctl -1 gdb | tee -a backtrace.txt + (gdb) 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: + +On systems without `coredumpctl`, you may find a `core` dump file appearing +in the current directory or in other locations. On Linux systems where +`apport` is installed (such as Ubuntu), the directory where core dump files +are saved can be `/var/lib/apport/coredump` or elsewhere, depending on the +system configuration (see `/proc/sys/kernel/core_pattern`). See also: +https://stackoverflow.com/a/18368068 + +To get a backtrace from the `./core` dump file: >bash - gdb build/bin/nvim core 2>&1 | tee backtrace.txt - thread apply all bt full + gdb build/bin/nvim ./core 2>&1 | tee backtrace.txt + (gdb) thread apply all bt full < MACOS @@ -76,7 +84,7 @@ core dumps with `/etc/launchd.conf`). ============================================================================== Gdb *dev-tools-gdb* -USING GDB TO STEP THROUGH FUNCTIONAL TESTS ~ +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 ...", ...)`): @@ -86,20 +94,19 @@ Use `TEST_TAG` to run tests matching busted tags (of the form `#foo` e.g. 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. + (gdb) target remote localhost:7777 +-- See `nvim_argv` in https://github.com/neovim/neovim/blob/master/test/functional/testnvim.lua. -USING LLDB TO STEP THROUGH UNIT TESTS ~ +USING LLDB TO STEP THROUGH UNIT TESTS ->bash +> lldb .deps/usr/bin/luajit -- .deps/usr/bin/busted --lpath="./build/?.lua" test/unit/ < +USING GDB -USING GDB ~ - -To attach to a running `nvim` process with a pid of 1234: +To attach to a running `nvim` process with a pid of 1234 (Tip: the pid of a +running Nvim instance can be obtained by calling |getpid()|), for instance: >bash gdb -tui -p 1234 build/bin/nvim < @@ -118,8 +125,7 @@ The `gdb` interactive prompt will appear. At any time you can: need for a gdb "frontend". - `<up>` and `<down>` to scroll the source file view - -GDB "REVERSE DEBUGGING" ~ +GDB REVERSE DEBUGGING - `set record full insn-number-max unlimited` - `continue` for a bit (at least until `main()` is executed @@ -127,8 +133,7 @@ GDB "REVERSE DEBUGGING" ~ - provoke the bug, then use `revert-next`, `reverse-step`, etc. to rewind the debugger - -USING GDBSERVER ~ +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 @@ -146,12 +151,12 @@ debugging session in another terminal: < Once you've entered `gdb`, you need to attach to the remote session: > - target remote localhost:6666 + (gdb) 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 -> +>c signal (SIGTTOU, SIG_IGN); if (!tcsetpgrp(data->input.in_fd, getpid())) { perror("tcsetpgrp failed"); @@ -159,8 +164,7 @@ unable to read input from pty (and receives SIGTTIN signal) and/or output data < to `tui.c:terminfo_start`. - -USING GDBSERVER IN TMUX ~ +USING GDBSERVER IN TMUX Consider using a custom makefile https://github.com/neovim/neovim/blob/master/BUILD.md#custom-makefile to @@ -185,8 +189,8 @@ 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 + (gdb) target remote localhost:6666 + (gdb) 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 index 96307dc7df..d6e4ced054 100644 --- a/runtime/doc/dev_vimpatch.txt +++ b/runtime/doc/dev_vimpatch.txt @@ -185,7 +185,7 @@ information. mch_memmove memmove vim_memset copy_chars copy_spaces memset vim_strbyte strchr - vim_strncpy strncpy xstrlcpy + vim_strncpy strncpy xstrlcpy/xmemcpyz vim_strcat strncat xstrlcat VIM_ISWHITE ascii_iswhite IS_WHITE_OR_NUL ascii_iswhite_or_nul @@ -209,6 +209,8 @@ information. utf_off2cells grid_off2cells ml_get_curline get_cursor_line_ptr ml_get_cursor get_cursor_pos_ptr + ml_get_curline_len get_cursor_line_len + ml_get_cursor_len get_cursor_pos_len screen_char ui_line screen_line grid_put_linebuf screen_* (most functions) grid_* diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 767f46ad1e..d7837dc2fe 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -4,7 +4,7 @@ NVIM REFERENCE MANUAL -Development of Nvim *development* *dev* +Development of Nvim *development* *dev* This reference describes design constraints and guidelines, for developing Nvim applications or Nvim itself. @@ -16,13 +16,13 @@ Nvim is free and open source. Everybody is encouraged to contribute. Type |gO| to see the table of contents. ============================================================================== -Design goals *design-goals* +Design goals *design-goals* Most important things come first (roughly). Some items conflict; this is intentional. A balance must be found. -NVIM IS... IMPROVED *design-improved* +NVIM IS... IMPROVED *design-improved* The Neo bits of Nvim should make it a better Vim, without becoming a completely different editor. @@ -35,7 +35,7 @@ completely different editor. never break. -NVIM IS... WELL DOCUMENTED *design-documented* +NVIM IS... WELL DOCUMENTED *design-documented* - A feature that isn't documented is a useless feature. A patch for a new feature must include the documentation. @@ -44,7 +44,7 @@ NVIM IS... WELL DOCUMENTED *design-documented* item is easier to find. -NVIM IS... FAST AND SMALL *design-speed-size* +NVIM IS... FAST AND SMALL *design-speed-size* Keep Nvim small and fast. This directly affects versatility and usability. - Computers are becoming faster and bigger each year. Vim can grow too, but @@ -59,7 +59,7 @@ Keep Nvim small and fast. This directly affects versatility and usability. ("composability"). -NVIM IS... MAINTAINABLE *design-maintain* +NVIM IS... MAINTAINABLE *design-maintain* - The source code should not become a mess. It should be reliable code. - Use comments in a useful way! Quoting the function name and argument names @@ -70,7 +70,7 @@ NVIM IS... MAINTAINABLE *design-maintain* knowledge spread to other parts of the code. -NVIM IS... NOT *design-not* +NVIM IS... NOT *design-not* Nvim is not an operating system; instead it should be composed with other tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not @@ -78,10 +78,10 @@ include the kitchen sink... but it's good for plumbing." ============================================================================== -Developer guidelines *dev-guidelines* +Developer guidelines *dev-guidelines* -PROVIDERS *dev-provider* +PROVIDERS *dev-provider* A primary goal of Nvim is to allow extension of the editor without special knowledge in the core. Some core functions are delegated to "providers" @@ -115,7 +115,7 @@ For example, the Python provider is implemented by the to 2 only if a valid external Python host is found. Then `has("python")` reflects whether Python support is working. - *provider-reload* + *provider-reload* Sometimes a GUI or other application may want to force a provider to "reload". To reload a provider, undefine its "loaded" flag, then use |:runtime| to reload it: >vim @@ -124,7 +124,7 @@ Sometimes a GUI or other application may want to force a provider to :runtime autoload/provider/clipboard.vim -DOCUMENTATION *dev-doc* +DOCUMENTATION *dev-doc* - "Just say it". Avoid mushy, colloquial phrasing in all documentation (docstrings, user manual, website materials, newsletters, …). Don't mince @@ -159,6 +159,12 @@ DOCUMENTATION *dev-doc* not "the user host terminal". - Use "tui-" to prefix help tags related to the host terminal, and "TUI" in prose if possible. +- Rough guidelines on where Lua documentation should end up: + - Nvim API functions `vim.api.nvim_*` should be in `api.txt`. + - If the module is big and not relevant to generic and lower-level Lua + functionality, then it's a strong candidate for separation. Example: + `treesitter.txt` + - Otherwise, add them to `lua.txt` Documentation format ~ @@ -230,7 +236,7 @@ in src/nvim/api/win_config.c like this: > Lua docstrings ~ - *dev-lua-doc* + *dev-lua-doc* Lua documentation lives in the source code, as docstrings on the function definitions. The |lua-vim| :help is generated from the docstrings. @@ -289,7 +295,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: > --- @returns false if client should cancel the paste. -LUA STDLIB DESIGN GUIDELINES *dev-lua* +LUA STDLIB DESIGN GUIDELINES *dev-lua* See also |dev-naming|. @@ -304,14 +310,22 @@ See also |dev-naming|. - accept iterable instead of table - exception: in some cases iterable doesn't make sense, e.g. spair() sorts the input by definition, so there is no reason for it to accept an - iterable, because the input needs to be "hydrated", it can't operate on + iterable, because the input needs to be "reified"; it can't operate on a "stream". - return iterable instead of table - mimic the pairs() or ipairs() interface if the function is intended to be used in a "for" loop. + - when a result-or-error interface is needed, return `result|nil, nil|errmsg`: > + ---@return Foo|nil # Result object, or nil if not found. + ---@return nil|string # Error message on failure, or nil on success. +< + - Examples: |vim.ui.open()| |io.open()| |luv-error-handling| + *dev-patterns* Interface conventions ~ +Where possible, these patterns apply to _both_ Lua and the API: + - When accepting a buffer id, etc., 0 means "current buffer", nil means "all buffers". Likewise for window id, tabpage id, etc. - Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()| @@ -322,8 +336,19 @@ Interface conventions ~ filter(table, opts, function() … end) BAD: filter(function() … end, table, opts) - -API DESIGN GUIDELINES *dev-api* +- "Enable" ("toggle") interface and behavior: + - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the + the "global" enablement of a feature. + - `is_enabled(nil)` and `is_enabled({buf=nil})`, likewise, query the + global state of the feature. + - `enable(…, {buf: number})` sets a buffer-local "enable" flag. + - `is_enabled({buf: number})`, likewise, queries the buffer-local state of + the feature. + - See |vim.lsp.inlay_hint.enable()| and |vim.lsp.inlay_hint.is_enabled()| + for a reference implementation of these "best practices". + - NOTE: open questions: https://github.com/neovim/neovim/issues/28603 + +API DESIGN GUIDELINES *dev-api* See also |dev-naming|. @@ -363,32 +388,45 @@ Naming conventions ~ In general, look for precedent when choosing a name, that is, look at existing (non-deprecated) functions. In particular, see below... - *dev-name-common* + *dev-name-common* Use existing common {verb} names (actions) if possible: - add: Appends or inserts into a collection - attach: Listens to something to get events from it (TODO: rename to "on"?) - call: Calls a function + - cancel: Cancels or dismisses an event or interaction, typically + user-initiated and without error. (Compare "abort", which + cancels and signals error/failure.) - clear: Clears state but does not destroy the container - create: Creates a new (non-trivial) thing (TODO: rename to "def"?) - del: Deletes a thing (or group of things) - detach: Dispose attached listener (TODO: rename to "un"?) + - enable: Enables/disables functionality. Signature should be + `enable(enable?:boolean, filter?:table)`. - eval: Evaluates an expression - - exec: Executes code + - exec: Executes code, may return a result - fmt: Formats - get: Gets things (often by a query) - inspect: Presents a high-level, often interactive, view + - is_enabled: Checks if functionality is enabled. - open: Opens something (a buffer, window, …) - parse: Parses something into a structured form - set: Sets a thing (or group of things) + - start: Spin up a long-lived process. Prefer "enable" except when + "start" is obviously more appropriate. + - stop: Inverse of "start". Teardown a long-lived process. - try_{verb}: Best-effort operation, failure returns null or error obj Do NOT use these deprecated verbs: + - disable: Prefer `enable(enable: boolean)`. + - exit: Prefer "cancel" (or "stop" if appropriate). + - is_disabled: Prefer `is_enabled()`. - list: Redundant with "get" - - show: Redundant with "print", "echo" - notify: Redundant with "print", "echo" + - show: Redundant with "print", "echo" + - toggle: Prefer `enable(not is_enabled())`. -Use consistent names for {noun} (nouns) in API functions: buffer is called -"buf" everywhere, not "buffer" in some places and "buf" in others. +Use consistent names for {topic} in API functions: buffer is called "buf" +everywhere, not "buffer" in some places and "buf" in others. - buf: Buffer - chan: |channel| - cmd: Command @@ -401,12 +439,12 @@ Use consistent names for {noun} (nouns) in API functions: buffer is called - win: Window Do NOT use these deprecated nouns: - - buffer + - buffer Use "buf" instead - callback Use on_foo instead - - command - - window + - command Use "cmd" instead + - window Use "win" instead - *dev-name-events* + *dev-name-events* Use the "on_" prefix to name event-handling callbacks and also the interface for "registering" such handlers (on_key). The dual nature is acceptable to avoid a confused collection of naming conventions for these related concepts. @@ -420,14 +458,17 @@ Use this format to name API (RPC) events: > Example: > nvim_buf_changedtick_event < - *dev-name-api* + *dev-api-name* Use this format to name new RPC |API| functions: > - nvim_{noun}_{verb}_{arbitrary-qualifiers} + nvim_{topic}_{verb}_{arbitrary-qualifiers} -If the function acts on an object then {noun} is the name of that object -(e.g. "buf" or "win"). If the function operates in a "global" context then -{noun} is usually omitted (but consider "namespacing" your global operations -with a {noun} that groups functions under a common concept). +Do not add new nvim_buf/nvim_win/nvim_tabpage APIs, unless you are certain the +concept will NEVER be applied to more than one "scope". That is, {topic} +should be the TOPIC ("ns", "extmark", "option", …) that acts on the scope(s) +(buf/win/tabpage/global), it should NOT be the scope. Instead the scope should +be a parameter (typically manifest as mutually-exclusive buf/win/… flags like +|nvim_get_option_value()|, or less commonly as a `scope: string` field like +|nvim_get_option_info2()|). - Example: `nvim_get_keymap('v')` operates in a global context (first parameter is not a Buffer). The "get" verb indicates that it gets anything @@ -437,9 +478,61 @@ with a {noun} that groups functions under a common concept). and uses the "del" {verb}. -API-CLIENT *dev-api-client* +INTERFACE PATTERNS *dev-api-patterns* + +Prefer adding a single `nvim_{topic}_{verb}_…` interface for a given topic. + +Example: > - *api-client* + nvim_ns_add( + ns_id: int, + filter: { + handle: integer (buf/win/tabpage id) + scope: "global" | "win" | "buf" | "tabpage" + } + ): { ok: boolean } + + nvim_ns_get( + ns_id: int, + filter: { + handle: integer (buf/win/tabpage id) + scope: "global" | "win" | "buf" | "tabpage" + } + ): { ids: int[] } + + nvim_ns_del( + ns_id: int, + filter: { + handle: integer (buf/win/tabpage id) + scope: "global" | "win" | "buf" | "tabpage" + } + ): { ok: boolean } + + +Anti-Example: + +Creating separate `nvim_xx`, `nvim_buf_xx`, `nvim_win_xx`, and +`nvim_tabpage_xx`, functions all for the same `xx` topic, requires 4x the +amount of documentation, tests, boilerplate, and interfaces, which users must +comprehend, maintainers must maintain, etc. Thus the following is NOT +recommended (compare these 12(!) functions to the above 3 functions): > + + nvim_add_ns(…) + nvim_buf_add_ns(…) + nvim_win_add_ns(…) + nvim_tabpage_add_ns(…) + nvim_del_ns(…) + nvim_buf_del_ns(…) + nvim_win_del_ns(…) + nvim_tabpage_del_ns(…) + nvim_get_ns(…) + nvim_buf_get_ns(…) + nvim_win_get_ns(…) + nvim_tabpage_get_ns(…) + +API-CLIENT *dev-api-client* + + *api-client* API clients wrap the Nvim |API| to provide idiomatic "SDKs" for their respective platforms (see |jargon|). You can build a new API client for your favorite platform or programming language. @@ -447,9 +540,10 @@ favorite platform or programming language. List of API clients: https://github.com/neovim/neovim/wiki/Related-projects#api-clients - *pynvim* -The Python client is the reference implementation for API clients. - https://github.com/neovim/pynvim + *node-client* *pynvim* +These clients can be considered the "reference implementation" for API clients: +- https://github.com/neovim/node-client +- https://github.com/neovim/pynvim Standard Features ~ @@ -500,7 +594,7 @@ API client implementation guidelines ~ https://github.com/msgpack-rpc/msgpack-rpc -EXTERNAL UI *dev-ui* +EXTERNAL UI *dev-ui* External UIs should be aware of the |api-contract|. In particular, future versions of Nvim may add new items to existing events. The API is strongly @@ -526,6 +620,8 @@ External UIs are expected to implement these common features: published in this event. See also "mouse_on", "mouse_off". - UIs generally should NOT set |$NVIM_APPNAME| (unless explicitly requested by the user). +- Support the text decorations/attributes given by |ui-event-hl_attr_define|. + The "url" attr should be presented as a clickable hyperlink. vim:tw=78:ts=8:sw=4:et:ft=help:norl: diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index c9e783ca62..36616b9a0d 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -371,8 +371,10 @@ Lua module: vim.diagnostic *diagnostic-api* A table with the following keys: Fields: ~ - • {namespace}? (`integer`) Limit diagnostics to the given namespace. - • {lnum}? (`integer`) Limit diagnostics to the given line number. + • {namespace}? (`integer[]|integer`) Limit diagnostics to one or more + namespaces. + • {lnum}? (`integer`) Limit diagnostics to those spanning the + specified line number. • {severity}? (`vim.diagnostic.SeverityFilter`) See |diagnostic-severity|. @@ -387,7 +389,7 @@ Lua module: vim.diagnostic *diagnostic-api* |nvim_win_get_cursor()|. • {wrap}? (`boolean`, default: `true`) Whether to loop around file or not. Similar to 'wrapscan'. - • {severity} (`vim.diagnostic.Severity`) See + • {severity}? (`vim.diagnostic.SeverityFilter`) See |diagnostic-severity|. • {float}? (`boolean|vim.diagnostic.Opts.Float`, default: `true`) If `true`, call @@ -432,7 +434,7 @@ Lua module: vim.diagnostic *diagnostic-api* • {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) + • {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 @@ -496,6 +498,7 @@ Lua module: vim.diagnostic *diagnostic-api* diagnostic instead of prepending it. Overrides the setting from |vim.diagnostic.config()|. • {focus_id}? (`string`) + • {border}? (`string`) see |nvim_open_win()|. *vim.diagnostic.Opts.Signs* @@ -615,23 +618,20 @@ count({bufnr}, {opts}) *vim.diagnostic.count()* (`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. +enable({enable}, {filter}) *vim.diagnostic.enable()* + Enables or disables diagnostics. - Parameters: ~ - • {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. + To "toggle", pass the inverse of `is_enabled()`: >lua + vim.diagnostic.enable(not vim.diagnostic.is_enabled()) +< Parameters: ~ - • {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. + • {enable} (`boolean?`) true/nil to enable, false to disable + • {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. + • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for + all. + • {bufnr}? (`integer`) Buffer number, or 0 for current + buffer, or `nil` for all buffers. fromqflist({list}) *vim.diagnostic.fromqflist()* Convert a list of quickfix items to a list of diagnostics. @@ -732,7 +732,7 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()* diagnostics, use |vim.diagnostic.reset()|. To hide diagnostics and prevent them from re-displaying, use - |vim.diagnostic.disable()|. + |vim.diagnostic.enable()|. Parameters: ~ • {namespace} (`integer?`) Diagnostic namespace. When omitted, hide @@ -740,14 +740,15 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()* • {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. +is_enabled({filter}) *vim.diagnostic.is_enabled()* + Check whether diagnostics are enabled. Parameters: ~ - • {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. + • {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. + • {ns_id}? (`integer`) Diagnostic namespace, or `nil` for + all. + • {bufnr}? (`integer`) Buffer number, or 0 for current + buffer, or `nil` for all buffers. Return: ~ (`boolean`) diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index 1a4572e94a..662d89895d 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -632,9 +632,12 @@ list of the current window. :[count]arge[dit][!] [++opt] [+cmd] {name} .. *:arge* *:argedit* Add {name}s to the argument list and edit it. - When {name} already exists in the argument list, this - entry is edited. - This is like using |:argadd| and then |:edit|. + There is no check for duplicates, it is possible to + add a file to the argument list twice |:argded|. + This is like using |:argadd| and then |:edit| (with + the small exception that |:edit| does not change the + argument list, so the argument list pointer isn't + changed). Spaces in filenames have to be escaped with "\". [count] is used like with |:argadd|. If the current file cannot be |abandon|ed {name}s will @@ -653,12 +656,12 @@ list of the current window. If the argument list is "a b c", and "b" is the current argument, then these commands result in: command new argument list ~ - :argadd x a b x c - :0argadd x x a b c - :1argadd x a x b c - :$argadd x a b c x + :argadd x a [b] x c + :0argadd x x a [b] c + :1argadd x a x [b] c + :$argadd x a [b] c x And after the last one: - :+2argadd y a b c x y + :+2argadd y a [b] c x y There is no check for duplicates, it is possible to add a file to the argument list twice. You can use |:argdedupe| to fix it afterwards: > diff --git a/runtime/doc/editorconfig.txt b/runtime/doc/editorconfig.txt index a2281a7b7c..0b20c77801 100644 --- a/runtime/doc/editorconfig.txt +++ b/runtime/doc/editorconfig.txt @@ -3,79 +3,35 @@ NVIM REFERENCE MANUAL + Type |gO| to see the table of contents. +============================================================================== EditorConfig integration *editorconfig* -Nvim supports EditorConfig. When a file is opened, Nvim searches all parent -directories of that file for ".editorconfig" files, parses them, and applies -any properties that match the opened file. Think of it like 'modeline' for an -entire (recursive) directory. For more information see -https://editorconfig.org/. +Nvim supports EditorConfig. When a file is opened, after running |ftplugin|s +and |FileType| autocommands, Nvim searches all parent directories of that file +for ".editorconfig" files, parses them, and applies any properties that match +the opened file. Think of it like 'modeline' for an entire (recursive) +directory. For more information see https://editorconfig.org/. *g:editorconfig* *b:editorconfig* -EditorConfig is enabled by default. To disable it, add to your config: >lua +EditorConfig is enabled by default. To disable it, add to your config: >lua vim.g.editorconfig = false < + (Vimscript: `let g:editorconfig = v:false`). It can also be disabled per-buffer by setting the |b:editorconfig| buffer-local variable to `false`. Nvim stores the applied properties in |b:editorconfig| if it is not `false`. - *editorconfig-properties* -The following properties are supported by default: - - *editorconfig_root* -root If "true", then stop searching for .editorconfig files - in parent directories. This property must be at the - top-level of the .editorconfig file (i.e. it must not - be within a glob section). - - *editorconfig_charset* -charset One of "utf-8", "utf-8-bom", "latin1", "utf-16be", or - "utf-16le". Sets the 'fileencoding' and 'bomb' - options. - - *editorconfig_end_of_line* -end_of_line One of "lf", "crlf", or "cr". These correspond to - setting 'fileformat' to "unix", "dos", or "mac", - respectively. - - *editorconfig_indent_style* -indent_style One of "tab" or "space". Sets the 'expandtab' option. - - *editorconfig_indent_size* -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 - trailing newline as its last byte. Sets the - 'fixendofline' and 'endofline' options. - - *editorconfig_max_line_length* -max_line_length A number indicating the maximum length of a single - line. Sets the 'textwidth' option. - - *editorconfig_tab_width* -tab_width The display size of a single tab character. Sets the - 'tabstop' option. - - *editorconfig_trim_trailing_whitespace* -trim_trailing_whitespace - When "true", trailing whitespace is automatically - removed when the buffer is written. - *editorconfig-custom-properties* + New properties can be added by adding a new entry to the "properties" table. The table key is a property name and the value is a callback function which -accepts the number of the buffer to be modified, the value of the property -in the .editorconfig file, and (optionally) a table containing all of the -other properties and their values (useful for properties which depend on other +accepts the number of the buffer to be modified, the value of the property in +the `.editorconfig` file, and (optionally) a table containing all of the other +properties and their values (useful for properties which depend on other properties). The value is always a string and must be coerced if necessary. Example: >lua @@ -86,4 +42,48 @@ Example: >lua vim.b[bufnr].foo = val end < - vim:tw=78:ts=8:et:sw=4:ft=help:norl: + + *editorconfig-properties* + +The following properties are supported by default: + + +charset *editorconfig.charset* + One of `"utf-8"`, `"utf-8-bom"`, `"latin1"`, `"utf-16be"`, or + `"utf-16le"`. Sets the 'fileencoding' and 'bomb' options. + +end_of_line *editorconfig.end_of_line* + One of `"lf"`, `"crlf"`, or `"cr"`. These correspond to setting + 'fileformat' to "unix", "dos", or "mac", respectively. + +indent_size *editorconfig.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. + +indent_style *editorconfig.indent_style* + One of `"tab"` or `"space"`. Sets the 'expandtab' option. + +insert_final_newline *editorconfig.insert_final_newline* + `"true"` or `"false"` to ensure the file always has a trailing newline as + its last byte. Sets the 'fixendofline' and 'endofline' options. + +max_line_length *editorconfig.max_line_length* + A number indicating the maximum length of a single line. Sets the + 'textwidth' option. + +root *editorconfig.root* + If "true", then stop searching for `.editorconfig` files in parent + directories. This property must be at the top-level of the `.editorconfig` + file (i.e. it must not be within a glob section). + +tab_width *editorconfig.tab_width* + The display size of a single tab character. Sets the 'tabstop' option. + +trim_trailing_whitespace *editorconfig.trim_trailing_whitespace* + When `"true"`, trailing whitespace is automatically removed when the + buffer is written. + + + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index ef416fe56f..7b4dba5a50 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2144,6 +2144,10 @@ text... :cons[t] {var-name} = {expr1} :cons[t] [{name1}, {name2}, ...] = {expr1} :cons[t] [{name}, ..., ; {lastname}] = {expr1} +:cons[t] {var-name} =<< [trim] [eval] {marker} +text... +text... +{marker} Similar to |:let|, but additionally lock the variable after setting the value. This is the same as locking the variable with |:lockvar| just after |:let|, thus: > diff --git a/runtime/doc/faq.txt b/runtime/doc/faq.txt index 09bf829512..7d2774c191 100644 --- a/runtime/doc/faq.txt +++ b/runtime/doc/faq.txt @@ -29,13 +29,6 @@ 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 @@ -288,19 +281,17 @@ 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 +If there's no results, you might not be using a UTF-8 locale. See these issues: +- https://github.com/neovim/neovim/issues/1601 +- https://github.com/neovim/neovim/issues/1858 +- 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 +(see also https://github.com/tmux/tmux/issues/131#issuecomment-145853211). The corresponding timeout needs to be tweaked to a low value (10-20ms). `.tmux.conf`: @@ -317,11 +308,11 @@ corresponding timeout needs to be tweaked to a low value (10-20ms). "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 +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. +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|. @@ -329,7 +320,7 @@ Nvim 0.3 mimics the Vim behavior while still fully supporting ALT mappings. See 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: +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 @@ -339,10 +330,11 @@ 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. +- https://github.com/neovim/neovim/issues/10008 +- https://github.com/neovim/neovim/issues/10116 +- https://github.com/neovim/neovim/issues/12288 +- 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. @@ -400,8 +392,8 @@ 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. +root user, then later run an unprivileged `make`. To fix this, run +`rm -rf build` and try again. GENERATING HELPTAGS FAILED ~ @@ -434,7 +426,7 @@ WHY EMBED LUA INSTEAD OF X? ~ - 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 + 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 diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 071a45c9c3..5eae78744c 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -155,6 +155,8 @@ variables can be used to overrule the filetype used for certain extensions: `*.inc` g:filetype_inc `*.lsl` g:filetype_lsl `*.m` g:filetype_m |ft-mathematica-syntax| + `*.markdown,*.mdown,*.mkd,*.mkdn,*.mdwn,*.md` + g:filetype_md |ft-pandoc-syntax| `*.mod` g:filetype_mod `*.p` g:filetype_p |ft-pascal-syntax| `*.pl` g:filetype_pl @@ -400,6 +402,31 @@ So to enable this only for ruby, set the following variable: > If both, the global `plugin_exec` and the `<filetype>_exec` specific variable are set, the filetype specific variable should have precedent. + +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 + + +ARDUINO *ft-arduino-plugin* + +By default the following options are set, in accordance with the default +settings of Arduino IDE: > + + setlocal expandtab tabstop=2 softtabstop=2 shiftwidth=2 + +To disable this behavior, set the following variable in your vimrc: > + + let g:arduino_recommended_style = 0 + + AWK *ft-awk-plugin* Support for features specific to GNU Awk, like @include, can be enabled by @@ -527,18 +554,6 @@ 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: @@ -587,6 +602,37 @@ The mapping can be disabled with: > let g:no_gprof_maps = 1 +JAVA *ft-java-plugin* + +Whenever the variable "g:ftplugin_java_source_path" is defined and its value +is a filename whose extension is either ".jar" or ".zip", e.g.: > + let g:ftplugin_java_source_path = '/path/to/src.jar' + let g:ftplugin_java_source_path = '/path/to/src.zip' +< +and the |zip| plugin has already been sourced, the |gf| command can be used to +open the archive and the |n| command can be used to look for the selected type +and the <Return> key can be used to load a listed file. + +Note that the effect of using the "gf" command WITHIN a buffer loaded with the +Zip plugin depends on the version of the Zip plugin. For the Zip plugin +versions that do not support Jar type archives, consider creating symbolic +links with the ".zip" extension for each Jar archive of interest and assigning +any such file to the variable from now on. + +Otherwise, for the defined variable "g:ftplugin_java_source_path", the local +value of the 'path' option will be further modified by prefixing the value of +the variable, e.g.: > + let g:ftplugin_java_source_path = $JDK_SRC_PATH + let &l:path = g:ftplugin_java_source_path . ',' . &l:path +< +and the "gf" command can be used on a fully-qualified type to look for a file +in the "path" and to try to load it. + +Remember to manually trigger the |FileType| event from a buffer with a Java +file loaded in it each time after assigning a new value to the variable: > + doautocmd FileType +< + MAIL *ft-mail-plugin* Options: @@ -626,8 +672,10 @@ Man Open the manpage for the <cWORD> (man buffers) or <cword> (non-man buffers) under the cursor. Man! Display the current buffer contents as a manpage. -|:Man| accepts command modifiers. For example, to use a vertical split: > +|:Man| accepts command modifiers. For example, to use a vertical split: >vim :vertical Man printf +To reuse the current window: >vim + :hide Man printf Local mappings: K or CTRL-] Jump to the manpage for the <cWORD> under the @@ -647,14 +695,14 @@ Variables: empty. Enabled by default. Set |FALSE| to enable soft wrapping. -To use Nvim as a manpager: > +To use Nvim as a manpager: >sh export MANPAGER='nvim +Man!' Note that when running `man` from the shell and with that `MANPAGER` in your environment, `man` will pre-format the manpage using `groff`. Thus, Nvim will inevitably display the manual page as it was passed to it from stdin. One of the caveats of this is that the width will _always_ be hard-wrapped and not -soft wrapped as with `g:man_hardwrap=0`. You can set in your environment: > +soft wrapped as with `g:man_hardwrap=0`. You can set in your environment: >sh export MANWIDTH=999 So `groff`'s pre-formatting output will be the same as with `g:man_hardwrap=0` i.e soft-wrapped. @@ -662,6 +710,10 @@ So `groff`'s pre-formatting output will be the same as with `g:man_hardwrap=0` i To disable bold highlighting: > :highlight link manBold Normal +An alternative to using `MANPAGER` in shell can be redefined `man`, for example: >sh + man() { + nvim "+hide Man $1" + } MARKDOWN *ft-markdown-plugin* @@ -942,6 +994,31 @@ The mappings can be disabled with: > let g:no_vim_maps = 1 +ZIG *ft-zig-plugin* + + *g:zig_recommended_style* +By default the following indentation options are set, in accordance with Zig's +recommended style (https://ziglang.org/documentation/master/): > + + setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8 +< +To disable this behavior, set |g:zig_recommended_style| to 0: > + + let g:zig_recommended_style = 0 +< + *g:zig_std_dir* +The path to the Zig standard library. The Zig |ftplugin| reads |g:zig_std_dir| +and appends it to the 'path' for Zig files. Where the Zig standard library +is located is system and installation method dependent. + +One can automatically set |g:zig_std_dir| using `zig env`: > + + let g:zig_std_dir = json_decode(system('zig env'))['std_dir'] +< +This can, for example, be put in a FileType |:autocmd| or user |ftplugin| to +only load when a Zig file is opened. + + ZIMBU *ft-zimbu-plugin* The Zimbu filetype plugin defines mappings to move to the start and end of diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index bf62dba539..a64d722177 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -443,18 +443,18 @@ You can define the special menu "PopUp". This is the menu that is displayed when the right mouse button is pressed, if 'mousemodel' is set to popup or popup_setpos. -The default "PopUp" menu is: > - aunmenu PopUp - vnoremenu PopUp.Cut "+x - vnoremenu PopUp.Copy "+y - anoremenu PopUp.Paste "+gP - vnoremenu PopUp.Paste "+P - vnoremenu PopUp.Delete "_x - nnoremenu PopUp.Select\ All ggVG - vnoremenu PopUp.Select\ All gg0oG$ - inoremenu PopUp.Select\ All <C-Home><C-O>VG - anoremenu PopUp.-1- <Nop> - anoremenu PopUp.How-to\ disable\ mouse <Cmd>help disable-mouse<CR> +The default "PopUp" menu is: >vim + vnoremenu PopUp.Cut "+x + vnoremenu PopUp.Copy "+y + anoremenu PopUp.Paste "+gP + vnoremenu PopUp.Paste "+P + vnoremenu PopUp.Delete "_x + nnoremenu PopUp.Select\ All ggVG + vnoremenu PopUp.Select\ All gg0oG$ + inoremenu PopUp.Select\ All <C-Home><C-O>VG + anoremenu PopUp.Inspect <Cmd>Inspect<CR> + anoremenu PopUp.-1- <Nop> + anoremenu PopUp.How-to\ disable\ mouse <Cmd>help disable-mouse<CR> < Showing What Menus Are Mapped To *showing-menus* diff --git a/runtime/doc/pi_health.txt b/runtime/doc/health.txt index bcc933d8b2..e879f11351 100644 --- a/runtime/doc/pi_health.txt +++ b/runtime/doc/health.txt @@ -1,11 +1,14 @@ -*pi_health.txt* Healthcheck framework +*health.txt* Nvim -Author: TJ DeVries <devries.timothyj@gmail.com> - Type |gO| to see the table of contents. + NVIM REFERENCE MANUAL + + + Type |gO| to see the table of contents. ============================================================================== -Introduction *health* +Checkhealth *health* + health.vim is a minimal framework to help users troubleshoot configuration and any other environment conditions that a plugin might care about. Nvim ships @@ -18,12 +21,11 @@ To run all healthchecks, use: >vim < Plugin authors are encouraged to write new healthchecks. |health-dev| -============================================================================== -Commands *health-commands* +Commands *health-commands* - *:che* *:checkhealth* + *:che* *:checkhealth* :che[ckhealth] Run all healthchecks. - *E5009* + *E5009* Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to find the standard "runtime files" for syntax highlighting, filetype-specific behavior, and standard plugins (including @@ -33,7 +35,7 @@ Commands *health-commands* :che[ckhealth] {plugins} Run healthcheck(s) for one or more plugins. E.g. to run only the standard Nvim healthcheck: >vim - :checkhealth nvim + :checkhealth vim.health < To run the healthchecks for the "foo" and "bar" plugins (assuming they are on 'runtimepath' and they have implemented @@ -46,33 +48,8 @@ Commands *health-commands* :checkhealth vim.lsp vim.treesitter :checkhealth vim* < -============================================================================== -Functions *health-functions* *vim.health* - -The Lua "health" module can be used to create new healthchecks. To get started -see |health-dev|. -vim.health.start({name}) *vim.health.start()* - Starts a new report. Most plugins should call this only once, but if - you want different sections to appear in your report, call this once - per section. - -vim.health.info({msg}) *vim.health.info()* - Reports an informational message. - -vim.health.ok({msg}) *vim.health.ok()* - Reports a "success" message. - -vim.health.warn({msg} [, {advice}]) *vim.health.warn()* - Reports a warning. {advice} is an optional list of suggestions to - present to the user. - -vim.health.error({msg} [, {advice}]) *vim.health.error()* - Reports an error. {advice} is an optional list of suggestions to - present to the user. - -============================================================================== -Create a healthcheck *health-dev* +Create a healthcheck *health-dev* *vim.health* Healthchecks are functions that check the user environment, configuration, or any other prerequisites that a plugin cares about. Nvim ships with @@ -119,4 +96,39 @@ with your plugin name: >lua return M -vim:et:tw=78:ts=8:ft=help:fdm=marker +error({msg}, {...}) *vim.health.error()* + Reports an error. + + Parameters: ~ + • {msg} (`string`) + • {...} (`string|string[]`) Optional advice + +info({msg}) *vim.health.info()* + Reports an informational message. + + Parameters: ~ + • {msg} (`string`) + +ok({msg}) *vim.health.ok()* + Reports a "success" message. + + Parameters: ~ + • {msg} (`string`) + +start({name}) *vim.health.start()* + Starts a new report. Most plugins should call this only once, but if you + want different sections to appear in your report, call this once per + section. + + Parameters: ~ + • {name} (`string`) + +warn({msg}, {...}) *vim.health.warn()* + Reports a warning. + + Parameters: ~ + • {msg} (`string`) + • {...} (`string|string[]`) Optional advice + + + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/hebrew.txt b/runtime/doc/hebrew.txt index e38385e13a..c19b4b9835 100644 --- a/runtime/doc/hebrew.txt +++ b/runtime/doc/hebrew.txt @@ -14,7 +14,7 @@ currently helping support these features. ------------------------------------------------------------------------------ Introduction -Hebrew-specific options are 'hkmap', 'hkmapp' 'keymap'=hebrew and 'aleph'. +Hebrew-specific 'keymap' values are "hebrew" and "hebrewp". Hebrew-useful options are 'delcombine', 'allowrevins', 'revins', 'rightleft' and 'rightleftcmd'. @@ -30,7 +30,7 @@ Details + 'rightleft' ('rl') sets window orientation to right-to-left. This means that the logical text 'ABC' will be displayed as 'CBA', and will start drawing at the right edge of the window, not the left edge. - + 'keymap' ('kmp') sets keyboard mapping. use values "hebrew" or "heprewp" + + 'keymap' ('kmp') sets keyboard mapping. use values "hebrew" or "hebrewp" (the latter option enables phonetic mapping) + 'delcombine' ('deco'), boolean, allows one to remove the niqud or te`amim by pressing 'x' on a character (with associated niqud). @@ -41,35 +41,23 @@ Details + Encoding: + Under Unix, ISO 8859-8 encoding (Hebrew letters codes: 224-250). + Under MS DOS, PC encoding (Hebrew letters codes: 128-154). - These are defaults, that can be overridden using the 'aleph' option. + You should prefer using UTF8, as it supports the combining-characters ('deco' does nothing if UTF8 encoding is not active). + Vim arguments: - + `vim -H file` starts editing a Hebrew file, i.e. 'rightleft' and 'hkmap' - are set. + + `vim -H file` starts editing a Hebrew file, i.e. 'rightleft' is set and + 'keymap' is set to "hebrew". + Keyboard: - + The 'allowrevins' option enables the CTRL-_ command in Insert mode and - in Command-line mode. + + The 'allowrevins' option enables the CTRL-_ command in Insert mode. - + CTRL-_ in insert/replace modes toggles 'revins' and 'hkmap' as follows: - - When in rightleft window, 'revins' is toggled, since - English will likely be inserted in this case. - - When in norightleft window, 'revins' is toggled, since Hebrew - will likely be inserted in this case. + + CTRL-_ in Insert mode toggles 'revins'. CTRL-_ moves the cursor to the end of the typed text. - + CTRL-_ in command mode only toggles keyboard mapping (see Bugs below). - This setting is independent of 'hkmap' option, which only applies to - insert/replace mode. - Note: On some keyboards, CTRL-_ is mapped to CTRL-?. - + Keyboard mapping while 'hkmap' is set (standard Israeli keyboard): + + Keyboard mapping while 'keymap' is "hebrew" (standard Israeli keyboard): q w e r t y u i o p / ' ק ר א ט ו ן ם פ @@ -80,11 +68,8 @@ Details z x c v b n m , . / ז ס ב ה נ מ צ ת ץ . - This is also the keymap when 'keymap=hebrew' is set. The advantage of - 'keymap' is that it works properly when using UTF8, e.g. it inserts the - correct characters; 'hkmap' does not. The 'keymap' keyboard can also - insert niqud and te`amim. To see what those mappings are, look at the - keymap file 'hebrew.vim' etc. + The 'keymap' keyboard can also insert niqud and te`amim. To see what + those mappings are, look at the keymap file hebrew.vim etc. Typing backwards @@ -102,13 +87,7 @@ If the 'showmode' option is set, "-- REVERSE INSERT --" will be shown in the status line when reverse Insert mode is active. When the 'allowrevins' option is set, reverse Insert mode can be also entered -via CTRL-_, which has some extra functionality: First, keyboard mapping is -changed according to the window orientation -- if in a left-to-right window, -'revins' is used to enter Hebrew text, so the keyboard changes to Hebrew -('hkmap' is set); if in a right-to-left window, 'revins' is used to enter -English text, so the keyboard changes to English ('hkmap' is reset). Second, -when exiting 'revins' via CTRL-_, the cursor moves to the end of the typed -text (if possible). +and exited via CTRL-_. ------------------------------------------------------------------------------ diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index 7545d2c621..43f80101ed 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -114,6 +114,7 @@ API (EXTENSIBILITY/SCRIPTING/PLUGINS) |vimscript-functions| Vimscript functions |testing.txt| Vimscript testing functions |remote-plugin| Nvim remote plugins +|health| Health checking ------------------------------------------------------------------------------ PROGRAMMING LANGUAGE SUPPORT @@ -175,7 +176,6 @@ DEVELOPING NVIM Standard plugins ~ *standard-plugin-list* |pi_gzip.txt| Reading and writing compressed files -|pi_health.txt| Healthcheck framework |pi_msgpack.txt| msgpack utilities |pi_netrw.txt| Reading and writing files over a network |pi_paren.txt| Highlight matching parens diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index efcc6afae9..46b3ab507d 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -305,7 +305,7 @@ Hints for translators: using the "tag@en" notation. - Make a package with all the files and the tags file available for download. Users can drop it in one of the "doc" directories and start use it. - Report this to Bram, so that he can add a link on www.vim.org. + Report to the development team, so they can add a link on www.vim.org. - Use the |:helptags| command to generate the tags files. It will find all languages in the specified directory. diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt index c20143bc6e..a890d531ac 100644 --- a/runtime/doc/indent.txt +++ b/runtime/doc/indent.txt @@ -1232,5 +1232,5 @@ 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 c1a8aec40e..79f10b33f1 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -92,8 +92,7 @@ tag char action in Insert mode ~ CTRL-\ others not used |i_CTRL-]| CTRL-] trigger abbreviation |i_CTRL-^| CTRL-^ toggle use of |:lmap| mappings -|i_CTRL-_| CTRL-_ When 'allowrevins' set: change language - (Hebrew) +|i_CTRL-_| CTRL-_ When 'allowrevins' set: toggle 'revins' <Space> to '~' not used, except '0' and '^' followed by CTRL-D @@ -699,7 +698,6 @@ tag char note action in Normal mode ~ tag char note action in Normal mode ~ ------------------------------------------------------------------------------ ~ -g_CTRL-A g CTRL-A dump a memory profile |g_CTRL-G| g CTRL-G show information about current cursor position |g_CTRL-H| g CTRL-H start Select block mode @@ -1073,8 +1071,6 @@ tag command action in Command-line editing mode ~ CTRL-\ others not used |c_CTRL-]| CTRL-] trigger abbreviation |c_CTRL-^| CTRL-^ toggle use of |:lmap| mappings -|c_CTRL-_| CTRL-_ when 'allowrevins' set: change language - (Hebrew) |c_<Del>| <Del> delete the character under the cursor |c_<Left>| <Left> cursor left diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index 34affb22e9..91b0d41f1c 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -225,11 +225,7 @@ CTRL-Y Insert the character which is above the cursor. able to copy characters from a long line. *i_CTRL-_* -CTRL-_ Switch between insert direction, by toggling 'revins', as follows: - - When in a rightleft window, 'revins' is toggled, - since English will likely be inserted in this case. - - When in a norightleft window, 'revins' is toggled, - since a rightleft language will likely be inserted in this case. +CTRL-_ Switch between insert direction, by toggling 'revins'. CTRL-_ moves the cursor to the end of the typed text. diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index c9211291d0..4c757cc1f6 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -69,11 +69,11 @@ If Nvim crashes, try to get a backtrace. See |debug.txt|. Sponsor Vim/Nvim development *sponsor* *register* Fixing bugs and adding new features takes a lot of time and effort. To show -your appreciation for the work and motivate Bram and others to continue -working on Vim please send a donation. +your appreciation for the work and motivate developers to continue working on +Vim please send a donation. -Since Bram is back to a paid job the money will now be used to help children -in Uganda. See |uganda|. But at the same time donations increase Bram's +The money you donated will be mainly used to help children in Uganda. See +|uganda|. But at the same time donations increase the development team motivation to keep working on Vim! For the most recent information about sponsoring look on the Vim web site: diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index eb37cb2a6f..50fffca497 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -12,7 +12,7 @@ enhanced LSP tools. https://microsoft.github.io/language-server-protocol/ -LSP facilitates features like go-to-definition, find-references, hover, +LSP facilitates features like go-to-definition, find references, hover, completion, rename, format, refactor, etc., using semantic whole-project analysis (unlike |ctags|). @@ -25,26 +25,36 @@ Nvim provides an LSP client, but the servers are provided by third parties. Follow these steps to get LSP features: 1. Install language servers using your package manager or by following the - upstream installation instruction. You can find language servers here: + upstream installation instructions. You can find language servers here: https://microsoft.github.io/language-server-protocol/implementors/servers/ -2. Configure the LSP client per language server. See |vim.lsp.start()| or use - this minimal example as a guide: >lua - - vim.lsp.start({ - name = 'my-server-name', - cmd = {'name-of-language-server-executable'}, - root_dir = vim.fs.dirname(vim.fs.find({'setup.py', 'pyproject.toml'}, { upward = true })[1]), +2. Use |vim.lsp.start()| to start the LSP server (or attach to an existing + one) when a file is opened. Example: >lua + -- Create an event handler for the FileType autocommand + vim.api.nvim_create_autocmd('FileType', { + -- This handler will fire when the buffer's 'filetype' is "python" + pattern = 'python', + callback = function(ev) + vim.lsp.start({ + name = 'my-server-name', + cmd = {'name-of-language-server-executable', '--option', 'arg1', 'arg2'}, + + -- Set the "root directory" to the parent directory of the file in the + -- current buffer (`ev.buf`) that contains either a "setup.py" or a + -- "pyproject.toml" file. Files that share a root directory will reuse + -- the connection to the same LSP server. + root_dir = vim.fs.root(ev.buf, {'setup.py', 'pyproject.toml'}), + }) + end, }) < -3. Check that the server attached to the buffer: > - :lua =vim.lsp.get_clients() +3. Check that the buffer is attached to the server: >vim + :checkhealth lsp -4. Configure keymaps and autocmds to use LSP features. See |lsp-config|. +4. (Optional) Configure keymaps and autocommands to use LSP features. |lsp-config| - *lsp-config* *lsp-defaults* -When the LSP client starts it enables diagnostics |vim.diagnostic| (see +When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see |vim.diagnostic.config()| to customize). It also sets various default options, listed below, if (1) the language server supports the functionality and (2) the options are empty or were set by the builtin runtime (ftplugin) files. The @@ -57,51 +67,47 @@ options are not restored when the LSP client is stopped or detached. |CTRL-W_}| to utilize the language server. - 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via |gq| if the language server supports it. - - To opt out of this use |gw| instead of gq, or set 'formatexpr' on LspAttach. + - To opt out of this use |gw| instead of gq, or clear 'formatexpr' on |LspAttach|. - |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or a custom keymap for `K` exists. + *grr* *gra* *grn* *i_CTRL-S* +Some keymaps are created unconditionally when Nvim starts: +- "grn" is mapped in Normal mode to |vim.lsp.buf.rename()| +- "gra" is mapped in Normal and Visual mode to |vim.lsp.buf.code_action()| +- "grr" is mapped in Normal mode to |vim.lsp.buf.references()| +- CTRL-S is mapped in Insert mode to |vim.lsp.buf.signature_help()| + +If not wanted, these keymaps can be removed at any time using +|vim.keymap.del()| or |:unmap| (see also |gr-default|). + *lsp-defaults-disable* -To override the above defaults, set or unset the options on |LspAttach|: >lua +To override or delete any of the above defaults, set or unset the options on +|LspAttach|: >lua + vim.api.nvim_create_autocmd('LspAttach', { callback = function(ev) vim.bo[ev.buf].formatexpr = nil vim.bo[ev.buf].omnifunc = nil - vim.keymap.del("n", "K", { buffer = ev.buf }) - end, - }) - -To use other LSP features like hover, rename, etc. you can set other keymaps -on |LspAttach|. Example: >lua - vim.api.nvim_create_autocmd('LspAttach', { - callback = function(args) - vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf }) + vim.keymap.del('n', 'K', { buffer = ev.buf }) end, }) +< + *lsp-config* +To use other LSP features, set keymaps on |LspAttach|. Not all language +servers provide the same capabilities. To ensure you only set keymaps if the +language server supports a feature, guard keymaps behind capability checks. +Example: >lua -The most common functions are: - -- |vim.lsp.buf.hover()| -- |vim.lsp.buf.format()| -- |vim.lsp.buf.references()| -- |vim.lsp.buf.implementation()| -- |vim.lsp.buf.code_action()| - - -Not all language servers provide the same capabilities. To ensure you only set -keymaps if the language server supports a feature, you can guard the keymap -calls behind capability checks: ->lua vim.api.nvim_create_autocmd('LspAttach', { callback = function(args) local client = vim.lsp.get_client_by_id(args.data.client_id) - if client.server_capabilities.hoverProvider then - vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf }) + if client.supports_method('textDocument/implementation') then + -- Create a keymap for vim.lsp.buf.implementation end end, }) < - To learn what capabilities are available you can run the following command in a buffer with a started LSP client: >vim @@ -182,6 +188,7 @@ won't run if your server doesn't support them. - textDocument/hover - textDocument/implementation* - textDocument/inlayHint +- textDocument/prepareTypeHierarchy - textDocument/publishDiagnostics - textDocument/rangeFormatting - textDocument/references @@ -190,6 +197,8 @@ won't run if your server doesn't support them. - textDocument/semanticTokens/full/delta - textDocument/signatureHelp - textDocument/typeDefinition* +- typeHierarchy/subtypes +- typeHierarchy/supertypes - window/logMessage - window/showMessage - window/showDocument @@ -454,23 +463,44 @@ You probably want these inside a |ColorScheme| autocommand. 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 +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): + +@lsp.type.class Identifiers that declare or reference a class type +@lsp.type.comment Tokens that represent a comment +@lsp.type.decorator Identifiers that declare or reference decorators and annotations +@lsp.type.enum Identifiers that declare or reference an enumeration type +@lsp.type.enumMember Identifiers that declare or reference an enumeration property, constant, or member +@lsp.type.event Identifiers that declare an event property +@lsp.type.function Identifiers that declare a function +@lsp.type.interface Identifiers that declare or reference an interface type +@lsp.type.keyword Tokens that represent a language keyword +@lsp.type.macro Identifiers that declare a macro +@lsp.type.method Identifiers that declare a member function or method +@lsp.type.modifier Tokens that represent a modifier +@lsp.type.namespace Identifiers that declare or reference a namespace, module, or package +@lsp.type.number Tokens that represent a number literal +@lsp.type.operator Tokens that represent an operator +@lsp.type.parameter Identifiers that declare or reference a function or method parameters +@lsp.type.property Identifiers that declare or reference a member property, member field, or member variable +@lsp.type.regexp Tokens that represent a regular expression literal +@lsp.type.string Tokens that represent a string literal +@lsp.type.struct Identifiers that declare or reference a struct type +@lsp.type.type Identifiers that declare or reference a type that is not covered above +@lsp.type.typeParameter Identifiers that declare or reference a type parameter +@lsp.type.variable Identifiers that declare or reference a local or global variable + +@lsp.mod.abstract Types and member functions that are abstract +@lsp.mod.async Functions that are marked async +@lsp.mod.declaration Declarations of symbols +@lsp.mod.defaultLibrary Symbols that are part of the standard library +@lsp.mod.definition Definitions of symbols, for example, in header files +@lsp.mod.deprecated Symbols that should no longer be used +@lsp.mod.documentation Occurrences of symbols in documentation +@lsp.mod.modification Variable references where the variable is assigned to +@lsp.mod.readonly Readonly variables and member fields (constants) +@lsp.mod.static Class members (static members) ============================================================================== EVENTS *lsp-events* @@ -533,14 +563,14 @@ 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 - |vim.lsp.status()| to get an aggregate message + |vim.lsp.status()| to get an aggregate message. If the server sends a "work done progress", the `pattern` is set to `kind` (one of `begin`, `report` or `end`). When used from Lua, the event contains a `data` table with `client_id` and - `result` properties. `result` will contain the request params sent by the - server. + `params` properties. `params` will contain the request params sent by the + server (see `lsp.ProgressParams`). Example: >vim autocmd LspProgress * redrawstatus @@ -683,8 +713,8 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) milliseconds to wait for a result. Return (multiple): ~ - (`table<integer, {err: lsp.ResponseError, result: any}>?`) result Map - of client_id:request_result. + (`table<integer, {error: 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. @@ -812,7 +842,7 @@ start({config}, {opts}) *vim.lsp.start()* vim.lsp.start({ name = 'my-server-name', cmd = {'name-of-language-server-executable'}, - root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]), + root_dir = vim.fs.root(0, {'pyproject.toml', 'setup.py'}), }) < @@ -824,7 +854,7 @@ start({config}, {opts}) *vim.lsp.start()* |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 + |vim.fs.root()| and |vim.fs.dirname()| to detect the root by traversing the file system upwards starting from the current directory until either a `pyproject.toml` or `setup.py` file is found. • `workspace_folders` list of `{ uri:string, name: string }` tables @@ -845,12 +875,14 @@ start({config}, {opts}) *vim.lsp.start()* |vim.lsp.ClientConfig|. • {opts} (`table?`) Optional keyword arguments • {reuse_client} - (`fun(client: vim.lsp.Client, config: table): boolean`) + (`fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): 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} (`integer`) Buffer handle to attach to if starting or re-using a client (0 for current). + • {silent}? (`boolean`) Suppress error reporting if the LSP + server fails to start (default false). Return: ~ (`integer?`) client_id @@ -862,10 +894,11 @@ start_client({config}) *vim.lsp.start_client()* • {config} (`vim.lsp.ClientConfig`) Configuration for the server. See |vim.lsp.ClientConfig|. - Return: ~ + Return (multiple): ~ (`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. + (`string?`) Error message, if any status() *vim.lsp.status()* Consumes the latest progress messages from all clients and formats them as @@ -886,8 +919,8 @@ stop_client({client_id}, {force}) *vim.lsp.stop_client()* for this client, then force-shutdown is attempted. Parameters: ~ - • {client_id} (`integer|vim.lsp.Client`) id or |vim.lsp.Client| object, - or list thereof + • {client_id} (`integer|integer[]|vim.lsp.Client[]`) id, list of id's, + or list of |vim.lsp.Client| objects • {force} (`boolean?`) shutdown forcefully tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()* @@ -978,9 +1011,9 @@ Lua module: vim.lsp.client *lsp-client* 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`) + • {allow_incremental_sync}? (`boolean`, + default: `true`) Allow using incremental + sync for buffer edits • {debounce_text_changes} (`integer`, default: `150`) Debounce `didChange` notifications to the server by the given number in @@ -995,7 +1028,7 @@ Lua module: vim.lsp.client *lsp-client* • {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?`) + • {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 @@ -1049,7 +1082,7 @@ Lua module: vim.lsp.client *lsp-client* *vim.lsp.ClientConfig* Fields: ~ - • {cmd} (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient?`) + • {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 @@ -1149,9 +1182,9 @@ Lua module: vim.lsp.client *lsp-client* 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`) + • {allow_incremental_sync}? (`boolean`, default: + `true`) Allow using incremental sync for + buffer edits • {debounce_text_changes} (`integer`, default: `150`) Debounce `didChange` notifications to the server by the given number in @@ -1187,12 +1220,11 @@ Lua module: vim.lsp.buf *lsp-buf* 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 + If you prefer loclist instead of qflist: >lua + vim.lsp.buf.definition({ loclist = true }) + vim.lsp.buf.references(nil, { loclist = true }) < + • {loclist}? (`boolean`) *vim.lsp.LocationOpts* Extends: |vim.lsp.ListOpts| @@ -1221,30 +1253,30 @@ add_workspace_folder({workspace_folder}) clear_references() *vim.lsp.buf.clear_references()* Removes document highlights from current buffer. -code_action({options}) *vim.lsp.buf.code_action()* +code_action({opts}) *vim.lsp.buf.code_action()* Selects a code action available at the current cursor position. Parameters: ~ - • {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`) List of LSP `CodeActionKind`s used to - filter the code actions. Most language servers support - values like `refactor` or `quickfix`. - • {triggerKind}? (`integer`) The reason why code actions - were requested. - • {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}? (`{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| + • {opts} (`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`) List of LSP `CodeActionKind`s used to + filter the code actions. Most language servers support + values like `refactor` or `quickfix`. + • {triggerKind}? (`integer`) The reason why code actions + were requested. + • {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}? (`{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 @@ -1263,7 +1295,7 @@ completion({context}) *vim.lsp.buf.completion()* See also: ~ • vim.lsp.protocol.CompletionTriggerKind -declaration({options}) *vim.lsp.buf.declaration()* +declaration({opts}) *vim.lsp.buf.declaration()* Jumps to the declaration of the symbol under the cursor. Note: ~ @@ -1271,13 +1303,13 @@ declaration({options}) *vim.lsp.buf.declaration()* |vim.lsp.buf.definition()| instead. Parameters: ~ - • {options} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. + • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. -definition({options}) *vim.lsp.buf.definition()* +definition({opts}) *vim.lsp.buf.definition()* Jumps to the definition of the symbol under the cursor. Parameters: ~ - • {options} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. + • {opts} (`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 @@ -1293,11 +1325,11 @@ document_highlight() *vim.lsp.buf.document_highlight()* highlights. |hl-LspReferenceText| |hl-LspReferenceRead| |hl-LspReferenceWrite| -document_symbol({options}) *vim.lsp.buf.document_symbol()* +document_symbol({opts}) *vim.lsp.buf.document_symbol()* Lists all symbols in the current buffer in the quickfix window. Parameters: ~ - • {options} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. + • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. execute_command({command_params}) *vim.lsp.buf.execute_command()* Executes an LSP server command. @@ -1308,53 +1340,53 @@ execute_command({command_params}) *vim.lsp.buf.execute_command()* See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand -format({options}) *vim.lsp.buf.format()* +format({opts}) *vim.lsp.buf.format()* Formats a buffer using the attached (and optionally filtered) language server clients. Parameters: ~ - • {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`, default: `1000`) Time in - milliseconds to block for formatting requests. No effect - 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 - } + • {opts} (`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`, default: `1000`) Time in + milliseconds to block for formatting requests. No effect 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`, default: false) If true the method - won't block. Editing the buffer while formatting - asynchronous can lead to unexpected changes. - • {id}? (`integer`) Restrict formatting to the client with - ID (client.id) matching this field. - • {name}? (`string`) Restrict formatting to the client with - name (client.name) matching this field. - • {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. + • {async}? (`boolean`, default: false) If true the method + won't block. Editing the buffer while formatting + asynchronous can lead to unexpected changes. + • {id}? (`integer`) Restrict formatting to the client with ID + (client.id) matching this field. + • {name}? (`string`) Restrict formatting to the client with + name (client.name) matching this field. + • {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 window. Calling the function twice will jump into the floating window. -implementation({options}) *vim.lsp.buf.implementation()* +implementation({opts}) *vim.lsp.buf.implementation()* Lists all the implementations for the symbol under the cursor in the quickfix window. Parameters: ~ - • {options} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. + • {opts} (`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| @@ -1369,13 +1401,13 @@ outgoing_calls() *vim.lsp.buf.outgoing_calls()* |quickfix| window. If the symbol can resolve to multiple items, the user can pick one in the |inputlist()|. -references({context}, {options}) *vim.lsp.buf.references()* +references({context}, {opts}) *vim.lsp.buf.references()* Lists all the references to the symbol under the cursor in the quickfix window. Parameters: ~ • {context} (`table?`) Context for the request - • {options} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. + • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references @@ -1388,13 +1420,13 @@ remove_workspace_folder({workspace_folder}) Parameters: ~ • {workspace_folder} (`string?`) -rename({new_name}, {options}) *vim.lsp.buf.rename()* +rename({new_name}, {opts}) *vim.lsp.buf.rename()* Renames all references to the symbol under the cursor. Parameters: ~ • {new_name} (`string?`) If not provided, the user will be prompted for a new name using |vim.ui.input()|. - • {options} (`table?`) Additional options: + • {opts} (`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 @@ -1407,13 +1439,21 @@ signature_help() *vim.lsp.buf.signature_help()* Displays signature information about the symbol under the cursor in a floating window. -type_definition({options}) *vim.lsp.buf.type_definition()* +type_definition({opts}) *vim.lsp.buf.type_definition()* Jumps to the definition of the type of the symbol under the cursor. Parameters: ~ - • {options} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. + • {opts} (`vim.lsp.LocationOpts?`) See |vim.lsp.LocationOpts|. -workspace_symbol({query}, {options}) *vim.lsp.buf.workspace_symbol()* +typehierarchy({kind}) *vim.lsp.buf.typehierarchy()* + Lists all the subtypes or supertypes of the symbol under the cursor in the + |quickfix| window. If the symbol can resolve to multiple items, the user + can pick one using |vim.ui.select()|. + + Parameters: ~ + • {kind} (`"subtypes"|"supertypes"`) + +workspace_symbol({query}, {opts}) *vim.lsp.buf.workspace_symbol()* Lists all symbols in the current workspace in the quickfix window. The list is filtered against {query}; if the argument is omitted from the @@ -1421,8 +1461,8 @@ workspace_symbol({query}, {options}) *vim.lsp.buf.workspace_symbol()* string means no filtering is done. Parameters: ~ - • {query} (`string?`) optional - • {options} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. + • {query} (`string?`) optional + • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. ============================================================================== @@ -1567,19 +1607,18 @@ save({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.save()* ============================================================================== Lua module: vim.lsp.inlay_hint *lsp-inlay_hint* -enable({bufnr}, {enable}) *vim.lsp.inlay_hint.enable()* - Enables or disables inlay hints for a buffer. +enable({enable}, {filter}) *vim.lsp.inlay_hint.enable()* + Enables or disables inlay hints for the {filter}ed scope. To "toggle", pass the inverse of `is_enabled()`: >lua - vim.lsp.inlay_hint.enable(0, not vim.lsp.inlay_hint.is_enabled()) + vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled()) < - Note: ~ - • This API is pre-release (unstable). - Parameters: ~ - • {bufnr} (`integer?`) Buffer handle, or 0 or nil for current • {enable} (`boolean?`) true/nil to enable, false to disable + • {filter} (`table?`) Optional filters |kwargs|, or `nil` for all. + • {bufnr} (`integer?`) Buffer number, or 0 for current + buffer, or nil for all. get({filter}) *vim.lsp.inlay_hint.get()* Get the list of inlay hints, (optionally) restricted by buffer or range. @@ -1588,7 +1627,8 @@ get({filter}) *vim.lsp.inlay_hint.get()* local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer local client = vim.lsp.get_client_by_id(hint.client_id) - resolved_hint = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0).result + local resp = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0) + local resolved_hint = assert(resp and resp.result, resp.err) vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding) location = resolved_hint.label[1].location @@ -1598,9 +1638,6 @@ get({filter}) *vim.lsp.inlay_hint.get()* }) < - Note: ~ - • This API is pre-release (unstable). - Parameters: ~ • {filter} (`table?`) Optional filters |kwargs|: • {bufnr} (`integer?`) @@ -1612,13 +1649,13 @@ get({filter}) *vim.lsp.inlay_hint.get()* • {client_id} (`integer`) • {inlay_hint} (`lsp.InlayHint`) -is_enabled({bufnr}) *vim.lsp.inlay_hint.is_enabled()* - - Note: ~ - • This API is pre-release (unstable). +is_enabled({filter}) *vim.lsp.inlay_hint.is_enabled()* + Query whether inlay hint is enabled in the {filter}ed scope Parameters: ~ - • {bufnr} (`integer?`) Buffer handle, or 0 or nil for current + • {filter} (`table`) Optional filters |kwargs|, or `nil` for all. + • {bufnr} (`integer?`) Buffer number, or 0 for current + buffer, or nil for all. Return: ~ (`boolean`) @@ -1668,9 +1705,10 @@ 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 - |LspTokenUpdate|. - • {bufnr} (`integer`) the buffer to highlight + • {token} (`table`) A semantic token, found as `args.data.token` in + |LspTokenUpdate| + • {bufnr} (`integer`) The buffer to highlight, or `0` for current + buffer • {client_id} (`integer`) The ID of the |vim.lsp.Client| • {hl_group} (`string`) Highlight group name • {opts} (`table?`) Optional parameters: @@ -1691,8 +1729,8 @@ start({bufnr}, {client_id}, {opts}) *vim.lsp.semantic_tokens.start()* < Parameters: ~ - • {bufnr} (`integer`) - • {client_id} (`integer`) + • {bufnr} (`integer`) Buffer number, or `0` for current buffer + • {client_id} (`integer`) The ID of the |vim.lsp.Client| • {opts} (`table?`) Optional keyword arguments • debounce (integer, default: 200): Debounce token requests to the server by the given number in @@ -1708,8 +1746,8 @@ stop({bufnr}, {client_id}) *vim.lsp.semantic_tokens.stop()* from the buffer. Parameters: ~ - • {bufnr} (`integer`) - • {client_id} (`integer`) + • {bufnr} (`integer`) Buffer number, or `0` for current buffer + • {client_id} (`integer`) The ID of the |vim.lsp.Client| ============================================================================== @@ -2096,7 +2134,7 @@ rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()* 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 + • the conflicting buffers are not loaded, so that deleting them does not result in data loss. Parameters: ~ @@ -2208,32 +2246,20 @@ Lua module: vim.lsp.rpc *lsp-rpc* • {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. - - 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). +connect({host_or_path}, {port}) *vim.lsp.rpc.connect()* + Create a LSP RPC client factory that connects to either: + • a named pipe (windows) + • a domain socket (unix) + • a host and port via TCP Return a function that can be passed to the `cmd` field for |vim.lsp.start_client()| or |vim.lsp.start()|. Parameters: ~ - • {pipe_path} (`string`) file path of the domain socket (Unix) or name - of the named pipe (Windows) to connect to + • {host_or_path} (`string`) host to connect to or path to a pipe/domain + socket + • {port} (`integer?`) TCP port to connect to. If absent the + first argument must be a pipe Return: ~ (`fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) @@ -2318,7 +2344,7 @@ start({cmd}, {dispatchers}, {extra_spawn_params}) *vim.lsp.rpc.start()* See |vim.system()| Return: ~ - (`vim.lsp.rpc.PublicClient?`) 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. diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 367b5c36d2..3d8453c5a2 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -34,10 +34,11 @@ Nvim ever ships with Lua 5.4+, a Lua 5.1 compatibility shim will be provided so that old plugins continue to work transparently. *lua-luajit* -Nvim is built with luajit on platforms which support it, which provides -extra functionality. Lua code in |init.lua| and plugins can assume its presence -on installations on common platforms. For maximum compatibility with less -common platforms, availability can be checked using the `jit` global variable: >lua +On supported platforms, Nvim is built with LuaJIT, which provides extra +functionality (compared to PUC Lua) such as "bit" and various utilities (see +|lua-profile|). Lua code in |init.lua| and plugins can assume its presence on +many platforms, but for maximum compatibility should check the `jit` global +variable: >lua if jit then -- code for luajit else @@ -45,9 +46,21 @@ common platforms, availability can be checked using the `jit` global variable: > end < *lua-bit* -In particular, the luajit "bit" extension module is _always_ available. -A fallback implementation is included when nvim is built with PUC Lua 5.1, -and will be transparently used when `require("bit")` is invoked. +The LuaJIT "bit" extension module is _always_ available: when built with PUC +Lua, Nvim includes a fallback implementation which provides `require("bit")`. + + *lua-profile* +To profile Lua code (with LuaJIT-enabled Nvim), the basic steps are: >lua + -- Start a profiling session: + require('jit.p').start('ri1', '/tmp/profile') + + -- Perform arbitrary tasks (use plugins, scripts, etc.) ... + + -- Stop the session. Profile is written to /tmp/profile. + require('jit.p').stop() + +See https://luajit.org/ext_profiler.html or the "p.lua" source for details: > + :lua vim.cmd.edit(package.searchpath('jit.p', package.path)) ============================================================================== LUA CONCEPTS AND IDIOMS *lua-concepts* @@ -244,8 +257,8 @@ arguments separated by " " (space) instead of "\t" (tab). *:lua=* *:lua* :lua {chunk} Executes Lua chunk {chunk}. If {chunk} starts with "=" the rest of the - chunk is evaluated as an expression and printed. `:lua =expr` or `:=expr` is - equivalent to `:lua print(vim.inspect(expr))`. + chunk is evaluated as an expression and printed. `:lua =expr` and `:=expr` + are equivalent to `:lua vim.print(expr)`. Examples: >vim :lua vim.api.nvim_command('echo "Hello, Nvim!"') @@ -530,6 +543,16 @@ Example: File-change detection *watch-file* vim.api.nvim_command( "command! -nargs=1 Watch call luaeval('watch_file(_A)', expand('<args>'))") < + *fswatch-limitations* +When on Linux and using fswatch, you may need to increase the maximum number +of `inotify` watches and queued events as the default limit can be too low. To +increase the limit, run: >sh + sysctl fs.inotify.max_user_watches=100000 + sysctl fs.inotify.max_queued_events=100000 +< +This will increase the limit to 100000 watches and queued events. These lines +can be added to `/etc/sysctl.conf` to make the changes persistent. + Example: TCP echo-server *tcp-server* 1. Save this code to a file. 2. Execute it with ":luafile %". @@ -582,24 +605,13 @@ A subset of the `vim.*` API is available in threads. This includes: ============================================================================== 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 - au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150} -< +vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* + Highlight the yanked text during a |TextYankPost| event. -If you want to exclude visual selections from highlighting on yank, use: >vim - au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} + Add the following to your `init.vim`: >vim + autocmd TextYankPost * silent! lua vim.highlight.on_yank {higroup='Visual', timeout=300} < - -vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* - Highlight the yanked text - Parameters: ~ • {opts} (`table?`) Optional parameters • higroup highlight group for yanked region (default @@ -633,12 +645,14 @@ vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) 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) - • priority number indicating priority of highlight (default - priorities.user) + • {opts} (`table?`) A table with the following fields: + • {regtype}? (`string`, default: `'charwise'`) Type of + range. See |setreg()| + • {inclusive}? (`boolean`, default: `false`) Indicates + whether the range is end-inclusive + • {priority}? (`integer`, default: + `vim.highlight.priorities.user`) Indicates priority of + highlight ============================================================================== @@ -666,44 +680,47 @@ 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: - • `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 + • {opts} (`table`) Optional parameters: + • {on_hunk} + (`fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer`) + Invoked for each hunk in the diff. Return a negative number + to cancel the callback for any remaining hunks. Arguments: + • `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} (`'unified'|'indices'`, default: `'unified'`) + Form of the returned diff: + • `unified`: 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 + • {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 `result_type = indices`, ignored otherwise. - • `algorithm` (string): Diff algorithm to use. Values: - • "myers" the default algorithm - • "minimal" spend extra time to generate the smallest + • {algorithm} (`'myers'|'minimal'|'patience'|'histogram'`, + default: `'myers'`) Diff algorithm to use. Values: + • `myers`: the default algorithm + • `minimal`: spend extra time to generate the smallest 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 - • `ignore_whitespace_change` (boolean): Ignore whitespace + • `patience`: patience diff algorithm + • `histogram`: histogram diff algorithm + • {ctxlen} (`integer`) Context length + • {interhunkctxlen} (`integer`) Inter hunk context length + • {ignore_whitespace} (`boolean`) Ignore whitespace + • {ignore_whitespace_change} (`boolean`) Ignore whitespace change - • `ignore_whitespace_change_at_eol` (boolean) Ignore + • {ignore_whitespace_change_at_eol} (`boolean`) Ignore whitespace change at end-of-line. - • `ignore_cr_at_eol` (boolean) Ignore carriage return at + • {ignore_cr_at_eol} (`boolean`) Ignore carriage return at end-of-line - • `ignore_blank_lines` (boolean) Ignore blank lines - • `indent_heuristic` (boolean): Use the indent heuristic for + • {ignore_blank_lines} (`boolean`) Ignore blank lines + • {indent_heuristic} (`boolean`) Use the indent heuristic for the internal diff library. Return: ~ - (`string|table?`) See {opts.result_type}. `nil` if {opts.on_hunk} is - given. + (`string|integer[]`) See {opts.result_type}. `nil` if {opts.on_hunk} + is given. ============================================================================== @@ -817,8 +834,8 @@ vim.spell.check({str}) *vim.spell.check()* • {str} (`string`) Return: ~ - (`{[1]: string, [2]: string, [3]: string}[]`) List of tuples with - three items: + (`{[1]: string, [2]: 'bad'|'rare'|'local'|'caps', [3]: integer}[]`) + 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 @@ -899,7 +916,7 @@ vim.empty_dict() *vim.empty_dict()* Return: ~ (`table`) -vim.iconv({str}, {from}, {to}, {opts}) *vim.iconv()* +vim.iconv({str}, {from}, {to}) *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 some characters could not be converted they are replaced with "?". The @@ -908,9 +925,8 @@ vim.iconv({str}, {from}, {to}, {opts}) *vim.iconv()* Parameters: ~ • {str} (`string`) Text to convert - • {from} (`number`) Encoding of {str} - • {to} (`number`) Target encoding - • {opts} (`table<string,any>?`) + • {from} (`string`) Encoding of {str} + • {to} (`string`) Target encoding Return: ~ (`string?`) Converted string if conversion succeeds, `nil` otherwise. @@ -950,20 +966,20 @@ vim.schedule({fn}) *vim.schedule()* |textlock| or other temporary restrictions. Parameters: ~ - • {fn} (`function`) + • {fn} (`fun()`) 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 supplied, it defaults to false (use UTF-32). Returns the byte index. - Invalid UTF-8 and NUL is treated like by |vim.str_byteindex()|. An {index} + Invalid UTF-8 and NUL is treated like in |vim.str_utfindex()|. An {index} in the middle of a UTF-16 sequence is rounded upwards to the end of that sequence. Parameters: ~ • {str} (`string`) - • {index} (`number`) - • {use_utf16} (`any?`) + • {index} (`integer`) + • {use_utf16} (`boolean?`) vim.str_utf_end({str}, {index}) *vim.str_utf_end()* Gets the distance (in bytes) from the last byte of the codepoint @@ -981,10 +997,10 @@ vim.str_utf_end({str}, {index}) *vim.str_utf_end()* Parameters: ~ • {str} (`string`) - • {index} (`number`) + • {index} (`integer`) Return: ~ - (`number`) + (`integer`) vim.str_utf_pos({str}) *vim.str_utf_pos()* Gets a list of the starting byte positions of each UTF-8 codepoint in the @@ -996,7 +1012,7 @@ vim.str_utf_pos({str}) *vim.str_utf_pos()* • {str} (`string`) Return: ~ - (`table`) + (`integer[]`) vim.str_utf_start({str}, {index}) *vim.str_utf_start()* Gets the distance (in bytes) from the starting byte of the codepoint @@ -1017,10 +1033,10 @@ vim.str_utf_start({str}, {index}) *vim.str_utf_start()* Parameters: ~ • {str} (`string`) - • {index} (`number`) + • {index} (`integer`) Return: ~ - (`number`) + (`integer`) vim.str_utfindex({str}, {index}) *vim.str_utfindex()* Convert byte index to UTF-32 and UTF-16 indices. If {index} is not @@ -1033,7 +1049,7 @@ vim.str_utfindex({str}, {index}) *vim.str_utfindex()* Parameters: ~ • {str} (`string`) - • {index} (`number?`) + • {index} (`integer?`) Return (multiple): ~ (`integer`) UTF-32 index @@ -1161,6 +1177,7 @@ Lua list copies the list object to Vimscript and does NOT modify the Lua list: > vim.print(list) --> "{ 1, 2, 3 }" < + vim.call({func}, {...}) *vim.call()* Invokes |vim-function| or |user-function| {func} with arguments {...}. See also |vim.fn|. @@ -1239,6 +1256,7 @@ vim.v *vim.v* |v:| variables. Invalid or unset key returns `nil`. + *lua-options* *lua-vim-options* *lua-vim-set* @@ -1262,6 +1280,7 @@ 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* @@ -1406,7 +1425,7 @@ Option:remove({value}) *vim.opt:remove()* Parameters: ~ • {value} (`string`) Value to remove -vim.bo *vim.bo* +vim.bo[{bufnr}] *vim.bo* 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. @@ -1456,7 +1475,7 @@ vim.o *vim.o* print(vim.o.foo) -- error: invalid key < -vim.wo *vim.wo* +vim.wo[{winid}][{bufnr}] *vim.wo* Get or set window-scoped |options| for the window with handle {winid} and buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| option or if {bufnr} is provided, like `:set` otherwise. If {winid} is @@ -1625,12 +1644,14 @@ vim.on_key({fn}, {ns_id}) *vim.on_key()* Note: ~ • {fn} will be removed on error. • {fn} will not be cleared by |nvim_buf_clear_namespace()| - • {fn} will receive the keys after mappings have been evaluated Parameters: ~ - • {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}. + • {fn} (`fun(key: string, typed: string)?`) Function invoked on + every key press. |i_CTRL-V| {key} is the key after mappings + have been applied, and {typed} is the key(s) before mappings + are applied, which may be empty if {key} is produced by + non-typed keys. When {fn} is nil and {ns_id} is specified, + the callback associated with namespace {ns_id} is removed. • {ns_id} (`integer?`) Namespace ID. If nil or 0, generates and returns a new |nvim_create_namespace()| id. @@ -1795,6 +1816,7 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()* Return: ~ (`vim.SystemObj`) Object with the fields: + • cmd (string[]) Command name and args • pid (integer) Process ID • wait (fun(timeout: integer|nil): SystemCompleted) Wait for the process to complete. Upon timeout the process is sent the KILL @@ -2011,6 +2033,43 @@ vim.is_callable({f}) *vim.is_callable()* Return: ~ (`boolean`) `true` if `f` is callable, else `false` +vim.isarray({t}) *vim.isarray()* + 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.islist()| + + Empty table `{}` is an array, 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?`) + + Return: ~ + (`boolean`) `true` if array-like table, else `false`. + + See also: ~ + • https://github.com/openresty/luajit2#tableisarray + +vim.islist({t}) *vim.islist()* + 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?`) + + Return: ~ + (`boolean`) `true` if list-like table, else `false`. + + See also: ~ + • |vim.isarray()| + vim.list_contains({t}, {value}) *vim.list_contains()* Checks if a list-like table (integer keys without gaps) contains `value`. @@ -2190,8 +2249,8 @@ vim.tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* Merges recursively two or more tables. Parameters: ~ - • {behavior} (`"error"|"keep"|"force"`) (string) Decides what to do if - a key is found in more than one map: + • {behavior} (`'error'|'keep'|'force'`) 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 @@ -2207,8 +2266,8 @@ 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} (`'error'|'keep'|'force'`) 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 @@ -2230,20 +2289,6 @@ vim.tbl_filter({func}, {t}) *vim.tbl_filter()* Return: ~ (`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 - - Return: ~ - (`table`) Flattened copy of the given list-like table - - See also: ~ - • 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 arguments. Return `nil` if the key does not exist. @@ -2261,26 +2306,6 @@ vim.tbl_get({o}, {...}) *vim.tbl_get()* Return: ~ (`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). - - If the indexes start from 1 and are contiguous then the array is also a - list. |vim.tbl_islist()| - - Empty table `{}` is an array, 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`) - - Return: ~ - (`boolean`) `true` if array-like table, else `false`. - - See also: ~ - • https://github.com/openresty/luajit2#tableisarray - vim.tbl_isempty({t}) *vim.tbl_isempty()* Checks if a table is empty. @@ -2293,23 +2318,6 @@ vim.tbl_isempty({t}) *vim.tbl_isempty()* 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"). - - 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`) - - Return: ~ - (`boolean`) `true` if list-like table, else `false`. - - See also: ~ - • |vim.tbl_isarray()| - vim.tbl_keys({t}) *vim.tbl_keys()* Return a list of all keys used in a table. However, the order of the return table of keys is not guaranteed. @@ -2358,7 +2366,8 @@ vim.trim({s}) *vim.trim()* • https://www.lua.org/pil/20.2.html vim.validate({opt}) *vim.validate()* - Validates a parameter specification (types and values). + Validates a parameter specification (types and values). Specs are + evaluated in alphanumeric order, until the first failure. Usage example: >lua function user.new(name, age, hobbies) @@ -2551,17 +2560,22 @@ vim.ui.open({path}) *vim.ui.open()* Expands "~/" and environment variables in filesystem paths. Examples: >lua + -- Asynchronous. vim.ui.open("https://neovim.io/") vim.ui.open("~/path/to/file") - vim.ui.open("$VIMRUNTIME") + -- Synchronous (wait until the process exits). + local cmd, err = vim.ui.open("$VIMRUNTIME") + if cmd then + cmd:wait() + end < Parameters: ~ • {path} (`string`) Path or URL to open Return (multiple): ~ - (`vim.SystemCompleted?`) Command result, or nil if not found. - (`string?`) Error message on failure + (`vim.SystemObj?`) Command object, or nil if not found. + (`string?`) Error message on failure, or nil on success. See also: ~ • |vim.system()| @@ -2672,7 +2686,6 @@ vim.filetype.add({filetypes}) *vim.filetype.add()* vim.filetype.add { pattern = { ['.*'] = { - priority = -math.huge, function(path, bufnr) local content = vim.api.nvim_buf_get_lines(bufnr, 0, 1, false)[1] or '' if vim.regex([[^#!.*\\<mine\\>]]):match_str(content) ~= nil then @@ -2681,6 +2694,7 @@ vim.filetype.add({filetypes}) *vim.filetype.add()* return 'drawing' end end, + { priority = -math.huge }, }, }, } @@ -2781,9 +2795,9 @@ vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* Parameters: ~ • {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. + • {opts} (`table?`) A table with the following fields: + • {buffer}? (`integer|boolean`) Remove a mapping from the + given buffer. When `0` or `true`, use the current buffer. See also: ~ • |vim.keymap.set()| @@ -2805,20 +2819,20 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* < Parameters: ~ - • {mode} (`string|table`) Mode short-name, see |nvim_set_keymap()|. Can - also be list of modes to create mapping on multiple modes. + • {mode} (`string|string[]`) 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?`) 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. - • "remap": (boolean) Make the mapping recursive. Inverse of - "noremap". Defaults to `false`. + • {opts} (`table?`) Table of |:map-arguments|. Same as + |nvim_set_keymap()| {opts}, except: + • {replace_keycodes} defaults to `true` if "expr" is `true`. + + Also accepts: + • {buffer}? (`integer|boolean`) Creates buffer-local mapping, + `0` or `true` for current buffer. + • {remap}? (`boolean`, default: `false`) Make the mapping + recursive. Inverse of {noremap}. See also: ~ • |nvim_set_keymap()| @@ -2881,13 +2895,6 @@ vim.fs.find({names}, {opts}) *vim.fs.find()* narrow the search to find only that type. Examples: >lua - -- location of Cargo.toml from the current buffer's path - local cargo = vim.fs.find('Cargo.toml', { - upward = true, - stop = vim.uv.os_homedir(), - path = vim.fs.dirname(vim.api.nvim_buf_get_name(0)), - }) - -- list all test directories under the runtime directory local test_dirs = vim.fs.find( {'test', 'tst', 'testdir'}, @@ -2939,26 +2946,41 @@ vim.fs.joinpath({...}) *vim.fs.joinpath()* vim.fs.normalize({path}, {opts}) *vim.fs.normalize()* Normalize a path to a standard format. A tilde (~) character at the - beginning of the path is expanded to the user's home directory and any - backslash (\) characters are converted to forward slashes (/). Environment - variables are also expanded. + beginning of the path is expanded to the user's home directory and + environment variables are also expanded. "." and ".." components are also + resolved, except when the path is relative and trying to resolve it would + result in an absolute path. + • "." as the only part in a relative path: + • "." => "." + • "././" => "." + • ".." when it leads outside the current directory + • "foo/../../bar" => "../bar" + • "../../foo" => "../../foo" + • ".." in the root directory returns the root directory. + • "/../../" => "/" + + On Windows, backslash (\) characters are converted to forward slashes (/). Examples: >lua - vim.fs.normalize('C:\\\\Users\\\\jdoe') - -- 'C:/Users/jdoe' - - vim.fs.normalize('~/src/neovim') - -- '/home/jdoe/src/neovim' - - vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim') - -- '/Users/jdoe/.config/nvim/init.vim' + [[C:\Users\jdoe]] => "C:/Users/jdoe" + "~/src/neovim" => "/home/jdoe/src/neovim" + "$XDG_CONFIG_HOME/nvim/init.vim" => "/Users/jdoe/.config/nvim/init.vim" + "~/src/nvim/api/../tui/./tui.c" => "/home/jdoe/src/nvim/tui/tui.c" + "./foo/bar" => "foo/bar" + "foo/../../../bar" => "../../bar" + "/home/jdoe/../../../bar" => "/bar" + "C:foo/../../baz" => "C:../baz" + "C:/foo/../../baz" => "C:/baz" + [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar" < Parameters: ~ • {path} (`string`) Path to normalize • {opts} (`table?`) A table with the following fields: - • {expand_env} (`boolean`, default: `true`) Expand environment - variables. + • {expand_env}? (`boolean`, default: `true`) Expand + environment variables. + • {win}? (`boolean`, default: `true` in Windows, `false` + otherwise) Path is a Windows path. Return: ~ (`string`) Normalized path @@ -2988,6 +3010,39 @@ vim.fs.parents({start}) *vim.fs.parents()* (`nil`) (`string?`) +vim.fs.root({source}, {marker}) *vim.fs.root()* + Find the first parent directory containing a specific "marker", relative + to a file path or buffer. + + If the buffer is unnamed (has no backing file) or has a non-empty + 'buftype' then the search begins from Nvim's |current-directory|. + + Example: >lua + -- Find the root of a Python project, starting from file 'main.py' + vim.fs.root(vim.fs.joinpath(vim.env.PWD, 'main.py'), {'pyproject.toml', 'setup.py' }) + + -- Find the root of a git repository + vim.fs.root(0, '.git') + + -- Find the parent directory containing any file with a .csproj extension + vim.fs.root(0, function(name, path) + return name:match('%.csproj$') ~= nil + end) +< + + Parameters: ~ + • {source} (`integer|string`) Buffer number (0 for current buffer) or + file path (absolute or relative to the |current-directory|) + to begin the search from. + • {marker} (`string|string[]|fun(name: string, path: string): boolean`) + A marker, or list of markers, to search for. If a function, + the function is called for each evaluated item and should + return true if {name} and {path} are a match. + + Return: ~ + (`string?`) Directory path containing one of the given markers, or nil + if no directory was found. + ============================================================================== Lua module: vim.glob *vim.glob* @@ -3022,11 +3077,10 @@ vim.glob.to_lpeg({pattern}) *vim.glob.to_lpeg()* VIM.LPEG *vim.lpeg* -LPeg is a pattern-matching library for Lua, based on -Parsing Expression Grammars (https://bford.info/packrat/) (PEGs). +LPeg is a pattern-matching library for Lua, based on Parsing Expression +Grammars (PEGs). https://bford.info/packrat/ - *lua-lpeg* - *vim.lpeg.Pattern* + *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/). @@ -3419,10 +3473,11 @@ vim.lpeg.version() *vim.lpeg.version()* VIM.RE *vim.re* The `vim.re` module provides a conventional regex-like syntax for pattern -usage within LPeg |vim.lpeg|. +usage within LPeg |vim.lpeg|. (Unrelated to |vim.regex| which provides Vim +|regexp| from Lua.) See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original -documentation including regex syntax and more concrete examples. +documentation including regex syntax and examples. vim.re.compile({string}, {defs}) *vim.re.compile()* @@ -3553,7 +3608,7 @@ vim.secure.trust({opts}) *vim.secure.trust()* The trust database is located at |$XDG_STATE_HOME|/nvim/trust. Parameters: ~ - • {opts} (`table?`) A table with the following fields: + • {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, @@ -3764,7 +3819,6 @@ vim.version.range({spec}) *vim.version.range()* (`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 @@ -3780,6 +3834,7 @@ 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. + • Holes (nil values) are allowed. • 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. @@ -3833,27 +3888,6 @@ Examples: >lua -- { "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()* - Filters a table or other |iterable|. >lua - -- Equivalent to: - vim.iter(src):filter(f):totable() -< - - Parameters: ~ - • {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 - - Return: ~ - (`table`) - - See also: ~ - • |Iter:filter()| Iter:all({pred}) *Iter:all()* Returns true if all items in the iterator match the given predicate. @@ -3897,6 +3931,7 @@ Iter:enumerate() *Iter:enumerate()* < Example: >lua + local it = vim.iter(vim.gsplit('abc', '')):enumerate() it:next() -- 1 'a' @@ -3931,6 +3966,7 @@ Iter:find({f}) *Iter:find()* found. Examples: >lua + local it = vim.iter({ 3, 6, 9, 12 }) it:find(12) -- 12 @@ -3973,18 +4009,23 @@ Iter:flatten({depth}) *Iter:flatten()* (`Iter`) Iter:fold({init}, {f}) *Iter:fold()* - Folds ("reduces") an iterator into a single value. + Folds ("reduces") an iterator into a single value. *Iter:reduce()* Examples: >lua -- Create a new table with only even values - local t = { a = 1, b = 2, c = 3, d = 4 } - local it = vim.iter(t) - it:filter(function(k, v) return v % 2 == 0 end) - it:fold({}, function(t, k, v) - t[k] = v - return t - end) - -- { b = 2, d = 4 } + vim.iter({ a = 1, b = 2, c = 3, d = 4 }) + :filter(function(k, v) return v % 2 == 0 end) + :fold({}, function(acc, k, v) + acc[k] = v + return acc + end) --> { b = 2, d = 4 } + + -- Get the "maximum" item of an iterable. + vim.iter({ -99, -4, 3, 42, 0, 0, 7 }) + :fold({}, function(acc, v) + acc.max = math.max(v, acc.max or v) + return acc + end) --> { max = 42 } < Parameters: ~ @@ -4011,6 +4052,7 @@ Iter:last() *Iter:last()* Drains the iterator and returns the last item. Example: >lua + local it = vim.iter(vim.gsplit('abcdefg', '')) it:last() -- 'g' @@ -4023,6 +4065,9 @@ Iter:last() *Iter:last()* Return: ~ (`any`) + See also: ~ + • Iter.rpeek + Iter:map({f}) *Iter:map()* Maps the items of an iterator pipeline to the values returned by `f`. @@ -4051,6 +4096,7 @@ Iter:next() *Iter:next()* Gets the next value from the iterator. Example: >lua + local it = vim.iter(string.gmatch('1 2 3', '%d+')):map(tonumber) it:next() -- 1 @@ -4063,51 +4109,28 @@ Iter:next() *Iter:next()* Return: ~ (`any`) -Iter:nextback() *Iter:nextback()* - "Pops" a value from a |list-iterator| (gets the last value and decrements - the tail). - - Example: >lua - local it = vim.iter({1, 2, 3, 4}) - it:nextback() - -- 4 - it:nextback() - -- 3 -< - - Return: ~ - (`any`) - Iter:nth({n}) *Iter:nth()* Gets the nth value of an iterator (and advances to it). + If `n` is negative, offsets from the end of a |list-iterator|. + Example: >lua local it = vim.iter({ 3, 6, 9, 12 }) it:nth(2) -- 6 it:nth(2) -- 12 -< - - Parameters: ~ - • {n} (`number`) The index of the value to return. - - Return: ~ - (`any`) - -Iter:nthback({n}) *Iter:nthback()* - Gets the nth value from the end of a |list-iterator| (and advances to it). - Example: >lua - local it = vim.iter({ 3, 6, 9, 12 }) - it:nthback(2) + local it2 = vim.iter({ 3, 6, 9, 12 }) + it2:nth(-2) -- 9 - it:nthback(2) + it2:nth(-2) -- 3 < Parameters: ~ - • {n} (`number`) The index of the value to return. + • {n} (`number`) Index of the value to return. May be negative if the + source is a |list-iterator|. Return: ~ (`any`) @@ -4116,6 +4139,7 @@ Iter:peek() *Iter:peek()* Gets the next value in a |list-iterator| without consuming it. Example: >lua + local it = vim.iter({ 3, 6, 9, 12 }) it:peek() -- 3 @@ -4128,19 +4152,16 @@ Iter:peek() *Iter:peek()* Return: ~ (`any`) -Iter:peekback() *Iter:peekback()* - Gets the last value of a |list-iterator| without consuming it. - - See also |Iter:last()|. +Iter:pop() *Iter:pop()* + "Pops" a value from a |list-iterator| (gets the last value and decrements + the tail). Example: >lua local it = vim.iter({1, 2, 3, 4}) - it:peekback() - -- 4 - it:peekback() - -- 4 - it:nextback() + it:pop() -- 4 + it:pop() + -- 3 < Return: ~ @@ -4150,6 +4171,7 @@ Iter:rev() *Iter:rev()* Reverses a |list-iterator| pipeline. Example: >lua + local it = vim.iter({ 3, 6, 9, 12 }):rev() it:totable() -- { 12, 9, 6, 3 } @@ -4159,13 +4181,14 @@ Iter:rev() *Iter:rev()* (`Iter`) Iter:rfind({f}) *Iter:rfind()* - Gets the first value in a |list-iterator| that satisfies a predicate, - starting from the end. + Gets the first value satisfying a predicate, from the end of a + |list-iterator|. Advances the iterator. Returns nil and drains the iterator if no value is found. Examples: >lua + local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate() it:rfind(1) -- 5 1 @@ -4182,13 +4205,34 @@ Iter:rfind({f}) *Iter:rfind()* See also: ~ • Iter.find -Iter:skip({n}) *Iter:skip()* - Skips `n` values of an iterator pipeline. +Iter:rpeek() *Iter:rpeek()* + Gets the last value of a |list-iterator| without consuming it. Example: >lua - local it = vim.iter({ 3, 6, 9, 12 }):skip(2) + local it = vim.iter({1, 2, 3, 4}) + it:rpeek() + -- 4 + it:rpeek() + -- 4 + it:pop() + -- 4 +< + + Return: ~ + (`any`) + + See also: ~ + • Iter.last + +Iter:rskip({n}) *Iter:rskip()* + Discards `n` values from the end of a |list-iterator| pipeline. + + Example: >lua + local it = vim.iter({ 1, 2, 3, 4, 5 }):rskip(2) it:next() - -- 9 + -- 1 + it:pop() + -- 3 < Parameters: ~ @@ -4197,15 +4241,14 @@ Iter:skip({n}) *Iter:skip()* Return: ~ (`Iter`) -Iter:skipback({n}) *Iter:skipback()* - Skips `n` values backwards from the end of a |list-iterator| pipeline. +Iter:skip({n}) *Iter:skip()* + Skips `n` values of an iterator pipeline. Example: >lua - local it = vim.iter({ 1, 2, 3, 4, 5 }):skipback(2) + + local it = vim.iter({ 3, 6, 9, 12 }):skip(2) it:next() - -- 1 - it:nextback() - -- 3 + -- 9 < Parameters: ~ @@ -4217,7 +4260,7 @@ Iter:skipback({n}) *Iter:skipback()* Iter:slice({first}, {last}) *Iter:slice()* Sets the start and end of a |list-iterator| pipeline. - Equivalent to `:skip(first - 1):skipback(len - last + 1)`. + Equivalent to `:skip(first - 1):rskip(len - last + 1)`. Parameters: ~ • {first} (`number`) @@ -4249,9 +4292,9 @@ Iter:totable() *Iter:totable()* Collect the iterator into a table. The resulting table depends on the initial source in the iterator - pipeline. List-like tables and function iterators will be collected into a - list-like table. If multiple values are returned from the final stage in - the iterator pipeline, each value will be included in a table. + pipeline. Array-like tables and function iterators will be collected into + an array-like table. If multiple values are returned from the final stage + in the iterator pipeline, each value will be included in a table. Examples: >lua vim.iter(string.gmatch('100 20 50', '%d+')):map(tonumber):totable() @@ -4264,90 +4307,65 @@ Iter:totable() *Iter:totable()* -- { { 'a', 1 }, { 'c', 3 } } < - The generated table is a list-like table with consecutive, numeric + The generated table is an array-like table with consecutive, numeric indices. To create a map-like table with arbitrary keys, use |Iter:fold()|. Return: ~ (`table`) -map({f}, {src}) *vim.iter.map()* - Maps a table or other |iterable|. >lua - -- Equivalent to: - vim.iter(src):map(f):totable() -< - - Parameters: ~ - • {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 - Return: ~ - (`table`) - - See also: ~ - • |Iter:map()| +============================================================================== +Lua module: vim.snippet *vim.snippet* -totable({f}) *vim.iter.totable()* - Collects an |iterable| into a table. >lua - -- Equivalent to: - vim.iter(f):totable() -< +*vim.snippet.ActiveFilter* - Parameters: ~ - • {f} (`function`) Iterator function + Fields: ~ + • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for + previous, 1 for next. - Return: ~ - (`table`) +vim.snippet.active({filter}) *vim.snippet.active()* + Returns `true` if there's an active snippet in the current buffer, + applying the given filter if provided. -============================================================================== -Lua module: vim.snippet *vim.snippet* + You can use this function to navigate a snippet as follows: >lua + vim.keymap.set({ 'i', 's' }, '<Tab>', function() + if vim.snippet.active({ direction = 1 }) then + return '<cmd>lua vim.snippet.jump(1)<cr>' + else + return '<Tab>' + end + end, { expr = true }) +< -vim.snippet.active() *vim.snippet.active()* - Returns `true` if there's an active snippet in the current buffer. + Parameters: ~ + • {filter} (`vim.snippet.ActiveFilter?`) Filter to constrain the search + with: + • `direction` (vim.snippet.Direction): Navigation direction. + Will return `true` if the snippet can be jumped in the + given direction. See |vim.snippet.ActiveFilter|. Return: ~ (`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. - Tabstops are highlighted with hl-SnippetTabstop. + Tabstops are highlighted with |hl-SnippetTabstop|. Parameters: ~ • {input} (`string`) vim.snippet.jump({direction}) *vim.snippet.jump()* - Jumps within the active snippet in the given direction. If the jump isn't - possible, the function call does nothing. - - You can use this function to navigate a snippet as follows: >lua - vim.keymap.set({ 'i', 's' }, '<Tab>', function() - if vim.snippet.jumpable(1) then - return '<cmd>lua vim.snippet.jump(1)<cr>' - else - return '<Tab>' - end - end, { expr = true }) -< + Jumps to the next (or previous) placeholder in the current snippet, if + possible. - Parameters: ~ - • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for - previous, 1 for next. - -vim.snippet.jumpable({direction}) *vim.snippet.jumpable()* - Returns `true` if there is an active snippet which can be jumped in the - given direction. You can use this function to navigate a snippet as - follows: >lua + For example, map `<Tab>` to jump while a snippet is active: >lua vim.keymap.set({ 'i', 's' }, '<Tab>', function() - if vim.snippet.jumpable(1) then + if vim.snippet.active({ direction = 1 }) then return '<cmd>lua vim.snippet.jump(1)<cr>' else return '<Tab>' @@ -4359,8 +4377,8 @@ vim.snippet.jumpable({direction}) *vim.snippet.jumpable()* • {direction} (`vim.snippet.Direction`) Navigation direction. -1 for previous, 1 for next. - Return: ~ - (`boolean`) +vim.snippet.stop() *vim.snippet.stop()* + Exits the current snippet. ============================================================================== diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt index e7b62f4c6c..cd0b648560 100644 --- a/runtime/doc/luaref.txt +++ b/runtime/doc/luaref.txt @@ -932,7 +932,7 @@ implicit extra parameter `self`. Thus, the statement is syntactic sugar for - `t.a.b.c:f = function (self, (` `params` `)` `body` `end` + `t.a.b.c:f = function (` `self`, `params` `)` `body` `end` ============================================================================== 2.6 Visibility Rules *lua-visibility* diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 68206dd494..9ec34d5d52 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -604,7 +604,7 @@ instead. Example: > map <Leader>A oanother line<Esc> Works like: > map \A oanother line<Esc> -But after: +But after: > let mapleader = "," It works like: > map ,A oanother line<Esc> diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index c3154fc372..afe64300e7 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -114,6 +114,13 @@ wiped out a buffer which contains a mark or is referenced in another way. You cannot have two buffers with exactly the same name. This includes the path leading to the file. + *E1513* > + Cannot switch buffer. 'winfixbuf' is enabled + +If a window has 'winfixbuf' enabled, you cannot change that window's current +buffer. You need to set 'nowinfixbuf' before continuing. You may use [!] to +force the window to switch buffers, if your command supports it. + *E72* > Close error on swap file diff --git a/runtime/doc/news-0.10.txt b/runtime/doc/news-0.10.txt new file mode 100644 index 0000000000..8a0e7e92e7 --- /dev/null +++ b/runtime/doc/news-0.10.txt @@ -0,0 +1,473 @@ +*news-10.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Notable changes since Nvim 0.9 *news-0.10* + +For changes in the previous release, see |news-0.9|. + + Type |gO| to see the table of contents. + +============================================================================== +BREAKING CHANGES + +These changes may require adaptations in your config or plugins. + +• API: + • |nvim_open_win()| now blocks all autocommands when `noautocmd` is set, + rather than just those from setting the `buffer` to display in the window. + +• Defaults: + • Default color scheme has been updated to be "Nvim branded" and accessible. + Use `:colorscheme vim` to revert to the old legacy color scheme. + • These Nvim specific highlight groups 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. + +• Editor: + • When switching windows, |CursorMoved| autocommands trigger when Nvim is + back on the main loop rather than immediately. This is more compatible + with Vim. + • "#" followed by a digit no longer stands for a function key at the start + of the lhs of a mapping. + • |shm-q| now fully hides macro recording message instead of only shortening it. + • Signs placed through the legacy |sign-commands| are now stored and + displayed as |extmarks| internally. Along with the following changes: + • A sign placed twice in the same group with the same identifier will be + moved. + • Legacy signs are always deleted along with the line it is placed on. + • Legacy and extmark signs will show up in both |:sign-place-list| and + |nvim_buf_get_extmarks()|. + • Legacy and extmark signs are displayed and listed with the same priority: + line number -> priority -> sign id -> recently placed + • `:behave` was removed. + • If you used `:behave xterm`, the following is equivalent: >vim + + set mousemodel=extend +< + • If you used `:behave mswin`, the following is equivalent: >vim + + set selection=exclusive + set selectmode=mouse,key + set mousemodel=popup + set keymodel=startsel,stopsel +< +• Events: + • Returning any truthy value from a callback passed to + |nvim_create_autocmd()| (rather than just `true`) will delete the + autocommand. + +• LSP: + • |LanguageTree:parse()| will no longer parse injections by default and now + requires an explicit range argument to be passed. If injections are + required, provide an explicit range via `parser:parse({ start_row, end_row })`. + • |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. + • |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. + • |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()|. + • |LspRequest| and LspProgressUpdate (renamed to |LspProgress|) autocmds + were promoted from |User| autocmds to first class citizens. + +• Lua: + • |-l| ensures output ends with a newline if the script prints messages and + doesn't cause Nvim to exit. + • Removed functions from the |vim.json| module: + • Unnecessary, undocumented functions which caused global side-effects. + • `vim.json.null` is redundant with `vim.NIL`. + • `vim.json.array_mt` (and related) is redundant with `vim.empty_dict()`. + • |vim.islist()| now checks whether a table is actually list-like (i.e., has + integer keys without gaps and starting from 1). For the previous behavior + (only check for integer keys, allow gaps or not starting with 1), use + |vim.isarray()|. + • Renamed `vim.treesitter.playground` to `vim.treesitter.dev`. + +• Options: + • Removed some Vim 5.0<= option compatibilities: + • 'backspace' no longer supports number values. Instead: + • for `backspace=0` set `backspace=` (empty) + • for `backspace=1` set `backspace=indent,eol` + • for `backspace=2` set `backspace=indent,eol,start` (default behavior in Nvim) + • for `backspace=3` set `backspace=indent,eol,nostop` + • 'backupdir' and 'directory' will no longer remove a `>` at the start of + the option. + • |OptionSet| autocommand args |v:option_new|, |v:option_old|, + |v:option_oldlocal|, |v:option_oldglobal| now have the type of the option + instead of always being strings. |v:option_old| is now the old global + value for all global-local options, instead of just string global-local + options. + • Local value for a global-local number/boolean option is now unset when the + option is set (e.g. using |:set| or |nvim_set_option_value()|) without + a scope, which means they now behave the same way as string options. + +• Plugins: + • |:TOhtml| has been rewritten in Lua to support Nvim-specific decorations, + and many options have been removed. + +• Treesitter: + • 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|. + +• TUI: + • 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 + set guicursor+=n-v-c:blinkon500-blinkoff500 +< + +============================================================================== +NEW FEATURES + +The following new features were added. + +• API: + • Passing 0 to |nvim_get_chan_info()| gets info about the current channel. + • |nvim_buf_set_extmark()| supports inline virtual text. + • |nvim_win_text_height()| computes the number of screen lines occupied + by a range of text in a given window. + • New RPC client type `msgpack-rpc` is added for |nvim_set_client_info()| to + support fully MessagePack-RPC compliant clients. + • Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or + |nvim_win_set_config()|. + • |nvim_input_mouse()| supports mouse buttons "x1" and "x2". + • Added "force_crlf" option field in |nvim_open_term()|. + • Added |nvim_tabpage_set_win()| to set the current window of a tabpage. + • |nvim__win_add_ns()| can bind a |namespace| to a window-local scope(s). + • Extmarks opt-in to this scoping via the `scoped` flag of |nvim_buf_set_extmark()|. + • Mapping APIs now support abbreviations when mode short-name has suffix "a". + • Floating windows can now show footer with new `footer` and `footer_pos` + config fields. Uses |hl-FloatFooter| by default. + • |extmarks| can set a "url" highlight attribute, so the text region can + become a clickable hyperlink (assuming UI support). The TUI renders URLs + using the OSC 8 control sequence, enabling clickable text in supporting + terminals. + • |nvim_open_win()| and |nvim_win_set_config()| now support opening normal + (split) windows, moving floating windows into split windows, and opening + windows in non-current tabpages. + • Flags 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. + • Extmarks now fully support multi-line ranges, and a single extmark can be + used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()| + API function already allowed you to define such ranges, but highlight + regions were not rendered consistently for a range that covers more than + one line break. This has now been fixed. Signs defined as part of + a multi-line extmark also apply to every line in the range, not just the + first. In addition, |nvim_buf_get_extmarks()| has gained an "overlap" + option to return such ranges even if they started before the specified + position. + +• Defaults: + • The `workspace/didChangeWatchedFiles` LSP client capability is now enabled + by default on Mac and Windows. Disabled on Linux since there currently + isn't a viable backend for watching files that scales well for large + directories. + • On Windows 'isfname' does not include ":". Drive letters are handled + correctly without it. (Use |gF| for filepaths suffixed with ":line:col"). + • 'comments' includes "fb:•". + • 'shortmess' includes the "C" flag. + • 'grepprg' uses the -H and -I flags for grep by default, + and defaults to using ripgrep if available. + • "]d" and "[d" in Normal mode map to |vim.diagnostic.goto_next()| and + |vim.diagnostic.goto_prev()|, respectively. |]d-default| |[d-default| + • <C-W>d (and <C-W><C-D>) map to |vim.diagnostic.open_float()| + |CTRL-W_d-default| + • |vim.lsp.start()| sets the following default keymaps (assuming server + support): + • |K| in Normal mode maps to |vim.lsp.buf.hover()|, unless 'keywordprg' + was customized before calling |vim.lsp.start()|. + • Automatic linting of treesitter query files (see |ft-query-plugin|). + Can be disabled via: >lua + vim.g.query_lint_on = {} +< + • Enabled treesitter highlighting for: + • Treesitter query files + • Vim help files + • Lua files + +• Editor: + • Better cmdline completion for string option value. |complete-set-option| + • Try it with `:set listchars=<Tab>` + • By default, the swapfile "ATTENTION" |E325| dialog is skipped if the + swapfile is owned by a running Nvim process, instead of prompting. If you + always want the swapfile dialog, delete the default SwapExists handler: + `autocmd! nvim_swapfile`. |default-autocmds| + • Navigating the |jumplist| with CTRL+O, CTRL+I behaves more intuitively + when deleting buffers, and avoids "invalid buffer" cases. #25461 + • |:fclose| command. + • |v_Q-default| and |v_@-default| repeat a register for each line of a linewise + visual selection. + • Clicking on a tabpage in the tabline with the middle mouse button closes it. + • |:checkhealth| buffer can be opened in a split window using modifiers like + |:vertical|, |:horizontal| and |:botright|. + +• Events: + • |vim.on_key()| callbacks receive a second argument for keys typed before + mappings are applied. + +• LSP: + • LSP method names are available in |vim.lsp.protocol.Methods|. + • Implemented LSP inlay hints: |lsp-inlay_hint| + 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 + • Implemented LSP type hierarchy: |vim.lsp.buf.typehierarchy()| + https://microsoft.github.io/language-server-protocol/specification/#textDocument_prepareTypeHierarchy + • |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 + responds with the `positionEncoding` capability in its initialization + response, Nvim automatically sets the client's `offset_encoding` field. + • Dynamic registration of LSP capabilities. An implication of this change is + that checking a client's `server_capabilities` is no longer a sufficient + 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`. + • `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.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. + • |vim.lsp.start()| accepts a "silent" option for suppressing messages + if an LSP server failed to start. + • |vim.lsp.buf.definition()|, |vim.lsp.buf.declaration()|, + |vim.lsp.buf.type_definition()|, and |vim.lsp.buf.implementation()| now + support the `loclist` field of |vim.lsp.ListOpts|. + +• Lua: + • |:lua| with a |[range]| executes that range as Lua code, in any buffer. + • |:source| without arguments treats a buffer with 'filetype' of "lua" as + Lua code regardless of its extension. + • Vimscript function |exists()| supports checking |v:lua| functions. + • |vim.iter()| is a generic interface for all |iterable| objects (tables, + |iterator|s). + • |vim.snippet| provides a mode for expanding and navigating snippets. + • |vim.ringbuf()| is a generic ring buffer (data structure). + • |vim.deepcopy()| gained a `noref` argument to avoid hashing table values. + • |vim.keycode()| translates keycodes in a string. + • |vim.system()| runs commands / starts processes. + • |vim.lpeg| and |vim.re| expose the bundled Lpeg expression grammar parser + and its regex interface. + • |vim.base64.encode()| and |vim.base64.decode()| encode and decode strings + using Base64 encoding. + • |vim.text.hexencode()| and |vim.text.hexdecode()| convert strings to and + from byte representations. + • |vim.ui.open()| opens URIs using the system default handler (macOS `open`, + Windows `explorer`, Linux `xdg-open`, etc.) + • |vim.wo| can now be double indexed for |:setlocal| behaviour. Currently + only `0` for the buffer index is supported. + • Improved messages for type errors in `vim.api.*` calls (including `opts` params). + • Lua type annotations for: + • `vim.*` + • `vim.fn.*` + • `vim.api.*` + • `vim.v.*` + • Functions that take a severity as an optional parameter (e.g. + |vim.diagnostic.get()|) now also accept a list of severities |vim.diagnostic.severity| + • |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.diagnostic.is_enabled()| + • |vim.version.le()|, |vim.version.ge()| + • |vim.fs.root()| finds project root directories from a list of "root + markers". + • |vim.tbl_contains()| now works for general tables and allows specifying + a predicate function that is checked for each value. (Use + |vim.list_contains()| for checking list-like tables (integer keys without + gaps) for literal values.) + • |vim.region()| can use a string accepted by |getpos()| as position. + +• Options: + • 'winfixbuf' keeps a window focused onto a specific buffer + • 'smoothscroll' option to scroll by screen line rather than by text line + when 'wrap' is set. + • '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. + • 'complete' option supports "f" flag for completing buffer names. + • 'completeopt' option supports "popup" flag to show extra information in + a floating window. + • 'errorfile' (|-q|) accepts `-` as an alias for stdin. + +• Performance: + • 'diffopt' "linematch" scoring algorithm now favours larger and less groups + https://github.com/neovim/neovim/pull/23611 + • 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. + +• Plugins: + • Nvim now includes |commenting| support. + • |:Man| supports the `:hide` modifier to open page in the current window. + • |:Man| respects 'wrapmargin' + +• Startup: + • |$NVIM_APPNAME| can be set to a relative path instead of only a name. + • |--startuptime| reports startup times for both processes (TUI + server) as + separate sections. + +• Terminal: + • |:terminal| accepts some |:command-modifiers| (specifically |:horizontal| + and those that affect splitting a window). + • Terminal buffers emit a |TermRequest| autocommand event when the child + process emits an OSC or DCS control sequence. + • Terminal buffers respond to OSC background and foreground requests. + |default-autocmds| + +• Treesitter: + • Bundled parsers and queries (highlight, folds) for Markdown, Python, and + Bash. + • |:InspectTree| shows root nodes. + • |:InspectTree| now supports |folding|. + • |:InspectTree| shows node ranges in 0-based instead of 1-based indexing. + • |vim.treesitter.foldexpr()| now recognizes folds captured using a + quantified query pattern. + • |vim.treesitter.query.omnifunc()| provides completion in treesitter query + files (set by default). + • |vim.treesitter.query.edit()| provides live editing of treesitter queries. + • |Query:iter_matches()| now has the ability to set the maximum start depth + for matches. + • `@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. + • `@injection.filename` will try to match the node text via + |vim.filetype.match()| and treat the result as a language name in the same + way as `@injection.language`. + • The `#set!` directive supports `injection.self` and `injection.parent` for + injecting either the current node's language or the parent + |LanguageTree|'s language, respectively. + • The `#set!` directive can set the "url" property of a node to have the + node emit a hyperlink. Hyperlinks are UI specific: in the TUI, the OSC 8 + control sequence is used. + • Improved error messages for query parsing. + +• TUI: + • Builtin TUI can now recognize "super" (|<D-|) and "meta" (|<T-|) modifiers + in a terminal emulator that supports |tui-csiu|. + • The |TermResponse| event can be used with |v:termresponse| to read escape + sequence responses from the host terminal. + • A clipboard provider which uses OSC 52 to copy the selection to the system + clipboard is now bundled by default and will be automatically enabled under + certain conditions. |clipboard-osc52| + • 'termsync' option asks the host terminal to buffer screen updates until + the redraw cycle is complete. Requires support from the host terminal. + +• UI: + • Enhanced support for rendering multibyte characters using composing + characters: the maximum limit was increased from 1+6 codepoints to + 31 bytes, which is guaranteed to fit all chars from before but often more. + • NOTE: the regexp engine still has a hard-coded limit of considering + 6 composing chars only. + + +============================================================================== +CHANGED FEATURES + +These existing features changed their behavior. + +• API: + • |nvim_buf_call()| and |nvim_win_call()| now preserve any return value (NB: + not multiple return values) + +• Editor: + • |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> + +• LSP: + • LSP hover and signature help now use Treesitter for highlighting of + Markdown content. Note that highlighting of code examples requires + a matching parser and may be affected by custom queries. + • |LspRequest| autocmd callbacks contain more information about the LSP + request status update that occurred. + +• Lua: + • |vim.wait()| cannot be called in |api-fast|. + • |vim.diagnostic.config()| now accepts virtual text relevant options to + |nvim_buf_set_extmark()| (e.g. "virt_text_pos" and "hl_mode") in its + "virtual_text" table, which gives users more control over how diagnostic + virtual text is displayed. + • |vim.diagnostic.get()| and |vim.diagnostic.count()| accept multiple + namespaces rather than just a single namespace. + • |vim.diagnostic.enable()| gained new parameters, and the old signature is + deprecated. + • |vim.diagnostic.config()| now accepts a function for the virtual_text.prefix + option, which allows for rendering e.g., diagnostic severities differently. + +• Options: + • Attempting to set an invalid keycode option (e.g. `set t_foo=123`) no + longer gives an error. + +• Terminal: + • Terminal buffers started with no arguments (and use 'shell') close + automatically if the job exited without error, eliminating the (often + unwanted) "[Process exited 0]" message. |default-autocmds| + +• 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 + +These deprecated features were removed. + +• Vimball support, including `:Vimuntar` command + +• Support for legacy treesitter injection queries + +• 'shortmess' flags: + • |shm-f|. Always use "(3 of 5)", never "(file 3 of 5)". + • |shm-i|. Always use "[noeol]". + • |shm-x|. Always use "[dos]", "[unix]" and "[mac]". + • |shm-n|. Always use "[New]". + +============================================================================== +DEPRECATIONS + +See |deprecated-0.10|. + + vim:tw=78:ts=8:sw=2:et:ft=help:norl: diff --git a/runtime/doc/news-0.9.txt b/runtime/doc/news-0.9.txt index 789bc9e0bc..7905d6c3e3 100644 --- a/runtime/doc/news-0.9.txt +++ b/runtime/doc/news-0.9.txt @@ -4,7 +4,7 @@ NVIM REFERENCE MANUAL -Notable changes in Nvim 0.9 from 0.8 *news-0.9* +Notable changes since Nvim 0.8 *news-0.9* Type |gO| to see the table of contents. @@ -162,7 +162,7 @@ The following new APIs or features were added. • |vim.diagnostic| now supports LSP DiagnosticsTag. See: https://microsoft.github.io/language-server-protocol/specification/#diagnosticTag -• |vim.diagnostic.is_disabled()| checks if diagnostics are disabled in a given +• vim.diagnostic.is_disabled() checks if diagnostics are disabled in a given buffer or namespace. • Treesitter captures can now be transformed by directives. This will allow @@ -290,34 +290,6 @@ The following deprecated functions or APIs were removed. ============================================================================== DEPRECATIONS -The following functions are now deprecated and will be removed in the next -release. - -• |vim.treesitter.language.add()| replaces `vim.treesitter.language.require_language()` - -• |vim.treesitter.get_node_at_pos()| and |vim.treesitter.get_node_at_cursor()| - are both deprecated in favor of |vim.treesitter.get_node()|. - -• `vim.api.nvim_get_hl_by_name()`, `vim.api.nvim_get_hl_by_id()` were deprecated, use |nvim_get_hl()| instead. - -• The following top level Treesitter functions have been moved: - `vim.treesitter.inspect_language()` -> `vim.treesitter.language.inspect()` - `vim.treesitter.get_query_files()` -> `vim.treesitter.query.get_files()` - `vim.treesitter.set_query()` -> `vim.treesitter.query.set()` - `vim.treesitter.query.set_query()` -> `vim.treesitter.query.set()` - `vim.treesitter.get_query()` -> `vim.treesitter.query.get()` - `vim.treesitter.query.get_query()` -> `vim.treesitter.query.get()` - `vim.treesitter.parse_query()` -> `vim.treesitter.query.parse()` - `vim.treesitter.query.parse_query()` -> `vim.treesitter.query.parse()` - `vim.treesitter.add_predicate()` -> `vim.treesitter.query.add_predicate()` - `vim.treesitter.add_directive()` -> `vim.treesitter.query.add_directive()` - `vim.treesitter.list_predicates()` -> `vim.treesitter.query.list_predicates()` - `vim.treesitter.list_directives()` -> `vim.treesitter.query.list_directives()` - `vim.treesitter.query.get_range()` -> `vim.treesitter.get_range()` - `vim.treesitter.query.get_node_text()` -> `vim.treesitter.get_node_text()` - -• |nvim_exec()| is now deprecated in favor of |nvim_exec2()|. - -• Renamed |vim.pretty_print()| to |vim.print()|. +See |deprecated-0.9|. vim:tw=78:ts=8:sw=2:et:ft=help:norl: diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 3029414500..708e127136 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -4,529 +4,156 @@ NVIM REFERENCE MANUAL -Notable changes in Nvim 0.10 from 0.9 *news* +Notable changes since Nvim 0.10 *news* -For changes in Nvim 0.9, see |news-0.9|. +For changes in the previous release, see |news-0.10|. Type |gO| to see the table of contents. ============================================================================== -BREAKING CHANGES *news-breaking* - -The following changes may require adaptations in user config or plugins. - -• 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 - - set guicursor+=n-v-c:blinkon500-blinkoff500 -< -• |vim.tbl_islist()| now checks whether a table is actually list-like (i.e., - has integer keys without gaps and starting from 1). For the previous - behavior (only check for integer keys, allow gaps or not starting with 1), - use |vim.tbl_isarray()|. - -• "#" followed by a digit no longer stands for a function key at the start of - the lhs of a mapping. - -• `:behave` was removed. - - If you used `:behave xterm`, the following is equivalent: >vim - - set mousemodel=extend -< - - If you used `:behave mswin`, the following is equivalent: >vim - - set selection=exclusive - set selectmode=mouse,key - set mousemodel=popup - set keymodel=startsel,stopsel -< -• When switching windows, |CursorMoved| autocommands trigger when Nvim is back - in the main loop rather than immediately. This is more compatible with Vim. - -• |-l| ensures output ends with a newline if the script prints messages and - doesn't cause Nvim to exit. - -• |LspRequest| and LspProgressUpdate (renamed to |LspProgress|) autocmds were - promoted from a |User| autocmd to first class citizen. - -• Renamed `vim.treesitter.playground` to `vim.treesitter.dev`. - -• Removed functions from the |vim.json| module: - • Unnecessary, undocumented functions which caused global side-effects. - • `vim.json.null` is redundant with `vim.NIL`. - • `vim.json.array_mt` (and related) is redundant with `vim.empty_dict()`. - -• Removed some Vim 5.0<= option compatibilities: - • |'backspace'| no longer supports number values. Instead: - • for `backspace=0` set `backspace=` (empty) - • for `backspace=1` set `backspace=indent,eol` - • for `backspace=2` set `backspace=indent,eol,start` (default behavior in Nvim) - • for `backspace=3` set `backspace=indent,eol,nostop` - • |'backupdir'| and |'directory'| will no longer remove a `>` at the start - of the option. - -• |LanguageTree:parse()| will no longer parse injections by default and - now requires an explicit range argument to be passed. If injections are - required, provide an explicit range via `parser:parse({ start_row, end_row })`. - -• |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. - -• |OptionSet| autocommand args |v:option_new|, |v:option_old|, - |v:option_oldlocal|, |v:option_oldglobal| now have the type of the option - instead of always being strings. |v:option_old| is now the old global value - for all global-local options, instead of just string global-local options. - -• Local value for a global-local number/boolean option is now unset when - the option is set (e.g. using |:set| or |nvim_set_option_value()|) without a - scope, which means they now behave the same way as string options. - -• Signs placed through the legacy |sign-commands| are now stored and displayed - as |extmarks| internally. Along with the following changes: - • A sign placed twice in the same group with the same identifier will be moved. - • Legacy signs are always deleted along with the line it is placed on. - • Legacy and extmark signs will show up in both |:sign-place-list| and |nvim_buf_get_extmarks()|. - • 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. + ====== Remove this section before release. ====== -• Removed `vim.treesitter.foldtext` as transparent foldtext is now supported - https://github.com/neovim/neovim/pull/20750 +The following changes to UNRELEASED features were made during the development +cycle (Nvim HEAD, the "master" branch). ============================================================================== -NEW FEATURES *news-features* - -The following new APIs and features were added. - -• Performance: - • 'diffopt' "linematch" scoring algorithm now favours larger and less groups - https://github.com/neovim/neovim/pull/23611 - • 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|. - -• |vim.ringbuf()| creates ring buffers. - -• |vim.keycode()| translates keycodes in a string. - -• |'smoothscroll'| option to scroll by screen line rather than by text line - when |'wrap'| is set. - -• |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. - -• |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. - -• Mapping APIs now support abbreviations when mode short-name has suffix "a". - -• Better cmdline completion for string option value. |complete-set-option| - -• Builtin TUI can now recognize "super" (|<D-|) and "meta" (|<T-|) modifiers in a - terminal emulator that supports |tui-csiu|. - -• Editor - • By default, the swapfile "ATTENTION" |E325| dialog is skipped if the - swapfile is owned by a running Nvim process, instead of prompting. If you - always want the swapfile dialog, delete the default SwapExists handler: - `autocmd! nvim_swapfile`. |default-autocmds| - -• LSP - • LSP method names are available in |vim.lsp.protocol.Methods|. - • Implemented LSP inlay hints: |lsp-inlay_hint| - 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 - • |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 - responds with the `positionEncoding` capability in its initialization - response, Nvim automatically sets the client's `offset_encoding` field. - • Dynamic registration of LSP capabilities. An implication of this change is - that checking a client's `server_capabilities` is no longer a sufficient - 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`. - • `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. - • |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 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. - • |: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.) - -• |vim.wo| can now be double indexed for |:setlocal| behaviour. Currently only - `0` for the buffer index is currently supported. - -• Lua type annotations for: - • `vim.*` - • `vim.fn.*` - • `vim.api.*` - • `vim.v.*` - -• Improved messages for type errors in `vim.api.*` calls (including `opts` params) +BREAKING CHANGES *news-breaking* -• Functions that take a severity as an optional parameter (e.g. - |vim.diagnostic.get()|) now also accept a list of severities |vim.diagnostic.severity| +These changes may require adaptations in your config or plugins. -• New RPC client type `msgpack-rpc` is added for |nvim_set_client_info()| to - support fully MessagePack-RPC compliant clients. +API -• Floating windows can now show footer with new `footer` and `footer_pos` - config fields. Uses |hl-FloatFooter| by default. +• `vim.rpcnotify(0)` and `rpcnotify(0)` broadcast to ALL channels. Previously + they would "multicast" only to subscribed channels (controlled by + `nvim_subscribe()`). Plugins and clients that want "multicast" behavior must + now maintain their own list of channels. + • In the future, |vim.rpcnotify()| may accept a list of channels, if there + is demand for this use-case. -• Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or - |nvim_win_set_config()|. +DEFAULTS -• |:terminal| command now accepts some |:command-modifiers| (specifically - |:horizontal| and those that affect splitting a window). +• TODO -• |$NVIM_APPNAME| can be set to a relative path instead of only a name. +EDITOR -• |:fclose| command. +• The order in which signs are placed was changed. Higher priority signs will now appear left of lower priority signs. -• |vim.snippet| handles expansion of snippets in LSP format. +EVENTS -• 'complete' option supports "f" flag for completing buffer names. +• TODO -• |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. - -• A clipboard provider which uses OSC 52 to copy the selection to the system - clipboard is now bundled by default and will be automatically enabled under - certain conditions. |clipboard-osc52| - -• '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. +LSP -• 'completeopt' option supports "popup" flag to show extra information in a - floating window. +• TODO -• |nvim_input_mouse()| supports mouse buttons "x1" and "x2". +LUA -• |v_Q-default| and |v_@-default| repeat a register for each line of a visual - selection. +• TODO -• |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. +OPTIONS -• |vim.deepcopy()| has a `noref` argument to avoid hashing table values. +• TODO -• Terminal buffers emit a |TermRequest| autocommand event when the child - process emits an OSC or DCS control sequence. +PLUGINS -• Terminal buffers respond to OSC background and foreground requests. |default-autocmds| +• TODO -• |vim.version.le()| and |vim.version.ge()| are added to |vim.version|. +TREESITTER -• |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. +• TODO -• Added |nvim_tabpage_set_win()| to set the current window of a tabpage. +TUI -• Clicking on a tabpage in the tabline with the middle mouse button closes it. +• TODO -• |namespace| can now have window scopes. |nvim_win_add_ns()| +============================================================================== +NEW FEATURES *news-features* -• |extmarks| option `scoped`: only show the extmarks in its namespace's scope. +The following new features were added. -============================================================================== -CHANGED FEATURES *news-changed* +API -The following changes to existing APIs or features add new behavior. +• TODO -• |vim.tbl_contains()| now works for general tables and allows specifying a - predicate function that is checked for each value. (Use |vim.list_contains()| - for checking list-like tables (integer keys without gaps) for literal values.) +DEFAULTS -• |vim.region()| can use a string accepted by |getpos()| as position. +• Keymaps: + - |grn| in Normal mode maps to |vim.lsp.buf.rename()| + - |grr| in Normal mode maps to |vim.lsp.buf.references()| + - |gra| in Normal and Visual mode maps to |vim.lsp.buf.code_action()| + - CTRL-S in Insert mode maps to |vim.lsp.buf.signature_help()| -• |vim.diagnostic.config()| now accepts a function for the virtual_text.prefix - option, which allows for rendering e.g., diagnostic severities differently. +EDITOR -• Defaults: - • On Windows 'isfname' does not include ":". Drive letters are handled - correctly without it. (Use |gF| for filepaths suffixed with ":line:col"). - • 'comments' includes "fb:•". - • 'shortmess' includes the "C" flag. - • Automatic linting of treesitter query files (see |ft-query-plugin|). - Can be disabled via: >lua - vim.g.query_lint_on = {} -< - • Enabled treesitter highlighting for treesitter query files. - • Enabled treesitter highlighting for help files. - • Enabled treesitter highlighting for Lua files. +• TODO -• 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. +EVENTS -• |LspRequest| autocmd callbacks now contain additional information about the LSP - request status update that occurred. +• TODO -• |:source| without arguments treats a buffer with its 'filetype' set to "lua" - as Lua code regardless of its extension. +LSP -• |:lua| with a |[range]| executes that range in the current buffer as Lua code - regardless of its extension. +• TODO -• |:checkhealth| buffer now implements |folding|. The initial folding status is - defined by the 'foldenable' option. +LUA -• |:Man| now respects 'wrapmargin' +• TODO -• |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 +OPTIONS - :call netrw#BrowseX(expand(exists("g:netrw_gx")? g:netrw_gx : '<cfile>'), netrw#CheckIfRemote())<CR> +• TODO -• |vim.lsp.start()| now maps |K| to use |vim.lsp.buf.hover()| if the server - supports it, unless |'keywordprg'| was customized before calling - |vim.lsp.start()|. +PERFORMANCE -• Terminal buffers started with no arguments (and use 'shell') close - automatically if the job exited without error, eliminating the (often - unwanted) "[Process exited 0]" message. +• TODO -• |vim.diagnostic.config()| now accepts virtual text relevant options to - |nvim_buf_set_extmark()| (e.g. "virt_text_pos" and "hl_mode") in its - "virtual_text" table, which gives users more control over how diagnostic - virtual text is displayed. +PLUGINS -• Extmarks now fully support multi-line ranges, and a single extmark can be - used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()| - API function already allowed you to define such ranges, but highlight regions - were not rendered consistently for a range that covers more than one line break. - This has now been fixed. Signs defined as part of a multi-line extmark also - apply to every line in the range, not just the first. - In addition, |nvim_buf_get_extmarks()| has gained an "overlap" option to - return such ranges even if they started before the specified position. +• TODO -• 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. +STARTUP -• LSP hover and signature help now use Treesitter for highlighting of Markdown - content. - Note that syntax highlighting of code examples requires a matching parser - and may be affected by custom queries. +• TODO -• Support for rendering multibyte characters using composing characters has been - enhanced. The maximum limit have been increased from 1+6 codepoints to - 31 bytes, which is guaranteed to fit all chars from before but often more. +TERMINAL - NOTE: the regexp engine still has a hard-coded limit of considering - 6 composing chars only. +• TODO -• |vim.wait()| is no longer allowed to be called in |api-fast|. +TREESITTER -• Vimscript function |exists()| supports checking |v:lua| functions. +• TODO -• Added "force_crlf" option field in |nvim_open_term()|. +TUI -• Attempting to set an invalid keycode option (e.g. `set t_foo=123`) no longer - gives an error. +• TODO -• Passing 0 to |nvim_get_chan_info()| gets info about the current channel. +UI -• |:checkhealth| buffer can now be opened in a split window using modifiers like - |:vertical|, |:horizontal| and |:botright|. +• TODO -• |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. +• |CompleteDone| now sets the `reason` key in `v:event` which specifies the reason + for completion being done. -• |--startuptime| reports the startup times for both processes (TUI + server) as separate sections. +============================================================================== +CHANGED FEATURES *news-changed* -• |nvim_buf_call()| and |nvim_win_call()| now preserves any return value (NB: not multiple return values) +These existing features changed their behavior. -• 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 }`. +• N/A ============================================================================== REMOVED FEATURES *news-removed* -The following deprecated functions or APIs were removed. - -• Vimball support - - :Vimuntar command - -• Support for legacy treesitter injection queries +These deprecated features were removed. -• '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]" - - |shm-n|. Always use "[New]". +• N/A ============================================================================== 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. - - |health#report_ok|, |vim.health.report_ok()| Use |vim.health.ok()| instead. - - |health#report_start|, |vim.health.report_start()| Use |vim.health.start()| instead. - - |health#report_warn|, |vim.health.report_warn()| Use |vim.health.warn()| instead. - -• |API| functions: - - |nvim_buf_get_option()| Use |nvim_get_option_value()| instead. - - |nvim_buf_set_option()| Use |nvim_set_option_value()| instead. - - |nvim_get_option()| Use |nvim_get_option_value()| instead. - - |nvim_set_option()| Use |nvim_set_option_value()| instead. - - |nvim_win_get_option()| Use |nvim_get_option_value()| instead. - - |nvim_win_set_option()| Use |nvim_set_option_value()| instead. - -• vim.lsp functions: - - |vim.lsp.util.get_progress_messages()| Use |vim.lsp.status()| instead. - - |vim.lsp.get_active_clients()| Use |vim.lsp.get_clients()| instead. - - |vim.lsp.for_each_buffer_client()| Use |vim.lsp.get_clients()| 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()| - - |vim.lsp.util.extract_completion_items()| - - |vim.lsp.util.parse_snippet()| - - |vim.lsp.util.text_document_completion_list_to_complete_items()| - -• `vim.loop` has been renamed to |vim.uv|. - -• 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()| +See |deprecated-0.11|. 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 d4e05cee26..a6ebc7e958 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -126,6 +126,46 @@ color index is just forwarded. Editor highlighting (|syntax-highlighting|, |highlight-groups|, etc.) has higher precedence: it is applied after terminal colors are resolved. +------------------------------------------------------------------------------ +EVENTS *terminal-events* + +Applications running in a :terminal buffer can send requests, which Nvim +exposes via the |TermRequest| event. + +OSC 7: change working directory *terminal-osc7* + +To handle OSC 7 emitted from :terminal processes, this code will :cd to the +directory indicated in the request. >lua + + vim.api.nvim_create_autocmd({ 'TermRequest' }, { + desc = 'Handles OSC 7 dir change requests', + callback = function(ev) + if string.sub(vim.v.termrequest, 1, 4) == '\x1b]7;' then + local dir = string.gsub(vim.v.termrequest, '\x1b]7;file://[^/]*', '') + if vim.fn.isdirectory(dir) == 0 then + vim.notify('invalid dir: '..dir) + return + end + vim.api.nvim_buf_set_var(ev.buf, 'osc7_dir', dir) + if vim.o.autochdir and vim.api.nvim_get_current_buf() == ev.buf then + vim.cmd.cd(dir) + end + end + end + }) + vim.api.nvim_create_autocmd({ 'BufEnter', 'WinEnter', 'DirChanged' }, { + callback = function(ev) + if vim.b.osc7_dir and vim.fn.isdirectory(vim.b.osc7_dir) == 1 then + vim.cmd.cd(vim.b.osc7_dir) + end + end + }) + +To try it out, select the above code and source it with `:'<,'>lua`, then run +this command in a :terminal buffer: > + + printf "\033]7;file://./foo/bar\033\\" + ============================================================================== Status Variables *terminal-status* diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 133b2bc33c..5570e62ab8 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -270,6 +270,7 @@ created, thus they behave slightly differently: Option Reason ~ 'previewwindow' there can only be a single one 'scroll' specific to existing window + 'winfixbuf' specific to existing window 'winfixheight' specific to existing window 'winfixwidth' specific to existing window @@ -638,10 +639,9 @@ A jump table for the options with a short description can be found at |Q_op|. *'allowrevins'* *'ari'* *'noallowrevins'* *'noari'* 'allowrevins' 'ari' boolean (default off) global - Allow CTRL-_ in Insert and Command-line mode. This is default off, to - avoid that users that accidentally type CTRL-_ instead of SHIFT-_ get - into reverse Insert mode, and don't know how to get out. See - 'revins'. + Allow CTRL-_ in Insert mode. This is default off, to avoid that users + that accidentally type CTRL-_ instead of SHIFT-_ get into reverse + Insert mode, and don't know how to get out. See 'revins'. *'ambiwidth'* *'ambw'* 'ambiwidth' 'ambw' string (default "single") @@ -1442,7 +1442,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'commentstring' 'cms' string (default "") local to buffer A template for a comment. The "%s" in the value is replaced with the - comment text. For example, C uses "/*%s*/". Currently only used to + comment text. For example, C uses "/*%s*/". Used for |commenting| and to add markers for folding, see |fold-marker|. *'complete'* *'cpt'* *E535* @@ -2851,25 +2851,33 @@ A jump table for the options with a short description can be found at |Q_op|. This is a scanf-like string that uses the same format as the 'errorformat' option: see |errorformat|. + If ripgrep ('grepprg') is available, this option defaults to `%f:%l:%c:%m`. + *'grepprg'* *'gp'* -'grepprg' 'gp' string (default "grep -n ", - Unix: "grep -n $* /dev/null") +'grepprg' 'gp' string (default see below) global or local to buffer |global-local| Program to use for the |:grep| command. This option may contain '%' and '#' characters, which are expanded like when used in a command- line. The placeholder "$*" is allowed to specify where the arguments 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: >vim - set grepprg=grep\ -nH -< Special value: When 'grepprg' is set to "internal" the |:grep| command + Special value: When 'grepprg' is set to "internal" the |:grep| command works like |:vimgrep|, |:lgrep| like |:lvimgrep|, |:grepadd| like |:vimgrepadd| and |:lgrepadd| like |:lvimgrepadd|. See also the section |:make_makeprg|, since most of the comments there apply equally to 'grepprg'. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. + This option defaults to: + - `rg --vimgrep -uu ` if ripgrep is available (|:checkhealth|), + - `grep -HIn $* /dev/null` on Unix, + - `findstr /n $* nul` on Windows. + Ripgrep can perform additional filtering such as using .gitignore rules + and skipping hidden files. This is disabled by default (see the -u option) + to more closely match the behaviour of standard grep. + You can make ripgrep match Vim's case handling using the + -i/--ignore-case and -S/--smart-case options. + An |OptionSet| autocmd can be used to set it up to match automatically. *'guicursor'* *'gcr'* *E545* *E546* *E548* *E549* 'guicursor' 'gcr' string (default "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20") @@ -4952,9 +4960,6 @@ A jump table for the options with a short description can be found at |Q_op|. Minimum is 1, maximum is 100000. Only in |terminal| buffers. - Note: Lines that are not visible and kept in scrollback are not - reflown when the terminal buffer is resized horizontally. - *'scrollbind'* *'scb'* *'noscrollbind'* *'noscb'* 'scrollbind' 'scb' boolean (default off) local to window @@ -5696,8 +5701,7 @@ A jump table for the options with a short description can be found at |Q_op|. highlighted with |hl-NonText|. You may also want to add "lastline" to the 'display' option to show as much of the last line as possible. - NOTE: only partly implemented, currently works with CTRL-E, CTRL-Y - and scrolling with the mouse. + NOTE: partly implemented, doesn't work yet for |gj| and |gk|. *'softtabstop'* *'sts'* 'softtabstop' 'sts' number (default 0) @@ -6271,6 +6275,8 @@ A jump table for the options with a short description can be found at |Q_op|. "split" when both are present. uselast If included, jump to the previously used window when jumping to errors with |quickfix| commands. + If a window has 'winfixbuf' enabled, 'switchbuf' is currently not + applied to the split window. *'synmaxcol'* *'smc'* 'synmaxcol' 'smc' number (default 3000) @@ -6349,7 +6355,7 @@ A jump table for the options with a short description can be found at |Q_op|. appear wrong in many places. The value must be more than 0 and less than 10000. - There are four main ways to use tabs in Vim: + There are five main ways to use tabs in Vim: 1. Always keep 'tabstop' at 8, set 'softtabstop' and 'shiftwidth' to 4 (or 3 or whatever you prefer) and use 'noexpandtab'. Then Vim will use a mix of tabs and spaces, but typing <Tab> and <BS> will @@ -6882,6 +6888,7 @@ A jump table for the options with a short description can be found at |Q_op|. Level Messages ~ ---------------------------------------------------------------------- + 1 Enables Lua tracing (see above). Does not produce messages. 2 When a file is ":source"'ed, or |shada| file is read or written. 3 UI info, terminal capabilities. 4 Shell commands. @@ -7216,11 +7223,20 @@ A jump table for the options with a short description can be found at |Q_op|. will scroll 'window' minus two lines, with a minimum of one. When 'window' is equal to 'lines' minus one CTRL-F and CTRL-B scroll in a much smarter way, taking care of wrapping lines. - When resizing the Vim window, the value is smaller than 1 or more than - or equal to 'lines' it will be set to 'lines' minus 1. + When resizing the Vim window, and the value is smaller than 1 or more + than or equal to 'lines' it will be set to 'lines' minus 1. Note: Do not confuse this with the height of the Vim window, use 'lines' for that. + *'winfixbuf'* *'wfb'* *'nowinfixbuf'* *'nowfb'* +'winfixbuf' 'wfb' boolean (default off) + local to window + If enabled, the window and the buffer it is displaying are paired. + For example, attempting to change the buffer with |:edit| will fail. + Other commands which change a window's buffer such as |:cnext| will + also skip any window with 'winfixbuf' enabled. However if an Ex + command has a "!" modifier, it can force switching buffers. + *'winfixheight'* *'wfh'* *'nowinfixheight'* *'nowfh'* 'winfixheight' 'wfh' boolean (default off) local to window |local-noglobal| diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt index 17136ee650..1ef182127c 100644 --- a/runtime/doc/pattern.txt +++ b/runtime/doc/pattern.txt @@ -1375,6 +1375,19 @@ Finally, these constructs are unique to Perl: ============================================================================== 10. Highlighting matches *match-highlight* + *syntax-vs-match* + Note that the match highlight mechanism is independent + of |syntax-highlighting|, which is (usually) a buffer-local + highlighting, while matching is window-local, both methods + can be freely mixed. Match highlighting functions give you + a bit more flexibility in when and how to apply, but are + typically only used for temporary highlighting, without strict + rules. Both methods can be used to conceal text. + + Thus the matching functions like |matchadd()| won't consider + syntax rules and functions like |synconcealed()| and the + other way around. + *:mat* *:match* :mat[ch] {group} /{pattern}/ Define a pattern to highlight in the current window. It will diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt index d8fcd066a8..81acd9cf7e 100644 --- a/runtime/doc/pi_netrw.txt +++ b/runtime/doc/pi_netrw.txt @@ -446,10 +446,6 @@ settings are described below, in |netrw-browser-options|, and in messages don't always seem to show up this way, but one doesn't have to quit the window. - *g:netrw_win95ftp* =1 if using Win95, will remove four trailing blank - lines that o/s's ftp "provides" on transfers - =0 force normal ftp behavior (no trailing line removal) - *g:netrw_cygwin* =1 assume scp under windows is from cygwin. Also permits network browsing to use ls with time and size sorting (default if windows) @@ -825,8 +821,6 @@ set in the user's <.vimrc> file: (see also |netrw-settings| |netrw-protocol|) g:netrw_uid Holds current user-id for ftp. g:netrw_use_nt_rcp =0 don't use WinNT/2K/XP's rcp (default) =1 use WinNT/2K/XP's rcp, binary mode - g:netrw_win95ftp =0 use unix-style ftp even if win95/98/ME/etc - =1 use default method to do ftp > ----------------------------------------------------------------------- < *netrw-internal-variables* @@ -955,21 +949,8 @@ messages) you may write a NetReadFixup() function: endfunction > The NetReadFixup() function will be called if it exists and thus allows you to -customize your reading process. As a further example, <netrw.vim> contains -just such a function to handle Windows 95 ftp. For whatever reason, Windows -95's ftp dumps four blank lines at the end of a transfer, and so it is -desirable to automate their removal. Here's some code taken from <netrw.vim> -itself: -> - if has("win95") && g:netrw_win95ftp - fun! NetReadFixup(method, line1, line2) - if method == 3 " ftp (no <.netrc>) - let fourblanklines= line2 - 3 - silent fourblanklines .. "," .. line2 .. "g/^\s*/d" - endif - endfunction - endif -> +customize your reading process. + (Related topics: |ftp| |netrw-userpass| |netrw-start|) ============================================================================== @@ -2048,11 +2029,7 @@ passwords: better way to do that: I can use a regular ssh account which uses a password to access the material without the need to key-in the password each time. It's good for security and convenience. I tried ssh public key - authorization + ssh-agent, implementing this, and it works! Here are two - links with instructions: - - http://www.ibm.com/developerworks/library/l-keyc2/ - http://sial.org/howto/openssh/publickey-auth/ + authorization + ssh-agent, implementing this, and it works! Ssh hints: @@ -3397,16 +3374,7 @@ Example: Clear netrw's marked file list via a mapping on gu > (This section is likely to grow as I get feedback) (also see |netrw-debug|) *netrw-p1* - P1. I use windows 95, and my ftp dumps four blank lines at the {{{2 - end of every read. - - See |netrw-fixup|, and put the following into your - <.vimrc> file: - - let g:netrw_win95ftp= 1 - - *netrw-p2* - P2. I use Windows, and my network browsing with ftp doesn't sort by {{{2 + P1. I use Windows, and my network browsing with ftp doesn't sort by {{{2 time or size! -or- The remote system is a Windows server; why don't I get sorts by time or size? @@ -3432,8 +3400,8 @@ Example: Clear netrw's marked file list via a mapping on gu > modify its listing behavior. - *netrw-p3* - P3. I tried rcp://user@host/ (or protocol other than ftp) and netrw {{{2 + *netrw-p2* + P2. I tried rcp://user@host/ (or protocol other than ftp) and netrw {{{2 used ssh! That wasn't what I asked for... Netrw has two methods for browsing remote directories: ssh @@ -3441,8 +3409,8 @@ Example: Clear netrw's marked file list via a mapping on gu > When it comes time to do download a file (not just a directory listing), netrw will use the given protocol to do so. - *netrw-p4* - P4. I would like long listings to be the default. {{{2 + *netrw-p3* + P3. I would like long listings to be the default. {{{2 Put the following statement into your |vimrc|: > @@ -3451,8 +3419,8 @@ Example: Clear netrw's marked file list via a mapping on gu > Check out |netrw-browser-var| for more customizations that you can set. - *netrw-p5* - P5. My times come up oddly in local browsing {{{2 + *netrw-p4* + P4. My times come up oddly in local browsing {{{2 Does your system's strftime() accept the "%c" to yield dates such as "Sun Apr 27 11:49:23 1997"? If not, do a @@ -3461,16 +3429,16 @@ Example: Clear netrw's marked file list via a mapping on gu > let g:netrw_timefmt= "%X" (where X is the option) < - *netrw-p6* - P6. I want my current directory to track my browsing. {{{2 + *netrw-p5* + P5. I want my current directory to track my browsing. {{{2 How do I do that? Put the following line in your |vimrc|: > let g:netrw_keepdir= 0 < - *netrw-p7* - P7. I use Chinese (or other non-ascii) characters in my filenames, {{{2 + *netrw-p6* + P6. I use Chinese (or other non-ascii) characters in my filenames, {{{2 and netrw (Explore, Sexplore, Hexplore, etc) doesn't display them! (taken from an answer provided by Wu Yongwei on the vim @@ -3484,8 +3452,8 @@ Example: Clear netrw's marked file list via a mapping on gu > (...it is one more reason to recommend that people use utf-8!) - *netrw-p8* - P8. I'm getting "ssh is not executable on your system" -- what do I {{{2 + *netrw-p7* + P7. I'm getting "ssh is not executable on your system" -- what do I {{{2 do? (Dudley Fox) Most people I know use putty for windows ssh. It @@ -3567,8 +3535,8 @@ Example: Clear netrw's marked file list via a mapping on gu > of the others will use the string in g:netrw_ssh_cmd by default. - *netrw-p9* *netrw-ml_get* - P9. I'm browsing, changing directory, and bang! ml_get errors {{{2 + *netrw-p8* *netrw-ml_get* + P8. I'm browsing, changing directory, and bang! ml_get errors {{{2 appear and I have to kill vim. Any way around this? Normally netrw attempts to avoid writing swapfiles for @@ -3578,8 +3546,8 @@ Example: Clear netrw's marked file list via a mapping on gu > in your <.vimrc>: > let g:netrw_use_noswf= 0 < - *netrw-p10* - P10. I'm being pestered with "[something] is a directory" and {{{2 + *netrw-p9* + P9. I'm being pestered with "[something] is a directory" and {{{2 "Press ENTER or type command to continue" prompts... The "[something] is a directory" prompt is issued by Vim, @@ -3589,8 +3557,8 @@ Example: Clear netrw's marked file list via a mapping on gu > I also suggest that you set your |'cmdheight'| to 2 (or more) in your <.vimrc> file. - *netrw-p11* - P11. I want to have two windows; a thin one on the left and my {{{2 + *netrw-p10* + P10. I want to have two windows; a thin one on the left and my {{{2 editing window on the right. How may I accomplish this? You probably want netrw running as in a side window. If so, you @@ -3615,8 +3583,8 @@ Example: Clear netrw's marked file list via a mapping on gu > <middlemouse> to select the file. - *netrw-p12* - P12. My directory isn't sorting correctly, or unwanted letters are {{{2 + *netrw-p11* + P11. My directory isn't sorting correctly, or unwanted letters are {{{2 appearing in the listed filenames, or things aren't lining up properly in the wide listing, ... @@ -3625,8 +3593,8 @@ Example: Clear netrw's marked file list via a mapping on gu > Multibyte encodings use two (or more) bytes per character. You may need to change |g:netrw_sepchr| and/or |g:netrw_xstrlen|. - *netrw-p13* - P13. I'm a Windows + putty + ssh user, and when I attempt to {{{2 + *netrw-p12* + P12. I'm a Windows + putty + ssh user, and when I attempt to {{{2 browse, the directories are missing trailing "/"s so netrw treats them as file transfers instead of as attempts to browse subdirectories. How may I fix this? @@ -3646,8 +3614,8 @@ Example: Clear netrw's marked file list via a mapping on gu > "let g:netrw_sftp_cmd = "d:\\dev\\putty\\PSFTP.exe" "let g:netrw_scp_cmd = "d:\\dev\\putty\\PSCP.exe" < - *netrw-p14* - P14. I would like to speed up writes using Nwrite and scp/ssh {{{2 + *netrw-p13* + P13. I would like to speed up writes using Nwrite and scp/ssh {{{2 style connections. How? (Thomer M. Gil) Try using ssh's ControlMaster and ControlPath (see the ssh_config @@ -3673,8 +3641,8 @@ Example: Clear netrw's marked file list via a mapping on gu > vim scp://host.domain.com//home/user/.bashrc < - *netrw-p15* - P15. How may I use a double-click instead of netrw's usual single {{{2 + *netrw-p14* + P14. How may I use a double-click instead of netrw's usual single {{{2 click to open a file or directory? (Ben Fritz) First, disable netrw's mapping with > @@ -3686,8 +3654,8 @@ Example: Clear netrw's marked file list via a mapping on gu > all netrw's mouse mappings, not just the <leftmouse> one. (see |g:netrw_mousemaps|) - *netrw-p16* - P16. When editing remote files (ex. :e ftp://hostname/path/file), {{{2 + *netrw-p15* + P15. When editing remote files (ex. :e ftp://hostname/path/file), {{{2 under Windows I get an |E303| message complaining that its unable to open a swap file. @@ -3695,8 +3663,8 @@ Example: Clear netrw's marked file list via a mapping on gu > directory. Start netrw from your $HOME or other writable directory. - *netrw-p17* - P17. Netrw is closing buffers on its own. {{{2 + *netrw-p16* + P16. Netrw is closing buffers on its own. {{{2 What steps will reproduce the problem? 1. :Explore, navigate directories, open a file 2. :Explore, open another file @@ -3709,15 +3677,15 @@ Example: Clear netrw's marked file list via a mapping on gu > It appears that the buffers are not exactly closed; a ":ls!" will show them (although ":ls" does not). - *netrw-P18* - P18. How to locally edit a file that's only available via {{{2 + *netrw-P17* + P17. How to locally edit a file that's only available via {{{2 another server accessible via ssh? See http://stackoverflow.com/questions/12469645/ "Using Vim to Remotely Edit A File on ServerB Only Accessible From ServerA" - *netrw-P19* - P19. How do I get numbering on in directory listings? {{{2 + *netrw-P18* + P18. How do I get numbering on in directory listings? {{{2 With |g:netrw_bufsettings|, you can control netrw's buffer settings; try putting > let g:netrw_bufsettings="noma nomod nu nobl nowrap ro nornu" @@ -3725,8 +3693,8 @@ Example: Clear netrw's marked file list via a mapping on gu > instead, try > let g:netrw_bufsettings="noma nomod nonu nobl nowrap ro rnu" < - *netrw-P20* - P20. How may I have gvim start up showing a directory listing? {{{2 + *netrw-P19* + P19. How may I have gvim start up showing a directory listing? {{{2 Try putting the following code snippet into your .vimrc: > augroup VimStartup au! @@ -3738,8 +3706,8 @@ Example: Clear netrw's marked file list via a mapping on gu > This snippet assumes that you have client-server enabled (ie. a "huge" vim version). - *netrw-P21* - P21. I've made a directory (or file) with an accented character, {{{2 + *netrw-P20* + P20. I've made a directory (or file) with an accented character, {{{2 but netrw isn't letting me enter that directory/read that file: Its likely that the shell or o/s is using a different encoding @@ -3749,8 +3717,8 @@ Example: Clear netrw's marked file list via a mapping on gu > au FileType netrw set enc=latin1 < - *netrw-P22* - P22. I get an error message when I try to copy or move a file: {{{2 + *netrw-P21* + P21. I get an error message when I try to copy or move a file: {{{2 > **error** (netrw) tried using g:netrw_localcopycmd<cp>; it doesn't work! < diff --git a/runtime/doc/pi_tar.txt b/runtime/doc/pi_tar.txt index dd1edb5707..c8570044e5 100644 --- a/runtime/doc/pi_tar.txt +++ b/runtime/doc/pi_tar.txt @@ -147,7 +147,8 @@ Copyright 2005-2017: *tar-copyright* v2 * converted to use Vim7's new autoload feature by Bram Moolenaar v1 (original) * Michael Toren - (see http://michael.toren.net/code/) + (see http://michael.toren.net/code/ + link seems dead) ============================================================================== vim:tw=78:ts=8:noet:ft=help diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index b8182347f8..a39f4bc5d7 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -185,7 +185,7 @@ See 'clipboard' for details and options. The presence of a working clipboard tool implicitly enables the '+' and "*" registers. Nvim looks for these clipboard tools, in order of priority: - - |g:clipboard| + - |g:clipboard| (unless unset or `false`) - pbcopy, pbpaste (macOS) - wl-copy, wl-paste (if $WAYLAND_DISPLAY is set) - waycopy, waypaste (if $WAYLAND_DISPLAY is set) diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index 9037ecc0f9..5d3c0cbdc2 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -275,7 +275,8 @@ processing a quickfix or location list command, it will be aborted. current window is used instead of the quickfix list. *:cb* *:cbuffer* *E681* -:cb[uffer][!] [bufnr] Read the error list from the current buffer. +:[range]cb[uffer][!] [bufnr] + Read the error list from the current buffer. When [bufnr] is given it must be the number of a loaded buffer. That buffer will then be used instead of the current buffer. @@ -284,26 +285,31 @@ processing a quickfix or location list command, it will be aborted. See |:cc| for [!]. *:lb* *:lbuffer* -:lb[uffer][!] [bufnr] Same as ":cbuffer", except the location list for the +:[range]lb[uffer][!] [bufnr] + Same as ":cbuffer", except the location list for the current window is used instead of the quickfix list. *:cgetb* *:cgetbuffer* -:cgetb[uffer] [bufnr] Read the error list from the current buffer. Just +:[range]cgetb[uffer] [bufnr] + Read the error list from the current buffer. Just like ":cbuffer" but don't jump to the first error. *:lgetb* *:lgetbuffer* -:lgetb[uffer] [bufnr] Same as ":cgetbuffer", except the location list for +:[range]lgetb[uffer] [bufnr] + Same as ":cgetbuffer", except the location list for the current window is used instead of the quickfix list. *:cad* *:cadd* *:caddbuffer* -:cad[dbuffer] [bufnr] Read the error list from the current buffer and add +:[range]cad[dbuffer] [bufnr] + Read the error list from the current buffer and add the errors to the current quickfix list. If a quickfix list is not present, then a new list is created. Otherwise, same as ":cbuffer". *:laddb* *:laddbuffer* -:laddb[uffer] [bufnr] Same as ":caddbuffer", except the location list for +:[range]laddb[uffer] [bufnr] + Same as ":caddbuffer", except the location list for the current window is used instead of the quickfix list. @@ -1282,6 +1288,15 @@ g:compiler_gcc_ignore_unmatched_lines commands run from make are generating false positives. +PANDOC *quickfix-pandoc* *compiler-pandoc* + +The Pandoc compiler plugin expects that an output file type extension is +passed to make, say :make html or :make pdf. + +Additional arguments can be passed to pandoc: + +- either by appending them to make, say `:make html --self-contained` . +- or setting them in `b:pandoc_compiler_args` or `g:pandoc_compiler_args` PERL *quickfix-perl* *compiler-perl* diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index 572dc8a841..c0d00d16cb 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -620,8 +620,7 @@ In Insert or Command-line mode: the help 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 +'allowrevins' 'ari' allow CTRL-_ in Insert mode 'ambiwidth' 'ambw' what to do with Unicode chars of ambiguous width 'arabic' 'arab' for Arabic as a default second language 'arabicshape' 'arshape' do shaping for Arabic characters @@ -739,8 +738,6 @@ Short explanation of each option: *option-list* 'helplang' 'hlg' preferred help languages 'hidden' 'hid' don't unload buffer when it is |abandon|ed '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 @@ -939,6 +936,7 @@ 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 +'winfixbuf' 'wfb' keep window focused on a single buffer '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 @@ -1140,7 +1138,7 @@ Context-sensitive completion on the command-line: |-b| -b binary mode |-l| -l lisp mode |-A| -A Arabic mode ('arabic' is set) -|-H| -H Hebrew mode ('hkmap' and 'rightleft' are set) +|-H| -H Hebrew mode (Hebrew keymap & 'rightleft' are set) |-V| -V Verbose, give informative messages |-r| -r give list of swap files |-r| -r {file} .. recover aborted edit session diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt index cfe4b08000..694c339ef2 100644 --- a/runtime/doc/remote_plugin.txt +++ b/runtime/doc/remote_plugin.txt @@ -30,9 +30,9 @@ check whether a plugin host is available for their chosen programming language. Plugin hosts are programs that provide a high-level environment for plugins, taking care of most boilerplate involved in defining commands, autocmds, and -functions that are implemented over |RPC| connections. Hosts are loaded only -when one of their registered plugins require it, keeping Nvim's startup as -fast as possible, even if many plugins/hosts are installed. +functions implemented over |RPC| connections. Hosts are loaded only when one +of their registered plugins require it, keeping Nvim's startup as fast as +possible, even if many plugins/hosts are installed. ============================================================================== 3. Example *remote-plugin-example* diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index ae827fa06f..2263b20d1a 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -149,8 +149,8 @@ q Stops recording. @@ 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. +{Visual}@{0-9a-z".=*+} In linewise Visual mode, execute the contents of the +{Visual}@@ register for each selected line. See |visual-repeat|, |default-mappings|. *Q* @@ -158,8 +158,8 @@ 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. +{Visual}Q In linewise Visual mode, repeat the last recorded + register for each selected line. See |visual-repeat|, |default-mappings|. *:@* diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt index 0360ce67f6..6fa260be40 100644 --- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -72,9 +72,10 @@ on the same line, the attributes of the sign with the highest priority is used independently of the sign group. The default priority for a sign is 10. The priority is assigned at the time of placing a sign. -When two signs with the same priority are present, and one has an icon or text -in the signcolumn while the other has line highlighting, then both are -displayed. +When multiple signs that each have an icon or text are present, signs are +ordered with increasing priority from left to right, up until the maximum +width set in 'signcolumn'. Lower priority signs that do not fit are hidden. +Highest priority signs with highlight attributes are always shown. When the line on which the sign is placed is deleted, the sign is removed along with it. diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt index 29e4a7b0aa..269d52352d 100644 --- a/runtime/doc/spell.txt +++ b/runtime/doc/spell.txt @@ -51,6 +51,17 @@ To search for the next misspelled word: *[S* [S Like "]S" but search backwards. + *]r* +]r Move to next "rare" word after the cursor. + A count before the command can be used to repeat. + 'wrapscan' applies. + + *[r* +[r Like "]r" but search backwards, find the "rare" + word before the cursor. Doesn't recognize words + split over two lines, thus may stop at words that are + not highlighted as rare. + To add words to your own word list: diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index a6619bc381..fb8ed0344b 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -139,7 +139,7 @@ argument. --cmd {command} *--cmd* {command} will be executed before processing any vimrc file. - Otherwise it acts like -c {command}. You can use up to 10 of + Otherwise, it acts like -c {command}. You can use up to 10 of these commands, independently from "-c" commands. *-S* @@ -260,7 +260,8 @@ argument. -A Arabic mode. Sets the 'arabic' option on. *-H* --H Hebrew mode. Sets the 'rightleft' option on and 'keymap' to "hebrew" +-H Hebrew mode. Sets the 'rightleft' option on and the 'keymap' + option to "hebrew". *-V* *verbose* -V[N] Verbose. Sets the 'verbose' option to [N] (default: 10). @@ -306,7 +307,7 @@ argument. few windows will be editing an empty file. *-O* --O[N] Open N windows, split vertically. Otherwise it's like -o. +-O[N] Open N windows, split vertically. Otherwise, it's like -o. If both the -o and the -O option are given, the last one on the command line determines how the windows will be split. @@ -325,8 +326,10 @@ argument. This can be used to start Vim in a special mode, with special mappings and settings. A shell alias can be used to make - this easy to use. For example: > - alias vimc vim -u ~/.config/nvim/c_init.vim !* + this easy to use. For example, in a C shell descendant: > + alias vimc 'nvim -u ~/.config/nvim/c_init.vim \!*' +< And in a Bash shell: > + alias vimc='nvim -u ~/.config/nvim/c_init.vim' < Also consider using autocommands; see |autocommand|. When {vimrc} is "NONE" (all uppercase), all initializations @@ -544,7 +547,7 @@ accordingly, proceeding as follows: This means that Nvim will figure out the values of 'shellpipe' and 'shellredir' for you, unless you have set them yourself. -12. Set 'updatecount' to zero, if "-n" command argument used +12. Set 'updatecount' to zero, if "-n" command argument used. 13. Set binary options if the |-b| flag was given. @@ -581,11 +584,11 @@ Avoiding trojan horses ~ *trojan-horse* While reading the "vimrc" or the "exrc" file in the current directory, some commands can be disabled for security reasons by setting the 'secure' option. -This is always done when executing the command from a tags file. Otherwise it -would be possible that you accidentally use a vimrc or tags file that somebody -else created and contains nasty commands. The disabled commands are the ones -that start a shell, the ones that write to a file, and ":autocmd". The ":map" -commands are echoed, so you can see which keys are being mapped. +This is always done when executing the command from a tags file. Otherwise, +it would be possible that you accidentally use a vimrc or tags file that +somebody else created and contains nasty commands. The disabled commands are +the ones that start a shell, the ones that write to a file, and ":autocmd". +The ":map" commands are echoed, so you can see which keys are being mapped. If you want Vim to execute all commands in a local vimrc file, you can reset the 'secure' option in the EXINIT or VIMINIT environment variable or in the global exrc or vimrc file. This is not possible in vimrc or @@ -743,7 +746,7 @@ these are terminal or file dependent. Note that the options 'binary', 'paste' and 'readonly' are included, this might not always be what you want. -When special keys are used in mappings, The 'cpoptions' option will be +When special keys are used in mappings, the 'cpoptions' option will be temporarily set to its Vim default, to avoid the mappings to be misinterpreted. This makes the file incompatible with Vi, but makes sure it can be used with different terminals. @@ -797,8 +800,8 @@ You can quickly start editing with a previously saved View or Session with the *:mks* *:mksession* :mks[ession][!] [file] Write a Vim script that restores the current editing session. - When [!] is included an existing file is overwritten. - When [file] is omitted "Session.vim" is used. + When [!] is included, an existing file is overwritten. + When [file] is omitted, "Session.vim" is used. The output of ":mksession" is like ":mkvimrc", but additional commands are added to the file. Which ones depends on the 'sessionoptions' option. The @@ -810,16 +813,16 @@ resulting file, when executed with a ":source" command: 3. Closes all windows in the current tab page, except the current one; closes all tab pages except the current one (this results in currently loaded buffers to be unloaded, some may become hidden if 'hidden' is set or - otherwise specified); wipes out the current buffer, if it is empty - and unnamed. -4. Restores the current directory if 'sessionoptions' contains "curdir", or - sets the current directory to where the Session file is if 'sessionoptions' - contains "sesdir". + otherwise specified); wipes out the current buffer, if it is empty and + unnamed. +4. Restores the current directory, if 'sessionoptions' contains "curdir", or + sets the current directory to where the Session file is, if + 'sessionoptions' contains "sesdir". 5. Restores GUI Vim window position, if 'sessionoptions' contains "winpos". 6. Restores screen size, if 'sessionoptions' contains "resize". 7. Reloads the buffer list, with the last cursor positions. If 'sessionoptions' contains "buffers" then all buffers are restored, - including hidden and unloaded buffers. Otherwise only buffers in windows + including hidden and unloaded buffers. Otherwise, only buffers in windows are restored. 8. Restores all windows with the same layout. If 'sessionoptions' contains "help", help windows are restored. If 'sessionoptions' contains "blank", @@ -846,14 +849,14 @@ A session includes all tab pages, unless "tabpages" was removed from The |SessionLoadPost| autocmd event is triggered after a session file is loaded/sourced. *SessionLoad-variable* -While the session file is loading the SessionLoad global variable is set to 1. -Plugins can use this to postpone some work until the SessionLoadPost event is -triggered. +While the session file is loading, the SessionLoad global variable is set to +1. Plugins can use this to postpone some work until the SessionLoadPost event +is triggered. *:mkvie* *:mkview* :mkvie[w][!] [file] Write a Vim script that restores the contents of the current window. - When [!] is included an existing file is overwritten. + When [!] is included, an existing file is overwritten. When [file] is omitted or is a number from 1 to 9, a name is generated and 'viewdir' prepended. When the last path part of 'viewdir' does not exist, this @@ -868,14 +871,13 @@ triggered. The output of ":mkview" contains these items: 1. The argument list used in the window. When the global argument list is - used it is reset to the global list. + used, it is reset to the global list. The index in the argument list is also restored. 2. The file being edited in the window. If there is no file, the window is made empty. -3. Restore mappings, abbreviations and options local to the window if - 'viewoptions' contains "options" or "localoptions". For the options it - restores only values that are local to the current buffer and values local - to the window. +3. Restore mappings, abbreviations and options local to the window, if + 'viewoptions' contains "options" or "localoptions". Only option values + that are local to the current buffer and the current window are restored. When storing the view as part of a session and "options" is in 'sessionoptions', global values for local options will be stored too. 4. Restore folds when using manual folding and 'viewoptions' contains @@ -909,7 +911,7 @@ Note that Views and Sessions are not perfect: The combination of ":mkview" and ":loadview" can be used to store up to ten different views of a file. These are remembered in the directory specified with the 'viewdir' option. The views are stored using the file name. If a -file is renamed or accessed through a (symbolic) link the view will not be +file is renamed or accessed through a (symbolic) link, the view will not be found. You might want to clean up your 'viewdir' directory now and then. @@ -969,7 +971,7 @@ Notes for Unix: allow just anybody to read and write your ShaDa file! - Vim will not overwrite a ShaDa file that is not writable by the current "real" user. This helps for when you did "su" to become root, but your - $HOME is still set to a normal user's home directory. Otherwise Vim would + $HOME is still set to a normal user's home directory. Otherwise, Vim would create a ShaDa file owned by root that nobody else can read. - The ShaDa file cannot be a symbolic link. This is to avoid security issues. @@ -1001,11 +1003,11 @@ using this command: > vim -c "normal '0" -In a csh compatible shell you could make an alias for it: > +In a C shell descendant, you could make an alias for it: > alias lvim vim -c '"'normal "'"0'"' -For a bash-like shell: > +For a Bash-like shell: > alias lvim='vim -c "normal '\''0"' @@ -1099,15 +1101,15 @@ MANUALLY READING AND WRITING *shada-read-write* Two commands can be used to read and write the ShaDa file manually. This can be used to exchange registers between two running Vim programs: First type ":wsh" in one and then ":rsh" in the other. Note that if the register -already contained something, then ":rsh!" would be required. Also note -however that this means everything will be overwritten with information from +already contained something, then ":rsh!" would be required. Also note, +however, that this means everything will be overwritten with information from the first Vim, including the command line history, etc. The ShaDa file itself can be edited by hand too, although we suggest you start with an existing one to get the format right. You need to understand MessagePack (or, more likely, find software that is able to use it) format to do this. This can be useful in order to create a second file, say -"~/.my.shada" which could contain certain settings that you always want when +"~/.my.shada", which could contain certain settings that you always want when you first start Nvim. For example, you can preload registers with particular data, or put certain commands in the command line history. A line in your |config| file like > @@ -1171,8 +1173,8 @@ running) you have additional options: described in |shada-error-handling|). If 'shada' is empty, marks for up to 100 files will be written. When you get error "E929: All .tmp.X files exist, - cannot write ShaDa file!" check that no old temp files - were left behind (e.g. + cannot write ShaDa file!", check that no old temp + files were left behind (e.g. ~/.local/state/nvim/shada/main.shada.tmp*). Note: Executing :wshada will reset all |'quote| marks. @@ -1192,7 +1194,7 @@ running) you have additional options: the list is edited. If you get the |press-enter| prompt you can press "q" and still get the prompt to enter a file number. - Use ! to abandon a modified buffer. |abandon| + Use [!] to abandon a modified buffer. |abandon| SHADA FILE FORMAT *shada-format* diff --git a/runtime/doc/support.txt b/runtime/doc/support.txt index 80a035068a..5b8b32fa16 100644 --- a/runtime/doc/support.txt +++ b/runtime/doc/support.txt @@ -13,12 +13,13 @@ Supported platforms *supported-platforms* `System` `Tier` `Versions` `Tested versions` Linux 1 >= 2.6.32, glibc >= 2.12 Ubuntu 22.04 -macOS (Intel) 1 >= 10.15 macOS 12 -Windows 64-bit 1 >= 8 (see note below) Windows Server 2022 +macOS (Intel) 1 >= 11 macOS 12 +macOS (M1) 2 >= 11 macOS 14 +Windows 64-bit 1 >= Windows 10 Version 1809 Windows Server 2022 FreeBSD 1 >= 10 FreeBSD 13 -macOS (M1) 2 >= 10.15 OpenBSD 2 >= 7 MinGW 2 MinGW-w64 +Windows 64-bit 3 < Windows 10 Version 1809 Note: Windows 10 "Version 1809" or later is required for |:terminal|. To check your Windows version, run the "winver" command and look for "Version xxxx" @@ -33,7 +34,7 @@ Support types ~ systems are maintained to the best of our ability, without being a top priority. -* Tier 3: Not tested and no guarantees, but may work. +* Tier 3: Not tested and no guarantees, and not all features may work. Adding support for a new platform ~ diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index c02752a2b7..7893822a66 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -461,8 +461,24 @@ nasm_loose_syntax unofficial parser allowed syntax not as Error nasm_ctx_outside_macro contexts outside macro not as Error nasm_no_warn potentially risky syntax not as ToDo +ASTRO *astro.vim* *ft-astro-syntax* -ASPPERL and ASPVBS *ft-aspperl-syntax* *ft-aspvbs-syntax* +Configuration + +The following variables control certain syntax highlighting features. +You can add them to your .vimrc: > + let g:astro_typescript = "enable" +< +Enables TypeScript and TSX for ".astro" files. Default Value: "disable" > + let g:astro_stylus = "enable" +< +Enables Stylus for ".astro" files. Default Value: "disable" + +NOTE: You need to install an external plugin to support stylus in astro files. + + +ASPPERL *ft-aspperl-syntax* +ASPVBS *ft-aspvbs-syntax* `*.asp` and `*.asa` files could be either Perl or Visual Basic script. Since it's hard to detect this you can set two global variables to tell Vim what you are @@ -998,9 +1014,9 @@ Two syntax highlighting files exist for Euphoria. One for Euphoria version 3.1.1, which is the default syntax highlighting file, and one for Euphoria version 4.0.5 or later. -Euphoria version 3.1.1 (https://www.rapideuphoria.com/) is still necessary -for developing applications for the DOS platform, which Euphoria version 4 -(https://www.openeuphoria.org/) does not support. +Euphoria version 3.1.1 (https://www.rapideuphoria.com/ link seems dead) is +still necessary for developing applications for the DOS platform, which +Euphoria version 4 (https://www.openeuphoria.org/) does not support. The following file extensions are auto-detected as Euphoria file type: > @@ -1057,7 +1073,8 @@ Elixir. FLEXWIKI *flexwiki.vim* *ft-flexwiki-syntax* -FlexWiki is an ASP.NET-based wiki package available at https://www.flexwiki.com +FlexWiki is an ASP.NET-based wiki package available at +https://www.flexwiki.com NOTE: This site currently doesn't work, on Wikipedia is mentioned that development stopped in 2009. @@ -1527,15 +1544,25 @@ Function names are not highlighted, as the way to find functions depends on how you write Java code. The syntax file knows two possible ways to highlight functions: -If you write function declarations that are always indented by either -a tab, 8 spaces or 2 spaces you may want to set > +If you write function declarations that are consistently indented by either +a tab, or a space . . . or eight space character(s), you may want to set > :let java_highlight_functions="indent" + :let java_highlight_functions="indent1" + :let java_highlight_functions="indent2" + :let java_highlight_functions="indent3" + :let java_highlight_functions="indent4" + :let java_highlight_functions="indent5" + :let java_highlight_functions="indent6" + :let java_highlight_functions="indent7" + :let java_highlight_functions="indent8" +Note that in terms of 'shiftwidth', this is the leftmost step of indentation. However, if you follow the Java guidelines about how functions and classes are -supposed to be named (with respect to upper and lowercase), use > +supposed to be named (with respect to upper- and lowercase) and there is any +amount of indentation, you may want to set > :let java_highlight_functions="style" -If both options do not work for you, but you would still want function -declarations to be highlighted create your own definitions by changing the -definitions in java.vim or by creating your own java.vim which includes the +If neither setting does work for you, but you would still want function +declarations to be highlighted, create your own definitions by changing the +definitions in java.vim or by creating your own java.vim that includes the original one and then adds the code to highlight functions. In Java 1.1 the functions System.out.println() and System.err.println() should @@ -1599,6 +1626,15 @@ To disable syntax highlighting of errors: > let g:vim_json_warnings = 0 +JQ *jq.vim* *jq_quote_highlight* *ft-jq-syntax* + +To disable numbers having their own color add the following to your vimrc: > + hi link jqNumber Normal + +If you want quotes to have different highlighting than strings > + let g:jq_quote_highlight = 1 + + LACE *lace.vim* *ft-lace-syntax* Lace (Language for Assembly of Classes in Eiffel) is case insensitive, but the @@ -1764,10 +1800,19 @@ MARKDOWN *ft-markdown-syntax* If you have long regions there might be wrong highlighting. At the cost of slowing down displaying, you can have the engine look further back to sync on -the start of a region, for example 500 lines: > +the start of a region, for example 500 lines (default is 50): > :let g:markdown_minlines = 500 +If you want to enable fenced code block syntax highlighting in your markdown +documents you can enable like this: > + + :let g:markdown_fenced_languages = ['html', 'python', 'bash=sh'] + +To disable markdown syntax concealing add the following to your vimrc: > + + :let g:markdown_syntax_conceal = 0 + MATHEMATICA *mma.vim* *ft-mma-syntax* *ft-mathematica-syntax* @@ -1985,6 +2030,95 @@ by the camlp4 preprocessor. Setting the variable > prevents highlighting of "end" as error, which is useful when sources contain very long structures that Vim does not synchronize anymore. +PANDOC *ft-pandoc-syntax* + +By default, markdown files will be detected as filetype "markdown". +Alternatively, you may want them to be detected as filetype "pandoc" instead. +To do so, set the following: > + + :let g:markdown_md = 'pandoc' + +The pandoc syntax plugin uses |conceal| for pretty highlighting. Default is 1 > + + :let g:pandoc#syntax#conceal#use = 1 + +To specify elements that should not be concealed, set the following variable: > + + :let g:pandoc#syntax#conceal#blacklist = [] + +This is a list of the rules wich can be used here: + + - titleblock + - image + - block + - subscript + - superscript + - strikeout + - atx + - codeblock_start + - codeblock_delim + - footnote + - definition + - list + - newline + - dashes + - ellipses + - quotes + - inlinecode + - inlinemath + +You can customize the way concealing works. For example, if you prefer to mark +footnotes with the `*` symbol: > + + :let g:pandoc#syntax#conceal#cchar_overrides = {"footnote" : "*"} + +To conceal the urls in links, use: > + + :let g:pandoc#syntax#conceal#urls = 1 + +Prevent highlighting specific codeblock types so that they remain Normal. +Codeblock types include "definition" for codeblocks inside definition blocks +and "delimited" for delimited codeblocks. Default = [] > + + :let g:pandoc#syntax#codeblocks#ignore = ['definition'] + +Use embedded highlighting for delimited codeblocks where a language is +specified. Default = 1 > + + :let g:pandoc#syntax#codeblocks#embeds#use = 1 + +For specify what languages and using what syntax files to highlight embeds. This is a +list of language names. When the language pandoc and vim use don't match, you +can use the "PANDOC=VIM" syntax. For example: > + + :let g:pandoc#syntax#codeblocks#embeds#langs = ["ruby", "bash=sh"] + +To use italics and strong in emphases. Default = 1 > + + :let g:pandoc#syntax#style#emphases = 1 + +"0" will add "block" to g:pandoc#syntax#conceal#blacklist, because otherwise +you couldn't tell where the styles are applied. + +To add underline subscript, superscript and strikeout text styles. Default = 1 > + + :let g:pandoc#syntax#style#underline_special = 1 + +Detect and highlight definition lists. Disabling this can improve performance. +Default = 1 (i.e., enabled by default) > + + :let g:pandoc#syntax#style#use_definition_lists = 1 + +The pandoc syntax script also comes with the following commands: > + + :PandocHighlight LANG + +Enables embedded highlighting for language LANG in codeblocks. Uses the +syntax for items in g:pandoc#syntax#codeblocks#embeds#langs. > + + :PandocUnhighlight LANG + +Disables embedded highlighting for language LANG in codeblocks. PAPP *papp.vim* *ft-papp-syntax* @@ -2099,8 +2233,8 @@ perl_string_as_statement, it will be highlighted as in the second line. The syncing has 3 options. The first two switch off some triggering of synchronization and should only be needed in case it fails to work properly. If while scrolling all of a sudden the whole screen changes color completely -then you should try and switch off one of those. Let me know if you can -figure out the line that causes the mistake. +then you should try and switch off one of those. Let the developer know if +you can figure out the line that causes the mistake. One triggers on "^\s*sub\s*" and the other on "^[$@%]" more or less. > @@ -3173,7 +3307,7 @@ The g:vimsyn_embed option allows users to select what, if any, types of embedded script highlighting they wish to have. > g:vimsyn_embed == 0 : disable (don't embed any scripts) - g:vimsyn_embed == 'lPr' : support embedded lua, python and ruby + g:vimsyn_embed == 'lpPr' : support embedded lua, perl, python and ruby < This option is disabled by default. *g:vimsyn_folding* @@ -3183,7 +3317,11 @@ Some folding is now supported with syntax/vim.vim: > g:vimsyn_folding == 0 or doesn't exist: no syntax-based folding g:vimsyn_folding =~ 'a' : augroups g:vimsyn_folding =~ 'f' : fold functions + g:vimsyn_folding =~ 'h' : fold heredocs + g:vimsyn_folding =~ 'l' : fold lua script + g:vimsyn_folding =~ 'p' : fold perl script g:vimsyn_folding =~ 'P' : fold python script + g:vimsyn_folding =~ 'r' : fold ruby script < *g:vimsyn_noerror* Not all error highlighting that syntax/vim.vim does may be correct; Vim script @@ -3708,7 +3846,9 @@ Whether or not it is actually concealed depends on the value of the 'conceallevel' option. The 'concealcursor' option is used to decide whether concealable items in the current line are displayed unconcealed to be able to edit the line. -Another way to conceal text is with |matchadd()|. + +Another way to conceal text is with |matchadd()|, but internally this works a +bit differently |syntax-vs-match|. concealends *:syn-concealends* @@ -3716,7 +3856,9 @@ When the "concealends" argument is given, the start and end matches of the region, but not the contents of the region, are marked as concealable. Whether or not they are actually concealed depends on the setting on the 'conceallevel' option. The ends of a region can only be concealed separately -in this way when they have their own highlighting via "matchgroup" +in this way when they have their own highlighting via "matchgroup". The +|synconcealed()| function can be used to retrieve information about conealed +items. cchar *:syn-cchar* *E844* @@ -4767,11 +4909,11 @@ guisp={color-name} *guisp* Colors which define Nvim's default color scheme: NvimDarkBlue NvimLightBlue NvimDarkCyan NvimLightCyan + NvimDarkGray1 NvimLightGray1 + NvimDarkGray2 NvimLightGray2 + NvimDarkGray3 NvimLightGray3 + NvimDarkGray4 NvimLightGray4 NvimDarkGreen NvimLightGreen - NvimDarkGrey1 NvimLightGrey1 - NvimDarkGrey2 NvimLightGrey2 - NvimDarkGrey3 NvimLightGrey3 - NvimDarkGrey4 NvimLightGrey4 NvimDarkMagenta NvimLightMagenta NvimDarkRed NvimLightRed NvimDarkYellow NvimLightYellow @@ -4868,7 +5010,7 @@ MatchParen Character under the cursor or just before it, if it *hl-ModeMsg* ModeMsg 'showmode' message (e.g., "-- INSERT --"). *hl-MsgArea* -MsgArea Area for messages and cmdline. +MsgArea Area for messages and command-line, see also 'cmdheight'. *hl-MsgSeparator* MsgSeparator Separator for scrolled messages |msgsep|. *hl-MoreMsg* @@ -4914,6 +5056,8 @@ QuickFixLine Current |quickfix| item in the quickfix window. Combined with *hl-Search* Search Last search pattern highlighting (see 'hlsearch'). Also used for similar items that need to stand out. + *hl-SnippetTabstop* +SnippetTabstop Tabstops in snippets. |vim.snippet| *hl-SpecialKey* SpecialKey Unprintable characters: Text displayed differently from what it really is. But not 'listchars' whitespace. |hl-Whitespace| diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt index 49b2773253..2f50e31ee5 100644 --- a/runtime/doc/tabpage.txt +++ b/runtime/doc/tabpage.txt @@ -187,7 +187,7 @@ gt *i_CTRL-<PageDown>* *i_<C-PageDown>* :1tabnext " go to the first tab page :$tabnext " go to the last tab page :tabnext $ " as above - :tabnext # " go to the last accessed tab page + :tabnext # " go to the last accessed tab page :tabnext - " go to the previous tab page :tabnext -1 " as above :tabnext + " go to the next tab page @@ -216,8 +216,8 @@ gT Go to the previous tab page. Wraps around from the first one :tabl[ast] Go to the last tab page. <C-Tab> *CTRL-<Tab>* *<C-Tab>* -CTRL-W g<Tab> *g<Tab>* *CTRL-W_g<Tab>* -g<Tab> Go to the last accessed tab page. +g<Tab> *g<Tab>* *CTRL-W_g<Tab>* +CTRL-W g<Tab> Go to the last accessed tab page. Other commands: *:tabs* @@ -239,18 +239,17 @@ REORDERING TAB PAGES: Move the current tab page to after tab page N. Use zero to make the current tab page the first one. N is counted before the move, thus if the second tab is the current one, - `:tabmove 1` and `:tabmove 2` have no effect. + `:tabmove 1` and `:tabmove 2` have no effect. Without N the tab page is made the last one. > - :.tabmove " do nothing - :-tabmove " move the tab page to the left - :+tabmove " move the tab page to the right - :0tabmove " move the tab page to the beginning of the tab - " list + :.tabmove " do nothing + :-tabmove " move the tab page to the left + :+tabmove " move the tab page to the right + :0tabmove " move the tab page to the first :tabmove 0 " as above :tabmove " move the tab page to the last :$tabmove " as above :tabmove $ " as above - :tabmove # " move the tab page after the last accessed + :tabmove # " move the tab page after the last accessed " tab page :tabm[ove] +[N] diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt index 2b5b253a09..ef1654d365 100644 --- a/runtime/doc/tagsrch.txt +++ b/runtime/doc/tagsrch.txt @@ -400,19 +400,24 @@ the pattern. *tag-!* If the tag is in the current file this will always work. Otherwise the performed actions depend on whether the current file was changed, whether a ! -is added to the command and on the 'autowrite' option: - - tag in file autowrite ~ -current file changed ! option action ~ - --------------------------------------------------------------------------- - yes x x x goto tag - no no x x read other file, goto tag - no yes yes x abandon current file, read other file, goto - tag - no yes no on write current file, read other file, goto - tag - no yes no off fail - --------------------------------------------------------------------------- +is added to the command and on the 'autowrite' and 'winfixbuf' options: + + tag in file winfixbuf autowrite ~ +current file changed ! option option action ~ + ----------------------------------------------------------------------------- + yes x x off x goto tag + no no x off x read other file, goto tag + no yes yes off x abandon current file, + read other file, goto tag + no yes no off on write current file, + read other file, goto tag + no yes no off off fail + yes x yes x x goto tag + no no no on x fail + no yes no on x fail + no yes no on on fail + no yes no on off fail + ----------------------------------------------------------------------------- - If the tag is in the current file, the command will always work. - If the tag is in another file and the current file was not changed, the @@ -428,6 +433,8 @@ current file changed ! option action ~ the changes, use the ":w" command and then use ":tag" without an argument. This works because the tag is put on the stack anyway. If you want to lose the changes you can use the ":tag!" command. +- If the tag is in another file and the window includes 'winfixbuf', the + command will fail. If the tag is in the same file then it may succeed. *tag-security* Note that Vim forbids some commands, for security reasons. This works like @@ -773,9 +780,17 @@ CTRL-W i Open a new window, with the cursor on the first line beginning of the file. If a count is given, the count'th matching line is displayed. + *[d-default* + Mapped to |vim.diagnostic.goto_prev()| by default. + |default-mappings| + *]d* ]d like "[d", but start at the current cursor position. + *]d-default* + Mapped to |vim.diagnostic.goto_next()| by default. + |default-mappings| + *:ds* *:dsearch* :[range]ds[earch][!] [count] [/]string[/] Like "[d" and "]d", but search in [range] lines @@ -822,6 +837,10 @@ CTRL-W d Open a new window, with the cursor on the first beginning of the file. If a count is given, the count'th matching line is jumped to. + *CTRL-W_d-default* + Mapped to |vim.diagnostic.open_float()| by default. + |default-mappings| + *:dsp* *:dsplit* :[range]dsp[lit][!] [count] [/]string[/] Like "CTRL-W d", but search in [range] lines diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 5f33802ad5..0b84bb60d4 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -18,18 +18,31 @@ changes. This documentation may also not fully reflect the latest changes. PARSER FILES *treesitter-parsers* 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 via a plugin like https://github.com/nvim-treesitter/nvim-treesitter -or even manually. +search for in the `parser` runtime directory. + +Nvim includes these parsers: + +- C +- Lua +- Markdown +- Vimscript +- Vimdoc +- Treesitter query files |ft-query-plugin| + +You can install more parsers manually, or with 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. (NOTE: This typically implies the priority "user config > plugins > bundled".) -A parser can also be loaded manually using a full path: >lua + +To load a parser from its filepath: >lua vim.treesitter.language.add('python', { path = "/path/to/python.so" }) < +Parser names are assumed to be lower case if the file system is +case-sensitive. + 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 @@ -65,6 +78,8 @@ An instance `TSNode` of a treesitter node supports the following methods. TSNode:parent() *TSNode:parent()* Get the node's immediate parent. + Prefer |TSNode:child_containing_descendant()| + for iterating over the node's ancestors. TSNode:next_sibling() *TSNode:next_sibling()* Get the node's next sibling. @@ -101,6 +116,9 @@ TSNode:named_child({index}) *TSNode:named_child()* Get the node's named child at the given {index}, where zero represents the first named child. +TSNode:child_containing_descendant({descendant}) *TSNode:child_containing_descendant()* + Get the node's child that contains {descendant}. + TSNode:start() *TSNode:start()* Get the node's start position. Return three values: the row, column and total byte count (all zero-based). @@ -149,7 +167,7 @@ TSNode:sexpr() *TSNode:sexpr()* Get an S-expression representing the node as a string. TSNode:id() *TSNode:id()* - Get an unique identifier for the node inside its own tree. + Get a unique identifier for the node inside its own tree. No guarantees are made about this identifier's internal representation, except for being a primitive Lua type with value equality (so not a @@ -469,10 +487,11 @@ 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 +@variable various variable names +@variable.builtin built-in variable names (e.g. `this`, `self`) +@variable.parameter parameters of a function +@variable.parameter.builtin special parameters (e.g. `_`, `it`) +@variable.member object and struct fields @constant constant identifiers @constant.builtin built-in constant values @@ -480,7 +499,7 @@ the exact definition): @module modules or namespaces @module.builtin built-in modules or namespaces -@label GOTO and other labels (e.g. `label:` in C), including heredoc labels +@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) @@ -501,9 +520,9 @@ the exact definition): @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) +@attribute attribute annotations (e.g. Python decorators, Rust lifetimes) +@attribute.builtin builtin annotations (e.g. `@property` in Python) @property the key in key/value pairs @function function definitions @@ -515,27 +534,28 @@ the exact definition): @function.method.call method calls @constructor constructor calls and definitions -@operator symbolic operators (e.g. `+` / `*`) +@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.operator operators that are English words (e.g. `and`, `or`) +@keyword.import keywords for including modules (e.g. `import`, `from` in Python) +@keyword.type keywords defining composite types (e.g. `struct`, `enum`) +@keyword.modifier keywords defining type modifiers (e.g. `const`, `static`, `public`) +@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.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.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.delimiter delimiters (e.g. `;`, `.`, `,`) +@punctuation.bracket brackets (e.g. `()`, `{}`, `[]`) @punctuation.special special symbols (e.g. `{}` in string interpolation) @comment line and block comments @@ -543,7 +563,7 @@ the exact definition): @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.todo todo-type comments (e.g. `TODO`, `WIP`) @comment.note note-type comments (e.g. `NOTE`, `INFO`, `XXX`) @markup.strong bold text @@ -552,10 +572,15 @@ the exact definition): @markup.underline underlined text (only for literal underline markup!) @markup.heading headings, titles (including markers) +@markup.heading.1 top-level heading +@markup.heading.2 section heading +@markup.heading.3 subsection heading +@markup.heading.4 and so on +@markup.heading.5 and so forth +@markup.heading.6 six levels ought to be enough for anybody @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 @@ -573,6 +598,7 @@ the exact definition): @diff.delta changed text (for diff files) @tag XML-style tag names (e.g. in XML, HTML, etc.) +@tag.builtin XML-style tag names (e.g. HTML5 tags) @tag.attribute XML-style tag attributes @tag.delimiter XML-style tag delimiters @@ -646,6 +672,10 @@ parent tree. The language injection query allows you to specify these • `@injection.language` - indicates that the captured node’s text may contain the name of a language that should be used to re-parse the `@injection.content`. + • `@injection.filename` - indicates that the captured node’s text may + contain a filename; the corresponding filetype is then looked-up up via + |vim.filetype.match()| and treated as the name of a language that should + be used to re-parse the `@injection.content`. The language injection behavior can also be configured by some properties associated with patterns: @@ -719,8 +749,7 @@ get_captures_at_pos({bufnr}, {row}, {col}) • {col} (`integer`) Position column Return: ~ - (`table[]`) List of captures - `{ capture = "name", metadata = { ... } }` + (`{capture: string, lang: string, metadata: table}[]`) get_node({opts}) *vim.treesitter.get_node()* Returns the smallest named node at the given position @@ -978,7 +1007,7 @@ add_directive({name}, {handler}, {opts}) Parameters: ~ • {name} (`string`) Name of the directive, without leading # - • {handler} (`function`) + • {handler} (`fun(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)`) • match: A table mapping capture IDs to a list of captured nodes • pattern: the index of the matching pattern in the query @@ -986,10 +1015,10 @@ add_directive({name}, {handler}, {opts}) • predicate: list of strings containing the full directive being called, e.g. `(node (#set! conceal "-"))` would get the predicate `{ "#set!", "conceal", "-" }` - • {opts} (`table<string, any>`) Optional options: - • force (boolean): Override an existing predicate of the - same name - • all (boolean): Use the correct implementation of the + • {opts} (`table`) A table with the following fields: + • {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 @@ -1001,13 +1030,13 @@ add_predicate({name}, {handler}, {opts}) Parameters: ~ • {name} (`string`) Name of the predicate, without leading # - • {handler} (`function`) + • {handler} (`fun(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)`) • see |vim.treesitter.query.add_directive()| for argument meanings - • {opts} (`table<string, any>`) Optional options: - • force (boolean): Override an existing predicate of the - same name - • all (boolean): Use the correct implementation of the + • {opts} (`table`) A table with the following fields: + • {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 @@ -1079,13 +1108,13 @@ list_directives() *vim.treesitter.query.list_directives()* Lists the currently available directives to use in queries. Return: ~ - (`string[]`) List of supported directives. + (`string[]`) 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[]`) Supported predicates. omnifunc({findstart}, {base}) *vim.treesitter.query.omnifunc()* Omnifunc for completing node names and predicates in treesitter queries. @@ -1132,10 +1161,10 @@ Query:iter_captures({node}, {source}, {start}, {stop}) i.e., to get syntax highlight matches in the current viewport). When omitted, the {start} and {stop} row values are used from the given node. - The iterator returns three values: a numeric id identifying the capture, - the captured node, and metadata from any directives processing the match. - The following example shows how to get captures by name: >lua - for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do + The iterator returns four values: a numeric id identifying the capture, + the captured node, metadata from any directives processing the match, and + the match itself. The following example shows how to get captures by name: >lua + for id, node, metadata, match in query:iter_captures(tree:root(), bufnr, first, last) do local name = query.captures[id] -- name of the capture in the query -- typically useful info about the node: local type = node:type() -- type of the captured node @@ -1144,6 +1173,10 @@ Query:iter_captures({node}, {source}, {start}, {stop}) end < + Note: ~ + • Captures are only returned if the query pattern of a specific capture + contained predicates. + Parameters: ~ • {node} (`TSNode`) under which the search will occur • {source} (`integer|string`) Source buffer or string to extract text @@ -1154,8 +1187,8 @@ Query:iter_captures({node}, {source}, {start}, {stop}) Defaults to `node:end_()`. Return: ~ - (`fun(end_line: integer?): integer, TSNode, vim.treesitter.query.TSMetadata`) - capture id, capture node, metadata + (`fun(end_line: integer?): integer, TSNode, vim.treesitter.query.TSMetadata, TSQueryMatch`) + capture id, capture node, metadata, match *Query:iter_matches()* Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) @@ -1198,6 +1231,8 @@ Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) • 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. + • match_limit (integer) Set the maximum number of + in-progress matches (Default: 256). • 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 @@ -1291,7 +1326,11 @@ LanguageTree:included_regions() *LanguageTree:included_regions()* (`table<integer, Range6[]>`) LanguageTree:invalidate({reload}) *LanguageTree:invalidate()* - Invalidates this parser and all its children + Invalidates this parser and its children. + + Should only be called when the tracked state of the LanguageTree is not + valid against the parse tree in treesitter. Doesn't clear filesystem + cache. Called often, so needs to be fast. Parameters: ~ • {reload} (`boolean?`) @@ -1319,7 +1358,7 @@ LanguageTree:language_for_range({range}) • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }` Return: ~ - (`vim.treesitter.LanguageTree`) Managing {range} + (`vim.treesitter.LanguageTree`) tree Managing {range} *LanguageTree:named_node_for_range()* LanguageTree:named_node_for_range({range}, {opts}) @@ -1327,12 +1366,12 @@ LanguageTree:named_node_for_range({range}, {opts}) Parameters: ~ • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }` - • {opts} (`table?`) Optional keyword arguments: - • ignore_injections boolean Ignore injected languages - (default true) + • {opts} (`table?`) A table with the following fields: + • {ignore_injections}? (`boolean`, default: `true`) Ignore + injected languages Return: ~ - (`TSNode?`) Found node + (`TSNode?`) LanguageTree:parse({range}) *LanguageTree:parse()* Recursively parse all regions in the language tree using @@ -1359,8 +1398,9 @@ LanguageTree:register_cbs({cbs}, {recursive}) Registers callbacks for the |LanguageTree|. Parameters: ~ - • {cbs} (`table`) An |nvim_buf_attach()|-like table argument with - the following handlers: + • {cbs} (`table<TSCallbackNameOn,function>`) 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_changedtree` : a callback that will be called every @@ -1387,9 +1427,9 @@ LanguageTree:tree_for_range({range}, {opts}) Parameters: ~ • {range} (`Range4`) `{ start_line, start_col, end_line, end_col }` - • {opts} (`table?`) Optional keyword arguments: - • ignore_injections boolean Ignore injected languages - (default true) + • {opts} (`table?`) A table with the following fields: + • {ignore_injections}? (`boolean`, default: `true`) Ignore + injected languages Return: ~ (`TSTree?`) diff --git a/runtime/doc/uganda.txt b/runtime/doc/uganda.txt index 42e275c230..0b281dc3a0 100644 --- a/runtime/doc/uganda.txt +++ b/runtime/doc/uganda.txt @@ -199,7 +199,7 @@ visited about once a year to check the progress (at our own cost). I have visited the centre myself many times, starting in 1993. The visit reports are on the ICCF web site. -If you have any further questions, send me e-mail: <Bram@vim.org>. +If you have any further questions, send e-mail: <Bram@vim.org>. The address of the centre is: Kibaale Children's Centre @@ -219,9 +219,8 @@ Canada: Contact Kuwasha in Surrey, Canada. They take care of the Canadian sponsors for the children in Kibaale. Kuwasha forwards 100% of the money to the project in Uganda. You can send them a one time donation directly. - Please send me a note so that I know what has been donated - because of Vim. Look on their site for information about - sponsorship: https://www.kuwasha.net/ + Look on their site for information about sponsorship: + https://www.kuwasha.net/ If you make a donation to Kuwasha you will receive a tax receipt which can be submitted with your tax return. diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index b8d47923ca..1f5132bd30 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -331,8 +331,8 @@ numerical highlight ids to the actual attributes. `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. + `url`: URL associated with this highlight. UIs should + present the region as a clickable hyperlink. 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 @@ -656,6 +656,11 @@ tabs. the screen and copy it to the viewport destination once `win_viewport` is received. +["win_viewport_margins", grid, win, top, bottom, left, right] ~ + Indicates the margins of a window grid which are _not_ part of the + viewport as indicated by the `win_viewport` event. This happens + e.g. in the presence of 'winbar' and floating window borders. + ["win_extmark", grid, win, ns_id, mark_id, row, col] ~ Updates the position of an extmark which is currently visible in a window. Only emitted if the mark has the `ui_watched` attribute. @@ -772,9 +777,10 @@ This UI extension delegates presentation of messages and dialogs. Messages that would otherwise render in the message/cmdline screen space, are emitted as UI events. -Nvim will not allocate screen space for the cmdline or messages, and -'cmdheight' will be forced zero. Cmdline state is emitted as |ui-cmdline| -events, which the UI must handle. +Nvim will not allocate screen space for the cmdline or messages. 'cmdheight' +will be set to zero, but can be changed and used for the replacing cmdline or +message window. Cmdline state is emitted as |ui-cmdline| events, which the UI +must handle. ["msg_show", kind, content, replace_last] ~ Display a message to the user. diff --git a/runtime/doc/usr_01.txt b/runtime/doc/usr_01.txt index 6b94806941..d285a35f26 100644 --- a/runtime/doc/usr_01.txt +++ b/runtime/doc/usr_01.txt @@ -85,7 +85,7 @@ The Vim user manual and reference manual are Copyright (c) 1988 by Bram Moolenaar. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later. The latest version is presently available at: - https://www.opencontent.org/openpub/ + https://opencontent.org/openpub/ People who contribute to the manuals must agree with the above copyright notice. diff --git a/runtime/doc/usr_30.txt b/runtime/doc/usr_30.txt index a0d22482c3..98dbefae46 100644 --- a/runtime/doc/usr_30.txt +++ b/runtime/doc/usr_30.txt @@ -246,7 +246,7 @@ code block the cursor is in: > =a{ -I you have really badly indented code, you can re-indent the whole file with: +If you have really badly indented code, you can re-indent the whole file with: > gg=G diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 56750420e9..ab2eecdfaf 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -794,6 +794,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 + getregionpos() get a list of positions for a region setline() replace a line in the buffer append() append line or list of lines in the buffer indent() indent of a specific line @@ -948,7 +949,7 @@ Syntax and highlighting: *syntax-functions* *highlighting-functions* synIDattr() get a specific attribute of a syntax ID synIDtrans() get translated syntax ID synstack() get list of syntax IDs at a specific position - synconcealed() get info about concealing + synconcealed() get info about (syntax) concealing diff_hlID() get highlight ID for diff mode at a position matchadd() define a pattern to highlight (a "match") matchaddpos() define a list of positions to highlight @@ -2500,13 +2501,9 @@ When you write a compiler file and put it in your personal runtime directory variable to make the default file skip the settings. *:CompilerSet* The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for -":compiler". Vim defines the ":CompilerSet" user command for this. However, -older Vim versions don't, thus your plugin should define it then. This is an -example: > +":compiler". Vim defines the ":CompilerSet" user command for this. This is +an example: > - if exists(":CompilerSet") != 2 - command -nargs=* CompilerSet setlocal <args> - endif CompilerSet errorformat& " use the default 'errorformat' CompilerSet makeprg=nmake diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index 33f57580c7..0287271d4c 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -14,6 +14,7 @@ Various commands *various* *CTRL-L* CTRL-L Clears and redraws the screen. The redraw may happen later, after processing typeahead. + See also |nvim__redraw()|. *CTRL-L-default* By default, also clears search highlighting |:nohlsearch| and updates diffs |:diffupdate|. @@ -21,6 +22,7 @@ CTRL-L Clears and redraws the screen. The redraw may happen *:mod* *:mode* :mod[e] Clears and redraws the screen. + See also |nvim__redraw()|. *:redr* *:redraw* :redr[aw][!] Redraws pending screen updates now, or the entire @@ -28,6 +30,7 @@ CTRL-L Clears and redraws the screen. The redraw may happen |:mode| or |CTRL-L|. Useful to update the screen during a script or function (or a mapping if 'lazyredraw' set). + See also |nvim__redraw()|. *:redraws* *:redrawstatus* :redraws[tatus][!] Redraws the status line and window bar of the current @@ -35,11 +38,12 @@ CTRL-L Clears and redraws the screen. The redraw may happen included. Redraws the commandline instead if it contains the 'ruler'. Useful if 'statusline' or 'winbar' includes an item that doesn't cause automatic updating. + See also |nvim__redraw()|. *:redrawt* *:redrawtabline* :redrawt[abline] Redraw the tabline. Useful to update the tabline when 'tabline' includes an item that doesn't trigger - automatic updating. + automatic updating. See also |nvim__redraw()|. *N<Del>* <Del> When entering a number: Remove the last digit. @@ -396,6 +400,7 @@ gx Opens the current filepath or URL (decided by |:command| - filter by command name |:files| - filter by file name |:highlight| - filter by highlight group + |:history| - filter by history commands |:jumps| - filter by file name |:let| - filter by variable name |:list| - filter whole line @@ -557,5 +562,47 @@ LessInitFunc in your vimrc, for example: > set nocursorcolumn nocursorline endfunc < +============================================================================== +3. Commenting *commenting* + +Nvim supports commenting and uncommenting of lines based on 'commentstring'. + +Acting on a single line behaves as follows: +- If the line matches 'commentstring', the comment markers are removed (e.g. + `/*foo*/` is transformed to `foo`). +- Otherwise the comment markers are added to the current line (e.g. `foo` is + transformed to `/*foo*/`). Blank lines are ignored. + +Acting on multiple lines behaves as follows: +- If each affected non-blank line matches 'commentstring', then all comment + markers are removed. +- Otherwise all affected lines are converted to comments; blank lines are + transformed to empty comments (e.g. `/**/`). Comment markers are aligned to + the least indented line. + +Matching 'commentstring' does not account for whitespace in comment markers. +Removing comment markers is first attempted exactly, with fallback to using +markers trimmed from whitespace. + +If the filetype of the buffer is associated with a language for which a +|treesitter| parser is installed, then |vim.filetype.get_option()| is called +to look up the value of 'commentstring' corresponding to the cursor position. +(This can be different from the buffer's 'commentstring' in case of +|treesitter-language-injections|.) + + *gc* *gc-default* +gc{motion} Comment or uncomment lines covered by {motion}. + + *gcc* *gcc-default* +gcc Comment or uncomment [count] lines starting at cursor. + + *v_gc* *v_gc-default* +{Visual}gc Comment or uncomment the selected line(s). + + *o_gc* *o_gc-default* +gc Text object for the largest contiguous block of + non-blank commented lines around the cursor (e.g. + `gcgc` uncomments a comment block; `dgc` deletes it). + Works only in Operator-pending mode. vim:noet:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index b0caf9fdaf..5d894bb5e1 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -1,19 +1,19 @@ *vim_diff.txt* Nvim - NVIM REFERENCE MANUAL + NVIM REFERENCE MANUAL -Differences between Nvim and Vim *vim-differences* +Differences between Nvim and Vim *vim-differences* Nvim differs from Vim in many ways, although editor and Vimscript (not Vim9script) features are mostly identical. This document is a complete and centralized reference of the differences. - Type |gO| to see the table of contents. + Type |gO| to see the table of contents. ============================================================================== -Configuration *nvim-config* +Configuration *nvim-config* User configuration and data files are found in standard |base-directories| (see also |$NVIM_APPNAME|). Note in particular: @@ -24,7 +24,7 @@ User configuration and data files are found in standard |base-directories| session information. |shada| ============================================================================== -Defaults *nvim-defaults* +Defaults *nvim-defaults* - Filetype detection is enabled by default. This can be disabled by adding ":filetype off" to |init.vim|. @@ -52,6 +52,8 @@ Defaults *nvim-defaults* - 'encoding' is UTF-8 (cf. 'fileencoding' for file-content encoding) - 'fillchars' defaults (in effect) to "vert:│,fold:·,foldsep:│" - 'formatoptions' defaults to "tcqj" +- 'grepprg' uses the -H and -I flags for regular grep, + and defaults to using ripgrep if available - 'hidden' is enabled - 'history' defaults to 10000 (the maximum) - 'hlsearch' is enabled @@ -80,6 +82,7 @@ Defaults *nvim-defaults* - 'tags' defaults to "./tags;,tags" - 'termguicolors' is enabled by default if Nvim can detect support from the host terminal +- 'ttimeout' is enabled - 'ttimeoutlen' defaults to 50 - 'ttyfast' is always set - 'undodir' defaults to ~/.local/state/nvim/undo// (|xdg|), auto-created @@ -96,7 +99,7 @@ Defaults *nvim-defaults* - |g:vimsyn_embed| defaults to "l" to enable Lua highlighting DEFAULT MOUSE - *default-mouse* *disable-mouse* + *default-mouse* *disable-mouse* By default the mouse is enabled, and <RightMouse> opens a |popup-menu| with standard actions ("Cut", "Copy", "Paste", …). Mouse is NOT enabled in |command-mode| or the |more-prompt|, so you can temporarily disable it just by @@ -120,7 +123,7 @@ To remove the "How-to disable mouse" menu item and the separator above it: >vim aunmenu PopUp.-1- < DEFAULT MAPPINGS - *default-mappings* + *default-mappings* Nvim creates the following default mappings at |startup|. You can disable any of these in your config by simply removing the mapping, e.g. ":unmap Y". @@ -133,11 +136,21 @@ of these in your config by simply removing the mapping, e.g. ":unmap Y". - @ |v_@-default| - # |v_#-default| - * |v_star-default| +- gc |gc-default| |v_gc-default| |o_gc-default| +- gcc |gcc-default| +- gr prefix |gr-default| + - |grn| + - |grr| + - |gra| +- <C-S> |i_CTRL-S| +- ]d |]d-default| +- [d |[d-default| +- <C-W>d |CTRL-W_d-default| - Nvim LSP client defaults |lsp-defaults| - K |K-lsp-default| DEFAULT AUTOCOMMANDS - *default-autocmds* + *default-autocmds* Default autocommands exist in the following groups. Use ":autocmd! {group}" to remove them and ":autocmd {group}" to see how they're defined. @@ -161,7 +174,7 @@ nvim_swapfile: swapfile…" message. ============================================================================== -New Features *nvim-features* +New Features *nvim-features* MAJOR COMPONENTS @@ -186,7 +199,7 @@ USER EXPERIENCE Working intuitively and consistently is a major goal of Nvim. - *feature-compile* + *feature-compile* - Nvim always includes ALL features, in contrast to Vim (which ships various combinations of 100+ optional features). |feature-compile| Think of it as a leaner version of Vim's "HUGE" build. This reduces surface area for bugs, @@ -233,182 +246,176 @@ by Nvim developers. FEATURES Command-line: - The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted +- The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted using a built-in Vimscript expression parser. |expr-highlight| - *E5408* *E5409* - |input()|, |inputdialog()| support custom highlighting. |input()-highlight| - *g:Nvim_color_cmdline* - (Experimental) Command-line (|:|) is colored by callback defined in - `g:Nvim_color_cmdline` (this callback is for testing only, and will be - removed in the future). +- *E5408* *E5409* |input()|, |inputdialog()| support custom highlighting. + |input()-highlight| +- (Experimental) *g:Nvim_color_cmdline* Command-line (|:|) is colored by + callback defined in `g:Nvim_color_cmdline` (this callback is for testing + only, and will be removed in the future). Commands: - |:checkhealth| - |:drop| is always available - |:Man| is available by default, with many improvements such as completion - |:match| can be invoked before highlight group is defined - |:source| works with Lua +- |:checkhealth| +- |:drop| is always available +- |:Man| is available by default, with many improvements such as completion +- |:match| can be invoked before highlight group is defined +- |:source| works with Lua User commands can support |:command-preview| to show results as you type - |:write| with "++p" flag creates parent directories. +- |:write| with "++p" flag creates parent directories. Events: - |RecordingEnter| - |RecordingLeave| - |SearchWrapped| - |Signal| - |TabNewEntered| - |TermClose| - |TermOpen| - |UIEnter| - |UILeave| +- |RecordingEnter| +- |RecordingLeave| +- |SearchWrapped| +- |Signal| +- |TabNewEntered| +- |TermClose| +- |TermOpen| +- |UIEnter| +- |UILeave| Functions: - |dictwatcheradd()| notifies a callback whenever a |Dict| is modified - |dictwatcherdel()| - |menu_get()| - |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization - |stdpath()| - |system()|, |systemlist()| can run {cmd} directly (without 'shell') - |matchadd()| can be called before highlight group is defined - |tempname()| tries to recover if the Nvim |tempdir| disappears. - |writefile()| with "p" flag creates parent directories. +- |dictwatcheradd()| notifies a callback whenever a |Dict| is modified +- |dictwatcherdel()| +- |menu_get()| +- |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization +- |stdpath()| +- |system()|, |systemlist()| can run {cmd} directly (without 'shell') +- |matchadd()| can be called before highlight group is defined +- |tempname()| tries to recover if the Nvim |tempdir| disappears. +- |writefile()| with "p" flag creates parent directories. Highlight groups: - |highlight-blend| controls blend level for a highlight group - |expr-highlight| highlight groups (prefixed with "Nvim") - |hl-NormalFloat| highlights floating window - |hl-FloatBorder| highlights border of a floating window - |hl-FloatTitle| highlights title of a floating window - |hl-FloatFooter| highlights footer of a floating window - |hl-NormalNC| highlights non-current windows - |hl-MsgArea| highlights messages/cmdline area - |hl-MsgSeparator| highlights separator for scrolled messages - |hl-Substitute| - |hl-TermCursor| - |hl-TermCursorNC| - |hl-WinSeparator| highlights window separators - |hl-Whitespace| highlights 'listchars' whitespace - |hl-WinBar| highlights 'winbar' - |hl-WinBarNC| highlights non-current window 'winbar' +- |highlight-blend| controls blend level for a highlight group +- |expr-highlight| highlight groups (prefixed with "Nvim") +- |hl-NormalFloat| highlights floating window +- |hl-FloatBorder| highlights border of a floating window +- |hl-FloatTitle| highlights title of a floating window +- |hl-FloatFooter| highlights footer of a floating window +- |hl-NormalNC| highlights non-current windows +- |hl-MsgArea| highlights messages/cmdline area +- |hl-MsgSeparator| highlights separator for scrolled messages +- |hl-Substitute| +- |hl-TermCursor| +- |hl-TermCursorNC| +- |hl-WinSeparator| highlights window separators +- |hl-Whitespace| highlights 'listchars' whitespace +- |hl-WinBar| highlights 'winbar' +- |hl-WinBarNC| highlights non-current window 'winbar' Input/Mappings: - ALT (|META|) chords always work (even in the |TUI|). Map |<M-| with any key: +- ALT (|META|) chords always work (even in the |TUI|). Map |<M-| with any key: <M-1>, <M-BS>, <M-Del>, <M-Ins>, <M-/>, <M-\>, <M-Space>, <M-Enter>, etc. - Case-sensitive: <M-a> and <M-A> are two different keycodes. - - ALT may behave like <Esc> if not mapped. |i_ALT| |v_ALT| |c_ALT| + - Case-sensitive: <M-a> and <M-A> are two different keycodes. +- ALT may behave like <Esc> if not mapped. |i_ALT| |v_ALT| |c_ALT| Normal commands: - |gO| shows a filetype-defined "outline" of the current buffer. - |Q| replays the last recorded macro instead of switching to Ex mode (|gQ|). +- |gO| shows a filetype-defined "outline" of the current buffer. +- |Q| replays the last recorded macro instead of switching to Ex mode (|gQ|). Options: - Local values for global-local number/boolean options are unset when the - option is set without a scope (e.g. by using |:set|), similarly to how - global-local string options work. - - 'autoread' works in the terminal (if it supports "focus" events) - 'cpoptions' flags: |cpo-_| - 'diffopt' "linematch" feature - 'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The + +Local values for global-local number/boolean options are unset when the option +is set without a scope (e.g. by using |:set|), similarly to how global-local +string options work. + +- 'autoread' works in the terminal (if it supports "focus" events) +- 'cpoptions' flags: |cpo-_| +- 'diffopt' "linematch" feature +- 'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The user is prompted whether to trust the file. - 'fillchars' flags: "msgsep", "horiz", "horizup", "horizdown", +- 'fillchars' flags: "msgsep", "horiz", "horizup", "horizdown", "vertleft", "vertright", "verthoriz" - 'foldcolumn' supports up to 9 dynamic/fixed columns - 'guicursor' works in the terminal (TUI) - 'inccommand' shows interactive results for |:substitute|-like commands +- 'foldcolumn' supports up to 9 dynamic/fixed columns +- 'guicursor' works in the terminal (TUI) +- 'inccommand' shows interactive results for |:substitute|-like commands and |:command-preview| commands - 'jumpoptions' "view" tries to restore the |mark-view| when moving through - the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|. - 'laststatus' global statusline support - 'mousescroll' amount to scroll by when scrolling with a mouse - 'pumblend' pseudo-transparent popupmenu - 'scrollback' - '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' middle-click on tabpage label closes tabpage, +- 'jumpoptions' "view" tries to restore the |mark-view| when moving through +- the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|. +- 'laststatus' global statusline support +- 'mousescroll' amount to scroll by when scrolling with a mouse +- 'pumblend' pseudo-transparent popupmenu +- 'scrollback' +- 'shortmess' + - "F" flag does not affect output from autocommands. + - "q" flag fully hides macro recording message. +- 'signcolumn' supports up to 9 dynamic/fixed columns +- 'statuscolumn' full control of columns using 'statusline' format +- '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| - 'winhighlight' window-local highlights +- 'termpastefilter' +- 'ttimeout', 'ttimeoutlen' behavior was simplified +- 'winblend' pseudo-transparency in floating windows |api-floatwin| +- 'winhighlight' window-local highlights Providers: - If a Python interpreter is available on your `$PATH`, |:python| and +- If a Python interpreter is available on your `$PATH`, |:python| and |:python3| are always available. See |provider-python|. Shell: - Shell output (|:!|, |:make|, …) is always routed through the UI, so it +- Shell output (|:!|, |:make|, …) is always routed through the UI, so it cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if you want to mess up the screen :) - - Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|) +- Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|) if there is too much output. No data is lost, this only affects display and improves performance. |:terminal| output is never throttled. - - |:!| does not support "interactive" commands. Use |:terminal| instead. +- |:!| does not support "interactive" commands. Use |:terminal| instead. (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.) - - :!start is not special-cased on Windows. - - |system()| does not support writing/reading "backgrounded" commands. |E5677| +- :!start is not special-cased on Windows. +- |system()| does not support writing/reading "backgrounded" commands. |E5677| Signs: - Signs are removed if the associated line is deleted. - Signs placed twice with the same identifier in the same group are moved. +- Signs are removed if the associated line is deleted. +- Signs placed twice with the same identifier in the same group are moved. Startup: - |-e| and |-es| invoke the same "improved Ex mode" as -E and -Es. - |-E| and |-Es| read stdin as text (into buffer 1). - |-es| and |-Es| have improved behavior: +- |-e| and |-es| invoke the same "improved Ex mode" as -E and -Es. +- |-E| and |-Es| read stdin as text (into buffer 1). +- |-es| and |-Es| have improved behavior: - Quits automatically, don't need "-c qa!". - Skips swap-file dialog. - |-s| reads Normal commands from stdin if the script name is "-". - Reading text (instead of commands) from stdin |--|: +- |-s| reads Normal commands from stdin if the script name is "-". +- Reading text (instead of commands) from stdin |--|: - works by default: "-" file is optional - works in more cases: |-Es|, file args TUI: - *:set-termcap* - Start Nvim with 'verbose' level 3 to show terminal capabilities: > - nvim -V3 + *:set-termcap* +- Start Nvim with 'verbose' level 3 to show terminal capabilities: > + nvim -V3 < - *'term'* *E529* *E530* *E531* - 'term' reflects the terminal type derived from |$TERM| and other environment + *'term'* *E529* *E530* *E531* +- 'term' reflects the terminal type derived from |$TERM| and other environment checks. For debugging only; not reliable during startup. >vim - :echo &term -< "builtin_x" means one of the |builtin-terms| was chosen, because the expected + :echo &term +- "builtin_x" means one of the |builtin-terms| was chosen, because the expected terminfo file was not found on the system. - - Nvim will use 256-colour capability on Linux virtual terminals. Vim uses +- Nvim will use 256-colour capability on Linux virtual terminals. Vim uses only 8 colours plus bright foreground on Linux VTs. - - Vim combines what is in its |builtin-terms| with what it reads from terminfo, +- Vim combines what is in its |builtin-terms| with what it reads from terminfo, and has a 'ttybuiltin' setting to control how that combination works. Nvim uses one or the other, it does not attempt to merge the two. UI/Display: - |Visual| selection highlights the character at cursor. |visual-use| - - messages: When showing messages longer than 'cmdheight', only +- |Visual| selection highlights the character at cursor. |visual-use| +- messages: When showing messages longer than 'cmdheight', only scroll the message lines, not the entire screen. The separator line is decorated by |hl-MsgSeparator| and the "msgsep" flag of 'fillchars'. *msgsep* Variables: - |v:progpath| is always absolute ("full") - |v:windowid| is always available (for use by external UIs) - |OptionSet| autocommand args |v:option_new|, |v:option_old|, - |v:option_oldlocal|, |v:option_oldglobal| have the type of the option +- |v:progpath| is always absolute ("full") +- |v:windowid| is always available (for use by external UIs) +- |OptionSet| autocommand args |v:option_new|, |v:option_old|, +- |v:option_oldlocal|, |v:option_oldglobal| have the type of the option instead of always being strings. |v:option_old| is now the old global value for all global-local options, instead of just string global-local options. Vimscript: - |:redir| nested in |execute()| works. +- |:redir| nested in |execute()| works. ============================================================================== -Upstreamed features *nvim-upstreamed* +Upstreamed features *nvim-upstreamed* These Nvim features were later integrated into Vim. @@ -423,45 +430,44 @@ These Nvim features were later integrated into Vim. - 'statusline' supports unlimited alignment sections ============================================================================== -Other changes *nvim-changed* +Other changes *nvim-changed* This section documents various low-level behavior changes. |mkdir()| behaviour changed: -1. Assuming /tmp/foo does not exist and /tmp can be written to - mkdir('/tmp/foo/bar', 'p', 0700) will create both /tmp/foo and /tmp/foo/bar - with 0700 permissions. Vim mkdir will create /tmp/foo with 0755. -2. If you try to create an existing directory with `'p'` (e.g. mkdir('/', - 'p')) mkdir() will silently exit. In Vim this was an error. -3. mkdir() error messages now include strerror() text when mkdir fails. +- 1. Assuming /tmp/foo does not exist and /tmp can be written to + mkdir('/tmp/foo/bar', 'p', 0700) will create both /tmp/foo and + /tmp/foo/bar with 0700 permissions. Vim mkdir will create /tmp/foo with + 0755. +- 2. If you try to create an existing directory with `'p'` (e.g. mkdir('/', + 'p')) mkdir() will silently exit. In Vim this was an error. +- 3. mkdir() error messages now include strerror() text when mkdir fails. |string()| and |:echo| behaviour changed: -1. No maximum recursion depth limit is applied to nested container - structures. -2. |string()| fails immediately on nested containers, not when recursion limit - was exceeded. -3. When |:echo| encounters duplicate containers like >vim - +- 1. No maximum recursion depth limit is applied to nested container + structures. +- 2. |string()| fails immediately on nested containers, not when recursion + limit was exceeded. +- 3. When |:echo| encounters duplicate containers like >vim let l = [] echo [l, l] -< - it does not use "[...]" (was: "[[], [...]]", now: "[[], []]"). "..." is - only used for recursive containers. -4. |:echo| printing nested containers adds "@level" after "..." designating - the level at which recursive container was printed: |:echo-self-refer|. - Same thing applies to |string()| (though it uses construct like - "{E724@level}"), but this is not reliable because |string()| continues to - error out. -5. Stringifyed infinite and NaN values now use |str2float()| and can be evaled - back. -6. (internal) Trying to print or stringify VAR_UNKNOWN in Vim results in - nothing, E908, in Nvim it is internal error. +< it does not use "[...]" (was: "[[], [...]]", now: "[[], []]"). "..." is + only used for recursive containers. +- 4. |:echo| printing nested containers adds "@level" after "..." designating + the level at which recursive container was printed: |:echo-self-refer|. + Same thing applies to |string()| (though it uses construct like + "{E724@level}"), but this is not reliable because |string()| continues to + error out. +- 5. Stringifyed infinite and NaN values now use |str2float()| and can be + evaled back. +- 6. (internal) Trying to print or stringify VAR_UNKNOWN in Vim results in + nothing, E908, in Nvim it is internal error. |json_decode()| behaviour changed: -1. It may output |msgpack-special-dict|. -2. |msgpack-special-dict| is emitted also in case of duplicate keys, while in - Vim it errors out. -3. It accepts only valid JSON. Trailing commas are not accepted. +- 1. It may output |msgpack-special-dict|. +- 2. |msgpack-special-dict| is emitted also in case of duplicate keys, while + in Vim it errors out. +- 3. It accepts only valid JSON. Trailing commas are not accepted. |json_encode()| behaviour slightly changed: now |msgpack-special-dict| values are accepted, but |v:none| is not. @@ -505,38 +511,37 @@ Lua interface (|lua.txt|): 'runtimepath'. |lua-module-load| Commands: - |:doautocmd| does not warn about "No matching autocommands". - |:wincmd| accepts a count. - `:write!` does not show a prompt if the file was updated externally. - |:=| does not accept |ex-flags|. With an arg it is equivalent to |:lua=| +- |:doautocmd| does not warn about "No matching autocommands". +- |:wincmd| accepts a count. +- `:write!` does not show a prompt if the file was updated externally. +- |:=| does not accept |ex-flags|. With an arg it is equivalent to |:lua=| Command-line: - The meanings of arrow keys do not change depending on 'wildoptions'. +- The meanings of arrow keys do not change depending on 'wildoptions'. Functions: - |input()| and |inputdialog()| support for each other’s features (return on +- |input()| and |inputdialog()| support for each other’s features (return on cancel and completion respectively) via dictionary argument (replaces all other arguments if used), and "cancelreturn" can have any type if passed in a dictionary. - |input()| and |inputdialog()| support user-defined cmdline highlighting. +- |input()| and |inputdialog()| support user-defined cmdline highlighting. Highlight groups: - |hl-ColorColumn|, |hl-CursorColumn| are lower priority than most other +- |hl-ColorColumn|, |hl-CursorColumn| are lower priority than most other groups - |hl-CurSearch| highlights match under cursor instead of last match found +- |hl-CurSearch| highlights match under cursor instead of last match found using |n| or |N| - |hl-CursorLine| is low-priority unless foreground color is set - |hl-VertSplit| superseded by |hl-WinSeparator| - Highlight groups names are allowed to contain `@` characters. - It is an error to define a highlight group with a name that doesn't match - the regexp `[a-zA-Z0-9_.@-]*` (see |group-name|). - -Macro/|recording| behavior - Replay of a macro recorded during :lmap produces the same actions as when it +- |hl-CursorLine| is low-priority unless foreground color is set +- |hl-VertSplit| superseded by |hl-WinSeparator| +- Highlight groups names are allowed to contain `@` characters. + - It is an error to define a highlight group with a name that doesn't match + the regexp `[a-zA-Z0-9_.@-]*` (see |group-name|). + +Macro (|recording|) behavior: +- Replay of a macro recorded during :lmap produces the same actions as when it was recorded. In Vim if a macro is recorded while using :lmap'ped keys then the behaviour during record and replay differs. - - 'keymap' is implemented via :lmap instead of :lnoremap so that you can use +- 'keymap' is implemented via :lmap instead of :lnoremap so that you can use macros and 'keymap' at the same time. This also means you can use |:imap| on the results of keys from 'keymap'. @@ -547,13 +552,13 @@ Mappings: lhs of a mapping. Motion: - The |jumplist| avoids useless/phantom jumps. +- The |jumplist| avoids useless/phantom jumps. Performance: - Folds are not updated during insert-mode. +- Folds are not updated during insert-mode. Syntax highlighting: - syncolor.vim has been removed. Nvim now sets up default highlighting groups +- syncolor.vim has been removed. Nvim now sets up default highlighting groups automatically for both light and dark backgrounds, regardless of whether or not syntax highlighting is enabled. This means that |:syntax-on| and |:syntax-enable| are now identical. Users who previously used an @@ -561,10 +566,10 @@ Syntax highlighting: colorscheme. |:colorscheme| Vimscript compatibility: - `count` does not alias to |v:count| - `errmsg` does not alias to |v:errmsg| - `shell_error` does not alias to |v:shell_error| - `this_session` does not alias to |v:this_session| +- `count` does not alias to |v:count| +- `errmsg` does not alias to |v:errmsg| +- `shell_error` does not alias to |v:shell_error| +- `this_session` does not alias to |v:this_session| Working directory (Vim implemented some of these after Nvim): - |DirChanged| and |DirChangedPre| can be triggered when switching to another @@ -582,11 +587,8 @@ 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* +Missing features *nvim-missing* These legacy Vim features are not yet implemented: @@ -596,75 +598,75 @@ These legacy Vim features are not yet implemented: - *'previewpopup'* ============================================================================== -Removed legacy features *nvim-removed* +Removed legacy features *nvim-removed* These Vim features were intentionally removed from Nvim. Aliases: - ex (alias for "nvim -e") - exim (alias for "nvim -E") - gex (GUI) - gview (GUI) - gvim (GUI) - gvimdiff (GUI) - rgview (GUI) - rgvim (GUI) - rview - rvim - view (alias for "nvim -R") - vimdiff (alias for "nvim -d" |diff-mode|) +- ex (alias for "nvim -e") +- exim (alias for "nvim -E") +- gex (GUI) +- gview (GUI) +- gvim (GUI) +- gvimdiff (GUI) +- rgview (GUI) +- rgvim (GUI) +- rview +- rvim +- view (alias for "nvim -R") +- vimdiff (alias for "nvim -d" |diff-mode|) Commands: - :behave - :fixdel - *hardcopy* `:hardcopy` was removed. Instead, use `:TOhtml` and print the +- :behave +- :fixdel +- *hardcopy* `:hardcopy` was removed. Instead, use `:TOhtml` and print the resulting HTML using a web browser or other HTML viewer. - :helpfind - :mode (no longer accepts an argument) - :open - :Print - :promptfind - :promptrepl - :scriptversion (always version 1) - :shell - :sleep! (does not hide the cursor; same as :sleep) - :smile - :tearoff - :cstag - :cscope - :lcscope - :scscope - :Vimuntar - The old `:TOhtml`, replaced by a Lua version (contains many differences) +- :helpfind +- :mode (no longer accepts an argument) +- :open +- :Print +- :promptfind +- :promptrepl +- :scriptversion (always version 1) +- :shell +- :sleep! (does not hide the cursor; same as :sleep) +- :smile +- :tearoff +- :cstag +- :cscope +- :lcscope +- :scscope +- :Vimuntar +- `:TOhtml` was replaced by a Lua version (with various differences) Compile-time features: - Emacs tags support - X11 integration (see |x11-selection|) +- Emacs tags support +- X11 integration (see |x11-selection|) Cscope: *cscope* - Cscope support was removed in favour of plugin-based solutions such as: +- Cscope support was removed in favour of plugin-based solutions such as: https://github.com/dhananjaylatkar/cscope_maps.nvim Eval: - Vim9script - *cscope_connection()* - *err_teapot()* - *js_encode()* - *js_decode()* - *v:none* (used by Vim to represent JavaScript "undefined"); use |v:null| instead. - *v:sizeofint* - *v:sizeoflong* - *v:sizeofpointer* +- Vim9script +- *cscope_connection()* +- *err_teapot()* +- *js_encode()* +- *js_decode()* +- *v:none* (used by Vim to represent JavaScript "undefined"); use |v:null| instead. +- *v:sizeofint* +- *v:sizeoflong* +- *v:sizeofpointer* Events: - *SafeStateAgain* - *SigUSR1* Use |Signal| to detect `SIGUSR1` signal instead. +- *SafeStateAgain* +- *SigUSR1* Use |Signal| to detect `SIGUSR1` signal instead. Highlight groups: - *hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim - supports 'winhighlight' window-local highlights. - For example, to mimic Vim's StatusLineTerm: >vim +- *hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim + supports 'winhighlight' window-local highlights. For example, to mimic Vim's + StatusLineTerm: >vim hi StatusLineTerm ctermfg=black ctermbg=green hi StatusLineTermNC ctermfg=green autocmd TermOpen,WinEnter * if &buftype=='terminal' @@ -673,48 +675,45 @@ Highlight groups: < Options: - *'aleph'* *'al'* - antialias - 'backspace' no longer supports number values. Instead: +- *'aleph'* *'al'* +- antialias +- 'backspace' no longer supports number values. Instead: - for `backspace=0` set `backspace=` (empty) - for `backspace=1` set `backspace=indent,eol` - for `backspace=2` set `backspace=indent,eol,start` (default behavior in Nvim) - for `backspace=3` set `backspace=indent,eol,nostop` - *'balloondelay'* *'bdlay'* - *'ballooneval'* *'beval'* *'noballooneval'* *'nobeval'* - *'balloonexpr'* *'bexpr'* - bioskey (MS-DOS) - conskey (MS-DOS) - *'cp'* *'nocompatible'* *'nocp'* *'compatible'* (Nvim is always "nocompatible".) - 'cpoptions' (gjpkHw<*- and all POSIX flags were removed) - *'cryptmethod'* *'cm'* *'key'* (Vim encryption implementation) - cscopepathcomp - cscopeprg - cscopequickfix - cscoperelative - cscopetag - cscopetagorder - cscopeverbose - *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'* - 'encoding' ("utf-8" is always used) - esckeys - 'guioptions' "t" flag was removed - *'guifontset'* *'gfs'* (Use 'guifont' instead.) - *'guipty'* (Nvim uses pipes and PTYs consistently on all platforms.) - 'highlight' (Names of builtin |highlight-groups| cannot be changed.) - *'hkmap'* *'hk'* use `set keymap=hebrew` instead. - *'hkmapp'* *'hkp'* use `set keymap=hebrewp` instead. - keyprotocol - - *'pastetoggle'* *'pt'* Just Paste It.™ |paste| is handled automatically when +- *'balloondelay'* *'bdlay'* +- *'ballooneval'* *'beval'* *'noballooneval'* *'nobeval'* +- *'balloonexpr'* *'bexpr'* +- bioskey (MS-DOS) +- conskey (MS-DOS) +- *'cp'* *'nocompatible'* *'nocp'* *'compatible'* (Nvim is always "nocompatible".) +- 'cpoptions' (gjpkHw<*- and all POSIX flags were removed) +- *'cryptmethod'* *'cm'* *'key'* (Vim encryption implementation) +- cscopepathcomp +- cscopeprg +- cscopequickfix +- cscoperelative +- cscopetag +- cscopetagorder +- cscopeverbose +- *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'* +- 'encoding' ("utf-8" is always used) +- esckeys +- 'guioptions' "t" flag was removed +- *'guifontset'* *'gfs'* (Use 'guifont' instead.) +- *'guipty'* (Nvim uses pipes and PTYs consistently on all platforms.) +- 'highlight' (Names of builtin |highlight-groups| cannot be changed.) +- *'hkmap'* *'hk'* use `set keymap=hebrew` instead. +- *'hkmapp'* *'hkp'* use `set keymap=hebrewp` instead. +- keyprotocol +- *'pastetoggle'* *'pt'* Just Paste It.™ |paste| is handled automatically when you paste text using your terminal's or GUI's paste feature (CTRL-SHIFT-v, CMD-v (macOS), middle-click, …). - - *'imactivatefunc'* *'imaf'* - *'imactivatekey'* *'imak'* - *'imstatusfunc'* *'imsf'* - *'insertmode'* *'im'* Use the following script to emulate 'insertmode': ->vim +- *'imactivatefunc'* *'imaf'* +- *'imactivatekey'* *'imak'* +- *'imstatusfunc'* *'imsf'* +- *'insertmode'* *'im'* Use the following script to emulate 'insertmode': >vim autocmd BufWinEnter * startinsert inoremap <Esc> <C-X><C-Z><C-]> inoremap <C-C> <C-X><C-Z> @@ -740,50 +739,44 @@ Options: end end) EOF -< - *'macatsui'* - *'maxcombine'* *'mco'* - Nvim counts maximum character sizes in bytes, not codepoints. This is - guaranteed to be big enough to always fit all chars properly displayed - in vim with 'maxcombine' set to 6. - - You can still edit text with larger characters than fits in the screen buffer, - you just can't see them. Use |g8| or |ga|. See |mbyte-combining|. - - NOTE: the rexexp engine still has a hard-coded limit of considering +- *'macatsui'* +- *'maxcombine'* *'mco'* : Nvim counts maximum character sizes in bytes, not + codepoints. This is guaranteed to be big enough to always fit all chars + properly displayed in vim with 'maxcombine' set to 6. + - You can still edit text with larger characters than fits in the screen + buffer, you just can't see them. Use |g8| or |ga|. See |mbyte-combining|. + - NOTE: the rexexp engine still has a hard-coded limit of considering 6 composing chars only. - - *'maxmem'* Nvim delegates memory-management to the OS. - *'maxmemtot'* Nvim delegates memory-management to the OS. - printoptions - *'printdevice'* - *'printencoding'* - *'printexpr'* - *'printfont'* - *'printheader'* - *'printmbcharset'* - *'prompt'* *'noprompt'* - *'remap'* *'noremap'* - *'restorescreen'* *'rs'* *'norestorescreen'* *'nors'* - *'secure'* - Everything is allowed in 'exrc' files since they must be explicitly marked - trusted. - *'shelltype'* - 'shortmess' flags: *shm-f* *shm-n* *shm-x* *shm-i* (behave like always on) - *'shortname'* *'sn'* *'noshortname'* *'nosn'* - *'swapsync'* *'sws'* - *'termencoding'* *'tenc'* (Vim 7.4.852 also removed this for Windows) - *'terse'* *'noterse'* (Add "s" to 'shortmess' instead) - textauto - textmode - *'toolbar'* *'tb'* - *'toolbariconsize'* *'tbis'* - *'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'* - *'ttyfast'* *'tf'* *'nottyfast'* *'notf'* - *'ttymouse'* *'ttym'* - *'ttyscroll'* *'tsl'* - *'ttytype'* *'tty'* - weirdinvert +- *'maxmem'* Nvim delegates memory-management to the OS. +- *'maxmemtot'* Nvim delegates memory-management to the OS. +- printoptions +- *'printdevice'* +- *'printencoding'* +- *'printexpr'* +- *'printfont'* +- *'printheader'* +- *'printmbcharset'* +- *'prompt'* *'noprompt'* +- *'remap'* *'noremap'* +- *'restorescreen'* *'rs'* *'norestorescreen'* *'nors'* +- *'secure'* : Everything is allowed in 'exrc' files, because they must be + explicitly marked as "trusted". +- *'shelltype'* +- 'shortmess' flags: *shm-f* *shm-n* *shm-x* *shm-i* (behave like always on) +- *'shortname'* *'sn'* *'noshortname'* *'nosn'* +- *'swapsync'* *'sws'* +- *'termencoding'* *'tenc'* (Vim 7.4.852 also removed this for Windows) +- *'terse'* *'noterse'* (Add "s" to 'shortmess' instead) +- textauto +- textmode +- *'toolbar'* *'tb'* +- *'toolbariconsize'* *'tbis'* +- *'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'* +- *'ttyfast'* *'tf'* *'nottyfast'* *'notf'* +- *'ttymouse'* *'ttym'* +- *'ttyscroll'* *'tsl'* +- *'ttytype'* *'tty'* +- weirdinvert Plugins: @@ -799,47 +792,47 @@ Providers: - *if_tcl* Startup: - --literal (file args are always literal; to expand wildcards on Windows, use - |:n| e.g. `nvim +"n *"`) - Easy mode: eview, evim, nvim -y - Restricted mode: rview, rvim, nvim -Z - Vi mode: nvim -v +- `--literal`: File args are always literal; to expand wildcards on Windows, + use |:n| e.g. `nvim +"n *"` +- Easy mode: eview, evim, nvim -y +- Restricted mode: rview, rvim, nvim -Z +- Vi mode: nvim -v Test functions: - test_alloc_fail() - test_autochdir() - test_disable_char_avail() - test_feedinput() - test_garbagecollect_soon - test_getvalue() - test_ignore_error() - test_null_blob() - test_null_channel() - test_null_dict() - test_null_function() - test_null_job() - test_null_list() - test_null_partial() - test_null_string() - test_option_not_set() - test_override() - test_refcount() - test_scrollbar() - test_setmouse() - test_settime() - test_srand_seed() +- test_alloc_fail() +- test_autochdir() +- test_disable_char_avail() +- test_feedinput() +- test_garbagecollect_soon +- test_getvalue() +- test_ignore_error() +- test_null_blob() +- test_null_channel() +- test_null_dict() +- test_null_function() +- test_null_job() +- test_null_list() +- test_null_partial() +- test_null_string() +- test_option_not_set() +- test_override() +- test_refcount() +- test_scrollbar() +- test_setmouse() +- test_settime() +- test_srand_seed() TUI: - *t_xx* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI* - Nvim does not have special `t_XX` options nor <t_XX> keycodes to configure + *t_xx* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_SI* +- Nvim does not have special `t_XX` options nor <t_XX> keycodes to configure terminal capabilities. Instead Nvim treats the terminal as any other UI, e.g. 'guicursor' sets the terminal cursor style if possible. - *termcap* - Nvim never uses the termcap database, only |terminfo| and |builtin-terms|. + *termcap* +- Nvim never uses the termcap database, only |terminfo| and |builtin-terms|. - *xterm-8bit* *xterm-8-bit* - Xterm can be run in a mode where it uses true 8-bit CSI. Supporting this + *xterm-8bit* *xterm-8-bit* +- Xterm can be run in a mode where it uses true 8-bit CSI. Supporting this requires autodetection of whether the terminal is in UTF-8 mode or non-UTF-8 mode, as the 8-bit CSI character has to be written differently in each case. Vim issues a "request version" sequence to the terminal at startup and looks diff --git a/runtime/doc/visual.txt b/runtime/doc/visual.txt index a20fb6d31e..6d3aaa62dd 100644 --- a/runtime/doc/visual.txt +++ b/runtime/doc/visual.txt @@ -366,15 +366,15 @@ 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: +Visual mode |default-mappings| "@" and "Q" repeat a register for all selected +lines if the selection is linewise. 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 +With register "x" containing the commands `yi(VP`, visually selecting the first two lines and typing `@x` produces: hello diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt index e71e31abf8..15d836a83d 100644 --- a/runtime/doc/vvars.txt +++ b/runtime/doc/vvars.txt @@ -60,9 +60,10 @@ v:collate *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. + Dictionary containing the |complete-items| for the most + recently completed word 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. @@ -186,6 +187,7 @@ v:event 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| + reason Reason for completion being done. |CompleteDone| *v:exception* *exception-variable* v:exception diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index b71e7c80ab..4791e73929 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -502,35 +502,33 @@ horizontally split windows. CTRL-W H does it the other way around. *CTRL-W_K* CTRL-W K Move the current window to be at the very top, using the full - width of the screen. This works like closing the current - window and then creating another one with ":topleft split", - except that the current window contents is used for the new - window. + width of the screen. This works like `:topleft split`, except + it is applied to the current window and no new window is + created. *CTRL-W_J* CTRL-W J Move the current window to be at the very bottom, using the - full width of the screen. This works like closing the current - window and then creating another one with ":botright split", - except that the current window contents is used for the new - window. + full width of the screen. This works like `:botright split`, + except it is applied to the current window and no new window + is created. *CTRL-W_H* CTRL-W H Move the current window to be at the far left, using the - full height of the screen. This works like closing the - current window and then creating another one with - `:vert topleft split`, except that the current window contents - is used for the new window. + full height of the screen. This works like + `:vert topleft split`, except it is applied to the current + window and no new window is created. *CTRL-W_L* CTRL-W L Move the current window to be at the far right, using the full - height of the screen. This works like closing the - current window and then creating another one with - `:vert botright split`, except that the current window - contents is used for the new window. + height of the screen. This works like `:vert botright split`, + except it is applied to the current window and no new window + is created. *CTRL-W_T* CTRL-W T Move the current window to a new tab page. This fails if there is only one window in the current tab page. + This works like `:tab split`, except the previous window is + closed. When a count is specified the new tab page will be opened before the tab page with this index. Otherwise it comes after the current tab page. |