mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-05 19:08:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: misc #32959

Browse Source
This commit is contained in:
Justin M. Keyes
2025-03-18 06:18:37 -07:00
committed by GitHub
parent 29a47b39cc
commit 7333c39e6c
16 changed files with 83 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
runtime/doc/api.txt
View File

@@ -3716,7 +3716,7 @@ nvim_create_augroup({name}, {opts}) *nvim_create_augroup()*
Create or get an autocommand group |autocmd-groups|.
To get an existing group id, do: >lua
local id = vim.api.nvim_create_augroup("MyGroup", {
local id = vim.api.nvim_create_augroup('my.lsp.config', {
clear = false
})
<
@@ -3742,8 +3742,8 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()*
string).
Example using Lua callback: >lua
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
pattern = {'*.c', '*.h'},
callback = function(ev)
print(string.format('event fired: %s', vim.inspect(ev)))
end
@@ -3751,15 +3751,15 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()*
<
Example using an Ex command as the handler: >lua
vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
pattern = {"*.c", "*.h"},
vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
pattern = {'*.c', '*.h'},
command = "echo 'Entering a C or C++ file'",
})
<
Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|),
thus names like "$HOME" and "~" must be expanded explicitly: >lua
pattern = vim.fn.expand("~") .. "/some/path/*.py"
pattern = vim.fn.expand('~') .. '/some/path/*.py'
<
Attributes: ~
@@ -3881,14 +3881,14 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()*
These examples will get autocommands matching ALL the given criteria: >lua
-- Matches all criteria
autocommands = vim.api.nvim_get_autocmds({
group = "MyGroup",
event = {"BufEnter", "BufWinEnter"},
pattern = {"*.c", "*.h"}
group = 'MyGroup',
event = {'BufEnter', 'BufWinEnter'},
pattern = {'*.c', '*.h'}
})
-- All commands from one group
autocommands = vim.api.nvim_get_autocmds({
group = "MyGroup",
group = 'MyGroup',
})
<

4
runtime/doc/deprecated.txt
View File

@@ -178,8 +178,8 @@ ENVIRONMENT VARIABLES
• 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
• Unset at startup (after |v:servername| is initialized). Can be explicitly
provided to |terminal| and |jobstart()| by the "env" option. Example: >vim
call jobstart(['foo'], { 'env': { 'NVIM_LISTEN_ADDRESS': v:servername } })
<

13
runtime/doc/insert.txt
View File

@@ -1092,19 +1092,20 @@ CTRL-X CTRL-Z Stop completion without changing the text.
AUTO-COMPLETION *compl-autocomplete*
To get basic "autocompletion" without installing a plugin, try this script: >lua
To get LSP-driven auto-completion, see |lsp-completion|. To get basic
auto-completion without installing plugins or LSP, try this: >lua
local triggers = {"."}
vim.api.nvim_create_autocmd("InsertCharPre", {
local triggers = {'.'}
vim.api.nvim_create_autocmd('InsertCharPre', {
buffer = vim.api.nvim_get_current_buf(),
callback = function()
if vim.fn.pumvisible() == 1 or vim.fn.state("m") == "m" then
if vim.fn.pumvisible() == 1 or vim.fn.state('m') == 'm' then
return
end
local char = vim.v.char
if vim.list_contains(triggers, char) then
local key = vim.keycode("<C-x><C-n>")
vim.api.nvim_feedkeys(key, "m", false)
local key = vim.keycode('<C-x><C-n>')
vim.api.nvim_feedkeys(key, 'm', false)
end
end
})

22
runtime/doc/lsp.txt
View File

@@ -185,11 +185,14 @@ Example: given the following configs... >lua
To use LSP features beyond those provided by Nvim (see |lsp-buf|), you can set
keymaps and options on |Client:on_attach()| or |LspAttach|. Not all language
servers provide the same capabilities; check `supports_method()` in your
LspAttach handler. Example: >lua
LspAttach handler.
*lsp-lint* *lsp-format*
Example: Enable auto-completion and auto-formatting ("linting"): >lua
vim.api.nvim_create_autocmd('LspAttach', {
group = vim.api.nvim_create_augroup('my.lsp', {}),
callback = function(args)
local client = vim.lsp.get_client_by_id(args.data.client_id)
local client = assert(vim.lsp.get_client_by_id(args.data.client_id))
if client:supports_method('textDocument/implementation') then
-- Create a keymap for vim.lsp.buf.implementation ...
end
@@ -199,12 +202,15 @@ LspAttach handler. Example: >lua
vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true})
end
-- Format the current buffer on save.
if client:supports_method('textDocument/formatting') then
-- Auto-format ("lint") on save.
-- Usually not needed if server supports "textDocument/willSaveWaitUntil".
if not client:supports_method('textDocument/willSaveWaitUntil')
and client:supports_method('textDocument/formatting') then
vim.api.nvim_create_autocmd('BufWritePre', {
group = vim.api.nvim_create_augroup('my.lsp', {clear=false}),
buffer = args.buf,
callback = function()
vim.lsp.buf.format({bufnr = args.buf, id = client.id})
vim.lsp.buf.format({ bufnr = args.buf, id = client.id, timeout_ms = 1000 })
end,
})
end
@@ -238,21 +244,19 @@ FAQ *lsp-faq*
" (async = false is the default for format)
autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false })
<
*lsp-vs-treesitter*
*lsp-vs-treesitter*
- Q: How do LSP and Treesitter compare?
- A: LSP requires a client and language server. The language server uses
semantic analysis to understand code at a project level. This provides
language servers with the ability to rename across files, find
definitions in external libraries and more.
Treesitter is a language parsing library that provides excellent tools
|treesitter| is a language parsing library that provides excellent tools
for incrementally parsing text and handling errors. This makes it a great
fit for editors to understand the contents of the current file for things
like syntax highlighting, simple goto-definitions, scope analysis and
more.
LSP and Treesitter are both great tools for editing and inspecting code.
================================================================================
LSP API *lsp-api*

10
runtime/doc/terminal.txt
View File

@@ -185,13 +185,12 @@ clipboard.
OSC 52 sequences sent from the :terminal buffer do not emit a |TermRequest|
event. The event is handled directly by Nvim and is not forwarded to plugins.
OSC 133: shell integration *terminal-osc133*
OSC 133: shell integration *terminal-osc133* *shell-prompt*
Shells can emit semantic escape sequences (OSC 133) to mark where each prompt
starts and ends. The start of a prompt is marked by sequence `OSC 133 ; A ST`,
and the end by `OSC 133 ; B ST`.
*shell-prompt-config*
You can configure your shell "rc" (e.g. ~/.bashrc) to emit OSC 133 sequences,
or your terminal may attempt to do it for you (assuming your shell config
doesn't interfere).
@@ -214,6 +213,9 @@ emits OSC 133 as described above.
To annotate each terminal prompt with a sign, call |nvim_buf_set_extmark()|
from a |TermRequest| handler: >lua
vim.api.nvim_create_autocmd('TermOpen', {
command = 'setlocal signcolumn=auto',
})
local ns = vim.api.nvim_create_namespace('my.terminal.prompt')
vim.api.nvim_create_autocmd('TermRequest', {
callback = function(args)
@@ -226,10 +228,6 @@ from a |TermRequest| handler: >lua
end
end,
})
-- Enable signcolumn in terminal buffers.
vim.api.nvim_create_autocmd('TermOpen', {
command = 'setlocal signcolumn=auto',
})
<
==============================================================================
Status Variables *terminal-status*

5
runtime/doc/vvars.txt
View File

@@ -563,8 +563,9 @@ v:servername
Read-only.
*$NVIM*
$NVIM is set by |terminal| and |jobstart()|, and is thus
a hint that the current environment is a subprocess of Nvim.
$NVIM is set to v:servername by |terminal| and |jobstart()|,
and is thus a hint that the current environment is a child
(direct subprocess) of Nvim.
Example: a child Nvim process can detect and make requests to
its parent Nvim: >lua

2
runtime/lua/vim/_editor.lua
View File

@@ -8,7 +8,7 @@
-- - "opt-in": runtime/pack/dist/opt/
-- 2. runtime/lua/vim/ (the runtime): Lazy-loaded modules. Examples: `inspect`, `lpeg`.
-- 3. runtime/lua/vim/shared.lua: pure Lua functions which always are available. Used in the test
-- runner, as well as worker threads and processes launched from Nvim.
-- runner, and worker threads/processes launched from Nvim.
-- 4. runtime/lua/vim/_editor.lua: Eager-loaded code which directly interacts with the Nvim
-- editor state. Only available in the main thread.
--

20
runtime/lua/vim/_meta/api.lua generated
View File

@@ -885,7 +885,7 @@ function vim.api.nvim_command_output(command) end
--- To get an existing group id, do:
---
--- ```lua
--- local id = vim.api.nvim_create_augroup("MyGroup", {
--- local id = vim.api.nvim_create_augroup('my.lsp.config', {
--- clear = false
--- })
--- ```
@@ -904,8 +904,8 @@ function vim.api.nvim_create_augroup(name, opts) end
--- Example using Lua callback:
---
--- ```lua
--- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
--- pattern = {"*.c", "*.h"},
--- vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
--- pattern = {'*.c', '*.h'},
--- callback = function(ev)
--- print(string.format('event fired: %s', vim.inspect(ev)))
--- end
@@ -915,8 +915,8 @@ function vim.api.nvim_create_augroup(name, opts) end
--- Example using an Ex command as the handler:
---
--- ```lua
--- vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
--- pattern = {"*.c", "*.h"},
--- vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
--- pattern = {'*.c', '*.h'},
--- command = "echo 'Entering a C or C++ file'",
--- })
--- ```
@@ -925,7 +925,7 @@ function vim.api.nvim_create_augroup(name, opts) end
--- and "~" must be expanded explicitly:
---
--- ```lua
--- pattern = vim.fn.expand("~") .. "/some/path/*.py"
--- pattern = vim.fn.expand('~') .. '/some/path/*.py'
--- ```
---
--- @see `:help autocommand`
@@ -1222,14 +1222,14 @@ function vim.api.nvim_get_all_options_info() end
--- ```lua
--- -- Matches all criteria
--- autocommands = vim.api.nvim_get_autocmds({
--- group = "MyGroup",
--- event = {"BufEnter", "BufWinEnter"},
--- pattern = {"*.c", "*.h"}
--- group = 'MyGroup',
--- event = {'BufEnter', 'BufWinEnter'},
--- pattern = {'*.c', '*.h'}
--- })
---
--- -- All commands from one group
--- autocommands = vim.api.nvim_get_autocmds({
--- group = "MyGroup",
--- group = 'MyGroup',
--- })
--- ```
---

5
runtime/lua/vim/_meta/vvars.lua generated
View File

@@ -586,8 +586,9 @@ vim.v.searchforward = ...
--- Read-only.
---
--- *$NVIM*
--- $NVIM is set by `terminal` and `jobstart()`, and is thus
--- a hint that the current environment is a subprocess of Nvim.
--- $NVIM is set to v:servername by `terminal` and `jobstart()`,
--- and is thus a hint that the current environment is a child
--- (direct subprocess) of Nvim.
---
--- Example: a child Nvim process can detect and make requests to
--- its parent Nvim:

8
src/gen/gen_api_dispatch.lua
View File

@@ -1,3 +1,5 @@
-- Generates C code to bridge API <=> Lua.
--
-- Example (manual) invocation:
--
-- make
@@ -192,7 +194,7 @@ for _, f in ipairs(shallowcopy(functions)) do
.. ' has deprecated alias\n'
.. newname
.. ' which has a separate implementation.\n'
.. 'Please remove it from src/nvim/api/dispatch_deprecated.lua'
.. 'Remove it from src/nvim/api/dispatch_deprecated.lua'
)
os.exit(1)
end
@@ -729,6 +731,10 @@ output:write('\n')
local lua_c_functions = {}
--- Generates C code to bridge RPC API <=> Lua.
---
--- Inspect the result here:
--- build/src/nvim/auto/api/private/dispatch_wrappers.generated.h
local function process_function(fn)
local lua_c_function_name = ('nlua_api_%s'):format(fn.name)
write_shifted_output(

20
src/nvim/api/autocmd.c
View File

@@ -53,14 +53,14 @@ static int64_t next_autocmd_id = 1;
/// ```lua
/// -- Matches all criteria
/// autocommands = vim.api.nvim_get_autocmds({
/// group = "MyGroup",
/// event = {"BufEnter", "BufWinEnter"},
/// pattern = {"*.c", "*.h"}
/// group = 'MyGroup',
/// event = {'BufEnter', 'BufWinEnter'},
/// pattern = {'*.c', '*.h'}
/// })
///
/// -- All commands from one group
/// autocommands = vim.api.nvim_get_autocmds({
/// group = "MyGroup",
/// group = 'MyGroup',
/// })
/// ```
///
@@ -336,8 +336,8 @@ cleanup:
/// Example using Lua callback:
///
/// ```lua
/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
/// pattern = {"*.c", "*.h"},
/// vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
/// pattern = {'*.c', '*.h'},
/// callback = function(ev)
/// print(string.format('event fired: %s', vim.inspect(ev)))
/// end
@@ -347,8 +347,8 @@ cleanup:
/// Example using an Ex command as the handler:
///
/// ```lua
/// vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
/// pattern = {"*.c", "*.h"},
/// vim.api.nvim_create_autocmd({'BufEnter', 'BufWinEnter'}, {
/// pattern = {'*.c', '*.h'},
/// command = "echo 'Entering a C or C++ file'",
/// })
/// ```
@@ -357,7 +357,7 @@ cleanup:
/// and "~" must be expanded explicitly:
///
/// ```lua
/// pattern = vim.fn.expand("~") .. "/some/path/*.py"
/// pattern = vim.fn.expand('~') .. '/some/path/*.py'
/// ```
///
/// @param event (string|array) Event(s) that will trigger the handler (`callback` or `command`).
@@ -603,7 +603,7 @@ void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Arena *arena, Error *err)
/// To get an existing group id, do:
///
/// ```lua
/// local id = vim.api.nvim_create_augroup("MyGroup", {
/// local id = vim.api.nvim_create_augroup('my.lsp.config', {
/// clear = false
/// })
/// ```

3
src/nvim/channel.c
View File

@@ -514,8 +514,7 @@ void channel_from_connection(SocketWatcher *watcher)
channel_create_event(channel, watcher->addr);
}
/// Creates an API channel from stdin/stdout. This is used when embedding
/// Neovim
/// Creates an API channel from stdin/stdout. Used when embedding Nvim.
uint64_t channel_from_stdio(bool rpc, CallbackReader on_output, const char **error)
FUNC_ATTR_NONNULL_ALL
{

6
src/nvim/eval/funcs.c
View File

@@ -3834,6 +3834,7 @@ static const char *pty_ignored_env_vars[] = {
"COLORFGBG",
"COLORTERM",
#endif
// Nvim-owned env vars. #6764
"VIM",
"VIMRUNTIME",
NULL
@@ -3870,9 +3871,8 @@ dict_T *create_environment(const dictitem_T *job_env, const bool clear_env, cons
tv_dict_free(temp_env.vval.v_dict);
if (pty) {
// These environment variables generally shouldn't be propagated to the
// child process. We're removing them here so the user can still decide
// they want to explicitly set them.
// These env vars shouldn't propagate to the child process. #6764
// Remove them here, then the user may decide to explicitly set them below.
for (size_t i = 0;
i < ARRAY_SIZE(pty_ignored_env_vars) && pty_ignored_env_vars[i];
i++) {

2
src/nvim/main.c
View File

@@ -165,7 +165,7 @@ void event_init(void)
}
/// @returns false if main_loop could not be closed gracefully
bool event_teardown(void)
static bool event_teardown(void)
{
if (!main_loop.events) {
input_stop();

5
src/nvim/vvars.lua
View File

@@ -674,8 +674,9 @@ M.vars = {
Read-only.
*$NVIM*
$NVIM is set by |terminal| and |jobstart()|, and is thus
a hint that the current environment is a subprocess of Nvim.
$NVIM is set to v:servername by |terminal| and |jobstart()|,
and is thus a hint that the current environment is a child
(direct subprocess) of Nvim.
Example: a child Nvim process can detect and make requests to
its parent Nvim: >lua

10
test/functional/core/job_spec.lua
View File

@@ -713,7 +713,7 @@ describe('jobs', function()
end)
it('jobstart() environment: $NVIM, $NVIM_LISTEN_ADDRESS #11009', function()
local function get_env_in_child_job(envname, env)
local function get_child_env(envname, env)
return exec_lua(
[[
local envname, env = ...
@@ -741,17 +741,17 @@ describe('jobs', function()
-- $NVIM is _not_ defined in the top-level Nvim process.
eq('', eval('$NVIM'))
-- jobstart() shares its v:servername with the child via $NVIM.
eq('NVIM=' .. addr, get_env_in_child_job('NVIM'))
eq('NVIM=' .. addr, get_child_env('NVIM'))
-- $NVIM_LISTEN_ADDRESS is unset by server_init in the child.
eq('NVIM_LISTEN_ADDRESS=v:null', get_env_in_child_job('NVIM_LISTEN_ADDRESS'))
eq('NVIM_LISTEN_ADDRESS=v:null', get_child_env('NVIM_LISTEN_ADDRESS'))
eq(
'NVIM_LISTEN_ADDRESS=v:null',
get_env_in_child_job('NVIM_LISTEN_ADDRESS', { NVIM_LISTEN_ADDRESS = 'Xtest_jobstart_env' })
get_child_env('NVIM_LISTEN_ADDRESS', { NVIM_LISTEN_ADDRESS = 'Xtest_jobstart_env' })
)
-- User can explicitly set $NVIM_LOG_FILE, $VIM, $VIMRUNTIME.
eq(
'NVIM_LOG_FILE=Xtest_jobstart_env',
get_env_in_child_job('NVIM_LOG_FILE', { NVIM_LOG_FILE = 'Xtest_jobstart_env' })
get_child_env('NVIM_LOG_FILE', { NVIM_LOG_FILE = 'Xtest_jobstart_env' })
)
os.remove('Xtest_jobstart_env')
end)