mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-11-04 01:34:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge #21428 docs: naming conventions, guidelines

Browse Source
This commit is contained in:
Justin M. Keyes
2023-02-22 10:40:01 -05:00
committed by GitHub
parent 675826da63 6752f1005d
commit 09b6a68c37
20 changed files with 412 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.github/ISSUE_TEMPLATE/bug_report.yml vendored
View File

@@ -6,15 +6,14 @@ body:
- type: markdown
attributes:
value: |
_Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage questions such as "How do I...?" belong on the [Neovim Discourse](https://neovim.discourse.group/c/7-category/7) and will be closed.
_Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage or "How to" questions belong on the [stackoverflow](https://vi.stackexchange.com/) and will be closed.
- type: textarea
attributes:
label: "Describe the bug"
label: "Problem"
description: "Describe the current behavior. May include logs, images, or videos."
validations:
required: true
- type: textarea
attributes:
label: "Steps to reproduce"
@@ -27,7 +26,6 @@ body:
yiwp
validations:
required: true
- type: textarea
attributes:
label: "Expected behavior"

2
.github/ISSUE_TEMPLATE/config.yml vendored
View File

@@ -1,5 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Question
url: https://neovim.discourse.group/
url: https://vi.stackexchange.com/
about: Ask questions about configuration and usage of Neovim

42
.github/ISSUE_TEMPLATE/lsp_bug_report.yml vendored
View File

@@ -6,27 +6,14 @@ body:
- type: markdown
attributes:
value: |
_Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage questions such as "How do I...?" or "Why isn't X language server/feature working?" belong on the [Neovim Discourse](https://neovim.discourse.group/c/7-category/7) and will be closed.
_Before reporting:_ search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and check the [FAQ](https://github.com/neovim/neovim/wiki/FAQ). Usage questions or "Why isn't X language server/feature working?" belong on [stackoverflow](https://vi.stackexchange.com/) and will be closed.
- type: input
- type: textarea
attributes:
label: "Neovim version (nvim -v)"
placeholder: "0.6.0 commit db1b0ee3b30f"
label: "Problem"
description: "Describe the bug caused by the Nvim LSP client."
validations:
required: true
- type: input
attributes:
label: "Language server name/version"
placeholder: "rls 0.5.2"
validations:
required: true
- type: input
attributes:
label: "Operating system/version"
placeholder: "emacs 23"
validations:
required: true
- type: textarea
attributes:
label: 'Steps to reproduce using "nvim -u minimal_init.lua"'
@@ -65,14 +52,29 @@ body:
_Note_: if the issue is with an autocompletion or other LSP plugin, report to that plugin's issue tracker.
validations:
required: true
- type: textarea
attributes:
label: "Expected behavior"
description: "Describe the behavior you expect. May include logs, images, or videos."
- type: textarea
- type: input
attributes:
label: "Actual behavior"
label: "Neovim version (nvim -v)"
placeholder: "0.6.0 commit db1b0ee3b30f"
validations:
required: true
- type: input
attributes:
label: "Language server name/version"
placeholder: "rls 0.5.2"
validations:
required: true
- type: input
attributes:
label: "Operating system/version"
placeholder: "emacs 23"
validations:
required: true
- type: input
attributes:

1
README.md
View File

@@ -75,7 +75,6 @@ See [`:help nvim-from-vim`](https://neovim.io/doc/user/nvim.html#nvim-from-vim)
Project layout
--------------
├─ ci/ build automation
├─ cmake/ CMake utils
├─ cmake.config/ CMake defines
├─ cmake.deps/ subproject to fetch and build dependencies (optional)

57
runtime/doc/api.txt
View File

@@ -1461,16 +1461,15 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()*
"!" for |:map!|, or empty string for |:map|.
• {lhs} Left-hand-side |{lhs}| of the mapping.
• {rhs} Right-hand-side |{rhs}| of the mapping.
• {opts} Optional parameters map: keys are |:map-arguments|, values are
booleans (default false). Accepts all |:map-arguments| as keys
excluding |<buffer>| but including |:noremap| and "desc".
Unknown key is an error. "desc" can be used to give a
description to the mapping. When called from Lua, also accepts
a "callback" key that takes a Lua function to call when the
mapping is executed. When "expr" is true, "replace_keycodes"
(boolean) can be used to replace keycodes in the resulting
string (see |nvim_replace_termcodes()|), and a Lua callback
returning `nil` is equivalent to returning an empty string.
• {opts} Optional parameters map: Accepts all |:map-arguments| as keys
except |<buffer>|, values are booleans (default false). Also:
• "noremap" non-recursive mapping |:noremap|
• "desc" human-readable description.
• "callback" Lua function called when the mapping is executed.
• "replace_keycodes" (boolean) When "expr" is true, replace
keycodes in the resulting string (see
|nvim_replace_termcodes()|). Returning nil from the Lua
"callback" is equivalent to returning an empty string.
nvim_set_var({name}, {value}) *nvim_set_var()*
Sets a global (g:) variable.
@@ -1678,7 +1677,7 @@ Command Functions *api-command*
*nvim_buf_create_user_command()*
nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts})
Create a new user command |user-commands| in the given buffer.
Creates a buffer-local command |user-commands|.
Parameters: ~
• {buffer} Buffer handle, or 0 for current buffer.
@@ -1743,15 +1742,12 @@ nvim_cmd({*cmd}, {*opts}) *nvim_cmd()*
*nvim_create_user_command()*
nvim_create_user_command({name}, {command}, {*opts})
Create a new user command |user-commands|
Creates a global |user-commands| command.
{name} is the name of the new command. The name must begin with an
uppercase letter.
{command} is the replacement text or Lua function to execute.
For Lua usage see |lua-guide-commands-create|.
Example: >vim
:call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
:call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
:SayHello
Hello world!
<
@@ -1783,19 +1779,20 @@ nvim_create_user_command({name}, {command}, {*opts})
• smods: (table) Command modifiers in a structured format.
Has the same structure as the "mods" key of
|nvim_parse_cmd()|.
• {opts} Optional command attributes. See |command-attributes| for
more details. To use boolean attributes (such as
|:command-bang| or |:command-bar|) set the value to "true".
In addition to the string options listed in
|:command-complete|, the "complete" key also accepts a Lua
function which works like the "customlist" completion mode
|:command-completion-customlist|. Additional parameters:
• desc: (string) Used for listing the command when a Lua
function is used for {command}.
• force: (boolean, default true) Override any previous
definition.
• preview: (function) Preview callback for 'inccommand'
|:command-preview|
• {opts} Optional |command-attributes|.
• Set boolean attributes such as |:command-bang| or
|:command-bar| to true (but not |:command-buffer|, use
|nvim_buf_create_user_command()| instead).
• "complete" |:command-complete| also accepts a Lua
function which works like
|:command-completion-customlist|.
• Other parameters:
• desc: (string) Used for listing the command when a Lua
function is used for {command}.
• force: (boolean, default true) Override any previous
definition.
• preview: (function) Preview callback for 'inccommand'
|:command-preview|
nvim_del_user_command({name}) *nvim_del_user_command()*
Delete a user-defined command.

183
runtime/doc/develop.txt
View File

@@ -132,6 +132,18 @@ DOCUMENTATION *dev-doc*
optimize for the reader's time and energy: be "precise yet concise".
- See https://developers.google.com/style/tone
- Prefer the active voice: "Foo does X", not "X is done by Foo".
- Start function docstrings with present tense ("Gets"), not imperative
("Get"). This tends to reduce ambiguity and improve clarity. >
GOOD:
/// Gets a highlight definition.
BAD:
/// 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:
/// @param dirname Path fragment before `pend`
BAD:
/// @param dirname The path fragment before `pend`
- Vim differences:
- Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
differences from Vim; no other distinction is necessary.
@@ -143,13 +155,6 @@ DOCUMENTATION *dev-doc*
not "the user host terminal".
- Use "tui-" to prefix help tags related to the host terminal, and "TUI"
in prose if possible.
- Docstrings: do not start parameter descriptions with "The" or "A" unless it
is critical to avoid ambiguity. >
GOOD:
/// @param dirname Path fragment before `pend`
BAD:
/// @param dirname The path fragment before `pend`
<
Documentation format ~
@@ -159,14 +164,14 @@ https://neovim.io/doc/user ).
Strict "vimdoc" subset:
- Use lists (like this!) prefixed with "-", "*", or "•", for adjacent lines
that you don't want auto-wrapped. Lists are always rendered with "flow"
(soft-wrapped) layout instead of preformatted (hard-wrapped) layout common
in legacy :help docs.
- Use lists (like this!) prefixed with "-" or "•", for adjacent lines that you
don't want to auto-wrap. Lists are always rendered with "flow" layout
(soft-wrapped) instead of preformatted (hard-wrapped) layout common in
legacy :help docs.
- Limitation: currently the parser https://github.com/neovim/tree-sitter-vimdoc
does not understand numbered listitems, so use a bullet symbol (- or •)
before numbered items, e.g. "- 1." instead of "1.".
- Separate blocks (paragraphs) of content by a blank line(s).
before numbered items, e.g. "• 1." instead of "1.".
- Separate blocks (paragraphs) of content by a blank line.
- Do not use indentation in random places—that prevents the page from using
"flow" layout. If you need a preformatted section, put it in
a |help-codeblock| starting with ">".
@@ -246,7 +251,9 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
---@returns false if client should cancel the paste.
LUA *dev-lua*
LUA STDLIB DESIGN GUIDELINES *dev-lua*
See also |dev-naming|.
- Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
pseudo-OOP designs. Plugin authors just want functions to call, not a big,
@@ -255,10 +262,26 @@ LUA *dev-lua*
tables or values are easier to serialize, easier to construct from literals,
easier to inspect and print, and inherently compatible with all Lua plugins.
(This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.)
- stdlib functions should follow these common patterns:
- accept iterable instead of table
- exception: in some cases iterable doesn't make sense, e.g. spair() sorts
the input by definition, so there is no reason for it to accept an
iterable, because the input needs to be "hydrated", it can't operate on
a "stream".
- return iterable instead of table
- mimic the pairs() or ipairs() interface if the function is intended to be
used in a "for" loop.
API *dev-api*
API DESIGN GUIDELINES *dev-api*
See also |dev-naming|.
- When adding an API, check the following:
- What precedents did you draw from? How does your solution compare to them?
- Does your new API allow future expansion? How? Or why not?
- Is the new API similar to existing APIs? Do we need to deprecate the old ones?
- Did you cross-reference related concepts in the docs?
- Avoid "mutually exclusive" parameters--via constraints or limitations, if
necessary. For example nvim_create_autocmd() has mutually exclusive
"callback" and "command" args; but the "command" arg could be eliminated by
@@ -266,66 +289,95 @@ API *dev-api*
"callback" arg as an Ex command (which can call Vimscript functions). The
"buffer" arg could also be eliminated by treating a number "pattern" as
a buffer number.
- Avoid functions that depend on cursor position, current buffer, etc. Instead
the function should take a position parameter, buffer parameter, etc.
*dev-api-naming*
Use this format to name new RPC |API| functions:
NAMING GUIDELINES *dev-naming*
nvim_{thing}_{action}_{arbitrary-qualifiers}
Naming is exceedingly important: the name of a thing is the primary interface
for uses it, discusses it, searches for it, shares it... Consistent
naming in the stdlib, API, and UI helps both users and developers discover and
intuitively understand related concepts ("families"), and reduces cognitive
burden. Discoverability encourages code re-use and likewise avoids redundant,
overlapping mechanisms, which reduces code surface-area, and thereby minimizes
bugs...
If the function acts on an object then {thing} is the name of that object
(e.g. "buf" or "win"). If the function operates in a "global" context then
{thing} is usually omitted (but consider "namespacing" your global operations
with a {thing} that groups functions under a common concept).
Naming conventions ~
Use existing common {action} names if possible:
- add Append to, or insert into, a collection
- call Call a function
- create Create a new (non-trivial) thing
- del Delete a thing (or group of things)
- eval Evaluate an expression
- exec Execute code
- fmt Format
- get Get things (often by a query)
- open Open
- parse Parse something into a structured form
- set Set a thing (or group of things)
In general, look for precedent when choosing a name, that is, look at existing
(non-deprecated) functions. In particular, see below...
*dev-name-common*
Use existing common {verb} names (actions) if possible:
- add: Appends or inserts into a collection
- attach: Listens to something to get events from it (TODO: rename to "on"?)
- call: Calls a function
- clear: Clears state but does not destroy the container
- create: Creates a new (non-trivial) thing (TODO: rename to "def"?)
- del: Deletes a thing (or group of things)
- detach: Dispose attached listener (TODO: rename to "un"?)
- eval: Evaluates an expression
- exec: Executes code
- fmt: Formats
- get: Gets things (often by a query)
- inspect: Presents a high-level, often interactive, view
- open: Opens something (a buffer, window, …)
- parse: Parses something into a structured form
- set: Sets a thing (or group of things)
- try_{verb}: Best-effort operation, failure returns null or error obj
Do NOT use these deprecated verbs:
- list Redundant with "get"
- list: Redundant with "get"
- show: Redundant with "print", "echo"
- notify: Redundant with "print", "echo"
Use consistent names for {thing} (nouns) in API functions: buffer is called
Use consistent names for {noun} (nouns) in API functions: buffer is called
"buf" everywhere, not "buffer" in some places and "buf" in others.
- buf Buffer
- chan |channel|
- cmd Command
- cmdline Command-line UI or input
- fn Function
- hl Highlight
- pos Position
- proc System process
- tabpage Tabpage
- win Window
- buf: Buffer
- chan: |channel|
- cmd: Command
- cmdline: Command-line UI or input
- fn: Function
- hl: Highlight
- pos: Position
- proc: System process
- tabpage: Tabpage
- win: Window
Do NOT use these deprecated nouns:
- buffer
- command
- window
Example:
`nvim_get_keymap('v')` operates in a global context (first parameter is not
a Buffer). The "get" {action} indicates that it gets anything matching the
given filter parameter. There is no need for a "list" action because
`nvim_get_keymap('')` (i.e., empty filter) returns all items.
*dev-name-events*
Use the "on_" prefix to name event-handling callbacks and also the interface for
"registering" such handlers (on_key). The dual nature is acceptable to avoid
a confused collection of naming conventions for these related concepts.
Example:
`nvim_buf_del_mark` acts on a `Buffer` object (the first parameter)
and uses the "del" {action}.
Editor |events| (autocommands) are historically named like: >
{Noun}{Event}
Use this format to name new API events:
nvim_{thing}_{event}_event
Use this format to name API (RPC) events: >
nvim_{noun}_{event-name}_event
Example:
`nvim_buf_changedtick_event`
Example: >
nvim_buf_changedtick_event
<
*dev-name-api*
Use this format to name new RPC |API| functions: >
nvim_{noun}_{verb}_{arbitrary-qualifiers}
If the function acts on an object then {noun} is the name of that object
(e.g. "buf" or "win"). If the function operates in a "global" context then
{noun} is usually omitted (but consider "namespacing" your global operations
with a {noun} that groups functions under a common concept).
- Example: `nvim_get_keymap('v')` operates in a global context (first
parameter is not a Buffer). The "get" verb indicates that it gets anything
matching the given filter parameter. A "list" verb is unnecessary because
`nvim_get_keymap('')` (empty filter) returns all items.
- Example: `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter)
and uses the "del" {verb}.
API-CLIENT *dev-api-client*
@@ -417,19 +469,4 @@ External UIs are expected to implement these common features:
published in this event. See also "mouse_on", "mouse_off".
NAMING *dev-naming*
Naming is important. Consistent naming in the API and UI helps both users and
developers discover and intuitively understand related concepts ("families"),
and reduces cognitive burden. Discoverability encourages code re-use and
likewise avoids redundant, overlapping mechanisms, which reduces code
surface-area, and thereby minimizes bugs...
Naming conventions ~
Use the "on_" prefix to name event handlers and also the interface for
"registering" such handlers (on_key). The dual nature is acceptable to avoid
a confused collection of naming conventions for these related concepts.
vim:tw=78:ts=8:sw=4:et:ft=help:norl:

35
runtime/doc/editing.txt
View File

@@ -1668,29 +1668,26 @@ There are three different types of searching:
==============================================================================
12. Trusted Files *trust*
Nvim has the ability to execute arbitrary code through the 'exrc' option. In
order to prevent executing code from untrusted sources, Nvim has the concept of
"trusted files". An untrusted file will not be executed without the user's
consent, and a user can permanently mark a file as trusted or untrusted using
the |:trust| command or the |vim.secure.read()| function.
Nvim executes arbitrary code found on the filesystem if 'exrc' is enabled. To
prevent executing malicious code, only "trusted files" are executed. You can
mark a file as trusted or untrusted using the |:trust| command or the
|vim.secure.read()| function.
*:trust* *E5570*
:trust [++deny] [++remove] [{file}]
:trust [++deny] [++remove] [file]
Manage files in the trust database. Without any options
or arguments, :trust adds the file associated with the
current buffer to the trust database, along with the
SHA256 hash of its contents.
Manage trusted files. Without ++ options, :trust marks
[file] (or current buffer if no [file]) as trusted,
keyed on a hash of its contents. The trust list is
stored on disk, Nvim will re-use it after restarting.
[++deny] marks the file associated with the current
buffer (or {file}, if given) as denied; no prompts will
be displayed to the user and the file will never be
executed.
[++deny] marks [file] (or current buffer if no [file]) as
untrusted: it will never be executed, 'exrc' will
ignore it.
[++remove] removes the file associated with the current
buffer (or {file}, if given) from the trust database.
Future attempts to read the file in a secure setting
(i.e. with 'exrc' or |vim.secure.read()|) will prompt
the user if the file is trusted.
[++remove] removes [file] (or current buffer if no
[file]) from the trust list. When the file is
discovered by 'exrc' or |vim.secure.read()|, the user
will be asked whether to trust or deny the file.
vim:tw=78:ts=8:noet:ft=help:norl:

24
runtime/doc/editorconfig.txt
View File

@@ -6,25 +6,21 @@
EditorConfig integration *editorconfig*
Nvim natively supports EditorConfig. When a file is opened, Nvim searches
upward through all of the parent directories of that file looking for
".editorconfig" files. Each of these is parsed and any properties that match
the opened file are applied.
For more information on EditorConfig, see https://editorconfig.org/.
Nvim supports EditorConfig. When a file is opened, Nvim searches all parent
directories of that file for ".editorconfig" files, parses them, and applies
any properties that match the opened file. Think of it like 'modeline' for an
entire (recursive) directory. For more information see
https://editorconfig.org/.
*g:editorconfig* *b:editorconfig*
EditorConfig integration can be disabled globally by adding >lua
EditorConfig is enabled by default. To disable it, add to your config: >lua
vim.g.editorconfig = false
<
to the user's |init.lua| file (or the Vimscript equivalent to |init.vim|). It
can also be disabled per-buffer by setting the |b:editorconfig| buffer-local
variable to `false`.
(Vimscript: `let g:editorconfig = v:false`). It can also be disabled
per-buffer by setting the |b:editorconfig| buffer-local variable to `false`.
When Nvim finds a valid .editorconfig file it will store the applied
properties in the buffer variable |b:editorconfig| if it was not already set to
`false` by the user.
Nvim stores the applied properties in |b:editorconfig| if it is not `false`.
*editorconfig-properties*
The following properties are supported by default:
@@ -88,4 +84,4 @@ Example: >lua
vim.b[bufnr].foo = val
end
<
vim:tw=78:ts=8:noet:ft=help:norl:
vim:tw=78:ts=8:et:sw=4:ft=help:norl:

6
runtime/doc/lua-guide.txt
View File

@@ -657,7 +657,7 @@ See also
• |nvim_exec_autocmds()|: execute all matching autocommands
==============================================================================
User commands *lua-guide-usercommands*
User commands *lua-guide-commands*
|user-commands| are custom Vim commands that call a Vimscript or Lua function.
Just like built-in commands, they can have arguments, act on ranges, or have
@@ -665,7 +665,7 @@ custom completion of arguments. As these are most useful for plugins, we will
cover only the basics of this advanced topic.
------------------------------------------------------------------------------
Creating user commands *lua-guide-usercommands-create*
Creating user commands *lua-guide-commands-create*
User commands can be created through the Neovim API with
`vim.api.`|nvim_create_user_command()|. This function takes three mandatory
@@ -734,7 +734,7 @@ the remaining arguments are the same as for |nvim_create_user_command()|:
{ nargs = 1 })
<
------------------------------------------------------------------------------
Deleting user commands *lua-guide-usercommands-delete*
Deleting user commands *lua-guide-commands-delete*
User commands can be deleted with `vim.api.`|nvim_del_user_command()|. The only
argument is the name of the command:

61
runtime/doc/lua.txt
View File

@@ -2029,7 +2029,8 @@ uri_to_fname({uri}) *vim.uri_to_fname()*
Lua module: ui *lua-ui*
input({opts}, {on_confirm}) *vim.ui.input()*
Prompts the user for input
Prompts the user for input, allowing arbitrary (potentially asynchronous)
work until `on_confirm`.
Example: >lua
@@ -2054,7 +2055,8 @@ input({opts}, {on_confirm}) *vim.ui.input()*
entered), or `nil` if the user aborted the dialog.
select({items}, {opts}, {on_choice}) *vim.ui.select()*
Prompts the user to pick a single item from a collection of entries
Prompts the user to pick from a list of items, allowing arbitrary
(potentially asynchronous) work until `on_choice`.
Example: >lua
@@ -2253,57 +2255,38 @@ del({modes}, {lhs}, {opts}) *vim.keymap.del()*
|vim.keymap.set()|
set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
Add a new |mapping|. Examples: >lua
Adds a new |mapping|. Examples: >lua
-- Can add mapping to Lua functions
-- Map to a Lua function:
vim.keymap.set('n', 'lhs', function() print("real lua function") end)
-- Can use it to map multiple modes
-- Map to multiple modes:
vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true })
-- Can add mapping for specific buffer
-- Buffer-local mapping:
vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
-- Expr mappings
-- Expr mapping:
vim.keymap.set('i', '<Tab>', function()
return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
end, { expr = true })
-- <Plug> mappings
-- <Plug> mapping:
vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
<
Note that in a mapping like: >lua
vim.keymap.set('n', 'asdf', require('jkl').my_fun)
<
the `require('jkl')` gets evaluated during this call in order to access the function. If you
want to avoid this cost at startup you can wrap it in a function, for
example: >lua
vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
<
Parameters: ~
• {mode} string|table Same mode short names as |nvim_set_keymap()|. Can
• {mode} string|table Mode short-name, see |nvim_set_keymap()|. Can
also be list of modes to create mapping on multiple modes.
• {lhs} (string) Left-hand side |{lhs}| of the mapping.
• {rhs} string|function Right-hand side |{rhs}| of the mapping. Can
also be a Lua function.
• {opts} (table|nil) A table of |:map-arguments|.
• Accepts options accepted by the {opts} parameter in
|nvim_set_keymap()|, with the following notable differences:
• replace_keycodes: Defaults to `true` if "expr" is `true`.
• noremap: Always overridden with the inverse of "remap"
(see below).
• {rhs} string|function Right-hand side |{rhs}| of the mapping, can be
a Lua function.
• {opts} (table|nil) Table of |:map-arguments|.
• Same as |nvim_set_keymap()| {opts}, except:
• "replace_keycodes" defaults to `true` if "expr" is `true`.
• "noremap": inverse of "remap" (see below).
• In addition to those options, the table accepts the
following keys:
• buffer: (number or boolean) Add a mapping to the given
buffer. When `0` or `true`, use the current buffer.
• remap: (boolean) Make the mapping recursive. This is the
inverse of the "noremap" option from |nvim_set_keymap()|.
Defaults to `false`.
• Also accepts:
• "buffer" number|boolean Creates buffer-local mapping, `0`
or `true` for current buffer.
• remap: (boolean) Make the mapping recursive. Inverses
"noremap". Defaults to `false`.
See also: ~
|nvim_set_keymap()|

4
runtime/doc/news.txt
View File

@@ -13,7 +13,7 @@ BREAKING CHANGES *news-breaking*
The following changes may require adaptations in user config or plugins.
• Cscope support is now removed (see |cscope| and |nvim-features-removed|):
• Cscope support is now removed (see |cscope| and |nvim-removed|):
- Commands removed:
- `:cscope`
- `:lcscope`
@@ -34,7 +34,7 @@ The following changes may require adaptations in user config or plugins.
See https://github.com/neovim/neovim/pull/20545 for more information.
• `:hardcopy` is now removed (see |hardcopy| and |nvim-features-removed|):
• `:hardcopy` is now removed (see |hardcopy| and |nvim-removed|):
- Commands removed:
- `:hardcopy`
- Options removed:

37
runtime/doc/options.txt
View File

@@ -401,20 +401,15 @@ the system, mostly it is something like 256 or 1024 characters.
==============================================================================
2. Automatically setting options *auto-setting*
Besides changing options with the ":set" command, there are three alternatives
to set options automatically for one or more files:
Besides changing options with the ":set" command, you can set options
automatically in various ways:
1. When starting Vim initializations are read from various places. See
|initialization|. Most of them are performed for all editing sessions,
and some of them depend on the directory where Vim is started.
You can create an initialization file with |:mkvimrc|, |:mkview| and
|:mksession|.
2. If you start editing a new file, the automatic commands are executed.
This can be used to set options for files matching a particular pattern and
many other things. See |autocommand|.
3. If you start editing a new file, and the 'modeline' option is on, a
number of lines at the beginning and end of the file are checked for
modelines. This is explained here.
1. With a |config| file or a |startup| argument. You can create an
initialization file with |:mkvimrc|, |:mkview| and |:mksession|.
2. |autocommand|s executed when you edit a file.
3. ".nvim.lua" files in the current directory, if 'exrc' is enabled.
4. |editorconfig| in the current buffer's directory or ancestors.
5. 'modeline' settings found at the beginning or end of the file. See below.
*modeline* *vim:* *vi:* *ex:* *E520*
There are two forms of modelines. The first form:
@@ -2267,15 +2262,13 @@ A jump table for the options with a short description can be found at |Q_op|.
*'exrc'* *'ex'* *'noexrc'* *'noex'*
'exrc' 'ex' boolean (default off)
global
Enables the reading of .nvim.lua, .nvimrc, and .exrc files in the current
directory.
Automatically execute .nvim.lua, .nvimrc, and .exrc files in the
current directory, if the file is in the |trust| list. Use |:trust| to
manage trusted files. See also |vim.secure.read()|.
The file is only sourced if the user indicates the file is trusted. If
it is, the SHA256 hash of the file contents and the full path of the
file are persisted to a trust database. The user is only prompted
again if the file contents change. See |vim.secure.read()|.
Use |:trust| to manage the trusted file database.
Compare 'exrc' to |editorconfig|:
- 'exrc' can execute any code; editorconfig only specifies settings.
- 'exrc' is Nvim-specific; editorconfig works in other editors.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
@@ -6199,6 +6192,8 @@ A jump table for the options with a short description can be found at |Q_op|.
is a bug that denotes that new mouse button recognition was
added without modifying code that reacts on mouse clicks on
this label.
Use |getmousepos()|.winid in the specified function to get the
corresponding window id of the clicked item.
< - Where to truncate line if too long. Default is at the start.
No width fields allowed.
= - Separation point between alignment sections. Each section will

6
runtime/doc/support.txt
View File

@@ -14,12 +14,16 @@ Supported platforms *supported-platforms*
`System` `Tier` `Versions` `Tested versions`
Linux 1 >= 2.6.32, glibc >= 2.12 Ubuntu 22.04
macOS (Intel) 1 >= 10.15 macOS 12
Windows 64-bit 1 >= 8 Windows Server 2019
Windows 64-bit 1 >= 8 (see note below) Windows Server 2019
FreeBSD 1 >= 10 FreeBSD 13
macOS (M1) 2 >= 10.15
OpenBSD 2 >= 7
MinGW 2 MinGW-w64
Note: Windows 10 "Version 1809" or later is required for |:terminal|. To check
your Windows version, run the "winver" command and look for "Version xxxx"
(NOT "OS Build").
Support types ~
* Tier 1: Officially supported and tested with CI. Any contributed patch

3
runtime/doc/ui.txt
View File

@@ -809,5 +809,8 @@ events, which the UI must handle.
Sent when |:messages| command is invoked. History is sent as a list of
entries, where each entry is a `[kind, content]` tuple.
["msg_history_clear"] ~
Clear the |:messages| history.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

240
runtime/doc/vim_diff.txt
View File

@@ -13,7 +13,7 @@ centralized reference of the differences.
Type |gO| to see the table of contents.
==============================================================================
1. Configuration *nvim-config*
Configuration *nvim-config*
- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for your |config|.
- Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files.
@@ -21,7 +21,7 @@ centralized reference of the differences.
session information. |shada|
==============================================================================
2. Defaults *nvim-defaults*
Defaults *nvim-defaults*
- Filetype detection is enabled by default. This can be disabled by adding
":filetype off" to |init.vim|.
@@ -72,13 +72,14 @@ centralized reference of the differences.
- 'wildmenu' is enabled
- 'wildoptions' defaults to "pum,tagfile"
- |editorconfig| plugin is enabled, .editorconfig settings are applied.
- |man.lua| plugin is enabled, so |:Man| is available by default.
- |matchit| plugin is enabled. To disable it in your config: >vim
:let loaded_matchit = 1
- |g:vimsyn_embed| defaults to "l" to enable Lua highlighting
Default Mouse ~
DEFAULT MOUSE
*default-mouse* *disable-mouse*
By default the mouse is enabled, and <RightMouse> opens a |popup-menu| with
standard actions ("Cut", "Copy", "Paste", …). Mouse is NOT enabled in
@@ -102,7 +103,7 @@ To remove the "How-to disable mouse" menu item and the separator above it: >vim
aunmenu PopUp.How-to\ disable\ mouse
aunmenu PopUp.-1-
<
Default Mappings ~
DEFAULT MAPPINGS
*default-mappings*
Nvim creates the following default mappings at |startup|. You can disable any
of these in your config by simply removing the mapping, e.g. ":unmap Y".
@@ -115,7 +116,7 @@ of these in your config by simply removing the mapping, e.g. ":unmap Y".
xnoremap # y?\V<C-R>"<CR>
nnoremap & :&&<CR>
<
Default Autocommands ~
DEFAULT AUTOCOMMANDS
*default-autocmds*
Default autocommands exist in the following groups. Use ":autocmd! {group}" to
remove them and ":autocmd {group}" to see how they're defined.
@@ -127,35 +128,36 @@ nvim_cmdwin:
- CmdwinEnter: Limits syntax sync to maxlines=1 in the |cmdwin|.
==============================================================================
3. New Features *nvim-features*
New Features *nvim-features*
MAJOR COMPONENTS
API |API|
Job control |job-control|
LSP framework |lsp|
Lua scripting |lua|
Parsing engine |treesitter|
Providers
Clipboard |provider-clipboard|
Node.js plugins |provider-nodejs|
Python plugins |provider-python|
Ruby plugins |provider-ruby|
Remote plugins |remote-plugin|
Shared data |shada|
Terminal emulator |terminal|
Vimscript parser |nvim_parse_expression()|
XDG base directories |xdg|
- API |API|
- Job control |job-control|
- LSP framework |lsp|
- Lua scripting |lua|
- Parsing engine |treesitter|
- Providers
- Clipboard |provider-clipboard|
- Node.js plugins |provider-nodejs|
- Python plugins |provider-python|
- Ruby plugins |provider-ruby|
- Remote plugins |remote-plugin|
- Shared data |shada|
- Terminal emulator |terminal|
- UI |ui| |--listen| |--server|
- Vimscript parser |nvim_parse_expression()|
- XDG base directories |xdg|
USER EXPERIENCE
Working intuitively and consistently is a major goal of Nvim.
*feature-compile*
- Nvim always includes ALL features, in contrast to Vim (which ships with
various combinations of 100+ optional features). Think of it as a leaner
version of Vim's "HUGE" build. This reduces surface area for bugs, and
removes a common source of confusion and friction for users.
- Nvim always includes ALL features, in contrast to Vim (which ships various
combinations of 100+ optional features). |feature-compile| Think of it as
a leaner version of Vim's "HUGE" build. This reduces surface area for bugs,
and removes a common source of confusion and friction for users.
- Nvim avoids features that cannot be provided on all platforms; instead that
is delegated to external plugins/extensions. E.g. the `-X` platform-specific
@@ -173,6 +175,7 @@ backwards-compatibility cost. Some examples:
- Directories for 'directory' and 'undodir' are auto-created.
- Terminal features such as 'guicursor' are enabled where possible.
- Various "nvim" |cli-arguments| were redesigned.
Some features are built in that otherwise required external plugins:
@@ -180,6 +183,11 @@ Some features are built in that otherwise required external plugins:
ARCHITECTURE
The Nvim UI is "decoupled" from the core editor: all UIs, including the
builtin |TUI| are just plugins that connect to a Nvim server (via |--server|
or |--embed|). Multiple Nvim UI clients can connect to the same Nvim editor
server.
External plugins run in separate processes. |remote-plugin| This improves
stability and allows those plugins to work without blocking the editor. Even
"legacy" Python and Ruby plugins which use the old Vim interfaces (|if_pyth|,
@@ -191,7 +199,7 @@ by Nvim developers.
FEATURES
Command-line highlighting:
Command-line:
The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted
using a built-in Vimscript expression parser. |expr-highlight|
*E5408* *E5409*
@@ -253,34 +261,105 @@ Input/Mappings:
Normal commands:
|gO| shows a filetype-defined "outline" of the current buffer.
|Q| replays the last recorded macro instead of switching to Ex mode (|gQ|).
Options:
'cpoptions' flags: |cpo-_|
'guicursor' works in the terminal
'diffopt' "linematch" feature
'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The
user is prompted whether to trust the file.
'fillchars' flags: "msgsep", "horiz", "horizup",
"horizdown", "vertleft", "vertright", "verthoriz"
'foldcolumn' supports up to 9 dynamic/fixed columns
'guicursor' works in the terminal (TUI)
'inccommand' shows interactive results for |:substitute|-like commands
and |:command-preview| commands
'jumpoptions' "stack" behavior
'jumpoptions' "view" tries to restore the |mark-view| when moving through
the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|.
'laststatus' global statusline support
'mousescroll' amount to scroll by when scrolling with a mouse
'pumblend' pseudo-transparent popupmenu
'scrollback'
'shortmess' "F" flag does not affect output from autocommands
'signcolumn' supports up to 9 dynamic/fixed columns
'statuscolumn' full control of columns using 'statusline' format
'statusline' supports unlimited alignment sections
'tabline' %@Func@foo%X can call any function on mouse-click
'ttimeout', 'ttimeoutlen' behavior was simplified
'winblend' pseudo-transparency in floating windows |api-floatwin|
'winhighlight' window-local highlights
'diffopt' has the option `linematch`.
Providers:
If a Python interpreter is available on your `$PATH`, |:python| and
|:python3| are always available. See |provider-python|.
Shell:
Shell output (|:!|, |:make|, …) is always routed through the UI, so it
cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if
you want to mess up the screen :)
Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|)
if there is too much output. No data is lost, this only affects display and
improves performance. |:terminal| output is never throttled.
|:!| does not support "interactive" commands. Use |:terminal| instead.
(GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)
:!start is not special-cased on Windows.
|system()| does not support writing/reading "backgrounded" commands. |E5677|
Signs:
Signs are removed if the associated line is deleted.
Startup:
|-e| and |-es| invoke the same "improved Ex mode" as -E and -Es.
|-E| and |-Es| read stdin as text (into buffer 1).
|-es| and |-Es| have improved behavior:
- Quits automatically, don't need "-c qa!".
- Skips swap-file dialog.
|-s| reads Normal commands from stdin if the script name is "-".
Reading text (instead of commands) from stdin |--|:
- works by default: "-" file is optional
- works in more cases: |-Es|, file args
TUI:
*:set-termcap*
Start Nvim with 'verbose' level 3 to show terminal capabilities: >
nvim -V3
<
*'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
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.
Vim combines what is in its |builtin-terms| with what it reads from terminfo,
and has a 'ttybuiltin' setting to control how that combination works. Nvim
uses one or the other, it does not attempt to merge the two.
UI/Display:
|Visual| selection highlights the character at cursor. |visual-use|
messages: When showing messages longer than 'cmdheight', only
scroll the message lines, not the entire screen. The
separator line is decorated by |hl-MsgSeparator| and
the "msgsep" flag of 'fillchars'. *msgsep*
Variables:
|v:progpath| is always absolute ("full")
|v:windowid| is always available (for use by external UIs)
Vimscript:
|:redir| nested in |execute()| works.
==============================================================================
4. Upstreamed features *nvim-upstreamed*
Upstreamed features *nvim-upstreamed*
These Nvim features were later integrated into Vim.
@@ -294,17 +373,9 @@ These Nvim features were later integrated into Vim.
- 'statusline' supports unlimited alignment sections
==============================================================================
5. Changed features *nvim-features-changed*
Changed features *nvim-changed*
Nvim always builds with all features, in contrast to Vim which may have
certain features removed/added at compile-time. |feature-compile|
Some Vim features were changed in Nvim, and vice versa.
If a Python interpreter is available on your `$PATH`, |:python| and |:python3|
are always available and may be used simultaneously. See |provider-python|.
|:redir| nested in |execute()| works.
This section lists various low-level details about other behavior changes.
|mkdir()| behaviour changed:
1. Assuming /tmp/foo does not exist and /tmp can be written to
@@ -345,7 +416,7 @@ are always available and may be used simultaneously. See |provider-python|.
|json_encode()| behaviour slightly changed: now |msgpack-special-dict| values
are accepted, but |v:none| is not.
Viminfo text files were replaced with binary (messagepack) ShaDa files.
Viminfo text files were replaced with binary (messagepack) |shada| files.
Additional differences:
- |shada-c| has no effect.
@@ -387,7 +458,7 @@ Commands:
|:wincmd| accepts a count.
`:write!` does not show a prompt if the file was updated externally.
Command line completion:
Command-line:
The meanings of arrow keys do not change depending on 'wildoptions'.
Functions:
@@ -424,46 +495,6 @@ Mappings:
Motion:
The |jumplist| avoids useless/phantom jumps.
Normal commands:
|Q| replays the last recorded macro instead of switching to Ex mode.
Instead |gQ| can be used to enter Ex mode.
Options:
'ttimeout', 'ttimeoutlen' behavior was simplified
'jumpoptions' "stack" behavior
'jumpoptions' "view" tries to restore the |mark-view| when moving through
the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|.
'shortmess' the "F" flag does not affect output from autocommands
'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The user is
prompted whether to trust the file.
Shell:
Shell output (|:!|, |:make|, …) is always routed through the UI, so it
cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if
you want to mess up the screen :)
Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|)
if there is too much output. No data is lost, this only affects display and
improves performance. |:terminal| output is never throttled.
|:!| does not support "interactive" commands. Use |:terminal| instead.
(GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)
:!start is not special-cased on Windows.
|system()| does not support writing/reading "backgrounded" commands. |E5677|
Startup:
|-e| and |-es| invoke the same "improved Ex mode" as -E and -Es.
|-E| and |-Es| read stdin as text (into buffer 1).
|-es| and |-Es| have improved behavior:
- Quits automatically, don't need "-c qa!".
- Skips swap-file dialog.
|-s| reads Normal commands from stdin if the script name is "-".
Reading text (instead of commands) from stdin |--|:
- works by default: "-" file is optional
- works in more cases: |-Es|, file args
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
@@ -472,40 +503,13 @@ Syntax highlighting:
after/syntax/syncolor.vim file should transition that file into a
colorscheme. |:colorscheme|
TUI:
*:set-termcap*
Start Nvim with 'verbose' level 3 to show terminal capabilities: >
nvim -V3
<
*'term'* *E529* *E530* *E531*
'term' reflects the terminal type derived from |$TERM| and other environment
checks. For debugging only; not reliable during startup. >vim
:echo &term
< "builtin_x" means one of the |builtin-terms| was chosen, because the expected
terminfo file was not found on the system.
Nvim will use 256-colour capability on Linux virtual terminals. Vim uses
only 8 colours plus bright foreground on Linux VTs.
Vim combines what is in its |builtin-terms| with what it reads from terminfo,
and has a 'ttybuiltin' setting to control how that combination works. Nvim
uses one or the other, it does not attempt to merge the two.
UI/Display:
|Visual| selection highlights the character at cursor. |visual-use|
messages: When showing messages longer than 'cmdheight', only
scroll the message lines, not the entire screen. The
separator line is decorated by |hl-MsgSeparator| and
the "msgsep" flag of 'fillchars'. *msgsep*
Vimscript compatibility:
`count` does not alias to |v:count|
`errmsg` does not alias to |v:errmsg|
`shell_error` does not alias to |v:shell_error|
`this_session` does not alias to |v:this_session|
Working directory (Vim implemented some of these later than Nvim):
Working directory (Vim implemented some of these after Nvim):
- |DirChanged| and |DirChangedPre| can be triggered when switching to another
window or tab.
- |getcwd()| and |haslocaldir()| may throw errors if the tab page or window
@@ -516,20 +520,15 @@ Working directory (Vim implemented some of these later than Nvim):
working directory. Use `getcwd(-1, -1)` to get the global working directory.
==============================================================================
6. Missing legacy features *nvim-features-missing*
Missing legacy features *nvim-missing*
Some legacy Vim features are not yet implemented:
- *if_lua* : Nvim |Lua| API is not compatible with Vim's "if_lua"
- *if_mzscheme*
- |if_pyth|: *python-bindeval* *python-Function* are not supported
- *if_tcl*
These legacy Vim features are not yet implemented:
*:gui*
*:gvim*
==============================================================================
7. Removed features *nvim-features-removed*
Removed legacy features *nvim-removed*
These Vim features were intentionally removed from Nvim.
@@ -687,6 +686,13 @@ Options:
Performance:
Folds are not updated during insert-mode.
Providers:
- *if_lua* : Nvim |Lua| API is not compatible with Vim's "if_lua".
- *if_mzscheme*
- |if_pyth|: *python-bindeval* *python-Function* are not supported.
- *if_tcl*
Startup:
--literal (file args are always literal; to expand wildcards on Windows, use
|:n| e.g. `nvim +"n *"`)

50
runtime/lua/vim/keymap.lua
View File

@@ -1,51 +1,35 @@
local keymap = {}
--- Add a new |mapping|.
--- Adds a new |mapping|.
--- Examples:
--- <pre>lua
--- -- Can add mapping to Lua functions
--- -- Map to a Lua function:
--- vim.keymap.set('n', 'lhs', function() print("real lua function") end)
---
--- -- Can use it to map multiple modes
--- -- Map to multiple modes:
--- vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true })
---
--- -- Can add mapping for specific buffer
--- -- Buffer-local mapping:
--- vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 })
---
--- -- Expr mappings
--- -- Expr mapping:
--- vim.keymap.set('i', '<Tab>', function()
--- return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
--- end, { expr = true })
--- -- <Plug> mappings
--- -- <Plug> mapping:
--- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
--- </pre>
---
--- Note that in a mapping like:
--- <pre>lua
--- vim.keymap.set('n', 'asdf', require('jkl').my_fun)
--- </pre>
---
--- the ``require('jkl')`` gets evaluated during this call in order to access the function.
--- If you want to avoid this cost at startup you can wrap it in a function, for example:
--- <pre>lua
--- vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end)
--- </pre>
---
---@param mode string|table Same mode short names as |nvim_set_keymap()|.
---@param mode string|table Mode short-name, see |nvim_set_keymap()|.
--- Can also be list of modes to create mapping on multiple modes.
---@param lhs string Left-hand side |{lhs}| of the mapping.
---@param rhs string|function Right-hand side |{rhs}| of the mapping. Can also be a Lua function.
--
---@param opts table|nil A table of |:map-arguments|.
--- + Accepts options accepted by the {opts} parameter in |nvim_set_keymap()|,
--- with the following notable differences:
--- - replace_keycodes: Defaults to `true` if "expr" is `true`.
--- - noremap: Always overridden with the inverse of "remap" (see below).
--- + In addition to those options, the table accepts the following keys:
--- - buffer: (number or boolean) Add a mapping to the given buffer.
--- When `0` or `true`, use the current buffer.
--- - remap: (boolean) Make the mapping recursive.
--- This is the inverse of the "noremap" option from |nvim_set_keymap()|.
---@param rhs string|function Right-hand side |{rhs}| of the mapping, can be a Lua function.
---
---@param opts table|nil Table of |:map-arguments|.
--- - Same as |nvim_set_keymap()| {opts}, except:
--- - "replace_keycodes" defaults to `true` if "expr" is `true`.
--- - "noremap": inverse of "remap" (see below).
--- - Also accepts:
--- - "buffer" number|boolean Creates buffer-local mapping, `0` or `true`
--- for current buffer.
--- - remap: (boolean) Make the mapping recursive. Inverses "noremap".
--- Defaults to `false`.
---@see |nvim_set_keymap()|
function keymap.set(mode, lhs, rhs, opts)

7
runtime/lua/vim/ui.lua
View File

@@ -1,6 +1,7 @@
local M = {}
--- Prompts the user to pick a single item from a collection of entries
--- Prompts the user to pick from a list of items, allowing arbitrary (potentially asynchronous)
--- work until `on_choice`.
---
---@param items table Arbitrary items
---@param opts table Additional options
@@ -35,7 +36,6 @@ local M = {}
--- end
--- end)
--- </pre>
function M.select(items, opts, on_choice)
vim.validate({
items = { items, 'table', false },
@@ -55,7 +55,8 @@ function M.select(items, opts, on_choice)
end
end
--- Prompts the user for input
--- Prompts the user for input, allowing arbitrary (potentially asynchronous) work until
--- `on_confirm`.
---
---@param opts table Additional options. See |input()|
--- - prompt (string|nil)

7
src/nvim/README.md
View File

@@ -81,6 +81,13 @@ Logs will be written to `${HOME}/logs/*san.PID` then.
For more information: https://github.com/google/sanitizers/wiki/SanitizerCommonFlags
Reproducible build
------------------
To make a reproducible build of Nvim, set cmake variable `LUA_GEN_PRG` to
a LuaJIT binary built with `LUAJIT_SECURITY_PRN=0`. See commit
cb757f2663e6950e655c6306d713338dfa66b18d.
Debug: Performance
------------------

29
src/nvim/api/command.c
View File

@@ -899,15 +899,13 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
}
}
/// Create a new user command |user-commands|
/// Creates a global |user-commands| command.
///
/// {name} is the name of the new command. The name must begin with an uppercase letter.
///
/// {command} is the replacement text or Lua function to execute.
/// For Lua usage see |lua-guide-commands-create|.
///
/// Example:
/// <pre>vim
/// :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
/// :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
/// :SayHello
/// Hello world!
/// </pre>
@@ -929,15 +927,16 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin
/// - mods: (string) Command modifiers, if any |<mods>|
/// - smods: (table) Command modifiers in a structured format. Has the same
/// structure as the "mods" key of |nvim_parse_cmd()|.
/// @param opts Optional command attributes. See |command-attributes| for more details. To use
/// boolean attributes (such as |:command-bang| or |:command-bar|) set the value to
/// "true". In addition to the string options listed in |:command-complete|, the
/// "complete" key also accepts a Lua function which works like the "customlist"
/// completion mode |:command-completion-customlist|. Additional parameters:
/// - desc: (string) Used for listing the command when a Lua function is used for
/// {command}.
/// - force: (boolean, default true) Override any previous definition.
/// - preview: (function) Preview callback for 'inccommand' |:command-preview|
/// @param opts Optional |command-attributes|.
/// - Set boolean attributes such as |:command-bang| or |:command-bar| to true (but
/// not |:command-buffer|, use |nvim_buf_create_user_command()| instead).
/// - "complete" |:command-complete| also accepts a Lua function which works like
/// |:command-completion-customlist|.
/// - Other parameters:
/// - desc: (string) Used for listing the command when a Lua function is used for
/// {command}.
/// - force: (boolean, default true) Override any previous definition.
/// - preview: (function) Preview callback for 'inccommand' |:command-preview|
/// @param[out] err Error details, if any.
void nvim_create_user_command(String name, Object command, Dict(user_command) *opts, Error *err)
FUNC_API_SINCE(9)
@@ -955,7 +954,7 @@ void nvim_del_user_command(String name, Error *err)
nvim_buf_del_user_command(-1, name, err);
}
/// Create a new user command |user-commands| in the given buffer.
/// Creates a buffer-local command |user-commands|.
///
/// @param buffer Buffer handle, or 0 for current buffer.
/// @param[out] err Error details, if any.

17
src/nvim/api/vim.c
View File

@@ -1442,15 +1442,14 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
/// or "!" for |:map!|, or empty string for |:map|.
/// @param lhs Left-hand-side |{lhs}| of the mapping.
/// @param rhs Right-hand-side |{rhs}| of the mapping.
/// @param opts Optional parameters map: keys are |:map-arguments|, values are booleans (default
/// false). Accepts all |:map-arguments| as keys excluding |<buffer>| but including
/// |:noremap| and "desc". Unknown key is an error.
/// "desc" can be used to give a description to the mapping.
/// When called from Lua, also accepts a "callback" key that takes a Lua function to
/// call when the mapping is executed.
/// When "expr" is true, "replace_keycodes" (boolean) can be used to replace keycodes
/// in the resulting string (see |nvim_replace_termcodes()|), and a Lua callback
/// returning `nil` is equivalent to returning an empty string.
/// @param opts Optional parameters map: Accepts all |:map-arguments| as keys except |<buffer>|,
/// values are booleans (default false). Also:
/// - "noremap" non-recursive mapping |:noremap|
/// - "desc" human-readable description.
/// - "callback" Lua function called when the mapping is executed.
/// - "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the
/// resulting string (see |nvim_replace_termcodes()|). Returning nil from the Lua
/// "callback" is equivalent to returning an empty string.
/// @param[out] err Error details, if any.
void nvim_set_keymap(uint64_t channel_id, String mode, String lhs, String rhs, Dict(keymap) *opts,
Error *err)