aboutsummaryrefslogtreecommitdiff
path: root/runtime/doc/lua.txt
Commit message (Collapse)AuthorAge
* docs(help): specify h4 "function signature" format #42434masterJustin M. Keyes2 days
| | | | | | | | | | | | | | | | | | | | | Work towards enabling ["flow" layout](https://github.com/neovim/neovim/blob/9244da12e400ec0291450a5e9400d995e7a29b83/src/gen/gen_help_html.lua#L86-L88) in all `:help` files. Problem: The final boss of vimdoc pseudo-structure: Vim's quasi-headings on function signatures and excmd docs is visually distinctive but too inconsistent for a nice parse rule. Solution: - Define the quasi-heading format as an "h4" variant, specified at `:help help-tag-heading`. - For simplicity and predictability, it is defined as any line that ends with a help tag(s) preceded by 2 or more spaces (or 1 tab). - Update existing docs. - This one-time update has a lot of changes, but is very unlikely to conflict with ported Vim-patches because (1) Vim rarely adds new *excmds* that we want, and (2) *function* docs are auto-generated. ref https://github.com/neovim/tree-sitter-vimdoc/issues/110
* feat(inspector): support ranges in vim.inspect_posLewis Russell3 days
| | | | | | | | | | | | | | | | Problem: Highlight inspection is limited to a single position, and its result types do not document the fields shared by different highlight sources. Solution: Accept end_row/end_col in vim.inspect_pos to inspect a range. Keep range ends exclusive and retain the existing single-position behavior. Support Ex line ranges in :Inspect, including Visual selections. Document named result types, expose shared highlight fields, and keep the existing extmark details and buffer field for compatibility. AI-assisted
* fix(docs): listitems with codeblocks #42367Justin M. Keyes4 days
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Problem: - `<` before a listitem (`< - foo`) is not concealed. - Codeblock HTML has extra blank lines. - Codeblock in a listitem ends the listitem, so HTML docs drop the rest of the item and its nesting. Example from `:h nvim_open_win()`: ``` • border: … the double-box style can be specified as: > [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. < If fewer than eight chars are given, they will be repeated. • bufpos: … tree-sitter-vimdoc v4.1.0: (block (line_li (prefix) (line) (codeblock (code (line))))) (block (line) ; "If fewer…" (line_li (prefix) (line) (line))) ; "bufpos" tree-sitter-vimdoc v4.2.0: (block (line_li (prefix) (line) (codeblock (code (line))) (line)) ; "If fewer…" (line_li (prefix) (line) (line))) ; "bufpos" ``` Solution: - Bump tree-sitter-vimdoc to v4.2.0. https://github.com/neovim/tree-sitter-vimdoc/pull/174 - gen_help_html: get listitem indent from its first line - gen_help_html: don't double codeblock newlines. - highlight query: conceal `<` in `line_li`. - docs: fix doc sources where a blank line was missing after listitems followed by non-listitem text.
* feat(api): nvim_chan_set()Justin M. Keyes10 days
| | | | | | | | | | | | | | | | | | | Problem: Only the stdio channel can "own" a server (self-exit on close). After :restart the TUI reconnects over a socket, so the restarted server does not have "self-exit" behavior when the channel closes (e.g. by UI disconnect, host-terminal close, etc.), which leaves a dangling server. Solution: - Introduce `nvim_chan_set`. (`nvim_set_client_info` doesn't fit: exposing it to Lua would require a `channel` param, which is not backwards-compatible, plus it's awkward because it doesn't merge info.) - Broadcast per-channel properties in the "restart" UI event as an opaque dict (a potentially useful pattern for other UI-events in the future). - UIs are expected to restore the channel properties on restart. - `nvim_get_chan_info()` reports "detach". - Remove `nvim__chan_set_detach()`.
* fix(vim.fs): find{follow=true} skips symlink targets of the given `type` #42246Justin M. Keyes14 days
| | | | | | | | | Problem: `vim.fs.find()` checks `type` against the symlink itself, so `{ type='file', follow=true }` skips symlinked files (e.g. `:helptags`). Solution: With `follow=true`, a symlink has the type of its target. Thus `type='link'` only matches broken symlinks (like `find -L -type l`).
* ci(lua): enable annotation and style checksLewis Russell2026-09-30
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Problem: - annotation-usage-error and code-style-check are disabled. - vim.inspect relies on a dummy self-assignment for docgen, and its help omits parameter and option details. - LuaLS fallback types obscure iterator inference. - Docgen hardcodes public function names and appends separately sorted files, leaving shared helpers under the inspector heading. Solution: - Enable annotation-usage-error and code-style-check, and fix misplaced annotations. - Document vim.inspect's callable module directly, removing the dummy assignment. Describe its parameters, option defaults and process callback. - Remove LuaLS iterator fallbacks, correct iterator signatures and check values that the improved inference identifies as optional. - Parse callable modules, require bindings and parent module references. Derive public names and inherited function docs from these links, including missing help for vim.async.semaphore() and vim.version(). - Export vim.lsp.tagfunc directly with lazy loading and document its implementation instead of maintaining a wrapper. - Group files in section_order, replacing append_only and merge_files. Merge declarations before sorting each section, placing shared helpers in the main vim section and keeping vim.inspect in alphabetical order. - Add basic parser coverage for callable modules and module links. AI-assisted
* fix(lua): enable assignment type checking in runtime codeLewis Russell2026-09-25
| | | | | | | | | | | Enable EmmyLua's assign-type-mismatch diagnostic after correcting the runtime annotations and assignments it flags. Correct option, tuple, and return types, and use separate locals when a value changes representation. Add guards and narrow casts where needed so the runtime passes the stricter check. Regenerate the affected docs. AI-assisted
* perf(hightlight): compute only bounds for non-blockwise highlightsVolodymyr Chernetskyi2026-09-16
| | | | | | | | | | | | | Problem: vim.hl.range() computes a segment for every selected line, then discards all but the outer endpoints for characterwise and linewise highlights. This makes highlighting large yanks and puts unnecessarily expensive. Solution: Use getregionpos() with bounds=true for these highlights. Also use bounds in the keymap example that only needs the first and last selected lines. AI-assisted
* fix(lua): add missing param annotations (#41911)Lewis Russell2026-09-15
|
* build: enable more EmmyLua checksLewis Russell2026-09-08
| | | | | | | | | | | | | | | | - call-non-callable - missing-fields - redefined-label - redefined-local - undefined-field - unreachable-code Promote redefined-local and unreachable-code to warnings. Fix DOS line-ending handling for multiline semantic tokens, and support intersection types in the help parser. AI-assisted
* build: replace LuaLS with EmmyLuaLewis Russell2026-09-07
| | | | | | | | | | | | | | | 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
* fix(help): resolve generic and nullable type referencesLewis Russell2026-09-07
| | | | | | | | | | 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
* feat(ui2): lift ui2 options into 'messagesopt' (part 1) #41474Justin M. Keyes2026-08-25
| | | | | | | | | | | | | | | | | | | 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
* fix(ui2): pager_char does not match keycode aliases #41468Justin M. Keyes2026-08-24
| | | | | | | | 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().
* fix(ui2): ui2 misinterprets getchar() input as pager_char (CR) #41465Justin M. Keyes2026-08-24
| | | | | | | | | | 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()`.
* docs: misc #41452Justin M. Keyes2026-08-23
| | | | | Co-authored-by: darkdi <rantovov5@gmail.com> Co-authored-by: Qiaoxi Guo <28090444+breadtitor@users.noreply.github.com> Co-authored-by: zaveshaa <zaveshaa@gmail.com>
* feat(ui2): drop default enter-pager-via-CR mapping #40993Rob Pilling2026-08-17
|
* feat(vim.fs): slug() supports URI #41241Willaaaaaaa2026-08-16
| | | | | | | | | | 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.
* docs: misc, :bcd, slug()Justin M. Keyes2026-08-06
|
* feat(fs): vim.fs.normalize{plain:boolean} #41127Olivia Kinnear2026-08-05
| | | | | | `opts.plain=true` does not expand tildes in addition to environment variables, unlike `opts.expand_env=false`. `opts.expand_env=false` is soft-deprecated.
* feat(lua): vim.fs.slug() #41005Willaaaaaaa2026-08-04
| | | | | | | | | | | | | | | | 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
* docs: func/expr options, misc #41102Justin M. Keyes2026-08-01
|
* feat(vim.fs): abspath({cwd, plain}) #40597AlexCodesApps2026-08-01
| | | | | 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.
* docs: misc #41063Justin M. Keyes2026-07-30
|
* feat(pos): vim.pos.cursor() without args returns curwin pos #40975Olivia Kinnear2026-07-28
|
* fix(lua): vim.regex():match_str abort in Luv callback #41008Justin M. Keyes2026-07-27
|
* Merge #40910 from barrettruth/fix/dir-literal-env-pathsJustin M. Keyes2026-07-26
|\
| * feat(vim.fs): dir(opts.normalize)Barrett Ruth2026-07-25
| |
* | fix(api): add `lhs` option for keymap deletionBarrett Ruth2026-07-25
| |
* | docs: misc #40847Justin M. Keyes2026-07-25
|/ | | | Co-authored-by: Barrett Ruth <br@barrettruth.com> Co-authored-by: Nathan Zeng <nathan.j.zeng@gmail.com>
* feat(lua): Iter:count() #40831PinkLea2026-07-20
|
* feat(eval): declare more "fast" functions #40834Justin M. Keyes2026-07-19
|
* fix(lua): vim.keycode cleanup #40817Justin M. Keyes2026-07-18
|
* feat(lua): vim.keycode() gets structured parse result #38636altermo2026-07-18
| | | | | | | | | | | | | | | | | 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>`)
* docs: misc, remove some old help tags #40214Justin M. Keyes2026-07-18
| | | | | | | | | | - Remove old help tags: they add noise to cmdline completion. Co-authored-by: acehinnnqru <acehinnnqru@gmail.com> Co-authored-by: KangaZero <samuelyongw@gmail.com> Co-authored-by: Simone Ragusa <hi@interrato.dev> Co-authored-by: Chinmay Dalal <~chinmay/public-inbox@lists.sr.ht> Co-authored-by: coyaSONG <66289470+coyaSONG@users.noreply.github.com> Co-authored-by: Olivia Kinnear <git@superatomic.dev>
* feat(marks): :marks completion, list extmarks #40743Justin M. Keyes2026-07-15
| | | | | | | | | 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.
* feat(api): optional params after `opts` #40720Justin M. Keyes2026-07-13
| | | | | | | | | | | | | | | | | | | | Problem: After 25439dad7e2b, `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
* refactor(logging)!: rename current_level #40642Justin M. Keyes2026-07-08
|
* feat(vim.fs): vim.fs.mkdir() #40599Barrett Ruth2026-07-08
| | | | | | | | | 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.
* feat(vim.fs): dir() ergonomicsJustin M. Keyes2026-07-01
|
* fix(vim.fs): dir(), find() error-reportingJustin M. Keyes2026-07-01
|
* feat(vim.fs): dir(), find() error-reportingRudrajeet Pal2026-07-01
| | | | | | | | | | | | | | 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.
* refactor: cleanup, docs #40480Justin M. Keyes2026-06-29
|
* feat(api): nvim_set_option_value(operation=...) #39849Kyle2026-06-28
| | | | | | | | | | | | | 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`.
* Merge #40087 from ofseed/pos-util-follow-upJustin M. Keyes2026-06-14
|\ | | | | feat(pos): create a cursor position by using the current of a window
| * feat(pos)!: match return value of `to_cursor()` with parameters of `cursor()`Yi Ming2026-06-08
| | | | | | | | | | | | | | | | | | | | | | 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.
| * feat(pos): create a cursor position by using the current of a windowYi Ming2026-06-08
| | | | | | | | | | | | | | | | | | | | 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.
* | fix(docs): numbered listitemsJustin M. Keyes2026-06-11
| |
* | docs: misc #40126Justin M. Keyes2026-06-08
|/
* fix(diagnostic): stack _tags hl-groups in a single extmark #38654Artem Krinitsyn2026-06-02
| | | | | | | | | | | | 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.