Problem: LuaLS struggles with the generics used in Nvim's runtime,
requiring broad diagnostic suppressions. Indexing is also slow.
Solution: Use EmmyLua for type checks in the build and CI. It offers
more sophisticated type checking, substantially better support for
generics, and much better flow analysis.
Correct the affected annotations. Use `@internal`, supported directly by
EmmyLua, instead of `@nodoc` for shared internal declarations, and
support it in the help parser.
AI-assisted
Problem: K on generic and nullable type annotations can jump to the
wrong help tag. Generated See references repeat the type names.
Solution: Strip generic arguments and nullable suffixes when resolving
help tags. Remove the redundant generated See references.
AI-assisted
Problem:
In order for ui2 to graduate to the main "messages ui" its configuration
needs to graduate into actual options.
Solution:
Migrate some of its config to 'messagesopt':
- "maxheight" (note: currently this is an integer treated as
a "percentage"; if we want to support a row count we could allow
values with units, like `"42%"`)
- "pager"
- "timeout"
Also improves error messages:
messagesopt=hit-enter,history:500,bogus E474: Unknown item 'bogus'
messagesopt=hit-enter,history:500,progress:x E474: 'progress' must be one of: , c
messagesopt=hit-enter,history:abc E474: 'history' requires a number
Problem:
`pager_char` compares the `keytrans()` result exactly. E.g. `pager_char
= "<cr>"` does not work, it expects `<CR>` (uppercase).
Solution:
Normalize `pager_char` in enable().
Problem:
`vim.on_key()` callbacks are invoked for keys that `getchar()` consumes,
which never reach the main loop, and there is no way to tell such a key
apart. With ui2 the `on_key` handler activated after interactive
cmdline, handles it as `pager_char` (thus enters the ui2 pager).
Solution:
Skip `vim.on_key()` callbacks during `getchar()`/`getcharstr()`.
Problem:
`vim.fs.slug()` does not handle URIs like `term://foo//123:bash`,
so callers (e.g. terminal persistence) must strip the scheme before
calling `slug()`.
Solution:
Detect `scheme://` from the raw input before `normalize()` and
replace it with a `=uri-<scheme>-` prefix.
`opts.plain=true` does not expand tildes in addition to environment
variables, unlike `opts.expand_env=false`.
`opts.expand_env=false` is soft-deprecated.
Problem:
Several subsystems need to derive a short, filesystem-safe identifier from an
arbitrary path, and each reinvents it ad-hoc:
- `'undodir'` and `swapfiles` encode the full path into a single filename, which
may exceed filesystem length-limits.
- `:connect ssh://` needs the SSH ControlPath socket name to stay under the
104-byte `sun_path` limit on macOS; today the path overflows it.
- the upcoming :terminal state dir.
- arbitrary plugin purposes.
Solution:
Provide `vim.fs.slug()`, which generates a bounded, one-way filename from an
arbitrary string. The input is normalized so equivalent paths produce the
same result. An 8-char hash is appended for uniqueness
Adds optional parameters to `vim.fs.abspath`:
1. `cwd` to specify directory akin to `--relative-from` in `realpath(1)`.
2. `plain` disables expansion of tilde (~) in paths.
Problems:
1. Can't get individual parts of a key-chord separately: modifiers, key.
2. Can't separate a key-combo into individual key-chords.
Solution:
Enhance `vim.keycode()` to optionally return a structured parse result
as a list of key-chords:
- `key_raw` the key-chord (problem 2)
- `mod` the modifiers of `key_raw` (problem 1)
- `key_orig` the key part of the key-chord, only here if differing from `key`
(this doesn't solve any of the above mentioned problems, but it may provide
useful and it's (in terms of code) free)
- `key` a normalized version of `key_orig` (solving problem 1), example(the
first is `key_orig` and second is `key`): `lt` and `<`, `Bar` and `|` (in
`<C-Bar>`)
Problem:
- No UI for listing extmarks.
- `:marks` doesn't support cmdline-completion.
Solution:
- Add completion and extmarks support to `:marks`.
- Update `get_buf_local_marks` to include the ":" (prompt-buffer) mark.
Problem:
After 25439dad7e, `opts` is optional, but not params that follow it.
Solution:
- Update `gen_api_dispatch.lua`, docs, tests.
- Enhance the `nvim_get_api_info()` api-metadata to include a boolean
flag indicating whether a parameter is optional:
```
[type, name, optional]
```
Note: Currently, optional params are assumed to be Dict/Array. Since we
don't yet have any use-cases of optional params following `opts`, the
build just checks this assumption and we can deal with it later if we
ever care to:
nvim_get_hl: optional param "foo" has type "Integer" but (currently)
we assume Dict/Array
Problem:
`vim.fs` does not provide a directory creation helper matching its
filesystem API shape.
Solution:
Add `vim.fs.mkdir()` as a thin wrapper around `vim.fn.mkdir()`, with
`parents` and `mode` options.
Problem:
vim.fs.dir() and vim.fs.find() drop errors returned by uv.fs_scandir().
Solution:
- vim.fs.dir():
- Return root scan failures as a secondary return value.
- Propagate recursive scan failures through the iterator. This allows
callers to distinguish unreadable directories from empty ones.
- vim.fs.find(): Collect errors during search, and return the list as
a second retval.
Problem:
`nvim_set_option_value` cannot "update" options similar to `:set opt=`,
`:set opt+=`, etc. The Lua impls of "vim.opt" / "vim.o" have incomplete,
bespoke reimplementations of those operations.
ref #38420
Solution:
- Add `operation` param to `nvim_set_option_value`, which may be "set",
"append", "prepend", or "remove".
- Use this feature to implement `vim.opt` / `vim.o`.
Problem:
- `pos.cursor()` receives a table contains `row` and `col` as arguments,
but `pos:to_cursor` returns `row` and `col` directly
without wrapping them in a table.
- `pos.mark()`/`pos:to_mark` can already handle unpacked `row` `col`.
Solution:
Make `pos:to_cursor()` return a `row` and `col` in a table.
Problem:
`vim.pos.cursor(vim.api.nvim_get_current_buf(win), vim.api.nvim_win_get_cursor(win))`
is too verbose to create a cursor position of a window,
but it is a common use case.
Solution:
Overload `vim.pos.cursor()`, so that it accepts `win` as an argument when `pos` is omitted.
Problem:
Diagnostic highlight groups were applied by iterating and calling
`vim.hl.range` for each group individually. That resulted in multiple
extmarks with the same priority being created separately, which does not
allow `DiagnosticUnnecessary` and `DiagnosticDeprecated` with matching
options override `Diagnostic*` styling.
Solution:
Pass the list of hl-groups to `vim.hl.range` so they are applied
together in the correct order.
Problem:
It is repetitive to map multiple keymaps to do the same thing. Here are some
cases where being able to do this would be useful:
-- Visual movement for both j/k and down/up:
vim.keymap.set({ 'n', 'x' }, { 'j', '<Down>' }, 'v:count == 0 ? "gj" : "j"', { expr = true })
vim.keymap.set({ 'n', 'x' }, { 'k', '<Up>' }, 'v:count == 0 ? "gk" : "k"', { expr = true })
-- Map multiple keys to `<Nop>` concisely:
vim.keymap.set({ 'n', 'x' }, { '<Leader>', '<Localleader>', '<CR>' }, '<Nop>')
-- Remove multiple keymaps at once:
vim.keymap.del('n', { 'gri', 'grn', 'grr' })
Solution:
Support the `lhs` of `vim.keymap.set()` and `vim.keymap.del()` being a table, in
the same way that `modes` can be.
Problem:
Potential documentation drift in `tui.txt` if fields for
`$NVIM_TERMDEFS` change.
Solution:
Generate docs for `tui.txt`. Add `brief_xform` to `gen_vimdoc.lua` to
allow transforming briefs during generation.
Problem:
Our documentation is incomplete or inconsistent in several ways:
- Some public APIs lack corresponding validators.
- Some public APIs lack usage examples.
- The meaning of some return values or parameters is not clearly explained.
Solution:
Add the missing validators, examples, and clarifications.
Problem:
- A window can only have one cursor, ranges selected by the cursor are typically
obtained by marks like ">" and "<", instead of calling get_cursor() twice.
- `vim.Range` is described as end-exclusive,
but the current `range.cursor()`/`range:to_cursor()` are end-inclusive.
- Conversion between `vim.Range` and mark-indexed range can be done by
`range.mark()`/`range:to_mark()`
Solution:
Remove `range.cursor()` and `range:to_cursor()`,
Problem:
Ranges represented by marks are usually end-inclusive,
but the range utilities we provided are end-exclusive.
Solution:
Add pos:to_mark(), pos.mark(), range:to_mark(), and range.mark().
Problem: There is no way for a `vim.ui.input` caller to indicate for
which scope the input is. As in "This input is for something at cursor
scope". This information can be useful for `vim.ui.input`
implementation to tweak its behavior and presentation:
- Show different floating window depending on the scope. For example:
- Near cursor for "cursor" scope.
- At line start for "line" scope.
- In window corner for "buffer" and "window" scopes.
- In whole editor corner for "tabpage", "editor", "project" scopes.
- Navigate through history only for inputs with the same scope.
Solution: Document new `opts.scope` for `vim.ui.input`. Use it in the
codebase.
