opensourcemirror
/
neovim
mirror of https://github.com/neovim/neovim.git
1
0
Fork 0
Code Issues Releases Wiki Activity

docs: naming conventions, guidelines 

close #21063
This commit is contained in:
Justin M. Keyes 2022-12-14 19:58:18 +01:00
parent 0b36145c69
commit 6752f1005d
19 changed files with 286 additions and 286 deletions
Show Stats 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()|

35
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.

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:

1
runtime/doc/vim_diff.txt
View File

@ -72,6 +72,7 @@ Defaults *nvim-defaults*
- '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

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)