diff options
Diffstat (limited to 'runtime/doc')
57 files changed, 3511 insertions, 6441 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index c5dabeb551..92f5a261ee 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -406,18 +406,9 @@ Another use case are plugins that show output in an append-only buffer, and want to add highlights to the outputs. Highlight data cannot be preserved on writing and loading a buffer to file, nor in undo/redo cycles. -Highlights are registered using the |nvim_buf_add_highlight()| function. If an -external highlighter plugin wants to add many highlights in a batch, -performance can be improved by calling |nvim_buf_add_highlight()| as an -asynchronous notification, after first (synchronously) requesting a source id. - -|nvim_buf_add_highlight()| adds highlights as |extmarks|. If highlights need to -be tracked or manipulated after adding them, it is better to use -|nvim_buf_set_extmark()| directly, as this function returns the placed |extmark| -id. Thus, instead of >lua - vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end) -< -use >lua +Highlights are registered using the |nvim_buf_set_extmark()| function, which +adds highlights as |extmarks|. If highlights need to be tracked or manipulated +after adding them, the returned |extmark| id can be used. >lua -- create the highlight through an extmark extid = vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = hl_group}) @@ -428,32 +419,10 @@ use >lua vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid}) < -Example using the Python API client (|pynvim|): ->python - src = vim.new_highlight_source() - buf = vim.current.buffer - for i in range(5): - buf.add_highlight("String",i,0,-1,src_id=src) - # some time later ... - buf.clear_namespace(src) -< -If the highlights don't need to be deleted or updated, just pass -1 as -src_id (this is the default in python). Use |nvim_buf_clear_namespace()| to -clear highlights from a specific source, in a specific line range or the -entire buffer by passing in the line range 0, -1 (the latter is the default in -python as used above). - -Example using the API from Vimscript: >vim - - call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"]) - let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4) - call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1) - " some time later ... - call nvim_buf_clear_namespace(0, src, 0, -1) - +See also |vim.hl.range()|. ============================================================================== -Floating windows *api-floatwin* +Floating windows *api-floatwin* *floating-windows* Floating windows ("floats") are displayed on top of normal windows. This is useful to implement simple widgets, such as tooltips displayed next to the @@ -654,35 +623,22 @@ nvim_del_var({name}) *nvim_del_var()* • {name} Variable name nvim_echo({chunks}, {history}, {opts}) *nvim_echo()* - Echo a message. + Prints a message given by a list of `[text, hl_group]` "chunks". + + Example: >lua + vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {}) +< Parameters: ~ - • {chunks} A list of `[text, hl_group]` arrays, each representing a - text chunk with specified highlight group name or ID. - `hl_group` element can be omitted for no highlight. + • {chunks} List of `[text, hl_group]` pairs, where each is a `text` + string highlighted by the (optional) name or ID `hl_group`. • {history} if true, add to |message-history|. • {opts} Optional parameters. - • verbose: Message is printed as a result of 'verbose' - option. If Nvim was invoked with -V3log_file, the message - will be redirected to the log_file and suppressed from - direct output. - -nvim_err_write({str}) *nvim_err_write()* - Writes a message to the Vim error buffer. Does not append "\n", the - message is buffered (won't display) until a linefeed is written. - - Parameters: ~ - • {str} Message - -nvim_err_writeln({str}) *nvim_err_writeln()* - Writes a message to the Vim error buffer. Appends "\n", so the buffer is - flushed (and displayed). - - Parameters: ~ - • {str} Message - - See also: ~ - • nvim_err_write() + • err: Treat the message like `:echoerr`. Sets `hl_group` + to |hl-ErrorMsg| by default. + • verbose: Message is controlled by the 'verbose' option. + Nvim invoked with `-V3log` will write the message to the + "log" file instead of standard output. nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()* Evaluates statusline string. @@ -716,7 +672,10 @@ nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()* true. Each element of the array is a |Dict| with these keys: • start: (number) Byte index (0-based) of first character that uses the highlight. - • group: (string) Name of highlight group. + • group: (string) Name of highlight group. May be removed in the + future, use `groups` instead. + • groups: (array) Names of stacked highlight groups (highest + priority last). nvim_exec_lua({code}, {args}) *nvim_exec_lua()* Execute Lua code. Parameters (if any) are available as `...` inside the @@ -775,6 +734,8 @@ nvim_get_api_info() *nvim_get_api_info()* nvim_get_chan_info({chan}) *nvim_get_chan_info()* Gets information about a channel. + See |nvim_list_uis()| for an example of how to get channel info. + Parameters: ~ • {chan} channel_id, or 0 for current channel @@ -796,7 +757,7 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* present if a pty is used (e.g. for conpty on Windows). • "buffer" (optional) Buffer connected to |terminal| instance. • "client" (optional) Info about the peer (client on the other end of - the RPC channel), which it provided via |nvim_set_client_info()|. + the channel), as set by |nvim_set_client_info()|. nvim_get_color_by_name({name}) *nvim_get_color_by_name()* Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or @@ -1079,6 +1040,12 @@ nvim_list_tabpages() *nvim_list_tabpages()* nvim_list_uis() *nvim_list_uis()* Gets a list of dictionaries representing attached UIs. + Example: The Nvim builtin |TUI| sets its channel info as described in + |startup-tui|. In particular, it sets `client.name` to "nvim-tui". So you + can check if the TUI is running by inspecting the client name of each UI: >lua + vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name) +< + Return: ~ Array of UI dictionaries, each with these keys: • "height" Requested height of the UI @@ -1099,22 +1066,11 @@ nvim_load_context({dict}) *nvim_load_context()* Parameters: ~ • {dict} |Context| map. -nvim_notify({msg}, {log_level}, {opts}) *nvim_notify()* - Notify the user with a message - - Relays the call to vim.notify . By default forwards your message in the - echo area but can be overridden to trigger desktop notifications. - - Parameters: ~ - • {msg} Message to display to the user - • {log_level} The log level - • {opts} Reserved for future use. - nvim_open_term({buffer}, {opts}) *nvim_open_term()* Open a terminal instance in a buffer By default (and currently the only option) the terminal will not be - connected to an external process. Instead, input send on the channel will + connected to an external process. Instead, input sent on the channel will be echoed directly by the terminal. This is useful to display ANSI terminal sequences returned as part of a rpc message, or similar. @@ -1125,6 +1081,17 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* |nvim_chan_send()| can be called immediately to process sequences in a virtual terminal having the intended size. + Example: this `TermHl` command can be used to display and highlight raw + ANSI termcodes, so you can use Nvim as a "scrollback pager" (for terminals + like kitty): *ansi-colorize* *terminal-scrollback-pager* >lua + vim.api.nvim_create_user_command('TermHl', function() + local b = vim.api.nvim_create_buf(false, true) + local chan = vim.api.nvim_open_term(b, {}) + vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n')) + vim.api.nvim_win_set_buf(0, b) + end, { desc = 'Highlights ANSI termcodes in curbuf' }) +< + Attributes: ~ not allowed when |textlock| is active @@ -1143,13 +1110,6 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* Return: ~ Channel id, or 0 on error -nvim_out_write({str}) *nvim_out_write()* - Writes a message to the Vim output buffer. Does not append "\n", the - message is buffered (won't display) until a linefeed is written. - - Parameters: ~ - • {str} Message - nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* Pastes at cursor (in any mode), and sets "redo" so dot (|.|) will repeat the input. UIs call this to implement "paste", but it's also intended for @@ -1248,25 +1208,23 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) *nvim_set_client_info()* nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) - Self-identifies the client. + Self-identifies the client. Sets the `client` object returned by + |nvim_get_chan_info()|. - The client/plugin/application should call this after connecting, to - provide hints about its identity and purpose, for debugging and - orchestration. + Clients should call this just after connecting, to provide hints for + debugging and orchestration. (Note: Something is better than nothing! + Fields are optional, but at least set `name`.) Can be called more than once; the caller should merge old info if appropriate. Example: library first identifies the channel, then a plugin using that library later identifies itself. - Note: ~ - • "Something is better than nothing". You don't need to include all the - fields. - Attributes: ~ |RPC| only Parameters: ~ - • {name} Short name for the connected client + • {name} Client short-name. Sets the `client.name` field of + |nvim_get_chan_info()|. • {version} Dict describing the version, with these (optional) keys: • "major" major version (defaults to 0 if not set, for no release yet) @@ -1636,11 +1594,9 @@ nvim_command({command}) *nvim_command()* On execution error: fails with Vimscript error, updates v:errmsg. - Prefer using |nvim_cmd()| or |nvim_exec2()| over this. To evaluate - multiple lines of Vim script or an Ex command directly, use - |nvim_exec2()|. To construct an Ex command using a structured format and - then execute it, use |nvim_cmd()|. To modify an Ex command before - evaluating it, use |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. + Prefer |nvim_cmd()| or |nvim_exec2()| instead. To modify an Ex command in + a structured way before executing it, modify the result of + |nvim_parse_cmd()| then pass it to |nvim_cmd()|. Parameters: ~ • {command} Ex command string @@ -2161,12 +2117,12 @@ nvim_buf_call({buffer}, {fun}) *nvim_buf_call()* This temporarily switches current buffer to "buffer". If the current window already shows "buffer", the window is not switched. If a window inside the current tabpage (including a float) already shows the buffer, - then one of these windows will be set as current window temporarily. + then one of those windows will be set as current window temporarily. Otherwise a temporary scratch window (called the "autocmd window" for historical reasons) will be used. This is useful e.g. to call Vimscript functions that only work with the - current buffer/window currently, like |termopen()|. + current buffer/window currently, like `jobstart(…, {'term': v:true})`. Attributes: ~ Lua |vim.api| only @@ -2507,42 +2463,6 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* ============================================================================== Extmark Functions *api-extmark* - *nvim_buf_add_highlight()* -nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line}, {col_start}, - {col_end}) - Adds a highlight to buffer. - - Useful for plugins that dynamically generate highlights to a buffer (like - a semantic highlighter or linter). The function adds a single highlight to - a buffer. Unlike |matchaddpos()| highlights follow changes to line - numbering (as lines are inserted/removed above the highlighted line), like - signs and marks do. - - Namespaces are used for batch deletion/updating of a set of highlights. To - create a namespace, use |nvim_create_namespace()| which returns a - namespace id. Pass it in to this function as `ns_id` to add highlights to - the namespace. All highlights in the same namespace can then be cleared - with single call to |nvim_buf_clear_namespace()|. If the highlight never - will be deleted by an API call, pass `ns_id = -1`. - - As a shorthand, `ns_id = 0` can be used to create a new namespace for the - highlight, the allocated id is then returned. If `hl_group` is the empty - string no highlight is added, but a new `ns_id` is still returned. This is - supported for backwards compatibility, new code should use - |nvim_create_namespace()| to create a new empty namespace. - - Parameters: ~ - • {buffer} Buffer handle, or 0 for current buffer - • {ns_id} namespace to use or -1 for ungrouped highlight - • {hl_group} Name of the highlight group to use - • {line} Line to highlight (zero-indexed) - • {col_start} Start of (byte-indexed) column range to highlight - • {col_end} End of (byte-indexed) column range to highlight, or -1 to - highlight to end of line - - Return: ~ - The ns_id that was used - *nvim_buf_clear_namespace()* nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) Clears |namespace|d objects (highlights, |extmarks|, virtual text) from a @@ -2676,6 +2596,8 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) and below highlight groups can be supplied either as a string or as an integer, the latter of which can be obtained using |nvim_get_hl_id_by_name()|. + Multiple highlight groups can be stacked by passing an + array (highest priority last). • hl_eol : when true, for a multiline highlight covering the EOL of a line, continue the highlight for the rest of the screen line (just like for diff and cursorline highlight). @@ -2687,6 +2609,13 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) last). • virt_text_pos : position of virtual text. Possible values: • "eol": right after eol character (default). + • "eol_right_align": display right aligned in the window + unless the virtual text is longer than the space + available. If the virtual text is too long, it is + truncated to fit in the window after the EOL character. + If the line is wrapped, the virtual text is shown after + the end of the line rather than the previous screen + line. • "overlay": display over the specified column, without shifting the underlying text. • "right_align": display right aligned in the window. @@ -2780,7 +2709,7 @@ nvim_create_namespace({name}) *nvim_create_namespace()* Creates a new namespace or gets an existing one. *namespace* Namespaces are used for buffer highlights and virtual text, see - |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|. + |nvim_buf_set_extmark()|. Namespaces can be named or anonymous. If `name` matches an existing namespace, the associated id is returned. If `name` is an empty string a @@ -2838,8 +2767,8 @@ nvim_set_decoration_provider({ns_id}, {opts}) • on_start: called first on each screen redraw > ["start", tick] < - • on_buf: called for each buffer being redrawn (before window - callbacks) > + • on_buf: called for each buffer being redrawn (once per + edit, before window callbacks) > ["buf", bufnr, tick] < • on_win: called when starting to redraw a specific window. > @@ -3166,11 +3095,13 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* • {config} Map defining the window configuration. Keys: • relative: Sets the window layout to "floating", placed at (row,col) coordinates relative to: - • "editor" The global editor grid + • "cursor" Cursor position in current window. + • "editor" The global editor grid. + • "laststatus" 'laststatus' if present, or last row. + • "mouse" Mouse position. + • "tabline" Tabline if present, or first row. • "win" Window given by the `win` field, or current window. - • "cursor" Cursor position in current window. - • "mouse" Mouse position • win: |window-ID| window to split, or relative window when creating a float (relative="win"). • anchor: Decides which corner of the float to place at @@ -3483,9 +3414,9 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* • event: (string) name of the triggered event |autocmd-events| • group: (number|nil) autocommand group id, if any - • match: (string) expanded value of <amatch> - • buf: (number) expanded value of <abuf> - • file: (string) expanded value of <afile> + • file: (string) <afile> (not expanded to a full path) + • match: (string) <amatch> (expanded to a full path) + • buf: (number) <abuf> • data: (any) arbitrary data passed from |nvim_exec_autocmds()| *event-data* • command (string) optional: Vim command to execute on event. @@ -3580,33 +3511,35 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()* Parameters: ~ • {opts} Dict with at least one of the following: - • group (string|integer): the autocommand group name or id to - match against. - • event (string|array): event or events to match against + • buffer: (integer) Buffer number or list of buffer numbers + for buffer local autocommands |autocmd-buflocal|. Cannot be + used with {pattern} + • event: (string|table) event or events to match against |autocmd-events|. - • pattern (string|array): pattern or patterns to match against + • id: (integer) Autocommand ID to match. + • group: (string|table) the autocommand group name or id to + match against. + • pattern: (string|table) pattern or patterns to match against |autocmd-pattern|. Cannot be used with {buffer} - • buffer: Buffer number or list of buffer numbers for buffer - local autocommands |autocmd-buflocal|. Cannot be used with - {pattern} Return: ~ Array of autocommands matching the criteria, with each item containing the following fields: - • id (number): the autocommand id (only when defined with the API). - • group (integer): the autocommand group id. - • group_name (string): the autocommand group name. - • desc (string): the autocommand description. - • event (string): the autocommand event. - • command (string): the autocommand command. Note: this will be empty + • buffer: (integer) the buffer number. + • buflocal: (boolean) true if the autocommand is buffer local. + • command: (string) the autocommand command. Note: this will be empty if a callback is set. - • callback (function|string|nil): Lua function or name of a Vim script - function which is executed when this autocommand is triggered. - • once (boolean): whether the autocommand is only run once. - • pattern (string): the autocommand pattern. If the autocommand is + • callback: (function|string|nil): Lua function or name of a Vim + script function which is executed when this autocommand is + triggered. + • desc: (string) the autocommand description. + • event: (string) the autocommand event. + • id: (integer) the autocommand id (only when defined with the API). + • group: (integer) the autocommand group id. + • group_name: (string) the autocommand group name. + • once: (boolean) whether the autocommand is only run once. + • pattern: (string) the autocommand pattern. If the autocommand is buffer local |autocmd-buffer-local|: - • buflocal (boolean): true if the autocommand is buffer local. - • buffer (number): the buffer number. ============================================================================== diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 998ef5e9f3..c094281154 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -463,6 +463,10 @@ CompleteDone After Insert mode completion is done. Either |v:completed_item| gives the completed item. Sets these |v:event| keys: + complete_word The word that was + selected, empty if + abandoned complete. + complete_type |complete_info_mode| reason Reason for completion being done. Can be one of: - "accept": completion was diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index ada3b7103c..96574e2899 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -1174,16 +1174,22 @@ complete_info([{what}]) *complete_info()* See |complete_info_mode| for the values. pum_visible |TRUE| if popup menu is visible. See |pumvisible()|. - items List of completion matches. Each item is a - dictionary containing the entries "word", + items List of all completion candidates. Each item + is a dictionary containing the entries "word", "abbr", "menu", "kind", "info" and "user_data". See |complete-items|. + matches Same as "items", but only returns items that + are matching current query. If both "matches" + and "items" are in "what", the returned list + will still be named "items", but each item + will have an additional "match" field. selected Selected item index. First index is zero. Index is -1 if no item is selected (showing typed text only, or the last completion after no item is selected when using the <Up> or <Down> keys) - inserted Inserted string. [NOT IMPLEMENTED YET] + completed Return a dictionary containing the entries of + the currently selected index item. preview_winid Info floating preview window id. preview_bufnr Info floating preview buffer id. @@ -1305,10 +1311,10 @@ copy({expr}) *copy()* Also see |deepcopy()|. Parameters: ~ - • {expr} (`any`) + • {expr} (`T`) Return: ~ - (`any`) + (`T`) cos({expr}) *cos()* Return the cosine of {expr}, measured in radians, as a |Float|. @@ -1407,7 +1413,7 @@ ctxset({context} [, {index}]) *ctxset()* • {index} (`integer?`) Return: ~ - (`any`) + (`integer`) ctxsize() *ctxsize()* Returns the size of the |context-stack|. @@ -1490,11 +1496,11 @@ deepcopy({expr} [, {noref}]) *deepcopy()* *E69 Also see |copy()|. Parameters: ~ - • {expr} (`any`) + • {expr} (`T`) • {noref} (`boolean?`) Return: ~ - (`any`) + (`T`) delete({fname} [, {flags}]) *delete()* Without {flags} or with {flags} empty: Deletes the file by the @@ -1618,7 +1624,7 @@ did_filetype() *did_filetype()* file. Return: ~ - (`any`) + (`integer`) diff_filler({lnum}) *diff_filler()* Returns the number of filler lines above line {lnum}. @@ -1633,7 +1639,7 @@ diff_filler({lnum}) *diff_filler()* • {lnum} (`integer`) Return: ~ - (`any`) + (`integer`) diff_hlID({lnum}, {col}) *diff_hlID()* Returns the highlight ID for diff mode at line {lnum} column @@ -1674,7 +1680,7 @@ digraph_get({chars}) *digraph_get()* *E121 • {chars} (`string`) Return: ~ - (`any`) + (`string`) digraph_getlist([{listall}]) *digraph_getlist()* Return a list of digraphs. If the {listall} argument is given @@ -1695,7 +1701,7 @@ digraph_getlist([{listall}]) *digraph_getlist()* • {listall} (`boolean?`) Return: ~ - (`any`) + (`string[][]`) digraph_set({chars}, {digraph}) *digraph_set()* Add digraph {chars} to the list. {chars} must be a string @@ -1756,7 +1762,7 @@ empty({expr}) *empty()* • {expr} (`any`) Return: ~ - (`any`) + (`integer`) environ() *environ()* Return all of environment variables as dictionary. You can @@ -1783,7 +1789,7 @@ escape({string}, {chars}) *escape()* • {chars} (`string`) Return: ~ - (`any`) + (`string`) eval({string}) *eval()* Evaluate {string} and return the result. Especially useful to @@ -2666,7 +2672,7 @@ foreach({expr1}, {expr2}) *foreach()* • {expr2} (`string|function`) Return: ~ - (`any`) + (`string|table`) fullcommand({name}) *fullcommand()* Get the full command name from a short abbreviated command @@ -2997,10 +3003,10 @@ getbufline({buf}, {lnum} [, {end}]) *getbufline()* Parameters: ~ • {buf} (`integer|string`) • {lnum} (`integer`) - • {end_} (`integer?`) + • {end} (`integer?`) Return: ~ - (`any`) + (`string[]`) getbufoneline({buf}, {lnum}) *getbufoneline()* Just like `getbufline()` but only get one line and return it @@ -3073,14 +3079,16 @@ getchangelist([{buf}]) *getchangelist()* Return: ~ (`table[]`) -getchar([{expr}]) *getchar()* +getchar([{expr} [, {opts}]]) *getchar()* Get a single character from the user or input stream. - If {expr} is omitted, wait until a character is available. + If {expr} is omitted or is -1, 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 not consumed. Return zero if no character available. - If you prefer always getting a string use |getcharstr()|. + If you prefer always getting a string use |getcharstr()|, or + specify |FALSE| as "number" in {opts}. Without {expr} and when {expr} is 0 a whole character or special key is returned. If it is a single character, the @@ -3090,7 +3098,8 @@ getchar([{expr}]) *getchar()* starting with 0x80 (decimal: 128). This is the same value as the String "\<Key>", e.g., "\<Left>". The returned value is also a String when a modifier (shift, control, alt) was used - that is not included in the character. + that is not included in the character. |keytrans()| can also + be used to convert a returned String into a readable form. 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 @@ -3102,6 +3111,32 @@ getchar([{expr}]) *getchar()* Use getcharmod() to obtain any additional modifiers. + The optional argument {opts} is a Dict and supports the + following items: + + cursor A String specifying cursor behavior + when waiting for a character. + "hide": hide the cursor. + "keep": keep current cursor unchanged. + "msg": move cursor to message area. + (default: automagically decide + between "keep" and "msg") + + number If |TRUE|, return a Number when getting + a single character. + If |FALSE|, the return value is always + converted to a String, and an empty + String (instead of 0) is returned when + no character is available. + (default: |TRUE|) + + simplify If |TRUE|, include modifiers in the + character if possible. E.g., return + the same value for CTRL-I and <Tab>. + If |FALSE|, don't include modifiers in + the character. + (default: |TRUE|) + When the user clicks a mouse button, the mouse event will be returned. The position can then be found in |v:mouse_col|, |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. @@ -3139,10 +3174,11 @@ getchar([{expr}]) *getchar()* < Parameters: ~ - • {expr} (`0|1?`) + • {expr} (`-1|0|1?`) + • {opts} (`table?`) Return: ~ - (`integer`) + (`integer|string`) getcharmod() *getcharmod()* The result is a Number which is the state of the modifiers for @@ -3207,19 +3243,12 @@ getcharsearch() *getcharsearch()* (`table`) 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 - available. Return an empty string otherwise. - 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 - result is converted to a string. + The same as |getchar()|, except that this always returns a + String, and "number" isn't allowed in {opts}. Parameters: ~ - • {expr} (`0|1?`) + • {expr} (`-1|0|1?`) + • {opts} (`table?`) Return: ~ (`string`) @@ -3295,7 +3324,7 @@ getcmdscreenpos() *getcmdscreenpos()* |setcmdline()|. Return: ~ - (`any`) + (`integer`) getcmdtype() *getcmdtype()* Return the current command-line type. Possible return values @@ -3635,7 +3664,7 @@ getline({lnum} [, {end}]) *getline()* Parameters: ~ • {lnum} (`integer|string`) - • {end_} (`nil|false?`) + • {end} (`nil|false?`) Return: ~ (`string`) @@ -4177,6 +4206,21 @@ getscriptinfo([{opts}]) *getscriptinfo()* Return: ~ (`vim.fn.getscriptinfo.ret[]`) +getstacktrace() *getstacktrace()* + Returns the current stack trace of Vim scripts. + Stack trace is a |List|, of which each item is a |Dictionary| + with the following items: + funcref The funcref if the stack is at a function, + otherwise this item is omitted. + event The string of the event description if the + stack is at an autocmd event, otherwise this + item is omitted. + lnum The line number in the script on the stack. + filepath The file path of the script on the stack. + + Return: ~ + (`table[]`) + gettabinfo([{tabnr}]) *gettabinfo()* If {tabnr} is not specified, then information about all the tab pages is returned as a |List|. Each List item is a @@ -4299,7 +4343,7 @@ gettext({text}) *gettext()* • {text} (`string`) Return: ~ - (`any`) + (`string`) getwininfo([{winid}]) *getwininfo()* Returns information about windows as a |List| with Dictionaries. @@ -4315,6 +4359,8 @@ getwininfo([{winid}]) *getwininfo()* botline last complete displayed buffer line bufnr number of buffer in the window height window height (excluding winbar) + leftcol first column displayed; only used when + 'wrap' is off loclist 1 if showing a location list quickfix 1 if quickfix or location list window terminal 1 if a terminal window @@ -4465,7 +4511,7 @@ glob2regpat({string}) *glob2regpat()* • {string} (`string`) Return: ~ - (`any`) + (`string`) globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]]) *globpath()* Perform glob() for String {expr} on all directories in {path} @@ -4822,7 +4868,7 @@ iconv({string}, {from}, {to}) *iconv()* • {to} (`string`) Return: ~ - (`any`) + (`string`) id({expr}) *id()* Returns a |String| which is a unique identifier of the @@ -4845,7 +4891,7 @@ id({expr}) *id()* • {expr} (`any`) Return: ~ - (`any`) + (`string`) indent({lnum}) *indent()* The result is a Number, which is indent of line {lnum} in the @@ -4895,7 +4941,7 @@ index({object}, {expr} [, {start} [, {ic}]]) *index()* • {ic} (`boolean?`) Return: ~ - (`any`) + (`integer`) indexof({object}, {expr} [, {opts}]) *indexof()* Returns the index of an item in {object} where {expr} is @@ -4942,7 +4988,7 @@ indexof({object}, {expr} [, {opts}]) *indexof()* • {opts} (`table?`) Return: ~ - (`any`) + (`integer`) input({prompt} [, {text} [, {completion}]]) *input()* @@ -4952,7 +4998,7 @@ input({prompt} [, {text} [, {completion}]]) *input()* • {completion} (`string?`) Return: ~ - (`any`) + (`string`) input({opts}) The result is a String, which is whatever the user typed on @@ -5069,7 +5115,7 @@ input({opts}) • {opts} (`table`) Return: ~ - (`any`) + (`string`) inputlist({textlist}) *inputlist()* {textlist} must be a |List| of strings. This |List| is @@ -5101,7 +5147,7 @@ inputrestore() *inputrestore()* Returns TRUE when there is nothing to restore, FALSE otherwise. Return: ~ - (`any`) + (`integer`) inputsave() *inputsave()* Preserve typeahead (also from mappings) and clear it, so that @@ -5112,7 +5158,7 @@ inputsave() *inputsave()* Returns TRUE when out of memory, FALSE otherwise. Return: ~ - (`any`) + (`integer`) inputsecret({prompt} [, {text}]) *inputsecret()* This function acts much like the |input()| function with but @@ -5130,7 +5176,7 @@ inputsecret({prompt} [, {text}]) *inputsecret()* • {text} (`string?`) Return: ~ - (`any`) + (`string`) insert({object}, {item} [, {idx}]) *insert()* When {object} is a |List| or a |Blob| insert {item} at the start @@ -5181,10 +5227,10 @@ invert({expr}) *invert()* < Parameters: ~ - • {expr} (`number`) + • {expr} (`integer`) Return: ~ - (`any`) + (`integer`) isabsolutepath({path}) *isabsolutepath()* The result is a Number, which is |TRUE| when {path} is an @@ -5279,7 +5325,7 @@ items({dict}) *items()* the index. Parameters: ~ - • {dict} (`any`) + • {dict} (`table`) Return: ~ (`any`) @@ -5307,7 +5353,7 @@ jobresize({job}, {width}, {height}) *jobresize()* (`any`) jobstart({cmd} [, {opts}]) *jobstart()* - Note: Prefer |vim.system()| in Lua (unless using the `pty` option). + Note: Prefer |vim.system()| in Lua (unless using `rpc`, `pty`, or `term`). Spawns {cmd} as a job. If {cmd} is a List it runs directly (no 'shell'). @@ -5315,8 +5361,11 @@ jobstart({cmd} [, {opts}]) *jobstart()* call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) < (See |shell-unquoting| for details.) - Example: >vim - call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}}) + Example: start a job and handle its output: >vim + call jobstart(['nvim', '-h'], {'on_stdout':{j,d,e->append(line('.'),d)}}) +< + Example: start a job in a |terminal| connected to the current buffer: >vim + call jobstart(['nvim', '-h'], {'term':v:true}) < Returns |job-id| on success, 0 on invalid arguments (or job table is full), -1 if {cmd}[0] or 'shell' is not executable. @@ -5381,6 +5430,10 @@ jobstart({cmd} [, {opts}]) *jobstart()* stdin: (string) Either "pipe" (default) to connect the job's stdin to a channel or "null" to disconnect stdin. + term: (boolean) Spawns {cmd} in a new pseudo-terminal session + connected to the current (unmodified) buffer. Implies "pty". + Default "height" and "width" are set to the current window + dimensions. |jobstart()|. Defaults $TERM to "xterm-256color". width: (number) Width of the `pty` terminal. {opts} is passed as |self| dictionary to the callback; the @@ -5397,7 +5450,7 @@ jobstart({cmd} [, {opts}]) *jobstart()* • {opts} (`table?`) Return: ~ - (`any`) + (`integer`) jobstop({id}) *jobstop()* Stop |job-id| {id} by sending SIGTERM to the job process. If @@ -5413,7 +5466,7 @@ jobstop({id}) *jobstop()* • {id} (`integer`) Return: ~ - (`any`) + (`integer`) jobwait({jobs} [, {timeout}]) *jobwait()* Waits for jobs and their |on_exit| handlers to complete. @@ -5441,7 +5494,7 @@ jobwait({jobs} [, {timeout}]) *jobwait()* • {timeout} (`integer?`) Return: ~ - (`any`) + (`integer[]`) join({list} [, {sep}]) *join()* Join the items in {list} together into one String. @@ -5459,7 +5512,7 @@ join({list} [, {sep}]) *join()* • {sep} (`string?`) Return: ~ - (`any`) + (`string`) json_decode({expr}) *json_decode()* Convert {expr} from JSON object. Accepts |readfile()|-style @@ -5498,7 +5551,7 @@ json_encode({expr}) *json_encode()* • {expr} (`any`) Return: ~ - (`any`) + (`string`) keys({dict}) *keys()* Return a |List| with all the keys of {dict}. The |List| is in @@ -5508,7 +5561,7 @@ keys({dict}) *keys()* • {dict} (`table`) Return: ~ - (`any`) + (`string[]`) keytrans({string}) *keytrans()* Turn the internal byte representation of keys into a form that @@ -5521,7 +5574,7 @@ keytrans({string}) *keytrans()* • {string} (`string`) Return: ~ - (`any`) + (`string`) len({expr}) *len()* *E701* The result is a Number, which is the length of the argument. @@ -5535,10 +5588,10 @@ len({expr}) *len()* *E70 Otherwise an error is given and returns zero. Parameters: ~ - • {expr} (`any`) + • {expr} (`any[]`) Return: ~ - (`any`) + (`integer`) libcall({libname}, {funcname}, {argument}) *libcall()* *E364* *E368* Call function {funcname} in the run-time library {libname} @@ -5664,7 +5717,7 @@ lispindent({lnum}) *lispindent()* • {lnum} (`integer`) Return: ~ - (`any`) + (`integer`) list2blob({list}) *list2blob()* Return a Blob concatenating all the number values in {list}. @@ -5680,7 +5733,7 @@ list2blob({list}) *list2blob()* • {list} (`any[]`) Return: ~ - (`any`) + (`string`) list2str({list} [, {utf8}]) *list2str()* Convert each number in {list} to a character string can @@ -5703,14 +5756,14 @@ list2str({list} [, {utf8}]) *list2str()* • {utf8} (`boolean?`) Return: ~ - (`any`) + (`string`) localtime() *localtime()* Return the current time, measured as seconds since 1st Jan 1970. See also |strftime()|, |strptime()| and |getftime()|. Return: ~ - (`any`) + (`integer`) log({expr}) *log()* Return the natural logarithm (base e) of {expr} as a |Float|. @@ -5727,7 +5780,7 @@ log({expr}) *log()* • {expr} (`number`) Return: ~ - (`any`) + (`number`) log10({expr}) *log10()* Return the logarithm of Float {expr} to base 10 as a |Float|. @@ -5743,7 +5796,7 @@ log10({expr}) *log10()* • {expr} (`number`) Return: ~ - (`any`) + (`number`) luaeval({expr} [, {expr}]) *luaeval()* Evaluate Lua expression {expr} and return its result converted @@ -6290,7 +6343,7 @@ matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}]) *matchbufline()* • {buf} (`string|integer`) • {pat} (`string`) • {lnum} (`string|integer`) - • {end_} (`string|integer`) + • {end} (`string|integer`) • {dict} (`table?`) Return: ~ @@ -6565,7 +6618,7 @@ max({expr}) *max()* • {expr} (`any`) Return: ~ - (`any`) + (`number`) menu_get({path} [, {modes}]) *menu_get()* Returns a |List| of |Dictionaries| describing |menus| (defined @@ -6712,7 +6765,7 @@ min({expr}) *min()* • {expr} (`any`) Return: ~ - (`any`) + (`number`) mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739* Create directory {name}. @@ -6760,7 +6813,7 @@ mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E73 • {prot} (`string?`) Return: ~ - (`any`) + (`integer`) mode([{expr}]) *mode()* Return a string that indicates the current mode. @@ -6935,7 +6988,7 @@ nextnonblank({lnum}) *nextnonblank()* • {lnum} (`integer`) Return: ~ - (`any`) + (`integer`) nr2char({expr} [, {utf8}]) *nr2char()* Return a string with a single character, which has the number @@ -6957,7 +7010,7 @@ nr2char({expr} [, {utf8}]) *nr2char()* • {utf8} (`boolean?`) Return: ~ - (`any`) + (`string`) nvim_...({...}) *nvim_...()* *E5555* *eval-api* Call nvim |api| functions. The type checking of arguments will @@ -7014,7 +7067,7 @@ pathshorten({path} [, {len}]) *pathshorten()* • {len} (`integer?`) Return: ~ - (`any`) + (`string`) perleval({expr}) *perleval()* Evaluate |perl| expression {expr} and return its result @@ -7054,7 +7107,7 @@ pow({x}, {y}) *pow()* • {y} (`number`) Return: ~ - (`any`) + (`number`) prevnonblank({lnum}) *prevnonblank()* Return the line number of the first line at or above {lnum} @@ -7069,7 +7122,7 @@ prevnonblank({lnum}) *prevnonblank()* • {lnum} (`integer`) Return: ~ - (`any`) + (`integer`) printf({fmt}, {expr1} ...) *printf()* Return a String with {fmt}, where "%" items are replaced by @@ -7731,11 +7784,11 @@ reduce({object}, {func} [, {initial}]) *reduce()* *E99 Parameters: ~ • {object} (`any`) - • {func} (`function`) + • {func} (`fun(accumulator: T, current: any): any`) • {initial} (`any?`) Return: ~ - (`any`) + (`T`) reg_executing() *reg_executing()* Returns the single letter name of the register being executed. @@ -7784,7 +7837,7 @@ reltime({start}, {end}) Parameters: ~ • {start} (`any?`) - • {end_} (`any?`) + • {end} (`any?`) Return: ~ (`any`) @@ -7845,7 +7898,7 @@ remove({list}, {idx}, {end}) Parameters: ~ • {list} (`any[]`) • {idx} (`integer`) - • {end_} (`integer?`) + • {end} (`integer?`) Return: ~ (`any`) @@ -7867,7 +7920,7 @@ remove({blob}, {idx}, {end}) Parameters: ~ • {blob} (`any`) • {idx} (`integer`) - • {end_} (`integer?`) + • {end} (`integer?`) Return: ~ (`any`) @@ -7899,7 +7952,7 @@ rename({from}, {to}) *rename()* • {to} (`string`) Return: ~ - (`any`) + (`integer`) repeat({expr}, {count}) *repeat()* Repeat {expr} {count} times and return the concatenated @@ -7935,7 +7988,7 @@ resolve({filename}) *resolve()* *E65 • {filename} (`string`) Return: ~ - (`any`) + (`string`) reverse({object}) *reverse()* Reverse the order of items in {object}. {object} can be a @@ -7949,10 +8002,10 @@ reverse({object}) *reverse()* < Parameters: ~ - • {object} (`any`) + • {object} (`T[]`) Return: ~ - (`any`) + (`T[]`) round({expr}) *round()* Round off {expr} to the nearest integral value and return it @@ -7972,7 +8025,7 @@ round({expr}) *round()* • {expr} (`number`) Return: ~ - (`any`) + (`number`) rpcnotify({channel}, {event} [, {args}...]) *rpcnotify()* Sends {event} to {channel} via |RPC| and returns immediately. @@ -7984,10 +8037,10 @@ rpcnotify({channel}, {event} [, {args}...]) *rpcnotify()* Parameters: ~ • {channel} (`integer`) • {event} (`string`) - • {args} (`any?`) + • {...} (`any`) Return: ~ - (`any`) + (`integer`) rpcrequest({channel}, {method} [, {args}...]) *rpcrequest()* Sends a request to {channel} to invoke {method} via @@ -7999,7 +8052,7 @@ rpcrequest({channel}, {method} [, {args}...]) *rpcrequest()* Parameters: ~ • {channel} (`integer`) • {method} (`string`) - • {args} (`any?`) + • {...} (`any`) Return: ~ (`any`) @@ -8031,7 +8084,7 @@ screenattr({row}, {col}) *screenattr()* • {col} (`integer`) Return: ~ - (`any`) + (`integer`) screenchar({row}, {col}) *screenchar()* The result is a Number, which is the character at position @@ -8048,7 +8101,7 @@ screenchar({row}, {col}) *screenchar()* • {col} (`integer`) Return: ~ - (`any`) + (`integer`) screenchars({row}, {col}) *screenchars()* The result is a |List| of Numbers. The first number is the same @@ -8062,7 +8115,7 @@ screenchars({row}, {col}) *screenchars()* • {col} (`integer`) Return: ~ - (`any`) + (`integer[]`) screencol() *screencol()* The result is a Number, which is the current screen column of @@ -8080,7 +8133,7 @@ screencol() *screencol()* < Return: ~ - (`any`) + (`integer[]`) screenpos({winid}, {lnum}, {col}) *screenpos()* The result is a Dict with the screen position of the text @@ -8123,7 +8176,7 @@ screenrow() *screenrow()* Note: Same restrictions as with |screencol()|. Return: ~ - (`any`) + (`integer`) screenstring({row}, {col}) *screenstring()* The result is a String that contains the base character and @@ -8138,7 +8191,7 @@ screenstring({row}, {col}) *screenstring()* • {col} (`integer`) Return: ~ - (`any`) + (`string`) search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) *search()* Search for regexp pattern {pattern}. The search starts at the @@ -8253,7 +8306,7 @@ search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) *search()* • {skip} (`string|function?`) Return: ~ - (`any`) + (`integer`) searchcount([{options}]) *searchcount()* Get or update the last search count, like what is displayed @@ -8498,7 +8551,7 @@ searchpair({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline} [, {timeo Parameters: ~ • {start} (`string`) • {middle} (`string`) - • {end_} (`string`) + • {end} (`string`) • {flags} (`string?`) • {skip} (`string|function?`) • {stopline} (`integer?`) @@ -8522,7 +8575,7 @@ searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline} [, {ti Parameters: ~ • {start} (`string`) • {middle} (`string`) - • {end_} (`string`) + • {end} (`string`) • {flags} (`string?`) • {skip} (`string|function?`) • {stopline} (`integer?`) @@ -8565,7 +8618,7 @@ serverlist() *serverlist()* < Return: ~ - (`any`) + (`string[]`) serverstart([{address}]) *serverstart()* Opens a socket or named pipe at {address} and listens for @@ -8605,7 +8658,7 @@ serverstart([{address}]) *serverstart()* • {address} (`string?`) Return: ~ - (`any`) + (`string`) serverstop({address}) *serverstop()* Closes the pipe or socket at {address}. @@ -8617,7 +8670,7 @@ serverstop({address}) *serverstop()* • {address} (`string`) Return: ~ - (`any`) + (`integer`) setbufline({buf}, {lnum}, {text}) *setbufline()* Set line {lnum} to {text} in buffer {buf}. This works like @@ -8650,7 +8703,7 @@ setbufline({buf}, {lnum}, {text}) *setbufline()* • {text} (`string|string[]`) Return: ~ - (`any`) + (`integer`) setbufvar({buf}, {varname}, {val}) *setbufvar()* Set option or local variable {varname} in buffer {buf} to @@ -8770,7 +8823,7 @@ setcmdline({str} [, {pos}]) *setcmdline()* • {pos} (`integer?`) Return: ~ - (`any`) + (`integer`) setcmdpos({pos}) *setcmdpos()* Set the cursor position in the command line to byte position @@ -9102,7 +9155,7 @@ setqflist({list} [, {action} [, {what}]]) *setqflist()* • {what} (`vim.fn.setqflist.what?`) Return: ~ - (`any`) + (`integer`) setreg({regname}, {value} [, {options}]) *setreg()* Set the register {regname} to {value}. @@ -9273,7 +9326,7 @@ sha256({string}) *sha256()* • {string} (`string`) Return: ~ - (`any`) + (`string`) shellescape({string} [, {special}]) *shellescape()* Escape {string} for use as a shell command argument. @@ -9312,7 +9365,7 @@ shellescape({string} [, {special}]) *shellescape()* • {special} (`boolean?`) Return: ~ - (`any`) + (`string`) shiftwidth([{col}]) *shiftwidth()* Returns the effective value of 'shiftwidth'. This is the @@ -9790,7 +9843,7 @@ simplify({filename}) *simplify()* • {filename} (`string`) Return: ~ - (`any`) + (`string`) sin({expr}) *sin()* Return the sine of {expr}, measured in radians, as a |Float|. @@ -9806,7 +9859,7 @@ sin({expr}) *sin()* • {expr} (`number`) Return: ~ - (`any`) + (`number`) sinh({expr}) *sinh()* Return the hyperbolic sine of {expr} as a |Float| in the range @@ -9838,7 +9891,7 @@ slice({expr}, {start} [, {end}]) *slice()* Parameters: ~ • {expr} (`any`) • {start} (`integer`) - • {end_} (`integer?`) + • {end} (`integer?`) Return: ~ (`any`) @@ -9950,12 +10003,12 @@ sort({list} [, {how} [, {dict}]]) *sort()* *E70 < Parameters: ~ - • {list} (`any`) + • {list} (`T[]`) • {how} (`string|function?`) • {dict} (`any?`) Return: ~ - (`any`) + (`T[]`) soundfold({word}) *soundfold()* Return the sound-folded equivalent of {word}. Uses the first @@ -9969,7 +10022,7 @@ soundfold({word}) *soundfold()* • {word} (`string`) Return: ~ - (`any`) + (`string`) spellbadword([{sentence}]) *spellbadword()* Without argument: The result is the badly spelled word under @@ -10028,7 +10081,7 @@ spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()* • {capital} (`boolean?`) Return: ~ - (`any`) + (`string[]`) split({string} [, {pattern} [, {keepempty}]]) *split()* Make a |List| out of {string}. When {pattern} is omitted or @@ -10061,7 +10114,7 @@ split({string} [, {pattern} [, {keepempty}]]) *split()* • {keepempty} (`boolean?`) Return: ~ - (`any`) + (`string[]`) sqrt({expr}) *sqrt()* Return the non-negative square root of Float {expr} as a @@ -10232,6 +10285,7 @@ str2list({string} [, {utf8}]) *str2list()* and exists only for backwards-compatibility. With UTF-8 composing characters are handled properly: >vim echo str2list("á") " returns [97, 769] +< Parameters: ~ • {string} (`string`) @@ -11165,28 +11219,6 @@ tempname() *tempname()* Return: ~ (`string`) -termopen({cmd} [, {opts}]) *termopen()* - Spawns {cmd} in a new pseudo-terminal session connected - to the current (unmodified) buffer. Parameters and behavior - are the same as |jobstart()| except "pty", "width", "height", - and "TERM" are ignored: "height" and "width" are taken from - the current window. Note that termopen() implies a "pty" arg - to jobstart(), and thus has the implications documented at - |jobstart()|. - - Returns the same values as jobstart(). - - Terminal environment is initialized as in |jobstart-env|, - except $TERM is set to "xterm-256color". Full behavior is - described in |terminal|. - - Parameters: ~ - • {cmd} (`string|string[]`) - • {opts} (`table?`) - - Return: ~ - (`any`) - test_garbagecollect_now() *test_garbagecollect_now()* Like |garbagecollect()|, but executed right away. This must only be called directly to avoid any structure to exist @@ -11646,7 +11678,7 @@ virtcol2col({winid}, {lnum}, {col}) *virtcol2col()* • {col} (`integer`) Return: ~ - (`any`) + (`integer`) visualmode([{expr}]) *visualmode()* The result is a String, which describes the last Visual mode @@ -11670,7 +11702,7 @@ visualmode([{expr}]) *visualmode()* • {expr} (`boolean?`) Return: ~ - (`any`) + (`string`) wait({timeout}, {condition} [, {interval}]) *wait()* Waits until {condition} evaluates to |TRUE|, where {condition} @@ -11812,7 +11844,7 @@ win_id2win({expr}) *win_id2win()* • {expr} (`integer`) Return: ~ - (`any`) + (`integer`) win_move_separator({nr}, {offset}) *win_move_separator()* Move window {nr}'s vertical separator (i.e., the right border) @@ -11989,7 +12021,7 @@ winlayout([{tabnr}]) *winlayout()* • {tabnr} (`integer?`) Return: ~ - (`any`) + (`any[]`) winline() *winline()* The result is a Number, which is the screen line of the cursor @@ -12037,7 +12069,7 @@ winnr([{arg}]) *winnr()* • {arg} (`string|integer?`) Return: ~ - (`any`) + (`integer`) winrestcmd() *winrestcmd()* Returns a sequence of |:resize| commands that should restore @@ -12051,7 +12083,7 @@ winrestcmd() *winrestcmd()* < Return: ~ - (`any`) + (`string`) winrestview({dict}) *winrestview()* Uses the |Dictionary| returned by |winsaveview()| to restore @@ -12123,7 +12155,7 @@ winwidth({nr}) *winwidth()* • {nr} (`integer`) Return: ~ - (`any`) + (`integer`) wordcount() *wordcount()* The result is a dictionary of byte/chars/word statistics for @@ -12213,11 +12245,11 @@ xor({expr}, {expr}) *xor()* < Parameters: ~ - • {expr} (`number`) - • {expr1} (`number`) + • {expr} (`integer`) + • {expr1} (`integer`) Return: ~ - (`any`) + (`integer`) ============================================================================== 2. Matching a pattern in a String *string-match* diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index 768a449581..9e44f54e6b 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -1443,18 +1443,17 @@ since formatting is highly dependent on the type of file. It makes sense to use an |autoload| script, so the corresponding script is only loaded when actually needed and the script should be called <filetype>format.vim. -For example, the XML filetype plugin distributed with Vim in the $VIMRUNTIME -directory, sets the 'formatexpr' option to: > +For example, the XML filetype plugin distributed with Vim in the +$VIMRUNTIME/ftplugin directory, sets the 'formatexpr' option to: > setlocal formatexpr=xmlformat#Format() That means, you will find the corresponding script, defining the -xmlformat#Format() function, in the directory: -`$VIMRUNTIME/autoload/xmlformat.vim` +xmlformat#Format() function, in the file `$VIMRUNTIME/autoload/xmlformat.vim` Here is an example script that removes trailing whitespace from the selected -text. Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim: > - +text. Put it in your autoload directory, e.g. ~/.vim/autoload/format.vim: +>vim func! format#Format() " only reformat on explicit gq command if mode() != 'n' @@ -1487,7 +1486,7 @@ debugging it helps to set the 'debug' option. *right-justify* There is no command in Vim to right justify text. You can do it with -an external command, like "par" (e.g.: "!}par" to format until the end of the +an external command, like "par" (e.g.: `:.,}!par` to format until the end of the paragraph) or set 'formatprg' to "par". *format-comments* @@ -1553,7 +1552,7 @@ type of comment string. A part consists of: some indent for the start or end part that can be removed. When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the -comment string repeats at the start of each line. The flags field may be +comment string repeats at the start of each line. The {flags} field may be empty. Any blank space in the text before and after the {string} is part of the diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt index 7184151cda..c2d220041c 100644 --- a/runtime/doc/channel.txt +++ b/runtime/doc/channel.txt @@ -11,21 +11,20 @@ Nvim asynchronous IO *channel* ============================================================================== 1. Introduction *channel-intro* -Channels are nvim's way of communicating with external processes. +Channels are Nvim's way of communicating with external processes. There are several ways to open a channel: - 1. Through stdin/stdout when `nvim` is started with `--headless`, and a startup - script or --cmd command opens the stdio channel using |stdioopen()|. + 1. Through stdin/stdout when `nvim` is started with `--headless` and a startup + script or `--cmd` command opens the stdio channel using |stdioopen()|. 2. Through stdin, stdout and stderr of a process spawned by |jobstart()|. - 3. Through the PTY master end of a PTY opened with - `jobstart(..., {'pty': v:true})` or |termopen()|. + 3. Through the PTY master end opened with `jobstart(…, {'pty': v:true})`. 4. By connecting to a TCP/IP socket or named pipe with |sockconnect()|. - 5. By another process connecting to a socket listened to by nvim. This only + 5. By another process connecting to a socket listened to by Nvim. This only supports RPC channels, see |rpc-connecting|. Channels support multiple modes or protocols. In the most basic @@ -146,7 +145,7 @@ from the host TTY, or if Nvim is |--headless| it uses default values: >vim :echo system('nvim --headless +"te stty -a" +"sleep 1" +"1,/^$/print" +q') ============================================================================== -3. Communicating using msgpack-rpc *channel-rpc* +3. Communicating with msgpack RPC *channel-rpc* When channels are opened with the `rpc` option set to true, the channel can be used for remote method calls in both directions, see |msgpack-rpc|. Note that diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index 7967e2ce1a..3fc17af185 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -41,15 +41,19 @@ thus you cannot edit beyond that. The command-lines that you enter are remembered in a history table. You can recall them with the up and down cursor keys. There are actually five history tables: + - one for ':' commands - one for search strings - one for expressions - one for input lines, typed for the |input()| function. - one for debug mode commands + These are completely separate. Each history can only be accessed when entering the same type of line. Use the 'history' option to set the number of lines that are remembered. + Notes: + - When you enter a command-line that is exactly the same as an older one, the old one is removed (to avoid repeated commands moving older commands out of the history). @@ -1218,10 +1222,10 @@ Thus you can resize the command-line window, but not others. The |getcmdwintype()| function returns the type of the command-line being edited as described in |cmdwin-char|. -Nvim defines this default CmdWinEnter autocmd in the "nvim_cmdwin" group: > +Nvim defines this default CmdWinEnter autocmd in the "nvim.cmdwin" group: > autocmd CmdWinEnter [:>] syntax sync minlines=1 maxlines=1 < -You can disable this in your config with "autocmd! nvim_cmdwin". |default-autocmds| +You can disable this in your config with "autocmd! nvim.cmdwin". |default-autocmds| AUTOCOMMANDS diff --git a/runtime/doc/backers.txt b/runtime/doc/credits.txt index d0cbd94978..5fe79dfef8 100644 --- a/runtime/doc/backers.txt +++ b/runtime/doc/credits.txt @@ -1,11 +1,118 @@ -*backers.txt* Nvim +*credits.txt* Nvim NVIM REFERENCE MANUAL ============================================================================== -Fundraiser Backers +Credits *credits* + +Most of Vim was written by Bram Moolenaar <Bram@vim.org> |Bram-Moolenaar|. + +Parts of the documentation come from several Vi manuals, written by: + W.N. Joy + Alan P.W. Hewett + Mark Horton + +The Vim editor is based on Stevie and includes (ideas from) other software, +worked on by the people mentioned here. Other people helped by sending me +patches, suggestions and giving feedback about what is good and bad in Vim. + +Vim would never have become what it is now, without the help of these people! + + Ron Aaron Win32 GUI changes + Mohsin Ahmed encryption + Zoltan Arpadffy work on VMS port + Tony Andrews Stevie + Gert van Antwerpen changes for DJGPP on MS-DOS + Berkeley DB(3) ideas for swap file implementation + Keith Bostic Nvi + Walter Briscoe Makefile updates, various patches + Ralf Brown SPAWNO library for MS-DOS + Robert Colon many useful remarks + Marcin Dalecki GTK+ GUI port, toolbar icons, gettext() + Kayhan Demirel sent me news in Uganda + Chris & John Downey xvi (ideas for multi-windows version) + Henk Elbers first VMS port + Daniel Elstner GTK+ 2 port + Eric Fischer Mac port, 'cindent', and other improvements + Benji Fisher Answering lots of user questions + Bill Foster Athena GUI port (later removed) + Google Let Bram work on Vim one day a week + Loic Grenie xvim (ideas for multi windows version) + Sven Guckes Vim promoter and previous WWW page maintainer + Darren Hiebert Exuberant ctags + Jason Hildebrand GTK+ 2 port + Bruce Hunsaker improvements for VMS port + Andy Kahn Cscope support, GTK+ GUI port + Oezguer Kesim Maintainer of Vim Mailing Lists + Axel Kielhorn work on the Macintosh port + Steve Kirkendall Elvis + Roger Knobbe original port to Windows NT + Sergey Laskavy Vim's help from Moscow + Felix von Leitner Previous maintainer of Vim Mailing Lists + David Leonard Port of Python extensions to Unix + Avner Lottem Edit in right-to-left windows + Flemming Madsen X11 client-server, various features and patches + Tony Mechelynck answers many user questions + Paul Moore Python interface extensions, many patches + Katsuhito Nagano Work on multibyte versions + Sung-Hyun Nam Work on multibyte versions + Vince Negri Win32 GUI and generic console enhancements + Steve Oualline Author of the first Vim book |frombook| + Dominique Pelle Valgrind reports and many fixes + A.Politz Many bug reports and some fixes + George V. Reilly Win32 port, Win32 GUI start-off + Stephen Riehm bug collector + Stefan Roemer various patches and help to users + Ralf Schandl IBM OS/390 port + Olaf Seibert DICE and BeBox version, regexp improvements + Mortaza Shiran Farsi patches + Peter da Silva termlib + Paul Slootman OS/2 port + Henry Spencer regular expressions + Dany St-Amant Macintosh port + Tim Thompson Stevie + G. R. (Fred) Walter Stevie + Sven Verdoolaege Perl interface + Robert Webb Command-line completion, GUI versions, and + lots of patches + Ingo Wilken Tcl interface + Mike Williams PostScript printing + Juergen Weigert Lattice version, AUX improvements, Unix and + MS-DOS ports, autoconf + Stefan 'Sec' Zehl Maintainer of vim.org + Yasuhiro Matsumoto many MS-Windows improvements + Ken Takata fixes and features + Kazunobu Kuriyama GTK 3 + Christian Brabandt many fixes, features, user support, etc. + Yegappan Lakshmanan many quickfix features + +I wish to thank all the people that sent me bug reports and suggestions. The +list is too long to mention them all here. Vim would not be the same without +the ideas from all these people: They keep Vim alive! +*love* *peace* *friendship* *gross-national-happiness* + + +Documentation may refer to other versions of Vi: + *Vi* *vi* +Vi "the original". Without further remarks this is the version + of Vi that appeared in Sun OS 4.x. ":version" returns + "Version 3.7, 6/7/85". Source code only available with a license. + *Nvi* +Nvi The "New" Vi. The version of Vi that comes with BSD 4.4 and FreeBSD. + Very good compatibility with the original Vi, with a few extensions. + The version used is 1.79. ":version" returns "Version 1.79 + (10/23/96)". Source code is freely available. + *Elvis* +Elvis Another Vi clone, made by Steve Kirkendall. Very compact but isn't + as flexible as Vim. Source code is freely available. + +Vim Nvim is based on Vim. https://www.vim.org/ + + +============================================================================== +Neovim fundraiser backers *backers.txt* Thank you to everyone who backed the original Neovim Fundraiser. diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 5e809ad26c..68258fedb4 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -16,46 +16,57 @@ 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. - -LUA -- vim.region() Use |getregionpos()| instead. -- *vim.highlight* Renamed to |vim.hl|. -- vim.validate(opts: table) Use form 1. See |vim.validate()|. +• nvim_notify() Use |nvim_echo()| or `nvim_exec_lua("vim.notify(...)", ...)` instead. +• nvim_subscribe() Plugins must maintain their own "multicast" channels list. +• nvim_unsubscribe() Plugins must maintain their own "multicast" channels list. +• nvim_out_write() Use |nvim_echo()|. +• nvim_err_write() Use |nvim_echo()| with `{err=true}`. +• nvim_err_writeln() Use |nvim_echo()| with `{err=true}`. +• nvim_buf_add_highlight() Use |vim.hl.range()| or |nvim_buf_set_extmark()| DIAGNOSTICS -- *vim.diagnostic.goto_next()* Use |vim.diagnostic.jump()| with `{count=1, float=true}` instead. -- *vim.diagnostic.goto_prev()* Use |vim.diagnostic.jump()| with `{count=-1, float=true}` instead. -- *vim.diagnostic.get_next_pos()* - Use the "lnum" and "col" fields from the return value of - |vim.diagnostic.get_next()| instead. -- *vim.diagnostic.get_prev_pos()* - Use the "lnum" and "col" fields from the return value of - |vim.diagnostic.get_prev()| instead. -- The "win_id" parameter used by various functions is deprecated in favor of +• *vim.diagnostic.goto_next()* Use |vim.diagnostic.jump()| with `{count=1, float=true}` instead. +• *vim.diagnostic.goto_prev()* Use |vim.diagnostic.jump()| with `{count=-1, float=true}` instead. +• *vim.diagnostic.get_next_pos()* Use the "lnum" and "col" fields from the + return value of |vim.diagnostic.get_next()| instead. +• *vim.diagnostic.get_prev_pos()* Use the "lnum" and "col" fields from the + return value of |vim.diagnostic.get_prev()| instead. +• The "win_id" parameter used by various functions is deprecated in favor of "winid" |winid| -- The "cursor_position" parameter of |vim.diagnostic.JumpOpts| is renamed to - "pos" +• |vim.diagnostic.JumpOpts| renamed its "cursor_position" field to "pos". -TREESITTER -• *TSNode:child_containing_descendant()* Use - |TSNode:child_with_descendant()| instead; it is identical except that it can - return the descendant itself. +HIGHLIGHTS +• *TermCursorNC* Unfocused |terminal| windows do not have a cursor. LSP • *vim.lsp.util.jump_to_location* Use |vim.lsp.util.show_document()| with - `{focus=true}` instead. + `{focus=true}` instead. • *vim.lsp.buf.execute_command* Use |Client:exec_cmd()| instead. • *vim.lsp.buf.completion* Use |vim.lsp.completion.trigger()| instead. • vim.lsp.buf_request_all The `error` key has been renamed to `err` inside the result parameter of the handler. • *vim.lsp.with()* Pass configuration to equivalent - functions in `vim.lsp.buf.*'. -• |vim.lsp.handlers| - No longer support client to server response handlers. Only server to - client requests/notification handlers are supported. + functions in `vim.lsp.buf.*`. +• |vim.lsp.handlers| Does not support client-to-server response handlers. Only + supports server-to-client requests/notification handlers. • *vim.lsp.handlers.signature_help()* Use |vim.lsp.buf.signature_help()| instead. +• `client.request()` Use |Client:request()| instead. +• `client.request_sync()` Use |Client:request_sync()| instead. +• `client.notify()` Use |Client:notify()| instead. +• `client.cancel_request()` Use |Client:cancel_request()| instead. +• `client.stop()` Use |Client:stop()| instead. +• `client.is_stopped()` Use |Client:is_stopped()| instead. +• `client.supports_method()` Use |Client:supports_method()| instead. +• `client.on_attach()` Use |Client:on_attach()| instead. +• `vim.lsp.start_client()` Use |vim.lsp.start()| instead. + +LUA +• vim.region() Use |getregionpos()| instead. +• *vim.highlight* Renamed to |vim.hl|. +• vim.validate(opts: table) Use form 1. See |vim.validate()|. + +VIMSCRIPT +• *termopen()* Use |jobstart() with `{term: v:true}`. ------------------------------------------------------------------------------ DEPRECATED IN 0.10 *deprecated-0.10* @@ -117,198 +128,198 @@ TREESITTER 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. +• *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()| +• *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()| + • *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. + • *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_option_info()* Use |nvim_get_option_info2()| instead. +• *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_option_info()* Use |nvim_get_option_info2()| instead. COMMANDS -- *:rv* *:rviminfo* Deprecated alias to |:rshada| command. -- *:wv* *:wviminfo* Deprecated alias to |:wshada| command. +• *:rv* *:rviminfo* Deprecated alias to |:rshada| command. +• *:wv* *:wviminfo* Deprecated alias to |:wshada| command. ENVIRONMENT VARIABLES -- *$NVIM_LISTEN_ADDRESS* - - Deprecated way to: - - set the server name (use |--listen| or |serverstart()| instead) - - get the server name (use |v:servername| instead) - - detect a parent Nvim (use |$NVIM| instead) - - Ignored if --listen is given. - - Unset by |terminal| and |jobstart()| unless explicitly given by the "env" +• *$NVIM_LISTEN_ADDRESS* + • Deprecated way to: + • set the server name (use |--listen| or |serverstart()| instead) + • get the server name (use |v:servername| instead) + • detect a parent Nvim (use |$NVIM| instead) + • Ignored if --listen is given. + • Unset by |terminal| and |jobstart()| unless explicitly given by the "env" option. Example: >vim call jobstart(['foo'], { 'env': { 'NVIM_LISTEN_ADDRESS': v:servername } }) < EVENTS -- *BufCreate* Use |BufAdd| instead. -- *EncodingChanged* Never fired; 'encoding' is always "utf-8". -- *FileEncoding* Never fired; equivalent to |EncodingChanged|. -- *GUIEnter* Never fired; use |UIEnter| instead. -- *GUIFailed* Never fired. +• *BufCreate* Use |BufAdd| instead. +• *EncodingChanged* Never fired; 'encoding' is always "utf-8". +• *FileEncoding* Never fired; equivalent to |EncodingChanged|. +• *GUIEnter* Never fired; use |UIEnter| instead. +• *GUIFailed* Never fired. KEYCODES -- *<MouseDown>* Use <ScrollWheelUp> instead. -- *<MouseUp>* Use <ScrollWheelDown> instead. - -FUNCTIONS -- *buffer_exists()* Obsolete name for |bufexists()|. -- *buffer_name()* Obsolete name for |bufname()|. -- *buffer_number()* Obsolete name for |bufnr()|. -- *file_readable()* Obsolete name for |filereadable()|. -- *highlight_exists()* Obsolete name for |hlexists()|. -- *highlightID()* Obsolete name for |hlID()|. -- *inputdialog()* Use |input()| instead. -- *jobclose()* Obsolete name for |chanclose()| -- *jobsend()* Obsolete name for |chansend()| -- *last_buffer_nr()* Obsolete name for bufnr("$"). -- *rpcstart()* Use |jobstart()| with `{'rpc': v:true}` instead. -- *rpcstop()* Use |jobstop()| instead to stop any job, or - `chanclose(id, "rpc")` to close RPC communication - without stopping the job. Use chanclose(id) to close - any socket. +• *<MouseDown>* Use <ScrollWheelUp> instead. +• *<MouseUp>* Use <ScrollWheelDown> instead. HIGHLIGHTS -- *hl-VertSplit* Use |hl-WinSeparator| instead. +• *hl-VertSplit* Use |hl-WinSeparator| instead. LSP DIAGNOSTICS For each of the functions below, use the corresponding function in |vim.diagnostic| instead (unless otherwise noted). For example, use |vim.diagnostic.get()| instead of |vim.lsp.diagnostic.get()|. -- *vim.lsp.diagnostic.clear()* Use |vim.diagnostic.hide()| instead. -- *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()* -- *vim.lsp.diagnostic.get_all()* Use |vim.diagnostic.get()| instead. -- *vim.lsp.diagnostic.get_count()* Use |vim.diagnostic.count()| instead. -- *vim.lsp.diagnostic.get_line_diagnostics()* Use |vim.diagnostic.get()| instead. -- *vim.lsp.diagnostic.get_next()* -- *vim.lsp.diagnostic.get_next_pos()* -- *vim.lsp.diagnostic.get_prev()* -- *vim.lsp.diagnostic.get_prev_pos()* -- *vim.lsp.diagnostic.get_virtual_text_chunks_for_line()* No replacement. Use +• *vim.lsp.diagnostic.clear()* Use |vim.diagnostic.hide()| instead. +• *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()* +• *vim.lsp.diagnostic.get_all()* Use |vim.diagnostic.get()| instead. +• *vim.lsp.diagnostic.get_count()* Use |vim.diagnostic.count()| instead. +• *vim.lsp.diagnostic.get_line_diagnostics()* Use |vim.diagnostic.get()| instead. +• *vim.lsp.diagnostic.get_next()* +• *vim.lsp.diagnostic.get_next_pos()* +• *vim.lsp.diagnostic.get_prev()* +• *vim.lsp.diagnostic.get_prev_pos()* +• *vim.lsp.diagnostic.get_virtual_text_chunks_for_line()* No replacement. Use options provided by |vim.diagnostic.config()| to customize virtual text. -- *vim.lsp.diagnostic.goto_next()* -- *vim.lsp.diagnostic.goto_prev()* -- *vim.lsp.diagnostic.redraw()* Use |vim.diagnostic.show()| instead. -- *vim.lsp.diagnostic.reset()* -- *vim.lsp.diagnostic.save()* Use |vim.diagnostic.set()| instead. -- *vim.lsp.diagnostic.set_loclist()* Use |vim.diagnostic.setloclist()| instead. -- *vim.lsp.diagnostic.set_qflist()* Use |vim.diagnostic.setqflist()| instead. -- *vim.lsp.diagnostic.show_line_diagnostics()* Use |vim.diagnostic.open_float()| instead. -- *vim.lsp.diagnostic.show_position_diagnostics()* Use |vim.diagnostic.open_float()| instead. +• *vim.lsp.diagnostic.goto_next()* +• *vim.lsp.diagnostic.goto_prev()* +• *vim.lsp.diagnostic.redraw()* Use |vim.diagnostic.show()| instead. +• *vim.lsp.diagnostic.reset()* +• *vim.lsp.diagnostic.save()* Use |vim.diagnostic.set()| instead. +• *vim.lsp.diagnostic.set_loclist()* Use |vim.diagnostic.setloclist()| instead. +• *vim.lsp.diagnostic.set_qflist()* Use |vim.diagnostic.setqflist()| instead. +• *vim.lsp.diagnostic.show_line_diagnostics()* Use |vim.diagnostic.open_float()| instead. +• *vim.lsp.diagnostic.show_position_diagnostics()* Use |vim.diagnostic.open_float()| instead. The following are deprecated without replacement. These functions are moved internally and are no longer exposed as part of the API. Instead, use |vim.diagnostic.config()| and |vim.diagnostic.show()|. -- *vim.lsp.diagnostic.set_signs()* -- *vim.lsp.diagnostic.set_underline()* -- *vim.lsp.diagnostic.set_virtual_text()* +• *vim.lsp.diagnostic.set_signs()* +• *vim.lsp.diagnostic.set_underline()* +• *vim.lsp.diagnostic.set_virtual_text()* LSP FUNCTIONS -- *vim.lsp.buf.server_ready()* +• *vim.lsp.buf.server_ready()* Use |LspAttach| instead, depending on your use-case. "Server ready" is not part of the LSP spec, so the Nvim LSP client cannot meaningfully implement it. "Ready" is ambiguous because: - - Language servers may finish analyzing the workspace, but edits can always + • Language servers may finish analyzing the workspace, but edits can always re-trigger analysis/builds. - - Language servers can serve some requests even while processing changes. -- *vim.lsp.buf.range_code_action()* Use |vim.lsp.buf.code_action()| with + • Language servers can serve some requests even while processing changes. +• *vim.lsp.buf.range_code_action()* Use |vim.lsp.buf.code_action()| with the `range` parameter. -- *vim.lsp.util.diagnostics_to_items()* Use |vim.diagnostic.toqflist()| instead. -- *vim.lsp.util.set_qflist()* Use |setqflist()| instead. -- *vim.lsp.util.set_loclist()* Use |setloclist()| instead. -- *vim.lsp.buf_get_clients()* Use |vim.lsp.get_clients()| with +• *vim.lsp.util.diagnostics_to_items()* Use |vim.diagnostic.toqflist()| instead. +• *vim.lsp.util.set_qflist()* Use |setqflist()| instead. +• *vim.lsp.util.set_loclist()* Use |setloclist()| instead. +• *vim.lsp.buf_get_clients()* Use |vim.lsp.get_clients()| with {buffer=bufnr} instead. -- *vim.lsp.buf.formatting()* Use |vim.lsp.buf.format()| with +• *vim.lsp.buf.formatting()* Use |vim.lsp.buf.format()| with {async=true} instead. -- *vim.lsp.buf.formatting_sync()* Use |vim.lsp.buf.format()| with +• *vim.lsp.buf.formatting_sync()* Use |vim.lsp.buf.format()| with {async=false} instead. -- *vim.lsp.buf.range_formatting()* Use |vim.lsp.formatexpr()| +• *vim.lsp.buf.range_formatting()* Use |vim.lsp.formatexpr()| or |vim.lsp.buf.format()| instead. LUA -- vim.register_keystroke_callback() Use |vim.on_key()| instead. +• vim.register_keystroke_callback() Use |vim.on_key()| instead. NORMAL COMMANDS -- *]f* *[f* Same as "gf". +• *]f* *[f* Same as "gf". OPTIONS -- *cpo-<* *:menu-<special>* *:menu-special* *:map-<special>* *:map-special* +• *cpo-<* *:menu-<special>* *:menu-special* *:map-<special>* *:map-special* `<>` notation is always enabled. -- *'fe'* 'fenc'+'enc' before Vim 6.0; no longer used. -- *'highlight'* *'hl'* Names of builtin |highlight-groups| cannot be changed. -- *'langnoremap'* Deprecated alias to 'nolangremap'. -- 'sessionoptions' Flags "unix", "slash" are ignored and always enabled. -- *'vi'* -- 'viewoptions' Flags "unix", "slash" are ignored and always enabled. -- *'viminfo'* Deprecated alias to 'shada' option. -- *'viminfofile'* Deprecated alias to 'shadafile' option. -- *'paste'* *'nopaste'* Just Paste It.™ The 'paste' option is obsolete: +• *'fe'* 'fenc'+'enc' before Vim 6.0; no longer used. +• *'highlight'* *'hl'* Names of builtin |highlight-groups| cannot be changed. +• *'langnoremap'* Deprecated alias to 'nolangremap'. +• 'sessionoptions' Flags "unix", "slash" are ignored and always enabled. +• *'vi'* +• 'viewoptions' Flags "unix", "slash" are ignored and always enabled. +• *'viminfo'* Deprecated alias to 'shada' option. +• *'viminfofile'* Deprecated alias to 'shadafile' option. +• *'paste'* *'nopaste'* Just Paste It.™ The 'paste' option is obsolete: |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, …). Enables "paste mode": - - Disables mappings in Insert, Cmdline mode. - - Disables abbreviations. - - Resets 'autoindent' 'expandtab' 'revins' 'ruler' + • Disables mappings in Insert, Cmdline mode. + • Disables abbreviations. + • Resets 'autoindent' 'expandtab' 'revins' 'ruler' 'showmatch' 'smartindent' 'smarttab' 'softtabstop' 'textwidth' 'wrapmargin'. - - Treats 'formatoptions' as empty. - - Disables the effect of these options: - - 'cindent' - - 'indentexpr' - - 'lisp' + • Treats 'formatoptions' as empty. + • Disables the effect of these options: + • 'cindent' + • 'indentexpr' + • 'lisp' UI EXTENSIONS -- *ui-wildmenu* Use |ui-cmdline| with |ui-popupmenu| instead. Enabled +• *ui-wildmenu* Use |ui-cmdline| with |ui-popupmenu| instead. Enabled by the `ext_wildmenu` |ui-option|. Emits these events: - - `["wildmenu_show", items]` - - `["wildmenu_select", selected]` - - `["wildmenu_hide"]` -- *term_background* Unused. The terminal background color is now detected + • `["wildmenu_show", items]` + • `["wildmenu_select", selected]` + • `["wildmenu_hide"]` +• *term_background* Unused. The terminal background color is now detected by the Nvim core directly instead of the TUI. VARIABLES -- *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')` +• *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')` + +VIMSCRIPT +• *buffer_exists()* Obsolete name for |bufexists()|. +• *buffer_name()* Obsolete name for |bufname()|. +• *buffer_number()* Obsolete name for |bufnr()|. +• *file_readable()* Obsolete name for |filereadable()|. +• *highlight_exists()* Obsolete name for |hlexists()|. +• *highlightID()* Obsolete name for |hlID()|. +• *inputdialog()* Use |input()| instead. +• *jobclose()* Obsolete name for |chanclose()| +• *jobsend()* Obsolete name for |chansend()| +• *last_buffer_nr()* Obsolete name for bufnr("$"). +• *rpcstart()* Use |jobstart()| with `{'rpc': v:true}` instead. +• *rpcstop()* Use |jobstop()| instead to stop any job, or + `chanclose(id, "rpc")` to close RPC communication + without stopping the job. Use chanclose(id) to close + any socket. vim:noet:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/dev_arch.txt b/runtime/doc/dev_arch.txt index 1cb3b9ad67..2be6221117 100644 --- a/runtime/doc/dev_arch.txt +++ b/runtime/doc/dev_arch.txt @@ -46,11 +46,11 @@ Remember to bump NVIM_API_LEVEL if it wasn't already during this development cycle. Other references: -* |msgpack-rpc| -* |ui| -* https://github.com/neovim/neovim/pull/3246 -* https://github.com/neovim/neovim/pull/18375 -* https://github.com/neovim/neovim/pull/21605 +- |msgpack-rpc| +- |ui| +- https://github.com/neovim/neovim/pull/3246 +- https://github.com/neovim/neovim/pull/18375 +- https://github.com/neovim/neovim/pull/21605 diff --git a/runtime/doc/dev_vimpatch.txt b/runtime/doc/dev_vimpatch.txt index 5119613b55..76be24878a 100644 --- a/runtime/doc/dev_vimpatch.txt +++ b/runtime/doc/dev_vimpatch.txt @@ -188,6 +188,7 @@ information. vim_strcat strncat xstrlcat VIM_ISWHITE ascii_iswhite IS_WHITE_OR_NUL ascii_iswhite_or_nul + IS_WHITE_NL_OR_NUL ascii_iswhite_nl_or_nul vim_isalpha mb_isalpha vim_isNormalIDc ascii_isident vim_islower vim_isupper mb_islower mb_isupper diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index a61c569a67..d3170f114f 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -300,7 +300,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* +STDLIB DESIGN GUIDELINES *dev-lua* See also |dev-naming|. @@ -337,7 +337,7 @@ preference): way. Advantage is that propagation happens for free and it's harder to accidentally swallow errors. (E.g. using `uv_handle/pipe:write()` without checking return values is common.) -4. `on_error` parameter +4. `on_error` callback - For async and "visitors" traversing a graph, where many errors may be collected while work continues. 5. `vim.notify` (sometimes with optional `opts.silent` (async, visitors ^)) @@ -376,6 +376,10 @@ Where possible, these patterns apply to _both_ Lua and the API: - 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 +- Transformation functions should also have a filter functionality when + appropriate. That is, when the function returns a nil value it "filters" its + input, otherwise the transformed value is used. + - Example: |vim.diagnostic.config.format()| API DESIGN GUIDELINES *dev-api* @@ -434,7 +438,9 @@ Use existing common {verb} names (actions) if possible: - eval: Evaluates an expression - exec: Executes code, may return a result - fmt: Formats - - get: Gets things (often by a query) + - get: Gets things. Two variants (overloads): + 1. `get<T>(id: int): T` returns one item. + 2. `get<T>(filter: dict): T[]` returns a list. - inspect: Presents a high-level, often interactive, view - is_enabled: Checks if functionality is enabled. - open: Opens something (a buffer, window, …) @@ -506,6 +512,15 @@ be a parameter (typically manifest as mutually-exclusive buf/win/… flags like - Example: `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter) and uses the "del" {verb}. + *dev-namespace-name* +Use namespace names like `nvim.foo.bar`: > + vim.api.nvim_create_namespace('nvim.lsp.codelens') +< + + *dev-augroup-name* +Use autocommand group names like `nvim.foo.bar`: > + vim.api.nvim_create_augroup('nvim.treesitter.dev') +< INTERFACE PATTERNS *dev-api-patterns* diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 9ccc3102b6..5e1e04ce56 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -93,8 +93,12 @@ The {opts} table passed to a handler is the full set of configuration options values in the table are already resolved (i.e. if a user specifies a function for a config option, the function has already been evaluated). -Nvim provides these handlers by default: "virtual_text", "signs", and -"underline". +If a diagnostic handler is configured with a "severity" key then the list of +diagnostics passed to that handler will be filtered using the value of that +key (see example below). + +Nvim provides these handlers by default: "virtual_text", "virtual_lines", +"signs", and "underline". *diagnostic-handlers-example* The example below creates a new handler that notifies the user of diagnostics @@ -119,6 +123,9 @@ with |vim.notify()|: >lua vim.diagnostic.config({ ["my/notify"] = { log_level = vim.log.levels.INFO + + -- This handler will only receive "error" diagnostics. + severity = vim.diagnostic.severity.ERROR, } }) < @@ -163,6 +170,43 @@ show a sign for the highest severity diagnostic on a given line: >lua } < + *diagnostic-toggle-virtual-lines-example* +Diagnostic handlers can also be toggled. For example, you might want to toggle +the `virtual_lines` handler with the following keymap: >lua + + vim.keymap.set('n', 'gK', function() + local new_config = not vim.diagnostic.config().virtual_lines + vim.diagnostic.config({ virtual_lines = new_config }) + end, { desc = 'Toggle diagnostic virtual_lines' }) +< + + *diagnostic-loclist-example* +Whenever the |location-list| is opened, the following `show` handler will show +the most recent diagnostics: >lua + + vim.diagnostic.handlers.loclist = { + show = function(_, _, _, opts) + -- Generally don't want it to open on every update + opts.loclist.open = opts.loclist.open or false + local winid = vim.api.nvim_get_current_win() + vim.diagnostic.setloclist(opts.loclist) + vim.api.nvim_set_current_win(winid) + end + } +< + +The handler accepts the same options as |vim.diagnostic.setloclist()| and can be +configured using |vim.diagnostic.config()|: >lua + + -- Open the location list on every diagnostic change (warnings/errors only). + vim.diagnostic.config({ + loclist = { + open = true, + severity = { min = vim.diagnostic.severity.WARN }, + } + }) +< + ============================================================================== HIGHLIGHTS *diagnostic-highlights* @@ -430,11 +474,13 @@ Lua module: vim.diagnostic *diagnostic-api* Fields: ~ • {underline}? (`boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline`, default: `true`) Use underline for diagnostics. - • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `true`) + • {virtual_text}? (`boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText`, default: `false`) Use virtual text for diagnostics. If multiple diagnostics are set for a namespace, one prefix per diagnostic + the last diagnostic message are shown. + • {virtual_lines}? (`boolean|vim.diagnostic.Opts.VirtualLines|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualLines`, default: `false`) + Use virtual lines for diagnostics. • {signs}? (`boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs`, default: `true`) Use signs for diagnostics |diagnostic-signs|. • {float}? (`boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float`) @@ -486,11 +532,13 @@ Lua module: vim.diagnostic *diagnostic-api* the buffer. Otherwise, any truthy value means to always show the diagnostic source. Overrides the setting from |vim.diagnostic.config()|. - • {format}? (`fun(diagnostic:vim.Diagnostic): string`) A + • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A function that takes a diagnostic as input and - returns a string. The return value is the text used - to display the diagnostic. Overrides the setting - from |vim.diagnostic.config()|. + returns a string or nil. If the return value is nil, + the diagnostic is not displayed by the handler. Else + the output text is used to display the diagnostic. + Overrides the setting from + |vim.diagnostic.config()|. • {prefix}? (`string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)`) Prefix each diagnostic in the floating window: • If a `function`, {i} is the index of the @@ -556,12 +604,25 @@ Lua module: vim.diagnostic *diagnostic-api* diagnostics matching the given severity |diagnostic-severity|. +*vim.diagnostic.Opts.VirtualLines* + + Fields: ~ + • {current_line}? (`boolean`, default: `false`) Only show diagnostics + for the current line. + • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) A + function that takes a diagnostic as input and returns + a string or nil. If the return value is nil, the + diagnostic is not displayed by the handler. Else the + output text is used to display the diagnostic. + *vim.diagnostic.Opts.VirtualText* Fields: ~ • {severity}? (`vim.diagnostic.SeverityFilter`) Only show virtual text for diagnostics matching the given severity |diagnostic-severity| + • {current_line}? (`boolean`) Only show diagnostics for the + current line. (default `false`) • {source}? (`boolean|"if_many"`) Include the diagnostic source in virtual text. Use `'if_many'` to only show sources if there is more than one @@ -579,9 +640,9 @@ Lua module: vim.diagnostic *diagnostic-api* • {suffix}? (`string|(fun(diagnostic:vim.Diagnostic): string)`) Append diagnostic message with suffix. This can be used to render an LSP diagnostic error code. - • {format}? (`fun(diagnostic:vim.Diagnostic): string`) The - return value is the text used to display the - diagnostic. Example: >lua + • {format}? (`fun(diagnostic:vim.Diagnostic): string?`) If + not nil, the return value is the text used to + display the diagnostic. Example: >lua function(diagnostic) if diagnostic.severity == vim.diagnostic.severity.ERROR then return string.format("E: %s", diagnostic.message) @@ -589,11 +650,14 @@ Lua module: vim.diagnostic *diagnostic-api* return diagnostic.message end < + + If the return value is nil, the diagnostic is + not displayed by the handler. • {hl_mode}? (`'replace'|'combine'|'blend'`) See |nvim_buf_set_extmark()|. • {virt_text}? (`[string,any][]`) See |nvim_buf_set_extmark()|. - • {virt_text_pos}? (`'eol'|'overlay'|'right_align'|'inline'`) See - |nvim_buf_set_extmark()|. + • {virt_text_pos}? (`'eol'|'eol_right_align'|'inline'|'overlay'|'right_align'`) + See |nvim_buf_set_extmark()|. • {virt_text_win_col}? (`integer`) See |nvim_buf_set_extmark()|. • {virt_text_hide}? (`boolean`) See |nvim_buf_set_extmark()|. @@ -847,7 +911,8 @@ setqflist({opts}) *vim.diagnostic.setqflist()* • {open}? (`boolean`, default: `true`) Open quickfix list after setting. • {title}? (`string`) Title of quickfix list. Defaults to - "Diagnostics". + "Diagnostics". If there's already a quickfix list with this + title, it's updated. If not, a new quickfix list is created. • {severity}? (`vim.diagnostic.SeverityFilter`) See |diagnostic-severity|. diff --git a/runtime/doc/digraph.txt b/runtime/doc/digraph.txt index 1e91e5e4b8..13df8ad4ac 100644 --- a/runtime/doc/digraph.txt +++ b/runtime/doc/digraph.txt @@ -119,8 +119,8 @@ see them. On most systems Vim uses the same digraphs. They work for the Unicode and ISO-8859-1 character sets. These default digraphs are taken from the RFC1345 -mnemonics. To make it easy to remember the mnemonic, the second character has -a standard meaning: +mnemonics (with some additions). To make it easy to remember the mnemonic, +the second character has a standard meaning: char name char meaning ~ Exclamation mark ! Grave @@ -1064,6 +1064,7 @@ the 1', 2' and 3' digraphs. ≅ ?= 2245 8773 APPROXIMATELY EQUAL TO ≈ ?2 2248 8776 ALMOST EQUAL TO ≌ =? 224C 8780 ALL EQUAL TO + ≐ .= 2250 8784 APPROACHES THE LIMIT ≓ HI 2253 8787 IMAGE OF OR APPROXIMATELY EQUAL TO ≠ != 2260 8800 NOT EQUAL TO ≡ =3 2261 8801 IDENTICAL TO diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index e0c45503cc..60238bc90d 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2848,7 +2848,8 @@ in the variable |v:exception|: > : echo "Number thrown. Value is" v:exception You may also be interested where an exception was thrown. This is stored in -|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the +|v:throwpoint|. And you can obtain the stack trace from |v:stacktrace|. +Note that "v:exception", "v:stacktrace" and "v:throwpoint" are valid for the exception most recently caught as long it is not finished. Example: > diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 19c018bc11..cc520484b3 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -597,7 +597,7 @@ To disable this behavior, set the following variable in your vimrc: > let g:gdscript_recommended_style = 0 -GIT COMMIT *ft-gitcommit-plugin* +GIT COMMIT *ft-gitcommit-plugin* One command, :DiffGitCached, is provided to show a diff of the current commit in the preview window. It is equivalent to calling "git diff --cached" plus @@ -778,7 +778,7 @@ An alternative to using `MANPAGER` in shell can be redefined `man`, for example: nvim "+hide Man $1" } -MARKDOWN *ft-markdown-plugin* +MARKDOWN *ft-markdown-plugin* To enable folding use this: > let g:markdown_folding = 1 @@ -870,7 +870,7 @@ To enable this behavior, set the following variable in your vimrc: > let g:rst_style = 1 -RNOWEB *ft-rnoweb-plugin* +RNOWEB *ft-rnoweb-plugin* The 'formatexpr' option is set dynamically with different values for R code and for LaTeX code. If you prefer that 'formatexpr' is not set, add to your diff --git a/runtime/doc/fold.txt b/runtime/doc/fold.txt index b844e0ed85..9e61e40814 100644 --- a/runtime/doc/fold.txt +++ b/runtime/doc/fold.txt @@ -82,9 +82,11 @@ The most efficient is to call a function without arguments: > The function must use v:lnum. See |expr-option-function|. These are the conditions with which the expression is evaluated: + - The current buffer and window are set for the line. - The variable "v:lnum" is set to the line number. -- The result is used for the fold level in this way: + +The result of foldexpr then determines the fold level as follows: value meaning ~ 0 the line is not in a fold 1, 2, .. the line is in a fold with this level @@ -99,6 +101,9 @@ These are the conditions with which the expression is evaluated: "<1", "<2", .. a fold with this level ends at this line ">1", ">2", .. a fold with this level starts at this line +The result values "=", "s" and "a" are more expensive, please see +|fold-expr-slow|. + It is not required to mark the start (end) of a fold with ">1" ("<1"), a fold will also start (end) when the fold level is higher (lower) than the fold level of the previous line. @@ -112,14 +117,8 @@ recognized, there is no error message and the fold level will be zero. For debugging the 'debug' option can be set to "msg", the error messages will be visible then. -Note: Since the expression has to be evaluated for every line, this fold -method can be very slow! - -Try to avoid the "=", "a" and "s" return values, since Vim often has to search -backwards for a line for which the fold level is defined. This can be slow. - If the 'foldexpr' expression starts with s: or |<SID>|, then it is replaced -with the script ID (|local-function|). Examples: > +with the script ID (|local-function|). Examples: > set foldexpr=s:MyFoldExpr() set foldexpr=<SID>SomeFoldExpr() < @@ -143,6 +142,37 @@ end in that line. It may happen that folds are not updated properly. You can use |zx| or |zX| to force updating folds. +MINIMIZING COMPUTATIONAL COST *fold-expr-slow* + +Due to its computational cost, this fold method can make Vim unresponsive, +especially when the fold level of all lines have to be initially computed. +Afterwards, after each change, Vim restricts the computation of foldlevels +to those lines whose fold level was affected by it (and reuses the known +foldlevels of all the others). + +The fold expression should therefore strive to minimize the number of +dependent lines needed for the computation of a given line: For example, try +to avoid the "=", "a" and "s" return values, because these will require the +evaluation of the fold levels on previous lines until an independent fold +level is found. + +If this proves difficult, the next best thing could be to cache all fold +levels in a buffer-local variable (b:foldlevels) that is only updated on +|b:changedtick|: +>vim + func MyFoldFunc() + if b:lasttick == b:changedtick + return b:foldlevels[v:lnum - 1] + endif + let b:lasttick = b:changedtick + let b:foldlevels = [] + " compute foldlevels ... + return b:foldlevels[v:lnum - 1] + enddef + set foldexpr=s:MyFoldFunc() +< +In above example further speedup was gained by using a function without +arguments (that must still use v:lnum). See |expr-option-function|. SYNTAX *fold-syntax* @@ -379,8 +409,8 @@ zX Undo manually opened and closed folds: re-apply 'foldlevel'. Also forces recomputing folds, like |zx|. *zm* -zm Fold more: Subtract |v:count1| from 'foldlevel'. If 'foldlevel' was - already zero nothing happens. +zm Fold more: Subtract |v:count1| from 'foldlevel'. If + 'foldlevel' was already zero nothing happens. 'foldenable' will be set. *zM* @@ -444,7 +474,7 @@ zk Move upwards to the end of the previous fold. A closed fold EXECUTING COMMANDS ON FOLDS ~ -:[range]foldd[oopen] {cmd} *:foldd* *:folddo* *:folddoopen* +:[range]foldd[oopen] {cmd} *:foldd* *:folddo* *:folddoopen* Execute {cmd} on all lines that are not in a closed fold. When [range] is given, only these lines are used. Each time {cmd} is executed the cursor is positioned on the @@ -532,7 +562,7 @@ When there is room after the text, it is filled with the character specified by 'fillchars'. If the 'foldtext' expression starts with s: or |<SID>|, then it is replaced -with the script ID (|local-function|). Examples: > +with the script ID (|local-function|). Examples: > set foldtext=s:MyFoldText() set foldtext=<SID>SomeFoldText() < diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 21f1ba8241..ecb4de09bb 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -1,10 +1,10 @@ *gui.txt* Nvim - VIM REFERENCE MANUAL by Bram Moolenaar + VIM REFERENCE MANUAL by Bram Moolenaar -Nvim Graphical User Interface *gui* *GUI* +Nvim Graphical User Interface *gui* *GUI* Any client that supports the Nvim |ui-protocol| can be used as a UI for Nvim. And multiple UIs can connect to the same Nvim instance! The terms "UI" and @@ -17,11 +17,16 @@ TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes specific to the terminal UI. Help tags with the "gui-" prefix refer to UI features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|. -Nvim provides a default, builtin UI (the |TUI|), but there are many other -(third-party) GUIs that you can use instead: +============================================================================== +Third-party GUIs *third-party-guis* *vscode* + +Nvim provides a builtin "terminal UI" (|TUI|), but also works with many +(third-party) GUIs which may provide a fresh look or extra features on top of +Nvim. For example, "vscode-neovim" essentially allows you to use VSCode as +a Nvim GUI. -- Firenvim (Nvim in your web browser!) https://github.com/glacambre/firenvim - vscode-neovim (Nvim in VSCode!) https://github.com/vscode-neovim/vscode-neovim +- Firenvim (Nvim in your web browser!) https://github.com/glacambre/firenvim - Neovide https://neovide.dev/ - Goneovim https://github.com/akiyosi/goneovim - Nvy https://github.com/RMichelsen/Nvy @@ -32,71 +37,257 @@ Nvim provides a default, builtin UI (the |TUI|), but there are many other Type |gO| to see the table of contents. ============================================================================== -Starting the GUI *gui-config* *gui-start* +Starting the GUI *gui-config* *gui-start* - *ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC* + *ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC* For GUI-specific configuration Nvim provides the |UIEnter| event. This happens after other |initialization|s, or whenever a UI attaches (multiple UIs can connect to any Nvim instance). Example: this sets "g:gui" to the value of the UI's "rgb" field: > - :autocmd UIEnter * let g:gui = filter(nvim_list_uis(),{k,v-> v.chan==v:event.chan})[0].rgb + :autocmd UIEnter * let g:gui = filter(nvim_list_uis(),{k,v-> v.chan==v:event.chan})[0].rgb < - *:winp* *:winpos* *E188* + *:winp* *:winpos* *E188* :winp[os] - Display current position of the top left corner of the GUI vim - window in pixels. Does not work in all versions. - Also see |getwinpos()|, |getwinposx()| and |getwinposy()|. - -:winp[os] {X} {Y} *E466* - Put the GUI vim window at the given {X} and {Y} coordinates. - The coordinates should specify the position in pixels of the - top left corner of the window. - When the GUI window has not been opened yet, the values are - remembered until the window is opened. The position is - adjusted to make the window fit on the screen (if possible). - - *:wi* *:win* *:winsize* *E465* + Display current position of the top left corner of the GUI vim + window in pixels. Does not work in all versions. + Also see |getwinpos()|, |getwinposx()| and |getwinposy()|. + +:winp[os] {X} {Y} *E466* + Put the GUI vim window at the given {X} and {Y} coordinates. + The coordinates should specify the position in pixels of the + top left corner of the window. + When the GUI window has not been opened yet, the values are + remembered until the window is opened. The position is + adjusted to make the window fit on the screen (if possible). + + *:wi* *:win* *:winsize* *E465* :win[size] {width} {height} - Set the window height to {width} by {height} characters. - Obsolete, use ":set lines=11 columns=22". + Set the window height to {width} by {height} characters. + Obsolete, use ":set lines=11 columns=22". ============================================================================== -Scrollbars *gui-scrollbars* +Using the mouse *mouse-using* + + *mouse-mode-table* *mouse-overview* +Overview of what the mouse buttons do, when 'mousemodel' is "extend": + + *<S-LeftMouse>* *<A-RightMouse>* *<S-RightMouse>* *<RightDrag>* + *<RightRelease>* *<LeftDrag>* +Normal Mode: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <LeftMouse> yes end yes + <C-LeftMouse> yes end yes "CTRL-]" (2) + <S-LeftMouse> yes no change yes "*" (2) + <LeftDrag> yes start or extend (1) no + <LeftRelease> yes start or extend (1) no + <MiddleMouse> yes if not active no put + <MiddleMouse> yes if active no yank and put + <RightMouse> yes start or extend yes + <A-RightMouse> yes start or extend blockw. yes + <S-RightMouse> yes no change yes "#" (2) + <C-RightMouse> no no change no "CTRL-T" + <RightDrag> yes extend no + <RightRelease> yes extend no + +Insert or Replace Mode: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <LeftMouse> yes (cannot be active) yes + <C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2) + <S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2) + <LeftDrag> yes start or extend (1) no like CTRL-O (1) + <LeftRelease> yes start or extend (1) no like CTRL-O (1) + <MiddleMouse> no (cannot be active) no put register + <RightMouse> yes start or extend yes like CTRL-O + <A-RightMouse> yes start or extend blockw. yes + <S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2) + <C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T" + +In a help window: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag) + +When 'mousemodel' is "popup", these are different: + + *<A-LeftMouse>* +Normal Mode: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <S-LeftMouse> yes start or extend (1) no + <A-LeftMouse> yes start/extend blockw no + <RightMouse> no popup menu no + +Insert or Replace Mode: > + event position selection change action + cursor window + --------------------------------------------------------------------------- + <S-LeftMouse> yes start or extend (1) no like CTRL-O (1) + <A-LeftMouse> yes start/extend blockw no + <RightMouse> no popup menu no + +(1) only if mouse pointer moved since press +(2) only if click is in same buffer + +Clicking the left mouse button causes the cursor to be positioned. If the +click is in another window that window is made the active window. When +editing the command-line the cursor can only be positioned on the +command-line. When in Insert mode Vim remains in Insert mode. If 'scrolloff' +is set, and the cursor is positioned within 'scrolloff' lines from the window +border, the text is scrolled. + +A selection can be started by pressing the left mouse button on the first +character, moving the mouse to the last character, then releasing the mouse +button. You will not always see the selection until you release the button, +only in some versions (GUI, Win32) will the dragging be shown immediately. +Note that you can make the text scroll by moving the mouse at least one +character in the first/last line in the window when 'scrolloff' is non-zero. + +In Normal, Visual and Select mode clicking the right mouse button causes the +Visual area to be extended. When 'mousemodel' is "popup", the left button has +to be used while keeping the shift key pressed. When clicking in a window +which is editing another buffer, the Visual or Select mode is stopped. + +In Normal, Visual and Select mode clicking the right mouse button with the alt +key pressed causes the Visual area to become blockwise. When 'mousemodel' is +"popup" the left button has to be used with the alt key. Note that this won't +work on systems where the window manager consumes the mouse events when the +alt key is pressed (it may move the window). + + *double-click* *<2-LeftMouse>* *<3-LeftMouse>* *<4-LeftMouse>* +Double, triple and quadruple clicks are supported. For selecting text, extra +clicks extend the selection: > + + click select + --------------------------------- + double word or % match + triple line + quadruple rectangular block + +Exception: In a :help window, double-click jumps to help for the word that is +clicked on. + +Double-click on a word selects that word. 'iskeyword' is used to specify +which characters are included in a word. Double-click on a character that has +a match selects until that match (like using "v%"). If the match is an +#if/#else/#endif block, the selection becomes linewise. The time for +double-clicking can be set with the 'mousetime' option. + +Example: configure double-click to jump to the tag under the cursor: >vim + :map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR> + +Dragging the mouse with a double-click (button-down, button-up, button-down +and then drag) will result in whole words to be selected. This continues +until the button is released, at which point the selection is per character +again. + +For scrolling with the mouse see |scroll-mouse-wheel|. + +In Insert mode, when a selection is started, Vim goes into Normal mode +temporarily. When Visual or Select mode ends, it returns to Insert mode. +This is like using CTRL-O in Insert mode. Select mode is used when the +'selectmode' option contains "mouse". + + *X1Mouse* *X1Drag* *X1Release* + *X2Mouse* *X2Drag* *X2Release* + *<MiddleRelease>* *<MiddleDrag>* +Mouse clicks can be mapped using these |keycodes|: > + code mouse button normal action + --------------------------------------------------------------------------- + <LeftMouse> left pressed set cursor position + <LeftDrag> left moved while pressed extend selection + <LeftRelease> left released set selection end + <MiddleMouse> middle pressed paste text at cursor position + <MiddleDrag> middle moved while pressed - + <MiddleRelease> middle released - + <RightMouse> right pressed extend selection + <RightDrag> right moved while pressed extend selection + <RightRelease> right released set selection end + <X1Mouse> X1 button pressed - + <X1Drag> X1 moved while pressed - + <X1Release> X1 button release - + <X2Mouse> X2 button pressed - + <X2Drag> X2 moved while pressed - + <X2Release> X2 button release - + +The X1 and X2 buttons refer to the extra buttons found on some mice (e.g. the +right thumb). + +Examples: >vim + :noremap <MiddleMouse> <LeftMouse><MiddleMouse> +Paste at the position of the middle mouse button click (otherwise the paste +would be done at the cursor position). >vim + + :noremap <LeftRelease> <LeftRelease>y +Immediately yank the selection, when using Visual mode. + +Note the use of ":noremap" instead of "map" to avoid a recursive mapping. +>vim + :map <X1Mouse> <C-O> + :map <X2Mouse> <C-I> +Map the X1 and X2 buttons to go forwards and backwards in the jump list, see +|CTRL-O| and |CTRL-I|. + + *mouse-swap-buttons* +To swap the meaning of the left and right mouse buttons: >vim + :noremap <LeftMouse> <RightMouse> + :noremap <LeftDrag> <RightDrag> + :noremap <LeftRelease> <RightRelease> + :noremap <RightMouse> <LeftMouse> + :noremap <RightDrag> <LeftDrag> + :noremap <RightRelease> <LeftRelease> + :noremap g<LeftMouse> <C-RightMouse> + :noremap g<RightMouse> <C-LeftMouse> + :noremap! <LeftMouse> <RightMouse> + :noremap! <LeftDrag> <RightDrag> + :noremap! <LeftRelease> <RightRelease> + :noremap! <RightMouse> <LeftMouse> + :noremap! <RightDrag> <LeftDrag> + :noremap! <RightRelease> <LeftRelease> +< + +============================================================================== +Scrollbars *gui-scrollbars* There are vertical scrollbars and a horizontal scrollbar. You may configure which ones appear with the 'guioptions' option. The interface looks like this (with `:set guioptions=mlrb`): > - +------------------------------+ ` - | File Edit Help | <- Menu bar (m) ` - +-+--------------------------+-+ ` - |^| |^| ` - |#| Text area. |#| ` - | | | | ` - |v|__________________________|v| ` - Normal status line -> |-+ File.c 5,2 +-| ` + +------------------------------+ ` + | File Edit Help | <- Menu bar (m) ` + +-+--------------------------+-+ ` + |^| |^| ` + |#| Text area. |#| ` + | | | | ` + |v|__________________________|v| ` + Normal status line -> |-+ File.c 5,2 +-| ` between Vim windows |^|""""""""""""""""""""""""""|^| ` - | | | | ` - | | Another file buffer. | | ` - | | | | ` - |#| |#| ` - Left scrollbar (l) -> |#| |#| <- Right ` - |#| |#| scrollbar (r) ` - | | | | ` - |v| |v| ` - +-+--------------------------+-+ ` - | |< #### >| | <- Bottom ` - +-+--------------------------+-+ scrollbar (b) ` + | | | | ` + | | Another file buffer. | | ` + | | | | ` + |#| |#| ` + Left scrollbar (l) -> |#| |#| <- Right ` + |#| |#| scrollbar (r) ` + | | | | ` + |v| |v| ` + +-+--------------------------+-+ ` + | |< #### >| | <- Bottom ` + +-+--------------------------+-+ scrollbar (b) ` < Any of the scrollbar or menu components may be turned off by not putting the appropriate letter in the 'guioptions' string. The bottom scrollbar is only useful when 'nowrap' is set. -VERTICAL SCROLLBARS *gui-vert-scroll* +VERTICAL SCROLLBARS *gui-vert-scroll* Each Vim window has a scrollbar next to it which may be scrolled up and down to move through the text in that buffer. The size of the scrollbar-thumb @@ -115,7 +306,7 @@ is on the left half, the right scrollbar column will contain scrollbars for the rightmost windows. The same happens on the other side. -HORIZONTAL SCROLLBARS *gui-horiz-scroll* +HORIZONTAL SCROLLBARS *gui-horiz-scroll* The horizontal scrollbar (at the bottom of the Vim GUI) may be used to scroll text sideways when the 'wrap' option is turned off. The @@ -131,7 +322,7 @@ include the 'h' flag in 'guioptions'. Then the scrolling is limited by the text of the current cursor line. ============================================================================== -Drag and drop *drag-n-drop* +Drag and drop *drag-n-drop* You can drag and drop one or more files into the Vim window, where they will be opened as if a |:drop| command was used. @@ -150,12 +341,12 @@ names with any Ex command. Special characters (space, tab, double quote and "|"; backslash on non-MS-Windows systems) will be escaped. ============================================================================== -Menus *menus* +Menus *menus* For an introduction see |usr_42.txt| in the user manual. -Using Menus *using-menus* +Using Menus *using-menus* Basically, menus can be used just like mappings. You can define your own menus, as many as you like. @@ -165,45 +356,45 @@ what the key sequence was. For creating menus in a different language, see |:menutrans|. - *menu.vim* + *menu.vim* The default menus are read from the file "$VIMRUNTIME/menu.vim". See |$VIMRUNTIME| for where the path comes from. You can set up your own menus. Starting off with the default set is a good idea. You can add more items, or, if you don't like the defaults at all, start with removing all menus |:unmenu-all|. You can also avoid the default menus being loaded by adding this line to your vimrc file (NOT your gvimrc file!): > - :let did_install_default_menus = 1 + :let did_install_default_menus = 1 If you also want to avoid the Syntax menu: > - :let did_install_syntax_menu = 1 + :let did_install_syntax_menu = 1 The first item in the Syntax menu can be used to show all available filetypes in the menu (which can take a bit of time to load). If you want to have all filetypes already present at startup, add: > - :let do_syntax_sel_menu = 1 + :let do_syntax_sel_menu = 1 Note that the menu.vim is sourced when `:syntax on` or `:filetype on` is executed or after your .vimrc file is sourced. This means that the 'encoding' option and the language of messages (`:language messages`) must be set before that (if you want to change them). - *console-menus* + *console-menus* Although this documentation is in the GUI section, you can actually use menus in console mode too. You will have to load |menu.vim| explicitly then, it is not done by default. You can use the |:emenu| command and command-line completion with 'wildmenu' to access the menu entries almost like a real menu system. To do this, put these commands in your vimrc file: > - :source $VIMRUNTIME/menu.vim - :set wildmenu - :set cpo-=< - :set wcm=<C-Z> - :map <F4> :emenu <C-Z> + :source $VIMRUNTIME/menu.vim + :set wildmenu + :set cpo-=< + :set wcm=<C-Z> + :map <F4> :emenu <C-Z> Pressing <F4> will start the menu. You can now use the cursor keys to select a menu entry. Hit <Enter> to execute it. Hit <Esc> if you want to cancel. -Creating New Menus *creating-menus* +Creating New Menus *creating-menus* - *:me* *:menu* *:noreme* *:noremenu* - *E330* *E327* *E331* *E336* *E333* - *E328* *E329* *E337* *E792* + *:me* *:menu* *:noreme* *:noremenu* + *E330* *E327* *E331* *E336* *E333* + *E328* *E329* *E337* *E792* To create a new menu item, use the ":menu" commands. They are mostly like the ":map" set of commands (see |map-modes|), but the first argument is a menu item name, given as a path of menus and submenus with a '.' between them, @@ -224,15 +415,16 @@ tooltips for menus. See |terminal-input|. Special characters in a menu name: - *menu-shortcut* - & The next character is the shortcut key. Make sure each - shortcut key is only used once in a (sub)menu. If you want to - insert a literal "&" in the menu name use "&&". - *menu-text* - <Tab> Separates the menu name from right-aligned text. This can be - used to show the equivalent typed command. The text "<Tab>" - can be used here for convenience. If you are using a real - tab, don't forget to put a backslash before it! + *menu-shortcut* +- & The next character is the shortcut key. Make sure each shortcut key is + only used once in a (sub)menu. If you want to insert a literal "&" in the + menu name use "&&". + *menu-text* +- <Tab> Separates the menu name from right-aligned text. This can be used to + show the equivalent typed command. The text "<Tab>" can be used here for + convenience. If you are using a real tab, don't forget to put a backslash + before it! + Example: > :amenu &File.&Open<Tab>:e :browse e<CR> @@ -242,99 +434,99 @@ With the shortcut "F" (while keeping the <Alt> key pressed), and then "O", this menu can be used. The second part is shown as "Open :e". The ":e" is right aligned, and the "O" is underlined, to indicate it is the shortcut. - *:am* *:amenu* *:an* *:anoremenu* + *:am* *:amenu* *:an* *:anoremenu* The ":amenu" command can be used to define menu entries for all modes at once, except for Terminal mode. To make the command work correctly, a character is -automatically inserted for some modes: - mode inserted appended ~ - Normal nothing nothing - Visual <C-C> <C-\><C-G> - Insert <C-\><C-O> - Cmdline <C-C> <C-\><C-G> - Op-pending <C-C> <C-\><C-G> - +automatically inserted for some modes: > + mode inserted appended + Normal nothing nothing + Visual <C-C> <C-\><C-G> + Insert <C-\><C-O> + Cmdline <C-C> <C-\><C-G> + Op-pending <C-C> <C-\><C-G> +< Example: > - :amenu File.Next :next^M + :amenu File.Next :next^M is equal to: > - :nmenu File.Next :next^M - :vmenu File.Next ^C:next^M^\^G - :imenu File.Next ^\^O:next^M - :cmenu File.Next ^C:next^M^\^G - :omenu File.Next ^C:next^M^\^G + :nmenu File.Next :next^M + :vmenu File.Next ^C:next^M^\^G + :imenu File.Next ^\^O:next^M + :cmenu File.Next ^C:next^M^\^G + :omenu File.Next ^C:next^M^\^G Careful: In Insert mode this only works for a SINGLE Normal mode command, because of the CTRL-O. If you have two or more commands, you will need to use the ":imenu" command. For inserting text in any mode, you can use the expression register: > - :amenu Insert.foobar "='foobar'<CR>P + :amenu Insert.foobar "='foobar'<CR>P The special text <Cmd> begins a "command menu", it executes the command directly without changing modes. Where you might use ":...<CR>" you can instead use "<Cmd>...<CR>". See |<Cmd>| for more info. Example: > - anoremenu File.Next <Cmd>next<CR> + anoremenu File.Next <Cmd>next<CR> Note that <Esc> in Cmdline mode executes the command, like in a mapping. This is Vi compatible. Use CTRL-C to quit Cmdline mode. - *:nme* *:nmenu* *:nnoreme* *:nnoremenu* *:nunme* *:nunmenu* + *:nme* *:nmenu* *:nnoreme* *:nnoremenu* *:nunme* *:nunmenu* Menu commands starting with "n" work in Normal mode. |mapmode-n| - *:ome* *:omenu* *:onoreme* *:onoremenu* *:ounme* *:ounmenu* + *:ome* *:omenu* *:onoreme* *:onoremenu* *:ounme* *:ounmenu* Menu commands starting with "o" work in Operator-pending mode. |mapmode-o| - *:vme* *:vmenu* *:vnoreme* *:vnoremenu* *:vunme* *:vunmenu* + *:vme* *:vmenu* *:vnoreme* *:vnoremenu* *:vunme* *:vunmenu* Menu commands starting with "v" work in Visual mode. |mapmode-v| - *:xme* *:xmenu* *:xnoreme* *:xnoremenu* *:xunme* *:xunmenu* + *:xme* *:xmenu* *:xnoreme* *:xnoremenu* *:xunme* *:xunmenu* Menu commands starting with "x" work in Visual and Select mode. |mapmode-x| - *:sme* *:smenu* *:snoreme* *:snoremenu* *:sunme* *:sunmenu* + *:sme* *:smenu* *:snoreme* *:snoremenu* *:sunme* *:sunmenu* Menu commands starting with "s" work in Select mode. |mapmode-s| - *:ime* *:imenu* *:inoreme* *:inoremenu* *:iunme* *:iunmenu* + *:ime* *:imenu* *:inoreme* *:inoremenu* *:iunme* *:iunmenu* Menu commands starting with "i" work in Insert mode. |mapmode-i| - *:cme* *:cmenu* *:cnoreme* *:cnoremenu* *:cunme* *:cunmenu* + *:cme* *:cmenu* *:cnoreme* *:cnoremenu* *:cunme* *:cunmenu* Menu commands starting with "c" work in Cmdline mode. |mapmode-c| - *:tlm* *:tlmenu* *:tln* *:tlnoremenu* *:tlu* *:tlunmenu* + *:tlm* *:tlmenu* *:tln* *:tlnoremenu* *:tlu* *:tlunmenu* Menu commands starting with "tl" work in Terminal mode. |mapmode-t| - *:menu-<silent>* *:menu-silent* + *:menu-<silent>* *:menu-silent* To define a menu which will not be echoed on the command line, add "<silent>" as the first argument. Example: > - :menu <silent> Settings.Ignore\ case :set ic<CR> + :menu <silent> Settings.Ignore\ case :set ic<CR> The ":set ic" will not be echoed when using this menu. Messages from the executed command are still given though. To shut them up too, add a ":silent" in the executed command: > - :menu <silent> Search.Header :exe ":silent normal /Header\r"<CR> + :menu <silent> Search.Header :exe ":silent normal /Header\r"<CR> "<silent>" may also appear just after "<script>". - *:menu-<script>* *:menu-script* + *:menu-<script>* *:menu-script* The "to" part of the menu will be inspected for mappings. If you don't want this, use the ":noremenu" command (or the similar one for a specific mode). If you do want to use script-local mappings, add "<script>" as the very first argument to the ":menu" command or just after "<silent>". - *menu-priority* + *menu-priority* You can give a priority to a menu. Menus with a higher priority go more to the right. The priority is given as a number before the ":menu" command. Example: > - :80menu Buffer.next :bn<CR> - -The default menus have these priorities: - File 10 - Edit 20 - Tools 40 - Syntax 50 - Buffers 60 - Window 70 - Help 9999 - + :80menu Buffer.next :bn<CR> + +The default menus have these priorities: > + File 10 + Edit 20 + Tools 40 + Syntax 50 + Buffers 60 + Window 70 + Help 9999 +< When no or zero priority is given, 500 is used. The priority for the PopUp menu is not used. @@ -342,18 +534,18 @@ You can use a priority higher than 9999, to make it go after the Help menu, but that is non-standard and is discouraged. The highest possible priority is about 32000. The lowest is 1. - *sub-menu-priority* + *sub-menu-priority* The same mechanism can be used to position a sub-menu. The priority is then given as a dot-separated list of priorities, before the menu name: > - :menu 80.500 Buffer.next :bn<CR> + :menu 80.500 Buffer.next :bn<CR> Giving the sub-menu priority is only needed when the item is not to be put in a normal position. For example, to put a sub-menu before the other items: > - :menu 80.100 Buffer.first :brew<CR> + :menu 80.100 Buffer.first :brew<CR> Or to put a sub-menu after the other items, and further items with default priority will be put before it: > - :menu 80.900 Buffer.last :blast<CR> + :menu 80.900 Buffer.last :blast<CR> When a number is missing, the default value 500 will be used: > - :menu .900 myMenu.test :echo "text"<CR> + :menu .900 myMenu.test :echo "text"<CR> The menu priority is only used when creating a new menu. When it already existed, e.g., in another mode, the priority will not change. Thus, the priority only needs to be given the first time a menu is used. @@ -363,49 +555,49 @@ menus can be different. This is different from menu-bar menus, which have the same order for all modes. NOTE: sub-menu priorities currently don't work for all versions of the GUI. - *menu-separator* *E332* + *menu-separator* *E332* Menu items can be separated by a special item that inserts some space between items. Depending on the system this is displayed as a line or a dotted line. These items must start with a '-' and end in a '-'. The part in between is used to give it a unique name. Priorities can be used as with normal items. Example: > - :menu Example.item1 :do something - :menu Example.-Sep- : - :menu Example.item2 :do something different + :menu Example.item1 :do something + :menu Example.-Sep- : + :menu Example.item2 :do something different Note that the separator also requires a rhs. It doesn't matter what it is, because the item will never be selected. Use a single colon to keep it simple. - *gui-toolbar* + *gui-toolbar* The default toolbar is setup in menu.vim. The display of the toolbar is controlled by the 'guioptions' letter 'T'. You can thus have menu & toolbar together, or either on its own, or neither. The appearance is controlled by the 'toolbar' option. You can choose between an image, text or both. - *toolbar-icon* + *toolbar-icon* The toolbar is defined as a special menu called ToolBar, which only has one level. Vim interprets the items in this menu as follows: -1) If an "icon=" argument was specified, the file with this name is used. +- 1 If an "icon=" argument was specified, the file with this name is used. The file can either be specified with the full path or with the base name. In the last case it is searched for in the "bitmaps" directory in 'runtimepath', like in point 3. Examples: > - :amenu icon=/usr/local/pixmaps/foo_icon.xpm ToolBar.Foo :echo "Foo"<CR> - :amenu icon=FooIcon ToolBar.Foo :echo "Foo"<CR> + :amenu icon=/usr/local/pixmaps/foo_icon.xpm ToolBar.Foo :echo "Foo"<CR> + :amenu icon=FooIcon ToolBar.Foo :echo "Foo"<CR> < Note that in the first case the extension is included, while in the second case it is omitted. If the file cannot be opened the next points are tried. A space in the file name must be escaped with a backslash. A menu priority must come _after_ the icon argument: > - :amenu icon=foo 1.42 ToolBar.Foo :echo "42!"<CR> -2) An item called 'BuiltIn##', where ## is a number, is taken as number ## of + :amenu icon=foo 1.42 ToolBar.Foo :echo "42!"<CR> +- 2 An item called 'BuiltIn##', where ## is a number, is taken as number ## of the built-in bitmaps available in Vim. Currently there are 31 numbered from 0 to 30 which cover most common editing operations |builtin-tools|. > - :amenu ToolBar.BuiltIn22 :call SearchNext("back")<CR> -3) An item with another name is first searched for in the directory + :amenu ToolBar.BuiltIn22 :call SearchNext("back")<CR> +- 3 An item with another name is first searched for in the directory "bitmaps" in 'runtimepath'. If found, the bitmap file is used as the toolbar button image. Note that the exact filename is OS-specific: For example, under Win32 the command > - :amenu ToolBar.Hello :echo "hello"<CR> + :amenu ToolBar.Hello :echo "hello"<CR> < would find the file 'hello.bmp'. Under X11 it is 'Hello.xpm'. For MS-Windows and the bitmap is scaled to fit the button. For MS-Windows a size of 18 by 18 pixels works best. @@ -413,55 +605,56 @@ level. Vim interprets the items in this menu as follows: The light grey pixels will be changed to the Window frame color and the dark grey pixels to the window shadow color. More colors might also work, depending on your system. -4) If the bitmap is still not found, Vim checks for a match against its list +- 4 If the bitmap is still not found, Vim checks for a match against its list of built-in names. Each built-in button image has a name. So the command > - :amenu ToolBar.Open :e + :amenu ToolBar.Open :e < will show the built-in "open a file" button image if no open.bmp exists. All the built-in names can be seen used in menu.vim. -5) If all else fails, a blank, but functioning, button is displayed. - - *builtin-tools* -nr Name Normal action ~ -00 New open new window -01 Open browse for file to open in current window -02 Save write buffer to file -03 Undo undo last change -04 Redo redo last undone change -05 Cut delete selected text to clipboard -06 Copy copy selected text to clipboard -07 Paste paste text from clipboard -08 Print print current buffer -09 Help open a buffer on Vim's builtin help -10 Find start a search command -11 SaveAll write all modified buffers to file -12 SaveSesn write session file for current situation -13 NewSesn write new session file -14 LoadSesn load session file -15 RunScript browse for file to run as a Vim script -16 Replace prompt for substitute command -17 WinClose close current window -18 WinMax make current window use many lines -19 WinMin make current window use few lines -20 WinSplit split current window -21 Shell start a shell -22 FindPrev search again, backward -23 FindNext search again, forward -24 FindHelp prompt for word to search help for -25 Make run make and jump to first error -26 TagJump jump to tag under the cursor -27 RunCtags build tags for files in current directory -28 WinVSplit split current window vertically -29 WinMaxWidth make current window use many columns -30 WinMinWidth make current window use few columns - - *hidden-menus* *win32-hidden-menus* +- 5 If all else fails, a blank, but functioning, button is displayed. + + *builtin-tools* +> + nr Name Normal action + 00 New open new window + 01 Open browse for file to open in current window + 02 Save write buffer to file + 03 Undo undo last change + 04 Redo redo last undone change + 05 Cut delete selected text to clipboard + 06 Copy copy selected text to clipboard + 07 Paste paste text from clipboard + 08 Print print current buffer + 09 Help open a buffer on Vim's builtin help + 10 Find start a search command + 11 SaveAll write all modified buffers to file + 12 SaveSesn write session file for current situation + 13 NewSesn write new session file + 14 LoadSesn load session file + 15 RunScript browse for file to run as a Vim script + 16 Replace prompt for substitute command + 17 WinClose close current window + 18 WinMax make current window use many lines + 19 WinMin make current window use few lines + 20 WinSplit split current window + 21 Shell start a shell + 22 FindPrev search again, backward + 23 FindNext search again, forward + 24 FindHelp prompt for word to search help for + 25 Make run make and jump to first error + 26 TagJump jump to tag under the cursor + 27 RunCtags build tags for files in current directory + 28 WinVSplit split current window vertically + 29 WinMaxWidth make current window use many columns + 30 WinMinWidth make current window use few columns +< + *hidden-menus* *win32-hidden-menus* In the Win32 GUI, starting a menu name with ']' excludes that menu from the main menu bar. You must then use the |:popup| command to display it. When splitting the window the window toolbar is not copied to the new window. - *popup-menu* + *popup-menu* 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. @@ -483,7 +676,7 @@ The default "PopUp" menu is: >vim anoremenu PopUp.How-to\ disable\ mouse <Cmd>help disable-mouse<CR> < -Showing What Menus Are Mapped To *showing-menus* +Showing What Menus Are Mapped To *showing-menus* To see what an existing menu is mapped to, use just one argument after the menu commands (just like you would with the ":map" commands). If the menu @@ -502,25 +695,25 @@ Note that hitting <Tab> while entering a menu name after a menu command may be used to complete the name of the menu item. -Executing Menus *execute-menus* +Executing Menus *execute-menus* - *:em* *:emenu* *E334* *E335* -:[range]em[enu] {menu} Execute {menu} from the command line. - The default is to execute the Normal mode - menu. If a range is specified, it executes - the Visual mode menu. - If used from <c-o>, it executes the - insert-mode menu Eg: > - :emenu File.Exit + *:em* *:emenu* *E334* *E335* +:[range]em[enu] {menu} Execute {menu} from the command line. + The default is to execute the Normal mode + menu. If a range is specified, it executes + the Visual mode menu. + If used from <c-o>, it executes the + insert-mode menu Eg: > + :emenu File.Exit -:[range]em[enu] {mode} {menu} Like above, but execute the menu for {mode}: - 'n': |:nmenu| Normal mode - 'v': |:vmenu| Visual mode - 's': |:smenu| Select mode - 'o': |:omenu| Operator-pending mode - 't': |:tlmenu| Terminal mode - 'i': |:imenu| Insert mode - 'c': |:cmenu| Cmdline mode +:[range]em[enu] {mode} {menu} Like above, but execute the menu for {mode}: + - 'n': |:nmenu| Normal mode + - 'v': |:vmenu| Visual mode + - 's': |:smenu| Select mode + - 'o': |:omenu| Operator-pending mode + - 't': |:tlmenu| Terminal mode + - 'i': |:imenu| Insert mode + - 'c': |:cmenu| Cmdline mode You can use :emenu to access useful menu items you may have got used to from @@ -531,10 +724,10 @@ When using a range, if the lines match with '<,'>, then the menu is executed using the last visual selection. -Deleting Menus *delete-menus* +Deleting Menus *delete-menus* - *:unme* *:unmenu* - *:aun* *:aunmenu* + *:unme* *:unmenu* + *:aun* *:aunmenu* To delete a menu item or a whole submenu, use the unmenu commands, which are analogous to the unmap commands. Eg: > :unmenu! Edit.Paste @@ -545,26 +738,26 @@ Command-line modes. Note that hitting <Tab> while entering a menu name after an umenu command may be used to complete the name of the menu item for the appropriate mode. -To remove all menus use: *:unmenu-all* > - :unmenu * " remove all menus in Normal and visual mode - :unmenu! * " remove all menus in Insert and Command-line mode - :aunmenu * " remove all menus in all modes, except for Terminal - " mode - :tlunmenu * " remove all menus in Terminal mode +To remove all menus use: *:unmenu-all* > + :unmenu * " remove all menus in Normal and visual mode + :unmenu! * " remove all menus in Insert and Command-line mode + :aunmenu * " remove all menus in all modes, except for Terminal + " mode + :tlunmenu * " remove all menus in Terminal mode If you want to get rid of the menu bar: > - :set guioptions-=m + :set guioptions-=m -Disabling Menus *disable-menus* +Disabling Menus *disable-menus* - *:menu-disable* *:menu-enable* + *:menu-disable* *:menu-enable* If you do not want to remove a menu, but disable it for a moment, this can be done by adding the "enable" or "disable" keyword to a ":menu" command. Examples: > - :menu disable &File.&Open\.\.\. - :amenu enable * - :amenu disable &Tools.* + :menu disable &File.&Open\.\.\. + :amenu enable * + :amenu disable &Tools.* The command applies to the modes as used with all menu commands. Note that characters like "&" need to be included for translated names to be found. @@ -572,36 +765,36 @@ When the argument is "*", all menus are affected. Otherwise the given menu name and all existing submenus below it are affected. -Examples for Menus *menu-examples* +Examples for Menus *menu-examples* Here is an example on how to add menu items with menus! You can add a menu item for the keyword under the cursor. The register "z" is used. > - :nmenu Words.Add\ Var wb"zye:menu! Words.<C-R>z <C-R>z<CR> - :nmenu Words.Remove\ Var wb"zye:unmenu! Words.<C-R>z<CR> - :vmenu Words.Add\ Var "zy:menu! Words.<C-R>z <C-R>z <CR> - :vmenu Words.Remove\ Var "zy:unmenu! Words.<C-R>z<CR> - :imenu Words.Add\ Var <Esc>wb"zye:menu! Words.<C-R>z <C-R>z<CR>a - :imenu Words.Remove\ Var <Esc>wb"zye:unmenu! Words.<C-R>z<CR>a + :nmenu Words.Add\ Var wb"zye:menu! Words.<C-R>z <C-R>z<CR> + :nmenu Words.Remove\ Var wb"zye:unmenu! Words.<C-R>z<CR> + :vmenu Words.Add\ Var "zy:menu! Words.<C-R>z <C-R>z <CR> + :vmenu Words.Remove\ Var "zy:unmenu! Words.<C-R>z<CR> + :imenu Words.Add\ Var <Esc>wb"zye:menu! Words.<C-R>z <C-R>z<CR>a + :imenu Words.Remove\ Var <Esc>wb"zye:unmenu! Words.<C-R>z<CR>a (the rhs is in <> notation, you can copy/paste this text to try out the mappings, or put these lines in your gvimrc; "<C-R>" is CTRL-R, "<CR>" is the <CR> key. |<>|) - *tooltips* *menu-tips* + *tooltips* *menu-tips* Tooltips & Menu tips See section |42.4| in the user manual. - *:tmenu* -:tm[enu] {menupath} {rhs} Define a tip for a menu or tool. (only in - X11 and Win32 GUI) + *:tmenu* +:tm[enu] {menupath} {rhs} Define a tip for a menu or tool. (only in + X11 and Win32 GUI) -:tm[enu] [menupath] List menu tips. (only in X11 and Win32 GUI) +:tm[enu] [menupath] List menu tips. (only in X11 and Win32 GUI) - *:tunmenu* -:tu[nmenu] {menupath} Remove a tip for a menu or tool. - (only in X11 and Win32 GUI) + *:tunmenu* +:tu[nmenu] {menupath} Remove a tip for a menu or tool. + (only in X11 and Win32 GUI) Note: To create menus for terminal mode, use |:tlmenu| instead. @@ -615,11 +808,11 @@ highlight group to change its colors. A "tip" can be defined for each menu item. For example, when defining a menu item like this: > - :amenu MyMenu.Hello :echo "Hello"<CR> + :amenu MyMenu.Hello :echo "Hello"<CR> The tip is defined like this: > - :tmenu MyMenu.Hello Displays a greeting. + :tmenu MyMenu.Hello Displays a greeting. And delete it with: > - :tunmenu MyMenu.Hello + :tunmenu MyMenu.Hello Tooltips are currently only supported for the X11 and Win32 GUI. However, they should appear for the other gui platforms in the not too distant future. @@ -638,24 +831,24 @@ a menu item - you don't need to do a :tunmenu as well. You can cause a menu to popup at the cursor. This behaves similarly to the PopUp menus except that any menu tree can be popped up. - *:popup* *:popu* -:popu[p] {name} Popup the menu {name}. The menu named must - have at least one subentry, but need not - appear on the menu-bar (see |hidden-menus|). + *:popup* *:popu* +:popu[p] {name} Popup the menu {name}. The menu named must + have at least one subentry, but need not + appear on the menu-bar (see |hidden-menus|). -:popu[p]! {name} Like above, but use the position of the mouse - pointer instead of the cursor. +:popu[p]! {name} Like above, but use the position of the mouse + pointer instead of the cursor. Example: > - :popup File + :popup File will make the "File" menu (if there is one) appear at the text cursor (mouse pointer if ! was used). > - :amenu ]Toolbar.Make :make<CR> - :popup ]Toolbar + :amenu ]Toolbar.Make :make<CR> + :popup ]Toolbar This creates a popup menu that doesn't exist on the main menu-bar. Note that a menu that starts with ']' will not be displayed. - vim:tw=78:sw=4:ts=8:noet:ft=help:norl: + vim:tw=78:sw=4:ts=8:et:ft=help:norl: diff --git a/runtime/doc/health.txt b/runtime/doc/health.txt index cb70961b55..3d37b88321 100644 --- a/runtime/doc/health.txt +++ b/runtime/doc/health.txt @@ -21,7 +21,7 @@ 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[ckhealth] Run all healthchecks. @@ -49,6 +49,23 @@ Commands *health-commands* :checkhealth vim* < +USAGE *health-usage* + +Local mappings in the healthcheck buffer: + +q Closes the window. + +Global configuration: + + *g:health* +g:health Dictionary with the following optional keys: + - `style` (`'float'|nil`) Set to "float" to display :checkhealth in + a floating window instead of the default behavior. + + Example: >lua + vim.g.health = { style = 'float' } + +-------------------------------------------------------------------------------- Create a healthcheck *health-dev* Healthchecks are functions that check the user environment, configuration, or diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index fd8bfd644f..914dc64c0a 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -150,6 +150,7 @@ LANGUAGE SUPPORT |arabic.txt| Arabic language support and editing |hebrew.txt| Hebrew language support and editing |russian.txt| Russian language support and editing +|vietnamese.txt| Vietnamese language support and editing ------------------------------------------------------------------------------ INTEROP diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index 46b3ab507d..72d37f6088 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -193,6 +193,7 @@ Jump to specific subjects by using tags. This can be done in two ways: Use CTRL-T or CTRL-O to jump back. Use ":q" to close the help window. +Use `g==` to execute the current Lua/Vimscript code block. If there are several matches for an item you are looking for, this is how you can jump to each one of them: diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index 9ee75ea950..0256707420 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -1190,7 +1190,7 @@ tag command action ~ |:breakdel| :breakd[el] delete a debugger breakpoint |:breaklist| :breakl[ist] list debugger breakpoints |:browse| :bro[wse] use file selection dialog -|:bufdo| :bufdo execute command in each listed buffer +|:bufdo| :bufd[o] execute command in each listed buffer |:buffers| :buffers list all files in the buffer list |:bunload| :bun[load] unload a specific buffer |:bwipeout| :bw[ipeout] really delete a buffer @@ -1206,7 +1206,7 @@ tag command action ~ |:cafter| :caf[ter] go to error after current cursor |:call| :cal[l] call a function |:catch| :cat[ch] part of a :try command -|:cbefore| :cbef[ore] go to error before current cursor +|:cbefore| :cbe[fore] go to error before current cursor |:cbelow| :cbel[ow] go to error below current line |:cbottom| :cbo[ttom] scroll to the bottom of the quickfix window |:cbuffer| :cb[uffer] parse error messages and jump to first error @@ -1262,6 +1262,7 @@ tag command action ~ |:delete| :d[elete] delete lines |:debug| :deb[ug] run a command in debugging mode |:debuggreedy| :debugg[reedy] read debug mode commands from normal input +|:defer| :defe[r] call function when current function is done |:delcommand| :delc[ommand] delete user-defined command |:delfunction| :delf[unction] delete a user function |:delmarks| :delm[arks] delete marks @@ -1271,7 +1272,7 @@ tag command action ~ |:diffpatch| :diffp[atch] apply a patch and show differences |:diffput| :diffpu[t] remove differences in other buffer |:diffsplit| :diffs[plit] show differences with another file -|:diffthis| :diffthis make current window a diff window +|:diffthis| :difft[his] make current window a diff window |:digraphs| :dig[raphs] show or enter digraphs |:display| :di[splay] display registers |:djump| :dj[ump] jump to #define @@ -1372,7 +1373,7 @@ tag command action ~ |:last| :la[st] go to the last file in the argument list |:language| :lan[guage] set the language (locale) |:later| :lat[er] go to newer change, redo -|:lbefore| :lbef[ore] go to location before current cursor +|:lbefore| :lbe[fore] go to location before current cursor |:lbelow| :lbel[ow] go to location below current line |:lbottom| :lbo[ttom] scroll to the bottom of the location window |:lbuffer| :lb[uffer] parse locations and jump to first location @@ -1410,7 +1411,7 @@ tag command action ~ |:lockmarks| :loc[kmarks] following command keeps marks where they are |:lockvar| :lockv[ar] lock variables |:lolder| :lol[der] go to older location list -|:lopen| :lope[n] open location window +|:lopen| :lop[en] open location window |:lprevious| :lp[revious] go to previous location |:lpfile| :lpf[ile] go to last location in previous file |:lrewind| :lr[ewind] go to the specified location, default first one @@ -1472,6 +1473,7 @@ tag command action ~ |:ownsyntax| :ow[nsyntax] set new local syntax highlight for this window |:packadd| :pa[ckadd] add a plugin from 'packpath' |:packloadall| :packl[oadall] load all packages under 'packpath' +|:pbuffer| :pb[uffer] edit buffer in the preview window |:pclose| :pc[lose] close preview window |:pedit| :ped[it] edit file in the preview window |:perl| :pe[rl] execute perl command @@ -1569,6 +1571,8 @@ tag command action ~ |:sign| :sig[n] manipulate signs |:silent| :sil[ent] run a command silently |:sleep| :sl[eep] do nothing for a few seconds +|:sleep!| :sl[eep]! do nothing for a few seconds, without the + cursor visible |:slast| :sla[st] split window and go to last file in the argument list |:smagic| :sm[agic] :substitute with 'magic' @@ -1615,7 +1619,7 @@ tag command action ~ |:tNext| :tN[ext] jump to previous matching tag |:tabNext| :tabN[ext] go to previous tab page |:tabclose| :tabc[lose] close current tab page -|:tabdo| :tabdo execute command in each tab page +|:tabdo| :tabd[o] execute command in each tab page |:tabedit| :tabe[dit] edit a file in a new tab page |:tabfind| :tabf[ind] find file in 'path', edit it in a new tab page |:tabfirst| :tabfir[st] go to first tab page @@ -1684,7 +1688,7 @@ tag command action ~ |:vsplit| :vs[plit] split current window vertically |:vunmap| :vu[nmap] like ":unmap" but for Visual+Select mode |:vunmenu| :vunme[nu] remove menu for Visual+Select mode -|:windo| :windo execute command in each window +|:windo| :wind[o] execute command in each window |:write| :w[rite] write to a file |:wNext| :wN[ext] write to a file and go to previous file in argument list diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index 48fd442b7e..bc0e9ba314 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -1189,6 +1189,7 @@ items: |hl-PmenuKind| highlight group, allowing for the customization of ctermfg and guifg properties for the completion kind + match See "matches" in |complete_info()|. All of these except "icase", "equal", "dup" and "empty" must be a string. If an item does not meet these requirements then an error message is given and @@ -2026,7 +2027,7 @@ the cursor is, or below the specified line. To insert text above the first line use the command ":0r {name}". After the ":read" command, the cursor is left on the first non-blank in the -first new line. Unless in Ex mode, then the cursor is left on the last new +first new line. If in Ex mode, then the cursor is left on the last new line (sorry, this is Vi compatible). If a file name is given with ":r", it becomes the alternate file. This can be diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index d099c29bdb..0c654b8b30 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -1,15 +1,15 @@ *intro.txt* Nvim - NVIM REFERENCE MANUAL + NVIM REFERENCE MANUAL -Nvim *ref* *reference* +Nvim *ref* *reference* Type |gO| to see the table of contents. ============================================================================== -Introduction *intro* +Introduction *intro* Vim is a text editor which includes most commands from the Unix program "Vi" and many new ones. @@ -21,52 +21,75 @@ It can be accessed from within Vim with the <Help> or <F1> key and with the is not located in the default place. You can jump to subjects like with tags: Use CTRL-] to jump to a subject under the cursor, use CTRL-T to jump back. - *pronounce* + *pronounce* Vim is pronounced as one word, like Jim. So Nvim is "En-Vim", two syllables. This manual is a reference for all Nvim editor and API features. It is not an -introduction; instead for beginners, there is a hands-on |tutor| and a user -manual |usr_toc.txt|. - - *book* -There are many books on Vi and Vim. We recommend: - - "Practical Vim" by Drew Neil - "Modern Vim" by Drew Neil - https://vimcasts.org/publications/ - -"Practical Vim" is acclaimed for its focus on quickly learning common editing -tasks with Vim. "Modern Vim" explores new features in Nvim and Vim 8. - - "Vim - Vi Improved" by Steve Oualline - -This was the first book dedicated to Vim. Parts of it were included in the -user manual. |frombook| ISBN: 0735710015 -For more information try one of these: - https://iccf-holland.org/click5.html - https://www.vim.org/iccf/click5.html - -============================================================================== -Nvim on the interwebs *internet* - - *www* *distribution* *download* - - Nvim home page: https://neovim.io/ - Downloads: https://github.com/neovim/neovim/releases - Vim FAQ: https://vimhelp.org/vim_faq.txt.html - - - *bugs* *bug-report* -Report bugs and request features here: -https://github.com/neovim/neovim/issues - +introduction; instead for beginners, there is a hands-on |tutor|, |lua-guide|, +and |user-manual|. + +------------------------------------------------------------------------------ +Resources *resources* + + *internet* *www* *distribution* +Nvim home page: + + https://neovim.io/ + + *book* +There are many resources to learn Vi, Vim, and Nvim. We recommend: + +- "Practical Vim" by Drew Neil. Acclaimed for its focus on quickly learning + common editing tasks with Vim. +- "Modern Vim" by Drew Neil. Explores new features in Nvim and Vim 8. +- https://vimcasts.org/publications/ +- "Vim - Vi Improved" by Steve Oualline. This was the first book dedicated to + Vim. Parts of it were included in the Vim user manual. |frombook| ISBN: + 0735710015 +- For more information try one of these: + - https://iccf-holland.org/click5.html + - https://www.vim.org/iccf/click5.html +- Vim FAQ: https://vimhelp.org/vim_faq.txt.html + + *bugs* *bug-report* *feature-request* +Report bugs and request features here: https://github.com/neovim/neovim/issues Be brief, yet complete. Always give a reproducible example and try to find -out which settings or other things trigger the bug. +out which settings or other things trigger the bug. If Nvim crashed, try to +get a backtrace (see |dev-tools-backtrace|). -If Nvim crashes, try to get a backtrace. See |debug.txt|. +============================================================================== +Installing Nvim *install* + + *download* *upgrade* *ubuntu* +To install or upgrade Nvim, you can... +- Download a pre-built archive: + https://github.com/neovim/neovim/releases +- Use your system package manager: + https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-package +- Build from source: + https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-source + +------------------------------------------------------------------------------ +Un-installing Nvim *uninstall* + +To uninstall Nvim: +- If you downloaded a pre-built archive or built Nvim from source (e.g. + `make install`), just delete its files, typically located in: > + /usr/local/bin/nvim + /usr/local/share/nvim +< + - To find where Nvim is installed, run these commands: > + :echo v:progpath + :echo $VIMRUNTIME +< +- If you installed via package manager, read your package manager's + documentation. Common examples: + - APT (Debian, Ubuntu, …): `apt-get remove neovim` + - Homebrew (macOS): `brew uninstall neovim` + - Scoop (Windows): `scoop uninstall neovim` ============================================================================== -Sponsor Vim/Nvim development *sponsor* *register* +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 developers to continue working on @@ -78,121 +101,15 @@ motivation to keep working on Vim! For the most recent information about sponsoring look on the Vim web site: - https://www.vim.org/sponsor/ + https://www.vim.org/sponsor/ Nvim development is funded separately from Vim: - https://neovim.io/#sponsor - -============================================================================== -Credits *credits* - -Most of Vim was written by Bram Moolenaar <Bram@vim.org> |Bram-Moolenaar|. - -Parts of the documentation come from several Vi manuals, written by: - W.N. Joy - Alan P.W. Hewett - Mark Horton - -The Vim editor is based on Stevie and includes (ideas from) other software, -worked on by the people mentioned here. Other people helped by sending me -patches, suggestions and giving feedback about what is good and bad in Vim. - -Vim would never have become what it is now, without the help of these people! - - Ron Aaron Win32 GUI changes - Mohsin Ahmed encryption - Zoltan Arpadffy work on VMS port - Tony Andrews Stevie - Gert van Antwerpen changes for DJGPP on MS-DOS - Berkeley DB(3) ideas for swap file implementation - Keith Bostic Nvi - Walter Briscoe Makefile updates, various patches - Ralf Brown SPAWNO library for MS-DOS - Robert Colon many useful remarks - Marcin Dalecki GTK+ GUI port, toolbar icons, gettext() - Kayhan Demirel sent me news in Uganda - Chris & John Downey xvi (ideas for multi-windows version) - Henk Elbers first VMS port - Daniel Elstner GTK+ 2 port - Eric Fischer Mac port, 'cindent', and other improvements - Benji Fisher Answering lots of user questions - Bill Foster Athena GUI port (later removed) - Google Let Bram work on Vim one day a week - Loic Grenie xvim (ideas for multi windows version) - Sven Guckes Vim promoter and previous WWW page maintainer - Darren Hiebert Exuberant ctags - Jason Hildebrand GTK+ 2 port - Bruce Hunsaker improvements for VMS port - Andy Kahn Cscope support, GTK+ GUI port - Oezguer Kesim Maintainer of Vim Mailing Lists - Axel Kielhorn work on the Macintosh port - Steve Kirkendall Elvis - Roger Knobbe original port to Windows NT - Sergey Laskavy Vim's help from Moscow - Felix von Leitner Previous maintainer of Vim Mailing Lists - David Leonard Port of Python extensions to Unix - Avner Lottem Edit in right-to-left windows - Flemming Madsen X11 client-server, various features and patches - Tony Mechelynck answers many user questions - Paul Moore Python interface extensions, many patches - Katsuhito Nagano Work on multibyte versions - Sung-Hyun Nam Work on multibyte versions - Vince Negri Win32 GUI and generic console enhancements - Steve Oualline Author of the first Vim book |frombook| - Dominique Pelle Valgrind reports and many fixes - A.Politz Many bug reports and some fixes - George V. Reilly Win32 port, Win32 GUI start-off - Stephen Riehm bug collector - Stefan Roemer various patches and help to users - Ralf Schandl IBM OS/390 port - Olaf Seibert DICE and BeBox version, regexp improvements - Mortaza Shiran Farsi patches - Peter da Silva termlib - Paul Slootman OS/2 port - Henry Spencer regular expressions - Dany St-Amant Macintosh port - Tim Thompson Stevie - G. R. (Fred) Walter Stevie - Sven Verdoolaege Perl interface - Robert Webb Command-line completion, GUI versions, and - lots of patches - Ingo Wilken Tcl interface - Mike Williams PostScript printing - Juergen Weigert Lattice version, AUX improvements, Unix and - MS-DOS ports, autoconf - Stefan 'Sec' Zehl Maintainer of vim.org - Yasuhiro Matsumoto many MS-Windows improvements - Ken Takata fixes and features - Kazunobu Kuriyama GTK 3 - Christian Brabandt many fixes, features, user support, etc. - Yegappan Lakshmanan many quickfix features - -I wish to thank all the people that sent me bug reports and suggestions. The -list is too long to mention them all here. Vim would not be the same without -the ideas from all these people: They keep Vim alive! -*love* *peace* *friendship* *gross-national-happiness* - - -Documentation may refer to other versions of Vi: - *Vi* *vi* -Vi "the original". Without further remarks this is the version - of Vi that appeared in Sun OS 4.x. ":version" returns - "Version 3.7, 6/7/85". Source code only available with a license. - *Nvi* -Nvi The "New" Vi. The version of Vi that comes with BSD 4.4 and FreeBSD. - Very good compatibility with the original Vi, with a few extensions. - The version used is 1.79. ":version" returns "Version 1.79 - (10/23/96)". Source code is freely available. - *Elvis* -Elvis Another Vi clone, made by Steve Kirkendall. Very compact but isn't - as flexible as Vim. Source code is freely available. - -Vim Nvim is based on Vim. https://www.vim.org/ + https://neovim.io/#sponsor ============================================================================== -Bram Moolenaar *Bram* *Moolenaar* *Bram-Moolenaar* *brammool* +Bram Moolenaar *Bram* *Moolenaar* *Bram-Moolenaar* *brammool* Nvim is a fork of the Vim ("Vi IMproved") text editor, which was originally developed by Bram Moolenaar. Searching his name within the source code of @@ -201,11 +118,11 @@ On August 3, 2023, he passed away at the age of 62. If Vim or Nvim have been of use to you in your life, please read |Uganda| and consider honoring his memory however you may see fit. -Obituary Articles: https://github.com/vim/vim/discussions/12742 -Say Farewell: https://github.com/vim/vim/discussions/12737 +- Obituary Articles: https://github.com/vim/vim/discussions/12742 +- Say Farewell: https://github.com/vim/vim/discussions/12737 ============================================================================== -Notation *notation* +Notation *notation* When syntax highlighting is used to read this, text that is not typed literally is often highlighted with the Special group. These are items in [], @@ -215,177 +132,177 @@ Note that Vim uses all possible characters in commands. Sometimes the [], {} and <> are part of what you type, the context should make this clear. -[] Characters in square brackets are optional. - - *count* *[count]* -[count] An optional number that may precede the command to multiply - or iterate the command. If no number is given, a count of one - is used, unless otherwise noted. Note that in this manual the - [count] is not mentioned in the description of the command, - but only in the explanation. This was done to make the - commands easier to look up. If the 'showcmd' option is on, - the (partially) entered count is shown at the bottom of the - window. You can use <Del> to erase the last digit (|N<Del>|). - - *[quotex]* -["x] An optional register designation where text can be stored. - See |registers|. The x is a single character between 'a' and - 'z' or 'A' and 'Z' or '"', and in some cases (with the put - command) between '0' and '9', '%', '#', or others. The - uppercase and lowercase letter designate the same register, - but the lowercase letter is used to overwrite the previous - register contents, while the uppercase letter is used to - append to the previous register contents. Without the ""x" or - with """" the stored text is put into the unnamed register. - - *{}* -{} Curly braces denote parts of the command which must appear, - but which can take a number of different values. The - differences between Vim and Vi are also given in curly braces - (this will be clear from the context). - - *{char1-char2}* -{char1-char2} A single character from the range char1 to char2. For - example: {a-z} is a lowercase letter. Multiple ranges may be - concatenated. For example, {a-zA-Z0-9} is any alphanumeric - character. - - *{motion}* *movement* -{motion} A command that moves the cursor. These are explained in - |motion.txt|. Examples: - w to start of next word - b to begin of current word - 4j four lines down - /The<CR> to next occurrence of "The" - This is used after an |operator| command to move over the text - that is to be operated upon. - - If the motion includes a count and the operator also has a - count, the two counts are multiplied. For example: "2d3w" - deletes six words. - - The motion can be backwards, e.g. "db" to delete to the - start of the word. - - The motion can also be a mouse click. The mouse is not - supported in every terminal though. - - The ":omap" command can be used to map characters while an - operator is pending. - - Ex commands can be used to move the cursor. This can be - used to call a function that does some complicated motion. - The motion is always charwise exclusive, no matter - what ":" command is used. This means it's impossible to - include the last character of a line without the line break - (unless 'virtualedit' is set). - If the Ex command changes the text before where the operator - starts or jumps to another buffer the result is - unpredictable. It is possible to change the text further - down. Jumping to another buffer is possible if the current - buffer is not unloaded. - - *{Visual}* -{Visual} A selected text area. It is started with the "v", "V", or - CTRL-V command, then any cursor movement command can be used - to change the end of the selected text. - This is used before an |operator| command to highlight the - text that is to be operated upon. - See |Visual-mode|. - - *<character>* -<character> A special character from the table below, optionally with - modifiers, or a single ASCII character with modifiers. - - *'character'* -'c' A single ASCII character. - - *CTRL-{char}* -CTRL-{char} {char} typed as a control character; that is, typing {char} - while holding the CTRL key down. The case of {char} is - ignored; thus CTRL-A and CTRL-a are equivalent. But in - some terminals and environments, using the SHIFT key will - produce a distinct code (e.g. CTRL-SHIFT-a); in these - environments using the SHIFT key will not trigger commands - such as CTRL-A. - - *'option'* -'option' An option, or parameter, that can be set to a value, is - enclosed in single quotes. See |options|. - - *quotecommandquote* -"command" A reference to a command that you can type is enclosed in - double quotes. -`command` New style command, this distinguishes it from other quoted - text and strings. - - *key-notation* *key-codes* *keycodes* +- [] Characters in square brackets are optional. + + *count* *[count]* +- [count] An optional number that may precede the command to multiply + or iterate the command. If no number is given, a count of one + is used, unless otherwise noted. Note that in this manual the + [count] is not mentioned in the description of the command, + but only in the explanation. This was done to make the + commands easier to look up. If the 'showcmd' option is on, + the (partially) entered count is shown at the bottom of the + window. You can use <Del> to erase the last digit (|N<Del>|). + + *[quotex]* +- ["x] An optional register designation where text can be stored. + See |registers|. The x is a single character between 'a' and + 'z' or 'A' and 'Z' or '"', and in some cases (with the put + command) between '0' and '9', '%', '#', or others. The + uppercase and lowercase letter designate the same register, + but the lowercase letter is used to overwrite the previous + register contents, while the uppercase letter is used to + append to the previous register contents. Without the ""x" or + with """" the stored text is put into the unnamed register. + + *{}* +- {} Curly braces denote parts of the command which must appear, + but which can take a number of different values. The + differences between Vim and Vi are also given in curly braces + (this will be clear from the context). + + *{char1-char2}* +- {char1-char2} A single character from the range char1 to char2. For + example: {a-z} is a lowercase letter. Multiple ranges may be + concatenated. For example, {a-zA-Z0-9} is any alphanumeric + character. + + *{motion}* *movement* +- {motion} A command that moves the cursor. These are explained in + |motion.txt|. + - Examples: + - `w` to start of next word + - `b` to begin of current word + - `4j` four lines down + - `/The<CR>` to next occurrence of "The" + - This is used after an |operator| command to move over the + text that is to be operated upon. + - If the motion includes a count and the operator also has + a count, the two counts are multiplied. For example: + "2d3w" deletes six words. + - The motion can be backwards, e.g. "db" to delete to the + start of the word. + - The motion can also be a mouse click. The mouse is not + supported in every terminal though. + - The ":omap" command can be used to map characters while an + operator is pending. + - Ex commands can be used to move the cursor. This can be + used to call a function that does some complicated motion. + The motion is always charwise exclusive, no matter what + ":" command is used. This means it's impossible to + include the last character of a line without the line + break (unless 'virtualedit' is set). If the Ex command + changes the text before where the operator starts or jumps + to another buffer the result is unpredictable. It is + possible to change the text further down. Jumping to + another buffer is possible if the current buffer is not + unloaded. + + *{Visual}* +- {Visual} A selected text area. It is started with the "v", "V", or + CTRL-V command, then any cursor movement command can be used + to change the end of the selected text. + This is used before an |operator| command to highlight the + text that is to be operated upon. + See |Visual-mode|. + + *<character>* +- <character> A special character from the table below, optionally with + modifiers, or a single ASCII character with modifiers. + + *'character'* +- 'c' A single ASCII character. + + *CTRL-{char}* +- CTRL-{char} {char} typed as a control character; that is, typing {char} + while holding the CTRL key down. The case of {char} is + ignored; thus CTRL-A and CTRL-a are equivalent. But in + some terminals and environments, using the SHIFT key will + produce a distinct code (e.g. CTRL-SHIFT-a); in these + environments using the SHIFT key will not trigger commands + such as CTRL-A. + + *'option'* +- 'option' An option, or parameter, that can be set to a value, is + enclosed in single quotes. See |options|. + + *quotecommandquote* +- "command" A reference to a command that you can type is enclosed in + double quotes. +- `command` New style command, this distinguishes it from other quoted + text and strings. + + *key-notation* *key-codes* *keycodes* These names for keys are used in the documentation. They can also be used with the ":map" command. -notation meaning equivalent decimal value(s) ~ ------------------------------------------------------------------------ ~ -<Nul> zero CTRL-@ 0 (stored as 10) *<Nul>* -<BS> backspace CTRL-H 8 *backspace* -<Tab> tab CTRL-I 9 *tab* *Tab* - *linefeed* -<NL> linefeed CTRL-J 10 (used for <Nul>) -<CR> carriage return CTRL-M 13 *carriage-return* -<Return> same as <CR> *<Return>* -<Enter> same as <CR> *<Enter>* -<Esc> escape CTRL-[ 27 *escape* *<Esc>* -<Space> space 32 *space* -<lt> less-than < 60 *<lt>* -<Bslash> backslash \ 92 *backslash* *<Bslash>* -<Bar> vertical bar | 124 *<Bar>* -<Del> delete 127 -<CSI> command sequence intro ALT-Esc 155 *<CSI>* - -<EOL> end-of-line (can be <CR>, <NL> or <CR><NL>, - depends on system and 'fileformat') *<EOL>* -<Ignore> cancel wait-for-character *<Ignore>* -<NOP> no-op: do nothing (useful in mappings) *<Nop>* - -<Up> cursor-up *cursor-up* *cursor_up* -<Down> cursor-down *cursor-down* *cursor_down* -<Left> cursor-left *cursor-left* *cursor_left* -<Right> cursor-right *cursor-right* *cursor_right* -<S-Up> shift-cursor-up -<S-Down> shift-cursor-down -<S-Left> shift-cursor-left -<S-Right> shift-cursor-right -<C-Left> control-cursor-left -<C-Right> control-cursor-right -<F1> - <F12> function keys 1 to 12 *function_key* *function-key* -<S-F1> - <S-F12> shift-function keys 1 to 12 *<S-F1>* -<Help> help key -<Undo> undo key -<Insert> insert key -<Home> home *home* -<End> end *end* -<PageUp> page-up *page_up* *page-up* -<PageDown> page-down *page_down* *page-down* -<kUp> keypad cursor-up *keypad-cursor-up* -<kDown> keypad cursor-down *keypad-cursor-down* -<kLeft> keypad cursor-left *keypad-cursor-left* -<kRight> keypad cursor-right *keypad-cursor-right* -<kHome> keypad home (upper left) *keypad-home* -<kEnd> keypad end (lower left) *keypad-end* -<kOrigin> keypad origin (middle) *keypad-origin* -<kPageUp> keypad page-up (upper right) *keypad-page-up* -<kPageDown> keypad page-down (lower right) *keypad-page-down* -<kDel> keypad delete *keypad-delete* -<kPlus> keypad + *keypad-plus* -<kMinus> keypad - *keypad-minus* -<kMultiply> keypad * *keypad-multiply* -<kDivide> keypad / *keypad-divide* -<kPoint> keypad . *keypad-point* -<kComma> keypad , *keypad-comma* -<kEqual> keypad = *keypad-equal* -<kEnter> keypad Enter *keypad-enter* -<k0> - <k9> keypad 0 to 9 *keypad-0* *keypad-9* -<S-…> shift-key *shift* *<S-* -<C-…> control-key *control* *ctrl* *<C-* -<M-…> alt-key or meta-key *META* *ALT* *<M-* -<A-…> same as <M-…> *<A-* -<T-…> meta-key when it's not alt *<T-* -<D-…> command-key or "super" key *<D-* ------------------------------------------------------------------------ ~ +notation meaning equivalent decimal value(s) ~ +<Nul> zero CTRL-@ 0 (stored as 10) *<Nul>* +<BS> backspace CTRL-H 8 *backspace* +<Tab> tab CTRL-I 9 *tab* *Tab* + *linefeed* +<NL> linefeed CTRL-J 10 (used for <Nul>) +<CR> carriage return CTRL-M 13 *carriage-return* +<Return> same as <CR> *<Return>* +<Enter> same as <CR> *<Enter>* +<Esc> escape CTRL-[ 27 *escape* *<Esc>* +<Space> space 32 *space* +<lt> less-than < 60 *<lt>* +<Bslash> backslash \ 92 *backslash* *<Bslash>* +<Bar> vertical bar | 124 *<Bar>* +<Del> delete 127 +<CSI> command sequence intro ALT-Esc 155 *<CSI>* + +<EOL> end-of-line (can be <CR>, <NL> or <CR><NL>, + depends on system and 'fileformat') *<EOL>* +<Ignore> cancel wait-for-character *<Ignore>* +<NOP> no-op: do nothing (useful in mappings) *<Nop>* + +<Up> cursor-up *cursor-up* *cursor_up* +<Down> cursor-down *cursor-down* *cursor_down* +<Left> cursor-left *cursor-left* *cursor_left* +<Right> cursor-right *cursor-right* *cursor_right* +<S-Up> shift-cursor-up +<S-Down> shift-cursor-down +<S-Left> shift-cursor-left +<S-Right> shift-cursor-right +<C-Left> control-cursor-left +<C-Right> control-cursor-right +<F1> - <F12> function keys 1 to 12 *function_key* *function-key* +<S-F1> - <S-F12> shift-function keys 1 to 12 *<S-F1>* +<Help> help key +<Undo> undo key +<Insert> insert key +<Home> home *home* +<End> end *end* +<PageUp> page-up *page_up* *page-up* +<PageDown> page-down *page_down* *page-down* +<kUp> keypad cursor-up *keypad-cursor-up* +<kDown> keypad cursor-down *keypad-cursor-down* +<kLeft> keypad cursor-left *keypad-cursor-left* +<kRight> keypad cursor-right *keypad-cursor-right* +<kHome> keypad home (upper left) *keypad-home* +<kEnd> keypad end (lower left) *keypad-end* +<kOrigin> keypad origin (middle) *keypad-origin* +<kPageUp> keypad page-up (upper right) *keypad-page-up* +<kPageDown> keypad page-down (lower right) *keypad-page-down* +<kDel> keypad delete *keypad-delete* +<kPlus> keypad + *keypad-plus* +<kMinus> keypad - *keypad-minus* +<kMultiply> keypad * *keypad-multiply* +<kDivide> keypad / *keypad-divide* +<kPoint> keypad . *keypad-point* +<kComma> keypad , *keypad-comma* +<kEqual> keypad = *keypad-equal* +<kEnter> keypad Enter *keypad-enter* +<k0> - <k9> keypad 0 to 9 *keypad-0* *keypad-9* +<S-…> shift-key *shift* *<S-* +<C-…> control-key *control* *ctrl* *<C-* +<M-…> alt-key or meta-key *META* *ALT* *<M-* +<A-…> same as <M-…> *<A-* +<T-…> meta-key when it's not alt *<T-* +<D-…> command-key or "super" key *<D-* + Note: @@ -400,125 +317,125 @@ Note: - It is possible to notate combined modifiers (e.g. <M-C-T> for CTRL-ALT-T), but your terminal must encode the input for that to work. |tui-input| - *<>* + *<>* Examples are often given in the <> notation. Sometimes this is just to make clear what you need to type, but often it can be typed literally, e.g., with the ":map" command. The rules are: - 1. Printable characters are typed directly, except backslash and "<" - 2. Backslash is represented with "\\", double backslash, or "<Bslash>". - 3. Literal "<" is represented with "\<" or "<lt>". When there is no - confusion possible, "<" can be used directly. - 4. "<key>" means the special key typed (see the table above). Examples: - <Esc> Escape key - <C-G> CTRL-G - <Up> cursor up key - <C-LeftMouse> Control- left mouse click - <S-F11> Shifted function key 11 - <M-a> Meta- a ('a' with bit 8 set) - <M-A> Meta- A ('A' with bit 8 set) +1. Printable characters are typed directly, except backslash and "<" +2. Backslash is represented with "\\", double backslash, or "<Bslash>". +3. Literal "<" is represented with "\<" or "<lt>". When there is no + confusion possible, "<" can be used directly. +4. "<key>" means the special key typed (see the table above). Examples: + - <Esc> Escape key + - <C-G> CTRL-G + - <Up> cursor up key + - <C-LeftMouse> Control- left mouse click + - <S-F11> Shifted function key 11 + - <M-a> Meta- a ('a' with bit 8 set) + - <M-A> Meta- A ('A' with bit 8 set) The <> notation uses <lt> to escape the special meaning of key names. Using a backslash also works, but only when 'cpoptions' does not include the 'B' flag. Examples for mapping CTRL-H to the six characters "<Home>": >vim - :imap <C-H> \<Home> - :imap <C-H> <lt>Home> + :imap <C-H> \<Home> + :imap <C-H> <lt>Home> The first one only works when the 'B' flag is not in 'cpoptions'. The second one always works. To get a literal "<lt>" in a mapping: >vim - :map <C-L> <lt>lt> + :map <C-L> <lt>lt> The notation can be used in a double quoted strings, using "\<" at the start, e.g. "\<C-Space>". This results in a special key code. To convert this back to readable text use `keytrans()`. ============================================================================== -Modes, introduction *vim-modes-intro* *vim-modes* +Modes, introduction *vim-modes-intro* *vim-modes* Vim has seven BASIC modes: - *Normal* *Normal-mode* *command-mode* -Normal mode In Normal mode you can enter all the normal editor - commands. If you start the editor you are in this - mode. This is also known as command mode. - -Visual mode This is like Normal mode, but the movement commands - extend a highlighted area. When a non-movement - command is used, it is executed for the highlighted - area. See |Visual-mode|. - If the 'showmode' option is on "-- VISUAL --" is shown - at the bottom of the window. - -Select mode This looks most like the MS-Windows selection mode. - Typing a printable character deletes the selection - and starts Insert mode. See |Select-mode|. - If the 'showmode' option is on "-- SELECT --" is shown - at the bottom of the window. - -Insert mode In Insert mode the text you type is inserted into the - buffer. See |Insert-mode|. - If the 'showmode' option is on "-- INSERT --" is shown - at the bottom of the window. - -Command-line mode In Command-line mode (also called Cmdline mode) you -Cmdline mode can enter one line of text at the bottom of the - window. This is for the Ex commands, ":", the pattern - search commands, "?" and "/", and the filter command, - "!". |Cmdline-mode| - -Ex mode Like Command-line mode, but after entering a command - you remain in Ex mode. Very limited editing of the - command line. |Ex-mode| - - *Terminal-mode* -Terminal mode In Terminal mode all input (except CTRL-\) is sent to - the process running in the current |terminal| buffer. - If CTRL-\ is pressed, the next key is sent unless it - is CTRL-N (|CTRL-\_CTRL-N|) or CTRL-O (|t_CTRL-\_CTRL-O|). - If the 'showmode' option is on "-- TERMINAL --" is shown - at the bottom of the window. + *Normal* *Normal-mode* *command-mode* +- Normal mode: In Normal mode you can enter all the normal editor + commands. If you start the editor you are in this + mode. This is also known as command mode. + +- Visual mode: This is like Normal mode, but the movement commands + extend a highlighted area. When a non-movement + command is used, it is executed for the highlighted + area. See |Visual-mode|. + If the 'showmode' option is on "-- VISUAL --" is shown + at the bottom of the window. + +- Select mode: This looks most like the MS-Windows selection mode. + Typing a printable character deletes the selection + and starts Insert mode. See |Select-mode|. + If the 'showmode' option is on "-- SELECT --" is shown + at the bottom of the window. + +- Insert mode: In Insert mode the text you type is inserted into the + buffer. See |Insert-mode|. + If the 'showmode' option is on "-- INSERT --" is shown + at the bottom of the window. + +- Cmdline mode: In Command-line mode (also called Cmdline mode) you + can enter one line of text at the bottom of the + window. This is for the Ex commands, ":", the pattern + search commands, "?" and "/", and the filter command, + "!". |Cmdline-mode| + +- Ex mode: Like Command-line mode, but after entering a command + you remain in Ex mode. Very limited editing of the + command line. |Ex-mode| + + *Terminal-mode* +- Terminal mode: In Terminal mode all input (except CTRL-\) is sent to + the process running in the current |terminal| buffer. + If CTRL-\ is pressed, the next key is sent unless it + is CTRL-N (|CTRL-\_CTRL-N|) or CTRL-O (|t_CTRL-\_CTRL-O|). + If the 'showmode' option is on "-- TERMINAL --" is shown + at the bottom of the window. There are six ADDITIONAL modes. These are variants of the BASIC modes: - *Operator-pending* *Operator-pending-mode* -Operator-pending mode This is like Normal mode, but after an operator - command has started, and Vim is waiting for a {motion} - to specify the text that the operator will work on. - -Replace mode Replace mode is a special case of Insert mode. You - can do the same things as in Insert mode, but for - each character you enter, one character of the existing - text is deleted. See |Replace-mode|. - If the 'showmode' option is on "-- REPLACE --" is - shown at the bottom of the window. - -Virtual Replace mode Virtual Replace mode is similar to Replace mode, but - instead of file characters you are replacing screen - real estate. See |Virtual-Replace-mode|. - If the 'showmode' option is on "-- VREPLACE --" is - shown at the bottom of the window. - -Insert Normal mode Entered when CTRL-O is typed in Insert mode (see - |i_CTRL-O|). This is like Normal mode, but after - executing one command Vim returns to Insert mode. - If the 'showmode' option is on "-- (insert) --" is - shown at the bottom of the window. - -Insert Visual mode Entered when starting a Visual selection from Insert - mode, e.g., by using CTRL-O and then "v", "V" or - CTRL-V. When the Visual selection ends, Vim returns - to Insert mode. - If the 'showmode' option is on "-- (insert) VISUAL --" - is shown at the bottom of the window. - -Insert Select mode Entered when starting Select mode from Insert mode. - E.g., by dragging the mouse or <S-Right>. - When the Select mode ends, Vim returns to Insert mode. - If the 'showmode' option is on "-- (insert) SELECT --" - is shown at the bottom of the window. + *Operator-pending* *Operator-pending-mode* +- Operator-pending mode: This is like Normal mode, but after an operator + command has started, and Vim is waiting for a {motion} + to specify the text that the operator will work on. + +- Replace mode: Replace mode is a special case of Insert mode. You + can do the same things as in Insert mode, but for + each character you enter, one character of the existing + text is deleted. See |Replace-mode|. + If the 'showmode' option is on "-- REPLACE --" is + shown at the bottom of the window. + +- Virtual Replace mode: Virtual Replace mode is similar to Replace mode, but + instead of file characters you are replacing screen + real estate. See |Virtual-Replace-mode|. + If the 'showmode' option is on "-- VREPLACE --" is + shown at the bottom of the window. + +- Insert Normal mode: Entered when CTRL-O is typed in Insert mode (see + |i_CTRL-O|). This is like Normal mode, but after + executing one command Vim returns to Insert mode. + If the 'showmode' option is on "-- (insert) --" is + shown at the bottom of the window. + +- Insert Visual mode: Entered when starting a Visual selection from Insert + mode, e.g., by using CTRL-O and then "v", "V" or + CTRL-V. When the Visual selection ends, Vim returns + to Insert mode. + If the 'showmode' option is on "-- (insert) VISUAL --" + is shown at the bottom of the window. + +- Insert Select mode: Entered when starting Select mode from Insert mode. + E.g., by dragging the mouse or <S-Right>. + When the Select mode ends, Vim returns to Insert mode. + If the 'showmode' option is on "-- (insert) SELECT --" + is shown at the bottom of the window. ============================================================================== -Switching from mode to mode *mode-switching* +Switching from mode to mode *mode-switching* If for any reason you do not know which mode you are in, you can always get back to Normal mode by typing <Esc> twice. This doesn't work for Ex mode @@ -528,25 +445,27 @@ hear the bell after you type <Esc>. However, when pressing <Esc> after using CTRL-O in Insert mode you get a beep but you are still in Insert mode, type <Esc> again. - *i_esc* - FROM mode TO mode ~ - Normal Visual Select Insert Replace Cmd-line Ex > - Normal v V ^V *4 *1 R gR : / ? ! Q - Visual *2 ^G c C -- : -- - Select *5 ^O ^G *6 -- -- -- - Insert <Esc> -- -- <Insert> -- -- - Replace <Esc> -- -- <Insert> -- -- - Command-line *3 -- -- :start -- -- - Ex :vi -- -- -- -- -- - --- not possible + *i_esc* + > + FROM mode TO mode + Normal Visual Select Insert Replace Cmd-line Ex > + Normal v V ^V *4 *1 R gR : / ? ! Q + Visual *2 ^G c C -- : -- + Select *5 ^O ^G *6 -- -- -- + Insert <Esc> -- -- <Insert> -- -- + Replace <Esc> -- -- <Insert> -- -- + Command-line *3 -- -- :start -- -- + Ex :vi -- -- -- -- -- + + -- not possible +< -* 1 Go from Normal mode to Insert mode by giving the command "i", "I", "a", +- 1 Go from Normal mode to Insert mode by giving the command "i", "I", "a", "A", "o", "O", "c", "C", "s" or S". -* 2 Go from Visual mode to Normal mode by giving a non-movement command, which +- 2 Go from Visual mode to Normal mode by giving a non-movement command, which causes the command to be executed, or by hitting <Esc> "v", "V" or "CTRL-V" (see |v_v|), which just stops Visual mode without side effects. -* 3 Go from Command-line mode to Normal mode by: +- 3 Go from Command-line mode to Normal mode by: - Hitting <CR> or <NL>, which causes the entered command to be executed. - Deleting the complete line (e.g., with CTRL-U) and giving a final <BS>. - Hitting CTRL-C or <Esc>, which quits the command-line without executing @@ -554,37 +473,37 @@ CTRL-O in Insert mode you get a beep but you are still in Insert mode, type In the last case <Esc> may be the character defined with the 'wildchar' option, in which case it will start command-line completion. You can ignore that and type <Esc> again. -* 4 Go from Normal to Select mode by: +- 4 Go from Normal to Select mode by: - use the mouse to select text while 'selectmode' contains "mouse" - use a non-printable command to move the cursor while keeping the Shift key pressed, and the 'selectmode' option contains "key" - use "v", "V" or "CTRL-V" while 'selectmode' contains "cmd" - use "gh", "gH" or "g CTRL-H" |g_CTRL-H| -* 5 Go from Select mode to Normal mode by using a non-printable command to move +- 5 Go from Select mode to Normal mode by using a non-printable command to move the cursor, without keeping the Shift key pressed. -* 6 Go from Select mode to Insert mode by typing a printable character. The +- 6 Go from Select mode to Insert mode by typing a printable character. The selection is deleted and the character is inserted. - *CTRL-\_CTRL-N* *i_CTRL-\_CTRL-N* *c_CTRL-\_CTRL-N* - *v_CTRL-\_CTRL-N* *t_CTRL-\_CTRL-N* + *CTRL-\_CTRL-N* *i_CTRL-\_CTRL-N* *c_CTRL-\_CTRL-N* + *v_CTRL-\_CTRL-N* *t_CTRL-\_CTRL-N* Additionally the command CTRL-\ CTRL-N or <C-\><C-N> can be used to go to Normal mode from any other mode. This can be used to make sure Vim is in Normal mode, without causing a beep like <Esc> would. However, this does not work in Ex mode. When used after a command that takes an argument, such as |f| or |m|, the timeout set with 'ttimeoutlen' applies. - *CTRL-\_CTRL-G* *i_CTRL-\_CTRL-G* *c_CTRL-\_CTRL-G* *v_CTRL-\_CTRL-G* + *CTRL-\_CTRL-G* *i_CTRL-\_CTRL-G* *c_CTRL-\_CTRL-G* *v_CTRL-\_CTRL-G* CTRL-\ CTRL-G works the same as |CTRL-\_CTRL-N| for backward compatibility. - *gQ* *mode-Ex* *Ex-mode* *Ex* *EX* *E501* -gQ Switch to Ex mode. This is like typing ":" commands - one after another, except: - - You don't have to keep pressing ":". - - The screen doesn't get updated after each command. - Use the `:vi` command (|:visual|) to exit this mode. + *gQ* *mode-Ex* *Ex-mode* *Ex* *EX* *E501* +gQ Switch to Ex mode. This is like typing ":" commands + one after another, except: + - You don't have to keep pressing ":". + - The screen doesn't get updated after each command. + Use the `:vi` command (|:visual|) to exit this mode. ============================================================================== -Window contents *window-contents* +Window contents *window-contents* In Normal mode and Insert/Replace mode the screen window will show the current contents of the buffer: What You See Is What You Get. There are two @@ -601,24 +520,24 @@ Lines longer than the window width will wrap, unless the 'wrap' option is off If the window has room after the last line of the buffer, Vim will show '~' in the first column of the last lines in the window, like this: > - +-----------------------+ - |some line | - |last line | - |~ | - |~ | - +-----------------------+ + +-----------------------+ + |some line | + |last line | + |~ | + |~ | + +-----------------------+ < Thus the '~' lines indicate that the end of the buffer was reached. If the last line in a window doesn't fit, Vim will indicate this with a '@' in the first column of the last lines in the window, like this: > - +-----------------------+ - |first line | - |second line | - |@ | - |@ | - +-----------------------+ + +-----------------------+ + |first line | + |second line | + |@ | + |@ | + +-----------------------+ < Thus the '@' lines indicate that there is a line that doesn't fit in the window. @@ -628,12 +547,12 @@ When the "lastline" flag is present in the 'display' option, you will not see completely, only the part that fits is shown, and the last three characters of the last line are replaced with "@@@", like this: > - +-----------------------+ - |first line | - |second line | - |a very long line that d| - |oesn't fit in the wi@@@| - +-----------------------+ + +-----------------------+ + |first line | + |second line | + |a very long line that d| + |oesn't fit in the wi@@@| + +-----------------------+ < If there is a single line that is too long to fit in the window, this is a special situation. Vim will show only part of the line, around where the @@ -646,7 +565,7 @@ from real characters in the buffer. The 'showbreak' option contains the string to put in front of wrapped lines. - *wrap-off* + *wrap-off* If the 'wrap' option is off, long lines will not wrap. Only the part that fits on the screen is shown. If the cursor is moved to a part of the line that is not shown, the screen is scrolled horizontally. The advantage of @@ -665,8 +584,8 @@ position on the screen. The cursor can only be positioned on the first one. If you set the 'number' option, all lines will be preceded with their number. Tip: If you don't like wrapping lines to mix with the line numbers, -set the 'showbreak' option to eight spaces: - ":set showbreak=\ \ \ \ \ \ \ \ " +set the 'showbreak' option to eight spaces: > + ":set showbreak=\ \ \ \ \ \ \ \ " If you set the 'list' option, <Tab> characters will not be shown as several spaces, but as "^I". A '$' will be placed at the end of the line, so you can @@ -677,19 +596,19 @@ display of the buffer contents is updated as soon as you go back to Command mode. The last line of the window is used for status and other messages. The -status messages will only be used if an option is on: +status messages will only be used if an option is on: > -status message option default Unix default ~ -current mode 'showmode' on on -command characters 'showcmd' on off -cursor position 'ruler' off off + status message option default Unix default + current mode 'showmode' on on + command characters 'showcmd' on off + cursor position 'ruler' off off The current mode is "-- INSERT --" or "-- REPLACE --", see |'showmode'|. The command characters are those that you typed but were not used yet. If you have a slow terminal you can switch off the status messages to speed up editing: > - :set nosc noru nosm + :set nosc noru nosm If there is an error, an error message will be shown for at least one second (in reverse video). @@ -704,70 +623,70 @@ small not a single line will fit in it. Make it at least 40 characters wide to be able to read most messages on the last line. ============================================================================== -Definitions *definitions* *jargon* +Definitions *definitions* *jargon* - buffer Contains lines of text, usually from a file. - screen The whole area that Nvim uses to display things. - window A view on a buffer. There can be multiple windows for - one buffer. - frame Windows are kept in a tree of frames. Each frame - contains a column, row, or window ("leaf" frame). +- buffer: Contains lines of text, usually from a file. +- screen: The whole area that Nvim uses to display things. +- window: A view on a buffer. There can be multiple windows for one buffer. +- frame: Windows are kept in a tree of frames. Each frame contains a column, + row, or window ("leaf" frame). A screen contains one or more windows, separated by status lines and with the command line at the bottom. > - +-------------------------------+ - screen | window 1 | window 2 | - | | | - | | | - |= status line =|= status line =| - | window 3 | - | | - | | - |==== status line ==============| - |command line | - +-------------------------------+ + +-------------------------------+ + screen | window 1 | window 2 | + | | | + | | | + |= status line =|= status line =| + | window 3 | + | | + | | + |==== status line ==============| + |command line | + +-------------------------------+ < The command line is also used for messages. It scrolls up the screen when there is not enough room in the command line. A difference is made between four types of lines: - buffer lines The lines in the buffer. This is the same as the - lines as they are read from/written to a file. They - can be thousands of characters long. - logical lines The buffer lines with folding applied. Buffer lines - in a closed fold are changed to a single logical line: - "+-- 99 lines folded". They can be thousands of - characters long. - window lines The lines displayed in a window: A range of logical - lines with wrapping, line breaks, etc. applied. They - can only be as long as the width of the window allows, - longer lines are wrapped or truncated. - screen lines The lines of the screen that Nvim uses. Consists of - the window lines of all windows, with status lines - and the command line added. They can only be as long - as the width of the screen allows. When the command - line gets longer it wraps and lines are scrolled to - make room. - -buffer lines logical lines window lines screen lines ~ - -1. one 1. one 1. +-- folded 1. +-- folded -2. two 2. +-- folded 2. five 2. five -3. three 3. five 3. six 3. six -4. four 4. six 4. seven 4. seven -5. five 5. seven 5. === status line === -6. six 6. aaa -7. seven 7. bbb - 8. ccc ccc c -1. aaa 1. aaa 1. aaa 9. cc -2. bbb 2. bbb 2. bbb 10. ddd -3. ccc ccc ccc 3. ccc ccc ccc 3. ccc ccc c 11. ~ -4. ddd 4. ddd 4. cc 12. === status line === - 5. ddd 13. (command line) - 6. ~ +- buffer lines: The lines in the buffer. This is the same as the + lines as they are read from/written to a file. They + can be thousands of characters long. +- logical lines: The buffer lines with folding applied. Buffer lines + in a closed fold are changed to a single logical line: + "+-- 99 lines folded". They can be thousands of + characters long. +- window lines: The lines displayed in a window: A range of logical + lines with wrapping, line breaks, etc. applied. They + can only be as long as the width of the window allows, + longer lines are wrapped or truncated. +- screen lines: The lines of the screen that Nvim uses. Consists of + the window lines of all windows, with status lines + and the command line added. They can only be as long + as the width of the screen allows. When the command + line gets longer it wraps and lines are scrolled to + make room. +> + buffer lines logical lines window lines screen lines + ----------------------------------------------------------------------- + 1. one 1. one 1. +-- folded 1. +-- folded + 2. two 2. +-- folded 2. five 2. five + 3. three 3. five 3. six 3. six + 4. four 4. six 4. seven 4. seven + 5. five 5. seven 5. === status line === + 6. six 6. aaa + 7. seven 7. bbb + 8. ccc ccc c + 1. aaa 1. aaa 1. aaa 9. cc + 2. bbb 2. bbb 2. bbb 10. ddd + 3. ccc ccc ccc 3. ccc ccc ccc 3. ccc ccc c 11. ~ + 4. ddd 4. ddd 4. cc 12. === status line === + 5. ddd 13. (command line) + 6. ~ +< API client ~ All external UIs and remote plugins (as opposed to regular Vim plugins) are @@ -775,8 +694,8 @@ All external UIs and remote plugins (as opposed to regular Vim plugins) are to abstract or wrap the RPC API for the convenience of other applications (just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST using an HTTP client like curl, but boto3 wraps that in a convenient python -interface). For example, the Nvim lua-client is an API client: - https://github.com/neovim/lua-client +interface). For example, the Nvim node-client is an API client: + https://github.com/neovim/node-client Host ~ @@ -791,4 +710,4 @@ process and communicates with Nvim via the |api|. ============================================================================== - vim:tw=78:ts=8:noet:ft=help:norl: + vim:tw=78:ts=8:et:sw=4:ft=help:norl: diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 64bef849fc..25ef7f24cc 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -28,31 +28,110 @@ Follow these steps to get LSP features: upstream installation instructions. You can find language servers here: https://microsoft.github.io/language-server-protocol/implementors/servers/ -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(args) - 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 (`args.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(args.buf, {'setup.py', 'pyproject.toml'}), - }) - end, - }) +2. Use |vim.lsp.config()| to define a configuration for an LSP client. + Example: >lua + vim.lsp.config['luals'] = { + -- Command and arguments to start the server. + cmd = { 'lua-language-server' }, + + -- Filetypes to automatically attach to. + filetypes = { 'lua' }, + + -- Sets the "root directory" to the parent directory of the file in the + -- current buffer that contains either a ".luarc.json" or a + -- ".luarc.jsonc" file. Files that share a root directory will reuse + -- the connection to the same LSP server. + root_markers = { '.luarc.json', '.luarc.jsonc' }, + + -- Specific settings to send to the server. The schema for this is + -- defined by the server. For example the schema for lua-language-server + -- can be found here https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json + settings = { + Lua = { + runtime = { + version = 'LuaJIT', + } + } + } + } +< +3. Use |vim.lsp.enable()| to enable a configuration. + Example: >lua + vim.lsp.enable('luals') +< +4. Check that the buffer is attached to the server: >vim + :checkhealth vim.lsp < -3. Check that the buffer is attached to the server: >vim - :checkhealth lsp +5. (Optional) Configure keymaps and autocommands to use LSP features. + |lsp-attach| + + *lsp-config* + +Configurations for LSP clients is done via |vim.lsp.config()|. + +When an LSP client starts, it resolves a configuration by merging +configurations, in increasing priority, from the following: + +1. Configuration defined for the `'*'` name. + +2. Configuration from the result of merging all tables returned by + `lsp/<name>.lua` files in 'runtimepath' for a server of name `name`. + +3. Configurations defined anywhere else. + +Note: The merge semantics of configurations follow the behaviour of +|vim.tbl_deep_extend()|. -4. (Optional) Configure keymaps and autocommands to use LSP features. |lsp-config| +Example: +Given: >lua + -- Defined in init.lua + vim.lsp.config('*', { + capabilities = { + textDocument = { + semanticTokens = { + multilineTokenSupport = true, + } + } + }, + root_markers = { '.git' }, + }) + + -- Defined in ../lsp/clangd.lua + return { + cmd = { 'clangd' }, + root_markers = { '.clangd', 'compile_commands.json' }, + filetypes = { 'c', 'cpp' }, + } + + -- Defined in init.lua + vim.lsp.config('clangd', { + filetypes = { 'c' }, + }) +< +Results in the configuration: >lua + { + -- From the clangd configuration in <rtp>/lsp/clangd.lua + cmd = { 'clangd' }, + + -- From the clangd configuration in <rtp>/lsp/clangd.lua + -- Overrides the * configuration in init.lua + root_markers = { '.clangd', 'compile_commands.json' }, + + -- From the clangd configuration in init.lua + -- Overrides the * configuration in init.lua + filetypes = { 'c' }, + + -- From the * configuration in init.lua + capabilities = { + textDocument = { + semanticTokens = { + multilineTokenSupport = true, + } + } + } + } +< *lsp-defaults* When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see |vim.diagnostic.config()| to customize). It also sets various default options, @@ -98,7 +177,7 @@ To override or delete any of the above defaults, set or unset the options on end, }) < - *lsp-config* + *lsp-attach* To use other LSP features, set keymaps and other buffer options on |LspAttach|. Not all language servers provide the same capabilities. Use capability checks to ensure you only use features supported by the language @@ -107,16 +186,16 @@ server. Example: >lua vim.api.nvim_create_autocmd('LspAttach', { callback = function(args) local client = vim.lsp.get_client_by_id(args.data.client_id) - if client.supports_method('textDocument/implementation') then + if client:supports_method('textDocument/implementation') then -- Create a keymap for vim.lsp.buf.implementation end - if client.supports_method('textDocument/completion') then + if client:supports_method('textDocument/completion') then -- Enable auto-completion vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true}) end - if client.supports_method('textDocument/formatting') then + if client:supports_method('textDocument/formatting') then -- Format the current buffer on save vim.api.nvim_create_autocmd('BufWritePre', { buffer = args.buf, @@ -204,6 +283,7 @@ won't run if your server doesn't support them. - `'textDocument/diagnostic'` - `'textDocument/documentHighlight'` - `'textDocument/documentSymbol'` +- `'textDocument/foldingRange'` - `'textDocument/formatting'` - `'textDocument/hover'` - `'textDocument/implementation'` @@ -264,22 +344,17 @@ Each response handler has this signature: > *lsp-handler-resolution* Handlers can be set by (in increasing priority): -- Setting a field in vim.lsp.handlers. *vim.lsp.handlers* - `vim.lsp.handlers` is a global table that contains the default mapping of - |lsp-method| names to lsp-handlers. - + *vim.lsp.handlers* +- Setting a field in `vim.lsp.handlers`. This global table contains the + default mappings of |lsp-method| names to handlers. (Note: only for + server-to-client requests/notifications, not client-to-server.) Example: >lua - vim.lsp.handlers['textDocument/publishDiagnostics'] = my_custom_diagnostics_handler < - Note: this only applies for requests/notifications made by the - server to the client. - -- The {handlers} parameter of |vim.lsp.start()|. This sets the default - |lsp-handler| for a specific server. - +- Passing a {handlers} parameter to |vim.lsp.start()|. This sets the default + |lsp-handler| for a specific server. (Note: only for server-to-client + requests/notifications, not client-to-server.) Example: >lua - vim.lsp.start { ..., -- Other configuration omitted. handlers = { @@ -287,14 +362,9 @@ Handlers can be set by (in increasing priority): }, } < - Note: this only applies for requests/notifications made by the - server to the client. - -- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets - the |lsp-handler| ONLY for the given request(s). - +- Passing a {handler} parameter to |vim.lsp.buf_request_all()|. This sets the + |lsp-handler| ONLY for the given request(s). Example: >lua - vim.lsp.buf_request_all( 0, 'textDocument/publishDiagnostics', @@ -464,7 +534,7 @@ EVENTS *lsp-events* LspAttach *LspAttach* After an LSP client attaches to a buffer. The |autocmd-pattern| is the name of the buffer. When used from Lua, the client ID is passed to the - callback in the "data" table. See |lsp-config| for an example. + callback in the "data" table. See |lsp-attach| for an example. LspDetach *LspDetach* Just before an LSP client detaches from a buffer. The |autocmd-pattern| @@ -477,7 +547,7 @@ LspDetach *LspDetach* local client = vim.lsp.get_client_by_id(args.data.client_id) -- Remove the autocommand to format the buffer on save, if it exists - if client.supports_method('textDocument/formatting') then + if client:supports_method('textDocument/formatting') then vim.api.nvim_clear_autocmds({ event = 'BufWritePre', buffer = args.buf, @@ -589,6 +659,34 @@ LspTokenUpdate *LspTokenUpdate* ============================================================================== Lua module: vim.lsp *lsp-core* +*vim.lsp.Config* + Extends: |vim.lsp.ClientConfig| + + + Fields: ~ + • {cmd}? (`string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers): vim.lsp.rpc.PublicClient`) + See `cmd` in |vim.lsp.ClientConfig|. + • {filetypes}? (`string[]`) Filetypes the client will attach to, if + activated by `vim.lsp.enable()`. If not provided, + then the client will attach to all filetypes. + • {root_markers}? (`string[]`) Directory markers (.e.g. '.git/') where + the LSP server will base its workspaceFolders, + rootUri, and rootPath on initialization. Unused if + `root_dir` is provided. + • {root_dir}? (`string|fun(cb:fun(string))`) Directory where the + LSP server will base its workspaceFolders, rootUri, + and rootPath on initialization. If a function, it + accepts a single callback argument which must be + called with the value of root_dir to use. The LSP + server will not be started until the callback is + called. + • {reuse_client}? (`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. + + buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()* Implements the `textDocument/did…` notifications required to track a buffer for any language server. @@ -688,7 +786,7 @@ commands *vim.lsp.commands* value is a function which is called if any LSP action (code action, code lenses, ...) triggers the command. - If a LSP response contains a command for which no matching entry is + If an LSP response contains a command for which no matching entry is available in this registry, the command will be executed via the LSP server using `workspace/executeCommand`. @@ -697,6 +795,108 @@ commands *vim.lsp.commands* The second argument is the `ctx` of |lsp-handler| +config({name}, {cfg}) *vim.lsp.config()* + Update the configuration for an LSP client. + + Use name '*' to set default configuration for all clients. + + Can also be table-assigned to redefine the configuration for a client. + + Examples: + • Add a root marker for all clients: >lua + vim.lsp.config('*', { + root_markers = { '.git' }, + }) +< + • Add additional capabilities to all clients: >lua + vim.lsp.config('*', { + capabilities = { + textDocument = { + semanticTokens = { + multilineTokenSupport = true, + } + } + } + }) +< + • (Re-)define the configuration for clangd: >lua + vim.lsp.config.clangd = { + cmd = { + 'clangd', + '--clang-tidy', + '--background-index', + '--offset-encoding=utf-8', + }, + root_markers = { '.clangd', 'compile_commands.json' }, + filetypes = { 'c', 'cpp' }, + } +< + • Get configuration for luals: >lua + local cfg = vim.lsp.config.luals +< + + Parameters: ~ + • {name} (`string`) + • {cfg} (`vim.lsp.Config`) See |vim.lsp.Config|. + +enable({name}, {enable}) *vim.lsp.enable()* + Enable an LSP server to automatically start when opening a buffer. + + Uses configuration defined with `vim.lsp.config`. + + Examples: >lua + vim.lsp.enable('clangd') + + vim.lsp.enable({'luals', 'pyright'}) +< + + Parameters: ~ + • {name} (`string|string[]`) Name(s) of client(s) to enable. + • {enable} (`boolean?`) `true|nil` to enable, `false` to disable. + +foldclose({kind}, {winid}) *vim.lsp.foldclose()* + Close all {kind} of folds in the the window with {winid}. + + To automatically fold imports when opening a file, you can use an autocmd: >lua + vim.api.nvim_create_autocmd('LspNotify', { + callback = function(args) + if args.data.method == 'textDocument/didOpen' then + vim.lsp.foldclose('imports', vim.fn.bufwinid(args.buf)) + end + end, + }) +< + + Parameters: ~ + • {kind} (`lsp.FoldingRangeKind`) Kind to close, one of "comment", + "imports" or "region". + • {winid} (`integer?`) Defaults to the current window. + +foldexpr({lnum}) *vim.lsp.foldexpr()* + Provides an interface between the built-in client and a `foldexpr` + function. + + To use, check for the "textDocument/foldingRange" capability in an + |LspAttach| autocommand. Example: >lua + vim.api.nvim_create_autocmd('LspAttach', { + callback = function(args) + local client = vim.lsp.get_client_by_id(args.data.client_id) + if client:supports_method('textDocument/foldingRange') then + local win = vim.api.nvim_get_current_win() + vim.wo[win][0].foldmethod = 'expr' + vim.wo[win][0].foldexpr = 'v:lua.vim.lsp.foldexpr()' + end + end, + }) +< + + Parameters: ~ + • {lnum} (`integer`) line number + +foldtext() *vim.lsp.foldtext()* + Provides a `foldtext` function that shows the `collapsedText` retrieved, + defaults to the first folded line if `collapsedText` is not provided. + formatexpr({opts}) *vim.lsp.formatexpr()* Provides an interface between the built-in client and a `formatexpr` function. @@ -798,12 +998,11 @@ start({config}, {opts}) *vim.lsp.start()* }) < - See |vim.lsp.start_client()| for all available options. The most important + See |vim.lsp.ClientConfig| for all available options. The most important are: • `name` arbitrary name for the LSP client. Should be unique per language server. - • `cmd` command string[] or function, described at - |vim.lsp.start_client()|. + • `cmd` command string[] or function. • `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.root()| to detect the root by traversing the file system upwards @@ -825,33 +1024,25 @@ start({config}, {opts}) *vim.lsp.start()* Parameters: ~ • {config} (`vim.lsp.ClientConfig`) Configuration for the server. See |vim.lsp.ClientConfig|. - • {opts} (`table?`) Optional keyword arguments + • {opts} (`table?`) Optional keyword arguments. • {reuse_client}? (`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. + re-uses a client if it has the same name and if the given + workspace folders (or root_dir) are all included in the + client's workspace folders. • {bufnr}? (`integer`) Buffer handle to attach to if starting or re-using a client (0 for current). + • {attach}? (`boolean`) Whether to attach the client to a + buffer (default true). If set to `false`, `reuse_client` + and `bufnr` will be ignored. • {silent}? (`boolean`) Suppress error reporting if the LSP server fails to start (default false). Return: ~ (`integer?`) client_id -start_client({config}) *vim.lsp.start_client()* - Starts and initializes a client with the given configuration. - - Parameters: ~ - • {config} (`vim.lsp.ClientConfig`) Configuration for the server. See - |vim.lsp.ClientConfig|. - - 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 a string. Empty if there are no clients or if no new messages @@ -904,14 +1095,15 @@ Lua module: vim.lsp.client *lsp-client* • {rpc} (`vim.lsp.rpc.PublicClient`) RPC client object, for low level interaction with the client. See |vim.lsp.rpc.start()|. - • {offset_encoding} (`string`) The encoding used for communicating - with the server. You can modify this in the + • {offset_encoding} (`string`) Called "position encoding" in LSP + spec, the encoding used for communicating with + the server. You can modify this in the `config`'s `on_init` method before text is sent to the server. • {handlers} (`table<string,lsp.Handler>`) The handlers used by the client as described in |lsp-handler|. - • {requests} (`table<integer,{ type: string, bufnr: integer, method: string}>`) + • {requests} (`table<integer,{ type: string, bufnr: integer, method: string}?>`) The current pending requests in flight to the server. Entries are key-value pairs with the key being the request id while the value is a @@ -924,11 +1116,13 @@ Lua module: vim.lsp.client *lsp-client* server. • {config} (`vim.lsp.ClientConfig`) copy of the table that was passed by the user to - |vim.lsp.start_client()|. See - |vim.lsp.ClientConfig|. + |vim.lsp.start()|. See |vim.lsp.ClientConfig|. • {server_capabilities} (`lsp.ServerCapabilities?`) Response from the server sent on `initialize` describing the server's capabilities. + • {server_info} (`lsp.ServerInfo?`) Response from the server + sent on `initialize` describing information + about the server. • {progress} (`vim.lsp.Client.Progress`) A ring buffer (|vim.ringbuf()|) containing progress messages sent by the server. See @@ -948,9 +1142,9 @@ Lua module: vim.lsp.client *lsp-client* lenses, ...) triggers the command. Client commands take precedence over the global command registry. - • {settings} (`table`) Map with language server specific - settings. These are returned to the language - server if requested via + • {settings} (`lsp.LSPObject`) Map with language server + specific settings. These are returned to the + language server if requested via `workspace/configuration`. Keys are case-sensitive. • {flags} (`table`) A table with flags for the client. @@ -972,54 +1166,24 @@ 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?`) - Sends a request to the server. This is a thin - wrapper around {client.rpc.request} with some - additional checking. If {handler} is not - specified and if there's no respective global - handler, then an error will occur. Returns: - {status}, {client_id}?. {status} is a boolean - indicating if the notification was successful. - If it is `false`, then it will always be - `false` (the client has shutdown). If {status} - is `true`, the function returns {request_id} - as the second result. You can use this with - `client.cancel_request(request_id)` to cancel - the request. - • {request_sync} (`fun(method: string, params: table?, timeout_ms: integer?, bufnr: integer): {err: lsp.ResponseError?, result:any}?, string?`) - err # a dict - • {notify} (`fun(method: string, params: table?): boolean`) - Sends a notification to an LSP server. - Returns: a boolean to indicate if the - notification was successful. If it is false, - then it will always be false (the client has - shutdown). - • {cancel_request} (`fun(id: integer): boolean`) Cancels a - request with a given request id. Returns: same - as `notify()`. - • {stop} (`fun(force?: boolean)`) Stops a client, - optionally with force. By default, it will - just ask the server to shutdown without force. - If you request to stop a client which has - previously been requested to shutdown, it will - automatically escalate and force shutdown. - • {on_attach} (`fun(bufnr: integer)`) Runs the on_attach - function from the client's config if it was - defined. Useful for buffer-local setup. - • {supports_method} (`fun(method: string, opts?: {bufnr: integer?}): boolean`) - Checks if a client supports a given method. - Always returns true for unknown off-spec - methods. {opts} is a optional - `{bufnr?: integer}` table. Some language - server capabilities can be file specific. - • {is_stopped} (`fun(): boolean`) Checks whether a client is - stopped. Returns: true if the client is fully - stopped. + • {request} (`fun(self: vim.lsp.Client, method: string, params: table?, handler: lsp.Handler?, bufnr: integer?): boolean, integer?`) + See |Client:request()|. + • {request_sync} (`fun(self: vim.lsp.Client, method: string, params: table, timeout_ms: integer?, bufnr: integer?): {err: lsp.ResponseError?, result:any}?, string?`) + See |Client:request_sync()|. + • {notify} (`fun(self: vim.lsp.Client, method: string, params: table?): boolean`) + See |Client:notify()|. + • {cancel_request} (`fun(self: vim.lsp.Client, id: integer): boolean`) + See |Client:cancel_request()|. + • {stop} (`fun(self: vim.lsp.Client, force: boolean?)`) + See |Client:stop()|. + • {is_stopped} (`fun(self: vim.lsp.Client): boolean`) See + |Client:is_stopped()|. • {exec_cmd} (`fun(self: vim.lsp.Client, command: lsp.Command, context: {bufnr?: integer}?, handler: lsp.Handler?)`) - Execute a lsp command, either via client - command function (if available) or via - workspace/executeCommand (if supported by the - server) + See |Client:exec_cmd()|. + • {on_attach} (`fun(self: vim.lsp.Client, bufnr: integer)`) + See |Client:on_attach()|. + • {supports_method} (`fun(self: vim.lsp.Client, method: string, bufnr: integer?)`) + See |Client:supports_method()|. *vim.lsp.Client.Progress* Extends: |vim.Ringbuf| @@ -1073,28 +1237,30 @@ Lua module: vim.lsp.client *lsp-client* an array. • {handlers}? (`table<string,function>`) Map of language server method names to |lsp-handler| - • {settings}? (`table`) Map with language server specific - settings. See the {settings} in + • {settings}? (`lsp.LSPObject`) Map with language server + specific settings. See the {settings} in |vim.lsp.Client|. • {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`) Table that maps string of clientside commands to user-defined functions. Commands passed to - start_client take precedence over the global + `start()` take precedence over the global command registry. Each key must be a unique command name, and the value is a function which is called if any LSP action (code action, code lenses, ...) triggers the command. - • {init_options}? (`table`) Values to pass in the initialization - request as `initializationOptions`. See - `initialize` in the LSP spec. + • {init_options}? (`lsp.LSPObject`) Values to pass in the + initialization request as + `initializationOptions`. See `initialize` in the + LSP spec. • {name}? (`string`, default: client-id) Name in log messages. • {get_language_id}? (`fun(bufnr: integer, filetype: string): string`) Language ID as string. Defaults to the buffer filetype. - • {offset_encoding}? (`'utf-8'|'utf-16'|'utf-32'`) The encoding that - the LSP server expects. Client does not verify - this is correct. + • {offset_encoding}? (`'utf-8'|'utf-16'|'utf-32'`) Called "position + encoding" in LSP spec, the encoding that the LSP + server expects. Client does not verify this is + correct. • {on_error}? (`fun(code: integer, err: string)`) Callback invoked when the client operation throws an error. `code` is a number describing the error. @@ -1107,9 +1273,9 @@ Lua module: vim.lsp.client *lsp-client* Callback invoked before the LSP "initialize" phase, where `params` contains the parameters being sent to the server and `config` is the - config that was passed to - |vim.lsp.start_client()|. You can use this to - modify parameters before they are sent. + config that was passed to |vim.lsp.start()|. You + can use this to modify parameters before they + are sent. • {on_init}? (`elem_or_list<fun(client: vim.lsp.Client, initialize_result: lsp.InitializeResult)>`) Callback invoked after LSP "initialize", where `result` is a table of `capabilities` and @@ -1150,6 +1316,18 @@ Lua module: vim.lsp.client *lsp-client* on initialization. +Client:cancel_request({id}) *Client:cancel_request()* + Cancels a request with a given request id. + + Parameters: ~ + • {id} (`integer`) id of request to cancel + + Return: ~ + (`boolean`) status indicating if the notification was successful. + + See also: ~ + • |Client:notify()| + Client:exec_cmd({command}, {context}, {handler}) *Client:exec_cmd()* Execute a lsp command, either via client command function (if available) or via workspace/executeCommand (if supported by the server) @@ -1159,6 +1337,96 @@ Client:exec_cmd({command}, {context}, {handler}) *Client:exec_cmd()* • {context} (`{bufnr?: integer}?`) • {handler} (`lsp.Handler?`) only called if a server command +Client:is_stopped() *Client:is_stopped()* + Checks whether a client is stopped. + + Return: ~ + (`boolean`) true if client is stopped or in the process of being + stopped; false otherwise + +Client:notify({method}, {params}) *Client:notify()* + Sends a notification to an LSP server. + + Parameters: ~ + • {method} (`string`) LSP method name. + • {params} (`table?`) LSP request params. + + Return: ~ + (`boolean`) status indicating if the notification was successful. If + it is false, then the client has shutdown. + +Client:on_attach({bufnr}) *Client:on_attach()* + Runs the on_attach function from the client's config if it was defined. + Useful for buffer-local setup. + + Parameters: ~ + • {bufnr} (`integer`) Buffer number + + *Client:request()* +Client:request({method}, {params}, {handler}, {bufnr}) + Sends a request to the server. + + This is a thin wrapper around {client.rpc.request} with some additional + checks for capabilities and handler availability. + + Parameters: ~ + • {method} (`string`) LSP method name. + • {params} (`table?`) LSP request params. + • {handler} (`lsp.Handler?`) Response |lsp-handler| for this method. + • {bufnr} (`integer?`) (default: 0) Buffer handle, or 0 for current. + + Return (multiple): ~ + (`boolean`) status indicates whether the request was successful. If it + is `false`, then it will always be `false` (the client has shutdown). + (`integer?`) request_id Can be used with |Client:cancel_request()|. + `nil` is request failed. + + See also: ~ + • |vim.lsp.buf_request_all()| + + *Client:request_sync()* +Client:request_sync({method}, {params}, {timeout_ms}, {bufnr}) + Sends a request to the server and synchronously waits for the response. + + This is a wrapper around |Client:request()| + + Parameters: ~ + • {method} (`string`) LSP method name. + • {params} (`table`) LSP request params. + • {timeout_ms} (`integer?`) Maximum time in milliseconds to wait for a + result. Defaults to 1000 + • {bufnr} (`integer?`) (default: 0) Buffer handle, or 0 for + current. + + Return (multiple): ~ + (`{err: lsp.ResponseError?, result:any}?`) `result` and `err` from the + |lsp-handler|. `nil` is the request was unsuccessful + (`string?`) err On timeout, cancel or error, where `err` is a string + describing the failure reason. + + See also: ~ + • |vim.lsp.buf_request_sync()| + +Client:stop({force}) *Client:stop()* + Stops a client, optionally with force. + + By default, it will just request the server to shutdown without force. If + you request to stop a client which has previously been requested to + shutdown, it will automatically escalate and force shutdown. + + Parameters: ~ + • {force} (`boolean?`) + +Client:supports_method({method}, {bufnr}) *Client:supports_method()* + Checks if a client supports a given method. Always returns true for + unknown off-spec methods. + + Note: Some language server capabilities can be file specific. + + Parameters: ~ + • {method} (`string`) + • {bufnr} (`integer?`) + ============================================================================== Lua module: vim.lsp.buf *lsp-buf* @@ -1178,12 +1446,11 @@ Lua module: vim.lsp.buf *lsp-buf* vim.lsp.buf.definition({ on_list = on_list }) vim.lsp.buf.references(nil, { on_list = on_list }) < - - If you prefer loclist instead of qflist: >lua + • {loclist}? (`boolean`) Whether to use the |location-list| or the + |quickfix| list in the default handler. >lua vim.lsp.buf.definition({ loclist = true }) - vim.lsp.buf.references(nil, { loclist = true }) + vim.lsp.buf.references(nil, { loclist = false }) < - • {loclist}? (`boolean`) *vim.lsp.LocationOpts* Extends: |vim.lsp.ListOpts| @@ -1286,7 +1553,7 @@ document_highlight() *vim.lsp.buf.document_highlight()* |hl-LspReferenceWrite| document_symbol({opts}) *vim.lsp.buf.document_symbol()* - Lists all symbols in the current buffer in the quickfix window. + Lists all symbols in the current buffer in the |location-list|. Parameters: ~ • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. @@ -1312,7 +1579,7 @@ format({opts}) *vim.lsp.buf.format()* predicate are included. Example: >lua -- Never request typescript-language-server for formatting vim.lsp.buf.format { - filter = function(client) return client.name ~= "tsserver" end + filter = function(client) return client.name ~= "ts_ls" end } < • {async}? (`boolean`, default: false) If true the method @@ -1375,7 +1642,7 @@ references({context}, {opts}) *vim.lsp.buf.references()* window. Parameters: ~ - • {context} (`table?`) Context for the request + • {context} (`lsp.ReferenceContext?`) Context for the request • {opts} (`vim.lsp.ListOpts?`) See |vim.lsp.ListOpts|. See also: ~ @@ -1461,12 +1728,13 @@ get_namespace({client_id}, {is_pull}) client. Defaults to push *vim.lsp.diagnostic.on_diagnostic()* -on_diagnostic({_}, {result}, {ctx}) +on_diagnostic({error}, {result}, {ctx}) |lsp-handler| for the method "textDocument/diagnostic" See |vim.diagnostic.config()| for configuration options. Parameters: ~ + • {error} (`lsp.ResponseError?`) • {result} (`lsp.DocumentDiagnosticReport`) • {ctx} (`lsp.HandlerContext`) @@ -1599,12 +1867,12 @@ 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) - local resp = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0) + 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 - client.request('textDocument/hover', { + client:request('textDocument/hover', { textDocument = { uri = location.uri }, position = location.range.start, }) @@ -1756,7 +2024,7 @@ Lua module: vim.lsp.util *lsp-util* • {zindex}? (`integer`) override `zindex`, defaults to 50 • {title}? (`string`) • {title_pos}? (`'left'|'center'|'right'`) - • {relative}? (`'mouse'|'cursor'`) (default: `'cursor'`) + • {relative}? (`'mouse'|'cursor'|'editor'`) (default: `'cursor'`) • {anchor_bias}? (`'auto'|'above'|'below'`, default: `'auto'`) - "auto": place window based on which side of the cursor has more lines @@ -1769,7 +2037,7 @@ Lua module: vim.lsp.util *lsp-util* *vim.lsp.util.apply_text_document_edit()* -apply_text_document_edit({text_document_edit}, {index}, {offset_encoding}) +apply_text_document_edit({text_document_edit}, {index}, {position_encoding}) Applies a `TextDocumentEdit`, which is a list of changes to a single document. @@ -1777,30 +2045,30 @@ apply_text_document_edit({text_document_edit}, {index}, {offset_encoding}) • {text_document_edit} (`lsp.TextDocumentEdit`) • {index} (`integer?`) Optional index of the edit, if from a list of edits (or nil, if not from a list) - • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'?`) + • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'?`) See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit *vim.lsp.util.apply_text_edits()* -apply_text_edits({text_edits}, {bufnr}, {offset_encoding}) +apply_text_edits({text_edits}, {bufnr}, {position_encoding}) Applies a list of text edits to a buffer. Parameters: ~ - • {text_edits} (`lsp.TextEdit[]`) - • {bufnr} (`integer`) Buffer id - • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'`) + • {text_edits} (`lsp.TextEdit[]`) + • {bufnr} (`integer`) Buffer id + • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'`) See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit *vim.lsp.util.apply_workspace_edit()* -apply_workspace_edit({workspace_edit}, {offset_encoding}) +apply_workspace_edit({workspace_edit}, {position_encoding}) Applies a `WorkspaceEdit`. Parameters: ~ - • {workspace_edit} (`lsp.WorkspaceEdit`) - • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'`) (required) + • {workspace_edit} (`lsp.WorkspaceEdit`) + • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'`) (required) See also: ~ • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_applyEdit @@ -1812,13 +2080,13 @@ buf_clear_references({bufnr}) *vim.lsp.util.buf_clear_references()* • {bufnr} (`integer?`) Buffer id *vim.lsp.util.buf_highlight_references()* -buf_highlight_references({bufnr}, {references}, {offset_encoding}) +buf_highlight_references({bufnr}, {references}, {position_encoding}) Shows a list of document highlights for a certain buffer. Parameters: ~ - • {bufnr} (`integer`) Buffer id - • {references} (`lsp.DocumentHighlight[]`) objects to highlight - • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'`) + • {bufnr} (`integer`) Buffer id + • {references} (`lsp.DocumentHighlight[]`) objects to highlight + • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'`) See also: ~ • https://microsoft.github.io/language-server-protocol/specification/#textDocumentContentChangeEvent @@ -1893,7 +2161,7 @@ get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()* • 'shiftwidth' *vim.lsp.util.locations_to_items()* -locations_to_items({locations}, {offset_encoding}) +locations_to_items({locations}, {position_encoding}) Returns the items with the byte position calculated correctly and in sorted order, for display in quickfix and location lists. @@ -1904,9 +2172,9 @@ locations_to_items({locations}, {offset_encoding}) |setloclist()|. Parameters: ~ - • {locations} (`lsp.Location[]|lsp.LocationLink[]`) - • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'?`) default to first - client of buffer + • {locations} (`lsp.Location[]|lsp.LocationLink[]`) + • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'?`) default to first + client of buffer Return: ~ (`vim.quickfix.entry[]`) See |setqflist()| for the format @@ -1941,37 +2209,33 @@ make_formatting_params({options}) • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting *vim.lsp.util.make_given_range_params()* -make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding}) +make_given_range_params({start_pos}, {end_pos}, {bufnr}, {position_encoding}) Using the given range in the current buffer, creates an object that is similar to |vim.lsp.util.make_range_params()|. Parameters: ~ - • {start_pos} (`[integer,integer]?`) {row,col} mark-indexed - position. Defaults to the start of the last visual - selection. - • {end_pos} (`[integer,integer]?`) {row,col} mark-indexed - position. Defaults to the end of the last visual - selection. - • {bufnr} (`integer?`) buffer handle or 0 for current, - defaults to current - • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'?`) defaults to - `offset_encoding` of first client of `bufnr` + • {start_pos} (`[integer,integer]?`) {row,col} mark-indexed + position. Defaults to the start of the last + visual selection. + • {end_pos} (`[integer,integer]?`) {row,col} mark-indexed + position. Defaults to the end of the last visual + selection. + • {bufnr} (`integer?`) buffer handle or 0 for current, + defaults to current + • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'`) Return: ~ - (`table`) { textDocument = { uri = `current_file_uri` }, range = { - start = `start_position`, end = `end_position` } } + (`{ textDocument: { uri: lsp.DocumentUri }, range: lsp.Range }`) *vim.lsp.util.make_position_params()* -make_position_params({window}, {offset_encoding}) +make_position_params({window}, {position_encoding}) Creates a `TextDocumentPositionParams` object for the current buffer and cursor position. Parameters: ~ - • {window} (`integer?`) window handle or 0 for current, - defaults to current - • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'?`) defaults to - `offset_encoding` of first client of buffer of - `window` + • {window} (`integer?`) window handle or 0 for current, + defaults to current + • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'`) Return: ~ (`lsp.TextDocumentPositionParams`) @@ -1980,22 +2244,19 @@ make_position_params({window}, {offset_encoding}) • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams *vim.lsp.util.make_range_params()* -make_range_params({window}, {offset_encoding}) +make_range_params({window}, {position_encoding}) Using the current position in the current buffer, creates an object that can be used as a building block for several LSP requests, such as `textDocument/codeAction`, `textDocument/colorPresentation`, `textDocument/rangeFormatting`. Parameters: ~ - • {window} (`integer?`) window handle or 0 for current, - defaults to current - • {offset_encoding} (`"utf-8"|"utf-16"|"utf-32"?`) defaults to - `offset_encoding` of first client of buffer of - `window` + • {window} (`integer?`) window handle or 0 for current, + defaults to current + • {position_encoding} (`"utf-8"|"utf-16"|"utf-32"`) Return: ~ - (`table`) { textDocument = { uri = `current_file_uri` }, range = { - start = `current_position`, end = `current_position` } } + (`{ textDocument: { uri: lsp.DocumentUri }, range: lsp.Range }`) *vim.lsp.util.make_text_document_params()* make_text_document_params({bufnr}) @@ -2074,17 +2335,17 @@ rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()* • {ignoreIfExists}? (`boolean`) *vim.lsp.util.show_document()* -show_document({location}, {offset_encoding}, {opts}) +show_document({location}, {position_encoding}, {opts}) Shows document and optionally jumps to the location. Parameters: ~ - • {location} (`lsp.Location|lsp.LocationLink`) - • {offset_encoding} (`'utf-8'|'utf-16'|'utf-32'?`) - • {opts} (`table?`) A table with the following fields: - • {reuse_win}? (`boolean`) Jump to existing window - if buffer is already open. - • {focus}? (`boolean`) Whether to focus/jump to - location if possible. (defaults: true) + • {location} (`lsp.Location|lsp.LocationLink`) + • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'?`) + • {opts} (`table?`) A table with the following fields: + • {reuse_win}? (`boolean`) Jump to existing + window if buffer is already open. + • {focus}? (`boolean`) Whether to focus/jump to + location if possible. (defaults: true) Return: ~ (`boolean`) `true` if succeeded @@ -2168,14 +2429,15 @@ should_log({level}) *vim.lsp.log.should_log()* Lua module: vim.lsp.rpc *lsp-rpc* *vim.lsp.rpc.PublicClient* + Client RPC object Fields: ~ - • {request} (`fun(method: string, params: table?, callback: fun(err: lsp.ResponseError?, result: any), notify_reply_callback: fun(message_id: integer)?):boolean,integer?`) - see |vim.lsp.rpc.request()| - • {notify} (`fun(method: string, params: any):boolean`) see + • {request} (`fun(method: string, params: table?, callback: fun(err?: lsp.ResponseError, result: any), notify_reply_callback?: fun(message_id: integer)):boolean,integer?`) + See |vim.lsp.rpc.request()| + • {notify} (`fun(method: string, params: any): boolean`) See |vim.lsp.rpc.notify()| - • {is_closing} (`fun(): boolean`) - • {terminate} (`fun()`) + • {is_closing} (`fun(): boolean`) Indicates if the RPC is closing. + • {terminate} (`fun()`) Terminates the RPC client. connect({host_or_path}, {port}) *vim.lsp.rpc.connect()* @@ -2185,7 +2447,7 @@ connect({host_or_path}, {port}) *vim.lsp.rpc.connect()* • 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()|. + |vim.lsp.start()|. Parameters: ~ • {host_or_path} (`string`) host to connect to or path to a pipe/domain @@ -2276,12 +2538,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: - • `notify()` |vim.lsp.rpc.notify()| - • `request()` |vim.lsp.rpc.request()| - • `is_closing()` returns a boolean indicating if the RPC is closing. - • `terminate()` terminates the RPC client. See - |vim.lsp.rpc.PublicClient|. + (`vim.lsp.rpc.PublicClient`) See |vim.lsp.rpc.PublicClient|. ============================================================================== diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index b40d5a0791..d0d148f689 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -153,7 +153,7 @@ its functions if this succeeds and prints an error message otherwise: if not ok then print("Module had an error") else - mymod.function() + mymod.func() end < In contrast to |:source|, |require()| not only searches through all `lua/` directories diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 243c907180..0eca3286d0 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -17,9 +17,9 @@ get an idea of what lurks beneath: >vim :lua vim.print(package.loaded) Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the -"editor stdlib" (|builtin-functions| and |Ex-commands|) and the |API|, all of -which can be used from Lua code (|lua-vimscript| |vim.api|). Together these -"namespaces" form the Nvim programming interface. +"editor stdlib" (|vimscript-functions| + |Ex-commands|) and the |API|, all of +which can be used from Lua code (|lua-vimscript| |vim.api|). These three +namespaces form the Nvim programming interface. Lua plugins and user config are automatically discovered and loaded, just like Vimscript. See |lua-guide| for practical guidance. @@ -161,7 +161,7 @@ languages like Python and C#. Example: >lua local func_with_opts = function(opts) local will_do_foo = opts.foo local filename = opts.filename - ... + -- ... end func_with_opts { foo = true, filename = "hello.world" } @@ -618,20 +618,20 @@ Example: TCP echo-server *tcp-server* Multithreading *lua-loop-threading* Plugins can perform work in separate (os-level) threads using the threading -APIs in luv, for instance `vim.uv.new_thread`. Note that every thread -gets its own separate Lua interpreter state, with no access to Lua globals -in the main thread. Neither can the state of the editor (buffers, windows, -etc) be directly accessed from threads. +APIs in luv, for instance `vim.uv.new_thread`. Each thread has its own +separate Lua interpreter state, with no access to Lua globals on the main +thread. Neither can the editor state (buffers, windows, etc) be directly +accessed from threads. -A subset of the `vim.*` API is available in threads. This includes: +A subset of the `vim.*` stdlib is available in threads, including: - `vim.uv` with a separate event loop per thread. - `vim.mpack` and `vim.json` (useful for serializing messages between threads) - `require` in threads can use Lua packages from the global |package.path| - `print()` and `vim.inspect` - `vim.diff` -- most utility functions in `vim.*` for working with pure Lua values - like `vim.split`, `vim.tbl_*`, `vim.list_*`, and so on. +- Most utility functions in `vim.*` that work with pure Lua values, like + `vim.split`, `vim.tbl_*`, `vim.list_*`, etc. - `vim.is_thread()` returns true from a non-main thread. @@ -685,6 +685,8 @@ vim.hl.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) whether the range is end-inclusive • {priority}? (`integer`, default: `vim.hl.priorities.user`) Highlight priority + • {timeout}? (`integer`, default: -1 no timeout) Time in ms + before highlight is cleared ============================================================================== @@ -811,11 +813,14 @@ vim.json.decode({str}, {opts}) *vim.json.decode()* Return: ~ (`any`) -vim.json.encode({obj}) *vim.json.encode()* +vim.json.encode({obj}, {opts}) *vim.json.encode()* Encodes (or "packs") Lua object {obj} as JSON in a Lua string. Parameters: ~ - • {obj} (`any`) + • {obj} (`any`) + • {opts} (`table<string,any>?`) Options table with keys: + • escape_slash: (boolean) (default false) Escape slash + characters "/" in string values. Return: ~ (`string`) @@ -1083,9 +1088,8 @@ vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()* |ui-popupmenu| and the sections below for event format for respective events. - Callbacks for `msg_show` events are executed in |api-fast| context unless - Nvim will wait for input, in which case messages should be shown - immediately. + Callbacks for `msg_show` events are executed in |api-fast| context; + showing the message should be scheduled. Excessive errors inside the callback will result in forced detachment. @@ -1297,7 +1301,7 @@ global value of a |global-local| option, see |:setglobal|. A special interface |vim.opt| exists for conveniently interacting with list- -and map-style option from Lua: It allows accessing them as Lua tables and +and map-style options from Lua: It allows accessing them as Lua tables and offers object-oriented method for adding and removing entries. Examples: ~ @@ -1471,10 +1475,8 @@ vim.go *vim.go* < vim.o *vim.o* - Get or set |options|. Like `:set`. Invalid key is an error. - - Note: this works on both buffer-scoped and window-scoped options using the - current buffer and window. + Get or set |options|. Works like `:set`, so buffer/window-scoped options + target the current buffer/window. Invalid key is an error. Example: >lua vim.o.cmdheight = 4 @@ -1505,7 +1507,7 @@ vim.wo[{winid}][{bufnr}] *vim.wo* Lua module: vim *lua-vim* vim.cmd({command}) *vim.cmd()* - Executes Vim script commands. + Executes Vimscript (|Ex-commands|). Note that `vim.cmd` can be indexed with a command name to return a callable function to the command. @@ -1539,9 +1541,9 @@ vim.cmd({command}) *vim.cmd()* Parameters: ~ • {command} (`string|table`) Command(s) to execute. If a string, - executes multiple lines of Vim script at once. In this - case, it is an alias to |nvim_exec2()|, where `opts.output` - is set to false. Thus it works identical to |:source|. If a + executes multiple lines of Vimscript at once. In this case, + it is an alias to |nvim_exec2()|, where `opts.output` is + set to false. Thus it works identical to |:source|. If a table, executes a single command. In this case, it is an alias to |nvim_cmd()| where `opts` is empty. @@ -1805,7 +1807,7 @@ vim.system({cmd}, {opts}, {on_exit}) *vim.system()* -- Runs synchronously: local obj = vim.system({'echo', 'hello'}, { text = true }):wait() - -- { code = 0, signal = 0, stdout = 'hello', stderr = '' } + -- { code = 0, signal = 0, stdout = 'hello\n', stderr = '' } < See |uv.spawn()| for more details. Note: unlike |uv.spawn()|, vim.system @@ -1911,6 +1913,11 @@ vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* Can also be shown with `:Inspect`. *:Inspect* + Example: To bind this function to the vim-scriptease inspired `zS` in + Normal mode: >lua + vim.keymap.set('n', 'zS', vim.show_pos) +< + Attributes: ~ Since: 0.9.0 @@ -1937,12 +1944,10 @@ vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* *vim.Ringbuf* Fields: ~ - • {clear} (`fun()`) Clear all items - • {push} (`fun(item: T)`) Adds an item, overriding the oldest item if - the buffer is full. - • {pop} (`fun(): T?`) Removes and returns the first unread item - • {peek} (`fun(): T?`) Returns the first unread item without removing - it + • {clear} (`fun()`) See |Ringbuf:clear()|. + • {push} (`fun(item: T)`) See |Ringbuf:push()|. + • {pop} (`fun(): T?`) See |Ringbuf:pop()|. + • {peek} (`fun(): T?`) See |Ringbuf:peek()|. Ringbuf:clear() *Ringbuf:clear()* @@ -2425,7 +2430,7 @@ vim.validate({name}, {value}, {validator}, {optional}, {message}) function vim.startswith(s, prefix) vim.validate('s', s, 'string') vim.validate('prefix', prefix, 'string') - ... + -- ... end < 2. `vim.validate(spec)` (deprecated) where `spec` is of type @@ -2439,7 +2444,7 @@ vim.validate({name}, {value}, {validator}, {optional}, {message}) age={age, 'number'}, hobbies={hobbies, 'table'}, } - ... + -- ... end < @@ -2471,7 +2476,7 @@ vim.validate({name}, {value}, {validator}, {optional}, {message}) Parameters: ~ • {name} (`string`) Argument name - • {value} (`string`) Argument value + • {value} (`any`) Argument value • {validator} (`vim.validate.Validator`) • (`string|string[]`): Any value that can be returned from |lua-type()| in addition to `'callable'`: @@ -2487,22 +2492,24 @@ vim.validate({name}, {value}, {validator}, {optional}, {message}) ============================================================================== Lua module: vim.loader *vim.loader* -vim.loader.disable() *vim.loader.disable()* +vim.loader.enable({enable}) *vim.loader.enable()* WARNING: This feature is experimental/unstable. - Disables the experimental Lua module loader: - • removes the loaders - • adds the default Nvim loader - -vim.loader.enable() *vim.loader.enable()* - WARNING: This feature is experimental/unstable. + Enables or disables the experimental Lua module loader: - Enables the experimental Lua module loader: - • overrides loadfile + Enable (`enable=true`): + • overrides |loadfile()| • adds the Lua loader using the byte-compilation cache • adds the libs loader • removes the default Nvim loader + Disable (`enable=false`): + • removes the loaders + • adds the default Nvim loader + + Parameters: ~ + • {enable} (`boolean?`) true/nil to enable, false to disable + vim.loader.find({modname}, {opts}) *vim.loader.find()* WARNING: This feature is experimental/unstable. @@ -2926,6 +2933,31 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* ============================================================================== Lua module: vim.fs *vim.fs* + + *vim.fs.exists()* +Use |uv.fs_stat()| to check a file's type, and whether it exists. + +Example: >lua + if vim.uv.fs_stat(file) then + vim.print("file exists") + end +< + + +vim.fs.abspath({path}) *vim.fs.abspath()* + Convert path to an absolute path. A tilde (~) character at the beginning + of the path is expanded to the user's home directory. Does not check if + the path exists, normalize the path, resolve symlinks or hardlinks + (including `.` and `..`), or expand environment variables. If the path is + already absolute, it is returned unchanged. Also converts `\` path + separators to `/`. + + Parameters: ~ + • {path} (`string`) Path + + Return: ~ + (`string`) Absolute path + vim.fs.basename({file}) *vim.fs.basename()* Return the basename of the given path @@ -2953,6 +2985,7 @@ vim.fs.dir({path}, {opts}) *vim.fs.dir()* • skip: (fun(dir_name: string): boolean)|nil Predicate to control traversal. Return false to stop searching the current directory. Only useful when depth > 1 + • follow: boolean|nil Follow symbolic links. (default: true) Return: ~ (`Iterator`) over items in {path}. Each iteration yields two values: @@ -2994,7 +3027,7 @@ vim.fs.find({names}, {opts}) *vim.fs.find()* -- get all files ending with .cpp or .hpp inside lib/ local cpp_hpp = vim.fs.find(function(name, path) - return name:match('.*%.[ch]pp$') and path:match('[/\\\\]lib$') + return name:match('.*%.[ch]pp$') and path:match('[/\\]lib$') end, {limit = math.huge, type = 'file'}) < @@ -3008,8 +3041,10 @@ vim.fs.find({names}, {opts}) *vim.fs.find()* If {names} is a function, it is called for each traversed item with args: • name: base name of the current item - • path: full path of the current item The function should - return `true` if the given item is considered a match. + • path: full path of the current item + + The function should return `true` if the given item is + considered a match. • {opts} (`table`) Optional keyword arguments: • {path}? (`string`) Path to begin searching from. If omitted, the |current-directory| is used. @@ -3023,14 +3058,21 @@ vim.fs.find({names}, {opts}) *vim.fs.find()* • {limit}? (`number`, default: `1`) Stop the search after finding this many matches. Use `math.huge` to place no limit on the number of matches. + • {follow}? (`boolean`, default: `true`) Follow symbolic + links. Return: ~ (`string[]`) Normalized paths |vim.fs.normalize()| of all matching items vim.fs.joinpath({...}) *vim.fs.joinpath()* - Concatenate directories and/or file paths into a single path with - normalization (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`) + Concatenates partial paths (one absolute or relative path followed by zero + or more relative paths). Slashes are normalized: redundant slashes are + removed, and (on Windows) backslashes are replaced with forward-slashes. + + Examples: + • "foo/", "/bar" => "foo/bar" + • Windows: "a\foo\", "\bar" => "a/foo/bar" Attributes: ~ Since: 0.10.0 @@ -3113,6 +3155,23 @@ vim.fs.parents({start}) *vim.fs.parents()* (`nil`) (`string?`) +vim.fs.relpath({base}, {target}, {opts}) *vim.fs.relpath()* + Gets `target` path relative to `base`, or `nil` if `base` is not an + ancestor. + + Example: >lua + vim.fs.relpath('/var', '/var/lib') -- 'lib' + vim.fs.relpath('/var', '/usr/bin') -- nil +< + + Parameters: ~ + • {base} (`string`) + • {target} (`string`) + • {opts} (`table?`) Reserved for future use + + Return: ~ + (`string?`) + vim.fs.rm({path}, {opts}) *vim.fs.rm()* WARNING: This feature is experimental/unstable. @@ -3979,6 +4038,7 @@ vim.version.range({spec}) *vim.version.range()* (`table?`) A table with the following fields: • {from} (`vim.Version`) • {to}? (`vim.Version`) + • {has} (`fun(self: vim.VersionRange, version: string|vim.Version)`) See also: ~ • https://github.com/npm/node-semver#ranges diff --git a/runtime/doc/luvref.txt b/runtime/doc/luvref.txt index 2be73f0412..3cbdb53e01 100644 --- a/runtime/doc/luvref.txt +++ b/runtime/doc/luvref.txt @@ -102,6 +102,7 @@ Low-level implementation details and unexposed C functions and types are not documented here except for when they are relevant to behavior seen in the Lua module. +- |luv-constants| — Constants - |luv-error-handling| — Error handling - |luv-version-checking| — Version checking - |uv_loop_t| — Event loop @@ -131,12 +132,103 @@ module. - |luv-metrics-operations| — Metrics operations ============================================================================== +CONSTANTS *luv-constants* + +As a Lua library, luv supports and encourages the use of lowercase strings to +represent options. For example: +>lua + -- signal start with string input + uv.signal_start("sigterm", function(signame) + print(signame) -- string output: "sigterm" + end) +< +However, luv also superficially exposes libuv constants in a Lua table at +`uv.constants` where its keys are uppercase constant names and their associated +values are integers defined internally by libuv. The values from this table may +be supported as function arguments, but their use may not change the output +type. For example: +>lua + -- signal start with integer input + uv.signal_start(uv.constants.SIGTERM, function(signame) + print(signame) -- string output: "sigterm" + end) +< +The uppercase constants defined in `uv.constants` that have associated +lowercase option strings are listed below. + +Address Families ~ + +- `AF_UNIX`: "unix" +- `AF_INET`: "inet" +- `AF_INET6`: "inet6" +- `AF_IPX`: "ipx" +- `AF_NETLINK`: "netlink" +- `AF_X25`: "x25" +- `AF_AX25`: "as25" +- `AF_ATMPVC`: "atmpvc" +- `AF_APPLETALK`: "appletalk" +- `AF_PACKET`: "packet" + +Signals ~ + +- `SIGHUP`: "sighup" +- `SIGINT`: "sigint" +- `SIGQUIT`: "sigquit" +- `SIGILL`: "sigill" +- `SIGTRAP`: "sigtrap" +- `SIGABRT`: "sigabrt" +- `SIGIOT`: "sigiot" +- `SIGBUS`: "sigbus" +- `SIGFPE`: "sigfpe" +- `SIGKILL`: "sigkill" +- `SIGUSR1`: "sigusr1" +- `SIGSEGV`: "sigsegv" +- `SIGUSR2`: "sigusr2" +- `SIGPIPE`: "sigpipe" +- `SIGALRM`: "sigalrm" +- `SIGTERM`: "sigterm" +- `SIGCHLD`: "sigchld" +- `SIGSTKFLT`: "sigstkflt" +- `SIGCONT`: "sigcont" +- `SIGSTOP`: "sigstop" +- `SIGTSTP`: "sigtstp" +- `SIGBREAK`: "sigbreak" +- `SIGTTIN`: "sigttin" +- `SIGTTOU`: "sigttou" +- `SIGURG`: "sigurg" +- `SIGXCPU`: "sigxcpu" +- `SIGXFSZ`: "sigxfsz" +- `SIGVTALRM`: "sigvtalrm" +- `SIGPROF`: "sigprof" +- `SIGWINCH`: "sigwinch" +- `SIGIO`: "sigio" +- `SIGPOLL`: "sigpoll" +- `SIGLOST`: "siglost" +- `SIGPWR`: "sigpwr" +- `SIGSYS`: "sigsys" + +Socket Types ~ + +- `SOCK_STREAM`: "stream" +- `SOCK_DGRAM`: "dgram" +- `SOCK_SEQPACKET`: "seqpacket" +- `SOCK_RAW`: "raw" +- `SOCK_RDM`: "rdm" + +TTY Modes ~ + +- `TTY_MODE_NORMAL`: "normal" +- `TTY_MODE_RAW`: "raw" +- `TTY_MODE_IO`: "io" + +============================================================================== ERROR HANDLING *luv-error-handling* -In libuv, errors are negative numbered constants; however, while those errors -are exposed through `uv.errno`, the functions used to handle them are not -exposed to luv users. Instead, if an internal error is encountered, the luv -function will return to the caller an assertable `nil, err, name` tuple. +In libuv, errors are represented by negative numbered constants. While these +constants are made available in the `uv.errno` table, they are not returned by +luv funtions and the libuv functions used to handle them are not exposed. +Instead, if an internal error is encountered, the failing luv function will +return to the caller an assertable `nil, err, name` tuple: - `nil` idiomatically indicates failure - `err` is a string with the format `{name}: {message}` @@ -153,9 +245,8 @@ success, or sometimes nothing at all. These cases are documented below. `uv.errno` *uv.errno* -A table value which exposes error constants as a map, where the key is the -error name (without the `UV_` prefix) and its value is a negative number. -See Libuv's "Error constants" page for further details. +Below is a list of known error names and error strings. See Libuv's "Error +constants" page for further details. (https://docs.libuv.org/en/v1.x/errors.html#error-constants) - `E2BIG`: argument list too long. @@ -1154,8 +1245,8 @@ Unix Notes: -- Create a new signal handler local signal = uv.new_signal() -- Define a handler function - uv.signal_start(signal, "sigint", function(signal) - print("got " .. signal .. ", shutting down") + uv.signal_start(signal, "sigint", function(signame) + print("got " .. signame .. ", shutting down") os.exit(1) end) < @@ -1167,34 +1258,40 @@ uv.new_signal() *uv.new_signal()* Returns: `uv_signal_t userdata` or `fail` -uv.signal_start({signal}, {signum}, {callback}) *uv.signal_start()* +uv.signal_start({signal}, {signame}, {callback}) *uv.signal_start()* - > method form `signal:start(signum, callback)` + > method form `signal:start(signame, callback)` Parameters: - `signal`: `uv_signal_t userdata` - - `signum`: `integer` or `string` + - `signame`: `string` or `integer` - `callback`: `callable` - - `signum`: `string` + - `signame`: `string` Start the handle with the given callback, watching for the given signal. + See |luv-constants| for supported `signame` input and output + values. + Returns: `0` or `fail` *uv.signal_start_oneshot()* -uv.signal_start_oneshot({signal}, {signum}, {callback}) +uv.signal_start_oneshot({signal}, {signame}, {callback}) - > method form `signal:start_oneshot(signum, callback)` + > method form `signal:start_oneshot(signame, callback)` Parameters: - `signal`: `uv_signal_t userdata` - - `signum`: `integer` or `string` + - `signame`: `string` or `integer` - `callback`: `callable` - - `signum`: `string` + - `signame`: `string` Same functionality as |uv.signal_start()| but the signal handler is reset the moment the signal is received. + See |luv-constants| for supported `signame` input and output + values. + Returns: `0` or `fail` uv.signal_stop({signal}) *uv.signal_stop()* @@ -1349,30 +1446,36 @@ uv.spawn({path}, {options}, {on_exit}) *uv.spawn()* Returns: `uv_process_t userdata`, `integer` -uv.process_kill({process}, {signum}) *uv.process_kill()* +uv.process_kill({process}, {signame}) *uv.process_kill()* - > method form `process:kill(signum)` + > method form `process:kill(signame)` Parameters: - `process`: `uv_process_t userdata` - - `signum`: `integer` or `string` or `nil` (default: `sigterm`) + - `signame`: `string` or `integer` or `nil` (default: `sigterm`) Sends the specified signal to the given process handle. Check the documentation on |uv_signal_t| for signal support, specially on Windows. + See |luv-constants| for supported `signame` input and output + values. + Returns: `0` or `fail` -uv.kill({pid}, {signum}) *uv.kill()* +uv.kill({pid}, {signame}) *uv.kill()* Parameters: - `pid`: `integer` - - `signum`: `integer` or `string` or `nil` (default: `sigterm`) + - `signame`: `string` or `integer` or `nil` (default: `sigterm`) Sends the specified signal to the given PID. Check the documentation on |uv_signal_t| for signal support, specially on Windows. + See |luv-constants| for supported `signame` input and output + values. + Returns: `0` or `fail` uv.process_get_pid({process}) *uv.process_get_pid()* @@ -1638,12 +1741,13 @@ TCP handles are used to represent both TCP streams and servers. uv.new_tcp([{flags}]) *uv.new_tcp()* Parameters: - - `flags`: `string` or `nil` + - `flags`: `string` or `integer` or `nil` Creates and initializes a new |uv_tcp_t|. Returns the Lua - userdata wrapping it. Flags may be a family string: `"unix"`, - `"inet"`, `"inet6"`, `"ipx"`, `"netlink"`, `"x25"`, `"ax25"`, - `"atmpvc"`, `"appletalk"`, or `"packet"`. + userdata wrapping it. + + If set, `flags` must be a valid address family. See + |luv-constants| for supported address family input values. Returns: `uv_tcp_t userdata` or `fail` @@ -1744,6 +1848,8 @@ uv.tcp_getpeername({tcp}) *uv.tcp_getpeername()* Get the address of the peer connected to the handle. + See |luv-constants| for supported address `family` output values. + Returns: `table` or `fail` - `ip` : `string` - `family` : `string` @@ -1758,6 +1864,8 @@ uv.tcp_getsockname({tcp}) *uv.tcp_getsockname()* Get the current address to which the handle is bound. + See |luv-constants| for supported address `family` output values. + Returns: `table` or `fail` - `ip` : `string` - `family` : `string` @@ -1823,8 +1931,7 @@ uv.socketpair([{socktype}, [{protocol}, [{flags1}, [{flags2}]]]]) |uv.tcp_open()|, used with |uv.spawn()|, or for any other purpose. - When specified as a string, `socktype` must be one of - `"stream"`, `"dgram"`, `"raw"`, `"rdm"`, or `"seqpacket"`. + See |luv-constants| for supported `socktype` input values. When `protocol` is set to 0 or nil, it will be automatically chosen based on the socket's domain and type. When `protocol` @@ -2184,17 +2291,11 @@ uv.tty_set_mode({tty}, {mode}) *uv.tty_set_mode()* Parameters: - `tty`: `uv_tty_t userdata` - - `mode`: `integer` + - `mode`: `string` or `integer` Set the TTY using the specified terminal mode. - Parameter `mode` is a C enum with the following values: - - - 0 - UV_TTY_MODE_NORMAL: Initial/normal terminal mode - - 1 - UV_TTY_MODE_RAW: Raw input mode (On Windows, - ENABLE_WINDOW_INPUT is also enabled) - - 2 - UV_TTY_MODE_IO: Binary-safe I/O mode for IPC - (Unix-only) + See |luv-constants| for supported TTY mode input values. Returns: `0` or `fail` @@ -2265,9 +2366,7 @@ uv.new_udp([{flags}]) *uv.new_udp()* Creates and initializes a new |uv_udp_t|. Returns the Lua userdata wrapping it. The actual socket is created lazily. - When specified, `family` must be one of `"unix"`, `"inet"`, - `"inet6"`, `"ipx"`, `"netlink"`, `"x25"`, `"ax25"`, - `"atmpvc"`, `"appletalk"`, or `"packet"`. + See |luv-constants| for supported address `family` input values. When specified, `mmsgs` determines the number of messages able to be received at one time via `recvmmsg(2)` (the allocated @@ -2510,6 +2609,51 @@ uv.udp_try_send({udp}, {data}, {host}, {port}) *uv.udp_try_send()* Returns: `integer` or `fail` +uv.udp_try_send2({udp}, {messages}, {flags}) *uv.udp_try_send2()* + + > method form `udp:try_send2(messages, flags)` + + Parameters: + - `udp`: `uv_udp_t userdata` + - `messages`: `table` + - `[1, 2, 3, ..., n]` : `table` + - `data` : `buffer` + - `addr` : `table` + - `ip` : `string` + - `port` : `integer` + - `flags`: `nil` (see below) + - `port`: `integer` + + Like `uv.udp_try_send()`, but can send multiple datagrams. + Lightweight abstraction around `sendmmsg(2)`, with a + `sendmsg(2)` fallback loop for platforms that do not support + the former. The `udp` handle must be fully initialized, either + from a `uv.udp_bind` call, another call that will bind + automatically (`udp_send`, `udp_try_send`, etc), or from + `uv.udp_connect`. `messages` should be an array-like table, + where `addr` must be specified if the `udp` has not been + connected via `udp_connect`. Otherwise, `addr` must be `nil`. + + `flags` is reserved for future extension and must currently be + `nil` or `0` or `{}`. + + Returns the number of messages sent successfully. An error will only be returned + if the first datagram failed to be sent. + + Returns: `integer` or `fail` + >lua + -- If client:connect(...) was not called + local addr = { ip = "127.0.0.1", port = 1234 } + client:try_send2({ + { data = "Message 1", addr = addr }, + { data = "Message 2", addr = addr }, + }) + -- If client:connect(...) was called + client:try_send2({ + { data = "Message 1" }, + { data = "Message 2" }, + }) +< uv.udp_recv_start({udp}, {callback}) *uv.udp_recv_start()* > method form `udp:recv_start(callback)` @@ -2531,6 +2675,8 @@ uv.udp_recv_start({udp}, {callback}) *uv.udp_recv_start()* been bound with |uv.udp_bind()| it is bound to `0.0.0.0` (the "all interfaces" IPv4 address) and a random port number. + See |luv-constants| for supported address `family` output values. + Returns: `0` or `fail` uv.udp_recv_stop({udp}) *uv.udp_recv_stop()* @@ -2743,7 +2889,8 @@ uv.fs_open({path}, {flags}, {mode} [, {callback}]) *uv.fs_open()* Parameters: - `path`: `string` - `flags`: `string` or `integer` - - `mode`: `integer` + - `mode`: `integer` (octal `chmod(1)` mode, e.g. + `tonumber('644', 8)`) - `callback`: `callable` (async version) or `nil` (sync version) - `err`: `nil` or `string` @@ -2829,7 +2976,8 @@ uv.fs_mkdir({path}, {mode} [, {callback}]) *uv.fs_mkdir()* Parameters: - `path`: `string` - - `mode`: `integer` + - `mode`: `integer` (octal representation of `chmod(1)` mode, + e.g. `tonumber('755', 8)`) - `callback`: `callable` (async version) or `nil` (sync version) - `err`: `nil` or `string` @@ -3078,7 +3226,9 @@ uv.fs_access({path}, {mode} [, {callback}]) *uv.fs_access()* Parameters: - `path`: `string` - - `mode`: `integer` + - `mode`: `integer` `string` (a combination of the `'r'`, + `'w'` and `'x'` characters denoting the symbolic mode as per + `chmod(1)`) - `callback`: `callable` (async version) or `nil` (sync version) - `err`: `nil` or `string` @@ -3097,7 +3247,8 @@ uv.fs_chmod({path}, {mode} [, {callback}]) *uv.fs_chmod()* Parameters: - `path`: `string` - - `mode`: `integer` + - `mode`: `integer` (octal representation of `chmod(1)` mode, + e.g. `tonumber('644', 8)`) - `callback`: `callable` (async version) or `nil` (sync version) - `err`: `nil` or `string` @@ -3480,14 +3631,17 @@ uv.getaddrinfo({host}, {service} [, {hints} [, {callback}]]) *uv.getaddrinfo()* Equivalent to `getaddrinfo(3)`. Either `node` or `service` may be `nil` but not both. - Valid hint strings for the keys that take a string: - - `family`: `"unix"`, `"inet"`, `"inet6"`, `"ipx"`, - `"netlink"`, `"x25"`, `"ax25"`, `"atmpvc"`, `"appletalk"`, - or `"packet"` - - `socktype`: `"stream"`, `"dgram"`, `"raw"`, `"rdm"`, or - `"seqpacket"` - - `protocol`: will be looked up using the `getprotobyname(3)` - function (examples: `"ip"`, `"icmp"`, `"tcp"`, `"udp"`, etc) + See |luv-constants| for supported address `family` input and + output values. + + See |luv-constants| for supported `socktype` input and + output values. + + When `protocol` is set to `0` or `nil`, it will be + automatically chosen based on the socket's domain and type. + When `protocol` is specified as a string, it will be looked up + using the `getprotobyname(3)` function. Examples: `"ip"`, + `"icmp"`, `"tcp"`, `"udp"`, etc. Returns (sync version): `table` or `fail` - `[1, 2, 3, ..., n]` : `table` @@ -3515,9 +3669,7 @@ uv.getnameinfo({address} [, {callback}]) *uv.getnameinfo()* Equivalent to `getnameinfo(3)`. - When specified, `family` must be one of `"unix"`, `"inet"`, - `"inet6"`, `"ipx"`, `"netlink"`, `"x25"`, `"ax25"`, - `"atmpvc"`, `"appletalk"`, or `"packet"`. + See |luv-constants| for supported address `family` input values. Returns (sync version): `string, string` or `fail` @@ -3526,7 +3678,7 @@ uv.getnameinfo({address} [, {callback}]) *uv.getnameinfo()* ============================================================================== THREADING AND SYNCHRONIZATION UTILITIES *luv-threading-and-synchronization-utilities* -Libuv provides cross-platform implementations for multiple threading an +Libuv provides cross-platform implementations for multiple threading and synchronization primitives. The API largely follows the pthreads API. uv.new_thread([{options}, ] {entry}, {...}) *uv.new_thread()* @@ -3683,6 +3835,43 @@ uv.thread_join({thread}) *uv.thread_join()* Returns: `boolean` or `fail` +uv.thread_detach({thread}) *uv.thread_detach()* + + > method form `thread:detach()` + + Parameters: + - `thread`: `luv_thread_t userdata` + + Detaches a thread. Detached threads automatically release + their resources upon termination, eliminating the need for the + application to call `uv.thread_join`. + + Returns: `boolean` or `fail` + +uv.thread_setname({name}) *uv.thread_setname()* + + Parameters: + - `name`: `string` + + Sets the name of the current thread. Different platforms + define different limits on the max number of characters a + thread name can be: Linux, IBM i (16), macOS (64), Windows + (32767), and NetBSD (32), etc. The name will be truncated if + `name` is larger than the limit of the platform. + + Returns: `0` or `fail` + +uv.thread_getname({thread}) *uv.thread_getname()* + + > method form `thread:getname()` + + Parameters: + - `thread`: `luv_thread_t userdata` + + Gets the name of the thread specified by `thread`. + + Returns: `string` or `fail` + uv.sleep({msec}) *uv.sleep()* Parameters: @@ -3796,6 +3985,36 @@ uv.getrusage() *uv.getrusage()* - `nvcsw` : `integer` (voluntary context switches) - `nivcsw` : `integer` (involuntary context switches) +uv.getrusage_thread() *uv.getrusage_thread()* + Gets the resource usage measures for the calling thread. + + Note: Not supported on all platforms. May return `ENOTSUP`. + + On macOS and Windows not all fields are set (the unsupported + fields are filled with zeroes). + + Returns: `table` or `fail` + - `utime` : `table` (user CPU time used) + - `sec` : `integer` + - `usec` : `integer` + - `stime` : `table` (system CPU time used) + - `sec` : `integer` + - `usec` : `integer` + - `maxrss` : `integer` (maximum resident set size) + - `ixrss` : `integer` (integral shared memory size) + - `idrss` : `integer` (integral unshared data size) + - `isrss` : `integer` (integral unshared stack size) + - `minflt` : `integer` (page reclaims (soft page faults)) + - `majflt` : `integer` (page faults (hard page faults)) + - `nswap` : `integer` (swaps) + - `inblock` : `integer` (block input operations) + - `oublock` : `integer` (block output operations) + - `msgsnd` : `integer` (IPC messages sent) + - `msgrcv` : `integer` (IPC messages received) + - `nsignals` : `integer` (signals received) + - `nvcsw` : `integer` (voluntary context switches) + - `nivcsw` : `integer` (involuntary context switches) + uv.available_parallelism() *uv.available_parallelism()* Returns an estimate of the default amount of parallelism a @@ -3968,6 +4187,8 @@ uv.interface_addresses() *uv.interface_addresses()* information where fields are `ip`, `family`, `netmask`, `internal`, and `mac`. + See |luv-constants| for supported address `family` output values. + Returns: `table` - `[name(s)]` : `table` - `ip` : `string` @@ -4202,6 +4423,67 @@ uv.metrics_info() *uv.metrics_info()* - `events_waiting` : `integer` ============================================================================== +STRING MANIPULATION FUNCTIONS *luv-string-manipulation* + +These string utilities are needed internally for dealing with Windows, and are +exported to allow clients to work uniformly with this data when the libuv API +is not complete. + +Notes: +1. New in luv version 1.49.0. +2. See the WTF-8 spec (https://simonsapin.github.io/wtf-8/) for information + about WTF-8. +3. Luv uses Lua-style strings, which means that all inputs and return values + (UTF-8 or UTF-16 strings) do not include a NUL terminator. + +uv.utf16_length_as_wtf8({utf16}) *uv.utf16_length_as_wtf8()* + + Get the length (in bytes) of a UTF-16 (or UCS-2) string + `utf16` value after converting it to WTF-8. The endianness of + the UTF-16 (or UCS-2) string is assumed to be the same as the + native endianness of the platform. + + Parameters: + - `utf16`: `string` + + Returns: `integer` + +uv.utf16_to_wtf8({utf16}) *uv.utf16_to_wtf8()* + + Convert UTF-16 (or UCS-2) string `utf16` to UTF-8 string. The + endianness of the UTF-16 (or UCS-2) string is assumed to be + the same as the native endianness of the platform. + + Parameters: + - `utf16`: `string` + + Returns: `string` + +uv.wtf8_length_as_utf16({wtf16}) *uv.wtf8_length_as_utf16()* + + Get the length (in UTF-16 code units) of a WTF-8 `wtf8` value + after converting it to UTF-16 (or UCS-2). + + Note: The number of bytes needed for a UTF-16 (or UCS-2) + string is `<number of code units> * 2`. + + Parameters: + - `wtf8`: `string` + + Returns: `integer` + +uv.wtf8_to_utf16({wtf16}) *uv.wtf8_to_utf16()* + + Convert WTF-8 string in `wtf8` to UTF-16 (or UCS-2) string. + The endianness of the UTF-16 (or UCS-2) string is assumed to + be the same as the native endianness of the platform. + + Parameters: + - `wtf8`: `string` + + Returns: `string` + +============================================================================== CREDITS *luv-credits* This document is a reformatted version of the LUV documentation, up-to-date @@ -4211,4 +4493,4 @@ https://github.com/luvit/luv/commit/dcd1a1cad5b05634a7691402d6ca2f214fb4ae76. Based on https://github.com/nanotee/luv-vimdocs with kind permission. -vim:tw=78:ts=8:ft=help:norl: +vim:tw=78:ts=8:sw=2:et:ft=help:norl: diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 11048aee30..52c04333fc 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -12,7 +12,7 @@ manual. Type |gO| to see the table of contents. ============================================================================== -1. Key mapping *key-mapping* *mapping* *macro* +1. Key mapping *keybind* *key-mapping* *mapping* Key mapping is used to change the meaning of typed keys. The most common use is to define a sequence of commands for a function key. Example: > @@ -1545,7 +1545,7 @@ Your command preview routine must implement this protocol: 3. Add required highlights to the target buffers. If preview buffer is provided, add required highlights to the preview buffer as well. All highlights must be added to the preview namespace which is provided as an - argument to the preview callback (see |nvim_buf_add_highlight()| and + argument to the preview callback (see |vim.hl.range()| and |nvim_buf_set_extmark()| for help on how to add highlights to a namespace). 4. Return an integer (0, 1, 2) which controls how Nvim behaves as follows: 0: No preview is shown. @@ -1574,13 +1574,12 @@ supports incremental command preview: if start_idx then -- Highlight the match - vim.api.nvim_buf_add_highlight( + vim.hl.range( buf, preview_ns, 'Substitute', - line1 + i - 2, - start_idx - 1, - end_idx + {line1 + i - 2, start_idx - 1}, + {line1 + i - 2, end_idx}, ) -- Add lines and set highlights in the preview buffer @@ -1595,13 +1594,12 @@ supports incremental command preview: false, { prefix .. line } ) - vim.api.nvim_buf_add_highlight( + vim.hl.range( preview_buf, preview_ns, 'Substitute', - preview_buf_line, - #prefix + start_idx - 1, - #prefix + end_idx + {preview_buf_line, #prefix + start_idx - 1}, + {preview_buf_line, #prefix + end_idx}, ) preview_buf_line = preview_buf_line + 1 end diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index ac151811c2..d6f5aeb354 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -27,7 +27,7 @@ depends on the 'shortmess' option. Clear messages, keeping only the {count} most recent ones. -The number of remembered messages is fixed at 200. +The number of remembered messages is determined by the 'messagesopt' option. *g<* The "g<" command can be used to see the last page of previous command output. @@ -789,6 +789,7 @@ If you accidentally hit <Enter> or <Space> and you want to see the displayed text then use |g<|. This only works when 'more' is set. To reduce the number of hit-enter prompts: +- Set 'messagesopt'. - Set 'cmdheight' to 2 or higher. - Add flags to 'shortmess'. - Reset 'showcmd' and/or 'ruler'. diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index 48e13d795e..284be09121 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -115,6 +115,12 @@ This cannot be repeated: > endif<CR> Note that when using ":" any motion becomes charwise exclusive. + *inclusive-motion-selection-exclusive* +When 'selection' is "exclusive", |Visual| mode is active and an inclusive +motion has been used, the cursor position will be adjusted by another +character to the right, so that the Visual selection includes the expected +text and can be acted upon. + *forced-motion* FORCING A MOTION TO BE LINEWISE, CHARWISE OR BLOCKWISE diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index d19df84023..12fac28db8 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -11,16 +11,36 @@ For changes in the previous release, see |news-0.10|. Type |gO| to see the table of contents. ============================================================================== -BREAKING CHANGES IN HEAD *news-breaking-dev* +BREAKING CHANGES IN HEAD OR EXPERIMENTAL *news-breaking-dev* ====== Remove this section before release. ====== The following changes to UNRELEASED features were made during the development cycle (Nvim HEAD, the "master" branch). +EXPERIMENTS + +• Removed `vim.loader.disable()`. Use `vim.loader.enable(false)` instead. + +LSP + +• `lsp/` runtimepath files should return a table instead of calling + |vim.lsp.config()| (or assigning to `vim.lsp.config`). See |lsp-config| +• `vim.lsp.buf.document_symbol()` uses the |location-list| by default. Use + `vim.lsp.buf.document_symbol({ loclist = false })` to use the |quickfix| + list. + + OPTIONS • 'jumpoptions' flag "unload" has been renamed to "clean". +• The `msghistory` option has been removed in favor of 'messagesopt'. + +TREESITTER + +• *TSNode:child_containing_descendant()* has been removed in the tree-sitter + library and is no longer available; use |TSNode:child_with_descendant()| + instead. ============================================================================== BREAKING CHANGES *news-breaking* @@ -29,7 +49,6 @@ These changes may require adaptations in your config or plugins. API -• Improved API "meta" docstrings and :help documentation. • `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 @@ -45,19 +64,24 @@ API • Renamed `nvim__id_dictionary` (unsupported/experimental API) to `nvim__id_dict`. +BUILD + +On Windows, only building with the UCRT runtime is supported. + DEFAULTS -• |]d-default| and |[d-default| accept a count. -• |[D-default| and |]D-default| jump to the first and last diagnostic in the - current buffer, respectively. +• 'number', 'relativenumber', 'signcolumn', and 'foldcolumn' are disabled in + |terminal| buffers. See |terminal-config| for an example of changing these defaults. DIAGNOSTICS -• |vim.diagnostic.config()| accepts a "jump" table to specify defaults for - |vim.diagnostic.jump()|. • The "underline" diagnostics handler sorts diagnostics by severity when using the "severity_sort" option. - +• Diagnostics are filtered by severity before being passed to a diagnostic + handler |diagnostic-handlers|. +• The "virtual_text" handler is disabled by default. Enable with >lua + vim.diagnostic.config({ virtual_text = true }) +< EDITOR • The order in which signs are placed was changed. Higher priority signs will @@ -74,14 +98,24 @@ EVENTS • |vim.ui_attach()| callbacks for |ui-messages| `msg_show` events are executed in |api-fast| context. +• New/enhanced arguments in these existing UI events: + • `cmdline_hide`: `abort` argument indicating if the cmdline was aborted. + • `cmdline_show`: + • Prompts that were previously emitted as `msg_show` events, are now routed + through `cmdline_show`. + • `hl_id` argument to highlight the prompt text. + • `msg_show`: + • `history` argument indicating if the message was added to the history. + • new message kinds: "bufwrite", "completion", "list_cmd", "lua_print", + "search_cmd", "shell_out/err/ret", "undo", "verbose", wildlist". + +HIGHLIGHTS + +• |TermCursorNC| is removed and no longer supported. Unfocused terminals no + longer have a cursor. LSP -• Improved rendering of LSP hover docs. |K-lsp-default| -• |vim.lsp.completion.enable()| gained the `convert` callback which enables - customizing the transformation of an LSP CompletionItem to |complete-items|. -• |vim.lsp.diagnostic.from()| can be used to convert a list of - |vim.Diagnostic| objects into their LSP diagnostic representation. • |vim.lsp.buf.references()|, |vim.lsp.buf.declaration()|, |vim.lsp.buf.definition()|, |vim.lsp.buf.type_definition()|, |vim.lsp.buf.implementation()| and |vim.lsp.buf.hover()| now support merging the results of multiple clients @@ -95,14 +129,15 @@ LSP Instead use: >lua vim.diagnostic.config(config, vim.lsp.diagnostic.get_namespace(client_id)) < +• |vim.lsp.util.make_position_params()|, |vim.lsp.util.make_range_params()| + and |vim.lsp.util.make_given_range_params()| now require the `position_encoding` + parameter. LUA • API functions now consistently return an empty dictionary as |vim.empty_dict()|. Earlier, a |lua-special-tbl| was sometimes used. -• Command-line completions for: `vim.g`, `vim.t`, `vim.w`, `vim.b`, `vim.v`, - `vim.o`, `vim.wo`, `vim.bo`, `vim.opt`, `vim.opt_local`, `vim.opt_global`, - and `vim.fn`. +• |vim.json.encode()| no longer escapes forward slashes "/" by default OPTIONS @@ -134,13 +169,17 @@ TREESITTER if no languages are explicitly registered. • |vim.treesitter.language.add()| returns `true` if a parser was loaded successfully and `nil,errmsg` otherwise instead of throwing an error. -• New |TSNode:child_with_descendant()|, which is nearly identical to - |TSNode:child_containing_descendant()| except that it can return the - descendant itself. +• |vim.treesitter.get_parser()| and |vim.treesitter.start()| no longer parse + the tree before returning. Scripts must call |LanguageTree:parse()| explicitly. >lua + local p = vim.treesitter.get_parser(0, 'c') + p:parse() +< TUI -• TODO +• OSC 52 is used as a fallback clipboard provider when no other + |clipboard-tool| is found, even when not using SSH |clipboard-osc52|. To + disable OSC 52 queries, set the "osc52" key of |g:termfeatures| to false. VIMSCRIPT @@ -155,7 +194,15 @@ The following new features were added. API +• Improved API "meta" docstrings and :help documentation. • |nvim__ns_set()| can set properties for a namespace +• |nvim_echo()| `err` field to print error messages and `chunks` accepts + highlight group IDs. +• |nvim_open_win()| `relative` field can be set to "laststatus" and "tabline". +• |nvim_buf_set_extmark()| `hl_group` field can be an array of layered groups +• |vim.hl.range()| now has a optional `timeout` field which allows for a timed highlight +• |nvim_buf_set_extmark()| virt_text_pos accepts `eol_right_align` to + allow for right aligned text that truncates before covering up buffer text. DEFAULTS @@ -173,6 +220,9 @@ DEFAULTS on a URL. • Mouse |popup-menu| includes a "Go to definition" item when LSP is active in the buffer. + • |]d-default| and |[d-default| accept a count. + • |[D-default| and |]D-default| jump to the first and last diagnostic in the + current buffer, respectively. • Mappings inspired by Tim Pope's vim-unimpaired: • |[q|, |]q|, |[Q|, |]Q|, |[CTRL-Q|, |]CTRL-Q| navigate through the |quickfix| list • |[l|, |]l|, |[L|, |]L|, |[CTRL-L|, |]CTRL-L| navigate through the |location-list| @@ -187,14 +237,25 @@ DEFAULTS • `<S-Tab>` in Insert and Select mode maps to `vim.snippet.jump({ direction = -1 })` when a snippet is active and jumpable backwards. +DIAGNOSTICS + +• |vim.diagnostic.config()| accepts a "jump" table to specify defaults for + |vim.diagnostic.jump()|. +• A "virtual_lines" diagnostic handler was added to render diagnostics using + virtual lines below the respective code. +• The "virtual_text" diagnostic handler accepts a `current_line` option to + only show virtual text at the cursor's line. + EDITOR +• Use |g==| in :help docs to execute Lua and Vimscript code examples. • Improved |paste| handling for redo (dot-repeat) and macros (|recording|): • Redoing a large paste is significantly faster and ignores 'autoindent'. • Replaying a macro with |@| also replays pasted text. • On Windows, filename arguments on the command-line prefixed with "~\" or "~/" are now expanded to the user's profile directory, not a relative path to a literal "~" directory. +• |hl-ComplMatchIns| shows matched text of the currently inserted completion. • |hl-PmenuMatch| and |hl-PmenuMatchSel| show matched text in completion popup. EVENTS @@ -205,6 +266,12 @@ EVENTS LSP +• Improved rendering of LSP hover docs. |K-lsp-default| +• |vim.lsp.completion.enable()| gained the `convert` callback which enables + customizing the transformation of an LSP CompletionItem to |complete-items|. +• |vim.lsp.diagnostic.from()| can be used to convert a list of + |vim.Diagnostic| objects into their LSP diagnostic representation. +• `:checkhealth vim.lsp` displays the server version (if available). • Completion side effects (including snippet expansion, execution of commands and application of additional text edits) is now built-in. • |vim.lsp.util.locations_to_items()| sets `end_col` and `end_lnum` fields. @@ -218,32 +285,61 @@ LSP • The client now supports `'utf-8'` and `'utf-32'` position encodings. • |vim.lsp.buf.hover()| now highlights hover ranges using the |hl-LspReferenceTarget| highlight group. +• Functions in |vim.lsp.Client| can now be called as methods. +• Implemented LSP folding: |vim.lsp.foldexpr()| + https://microsoft.github.io/language-server-protocol/specification/#textDocument_foldingRange +• |vim.lsp.config()| has been added to define default configurations for + servers. In addition, configurations can be specified in `lsp/<name>.lua`. +• |vim.lsp.enable()| has been added to enable servers. LUA +• Command-line completions for: `vim.g`, `vim.t`, `vim.w`, `vim.b`, `vim.v`, + `vim.o`, `vim.wo`, `vim.bo`, `vim.opt`, `vim.opt_local`, `vim.opt_global`, + and `vim.fn`. • |vim.fs.rm()| can delete files and directories. • |vim.validate()| now has a new signature which uses less tables, - is more peformant and easier to read. + is more performant and easier to read. • |vim.str_byteindex()| and |vim.str_utfindex()| gained overload signatures supporting two new parameters, `encoding` and `strict_indexing`. +• |vim.json.encode()| has an option to enable forward slash escaping +• |vim.fs.abspath()| converts paths to absolute paths. +• |vim.fs.relpath()| gets relative path compared to base path. +• |vim.fs.dir()| and |vim.fs.find()| now follow symbolic links by default, + the behavior can be turn off using the new `follow` option. OPTIONS • 'completeopt' flag "fuzzy" enables |fuzzy-matching| during |ins-completion|. -• 'msghistory' controls maximum number of messages to remember. +• 'completeopt' flag "preinsert" highlights text to be inserted. +• 'messagesopt' configures |:messages| and |hit-enter| prompt. • 'tabclose' controls which tab page to focus when closing a tab page. PERFORMANCE -• TODO +• Significantly reduced redraw time for long lines with treesitter + highlighting. +• LSP diagnostics and inlay hints are de-duplicated (new requests cancel + inflight requests). This greatly improves performance with slow LSP servers. +• 10x speedup for |vim.treesitter.foldexpr()| (when no parser exists for the + buffer). +• Strong |treesitter-query| caching makes repeat |vim.treesitter.query.get()| + and |vim.treesitter.query.parse()| calls significantly faster for large + queries. +• Treesitter highlighting is now asynchronous. To force synchronous parsing, + use `vim.g._ts_force_sync_parsing = true`. +• Treesitter folding is now calculated asynchronously. PLUGINS • EditorConfig • spelling_language property is now supported. +• 'inccommand' incremental preview can run on 'nomodifiable' buffers and + restores their 'modifiable' state STARTUP +• |-es| ("script mode") disables shada by default. • Nvim will fail if the |--listen| or |$NVIM_LISTEN_ADDRESS| address is invalid, instead of silently skipping an invalid address. @@ -258,12 +354,36 @@ TERMINAL 'scrollback' are not reflown. • The |terminal| now supports OSC 8 escape sequences and will display hyperlinks in supporting host terminals. +• The |terminal| now uses the actual cursor, rather than a "virtual" cursor. + This means that escape codes sent by applications running in a terminal + buffer can change the cursor shape and visibility. However, it also + means that the |TermCursorNC| highlight group is no longer supported: an + unfocused terminal window will have no cursor at all (so there is nothing to + highlight). +• |jobstart()| gained the "term" flag. +• The |terminal| will send theme update notifications when 'background' is + changed and DEC mode 2031 is enabled. +• The |terminal| has experimental support for the Kitty keyboard protocol + (sometimes called "CSI u" key encoding). Only the "Disambiguate escape + codes" mode is currently supported. TREESITTER • |LanguageTree:node_for_range()| gets anonymous and named nodes for a range • |vim.treesitter.get_node()| now takes an option `include_anonymous`, default false, which allows it to return anonymous nodes as well as named nodes. +• |treesitter-directive-trim!| can trim all whitespace (not just empty lines) + from both sides of a node. +• |vim.treesitter.get_captures_at_pos()| now returns the `id` of each capture +• New |TSNode:child_with_descendant()|, which efficiently gets the node's + child that contains a given node as descendant. +• |LanguageTree:parse()| optionally supports asynchronous invocation, which is + activated by passing the `on_parse` callback parameter. +• |vim.treesitter.query.set()| can now inherit and/or extend runtime file + queries in addition to overriding. +• |LanguageTree:is_valid()| now accepts a range parameter to narrow the scope + of the validity check. +• |:InspectTree| now shows which nodes are missing. TUI @@ -272,6 +392,8 @@ TUI :lua =vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan) • |log| messages written by the builtin UI client (TUI, |--remote-ui|) are now prefixed with "ui" instead of "?". +• The TUI will re-query the terminal's background color when a theme update + notification is received and Nvim will update 'background' accordingly. UI @@ -279,7 +401,7 @@ UI which controls the tool used to open the given path or URL. If you want to globally set this, you can override vim.ui.open using the same approach described at |vim.paste()|. -- `vim.ui.open()` now supports +• `vim.ui.open()` now supports [lemonade](https://github.com/lemonade-command/lemonade) as an option for opening urls/files. This is handy if you are in an ssh connection and use `lemonade`. @@ -287,8 +409,16 @@ UI |hl-PmenuSel| and |hl-PmenuMatch| both inherit from |hl-Pmenu|, and |hl-PmenuMatchSel| inherits highlights from both |hl-PmenuSel| and |hl-PmenuMatch|. - +• |vim.diagnostic.setqflist()| updates an existing quickfix list with the + given title if found • |ui-messages| content chunks now also contain the highlight group ID. +• |:checkhealth| can display in a floating window, controlled by the + |g:health| variable. + +VIMSCRIPT + +• |getchar()| and |getcharstr()| have optional {opts} |Dict| argument to control: + cursor behavior, return type, and whether to simplify the returned key. ============================================================================== CHANGED FEATURES *news-changed* @@ -309,9 +439,14 @@ These existing features changed their behavior. more emoji characters than before, including those encoded with multiple emoji codepoints combined with ZWJ (zero width joiner) codepoints. -• Text in the 'statusline', 'tabline', and 'winbar' now inherits highlights - from the respective |hl-StatusLine|, |hl-TabLine|, and |hl-WinBar| highlight - groups. + This also applies to :terminal output, where width of cells will be calculated + using the upgraded implementation. + +• Custom highlights in 'rulerformat', 'statuscolumn', 'statusline', 'tabline', + 'winbar', and the sign/number column are stacked with their respective + highlight groups, as opposed to |hl-Normal|. + This is also reflected in the `highlights` from |nvim_eval_statusline()|, + with a new `groups` field containing an array of stacked highlight groups. • |vim.on_key()| callbacks won't be invoked recursively when a callback itself consumes input. @@ -320,6 +455,11 @@ These existing features changed their behavior. current window, and it no longer throws |E444| when there is only one window on the screen. Global variable `vim.g.pager` is removed. +• Default 'titlestring' is now implemented with 'statusline' "%" format items. + This means the default, empty value is essentially an alias to: + `%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim`. This is only an + implementation simplification, not a behavior change. + ============================================================================== REMOVED FEATURES *news-removed* diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt index 86e344c654..8593511dbc 100644 --- a/runtime/doc/nvim.txt +++ b/runtime/doc/nvim.txt @@ -6,21 +6,23 @@ Nvim *nvim* *neovim* *nvim-intro* -Nvim is based on Vim by Bram Moolenaar. +Nvim is based on Vim by Bram Moolenaar. Nvim is emphatically a fork of Vim, +not a clone: compatibility with Vim (especially editor and Vimscript features, +except |Vim9script|) is maintained where possible. See |vim-differences| for +the complete reference. -If you already use Vim see |nvim-from-vim| for a quickstart. -If you are new to Vim, try the 30-minute tutorial: >vim +If you already use Vim, see |nvim-from-vim| for a quickstart. If you just +installed Nvim and have never used it before, watch this 10-minute +video: https://youtu.be/TQn2hJeHQbM . - :Tutor<Enter> - -Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim -(especially editor and Vimscript features) is maintained where possible. See -|vim-differences| for the complete reference of differences from Vim. +To learn how to use Vim in 30 minutes, try the tutorial: >vim + :Tutor<Enter> +< Type |gO| to see the table of contents. ============================================================================== -Transitioning from Vim *nvim-from-vim* +Transitioning from Vim *nvim-from-vim* 1. To start the transition, create your |init.vim| (user config) file: >vim @@ -71,4 +73,20 @@ the same Nvim configuration on all of your machines, by creating source ~/.config/nvim/init.vim ============================================================================== +What next? *nvim-quickstart* + +If you are just trying out Nvim for a few minutes, and want to see the +extremes of what it can do, try one of these popular "extension packs" or +"distributions" (Note: Nvim is not affiliated with these projects, and does +not support them): + +- *kickstart* https://github.com/nvim-lua/kickstart.nvim +- *lazyvim* https://www.lazyvim.org/ +- *nvchad* https://nvchad.com/ + +However, in general, we recommend (eventually) taking time to learn Nvim from +its stock configuration, and incrementally setting options and adding plugins +to your |config| as you find an explicit need to do so. + +============================================================================== vim:tw=78:ts=8:et:ft=help:norl: diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 97d5082e9e..b35049343d 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -1559,9 +1559,9 @@ A jump table for the options with a short description can be found at |Q_op|. a match from the menu. Only works in combination with "menu" or "menuone". No effect if "longest" is present. - noselect Do not select a match in the menu, force the user to - select one from the menu. Only works in combination with - "menu" or "menuone". + noselect Same as "noinsert", except that no menu item is + pre-selected. If both "noinsert" and "noselect" are + present, "noselect" has precedence. fuzzy Enable |fuzzy-matching| for completion candidates. This allows for more flexible and intuitive matching, where @@ -1571,6 +1571,16 @@ A jump table for the options with a short description can be found at |Q_op|. list of alternatives, but not how the candidates are collected (using different completion types). + nosort Disable sorting of completion candidates based on fuzzy + scores when "fuzzy" is enabled. Candidates will appear + in their original order. + + preinsert + Preinsert the portion of the first candidate word that is + not part of the current completion leader and using the + |hl-ComplMatchIns| highlight group. Does not work when + "fuzzy" is also included. + *'completeslash'* *'csl'* 'completeslash' 'csl' string (default "") local to buffer @@ -2027,11 +2037,20 @@ A jump table for the options with a short description can be found at |Q_op|. Option settings for diff mode. It can consist of the following items. All are optional. Items must be separated by a comma. - filler Show filler lines, to keep the text - synchronized with a window that has inserted - lines at the same position. Mostly useful - when windows are side-by-side and 'scrollbind' - is set. + algorithm:{text} Use the specified diff algorithm with the + internal diff engine. Currently supported + algorithms are: + myers the default algorithm + minimal spend extra time to generate the + smallest possible diff + patience patience diff algorithm + histogram histogram diff algorithm + + closeoff When a window is closed where 'diff' is set + and there is only one window remaining in the + same tab page with 'diff' set, execute + `:diffoff` in that window. This undoes a + `:diffsplit` command. context:{n} Use a context of {n} lines between a change and a fold that contains unchanged lines. @@ -2042,6 +2061,23 @@ A jump table for the options with a short description can be found at |Q_op|. value (999999) to disable folding completely. See |fold-diff|. + filler Show filler lines, to keep the text + synchronized with a window that has inserted + lines at the same position. Mostly useful + when windows are side-by-side and 'scrollbind' + is set. + + foldcolumn:{n} Set the 'foldcolumn' option to {n} when + starting diff mode. Without this 2 is used. + + followwrap Follow the 'wrap' option and leave as it is. + + horizontal Start diff mode with horizontal splits (unless + explicitly specified otherwise). + + hiddenoff Do not use diff mode for a buffer when it + becomes hidden. + iblank Ignore changes where lines are all blank. Adds the "-B" flag to the "diff" command if 'diffexpr' is empty. Check the documentation @@ -2055,6 +2091,17 @@ A jump table for the options with a short description can be found at |Q_op|. are considered the same. Adds the "-i" flag to the "diff" command if 'diffexpr' is empty. + indent-heuristic + Use the indent heuristic for the internal + diff library. + + internal Use the internal diff library. This is + ignored when 'diffexpr' is set. *E960* + When running out of memory when writing a + buffer this item will be ignored for diffs + involving that buffer. Set the 'verbose' + option to see when this happens. + iwhite Ignore changes in amount of white space. Adds the "-b" flag to the "diff" command if 'diffexpr' is empty. Check the documentation @@ -2074,56 +2121,19 @@ A jump table for the options with a short description can be found at |Q_op|. of the "diff" command for what this does exactly. - horizontal Start diff mode with horizontal splits (unless - explicitly specified otherwise). + linematch:{n} Align and mark changes between the most + similar lines between the buffers. When the + total number of lines in the diff hunk exceeds + {n}, the lines will not be aligned because for + very large diff hunks there will be a + noticeable lag. A reasonable setting is + "linematch:60", as this will enable alignment + for a 2 buffer diff hunk of 30 lines each, + or a 3 buffer diff hunk of 20 lines each. vertical Start diff mode with vertical splits (unless explicitly specified otherwise). - closeoff When a window is closed where 'diff' is set - and there is only one window remaining in the - same tab page with 'diff' set, execute - `:diffoff` in that window. This undoes a - `:diffsplit` command. - - hiddenoff Do not use diff mode for a buffer when it - becomes hidden. - - foldcolumn:{n} Set the 'foldcolumn' option to {n} when - starting diff mode. Without this 2 is used. - - followwrap Follow the 'wrap' option and leave as it is. - - internal Use the internal diff library. This is - ignored when 'diffexpr' is set. *E960* - When running out of memory when writing a - buffer this item will be ignored for diffs - involving that buffer. Set the 'verbose' - option to see when this happens. - - indent-heuristic - Use the indent heuristic for the internal - diff library. - - linematch:{n} Enable a second stage diff on each generated - hunk in order to align lines. When the total - number of lines in a hunk exceeds {n}, the - second stage diff will not be performed as - very large hunks can cause noticeable lag. A - recommended setting is "linematch:60", as this - will enable alignment for a 2 buffer diff with - hunks of up to 30 lines each, or a 3 buffer - diff with hunks of up to 20 lines each. - - algorithm:{text} Use the specified diff algorithm with the - internal diff engine. Currently supported - algorithms are: - myers the default algorithm - minimal spend extra time to generate the - smallest possible diff - patience patience diff algorithm - histogram histogram diff algorithm - Examples: >vim set diffopt=internal,filler,context:4 set diffopt= @@ -2977,7 +2987,7 @@ A jump table for the options with a short description can be found at |Q_op|. 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") +'guicursor' 'gcr' string (default "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20,t:block-blinkon500-blinkoff500-TermCursor") global Configures the cursor style for each mode. Works in the GUI and many terminals. See |tui-cursor-shape|. @@ -3005,6 +3015,7 @@ A jump table for the options with a short description can be found at |Q_op|. ci Command-line Insert mode cr Command-line Replace mode sm showmatch in Insert mode + t Terminal mode a all modes The argument-list is a dash separated list of these arguments: hor{N} horizontal bar, {N} percent of the character height @@ -3021,7 +3032,8 @@ A jump table for the options with a short description can be found at |Q_op|. cursor is not shown. Times are in msec. When one of the numbers is zero, there is no blinking. E.g.: >vim set guicursor=n:blinkon0 -< - Default is "blinkon0" for each mode. +< + Default is "blinkon0" for each mode. {group-name} Highlight group that decides the color and font of the cursor. @@ -3197,7 +3209,7 @@ A jump table for the options with a short description can be found at |Q_op|. global A history of ":" commands, and a history of previous search patterns is remembered. This option decides how many entries may be stored in - each of these histories (see |cmdline-editing| and 'msghistory' for + each of these histories (see |cmdline-editing| and 'messagesopt' for the number of messages to remember). The maximum value is 10000. @@ -4045,6 +4057,28 @@ A jump table for the options with a short description can be found at |Q_op|. generated from a list of items, e.g., the Buffers menu. Changing this option has no direct effect, the menu must be refreshed first. + *'messagesopt'* *'mopt'* +'messagesopt' 'mopt' string (default "hit-enter,history:500") + global + Option settings for outputting messages. It can consist of the + following items. Items must be separated by a comma. + + hit-enter Use a |hit-enter| prompt when the message is longer than + 'cmdheight' size. + + wait:{n} Instead of using a |hit-enter| prompt, simply wait for + {n} milliseconds so that the user has a chance to read + the message. The maximum value of {n} is 10000. Use + 0 to disable the wait (but then the user may miss an + important message). + This item is ignored when "hit-enter" is present, but + required when "hit-enter" is not present. + + history:{n} Determines how many entries are remembered in the + |:messages| history. The maximum value is 10000. + Setting it to zero clears the message history. + This item must always be present. + *'mkspellmem'* *'msm'* 'mkspellmem' 'msm' string (default "460000,2000,500") global @@ -4290,12 +4324,6 @@ A jump table for the options with a short description can be found at |Q_op|. Defines the maximum time in msec between two mouse clicks for the second click to be recognized as a multi click. - *'msghistory'* *'mhi'* -'msghistory' 'mhi' number (default 500) - global - Determines how many entries are remembered in the |:messages| history. - The maximum value is 10000. - *'nrformats'* *'nf'* 'nrformats' 'nf' string (default "bin,hex") local to buffer @@ -4639,8 +4667,8 @@ A jump table for the options with a short description can be found at |Q_op|. 'redrawtime' 'rdt' number (default 2000) global Time in milliseconds for redrawing the display. Applies to - 'hlsearch', 'inccommand', |:match| highlighting and syntax - highlighting. + 'hlsearch', 'inccommand', |:match| highlighting, syntax highlighting, + and async |LanguageTree:parse()|. When redrawing takes more than this many milliseconds no further matches will be highlighted. For syntax highlighting the time applies per window. When over the @@ -4794,6 +4822,7 @@ A jump table for the options with a short description can be found at |Q_op|. indent/ indent scripts |indent-expression| keymap/ key mapping files |mbyte-keymap| lang/ menu translations |:menutrans| + lsp/ LSP client configurations |lsp-config| lua/ |Lua| plugins menu.vim GUI menus |menu.vim| pack/ packages |:packadd| @@ -4965,6 +4994,8 @@ A jump table for the options with a short description can be found at |Q_op|. selection. When "old" is used and 'virtualedit' allows the cursor to move past the end of line the line break still isn't included. + When "exclusive" is used, cursor position in visual mode will be + adjusted for inclusive motions |inclusive-motion-selection-exclusive|. Note that when "exclusive" is used and selecting from the end backwards, you cannot include the last character of a line, when starting in Normal mode and 'virtualedit' empty. @@ -5916,6 +5947,7 @@ A jump table for the options with a short description can be found at |Q_op|. All fields except the {item} are optional. A single percent sign can be given as "%%". + *stl-%!* When the option starts with "%!" then it is used as an expression, evaluated and the result is used as the option value. Example: >vim set statusline=%!MyStatusLine() @@ -6590,6 +6622,10 @@ A jump table for the options with a short description can be found at |Q_op|. expanded according to the rules used for 'statusline'. If it contains an invalid '%' format, the value is used as-is and no error or warning will be given when the value is set. + + The default behaviour is equivalent to: >vim + set titlestring=%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim +< This option cannot be set in a modeline when 'modelineexpr' is off. Example: >vim diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt index 7f0938be05..be913e941e 100644 --- a/runtime/doc/pattern.txt +++ b/runtime/doc/pattern.txt @@ -1485,6 +1485,7 @@ criteria: - Matches at a camel case character (e.g. Case in CamelCase) - Matches after a path separator or a hyphen. - The number of unmatched characters in a string. + - A full/exact match is preferred. The matching string with the highest score is returned first. For example, when you search for the "get pat" string using fuzzy matching, it diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt deleted file mode 100644 index 09d1369d46..0000000000 --- a/runtime/doc/pi_netrw.txt +++ /dev/null @@ -1,4373 +0,0 @@ -*pi_netrw.txt* For Vim version 8.2. Last change: 2020 Aug 15 - - ------------------------------------------------ - NETRW REFERENCE MANUAL by Charles E. Campbell - ------------------------------------------------ -Author: Charles E. Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> - (remove NOSPAM from Campbell's email first) - -Copyright: Copyright (C) 2017 Charles E Campbell *netrw-copyright* - The VIM LICENSE applies to the files in this package, including - netrw.vim, pi_netrw.txt, netrwFileHandlers.vim, netrwSettings.vim, and - syntax/netrw.vim. Like anything else that's free, netrw.vim and its - associated files are provided *as is* and comes with no warranty of - any kind, either expressed or implied. No guarantees of - merchantability. No guarantees of suitability for any purpose. By - using this plugin, you agree that in no event will the copyright - holder be liable for any damages resulting from the use of this - software. Use at your own risk! - - *netrw* - *dav* *ftp* *netrw-file* *rcp* *scp* - *davs* *http* *netrw.vim* *rsync* *sftp* - *fetch* *network* - -============================================================================== -1. Contents *netrw-contents* {{{1 - -1. Contents..............................................|netrw-contents| -2. Starting With Netrw...................................|netrw-start| -3. Netrw Reference.......................................|netrw-ref| - EXTERNAL APPLICATIONS AND PROTOCOLS.................|netrw-externapp| - READING.............................................|netrw-read| - WRITING.............................................|netrw-write| - SOURCING............................................|netrw-source| - DIRECTORY LISTING...................................|netrw-dirlist| - CHANGING THE USERID AND PASSWORD....................|netrw-chgup| - VARIABLES AND SETTINGS..............................|netrw-variables| - PATHS...............................................|netrw-path| -4. Network-Oriented File Transfer........................|netrw-xfer| - NETRC...............................................|netrw-netrc| - PASSWORD............................................|netrw-passwd| -5. Activation............................................|netrw-activate| -6. Transparent Remote File Editing.......................|netrw-transparent| -7. Ex Commands...........................................|netrw-ex| -8. Variables and Options.................................|netrw-variables| -9. Browsing..............................................|netrw-browse| - Introduction To Browsing............................|netrw-intro-browse| - Quick Reference: Maps...............................|netrw-browse-maps| - Quick Reference: Commands...........................|netrw-browse-cmds| - Banner Display......................................|netrw-I| - Bookmarking A Directory.............................|netrw-mb| - Browsing............................................|netrw-cr| - Squeezing the Current Tree-Listing Directory........|netrw-s-cr| - Browsing With A Horizontally Split Window...........|netrw-o| - Browsing With A New Tab.............................|netrw-t| - Browsing With A Vertically Split Window.............|netrw-v| - Change Listing Style (thin wide long tree)..........|netrw-i| - Changing To A Bookmarked Directory..................|netrw-gb| - Quick hide/unhide of dot-files......................|netrw-gh| - Changing local-only File Permission.................|netrw-gp| - Changing To A Predecessor Directory.................|netrw-u| - Changing To A Successor Directory...................|netrw-U| - Customizing Browsing With A Special Handler.........|netrw-x| - Deleting Bookmarks..................................|netrw-mB| - Deleting Files Or Directories.......................|netrw-D| - Directory Exploring Commands........................|netrw-explore| - Exploring With Stars and Patterns...................|netrw-star| - Displaying Information About File...................|netrw-qf| - Edit File Or Directory Hiding List..................|netrw-ctrl-h| - Editing The Sorting Sequence........................|netrw-S| - Forcing treatment as a file or directory............|netrw-gd| |netrw-gf| - Going Up............................................|netrw--| - Hiding Files Or Directories.........................|netrw-a| - Improving Browsing..................................|netrw-ssh-hack| - Listing Bookmarks And History.......................|netrw-qb| - Making A New Directory..............................|netrw-d| - Making The Browsing Directory The Current Directory.|netrw-cd| - Marking Files.......................................|netrw-mf| - Unmarking Files.....................................|netrw-mF| - Marking Files By Location List......................|netrw-qL| - Marking Files By QuickFix List......................|netrw-qF| - Marking Files By Regular Expression.................|netrw-mr| - Marked Files: Arbitrary Shell Command...............|netrw-mx| - Marked Files: Arbitrary Shell Command, En Bloc......|netrw-mX| - Marked Files: Arbitrary Vim Command.................|netrw-mv| - Marked Files: Argument List.........................|netrw-ma| |netrw-mA| - Marked Files: Buffer List...........................|netrw-cb| |netrw-cB| - Marked Files: Compression And Decompression.........|netrw-mz| - Marked Files: Copying...............................|netrw-mc| - Marked Files: Diff..................................|netrw-md| - Marked Files: Editing...............................|netrw-me| - Marked Files: Grep..................................|netrw-mg| - Marked Files: Hiding and Unhiding by Suffix.........|netrw-mh| - Marked Files: Moving................................|netrw-mm| - Marked Files: Sourcing..............................|netrw-ms| - Marked Files: Setting the Target Directory..........|netrw-mt| - Marked Files: Tagging...............................|netrw-mT| - Marked Files: Target Directory Using Bookmarks......|netrw-Tb| - Marked Files: Target Directory Using History........|netrw-Th| - Marked Files: Unmarking.............................|netrw-mu| - Netrw Browser Variables.............................|netrw-browser-var| - Netrw Browsing And Option Incompatibilities.........|netrw-incompatible| - Netrw Settings Window...............................|netrw-settings-window| - Obtaining A File....................................|netrw-O| - Preview Window......................................|netrw-p| - Previous Window.....................................|netrw-P| - Refreshing The Listing..............................|netrw-ctrl-l| - Reversing Sorting Order.............................|netrw-r| - Renaming Files Or Directories.......................|netrw-R| - Selecting Sorting Style.............................|netrw-s| - Setting Editing Window..............................|netrw-C| -10. Problems and Fixes....................................|netrw-problems| -11. Debugging Netrw Itself................................|netrw-debug| -12. History...............................................|netrw-history| -13. Todo..................................................|netrw-todo| -14. Credits...............................................|netrw-credits| - -============================================================================== -2. Starting With Netrw *netrw-start* {{{1 - -Netrw makes reading files, writing files, browsing over a network, and -local browsing easy! First, make sure that you have plugins enabled, so -you'll need to have at least the following in your <.vimrc>: -(or see |netrw-activate|) > - - set nocp " 'compatible' is not set - filetype plugin on " plugins are enabled -< -(see |'cp'| and |:filetype-plugin-on|) - -Netrw supports "transparent" editing of files on other machines using urls -(see |netrw-transparent|). As an example of this, let's assume you have an -account on some other machine; if you can use scp, try: > - - vim scp://hostname/path/to/file -< -Want to make ssh/scp easier to use? Check out |netrw-ssh-hack|! - -So, what if you have ftp, not ssh/scp? That's easy, too; try > - - vim ftp://hostname/path/to/file -< -Want to make ftp simpler to use? See if your ftp supports a file called -<.netrc> -- typically it goes in your home directory, has read/write -permissions for only the user to read (ie. not group, world, other, etc), -and has lines resembling > - - machine HOSTNAME login USERID password "PASSWORD" - machine HOSTNAME login USERID password "PASSWORD" - ... - default login USERID password "PASSWORD" -< -Windows' ftp doesn't support .netrc; however, one may have in one's .vimrc: > - - let g:netrw_ftp_cmd= 'c:\Windows\System32\ftp -s:C:\Users\MyUserName\MACHINE' -< -Netrw will substitute the host's machine name for "MACHINE" from the URL it is -attempting to open, and so one may specify > - userid - password -for each site in a separate file: c:\Users\MyUserName\MachineName. - -Now about browsing -- when you just want to look around before editing a -file. For browsing on your current host, just "edit" a directory: > - - vim . - vim /home/userid/path -< -For browsing on a remote host, "edit" a directory (but make sure that -the directory name is followed by a "/"): > - - vim scp://hostname/ - vim ftp://hostname/path/to/dir/ -< -See |netrw-browse| for more! - -There are more protocols supported by netrw than just scp and ftp, too: see the -next section, |netrw-externapp|, on how to use these external applications with -netrw and vim. - -PREVENTING LOADING *netrw-noload* - -If you want to use plugins, but for some reason don't wish to use netrw, then -you need to avoid loading both the plugin and the autoload portions of netrw. -You may do so by placing the following two lines in your <.vimrc>: > - - :let g:loaded_netrw = 1 - :let g:loaded_netrwPlugin = 1 -< - -============================================================================== -3. Netrw Reference *netrw-ref* {{{1 - - Netrw supports several protocols in addition to scp and ftp as mentioned - in |netrw-start|. These include dav, fetch, http,... well, just look - at the list in |netrw-externapp|. Each protocol is associated with a - variable which holds the default command supporting that protocol. - -EXTERNAL APPLICATIONS AND PROTOCOLS *netrw-externapp* {{{2 - - Protocol Variable Default Value - -------- ---------------- ------------- - dav: *g:netrw_dav_cmd* = "cadaver" if cadaver is executable - dav: g:netrw_dav_cmd = "curl -o" elseif curl is available - fetch: *g:netrw_fetch_cmd* = "fetch -o" if fetch is available - ftp: *g:netrw_ftp_cmd* = "ftp" - http: *g:netrw_http_cmd* = "elinks" if elinks is available - http: g:netrw_http_cmd = "links" elseif links is available - http: g:netrw_http_cmd = "curl" elseif curl is available - http: g:netrw_http_cmd = "wget" elseif wget is available - http: g:netrw_http_cmd = "fetch" elseif fetch is available - http: *g:netrw_http_put_cmd* = "curl -T" - rcp: *g:netrw_rcp_cmd* = "rcp" - rsync: *g:netrw_rsync_cmd* = "rsync" (see |g:netrw_rsync_sep|) - scp: *g:netrw_scp_cmd* = "scp -q" - sftp: *g:netrw_sftp_cmd* = "sftp" - file: *g:netrw_file_cmd* = "elinks" or "links" - - *g:netrw_http_xcmd* : the option string for http://... protocols are - specified via this variable and may be independently overridden. By - default, the option arguments for the http-handling commands are: > - - elinks : "-source >" - links : "-dump >" - curl : "-L -o" - wget : "-q -O" - fetch : "-o" -< - For example, if your system has elinks, and you'd rather see the - page using an attempt at rendering the text, you may wish to have > - let g:netrw_http_xcmd= "-dump >" -< in your .vimrc. - - g:netrw_http_put_cmd: this option specifies both the executable and - any needed options. This command does a PUT operation to the url. - - -READING *netrw-read* *netrw-nread* {{{2 - - Generally, one may just use the URL notation with a normal editing - command, such as > - - :e ftp://[user@]machine/path -< - Netrw also provides the Nread command: - - :Nread ? give help - :Nread "machine:path" uses rcp - :Nread "machine path" uses ftp w/ <.netrc> - :Nread "machine id password path" uses ftp - :Nread "dav://machine[:port]/path" uses cadaver - :Nread "fetch://[user@]machine/path" uses fetch - :Nread "ftp://[user@]machine[[:#]port]/path" uses ftp w/ <.netrc> - :Nread "http://[user@]machine/path" uses http uses wget - :Nread "rcp://[user@]machine/path" uses rcp - :Nread "rsync://[user@]machine[:port]/path" uses rsync - :Nread "scp://[user@]machine[[:#]port]/path" uses scp - :Nread "sftp://[user@]machine/path" uses sftp - -WRITING *netrw-write* *netrw-nwrite* {{{2 - - One may just use the URL notation with a normal file writing - command, such as > - - :w ftp://[user@]machine/path -< - Netrw also provides the Nwrite command: - - :Nwrite ? give help - :Nwrite "machine:path" uses rcp - :Nwrite "machine path" uses ftp w/ <.netrc> - :Nwrite "machine id password path" uses ftp - :Nwrite "dav://machine[:port]/path" uses cadaver - :Nwrite "ftp://[user@]machine[[:#]port]/path" uses ftp w/ <.netrc> - :Nwrite "rcp://[user@]machine/path" uses rcp - :Nwrite "rsync://[user@]machine[:port]/path" uses rsync - :Nwrite "scp://[user@]machine[[:#]port]/path" uses scp - :Nwrite "sftp://[user@]machine/path" uses sftp - http: not supported! - -SOURCING *netrw-source* {{{2 - - One may just use the URL notation with the normal file sourcing - command, such as > - - :so ftp://[user@]machine/path -< - Netrw also provides the Nsource command: - - :Nsource ? give help - :Nsource "dav://machine[:port]/path" uses cadaver - :Nsource "fetch://[user@]machine/path" uses fetch - :Nsource "ftp://[user@]machine[[:#]port]/path" uses ftp w/ <.netrc> - :Nsource "http://[user@]machine/path" uses http uses wget - :Nsource "rcp://[user@]machine/path" uses rcp - :Nsource "rsync://[user@]machine[:port]/path" uses rsync - :Nsource "scp://[user@]machine[[:#]port]/path" uses scp - :Nsource "sftp://[user@]machine/path" uses sftp - -DIRECTORY LISTING *netrw-trailingslash* *netrw-dirlist* {{{2 - - One may browse a directory to get a listing by simply attempting to - edit the directory: > - - :e scp://[user]@hostname/path/ - :e ftp://[user]@hostname/path/ -< - For remote directory listings (ie. those using scp or ftp), that - trailing "/" is necessary (the slash tells netrw to treat the argument - as a directory to browse instead of as a file to download). - - The Nread command may also be used to accomplish this (again, that - trailing slash is necessary): > - - :Nread [protocol]://[user]@hostname/path/ -< - *netrw-login* *netrw-password* -CHANGING USERID AND PASSWORD *netrw-chgup* *netrw-userpass* {{{2 - - Attempts to use ftp will prompt you for a user-id and a password. - These will be saved in global variables |g:netrw_uid| and - |s:netrw_passwd|; subsequent use of ftp will re-use those two strings, - thereby simplifying use of ftp. However, if you need to use a - different user id and/or password, you'll want to call |NetUserPass()| - first. To work around the need to enter passwords, check if your ftp - supports a <.netrc> file in your home directory. Also see - |netrw-passwd| (and if you're using ssh/scp hoping to figure out how - to not need to use passwords for scp, look at |netrw-ssh-hack|). - - :NetUserPass [uid [password]] -- prompts as needed - :call NetUserPass() -- prompts for uid and password - :call NetUserPass("uid") -- prompts for password - :call NetUserPass("uid","password") -- sets global uid and password - -(Related topics: |ftp| |netrw-userpass| |netrw-start|) - -NETRW VARIABLES AND SETTINGS *netrw-variables* {{{2 - (Also see: - |netrw-browser-var| : netrw browser option variables - |netrw-protocol| : file transfer protocol option variables - |netrw-settings| : additional file transfer options - |netrw-browser-options| : these options affect browsing directories - ) - -Netrw provides a lot of variables which allow you to customize netrw to your -preferences. One way to look at them is via the command :NetrwSettings (see -|netrw-settings|) which will display your current netrw settings. Most such -settings are described below, in |netrw-browser-options|, and in -|netrw-externapp|: - - *b:netrw_lastfile* last file Network-read/written retained on a - per-buffer basis (supports plain :Nw ) - - *g:netrw_bufsettings* the settings that netrw buffers have - (default) noma nomod nonu nowrap ro nobl - - *g:netrw_chgwin* specifies a window number where subsequent file edits - will take place. (also see |netrw-C|) - (default) -1 - - *g:Netrw_funcref* specifies a function (or functions) to be called when - netrw edits a file. The file is first edited, and - then the function reference (|Funcref|) is called. - This variable may also hold a |List| of Funcrefs. - (default) not defined. (the capital in g:Netrw... - is required by its holding a function reference) -> - Example: place in .vimrc; affects all file opening - fun! MyFuncRef() - endfun - let g:Netrw_funcref= function("MyFuncRef") - -< - *g:Netrw_UserMaps* specifies a function or |List| of functions which can - be used to set up user-specified maps and functionality. - See |netrw-usermaps| - - *g:netrw_ftp* if it doesn't exist, use default ftp - =0 use default ftp (uid password) - =1 use alternate ftp method (user uid password) - If you're having trouble with ftp, try changing the - value of this variable to see if the alternate ftp - method works for your setup. - - *g:netrw_ftp_options* Chosen by default, these options are supposed to - turn interactive prompting off and to restrain ftp - from attempting auto-login upon initial connection. - However, it appears that not all ftp implementations - support this (ex. ncftp). - ="-i -n" - - *g:netrw_ftpextracmd* default: doesn't exist - If this variable exists, then any string it contains - will be placed into the commands set to your ftp - client. As an example: - ="passive" - - *g:netrw_ftpmode* ="binary" (default) - ="ascii" - - *g:netrw_ignorenetrc* =0 (default for linux, cygwin) - =1 If you have a <.netrc> file but it doesn't work and - you want it ignored, then set this variable as - shown. (default for Windows + cmd.exe) - - *g:netrw_menu* =0 disable netrw's menu - =1 (default) netrw's menu enabled - - *g:netrw_nogx* if this variable exists, then the "gx" map will not - be available (see |netrw-gx|) - - *g:netrw_uid* (ftp) user-id, retained on a per-vim-session basis - *s:netrw_passwd* (ftp) password, retained on a per-vim-session basis - - *g:netrw_preview* =0 (default) preview window shown in a horizontally - split window - =1 preview window shown in a vertically split window. - Also affects the "previous window" (see |netrw-P|) - in the same way. - The |g:netrw_alto| variable may be used to provide - additional splitting control: - g:netrw_preview g:netrw_alto result - 0 0 |:aboveleft| - 0 1 |:belowright| - 1 0 |:topleft| - 1 1 |:botright| - To control sizing, see |g:netrw_winsize| - - *g:netrw_scpport* = "-P" : option to use to set port for scp - *g:netrw_sshport* = "-p" : option to use to set port for ssh - - *g:netrw_sepchr* =\0xff - =\0x01 for enc == euc-jp (and perhaps it should be for - others, too, please let me know) - Separates priority codes from filenames internally. - See |netrw-p12|. - - *g:netrw_silent* =0 : transfers done normally - =1 : transfers done silently - - *g:netrw_use_errorwindow* =2: messages from netrw will use a popup window - Move the mouse and pause to remove the popup window. - =1 : messages from netrw will use a separate one - line window. This window provides reliable - delivery of messages. - =0 : (default) messages from netrw will use echoerr ; - messages don't always seem to show up this - way, but one doesn't have to quit the window. - - *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) - =0 assume Windows' scp accepts windows-style paths - Network browsing uses dir instead of ls - This option is ignored if you're using unix - - *g:netrw_use_nt_rcp* =0 don't use the rcp of WinNT, Win2000 and WinXP - =1 use WinNT's rcp in binary mode (default) - -PATHS *netrw-path* {{{2 - -Paths to files are generally user-directory relative for most protocols. -It is possible that some protocol will make paths relative to some -associated directory, however. -> - example: vim scp://user@host/somefile - example: vim scp://user@host/subdir1/subdir2/somefile -< -where "somefile" is in the "user"'s home directory. If you wish to get a -file using root-relative paths, use the full path: -> - example: vim scp://user@host//somefile - example: vim scp://user@host//subdir1/subdir2/somefile -< - -============================================================================== -4. Network-Oriented File Transfer *netrw-xfer* {{{1 - -Network-oriented file transfer under Vim is implemented by a vim script -(<netrw.vim>) using plugin techniques. It currently supports both reading and -writing across networks using rcp, scp, ftp or ftp+<.netrc>, scp, fetch, -dav/cadaver, rsync, or sftp. - -http is currently supported read-only via use of wget or fetch. - -<netrw.vim> is a standard plugin which acts as glue between Vim and the -various file transfer programs. It uses autocommand events (BufReadCmd, -FileReadCmd, BufWriteCmd) to intercept reads/writes with url-like filenames. > - - ex. vim ftp://hostname/path/to/file -< -The characters preceding the colon specify the protocol to use; in the -example, it's ftp. The <netrw.vim> script then formulates a command or a -series of commands (typically ftp) which it issues to an external program -(ftp, scp, etc) which does the actual file transfer/protocol. Files are read -from/written to a temporary file (under Unix/Linux, /tmp/...) which the -<netrw.vim> script will clean up. - -Now, a word about Jan Minář's "FTP User Name and Password Disclosure"; first, -ftp is not a secure protocol. User names and passwords are transmitted "in -the clear" over the internet; any snooper tool can pick these up; this is not -a netrw thing, this is a ftp thing. If you're concerned about this, please -try to use scp or sftp instead. - -Netrw re-uses the user id and password during the same vim session and so long -as the remote hostname remains the same. - -Jan seems to be a bit confused about how netrw handles ftp; normally multiple -commands are performed in a "ftp session", and he seems to feel that the -uid/password should only be retained over one ftp session. However, netrw -does every ftp operation in a separate "ftp session"; so remembering the -uid/password for just one "ftp session" would be the same as not remembering -the uid/password at all. IMHO this would rapidly grow tiresome as one -browsed remote directories, for example. - -On the other hand, thanks go to Jan M. for pointing out the many -vulnerabilities that netrw (and vim itself) had had in handling "crafted" -filenames. The |shellescape()| and |fnameescape()| functions were written in -response by Bram Moolenaar to handle these sort of problems, and netrw has -been modified to use them. Still, my advice is, if the "filename" looks like -a vim command that you aren't comfortable with having executed, don't open it. - - *netrw-putty* *netrw-pscp* *netrw-psftp* -One may modify any protocol's implementing external application by setting a -variable (ex. scp uses the variable g:netrw_scp_cmd, which is defaulted to -"scp -q"). As an example, consider using PuTTY: > - - let g:netrw_scp_cmd = '"c:\Program Files\PuTTY\pscp.exe" -q -batch' - let g:netrw_sftp_cmd= '"c:\Program Files\PuTTY\psftp.exe"' -< -(note: it has been reported that windows 7 with putty v0.6's "-batch" option - doesn't work, so its best to leave it off for that system) - -See |netrw-p8| for more about putty, pscp, psftp, etc. - -Ftp, an old protocol, seems to be blessed by numerous implementations. -Unfortunately, some implementations are noisy (ie., add junk to the end of the -file). Thus, concerned users may decide to write a NetReadFixup() function -that will clean up after reading with their ftp. Some Unix systems (ie., -FreeBSD) provide a utility called "fetch" which uses the ftp protocol but is -not noisy and more convenient, actually, for <netrw.vim> to use. -Consequently, if "fetch" is available (ie. executable), it may be preferable -to use it for ftp://... based transfers. - -For rcp, scp, sftp, and http, one may use network-oriented file transfers -transparently; ie. -> - vim rcp://[user@]machine/path - vim scp://[user@]machine/path -< -If your ftp supports <.netrc>, then it too can be transparently used -if the needed triad of machine name, user id, and password are present in -that file. Your ftp must be able to use the <.netrc> file on its own, however. -> - vim ftp://[user@]machine[[:#]portnumber]/path -< -Windows provides an ftp (typically c:\Windows\System32\ftp.exe) which uses -an option, -s:filename (filename can and probably should be a full path) -which contains ftp commands which will be automatically run whenever ftp -starts. You may use this feature to enter a user and password for one site: > - userid - password -< *netrw-windows-netrc* *netrw-windows-s* -If |g:netrw_ftp_cmd| contains -s:[path/]MACHINE, then (on Windows machines -only) netrw will substitute the current machine name requested for ftp -connections for MACHINE. Hence one can have multiple machine.ftp files -containing login and password for ftp. Example: > - - let g:netrw_ftp_cmd= 'c:\Windows\System32\ftp -s:C:\Users\Myself\MACHINE' - vim ftp://myhost.somewhere.net/ - -will use a file > - - C:\Users\Myself\myhost.ftp -< -Often, ftp will need to query the user for the userid and password. -The latter will be done "silently"; ie. asterisks will show up instead of -the actually-typed-in password. Netrw will retain the userid and password -for subsequent read/writes from the most recent transfer so subsequent -transfers (read/write) to or from that machine will take place without -additional prompting. - - *netrw-urls* - +=================================+============================+============+ - | Reading | Writing | Uses | - +=================================+============================+============+ - | DAV: | | | - | dav://host/path | | cadaver | - | :Nread dav://host/path | :Nwrite dav://host/path | cadaver | - +---------------------------------+----------------------------+------------+ - | DAV + SSL: | | | - | davs://host/path | | cadaver | - | :Nread davs://host/path | :Nwrite davs://host/path | cadaver | - +---------------------------------+----------------------------+------------+ - | FETCH: | | | - | fetch://[user@]host/path | | | - | fetch://[user@]host:http/path | Not Available | fetch | - | :Nread fetch://[user@]host/path| | | - +---------------------------------+----------------------------+------------+ - | FILE: | | | - | file:///* | file:///* | | - | file://localhost/* | file://localhost/* | | - +---------------------------------+----------------------------+------------+ - | FTP: (*3) | (*3) | | - | ftp://[user@]host/path | ftp://[user@]host/path | ftp (*2) | - | :Nread ftp://host/path | :Nwrite ftp://host/path | ftp+.netrc | - | :Nread host path | :Nwrite host path | ftp+.netrc | - | :Nread host uid pass path | :Nwrite host uid pass path | ftp | - +---------------------------------+----------------------------+------------+ - | HTTP: wget is executable: (*4) | | | - | http://[user@]host/path | Not Available | wget | - +---------------------------------+----------------------------+------------+ - | HTTP: fetch is executable (*4) | | | - | http://[user@]host/path | Not Available | fetch | - +---------------------------------+----------------------------+------------+ - | RCP: | | | - | rcp://[user@]host/path | rcp://[user@]host/path | rcp | - +---------------------------------+----------------------------+------------+ - | RSYNC: | | | - | rsync://[user@]host/path | rsync://[user@]host/path | rsync | - | :Nread rsync://host/path | :Nwrite rsync://host/path | rsync | - | :Nread rcp://host/path | :Nwrite rcp://host/path | rcp | - +---------------------------------+----------------------------+------------+ - | SCP: | | | - | scp://[user@]host/path | scp://[user@]host/path | scp | - | :Nread scp://host/path | :Nwrite scp://host/path | scp (*1) | - +---------------------------------+----------------------------+------------+ - | SFTP: | | | - | sftp://[user@]host/path | sftp://[user@]host/path | sftp | - | :Nread sftp://host/path | :Nwrite sftp://host/path | sftp (*1) | - +=================================+============================+============+ - - (*1) For an absolute path use scp://machine//path. - - (*2) if <.netrc> is present, it is assumed that it will - work with your ftp client. Otherwise the script will - prompt for user-id and password. - - (*3) for ftp, "machine" may be machine#port or machine:port - if a different port is needed than the standard ftp port - - (*4) for http:..., if wget is available it will be used. Otherwise, - if fetch is available it will be used. - -Both the :Nread and the :Nwrite ex-commands can accept multiple filenames. - - -NETRC *netrw-netrc* - -The <.netrc> file, typically located in your home directory, contains lines -therein which map a hostname (machine name) to the user id and password you -prefer to use with it. - -The typical syntax for lines in a <.netrc> file is given as shown below. -Ftp under Unix usually supports <.netrc>; ftp under Windows usually doesn't. -> - machine {full machine name} login {user-id} password "{password}" - default login {user-id} password "{password}" - -Your ftp client must handle the use of <.netrc> on its own, but if the -<.netrc> file exists, an ftp transfer will not ask for the user-id or -password. - - Note: - Since this file contains passwords, make very sure nobody else can - read this file! Most programs will refuse to use a .netrc that is - readable for others. Don't forget that the system administrator can - still read the file! Ie. for Linux/Unix: chmod 600 .netrc - -Even though Windows' ftp clients typically do not support .netrc, netrw has -a work-around: see |netrw-windows-s|. - - -PASSWORD *netrw-passwd* - -The script attempts to get passwords for ftp invisibly using |inputsecret()|, -a built-in Vim function. See |netrw-userpass| for how to change the password -after one has set it. - -Unfortunately there doesn't appear to be a way for netrw to feed a password to -scp. Thus every transfer via scp will require re-entry of the password. -However, |netrw-ssh-hack| can help with this problem. - - -============================================================================== -5. Activation *netrw-activate* {{{1 - -Network-oriented file transfers are available by default whenever Vim's -|'nocompatible'| mode is enabled. Netrw's script files reside in your -system's plugin, autoload, and syntax directories; just the -plugin/netrwPlugin.vim script is sourced automatically whenever you bring up -vim. The main script in autoload/netrw.vim is only loaded when you actually -use netrw. I suggest that, at a minimum, you have at least the following in -your <.vimrc> customization file: > - - set nocp - if version >= 600 - filetype plugin indent on - endif -< -By also including the following lines in your .vimrc, one may have netrw -immediately activate when using [g]vim without any filenames, showing the -current directory: > - - " Augroup VimStartup: - augroup VimStartup - au! - au VimEnter * if expand("%") == "" | e . | endif - augroup END -< - -============================================================================== -6. Transparent Remote File Editing *netrw-transparent* {{{1 - -Transparent file transfers occur whenever a regular file read or write -(invoked via an |:autocmd| for |BufReadCmd|, |BufWriteCmd|, or |SourceCmd| -events) is made. Thus one may read, write, or source files across networks -just as easily as if they were local files! > - - vim ftp://[user@]machine/path - ... - :wq - -See |netrw-activate| for more on how to encourage your vim to use plugins -such as netrw. - -For password-free use of scp:, see |netrw-ssh-hack|. - - -============================================================================== -7. Ex Commands *netrw-ex* {{{1 - -The usual read/write commands are supported. There are also a few -additional commands available. Often you won't need to use Nwrite or -Nread as shown in |netrw-transparent| (ie. simply use > - :e URL - :r URL - :w URL -instead, as appropriate) -- see |netrw-urls|. In the explanations -below, a {netfile} is a URL to a remote file. - - *:Nwrite* *:Nw* -:[range]Nw[rite] Write the specified lines to the current - file as specified in b:netrw_lastfile. - (related: |netrw-nwrite|) - -:[range]Nw[rite] {netfile} [{netfile}]... - Write the specified lines to the {netfile}. - - *:Nread* *:Nr* -:Nr[ead] Read the lines from the file specified in b:netrw_lastfile - into the current buffer. (related: |netrw-nread|) - -:Nr[ead] {netfile} {netfile}... - Read the {netfile} after the current line. - - *:Nsource* *:Ns* -:Ns[ource] {netfile} - Source the {netfile}. - To start up vim using a remote .vimrc, one may use - the following (all on one line) (tnx to Antoine Mechelynck) > - vim -u NORC -N - --cmd "runtime plugin/netrwPlugin.vim" - --cmd "source scp://HOSTNAME/.vimrc" -< (related: |netrw-source|) - -:call NetUserPass() *NetUserPass()* - If g:netrw_uid and s:netrw_passwd don't exist, - this function will query the user for them. - (related: |netrw-userpass|) - -:call NetUserPass("userid") - This call will set the g:netrw_uid and, if - the password doesn't exist, will query the user for it. - (related: |netrw-userpass|) - -:call NetUserPass("userid","passwd") - This call will set both the g:netrw_uid and s:netrw_passwd. - The user-id and password are used by ftp transfers. One may - effectively remove the user-id and password by using empty - strings (ie. ""). - (related: |netrw-userpass|) - -:NetrwSettings This command is described in |netrw-settings| -- used to - display netrw settings and change netrw behavior. - - -============================================================================== -8. Variables and Options *netrw-var* *netrw-settings* {{{1 - -(also see: |netrw-options| |netrw-variables| |netrw-protocol| - |netrw-browser-settings| |netrw-browser-options| ) - -The <netrw.vim> script provides several variables which act as options to -affect <netrw.vim>'s file transfer behavior. These variables typically may be -set in the user's <.vimrc> file: (see also |netrw-settings| |netrw-protocol|) - *netrw-options* -> - ------------- - Netrw Options - ------------- - Option Meaning - -------------- ----------------------------------------------- -< - b:netrw_col Holds current cursor position (during NetWrite) - g:netrw_cygwin =1 assume scp under windows is from cygwin - (default/windows) - =0 assume scp under windows accepts windows - style paths (default/else) - g:netrw_ftp =0 use default ftp (uid password) - g:netrw_ftpmode ="binary" (default) - ="ascii" (your choice) - g:netrw_ignorenetrc =1 (default) - if you have a <.netrc> file but you don't - want it used, then set this variable. Its - mere existence is enough to cause <.netrc> - to be ignored. - b:netrw_lastfile Holds latest method/machine/path. - b:netrw_line Holds current line number (during NetWrite) - g:netrw_silent =0 transfers done normally - =1 transfers done silently - 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 - ----------------------------------------------------------------------- -< - *netrw-internal-variables* -The script will also make use of the following variables internally, albeit -temporarily. -> - ------------------- - Temporary Variables - ------------------- - Variable Meaning - -------- ------------------------------------ -< - b:netrw_method Index indicating rcp/ftp+.netrc/ftp - w:netrw_method (same as b:netrw_method) - g:netrw_machine Holds machine name parsed from input - b:netrw_fname Holds filename being accessed > - ------------------------------------------------------------ -< - *netrw-protocol* - -Netrw supports a number of protocols. These protocols are invoked using the -variables listed below, and may be modified by the user. -> - ------------------------ - Protocol Control Options - ------------------------ - Option Type Setting Meaning - --------- -------- -------------- --------------------------- -< netrw_ftp variable =doesn't exist userid set by "user userid" - =0 userid set by "user userid" - =1 userid set by "userid" - NetReadFixup function =doesn't exist no change - =exists Allows user to have files - read via ftp automatically - transformed however they wish - by NetReadFixup() - g:netrw_dav_cmd var ="cadaver" if cadaver is executable - g:netrw_dav_cmd var ="curl -o" elseif curl is executable - g:netrw_fetch_cmd var ="fetch -o" if fetch is available - g:netrw_ftp_cmd var ="ftp" - g:netrw_http_cmd var ="fetch -o" if fetch is available - g:netrw_http_cmd var ="wget -O" else if wget is available - g:netrw_http_put_cmd var ="curl -T" - |g:netrw_list_cmd| var ="ssh USEPORT HOSTNAME ls -Fa" - g:netrw_rcp_cmd var ="rcp" - g:netrw_rsync_cmd var ="rsync" - *g:netrw_rsync_sep* var ="/" used to separate the hostname - from the file spec - g:netrw_scp_cmd var ="scp -q" - g:netrw_sftp_cmd var ="sftp" > - ------------------------------------------------------------------------- -< - *netrw-ftp* - -The g:netrw_..._cmd options (|g:netrw_ftp_cmd| and |g:netrw_sftp_cmd|) -specify the external program to use handle the ftp protocol. They may -include command line options (such as -p for passive mode). Example: > - - let g:netrw_ftp_cmd= "ftp -p" -< -Browsing is supported by using the |g:netrw_list_cmd|; the substring -"HOSTNAME" will be changed via substitution with whatever the current request -is for a hostname. - -Two options (|g:netrw_ftp| and |netrw-fixup|) both help with certain ftp's -that give trouble . In order to best understand how to use these options if -ftp is giving you troubles, a bit of discussion is provided on how netrw does -ftp reads. - -For ftp, netrw typically builds up lines of one of the following formats in a -temporary file: -> - IF g:netrw_ftp !exists or is not 1 IF g:netrw_ftp exists and is 1 - ---------------------------------- ------------------------------ -< - open machine [port] open machine [port] - user userid password userid password - [g:netrw_ftpmode] password - [g:netrw_ftpextracmd] [g:netrw_ftpmode] - get filename tempfile [g:netrw_extracmd] - get filename tempfile > - --------------------------------------------------------------------- -< -The |g:netrw_ftpmode| and |g:netrw_ftpextracmd| are optional. - -Netrw then executes the lines above by use of a filter: -> - :%! {g:netrw_ftp_cmd} -i [-n] -< -where - g:netrw_ftp_cmd is usually "ftp", - -i tells ftp not to be interactive - -n means don't use netrc and is used for Method #3 (ftp w/o <.netrc>) - -If <.netrc> exists it will be used to avoid having to query the user for -userid and password. The transferred file is put into a temporary file. -The temporary file is then read into the main editing session window that -requested it and the temporary file deleted. - -If your ftp doesn't accept the "user" command and immediately just demands a -userid, then try putting "let netrw_ftp=1" in your <.vimrc>. - - *netrw-cadaver* -To handle the SSL certificate dialog for untrusted servers, one may pull -down the certificate and place it into /usr/ssl/cert.pem. This operation -renders the server treatment as "trusted". - - *netrw-fixup* *netreadfixup* -If your ftp for whatever reason generates unwanted lines (such as AUTH -messages) you may write a NetReadFixup() function: -> - function! NetReadFixup(method,line1,line2) - " a:line1: first new line in current file - " a:line2: last new line in current file - if a:method == 1 "rcp - elseif a:method == 2 "ftp + <.netrc> - elseif a:method == 3 "ftp + machine,uid,password,filename - elseif a:method == 4 "scp - elseif a:method == 5 "http/wget - elseif a:method == 6 "dav/cadaver - elseif a:method == 7 "rsync - elseif a:method == 8 "fetch - elseif a:method == 9 "sftp - else " complain - endif - endfunction -> -The NetReadFixup() function will be called if it exists and thus allows you to -customize your reading process. - -(Related topics: |ftp| |netrw-userpass| |netrw-start|) - -============================================================================== -9. Browsing *netrw-browsing* *netrw-browse* *netrw-help* {{{1 - *netrw-browser* *netrw-dir* *netrw-list* - -INTRODUCTION TO BROWSING *netrw-intro-browse* {{{2 - (Quick References: |netrw-quickmaps| |netrw-quickcoms|) - -Netrw supports the browsing of directories on your local system and on remote -hosts; browsing includes listing files and directories, entering directories, -editing files therein, deleting files/directories, making new directories, -moving (renaming) files and directories, copying files and directories, etc. -One may mark files and execute any system command on them! The Netrw browser -generally implements the previous explorer's maps and commands for remote -directories, although details (such as pertinent global variable names) -necessarily differ. To browse a directory, simply "edit" it! > - - vim /your/directory/ - vim . - vim c:\your\directory\ -< -(Related topics: |netrw-cr| |netrw-o| |netrw-p| |netrw-P| |netrw-t| - |netrw-mf| |netrw-mx| |netrw-D| |netrw-R| |netrw-v| ) - -The Netrw remote file and directory browser handles two protocols: ssh and -ftp. The protocol in the url, if it is ftp, will cause netrw also to use ftp -in its remote browsing. Specifying any other protocol will cause it to be -used for file transfers; but the ssh protocol will be used to do remote -browsing. - -To use Netrw's remote directory browser, simply attempt to read a "file" with -a trailing slash and it will be interpreted as a request to list a directory: -> - vim [protocol]://[user@]hostname/path/ -< -where [protocol] is typically scp or ftp. As an example, try: > - - vim ftp://ftp.home.vim.org/pub/vim/ -< -For local directories, the trailing slash is not required. Again, because it's -easy to miss: to browse remote directories, the URL must terminate with a -slash! - -If you'd like to avoid entering the password repeatedly for remote directory -listings with ssh or scp, see |netrw-ssh-hack|. To avoid password entry with -ftp, see |netrw-netrc| (if your ftp supports it). - -There are several things you can do to affect the browser's display of files: - - * To change the listing style, press the "i" key (|netrw-i|). - Currently there are four styles: thin, long, wide, and tree. - To make that change "permanent", see |g:netrw_liststyle|. - - * To hide files (don't want to see those xyz~ files anymore?) see - |netrw-ctrl-h|. - - * Press s to sort files by name, time, or size. - -See |netrw-browse-cmds| for all the things you can do with netrw! - - *netrw-getftype* *netrw-filigree* *netrw-ftype* -The |getftype()| function is used to append a bit of filigree to indicate -filetype to locally listed files: - - directory : / - executable : * - fifo : | - links : @ - sockets : = - -The filigree also affects the |g:netrw_sort_sequence|. - - -QUICK HELP *netrw-quickhelp* {{{2 - (Use ctrl-] to select a topic)~ - Intro to Browsing...............................|netrw-intro-browse| - Quick Reference: Maps.........................|netrw-quickmap| - Quick Reference: Commands.....................|netrw-browse-cmds| - Hiding - Edit hiding list..............................|netrw-ctrl-h| - Hiding Files or Directories...................|netrw-a| - Hiding/Unhiding by suffix.....................|netrw-mh| - Hiding dot-files.............................|netrw-gh| - Listing Style - Select listing style (thin/long/wide/tree)....|netrw-i| - Associated setting variable...................|g:netrw_liststyle| - Shell command used to perform listing.........|g:netrw_list_cmd| - Quick file info...............................|netrw-qf| - Sorted by - Select sorting style (name/time/size).........|netrw-s| - Editing the sorting sequence..................|netrw-S| - Sorting options...............................|g:netrw_sort_options| - Associated setting variable...................|g:netrw_sort_sequence| - Reverse sorting order.........................|netrw-r| - - - *netrw-quickmap* *netrw-quickmaps* -QUICK REFERENCE: MAPS *netrw-browse-maps* {{{2 -> - --- ----------------- ---- - Map Quick Explanation Link - --- ----------------- ---- -< <F1> Causes Netrw to issue help - <cr> Netrw will enter the directory or read the file |netrw-cr| - <del> Netrw will attempt to remove the file/directory |netrw-del| - <c-h> Edit file hiding list |netrw-ctrl-h| - <c-l> Causes Netrw to refresh the directory listing |netrw-ctrl-l| - <c-r> Browse using a gvim server |netrw-ctrl-r| - <c-tab> Shrink/expand a netrw/explore window |netrw-c-tab| - - Makes Netrw go up one directory |netrw--| - a Cycles between normal display, |netrw-a| - hiding (suppress display of files matching g:netrw_list_hide) - and showing (display only files which match g:netrw_list_hide) - cd Make browsing directory the current directory |netrw-cd| - C Setting the editing window |netrw-C| - d Make a directory |netrw-d| - D Attempt to remove the file(s)/directory(ies) |netrw-D| - gb Go to previous bookmarked directory |netrw-gb| - gd Force treatment as directory |netrw-gd| - gf Force treatment as file |netrw-gf| - gh Quick hide/unhide of dot-files |netrw-gh| - gn Make top of tree the directory below the cursor |netrw-gn| - gp Change local-only file permissions |netrw-gp| - i Cycle between thin, long, wide, and tree listings |netrw-i| - I Toggle the displaying of the banner |netrw-I| - mb Bookmark current directory |netrw-mb| - mc Copy marked files to marked-file target directory |netrw-mc| - md Apply diff to marked files (up to 3) |netrw-md| - me Place marked files on arg list and edit them |netrw-me| - mf Mark a file |netrw-mf| - mF Unmark files |netrw-mF| - mg Apply vimgrep to marked files |netrw-mg| - mh Toggle marked file suffices' presence on hiding list |netrw-mh| - mm Move marked files to marked-file target directory |netrw-mm| - mr Mark files using a shell-style |regexp| |netrw-mr| - mt Current browsing directory becomes markfile target |netrw-mt| - mT Apply ctags to marked files |netrw-mT| - mu Unmark all marked files |netrw-mu| - mv Apply arbitrary vim command to marked files |netrw-mv| - mx Apply arbitrary shell command to marked files |netrw-mx| - mX Apply arbitrary shell command to marked files en bloc|netrw-mX| - mz Compress/decompress marked files |netrw-mz| - o Enter the file/directory under the cursor in a new |netrw-o| - browser window. A horizontal split is used. - O Obtain a file specified by cursor |netrw-O| - p Preview the file |netrw-p| - P Browse in the previously used window |netrw-P| - qb List bookmarked directories and history |netrw-qb| - qf Display information on file |netrw-qf| - qF Mark files using a quickfix list |netrw-qF| - qL Mark files using a |location-list| |netrw-qL| - r Reverse sorting order |netrw-r| - R Rename the designated file(s)/directory(ies) |netrw-R| - s Select sorting style: by name, time, or file size |netrw-s| - S Specify suffix priority for name-sorting |netrw-S| - t Enter the file/directory under the cursor in a new tab|netrw-t| - u Change to recently-visited directory |netrw-u| - U Change to subsequently-visited directory |netrw-U| - v Enter the file/directory under the cursor in a new |netrw-v| - browser window. A vertical split is used. - x View file with an associated program |netrw-x| - X Execute filename under cursor via |system()| |netrw-X| - - % Open a new file in netrw's current directory |netrw-%| - - *netrw-mouse* *netrw-leftmouse* *netrw-middlemouse* *netrw-rightmouse* - <leftmouse> (gvim only) selects word under mouse as if a <cr> - had been pressed (ie. edit file, change directory) - <middlemouse> (gvim only) same as P selecting word under mouse; - see |netrw-P| - <rightmouse> (gvim only) delete file/directory using word under - mouse - <2-leftmouse> (gvim only) when: - * in a netrw-selected file, AND - * |g:netrw_retmap| == 1 AND - * the user doesn't already have a <2-leftmouse> - mapping defined before netrw is autoloaded, - then a double clicked leftmouse button will return - to the netrw browser window. See |g:netrw_retmap|. - <s-leftmouse> (gvim only) like mf, will mark files. Dragging - the shifted leftmouse will mark multiple files. - (see |netrw-mf|) - - (to disable mouse buttons while browsing: |g:netrw_mousemaps|) - - *netrw-quickcom* *netrw-quickcoms* -QUICK REFERENCE: COMMANDS *netrw-explore-cmds* *netrw-browse-cmds* {{{2 - :NetrwClean[!]............................................|netrw-clean| - :NetrwSettings............................................|netrw-settings| - :Ntree....................................................|netrw-ntree| - :Explore[!] [dir] Explore directory of current file......|netrw-explore| - :Hexplore[!] [dir] Horizontal Split & Explore.............|netrw-explore| - :Lexplore[!] [dir] Left Explorer Toggle...................|netrw-explore| - :Nexplore[!] [dir] Vertical Split & Explore...............|netrw-explore| - :Pexplore[!] [dir] Vertical Split & Explore...............|netrw-explore| - :Rexplore Return to Explorer.....................|netrw-explore| - :Sexplore[!] [dir] Split & Explore directory .............|netrw-explore| - :Texplore[!] [dir] Tab & Explore..........................|netrw-explore| - :Vexplore[!] [dir] Vertical Split & Explore...............|netrw-explore| - - -BANNER DISPLAY *netrw-I* - -One may toggle the displaying of the banner by pressing "I". - -Also See: |g:netrw_banner| - - -BOOKMARKING A DIRECTORY *netrw-mb* *netrw-bookmark* *netrw-bookmarks* {{{2 - -One may easily "bookmark" the currently browsed directory by using > - - mb -< - *.netrwbook* -Bookmarks are retained in between sessions of vim in a file called .netrwbook -as a |List|, which is typically stored in the first directory on the user's -'runtimepath'; entries are kept in sorted order. - -If there are marked files and/or directories, mb will add them to the bookmark -list. - - *netrw-:NetrwMB* -Additionally, one may use :NetrwMB to bookmark files or directories. > - - :NetrwMB[!] [files/directories] - -< No bang: enters files/directories into Netrw's bookmark system - - No argument and in netrw buffer: - if there are marked files : bookmark marked files - otherwise : bookmark file/directory under cursor - No argument and not in netrw buffer: bookmarks current open file - Has arguments : |glob()|s each arg and bookmarks them - - With bang: deletes files/directories from Netrw's bookmark system - -The :NetrwMB command is available outside of netrw buffers (once netrw has been -invoked in the session). - -The file ".netrwbook" holds bookmarks when netrw (and vim) is not active. By -default, its stored on the first directory on the user's |'runtimepath'|. - -Related Topics: - |netrw-gb| how to return (go) to a bookmark - |netrw-mB| how to delete bookmarks - |netrw-qb| how to list bookmarks - |g:netrw_home| controls where .netrwbook is kept - - -BROWSING *netrw-enter* *netrw-cr* {{{2 - -Browsing is simple: move the cursor onto a file or directory of interest. -Hitting the <cr> (the return key) will select the file or directory. -Directories will themselves be listed, and files will be opened using the -protocol given in the original read request. - - CAVEAT: There are four forms of listing (see |netrw-i|). Netrw assumes that - two or more spaces delimit filenames and directory names for the long and - wide listing formats. Thus, if your filename or directory name has two or - more sequential spaces embedded in it, or any trailing spaces, then you'll - need to use the "thin" format to select it. - -The |g:netrw_browse_split| option, which is zero by default, may be used to -cause the opening of files to be done in a new window or tab instead of the -default. When the option is one or two, the splitting will be taken -horizontally or vertically, respectively. When the option is set to three, a -<cr> will cause the file to appear in a new tab. - - -When using the gui (gvim), one may select a file by pressing the <leftmouse> -button. In addition, if - - * |g:netrw_retmap| == 1 AND (its default value is 0) - * in a netrw-selected file, AND - * the user doesn't already have a <2-leftmouse> mapping defined before - netrw is loaded - -then a doubly-clicked leftmouse button will return to the netrw browser -window. - -Netrw attempts to speed up browsing, especially for remote browsing where one -may have to enter passwords, by keeping and re-using previously obtained -directory listing buffers. The |g:netrw_fastbrowse| variable is used to -control this behavior; one may have slow browsing (no buffer re-use), medium -speed browsing (re-use directory buffer listings only for remote directories), -and fast browsing (re-use directory buffer listings as often as possible). -The price for such re-use is that when changes are made (such as new files -are introduced into a directory), the listing may become out-of-date. One may -always refresh directory listing buffers by pressing ctrl-L (see -|netrw-ctrl-l|). - - *netrw-s-cr* -Squeezing the Current Tree-Listing Directory~ - -When the tree listing style is enabled (see |netrw-i|) and one is using -gvim, then the <s-cr> mapping may be used to squeeze (close) the -directory currently containing the cursor. - -Otherwise, one may remap a key combination of one's own choice to get -this effect: > - - nmap <buffer> <silent> <nowait> YOURKEYCOMBO <Plug>NetrwTreeSqueeze -< -Put this line in $HOME/ftplugin/netrw/netrw.vim; it needs to be generated -for netrw buffers only. - -Related topics: - |netrw-ctrl-r| |netrw-o| |netrw-p| - |netrw-P| |netrw-t| |netrw-v| -Associated setting variables: - |g:netrw_browse_split| |g:netrw_fastbrowse| - |g:netrw_ftp_list_cmd| |g:netrw_ftp_sizelist_cmd| - |g:netrw_ftp_timelist_cmd| |g:netrw_ssh_browse_reject| - |g:netrw_ssh_cmd| |g:netrw_use_noswf| - - -BROWSING WITH A HORIZONTALLY SPLIT WINDOW *netrw-o* *netrw-horiz* {{{2 - -Normally one enters a file or directory using the <cr>. However, the "o" map -allows one to open a new window to hold the new directory listing or file. A -horizontal split is used. (for vertical splitting, see |netrw-v|) - -Normally, the o key splits the window horizontally with the new window and -cursor at the top. - -Associated setting variables: |g:netrw_alto| |g:netrw_winsize| - -Related topics: - |netrw-ctrl-r| |netrw-o| |netrw-p| - |netrw-P| |netrw-t| |netrw-v| -Associated setting variables: - |g:netrw_alto| control above/below splitting - |g:netrw_winsize| control initial sizing - -BROWSING WITH A NEW TAB *netrw-t* {{{2 - -Normally one enters a file or directory using the <cr>. The "t" map -allows one to open a new window holding the new directory listing or file in -a new tab. - -If you'd like to have the new listing in a background tab, use |gT|. - -Related topics: - |netrw-ctrl-r| |netrw-o| |netrw-p| - |netrw-P| |netrw-t| |netrw-v| -Associated setting variables: - |g:netrw_winsize| control initial sizing - -BROWSING WITH A VERTICALLY SPLIT WINDOW *netrw-v* {{{2 - -Normally one enters a file or directory using the <cr>. However, the "v" map -allows one to open a new window to hold the new directory listing or file. A -vertical split is used. (for horizontal splitting, see |netrw-o|) - -Normally, the v key splits the window vertically with the new window and -cursor at the left. - -There is only one tree listing buffer; using "v" on a displayed subdirectory -will split the screen, but the same buffer will be shown twice. - -Related topics: - |netrw-ctrl-r| |netrw-o| |netrw-p| - |netrw-P| |netrw-t| |netrw-v| -Associated setting variables: - |g:netrw_altv| control right/left splitting - |g:netrw_winsize| control initial sizing - - -BROWSING USING A GVIM SERVER *netrw-ctrl-r* {{{2 - -One may keep a browsing gvim separate from the gvim being used to edit. -Use the <c-r> map on a file (not a directory) in the netrw browser, and it -will use a gvim server (see |g:netrw_servername|). Subsequent use of <cr> -(see |netrw-cr|) will re-use that server for editing files. - -Related topics: - |netrw-ctrl-r| |netrw-o| |netrw-p| - |netrw-P| |netrw-t| |netrw-v| -Associated setting variables: - |g:netrw_servername| : sets name of server - |g:netrw_browse_split| : controls how <cr> will open files - - -CHANGE LISTING STYLE (THIN LONG WIDE TREE) *netrw-i* {{{2 - -The "i" map cycles between the thin, long, wide, and tree listing formats. - -The thin listing format gives just the files' and directories' names. - -The long listing is either based on the "ls" command via ssh for remote -directories or displays the filename, file size (in bytes), and the time and -date of last modification for local directories. With the long listing -format, netrw is not able to recognize filenames which have trailing spaces. -Use the thin listing format for such files. - -The wide listing format uses two or more contiguous spaces to delineate -filenames; when using that format, netrw won't be able to recognize or use -filenames which have two or more contiguous spaces embedded in the name or any -trailing spaces. The thin listing format will, however, work with such files. -The wide listing format is the most compact. - -The tree listing format has a top directory followed by files and directories -preceded by one or more "|"s, which indicate the directory depth. One may -open and close directories by pressing the <cr> key while atop the directory -name. - -One may make a preferred listing style your default; see |g:netrw_liststyle|. -As an example, by putting the following line in your .vimrc, > - let g:netrw_liststyle= 3 -the tree style will become your default listing style. - -One typical way to use the netrw tree display is to: > - - vim . - (use i until a tree display shows) - navigate to a file - v (edit as desired in vertically split window) - ctrl-w h (to return to the netrw listing) - P (edit newly selected file in the previous window) - ctrl-w h (to return to the netrw listing) - P (edit newly selected file in the previous window) - ...etc... -< -Associated setting variables: |g:netrw_liststyle| |g:netrw_maxfilenamelen| - |g:netrw_timefmt| |g:netrw_list_cmd| - -CHANGE FILE PERMISSION *netrw-gp* {{{2 - -"gp" will ask you for a new permission for the file named under the cursor. -Currently, this only works for local files. - -Associated setting variables: |g:netrw_chgperm| - - -CHANGING TO A BOOKMARKED DIRECTORY *netrw-gb* {{{2 - -To change directory back to a bookmarked directory, use - - {cnt}gb - -Any count may be used to reference any of the bookmarks. -Note that |netrw-qb| shows both bookmarks and history; to go -to a location stored in the history see |netrw-u| and |netrw-U|. - -Related Topics: - |netrw-mB| how to delete bookmarks - |netrw-mb| how to make a bookmark - |netrw-qb| how to list bookmarks - - -CHANGING TO A PREDECESSOR DIRECTORY *netrw-u* *netrw-updir* {{{2 - -Every time you change to a new directory (new for the current session), netrw -will save the directory in a recently-visited directory history list (unless -|g:netrw_dirhistmax| is zero; by default, it holds ten entries). With the "u" -map, one can change to an earlier directory (predecessor). To do the -opposite, see |netrw-U|. - -The "u" map also accepts counts to go back in the history several slots. For -your convenience, qb (see |netrw-qb|) lists the history number which may be -used in that count. - - *.netrwhist* -See |g:netrw_dirhistmax| for how to control the quantity of history stack -slots. The file ".netrwhist" holds history when netrw (and vim) is not -active. By default, its stored on the first directory on the user's -|'runtimepath'|. - -Related Topics: - |netrw-U| changing to a successor directory - |g:netrw_home| controls where .netrwhist is kept - - -CHANGING TO A SUCCESSOR DIRECTORY *netrw-U* *netrw-downdir* {{{2 - -With the "U" map, one can change to a later directory (successor). -This map is the opposite of the "u" map. (see |netrw-u|) Use the -qb map to list both the bookmarks and history. (see |netrw-qb|) - -The "U" map also accepts counts to go forward in the history several slots. - -See |g:netrw_dirhistmax| for how to control the quantity of history stack -slots. - - -CHANGING TREE TOP *netrw-ntree* *:Ntree* *netrw-gn* {{{2 - -One may specify a new tree top for tree listings using > - - :Ntree [dirname] - -Without a "dirname", the current line is used (and any leading depth -information is elided). -With a "dirname", the specified directory name is used. - -The "gn" map will take the word below the cursor and use that for -changing the top of the tree listing. - - -NETRW CLEAN *netrw-clean* *:NetrwClean* {{{2 - -With :NetrwClean one may easily remove netrw from one's home directory; -more precisely, from the first directory on your |'runtimepath'|. - -With :NetrwClean!, netrw will attempt to remove netrw from all directories on -your |'runtimepath'|. Of course, you have to have write/delete permissions -correct to do this. - -With either form of the command, netrw will first ask for confirmation -that the removal is in fact what you want to do. If netrw doesn't have -permission to remove a file, it will issue an error message. - -CUSTOMIZING BROWSING WITH A SPECIAL HANDLER *netrw-x* *netrw-handler* {{{2 - -Certain files, such as html, gif, jpeg, (word/office) doc, etc, files, are -best seen with a special handler (ie. a tool provided with your computer's -operating system). Netrw allows one to invoke such special handlers by: - - * hitting gx with the cursor atop the file path or alternatively x - in a netrw buffer; the former can be disabled by defining the - |g:netrw_nogx| variable - * when in command line, typing :Open <path>, see |:Open| below. - -One may also use visual mode (see |visual-start|) to select the text that the -special handler will use. Normally gx checks for a close-by URL or file name -to pick up the text under the cursor; one may change what |expand()| uses via the -|g:netrw_gx| variable (options include "<cword>", "<cWORD>"). Note that -expand("<cfile>") depends on the |'isfname'| setting. Alternatively, one may -select the text to be used by gx by making a visual selection (see -|visual-block|) and then pressing gx. - -The selection function can be adapted for each filetype by adding a function -`Netrw_get_URL_<filetype>`, where <filetype> is given by the 'filetype'. -The function should return the URL or file name to be used by gx, and will -fall back to the default behavior if it returns an empty string. -For example, special handlers for links Markdown and HTML are - -" make gx work on concealed links regardless of exact cursor position: > - - function Netrw_get_URL_markdown() - " markdown URL such as [link text](http://ya.ru 'yandex search') - try - let save_view = winsaveview() - if searchpair('\[.\{-}\](', '', ')\zs', 'cbW', '', line('.')) > 0 - return matchstr(getline('.')[col('.')-1:], - \ '\[.\{-}\](\zs' .. g:netrw_regex_url .. '\ze\(\s\+.\{-}\)\?)') - endif - return '' - finally - call winrestview(save_view) - endtry - endfunction - - function Netrw_get_URL_html() - " HTML URL such as <a href='http://www.python.org'>Python is here</a> - " <a href="http://www.python.org"/> - try - let save_view = winsaveview() - if searchpair('<a\s\+href=', '', '\%(</a>\|/>\)\zs', 'cbW', '', line('.')) > 0 - return matchstr(getline('.')[col('.') - 1 : ], - \ 'href=["'.."'"..']\?\zs\S\{-}\ze["'.."'"..']\?/\?>') - endif - return '' - finally - call winrestview(save_view) - endtry - endfunction -< -Other than a file path, the text under the cursor may be a URL. Netrw uses -by default the following regular expression to determine if the text under the -cursor is a URL: -> - :let g:netrw_regex_url = '\%(\%(http\|ftp\|irc\)s\?\|file\)://\S\{-}' -< -Associated setting variables: - |g:netrw_gx| control how gx picks up the text under the cursor - |g:netrw_nogx| prevent gx map while editing - |g:netrw_suppress_gx_mesg| controls gx's suppression of browser messages - -OPENING FILES AND LAUNCHING APPS *netrw-gx* *:Open* *:Launch* {{{2 - -Netrw determines which special handler by the following method: - - * if |g:netrw_browsex_viewer| exists, then it will be used to attempt to - view files. - If the viewer you wish to use does not support handling of a remote URL - directory, set |g:netrw_browsex_support_remote| to 0. - * otherwise: - - * for Windows : explorer.exe is used - * for Mac OS X : open is used. - * for Linux : xdg-open is used. - -To open a path (or URL) <path> by the appropriate handler, type > - - :Open <path> -< -No escaping, neither for the shell nor for Vim's command-line, is needed. - -To launch a specific application <app> <args>, often <args> being <path> > - - :Launch <app> <args>. - -Since <args> can be arbitrarily complex, in particular contain many file -paths, the escaping is left to the user. - -If you disabled the netrw plugin by setting g:loaded_netrwPlugin (see -|netrw-noload|), then you can use > - - :call netrw#Launch('<app> <args>') - :call netrw#Open('<path>') -< - *netrw-curdir* -DELETING BOOKMARKS *netrw-mB* {{{2 - -To delete a bookmark, use > - - {cnt}mB - -If there are marked files, then mB will remove them from the -bookmark list. - -Alternatively, one may use :NetrwMB! (see |netrw-:NetrwMB|). > - - :NetrwMB! [files/directories] - -Related Topics: - |netrw-gb| how to return (go) to a bookmark - |netrw-mb| how to make a bookmark - |netrw-qb| how to list bookmarks - - -DELETING FILES OR DIRECTORIES *netrw-delete* *netrw-D* *netrw-del* {{{2 - -If files have not been marked with |netrw-mf|: (local marked file list) - - Deleting/removing files and directories involves moving the cursor to the - file/directory to be deleted and pressing "D". Directories must be empty - first before they can be successfully removed. If the directory is a - softlink to a directory, then netrw will make two requests to remove the - directory before succeeding. Netrw will ask for confirmation before doing - the removal(s). You may select a range of lines with the "V" command - (visual selection), and then pressing "D". - -If files have been marked with |netrw-mf|: (local marked file list) - - Marked files (and empty directories) will be deleted; again, you'll be - asked to confirm the deletion before it actually takes place. - -A further approach is to delete files which match a pattern. - - * use :MF pattern (see |netrw-:MF|); then press "D". - - * use mr (see |netrw-mr|) which will prompt you for pattern. - This will cause the matching files to be marked. Then, - press "D". - -Please note that only empty directories may be deleted with the "D" mapping. -Regular files are deleted with |delete()|, too. - -The |g:netrw_rm_cmd|, |g:netrw_rmf_cmd|, and |g:netrw_rmdir_cmd| variables are -used to control the attempts to remove remote files and directories. The -g:netrw_rm_cmd is used with files, and its default value is: - - g:netrw_rm_cmd: ssh HOSTNAME rm - -The g:netrw_rmdir_cmd variable is used to support the removal of directories. -Its default value is: - - |g:netrw_rmdir_cmd|: ssh HOSTNAME rmdir - -If removing a directory fails with g:netrw_rmdir_cmd, netrw then will attempt -to remove it again using the g:netrw_rmf_cmd variable. Its default value is: - - |g:netrw_rmf_cmd|: ssh HOSTNAME rm -f - -Related topics: |netrw-d| -Associated setting variable: |g:netrw_rm_cmd| |g:netrw_ssh_cmd| - - -*netrw-explore* *netrw-hexplore* *netrw-nexplore* *netrw-pexplore* -*netrw-rexplore* *netrw-sexplore* *netrw-texplore* *netrw-vexplore* *netrw-lexplore* -DIRECTORY EXPLORATION COMMANDS {{{2 - - :[N]Explore[!] [dir]... Explore directory of current file *:Explore* - :[N]Hexplore[!] [dir]... Horizontal Split & Explore *:Hexplore* - :[N]Lexplore[!] [dir]... Left Explorer Toggle *:Lexplore* - :[N]Sexplore[!] [dir]... Split&Explore current file's directory *:Sexplore* - :[N]Vexplore[!] [dir]... Vertical Split & Explore *:Vexplore* - :Texplore [dir]... Tab & Explore *:Texplore* - :Rexplore ... Return to/from Explorer *:Rexplore* - - Used with :Explore **/pattern : (also see |netrw-starstar|) - :Nexplore............. go to next matching file *:Nexplore* - :Pexplore............. go to previous matching file *:Pexplore* - - *netrw-:Explore* -:Explore will open the local-directory browser on the current file's - directory (or on directory [dir] if specified). The window will be - split only if the file has been modified and |'hidden'| is not set, - otherwise the browsing window will take over that window. Normally - the splitting is taken horizontally. - Also see: |netrw-:Rexplore| -:Explore! is like :Explore, but will use vertical splitting. - - *netrw-:Hexplore* -:Hexplore [dir] does an :Explore with |:belowright| horizontal splitting. -:Hexplore! [dir] does an :Explore with |:aboveleft| horizontal splitting. - - *netrw-:Lexplore* -:[N]Lexplore [dir] toggles a full height Explorer window on the left hand side - of the current tab. It will open a netrw window on the current - directory if [dir] is omitted; a :Lexplore [dir] will show the - specified directory in the left-hand side browser display no matter - from which window the command is issued. - - By default, :Lexplore will change an uninitialized |g:netrw_chgwin| - to 2; edits will thus preferentially be made in window#2. - - The [N] specifies a |g:netrw_winsize| just for the new :Lexplore - window. That means that - if [N] < 0 : use |N| columns for the Lexplore window - if [N] = 0 : a normal split is made - if [N] > 0 : use N% of the current window will be used for the - new window - - Those who like this method often also like tree style displays; - see |g:netrw_liststyle|. - -:[N]Lexplore! [dir] is similar to :Lexplore, except that the full-height - Explorer window will open on the right hand side and an - uninitialized |g:netrw_chgwin| will be set to 1 (eg. edits will - preferentially occur in the leftmost window). - - Also see: |netrw-C| |g:netrw_browse_split| |g:netrw_wiw| - |netrw-p| |netrw-P| |g:netrw_chgwin| - |netrw-c-tab| |g:netrw_winsize| - - *netrw-:Sexplore* -:[N]Sexplore will always split the window before invoking the local-directory - browser. As with Explore, the splitting is normally done - horizontally. -:[N]Sexplore! [dir] is like :Sexplore, but the splitting will be done vertically. - - *netrw-:Texplore* -:Texplore [dir] does a |:tabnew| before generating the browser window - - *netrw-:Vexplore* -:[N]Vexplore [dir] does an :Explore with |:leftabove| vertical splitting. -:[N]Vexplore! [dir] does an :Explore with |:rightbelow| vertical splitting. - -The optional parameters are: - - [N]: This parameter will override |g:netrw_winsize| to specify the quantity of - rows and/or columns the new explorer window should have. - Otherwise, the |g:netrw_winsize| variable, if it has been specified by the - user, is used to control the quantity of rows and/or columns new - explorer windows should have. - - [dir]: By default, these explorer commands use the current file's directory. - However, one may explicitly provide a directory (path) to use instead; - ie. > - - :Explore /some/path -< - *netrw-:Rexplore* -:Rexplore This command is a little different from the other Explore commands - as it doesn't necessarily open an Explorer window. - - Return to Explorer~ - When one edits a file using netrw which can occur, for example, - when pressing <cr> while the cursor is atop a filename in a netrw - browser window, a :Rexplore issued while editing that file will - return the display to that of the last netrw browser display in - that window. - - Return from Explorer~ - Conversely, when one is editing a directory, issuing a :Rexplore - will return to editing the file that was last edited in that - window. - - The <2-leftmouse> map (which is only available under gvim and - cooperative terms) does the same as :Rexplore. - -Also see: |g:netrw_alto| |g:netrw_altv| |g:netrw_winsize| - - -*netrw-star* *netrw-starpat* *netrw-starstar* *netrw-starstarpat* *netrw-grep* -EXPLORING WITH STARS AND PATTERNS {{{2 - -When Explore, Sexplore, Hexplore, or Vexplore are used with one of the -following four patterns Explore generates a list of files which satisfy the -request for the local file system. These exploration patterns will not work -with remote file browsing. - - */filepat files in current directory which satisfy filepat - **/filepat files in current directory or below which satisfy the - file pattern - *//pattern files in the current directory which contain the - pattern (vimgrep is used) - **//pattern files in the current directory or below which contain - the pattern (vimgrep is used) -< -The cursor will be placed on the first file in the list. One may then -continue to go to subsequent files on that list via |:Nexplore| or to -preceding files on that list with |:Pexplore|. Explore will update the -directory and place the cursor appropriately. - -A plain > - :Explore -will clear the explore list. - -If your console or gui produces recognizable shift-up or shift-down sequences, -then you'll likely find using shift-downarrow and shift-uparrow convenient. -They're mapped by netrw as follows: - - <s-down> == Nexplore, and - <s-up> == Pexplore. - -As an example, consider -> - :Explore */*.c - :Nexplore - :Nexplore - :Pexplore -< -The status line will show, on the right hand side of the status line, a -message like "Match 3 of 20". - -Associated setting variables: - |g:netrw_keepdir| |g:netrw_browse_split| - |g:netrw_fastbrowse| |g:netrw_ftp_browse_reject| - |g:netrw_ftp_list_cmd| |g:netrw_ftp_sizelist_cmd| - |g:netrw_ftp_timelist_cmd| |g:netrw_list_cmd| - |g:netrw_liststyle| - - -DISPLAYING INFORMATION ABOUT FILE *netrw-qf* {{{2 - -With the cursor atop a filename, pressing "qf" will reveal the file's size -and last modification timestamp. Currently this capability is only available -for local files. - - -EDIT FILE OR DIRECTORY HIDING LIST *netrw-ctrl-h* *netrw-edithide* {{{2 - -The "<ctrl-h>" map brings up a requestor allowing the user to change the -file/directory hiding list contained in |g:netrw_list_hide|. The hiding list -consists of one or more patterns delimited by commas. Files and/or -directories satisfying these patterns will either be hidden (ie. not shown) or -be the only ones displayed (see |netrw-a|). - -The "gh" mapping (see |netrw-gh|) quickly alternates between the usual -hiding list and the hiding of files or directories that begin with ".". - -As an example, > - let g:netrw_list_hide= '\(^\|\s\s\)\zs\.\S\+' -Effectively, this makes the effect of a |netrw-gh| command the initial setting. -What it means: - - \(^\|\s\s\) : if the line begins with the following, -or- - two consecutive spaces are encountered - \zs : start the hiding match now - \. : if it now begins with a dot - \S\+ : and is followed by one or more non-whitespace - characters - -Associated setting variables: |g:netrw_hide| |g:netrw_list_hide| -Associated topics: |netrw-a| |netrw-gh| |netrw-mh| - - *netrw-sort-sequence* -EDITING THE SORTING SEQUENCE *netrw-S* *netrw-sortsequence* {{{2 - -When "Sorted by" is name, one may specify priority via the sorting sequence -(g:netrw_sort_sequence). The sorting sequence typically prioritizes the -name-listing by suffix, although any pattern will do. Patterns are delimited -by commas. The default sorting sequence is (all one line): - -For Unix: > - '[\/]$,\<core\%(\.\d\+\)\=,\.[a-np-z]$,\.h$,\.c$,\.cpp$,*,\.o$,\.obj$, - \.info$,\.swp$,\.bak$,\~$' -< -Otherwise: > - '[\/]$,\.[a-np-z]$,\.h$,\.c$,\.cpp$,*,\.o$,\.obj$,\.info$, - \.swp$,\.bak$,\~$' -< -The lone * is where all filenames not covered by one of the other patterns -will end up. One may change the sorting sequence by modifying the -g:netrw_sort_sequence variable (either manually or in your <.vimrc>) or by -using the "S" map. - -Related topics: |netrw-s| |netrw-S| -Associated setting variables: |g:netrw_sort_sequence| |g:netrw_sort_options| - - -EXECUTING FILE UNDER CURSOR VIA SYSTEM() *netrw-X* {{{2 - -Pressing X while the cursor is atop an executable file will yield a prompt -using the filename asking for any arguments. Upon pressing a [return], netrw -will then call |system()| with that command and arguments. The result will be -displayed by |:echomsg|, and so |:messages| will repeat display of the result. -Ansi escape sequences will be stripped out. - -See |cmdline-window| for directions for more on how to edit the arguments. - - -FORCING TREATMENT AS A FILE OR DIRECTORY *netrw-gd* *netrw-gf* {{{2 - -Remote symbolic links (ie. those listed via ssh or ftp) are problematic -in that it is difficult to tell whether they link to a file or to a -directory. - -To force treatment as a file: use > - gf -< -To force treatment as a directory: use > - gd -< - -GOING UP *netrw--* {{{2 - -To go up a directory, press "-" or press the <cr> when atop the ../ directory -entry in the listing. - -Netrw will use the command in |g:netrw_list_cmd| to perform the directory -listing operation after changing HOSTNAME to the host specified by the -user-prpvided url. By default netrw provides the command as: > - - ssh HOSTNAME ls -FLa -< -where the HOSTNAME becomes the [user@]hostname as requested by the attempt to -read. Naturally, the user may override this command with whatever is -preferred. The NetList function which implements remote browsing -expects that directories will be flagged by a trailing slash. - - -HIDING FILES OR DIRECTORIES *netrw-a* *netrw-hiding* {{{2 - -Netrw's browsing facility allows one to use the hiding list in one of three -ways: ignore it, hide files which match, and show only those files which -match. - -If no files have been marked via |netrw-mf|: - -The "a" map allows the user to cycle through the three hiding modes. - -The |g:netrw_list_hide| variable holds a comma delimited list of patterns -based on regular expressions (ex. ^.*\.obj$,^\.) which specify the hiding list. -(also see |netrw-ctrl-h|) To set the hiding list, use the <c-h> map. As an -example, to hide files which begin with a ".", one may use the <c-h> map to -set the hiding list to '^\..*' (or one may put let g:netrw_list_hide= '^\..*' -in one's <.vimrc>). One may then use the "a" key to show all files, hide -matching files, or to show only the matching files. - - Example: \.[ch]$ - This hiding list command will hide/show all *.c and *.h files. - - Example: \.c$,\.h$ - This hiding list command will also hide/show all *.c and *.h - files. - -Don't forget to use the "a" map to select the mode (normal/hiding/show) you -want! - -If files have been marked using |netrw-mf|, then this command will: - - if showing all files or non-hidden files: - modify the g:netrw_list_hide list by appending the marked files to it - and showing only non-hidden files. - - else if showing hidden files only: - modify the g:netrw_list_hide list by removing the marked files from it - and showing only non-hidden files. - endif - - *netrw-gh* *netrw-hide* -As a quick shortcut, one may press > - gh -to toggle between hiding files which begin with a period (dot) and not hiding -them. - -Associated setting variables: |g:netrw_list_hide| |g:netrw_hide| -Associated topics: |netrw-a| |netrw-ctrl-h| |netrw-mh| - - *netrw-gitignore* -Netrw provides a helper function 'netrw_gitignore#Hide()' that, when used with -|g:netrw_list_hide| automatically hides all git-ignored files. - -'netrw_gitignore#Hide' searches for patterns in the following files: > - - './.gitignore' - './.git/info/exclude' - global gitignore file: `git config --global core.excludesfile` - system gitignore file: `git config --system core.excludesfile` -< -Files that do not exist, are ignored. -Git-ignore patterns are taken from existing files, and converted to patterns for -hiding files. For example, if you had '*.log' in your '.gitignore' file, it -would be converted to '.*\.log'. - -To use this function, simply assign its output to |g:netrw_list_hide| option. > - - Example: let g:netrw_list_hide= netrw_gitignore#Hide() - Git-ignored files are hidden in Netrw. - - Example: let g:netrw_list_hide= netrw_gitignore#Hide('my_gitignore_file') - Function can take additional files with git-ignore patterns. - - Example: let g:netrw_list_hide= netrw_gitignore#Hide() .. '.*\.swp$' - Combining 'netrw_gitignore#Hide' with custom patterns. -< - -IMPROVING BROWSING *netrw-listhack* *netrw-ssh-hack* {{{2 - -Especially with the remote directory browser, constantly entering the password -is tedious. - -For Linux/Unix systems, the book "Linux Server Hacks - 100 industrial strength -tips & tools" by Rob Flickenger (O'Reilly, ISBN 0-596-00461-3) gives a tip -for setting up no-password ssh and scp and discusses associated security -issues. It used to be available at http://hacks.oreilly.com/pub/h/66 , -but apparently that address is now being redirected to some "hackzine". -I'll attempt a summary based on that article and on a communication from -Ben Schmidt: - - 1. Generate a public/private key pair on the local machine - (ssh client): > - ssh-keygen -t rsa - (saving the file in ~/.ssh/id_rsa as prompted) -< - 2. Just hit the <CR> when asked for passphrase (twice) for no - passphrase. If you do use a passphrase, you will also need to use - ssh-agent so you only have to type the passphrase once per session. - If you don't use a passphrase, simply logging onto your local - computer or getting access to the keyfile in any way will suffice - to access any ssh servers which have that key authorized for login. - - 3. This creates two files: > - ~/.ssh/id_rsa - ~/.ssh/id_rsa.pub -< - 4. On the target machine (ssh server): > - cd - mkdir -p .ssh - chmod 0700 .ssh -< - 5. On your local machine (ssh client): (one line) > - ssh {serverhostname} - cat '>>' '~/.ssh/authorized_keys2' < ~/.ssh/id_rsa.pub -< - or, for OpenSSH, (one line) > - ssh {serverhostname} - cat '>>' '~/.ssh/authorized_keys' < ~/.ssh/id_rsa.pub -< -You can test it out with > - ssh {serverhostname} -and you should be log onto the server machine without further need to type -anything. - -If you decided to use a passphrase, do: > - ssh-agent $SHELL - ssh-add - ssh {serverhostname} -You will be prompted for your key passphrase when you use ssh-add, but not -subsequently when you use ssh. For use with vim, you can use > - ssh-agent vim -and, when next within vim, use > - :!ssh-add -Alternatively, you can apply ssh-agent to the terminal you're planning on -running vim in: > - ssh-agent xterm & -and do ssh-add whenever you need. - -For Windows, folks on the vim mailing list have mentioned that Pageant helps -with avoiding the constant need to enter the password. - -Kingston Fung wrote about another way to avoid constantly needing to enter -passwords: - - In order to avoid the need to type in the password for scp each time, you - provide a hack in the docs to set up a non password ssh account. I found a - 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! - - - Ssh hints: - - Thomer Gil has provided a hint on how to speed up netrw+ssh: - http://thomer.com/howtos/netrw_ssh.html - - Alex Young has several hints on speeding ssh up: - http://usevim.com/2012/03/16/editing-remote-files/ - - -LISTING BOOKMARKS AND HISTORY *netrw-qb* *netrw-listbookmark* {{{2 - -Pressing "qb" (query bookmarks) will list both the bookmarked directories and -directory traversal history. - -Related Topics: - |netrw-gb| how to return (go) to a bookmark - |netrw-mb| how to make a bookmark - |netrw-mB| how to delete bookmarks - |netrw-u| change to a predecessor directory via the history stack - |netrw-U| change to a successor directory via the history stack - -MAKING A NEW DIRECTORY *netrw-d* {{{2 - -With the "d" map one may make a new directory either remotely (which depends -on the global variable g:netrw_mkdir_cmd) or locally (which depends on the -global variable g:netrw_localmkdir). Netrw will issue a request for the new -directory's name. A bare <CR> at that point will abort the making of the -directory. Attempts to make a local directory that already exists (as either -a file or a directory) will be detected, reported on, and ignored. - -Related topics: |netrw-D| -Associated setting variables: |g:netrw_localmkdir| |g:netrw_mkdir_cmd| - |g:netrw_remote_mkdir| |netrw-%| - - -MAKING THE BROWSING DIRECTORY THE CURRENT DIRECTORY *netrw-cd* {{{2 - -By default, |g:netrw_keepdir| is 1. This setting means that the current -directory will not track the browsing directory. (done for backwards -compatibility with v6's file explorer). - -Setting g:netrw_keepdir to 0 tells netrw to make vim's current directory -track netrw's browsing directory. - -However, given the default setting for g:netrw_keepdir of 1 where netrw -maintains its own separate notion of the current directory, in order to make -the two directories the same, use the "cd" map (type cd). That map will -set Vim's notion of the current directory to netrw's current browsing -directory. - -|netrw-cd| : This map's name was changed from "c" to cd (see |netrw-cd|). - This change was done to allow for |netrw-cb| and |netrw-cB| maps. - -Associated setting variable: |g:netrw_keepdir| - -MARKING FILES *netrw-:MF* *netrw-mf* {{{2 - (also see |netrw-mr|) - -Netrw provides several ways to mark files: - - * One may mark files with the cursor atop a filename and - then pressing "mf". - - * With gvim, in addition one may mark files with - <s-leftmouse>. (see |netrw-mouse|) - - * One may use the :MF command, which takes a list of - files (for local directories, the list may include - wildcards -- see |glob()|) > - - :MF *.c -< - (Note that :MF uses |<f-args>| to break the line - at spaces) - - * Mark files using the |argument-list| (|netrw-mA|) - - * Mark files based upon a |location-list| (|netrw-qL|) - - * Mark files based upon the quickfix list (|netrw-qF|) - (|quickfix-error-lists|) - -The following netrw maps make use of marked files: - - |netrw-a| Hide marked files/directories - |netrw-D| Delete marked files/directories - |netrw-ma| Move marked files' names to |arglist| - |netrw-mA| Move |arglist| filenames to marked file list - |netrw-mb| Append marked files to bookmarks - |netrw-mB| Delete marked files from bookmarks - |netrw-mc| Copy marked files to target - |netrw-md| Apply vimdiff to marked files - |netrw-me| Edit marked files - |netrw-mF| Unmark marked files - |netrw-mg| Apply vimgrep to marked files - |netrw-mm| Move marked files to target - |netrw-ms| Netrw will source marked files - |netrw-mt| Set target for |netrw-mm| and |netrw-mc| - |netrw-mT| Generate tags using marked files - |netrw-mv| Apply vim command to marked files - |netrw-mx| Apply shell command to marked files - |netrw-mX| Apply shell command to marked files, en bloc - |netrw-mz| Compress/Decompress marked files - |netrw-O| Obtain marked files - |netrw-R| Rename marked files - -One may unmark files one at a time the same way one marks them; ie. place -the cursor atop a marked file and press "mf". This process also works -with <s-leftmouse> using gvim. One may unmark all files by pressing -"mu" (see |netrw-mu|). - -Marked files are highlighted using the "netrwMarkFile" highlighting group, -which by default is linked to "Identifier" (see Identifier under -|group-name|). You may change the highlighting group by putting something -like > - - highlight clear netrwMarkFile - hi link netrwMarkFile ..whatever.. -< -into $HOME/.vim/after/syntax/netrw.vim . - -If the mouse is enabled and works with your vim, you may use <s-leftmouse> to -mark one or more files. You may mark multiple files by dragging the shifted -leftmouse. (see |netrw-mouse|) - - *markfilelist* *global_markfilelist* *local_markfilelist* -All marked files are entered onto the global marked file list; there is only -one such list. In addition, every netrw buffer also has its own buffer-local -marked file list; since netrw buffers are associated with specific -directories, this means that each directory has its own local marked file -list. The various commands which operate on marked files use one or the other -of the marked file lists. - -Known Problem: if one is using tree mode (|g:netrw_liststyle|) and several -directories have files with the same name, then marking such a file will -result in all such files being highlighted as if they were all marked. The -|markfilelist|, however, will only have the selected file in it. This problem -is unlikely to be fixed. - - -UNMARKING FILES *netrw-mF* {{{2 - (also see |netrw-mf|, |netrw-mu|) - -The "mF" command will unmark all files in the current buffer. One may also use -mf (|netrw-mf|) on a specific, already marked, file to unmark just that file. - -MARKING FILES BY LOCATION LIST *netrw-qL* {{{2 - (also see |netrw-mf|) - -One may convert |location-list|s into a marked file list using "qL". -You may then proceed with commands such as me (|netrw-me|) to edit them. - - -MARKING FILES BY QUICKFIX LIST *netrw-qF* {{{2 - (also see |netrw-mf|) - -One may convert |quickfix-error-lists| into a marked file list using "qF". -You may then proceed with commands such as me (|netrw-me|) to edit them. -Quickfix error lists are generated, for example, by calls to |:vimgrep|. - - -MARKING FILES BY REGULAR EXPRESSION *netrw-mr* {{{2 - (also see |netrw-mf|) - -One may also mark files by pressing "mr"; netrw will then issue a prompt, -"Enter regexp: ". You may then enter a shell-style regular expression such -as *.c$ (see |glob()|). For remote systems, glob() doesn't work -- so netrw -converts "*" into ".*" (see |regexp|) and marks files based on that. In the -future I may make it possible to use |regexp|s instead of glob()-style -expressions (yet-another-option). - -See |cmdline-window| for directions on more on how to edit the regular -expression. - - -MARKED FILES, ARBITRARY VIM COMMAND *netrw-mv* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the local marked-file list) - -The "mv" map causes netrw to execute an arbitrary vim command on each file on -the local marked file list, individually: - - * 1split - * sil! keepalt e file - * run vim command - * sil! keepalt wq! - -A prompt, "Enter vim command: ", will be issued to elicit the vim command you -wish used. See |cmdline-window| for directions for more on how to edit the -command. - - -MARKED FILES, ARBITRARY SHELL COMMAND *netrw-mx* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the local marked-file list) - -Upon activation of the "mx" map, netrw will query the user for some (external) -command to be applied to all marked files. All "%"s in the command will be -substituted with the name of each marked file in turn. If no "%"s are in the -command, then the command will be followed by a space and a marked filename. - -Example: - (mark files) - mx - Enter command: cat - - The result is a series of shell commands: - cat 'file1' - cat 'file2' - ... - - -MARKED FILES, ARBITRARY SHELL COMMAND, EN BLOC *netrw-mX* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the global marked-file list) - -Upon activation of the 'mX' map, netrw will query the user for some (external) -command to be applied to all marked files on the global marked file list. The -"en bloc" means that one command will be executed on all the files at once: > - - command files - -This approach is useful, for example, to select files and make a tarball: > - - (mark files) - mX - Enter command: tar cf mynewtarball.tar -< -The command that will be run with this example: - - tar cf mynewtarball.tar 'file1' 'file2' ... - - -MARKED FILES: ARGUMENT LIST *netrw-ma* *netrw-mA* - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the global marked-file list) - -Using ma, one moves filenames from the marked file list to the argument list. -Using mA, one moves filenames from the argument list to the marked file list. - -See Also: |netrw-cb| |netrw-cB| |netrw-qF| |argument-list| |:args| - - -MARKED FILES: BUFFER LIST *netrw-cb* *netrw-cB* - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the global marked-file list) - -Using cb, one moves filenames from the marked file list to the buffer list. -Using cB, one copies filenames from the buffer list to the marked file list. - -See Also: |netrw-ma| |netrw-mA| |netrw-qF| |buffer-list| |:buffers| - - -MARKED FILES: COMPRESSION AND DECOMPRESSION *netrw-mz* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the local marked file list) - -If any marked files are compressed, then "mz" will decompress them. -If any marked files are decompressed, then "mz" will compress them -using the command specified by |g:netrw_compress|; by default, -that's "gzip". - -For decompression, netrw uses a |Dictionary| of suffices and their -associated decompressing utilities; see |g:netrw_decompress|. - -Remember that one can mark multiple files by regular expression -(see |netrw-mr|); this is particularly useful to facilitate compressing and -decompressing a large number of files. - -Associated setting variables: |g:netrw_compress| |g:netrw_decompress| - -MARKED FILES: COPYING *netrw-mc* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (Uses the global marked file list) - -Select a target directory with mt (|netrw-mt|). Then change directory, -select file(s) (see |netrw-mf|), and press "mc". The copy is done -from the current window (where one does the mf) to the target. - -If one does not have a target directory set with |netrw-mt|, then netrw -will query you for a directory to copy to. - -One may also copy directories and their contents (local only) to a target -directory. - -Associated setting variables: - |g:netrw_localcopycmd| |g:netrw_localcopycmdopt| - |g:netrw_localcopydircmd| |g:netrw_localcopydircmdopt| - |g:netrw_ssh_cmd| - -MARKED FILES: DIFF *netrw-md* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the global marked file list) - -Use vimdiff to visualize difference between selected files (two or -three may be selected for this). Uses the global marked file list. - -MARKED FILES: EDITING *netrw-me* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the global marked file list) - -The "me" command will place the marked files on the |arglist| and commence -editing them. One may return the to explorer window with |:Rexplore|. -(use |:n| and |:p| to edit next and previous files in the arglist) - -MARKED FILES: GREP *netrw-mg* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the global marked file list) - -The "mg" command will apply |:vimgrep| to the marked files. -The command will ask for the requested pattern; one may then enter: > - - /pattern/[g][j] - ! /pattern/[g][j] - pattern -< -With /pattern/, editing will start with the first item on the |quickfix| list -that vimgrep sets up (see |:copen|, |:cnext|, |:cprevious|, |:cclose|). The |:vimgrep| -command is in use, so without 'g' each line is added to quickfix list only -once; with 'g' every match is included. - -With /pattern/j, "mg" will winnow the current marked file list to just those -marked files also possessing the specified pattern. Thus, one may use > - - mr ...file-pattern... - mg /pattern/j -< -to have a marked file list satisfying the file-pattern but also restricted to -files containing some desired pattern. - - -MARKED FILES: HIDING AND UNHIDING BY SUFFIX *netrw-mh* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the local marked file list) - -The "mh" command extracts the suffices of the marked files and toggles their -presence on the hiding list. Please note that marking the same suffix -this way multiple times will result in the suffix's presence being toggled -for each file (so an even quantity of marked files having the same suffix -is the same as not having bothered to select them at all). - -Related topics: |netrw-a| |g:netrw_list_hide| - -MARKED FILES: MOVING *netrw-mm* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the global marked file list) - - WARNING: moving files is more dangerous than copying them. - A file being moved is first copied and then deleted; if the - copy operation fails and the delete succeeds, you will lose - the file. Either try things out with unimportant files - first or do the copy and then delete yourself using mc and D. - Use at your own risk! - -Select a target directory with mt (|netrw-mt|). Then change directory, -select file(s) (see |netrw-mf|), and press "mm". The move is done -from the current window (where one does the mf) to the target. - -Associated setting variable: |g:netrw_localmovecmd| |g:netrw_ssh_cmd| - -MARKED FILES: SOURCING *netrw-ms* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the local marked file list) - -With "ms", netrw will source the marked files (using vim's |:source| command) - - -MARKED FILES: SETTING THE TARGET DIRECTORY *netrw-mt* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - -Set the marked file copy/move-to target (see |netrw-mc| and |netrw-mm|): - - * If the cursor is atop a file name, then the netrw window's currently - displayed directory is used for the copy/move-to target. - - * Also, if the cursor is in the banner, then the netrw window's currently - displayed directory is used for the copy/move-to target. - Unless the target already is the current directory. In which case, - typing "mf" clears the target. - - * However, if the cursor is atop a directory name, then that directory is - used for the copy/move-to target - - * One may use the :MT [directory] command to set the target *netrw-:MT* - This command uses |<q-args>|, so spaces in the directory name are - permitted without escaping. - - * With mouse-enabled vim or with gvim, one may select a target by using - <c-leftmouse> - -There is only one copy/move-to target at a time in a vim session; ie. the -target is a script variable (see |s:var|) and is shared between all netrw -windows (in an instance of vim). - -When using menus and gvim, netrw provides a "Targets" entry which allows one -to pick a target from the list of bookmarks and history. - -Related topics: - Marking Files......................................|netrw-mf| - Marking Files by Regular Expression................|netrw-mr| - Marked Files: Target Directory Using Bookmarks.....|netrw-Tb| - Marked Files: Target Directory Using History.......|netrw-Th| - - -MARKED FILES: TAGGING *netrw-mT* {{{2 - (See |netrw-mf| and |netrw-mr| for how to mark files) - (uses the global marked file list) - -The "mT" mapping will apply the command in |g:netrw_ctags| (by default, it is -"ctags") to marked files. For remote browsing, in order to create a tags file -netrw will use ssh (see |g:netrw_ssh_cmd|), and so ssh must be available for -this to work on remote systems. For your local system, see |ctags| on how to -get a version. I myself use hdrtags, currently available at -http://www.drchip.org/astronaut/src/index.html , and have > - - let g:netrw_ctags= "hdrtag" -< -in my <.vimrc>. - -When a remote set of files are tagged, the resulting tags file is "obtained"; -ie. a copy is transferred to the local system's directory. The now local tags -file is then modified so that one may use it through the network. The -modification made concerns the names of the files in the tags; each filename is -preceded by the netrw-compatible URL used to obtain it. When one subsequently -uses one of the go to tag actions (|tags|), the URL will be used by netrw to -edit the desired file and go to the tag. - -Associated setting variables: |g:netrw_ctags| |g:netrw_ssh_cmd| - -MARKED FILES: TARGET DIRECTORY USING BOOKMARKS *netrw-Tb* {{{2 - -Sets the marked file copy/move-to target. - -The |netrw-qb| map will give you a list of bookmarks (and history). -One may choose one of the bookmarks to become your marked file -target by using [count]Tb (default count: 1). - -Related topics: - Copying files to target............................|netrw-mc| - Listing Bookmarks and History......................|netrw-qb| - Marked Files: Setting The Target Directory.........|netrw-mt| - Marked Files: Target Directory Using History.......|netrw-Th| - Marking Files......................................|netrw-mf| - Marking Files by Regular Expression................|netrw-mr| - Moving files to target.............................|netrw-mm| - - -MARKED FILES: TARGET DIRECTORY USING HISTORY *netrw-Th* {{{2 - -Sets the marked file copy/move-to target. - -The |netrw-qb| map will give you a list of history (and bookmarks). -One may choose one of the history entries to become your marked file -target by using [count]Th (default count: 0; ie. the current directory). - -Related topics: - Copying files to target............................|netrw-mc| - Listing Bookmarks and History......................|netrw-qb| - Marked Files: Setting The Target Directory.........|netrw-mt| - Marked Files: Target Directory Using Bookmarks.....|netrw-Tb| - Marking Files......................................|netrw-mf| - Marking Files by Regular Expression................|netrw-mr| - Moving files to target.............................|netrw-mm| - - -MARKED FILES: UNMARKING *netrw-mu* {{{2 - (See |netrw-mf|, |netrw-mF|) - -The "mu" mapping will unmark all currently marked files. This command differs -from "mF" as the latter only unmarks files in the current directory whereas -"mu" will unmark global and all buffer-local marked files. -(see |netrw-mF|) - - - *netrw-browser-settings* -NETRW BROWSER VARIABLES *netrw-browser-options* *netrw-browser-var* {{{2 - -(if you're interested in the netrw file transfer settings, see |netrw-options| - and |netrw-protocol|) - -The <netrw.vim> browser provides settings in the form of variables which -you may modify; by placing these settings in your <.vimrc>, you may customize -your browsing preferences. (see also: |netrw-settings|) -> - --- ----------- - Var Explanation - --- ----------- -< *g:netrw_altfile* some like |CTRL-^| to return to the last - edited file. Choose that by setting this - parameter to 1. - Others like |CTRL-^| to return to the - netrw browsing buffer. Choose that by setting - this parameter to 0. - default: =0 - - *g:netrw_alto* change from above splitting to below splitting - by setting this variable (see |netrw-o|) - default: =&sb (see |'sb'|) - - *g:netrw_altv* change from left splitting to right splitting - by setting this variable (see |netrw-v|) - default: =&spr (see |'spr'|) - - *g:netrw_banner* enable/suppress the banner - =0: suppress the banner - =1: banner is enabled (default) - - *g:netrw_bannerbackslash* if this variable exists and is not zero, the - banner will be displayed with backslashes - rather than forward slashes. - - *g:netrw_browse_split* when browsing, <cr> will open the file by: - =0: re-using the same window (default) - =1: horizontally splitting the window first - =2: vertically splitting the window first - =3: open file in new tab - =4: act like "P" (ie. open previous window) - Note that |g:netrw_preview| may be used - to get vertical splitting instead of - horizontal splitting. - =[servername,tab-number,window-number] - Given a |List| such as this, a remote server - named by the "servername" will be used for - editing. It will also use the specified tab - and window numbers to perform editing - (see |clientserver|, |netrw-ctrl-r|) - This option does not affect the production of - |:Lexplore| windows. - - Related topics: - |g:netrw_alto| |g:netrw_altv| - |netrw-C| |netrw-cr| - |netrw-ctrl-r| - - *g:netrw_browsex_viewer* specify user's preference for a viewer: > - "kfmclient exec" - "gnome-open" -< - *g:netrw_browsex_support_remote* - specify if the specified viewer supports a - remote URL. (see |netrw-handler|). - - *g:netrw_chgperm* Unix/Linux: "chmod PERM FILENAME" - Windows: "cacls FILENAME /e /p PERM" - Used to change access permission for a file. - - *g:netrw_clipboard* =1 - By default, netrw will attempt to insure that - the clipboard's values will remain unchanged. - However, some users report that they have - speed problems with this; consequently, this - option, when set to zero, lets such users - prevent netrw from saving and restoring the - clipboard (the latter is done only as needed). - That means that if the clipboard is changed - (inadvertently) by normal netrw operation that - it will not be restored to its prior state. - - *g:netrw_compress* ="gzip" - Will compress marked files with this - command - - *g:Netrw_corehandler* Allows one to specify something additional - to do when handling <core> files via netrw's - browser's "x" command (see |netrw-x|). If - present, g:Netrw_corehandler specifies - either one or more function references - (see |Funcref|). (the capital g:Netrw... - is required its holding a function reference) - - - *g:netrw_ctags* ="ctags" - The default external program used to create - tags - - *g:netrw_cursor* = 2 (default) - This option controls the use of the - |'cursorline'| (cul) and |'cursorcolumn'| - (cuc) settings by netrw: - - Value Thin-Long-Tree Wide - =0 u-cul u-cuc u-cul u-cuc - =1 u-cul u-cuc cul u-cuc - =2 cul u-cuc cul u-cuc - =3 cul u-cuc cul cuc - =4 cul cuc cul cuc - =5 U-cul U-cuc U-cul U-cuc - =6 U-cul U-cuc cul U-cuc - =7 cul U-cuc cul U-cuc - =8 cul U-cuc cul cuc - - Where - u-cul : user's |'cursorline'| initial setting used - u-cuc : user's |'cursorcolumn'| initial setting used - U-cul : user's |'cursorline'| current setting used - U-cuc : user's |'cursorcolumn'| current setting used - cul : |'cursorline'| will be locally set - cuc : |'cursorcolumn'| will be locally set - - The "initial setting" means the values of - the |'cuc'| and |'cul'| settings in effect when - netrw last saw |g:netrw_cursor| >= 5 or when - netrw was initially run. - - *g:netrw_decompress* = { ".gz" : "gunzip" , - ".bz2" : "bunzip2" , - ".zip" : "unzip" , - ".tar" : "tar -xf"} - A dictionary mapping suffices to - decompression programs. - - *g:netrw_dirhistmax* =10: controls maximum quantity of past - history. May be zero to suppress - history. - (related: |netrw-qb| |netrw-u| |netrw-U|) - - *g:netrw_dynamic_maxfilenamelen* =32: enables dynamic determination of - |g:netrw_maxfilenamelen|, which affects - local file long listing. - - *g:netrw_errorlvl* =0: error levels greater than or equal to - this are permitted to be displayed - 0: notes - 1: warnings - 2: errors - - *g:netrw_fastbrowse* =0: slow speed directory browsing; - never re-uses directory listings; - always obtains directory listings. - =1: medium speed directory browsing; - re-use directory listings only - when remote directory browsing. - (default value) - =2: fast directory browsing; - only obtains directory listings when the - directory hasn't been seen before - (or |netrw-ctrl-l| is used). - - Fast browsing retains old directory listing - buffers so that they don't need to be - re-acquired. This feature is especially - important for remote browsing. However, if - a file is introduced or deleted into or from - such directories, the old directory buffer - becomes out-of-date. One may always refresh - such a directory listing with |netrw-ctrl-l|. - This option gives the user the choice of - trading off accuracy (ie. up-to-date listing) - versus speed. - - *g:netrw_ffkeep* (default: doesn't exist) - If this variable exists and is zero, then - netrw will not do a save and restore for - |'fileformat'|. - - *g:netrw_fname_escape* =' ?&;%' - Used on filenames before remote reading/writing - - *g:netrw_ftp_browse_reject* ftp can produce a number of errors and warnings - that can show up as "directories" and "files" - in the listing. This pattern is used to - remove such embedded messages. By default its - value is: - '^total\s\+\d\+$\| - ^Trying\s\+\d\+.*$\| - ^KERBEROS_V\d rejected\| - ^Security extensions not\| - No such file\| - : connect to address [0-9a-fA-F:]* - : No route to host$' - - *g:netrw_ftp_list_cmd* options for passing along to ftp for directory - listing. Defaults: - unix or g:netrw_cygwin set: : "ls -lF" - otherwise "dir" - - - *g:netrw_ftp_sizelist_cmd* options for passing along to ftp for directory - listing, sorted by size of file. - Defaults: - unix or g:netrw_cygwin set: : "ls -slF" - otherwise "dir" - - *g:netrw_ftp_timelist_cmd* options for passing along to ftp for directory - listing, sorted by time of last modification. - Defaults: - unix or g:netrw_cygwin set: : "ls -tlF" - otherwise "dir" - - *g:netrw_glob_escape* ='[]*?`{~$' (unix) - ='[]*?`{$' (windows - These characters in directory names are - escaped before applying glob() - - *g:netrw_gx* ="<cfile>" - This option controls how gx (|netrw-gx|) picks - up the text under the cursor. See |expand()| - for possibilities. - - *g:netrw_hide* Controlled by the "a" map (see |netrw-a|) - =0 : show all - =1 : show not-hidden files - =2 : show hidden files only - default: =1 - - *g:netrw_home* The home directory for where bookmarks and - history are saved (as .netrwbook and - .netrwhist). - Netrw uses |expand()| on the string. - default: stdpath("data") (see |stdpath()|) - - *g:netrw_keepdir* =1 (default) keep current directory immune from - the browsing directory. - =0 keep the current directory the same as the - browsing directory. - The current browsing directory is contained in - b:netrw_curdir (also see |netrw-cd|) - - *g:netrw_keepj* ="keepj" (default) netrw attempts to keep the - |:jumps| table unaffected. - ="" netrw will not use |:keepjumps| with - exceptions only for the - saving/restoration of position. - - *g:netrw_list_cmd* command for listing remote directories - default: (if ssh is executable) - "ssh HOSTNAME ls -FLa" - - *g:netrw_list_cmd_options* If this variable exists, then its contents are - appended to the g:netrw_list_cmd. For - example, use "2>/dev/null" to get rid of banner - messages on unix systems. - - - *g:netrw_liststyle* Set the default listing style: - = 0: thin listing (one file per line) - = 1: long listing (one file per line with time - stamp information and file size) - = 2: wide listing (multiple files in columns) - = 3: tree style listing - - *g:netrw_list_hide* comma-separated pattern list for hiding files - Patterns are regular expressions (see |regexp|) - There's some special support for git-ignore - files: you may add the output from the helper - function 'netrw_gitignore#Hide() automatically - hiding all gitignored files. - For more details see |netrw-gitignore|. - default: "" - - Examples: > - let g:netrw_list_hide= '.*\.swp$' - let g:netrw_list_hide= netrw_gitignore#Hide() .. '.*\.swp$' -< - *g:netrw_localcopycmd* ="cp" Linux/Unix/MacOS/Cygwin - =expand("$COMSPEC") Windows - Copies marked files (|netrw-mf|) to target - directory (|netrw-mt|, |netrw-mc|) - - *g:netrw_localcopycmdopt* ='' Linux/Unix/MacOS/Cygwin - =' \c copy' Windows - Options for the |g:netrw_localcopycmd| - - *g:netrw_localcopydircmd* ="cp" Linux/Unix/MacOS/Cygwin - =expand("$COMSPEC") Windows - Copies directories to target directory. - (|netrw-mc|, |netrw-mt|) - - *g:netrw_localcopydircmdopt* =" -R" Linux/Unix/MacOS/Cygwin - =" /c xcopy /e /c /h/ /i /k" Windows - Options for |g:netrw_localcopydircmd| - - *g:netrw_localmkdir* ="mkdir" Linux/Unix/MacOS/Cygwin - =expand("$COMSPEC") Windows - command for making a local directory - - *g:netrw_localmkdiropt* ="" Linux/Unix/MacOS/Cygwin - =" /c mkdir" Windows - Options for |g:netrw_localmkdir| - - *g:netrw_localmovecmd* ="mv" Linux/Unix/MacOS/Cygwin - =expand("$COMSPEC") Windows - Moves marked files (|netrw-mf|) to target - directory (|netrw-mt|, |netrw-mm|) - - *g:netrw_localmovecmdopt* ="" Linux/Unix/MacOS/Cygwin - =" /c move" Windows - Options for |g:netrw_localmovecmd| - - *g:netrw_maxfilenamelen* =32 by default, selected so as to make long - listings fit on 80 column displays. - If your screen is wider, and you have file - or directory names longer than 32 bytes, - you may set this option to keep listings - columnar. - - *g:netrw_mkdir_cmd* command for making a remote directory - via ssh (also see |g:netrw_remote_mkdir|) - default: "ssh USEPORT HOSTNAME mkdir" - - *g:netrw_mousemaps* =1 (default) enables mouse buttons while - browsing to: - leftmouse : open file/directory - shift-leftmouse : mark file - middlemouse : same as P - rightmouse : remove file/directory - =0: disables mouse maps - - *g:netrw_nobeval* doesn't exist (default) - If this variable exists, then balloon - evaluation will be suppressed - (see |'ballooneval'|) - - *g:netrw_sizestyle* not defined: actual bytes (default) - ="b" : actual bytes (default) - ="h" : human-readable (ex. 5k, 4m, 3g) - uses 1000 base - ="H" : human-readable (ex. 5K, 4M, 3G) - uses 1024 base - The long listing (|netrw-i|) and query-file - maps (|netrw-qf|) will display file size - using the specified style. - - *g:netrw_usetab* if this variable exists and is non-zero, then - the <tab> map supporting shrinking/expanding a - Lexplore or netrw window will be enabled. - (see |netrw-c-tab|) - - *g:netrw_remote_mkdir* command for making a remote directory - via ftp (also see |g:netrw_mkdir_cmd|) - default: "mkdir" - - *g:netrw_retmap* if it exists and is set to one, then: - * if in a netrw-selected file, AND - * no normal-mode <2-leftmouse> mapping exists, - then the <2-leftmouse> will be mapped for easy - return to the netrw browser window. - example: click once to select and open a file, - double-click to return. - - Note that one may instead choose to: - * let g:netrw_retmap= 1, AND - * nmap <silent> YourChoice <Plug>NetrwReturn - and have another mapping instead of - <2-leftmouse> to invoke the return. - - You may also use the |:Rexplore| command to do - the same thing. - - default: =0 - - *g:netrw_rm_cmd* command for removing remote files - default: "ssh USEPORT HOSTNAME rm" - - *g:netrw_rmdir_cmd* command for removing remote directories - default: "ssh USEPORT HOSTNAME rmdir" - - *g:netrw_rmf_cmd* command for removing remote softlinks - default: "ssh USEPORT HOSTNAME rm -f" - - *g:netrw_servername* use this variable to provide a name for - |netrw-ctrl-r| to use for its server. - default: "NETRWSERVER" - - *g:netrw_sort_by* sort by "name", "time", "size", or - "exten". - default: "name" - - *g:netrw_sort_direction* sorting direction: "normal" or "reverse" - default: "normal" - - *g:netrw_sort_options* sorting is done using |:sort|; this - variable's value is appended to the - sort command. Thus one may ignore case, - for example, with the following in your - .vimrc: > - let g:netrw_sort_options="i" -< default: "" - - *g:netrw_sort_sequence* when sorting by name, first sort by the - comma-separated pattern sequence. Note that - any filigree added to indicate filetypes - should be accounted for in your pattern. - default: '[\/]$,*,\.bak$,\.o$,\.h$, - \.info$,\.swp$,\.obj$' - - *g:netrw_special_syntax* If true, then certain files will be shown - using special syntax in the browser: - - netrwBak : *.bak - netrwCompress: *.gz *.bz2 *.Z *.zip - netrwCoreDump: core.\d\+ - netrwData : *.dat - netrwDoc : *.doc,*.txt,*.pdf, - *.pdf,*.docx - netrwHdr : *.h - netrwLex : *.l *.lex - netrwLib : *.a *.so *.lib *.dll - netrwMakefile: [mM]akefile *.mak - netrwObj : *.o *.obj - netrwPix : *.bmp,*.fit,*.fits,*.gif, - *.jpg,*.jpeg,*.pcx,*.ppc - *.pgm,*.png,*.psd,*.rgb - *.tif,*.xbm,*.xcf - netrwTags : tags ANmenu ANtags - netrwTilde : * - netrwTmp : tmp* *tmp - netrwYacc : *.y - - In addition, those groups mentioned in - |'suffixes'| are also added to the special - file highlighting group. - These syntax highlighting groups are linked - to netrwGray or Folded by default - (see |hl-Folded|), but one may put lines like > - hi link netrwCompress Visual -< into one's <.vimrc> to use one's own - preferences. Alternatively, one may - put such specifications into > - .vim/after/syntax/netrw.vim. -< The netrwGray highlighting is set up by - netrw when > - * netrwGray has not been previously - defined - * the gui is running -< As an example, I myself use a dark-background - colorscheme with the following in - .vim/after/syntax/netrw.vim: > - - hi netrwCompress term=NONE cterm=NONE gui=NONE ctermfg=10 guifg=green ctermbg=0 guibg=black - hi netrwData term=NONE cterm=NONE gui=NONE ctermfg=9 guifg=blue ctermbg=0 guibg=black - hi netrwHdr term=NONE cterm=NONE,italic gui=NONE guifg=SeaGreen1 - hi netrwLex term=NONE cterm=NONE,italic gui=NONE guifg=SeaGreen1 - hi netrwYacc term=NONE cterm=NONE,italic gui=NONE guifg=SeaGreen1 - hi netrwLib term=NONE cterm=NONE gui=NONE ctermfg=14 guifg=yellow - hi netrwObj term=NONE cterm=NONE gui=NONE ctermfg=12 guifg=red - hi netrwTilde term=NONE cterm=NONE gui=NONE ctermfg=12 guifg=red - hi netrwTmp term=NONE cterm=NONE gui=NONE ctermfg=12 guifg=red - hi netrwTags term=NONE cterm=NONE gui=NONE ctermfg=12 guifg=red - hi netrwDoc term=NONE cterm=NONE gui=NONE ctermfg=220 ctermbg=27 guifg=yellow2 guibg=Blue3 - hi netrwSymLink term=NONE cterm=NONE gui=NONE ctermfg=220 ctermbg=27 guifg=grey60 -< - *g:netrw_ssh_browse_reject* ssh can sometimes produce unwanted lines, - messages, banners, and whatnot that one doesn't - want masquerading as "directories" and "files". - Use this pattern to remove such embedded - messages. By default its value is: - '^total\s\+\d\+$' - - *g:netrw_ssh_cmd* One may specify an executable command - to use instead of ssh for remote actions - such as listing, file removal, etc. - default: ssh - - *g:netrw_suppress_gx_mesg* =1 : browsers sometimes produce messages - which are normally unwanted intermixed - with the page. - However, when using links, for example, - those messages are what the browser produces. - By setting this option to 0, netrw will not - suppress browser messages. - - *g:netrw_tmpfile_escape* =' &;' - escape() is applied to all temporary files - to escape these characters. - - *g:netrw_timefmt* specify format string to vim's strftime(). - The default, "%c", is "the preferred date - and time representation for the current - locale" according to my manpage entry for - strftime(); however, not all are satisfied - with it. Some alternatives: - "%a %d %b %Y %T", - " %a %Y-%m-%d %I-%M-%S %p" - default: "%c" - - *g:netrw_use_noswf* netrw normally avoids writing swapfiles - for browser buffers. However, under some - systems this apparently is causing nasty - ml_get errors to appear; if you're getting - ml_get errors, try putting - let g:netrw_use_noswf= 0 - in your .vimrc. - default: 1 - - *g:netrw_winsize* specify initial size of new windows made with - "o" (see |netrw-o|), "v" (see |netrw-v|), - |:Hexplore| or |:Vexplore|. The g:netrw_winsize - is an integer describing the percentage of the - current netrw buffer's window to be used for - the new window. - If g:netrw_winsize is less than zero, then - the absolute value of g:netrw_winsize will be - used to specify the quantity of lines or - columns for the new window. - If g:netrw_winsize is zero, then a normal - split will be made (ie. |'equalalways'| will - take effect, for example). - default: 50 (for 50%) - - *g:netrw_wiw* =1 specifies the minimum window width to use - when shrinking a netrw/Lexplore window - (see |netrw-c-tab|). - - *g:netrw_xstrlen* Controls how netrw computes string lengths, - including multi-byte characters' string - length. (thanks to N Weibull, T Mechelynck) - =0: uses Vim's built-in strlen() - =1: number of codepoints (Latin a + combining - circumflex is two codepoints) (DEFAULT) - =2: number of spacing codepoints (Latin a + - combining circumflex is one spacing - codepoint; a hard tab is one; wide and - narrow CJK are one each; etc.) - =3: virtual length (counting tabs as anything - between 1 and |'tabstop'|, wide CJK as 2 - rather than 1, Arabic alif as zero when - immediately preceded by lam, one - otherwise, etc) - - *g:NetrwTopLvlMenu* This variable specifies the top level - menu name; by default, it's "Netrw.". If - you wish to change this, do so in your - .vimrc. - -NETRW BROWSING AND OPTION INCOMPATIBILITIES *netrw-incompatible* {{{2 - -Netrw has been designed to handle user options by saving them, setting the -options to something that's compatible with netrw's needs, and then restoring -them. However, the autochdir option: > - :set acd -is problematic. Autochdir sets the current directory to that containing the -file you edit; this apparently also applies to directories. In other words, -autochdir sets the current directory to that containing the "file" (even if -that "file" is itself a directory). - -NETRW SETTINGS WINDOW *netrw-settings-window* {{{2 - -With the NetrwSettings.vim plugin, > - :NetrwSettings -will bring up a window with the many variables that netrw uses for its -settings. You may change any of their values; when you save the file, the -settings therein will be used. One may also press "?" on any of the lines for -help on what each of the variables do. - -(also see: |netrw-browser-var| |netrw-protocol| |netrw-variables|) - - -============================================================================== -OBTAINING A FILE *netrw-obtain* *netrw-O* {{{2 - -If there are no marked files: - - When browsing a remote directory, one may obtain a file under the cursor - (ie. get a copy on your local machine, but not edit it) by pressing the O - key. - -If there are marked files: - - The marked files will be obtained (ie. a copy will be transferred to your - local machine, but not set up for editing). - -Only ftp and scp are supported for this operation (but since these two are -available for browsing, that shouldn't be a problem). The status bar will -then show, on its right hand side, a message like "Obtaining filename". The -statusline will be restored after the transfer is complete. - -Netrw can also "obtain" a file using the local browser. Netrw's display -of a directory is not necessarily the same as Vim's "current directory", -unless |g:netrw_keepdir| is set to 0 in the user's <.vimrc>. One may select -a file using the local browser (by putting the cursor on it) and pressing -"O" will then "obtain" the file; ie. copy it to Vim's current directory. - -Related topics: - * To see what the current directory is, use |:pwd| - * To make the currently browsed directory the current directory, see - |netrw-cd| - * To automatically make the currently browsed directory the current - directory, see |g:netrw_keepdir|. - - *netrw-newfile* *netrw-createfile* -OPEN A NEW FILE IN NETRW'S CURRENT DIRECTORY *netrw-%* {{{2 - -To open a new file in netrw's current directory, press "%". This map -will query the user for a new filename; an empty file by that name will -be placed in the netrw's current directory (ie. b:netrw_curdir). - -If Lexplore (|netrw-:Lexplore|) is in use, the new file will be generated -in the |g:netrw_chgwin| window. - -Related topics: |netrw-d| - - -PREVIEW WINDOW *netrw-p* *netrw-preview* {{{2 - -One may use a preview window by using the "p" key when the cursor is atop the -desired filename to be previewed. The display will then split to show both -the browser (where the cursor will remain) and the file (see |:pedit|). By -default, the split will be taken horizontally; one may use vertical splitting -if one has set |g:netrw_preview| first. - -An interesting set of netrw settings is: > - - let g:netrw_preview = 1 - let g:netrw_liststyle = 3 - let g:netrw_winsize = 30 - -These will: - - 1. Make vertical splitting the default for previewing files - 2. Make the default listing style "tree" - 3. When a vertical preview window is opened, the directory listing - will use only 30% of the columns available; the rest of the window - is used for the preview window. - - Related: if you like this idea, you may also find :Lexplore - (|netrw-:Lexplore|) or |g:netrw_chgwin| of interest - -Also see: |g:netrw_chgwin| |netrw-P| |'previewwindow'| |CTRL-W_z| |:pclose| - - -PREVIOUS WINDOW *netrw-P* *netrw-prvwin* {{{2 - -To edit a file or directory under the cursor in the previously used (last -accessed) window (see :he |CTRL-W_p|), press a "P". If there's only one -window, then the one window will be horizontally split (by default). - -If there's more than one window, the previous window will be re-used on -the selected file/directory. If the previous window's associated buffer -has been modified, and there's only one window with that buffer, then -the user will be asked if they wish to save the buffer first (yes, no, or -cancel). - -Related Actions |netrw-cr| |netrw-o| |netrw-t| |netrw-v| -Associated setting variables: - |g:netrw_alto| control above/below splitting - |g:netrw_altv| control right/left splitting - |g:netrw_preview| control horizontal vs vertical splitting - |g:netrw_winsize| control initial sizing - -Also see: |g:netrw_chgwin| |netrw-p| - - -REFRESHING THE LISTING *netrw-refresh* *netrw-ctrl-l* *netrw-ctrl_l* {{{2 - -To refresh either a local or remote directory listing, press ctrl-l (<c-l>) or -hit the <cr> when atop the ./ directory entry in the listing. One may also -refresh a local directory by using ":e .". - - -REVERSING SORTING ORDER *netrw-r* *netrw-reverse* {{{2 - -One may toggle between normal and reverse sorting order by pressing the -"r" key. - -Related topics: |netrw-s| -Associated setting variable: |g:netrw_sort_direction| - - -RENAMING FILES OR DIRECTORIES *netrw-move* *netrw-rename* *netrw-R* {{{2 - -If there are no marked files: (see |netrw-mf|) - - Renaming files and directories involves moving the cursor to the - file/directory to be moved (renamed) and pressing "R". You will then be - queried for what you want the file/directory to be renamed to. You may - select a range of lines with the "V" command (visual selection), and then - press "R"; you will be queried for each file as to what you want it - renamed to. - -If there are marked files: (see |netrw-mf|) - - Marked files will be renamed (moved). You will be queried as above in - order to specify where you want the file/directory to be moved. - - If you answer a renaming query with a "s/frompattern/topattern/", then - subsequent files on the marked file list will be renamed by taking each - name, applying that substitute, and renaming each file to the result. - As an example : > - - mr [query: reply with *.c] - R [query: reply with s/^\(.*\)\.c$/\1.cpp/] -< - This example will mark all "*.c" files and then rename them to "*.cpp" - files. Netrw will protect you from overwriting local files without - confirmation, but not remote ones. - - The ctrl-X character has special meaning for renaming files: > - - <c-x> : a single ctrl-x tells netrw to ignore the portion of the response - lying between the last '/' and the ctrl-x. - - <c-x><c-x> : a pair of contiguous ctrl-x's tells netrw to ignore any - portion of the string preceding the double ctrl-x's. -< - WARNING: ~ - - Note that moving files is a dangerous operation; copies are safer. That's - because a "move" for remote files is actually a copy + delete -- and if - the copy fails and the delete succeeds you may lose the file. - Use at your own risk. - -The *g:netrw_rename_cmd* variable is used to implement remote renaming. By -default its value is: > - - ssh HOSTNAME mv -< -One may rename a block of files and directories by selecting them with -V (|linewise-visual|) when using thin style. - -See |cmdline-editing| for more on how to edit the command line; in particular, -you'll find <ctrl-f> (initiates cmdline window editing) and <ctrl-c> (uses the -command line under the cursor) useful in conjunction with the R command. - - -SELECTING SORTING STYLE *netrw-s* *netrw-sort* {{{2 - -One may select the sorting style by name, time, or (file) size. The "s" map -allows one to circulate amongst the three choices; the directory listing will -automatically be refreshed to reflect the selected style. - -Related topics: |netrw-r| |netrw-S| -Associated setting variables: |g:netrw_sort_by| |g:netrw_sort_sequence| - - -SETTING EDITING WINDOW *netrw-editwindow* *netrw-C* *netrw-:NetrwC* {{{2 - -One may select a netrw window for editing with the "C" mapping, using the -:NetrwC [win#] command, or by setting |g:netrw_chgwin| to the selected window -number. Subsequent selection of a file to edit (|netrw-cr|) will use that -window. - - * C : by itself, will select the current window holding a netrw buffer - for subsequent editing via |netrw-cr|. The C mapping is only available - while in netrw buffers. - - * [count]C : the count will be used as the window number to be used - for subsequent editing via |netrw-cr|. - - * :NetrwC will set |g:netrw_chgwin| to the current window - - * :NetrwC win# will set |g:netrw_chgwin| to the specified window - number - -Using > - let g:netrw_chgwin= -1 -will restore the default editing behavior -(ie. subsequent editing will use the current window). - -Related topics: |netrw-cr| |g:netrw_browse_split| -Associated setting variables: |g:netrw_chgwin| - - -SHRINKING OR EXPANDING A NETRW OR LEXPLORE WINDOW *netrw-c-tab* {{{2 - -The <c-tab> key will toggle a netrw or |:Lexplore| window's width, -but only if |g:netrw_usetab| exists and is non-zero (and, of course, -only if your terminal supports differentiating <c-tab> from a plain -<tab>). - - * If the current window is a netrw window, toggle its width - (between |g:netrw_wiw| and its original width) - - * Else if there is a |:Lexplore| window in the current tab, toggle - its width - - * Else bring up a |:Lexplore| window - -If |g:netrw_usetab| exists and is zero, or if there is a pre-existing mapping -for <c-tab>, then the <c-tab> will not be mapped. One may map something other -than a <c-tab>, too: (but you'll still need to have had |g:netrw_usetab| set). > - - nmap <unique> (whatever) <Plug>NetrwShrink -< -Related topics: |:Lexplore| -Associated setting variable: |g:netrw_usetab| - - -USER SPECIFIED MAPS *netrw-usermaps* {{{1 - -One may make customized user maps. Specify a variable, |g:Netrw_UserMaps|, -to hold a |List| of lists of keymap strings and function names: > - - [["keymap-sequence","ExampleUserMapFunc"],...] -< -When netrw is setting up maps for a netrw buffer, if |g:Netrw_UserMaps| -exists, then the internal function netrw#UserMaps(islocal) is called. -This function goes through all the entries in the |g:Netrw_UserMaps| list: - - * sets up maps: > - nno <buffer> <silent> KEYMAP-SEQUENCE - :call s:UserMaps(islocal,"ExampleUserMapFunc") -< * refreshes if result from that function call is the string - "refresh" - * if the result string is not "", then that string will be - executed (:exe result) - * if the result is a List, then the above two actions on results - will be taken for every string in the result List - -The user function is passed one argument; it resembles > - - fun! ExampleUserMapFunc(islocal) -< -where a:islocal is 1 if its a local-directory system call or 0 when -remote-directory system call. - - *netrw-call* *netrw-expose* *netrw-modify* -Use netrw#Expose("varname") to access netrw-internal (script-local) - variables. -Use netrw#Modify("varname",newvalue) to change netrw-internal variables. -Use netrw#Call("funcname"[,args]) to call a netrw-internal function with - specified arguments. - -Example: Get a copy of netrw's marked file list: > - - let netrwmarkfilelist= netrw#Expose("netrwmarkfilelist") -< -Example: Modify the value of netrw's marked file list: > - - call netrw#Modify("netrwmarkfilelist",[]) -< -Example: Clear netrw's marked file list via a mapping on gu > - " ExampleUserMap: {{{2 - fun! ExampleUserMap(islocal) - call netrw#Modify("netrwmarkfilelist",[]) - call netrw#Modify('netrwmarkfilemtch_{bufnr("%")}',"") - let retval= ["refresh"] - return retval - endfun - let g:Netrw_UserMaps= [["gu","ExampleUserMap"]] -< - -10. Problems and Fixes *netrw-problems* {{{1 - - (This section is likely to grow as I get feedback) - (also see |netrw-debug|) - *netrw-p1* - 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? - - Windows' ftp has a minimal support for ls (ie. it doesn't - accept sorting options). It doesn't support the -F which - gives an explanatory character (ABC/ for "ABC is a directory"). - Netrw then uses "dir" to get both its thin and long listings. - If you think your ftp does support a full-up ls, put the - following into your <.vimrc>: > - - let g:netrw_ftp_list_cmd = "ls -lF" - let g:netrw_ftp_timelist_cmd= "ls -tlF" - let g:netrw_ftp_sizelist_cmd= "ls -slF" -< - Alternatively, if you have cygwin on your Windows box, put - into your <.vimrc>: > - - let g:netrw_cygwin= 1 -< - This problem also occurs when the remote system is Windows. - In this situation, the various g:netrw_ftp_[time|size]list_cmds - are as shown above, but the remote system will not correctly - modify its listing behavior. - - - *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 - and ftp. Unless you specify ftp specifically, ssh is used. - When it comes time to do download a file (not just a directory - listing), netrw will use the given protocol to do so. - - *netrw-p3* - P3. I would like long listings to be the default. {{{2 - - Put the following statement into your |vimrc|: > - - let g:netrw_liststyle= 1 -< - Check out |netrw-browser-var| for more customizations that - you can set. - - *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 - "man strftime" and find out what option should be used. Then - put it into your |vimrc|: > - - let g:netrw_timefmt= "%X" (where X is the option) -< - *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-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 - mailing list) - I now see the problem. Your code page is not 936, right? Vim - seems only able to open files with names that are valid in the - current code page, as are many other applications that do not - use the Unicode version of Windows APIs. This is an OS-related - issue. You should not have such problems when the system - locale uses UTF-8, such as modern Linux distros. - - (...it is one more reason to recommend that people use utf-8!) - - *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 - is a free ssh/telnet application. You can read more about it - here: - - http://www.chiark.greenend.org.uk/~sgtatham/putty/ Also: - - (Marlin Unruh) This program also works for me. It's a single - executable, so he/she can copy it into the Windows\System32 - folder and create a shortcut to it. - - (Dudley Fox) You might also wish to consider plink, as it - sounds most similar to what you are looking for. plink is an - application in the putty suite. - - http://the.earth.li/~sgtatham/putty/0.58/htmldoc/Chapter7.html#plink - - (Vissale Neang) Maybe you can try OpenSSH for windows, which - can be obtained from: - - http://sshwindows.sourceforge.net/ - - It doesn't need the full Cygwin package. - - (Antoine Mechelynck) For individual Unix-like programs needed - for work in a native-Windows environment, I recommend getting - them from the GnuWin32 project on sourceforge if it has them: - - http://gnuwin32.sourceforge.net/ - - Unlike Cygwin, which sets up a Unix-like virtual machine on - top of Windows, GnuWin32 is a rewrite of Unix utilities with - Windows system calls, and its programs works quite well in the - cmd.exe "Dos box". - - (dave) Download WinSCP and use that to connect to the server. - In Preferences > Editors, set gvim as your editor: - - - Click "Add..." - - Set External Editor (adjust path as needed, include - the quotes and !.! at the end): - "c:\Program Files\Vim\vim82\gvim.exe" !.! - - Check that the filetype in the box below is - {asterisk}.{asterisk} (all files), or whatever types - you want (cec: change {asterisk} to * ; I had to - write it that way because otherwise the helptags - system thinks it's a tag) - - Make sure it's at the top of the listbox (click it, - then click "Up" if it's not) - If using the Norton Commander style, you just have to hit <F4> - to edit a file in a local copy of gvim. - - (Vit Gottwald) How to generate public/private key and save - public key it on server: > - http://www.chiark.greenend.org.uk/~sgtatham/putty/0.60/htmldoc/Chapter8.html#pubkey-gettingready - (8.3 Getting ready for public key authentication) -< - How to use a private key with "pscp": > - - http://www.chiark.greenend.org.uk/~sgtatham/putty/0.60/htmldoc/Chapter5.html - (5.2.4 Using public key authentication with PSCP) -< - (Ben Schmidt) I find the ssh included with cwRsync is - brilliant, and install cwRsync or cwRsyncServer on most - Windows systems I come across these days. I guess COPSSH, - packed by the same person, is probably even better for use as - just ssh on Windows, and probably includes sftp, etc. which I - suspect the cwRsync doesn't, though it might - - (cec) To make proper use of these suggestions above, you will - need to modify the following user-settable variables in your - .vimrc: - - |g:netrw_ssh_cmd| |g:netrw_list_cmd| |g:netrw_mkdir_cmd| - |g:netrw_rm_cmd| |g:netrw_rmdir_cmd| |g:netrw_rmf_cmd| - - The first one (|g:netrw_ssh_cmd|) is the most important; most - of the others will use the string in g:netrw_ssh_cmd by - default. - - *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 - its temporary directory buffers. However, on some systems - this attempt appears to be causing ml_get errors to - appear. Please try setting |g:netrw_use_noswf| to 0 - in your <.vimrc>: > - let g:netrw_use_noswf= 0 -< - *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, - not by netrw, and there appears to be no way to work around - it. Coupled with the default cmdheight of 1, this message - causes the "Press ENTER..." prompt. So: read |hit-enter|; - I also suggest that you set your |'cmdheight'| to 2 (or more) in - your <.vimrc> file. - - *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 - will likely find that ":[N]Lexplore" does what you want. The - optional "[N]" allows you to select the quantity of columns you - wish the |:Lexplore|r window to start with (see |g:netrw_winsize| - for how this parameter works). - - Previous solution: - - * Put the following line in your <.vimrc>: - let g:netrw_altv = 1 - * Edit the current directory: :e . - * Select some file, press v - * Resize the windows as you wish (see |CTRL-W_<| and - |CTRL-W_>|). If you're using gvim, you can drag - the separating bar with your mouse. - * When you want a new file, use ctrl-w h to go back to the - netrw browser, select a file, then press P (see |CTRL-W_h| - and |netrw-P|). If you're using gvim, you can press - <leftmouse> in the browser window and then press the - <middlemouse> to select the file. - - - *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, ... - - This may be due to an encoding problem. I myself usually use - utf-8, but really only use ascii (ie. bytes from 32-126). - Multibyte encodings use two (or more) bytes per character. - You may need to change |g:netrw_sepchr| and/or |g:netrw_xstrlen|. - - *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? - - (mikeyao) If you want to use vim via ssh and putty under Windows, - try combining the use of pscp/psftp with plink. pscp/psftp will - be used to connect and plink will be used to execute commands on - the server, for example: list files and directory using 'ls'. - - These are the settings I use to do this: -> - " list files, it's the key setting, if you haven't set, - " you will get a blank buffer - let g:netrw_list_cmd = "plink HOSTNAME ls -Fa" - " if you haven't add putty directory in system path, you should - " specify scp/sftp command. For examples: - "let g:netrw_sftp_cmd = "d:\\dev\\putty\\PSFTP.exe" - "let g:netrw_scp_cmd = "d:\\dev\\putty\\PSCP.exe" -< - *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 - man page) to share multiple ssh connections over a single network - connection. That cuts out the cryptographic handshake on each - file write, sometimes speeding it up by an order of magnitude. - (see http://thomer.com/howtos/netrw_ssh.html) - (included by permission) - - Add the following to your ~/.ssh/config: > - - # you change "*" to the hostname you care about - Host * - ControlMaster auto - ControlPath /tmp/%r@%h:%p - -< Then create an ssh connection to the host and leave it running: > - - ssh -N host.domain.com - -< Now remotely open a file with Vim's Netrw and enjoy the - zippiness: > - - vim scp://host.domain.com//home/user/.bashrc -< - *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 > - let g:netrw_mousemaps= 0 -< and then create a netrw buffer only mapping in - $HOME/.vim/after/ftplugin/netrw.vim: > - nmap <buffer> <2-leftmouse> <CR> -< Note that setting g:netrw_mousemaps to zero will turn off - all netrw's mouse mappings, not just the <leftmouse> one. - (see |g:netrw_mousemaps|) - - *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. - - (romainl) It looks like you are starting Vim from a protected - directory. Start netrw from your $HOME or other writable - directory. - - *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 - 3. Buffer opened in step 1 will be closed. o - What is the expected output? What do you see instead? - I expect both buffers to exist, but only the last one does. - - (Lance) Problem is caused by "set autochdir" in .vimrc. - (drchip) I am able to duplicate this problem with |'acd'| set. - It appears that the buffers are not exactly closed; - a ":ls!" will show them (although ":ls" does not). - - *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-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" -< in your .vimrc. If you'd like to have relative numbering - instead, try > - let g:netrw_bufsettings="noma nomod nonu nobl nowrap ro rnu" -< - *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! - au VimEnter * if expand("%") == "" && argc() == 0 && - \ (v:servername =~ 'GVIM\d*' || v:servername == "") - \ | e . | endif - augroup END -< You may use Lexplore instead of "e" if you're so inclined. - This snippet assumes that you have client-server enabled - (ie. a "huge" vim version). - - *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 - than you have vim (netrw) using. A patch to vim supporting - "systemencoding" may address this issue in the future; for - now, just have netrw use the proper encoding. For example: > - - au FileType netrw set enc=latin1 -< - *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! -< - What's wrong? - - Netrw uses several system level commands to do things (see - - |g:netrw_localcopycmd|, |g:netrw_localmovecmd|, - |g:netrw_mkdir_cmd|). - - You may need to adjust the default commands for one or more of - these commands by setting them properly in your .vimrc. Another - source of difficulty is that these commands use vim's local - directory, which may not be the same as the browsing directory - shown by netrw (see |g:netrw_keepdir|). - - -============================================================================== -11. Debugging Netrw Itself *netrw-debug* {{{1 - -Step 1: check that the problem you've encountered hasn't already been resolved -by obtaining a copy of the latest (often developmental) netrw at: - - http://www.drchip.org/astronaut/vim/index.html#NETRW - -The <netrw.vim> script is typically installed on systems as something like: -> - /usr/local/share/vim/vim8x/plugin/netrwPlugin.vim - /usr/local/share/vim/vim8x/autoload/netrw.vim - (see output of :echo &rtp) -< -which is loaded automatically at startup (assuming :set nocp). If you -installed a new netrw, then it will be located at > - - $HOME/.vim/plugin/netrwPlugin.vim - $HOME/.vim/autoload/netrw.vim -< -Step 2: assuming that you've installed the latest version of netrw, -check that your problem is really due to netrw. Create a file -called netrw.vimrc with the following contents: > - - set nocp - so $HOME/.vim/plugin/netrwPlugin.vim -< -Then run netrw as follows: > - - vim -u netrw.vimrc --noplugins -i NONE [some path here] -< -Perform whatever netrw commands you need to, and check that the problem is -still present. This procedure sidesteps any issues due to personal .vimrc -settings, .viminfo file, and other plugins. If the problem does not appear, -then you need to determine which setting in your .vimrc is causing the -conflict with netrw or which plugin(s) is/are involved. - -Step 3: If the problem still is present, then get a debugging trace from -netrw: - - 1. Get the <Decho.vim> script, available as: - - http://www.drchip.org/astronaut/vim/index.html#DECHO - or - http://vim.sourceforge.net/scripts/script.php?script_id=120 - - Decho.vim is provided as a "vimball". You - should edit the Decho.vba.gz file and source it in: > - - vim Decho.vba.gz - :so % - :q -< - 2. To turn on debug tracing in netrw, then edit the <netrw.vim> - file by typing: > - - vim netrw.vim - :DechoOn - :wq -< - To restore to normal non-debugging behavior, re-edit <netrw.vim> - and type > - - vim netrw.vim - :DechoOff - :wq -< - This command, provided by <Decho.vim>, will comment out all - Decho-debugging statements (Dfunc(), Dret(), Decho(), Dredir()). - - 3. Then bring up vim and attempt to evoke the problem by doing a - transfer or doing some browsing. A set of messages should appear - concerning the steps that <netrw.vim> took in attempting to - read/write your file over the network in a separate tab or - server vim window. - - Change the netrw.vimrc file to include the Decho plugin: > - - set nocp - so $HOME/.vim/plugin/Decho.vim - so $HOME/.vim/plugin/netrwPlugin.vim -< - You should continue to run vim with > - - vim -u netrw.vimrc --noplugins -i NONE [some path here] -< - to avoid entanglements with options and other plugins. - - To save the file: under linux, the output will be in a separate - remote server window; in it, just save the file with > - - :w! DBG - -< Under a vim that doesn't support clientserver, your debugging - output will appear in another tab: > - - :tabnext - :set bt= - :w! DBG -< - Furthermore, it'd be helpful if you would type > - - :Dsep <command> - -< where <command> is the command you're about to type next, - thereby making it easier to associate which part of the - debugging trace is due to which command. - - Please send that information to <netrw.vim>'s maintainer along - with the o/s you're using and the vim version that you're using - (see |:version|) (remove the embedded NOSPAM first) > - - NcampObell@SdrPchip.AorgM-NOSPAM -< -============================================================================== -12. History *netrw-history* {{{1 - - v172: Sep 02, 2021 * (Bram Moolenaar) Changed "l:go" to "go" - * (Bram Moolenaar) no need for "b" in - netrw-safe guioptions - Nov 15, 2021 * removed netrw_localrm and netrw_localrmdir - references - Aug 18, 2022 * (Miguel Barro) improving compatibility with - powershell - v171: Oct 09, 2020 * included code in s:NetrwOptionsSafe() - to allow |'bh'| to be set to delete when - rather than hide when g:netrw_fastbrowse - was zero. - * Installed |g:netrw_clipboard| setting - * Installed option bypass for |'guioptions'| - a/A settings - * Changed popup_beval() to popup_atcursor() - in netrw#ErrorMsg (lacygoill). Apparently - popup_beval doesn't reliably close the - popup when the mouse is moved. - * VimEnter() now using win_execute to examine - buffers for an attempt to open a directory. - Avoids issues with popups/terminal from - command line. (lacygoill) - Jun 28, 2021 * (zeertzjq) provided a patch for use of - xmap,xno instead of vmap,vno in - netrwPlugin.vim. Avoids entanglement with - select mode. - Jul 14, 2021 * Fixed problem addressed by tst976; opening - a file using tree mode, going up a - directory, and opening a file there was - opening the file in the wrong directory. - Jul 28, 2021 * (Ingo Karkat) provided a patch fixing an - E488 error with netrwPlugin.vim - (occurred for vim versions < 8.02) - v170: Mar 11, 2020 * (reported by Reiner Herrmann) netrw+tree - would not hide with the ^\..* pattern - correctly. - * (Marcin Szamotulski) NetrwOptionRestore - did not restore options correctly that - had a single quote in the option string. - Apr 13, 2020 * implemented error handling via popup - windows (see popup_beval()) - Apr 30, 2020 * (reported by Manatsu Takahashi) while - using Lexplore, a modified file could - be overwritten. Sol'n: will not overwrite, - but will emit an |E37| (although one cannot - add an ! to override) - Jun 07, 2020 * (reported by Jo Totland) repeatedly invoking - :Lexplore and quitting it left unused - hidden buffers. Netrw will now set netrw - buffers created by :Lexplore to |'bh'|=wipe. - v169: Dec 20, 2019 * (reported by amkarthik) that netrw's x - (|netrw-x|) would throw an error when - attempting to open a local directory. - v168: Dec 12, 2019 * scp timeout error message not reported, - hopefully now fixed (Shane Xb Qian) - v167: Nov 29, 2019 * netrw does a save&restore on @* and @+. - That causes problems with the clipboard. - Now restores occurs only if @* or @+ have - been changed. - * netrw will change @* or @+ less often. - Never if I happen to have caught all the - operations that modify the unnamed - register (which also writes @*). - * Modified hiding behavior so that "s" - will not ignore hiding. - v166: Nov 06, 2019 * Removed a space from a nmap for "-" - * Numerous debugging statement changes - v163: Dec 05, 2017 * (Cristi Balan) reported that a setting ('sel') - was left changed - * (Holger Mitschke) reported a problem with - saving and restoring history. Fixed. - * Hopefully I fixed a nasty bug that caused a - file rename to wipe out a buffer that it - should not have wiped out. - * (Holger Mitschke) amended this help file - with additional |g:netrw_special_syntax| - items - * Prioritized wget over curl for - g:netrw_http_cmd - v162: Sep 19, 2016 * (haya14busa) pointed out two syntax errors - with a patch; these are now fixed. - Oct 26, 2016 * I started using mate-terminal and found that - x and gx (|netrw-x| and |netrw-gx|) were no - longer working. Fixed (using atril when - $DESKTOP_SESSION is "mate"). - Nov 04, 2016 * (Martin Vuille) pointed out that @+ was - being restored with keepregstar rather than - keepregplus. - Nov 09, 2016 * Broke apart the command from the options, - mostly for Windows. Introduced new netrw - settings: |g:netrw_localcopycmdopt| - |g:netrw_localcopydircmdopt| - |g:netrw_localmkdiropt| - |g:netrw_localmovecmdopt| - Nov 21, 2016 * (mattn) provided a patch for preview; swapped - winwidth() with winheight() - Nov 22, 2016 * (glacambre) reported that files containing - spaces weren't being obtained properly via - scp. Fix: apparently using single quotes - such as with "file name" wasn't enough; the - spaces inside the quotes also had to be - escaped (ie. "file\ name"). - * Also fixed obtain (|netrw-O|) to be able to - obtain files with spaces in their names - Dec 20, 2016 * (xc1427) Reported that using "I" (|netrw-I|) - when atop "Hiding" in the banner also caused - the active-banner hiding control to occur - Jan 03, 2017 * (Enno Nagel) reported that attempting to - apply netrw to a directory that was without - read permission caused a syntax error. - Jan 13, 2017 * (Ingo Karkat) provided a patch which makes - using netrw#Call() better. Now returns - value of internal routines return, for example. - Jan 13, 2017 * (Ingo Karkat) changed netrw#FileUrlRead to - use |:edit| instead of |:read|. I also - changed the routine name to netrw#FileUrlEdit. - Jan 16, 2017 * (Sayem) reported a problem where :Lexplore - could generate a new listing buffer and - window instead of toggling the netrw display. - Unfortunately, the directions for eliciting - the problem weren't complete, so I may or - may not have fixed that issue. - Feb 06, 2017 * Implemented cb and cB. Changed "c" to "cd". - (see |netrw-cb|, |netrw-cB|, and |netrw-cd|) - Mar 21, 2017 * previously, netrw would specify (safe) settings - even when the setting was already safe for - netrw. Netrw now attempts to leave such - already-netrw-safe settings alone. - (affects s:NetrwOptionRestore() and - s:NetrwSafeOptions(); also introduced - s:NetrwRestoreSetting()) - Jun 26, 2017 * (Christian Brabandt) provided a patch to - allow curl to follow redirects (ie. -L - option) - Jun 26, 2017 * (Callum Howard) reported a problem with - :Lexpore not removing the Lexplore window - after a change-directory - Aug 30, 2017 * (Ingo Karkat) one cannot switch to the - previously edited file (e.g. with CTRL-^) - after editing a file:// URL. Patch to - have a "keepalt" included. - Oct 17, 2017 * (Adam Faryna) reported that gn (|netrw-gn|) - did not work on directories in the current - tree - v157: Apr 20, 2016 * (Nicola) had set up a "nmap <expr> ..." with - a function that returned a 0 while silently - invoking a shell command. The shell command - activated a ShellCmdPost event which in turn - called s:LocalBrowseRefresh(). That looks - over all netrw buffers for changes needing - refreshes. However, inside a |:map-<expr>|, - tab and window changes are disallowed. Fixed. - (affects netrw's s:LocalBrowseRefresh()) - * g:netrw_localrmdir not used any more, but - the relevant patch that causes |delete()| to - take over was #1107 (not #1109). - * |expand()| is now used on |g:netrw_home|; - consequently, g:netrw_home may now use - environment variables - * s:NetrwLeftmouse and s:NetrwCLeftmouse will - return without doing anything if invoked - when inside a non-netrw window - Jun 15, 2016 * gx now calls netrw#GX() which returns - the word under the cursor. The new - wrinkle: if one is in a netrw buffer, - then netrw's s:NetrwGetWord(). - Jun 22, 2016 * Netrw was executing all its associated - Filetype commands silently; I'm going - to try doing that "noisily" and see if - folks have a problem with that. - Aug 12, 2016 * Changed order of tool selection for - handling http://... viewing. - (Nikolay Aleksandrovich Pavlov) - Aug 21, 2016 * Included hiding/showing/all for tree - listings - * Fixed refresh (^L) for tree listings - v156: Feb 18, 2016 * Changed =~ to =~# where appropriate - Feb 23, 2016 * s:ComposePath(base,subdir) now uses - fnameescape() on the base portion - Mar 01, 2016 * (gt_macki) reported where :Explore would - make file unlisted. Fixed (tst943) - Apr 04, 2016 * (reported by John Little) netrw normally - suppresses browser messages, but sometimes - those "messages" are what is wanted. - See |g:netrw_suppress_gx_mesg| - Apr 06, 2016 * (reported by Carlos Pita) deleting a remote - file was giving an error message. Fixed. - Apr 08, 2016 * (Charles Cooper) had a problem with an - undefined b:netrw_curdir. He also provided - a fix. - Apr 20, 2016 * Changed s:NetrwGetBuffer(); now uses - dictionaries. Also fixed the "No Name" - buffer problem. - v155: Oct 29, 2015 * (Timur Fayzrakhmanov) reported that netrw's - mapping of ctrl-l was not allowing refresh of - other windows when it was done in a netrw - window. - Nov 05, 2015 * Improved s:TreeSqueezeDir() to use search() - instead of a loop - * NetrwBrowse() will return line to - w:netrw_bannercnt if cursor ended up in - banner - Nov 16, 2015 * Added a <Plug>NetrwTreeSqueeze (|netrw-s-cr|) - Nov 17, 2015 * Commented out imaps -- perhaps someone can - tell me how they're useful and should be - retained? - Nov 20, 2015 * Added |netrw-ma| and |netrw-mA| support - Nov 20, 2015 * gx (|netrw-gx|) on a URL downloaded the - file in addition to simply bringing up the - URL in a browser. Fixed. - Nov 23, 2015 * Added |g:netrw_sizestyle| support - Nov 27, 2015 * Inserted a lot of <c-u>s into various netrw - maps. - Jan 05, 2016 * |netrw-qL| implemented to mark files based - upon |location-list|s; similar to |netrw-qF|. - Jan 19, 2016 * using - call delete(directoryname,"d") - - instead of using g:netrw_localrmdir if - v7.4 + patch#1107 is available - Jan 28, 2016 * changed to using |winsaveview()| and - |winrestview()| - Jan 28, 2016 * s:NetrwTreePath() now does a save and - restore of view - Feb 08, 2016 * Fixed a tree-listing problem with remote - directories - v154: Feb 26, 2015 * (Yuri Kanivetsky) reported a situation where - a file was not treated properly as a file - due to g:netrw_keepdir == 1 - Mar 25, 2015 * (requested by Ben Friz) one may now sort by - extension - Mar 28, 2015 * (requested by Matt Brooks) netrw has a lot - of buffer-local mappings; however, some - plugins (such as vim-surround) set up - conflicting mappings that cause vim to wait. - The "<nowait>" modifier has been included - with most of netrw's mappings to avoid that - delay. - Jun 26, 2015 * |netrw-gn| mapping implemented - * :Ntree NotADir resulted in having - the tree listing expand in the error messages - window. Fixed. - Jun 29, 2015 * Attempting to delete a file remotely caused - an error with "keepsol" mentioned; fixed. - Jul 08, 2015 * Several changes to keep the |:jumps| table - correct when working with - |g:netrw_fastbrowse| set to 2 - * wide listing with accented characters fixed - (using %-S instead of %-s with a |printf()| - Jul 13, 2015 * (Daniel Hahler) CheckIfKde() could be true - but kfmclient not installed. Changed order - in netrw#BrowseX(): checks if kde and - kfmclient, then will use xdg-open on a unix - system (if xdg-open is executable) - Aug 11, 2015 * (McDonnell) tree listing mode wouldn't - select a file in a open subdirectory. - * (McDonnell) when multiple subdirectories - were concurrently open in tree listing - mode, a ctrl-L wouldn't refresh properly. - * The netrw:target menu showed duplicate - entries - Oct 13, 2015 * (mattn) provided an exception to handle - windows with shellslash set but no shell - Oct 23, 2015 * if g:netrw_usetab and <c-tab> now used - to control whether NetrwShrink is used - (see |netrw-c-tab|) - v153: May 13, 2014 * added another |g:netrw_ffkeep| usage {{{2 - May 14, 2014 * changed s:PerformListing() so that it - always sets ft=netrw for netrw buffers - (ie. even when syntax highlighting is - off, not available, etc) - May 16, 2014 * introduced the |netrw-ctrl-r| functionality - May 17, 2014 * introduced the |netrw-:NetrwMB| functionality - * mb and mB (|netrw-mb|, |netrw-mB|) will - add/remove marked files from bookmark list - May 20, 2014 * (Enno Nagel) reported that :Lex <dirname> - wasn't working. Fixed. - May 26, 2014 * restored test to prevent leftmouse window - resizing from causing refresh. - (see s:NetrwLeftmouse()) - * fixed problem where a refresh caused cursor - to go just under the banner instead of - staying put - May 28, 2014 * (László Bimba) provided a patch for opening - the |:Lexplore| window 100% high, optionally - on the right, and will work with remote - files. - May 29, 2014 * implemented :NetrwC (see |netrw-:NetrwC|) - Jun 01, 2014 * Removed some "silent"s from commands used - to implemented scp://... and pscp://... - directory listing. Permits request for - password to appear. - Jun 05, 2014 * (Enno Nagel) reported that user maps "/" - caused problems with "b" and "w", which - are mapped (for wide listings only) to - skip over files rather than just words. - Jun 10, 2014 * |g:netrw_gx| introduced to allow users to - override default "<cfile>" with the gx - (|netrw-gx|) map - Jun 11, 2014 * gx (|netrw-gx|), with |'autowrite'| set, - will write modified files. s:NetrwBrowseX() - will now save, turn off, and restore the - |'autowrite'| setting. - Jun 13, 2014 * added visual map for gx use - Jun 15, 2014 * (Enno Nagel) reported that with having hls - set and wide listing style in use, that the - b and w maps caused unwanted highlighting. - Jul 05, 2014 * |netrw-mv| and |netrw-mX| commands included - Jul 09, 2014 * |g:netrw_keepj| included, allowing optional - keepj - Jul 09, 2014 * fixing bugs due to previous update - Jul 21, 2014 * (Bruno Sutic) provided an updated - netrw_gitignore.vim - Jul 30, 2014 * (Yavuz Yetim) reported that editing two - remote files of the same name caused the - second instance to have a "temporary" - name. Fixed: now they use the same buffer. - Sep 18, 2014 * (Yasuhiro Matsumoto) provided a patch which - allows scp and windows local paths to work. - Oct 07, 2014 * gx (see |netrw-gx|) when atop a directory, - will now do |gf| instead - Nov 06, 2014 * For cygwin: cygstart will be available for - netrw#BrowseX() to use if its executable. - Nov 07, 2014 * Began support for file://... urls. Will use - |g:netrw_file_cmd| (typically elinks or links) - Dec 02, 2014 * began work on having mc (|netrw-mc|) copy - directories. Works for linux machines, - cygwin+vim, but not for windows+gvim. - Dec 02, 2014 * in tree mode, netrw was not opening - directories via symbolic links. - Dec 02, 2014 * added resolved link information to - thin and tree modes - Dec 30, 2014 * (issue#231) |:ls| was not showing - remote-file buffers reliably. Fixed. - v152: Apr 08, 2014 * uses the |'noswapfile'| option (requires {{{2 - vim 7.4 with patch 213) - * (Enno Nagel) turn |'rnu'| off in netrw - buffers. - * (Quinn Strahl) suggested that netrw - allow regular window splitting to occur, - thereby allowing |'equalalways'| to take - effect. - * (qingtian zhao) normally, netrw will - save and restore the |'fileformat'|; - however, sometimes that isn't wanted - Apr 14, 2014 * whenever netrw marks a buffer as ro, - it will also mark it as nomod. - Apr 16, 2014 * sftp protocol now supported by - netrw#Obtain(); this means that one - may use "mc" to copy a remote file - to a local file using sftp, and that - the |netrw-O| command can obtain remote - files via sftp. - * added [count]C support (see |netrw-C|) - Apr 18, 2014 * when |g:netrw_chgwin| is one more than - the last window, then vertically split - the last window and use it as the - chgwin window. - May 09, 2014 * SavePosn was "saving filename under cursor" - from a non-netrw window when using :Rex. - v151: Jan 22, 2014 * extended :Rexplore to return to buffer {{{2 - prior to Explore or editing a directory - * (Ken Takata) netrw gave error when - clipboard was disabled. Sol'n: Placed - several if has("clipboard") tests in. - * Fixed ftp://X@Y@Z// problem; X@Y now - part of user id, and only Z is part of - hostname. - * (A Loumiotis) reported that completion - using a directory name containing spaces - did not work. Fixed with a retry in - netrw#Explore() which removes the - backslashes vim inserted. - Feb 26, 2014 * :Rexplore now records the current file - using w:netrw_rexfile when returning via - |:Rexplore| - Mar 08, 2014 * (David Kotchan) provided some patches - allowing netrw to work properly with - windows shares. - * Multiple one-liner help messages available - by pressing <cr> while atop the "Quick - Help" line - * worked on ShellCmdPost, FocusGained event - handling. - * |:Lexplore| path: will be used to update - a left-side netrw browsing directory. - Mar 12, 2014 * |netrw-s-cr|: use <s-cr> to close - tree directory implemented - Mar 13, 2014 * (Tony Mechylynck) reported that using - the browser with ftp on a directory, - and selecting a gzipped txt file, that - an E19 occurred (which was issued by - gzip.vim). Fixed. - Mar 14, 2014 * Implemented :MF and :MT (see |netrw-:MF| - and |netrw-:MT|, respectively) - Mar 17, 2014 * |:Ntree| [dir] wasn't working properly; fixed - Mar 18, 2014 * Changed all uses of set to setl - Mar 18, 2014 * Commented the netrw_btkeep line in - s:NetrwOptionSave(); the effect is that - netrw buffers will remain as |'bt'|=nofile. - This should prevent swapfiles being created - for netrw buffers. - Mar 20, 2014 * Changed all uses of lcd to use s:NetrwLcd() - instead. Consistent error handling results - and it also handles Window's shares - * Fixed |netrw-d| command when applied with ftp - * https: support included for netrw#NetRead() - v150: Jul 12, 2013 * removed a "keepalt" to allow ":e #" to {{{2 - return to the netrw directory listing - Jul 13, 2013 * (Jonas Diemer) suggested changing - a <cWORD> to <cfile>. - Jul 21, 2013 * (Yuri Kanivetsky) reported that netrw's - use of mkdir did not produce directories - following the user's umask. - Aug 27, 2013 * introduced |g:netrw_altfile| option - Sep 05, 2013 * s:Strlen() now uses |strdisplaywidth()| - when available, by default - Sep 12, 2013 * (Selyano Baldo) reported that netrw wasn't - opening some directories properly from the - command line. - Nov 09, 2013 * |:Lexplore| introduced - * (Ondrej Platek) reported an issue with - netrw's trees (P15). Fixed. - * (Jorge Solis) reported that "t" in - tree mode caused netrw to forget its - line position. - Dec 05, 2013 * Added <s-leftmouse> file marking - (see |netrw-mf|) - Dec 05, 2013 * (Yasuhiro Matsumoto) Explore should use - strlen() instead s:Strlen() when handling - multibyte chars with strpart() - (ie. strpart() is byte oriented, not - display-width oriented). - Dec 09, 2013 * (Ken Takata) Provided a patch; File sizes - and a portion of timestamps were wrongly - highlighted with the directory color when - setting `:let g:netrw_liststyle=1` on Windows. - * (Paul Domaskis) noted that sometimes - cursorline was activating in non-netrw - windows. All but one setting of cursorline - was done via setl; there was one that was - overlooked. Fixed. - Dec 24, 2013 * (esquifit) asked that netrw allow the - /cygdrive prefix be a user-alterable - parameter. - Jan 02, 2014 * Fixed a problem with netrw-based balloon - evaluation (ie. netrw#NetrwBalloonHelp() - not having been loaded error messages) - Jan 03, 2014 * Fixed a problem with tree listings - * New command installed: |:Ntree| - Jan 06, 2014 * (Ivan Brennan) reported a problem with - |netrw-P|. Fixed. - Jan 06, 2014 * Fixed a problem with |netrw-P| when the - modified file was to be abandoned. - Jan 15, 2014 * (Matteo Cavalleri) reported that when the - banner is suppressed and tree listing is - used, a blank line was left at the top of - the display. Fixed. - Jan 20, 2014 * (Gideon Go) reported that, in tree listing - style, with a previous window open, that - the wrong directory was being used to open - a file. Fixed. (P21) - v149: Apr 18, 2013 * in wide listing format, now have maps for {{{2 - w and b to move to next/previous file - Apr 26, 2013 * one may now copy files in the same - directory; netrw will issue requests for - what names the files should be copied under - Apr 29, 2013 * Trying Benzinger's problem again. Seems - that commenting out the BufEnter and - installing VimEnter (only) works. Weird - problem! (tree listing, vim -O Dir1 Dir2) - May 01, 2013 * :Explore ftp://... wasn't working. Fixed. - May 02, 2013 * introduced |g:netrw_bannerbackslash| as - requested by Paul Domaskis. - Jul 03, 2013 * Explore now avoids splitting when a buffer - will be hidden. - v148: Apr 16, 2013 * changed Netrw's Style menu to allow direct {{{2 - choice of listing style, hiding style, and - sorting style - -============================================================================== -13. Todo *netrw-todo* {{{1 - -07/29/09 : banner :|g:netrw_banner| can be used to suppress the - suppression banner. This feature is new and experimental, - so its in the process of being debugged. -09/04/09 : "gp" : See if it can be made to work for remote systems. - : See if it can be made to work with marked files. - -============================================================================== -14. Credits *netrw-credits* {{{1 - - Vim editor by Bram Moolenaar (Thanks, Bram!) - dav support by C Campbell - fetch support by Bram Moolenaar and C Campbell - ftp support by C Campbell <NcampObell@SdrPchip.AorgM-NOSPAM> - http support by Bram Moolenaar <bram@moolenaar.net> - rcp - rsync support by C Campbell (suggested by Erik Warendorph) - scp support by raf <raf@comdyn.com.au> - sftp support by C Campbell - - inputsecret(), BufReadCmd, BufWriteCmd contributed by C Campbell - - Jérôme Augé -- also using new buffer method with ftp+.netrc - Bram Moolenaar -- obviously vim itself, :e and v:cmdarg use, - fetch,... - Yasuhiro Matsumoto -- pointing out undo+0r problem and a solution - Erik Warendorph -- for several suggestions (g:netrw_..._cmd - variables, rsync etc) - Doug Claar -- modifications to test for success with ftp - operation - -============================================================================== -Modelines: {{{1 -vim:tw=78:ts=8:ft=help:noet:norl:fdm=marker diff --git a/runtime/doc/pi_tar.txt b/runtime/doc/pi_tar.txt index c8570044e5..96b26d92e7 100644 --- a/runtime/doc/pi_tar.txt +++ b/runtime/doc/pi_tar.txt @@ -1,4 +1,4 @@ -*pi_tar.txt* For Vim version 8.2. Last change: 2020 Jan 07 +*pi_tar.txt* Nvim +====================+ | Tar File Interface | diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index f1b0daee76..69ae0f20d1 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -193,7 +193,7 @@ registers. Nvim looks for these clipboard tools, in order of priority: - xclip (if $DISPLAY is set) - lemonade (for SSH) https://github.com/pocke/lemonade - doitclient (for SSH) https://www.chiark.greenend.org.uk/~sgtatham/doit/ - - win32yank (Windows) + - *win32yank* (Windows) - putclip, getclip (Windows) https://cygwin.com/packages/summary/cygutils.html - clip, powershell (Windows) https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/clip - termux (via termux-clipboard-set, termux-clipboard-set) @@ -259,23 +259,21 @@ For Windows WSL, try this g:clipboard definition: *clipboard-osc52* Nvim bundles a clipboard provider that allows copying to the system clipboard using OSC 52. OSC 52 is an Operating System Command control sequence that -writes the copied text to the terminal emulator. If the terminal emulator -supports OSC 52 then it will write the copied text into the system clipboard. - -Nvim will attempt to automatically determine if the host terminal emulator -supports the OSC 52 sequence and enable the OSC 52 clipboard provider if it -does as long as all of the following are true: - - • Nvim is running in the |TUI| - • |g:clipboard| is unset - • 'clipboard' is not set to "unnamed" or "unnamedplus" - • $SSH_TTY is set - -If any of the above conditions are not met then the OSC 52 clipboard provider -will not be used by default and Nvim will fall back to discovering a -|clipboard-tool| through the usual process. - -To force Nvim to use the OSC 52 provider you can use the following +causes the terminal emulator to write to or read from the system clipboard. + +When Nvim is running in the |TUI|, it will automatically attempt to determine if +the host terminal emulator supports OSC 52. If it does, then Nvim will use OSC +52 for copying and pasting if no other |clipboard-tool| is found and when +'clipboard' is unset. + + *g:termfeatures* +To disable the automatic detection, set the "osc52" key of |g:termfeatures| to +|v:false| in the |config| file. Example: >lua + local termfeatures = vim.g.termfeatures or {} + termfeatures.osc52 = false + vim.g.termfeatures = termfeatures +< +To force Nvim to always use the OSC 52 provider you can use the following |g:clipboard| definition: >lua vim.g.clipboard = { diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index b3399b2766..7aeb494437 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -538,9 +538,9 @@ EXECUTE A COMMAND IN ALL THE BUFFERS IN QUICKFIX OR LOCATION LIST: < Otherwise it works the same as `:ldo`. FILTERING A QUICKFIX OR LOCATION LIST: - *cfilter-plugin* *:Cfilter* *:Lfilter* + *cfilter-plugin* *:Cfilter* *:Lfilter* *package-cfilter* If you have too many entries in a quickfix list, you can use the cfilter -plugin to reduce the number of entries. Load the plugin with: > +plugin to reduce the number of entries. Load the plugin with: >vim packadd cfilter @@ -1317,9 +1317,235 @@ g:compiler_gcc_ignore_unmatched_lines JAVAC *compiler-javac* Commonly used compiler options can be added to 'makeprg' by setting the -g:javac_makeprg_params variable. For example: > +b/g:javac_makeprg_params variable. For example: > + let g:javac_makeprg_params = "-Xlint:all -encoding utf-8" -< + +MAVEN *compiler-maven* + +Commonly used compiler options can be added to 'makeprg' by setting the +b/g:maven_makeprg_params variable. For example: > + + let g:maven_makeprg_params = "-DskipTests -U -X" + +SPOTBUGS *compiler-spotbugs* + +SpotBugs is a static analysis tool that can be used to find bugs in Java. +It scans the Java bytecode of all classes in the currently open buffer. +(Therefore, `:compiler! spotbugs` is not supported.) + +Commonly used compiler options can be added to 'makeprg' by setting the +"b:" or "g:spotbugs_makeprg_params" variable. For example: >vim + + let b:spotbugs_makeprg_params = "-longBugCodes -effort:max -low" + +The global default is "-workHard -experimental". + +By default, the class files are searched in the directory where the source +files are placed. However, typical Java projects use distinct directories +for source files and class files. To make both known to SpotBugs, assign +their paths (distinct and relative to their common root directory) to the +following properties (using the example of a common Maven project): >vim + + let g:spotbugs_properties = { + \ 'sourceDirPath': ['src/main/java'], + \ 'classDirPath': ['target/classes'], + \ 'testSourceDirPath': ['src/test/java'], + \ 'testClassDirPath': ['target/test-classes'], + \ } + +Note that source and class path entries are expected to come in pairs: define +both "sourceDirPath" and "classDirPath" when you are considering at least one, +and apply the same logic to "testSourceDirPath" and "testClassDirPath". +Note that values for the path keys describe only for SpotBugs where to look +for files; refer to the documentation for particular compiler plugins for more +information. + +The default pre- and post-compiler actions are provided for Ant, Maven, and +Javac compiler plugins and can be selected by assigning the name of a compiler +plugin (`ant`, `maven`, or `javac`) to the "compiler" key: >vim + + let g:spotbugs_properties = { + \ 'compiler': 'maven', + \ } + +This single setting is essentially equivalent to all the settings below, with +the exception made for the "PreCompilerAction" and "PreCompilerTestAction" +values: their listed |Funcref|s will obtain no-op implementations whereas the +implicit Funcrefs of the "compiler" key will obtain the requested defaults if +available. >vim + + let g:spotbugs_properties = { + \ 'PreCompilerAction': + \ function('spotbugs#DefaultPreCompilerAction'), + \ 'PreCompilerTestAction': + \ function('spotbugs#DefaultPreCompilerTestAction'), + \ 'PostCompilerAction': + \ function('spotbugs#DefaultPostCompilerAction'), + \ 'sourceDirPath': ['src/main/java'], + \ 'classDirPath': ['target/classes'], + \ 'testSourceDirPath': ['src/test/java'], + \ 'testClassDirPath': ['target/test-classes'], + \ } + +With default actions, the compiler of choice will attempt to rebuild the class +files for the buffer (and possibly for the whole project) as soon as a Java +syntax file is loaded; then, `spotbugs` will attempt to analyze the quality of +the compilation unit of the buffer. + +Vim commands proficient in 'makeprg' [0] can be composed with default actions. +Begin by considering which of the supported keys, "DefaultPreCompilerCommand", +"DefaultPreCompilerTestCommand", or "DefaultPostCompilerCommand", you need to +write an implementation for, observing that each of these keys corresponds to +a particular "*Action" key. Follow it by defining a new function that always +declares an only parameter of type string and puts to use a command equivalent +of |:make|, and assigning its |Funcref| to the selected key. For example: +>vim + function! GenericPostCompilerCommand(arguments) abort + execute 'make ' . a:arguments + endfunction + + let g:spotbugs_properties = { + \ 'DefaultPostCompilerCommand': + \ function('GenericPostCompilerCommand'), + \ } + +When "PostCompilerAction" is available, "PostCompilerActionExecutor" is also +supported. Its value must be a Funcref pointing to a function that always +declares a single parameter of type string and decides whether |:execute| can +be dispatched on its argument, containing a pending post-compiler action, +after ascertaining the current status of |:cc| (or |:ll|): >vim + + function! GenericPostCompilerActionExecutor(action) abort + try + cc + catch /\<E42:/ + execute a:action + endtry + endfunction + +Complementary, some or all of the available "Pre*Action"s (or "*Pre*Command"s) +may run `:doautocmd java_spotbugs_post User` in their implementations before +|:make| (or its equivalent) to define a once-only |ShellCmdPost| `:autocmd` +that will arrange for "PostCompilerActionExecutor" to be invoked; and then run +`:doautocmd java_spotbugs_post ShellCmdPost` to consume this event: >vim + + function! GenericPreCompilerCommand(arguments) abort + if !exists('g:spotbugs_compilation_done') + doautocmd java_spotbugs_post User + execute 'make ' . a:arguments + " only run doautocmd when :make was synchronous + " see note below + doautocmd java_spotbugs_post ShellCmdPost " XXX: (a) + let g:spotbugs_compilation_done = 1 + else + cc + endif + endfunction + + function! GenericPreCompilerTestCommand(arguments) abort + if !exists('g:spotbugs_test_compilation_done') + doautocmd java_spotbugs_post User + execute 'make ' . a:arguments + " only run doautocmd when :make was synchronous + " see note below + doautocmd java_spotbugs_post ShellCmdPost " XXX: (b) + let g:spotbugs_test_compilation_done = 1 + else + cc + endif + endfunction + + let g:spotbugs_properties = { + \ 'compiler': 'maven', + \ 'DefaultPreCompilerCommand': + \ function('GenericPreCompilerCommand'), + \ 'DefaultPreCompilerTestCommand': + \ function('GenericPreCompilerTestCommand'), + \ 'PostCompilerActionExecutor': + \ function('GenericPostCompilerActionExecutor'), + \ } + +If a command equivalent of `:make` is capable of asynchronous execution and +consuming `ShellCmdPost` events, `:doautocmd java_spotbugs_post ShellCmdPost` +must be removed from such "*Action" (or "*Command") implementations (i.e. the +lines `(a)` and `(b)` in the listed examples) to retain a sequential order for +non-blocking execution, and any notification (see below) must be suppressed. +A `ShellCmdPost` `:autocmd` can be associated with any |:augroup| by assigning +its name to the "augroupForPostCompilerAction" key. + +When default actions are not suited to a desired workflow, proceed by writing +arbitrary functions yourself and matching their Funcrefs to the supported +keys: "PreCompilerAction", "PreCompilerTestAction", and "PostCompilerAction". + +The next example re-implements the default pre-compiler actions for a Maven +project and requests other default Maven settings with the "compiler" entry: +>vim + function! MavenPreCompilerAction() abort + call spotbugs#DeleteClassFiles() + compiler maven + make compile + cc + endfunction + + function! MavenPreCompilerTestAction() abort + call spotbugs#DeleteClassFiles() + compiler maven + make test-compile + cc + endfunction + + let g:spotbugs_properties = { + \ 'compiler': 'maven', + \ 'PreCompilerAction': + \ function('MavenPreCompilerAction'), + \ 'PreCompilerTestAction': + \ function('MavenPreCompilerTestAction'), + \ } + +Note that all entered custom settings will take precedence over the matching +default settings in "g:spotbugs_properties". +Note that it is necessary to notify the plugin of the result of a pre-compiler +action before further work can be undertaken. Using |:cc| after |:make| (or +|:ll| after |:lmake|) as the last command of an action is the supported means +of such communication. + +Two commands, "SpotBugsRemoveBufferAutocmd" and "SpotBugsDefineBufferAutocmd", +are provided to toggle actions for buffer-local autocommands. For example, to +also run actions on any |BufWritePost| and |Signal| event, add these lines to +`~/.config/nvim/after/ftplugin/java.vim`: >vim + + if exists(':SpotBugsDefineBufferAutocmd') == 2 + SpotBugsDefineBufferAutocmd BufWritePost Signal + endif + +Otherwise, you can turn to `:doautocmd java_spotbugs User` at any time. + +The "g:spotbugs_properties" variable is consulted by the Java filetype plugin +(|ft-java-plugin|) to arrange for the described automation, and, therefore, it +must be defined before |FileType| events can take place for the buffers loaded +with Java source files. It could, for example, be set in a project-local +|vimrc| loaded by [1]. + +Both "g:spotbugs_properties" and "b:spotbugs_properties" are recognized and +must be modifiable (|:unlockvar|). The "*Command" entries are always treated +as global functions to be shared among all Java buffers. + +The SpotBugs Java library and, by extension, its distributed shell scripts do +not support in the `-textui` mode listed pathnames with directory filenames +that contain blank characters [2]. To work around this limitation, consider +making a symbolic link to such a directory from a directory that does not have +blank characters in its name and passing this information to SpotBugs: >vim + + let g:spotbugs_alternative_path = { + \ 'fromPath': 'path/to/dir_without_blanks', + \ 'toPath': 'path/to/dir with blanks', + \ } + +[0] https://github.com/Konfekt/vim-compilers +[1] https://github.com/MarcWeber/vim-addon-local-vimrc +[2] https://github.com/spotbugs/spotbugs/issues/909 + GNU MAKE *compiler-make* Since the default make program is "make", the compiler plugin for make, @@ -1409,6 +1635,13 @@ Useful values for the 'makeprg' options therefore are: setlocal makeprg=./alltests.py " Run a testsuite setlocal makeprg=python\ %:S " Run a single testcase +PYTEST COMPILER *compiler-pytest* +Commonly used compiler options can be added to 'makeprg' by setting the +b/g:pytest_makeprg_params variable. For example: > + + let b:pytest_makeprg_params = "--verbose --no-summary --disable-warnings" + +The global default is "--tb=short --quiet"; Python warnings are suppressed. TEX COMPILER *compiler-tex* diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index abeefb980e..e65caa72ed 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -111,7 +111,7 @@ To abort this type CTRL-C twice. ============================================================================== Complex repeats *complex-repeat* - *q* *recording* + *q* *recording* *macro* q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"} (uppercase to append). The 'q' command is disabled while executing a register, and it doesn't work inside diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt index 9d74f1f376..9895b606fd 100644 --- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -10,7 +10,7 @@ Sign Support Features *sign-support* Type |gO| to see the table of contents. ============================================================================== -1. Introduction *sign-intro* *signs* +1. Introduction *sign-intro* *signs* *gutter* When a debugger or other IDE tool is driving an editor it needs to be able to give specific highlights which quickly tell the user useful information diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 3b0fa2b371..d8d5e42397 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -164,8 +164,7 @@ argument. you can overwrite a file by adding an exclamation mark to the Ex command, as in ":w!". The 'readonly' option can be reset with ":set noro" (see the options chapter, |options|). - Subsequent edits will not be done in readonly mode. Calling - the executable "view" has the same effect as the -R argument. + Subsequent edits will not be done in readonly mode. The 'updatecount' option will be set to 10000, meaning that the swap file will not be updated automatically very often. See |-M| for disallowing modifications. @@ -207,12 +206,12 @@ argument. :print :set With |:verbose| or 'verbose', other commands display on stderr: > - nvim -es +":verbose echo 'foo'" - nvim -V1 -es +foo - -< User |config| is skipped unless |-u| was given. - Swap file is skipped (like |-n|). - User |shada| is loaded (unless "-i NONE" is given). + nvim -es +"verbose echo 'foo'" + nvim -V1 -es +"echo 'foo'" +< + Skips user |config| unless |-u| was given. + Disables |shada| unless |-i| was given. + Disables swapfile (like |-n|). *-l* -l {script} [args] @@ -226,7 +225,8 @@ argument. arguments. The {script} name is stored at `_G.arg[0]`. Sets 'verbose' to 1 (like "-V1"), so Lua `print()` writes to - output. + output, as well as other message-emitting functions like + |:echo|. If {script} prints messages and doesn't cause Nvim to exit, Nvim ensures output ends with a newline. @@ -235,6 +235,11 @@ argument. nvim +q -l foo.lua < This loads Lua module "bar" before executing "foo.lua": > nvim +"lua require('bar')" -l foo.lua +< *lua-shebang* + You can set the "shebang" of the script so that Nvim executes + the script when called with "./" from a shell (remember to + "chmod u+x"): > + #!/usr/bin/env -S nvim -l < Skips user |config| unless |-u| was given. Disables plugins unless 'loadplugins' was set. @@ -243,7 +248,7 @@ argument. *-ll* -ll {script} [args] - Execute a Lua script, similarly to |-l|, but the editor is not + Executes a Lua script, similarly to |-l|, but the editor is not initialized. This gives a Lua environment similar to a worker thread. See |lua-loop-threading|. @@ -283,21 +288,18 @@ argument. command from a script. |debug-mode| *-n* --n No |swap-file| will be used. Recovery after a crash will be - impossible. Handy if you want to view or edit a file on a - very slow medium (e.g., a floppy). - Can also be done with ":set updatecount=0". You can switch it - on again by setting the 'updatecount' option to some value, - e.g., ":set uc=100". - 'updatecount' is set to 0 AFTER executing commands from a - vimrc file, but before the GUI initializations. Thus it - overrides a setting for 'updatecount' in a vimrc file, but not - in a gvimrc file. See |startup|. - When you want to reduce accesses to the disk (e.g., for a - laptop), don't use "-n", but set 'updatetime' and - 'updatecount' to very big numbers, and type ":preserve" when - you want to save your work. This way you keep the possibility - for crash recovery. +-n Disables |swap-file| by setting 'updatecount' to 0 (after + executing any |vimrc|). Recovery after a crash will be + impossible. Improves performance when working with a file on + a very slow medium (usb drive, network share). + + Enable it again by setting 'updatecount' to some value, e.g. + ":set updatecount=100". + + To reduce accesses to the disk, don't use "-n", but set + 'updatetime' and 'updatecount' to very big numbers, and type + ":preserve" when you want to save your work. This way you + keep the possibility for crash recovery. *-o* -o[N] Open N windows, split horizontally. If [N] is not given, diff --git a/runtime/doc/support.txt b/runtime/doc/support.txt index a2776fca0d..103fb90b6d 100644 --- a/runtime/doc/support.txt +++ b/runtime/doc/support.txt @@ -12,9 +12,10 @@ Support *support* Supported platforms *supported-platforms* `System` `Tier` `Versions` `Tested versions` -Linux 1 >= 2.6.32, glibc >= 2.12 Ubuntu 24.04 -macOS (Intel) 1 >= 11 macOS 13 -macOS (M1) 1 >= 11 macOS 15 +Linux (x86_64) 1 >= 2.6.32, glibc >= 2.12 Ubuntu 24.04 +Linux (arm64) 1 >= 2.6.32, glibc >= 2.12 Ubuntu 24.04 +macOS (x86_64) 1 >= 11 macOS 13 +macOS (arm64) 1 >= 11 macOS 15 Windows 64-bit 1 >= Windows 10 Version 1809 Windows Server 2022 FreeBSD 1 >= 10 FreeBSD 14 OpenBSD 2 >= 7 diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index 75a855bbdd..75d6d85183 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -414,12 +414,15 @@ There are many types of assembly languages that all use the same file name extensions. Therefore you will have to select the type yourself, or add a line in the assembly file that Vim will recognize. Currently these syntax files are included: - asm GNU assembly (the default) + asm GNU assembly (usually have .s or .S extension and were + already built using C compiler such as GCC or CLANG) asm68k Motorola 680x0 assembly asmh8300 Hitachi H-8300 version of GNU assembly ia64 Intel Itanium 64 fasm Flat assembly (https://flatassembler.net) - masm Microsoft assembly (probably works for any 80x86) + masm Microsoft assembly (.masm files are compiled with + Microsoft's Macro Assembler. This is only supported + for x86, x86_64, ARM and AARCH64 CPU families) nasm Netwide assembly tasm Turbo Assembly (with opcodes 80x86 up to Pentium, and MMX) @@ -590,6 +593,7 @@ Variable Highlight ~ *c_no_cformat* don't highlight %-formats in strings *c_no_c99* don't highlight C99 standard items *c_no_c11* don't highlight C11 standard items +*c_no_c23* don't highlight C23 standard items *c_no_bsd* don't highlight BSD specific types *c_functions* highlight function calls and definitions *c_function_pointers* highlight function pointers definitions @@ -1741,6 +1745,16 @@ To disable numbers having their own color add the following to your vimrc: > If you want quotes to have different highlighting than strings > let g:jq_quote_highlight = 1 +KCONFIG *ft-kconfig-syntax* + +Kconfig syntax highlighting language. For syntax syncing, you can configure +the following variable (default: 50): > + + let kconfig_minlines = 50 + +To configure a bit more (heavier) highlighting, set the following variable: > + + let kconfig_syntax_heavy = 1 LACE *lace.vim* *ft-lace-syntax* @@ -5159,8 +5173,6 @@ EndOfBuffer Filler lines (~) after the end of the buffer. By default, this is highlighted like |hl-NonText|. *hl-TermCursor* TermCursor Cursor in a focused terminal. - *hl-TermCursorNC* -TermCursorNC Cursor in an unfocused terminal. *hl-ErrorMsg* ErrorMsg Error messages on the command line. *hl-WinSeparator* @@ -5242,6 +5254,8 @@ PmenuMatch Popup menu: Matched text in normal item. Combined with *hl-PmenuMatchSel* PmenuMatchSel Popup menu: Matched text in selected item. Combined with |hl-PmenuMatch| and |hl-PmenuSel|. + *hl-ComplMatchIns* +ComplMatchIns Matched text of the currently inserted completion. *hl-Question* Question |hit-enter| prompt and yes/no questions. *hl-QuickFixLine* diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt index ed9659d6e7..0ab7151728 100644 --- a/runtime/doc/terminal.txt +++ b/runtime/doc/terminal.txt @@ -26,7 +26,7 @@ Start *terminal-start* There are several ways to create a terminal buffer: - Run the |:terminal| command. -- Call the |nvim_open_term()| or |termopen()| function. +- Call |nvim_open_term()| or `jobstart(…, {'term': v:true})`. - Edit a "term://" buffer. Examples: >vim :edit term://bash :vsplit term://top @@ -101,13 +101,17 @@ Configuration *terminal-config* Options: 'modified', 'scrollback' Events: |TermOpen|, |TermEnter|, |TermLeave|, |TermClose| -Highlight groups: |hl-TermCursor|, |hl-TermCursorNC| +Highlight groups: |hl-TermCursor| Terminal sets local defaults for some options, which may differ from your global configuration. - 'list' is disabled - 'wrap' is disabled +- 'number' is disabled +- 'relativenumber' is disabled +- 'signcolumn' is set to "no" +- 'foldcolumn' is set to "0" You can change the defaults with a TermOpen autocommand: >vim au TermOpen * setlocal list @@ -161,8 +165,8 @@ directory indicated in the request. >lua end }) -To try it out, select the above code and source it with `:'<,'>lua`, then run -this command in a :terminal buffer: > +To try it out, select the above code and source it with `:'<,'>lua` (or +`g==`), then run this command in a :terminal buffer: > printf "\033]7;file://./foo/bar\033\\" @@ -203,7 +207,7 @@ Use |jobwait()| to check if the terminal job has finished: >vim let running = jobwait([&channel], 0)[0] == -1 < ============================================================================== -:Termdebug plugin *terminal-debug* +:Termdebug plugin *terminal-debug* *terminal-debugger* *package-termdebug* The Terminal debugging plugin can be used to debug a program with gdb and view the source code in a Vim window. Since this is completely contained inside diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 5fc6429f7a..b04f13add5 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -70,7 +70,7 @@ adds arbitrary metadata and conditional data to a match. Queries are written in a lisp-like language documented in https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax -Note: The predicates listed there page differ from those Nvim supports. See +Note: The predicates listed there differ from those Nvim supports. See |treesitter-predicates| for a complete list of predicates supported by Nvim. Nvim looks for queries as `*.scm` files in a `queries` directory under @@ -81,8 +81,7 @@ that user config takes precedence over plugins, which take precedence over queries bundled with Nvim). If a query should extend other queries instead of replacing them, use |treesitter-query-modeline-extends|. -See |lua-treesitter-query| for the list of available methods for working with -treesitter queries from Lua. +The Lua interface is described at |lua-treesitter-query|. TREESITTER QUERY PREDICATES *treesitter-predicates* @@ -158,12 +157,12 @@ The following predicates are built in: (field_identifier) @method)) @_parent (#has-parent? @_parent template_method function_declarator)) < - *lua-treesitter-not-predicate* + *treesitter-predicate-not* Each predicate has a `not-` prefixed predicate that is just the negation of the predicate. - *lua-treesitter-all-predicate* - *lua-treesitter-any-predicate* + *treesitter-predicate-all* + *treesitter-predicate-any* Queries can use quantifiers to capture multiple nodes. When a capture contains multiple nodes, predicates match only if ALL nodes contained by the capture match the predicate. Some predicates (`eq?`, `match?`, `lua-match?`, @@ -245,15 +244,32 @@ The following directives are built in: (#gsub! @_node ".*%.(.*)" "%1") < `trim!` *treesitter-directive-trim!* - Trim blank lines from the end of the node. This will set a new - `metadata[capture_id].range`. + Trims whitespace from the node. Sets a new + `metadata[capture_id].range`. Takes a capture ID and, optionally, four + integers to customize trimming behavior (`1` meaning trim, `0` meaning + don't trim). When only given a capture ID, trims blank lines (lines + that contain only whitespace, or are empty) from the end of the node + (for backwards compatibility). Can trim all whitespace from both sides + of the node if parameters are given. + Examples: >query + ; only trim blank lines from the end of the node + ; (equivalent to (#trim! @fold 0 0 1 0)) + (#trim! @fold) + + ; trim blank lines from both sides of the node + (#trim! @fold 1 0 1 0) + + ; trim all whitespace around the node + (#trim! @fold 1 1 1 1) +< Parameters: ~ {capture_id} + {trim_start_linewise} + {trim_start_charwise} + {trim_end_linewise} (default `1` if only given {capture_id}) + {trim_end_charwise} - Example: >query - (#trim! @fold) -< Further directives can be added via |vim.treesitter.query.add_directive()|. Use |vim.treesitter.query.list_directives()| to list all available directives. @@ -481,7 +497,7 @@ convention, nodes to be concealed are captured as `@conceal`, but any capture can be used. For example, the following query can be used to hide code block delimiters in Markdown: >query - (fenced_code_block_delimiter @conceal (#set! conceal "")) + ((fenced_code_block_delimiter) @conceal (#set! conceal "")) < It is also possible to replace a node with a single character, which (unlike legacy syntax) can be given a custom highlight. For example, the following @@ -492,6 +508,13 @@ still highlighted the same as other operators: >query < Conceals specified in this way respect 'conceallevel'. +Note that although you can use any string for `conceal`, only the first +character will be used: >query + + ; identifiers will be concealed with 'f'. + ((identifier) @conceal (#set! conceal "foo")) +< + *treesitter-highlight-priority* Treesitter uses |nvim_buf_set_extmark()| to set highlights with a default priority of 100. This enables plugins to set a highlighting priority lower or @@ -556,6 +579,10 @@ associated with patterns: • `injection.parent` - indicates that the captured node’s text should be parsed with the same language as the node's parent LanguageTree. +Injection queries are currently run over the entire buffer, which can be slow +for large buffers. To disable injections for, e.g., `c`, just place an +empty `queries/c/injections.scm` file in your 'runtimepath'. + ============================================================================== VIM.TREESITTER *lua-treesitter* @@ -816,7 +843,13 @@ TSNode:range({include_bytes}) *TSNode:range()* • end byte (if {include_bytes} is `true`) Parameters: ~ - • {include_bytes} (`boolean?`) + • {include_bytes} (`false?`) + + Return (multiple): ~ + (`integer`) + (`integer`) + (`integer`) + (`integer`) TSNode:sexpr() *TSNode:sexpr()* Get an S-expression representing the node as a string. @@ -885,8 +918,8 @@ get_captures_at_pos({bufnr}, {row}, {col}) Returns a list of highlight captures at the given position Each capture is represented by a table containing the capture name as a - string as well as a table of metadata (`priority`, `conceal`, ...; empty - if none are defined). + string, the capture's language, a table of metadata (`priority`, + `conceal`, ...; empty if none are defined), and the id of the capture. Parameters: ~ • {bufnr} (`integer`) Buffer number (0 for current buffer) @@ -894,7 +927,7 @@ get_captures_at_pos({bufnr}, {row}, {col}) • {col} (`integer`) Position column Return: ~ - (`{capture: string, lang: string, metadata: vim.treesitter.query.TSMetadata}[]`) + (`{capture: string, lang: string, metadata: vim.treesitter.query.TSMetadata, id: integer}[]`) get_node({opts}) *vim.treesitter.get_node()* Returns the smallest named node at the given position @@ -926,7 +959,7 @@ get_node_range({node_or_range}) *vim.treesitter.get_node_range()* Returns the node's range or an unpacked range table Parameters: ~ - • {node_or_range} (`TSNode|table`) Node or table of positions + • {node_or_range} (`TSNode|Range4`) Node or table of positions Return (multiple): ~ (`integer`) start_row @@ -1074,6 +1107,9 @@ start({bufnr}, {lang}) *vim.treesitter.start()* required for some plugins. In this case, add `vim.bo.syntax = 'on'` after the call to `start`. + Note: By default, the highlighter parses code asynchronously, using a + segment time of 3ms. + Example: >lua vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', callback = function(args) @@ -1098,7 +1134,7 @@ stop({bufnr}) *vim.treesitter.stop()* ============================================================================== -Lua module: vim.treesitter.language *lua-treesitter-language* +Lua module: vim.treesitter.language *treesitter-language* add({lang}, {opts}) *vim.treesitter.language.add()* Load parser with name {lang} @@ -1162,7 +1198,7 @@ inspect({lang}) *vim.treesitter.language.inspect()* • {lang} (`string`) Language Return: ~ - (`table`) + (`TSLangInfo`) register({lang}, {filetype}) *vim.treesitter.language.register()* Register a parser named {lang} to be used for {filetype}(s). @@ -1178,6 +1214,10 @@ register({lang}, {filetype}) *vim.treesitter.language.register()* ============================================================================== Lua module: vim.treesitter.query *lua-treesitter-query* +This Lua |treesitter-query| interface allows you to create queries and use +them to parse text. See |vim.treesitter.query.parse()| for a working example. + + *vim.treesitter.query.add_directive()* add_directive({name}, {handler}, {opts}) Adds a new directive to be used in queries @@ -1308,21 +1348,30 @@ omnifunc({findstart}, {base}) *vim.treesitter.query.omnifunc()* • {base} (`string`) parse({lang}, {query}) *vim.treesitter.query.parse()* - Parse {query} as a string. (If the query is in a file, the caller should - read the contents into a string before calling). - - Returns a `Query` (see |lua-treesitter-query|) object which can be used to - search nodes in the syntax tree for the patterns defined in {query} using - the `iter_captures` and `iter_matches` methods. + Parses a {query} string and returns a `Query` object + (|lua-treesitter-query|), which can be used to search the tree for the + query patterns (via |Query:iter_captures()|, |Query:iter_matches()|), or + inspect the query via these fields: + • `captures`: a list of unique capture names defined in the query (alias: + `info.captures`). + • `info.patterns`: information about predicates. - Exposes `info` and `captures` with additional context about {query}. - • `captures` contains the list of unique capture names defined in {query}. - • `info.captures` also points to `captures`. - • `info.patterns` contains information about predicates. + Example: >lua + local query = vim.treesitter.query.parse('vimdoc', [[ + ; query + ((h1) @str + (#trim! @str 1 1 1 1)) + ]]) + local tree = vim.treesitter.get_parser():parse()[1] + for id, node, metadata in query:iter_captures(tree:root(), 0) do + -- Print the node name and source text. + vim.print({node:type(), vim.treesitter.get_node_text(node, vim.api.nvim_get_current_buf())}) + end +< Parameters: ~ • {lang} (`string`) Language to use for the query - • {query} (`string`) Query in s-expr syntax + • {query} (`string`) Query text, in s-expr syntax Return: ~ (`vim.treesitter.Query`) Parsed query @@ -1332,18 +1381,23 @@ parse({lang}, {query}) *vim.treesitter.query.parse()* *Query:iter_captures()* Query:iter_captures({node}, {source}, {start}, {stop}) - Iterate over all captures from all matches inside {node} - - {source} is needed if the query contains predicates; then the caller must - ensure to use a freshly parsed tree consistent with the current text of - the buffer (if relevant). {start} and {stop} can be used to limit matches - inside a row range (this is typically used with root node as the {node}, - 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 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 + Iterates over all captures from all matches in {node}. + + {source} is required if the query contains predicates; then the caller + must ensure to use a freshly parsed tree consistent with the current text + of the buffer (if relevant). {start} and {stop} can be used to limit + matches inside a row range (this is typically used with root node as the + {node}, 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 four values: + 1. the numeric id identifying the capture + 2. the captured node + 3. metadata from any directives processing the match + 4. the match itself + + Example: 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: @@ -1367,8 +1421,8 @@ Query:iter_captures({node}, {source}, {start}, {stop}) Defaults to `node:end_()`. Return: ~ - (`fun(end_line: integer?): integer, TSNode, vim.treesitter.query.TSMetadata, TSQueryMatch`) - capture id, capture node, metadata, match + (`fun(end_line: integer?): integer, TSNode, vim.treesitter.query.TSMetadata, TSQueryMatch, TSTree`) + capture id, capture node, metadata, match, tree *Query:iter_matches()* Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) @@ -1388,7 +1442,7 @@ Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) -- `node` was captured by the `name` capture in the match local node_data = metadata[id] -- Node level metadata - ... use the info here ... + -- ... use the info here ... end end end @@ -1413,14 +1467,24 @@ Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) compatibility and will be removed in a future release. Return: ~ - (`fun(): integer, table<integer, TSNode[]>, vim.treesitter.query.TSMetadata`) - pattern id, match, metadata + (`fun(): integer, table<integer, TSNode[]>, vim.treesitter.query.TSMetadata, TSTree`) + pattern id, match, metadata, tree set({lang}, {query_name}, {text}) *vim.treesitter.query.set()* Sets the runtime query named {query_name} for {lang} - This allows users to override any runtime files and/or configuration set - by plugins. + This allows users to override or extend any runtime files and/or + configuration set by plugins. + + For example, you could enable spellchecking of `C` identifiers with the + following code: >lua + vim.treesitter.query.set( + 'c', + 'highlights', + [[;inherits c + (identifier) @spell]]) + ]]) +< Parameters: ~ • {lang} (`string`) Language to use for the query @@ -1429,7 +1493,7 @@ set({lang}, {query_name}, {text}) *vim.treesitter.query.set()* ============================================================================== -Lua module: vim.treesitter.languagetree *lua-treesitter-languagetree* +Lua module: vim.treesitter.languagetree *treesitter-languagetree* A *LanguageTree* contains a tree of parsers: the root treesitter parser for {lang} and any "injected" language parsers, which themselves may inject other @@ -1465,6 +1529,9 @@ analysis on a tree should use a timer to throttle too frequent updates. LanguageTree:children() *LanguageTree:children()* Returns a map of language to child tree. + Return: ~ + (`table<string,vim.treesitter.LanguageTree>`) + LanguageTree:contains({range}) *LanguageTree:contains()* Determines whether {range} is contained in the |LanguageTree|. @@ -1514,7 +1581,8 @@ LanguageTree:invalidate({reload}) *LanguageTree:invalidate()* Parameters: ~ • {reload} (`boolean?`) -LanguageTree:is_valid({exclude_children}) *LanguageTree:is_valid()* + *LanguageTree:is_valid()* +LanguageTree:is_valid({exclude_children}, {range}) Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()| reflects the latest state of the source. If invalid, user should call |LanguageTree:parse()|. @@ -1522,6 +1590,7 @@ LanguageTree:is_valid({exclude_children}) *LanguageTree:is_valid()* Parameters: ~ • {exclude_children} (`boolean?`) whether to ignore the validity of children (default `false`) + • {range} (`Range?`) range to check for validity Return: ~ (`boolean`) @@ -1529,6 +1598,9 @@ LanguageTree:is_valid({exclude_children}) *LanguageTree:is_valid()* LanguageTree:lang() *LanguageTree:lang()* Gets the language of this tree node. + Return: ~ + (`string`) + *LanguageTree:language_for_range()* LanguageTree:language_for_range({range}) Gets the appropriate language that contains {range}. @@ -1577,7 +1649,13 @@ LanguageTree:node_for_range({range}, {opts}) Return: ~ (`TSNode?`) -LanguageTree:parse({range}) *LanguageTree:parse()* +LanguageTree:parent() *LanguageTree:parent()* + Returns the parent tree. `nil` for the root tree. + + Return: ~ + (`vim.treesitter.LanguageTree?`) + +LanguageTree:parse({range}, {on_parse}) *LanguageTree:parse()* Recursively parse all regions in the language tree using |treesitter-parsers| for the corresponding languages and run injection queries on the parsed trees to determine whether child trees should be @@ -1588,14 +1666,27 @@ LanguageTree:parse({range}) *LanguageTree:parse()* if {range} is `true`). Parameters: ~ - • {range} (`boolean|Range?`) Parse this range in the parser's source. - Set to `true` to run a complete parse of the source (Note: - Can be slow!) Set to `false|nil` to only parse regions with - empty ranges (typically only the root tree without - injections). + • {range} (`boolean|Range?`) Parse this range in the parser's + source. Set to `true` to run a complete parse of the + source (Note: Can be slow!) Set to `false|nil` to only + parse regions with empty ranges (typically only the root + tree without injections). + • {on_parse} (`fun(err?: string, trees?: table<integer, TSTree>)?`) + Function invoked when parsing completes. When provided and + `vim.g._ts_force_sync_parsing` is not set, parsing will + run asynchronously. The first argument to the function is + a string representing the error type, in case of a failure + (currently only possible for timeouts). The second + argument is the list of trees returned by the parse (upon + success), or `nil` if the parse timed out (determined by + 'redrawtime'). + + If parsing was still able to finish synchronously (within + 3ms), `parse()` returns the list of trees. Otherwise, it + returns `nil`. Return: ~ - (`table<integer, TSTree>`) + (`table<integer, TSTree>?`) *LanguageTree:register_cbs()* LanguageTree:register_cbs({cbs}, {recursive}) @@ -1624,6 +1715,9 @@ LanguageTree:register_cbs({cbs}, {recursive}) LanguageTree:source() *LanguageTree:source()* Returns the source content of the language tree (bufnr or string). + Return: ~ + (`integer|string`) + *LanguageTree:tree_for_range()* LanguageTree:tree_for_range({range}, {opts}) Gets the tree that contains {range}. diff --git a/runtime/doc/tui.txt b/runtime/doc/tui.txt index 9493f91b1e..96ac54abc5 100644 --- a/runtime/doc/tui.txt +++ b/runtime/doc/tui.txt @@ -280,191 +280,5 @@ colours of whitespace are immaterial, in practice they change the colours of cursors and selections that cross them. This may have a visible, but minor, effect on some UIs. -============================================================================== -Using the mouse *mouse-using* - - *mouse-mode-table* *mouse-overview* -Overview of what the mouse buttons do, when 'mousemodel' is "extend": - - *<S-LeftMouse>* *<A-RightMouse>* *<S-RightMouse>* *<RightDrag>* - *<RightRelease>* *<LeftDrag>* -Normal Mode: > - event position selection change action - cursor window - --------------------------------------------------------------------------- - <LeftMouse> yes end yes - <C-LeftMouse> yes end yes "CTRL-]" (2) - <S-LeftMouse> yes no change yes "*" (2) - <LeftDrag> yes start or extend (1) no - <LeftRelease> yes start or extend (1) no - <MiddleMouse> yes if not active no put - <MiddleMouse> yes if active no yank and put - <RightMouse> yes start or extend yes - <A-RightMouse> yes start or extend blockw. yes - <S-RightMouse> yes no change yes "#" (2) - <C-RightMouse> no no change no "CTRL-T" - <RightDrag> yes extend no - <RightRelease> yes extend no - -Insert or Replace Mode: > - event position selection change action - cursor window - --------------------------------------------------------------------------- - <LeftMouse> yes (cannot be active) yes - <C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2) - <S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2) - <LeftDrag> yes start or extend (1) no like CTRL-O (1) - <LeftRelease> yes start or extend (1) no like CTRL-O (1) - <MiddleMouse> no (cannot be active) no put register - <RightMouse> yes start or extend yes like CTRL-O - <A-RightMouse> yes start or extend blockw. yes - <S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2) - <C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T" - -In a help window: > - event position selection change action - cursor window - --------------------------------------------------------------------------- - <2-LeftMouse> yes (cannot be active) no "^]" (jump to help tag) - -When 'mousemodel' is "popup", these are different: - - *<A-LeftMouse>* -Normal Mode: > - event position selection change action - cursor window - --------------------------------------------------------------------------- - <S-LeftMouse> yes start or extend (1) no - <A-LeftMouse> yes start/extend blockw no - <RightMouse> no popup menu no - -Insert or Replace Mode: > - event position selection change action - cursor window - --------------------------------------------------------------------------- - <S-LeftMouse> yes start or extend (1) no like CTRL-O (1) - <A-LeftMouse> yes start/extend blockw no - <RightMouse> no popup menu no - -(1) only if mouse pointer moved since press -(2) only if click is in same buffer - -Clicking the left mouse button causes the cursor to be positioned. If the -click is in another window that window is made the active window. When -editing the command-line the cursor can only be positioned on the -command-line. When in Insert mode Vim remains in Insert mode. If 'scrolloff' -is set, and the cursor is positioned within 'scrolloff' lines from the window -border, the text is scrolled. - -A selection can be started by pressing the left mouse button on the first -character, moving the mouse to the last character, then releasing the mouse -button. You will not always see the selection until you release the button, -only in some versions (GUI, Win32) will the dragging be shown immediately. -Note that you can make the text scroll by moving the mouse at least one -character in the first/last line in the window when 'scrolloff' is non-zero. - -In Normal, Visual and Select mode clicking the right mouse button causes the -Visual area to be extended. When 'mousemodel' is "popup", the left button has -to be used while keeping the shift key pressed. When clicking in a window -which is editing another buffer, the Visual or Select mode is stopped. - -In Normal, Visual and Select mode clicking the right mouse button with the alt -key pressed causes the Visual area to become blockwise. When 'mousemodel' is -"popup" the left button has to be used with the alt key. Note that this won't -work on systems where the window manager consumes the mouse events when the -alt key is pressed (it may move the window). - - *double-click* *<2-LeftMouse>* *<3-LeftMouse>* *<4-LeftMouse>* -Double, triple and quadruple clicks are supported when the GUI is active, for -Win32 and for an xterm. For selecting text, extra clicks extend the -selection: > - - click select - --------------------------------- - double word or % match - triple line - quadruple rectangular block - -Exception: In a Help window a double click jumps to help for the word that is -clicked on. - -A double click on a word selects that word. 'iskeyword' is used to specify -which characters are included in a word. A double click on a character -that has a match selects until that match (like using "v%"). If the match is -an #if/#else/#endif block, the selection becomes linewise. -For MS-Windows and xterm the time for double clicking can be set with the -'mousetime' option. For the other systems this time is defined outside of Vim. -An example, for using a double click to jump to the tag under the cursor: >vim - :map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR> - -Dragging the mouse with a double click (button-down, button-up, button-down -and then drag) will result in whole words to be selected. This continues -until the button is released, at which point the selection is per character -again. - -For scrolling with the mouse see |scroll-mouse-wheel|. - -In Insert mode, when a selection is started, Vim goes into Normal mode -temporarily. When Visual or Select mode ends, it returns to Insert mode. -This is like using CTRL-O in Insert mode. Select mode is used when the -'selectmode' option contains "mouse". - - *X1Mouse* *X1Drag* *X1Release* - *X2Mouse* *X2Drag* *X2Release* - *<MiddleRelease>* *<MiddleDrag>* -Mouse clicks can be mapped. The codes for mouse clicks are: > - code mouse button normal action - --------------------------------------------------------------------------- - <LeftMouse> left pressed set cursor position - <LeftDrag> left moved while pressed extend selection - <LeftRelease> left released set selection end - <MiddleMouse> middle pressed paste text at cursor position - <MiddleDrag> middle moved while pressed - - <MiddleRelease> middle released - - <RightMouse> right pressed extend selection - <RightDrag> right moved while pressed extend selection - <RightRelease> right released set selection end - <X1Mouse> X1 button pressed - - <X1Drag> X1 moved while pressed - - <X1Release> X1 button release - - <X2Mouse> X2 button pressed - - <X2Drag> X2 moved while pressed - - <X2Release> X2 button release - - -The X1 and X2 buttons refer to the extra buttons found on some mice. The -'Microsoft Explorer' mouse has these buttons available to the right thumb. -Currently X1 and X2 only work on Win32 and X11 environments. - -Examples: >vim - :noremap <MiddleMouse> <LeftMouse><MiddleMouse> -Paste at the position of the middle mouse button click (otherwise the paste -would be done at the cursor position). >vim - - :noremap <LeftRelease> <LeftRelease>y -Immediately yank the selection, when using Visual mode. - -Note the use of ":noremap" instead of "map" to avoid a recursive mapping. ->vim - :map <X1Mouse> <C-O> - :map <X2Mouse> <C-I> -Map the X1 and X2 buttons to go forwards and backwards in the jump list, see -|CTRL-O| and |CTRL-I|. - - *mouse-swap-buttons* -To swap the meaning of the left and right mouse buttons: >vim - :noremap <LeftMouse> <RightMouse> - :noremap <LeftDrag> <RightDrag> - :noremap <LeftRelease> <RightRelease> - :noremap <RightMouse> <LeftMouse> - :noremap <RightDrag> <LeftDrag> - :noremap <RightRelease> <LeftRelease> - :noremap g<LeftMouse> <C-RightMouse> - :noremap g<RightMouse> <C-LeftMouse> - :noremap! <LeftMouse> <RightMouse> - :noremap! <LeftDrag> <RightDrag> - :noremap! <LeftRelease> <RightRelease> - :noremap! <RightMouse> <LeftMouse> - :noremap! <RightDrag> <LeftDrag> - :noremap! <RightRelease> <LeftRelease> -< + vim:et:sw=2:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index 4e8253c47a..d8a0e3d0d7 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -562,7 +562,7 @@ with the following possible keys: "ui": Builtin UI highlight. |highlight-groups| "syntax": Highlight applied to a buffer by a syntax declaration or other runtime/plugin functionality such as - |nvim_buf_add_highlight()| + |nvim_buf_set_extmark()| "terminal": highlight from a process running in a |terminal-emulator|. Contains no further semantic information. `ui_name`: Highlight name from |highlight-groups|. Only for "ui" kind. @@ -715,7 +715,7 @@ Activated by the `ext_cmdline` |ui-option|. This UI extension delegates presentation of the |cmdline| (except 'wildmenu'). For command-line 'wildmenu' UI events, activate |ui-popupmenu|. -["cmdline_show", content, pos, firstc, prompt, indent, level] ~ +["cmdline_show", content, pos, firstc, prompt, indent, level, hl_id] ~ content: List of [attrs, string] [[{}, "t"], [attrs, "est"], ...] @@ -728,8 +728,8 @@ For command-line 'wildmenu' UI events, activate |ui-popupmenu|. `firstc` and `prompt` are text, that if non-empty should be displayed in front of the command line. `firstc` always indicates built-in command lines such as `:` (ex command) and `/` `?` (search), - while `prompt` is an |input()| prompt. `indent` tells how many spaces - the content should be indented. + while `prompt` is an |input()| prompt, highlighted with `hl_id`. + `indent` tells how many spaces the content should be indented. The Nvim command line can be invoked recursively, for instance by typing `<c-r>=` at the command line prompt. The `level` field is used @@ -749,8 +749,9 @@ For command-line 'wildmenu' UI events, activate |ui-popupmenu|. Should be hidden at next cmdline_show. -["cmdline_hide"] ~ - Hide the cmdline. +["cmdline_hide", abort] ~ + Hide the cmdline. `abort` is true if the cmdline is hidden after an + aborting condition (|c_Esc| or |c_CTRL-C|). ["cmdline_block_show", lines] ~ Show a block of context to the current command line. For example if @@ -783,24 +784,33 @@ 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] ~ +["msg_show", kind, content, replace_last, history] ~ Display a message to the user. kind Name indicating the message kind: - "" (empty) Unknown (consider a feature-request: |bugs|) + "" (empty) Unknown (consider a |feature-request|) + "bufwrite" |:write| message "confirm" |confirm()| or |:confirm| dialog - "confirm_sub" |:substitute| confirm dialog |:s_c| "emsg" Error (|errors|, internal error, |:throw|, …) "echo" |:echo| message "echomsg" |:echomsg| message "echoerr" |:echoerr| message + "completion" |ins-completion-menu| message + "list_cmd" List output for various commands (|:ls|, |:set|, …) "lua_error" Error in |:lua| code "lua_print" |print()| from |:lua| code "rpc_error" Error response from |rpcrequest()| "return_prompt" |press-enter| prompt after a multiple messages "quickfix" Quickfix navigation message + "search_cmd" Entered search command "search_count" Search count message ("S" flag of 'shortmess') + "shell_err" |:!cmd| shell stderr output + "shell_out" |:!cmd| shell stdout output + "shell_ret" |:!cmd| shell return code + "undo" |:undo| and |:redo| message + "verbose" 'verbose' message + "wildlist" 'wildmode' "list" message "wmsg" Warning ("search hit BOTTOM", |W10|, …) New kinds may be added in the future; clients should treat unknown kinds as the empty kind. @@ -819,6 +829,9 @@ must handle. true: Replace the message in the most-recent `msg_show` call, but any other visible message should still remain. + history + True if the message was added to the |:messages| history. + ["msg_clear"] ~ Clear all messages currently displayed by "msg_show". (Messages sent by other "msg_" events below will not be affected). diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt index 1fc612de26..41cee4e540 100644 --- a/runtime/doc/usr_02.txt +++ b/runtime/doc/usr_02.txt @@ -684,6 +684,13 @@ Summary: *help-summary* > :help E128 < takes you to the |:function| command +27) Documentation for packages distributed with Vim have the form + package-<name>. So > + :help package-termdebug +< + will bring you to the help section for the included termdebug plugin and + how to enable it. + ============================================================================== diff --git a/runtime/doc/usr_05.txt b/runtime/doc/usr_05.txt index 698d1207d3..d75438cd22 100644 --- a/runtime/doc/usr_05.txt +++ b/runtime/doc/usr_05.txt @@ -235,7 +235,7 @@ an archive or as a repository. For an archive you can follow these steps: else. -Adding nohlsearch package *nohlsearch-install* +Adding nohlsearch package *nohlsearch-install* *package-nohlsearch* Load the plugin with this command: > packadd nohlsearch diff --git a/runtime/doc/usr_10.txt b/runtime/doc/usr_10.txt index 2f55aadef0..98337e4b76 100644 --- a/runtime/doc/usr_10.txt +++ b/runtime/doc/usr_10.txt @@ -192,7 +192,7 @@ following: > Vim finds the first occurrence of "Professor" and displays the text it is about to change. You get the following prompt: > - replace with Teacher (y/n/a/q/l/^E/^Y)? + replace with Teacher? (y)es/(n)o/(a)ll/(q)uit/(l)ast/scroll up(^E)/down(^Y) At this point, you must enter one of the following answers: diff --git a/runtime/doc/usr_25.txt b/runtime/doc/usr_25.txt index 955d2ae5f0..8dbe1332b5 100644 --- a/runtime/doc/usr_25.txt +++ b/runtime/doc/usr_25.txt @@ -190,15 +190,15 @@ This results in the following: story. ~ -JUSTIFYING TEXT +JUSTIFYING TEXT *justify* *:Justify* *Justify()* *package-justify* Vim has no built-in way of justifying text. However, there is a neat macro package that does the job. To use this package, execute the following -command: > +command: >vim :packadd justify -Or put this line in your |vimrc|: > +Or put this line in your |vimrc|: >vim packadd! justify diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 3202a70b76..f958491ccf 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -1103,7 +1103,8 @@ Various: *various-functions* did_filetype() check if a FileType autocommand was used eventhandler() check if invoked by an event handler getpid() get process ID of Vim - getscriptinfo() get list of sourced vim scripts + getscriptinfo() get list of sourced Vim scripts + getstacktrace() get current stack trace of Vim scripts libcall() call a function in an external library libcallnr() idem, returning a number diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index 1ded5154a7..662519d415 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -282,6 +282,16 @@ gx Opens the current filepath or URL (decided by requires using the call operator (&). > :!Write-Output "1`n2" | & "C:\Windows\System32\sort.exe" /r < + Vim builds command line using options 'shell', 'shcf', + 'sxq' and 'shq' in the following order: + `&sh &shcf &sxq &shq {cmd} &shq &sxq` + So setting both 'sxq' and 'shq' is possible but rarely + useful. Additional escaping inside `{cmd}` may also + be due to 'sxe' option. + + Also, all |cmdline-special| characters in {cmd} are + replaced by Vim before passing them to shell. + *E34* Any "!" in {cmd} is replaced with the previous external command (see also 'cpoptions'), unless @@ -524,7 +534,8 @@ gO Show a filetype-specific, navigable "outline" of the current buffer. For example, in a |help| buffer this shows the table of contents. - Currently works in |help| and |:Man| buffers. + Works in |help| and |:Man| buffers, or any buffer with + an active |LSP| client (|lsp-defaults|). [N]gs *gs* *:sl* *:sleep* :[N]sl[eep] [N][m] Do nothing for [N] seconds, or [N] milliseconds if [m] @@ -541,8 +552,12 @@ gO Show a filetype-specific, navigable "outline" of the Queued messages are processed during the sleep. *:sl!* *:sleep!* -:[N]sl[eep]! [N][m] Same as above. Unlike Vim, it does not hide the - cursor. |vim-differences| +:[N]sl[eep]! [N][m] Same as above, but hide the cursor. + + *g==* +g== Executes the current code block. + + Works in |help| buffers. ============================================================================== 2. Using Vim like less or more *less* diff --git a/runtime/doc/vietnamese.txt b/runtime/doc/vietnamese.txt new file mode 100644 index 0000000000..ed3fe9bc68 --- /dev/null +++ b/runtime/doc/vietnamese.txt @@ -0,0 +1,73 @@ +*vietnamese.txt* Nvim + + + VIM REFERENCE MANUAL by Phạm Bình An + + Type |gO| to see the table of contents. + +=============================================================================== +1. Introduction + *vietnamese-intro* +Vim supports Vietnamese language in the following ways: + +- Built-in |vietnamese-keymap|, which allows you to type Vietnamese characters + in |Insert-mode| and |search-commands| using US keyboard layout. +- Localization in Vietnamese. See |vietnamese-l10n| + +=============================================================================== +2. Vietnamese keymaps + *vietnamese-keymap* +To switch between languages you can use your system native keyboard switcher, +or use one of the Vietnamese keymaps included in the Vim distribution, like +below > + :set keymap=vietnamese-telex_utf-8 +< +See |'keymap'| for more information. + +In the latter case, you can type Vietnamese even if you do not have a +Vietnamese input method engine (IME) or you want Vim to be independent from a +system-wide keyboard settings (when |'imdisable'| is set). You can also |:map| +a key to switch between keyboards. + +Vim comes with the following Vietnamese keymaps: +- *vietnamese-telex_utf-8* Telex input method, |UTF-8| encoding. +- *vietnamese-viqr_utf-8* VIQR input method, |UTF-8| encoding. +- *vietnamese-vni_utf-8* VNI input method, |UTF-8| encoding. + + *vietnamese-ime_diff* +Since these keymaps were designed to be minimalistic, they do not support all +features of the corresponding input methods. The differences are described +below: + +- You can only type each character individually, entering the base letter first + and then the diacritics later. For example, to type the word `nến` using + |vietnamese-vni_utf-8|, you must type `ne61n`, not `nen61` or `ne6n1` +- For characters with more than 1 diacritic, you need to type vowel mark before + tone mark. For example, to type `ồ` using |vietnamese-telex_utf-8|, you need + to type `oof`, not `ofo`. +- With |vietnamese-telex_utf-8|, you need to type all uppercase letters to + produce uppercase characters with diacritics. For example, `Ừ` must be typed + as `UWF`. +- With |vietnamese-telex_utf-8|, the escape character `\` from VNI is added, + hence the confusing `ooo` input to type `oo` is removed, which could lead to + ambiguities. For example, to type the word `Đoòng`, you would type + `DDo\ofng`. +- Simple Telex (both v1 and v2), including the `w[]{}` style, is not + supported. +- Removing diacritics using `z` in Telex or `0` in VNI and VIQR is not supported. + +=============================================================================== +3. Localization + *vietnamese-l10n* +Vim |messages| are also available in Vietnamese. If you wish to see messages +in Vietnamese, you can run the command |:language| with an argument being the +name of the Vietnamese locale. For example, > + :language vi_VN +< or > + :language vi_VN.utf-8 +< +Note that the name of the Vietnamese locale may vary depending on your system. +See |mbyte-first| for details. + +=============================================================================== +vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 8fa94a2601..eae341da49 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -24,7 +24,7 @@ User configuration and data files are found in standard |base-directories| session information. |shada| ============================================================================== -Defaults *nvim-defaults* +Defaults *defaults* *nvim-defaults* - Filetype detection is enabled by default. This can be disabled by adding ":filetype off" to |init.vim|. @@ -39,7 +39,6 @@ Defaults *nvim-defaults* - 'autoindent' is enabled - 'autoread' is enabled (works in all UIs, including terminal) - 'background' defaults to "dark" (unless set automatically by the terminal/UI) -- 'backspace' defaults to "indent,eol,start" - 'backupdir' defaults to .,~/.local/state/nvim/backup// (|xdg|), auto-created - 'belloff' defaults to "all" - 'comments' includes "fb:•" @@ -89,7 +88,6 @@ Defaults *nvim-defaults* - 'undodir' defaults to ~/.local/state/nvim/undo// (|xdg|), auto-created - 'viewoptions' includes "unix,slash", excludes "options" - 'viminfo' includes "!" -- 'wildmenu' is enabled - 'wildoptions' defaults to "pum,tagfile" - |editorconfig| plugin is enabled, .editorconfig settings are applied. @@ -124,7 +122,7 @@ fully disable the mouse or popup-menu, do any of the following: < To remove the default popup-menu without disabling mouse: >vim aunmenu PopUp - autocmd! nvim_popupmenu + autocmd! nvim.popupmenu To remove only the "How-to disable mouse" menu item (and its separator): >vim aunmenu PopUp.How-to\ disable\ mouse @@ -172,7 +170,7 @@ DEFAULT AUTOCOMMANDS Default autocommands exist in the following groups. Use ":autocmd! {group}" to remove them and ":autocmd {group}" to see how they're defined. -nvim_terminal: +nvim.terminal: - BufReadCmd: Treats "term://" buffers as |terminal| buffers. |terminal-start| - TermClose: A |terminal| buffer started with no arguments (which thus uses 'shell') and which exits with no error is closed automatically. @@ -188,13 +186,17 @@ nvim_terminal: - 'textwidth' set to 0 - 'nowrap' - 'nolist' + - 'nonumber' + - 'norelativenumber' + - 'signcolumn' set to "no" + - 'foldcolumn' set to "0" - 'winhighlight' uses |hl-StatusLineTerm| and |hl-StatusLineTermNC| in place of |hl-StatusLine| and |hl-StatusLineNC| -nvim_cmdwin: +nvim.cmdwin: - CmdwinEnter: Limits syntax sync to maxlines=1 in the |cmdwin|. -nvim_swapfile: +nvim.swapfile: - SwapExists: Skips the swapfile prompt (sets |v:swapchoice| to "e") when the swapfile is owned by a running Nvim process. Shows |W325| "Ignoring swapfile…" message. @@ -289,7 +291,8 @@ Commands: User commands can support |:command-preview| to show results as you type - |:write| with "++p" flag creates parent directories. -Events: +Events (autocommands): +- Fixed inconsistent behavior in execution of nested autocommands #23368 - |RecordingEnter| - |RecordingLeave| - |SearchWrapped| @@ -297,6 +300,8 @@ Events: - |TabNewEntered| - |TermClose| - |TermOpen| +- |TermResponse| is fired for any OSC sequence received from the terminal, + instead of the Primary Device Attributes response. |v:termresponse| - |UIEnter| - |UILeave| @@ -323,7 +328,6 @@ Highlight groups: - |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' @@ -343,11 +347,14 @@ Options: - `:set {option}<` removes local value for all |global-local| options. - `:setlocal {option}<` copies global value to local value for all options. +- 'ambiwidth' cannot be set to empty. - 'autoread' works in the terminal (if it supports "focus" events) +- 'background' cannot be set to empty. - 'cpoptions' flags: |cpo-_| -- 'diffopt' "linematch" feature +- 'eadirection' cannot be set to empty. - 'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The user is prompted whether to trust the file. +- 'fileformat' cannot be set to empty. - 'fillchars' flags: "msgsep", "horiz", "horizup", "horizdown", "vertleft", "vertright", "verthoriz" - 'foldcolumn' supports up to 9 dynamic/fixed columns @@ -359,14 +366,17 @@ Options: - "clean" removes unloaded buffers from the jumplist. - the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|. - 'laststatus' global statusline support +- 'mousemodel' cannot be set to empty. - '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 +- 'showcmdloc' cannot be set to empty. +- 'signcolumn' can show multiple signs (dynamic or fixed columns) - 'statuscolumn' full control of columns using 'statusline' format +- 'splitkeep' cannot be set to empty. - 'tabline' middle-click on tabpage label closes tabpage, and %@Func@foo%X can call any function on mouse-click - 'termpastefilter' @@ -374,6 +384,10 @@ Options: - 'winblend' pseudo-transparency in floating windows |api-floatwin| - 'winhighlight' window-local highlights +Performance: +- Signs are implemented using Nvim's internal "marktree" (btree) structure. +- Folds are not updated during insert-mode. + Providers: - If a Python interpreter is available on your `$PATH`, |:python| and |:python3| are always available. See |provider-python|. @@ -391,6 +405,7 @@ Shell: - |system()| does not support writing/reading "backgrounded" commands. |E5677| Signs: +- 'signcolumn' can show multiple signs. - Signs are removed if the associated line is deleted. - Signs placed twice with the same identifier in the same group are moved. @@ -400,6 +415,8 @@ Startup: - |-es| and |-Es| have improved behavior: - Quits automatically, don't need "-c qa!". - Skips swap-file dialog. + - Optimized for non-interactive scripts: disables swapfile, shada. +- |-l| Executes Lua scripts non-interactively. - |-s| reads Normal commands from stdin if the script name is "-". - Reading text (instead of commands) from stdin |--|: - works by default: "-" file is optional @@ -412,9 +429,12 @@ TUI: < *'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 + checks. Use `:echo &term` to get its value. For debugging only; not + reliable during startup. + - Note: If you want to detect when Nvim is running in a terminal, use + `has('gui_running')` |has()| or see |nvim_list_uis()| for an example of + how to inspect the UI channel. +- "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 only 8 colours plus bright foreground on Linux VTs. @@ -445,6 +465,7 @@ Upstreamed features *nvim-upstreamed* These Nvim features were later integrated into Vim. +- 'diffopt' "linematch" feature - 'fillchars' flags: "eob" - 'jumpoptions' "stack" behavior - 'wildoptions' flags: "pum" enables popupmenu for wildmode completion @@ -583,9 +604,6 @@ Mappings: Motion: - The |jumplist| avoids useless/phantom jumps. -Performance: -- Folds are not updated during insert-mode. - Syntax highlighting: - syncolor.vim has been removed. Nvim now sets up default highlighting groups automatically for both light and dark backgrounds, regardless of whether or @@ -610,11 +628,10 @@ Working directory (Vim implemented some of these after Nvim): - `getcwd(-1)` is equivalent to `getcwd(-1, 0)` instead of returning the global working directory. Use `getcwd(-1, -1)` to get the global working directory. -Autocommands: -- Fixed inconsistent behavior in execution of nested autocommands: - https://github.com/neovim/neovim/issues/23368 -- |TermResponse| is fired for any OSC sequence received from the terminal, - instead of the Primary Device Attributes response. |v:termresponse| +Options: +- 'titlestring' uses printf-style '%' items (see: 'statusline') to implement + the default behaviour. The implementation is equivalent to setting + 'titlestring' to `%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim`. ============================================================================== Missing features *nvim-missing* @@ -663,7 +680,6 @@ Commands: - :promptrepl - :scriptversion (always version 1) - :shell -- :sleep! (does not hide the cursor; same as :sleep) - :smile - :tearoff - :cstag @@ -683,7 +699,7 @@ Cscope: https://github.com/dhananjaylatkar/cscope_maps.nvim Eval: -- Vim9script +- *Vim9script* (the Vim 9+ flavor of Vimscript) is not supported. - *cscope_connection()* - *err_teapot()* - *js_encode()* diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt index 0c349c4e57..0ebb54e38a 100644 --- a/runtime/doc/vvars.txt +++ b/runtime/doc/vvars.txt @@ -6,7 +6,8 @@ Predefined variables *vvars* -Some variables can be set by the user, but the type cannot be changed. +Most variables are read-only, when a variable can be set by the user, it will +be mentioned at the variable description below. The type cannot be changed. Type |gO| to see the table of contents. @@ -189,11 +190,14 @@ v:event changing window (or tab) on |DirChanged|. status Job status or exit code, -1 means "unknown". |TermClose| reason Reason for completion being done. |CompleteDone| + complete_word The word that was selected, empty if abandoned complete. + complete_type See |complete_info_mode| *v:exception* *exception-variable* v:exception The value of the exception most recently caught and not - finished. See also |v:throwpoint| and |throw-variables|. + finished. See also |v:stacktrace|, |v:throwpoint|, and + |throw-variables|. Example: >vim try throw "oops" @@ -584,6 +588,13 @@ v:shell_error endif < + *v:stacktrace* *stacktrace-variable* +v:stacktrace + The stack trace of the exception most recently caught and + not finished. Refer to |getstacktrace()| for the structure of + stack trace. See also |v:exception|, |v:throwpoint|, and + |throw-variables|. + *v:statusmsg* *statusmsg-variable* v:statusmsg Last given status message. @@ -677,7 +688,7 @@ v:this_session v:throwpoint The point where the exception most recently caught and not finished was thrown. Not set when commands are typed. See - also |v:exception| and |throw-variables|. + also |v:exception|, |v:stacktrace|, and |throw-variables|. Example: >vim try throw "oops" diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 24aa7b1b11..6dd90f7e49 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -941,8 +941,8 @@ set in the preview window to be able to recognize it. The 'winfixheight' option is set to have it keep the same height when opening/closing other windows. - *:pta* *:ptag* -:pta[g][!] [tagname] + *:pt* *:ptag* +:pt[ag][!] [tagname] Does ":tag[!] [tagname]" and shows the found tag in a "Preview" window without changing the current buffer or cursor position. If a "Preview" window already exists, it is re-used @@ -978,6 +978,14 @@ CTRL-W g } *CTRL-W_g}* it. Make the new Preview window (if required) N high. If N is not given, 'previewheight' is used. + *:pb* *:pbuffer* +:[N]pb[uffer][!] [+cmd] [N] + Edit buffer [N] from the buffer list in the preview window. + If [N] is not given, the current buffer remains being edited. + See |:buffer-!| for [!]. This will also edit a buffer that is + not in the buffer list, without setting the 'buflisted' flag. + Also see |+cmd|. + *:ped* *:pedit* :ped[it][!] [++opt] [+cmd] {file} Edit {file} in the preview window. The preview window is @@ -985,6 +993,8 @@ CTRL-W g } *CTRL-W_g}* position isn't changed. Useful example: > :pedit +/fputc /usr/include/stdio.h < + Also see |++opt| and |+cmd|. + *:ps* *:psearch* :[range]ps[earch][!] [count] [/]pattern[/] Works like |:ijump| but shows the found match in the preview |