wyj/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-09-17 20:58:20 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge #28747 from justinmk/doc

Browse Source
This commit is contained in:
Justin M. Keyes 2024-05-15 15:44:10 -07:00 committed by GitHub
commit 7c13d1a4a8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
20 changed files with 503 additions and 628 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
CONTRIBUTING.md
View File

@ -114,11 +114,6 @@ the VCS/git logs more valuable. The structure of a commit message is:
BREAKING CHANGE: refactor to use Python 3 features since Python 2 is no longer supported.
```
### News
High level release notes are maintained in [news.txt](runtime/doc/news.txt). A PR is not required to add a news item
but is generally recommended.
### Automated builds (CI)
Each pull request must pass the automated builds on [Cirrus CI] and [GitHub Actions].

64
MAINTAIN.md
View File

@ -50,10 +50,9 @@ has a major bug:
1. Fix the bug on `master`.
2. Cherry-pick the fix to `release-x.y`.
3. Cut a release from `release-x.y`.
* Run `./scripts/release.sh`
* Update (force-push) the remote `stable` tag.
* Run `./scripts/release.sh` (requires [git cliff](https://github.com/orhun/git-cliff))
* The [CI job](https://github.com/neovim/neovim/blob/3d45706478cd030c3ee05b4f336164bb96138095/.github/workflows/release.yml#L11-L13)
will update the release assets and force-push to the `stable` tag.
will update the release assets and [force-push to the "stable" tag](https://github.com/neovim/neovim/blob/cdd87222c86c5b2274a13d36f23de0637462e317/.github/workflows/release.yml#L229).
### Release automation
@ -72,39 +71,37 @@ inform users of the change.
When a (non-experimental) feature is slated to be removed it should:
1. Be _soft_ deprecated in the _next_ release
- Use of the deprecated feature will still work.
- This means deprecating via documentation and annotation (`@deprecated`).
- Include a note in `deprecated.txt`.
- For Lua features, use `vim.deprecate()`. The specified version is the
current minor version + 2. For example, if the current version is
`v0.10.0-dev-1957+gd676746c33` then use `0.12`.
- For Vimscript features, use `v:lua.vim.deprecate()`. Use the same version
as described for Lua features.
- Use of the deprecated feature will still work.
- This means deprecating via documentation and annotation (`@deprecated`).
- Include a note in `deprecated.txt`.
- For Lua features, use `vim.deprecate()`. The specified version is the
current minor version + 2. For example, if the current version is
`v0.10.0-dev-1957+gd676746c33` then use `0.12`.
- For Vimscript features, use `v:lua.vim.deprecate()`. Use the same version
as described for Lua features.
2. Be _hard_ deprecated in a following a release in which it was soft deprecated.
- Use of the deprecated feature will still work but should issue a warning.
- Features implemented in C will need bespoke implementations to communicate
to users that the feature is deprecated.
- Use of the deprecated feature will still work but should issue a warning.
- Features implemented in C will need bespoke implementations to communicate
to users that the feature is deprecated.
3. Be removed in a release following the release in which it was hard deprecated
- Usually this will be the next release, but it may be a later release if a
longer deprecation cycle is desired
- If possible, keep the feature as a stub (e.g. function API) and issue an error
when it is accessed.
- Usually this will be the next release, but it may be a later release if
a longer deprecation cycle is desired
- If possible, keep the feature as a stub (e.g. function API) and issue an
error when it is accessed.
Example:
```
Deprecation Removal
┆ ┆ ┆
┆ Soft ┆ Hard ┆
┆ Deprecation ┆ Deprecation ┆
┆ Period ┆ Period ┆
────────────────────────────────────────────────────────────
Version: 0.10 0.11 0.12
────────────────────────────────────────────────────────────
Old code Old code Old code
+ +
New code New code New code
```
Deprecation Removal
┆ ┆ ┆
┆ Soft ┆ Hard ┆
┆ Deprecation ┆ Deprecation ┆
┆ Period ┆ Period ┆
────────────────────────────────────────────────────────────
Version: 0.10 0.11 0.12
────────────────────────────────────────────────────────────
Old code Old code Old code
+ +
New code New code New code
Feature removals which may benefit from community input or further discussion
should also have a tracking issue (which should be linked to in the release
@ -133,11 +130,11 @@ Some can be auto-bumped by `scripts/bump_deps.lua`.
* [libiconv](https://ftp.gnu.org/pub/gnu/libiconv)
* [libuv](https://github.com/libuv/libuv)
* [libvterm](https://www.leonerd.org.uk/code/libvterm/)
* Downloading from the original source is unreliable, so we use our [mirror](https://github.com/neovim/libvterm) instead.
* Downloading from the original source is unreliable, so we use our [mirror](https://github.com/neovim/libvterm) instead.
* [lua-compat](https://github.com/keplerproject/lua-compat-5.3)
* [tree-sitter](https://github.com/tree-sitter/tree-sitter)
* [unibilium](https://github.com/neovim/unibilium)
* The original project [was abandoned](https://github.com/neovim/neovim/issues/10302), so the [neovim/unibilium](https://github.com/neovim/unibilium) fork is considered "upstream" and is maintained on the `master` branch.
* The original project [was abandoned](https://github.com/neovim/neovim/issues/10302), so the [neovim/unibilium](https://github.com/neovim/unibilium) fork is considered "upstream" and is maintained on the `master` branch.
* [treesitter parsers](https://github.com/neovim/neovim/blob/7e97c773e3ba78fcddbb2a0b9b0d572c8210c83e/cmake.deps/deps.txt#L47-L62)
### Vendored dependencies
@ -210,7 +207,6 @@ https://github.com/neovim/neovim-backup
* Avoid macOS if an Ubuntu or a Windows runner can be used instead. This is
because macOS runners have [tighter restrictions on the number of concurrent
jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).
* Runner versions:
* For special-purpose jobs where the runner version doesn't really matter,
prefer `-latest` tags so we don't need to manually bump the versions. An

28
runtime/doc/deprecated.txt
View File

@ -79,20 +79,20 @@ DEPRECATED IN 0.9 *deprecated-0.9*
- *nvim_get_hl_by_id()* Use |nvim_get_hl()| instead.
• The following top level Treesitter functions have been moved:
*vim.treesitter.inspect_language()* -> |vim.treesitter.language.inspect()|
*vim.treesitter.get_query_files()* -> |vim.treesitter.query.get_files()|
*vim.treesitter.set_query()* -> |vim.treesitter.query.set()|
*vim.treesitter.query.set_query()* -> |vim.treesitter.query.set()|
*vim.treesitter.get_query()* -> |vim.treesitter.query.get()|
*vim.treesitter.query.get_query()* -> |vim.treesitter.query.get()|
*vim.treesitter.parse_query()* -> |vim.treesitter.query.parse()|
*vim.treesitter.query.parse_query()* -> |vim.treesitter.query.parse()|
*vim.treesitter.add_predicate()* -> |vim.treesitter.query.add_predicate()|
*vim.treesitter.add_directive()* -> |vim.treesitter.query.add_directive()|
*vim.treesitter.list_predicates()* -> |vim.treesitter.query.list_predicates()|
*vim.treesitter.list_directives()* -> |vim.treesitter.query.list_directives()|
*vim.treesitter.query.get_range()* -> |vim.treesitter.get_range()|
*vim.treesitter.query.get_node_text()* -> |vim.treesitter.get_node_text()|
- *vim.treesitter.inspect_language()* -> |vim.treesitter.language.inspect()|
- *vim.treesitter.get_query_files()* -> |vim.treesitter.query.get_files()|
- *vim.treesitter.set_query()* -> |vim.treesitter.query.set()|
- *vim.treesitter.query.set_query()* -> |vim.treesitter.query.set()|
- *vim.treesitter.get_query()* -> |vim.treesitter.query.get()|
- *vim.treesitter.query.get_query()* -> |vim.treesitter.query.get()|
- *vim.treesitter.parse_query()* -> |vim.treesitter.query.parse()|
- *vim.treesitter.query.parse_query()* -> |vim.treesitter.query.parse()|
- *vim.treesitter.add_predicate()* -> |vim.treesitter.query.add_predicate()|
- *vim.treesitter.add_directive()* -> |vim.treesitter.query.add_directive()|
- *vim.treesitter.list_predicates()* -> |vim.treesitter.query.list_predicates()|
- *vim.treesitter.list_directives()* -> |vim.treesitter.query.list_directives()|
- *vim.treesitter.query.get_range()* -> |vim.treesitter.get_range()|
- *vim.treesitter.query.get_node_text()* -> |vim.treesitter.get_node_text()|
• Lua stdlib:
- *nvim_exec()* Use |nvim_exec2()| instead.

2
runtime/doc/dev_style.txt
View File

@ -6,7 +6,7 @@
Nvim style guide *dev-style*
This is style guide for developers working on Nvim's source code.
Style guidelines for developers working Nvim's source code.
License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/

28
runtime/doc/dev_theme.txt
View File

@ -4,9 +4,9 @@
NVIM REFERENCE MANUAL
Nvim theme style guide *dev-theme*
Nvim colorscheme guidelines *dev-theme*
This is style guide for developers working on Nvim's default color scheme.
Style guidelines for developing Nvim's default colorscheme.
License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/
@ -17,19 +17,15 @@ Design
- Be "Neovim branded", i.e. have mostly "green-blue" feel plus one or two
colors reserved for very occasional user attention.
- Be oriented for 'termguicolors' (true colors) while being extra minimal for
'notermguicolors' (16 colors) as fallback.
- Be accessible, i.e. have high enough contrast ratio (as defined in
https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef).
This means to have value at least 7 for |hl-Normal| and 4.5 for some common
cases (|hl-Visual|, `Comment` with set 'cursorline', colored syntax, `Diff*`,
|hl-Search|).
- Be suitable for dark and light backgrounds via exchange of dark and light
palettes.
- Be usable, i.e. provide enough visual feedback for common objects.
@ -38,39 +34,29 @@ Palettes
- There are two separate palettes: dark and light. They all contain the same
set of colors exported as `NvimDark*` and `NvimLight*` colors respectively.
- The dark palette is used for background in the dark color scheme and for
foreground in the light color scheme; and vice versa. This introduces
recognizable visual system without too standing out.
- Actual computation of palettes should be done in a perceptually uniform
color space. Oklch is a good choice.
- Each palette has the following colors (descriptions are for dark background;
reverse for light one):
- Four shades of colored "cold" greys for general UI.
- Dark ones (from darkest to lightest) are reserved as background for
|hl-NormalFloat| (considered as "black"), |hl-Normal| (background),
|hl-CursorLine|, |hl-Visual|.
- Light ones (also from darkest to lightest) are reserved for
`Comment`, |hl-StatusLine|/|hl-TabLine|, |hl-Normal| (foreground),
and color considered as "white".
- Six colors to provide enough terminal colors: red, yellow, green, cyan,
blue, magenta.
They should have (reasonably) similar lightness and chroma to make them
visually coherent. Lightness should be as equal to the palette's basic grey
(which is used for |hl-Normal|) as possible. They should have (reasonably)
different hues to make them visually separable.
- For 16 colors:
- Greys are not used and are replaced with the foreground and background
colors of the terminal emulator.
- Non-grey colors fall back to terminal colors as ordered in ANSI codes
(https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit),
that is red (1, 9), green (2, 10), yellow (3, 11), blue (4, 12),
@ -78,33 +64,25 @@ Palettes
To increase contrast, colors 1-6 are used for light background and 9-14
for dark background.
==============================================================================
Highlight groups
Use:
- Grey shades for general UI according to their design.
- Bold text for keywords (`Statement` highlight group). This is an important
choice to increase accessibility for people with color deficiencies, as it
doesn't rely on actual color.
- Green for strings, |hl-DiffAdd| (as background), |hl-DiagnosticOk|, and some
minor text UI elements.
- Cyan as main syntax color, i.e. for function usage (`Function` highlight
group), |hl-DiffText|, |hl-DiagnosticInfo|, and some minor text UI elements.
- Red to generally mean high user attention, i.e. errors; in particular for
|hl-ErrorMsg|, |hl-DiffDelete|, |hl-DiagnosticError|.
- Yellow very sparingly to mean mild user attention, i.e. warnings. That is,
|hl-DiagnosticWarn| and |hl-WarningMsg|.
- Blue very sparingly as |hl-DiagnosticHint| and some additional important
syntax group (like `Identifier`).
- Magenta very carefully (if at all).
In case of 16 colors:
@ -113,9 +91,7 @@ In case of 16 colors:
colors can be used as foreground". This means that in any
foreground/background combination there should be background and one
non-background color.
- Use 0 (black) or 15 (bright white) as foreground for non-grey background,
depending on whether normal background is light or dark.
vim:tw=78:ts=8:et:ft=help:norl:

67
runtime/doc/develop.txt
View File

@ -4,7 +4,7 @@
NVIM REFERENCE MANUAL
Development of Nvim *development* *dev*
Development of Nvim *development* *dev*
This reference describes design constraints and guidelines, for developing
Nvim applications or Nvim itself.
@ -16,13 +16,13 @@ Nvim is free and open source. Everybody is encouraged to contribute.
Type |gO| to see the table of contents.
==============================================================================
Design goals *design-goals*
Design goals *design-goals*
Most important things come first (roughly). Some items conflict; this is
intentional. A balance must be found.
NVIM IS... IMPROVED *design-improved*
NVIM IS... IMPROVED *design-improved*
The Neo bits of Nvim should make it a better Vim, without becoming a
completely different editor.
@ -35,7 +35,7 @@ completely different editor.
never break.
NVIM IS... WELL DOCUMENTED *design-documented*
NVIM IS... WELL DOCUMENTED *design-documented*
- A feature that isn't documented is a useless feature. A patch for a new
feature must include the documentation.
@ -44,7 +44,7 @@ NVIM IS... WELL DOCUMENTED *design-documented*
item is easier to find.
NVIM IS... FAST AND SMALL *design-speed-size*
NVIM IS... FAST AND SMALL *design-speed-size*
Keep Nvim small and fast. This directly affects versatility and usability.
- Computers are becoming faster and bigger each year. Vim can grow too, but
@ -59,7 +59,7 @@ Keep Nvim small and fast. This directly affects versatility and usability.
("composability").
NVIM IS... MAINTAINABLE *design-maintain*
NVIM IS... MAINTAINABLE *design-maintain*
- The source code should not become a mess. It should be reliable code.
- Use comments in a useful way! Quoting the function name and argument names
@ -70,7 +70,7 @@ NVIM IS... MAINTAINABLE *design-maintain*
knowledge spread to other parts of the code.
NVIM IS... NOT *design-not*
NVIM IS... NOT *design-not*
Nvim is not an operating system; instead it should be composed with other
tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
@ -78,10 +78,10 @@ include the kitchen sink... but it's good for plumbing."
==============================================================================
Developer guidelines *dev-guidelines*
Developer guidelines *dev-guidelines*
PROVIDERS *dev-provider*
PROVIDERS *dev-provider*
A primary goal of Nvim is to allow extension of the editor without special
knowledge in the core. Some core functions are delegated to "providers"
@ -115,7 +115,7 @@ For example, the Python provider is implemented by the
to 2 only if a valid external Python host is found. Then `has("python")`
reflects whether Python support is working.
*provider-reload*
*provider-reload*
Sometimes a GUI or other application may want to force a provider to
"reload". To reload a provider, undefine its "loaded" flag, then use
|:runtime| to reload it: >vim
@ -124,7 +124,7 @@ Sometimes a GUI or other application may want to force a provider to
:runtime autoload/provider/clipboard.vim
DOCUMENTATION *dev-doc*
DOCUMENTATION *dev-doc*
- "Just say it". Avoid mushy, colloquial phrasing in all documentation
(docstrings, user manual, website materials, newsletters, …). Don't mince
@ -230,7 +230,7 @@ in src/nvim/api/win_config.c like this: >
Lua docstrings ~
*dev-lua-doc*
*dev-lua-doc*
Lua documentation lives in the source code, as docstrings on the function
definitions. The |lua-vim| :help is generated from the docstrings.
@ -289,7 +289,7 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
--- @returns false if client should cancel the paste.
LUA STDLIB DESIGN GUIDELINES *dev-lua*
LUA STDLIB DESIGN GUIDELINES *dev-lua*
See also |dev-naming|.
@ -304,19 +304,22 @@ See also |dev-naming|.
- 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
iterable, because the input needs to be "reified"; 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.
- when a result-or-error interface is needed, return `result|nil, errmsg|nil`: >
- when a result-or-error interface is needed, return `result|nil, nil|errmsg`: >
---@return Foo|nil # Result object, or nil if not found.
---@return nil|string # Error message on failure, or nil on success.
<
- Examples: |vim.ui.open()| |io.open()| |luv-error-handling|
*dev-patterns*
Interface conventions ~
Where possible, these patterns apply to _both_ Lua and the API:
- When accepting a buffer id, etc., 0 means "current buffer", nil means "all
buffers". Likewise for window id, tabpage id, etc.
- Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()|
@ -327,8 +330,19 @@ Interface conventions ~
filter(table, opts, function() … end)
BAD:
filter(function() … end, table, opts)
- "Enable" ("toggle") interface and behavior:
- `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the
the "global" enablement of a feature.
- `is_enabled(nil)` and `is_enabled({buf=nil})`, likewise, query the
global state of the feature.
- `enable(…, {buf: number})` sets a buffer-local "enable" flag.
- `is_enabled({buf: number})`, likewise, queries the buffer-local state of
the feature.
- See |vim.lsp.inlay_hint.enable()| and |vim.lsp.inlay_hint.is_enabled()|
for a reference implementation of these "best practices".
- NOTE: open questions: https://github.com/neovim/neovim/issues/28603
API DESIGN GUIDELINES *dev-api*
API DESIGN GUIDELINES *dev-api*
See also |dev-naming|.
@ -368,7 +382,7 @@ Naming conventions ~
In general, look for precedent when choosing a name, that is, look at existing
(non-deprecated) functions. In particular, see below...
*dev-name-common*
*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"?)
@ -424,7 +438,7 @@ Do NOT use these deprecated nouns:
- command Use "cmd" instead
- window Use "win" instead
*dev-name-events*
*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.
@ -438,7 +452,7 @@ Use this format to name API (RPC) events: >
Example: >
nvim_buf_changedtick_event
<
*dev-name-api*
*dev-api-name*
Use this format to name new RPC |API| functions: >
nvim_{topic}_{verb}_{arbitrary-qualifiers}
@ -458,7 +472,7 @@ be a parameter (typically manifest as mutually-exclusive buf/win/… flags like
and uses the "del" {verb}.
INTERFACE PATTERNS *dev-patterns*
INTERFACE PATTERNS *dev-api-patterns*
Prefer adding a single `nvim_{topic}_{verb}_…` interface for a given topic.
@ -510,9 +524,9 @@ recommended (compare these 12(!) functions to the above 3 functions): >
nvim_win_get_ns(…)
nvim_tabpage_get_ns(…)
API-CLIENT *dev-api-client*
API-CLIENT *dev-api-client*
*api-client*
*api-client*
API clients wrap the Nvim |API| to provide idiomatic "SDKs" for their
respective platforms (see |jargon|). You can build a new API client for your
favorite platform or programming language.
@ -520,9 +534,10 @@ favorite platform or programming language.
List of API clients:
https://github.com/neovim/neovim/wiki/Related-projects#api-clients
*pynvim*
The Python client is the reference implementation for API clients.
https://github.com/neovim/pynvim
*node-client* *pynvim*
These clients can be considered the "reference implementation" for API clients:
- https://github.com/neovim/node-client
- https://github.com/neovim/pynvim
Standard Features ~
@ -573,7 +588,7 @@ API client implementation guidelines ~
https://github.com/msgpack-rpc/msgpack-rpc
EXTERNAL UI *dev-ui*
EXTERNAL UI *dev-ui*
External UIs should be aware of the |api-contract|. In particular, future
versions of Nvim may add new items to existing events. The API is strongly

3
runtime/doc/lsp.txt
View File

@ -1611,7 +1611,8 @@ get({filter}) *vim.lsp.inlay_hint.get()*
local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
local client = vim.lsp.get_client_by_id(hint.client_id)
resolved_hint = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0).result
local resp = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0)
local resolved_hint = assert(resp and resp.result, resp.err)
vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding)
location = resolved_hint.label[1].location

49
runtime/doc/lua.txt
View File

@ -34,10 +34,11 @@ Nvim ever ships with Lua 5.4+, a Lua 5.1 compatibility shim will be provided
so that old plugins continue to work transparently.
*lua-luajit*
Nvim is built with luajit on platforms which support it, which provides
extra functionality. Lua code in |init.lua| and plugins can assume its presence
on installations on common platforms. For maximum compatibility with less
common platforms, availability can be checked using the `jit` global variable: >lua
On supported platforms, Nvim is built with LuaJIT, which provides extra
functionality (compared to PUC Lua) such as "bit" and various utilities (see
|lua-profile|). Lua code in |init.lua| and plugins can assume its presence on
many platforms, but for maximum compatibility should check the `jit` global
variable: >lua
if jit then
-- code for luajit
else
@ -45,9 +46,21 @@ common platforms, availability can be checked using the `jit` global variable: >
end
<
*lua-bit*
In particular, the luajit "bit" extension module is _always_ available.
A fallback implementation is included when nvim is built with PUC Lua 5.1,
and will be transparently used when `require("bit")` is invoked.
The LuaJIT "bit" extension module is _always_ available: when built with PUC
Lua, Nvim includes a fallback implementation which provides `require("bit")`.
*lua-profile*
To profile Lua code (with LuaJIT-enabled Nvim), the basic steps are: >lua
-- Start a profiling session:
require('jit.p').start('ri1', '/tmp/profile')
-- Perform arbitrary tasks (use plugins, scripts, etc.) ...
-- Stop the session. Profile is written to /tmp/profile.
require('jit.p').stop()
See https://luajit.org/ext_profiler.html or the "p.lua" source for details: >
:lua vim.cmd.edit(package.searchpath('jit.p', package.path))
==============================================================================
LUA CONCEPTS AND IDIOMS *lua-concepts*
@ -244,8 +257,8 @@ arguments separated by " " (space) instead of "\t" (tab).
*:lua=* *:lua*
:lua {chunk}
Executes Lua chunk {chunk}. If {chunk} starts with "=" the rest of the
chunk is evaluated as an expression and printed. `:lua =expr` or `:=expr` is
equivalent to `:lua print(vim.inspect(expr))`.
chunk is evaluated as an expression and printed. `:lua =expr` and `:=expr`
are equivalent to `:lua vim.print(expr)`.
Examples: >vim
:lua vim.api.nvim_command('echo "Hello, Nvim!"')
@ -3060,11 +3073,10 @@ vim.glob.to_lpeg({pattern}) *vim.glob.to_lpeg()*
VIM.LPEG *vim.lpeg*
LPeg is a pattern-matching library for Lua, based on
Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
LPeg is a pattern-matching library for Lua, based on Parsing Expression
Grammars (PEGs). https://bford.info/packrat/
*lua-lpeg*
*vim.lpeg.Pattern*
*lua-lpeg* *vim.lpeg.Pattern*
The LPeg library for parsing expression grammars is included as `vim.lpeg`
(https://www.inf.puc-rio.br/~roberto/lpeg/).
@ -3457,10 +3469,11 @@ vim.lpeg.version() *vim.lpeg.version()*
VIM.RE *vim.re*
The `vim.re` module provides a conventional regex-like syntax for pattern
usage within LPeg |vim.lpeg|.
usage within LPeg |vim.lpeg|. (Unrelated to |vim.regex| which provides Vim
|regexp| from Lua.)
See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
documentation including regex syntax and more concrete examples.
documentation including regex syntax and examples.
vim.re.compile({string}, {defs}) *vim.re.compile()*
@ -4342,10 +4355,10 @@ vim.snippet.expand({input}) *vim.snippet.expand()*
• {input} (`string`)
vim.snippet.jump({direction}) *vim.snippet.jump()*
Jumps within the active snippet in the given direction. If the jump isn't
possible, the function call does nothing.
Jumps to the next (or previous) placeholder in the current snippet, if
possible.
You can use this function to navigate a snippet as follows: >lua
For example, map `<Tab>` to jump while a snippet is active: >lua
vim.keymap.set({ 'i', 's' }, '<Tab>', function()
if vim.snippet.active({ direction = 1 }) then
return '<cmd>lua vim.snippet.jump(1)<cr>'

2
runtime/doc/news-0.9.txt
View File

@ -4,7 +4,7 @@
NVIM REFERENCE MANUAL
Notable changes in Nvim 0.9 from 0.8 *news-0.9*
Notable changes since Nvim 0.8 *news-0.9*
Type |gO| to see the table of contents.

736
runtime/doc/news.txt
View File

@ -13,200 +13,139 @@ For changes in the previous release, see |news-0.9|.
==============================================================================
BREAKING CHANGES *news-breaking*
The following changes may require adaptations in user config or plugins.
These changes may require adaptations in your config or plugins.
• In some cases, the cursor in the Nvim |TUI| used to blink even without
configuring 'guicursor' as mentioned in |cursor-blinking|. This was a bug
that has now been fixed. If your cursor has stopped blinking, add the
following (or similar, adapted to user preference) to your |config| file: >vim
• API:
• |nvim_open_win()| now blocks all autocommands when `noautocmd` is set,
rather than just those from setting the `buffer` to display in the window.
set guicursor+=n-v-c:blinkon500-blinkoff500
• Defaults:
• Default color scheme has been updated to be "Nvim branded" and accessible.
Use `:colorscheme vim` to revert to the old legacy color scheme.
• These Nvim specific highlight groups are now defined in a meaningfully
different way and might need an update:
• |hl-FloatBorder| is linked to |hl-NormalFloat| instead of |hl-WinSeparator|.
• |hl-NormalFloat| is not linked to |hl-Pmenu|.
• |hl-WinBar| has different background.
• |hl-WinBarNC| is similar to |hl-WinBar| but not bold.
• |hl-WinSeparator| is linked to |hl-Normal| instead of |hl-VertSplit|.
• This also might result into some color schemes looking differently due
to them relying on implicit assumptions about how highlight groups are
defined by default. To account for this, define all attributes of
highlight groups explicitly. Alternatively, use `:colorscheme vim` or
`:source $VIMRUNTIME/colors/vim.lua` to restore previous definitions.
• 'termguicolors' is enabled by default when Nvim is able to determine that
the host terminal emulator supports 24-bit color.
• Editor
• When switching windows, |CursorMoved| autocommands trigger when Nvim is
back in the main loop rather than immediately. This is more compatible
with Vim.
• "#" followed by a digit no longer stands for a function key at the start
of the lhs of a mapping.
• |shm-q| now fully hides macro recording message instead of only shortening it.
• Signs placed through the legacy |sign-commands| are now stored and
displayed as |extmarks| internally. Along with the following changes:
• A sign placed twice in the same group with the same identifier will be
moved.
• Legacy signs are always deleted along with the line it is placed on.
• Legacy and extmark signs will show up in both |:sign-place-list| and
|nvim_buf_get_extmarks()|.
• Legacy and extmark signs are displayed and listed with the same priority:
line number -> priority -> sign id -> recently placed
• `:behave` was removed.
- If you used `:behave xterm`, the following is equivalent: >vim
set mousemodel=extend
<
• |vim.islist()| now checks whether a table is actually list-like (i.e.,
has integer keys without gaps and starting from 1). For the previous
behavior (only check for integer keys, allow gaps or not starting with 1),
use |vim.isarray()|.
- If you used `:behave mswin`, the following is equivalent: >vim
• "#" followed by a digit no longer stands for a function key at the start of
the lhs of a mapping.
• `:behave` was removed.
- If you used `:behave xterm`, the following is equivalent: >vim
set mousemodel=extend
set selection=exclusive
set selectmode=mouse,key
set mousemodel=popup
set keymodel=startsel,stopsel
<
- If you used `:behave mswin`, the following is equivalent: >vim
set selection=exclusive
set selectmode=mouse,key
set mousemodel=popup
set keymodel=startsel,stopsel
• Events
• Returning any truthy value from a callback passed to
|nvim_create_autocmd()| (rather than just `true`) will delete the
autocommand.
• LSP
• |LanguageTree:parse()| will no longer parse injections by default and now
requires an explicit range argument to be passed. If injections are
required, provide an explicit range via `parser:parse({ start_row, end_row })`.
• |vim.lsp.util.parse_snippet()| will now strictly follow the snippet
grammar defined by LSP, and hence previously parsed snippets might now be
considered invalid input.
• |vim.lsp.codelens.refresh()| now takes an `opts` argument. With this
change, the default behavior of just refreshing the current buffer has
been replaced by refreshing all buffers.
• |vim.lsp.util.extract_completion_items()| will no longer return reliable
results, since it does not apply `itemDefaults` when its input is
a `CompletionList`. Moreover, since support for LSP
`completionList.itemDefaults` was added, some third party plugins might be
negatively impacted in case the language servers support the feature but
the plugin does not. If necessary, the respective capability can be
removed when calling |vim.lsp.protocol.make_client_capabilities()|.
• |LspRequest| and LspProgressUpdate (renamed to |LspProgress|) autocmds
were promoted from a |User| autocmd to first class citizen.
• Lua:
• |-l| ensures output ends with a newline if the script prints messages and
doesn't cause Nvim to exit.
• Removed functions from the |vim.json| module:
• Unnecessary, undocumented functions which caused global side-effects.
• `vim.json.null` is redundant with `vim.NIL`.
• `vim.json.array_mt` (and related) is redundant with `vim.empty_dict()`.
• |vim.islist()| now checks whether a table is actually list-like (i.e., has
integer keys without gaps and starting from 1). For the previous behavior
(only check for integer keys, allow gaps or not starting with 1), use
|vim.isarray()|.
• Renamed `vim.treesitter.playground` to `vim.treesitter.dev`.
• Options
• Removed some Vim 5.0<= option compatibilities:
• 'backspace' no longer supports number values. Instead:
• for `backspace=0` set `backspace=` (empty)
• for `backspace=1` set `backspace=indent,eol`
• for `backspace=2` set `backspace=indent,eol,start` (default behavior in Nvim)
• for `backspace=3` set `backspace=indent,eol,nostop`
• 'backupdir' and 'directory' will no longer remove a `>` at the start of
the option.
• |OptionSet| autocommand args |v:option_new|, |v:option_old|,
|v:option_oldlocal|, |v:option_oldglobal| now have the type of the option
instead of always being strings. |v:option_old| is now the old global
value for all global-local options, instead of just string global-local
options.
• Local value for a global-local number/boolean option is now unset when the
option is set (e.g. using |:set| or |nvim_set_option_value()|) without
a scope, which means they now behave the same way as string options.
• Plugins:
• |:TOhtml| has been rewritten in Lua to support Neovim-specific
decorations, and many options have been removed.
• Treesitter
• Treesitter highlight groups have been renamed to be more in line with
upstream tree-sitter and Helix to make it easier to share queries. The
full list is documented in |treesitter-highlight-groups|.
• TUI
• In some cases, the cursor in the Nvim |TUI| used to blink even without
configuring 'guicursor' as mentioned in |cursor-blinking|. This was a bug
that has now been fixed. If your cursor has stopped blinking, add the
following (or similar, adapted to user preference) to your |config| file: >vim
set guicursor+=n-v-c:blinkon500-blinkoff500
<
• When switching windows, |CursorMoved| autocommands trigger when Nvim is back
in the main loop rather than immediately. This is more compatible with Vim.
• |-l| ensures output ends with a newline if the script prints messages and
doesn't cause Nvim to exit.
• |LspRequest| and LspProgressUpdate (renamed to |LspProgress|) autocmds were
promoted from a |User| autocmd to first class citizen.
• Renamed `vim.treesitter.playground` to `vim.treesitter.dev`.
• Removed functions from the |vim.json| module:
• Unnecessary, undocumented functions which caused global side-effects.
• `vim.json.null` is redundant with `vim.NIL`.
• `vim.json.array_mt` (and related) is redundant with `vim.empty_dict()`.
• Removed some Vim 5.0<= option compatibilities:
• |'backspace'| no longer supports number values. Instead:
• for `backspace=0` set `backspace=` (empty)
• for `backspace=1` set `backspace=indent,eol`
• for `backspace=2` set `backspace=indent,eol,start` (default behavior in Nvim)
• for `backspace=3` set `backspace=indent,eol,nostop`
• |'backupdir'| and |'directory'| will no longer remove a `>` at the start
of the option.
• |LanguageTree:parse()| will no longer parse injections by default and
now requires an explicit range argument to be passed. If injections are
required, provide an explicit range via `parser:parse({ start_row, end_row })`.
• |vim.lsp.util.parse_snippet()| will now strictly follow the snippet grammar
defined by LSP, and hence previously parsed snippets might now be considered
invalid input.
• |OptionSet| autocommand args |v:option_new|, |v:option_old|,
|v:option_oldlocal|, |v:option_oldglobal| now have the type of the option
instead of always being strings. |v:option_old| is now the old global value
for all global-local options, instead of just string global-local options.
• Local value for a global-local number/boolean option is now unset when
the option is set (e.g. using |:set| or |nvim_set_option_value()|) without a
scope, which means they now behave the same way as string options.
• Signs placed through the legacy |sign-commands| are now stored and displayed
as |extmarks| internally. Along with the following changes:
• A sign placed twice in the same group with the same identifier will be moved.
• Legacy signs are always deleted along with the line it is placed on.
• Legacy and extmark signs will show up in both |:sign-place-list| and |nvim_buf_get_extmarks()|.
• Legacy and extmark signs are displayed and listed with the same priority:
line number -> priority -> sign id -> recently placed
• Default color scheme has been updated to be "Nvim branded" and accessible.
Use `:colorscheme vim` to revert to the old legacy color scheme.
Here is a list of Nvim specific highlight groups which are now defined in
a meaningfully different way and might need an update:
• |hl-FloatBorder| is linked to |hl-NormalFloat| instead of |hl-WinSeparator|.
• |hl-NormalFloat| is not linked to |hl-Pmenu|.
• |hl-WinBar| has different background.
• |hl-WinBarNC| is similar to |hl-WinBar| but not bold.
• |hl-WinSeparator| is linked to |hl-Normal| instead of |hl-VertSplit|.
This also might result into some color schemes looking differently due to
them relying on implicit assumptions about how highlight groups are defined
by default. To account for this, define all attributes of highlight groups
explicitly. Alternatively, use `:colorscheme vim` or `:source
$VIMRUNTIME/colors/vim.lua` to restore previous definitions.
• 'termguicolors' is enabled by default when Nvim is able to determine that
the host terminal emulator supports 24-bit color.
• Treesitter highlight groups have been renamed to be more in line with
upstream tree-sitter and Helix to make it easier to share queries. The full
list is documented in |treesitter-highlight-groups|.
• |vim.lsp.codelens.refresh()| now takes an `opts` argument. With this change,
the default behavior of just refreshing the current buffer has been replaced by
refreshing all buffers.
• |shm-q| now fully hides macro recording message instead of only shortening it.
• Returning any truthy value from a callback passed to |nvim_create_autocmd()|
(rather than just `true`) will delete the autocommand.
• |vim.lsp.util.extract_completion_items()| will no longer return reliable
results, since it does not apply `itemDefaults` when its input is a
`CompletionList`.
Moreover, since support for LSP `completionList.itemDefaults` was added,
some third party plugins might be negatively impacted in case the language
servers support the feature but the plugin does not.
If necessary, the respective capability can be
removed when calling |vim.lsp.protocol.make_client_capabilities()|.
• |:TOhtml| has been rewritten in Lua to support Neovim-specific decorations,
and many options have been removed.
• |nvim_open_win()| now blocks all autocommands when `noautocmd` is set,
rather than just those from setting the `buffer` to display in the window.
==============================================================================
BREAKING CHANGES IN HEAD *news-breaking-dev*
====== Remove this section before release. ======
The following changes to UNRELEASED features were made during the development
cycle (Nvim HEAD, the "master" branch).
• Changed the signature of `vim.lsp.inlay_hint.is_enabled()`.
• `vim.lsp.inlay_hint.enable()` now take effect on all buffers by default.
• Removed `vim.treesitter.foldtext` as transparent foldtext is now supported
https://github.com/neovim/neovim/pull/20750
• Changed the signature of `vim.lsp.inlay_hint.enable()`.
• Changed the signature of `vim.diagnostic.enable()`.
• Removed vim.iter.map(), vim.iter.filter(), vim.iter.totable().
• Renamed vim.tbl_isarray() to vim.isarray().
• Changed |vim.ui.open()| return-signature to match `result|nil, errormsg|nil` convention.
• Renamed Iter:nextback() to Iter:pop()
• Renamed Iter:peekback() to Iter:rpeek()
• Renamed Iter:skipback() to Iter:rskip()
• Removed Iter:nthback(), use Iter:nth() with negative index instead.
• Renamed nvim_complete_set to nvim__complete_set and marked it as
experimental.
• Renamed vim.snippet.exit() to vim.snippet.stop().
• Changed |event-data| table for |LspProgress|: renamed `result` to `params`.
==============================================================================
NEW FEATURES *news-features*
The following new APIs and features were added.
The following new features were added.
• Performance:
• 'diffopt' "linematch" scoring algorithm now favours larger and less groups
https://github.com/neovim/neovim/pull/23611
• Treesitter highlighting now parses injections incrementally during
screen redraws only for the line range being rendered. This significantly
improves performance in large files with many injections.
• 'breakindent' performance is significantly improved for wrapped lines.
• Cursor movement, insertion with [count] and |screenpos()| are now faster.
• |'winfixbuf'| keeps a window focused onto a specific buffer
• |vim.iter()| provides a generic iterator interface for tables and Lua
iterators |for-in|.
• |vim.ringbuf()| creates ring buffers.
• |vim.keycode()| translates keycodes in a string.
• |'smoothscroll'| option to scroll by screen line rather than by text line
when |'wrap'| is set.
• API enhancements
• API
• Passing 0 to |nvim_get_chan_info()| gets info about the current channel.
• |nvim_buf_set_extmark()| supports inline virtual text.
• |nvim_win_text_height()| computes the number of screen lines occupied
by a range of text in a given window.
@ -215,34 +154,81 @@ The following new APIs and features were added.
• Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or
|nvim_win_set_config()|.
• |nvim_input_mouse()| supports mouse buttons "x1" and "x2".
• Added "force_crlf" option field in |nvim_open_term()|.
• Added |nvim_tabpage_set_win()| to set the current window of a tabpage.
• |nvim__win_add_ns()| can bind a |namespace| to a window-local scope(s).
• Extmarks opt-in to this scoping via the `scoped` flag of |nvim_buf_set_extmark()|.
• Mapping APIs now support abbreviations when mode short-name has suffix "a".
• Floating windows can now show footer with new `footer` and `footer_pos`
config fields. Uses |hl-FloatFooter| by default.
• |extmarks| can set a "url" highlight attribute, so the text region can
become a clickable hyperlink (assuming UI support). The TUI renders URLs
using the OSC 8 control sequence, enabling clickable text in supporting
terminals.
• |nvim_open_win()| and |nvim_win_set_config()| now support opening normal
(split) windows, moving floating windows into split windows, and opening
windows in non-current tabpages.
• Flags added to |nvim_buf_set_extmark()|:
- "undo_restore": opt-out extmarks of precise undo tracking.
- "invalidate": automatically hide or delete extmarks.
- "virt_text_repeat_linebreak": repeat virtual text on wrapped lines.
• Extmarks now fully support multi-line ranges, and a single extmark can be
used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()|
API function already allowed you to define such ranges, but highlight
regions were not rendered consistently for a range that covers more than
one line break. This has now been fixed. Signs defined as part of
a multi-line extmark also apply to every line in the range, not just the
first. In addition, |nvim_buf_get_extmarks()| has gained an "overlap"
option to return such ranges even if they started before the specified
position.
• 'foldtext' now supports virtual text format. |fold-foldtext|
• |'foldtext'| can be set to an empty string to disable and render the line:
as normal with regular highlighting and no line wrapping.
• |vim.system()| for running system commands.
• |vim.lpeg| and |vim.re| expose the bundled Lpeg expression grammar parser
and its regex interface.
• Mapping APIs now support abbreviations when mode short-name has suffix "a".
• Better cmdline completion for string option value. |complete-set-option|
• Builtin TUI can now recognize "super" (|<D-|) and "meta" (|<T-|) modifiers in a
terminal emulator that supports |tui-csiu|.
• Defaults:
• The `workspace/didChangeWatchedFiles` LSP client capability is now enabled
by default on Mac and Windows. Disabled on Linux since there currently
isn't a viable backend for watching files that scales well for large
directories.
• On Windows 'isfname' does not include ":". Drive letters are handled
correctly without it. (Use |gF| for filepaths suffixed with ":line:col").
• 'comments' includes "fb:•".
• 'shortmess' includes the "C" flag.
• 'grepprg' uses the -H and -I flags for grep by default,
and defaults to using ripgrep if available.
• "]d" and "[d" in Normal mode map to |vim.diagnostic.goto_next()| and
|vim.diagnostic.goto_prev()|, respectively. |]d-default| |[d-default|
• <C-W>d (and <C-W><C-D>) map to |vim.diagnostic.open_float()|
|CTRL-W_d-default|
• |vim.lsp.start()| sets the following default keymaps (assuming server
support):
• |K| in Normal mode maps to |vim.lsp.buf.hover()|, unless 'keywordprg'
was customized before calling |vim.lsp.start()|.
• Automatic linting of treesitter query files (see |ft-query-plugin|).
Can be disabled via: >lua
vim.g.query_lint_on = {}
<
• Enabled treesitter highlighting for:
• treesitter query files
• Vim help files
• Lua files
• Editor
• Better cmdline completion for string option value. |complete-set-option|
• Try it with `:set listchars=<tab>`
• By default, the swapfile "ATTENTION" |E325| dialog is skipped if the
swapfile is owned by a running Nvim process, instead of prompting. If you
always want the swapfile dialog, delete the default SwapExists handler:
`autocmd! nvim_swapfile`. |default-autocmds|
• Navigating the |jumplist| with CTRL+O, CTRL+I behaves more intuitively
when deleting buffers, and avoids "invalid buffer" cases. #25461
• |:fclose| command.
• |v_Q-default| and |v_@-default| repeat a register for each line of
a linewise visual selection.
• Clicking on a tabpage in the tabline with the middle mouse button closes it.
• |:checkhealth| buffer can be opened in a split window using modifiers like
|:vertical|, |:horizontal| and |:botright|.
• Events
• |vim.on_key()| callbacks receive a second argument for keys typed before
mappings are applied.
• LSP
• LSP method names are available in |vim.lsp.protocol.Methods|.
@ -280,11 +266,100 @@ The following new APIs and features were added.
|vim.lsp.buf.type_definition()|, and |vim.lsp.buf.implementation()| now
support the `loclist` field of |vim.lsp.ListOpts|.
• Lua:
• |:lua| with a |[range]| executes that range as Lua code, in any buffer.
• |:source| without arguments treats a buffer with 'filetype' of "lua" as
Lua code regardless of its extension.
• Vimscript function |exists()| supports checking |v:lua| functions.
• |vim.iter()| is a generic interface for all |iterable| objects (tables,
|iterator|s).
• |vim.snippet| provides a mode for expanding and navigating snippets.
• |vim.ringbuf()| is a generic ring buffer (data structure).
• |vim.deepcopy()| gained a `noref` argument to avoid hashing table values.
• |vim.keycode()| translates keycodes in a string.
• |vim.system()| runs commands / starts processes.
• |vim.lpeg| and |vim.re| expose the bundled Lpeg expression grammar parser
and its regex interface.
• |vim.base64.encode()| and |vim.base64.decode()| encode and decode strings
using Base64 encoding.
• |vim.text.hexencode()| and |vim.text.hexdecode()| convert strings to and
from byte representations.
• |vim.ui.open()| opens URIs using the system default handler (macOS `open`,
Windows `explorer`, Linux `xdg-open`, etc.)
• |vim.wo| can now be double indexed for |:setlocal| behaviour. Currently
only `0` for the buffer index is supported.
• Improved messages for type errors in `vim.api.*` calls (including `opts` params).
• Lua type annotations for:
• `vim.*`
• `vim.fn.*`
• `vim.api.*`
• `vim.v.*`
• Functions that take a severity as an optional parameter (e.g.
|vim.diagnostic.get()|) now also accept a list of severities |vim.diagnostic.severity|
• |vim.diagnostic.count()| returns the number of diagnostics for a given
buffer and/or namespace, by severity. This is a faster alternative to
|vim.diagnostic.get()| when only the number of diagnostics is needed, but
not the diagnostics themselves.
• |vim.diagnostic.is_enabled()|
• |vim.version.le()|, |vim.version.ge()|
• |vim.fs.root()| finds project root directories from a list of "root
markers".
• |vim.tbl_contains()| now works for general tables and allows specifying
a predicate function that is checked for each value. (Use
|vim.list_contains()| for checking list-like tables (integer keys without
gaps) for literal values.)
• |vim.region()| can use a string accepted by |getpos()| as position.
• Options
• 'winfixbuf' keeps a window focused onto a specific buffer
• 'smoothscroll' option to scroll by screen line rather than by text line
when 'wrap' is set.
• 'foldtext' now supports virtual text format. |fold-foldtext|
• 'foldtext' can be set to an empty string to disable and render the line:
as normal with regular highlighting and no line wrapping.
• 'complete' option supports "f" flag for completing buffer names.
• 'completeopt' option supports "popup" flag to show extra information in
a floating window.
• 'errorfile' (|-q|) accepts `-` as an alias for stdin.
• Performance:
• 'diffopt' "linematch" scoring algorithm now favours larger and less groups
https://github.com/neovim/neovim/pull/23611
• Treesitter highlighting now parses injections incrementally during
screen redraws only for the line range being rendered. This significantly
improves performance in large files with many injections.
• 'breakindent' performance is significantly improved for wrapped lines.
• Cursor movement, insertion with [count] and |screenpos()| are now faster.
• Plugins:
• Nvim now includes |commenting| support.
• |:Man| supports the `:hide` modifier to open page in the current window.
• |:Man| respects 'wrapmargin'
• Startup:
• |$NVIM_APPNAME| can be set to a relative path instead of only a name.
• |--startuptime| reports the startup times for both processes (TUI
+ server) as separate sections.
• Terminal
• |:terminal| accepts some |:command-modifiers| (specifically |:horizontal|
and those that affect splitting a window).
• Terminal buffers emit a |TermRequest| autocommand event when the child
process emits an OSC or DCS control sequence.
• Terminal buffers respond to OSC background and foreground requests.
|default-autocmds|
• Treesitter
• Bundled parsers and queries (highlight, folds) for Markdown, Python, and
Bash.
• |vim.treesitter.query.omnifunc()| for treesitter query files (set by
default).
• |:InspectTree| shows root nodes
• |:InspectTree| now supports |folding|
• |:InspectTree| shows node ranges in 0-based instead of 1-based indexing.
• |vim.treesitter.foldexpr()| now recognizes folds captured using a
quantified query pattern.
• |vim.treesitter.query.omnifunc()| provides completion in treesitter query
files (set by default).
• |vim.treesitter.query.edit()| provides live editing of treesitter queries.
• |Query:iter_matches()| now has the ability to set the maximum start depth
for matches.
• `@injection.language` now has smarter resolution and will fall back to
@ -294,230 +369,75 @@ The following new APIs and features were added.
• `@injection.filename` will try to match the node text via
|vim.filetype.match()| and treat the result as a language name in the same
way as `@injection.language`.
• The `#set!` directive now supports `injection.self` and `injection.parent`
for injecting either the current node's language or the parent
• The `#set!` directive supports `injection.self` and `injection.parent` for
injecting either the current node's language or the parent
|LanguageTree|'s language, respectively.
• |vim.treesitter.query.edit()| allows live editing of treesitter
queries.
• Improved error messages for query parsing.
• |:InspectTree| shows node ranges in 0-based indexing instead of 1-based
indexing.
• |:InspectTree| shows root nodes
• |:InspectTree| now supports |folding|
• The `#set!` directive can set the "url" property of a node to have the
node emit a hyperlink. Hyperlinks are UI specific: in the TUI, the OSC 8
control sequence is used.
• |vim.treesitter.foldexpr()| now recognizes folds captured using a
quantified query pattern.
• Improved error messages for query parsing.
• |:Man| now supports `:hide` modifier to open page in the current window.
• TUI
• Builtin TUI can now recognize "super" (|<D-|) and "meta" (|<T-|) modifiers
in a terminal emulator that supports |tui-csiu|.
• The |TermResponse| event can be used with |v:termresponse| to read escape
sequence responses from the host terminal.
• A clipboard provider which uses OSC 52 to copy the selection to the system
clipboard is now bundled by default and will be automatically enabled under
certain conditions. |clipboard-osc52|
• 'termsync' option asks the terminal emulator to buffer screen updates
until the redraw cycle is complete. Requires support from the host terminal.
• |vim.ui.open()| opens URIs using the system default handler (macOS `open`,
Windows `explorer`, Linux `xdg-open`, etc.)
• UI
• Enhanced support for rendering multibyte characters using composing
characters: the maximum limit was increased from 1+6 codepoints to
31 bytes, which is guaranteed to fit all chars from before but often more.
• NOTE: the regexp engine still has a hard-coded limit of considering
6 composing chars only.
• |vim.wo| can now be double indexed for |:setlocal| behaviour. Currently only
`0` for the buffer index is currently supported.
• Lua type annotations for:
• `vim.*`
• `vim.fn.*`
• `vim.api.*`
• `vim.v.*`
• Improved messages for type errors in `vim.api.*` calls (including `opts` params)
• Functions that take a severity as an optional parameter (e.g.
|vim.diagnostic.get()|) now also accept a list of severities |vim.diagnostic.severity|
• Floating windows can now show footer with new `footer` and `footer_pos`
config fields. Uses |hl-FloatFooter| by default.
• |:terminal| command now accepts some |:command-modifiers| (specifically
|:horizontal| and those that affect splitting a window).
• |$NVIM_APPNAME| can be set to a relative path instead of only a name.
• |:fclose| command.
• |vim.snippet| handles expansion of snippets in LSP format.
• 'complete' option supports "f" flag for completing buffer names.
• |vim.base64.encode()| and |vim.base64.decode()| encode and decode strings
using Base64 encoding.
• The |TermResponse| autocommand event can be used with |v:termresponse| to
read escape sequence responses from the terminal.
• A clipboard provider which uses OSC 52 to copy the selection to the system
clipboard is now bundled by default and will be automatically enabled under
certain conditions. |clipboard-osc52|
• 'termsync' option asks the terminal emulator to buffer screen updates until
the redraw cycle is complete. Requires support from the terminal.
• |vim.text.hexencode()| and |vim.text.hexdecode()| convert strings to and
from byte representations.
• 'completeopt' option supports "popup" flag to show extra information in a
floating window.
• |v_Q-default| and |v_@-default| repeat a register for each line of a linewise
visual selection.
• |vim.diagnostic.count()| returns the number of diagnostics for a given
buffer and/or namespace, by severity. This is a faster alternative to
|vim.diagnostic.get()| when only the number of diagnostics is needed, but
not the diagnostics themselves.
• Introduced |vim.diagnostic.is_enabled()|
• |vim.deepcopy()| has a `noref` argument to avoid hashing table values.
• Terminal buffers emit a |TermRequest| autocommand event when the child
process emits an OSC or DCS control sequence.
• Terminal buffers respond to OSC background and foreground requests. |default-autocmds|
• |vim.version.le()| and |vim.version.ge()| are added to |vim.version|.
• |extmarks| can set a "url" highlight attribute, so the text region can
become a clickable hyperlink (assuming UI support). The TUI renders URLs
using the OSC 8 control sequence, enabling clickable text in supporting
terminals.
• Clicking on a tabpage in the tabline with the middle mouse button closes it.
• Added built-in |commenting| support.
• |vim.fs.root()| finds project root directories from a list of "root
markers".
==============================================================================
CHANGED FEATURES *news-changed*
The following changes to existing APIs or features add new behavior.
These existing features changed their behavior.
• |vim.tbl_contains()| now works for general tables and allows specifying a
predicate function that is checked for each value. (Use |vim.list_contains()|
for checking list-like tables (integer keys without gaps) for literal values.)
• API:
• |nvim_buf_call()| and |nvim_win_call()| now preserve any return value (NB:
not multiple return values)
• |vim.region()| can use a string accepted by |getpos()| as position.
• Editor
• |gx| now uses |vim.ui.open()| and not netrw. To customize, you can redefine
`vim.ui.open` or remap `gx`. To continue using netrw (deprecated): >vim
:call netrw#BrowseX(expand(exists("g:netrw_gx")? g:netrw_gx : '<cfile>'), netrw#CheckIfRemote())<CR>
• |vim.on_key()| callbacks receive a second argument for keys typed before
mappings are applied.
• LSP:
• LSP hover and signature help now use Treesitter for highlighting of
Markdown content. Note that highlighting of code examples requires
a matching parser and may be affected by custom queries.
• |LspRequest| autocmd callbacks contain more information about the LSP
request status update that occurred.
• |vim.diagnostic.config()| now accepts a function for the virtual_text.prefix
option, which allows for rendering e.g., diagnostic severities differently.
• Lua:
• |vim.wait()| cannot be called in |api-fast|.
• |vim.diagnostic.config()| now accepts virtual text relevant options to
|nvim_buf_set_extmark()| (e.g. "virt_text_pos" and "hl_mode") in its
"virtual_text" table, which gives users more control over how diagnostic
virtual text is displayed.
• |vim.diagnostic.get()| and |vim.diagnostic.count()| accept multiple
namespaces rather than just a single namespace.
• |vim.diagnostic.enable()| gained new parameters, and the old signature is
deprecated.
• |vim.diagnostic.config()| now accepts a function for the virtual_text.prefix
option, which allows for rendering e.g., diagnostic severities differently.
• Defaults:
• On Windows 'isfname' does not include ":". Drive letters are handled
correctly without it. (Use |gF| for filepaths suffixed with ":line:col").
• 'comments' includes "fb:•".
• 'shortmess' includes the "C" flag.
• 'grepprg' uses the -H and -I flags for grep by default,
and defaults to using ripgrep if available.
• "]d" and "[d" in Normal mode map to |vim.diagnostic.goto_next()| and
|vim.diagnostic.goto_prev()|, respectively. |]d-default| |[d-default|
• <C-W>d (and <C-W><C-D>) map to |vim.diagnostic.open_float()|
|CTRL-W_d-default|
• Automatic linting of treesitter query files (see |ft-query-plugin|).
Can be disabled via: >lua
vim.g.query_lint_on = {}
<
• Enabled treesitter highlighting for treesitter query files.
• Enabled treesitter highlighting for help files.
• Enabled treesitter highlighting for Lua files.
• Options
• Attempting to set an invalid keycode option (e.g. `set t_foo=123`) no
longer gives an error.
• The `workspace/didChangeWatchedFiles` LSP client capability is now enabled
by default on Mac and Windows. Disabled on Linux since there currently isn't
a viable backend for watching files that scales well for large directories.
• |LspRequest| autocmd callbacks now contain additional information about the LSP
request status update that occurred.
• |:source| without arguments treats a buffer with its 'filetype' set to "lua"
as Lua code regardless of its extension.
• |:lua| with a |[range]| executes that range in the current buffer as Lua code
regardless of its extension.
• |:Man| now respects 'wrapmargin'
• |gx| now uses |vim.ui.open()| and not netrw. To customize, you can redefine
`vim.ui.open` or remap `gx`. To continue using netrw (deprecated): >vim
:call netrw#BrowseX(expand(exists("g:netrw_gx")? g:netrw_gx : '<cfile>'), netrw#CheckIfRemote())<CR>
• |vim.lsp.start()| now creates the following default keymaps (assuming the
server supports the feature):
- |K| in Normal mode maps to |vim.lsp.buf.hover()|, unless |'keywordprg'|
was customized before calling |vim.lsp.start()|.
• Terminal buffers started with no arguments (and use 'shell') close
automatically if the job exited without error, eliminating the (often
unwanted) "[Process exited 0]" message.
• |vim.diagnostic.config()| now accepts virtual text relevant options to
|nvim_buf_set_extmark()| (e.g. "virt_text_pos" and "hl_mode") in its
"virtual_text" table, which gives users more control over how diagnostic
virtual text is displayed.
• |vim.diagnostic.get()| and |vim.diagnostic.count()| accept multiple
namespaces rather than just a single namespace.
• |vim.diagnostic.enable()| gained new parameters, and the old signature is
deprecated.
• Extmarks now fully support multi-line ranges, and a single extmark can be
used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()|
API function already allowed you to define such ranges, but highlight regions
were not rendered consistently for a range that covers more than one line break.
This has now been fixed. Signs defined as part of a multi-line extmark also
apply to every line in the range, not just the first.
In addition, |nvim_buf_get_extmarks()| has gained an "overlap" option to
return such ranges even if they started before the specified position.
• The following flags were added to |nvim_buf_set_extmark()|:
- "undo_restore": opt-out extmarks of precise undo tracking.
- "invalidate": automatically hide or delete extmarks.
- "virt_text_repeat_linebreak": repeat virtual text on wrapped lines.
• LSP hover and signature help now use Treesitter for highlighting of Markdown
content.
Note that syntax highlighting of code examples requires a matching parser
and may be affected by custom queries.
• Support for rendering multibyte characters using composing characters has been
enhanced. The maximum limit have been increased from 1+6 codepoints to
31 bytes, which is guaranteed to fit all chars from before but often more.
NOTE: the regexp engine still has a hard-coded limit of considering
6 composing chars only.
• |vim.wait()| is no longer allowed to be called in |api-fast|.
• Vimscript function |exists()| supports checking |v:lua| functions.
• Added "force_crlf" option field in |nvim_open_term()|.
• Attempting to set an invalid keycode option (e.g. `set t_foo=123`) no longer
gives an error.
• Passing 0 to |nvim_get_chan_info()| gets info about the current channel.
• |:checkhealth| buffer can now be opened in a split window using modifiers like
|:vertical|, |:horizontal| and |:botright|.
• |nvim_open_win()| and |nvim_win_set_config()| now support opening normal (split)
windows, moving floating windows into split windows, and opening windows in
non-current tabpages.
• 'errorfile' (|-q|) accepts `-` as an alias for stdin.
• |--startuptime| reports the startup times for both processes (TUI + server) as separate sections.
• |nvim_buf_call()| and |nvim_win_call()| now preserves any return value (NB: not multiple return values)
• Terminal
• Terminal buffers started with no arguments (and use 'shell') close
automatically if the job exited without error, eliminating the (often
unwanted) "[Process exited 0]" message.
• Treesitter
• |Query:iter_matches()|, |vim.treesitter.query.add_predicate()|, and
@ -534,7 +454,7 @@ The following changes to existing APIs or features add new behavior.
==============================================================================
REMOVED FEATURES *news-removed*
The following deprecated functions or APIs were removed.
These deprecated features were removed.
• Vimball support
- :Vimuntar command

6
runtime/doc/treesitter.txt
View File

@ -1321,7 +1321,11 @@ LanguageTree:included_regions() *LanguageTree:included_regions()*
(`table<integer, Range6[]>`)
LanguageTree:invalidate({reload}) *LanguageTree:invalidate()*
Invalidates this parser and all its children
Invalidates this parser and its children.
Should only be called when the tracked state of the LanguageTree is not
valid against the parse tree in treesitter. Doesn't clear filesystem
cache. Called often, so needs to be fast.
Parameters: ~
• {reload} (`boolean?`)

7
runtime/lua/vim/_meta/lpeg.lua
View File

@ -6,11 +6,10 @@ error('Cannot require a meta file')
-- with types being renamed to include the vim namespace and with some descriptions made less verbose.
--- @brief <pre>help
--- LPeg is a pattern-matching library for Lua, based on
--- Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
--- LPeg is a pattern-matching library for Lua, based on Parsing Expression
--- Grammars (PEGs). https://bford.info/packrat/
---
--- *lua-lpeg*
--- *vim.lpeg.Pattern*
--- *lua-lpeg* *vim.lpeg.Pattern*
--- The LPeg library for parsing expression grammars is included as `vim.lpeg`
--- (https://www.inf.puc-rio.br/~roberto/lpeg/).
---

8
runtime/lua/vim/_meta/re.lua
View File

@ -8,11 +8,11 @@ error('Cannot require a meta file')
-- See 'lpeg.html' for license
--- @brief
--- The `vim.re` module provides a conventional regex-like syntax for pattern usage
--- within LPeg |vim.lpeg|.
--- The `vim.re` module provides a conventional regex-like syntax for pattern usage within LPeg
--- |vim.lpeg|. (Unrelated to |vim.regex| which provides Vim |regexp| from Lua.)
---
--- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
--- documentation including regex syntax and more concrete examples.
--- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original documentation including
--- regex syntax and examples.
--- Compiles the given {string} and returns an equivalent LPeg pattern. The given string may define
--- either an expression or a grammar. The optional {defs} table provides extra Lua values to be used

3
runtime/lua/vim/lsp/inlay_hint.lua
View File

@ -136,7 +136,8 @@ end
--- local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
---
--- local client = vim.lsp.get_client_by_id(hint.client_id)
--- resolved_hint = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0).result
--- local resp = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0)
--- local resolved_hint = assert(resp and resp.result, resp.err)
--- vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding)
---
--- location = resolved_hint.label[1].location

5
runtime/lua/vim/snippet.lua
View File

@ -532,10 +532,9 @@ end
--- @alias vim.snippet.Direction -1 | 1
--- Jumps within the active snippet in the given direction.
--- If the jump isn't possible, the function call does nothing.
--- Jumps to the next (or previous) placeholder in the current snippet, if possible.
---
--- You can use this function to navigate a snippet as follows:
--- For example, map `<Tab>` to jump while a snippet is active:
---
--- ```lua
--- vim.keymap.set({ 'i', 's' }, '<Tab>', function()

5
runtime/lua/vim/treesitter/languagetree.lua
View File

@ -225,7 +225,10 @@ function LanguageTree:_log(...)
self._logger('nvim', table.concat(msg, ' '))
end
--- Invalidates this parser and all its children
--- Invalidates this parser and its children.
---
--- Should only be called when the tracked state of the LanguageTree is not valid against the parse
--- tree in treesitter. Doesn't clear filesystem cache. Called often, so needs to be fast.
---@param reload boolean|nil
function LanguageTree:invalidate(reload)
self._valid = false

36
scripts/cliff.toml
View File

@ -4,27 +4,29 @@
# changelog header
header = """
# Changelog\n
All notable changes to this project will be documented in this file.\n
For notable changes, see runtime/doc/news.txt (or `:help news` in Nvim).\n
Following is a list of fixes/features commits.\n
"""
# template for the changelog body
# https://github.com/Keats/tera
# https://keats.github.io/tera/docs/
body = """
{% if version %}\
## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
# [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
{% else %}\
## [unreleased]
# [unreleased]
{% endif %}\
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | striptags | upper_first }}
{{ group | striptags | upper_first }}
--------------------------------------------------------------------------------
{% for commit in commits | sort(attribute="message")%}\
{% if not commit.scope %}\
- {{ commit.message }}
- {{ commit.id | truncate(length=12, end="") }} {{ commit.message }}
{% endif %}\
{% endfor %}\
{% for group, commits in commits | group_by(attribute="scope") %}\
{% for commit in commits | sort(attribute="message") %}\
- **{{commit.scope}}**: {{ commit.message }}
- {{ commit.id | truncate(length=12, end="") }} {{commit.scope}}: {{ commit.message }}
{% endfor %}\
{% endfor %}
{% endfor %}\n
@ -45,18 +47,18 @@ commit_preprocessors = [
]
# regex for parsing and grouping commits
commit_parsers = [
{ message = "!:", group = "<!-- 0 -->Breaking"},
{ message = "^feat", group = "<!-- 1 -->Features"},
{ message = "^fix", group = "<!-- 2 -->Bug Fixes"},
{ message = "^perf", group = "<!-- 3 -->Performance"},
{ message = "^build", group = "<!-- 4 -->Build System"},
{ message = "^vim-patch", group = "<!-- 5 -->Vim patches"},
{ message = "^refactor", group = "<!-- 6 -->Refactor" },
{ message = "!:", group = "<!-- 0 -->BREAKING"},
{ message = "^feat", group = "<!-- 1 -->FEATURES"},
{ message = "^fix", group = "<!-- 2 -->FIXES"},
{ message = "^perf", group = "<!-- 3 -->PERFORMANCE"},
{ message = "^build", group = "<!-- 4 -->BUILD"},
{ message = "^vim-patch", group = "<!-- 5 -->VIM PATCHES"},
{ message = "^refactor", group = "<!-- 6 -->REFACTOR" },
{ message = "^ci", group = "<!-- 8 -->CI" },
{ message = "^test", group = "<!-- 9 -->Testing" },
{ message = "^docs", group = "<!-- 99 -->Documentation" },
{ message = "^revert", group = "<!-- 999 -->Reverted Changes" },
{ message = ".*", group = "<!-- 9999 -->Other"},
{ message = "^test", group = "<!-- 9 -->TESTING" },
{ message = "^docs", group = "<!-- 99 -->DOCUMENTATION" },
{ message = "^revert", group = "<!-- 999 -->REVERTED CHANGES" },
{ message = ".*", group = "<!-- 9999 -->OTHER"},
]
# filter out the commits that are not matched by commit parsers
filter_commits = true

5
scripts/gen_help_html.lua
View File

@ -63,10 +63,15 @@ local new_layout = {
['channel.txt'] = true,
['deprecated.txt'] = true,
['develop.txt'] = true,
['dev_style.txt'] = true,
['dev_theme.txt'] = true,
['dev_tools.txt'] = true,
['dev_vimpatch.txt'] = true,
['lua.txt'] = true,
['luaref.txt'] = true,
['news.txt'] = true,
['news-0.9.txt'] = true,
['news-0.10.txt'] = true,
['nvim.txt'] = true,
['pi_health.txt'] = true,
['provider.txt'] = true,

52
scripts/git-log-pretty-since.sh
View File

@ -1,52 +0,0 @@
#!/usr/bin/env bash
# Prints a nicely-formatted commit history.
# - Commits are grouped below their merge-commit.
# - Issue numbers are moved next to the commit-id.
#
# Parameters:
# $1 "since" commit
# $2 "inverse match" regex pattern
set -e
set -u
set -o pipefail
__SINCE=$1
__INVMATCH=$2
is_merge_commit() {
git rev-parse "$1" >/dev/null 2>&1 \
|| { echo "ERROR: invalid commit: $1"; exit 1; }
git log "$1"^2 >/dev/null 2>&1 && return 0 || return 1
}
# Removes parens from issue/ticket/PR numbers.
#
# Example:
# in: 3340e08becbf foo (#9423)
# out: 3340e08becbf foo #9423
_deparen() {
sed 's/(\(\#[0-9]\{3,\}\))/\1/g'
}
# Cleans up issue/ticket/PR numbers in the commit descriptions.
#
# Example:
# in: 3340e08becbf foo (#9423)
# out: 3340e08becbf #9423 foo
_format_ticketnums() {
nvim -Es +'g/\v(#[0-9]{3,})/norm! ngEldE0ep' +'%p' | _deparen
}
for commit in $(git log --format='%H' --first-parent "$__SINCE"..HEAD); do
if is_merge_commit "${commit}" ; then
if [ -z "$__INVMATCH" ] || ! git log --oneline "${commit}^1..${commit}^2" \
| >/dev/null 2>&1 grep -E "$__INVMATCH" ; then
git log -1 --oneline "${commit}"
git log --format=' %h %s' "${commit}^1..${commit}^2"
fi
else
git log -1 --oneline "${commit}"
fi
done | _format_ticketnums

20
scripts/release.sh
View File

@ -31,30 +31,28 @@ __DATE=$(date +'%Y-%m-%d')
__LAST_TAG=$(git describe --abbrev=0)
[ -z "$__LAST_TAG" ] && { echo 'ERROR: no tag found'; exit 1; }
__VERSION_MAJOR=$(grep 'set(NVIM_VERSION_MAJOR' CMakeLists.txt\
|$__sed 's/.*NVIM_VERSION_MAJOR ([[:digit:]]).*/\1/')
|$__sed 's/.*NVIM_VERSION_MAJOR ([[:digit:]]+).*/\1/')
__VERSION_MINOR=$(grep 'set(NVIM_VERSION_MINOR' CMakeLists.txt\
|$__sed 's/.*NVIM_VERSION_MINOR ([[:digit:]]).*/\1/')
|$__sed 's/.*NVIM_VERSION_MINOR ([[:digit:]]+).*/\1/')
__VERSION_PATCH=$(grep 'set(NVIM_VERSION_PATCH' CMakeLists.txt\
|$__sed 's/.*NVIM_VERSION_PATCH ([[:digit:]]).*/\1/')
|$__sed 's/.*NVIM_VERSION_PATCH ([[:digit:]]+).*/\1/')
__VERSION="${__VERSION_MAJOR}.${__VERSION_MINOR}.${__VERSION_PATCH}"
__API_LEVEL=$(grep 'set(NVIM_API_LEVEL ' CMakeLists.txt\
|$__sed 's/.*NVIM_API_LEVEL ([[:digit:]]).*/\1/')
|$__sed 's/.*NVIM_API_LEVEL ([[:digit:]]+).*/\1/')
{ [ -z "$__VERSION_MAJOR" ] || [ -z "$__VERSION_MINOR" ] || [ -z "$__VERSION_PATCH" ]; } \
&& { echo "ERROR: version parse failed: '${__VERSION}'"; exit 1; }
__RELEASE_MSG="NVIM v${__VERSION}
FEATURES:
FIXES:
CHANGES:
"
__BUMP_MSG="version bump"
echo "Most recent tag: ${__LAST_TAG}"
echo "Release version: ${__VERSION}"
_git_log_pretty() {
git cliff --config scripts/cliff.toml --unreleased || echo 'git cliff failed'
}
_do_release_commit() {
$__sed -i.bk 's/(NVIM_VERSION_PRERELEASE) "-dev"/\1 ""/' CMakeLists.txt
if grep '(NVIM_API_PRERELEASE true)' CMakeLists.txt > /dev/null; then
@ -73,7 +71,7 @@ _do_release_commit() {
echo "Building changelog since ${__LAST_TAG}..."
git add CMakeLists.txt
(echo "${__RELEASE_MSG}"; ./scripts/git-log-pretty-since.sh "$__LAST_TAG" 'vim-patch:[^[:space:]]') | git commit --edit -F -
(echo "${__RELEASE_MSG}"; _git_log_pretty) | git commit --edit -F -
fi
git tag --sign -a v"${__VERSION}" -m "NVIM v${__VERSION}"