diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2533f740f..d080f3079e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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]. diff --git a/MAINTAIN.md b/MAINTAIN.md index 5cb97fb81b..f7f0c5769c 100644 --- a/MAINTAIN.md +++ b/MAINTAIN.md @@ -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 diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 309d5b7d60..06f8319453 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -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. diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt index 85aeddd425..6c805963a9 100644 --- a/runtime/doc/dev_style.txt +++ b/runtime/doc/dev_style.txt @@ -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/ diff --git a/runtime/doc/dev_theme.txt b/runtime/doc/dev_theme.txt index 29a2da0d90..532506abcb 100644 --- a/runtime/doc/dev_theme.txt +++ b/runtime/doc/dev_theme.txt @@ -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: diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 11c25362b6..adbe4eeeff 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -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 diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 584fef0ed2..7f6a2e3b73 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -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 diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 20a53537bc..0be3c24b0a 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -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 `` to jump while a snippet is active: >lua vim.keymap.set({ 'i', 's' }, '', function() if vim.snippet.active({ direction = 1 }) then return 'lua vim.snippet.jump(1)' diff --git a/runtime/doc/news-0.9.txt b/runtime/doc/news-0.9.txt index 20c92a2750..7905d6c3e3 100644 --- a/runtime/doc/news-0.9.txt +++ b/runtime/doc/news-0.9.txt @@ -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. diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 6045acf935..3ffc844344 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -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 ) 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=` • 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" (|vim + :call netrw#BrowseX(expand(exists("g:netrw_gx")? g:netrw_gx : ''), netrw#CheckIfRemote()) -• |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| - • d (and ) 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 : ''), netrw#CheckIfRemote()) - -• |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 diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 7ee3769bbd..e105d06ebb 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -1321,7 +1321,11 @@ LanguageTree:included_regions() *LanguageTree:included_regions()* (`table`) 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?`) diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua index 1ce40f3340..73b3375c82 100644 --- a/runtime/lua/vim/_meta/lpeg.lua +++ b/runtime/lua/vim/_meta/lpeg.lua @@ -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 
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/).
 ---
diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua
index 9721e6f8c8..d16751fbbf 100644
--- a/runtime/lua/vim/_meta/re.lua
+++ b/runtime/lua/vim/_meta/re.lua
@@ -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
diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua
index 8d22859a80..f98496456b 100644
--- a/runtime/lua/vim/lsp/inlay_hint.lua
+++ b/runtime/lua/vim/lsp/inlay_hint.lua
@@ -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
diff --git a/runtime/lua/vim/snippet.lua b/runtime/lua/vim/snippet.lua
index 2d95d4203d..3d8f73f362 100644
--- a/runtime/lua/vim/snippet.lua
+++ b/runtime/lua/vim/snippet.lua
@@ -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 `` to jump while a snippet is active:
 ---
 --- ```lua
 --- vim.keymap.set({ 'i', 's' }, '', function()
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
index e618f29f8f..270d869e43 100644
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@@ -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
diff --git a/scripts/cliff.toml b/scripts/cliff.toml
index ac060b7796..51725cacfc 100644
--- a/scripts/cliff.toml
+++ b/scripts/cliff.toml
@@ -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 = "Breaking"},
-    { message = "^feat", group = "Features"},
-    { message = "^fix", group = "Bug Fixes"},
-    { message = "^perf", group = "Performance"},
-    { message = "^build", group = "Build System"},
-    { message = "^vim-patch", group = "Vim patches"},
-    { message = "^refactor", group = "Refactor" },
+    { message = "!:", group = "BREAKING"},
+    { message = "^feat", group = "FEATURES"},
+    { message = "^fix", group = "FIXES"},
+    { message = "^perf", group = "PERFORMANCE"},
+    { message = "^build", group = "BUILD"},
+    { message = "^vim-patch", group = "VIM PATCHES"},
+    { message = "^refactor", group = "REFACTOR" },
     { message = "^ci", group = "CI" },
-    { message = "^test", group = "Testing" },
-    { message = "^docs", group = "Documentation" },
-    { message = "^revert", group = "Reverted Changes" },
-    { message = ".*", group = "Other"},
+    { message = "^test", group = "TESTING" },
+    { message = "^docs", group = "DOCUMENTATION" },
+    { message = "^revert", group = "REVERTED CHANGES" },
+    { message = ".*", group = "OTHER"},
 ]
 # filter out the commits that are not matched by commit parsers
 filter_commits = true
diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 7051c8dbc3..d65f3aace2 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -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,
diff --git a/scripts/git-log-pretty-since.sh b/scripts/git-log-pretty-since.sh
deleted file mode 100755
index 95dcee23f5..0000000000
--- a/scripts/git-log-pretty-since.sh
+++ /dev/null
@@ -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
diff --git a/scripts/release.sh b/scripts/release.sh
index f798b81d6a..8e26ecb244 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -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}"