diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 5fd7bc37b6..8795a7306c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -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" diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 1e717ba6c5..f25732f90d 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/lsp_bug_report.yml b/.github/ISSUE_TEMPLATE/lsp_bug_report.yml index f453d3864e..bdad12e412 100644 --- a/.github/ISSUE_TEMPLATE/lsp_bug_report.yml +++ b/.github/ISSUE_TEMPLATE/lsp_bug_report.yml @@ -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: diff --git a/README.md b/README.md index 9471c2324a..7ab0f0ea8f 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 7bcae79852..3ca50dda15 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -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 || 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 ||, 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. diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 87190d7f33..b090fd4f09 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -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: diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index f77db5fab3..bd1b62635e 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -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: diff --git a/runtime/doc/editorconfig.txt b/runtime/doc/editorconfig.txt index 04a057e5ff..52fd860d2d 100644 --- a/runtime/doc/editorconfig.txt +++ b/runtime/doc/editorconfig.txt @@ -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: diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index b971a7d2ad..236905a077 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -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: diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 0472c11a15..32e89bd237 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -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'}, 'lr', vim.lsp.buf.references, { buffer=true }) - - -- Can add mapping for specific buffer + -- Buffer-local mapping: vim.keymap.set('n', 'w', "w", { silent = true, buffer = 5 }) - - -- Expr mappings + -- Expr mapping: vim.keymap.set('i', '', function() return vim.fn.pumvisible() == 1 and "" or "" end, { expr = true }) - -- mappings + -- mapping: vim.keymap.set('n', '[%', '(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()| diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 2260cd8377..f44b6f28e3 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -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. diff --git a/runtime/doc/support.txt b/runtime/doc/support.txt index 481959d8f1..e4641751f2 100644 --- a/runtime/doc/support.txt +++ b/runtime/doc/support.txt @@ -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 diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index 4e4f88f275..bb567e021e 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -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: diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index b274c02945..79808eccc9 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -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 diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua index ef1c66ea20..911b584c14 100644 --- a/runtime/lua/vim/keymap.lua +++ b/runtime/lua/vim/keymap.lua @@ -1,51 +1,35 @@ local keymap = {} ---- Add a new |mapping|. +--- 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'}, 'lr', vim.lsp.buf.references, { buffer=true })
----
----   -- Can add mapping for specific buffer
+---   -- Buffer-local mapping:
 ---   vim.keymap.set('n', 'w', "w", { silent = true, buffer = 5 })
----
----   -- Expr mappings
+---   -- Expr mapping:
 ---   vim.keymap.set('i', '', function()
 ---     return vim.fn.pumvisible() == 1 and "" or ""
 ---   end, { expr = true })
----   --  mappings
+---   --  mapping:
 ---   vim.keymap.set('n', '[%%', '(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)
----
---- ----@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) diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua index 8f5be15221..aaee175f3a 100644 --- a/runtime/lua/vim/ui.lua +++ b/runtime/lua/vim/ui.lua @@ -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) --- - 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) diff --git a/src/nvim/README.md b/src/nvim/README.md index 712fda87ba..0951142555 100644 --- a/src/nvim/README.md +++ b/src/nvim/README.md @@ -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 ------------------ diff --git a/src/nvim/api/command.c b/src/nvim/api/command.c index 6d63ae5e24..32378ed244 100644 --- a/src/nvim/api/command.c +++ b/src/nvim/api/command.c @@ -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: /// 
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!
 ///
@@ -929,15 +927,16 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin /// - mods: (string) Command modifiers, if any || /// - 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. diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 3a93005841..0f27040fd3 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -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 || 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 ||, +/// 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)