mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-10-26 12:27:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: news

Browse Source 
Set dev_xx.txt help files to use "flow" layout.
This commit is contained in:
Justin M. Keyes
2024-05-02 15:57:21 +02:00
parent cdd87222c8
commit 01b6bff7e9
18 changed files with 484 additions and 553 deletions
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. 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) ### Automated builds (CI)
Each pull request must pass the automated builds on [Cirrus CI] and [GitHub Actions]. Each pull request must pass the automated builds on [Cirrus CI] and [GitHub Actions].

18
MAINTAIN.md
View File

@@ -50,10 +50,11 @@ has a major bug:
1. Fix the bug on `master`. 1. Fix the bug on `master`.
2. Cherry-pick the fix to `release-x.y`. 2. Cherry-pick the fix to `release-x.y`.
3. Cut a release from `release-x.y`. 3. Cut a release from `release-x.y`.
* Run `git cliff --config scripts/cliff.toml --unreleased -o CHANGELOG.md`
* Run `./scripts/release.sh` * Run `./scripts/release.sh`
* Update (force-push) the remote `stable` tag. * Paste `CHANGELOG.md` into the release commit message.
* The [CI job](https://github.com/neovim/neovim/blob/3d45706478cd030c3ee05b4f336164bb96138095/.github/workflows/release.yml#L11-L13) * 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 ### Release automation
@@ -85,26 +86,24 @@ When a (non-experimental) feature is slated to be removed it should:
- Features implemented in C will need bespoke implementations to communicate - Features implemented in C will need bespoke implementations to communicate
to users that the feature is deprecated. to users that the feature is deprecated.
3. Be removed in a release following the release in which it was hard 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 - Usually this will be the next release, but it may be a later release if
longer deprecation cycle is desired a longer deprecation cycle is desired
- If possible, keep the feature as a stub (e.g. function API) and issue an error - If possible, keep the feature as a stub (e.g. function API) and issue an
when it is accessed. error when it is accessed.
Example: Example:
```
Deprecation Removal Deprecation Removal
┆ ┆ ┆ ┆ ┆ ┆
┆ Soft ┆ Hard ┆ ┆ Soft ┆ Hard ┆
┆ Deprecation ┆ Deprecation ┆ ┆ Deprecation ┆ Deprecation ┆
┆ Period ┆ Period ┆ ┆ Period ┆ Period ┆
──────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────
Version: 0.10 0.11 0.12 Version: 0.10 0.11 0.12
──────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────
Old code Old code Old code Old code Old code Old code
+ + + +
New code New code New code New code New code New code
```
Feature removals which may benefit from community input or further discussion 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 should also have a tracking issue (which should be linked to in the release
@@ -210,7 +209,6 @@ https://github.com/neovim/neovim-backup
* Avoid macOS if an Ubuntu or a Windows runner can be used instead. This is * 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 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). jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).
* Runner versions: * Runner versions:
* For special-purpose jobs where the runner version doesn't really matter, * 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 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. - *nvim_get_hl_by_id()* Use |nvim_get_hl()| instead.
• The following top level Treesitter functions have been moved: • The following top level Treesitter functions have been moved:
*vim.treesitter.inspect_language()* -> |vim.treesitter.language.inspect()| - *vim.treesitter.inspect_language()* -> |vim.treesitter.language.inspect()|
*vim.treesitter.get_query_files()* -> |vim.treesitter.query.get_files()| - *vim.treesitter.get_query_files()* -> |vim.treesitter.query.get_files()|
*vim.treesitter.set_query()* -> |vim.treesitter.query.set()| - *vim.treesitter.set_query()* -> |vim.treesitter.query.set()|
*vim.treesitter.query.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.get_query()* -> |vim.treesitter.query.get()|
*vim.treesitter.query.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.parse_query()* -> |vim.treesitter.query.parse()|
*vim.treesitter.query.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_predicate()* -> |vim.treesitter.query.add_predicate()|
*vim.treesitter.add_directive()* -> |vim.treesitter.query.add_directive()| - *vim.treesitter.add_directive()* -> |vim.treesitter.query.add_directive()|
*vim.treesitter.list_predicates()* -> |vim.treesitter.query.list_predicates()| - *vim.treesitter.list_predicates()* -> |vim.treesitter.query.list_predicates()|
*vim.treesitter.list_directives()* -> |vim.treesitter.query.list_directives()| - *vim.treesitter.list_directives()* -> |vim.treesitter.query.list_directives()|
*vim.treesitter.query.get_range()* -> |vim.treesitter.get_range()| - *vim.treesitter.query.get_range()* -> |vim.treesitter.get_range()|
*vim.treesitter.query.get_node_text()* -> |vim.treesitter.get_node_text()| - *vim.treesitter.query.get_node_text()* -> |vim.treesitter.get_node_text()|
• Lua stdlib: • Lua stdlib:
- *nvim_exec()* Use |nvim_exec2()| instead. - *nvim_exec()* Use |nvim_exec2()| instead.

2
runtime/doc/dev_style.txt
View File

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

29
runtime/doc/develop.txt
View File

@@ -304,19 +304,22 @@ See also |dev-naming|.
- accept iterable instead of table - accept iterable instead of table
- exception: in some cases iterable doesn't make sense, e.g. spair() sorts - 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 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". a "stream".
- return iterable instead of table - return iterable instead of table
- mimic the pairs() or ipairs() interface if the function is intended to be - mimic the pairs() or ipairs() interface if the function is intended to be
used in a "for" loop. 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 Foo|nil # Result object, or nil if not found.
---@return nil|string # Error message on failure, or nil on success. ---@return nil|string # Error message on failure, or nil on success.
< <
- Examples: |vim.ui.open()| |io.open()| |luv-error-handling| - Examples: |vim.ui.open()| |io.open()| |luv-error-handling|
*dev-patterns*
Interface conventions ~ 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 - When accepting a buffer id, etc., 0 means "current buffer", nil means "all
buffers". Likewise for window id, tabpage id, etc. buffers". Likewise for window id, tabpage id, etc.
- Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()| - Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()|
@@ -327,6 +330,17 @@ Interface conventions ~
filter(table, opts, function() … end) filter(table, opts, function() … end)
BAD: BAD:
filter(function() … end, table, opts) 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*
@@ -438,7 +452,7 @@ Use this format to name API (RPC) events: >
Example: > Example: >
nvim_buf_changedtick_event nvim_buf_changedtick_event
< <
*dev-name-api* *dev-api-name*
Use this format to name new RPC |API| functions: > Use this format to name new RPC |API| functions: >
nvim_{topic}_{verb}_{arbitrary-qualifiers} 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}. 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. Prefer adding a single `nvim_{topic}_{verb}_…` interface for a given topic.
@@ -520,9 +534,10 @@ favorite platform or programming language.
List of API clients: List of API clients:
https://github.com/neovim/neovim/wiki/Related-projects#api-clients https://github.com/neovim/neovim/wiki/Related-projects#api-clients
*pynvim* *node-client* *pynvim*
The Python client is the reference implementation for API clients. These clients can be considered the "reference implementation" for API clients:
https://github.com/neovim/pynvim - https://github.com/neovim/node-client
- https://github.com/neovim/pynvim
Standard Features ~ Standard Features ~

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 hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
local client = vim.lsp.get_client_by_id(hint.client_id) 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) vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding)
location = resolved_hint.label[1].location 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. so that old plugins continue to work transparently.
*lua-luajit* *lua-luajit*
Nvim is built with luajit on platforms which support it, which provides On supported platforms, Nvim is built with LuaJIT, which provides extra
extra functionality. Lua code in |init.lua| and plugins can assume its presence functionality (compared to PUC Lua) such as "bit" and various utilities (see
on installations on common platforms. For maximum compatibility with less |lua-profile|). Lua code in |init.lua| and plugins can assume its presence on
common platforms, availability can be checked using the `jit` global variable: >lua many platforms, but for maximum compatibility should check the `jit` global
variable: >lua
if jit then if jit then
-- code for luajit -- code for luajit
else else
@@ -45,9 +46,21 @@ common platforms, availability can be checked using the `jit` global variable: >
end end
< <
*lua-bit* *lua-bit*
In particular, the luajit "bit" extension module is _always_ available. The LuaJIT "bit" extension module is _always_ available: when built with PUC
A fallback implementation is included when nvim is built with PUC Lua 5.1, Lua, Nvim includes a fallback implementation which provides `require("bit")`.
and will be transparently used when `require("bit")` is invoked.
*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* LUA CONCEPTS AND IDIOMS *lua-concepts*
@@ -244,8 +257,8 @@ arguments separated by " " (space) instead of "\t" (tab).
*:lua=* *:lua* *:lua=* *:lua*
:lua {chunk} :lua {chunk}
Executes Lua chunk {chunk}. If {chunk} starts with "=" the rest of the 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 chunk is evaluated as an expression and printed. `:lua =expr` and `:=expr`
equivalent to `:lua print(vim.inspect(expr))`. are equivalent to `:lua vim.print(expr)`.
Examples: >vim Examples: >vim
:lua vim.api.nvim_command('echo "Hello, Nvim!"') :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* VIM.LPEG *vim.lpeg*
LPeg is a pattern-matching library for Lua, based on LPeg is a pattern-matching library for Lua, based on Parsing Expression
Parsing Expression Grammars (https://bford.info/packrat/) (PEGs). Grammars (PEGs). https://bford.info/packrat/
*lua-lpeg* *lua-lpeg* *vim.lpeg.Pattern*
*vim.lpeg.Pattern*
The LPeg library for parsing expression grammars is included as `vim.lpeg` The LPeg library for parsing expression grammars is included as `vim.lpeg`
(https://www.inf.puc-rio.br/~roberto/lpeg/). (https://www.inf.puc-rio.br/~roberto/lpeg/).
@@ -3457,10 +3469,11 @@ vim.lpeg.version() *vim.lpeg.version()*
VIM.RE *vim.re* VIM.RE *vim.re*
The `vim.re` module provides a conventional regex-like syntax for pattern 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 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()* vim.re.compile({string}, {defs}) *vim.re.compile()*
@@ -4342,10 +4355,10 @@ vim.snippet.expand({input}) *vim.snippet.expand()*
• {input} (`string`) • {input} (`string`)
vim.snippet.jump({direction}) *vim.snippet.jump()* vim.snippet.jump({direction}) *vim.snippet.jump()*
Jumps within the active snippet in the given direction. If the jump isn't Jumps to the next (or previous) placeholder in the current snippet, if
possible, the function call does nothing. 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() vim.keymap.set({ 'i', 's' }, '<Tab>', function()
if vim.snippet.active({ direction = 1 }) then if vim.snippet.active({ direction = 1 }) then
return '<cmd>lua vim.snippet.jump(1)<cr>' return '<cmd>lua vim.snippet.jump(1)<cr>'

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

@@ -4,7 +4,7 @@
NVIM REFERENCE MANUAL 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. Type |gO| to see the table of contents.

676
runtime/doc/news.txt
View File

@@ -13,24 +13,47 @@ For changes in the previous release, see |news-0.9|.
============================================================================== ==============================================================================
BREAKING CHANGES *news-breaking* 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 • API:
configuring 'guicursor' as mentioned in |cursor-blinking|. This was a bug • |nvim_open_win()| now blocks all autocommands when `noautocmd` is set,
that has now been fixed. If your cursor has stopped blinking, add the rather than just those from setting the `buffer` to display in the window.
following (or similar, adapted to user preference) to your |config| file: >vim
set guicursor+=n-v-c:blinkon500-blinkoff500 • Defaults:
< • Default color scheme has been updated to be "Nvim branded" and accessible.
• |vim.islist()| now checks whether a table is actually list-like (i.e., Use `:colorscheme vim` to revert to the old legacy color scheme.
has integer keys without gaps and starting from 1). For the previous • These Nvim specific highlight groups are now defined in a meaningfully
behavior (only check for integer keys, allow gaps or not starting with 1), different way and might need an update:
use |vim.isarray()|. • |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.
• "#" followed by a digit no longer stands for a function key at the start of • Editor
the lhs of a mapping. • When switching windows, |CursorMoved| autocommands trigger when Nvim is
back in the main loop rather than immediately. This is more compatible
• `:behave` was removed. 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 - If you used `:behave xterm`, the following is equivalent: >vim
set mousemodel=extend set mousemodel=extend
@@ -42,171 +65,87 @@ The following changes may require adaptations in user config or plugins.
set mousemodel=popup set mousemodel=popup
set keymodel=startsel,stopsel set keymodel=startsel,stopsel
< <
• 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 • 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. doesn't cause Nvim to exit.
• Removed functions from the |vim.json| module:
• |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. • Unnecessary, undocumented functions which caused global side-effects.
• `vim.json.null` is redundant with `vim.NIL`. • `vim.json.null` is redundant with `vim.NIL`.
• `vim.json.array_mt` (and related) is redundant with `vim.empty_dict()`. • `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`.
• Removed some Vim 5.0<= option compatibilities: • Options
• |'backspace'| no longer supports number values. Instead: • Removed some Vim 5.0<= option compatibilities:
• 'backspace' no longer supports number values. Instead:
• for `backspace=0` set `backspace=` (empty) • for `backspace=0` set `backspace=` (empty)
• for `backspace=1` set `backspace=indent,eol` • for `backspace=1` set `backspace=indent,eol`
• for `backspace=2` set `backspace=indent,eol,start` (default behavior in Nvim) • for `backspace=2` set `backspace=indent,eol,start` (default behavior in Nvim)
• for `backspace=3` set `backspace=indent,eol,nostop` • for `backspace=3` set `backspace=indent,eol,nostop`
• |'backupdir'| and |'directory'| will no longer remove a `>` at the start • 'backupdir' and 'directory' will no longer remove a `>` at the start of
of the option. the option.
• |OptionSet| autocommand args |v:option_new|, |v:option_old|,
• |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 |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 instead of always being strings. |v:option_old| is now the old global
for all global-local options, instead of just string global-local options. 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.
• Local value for a global-local number/boolean option is now unset when • Plugins:
the option is set (e.g. using |:set| or |nvim_set_option_value()|) without a • |:TOhtml| has been rewritten in Lua to support Neovim-specific
scope, which means they now behave the same way as string options. decorations, and many options have been removed.
• Signs placed through the legacy |sign-commands| are now stored and displayed • Treesitter
as |extmarks| internally. Along with the following changes: • Treesitter highlight groups have been renamed to be more in line with
• A sign placed twice in the same group with the same identifier will be moved. upstream tree-sitter and Helix to make it easier to share queries. The
• Legacy signs are always deleted along with the line it is placed on. full list is documented in |treesitter-highlight-groups|.
• 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. • TUI
Use `:colorscheme vim` to revert to the old legacy color scheme. • 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
Here is a list of Nvim specific highlight groups which are now defined in that has now been fixed. If your cursor has stopped blinking, add the
a meaningfully different way and might need an update: following (or similar, adapted to user preference) to your |config| file: >vim
• |hl-FloatBorder| is linked to |hl-NormalFloat| instead of |hl-WinSeparator|. set guicursor+=n-v-c:blinkon500-blinkoff500
• |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* NEW FEATURES *news-features*
The following new APIs and features were added. The following new features were added.
• Performance: • API
• 'diffopt' "linematch" scoring algorithm now favours larger and less groups • Passing 0 to |nvim_get_chan_info()| gets info about the current channel.
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
• |nvim_buf_set_extmark()| supports inline virtual text. • |nvim_buf_set_extmark()| supports inline virtual text.
• |nvim_win_text_height()| computes the number of screen lines occupied • |nvim_win_text_height()| computes the number of screen lines occupied
by a range of text in a given window. 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 • Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or
|nvim_win_set_config()|. |nvim_win_set_config()|.
• |nvim_input_mouse()| supports mouse buttons "x1" and "x2". • |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. • 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). • |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()|. • 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| • Defaults:
• The `workspace/didChangeWatchedFiles` LSP client capability is now enabled
• |'foldtext'| can be set to an empty string to disable and render the line: by default on Mac and Windows. Disabled on Linux since there currently
as normal with regular highlighting and no line wrapping. isn't a viable backend for watching files that scales well for large
directories.
• |vim.system()| for running system commands. • On Windows 'isfname' does not include ":". Drive letters are handled
correctly without it. (Use |gF| for filepaths suffixed with ":line:col").
• |vim.lpeg| and |vim.re| expose the bundled Lpeg expression grammar parser • 'comments' includes "fb:•".
and its regex interface. • 'shortmess' includes the "C" flag.
• 'grepprg' uses the -H and -I flags for grep by default,
• Mapping APIs now support abbreviations when mode short-name has suffix "a". and defaults to using ripgrep if available.
• "]d" and "[d" in Normal mode map to |vim.diagnostic.goto_next()| and
• Better cmdline completion for string option value. |complete-set-option| |vim.diagnostic.goto_prev()|, respectively. |]d-default| |[d-default|
• <C-W>d (and <C-W><C-D>) map to |vim.diagnostic.open_float()|
• Builtin TUI can now recognize "super" (|<D-|) and "meta" (|<T-|) modifiers in a |CTRL-W_d-default|
terminal emulator that supports |tui-csiu|. • |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 • 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 • By default, the swapfile "ATTENTION" |E325| dialog is skipped if the
swapfile is owned by a running Nvim process, instead of prompting. If you swapfile is owned by a running Nvim process, instead of prompting. If you
always want the swapfile dialog, delete the default SwapExists handler: always want the swapfile dialog, delete the default SwapExists handler:
`autocmd! nvim_swapfile`. |default-autocmds| `autocmd! nvim_swapfile`. |default-autocmds|
• Navigating the |jumplist| with CTRL+O, CTRL+I behaves more intuitively • Navigating the |jumplist| with CTRL+O, CTRL+I behaves more intuitively
when deleting buffers, and avoids "invalid buffer" cases. #25461 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
• LSP method names are available in |vim.lsp.protocol.Methods|. • 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 |vim.lsp.buf.type_definition()|, and |vim.lsp.buf.implementation()| now
support the `loclist` field of |vim.lsp.ListOpts|. 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 • Treesitter
• Bundled parsers and queries (highlight, folds) for Markdown, Python, and • Bundled parsers and queries (highlight, folds) for Markdown, Python, and
Bash. Bash.
• |vim.treesitter.query.omnifunc()| for treesitter query files (set by • |:InspectTree| shows root nodes
default). • |: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 • |Query:iter_matches()| now has the ability to set the maximum start depth
for matches. for matches.
• `@injection.language` now has smarter resolution and will fall back to • `@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 • `@injection.filename` will try to match the node text via
|vim.filetype.match()| and treat the result as a language name in the same |vim.filetype.match()| and treat the result as a language name in the same
way as `@injection.language`. way as `@injection.language`.
• The `#set!` directive now supports `injection.self` and `injection.parent` • The `#set!` directive supports `injection.self` and `injection.parent` for
for injecting either the current node's language or the parent injecting either the current node's language or the parent
|LanguageTree|'s language, respectively. |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 • 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 node emit a hyperlink. Hyperlinks are UI specific: in the TUI, the OSC 8
control sequence is used. control sequence is used.
• |vim.treesitter.foldexpr()| now recognizes folds captured using a • Improved error messages for query parsing.
quantified query pattern.
• |:Man| now supports `:hide` modifier to open page in the current window. • TUI
• Builtin TUI can now recognize "super" (|<D-|) and "meta" (|<T-|) modifiers
• |vim.ui.open()| opens URIs using the system default handler (macOS `open`, in a terminal emulator that supports |tui-csiu|.
Windows `explorer`, Linux `xdg-open`, etc.) • The |TermResponse| event can be used with |v:termresponse| to read escape
sequence responses from the host terminal.
• |vim.wo| can now be double indexed for |:setlocal| behaviour. Currently only • A clipboard provider which uses OSC 52 to copy the selection to the system
`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 clipboard is now bundled by default and will be automatically enabled under
certain conditions. |clipboard-osc52| 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.
• 'termsync' option asks the terminal emulator to buffer screen updates until • UI
the redraw cycle is complete. Requires support from the terminal. • 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.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* 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 • API:
predicate function that is checked for each value. (Use |vim.list_contains()| • |nvim_buf_call()| and |nvim_win_call()| now preserve any return value (NB:
for checking list-like tables (integer keys without gaps) for literal values.) 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.on_key()| callbacks receive a second argument for keys typed before
mappings are applied.
• |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.
• 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 `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> :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 • LSP:
server supports the feature): • LSP hover and signature help now use Treesitter for highlighting of
- |K| in Normal mode maps to |vim.lsp.buf.hover()|, unless |'keywordprg'| Markdown content. Note that highlighting of code examples requires
was customized before calling |vim.lsp.start()|. a matching parser and may be affected by custom queries.
• |LspRequest| autocmd callbacks contain more information about the LSP
request status update that occurred.
• Terminal buffers started with no arguments (and use 'shell') close • Lua:
automatically if the job exited without error, eliminating the (often • |vim.wait()| cannot be called in |api-fast|.
unwanted) "[Process exited 0]" message. • |vim.diagnostic.config()| now accepts virtual text relevant options to
• |vim.diagnostic.config()| now accepts virtual text relevant options to
|nvim_buf_set_extmark()| (e.g. "virt_text_pos" and "hl_mode") in its |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" table, which gives users more control over how diagnostic
virtual text is displayed. virtual text is displayed.
• |vim.diagnostic.get()| and |vim.diagnostic.count()| accept multiple
• |vim.diagnostic.get()| and |vim.diagnostic.count()| accept multiple
namespaces rather than just a single namespace. namespaces rather than just a single namespace.
• |vim.diagnostic.enable()| gained new parameters, and the old signature is
• |vim.diagnostic.enable()| gained new parameters, and the old signature is
deprecated. deprecated.
• |vim.diagnostic.config()| now accepts a function for the virtual_text.prefix
option, which allows for rendering e.g., diagnostic severities differently.
• Extmarks now fully support multi-line ranges, and a single extmark can be • Options
used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()| • Attempting to set an invalid keycode option (e.g. `set t_foo=123`) no
API function already allowed you to define such ranges, but highlight regions longer gives an error.
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()|: • Terminal
- "undo_restore": opt-out extmarks of precise undo tracking. • Terminal buffers started with no arguments (and use 'shell') close
- "invalidate": automatically hide or delete extmarks. automatically if the job exited without error, eliminating the (often
- "virt_text_repeat_linebreak": repeat virtual text on wrapped lines. unwanted) "[Process exited 0]" message.
• 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)
• Treesitter • Treesitter
• |Query:iter_matches()|, |vim.treesitter.query.add_predicate()|, and • |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* REMOVED FEATURES *news-removed*
The following deprecated functions or APIs were removed. These deprecated features were removed.
• Vimball support • Vimball support
- :Vimuntar command - :Vimuntar command

6
runtime/doc/treesitter.txt
View File

@@ -1321,7 +1321,11 @@ LanguageTree:included_regions() *LanguageTree:included_regions()*
(`table<integer, Range6[]>`) (`table<integer, Range6[]>`)
LanguageTree:invalidate({reload}) *LanguageTree:invalidate()* 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: ~ Parameters: ~
• {reload} (`boolean?`) • {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. -- with types being renamed to include the vim namespace and with some descriptions made less verbose.
--- @brief <pre>help --- @brief <pre>help
--- LPeg is a pattern-matching library for Lua, based on --- LPeg is a pattern-matching library for Lua, based on Parsing Expression
--- Parsing Expression Grammars (https://bford.info/packrat/) (PEGs). --- Grammars (PEGs). https://bford.info/packrat/
--- ---
--- *lua-lpeg* --- *lua-lpeg* *vim.lpeg.Pattern*
--- *vim.lpeg.Pattern*
--- The LPeg library for parsing expression grammars is included as `vim.lpeg` --- The LPeg library for parsing expression grammars is included as `vim.lpeg`
--- (https://www.inf.puc-rio.br/~roberto/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 -- See 'lpeg.html' for license
--- @brief --- @brief
--- The `vim.re` module provides a conventional regex-like syntax for pattern usage --- The `vim.re` module provides a conventional regex-like syntax for pattern usage within LPeg
--- within LPeg |vim.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 --- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original documentation including
--- documentation including regex syntax and more concrete examples. --- regex syntax and examples.
--- Compiles the given {string} and returns an equivalent LPeg pattern. The given string may define --- 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 --- 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 hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
--- ---
--- local client = vim.lsp.get_client_by_id(hint.client_id) --- 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) --- vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding)
--- ---
--- location = resolved_hint.label[1].location --- 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 --- @alias vim.snippet.Direction -1 | 1
--- Jumps within the active snippet in the given direction. --- Jumps to the next (or previous) placeholder in the current snippet, if possible.
--- If the jump isn't possible, the function call does nothing.
--- ---
--- You can use this function to navigate a snippet as follows: --- For example, map `<Tab>` to jump while a snippet is active:
--- ---
--- ```lua --- ```lua
--- vim.keymap.set({ 'i', 's' }, '<Tab>', function() --- 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, ' ')) self._logger('nvim', table.concat(msg, ' '))
end 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 ---@param reload boolean|nil
function LanguageTree:invalidate(reload) function LanguageTree:invalidate(reload)
self._valid = false self._valid = false

14
scripts/cliff.toml
View File

@@ -4,27 +4,29 @@
# changelog header # changelog header
header = """ header = """
# Changelog\n # 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 # template for the changelog body
# https://github.com/Keats/tera # https://github.com/Keats/tera
# https://keats.github.io/tera/docs/ # https://keats.github.io/tera/docs/
body = """ body = """
{% if version %}\ {% 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 %}\ {% else %}\
## [unreleased] # [unreleased]
{% endif %}\ {% endif %}\
{% for group, commits in commits | group_by(attribute="group") %} {% for group, commits in commits | group_by(attribute="group") %}
### {{ group | striptags | upper_first }} {{ group | striptags | upper_first }}
--------------------------------------------------------------------------------
{% for commit in commits | sort(attribute="message")%}\ {% for commit in commits | sort(attribute="message")%}\
{% if not commit.scope %}\ {% if not commit.scope %}\
- {{ commit.message }} - {{ commit.id | truncate(length=12, end="") }} {{ commit.message }}
{% endif %}\ {% endif %}\
{% endfor %}\ {% endfor %}\
{% for group, commits in commits | group_by(attribute="scope") %}\ {% for group, commits in commits | group_by(attribute="scope") %}\
{% for commit in commits | sort(attribute="message") %}\ {% for commit in commits | sort(attribute="message") %}\
- **{{commit.scope}}**: {{ commit.message }} - {{ commit.id | truncate(length=12, end="") }} {{commit.scope}}: {{ commit.message }}
{% endfor %}\ {% endfor %}\
{% endfor %} {% endfor %}
{% endfor %}\n {% endfor %}\n

5
scripts/gen_help_html.lua
View File

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