mirror of
https://github.com/neovim/neovim.git
synced 2024-09-17 20:58:20 -04:00
docs: misc #28970
This commit is contained in:
parent
6913c5e1d9
commit
61e9137394
1
runtime/doc/builtin.txt
generated
1
runtime/doc/builtin.txt
generated
@ -4361,6 +4361,7 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
|
||||
"lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
|
||||
form, only present when it differs from "lhsraw"
|
||||
"rhs" The {rhs} of the mapping as typed.
|
||||
"callback" Lua function, if RHS was defined as such.
|
||||
"silent" 1 for a |:map-silent| mapping, else 0.
|
||||
"noremap" 1 if the {rhs} of the mapping is not remappable.
|
||||
"script" 1 if mapping was defined with <script>.
|
||||
|
@ -138,15 +138,15 @@ DOCUMENTATION *dev-doc*
|
||||
- Write docstrings (as opposed to inline comments) with present tense ("Gets"),
|
||||
not imperative ("Get"). This tends to reduce ambiguity and improve clarity
|
||||
by describing "What" instead of "How". >
|
||||
GOOD:
|
||||
✅ OK:
|
||||
/// Gets a highlight definition.
|
||||
BAD:
|
||||
❌ NO:
|
||||
/// Get a highlight definition.
|
||||
- Avoid starting docstrings with "The" or "A" unless needed to avoid
|
||||
ambiguity. This is a visual aid and reduces noise. >
|
||||
GOOD:
|
||||
✅ OK:
|
||||
/// @param dirname Path fragment before `pend`
|
||||
BAD:
|
||||
❌ NO:
|
||||
/// @param dirname The path fragment before `pend`
|
||||
- Vim differences:
|
||||
- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
|
||||
@ -329,13 +329,20 @@ Where possible, these patterns apply to _both_ Lua and the API:
|
||||
- When accepting a buffer id, etc., 0 means "current buffer", nil means "all
|
||||
buffers". Likewise for window id, tabpage id, etc.
|
||||
- Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()|
|
||||
- Any function signature that accepts a callback function should define the
|
||||
callback as the LAST parameter, if possible. This improves readability of
|
||||
calls by placing the less "noisy" arguments near the start. >
|
||||
GOOD:
|
||||
filter(table, opts, function() … end)
|
||||
BAD:
|
||||
filter(function() … end, table, opts)
|
||||
- Any function signature that accepts a callback (example: |table.foreach()|)
|
||||
should place it as the LAST parameter (after opts), if possible (or ALWAYS
|
||||
for "continuation callbacks"—functions called exactly once).
|
||||
- Improves readability by placing the less "noisy" arguments near the start.
|
||||
- Consistent with luv.
|
||||
- Useful for future async lib which transforms functions of the form
|
||||
`function(<args>, cb(<ret)>))` => `function(<args>) -> <ret>`.
|
||||
- Example: >lua
|
||||
-- ✅ OK:
|
||||
filter(…, opts, function() … end)
|
||||
-- ❌ NO:
|
||||
filter(function() … end, …, opts)
|
||||
-- ❌ NO:
|
||||
filter(…, function() … end, opts)
|
||||
- "Enable" ("toggle") interface and behavior:
|
||||
- `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the
|
||||
the "global" enablement of a feature.
|
||||
@ -566,10 +573,10 @@ a good name: it's idiomatic and unambiguous. If the package is named "neovim",
|
||||
it confuses users, and complicates documentation and discussions.
|
||||
|
||||
Examples of API-client package names:
|
||||
- GOOD: nvim-racket
|
||||
- GOOD: pynvim
|
||||
- BAD: python-client
|
||||
- BAD: neovim_
|
||||
- ✅ OK: nvim-racket
|
||||
- ✅ OK: pynvim
|
||||
- ❌ NO: python-client
|
||||
- ❌ NO: neovim_
|
||||
|
||||
API client implementation guidelines ~
|
||||
|
||||
|
@ -7,10 +7,10 @@
|
||||
Type |gO| to see the table of contents.
|
||||
|
||||
==============================================================================
|
||||
Checkhealth *health*
|
||||
Checkhealth *vim.health* *health*
|
||||
|
||||
|
||||
health.vim is a minimal framework to help users troubleshoot configuration and
|
||||
vim.health is a minimal framework to help users troubleshoot configuration and
|
||||
any other environment conditions that a plugin might care about. Nvim ships
|
||||
with healthchecks for configuration, performance, python support, ruby
|
||||
support, clipboard support, and more.
|
||||
@ -49,7 +49,7 @@ Commands *health-commands*
|
||||
:checkhealth vim*
|
||||
<
|
||||
|
||||
Create a healthcheck *health-dev* *vim.health*
|
||||
Create a healthcheck *health-dev*
|
||||
|
||||
Healthchecks are functions that check the user environment, configuration, or
|
||||
any other prerequisites that a plugin cares about. Nvim ships with
|
||||
|
@ -1639,8 +1639,7 @@ Lua module: vim.lsp.completion *lsp-completion*
|
||||
Fields: ~
|
||||
• {autotrigger}? (`boolean`) Whether to trigger completion
|
||||
automatically. Default: false
|
||||
• {convert}? (`fun(item: lsp.CompletionItem): table`) An optional
|
||||
function used to customize the transformation of an
|
||||
• {convert}? (`fun(item: lsp.CompletionItem): table`) Transforms an
|
||||
LSP CompletionItem to |complete-items|.
|
||||
|
||||
|
||||
|
@ -352,16 +352,14 @@ Example: >vim
|
||||
<
|
||||
*lua-table-ambiguous*
|
||||
Lua tables are used as both dictionaries and lists, so it is impossible to
|
||||
determine whether empty table is meant to be empty list or empty dictionary.
|
||||
Additionally Lua does not have integer numbers. To distinguish between these
|
||||
cases there is the following agreement:
|
||||
decide whether empty table is a list or a dict. Also Lua does not have integer
|
||||
numbers. To disambiguate these cases, we define:
|
||||
*lua-list*
|
||||
0. Empty table is empty list.
|
||||
1. Table with N consecutive integer indices starting from 1 and ending with
|
||||
N is considered a list. See also |list-iterator|.
|
||||
0. Empty table is a list. Use |vim.empty_dict()| to represent empty dict.
|
||||
1. Table with N consecutive (no `nil` values, aka "holes") integer keys 1…N is
|
||||
a list. See also |list-iterator|.
|
||||
*lua-dict*
|
||||
2. Table with string keys, none of which contains NUL byte, is considered to
|
||||
be a dictionary.
|
||||
2. Table with string keys, none of which contains NUL byte, is a dict.
|
||||
3. Table with string keys, at least one of which contains NUL byte, is also
|
||||
considered to be a dictionary, but this time it is converted to
|
||||
a |msgpack-special-map|.
|
||||
@ -3839,8 +3837,10 @@ argument into an *Iter* object with methods (such as |Iter:filter()| and
|
||||
chained to create iterator "pipelines": the output of each pipeline stage is
|
||||
input to the next stage. The first stage depends on the type passed to
|
||||
`vim.iter()`:
|
||||
• List tables (arrays, |lua-list|) yield only the value of each element.
|
||||
• Holes (nil values) are allowed.
|
||||
• Lists or arrays (|lua-list|) yield only the value of each element.
|
||||
• Holes (nil values) are allowed (but discarded).
|
||||
• Use pairs() to treat array/list tables as dicts (preserve holes and
|
||||
non-contiguous integer keys): `vim.iter(pairs(…))`.
|
||||
• Use |Iter:enumerate()| to also pass the index to the next stage.
|
||||
• Or initialize with ipairs(): `vim.iter(ipairs(…))`.
|
||||
• Non-list tables (|lua-dict|) yield both the key and value of each element.
|
||||
|
@ -65,9 +65,8 @@ EVENTS
|
||||
|
||||
LSP
|
||||
|
||||
• Add convert field in |vim.lsp.completion.BufferOpts| of
|
||||
|vim.lsp.completion.enable()| an optional function used to customize the
|
||||
transformation of an Lsp CompletionItem to |complete-items|.
|
||||
• |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.
|
||||
|
||||
|
@ -248,8 +248,8 @@ For Windows WSL, try this g:clipboard definition:
|
||||
\ '*': 'clip.exe',
|
||||
\ },
|
||||
\ 'paste': {
|
||||
\ '+': 'powershell.exe -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
|
||||
\ '*': 'powershell.exe -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
|
||||
\ '+': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
|
||||
\ '*': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
|
||||
\ },
|
||||
\ 'cache_enabled': 0,
|
||||
\ }
|
||||
|
@ -1,17 +1,19 @@
|
||||
-- Nvim-Lua stdlib: the `vim` module (:help lua-stdlib)
|
||||
--
|
||||
-- Lua code lives in one of three places:
|
||||
-- 1. runtime/lua/vim/ (the runtime): For "nice to have" features, e.g. the
|
||||
-- `inspect` and `lpeg` modules.
|
||||
-- 2. 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.
|
||||
-- 3. runtime/lua/vim/_editor.lua: Code which directly interacts with
|
||||
-- the Nvim editor state. Only available in the main thread.
|
||||
-- Lua code lives in one of four places:
|
||||
-- 1. Plugins! Not everything needs to live on "vim.*". Plugins are the correct model for
|
||||
-- non-essential features which the user may want to disable or replace with a third-party
|
||||
-- plugin. Examples: "editorconfig", "comment".
|
||||
-- - "opt-out": runtime/plugin/*.lua
|
||||
-- - "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.
|
||||
-- 4. runtime/lua/vim/_editor.lua: Eager-loaded code which directly interacts with the Nvim
|
||||
-- editor state. Only available in the main thread.
|
||||
--
|
||||
-- Guideline: "If in doubt, put it in the runtime".
|
||||
--
|
||||
-- Most functions should live directly in `vim.`, not in submodules.
|
||||
-- The top level "vim.*" namespace is for fundamental Lua and editor features. Use submodules for
|
||||
-- everything else (but avoid excessive "nesting"), or plugins (see above).
|
||||
--
|
||||
-- Compatibility with Vim's `if_lua` is explicitly a non-goal.
|
||||
--
|
||||
@ -19,9 +21,7 @@
|
||||
-- - https://github.com/luafun/luafun
|
||||
-- - https://github.com/rxi/lume
|
||||
-- - http://leafo.net/lapis/reference/utilities.html
|
||||
-- - https://github.com/torch/paths
|
||||
-- - https://github.com/bakpakin/Fennel (pretty print, repl)
|
||||
-- - https://github.com/howl-editor/howl/tree/master/lib/howl/util
|
||||
|
||||
-- These are for loading runtime modules lazily since they aren't available in
|
||||
-- the nvim binary as specified in executor.c
|
||||
|
1
runtime/lua/vim/_meta/vimfn.lua
generated
1
runtime/lua/vim/_meta/vimfn.lua
generated
@ -5262,6 +5262,7 @@ function vim.fn.map(expr1, expr2) end
|
||||
--- "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
|
||||
--- form, only present when it differs from "lhsraw"
|
||||
--- "rhs" The {rhs} of the mapping as typed.
|
||||
--- "callback" Lua function, if RHS was defined as such.
|
||||
--- "silent" 1 for a |:map-silent| mapping, else 0.
|
||||
--- "noremap" 1 if the {rhs} of the mapping is not remappable.
|
||||
--- "script" 1 if mapping was defined with <script>.
|
||||
|
@ -1,6 +1,6 @@
|
||||
--- @brief
|
||||
---<pre>help
|
||||
--- health.vim is a minimal framework to help users troubleshoot configuration and
|
||||
--- vim.health is a minimal framework to help users troubleshoot configuration and
|
||||
--- any other environment conditions that a plugin might care about. Nvim ships
|
||||
--- with healthchecks for configuration, performance, python support, ruby
|
||||
--- support, clipboard support, and more.
|
||||
@ -39,7 +39,7 @@
|
||||
--- :checkhealth vim*
|
||||
--- <
|
||||
---
|
||||
--- Create a healthcheck *health-dev* *vim.health*
|
||||
--- Create a healthcheck *health-dev*
|
||||
---
|
||||
--- Healthchecks are functions that check the user environment, configuration, or
|
||||
--- any other prerequisites that a plugin cares about. Nvim ships with
|
||||
|
@ -6,8 +6,10 @@
|
||||
--- of each pipeline stage is input to the next stage. The first stage depends on the type passed to
|
||||
--- `vim.iter()`:
|
||||
---
|
||||
--- - List tables (arrays, |lua-list|) yield only the value of each element.
|
||||
--- - Holes (nil values) are allowed.
|
||||
--- - Lists or arrays (|lua-list|) yield only the value of each element.
|
||||
--- - Holes (nil values) are allowed (but discarded).
|
||||
--- - Use pairs() to treat array/list tables as dicts (preserve holes and non-contiguous integer
|
||||
--- keys): `vim.iter(pairs(…))`.
|
||||
--- - Use |Iter:enumerate()| to also pass the index to the next stage.
|
||||
--- - Or initialize with ipairs(): `vim.iter(ipairs(…))`.
|
||||
--- - Non-list tables (|lua-dict|) yield both the key and value of each element.
|
||||
@ -1034,7 +1036,7 @@ function Iter.new(src, ...)
|
||||
if type(k) ~= 'number' or k <= 0 or math.floor(k) ~= k then
|
||||
return Iter.new(pairs(src))
|
||||
end
|
||||
t[#t + 1] = v
|
||||
t[#t + 1] = v -- Coerce to list-like table.
|
||||
end
|
||||
return ArrayIter.new(t)
|
||||
end
|
||||
|
@ -597,7 +597,7 @@ end
|
||||
|
||||
--- @class vim.lsp.completion.BufferOpts
|
||||
--- @field autotrigger? boolean Whether to trigger completion automatically. Default: false
|
||||
--- @field convert? fun(item: lsp.CompletionItem): table An optional function used to customize the transformation of an LSP CompletionItem to |complete-items|.
|
||||
--- @field convert? fun(item: lsp.CompletionItem): table Transforms an LSP CompletionItem to |complete-items|.
|
||||
|
||||
---@param client_id integer
|
||||
---@param bufnr integer
|
||||
|
@ -373,8 +373,8 @@ local config = {
|
||||
section_fmt = function(_name)
|
||||
return 'Checkhealth'
|
||||
end,
|
||||
helptag_fmt = function(name)
|
||||
return name:lower()
|
||||
helptag_fmt = function()
|
||||
return 'vim.health* *health' -- HACK
|
||||
end,
|
||||
},
|
||||
}
|
||||
|
@ -6442,6 +6442,7 @@ M.funcs = {
|
||||
"lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
|
||||
form, only present when it differs from "lhsraw"
|
||||
"rhs" The {rhs} of the mapping as typed.
|
||||
"callback" Lua function, if RHS was defined as such.
|
||||
"silent" 1 for a |:map-silent| mapping, else 0.
|
||||
"noremap" 1 if the {rhs} of the mapping is not remappable.
|
||||
"script" 1 if mapping was defined with <script>.
|
||||
|
@ -1434,9 +1434,9 @@ scripterror:
|
||||
// On Windows expand "~\" or "~/" prefix in file names to profile directory.
|
||||
#ifdef MSWIN
|
||||
if (*p == '~' && (p[1] == '\\' || p[1] == '/')) {
|
||||
size_t size = strlen(os_get_homedir()) + strlen(p);
|
||||
size_t size = strlen(os_homedir()) + strlen(p);
|
||||
char *tilde_expanded = xmalloc(size);
|
||||
snprintf(tilde_expanded, size, "%s%s", os_get_homedir(), p + 1);
|
||||
snprintf(tilde_expanded, size, "%s%s", os_homedir(), p + 1);
|
||||
xfree(p);
|
||||
p = tilde_expanded;
|
||||
}
|
||||
|
@ -395,7 +395,21 @@ void os_get_hostname(char *hostname, size_t size)
|
||||
#endif
|
||||
}
|
||||
|
||||
/// To get the "real" home directory:
|
||||
/// The "real" home directory as determined by `init_homedir`.
|
||||
static char *homedir = NULL;
|
||||
static char *os_uv_homedir(void);
|
||||
|
||||
/// Gets the "real", resolved user home directory as determined by `init_homedir`.
|
||||
const char *os_homedir(void)
|
||||
{
|
||||
if (!homedir) {
|
||||
emsg("os_homedir failed: homedir not initialized");
|
||||
return NULL;
|
||||
}
|
||||
return homedir;
|
||||
}
|
||||
|
||||
/// Sets `homedir` to the "real", resolved user home directory, as follows:
|
||||
/// 1. get value of $HOME
|
||||
/// 2. if $HOME is not set, try the following
|
||||
/// For Windows:
|
||||
@ -409,20 +423,6 @@ void os_get_hostname(char *hostname, size_t size)
|
||||
/// This also works with mounts and links.
|
||||
/// Don't do this for Windows, it will change the "current dir" for a drive.
|
||||
/// 3. fall back to current working directory as a last resort
|
||||
static char *homedir = NULL;
|
||||
static char *os_uv_homedir(void);
|
||||
|
||||
/// Public accessor for the cached "real", resolved user home directory. See
|
||||
/// comment on `homedir`.
|
||||
const char *os_get_homedir(void)
|
||||
{
|
||||
if (!homedir) {
|
||||
emsg("os_get_homedir failed: homedir not initialized");
|
||||
return NULL;
|
||||
}
|
||||
return homedir;
|
||||
}
|
||||
|
||||
void init_homedir(void)
|
||||
{
|
||||
// In case we are called a second time.
|
||||
|
@ -514,7 +514,7 @@ static void process_ctrl_c(void)
|
||||
|
||||
size_t available = input_available();
|
||||
ssize_t i;
|
||||
for (i = (ssize_t)available - 1; i >= 0; i--) {
|
||||
for (i = (ssize_t)available - 1; i >= 0; i--) { // Reverse-search input for Ctrl_C.
|
||||
uint8_t c = (uint8_t)input_read_pos[i];
|
||||
if (c == Ctrl_C
|
||||
|| (c == 'C' && i >= 3
|
||||
|
@ -145,10 +145,9 @@ describe('lua stdlib', function()
|
||||
-- "0.10" or "0.10-dev+xxx"
|
||||
local curstr = ('%s.%s%s'):format(curver.major, curver.minor, prerel or '')
|
||||
eq(
|
||||
dedent(
|
||||
[[
|
||||
foo.bar() is deprecated. Run ":checkhealth vim.deprecated" for more information]]
|
||||
):format(curstr),
|
||||
([[foo.bar() is deprecated. Run ":checkhealth vim.deprecated" for more information]]):format(
|
||||
curstr
|
||||
),
|
||||
exec_lua('return vim.deprecate(...)', 'foo.bar()', 'zub.wooo{ok=yay}', curstr)
|
||||
)
|
||||
-- Same message as above; skipped this time.
|
||||
@ -178,8 +177,7 @@ describe('lua stdlib', function()
|
||||
|
||||
it('plugin=nil, to be deleted in the next major version (1.0)', function()
|
||||
eq(
|
||||
dedent [[
|
||||
foo.baz() is deprecated. Run ":checkhealth vim.deprecated" for more information]],
|
||||
[[foo.baz() is deprecated. Run ":checkhealth vim.deprecated" for more information]],
|
||||
exec_lua [[ return vim.deprecate('foo.baz()', nil, '1.0') ]]
|
||||
)
|
||||
end)
|
||||
|
@ -724,7 +724,7 @@ describe('vim.lsp.completion: protocol', function()
|
||||
end)
|
||||
end)
|
||||
|
||||
it('custom word/abbar format', function()
|
||||
it('enable(…,{convert=fn}) custom word/abbr format', function()
|
||||
create_server({
|
||||
isIncomplete = false,
|
||||
items = {
|
||||
|
Loading…
Reference in New Issue
Block a user