news.txt

*news.txt*    Nvim


                            NVIM REFERENCE MANUAL


Notable changes in Nvim 0.10 from 0.9                                    *news*

For changes in Nvim 0.9, see |news-0.9|.

                                       Type |gO| to see the table of contents.

==============================================================================
BREAKING CHANGES                                                *news-breaking*

The following changes may require adaptations in user config or plugins.

• In some cases, the cursor in the Nvim |TUI| would 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
<
• |vim.tbl_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.tbl_isarray()|.

• "#" 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
<
  - If you used `:behave mswin`, the following is equivalent: >vim

    set selection=exclusive
    set selectmode=mouse,key
    set mousemodel=popup
    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
  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 "Neovim branded" and accessible.
  Use `:colorscheme vim` to revert to the old legacy color scheme.

• 'termguicolors' is enabled by default when Nvim is able to determine that
  the host terminal emulator supports 24-bit color.

==============================================================================
BREAKING CHANGES IN HEAD                                    *news-breaking-dev*

The following breaking changes were made during the development cycle to
unreleased features on Nvim HEAD.

• ...
• ...

==============================================================================
NEW FEATURES                                                    *news-features*

The following new APIs and 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.

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

• |nvim_buf_set_extmark()| supports inline virtual text.

• 'foldtext' now supports virtual text format. |fold-foldtext|

• The terminal buffer now supports reflow (wrapped lines adapt when the buffer
  is resized horizontally). Note: Lines that are not visible and kept in
  |'scrollback'| are not reflown.

• |vim.system()| for running system commands.

• |vim.lpeg| and |vim.re| expose the bundled Lpeg expression grammar parser
  and its regex interface.

• |nvim_win_text_height()| computes the number of screen lines occupied
  by a range of text in a given window.

• |nvim_set_keymap()| and |nvim_del_keymap()| now support abbreviations.

• Better cmdline completion for string option value. |complete-set-option|

• Builtin TUI can now recognize "super" (|<D-|) and "meta" (|<T-|) modifiers in a
  terminal emulator that supports |tui-csiu|.

• Editor
  • 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|

• LSP
  • LSP method names are available in |vim.lsp.protocol.Methods|.
  • Implemented LSP inlay hints: |lsp-inlay_hint|
    https://microsoft.github.io/language-server-protocol/specification/#textDocument_inlayHint
  • Implemented pull diagnostic textDocument/diagnostic: |vim.lsp.diagnostic.on_diagnostic()|
    https://microsoft.github.io/language-server-protocol/specification/#textDocument_diagnostic
  • |vim.lsp.status()| consumes the last progress messages as a string.
  • LSP client now always saves and restores named buffer marks when applying
    text edits.
  • LSP client now supports the `positionEncoding` server capability. If a server
    responds with the `positionEncoding` capability in its initialization
    response, Nvim automatically sets the client's `offset_encoding` field.
  • Dynamic registration of LSP capabilities. An implication of this change is
    that checking a client's `server_capabilities` is no longer a sufficient
    indicator to see if a server supports a feature. Instead use
    `client.supports_method(<method>)`. It considers both the dynamic
    capabilities and static `server_capabilities`.
  • `anchor_bias` option to |lsp-handlers| aids in positioning of floating
    windows.
  • |vim.lsp.util.locations_to_items()| sets the `user_data` of each item to
    the original LSP `Location` or `LocationLink`.

• Treesitter
  • Bundled parsers and queries (highlight, folds) for Markdown, Python, and
    Bash.
  • |vim.treesitter.query.omnifunc()| for treesitter query files (set by
    default).
  • |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
    language aliases (e.g., filetype or custom shorthands) registered via
    |vim.treesitter.language.register()| and/or attempt lower case variants of
    the text.
  • The `#set!` directive now 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.
  • |vim.treesitter.foldtext()| applies treesitter highlighting to
    foldtext.

• |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 currently supported.

• Lua type annotations for:
  • `vim.*`
  • `vim.fn.*`
  • `vim.api.*`

• 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|

• New RPC client type `msgpack-rpc` is added for |nvim_set_client_info()| to
  support fully MessagePack-RPC compliant clients.

• Floating windows can now show footer with new `footer` and `footer_pos`
  config fields. Uses |hl-FloatFooter| by default.

• Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or
  |nvim_win_set_config()|.

• The |:terminal| command now accepts some |:command-modifiers| (specifically
  |:horizontal| and those that affect splitting a window).

• |$NVIM_APPNAME| can be set to a relative path instead of only a name.

• |:fclose| command.

• |vim.snippet| handles expansion of snippets in LSP format.

• 'complete' option supports "f" flag for completing buffer names.

• |vim.base64.encode()| and |vim.base64.decode()| encode and decode strings
  using Base64 encoding.

• The |TermResponse| autocommand event can be used with |v:termresponse| to
  read escape sequence responses from the terminal.

• A clipboard provider which uses OSC 52 to copy the selection to the system
  clipboard is now bundled by default and will be automatically enabled under
  certain conditions. |clipboard-osc52|

• The 'termsync' option asks the terminal emulator to buffer screen updates
  until the redraw cycle is complete. Requires support from the terminal.

• |vim.text.hexencode()| and |vim.text.hexdecode()| convert strings to and
  from byte representations.

==============================================================================
CHANGED FEATURES                                                 *news-changed*

The following changes to existing APIs or features add new behavior.

• |vim.tbl_contains()| now works for general tables and allows specifying a
  predicate function that is checked for each value. (Use |vim.list_contains()|
  for checking list-like tables (integer keys without gaps) for literal values.)

• |vim.region()| can use a string accepted by |getpos()| as position.

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

• The `workspace/didChangeWatchedFiles` LSP client capability is now enabled
  by default.

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

• |:checkhealth| buffer now implements |folding|. The initial folding status is
  defined by the 'foldenable' option.

• |:Man| now respects 'wrapmargin'

• |gx| now uses |vim.ui.open()| and not netrw. To customize, you can redefine
  `vim.ui.open` or remap `gx`. To continue using netrw (deprecated): >vim

  :call netrw#BrowseX(expand(exists("g:netrw_gx")? g:netrw_gx : '<cfile>'), netrw#CheckIfRemote())<CR>

• |vim.lsp.start()| now maps |K| to use |vim.lsp.buf.hover()| if the server
  supports it, 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.

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

• Extmarks can opt-out of precise undo tracking using the new "undo_restore"
  flag to |nvim_buf_set_extmark()|

• Extmarks can be automatically hidden or removed using the new "invalidate"
  flag to |nvim_buf_set_extmark()|

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

==============================================================================
REMOVED FEATURES                                                 *news-removed*

The following deprecated functions or APIs were removed.

• Vimball support
  - :Vimuntar command

• Support for legacy treesitter injection queries

• 'shortmess' flags:
  - |shm-f|. Always uses "(3 of 5)", never "(file 3 of 5)"
  - |shm-i|. Always use "[noeol]".
  - |shm-x|. Always use "[dos]", "[unix]" and "[mac]"
  - |shm-n|. Always use "[New]".

==============================================================================
DEPRECATIONS                                                *news-deprecations*

The following functions are now deprecated and will be removed in a future
release.

• Checkhealth functions:
  - |health#report_error|, |vim.health.report_error()|	Use |vim.health.error()| instead.
  - |health#report_info|, |vim.health.report_info()|	Use |vim.health.info()| instead.
  - |health#report_ok|, |vim.health.report_ok()|	Use |vim.health.ok()| instead.
  - |health#report_start|, |vim.health.report_start()|	Use |vim.health.start()| instead.
  - |health#report_warn|, |vim.health.report_warn()|	Use |vim.health.warn()| instead.

• |API| functions:
  - |nvim_buf_get_option()|	Use |nvim_get_option_value()| instead.
  - |nvim_buf_set_option()|	Use |nvim_set_option_value()| instead.
  - |nvim_get_option()|		Use |nvim_get_option_value()| instead.
  - |nvim_set_option()|		Use |nvim_set_option_value()| instead.
  - |nvim_win_get_option()|	Use |nvim_get_option_value()| instead.
  - |nvim_win_set_option()|	Use |nvim_set_option_value()| instead.

• vim.lsp functions:
  - |vim.lsp.util.get_progress_messages()|	Use |vim.lsp.status()| instead.
  - |vim.lsp.get_active_clients()|		Use |vim.lsp.get_clients()| instead.
  - |vim.lsp.for_each_buffer_client()|		Use |vim.lsp.get_clients()| instead.
  - |vim.lsp.util.trim_empty_lines()|		Use |vim.split()| with `trimempty` instead.
  - |vim.lsp.util.try_trim_markdown_code_blocks()|
  - |vim.lsp.util.set_lines()|
  - |vim.lsp.util.extract_completion_items()|
  - |vim.lsp.util.parse_snippet()|
  - |vim.lsp.util.text_document_completion_list_to_complete_items()|

• `vim.loop` has been renamed to |vim.uv|.

• vim.treesitter.languagetree functions:
  - |LanguageTree:for_each_child()|	Use |LanguageTree:children()| (non-recursive) instead.

• The "term_background" UI option |ui-ext-options| is deprecated and no longer
  populated. Background color detection is now performed in Lua by the Nvim
  core, not the TUI.

 vim:tw=78:ts=8:sw=2:et:ft=help:norl: