From d2073d2eec41636f44c3edb2a794a0abf84dd444 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 29 Jun 2026 13:10:31 -0400 Subject: [PATCH] refactor: cleanup, docs #40480 --- runtime/doc/api.txt | 3 +- runtime/doc/dev.txt | 15 +++++--- runtime/doc/editing.txt | 50 +++++++++++++-------------- runtime/doc/gui.txt | 23 ++++++------ runtime/doc/index.txt | 2 +- runtime/doc/lua.txt | 2 +- runtime/doc/news.txt | 7 ++-- runtime/doc/options.txt | 29 ++++++++-------- runtime/doc/plugins.txt | 4 +-- runtime/doc/terminal.txt | 6 ++++ runtime/doc/vim_diff.txt | 7 ++-- runtime/doc/vimeval.txt | 2 +- runtime/doc/vimfn.txt | 38 +++++++++++--------- runtime/doc/vvars.txt | 10 +++--- runtime/lua/vim/_core/server.lua | 40 +++++++++------------ runtime/lua/vim/_meta/api.gen.lua | 2 +- runtime/lua/vim/_meta/options.gen.lua | 29 ++++++++-------- runtime/lua/vim/_meta/vimfn.gen.lua | 38 +++++++++++--------- runtime/lua/vim/_meta/vvars.gen.lua | 6 ++-- runtime/lua/vim/fs.lua | 2 +- src/nvim/api/buffer.c | 2 +- src/nvim/eval.lua | 38 +++++++++++--------- src/nvim/ex_docmd.c | 6 ++-- src/nvim/options.lua | 29 ++++++++-------- src/nvim/vvars.lua | 7 ++-- 25 files changed, 211 insertions(+), 186 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index f45f9eb538..0e2ca6db42 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -2606,7 +2606,8 @@ nvim_buf_get_mark({buf}, {name}) *nvim_buf_get_mark()* • |nvim_buf_del_mark()| nvim_buf_get_name({buf}) *nvim_buf_get_name()* - Gets the full file name for the buffer + Gets the full/absolute filepath of the buffer, or the buffer name for + non-file buffers. Attributes: ~ Since: 0.1.0 diff --git a/runtime/doc/dev.txt b/runtime/doc/dev.txt index 115f2bfb01..c56a53e9da 100644 --- a/runtime/doc/dev.txt +++ b/runtime/doc/dev.txt @@ -358,7 +358,7 @@ preference): 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)) +5. `nvim_echo` (consider `opts.silent` for async/visitors) - High-level / application-level messages. End-user invokes these directly. @@ -409,9 +409,16 @@ API PATTERNS *dev-api-patterns* filter(…, opts, fn) -- ❌ NO: filter(…, fn, opts) -- Expose a `config(opts)` function if the module accepts user configuration. - If `opts` is omitted (or `nil`) it returns the current configuration. - - Example: See |vim.diagnostic.config()|. +- If the module or topic wants to support configuration: + - Prefer a new 'option' (or family of related options, or "xxoptions" style + such as 'jumpoptions'). Options get these benefits "for free": + - Completion: `:set a`, `:lua vim.o.a` + - |OptionSet| event + - Scopes: global/buf/win/tab (can start as global, then "graduate" later) + - UI: `:verbose set`, `:options`, etc. + - Alternatively if the editor |options| system absolutey doesn't fit: Expose + a `config(opts)` interface (example: |vim.diagnostic.config()|). If `opts` + is omitted (or `nil`) it returns the current configuration. - "Enable" ("toggle") interface and behavior: - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the "global" enablement of a feature. diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index 2f3e45cf50..d9a26c1614 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -260,34 +260,33 @@ CTRL-^ Edit the alternate file. Mostly the alternate file is See |CTRL-^| above for further details. *gf* *E446* *E447* -[count]gf Edit the file whose name is under or after the cursor. +[count]gf Edit the filename at (or after) cursor. Mnemonic: "goto file". - Uses the 'isfname' option to find out which characters - are supposed to be in a file name. Trailing - punctuation characters ".,:;!" are ignored. Escaped - spaces "\ " are reduced to a single space. - Uses the 'path' option as a list of directory names to - look for the file. See the 'path' option for details - about relative directories and wildcards. - Uses the 'suffixesadd' option to check for file names - with a suffix added. - If the file can't be found, 'includeexpr' is used to - modify the name and another attempt is done. - If a [count] is given, the count'th file that is found - in the 'path' is edited. + + - The 'isfname' option decides what a filename is. + Trailing punctuation characters ".,:;!" are ignored. + Escaped spaces "\ " are reduced to a single space. + - The 'path' option decides where to look for the + file, including relative directories and wildcards. + - The 'suffixesadd' option controls which suffixes + (file extensions) are tried when building potential + filepaths. + - If the search fails, it is retried after applying + 'includeexpr' to the filename. + - If a [count] is given, the count'th file that is + found in the 'path' is edited. + - If the name is a URL ("type://machine/path"), you + need the |netrw| plugin. + - Environment variables are expanded. |expand-env|. + - On unix: "~" is expanded. + This command fails if Vim refuses to |abandon| the current file. - If you want to edit the file in a new window use - |CTRL-W_CTRL-F|. + See |CTRL-W_CTRL-F| to edit the file in a new window. + If you do want to edit a new file, use: > :e -< To make gf always work like that: > - :map gf :e -< If the name is a hypertext link, that looks like - "type://machine/path", you need the |netrw| plugin. - For Unix the '~' character is expanded, like in - "~user/file". Environment variables are expanded too - |expand-env|. +< *v_gf* {Visual}[count]gf Same as "gf", but the highlighted text is used as the @@ -603,9 +602,8 @@ argument is subject to |cmdline-special| expansion, |wildcard| expansion, etc. Instead, to open a filepath literally, use `bufadd(vim.fs.normalize(…))`: >lua local buf = vim.fn.bufadd(vim.fs.normalize(path)) - vim.fn.bufload(buf) -- Trigger BufReadPre/BufReadPost/FileType. - vim.bo[buf].buflisted = true -- Show in ":ls". - vim.api.nvim_win_set_buf(0, buf) -- Show in current window. + -- Set 'buflisted'; trigger BufReadPre/BufReadPost/FileType. + vim.api.nvim_buf_call(buf, vim.cmd.edit) Alternatively, |nvim_cmd()| and |vim.cmd()| accept a structured form whose `args` are tokenized verbatim. But the argument still goes through |:edit|'s diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 35ae45432b..8e6dfc971f 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -77,29 +77,30 @@ Restart Nvim *:restart* *:restart!* :restart[!] [+cmd] [command] - Restarts Nvim. Sets |v:exitreason|. See also |ZR|. - When [!] is included, the session is not restored. + Restarts Nvim. Saves and restores the current session, unless + [!] is given. Sets |v:exitreason|. See also |ZR|. - 1. Stops Nvim using `:qall` (or |+cmd|, if given). - 2. Starts a new Nvim server using the same |v:argv| (except - `-- [file…]` files). Sets |v:startreason| to "restart" on the - new server. - 3. Attaches all UIs to the new Nvim server and runs `[command]` + 1. Saves the current session (unless [!] was given). + 2. Stops Nvim using `:qall` (or |+cmd|, if given). + 3. Starts a new Nvim server using the same |v:argv| (except + `-- [file…]` files), and sets |v:startreason|. + 4. Restores the saved session (unless [!] was given). + 5. Attaches all UIs to the new Nvim server and runs `[command]` on it. Example: discard changes and stop with `:qall!`, then restart: > :restart +qall! -< Example: restart and restore the current session: > +< Example: restart and (manually) restore the session: > :mksession! Session.vim | restart! source Session.vim < Example: restart and update plugins: > :restart packupdate < Note: • Only works if the UI and server are on the same system. - • Windows limitation: when +cmd is executed, |v:servername| + • Windows limitation: during +cmd execution, |v:servername| refers to a temporary address. - • If no UI handles the "restart" event, this command will lead - to a dangling server process. + • If no UI handles the "restart" event, this leaves a dangling + process. ------------------------------------------------------------------------------ Connect UI to a different server diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index 13fa624876..993e6f60a4 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -12,7 +12,7 @@ to look for deleting something, use: "/delete". For an overview of options see |option-list|. For an overview of built-in functions see |functions|. -For a list of Vim variables see |vim-variable|. +For a list of Vim variables see |vvars|. Type |gO| to see the table of contents. diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index cc2b8ffd16..aa9fb67ad6 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -2749,7 +2749,7 @@ vim.fs.normalize({path}, {opts}) *vim.fs.normalize()* On Windows, backslash (\) characters are converted to forward slashes (/). - Examples: >lua + Examples: > [[C:\Users\jdoe]] => "C:/Users/jdoe" "~/src/neovim" => "/home/jdoe/src/neovim" "$XDG_CONFIG_HOME/nvim/init.vim" => "/Users/jdoe/.config/nvim/init.vim" diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 6b5bf77930..34ec454817 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -89,6 +89,7 @@ EDITOR • Only supports one "cmdline level", not "infinite recursion". • Expr-register (|i_CTRL-R_=|, |c_CTRL-R_=|) no longer supports opening cmdwin via |c_CTRL-F|. +• Behavior of |:restart| changed. Use "!" (|:restart!|) to get the old behavior. EVENTS @@ -195,7 +196,8 @@ EDITOR • The |cmdwin-char| is shown via 'statuscolumn'. • |gf| and || support `file://…` URIs. • |:log| opens log files. -• |:restart| now restores the current session while |:restart!| does not. +• |:restart| saves/restores the current session (window layout, buffers, …). + • |:restart!| (with a bang "!") does not save/restore the session. • |ZR| restarts Nvim (|:restart!|). • |:uptime| displays uptime. • |:packupdate| and |:packdel| for managing |vim.pack|. @@ -295,6 +297,7 @@ PERFORMANCE • Internal LSP data is cleared using `table.clear`, which reduces GC and memory reallocation during each data reset. • RPC client avoids string allocations when parsing Content-Length messages. +• LSP: "overscan" semantic_token range requests to avoid flicker. PLUGINS @@ -335,7 +338,7 @@ UI VIMSCRIPT • |v:exitreason| is set before |QuitPre|. -• |v:startreason| differentiates between restart and normal start. +• |v:startreason| indicates whether Nvim started normally or by |:restart|. • |v:starttime| is the process start time (nanoseconds since UNIX epoch). • |v:useractive| indicates user activity. • |serverlist()| with `info=true` returns details for each server (own + peers). diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 08ae00347c..7ab2390823 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -810,11 +810,13 @@ A jump table for the options with a short description can be found at |Q_op|. 'autoread' 'ar' boolean (default on) global or local to buffer |global-local| When a file was changed outside of Nvim, automatically read it again. - Skipped if the file was deleted, so you have the text from before it - was deleted. If the file appears again then it is read. |timestamp| + Skipped if the file was deleted (so you still have the last-available + text). If the file appears again, then it is read; you can |undo| to + see the previous contents. |timestamp| - This is partially driven by OS filewatcher events |uv_fs_event_t|, so - even the current buffer may be updated. + This is driven (partially) by OS filewatcher events |uv_fs_event_t|, + so buffers are updated immediately (instead of only on focus-change or + shell-commands). If this option has a local value, use this command to switch back to using the global value: >vim @@ -855,13 +857,13 @@ A jump table for the options with a short description can be found at |Q_op|. that background type. The |TUI| or other UI sets this on startup if it can detect the background color, and re-detects it whenever a UI attaches later, unless 'background' was set explicitly. When multiple - terminal UIs are attached they share one value, taken from whichever - terminal reports its background last (which may not be the most - recently attached one, since it depends on response speed). + UIs are attached they share one value, decided by "last wins" (may + not be the most recently-attached UI, since it depends on response + speed). This option does NOT change the background color, it tells Nvim what - the "inherited" (terminal/GUI) background looks like. - See |:hi-normal| if you want to set the background color explicitly. + the "inherited" (terminal/GUI) background looks like. See |:hi-normal| + to set the background color explicitly. *g:colors_name* When a color scheme is loaded (the "g:colors_name" variable is set) changing 'background' will cause the color scheme to be reloaded. If @@ -869,14 +871,13 @@ A jump table for the options with a short description can be found at |Q_op|. However, if the color scheme sets 'background' itself the effect may be undone. First delete the "g:colors_name" variable when needed. - Normally this option would be set in the vimrc file. Possibly - depending on the terminal name. Example: >vim + Historically, this option was set in the vimrc file. Example: >vim if $TERM ==# "xterm" set background=dark endif -< When this option is changed, the default settings for the highlight groups - will change. To use other settings, place ":highlight" commands AFTER - the setting of the 'background' option. +< When this option is changed, the defaults for highlight groups + will change. To override those defaults, place ":highlight" commands + AFTER setting the 'background' option. *'backspace'* *'bs'* 'backspace' 'bs' string (default "indent,eol,start") diff --git a/runtime/doc/plugins.txt b/runtime/doc/plugins.txt index 028c7b64e0..a9597b6a88 100644 --- a/runtime/doc/plugins.txt +++ b/runtime/doc/plugins.txt @@ -19,7 +19,7 @@ Standard plugins *standard-plugin-list* Help-link Loaded Short description ~ |dir| Yes Directory listing for |:edit| -|difftool| No Compares two directories or files side-by-side +|difftool| No Compares directories (and files) side-by-side |editorconfig| Yes Detect and interpret editorconfig |ft-shada| Yes Allows editing binary |shada| files |man.lua| Yes View manpages in Nvim @@ -69,7 +69,7 @@ Directory buffers follow the global 'hidden' option by default. To delete them after use: >vim autocmd FileType directory setlocal bufhidden=delete < -Use "wipe" to discard all buffer state; see |'bufhidden'|. +Use "wipe" to discard all buffer state; see 'bufhidden'. *g:loaded_nvim_dir_plugin* To disable this plugin, set this in your config before startup: >lua diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt index 46aae00ad3..ca32fff420 100644 --- a/runtime/doc/terminal.txt +++ b/runtime/doc/terminal.txt @@ -265,6 +265,12 @@ Example: >vim Use |jobwait()| to check if the terminal job has finished: >vim let running = jobwait([&channel], 0)[0] == -1 < + +============================================================================== +Concepts *terminal-concepts* + +TODO + ============================================================================== :Termdebug plugin *terminal-debug* *terminal-debugger* *package-termdebug* *termdebug* diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 3e130c493a..f92499d080 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -425,9 +425,10 @@ Options: - 'inccommand' shows interactive results for |:substitute|-like commands and |:command-preview| commands - 'jumpoptions' - - "view" tries to restore |mark-view| when moving through the jumplist. + - "view" tries to restore |mark-view| when moving through the |jumplist|, + |changelist|, |alternate-file|, and |mark-motions|. - "clean" removes unloaded buffers from the jumplist. -- the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|. +- 'langmap' supports multibyte chars. - 'laststatus' global statusline support - 'mousemodel' cannot be set to empty. - 'mousescroll' amount to scroll by when scrolling with a mouse @@ -712,7 +713,6 @@ Missing features *nvim-missing* These legacy Vim features are not yet implemented: - *:gui* -- *:gvim* - *'browsedir'* *'bsdir'* - *'completepopup'* - *'guioptions'* *'go'* @@ -743,6 +743,7 @@ Aliases: Commands: - :behave - :fixdel +- *:gvim* - *hardcopy* `:hardcopy` was removed. Instead, use `:TOhtml` and print the resulting HTML using a web browser or other HTML viewer. - :helpfind diff --git a/runtime/doc/vimeval.txt b/runtime/doc/vimeval.txt index d388b601f0..9d234b5682 100644 --- a/runtime/doc/vimeval.txt +++ b/runtime/doc/vimeval.txt @@ -1803,7 +1803,7 @@ Note that this means that filetype plugins don't get a different set of script variables for each buffer. Use local buffer variables instead |b:var|. -PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:* +PREDEFINED VIM VARIABLES *vim-variable* *E963* The alphabetic list of all builtin variables and details are in a separate diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index 1922334943..dd86808b83 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -593,7 +593,7 @@ browsedir({title}, {initdir}) *browsedir()* (`0|1`) bufadd({name}) *bufadd()* - Adds buffer {name} to the buffer list literally: no special + Adds buffer {name} to the |buffer-list| literally: no special chars or expansion are applied (including "~"). Returns the new (or existing matching) buffer number, or 0 on error. @@ -601,9 +601,9 @@ bufadd({name}) *bufadd()* {name} is an empty string, a new buffer is always created. Example (Lua): >lua - local b = vim.fn.bufadd(vim.fs.normalize('someName')) - vim.bo[b].buflisted = true - vim.fn.bufload(b) + local buf = vim.fn.bufadd(vim.fs.normalize('someName')) + -- Set 'buflisted'; trigger BufReadPre/BufReadPost/FileType. + vim.api.nvim_buf_call(buf, vim.cmd.edit) < Parameters: ~ @@ -5800,7 +5800,11 @@ jobstart({cmd} [, {opts}]) *jobstart()* pty: (boolean) Connect the job to a new pseudo terminal, and its streams to the master file descriptor. `on_stdout` receives all output, - `on_stderr` is ignored. |terminal-start| + `on_stderr` is ignored. Note: if the child writes + a query (DA1, OSC, …), it may hang or timeout waiting + for a response! To avoid that, `on_stdout` should + reply via |nvim_chan_send()| on the child's stdin. + See |terminal-start| |terminal-concepts| rpc: (boolean) Use |msgpack-rpc| to communicate with the job over stdio. Then `on_stdout` is ignored, but `on_stderr` can still be used. @@ -5811,11 +5815,12 @@ 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. + term: (boolean) Spawns {cmd} in a new pseudo-terminal + session connected to the current (unmodified) buffer. + Implies "pty". Defaults "height" and "width" to the + current window dimensions. Defaults $TERM to + "xterm-256color". + width: (number) Width of the `pty` pseudo-terminal. {opts} is passed as |self| dictionary to the callback; the caller may set other keys to pass application-specific data. @@ -9274,14 +9279,13 @@ setbufvar({buf}, {varname}, {val}) *setbufvar()* Lua: Prefer |nvim_buf_set_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_set_option_value()|. - Set option or local variable {varname} in buffer {buf} to - {val}. - This also works for a global or local window option, but it - doesn't work for a global or local window variable. - For a local window option the global value is unchanged. + Set option or local variable {varname} (string, without "b:") + in buffer {buf} to {val}. Also works for a global or + window-local option (not variable). When targeting + a window-local option, the global option is unchanged. + For the use of {buf}, see |bufname()| above. - The {varname} argument is a string. - Note that the variable name without "b:" must be used. + Examples: >vim call setbufvar(1, "&mod", 1) call setbufvar("todo", "myvar", "foobar") diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt index dc29d0059c..da5323523b 100644 --- a/runtime/doc/vvars.txt +++ b/runtime/doc/vvars.txt @@ -4,7 +4,7 @@ NVIM REFERENCE MANUAL -Predefined variables *vvars* +Predefined variables *vvars* *v:var* *v:* 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. @@ -636,9 +636,9 @@ v:stacktrace *v:startreason* *startreason-variable* v:startreason The reason Nvim started. Possible values: - - "normal" normal startup. - - "restart" started by |:restart|. - - "restart!" started by |:restart!| or |ZR|. + - "normal" Normal startup, yearning for life, etc. + - "restart" Started by |:restart|. + - "restart!" Started by |:restart!| or |ZR|. Read-only. @@ -763,7 +763,7 @@ v:true operator) and to one when used as a Number (e.g. in |expr5| or |expr7| when used with numeric operators). Read-only. - *v:useractive* *useractive-variable* + *v:useractive* *useractive-variable* *user-idle* v:useractive Timestamp (nanoseconds since UNIX epoch) indicating the most recent user activity, i.e. when a key is received from a UI diff --git a/runtime/lua/vim/_core/server.lua b/runtime/lua/vim/_core/server.lua index 2127ec3c3d..cabbfccb24 100644 --- a/runtime/lua/vim/_core/server.lua +++ b/runtime/lua/vim/_core/server.lua @@ -1,6 +1,4 @@ -local fs = vim.fs -local uv = vim.uv --- For "--listen" and related functionality. +-- For "--listen", ":restart", and related remote/server functionality. local M = {} @@ -156,34 +154,32 @@ function M.rebind_after_restart(canonical_addr, expected_uis) end) end --- Called by ex_restart(). Saves the current session and calls back to --- ex_restart() with the necessary arguments to restore the session. +-- Called by ex_restart(). Saves the current session and calls ex_restart() (again) with the +-- updated arguments. +-- -- TODO: https://github.com/neovim/neovim/issues/34204 +-- --- @param eap vim._core.ExCmdArgs --- @param extra { quit_cmd: string } function M.ex_session_restart(eap, extra) - -- Commands to run after restart - local after_cmd = eap.args + local after_cmd = eap.args -- User-provided [command]. assert(not after_cmd:find(']==]')) - -- Use custom quit command if provided - local quit_cmd = 'qall' - if extra.quit_cmd ~= '' then - quit_cmd = extra.quit_cmd - end + -- Use custom +cmd if given. + local quit_cmd = extra.quit_cmd == '' and 'qall' or extra.quit_cmd - -- Preserve the value of v:this_session + -- Preserve v:this_session in the restarted Nvim. local this_session = vim.v.this_session assert(not this_session:find(']==]')) - -- Get temp file to write session to - local temp_dir = fs.abspath(fs.dirname(fs.dirname(vim.fn.tempname()))) - assert(not temp_dir:find(']==]')) - local fd, session = uv.fs_mkstemp(fs.joinpath(temp_dir, 'restart_session_XXXXXX')) + -- Nvim temp "root dir": "/tmp/…/nvim./" + local tmproot = vim.fs.abspath(vim.fs.dirname(vim.fs.dirname(vim.fn.tempname()))) + assert(not tmproot:find(']==]')) + local fd, session = vim.uv.fs_mkstemp(vim.fs.joinpath(tmproot, 'restart_session_XXXXXX')) if not fd then error('Failed to get temporary filename for restart session') end - uv.fs_close(fd) + vim.uv.fs_close(fd) -- Write session local session_arg = vim.fn.fnameescape(session) @@ -195,22 +191,20 @@ function M.ex_session_restart(eap, extra) table.insert(after_list, ('vim.cmd("source %s")'):format(session_arg)) table.insert(after_list, ('pcall(vim.fs.rm, [==[%s]==])'):format(session)) table.insert(after_list, ('vim.v.this_session = [==[%s]==]'):format(this_session)) - -- User provided command if after_cmd ~= '' then table.insert(after_list, ('vim.cmd([==[%s]==])'):format(after_cmd)) end - -- Concatenate everything together local after = 'lua ' .. table.concat(after_list, ';') -- Restart Neovim and run our Lua commands local success, msg = pcall(function() - -- "+:::" special argument tells the C handler that this is actually a non-bang restart - -- That way, v:startreason can be set correctly + -- "+:::" dummy prefix tells the C handler that this is actually a non-bang restart. + -- Then v:startreason (if any) can be preserved. vim.cmd.restart { '+:::', quit_cmd, after, bang = true } end) if not success then - fs.rm(session, { force = true }) + vim.fs.rm(session, { force = true }) error(msg) end end diff --git a/runtime/lua/vim/_meta/api.gen.lua b/runtime/lua/vim/_meta/api.gen.lua index fcfe124b26..06d231671e 100644 --- a/runtime/lua/vim/_meta/api.gen.lua +++ b/runtime/lua/vim/_meta/api.gen.lua @@ -509,7 +509,7 @@ function vim.api.nvim_buf_get_lines(buf, start, end_, strict_indexing) end --- uppercase/file mark set in another buffer. function vim.api.nvim_buf_get_mark(buf, name) end ---- Gets the full file name for the buffer +--- Gets the full/absolute filepath of the buffer, or the buffer name for non-file buffers. --- --- @param buf integer Buffer id, or 0 for current buffer --- @return string # Buffer name diff --git a/runtime/lua/vim/_meta/options.gen.lua b/runtime/lua/vim/_meta/options.gen.lua index 696bab9b12..a647755522 100644 --- a/runtime/lua/vim/_meta/options.gen.lua +++ b/runtime/lua/vim/_meta/options.gen.lua @@ -169,11 +169,13 @@ vim.bo.autoindent = vim.o.autoindent vim.bo.ai = vim.bo.autoindent --- When a file was changed outside of Nvim, automatically read it again. ---- Skipped if the file was deleted, so you have the text from before it ---- was deleted. If the file appears again then it is read. `timestamp` +--- Skipped if the file was deleted (so you still have the last-available +--- text). If the file appears again, then it is read; you can `undo` to +--- see the previous contents. `timestamp` --- ---- This is partially driven by OS filewatcher events `uv_fs_event_t`, so ---- even the current buffer may be updated. +--- This is driven (partially) by OS filewatcher events `uv_fs_event_t`, +--- so buffers are updated immediately (instead of only on focus-change or +--- shell-commands). --- --- If this option has a local value, use this command to switch back to --- using the global value: @@ -228,13 +230,13 @@ vim.go.awa = vim.go.autowriteall --- that background type. The `TUI` or other UI sets this on startup --- if it can detect the background color, and re-detects it whenever a UI --- attaches later, unless 'background' was set explicitly. When multiple ---- terminal UIs are attached they share one value, taken from whichever ---- terminal reports its background last (which may not be the most ---- recently attached one, since it depends on response speed). +--- UIs are attached they share one value, decided by "last wins" (may +--- not be the most recently-attached UI, since it depends on response +--- speed). --- --- This option does NOT change the background color, it tells Nvim what ---- the "inherited" (terminal/GUI) background looks like. ---- See `:hi-normal` if you want to set the background color explicitly. +--- the "inherited" (terminal/GUI) background looks like. See `:hi-normal` +--- to set the background color explicitly. --- *g:colors_name* --- When a color scheme is loaded (the "g:colors_name" variable is set) --- changing 'background' will cause the color scheme to be reloaded. If @@ -242,17 +244,16 @@ vim.go.awa = vim.go.autowriteall --- However, if the color scheme sets 'background' itself the effect may --- be undone. First delete the "g:colors_name" variable when needed. --- ---- Normally this option would be set in the vimrc file. Possibly ---- depending on the terminal name. Example: +--- Historically, this option was set in the vimrc file. Example: --- --- ```vim --- if $TERM ==# "xterm" --- set background=dark --- endif --- ``` ---- When this option is changed, the default settings for the highlight groups ---- will change. To use other settings, place ":highlight" commands AFTER ---- the setting of the 'background' option. +--- When this option is changed, the defaults for highlight groups +--- will change. To override those defaults, place ":highlight" commands +--- AFTER setting the 'background' option. --- --- @type 'light'|'dark' vim.o.background = "dark" diff --git a/runtime/lua/vim/_meta/vimfn.gen.lua b/runtime/lua/vim/_meta/vimfn.gen.lua index 9d08c79764..96cd2af4d5 100644 --- a/runtime/lua/vim/_meta/vimfn.gen.lua +++ b/runtime/lua/vim/_meta/vimfn.gen.lua @@ -496,7 +496,7 @@ function vim.fn.browse(save, title, initdir, default) end --- @return 0|1 function vim.fn.browsedir(title, initdir) end ---- Adds buffer {name} to the buffer list literally: no special +--- Adds buffer {name} to the |buffer-list| literally: no special --- chars or expansion are applied (including "~"). Returns the --- new (or existing matching) buffer number, or 0 on error. --- @@ -504,9 +504,9 @@ function vim.fn.browsedir(title, initdir) end --- {name} is an empty string, a new buffer is always created. --- --- Example (Lua): >lua ---- local b = vim.fn.bufadd(vim.fs.normalize('someName')) ---- vim.bo[b].buflisted = true ---- vim.fn.bufload(b) +--- local buf = vim.fn.bufadd(vim.fs.normalize('someName')) +--- -- Set 'buflisted'; trigger BufReadPre/BufReadPost/FileType. +--- vim.api.nvim_buf_call(buf, vim.cmd.edit) --- < --- --- @param name string @@ -5247,7 +5247,11 @@ function vim.fn.jobsend(...) end --- pty: (boolean) Connect the job to a new pseudo --- terminal, and its streams to the master file --- descriptor. `on_stdout` receives all output, ---- `on_stderr` is ignored. |terminal-start| +--- `on_stderr` is ignored. Note: if the child writes +--- a query (DA1, OSC, …), it may hang or timeout waiting +--- for a response! To avoid that, `on_stdout` should +--- reply via |nvim_chan_send()| on the child's stdin. +--- See |terminal-start| |terminal-concepts| --- rpc: (boolean) Use |msgpack-rpc| to communicate with --- the job over stdio. Then `on_stdout` is ignored, --- but `on_stderr` can still be used. @@ -5258,11 +5262,12 @@ function vim.fn.jobsend(...) end --- 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. +--- term: (boolean) Spawns {cmd} in a new pseudo-terminal +--- session connected to the current (unmodified) buffer. +--- Implies "pty". Defaults "height" and "width" to the +--- current window dimensions. Defaults $TERM to +--- "xterm-256color". +--- width: (number) Width of the `pty` pseudo-terminal. --- --- {opts} is passed as |self| dictionary to the callback; the --- caller may set other keys to pass application-specific data. @@ -8412,14 +8417,13 @@ function vim.fn.setbufline(buf, lnum, text) end --- Lua: Prefer |nvim_buf_set_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_set_option_value()|. --- ---- Set option or local variable {varname} in buffer {buf} to ---- {val}. ---- This also works for a global or local window option, but it ---- doesn't work for a global or local window variable. ---- For a local window option the global value is unchanged. +--- Set option or local variable {varname} (string, without "b:") +--- in buffer {buf} to {val}. Also works for a global or +--- window-local option (not variable). When targeting +--- a window-local option, the global option is unchanged. +--- --- For the use of {buf}, see |bufname()| above. ---- The {varname} argument is a string. ---- Note that the variable name without "b:" must be used. +--- --- Examples: >vim --- call setbufvar(1, "&mod", 1) --- call setbufvar("todo", "myvar", "foobar") diff --git a/runtime/lua/vim/_meta/vvars.gen.lua b/runtime/lua/vim/_meta/vvars.gen.lua index 141fc70426..3bc819b5a1 100644 --- a/runtime/lua/vim/_meta/vvars.gen.lua +++ b/runtime/lua/vim/_meta/vvars.gen.lua @@ -668,9 +668,9 @@ vim.v.shell_error = ... vim.v.stacktrace = ... --- The reason Nvim started. Possible values: ---- - "normal" normal startup. ---- - "restart" started by `:restart`. ---- - "restart!" started by `:restart!` or `ZR`. +--- - "normal" Normal startup, yearning for life, etc. +--- - "restart" Started by `:restart`. +--- - "restart!" Started by `:restart!` or `ZR`. --- --- Read-only. --- @type string diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index 586ded37ba..7e85e80056 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -640,7 +640,7 @@ end --- On Windows, backslash (\) characters are converted to forward slashes (/). --- --- Examples: ---- ```lua +--- ``` --- [[C:\Users\jdoe]] => "C:/Users/jdoe" --- "~/src/neovim" => "/home/jdoe/src/neovim" --- "$XDG_CONFIG_HOME/nvim/init.vim" => "/Users/jdoe/.config/nvim/init.vim" diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 85c5f75540..cc0c06b52d 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -938,7 +938,7 @@ void nvim_buf_del_var(Buffer buf, String name, Error *err) dict_set_var(b->b_vars, name, NIL, true, false, NULL, err); } -/// Gets the full file name for the buffer +/// Gets the full/absolute filepath of the buffer, or the buffer name for non-file buffers. /// /// @param buf Buffer id, or 0 for current buffer /// @param[out] err Error details, if any diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index f6b49db15a..431bc273dd 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -671,7 +671,7 @@ M.funcs = { args = 1, base = 1, desc = [=[ - Adds buffer {name} to the buffer list literally: no special + Adds buffer {name} to the |buffer-list| literally: no special chars or expansion are applied (including "~"). Returns the new (or existing matching) buffer number, or 0 on error. @@ -679,9 +679,9 @@ M.funcs = { {name} is an empty string, a new buffer is always created. Example (Lua): >lua - local b = vim.fn.bufadd(vim.fs.normalize('someName')) - vim.bo[b].buflisted = true - vim.fn.bufload(b) + local buf = vim.fn.bufadd(vim.fs.normalize('someName')) + -- Set 'buflisted'; trigger BufReadPre/BufReadPost/FileType. + vim.api.nvim_buf_call(buf, vim.cmd.edit) < ]=], name = 'bufadd', @@ -6378,7 +6378,11 @@ M.funcs = { pty: (boolean) Connect the job to a new pseudo terminal, and its streams to the master file descriptor. `on_stdout` receives all output, - `on_stderr` is ignored. |terminal-start| + `on_stderr` is ignored. Note: if the child writes + a query (DA1, OSC, …), it may hang or timeout waiting + for a response! To avoid that, `on_stdout` should + reply via |nvim_chan_send()| on the child's stdin. + See |terminal-start| |terminal-concepts| rpc: (boolean) Use |msgpack-rpc| to communicate with the job over stdio. Then `on_stdout` is ignored, but `on_stderr` can still be used. @@ -6389,11 +6393,12 @@ M.funcs = { 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. + term: (boolean) Spawns {cmd} in a new pseudo-terminal + session connected to the current (unmodified) buffer. + Implies "pty". Defaults "height" and "width" to the + current window dimensions. Defaults $TERM to + "xterm-256color". + width: (number) Width of the `pty` pseudo-terminal. {opts} is passed as |self| dictionary to the callback; the caller may set other keys to pass application-specific data. @@ -10106,14 +10111,13 @@ M.funcs = { args = 3, base = 3, desc = [=[ - Set option or local variable {varname} in buffer {buf} to - {val}. - This also works for a global or local window option, but it - doesn't work for a global or local window variable. - For a local window option the global value is unchanged. + Set option or local variable {varname} (string, without "b:") + in buffer {buf} to {val}. Also works for a global or + window-local option (not variable). When targeting + a window-local option, the global option is unchanged. + For the use of {buf}, see |bufname()| above. - The {varname} argument is a string. - Note that the variable name without "b:" must be used. + Examples: >vim call setbufvar(1, "&mod", 1) call setbufvar("todo", "myvar", "foobar") diff --git a/src/nvim/ex_docmd.c b/src/nvim/ex_docmd.c index 74a87652ff..c0a98c96cc 100644 --- a/src/nvim/ex_docmd.c +++ b/src/nvim/ex_docmd.c @@ -4970,8 +4970,7 @@ static void ex_quitall(exarg_T *eap) static void ex_restart(exarg_T *eap) { if (!eap->forceit) { - // Pass +cmd via the `extra` slot of nlua_call_excmd - dict_T *extra_d = tv_dict_alloc(); + dict_T *extra_d = tv_dict_alloc(); // Pass +cmd in the `extra` param of nlua_call_excmd. tv_dict_add_str(extra_d, S_LEN("quit_cmd"), eap->do_ecmd_cmd ? eap->do_ecmd_cmd : ""); typval_T extra_tv = { .v_type = VAR_DICT, .vval.v_dict = extra_d }; nlua_call_excmd("vim._core.server", "ex_session_restart", eap, &cmdmod, &extra_tv); @@ -4983,10 +4982,9 @@ static void ex_restart(exarg_T *eap) char *quit_cmd = (eap->do_ecmd_cmd) ? eap->do_ecmd_cmd : "qall"; char *after_cmd = eap->arg; - // "+:::" is how ex_session_restart() signals that it (recursively) called into :restart. + // XXX: "+:::" is how ex_session_restart() signals that it (recursively) called :restart. if (strequal(quit_cmd, ":::")) { startreason = "restart"; - // Set quit_cmd and after_cmd from args if (eap->argc > 1) { eap->args[1][eap->arglens[1]] = NUL; quit_cmd = eap->args[1]; diff --git a/src/nvim/options.lua b/src/nvim/options.lua index d15c980089..20c000479c 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -302,11 +302,13 @@ local options = { defaults = true, desc = [=[ When a file was changed outside of Nvim, automatically read it again. - Skipped if the file was deleted, so you have the text from before it - was deleted. If the file appears again then it is read. |timestamp| + Skipped if the file was deleted (so you still have the last-available + text). If the file appears again, then it is read; you can |undo| to + see the previous contents. |timestamp| - This is partially driven by OS filewatcher events |uv_fs_event_t|, so - even the current buffer may be updated. + This is driven (partially) by OS filewatcher events |uv_fs_event_t|, + so buffers are updated immediately (instead of only on focus-change or + shell-commands). If this option has a local value, use this command to switch back to using the global value: >vim @@ -370,13 +372,13 @@ local options = { that background type. The |TUI| or other UI sets this on startup if it can detect the background color, and re-detects it whenever a UI attaches later, unless 'background' was set explicitly. When multiple - terminal UIs are attached they share one value, taken from whichever - terminal reports its background last (which may not be the most - recently attached one, since it depends on response speed). + UIs are attached they share one value, decided by "last wins" (may + not be the most recently-attached UI, since it depends on response + speed). This option does NOT change the background color, it tells Nvim what - the "inherited" (terminal/GUI) background looks like. - See |:hi-normal| if you want to set the background color explicitly. + the "inherited" (terminal/GUI) background looks like. See |:hi-normal| + to set the background color explicitly. *g:colors_name* When a color scheme is loaded (the "g:colors_name" variable is set) changing 'background' will cause the color scheme to be reloaded. If @@ -384,14 +386,13 @@ local options = { However, if the color scheme sets 'background' itself the effect may be undone. First delete the "g:colors_name" variable when needed. - Normally this option would be set in the vimrc file. Possibly - depending on the terminal name. Example: >vim + Historically, this option was set in the vimrc file. Example: >vim if $TERM ==# "xterm" set background=dark endif - < When this option is changed, the default settings for the highlight groups - will change. To use other settings, place ":highlight" commands AFTER - the setting of the 'background' option. + < When this option is changed, the defaults for highlight groups + will change. To override those defaults, place ":highlight" commands + AFTER setting the 'background' option. ]=], full_name = 'background', scope = { 'global' }, diff --git a/src/nvim/vvars.lua b/src/nvim/vvars.lua index 58408c485e..0cca5124e3 100644 --- a/src/nvim/vvars.lua +++ b/src/nvim/vvars.lua @@ -449,6 +449,7 @@ M.vars = { }, useractive = { type = 'integer', + tags = { 'user-idle' }, desc = [=[ Timestamp (nanoseconds since UNIX epoch) indicating the most recent user activity, i.e. when a key is received from a UI @@ -780,9 +781,9 @@ M.vars = { type = 'string', desc = [=[ The reason Nvim started. Possible values: - - "normal" normal startup. - - "restart" started by |:restart|. - - "restart!" started by |:restart!| or |ZR|. + - "normal" Normal startup, yearning for life, etc. + - "restart" Started by |:restart|. + - "restart!" Started by |:restart!| or |ZR|. Read-only. ]=],