commit 4f3aa7bafb75b56acb3d16a7c35a9cb589d86c1e parent 7a69fefdb95daba355aa1b05ebfdf4d0b0d51ec2 Author: Justin M. Keyes <justinkz@gmail.com> Date: Thu, 10 Jul 2025 22:36:16 -0400 Merge #34558 docs Diffstat:
33 files changed, 1084 insertions(+), 1142 deletions(-)
diff --git a/runtime/doc/api-ui-events.txt b/runtime/doc/api-ui-events.txt @@ -0,0 +1,906 @@ +*api-ui-events.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Nvim UI protocol *UI* *ui* *api-ui-events* + +This document describes the UI protocol. See |gui| and |tui| for user-facing +UI components and features. + + Type |gO| to see the table of contents. + +============================================================================== +UI Events *ui-protocol* *ui-events* + +UIs can be implemented as external client processes communicating with Nvim +over the RPC API. The default UI model is a terminal-like grid with a single, +monospace font. The UI can opt-in to have windows drawn on separate grids, and +have some elements ("widgets") presented by the UI itself rather than by Nvim +("externalized"). + + *ui-option* +Call |nvim_ui_attach()| to tell Nvim that your program wants to draw the Nvim +screen grid with a size of width × height cells. This is typically done by an +embedder at startup (see |ui-startup|), but UIs can also connect to a running +Nvim instance and invoke nvim_ui_attach(). The `options` parameter is a map +with these (optional) keys: + + *ui-rgb* +- `rgb` Decides the color format. + - true: (default) 24-bit RGB colors + - false: Terminal colors (8-bit, max 256) + + *ui-override* +- `override` Decides how UI capabilities are resolved. + - true: Enable requested UI capabilities, even if not + supported by all connected UIs (including |TUI|). + - false: (default) Disable UI capabilities not + supported by all connected UIs (including TUI). + + *ui-ext-options* +- `ext_cmdline` Externalize the cmdline. |ui-cmdline| +- `ext_hlstate` Detailed highlight state. |ui-hlstate| + Sets `ext_linegrid` implicitly. +- `ext_linegrid` Line-based grid events. |ui-linegrid| + Deactivates |ui-grid-old| implicitly. +- `ext_messages` Externalize messages. |ui-messages| + Sets `ext_linegrid` and `ext_cmdline` implicitly. +- `ext_multigrid` Per-window grid events. |ui-multigrid| + Sets `ext_linegrid` implicitly. +- `ext_popupmenu` Externalize |popupmenu-completion| and + 'wildmenu'. |ui-popupmenu| +- `ext_tabline` Externalize the tabline. |ui-tabline| +- `ext_termcolors` Use external default colors. +- `term_name` Sets the name of the terminal 'term'. +- `term_colors` Sets the number of supported colors 't_Co'. +- `stdin_fd` Read buffer 1 from this fd as if it were stdin |--|. + Only from |--embed| UI on startup. |ui-startup-stdin| +- `stdin_tty` Tells if `stdin` is a `tty` or not. +- `stdout_tty` Tells if `stdout` is a `tty` or not. + +Specifying an unknown option is an error; UIs can check the |api-metadata| +`ui_options` key for supported options. + +By default Nvim requires all connected UIs to support the same capabilities, +thus the active capabilities are the intersection of those requested. UIs may +specify |ui-override| to invert this behavior (useful for debugging). The +"option_set" event announces which capabilities are active. + +Nvim sends RPC notifications to all attached UIs, with method name "redraw" +and a single argument: an array (batch) of screen "update events". Each update +event is itself an array whose first element is the event name and remaining +elements are event-parameter tuples. Thus multiple events of the same kind can +be sent contiguously without repeating the event name. + +Example of a typical "redraw" batch in a single RPC notification: > + + ['notification', 'redraw', + [ + ['grid_resize', [2, 77, 36]], + ['grid_line', + [2, 0, 0, [[' ' , 0, 77]], false], + [2, 1, 0, [['~', 7], [' ', 7, 76]], false], + [2, 9, 0, [['~', 7], [' ', 7, 76]], false], + ... + [2, 35, 0, [['~', 7], [' ', 7, 76]], false], + [1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']], false], + [1, 36, 9, [[' ', 9, 50]], false], + [1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]], false] + ], + ['msg_showmode', [[]]], + ['win_pos', [2, 1000, 0, 0, 77, 36]], + ['grid_cursor_goto', [2, 0, 0]], + ['flush', []] + ] + ] + +Events must be handled in-order. Nvim sends a "flush" event when it has +completed a redraw of the entire screen (so all windows have a consistent view +of buffer state, options, etc.). Multiple "redraw" batches may be sent before +the entire screen has been redrawn, with "flush" following only the last +batch. The user should only see the final state (when "flush" is sent), not +any intermediate state while processing part of the batch array, nor after +a batch not ending with "flush". + +By default, Nvim sends |ui-global| and |ui-grid-old| events (for backwards +compatibility); these suffice to implement a terminal-like interface. However +the new |ui-linegrid| represents text more efficiently (especially highlighted +text), and allows UI capabilities requiring multiple grids. New UIs should +implement |ui-linegrid| instead of |ui-grid-old|. + +Nvim optionally sends various screen elements "semantically" as structured +events instead of raw grid-lines, as specified by |ui-ext-options|. The UI +must present such elements itself, Nvim will not draw them on the grid. + +Future versions of Nvim may add new update kinds and may append new parameters +to existing update kinds. Clients must be prepared to ignore such extensions, +for forward-compatibility. |api-contract| + +============================================================================== +UI startup *ui-startup* + +UI embedders (clients that start Nvim with |--embed| and later call +|nvim_ui_attach()|) must start Nvim without |--headless|: >bash + nvim --embed +Nvim will pause before loading startup files and reading buffers, so the UI +has a chance to invoke requests and do early initialization. Startup will +continue when the UI invokes |nvim_ui_attach()|. + +A simple UI only needs to do a single |nvim_ui_attach()| request and then +prepare to handle any UI event. A more featureful UI, which might need +additional configuration of the Nvim process, should use the following startup +procedure: + +1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or + to get the list of supported UI extensions. + +2. Do any configuration that should be happen before user config is loaded. + Buffers and windows are not available at this point, but this could be used + to set |g:| variables visible to init.vim + +3. If the UI wants to do additional setup after user config is loaded, + register a VimEnter autocmd: >lua + nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')") + +4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now: + sourcing init.vim and loading buffers might lead to blocking prompts. + +5. If step 3 was used, Nvim will send a blocking "vimenter" request to the UI. + Inside this request handler, the UI can safely do any initialization before + entering normal mode, for example reading variables set by init.vim. + + *ui-startup-stdin* +UIs can support reading from stdin (like `command | nvim -`, see |--|) as follows: + +1. The embedding process detects that the stdin fd is not a terminal. +2. It then needs to forward this fd to Nvim. Because fd=0 is already is used + to send RPC data from embedder to Nvim, it must use some other file + descriptor, like fd=3 or higher. +3. Then pass the fd as the `stdin_fd` parameter of `nvim_ui_attach`. Nvim will + read it as text into buffer 1. + +============================================================================== +Global Events *ui-global* + +The following UI events are always emitted, and describe global state of +the editor. + +["set_title", title] ~ +["set_icon", icon] ~ + Set the window title, and icon (minimized) window title, respectively. + In windowing systems not distinguishing between the two, "set_icon" + can be ignored. + +["mode_info_set", cursor_style_enabled, mode_info] ~ + `cursor_style_enabled` is a boolean indicating if the UI should set + the cursor style. `mode_info` is a list of mode property maps. The + current mode is given by the `mode_idx` field of the `mode_change` + event. + + Each mode property map may contain these keys: + + KEY DESCRIPTION ~ + `cursor_shape`: "block", "horizontal", "vertical" + `cell_percentage`: Cell % occupied by the cursor. + `blinkwait`, `blinkon`, `blinkoff`: See |cursor-blinking|. + `attr_id`: Cursor attribute id (defined by `hl_attr_define`). + When attr_id is 0, the background and foreground + colors should be swapped. + `attr_id_lm`: Cursor attribute id for when |:lmap| is on. + `short_name`: Mode code name, see 'guicursor'. + `name`: Mode descriptive name. + `mouse_shape`: (To be implemented.) + + Some keys are missing in some modes. + + The following keys are deprecated: + + `hl_id`: Use `attr_id` instead. + `id_lm`: Use `attr_id_lm` instead. + +["option_set", name, value] ~ + UI-related option changed, where `name` is one of: + + - 'arabicshape' + - 'ambiwidth' + - 'emoji' + - 'guifont' + - 'guifontwide' + - 'linespace' + - 'mousefocus' + - 'mousehide' + - 'mousemoveevent' + - 'pumblend' + - 'showtabline' + - 'termguicolors' + - "ext_*" (all |ui-ext-options|) + + Triggered when the UI first connects to Nvim, and whenever an option + is changed by the user or a plugin. + + Options are not represented here if their effects are communicated in + other UI events. For example, instead of forwarding the 'mouse' option + value, the "mouse_on" and "mouse_off" UI events directly indicate if + mouse support is active. Some options like 'ambiwidth' have already + taken effect on the grid, where appropriate empty cells are added, + however a UI might still use such options when rendering raw text + sent from Nvim, like for |ui-cmdline|. + +["chdir", path] ~ + The |current-directory| changed to `path`. + +["mode_change", mode, mode_idx] ~ + Editor mode changed. The `mode` parameter is a string representing + the current mode. `mode_idx` is an index into the array emitted in + the `mode_info_set` event. UIs should change the cursor style + according to the properties specified in the corresponding item. The + set of modes reported will change in new versions of Nvim, for + instance more submodes and temporary states might be represented as + separate modes. + +["mouse_on"] ~ +["mouse_off"] ~ + 'mouse' was enabled/disabled in the current editor mode. Useful for + a terminal UI, or embedding into an application where Nvim mouse would + conflict with other usages of the mouse. Other UI:s may ignore this event. + +["busy_start"] ~ +["busy_stop"] ~ + Indicates to the UI that it must stop rendering the cursor. This event + is misnamed and does not actually have anything to do with busyness. + +["restart", progpath, argv] ~ + |:restart| command has been used and the Nvim server is about to exit. + The UI should wait for the server to exit, and then start a new server + using `progpath` as the full path to the Nvim executable |v:progpath| and + `argv` as its arguments |v:argv|, and reattach to the new server. + Note: |--embed| and |--headless| are excluded from `argv`, and the client + should decide itself whether to add either flag. + +["suspend"] ~ + |:suspend| command or |CTRL-Z| mapping is used. A terminal client (or + another client where it makes sense) could suspend itself. Other + clients can safely ignore it. + +["update_menu"] ~ + The menu mappings changed. + +["bell"] ~ +["visual_bell"] ~ + Notify the user with an audible or visual bell, respectively. + +["flush"] ~ + Nvim is done redrawing the screen. For an implementation that renders + to an internal buffer, this is the time to display the redrawn parts + to the user. + +============================================================================== +Grid Events (line-based) *ui-linegrid* + +Activated by the `ext_linegrid` |ui-option|. Recommended for all new UIs. +Deactivates |ui-grid-old| implicitly. + +Unlike |ui-grid-old|, this UI extension emits a single `grid_line` event to +update a screen-line (whereas the old protocol emitted separate cursor, +highlight and text events per screen-line). + +Most of these events take a `grid` index as first parameter. Grid 1 is the +global grid used by default for the entire editor screen state. The +`ext_linegrid` capability by itself will never cause any additional grids to +be created; to enable per-window grids, activate |ui-multigrid|. + +Highlight attribute groups are predefined. UIs should maintain a table to map +numerical highlight ids to the actual attributes. + +["grid_resize", grid, width, height] ~ + Resize a `grid`. If `grid` wasn't seen by the client before, a new grid is + being created with this size. + +["default_colors_set", rgb_fg, rgb_bg, rgb_sp, cterm_fg, cterm_bg] ~ + The first three arguments set the default foreground, background and + special colors respectively. `cterm_fg` and `cterm_bg` specifies the + default color codes to use in a 256-color terminal. + + The RGB values will always be valid colors, by default. If no + colors have been set, they will default to black and white, depending + on 'background'. By setting the `ext_termcolors` option, instead + -1 will be used for unset colors. This is mostly useful for a TUI + implementation, where using the terminal builtin ("ANSI") defaults + are expected. + + Note: Unlike the corresponding |ui-grid-old| events, the screen is not + always cleared after sending this event. The UI must repaint the + screen with changed background color itself. + + *ui-event-hl_attr_define* +["hl_attr_define", id, rgb_attr, cterm_attr, info] ~ + Add a highlight with `id` to the highlight table, with the + attributes specified by the `rgb_attr` and `cterm_attr` dicts, with the + following (all optional) keys. + + `foreground`: foreground color. + `background`: background color. + `special`: color to use for various underlines, when + present. + `reverse`: reverse video. Foreground and background colors + are switched. + `italic`: italic text. + `bold`: bold text. + `strikethrough`: struckthrough text. + `underline`: underlined text. The line has `special` color. + `undercurl`: undercurled text. The curl has `special` color. + `underdouble`: double underlined text. The lines have `special` color. + `underdotted`: underdotted text. The dots have `special` color. + `underdashed`: underdashed text. The dashes have `special` color. + `altfont`: alternative font. + `blend`: blend level (0-100). Could be used by UIs to + support blending floating windows to the + background or to signal a transparent cursor. + `url`: URL associated with this highlight. UIs should + present the region as a clickable hyperlink. + + For absent color keys the default color should be used. Don't store + the default value in the table, rather a sentinel value, so that + a changed default color will take effect. + All boolean keys default to false, and will only be sent when they + are true. + + Highlights are always transmitted both for both the RGB format and as + terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters + respectively. The |ui-rgb| option has no effect anymore. + Most external UIs will only need to store and use the `rgb_attr` + attributes. + + `id` 0 will always be used for the default highlight with colors defined + by `default_colors_set` and no styles applied. + + Note: Nvim may reuse `id` values if its internal highlight table is full. + In that case Nvim will always issue redraws of screen cells that are + affected by redefined ids, so UIs do not need to keep track of this + themselves. + + `info` is an empty array unless |ui-hlstate| is enabled. + +["hl_group_set", name, hl_id] ~ + The built-in highlight group `name` was set to use the attributes `hl_id` + defined by a previous `hl_attr_define` call. This event is not needed + to render the grids which use attribute ids directly, but is useful + for a UI who want to render its own elements with consistent + highlighting. For instance a UI using |ui-popupmenu| events, might + use the |hl-Pmenu| family of builtin highlights. + + *ui-event-grid_line* +["grid_line", grid, row, col_start, cells, wrap] ~ + Redraw a continuous part of a `row` on a `grid`, starting at the column + `col_start`. `cells` is an array of arrays each with 1 to 3 items: + `[text(, hl_id, repeat)]` . `text` is the UTF-8 text that should be put in + a cell, with the highlight `hl_id` defined by a previous `hl_attr_define` + call. If `hl_id` is not present the most recently seen `hl_id` in + the same call should be used (it is always sent for the first + cell in the event). If `repeat` is present, the cell should be + repeated `repeat` times (including the first time), otherwise just + once. + + The right cell of a double-width char will be represented as the empty + string. Double-width chars never use `repeat`. + + If the array of cell changes doesn't reach to the end of the line, the + rest should remain unchanged. A whitespace char, repeated + enough to cover the remaining line, will be sent when the rest of the + line should be cleared. + + `wrap` is a boolean indicating that this line wraps to the next row. + When redrawing a line which wraps to the next row, Nvim will emit a + `grid_line` event covering the last column of the line with `wrap` set + to true, followed immediately by a `grid_line` event starting at the + first column of the next row. + +["grid_clear", grid] ~ + Clear a `grid`. + +["grid_destroy", grid] ~ + `grid` will not be used anymore and the UI can free any data associated + with it. + +["grid_cursor_goto", grid, row, col] ~ + Makes `grid` the current grid and `row, col` the cursor position on this + grid. This event will be sent at most once in a `redraw` batch and + indicates the visible cursor position. + +["grid_scroll", grid, top, bot, left, right, rows, cols] ~ + Scroll a region of `grid`. This is semantically unrelated to editor + |scrolling|, rather this is an optimized way to say "copy these screen + cells". + + The following diagrams show what happens per scroll direction. + "===" represents the SR (scroll region) boundaries. + "---" represents the moved rectangles. + Note that dst and src share a common region. + + If `rows` is bigger than 0, move a rectangle in the SR up, this can + happen while scrolling down. +> + +-------------------------+ + | (clipped above SR) | ^ + |=========================| dst_top | + | dst (still in SR) | | + +-------------------------+ src_top | + | src (moved up) and dst | | + |-------------------------| dst_bot | + | src (invalid) | | + +=========================+ src_bot +< + If `rows` is less than zero, move a rectangle in the SR down, this can + happen while scrolling up. +> + +=========================+ src_top + | src (invalid) | | + |------------------------ | dst_top | + | src (moved down) and dst| | + +-------------------------+ src_bot | + | dst (still in SR) | | + |=========================| dst_bot | + | (clipped below SR) | v + +-------------------------+ +< + `cols` is always zero in this version of Nvim, and reserved for future + use. + + Note when updating code from |ui-grid-old| events: ranges are + end-exclusive, which is consistent with API conventions, but different + from `set_scroll_region` which was end-inclusive. + + The scrolled-in area will be filled using |ui-event-grid_line| directly + after the scroll event. The UI thus doesn't need to clear this area as + part of handling the scroll event. + +============================================================================== +Grid Events (cell-based) *ui-grid-old* + +This is the legacy representation of the screen grid, emitted if |ui-linegrid| +is not active. New UIs should implement |ui-linegrid| instead. + +["resize", width, height] ~ + The grid is resized to `width` and `height` cells. + +["clear"] ~ + Clear the grid. + +["eol_clear"] ~ + Clear from the cursor position to the end of the current line. + +["cursor_goto", row, col] ~ + Move the cursor to position (row, col). Currently, the same cursor is + used to define the position for text insertion and the visible cursor. + However, only the last cursor position, after processing the entire + array in the "redraw" event, is intended to be a visible cursor + position. + +["update_fg", color] ~ +["update_bg", color] ~ +["update_sp", color] ~ + Set the default foreground, background and special colors + respectively. + + *ui-event-highlight_set* +["highlight_set", attrs] ~ + Set the attributes that the next text put on the grid will have. + `attrs` is a dict with the keys below. Any absent key is reset + to its default value. Color defaults are set by the `update_fg` etc + updates. All boolean keys default to false. + + `foreground`: foreground color. + `background`: background color. + `special`: color to use for various underlines, when present. + `reverse`: reverse video. Foreground and background colors are + switched. + `italic`: italic text. + `bold`: bold text. + `strikethrough`: struckthrough text. + `underline`: underlined text. The line has `special` color. + `undercurl`: undercurled text. The curl has `special` color. + `underdouble`: double underlined text. The lines have `special` color. + `underdotted`: underdotted text. The dots have `special` color. + `underdashed`: underdashed text. The dashes have `special` color. + +["put", text] ~ + The (utf-8 encoded) string `text` is put at the cursor position + (and the cursor is advanced), with the highlights as set by the + last `highlight_set` update. + +["set_scroll_region", top, bot, left, right] ~ + Define the scroll region used by `scroll` below. + + Note: ranges are end-inclusive, which is inconsistent with API + conventions. + +["scroll", count] ~ + Scroll the text in the scroll region. The diagrams below illustrate + what will happen, depending on the scroll direction. "=" is used to + represent the SR(scroll region) boundaries and "-" the moved rectangles. + Note that dst and src share a common region. + + If count is bigger than 0, move a rectangle in the SR up, this can + happen while scrolling down. +> + +-------------------------+ + | (clipped above SR) | ^ + |=========================| dst_top | + | dst (still in SR) | | + +-------------------------+ src_top | + | src (moved up) and dst | | + |-------------------------| dst_bot | + | src (cleared) | | + +=========================+ src_bot +< + If count is less than zero, move a rectangle in the SR down, this can + happen while scrolling up. +> + +=========================+ src_top + | src (cleared) | | + |------------------------ | dst_top | + | src (moved down) and dst| | + +-------------------------+ src_bot | + | dst (still in SR) | | + |=========================| dst_bot | + | (clipped below SR) | v + +-------------------------+ +< +============================================================================== +Highlight Events *ui-hlstate* + +Activated by the `ext_hlstate` |ui-option|. +Activates |ui-linegrid| implicitly. + +If `ext_hlstate` is enabled, Nvim will emit detailed highlight state in +|ui-linegrid| events. Otherwise (by default) Nvim only describes grid cells +using the final calculated highlight attributes described at +|ui-event-highlight_set|. + +`ext_hlstate` provides a semantic description of active highlights for each +grid cell. Highlights are predefined in a table, see |ui-event-hl_attr_define| +and |ui-event-grid_line|. + +The `info` parameter in `hl_attr_define` contains a semantic description of +the highlights. Because highlight groups can be combined, this is an array +where the highest-priority item is last. Each item is a dict with these keys: + + `kind`: always present. One of the following values: + "ui": Builtin UI highlight. |highlight-groups| + "syntax": Highlight applied to a buffer by a syntax declaration or + other runtime/plugin functionality such as + |nvim_buf_set_extmark()| + "terminal": highlight from a process running in a |terminal-emulator|. + Contains no further semantic information. + `ui_name`: Highlight name from |highlight-groups|. Only for "ui" kind. + `hi_name`: Name of the final |:highlight| group where the used + attributes are defined. + `id`: Unique numeric id representing this item. + +Note: "ui" items will have both `ui_name` and `hi_name` present. These can +differ, because the builtin group was linked to another group |:hi-link| , or +because 'winhighlight' was used. UI items will be transmitted, even if the +highlight group is cleared, so `ui_name` can always be used to reliably identify +screen elements, even if no attributes have been applied. + +============================================================================== +Multigrid Events *ui-multigrid* + +Activated by the `ext_multigrid` |ui-option|. +Activates |ui-linegrid| implicitly. + +See |ui-linegrid| for grid events. +See |nvim_ui_try_resize_grid()| to request changing the grid size. +See |nvim_input_mouse()| for sending mouse events to Nvim. + +The multigrid extension gives UIs more control over how windows are displayed: +- UIs receive updates on a separate grid for each window. +- UIs can set the grid size independently of how much space the window + occupies on the global layout. So the UI could use a different font size + per-window. Or reserve space around the border of the window for its own + elements, such as scrollbars from the UI toolkit. +- A dedicated grid is used for messages, which may scroll over the window + area. (Alternatively |ui-messages| can be used). + +By default, the grid size is handled by Nvim and set to the outer grid size +(i.e. the size of the window frame in Nvim) whenever the split is created. +Once a UI sets a grid size, Nvim does not handle the size for that grid and +the UI must change the grid size whenever the outer size is changed. To +delegate grid-size handling back to Nvim, request the size (0, 0). + +A window can be hidden and redisplayed without its grid being deallocated. +This can happen multiple times for the same window, for instance when switching +tabs. + +["win_pos", grid, win, start_row, start_col, width, height] ~ + Set the position and size of the grid in Nvim (i.e. the outer grid + size). If the window was previously hidden, it should now be shown + again. + +["win_float_pos", grid, win, anchor, anchor_grid, anchor_row, anchor_col, mouse_enabled, zindex, compindex, screen_row, screen_col] ~ + Display or reconfigure floating window `win`. + + There are two alternative ways of positioning the window + - Manually - The window should be displayed above another grid + `anchor_grid` at the specified position `anchor_row` and + `anchor_col`. For the meaning of `anchor` and more details of + positioning, see |nvim_open_win()|. NOTE: you have to manually + ensure that the window fits the screen, possibly by further + reposition it. Ignore `screen_row` and `screen_col` in this case. + - Let nvim take care of the positioning - You can ignore `anchor` + and display the window at `screen_row` and `screen_col`. + + `mouse_enabled` is true if the window can receive mouse events. + + `zindex` is the configured zindex, while `compindex` is the exact + rendering order of the windows determined by nvim. To render exactly + like the TUI, first render all the non-floating windows, then render + in the `compindex` order, overwriting any floating window cells. + Finally, blend the floating window cells against the non-floating + background. To add more blending, you can group the windows by zindex, + and blend between the layers. But note that windows inside the same + zindex should still overwrite previous cells inside the same layer + without blending. This ensures that plugins that render multiple + windows, to add borders for example, work as expected. + +["win_external_pos", grid, win] ~ + Display or reconfigure external window `win`. The window should be + displayed as a separate top-level window in the desktop environment, + or something similar. + +["win_hide", grid] ~ + Stop displaying the window. The window can be shown again later. + +["win_close", grid] ~ + Close the window. + +["msg_set_pos", grid, row, scrolled, sep_char, zindex, compindex] ~ + Display messages on `grid`. The grid will be displayed at `row` on + the default grid (grid=1), covering the full column width. `scrolled` + indicates whether the message area has been scrolled to cover other + grids. It can be useful to draw a separator then |msgsep|. The Builtin + TUI draws a full line filled with `sep_char` ('fillchars' msgsep + field) and |hl-MsgSeparator| highlight. + + When |ui-messages| is active, no message grid is used, and this event + will not be sent. + + `zindex` and `compindex` have the same meaning as for `win_float_pos`. + The `zindex` always has a fixed value of 200 and included for + completeness. + +["win_viewport", grid, win, topline, botline, curline, curcol, line_count, scroll_delta] ~ + Indicates the range of buffer text displayed in the window, as well + as the cursor position in the buffer. All positions are zero-based. + `botline` is set to one more than the line count of the buffer, if + there are filler lines past the end. `scroll_delta` contains how much + the top line of a window moved since `win_viewport` was last emitted. + It is intended to be used to implement smooth scrolling. For this + purpose it only counts "virtual" or "displayed" lines, so folds + only count as one line. When scrolling more than a full screen it is + an approximate value. + + All updates, such as `grid_line`, in a batch affects the new viewport, + despite the fact that `win_viewport` is received after the updates. + Applications implementing, for example, smooth scrolling should take + this into account and keep the grid separated from what's displayed on + the screen and copy it to the viewport destination once `win_viewport` + is received. + +["win_viewport_margins", grid, win, top, bottom, left, right] ~ + Indicates the margins of a window grid which are _not_ part of the + viewport as indicated by the `win_viewport` event. This happens + e.g. in the presence of 'winbar' and floating window borders. + +["win_extmark", grid, win, ns_id, mark_id, row, col] ~ + Updates the position of an extmark which is currently visible in a + window. Only emitted if the mark has the `ui_watched` attribute. + +============================================================================== +Popupmenu Events *ui-popupmenu* + +Activated by the `ext_popupmenu` |ui-option|. + +This UI extension delegates presentation of the |popupmenu-completion| and +command-line 'wildmenu'. + +The UI decides how to present the menu. For example, depending on the last +`mode_change` event, command-line wildmenu may be presented horizontally, +while insert-mode completion would show a vertical popupmenu. + +["popupmenu_show", items, selected, row, col, grid] ~ + Show |popupmenu-completion|. `items` is an array of completion items + to show; each item is an array of the form [word, kind, menu, info] as + defined at |complete-items|, except that `word` is replaced by `abbr` + if present. `selected` is the initially-selected item, a zero-based + index into the array of items (-1 if no item is selected). `row` and + `col` give the anchor position, where the first character of the + completed word will be. When |ui-multigrid| is used, `grid` is the + grid for the anchor position. When `ext_cmdline` is active, `grid` is + set to -1 to indicate the popupmenu should be anchored to the external + cmdline. Then `col` will be a byte position in the cmdline text. + +["popupmenu_select", selected] ~ + Select an item in the current popupmenu. `selected` is a zero-based + index into the array of items from the last popupmenu_show event, or + -1 if no item is selected. + +["popupmenu_hide"] ~ + Hide the popupmenu. + +============================================================================== +Tabline Events *ui-tabline* + +Activated by the `ext_tabline` |ui-option|. + +["tabline_update", curtab, tabs, curbuf, buffers] ~ + Tabline was updated. UIs should present this data in a custom tabline + widget. Note: options `curbuf` + `buffers` were added in API7. + curtab: Current Tabpage + tabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...] + curbuf: Current buffer handle. + buffers: List of Dicts [{ "buffer": buffer handle, "name": String}, ...] + +============================================================================== +Cmdline Events *ui-cmdline* + +Activated by the `ext_cmdline` |ui-option|. + +This UI extension delegates presentation of the |cmdline| (except 'wildmenu'). +For command-line 'wildmenu' UI events, activate |ui-popupmenu|. + +["cmdline_show", content, pos, firstc, prompt, indent, level, hl_id] ~ + content: List of [attrs, string, hl_id] + [[{}, "t", hl_id], [attrs, "est", hl_id], ...] + + Triggered when the cmdline is displayed or changed. + The `content` is the full content that should be displayed in the + cmdline, and the `pos` is the position of the cursor that in the + cmdline. The content is divided into chunks with different highlight + attributes represented as a dict (see |ui-event-highlight_set|). + + `firstc` and `prompt` are text, that if non-empty should be + displayed in front of the command line. `firstc` always indicates + built-in command lines such as `:` (ex command) and `/` `?` (search), + while `prompt` is an |input()| prompt, highlighted with `hl_id`. + `indent` tells how many spaces the content should be indented. + + The Nvim command line can be invoked recursively, for instance by + typing `<c-r>=` at the command line prompt. The `level` field is used + to distinguish different command lines active at the same time. The + first invoked command line has level 1, the next recursively-invoked + prompt has level 2. A command line invoked from the |cmdline-window| + has a higher level than the edited command line. + +["cmdline_pos", pos, level] ~ + Change the cursor position in the cmdline. + +["cmdline_special_char", c, shift, level] ~ + Display a special char in the cmdline at the cursor position. This is + typically used to indicate a pending state, e.g. after |c_CTRL-V|. If + `shift` is true the text after the cursor should be shifted, otherwise + it should overwrite the char at the cursor. + + Should be hidden at next cmdline_show. + +["cmdline_hide", level, abort] ~ + Hide the cmdline. `level` is the nesting level of the cmdline being hidden. + `abort` is true if the cmdline is hidden after an aborting condition + (|c_Esc| or |c_CTRL-C|). + +["cmdline_block_show", lines] ~ + Show a block of context to the current command line. For example if + the user defines a |:function| interactively: >vim + :function Foo() + : echo "foo" + : +< + `lines` is a list of lines of highlighted chunks, in the same form as + the "cmdline_show" `contents` parameter. + +["cmdline_block_append", line] ~ + Append a line at the end of the currently shown block. + +["cmdline_block_hide"] ~ + Hide the block. + +============================================================================== +Message/Dialog Events *ui-messages* + +Activated by the `ext_messages` |ui-option|. +Activates |ui-linegrid| and |ui-cmdline| implicitly. + +This UI extension delegates presentation of messages and dialogs. Messages +that would otherwise render in the message/cmdline screen space, are emitted +as UI events. + +Nvim will not allocate screen space for the cmdline or messages. 'cmdheight' +will be set to zero, but can be changed and used for the replacing cmdline or +message window. Cmdline state is emitted as |ui-cmdline| events, which the UI +must handle. + +["msg_show", kind, content, replace_last, history, append] ~ + Display a message to the user. + + kind + Name indicating the message kind: + "" (empty) Unknown (consider a |feature-request|) + "empty" Empty message (`:echo ""`), with empty `content`. + Should clear messages sharing the 'cmdheight' + area if it is the only message in a batch. + "bufwrite" |:write| message + "confirm" Message preceding a prompt (|:confirm|, + |confirm()|, |inputlist()|, |z=|, …) + "emsg" Error (|errors|, internal error, |:throw|, …) + "echo" |:echo| message + "echomsg" |:echomsg| message + "echoerr" |:echoerr| message + "completion" |ins-completion-menu| message + "list_cmd" List output for various commands (|:ls|, |:set|, …) + "lua_error" Error in |:lua| code + "lua_print" |print()| from |:lua| code + "rpc_error" Error response from |rpcrequest()| + "quickfix" Quickfix navigation message + "search_cmd" Entered search command + "search_count" Search count message ("S" flag of 'shortmess') + "shell_cmd" |:!cmd| executed command + "shell_err" |:!cmd| shell stderr output + "shell_out" |:!cmd| shell stdout output + "shell_ret" |:!cmd| shell return code + "undo" |:undo| and |:redo| message + "verbose" 'verbose' message + "wildlist" 'wildmode' "list" message + "wmsg" Warning ("search hit BOTTOM", |W10|, …) + New kinds may be added in the future; clients should treat unknown + kinds as the empty kind. + + content + Array of `[attr_id, text_chunk, hl_id]` tuples, building up the + message text of chunks of different highlights. No extra spacing + should be added between chunks, the `text_chunk` by itself + contains any necessary whitespace. Messages can contain line + breaks "\n". + + replace_last + Decides how multiple messages should be displayed: + false: Display the message together with all previous messages + that are still visible. + true: Replace the message in the most-recent `msg_show` call, + but any other visible message should still remain. + + history + True if the message was added to the |:messages| history. + + append + True if the message should be appeneded to the previous message, + rather than started on a new line. Is set for |:echon|. + +["msg_clear"] ~ + Clear all messages currently displayed by "msg_show", emitted after + clearing the screen (messages sent by other "msg_" events below should + not be affected). + +["msg_showmode", content] ~ + Shows 'showmode' and |recording| messages. `content` has the same + format as in "msg_show". This event is sent with empty `content` to + hide the last message. + +["msg_showcmd", content] ~ + Shows 'showcmd' messages. `content` has the same format as in "msg_show". + This event is sent with empty `content` to hide the last message. + +["msg_ruler", content] ~ + Used to display 'ruler' when there is no space for the ruler in a + statusline. `content` has the same format as in "msg_show". This event is + sent with empty `content` to hide the last message. + +["msg_history_show", entries, prev_cmd] ~ + Sent when |:messages| or |g<| command is invoked. History is sent as a + list of entries, where each entry is a `[kind, content, append]` tuple. + + prev_cmd + True when sent with |g<| command, false with |:messages|. + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt @@ -231,21 +231,19 @@ As Nvim evolves the API may change in compliance with this CONTRACT: - New functions and events may be added. - Any such extensions are OPTIONAL: old clients may ignore them. -- Function signatures will NOT CHANGE (after release), except as follows: - - Functions introduced in the development (unreleased) version MAY CHANGE. - (Clients can dynamically check `api_prerelease`, etc. |api-metadata|) - - New items may be ADDED to map/list parameters/results of functions and - events. - - Any such new items are OPTIONAL: old clients may ignore them. - - Existing items will not be removed (after release). - - Return type may change from void to non-void. Old clients MAY ignore the +- New functions MAY CHANGE before release. Clients can dynamically check + `api_prerelease`, |api-metadata|. +- Function signatures will NOT CHANGE after release, except as follows: + - Map/list parameters/results may be EXTENDED (new fields may be added). + - Such new fields are OPTIONAL: old clients MAY ignore them. + - Existing fields will not be removed. + - Return type MAY CHANGE from void to non-void. Old clients MAY ignore the new return value. - - An `opts` parameter may be added, which is not required in the request. - - Unlimited optional parameters may be added following an `opts` - parameter. + - An optional `opts` parameter may be ADDED. + - Optional parameters may be ADDED following an `opts` parameter. - Event parameters will not be removed or reordered (after release). - Events may be EXTENDED: new parameters may be added. -- Deprecated functions will not be removed until Nvim version 2.0 +- Deprecated functions will not be removed until Nvim 2.0. "Private" interfaces are NOT covered by this contract: diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt @@ -73,7 +73,8 @@ Or use `:execute`: > Note that special characters (e.g., "%", "<cword>") in the ":autocmd" arguments are not expanded when the autocommand is defined. These will be expanded when the Event is recognized, and the {cmd} is executed. The only -exception is that "<sfile>" is expanded when the autocmd is defined. Example: +exception is that "<sfile>" (unlike "<script>") is expanded when the autocmd +is defined. Example: > :au BufNewFile,BufRead *.html so <sfile>:h/html.vim @@ -261,7 +262,7 @@ BufLeave Before leaving to another buffer. Also when Not used for ":qa" or ":q" when exiting Vim. *BufModifiedSet* BufModifiedSet After the `'modified'` value of a buffer has - been changed. + been changed. Special-case of |OptionSet|. *BufNew* BufNew After creating a new buffer (except during startup, see |VimEnter|) or renaming an @@ -497,22 +498,11 @@ CompleteDone After Insert mode completion is done. Either abandoned for other reason. *CursorHold* -CursorHold When the user doesn't press a key for the time - specified with 'updatetime'. Not triggered - until the user has pressed a key (i.e. doesn't - fire every 'updatetime' ms if you leave Vim to - make some coffee. :) See |CursorHold-example| - for previewing tags. - This event is only triggered in Normal mode. - It is not triggered when waiting for a command - argument to be typed, or a movement after an - operator. - While recording the CursorHold event is not - triggered. |q| - *<CursorHold>* - Internally the autocommand is triggered by the - <CursorHold> key. In an expression mapping - |getchar()| may see this character. +CursorHold When there is no user input for 'updatetime' + duration, in Normal-mode. Not triggered while + waiting for a command argument or movement + after an operator, nor while |recording| + a macro. See |CursorHold-example|. Note: Interactive commands cannot be used for this event. There is no hit-enter prompt, @@ -837,6 +827,10 @@ OptionSet After setting an option (except during always use |:noautocmd| to prevent triggering OptionSet. + Note: Not triggered by the 'modified' option; + the |BufModifiedSet| event may be used to + handle that. + Non-recursive: |:set| in the autocommand does not trigger OptionSet again. diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt @@ -177,85 +177,85 @@ Put this in `uppercase.vim` and run: >bash ============================================================================== 5. Using a prompt buffer *prompt-buffer* -If you want to type input for the job in a Vim window you have a few options: -- Use a normal buffer and handle all possible commands yourself. - This will be complicated, since there are so many possible commands. -- Use a terminal window. This works well if what you type goes directly to - the job and the job output is directly displayed in the window. - See |terminal|. -- Use a window with a prompt buffer. This works well when entering lines for - the job in Vim while displaying (possibly filtered) output from the job. +Prompt buffers provide a "prompt" interface: they are like regular buffers, +except only the last section of the buffer is editable, and the user can +"submit" the prompt by hitting Enter. Useful for implementing: + +- chat UI +- REPL or shell plugins +- advanced "picker" plugins A prompt buffer is created by setting 'buftype' to "prompt". You would -normally only do that in a newly created buffer. +normally only do that in a newly created buffer: >vim + + :set buftype=prompt -The user can edit and enter text at the very last line of the buffer. Pressing -Enter in the prompt line invokes the |prompt_setcallback()| callback. Use -Shift+Enter to add a new line without submitting the prompt, or paste -multiline text using any |put| or |paste| command. The callback is typically -expected to process the prompt and show results by appending to the buffer, -below the prompt (and above the next prompt). +The user can edit and enter text at the end of the buffer. Pressing Enter in +the prompt section invokes the |prompt_setcallback()| callback, which is +typically expected to process the prompt and show results by appending to the +buffer. To input multiline text, use Shift+Enter to add a new line without +submitting the prompt, or just |put| or |paste| multiline text. -Only the text after the last prompt (starting from the |':| mark), is -user-editable. The rest of the buffer is not modifiable with Normal mode -commands. It can be modified by functions such as |append()|. Using other -commands may mess up the buffer. +Only the "prompt" part of the buffer user-editable, given by the |':| mark. +The rest of the buffer is not modifiable with Normal mode commands, though it +can be modified by functions such as |append()|. Using other commands may +mess up the buffer. -After setting 'buftype' to "prompt" Vim does not automatically start Insert -mode, use `:startinsert` if you want to enter Insert mode, so that the user -can start typing a line. +After setting `buftype=prompt`: +- Nvim unsets the 'comments' option. +- Nvim does not automatically start Insert mode (use `:startinsert` if you + want to enter Insert mode) -The text of the prompt can be set with the |prompt_setprompt()| function. If -no prompt is set with |prompt_setprompt()|, "% " is used. You can get the -effective prompt text for a buffer, with |prompt_getprompt()|. +The prompt prefix defaults to "% ", but can be set with |prompt_setprompt()|. +You can get the effective prompt prefix for with |prompt_getprompt()|. The user can go to Normal mode and navigate through the buffer. This can be useful to see older output or copy text. -The CTRL-W key can be used to start a window command, such as CTRL-W w to -switch to the next window. This also works in Insert mode (use Shift-CTRL-W -to delete a word). When leaving the window Insert mode will be stopped. When -coming back to the prompt window Insert mode will be restored. +By default during prompt insert-mode, the CTRL-W key can be used to start +a window command, such as CTRL-W w to switch to the next window. (Use +Shift-CTRL-W to delete a word). When leaving the window Insert mode will be +stopped. When coming back to the prompt window Insert mode will be restored. Any command that starts Insert mode, such as "a", "i", "A" and "I", will move the cursor to the last line. "A" will move to the end of the line, "I" to the start of the line. -Here is an example for Unix. It starts a shell in the background and prompts -for the next shell command. Output from the shell is displayed above the -prompt. >vim - - " Function handling a line of text that has been typed. - func TextEntered(text) - " Send the text to a shell with Enter appended. - call chansend(g:shell_job, [a:text, '']) - endfunc - - " Function handling output from the shell: Add it above the prompt. - func GotOutput(channel, msg, name) - call append(line("$") - 1, a:msg) - endfunc - - " Function handling the shell exits: close the window. - func JobExit(job, status, event) - quit! - endfunc - - " Start a shell in the background. - let shell_job = jobstart(["/bin/sh"], #{ - \ on_stdout: function('GotOutput'), - \ on_stderr: function('GotOutput'), - \ on_exit: function('JobExit'), - \ }) - - new - set buftype=prompt - let buf = bufnr('') - call prompt_setcallback(buf, function("TextEntered")) - call prompt_setprompt(buf, "shell command: ") - - " start accepting shell commands - startinsert +Example: start a shell in the background and prompt for the next shell +command, displaying shell output above the prompt: >vim + + " Handles a line of user input. + func OnSubmit(text) + " Send the text to a shell with Enter appended. + call chansend(g:shell_job, [a:text, '']) + endfunc + + " Handles output from the shell. + func OnOutput(channel, msg, name) + " Add shell output above the prompt. + call append(line('$') - 1, a:msg) + endfunc + + " Handles the shell exit. + func JobExit(job, status, event) + quit! + endfunc + + " Start a shell in the background. + let shell_job = jobstart(['/bin/sh'], #{ + \ on_stdout: function('OnOutput'), + \ on_stderr: function('OnOutput'), + \ on_exit: function('JobExit'), + \ }) + + new + set buftype=prompt + let buf = bufnr('') + call prompt_setcallback(buf, function('OnSubmit')) + call prompt_setprompt(buf, 'shell command: ') + + " Start accepting shell commands. + startinsert < - vim:tw=78:ts=8:noet:ft=help:norl: + vim:tw=78:ts=8:et:sw=4:ft=help:norl: diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt @@ -568,7 +568,6 @@ that see the '"' as part of their argument: :menu (and the like) :mkspell :normal - :ownsyntax :popup :registers :return diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt @@ -26,7 +26,7 @@ DIAGNOSTICS HIGHLIGHTS -• todo +• *:ownsyntax* *w:current_syntax* Use 'winhighlight' instead. LSP diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt @@ -426,6 +426,9 @@ 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"?) - call: Calls a function + - callback Continuation callback: a single function parameter (not + a field) that returns the result of an async function. Use + "on_…" for all other callbacks and event handlers. - cancel: Cancels or dismisses an event or interaction, typically user-initiated and without error. (Compare "abort", which cancels and signals error/failure.) @@ -444,6 +447,8 @@ Use existing common {verb} names (actions) if possible: - has: Checks for the presence of an item, feature, etc. - inspect: Presents a high-level, often interactive, view - is_enabled: Checks if functionality is enabled. + - on_…: Handles events or async results, or registers such + a handler. |dev-name-events| - open: Opens something (a buffer, window, …) - parse: Parses something into a structured form - set: Sets a thing (or group of things) @@ -477,7 +482,6 @@ everywhere, not "buffer" in some places and "buf" in others. Do NOT use these deprecated nouns: - buffer Use "buf" instead - - callback Use on_foo instead - command Use "cmd" instead - window Use "win" instead @@ -669,6 +673,7 @@ External UIs are expected to implement these common features: - Support the text decorations/attributes given by |ui-event-hl_attr_define|. The "url" attr should be presented as a clickable hyperlink. - Handle the "restart" UI event so that |:restart| works. +- Detect capslock and show an indicator if capslock is active. vim:tw=78:ts=8:sw=4:et:ft=help:norl: diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt @@ -17,6 +17,8 @@ TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes specific to the terminal UI. Help tags with the "gui-" prefix refer to UI features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|. + Type |gO| to see the table of contents. + ============================================================================== Third-party GUIs *third-party-guis* *vscode* @@ -34,8 +36,6 @@ a Nvim GUI. - VimR (macOS) https://github.com/qvacua/vimr - Others https://github.com/neovim/neovim/wiki/Related-projects#gui - Type |gO| to see the table of contents. - ============================================================================== Starting the GUI *gui-config* *gui-start* diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt @@ -1473,7 +1473,6 @@ tag command action ~ |:options| :opt[ions] open the options-window |:ounmap| :ou[nmap] like ":unmap" but for Operator-pending mode |:ounmenu| :ounme[nu] remove menu for Operator-pending mode -|:ownsyntax| :ow[nsyntax] set new local syntax highlight for this window |:packadd| :pa[ckadd] add a plugin from 'packpath' |:packloadall| :packl[oadall] load all packages under 'packpath' |:pbuffer| :pb[uffer] edit buffer in the preview window diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt @@ -859,16 +859,13 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) describing the failure reason, and `result` is nil. commands *vim.lsp.commands* - Registry (a table) for client-side handlers, for custom server-commands - that are not in the LSP specification. + Map of client-defined handlers implementing custom (off-spec) commands + which a server may invoke. Each key is a unique command name; each value + is a function which is called when an LSP action (code action, code + lenses, …) requests it by name. - If an LSP response contains a command which is not found in - `vim.lsp.commands`, the command will be executed via the LSP server using - `workspace/executeCommand`. - - Each key in the table is a unique command name, and each value is a - function which is called when an LSP action (code action, code lenses, - …) triggers the command. + If an LSP response requests a command not defined client-side, Nvim will + forward it to the server as `workspace/executeCommand`. • Argument 1 is the `Command`: > Command title: String @@ -1381,13 +1378,8 @@ Lua module: vim.lsp.client *lsp-client* { PORT = 8080; HOST = '0.0.0.0'; } < • {commands}? (`table<string,fun(command: lsp.Command, ctx: table)>`) - Client commands. Map of command names to - user-defined functions. Commands passed to - `start()` take precedence over the global - command registry. Each key must be a unique - command name, and the value is a function which - is called if any LSP action (code action, code - lenses, …) triggers the command. + Map of client-defined commands overriding the + global |vim.lsp.commands|. • {detached}? (`boolean`, default: `true`) Daemonize the server process so that it runs in a separate process group from Nvim. Nvim will shutdown the diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt @@ -30,16 +30,17 @@ The purpose of this guide is to introduce the different ways of interacting with Nvim through Lua (the "API"). This API consists of three different layers: -1. The "Vim API" inherited from Vim: |Ex-commands| and |builtin-functions| as -well as |user-function|s in Vimscript. These are accessed through |vim.cmd()| -and |vim.fn| respectively, which are discussed under |lua-guide-vimscript| -below. +1. The "Vim API" inherited from Vim: |Ex-commands| and |vimscript-functions| + as well as |user-function|s in Vimscript. These are accessed through + |vim.cmd()| and |vim.fn| respectively, which are discussed under + |lua-guide-vimscript| below. 2. The "Nvim API" written in C for use in remote plugins and GUIs; see |api|. -These functions are accessed through |vim.api|. + These functions are accessed through |vim.api|. 3. The "Lua API" written in and specifically for Lua. These are any other -functions accessible through `vim.*` not mentioned already; see |lua-stdlib|. + functions accessible through `vim.*` not mentioned already; see + |lua-stdlib|. This distinction is important, as API functions inherit behavior from their original layer: For example, Nvim API functions always need all arguments to @@ -223,7 +224,7 @@ Vimscript are automatically converted: vim.fn.jobstart('ls', { on_stdout = print_stdout }) < -This works for both |builtin-functions| and |user-function|s. +This works for both |vimscript-functions| and |user-function|s. Note that hashes (`#`) are not valid characters for identifiers in Lua, so, e.g., |autoload| functions have to be called with this syntax: @@ -232,9 +233,9 @@ e.g., |autoload| functions have to be called with this syntax: < ------------------------------------------------------------------------------ See also: -• |builtin-functions|: alphabetic list of all Vimscript functions -• |function-list|: list of all Vimscript functions grouped by topic -• |:runtime|: run all Lua scripts matching a pattern in |'runtimepath'| +• |vimscript-functions|: descriptions of all Vimscript functions +• |function-list|: Vimscript functions grouped by topic +• |:runtime|: run all Lua scripts matching a pattern in |'runtimepath'| ============================================================================== Variables *lua-guide-variables* diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt @@ -3177,12 +3177,12 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* Examples: >lua -- Map "x" to a Lua function: - vim.keymap.set('n', 'x', function() print("real lua function") end) + vim.keymap.set('n', 'x', function() print('real lua function') end) -- Map "<leader>x" to multiple modes for the current buffer: vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true }) -- Map <Tab> to an expression (|:map-<expr>|): vim.keymap.set('i', '<Tab>', function() - return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" + return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>' end, { expr = true }) -- Map "[%%" to a <Plug> mapping: vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)') diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt @@ -1178,10 +1178,10 @@ A jump table for the options with a short description can be found at |Q_op|. help help buffer (do not set this manually) nofile buffer is not related to a file, will not be written nowrite buffer will not be written + prompt buffer where only the last section can be edited, for + use by plugins. |prompt-buffer| quickfix list of errors |:cwindow| or locations |:lwindow| terminal |terminal-emulator| buffer - prompt buffer where only the last line can be edited, meant - to be used by a plugin, see |prompt-buffer| This option is used together with 'bufhidden' and 'swapfile' to specify special kinds of buffers. See |special-buffers|. diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt @@ -265,24 +265,24 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. about each searched file. *:pa* *:packadd* *E919* -:pa[ckadd][!] {name} Search for an optional plugin directory in 'packpath' - and source any plugin files found. The directory must - match: - pack/*/opt/{name} ~ - The directory is added to 'runtimepath' if it wasn't - there yet. - If the directory pack/*/opt/{name}/after exists it is +:pa[ckadd][!] {name} |pack-add| Search for an optional plugin directory in + 'packpath', source any plugin files found, and add it + to 'runtimepath'. The directory must match: > + pack/*/opt/{name} +< If the directory pack/*/opt/{name}/after exists it is added at the end of 'runtimepath'. - If loading packages from "pack/*/start" was skipped, - then this directory is searched first: - pack/*/start/{name} ~ + Note: Use |vim.pack.add()) to install from a URL. + If loading packages from "pack/*/start" was skipped, + then this directory is searched first: > + pack/*/start/{name} +< Note that {name} is the directory name, not the name - of the .vim file. All files matching the patterns - pack/*/opt/{name}/plugin/**/*.vim ~ - pack/*/opt/{name}/plugin/**/*.lua ~ - will be sourced. This allows for using subdirectories + of the .vim file. All files matching the patterns > + pack/*/opt/{name}/plugin/**/*.vim + pack/*/opt/{name}/plugin/**/*.lua +< will be sourced. This allows for using subdirectories below "plugin", just like with plugins in 'runtimepath'. @@ -293,17 +293,14 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. "pack/*/opt/{name}", this command will also look for "{name}/ftdetect/*.vim" files. - When the optional ! is added no plugin files or - ftdetect scripts are loaded, only the matching + When the optional "!" is given, no plugin/ files or + ftdetect/ scripts are loaded, only the matching directories are added to 'runtimepath'. This is useful in your |init.vim|. The plugins will then be - loaded during |initialization|, see |load-plugins| (note - that the loading order will be reversed, because each - directory is inserted before others). In this case, the - ftdetect scripts will be loaded during |initialization|, - before the |load-plugins| step. - - Also see |pack-add|. + loaded during the |load-plugins| |initialization| step + (note that the loading order will be reversed because + each directory is inserted before others), after + loading the ftdetect scripts. *:packl* *:packloadall* :packl[oadall][!] Load all packages in the "start" directory under each diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt @@ -5505,38 +5505,7 @@ And put these lines in your vimrc: > autocmd BufRead,BufNewFile *.[ch] endif ============================================================================== -17. Window-local syntax *:ownsyntax* - -Normally all windows on a buffer share the same syntax settings. It is -possible, however, to set a particular window on a file to have its own -private syntax setting. A possible example would be to edit LaTeX source -with conventional highlighting in one window, while seeing the same source -highlighted differently (so as to hide control sequences and indicate bold, -italic etc regions) in another. The 'scrollbind' option is useful here. - -To set the current window to have the syntax "foo", separately from all other -windows on the buffer: > - :ownsyntax foo -< *w:current_syntax* -This will set the "w:current_syntax" variable to "foo". The value of -"b:current_syntax" does not change. This is implemented by saving and -restoring "b:current_syntax", since the syntax files do set -"b:current_syntax". The value set by the syntax file is assigned to -"w:current_syntax". -Note: This resets the 'spell', 'spellcapcheck', 'spellfile' and 'spelloptions' -options. - -Once a window has its own syntax, syntax commands executed from other windows -on the same buffer (including :syntax clear) have no effect. Conversely, -syntax commands executed from that window do not affect other windows on the -same buffer. - -A window with its own syntax reverts to normal behavior when another buffer -is loaded into that window or the file is reloaded. -When splitting the window, the new window will use the original syntax. - -============================================================================== -18. Color xterms *xterm-color* *color-xterm* +17. Color xterms *xterm-color* *color-xterm* *colortest.vim* To test your color setup, a file has been included in the Vim distribution. @@ -5546,7 +5515,7 @@ To use it, execute this command: > Nvim uses 256-color and |true-color| terminal capabilities wherever possible. ============================================================================== -19. When syntax is slow *:syntime* +18. When syntax is slow *:syntime* This is aimed at authors of a syntax file. diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt @@ -1,903 +0,0 @@ -*ui.txt* Nvim - - - NVIM REFERENCE MANUAL - - -Nvim UI protocol *UI* *ui* - - Type |gO| to see the table of contents. - -============================================================================== -UI Events *ui-protocol* *ui-events* - -UIs can be implemented as external client processes communicating with Nvim -over the RPC API. The default UI model is a terminal-like grid with a single, -monospace font. The UI can opt-in to have windows drawn on separate grids, and -have some elements ("widgets") presented by the UI itself rather than by Nvim -("externalized"). - - *ui-option* -Call |nvim_ui_attach()| to tell Nvim that your program wants to draw the Nvim -screen grid with a size of width × height cells. This is typically done by an -embedder at startup (see |ui-startup|), but UIs can also connect to a running -Nvim instance and invoke nvim_ui_attach(). The `options` parameter is a map -with these (optional) keys: - - *ui-rgb* -- `rgb` Decides the color format. - - true: (default) 24-bit RGB colors - - false: Terminal colors (8-bit, max 256) - - *ui-override* -- `override` Decides how UI capabilities are resolved. - - true: Enable requested UI capabilities, even if not - supported by all connected UIs (including |TUI|). - - false: (default) Disable UI capabilities not - supported by all connected UIs (including TUI). - - *ui-ext-options* -- `ext_cmdline` Externalize the cmdline. |ui-cmdline| -- `ext_hlstate` Detailed highlight state. |ui-hlstate| - Sets `ext_linegrid` implicitly. -- `ext_linegrid` Line-based grid events. |ui-linegrid| - Deactivates |ui-grid-old| implicitly. -- `ext_messages` Externalize messages. |ui-messages| - Sets `ext_linegrid` and `ext_cmdline` implicitly. -- `ext_multigrid` Per-window grid events. |ui-multigrid| - Sets `ext_linegrid` implicitly. -- `ext_popupmenu` Externalize |popupmenu-completion| and - 'wildmenu'. |ui-popupmenu| -- `ext_tabline` Externalize the tabline. |ui-tabline| -- `ext_termcolors` Use external default colors. -- `term_name` Sets the name of the terminal 'term'. -- `term_colors` Sets the number of supported colors 't_Co'. -- `stdin_fd` Read buffer 1 from this fd as if it were stdin |--|. - Only from |--embed| UI on startup. |ui-startup-stdin| -- `stdin_tty` Tells if `stdin` is a `tty` or not. -- `stdout_tty` Tells if `stdout` is a `tty` or not. - -Specifying an unknown option is an error; UIs can check the |api-metadata| -`ui_options` key for supported options. - -By default Nvim requires all connected UIs to support the same capabilities, -thus the active capabilities are the intersection of those requested. UIs may -specify |ui-override| to invert this behavior (useful for debugging). The -"option_set" event announces which capabilities are active. - -Nvim sends RPC notifications to all attached UIs, with method name "redraw" -and a single argument: an array (batch) of screen "update events". Each update -event is itself an array whose first element is the event name and remaining -elements are event-parameter tuples. Thus multiple events of the same kind can -be sent contiguously without repeating the event name. - -Example of a typical "redraw" batch in a single RPC notification: > - - ['notification', 'redraw', - [ - ['grid_resize', [2, 77, 36]], - ['grid_line', - [2, 0, 0, [[' ' , 0, 77]], false], - [2, 1, 0, [['~', 7], [' ', 7, 76]], false], - [2, 9, 0, [['~', 7], [' ', 7, 76]], false], - ... - [2, 35, 0, [['~', 7], [' ', 7, 76]], false], - [1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']], false], - [1, 36, 9, [[' ', 9, 50]], false], - [1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]], false] - ], - ['msg_showmode', [[]]], - ['win_pos', [2, 1000, 0, 0, 77, 36]], - ['grid_cursor_goto', [2, 0, 0]], - ['flush', []] - ] - ] - -Events must be handled in-order. Nvim sends a "flush" event when it has -completed a redraw of the entire screen (so all windows have a consistent view -of buffer state, options, etc.). Multiple "redraw" batches may be sent before -the entire screen has been redrawn, with "flush" following only the last -batch. The user should only see the final state (when "flush" is sent), not -any intermediate state while processing part of the batch array, nor after -a batch not ending with "flush". - -By default, Nvim sends |ui-global| and |ui-grid-old| events (for backwards -compatibility); these suffice to implement a terminal-like interface. However -the new |ui-linegrid| represents text more efficiently (especially highlighted -text), and allows UI capabilities requiring multiple grids. New UIs should -implement |ui-linegrid| instead of |ui-grid-old|. - -Nvim optionally sends various screen elements "semantically" as structured -events instead of raw grid-lines, as specified by |ui-ext-options|. The UI -must present such elements itself, Nvim will not draw them on the grid. - -Future versions of Nvim may add new update kinds and may append new parameters -to existing update kinds. Clients must be prepared to ignore such extensions, -for forward-compatibility. |api-contract| - -============================================================================== -UI startup *ui-startup* - -UI embedders (clients that start Nvim with |--embed| and later call -|nvim_ui_attach()|) must start Nvim without |--headless|: >bash - nvim --embed -Nvim will pause before loading startup files and reading buffers, so the UI -has a chance to invoke requests and do early initialization. Startup will -continue when the UI invokes |nvim_ui_attach()|. - -A simple UI only needs to do a single |nvim_ui_attach()| request and then -prepare to handle any UI event. A more featureful UI, which might need -additional configuration of the Nvim process, should use the following startup -procedure: - -1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or - to get the list of supported UI extensions. - -2. Do any configuration that should be happen before user config is loaded. - Buffers and windows are not available at this point, but this could be used - to set |g:| variables visible to init.vim - -3. If the UI wants to do additional setup after user config is loaded, - register a VimEnter autocmd: >lua - nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')") - -4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now: - sourcing init.vim and loading buffers might lead to blocking prompts. - -5. If step 3 was used, Nvim will send a blocking "vimenter" request to the UI. - Inside this request handler, the UI can safely do any initialization before - entering normal mode, for example reading variables set by init.vim. - - *ui-startup-stdin* -UIs can support reading from stdin (like `command | nvim -`, see |--|) as follows: - -1. The embedding process detects that the stdin fd is not a terminal. -2. It then needs to forward this fd to Nvim. Because fd=0 is already is used - to send RPC data from embedder to Nvim, it must use some other file - descriptor, like fd=3 or higher. -3. Then pass the fd as the `stdin_fd` parameter of `nvim_ui_attach`. Nvim will - read it as text into buffer 1. - -============================================================================== -Global Events *ui-global* - -The following UI events are always emitted, and describe global state of -the editor. - -["set_title", title] ~ -["set_icon", icon] ~ - Set the window title, and icon (minimized) window title, respectively. - In windowing systems not distinguishing between the two, "set_icon" - can be ignored. - -["mode_info_set", cursor_style_enabled, mode_info] ~ - `cursor_style_enabled` is a boolean indicating if the UI should set - the cursor style. `mode_info` is a list of mode property maps. The - current mode is given by the `mode_idx` field of the `mode_change` - event. - - Each mode property map may contain these keys: - - KEY DESCRIPTION ~ - `cursor_shape`: "block", "horizontal", "vertical" - `cell_percentage`: Cell % occupied by the cursor. - `blinkwait`, `blinkon`, `blinkoff`: See |cursor-blinking|. - `attr_id`: Cursor attribute id (defined by `hl_attr_define`). - When attr_id is 0, the background and foreground - colors should be swapped. - `attr_id_lm`: Cursor attribute id for when |:lmap| is on. - `short_name`: Mode code name, see 'guicursor'. - `name`: Mode descriptive name. - `mouse_shape`: (To be implemented.) - - Some keys are missing in some modes. - - The following keys are deprecated: - - `hl_id`: Use `attr_id` instead. - `id_lm`: Use `attr_id_lm` instead. - -["option_set", name, value] ~ - UI-related option changed, where `name` is one of: - - - 'arabicshape' - - 'ambiwidth' - - 'emoji' - - 'guifont' - - 'guifontwide' - - 'linespace' - - 'mousefocus' - - 'mousehide' - - 'mousemoveevent' - - 'pumblend' - - 'showtabline' - - 'termguicolors' - - "ext_*" (all |ui-ext-options|) - - Triggered when the UI first connects to Nvim, and whenever an option - is changed by the user or a plugin. - - Options are not represented here if their effects are communicated in - other UI events. For example, instead of forwarding the 'mouse' option - value, the "mouse_on" and "mouse_off" UI events directly indicate if - mouse support is active. Some options like 'ambiwidth' have already - taken effect on the grid, where appropriate empty cells are added, - however a UI might still use such options when rendering raw text - sent from Nvim, like for |ui-cmdline|. - -["chdir", path] ~ - The |current-directory| changed to `path`. - -["mode_change", mode, mode_idx] ~ - Editor mode changed. The `mode` parameter is a string representing - the current mode. `mode_idx` is an index into the array emitted in - the `mode_info_set` event. UIs should change the cursor style - according to the properties specified in the corresponding item. The - set of modes reported will change in new versions of Nvim, for - instance more submodes and temporary states might be represented as - separate modes. - -["mouse_on"] ~ -["mouse_off"] ~ - 'mouse' was enabled/disabled in the current editor mode. Useful for - a terminal UI, or embedding into an application where Nvim mouse would - conflict with other usages of the mouse. Other UI:s may ignore this event. - -["busy_start"] ~ -["busy_stop"] ~ - Indicates to the UI that it must stop rendering the cursor. This event - is misnamed and does not actually have anything to do with busyness. - -["restart", progpath, argv] ~ - |:restart| command has been used and the Nvim server is about to exit. - The UI should wait for the server to exit, and then start a new server - using `progpath` as the full path to the Nvim executable |v:progpath| and - `argv` as its arguments |v:argv|, and reattach to the new server. - Note: |--embed| and |--headless| are excluded from `argv`, and the client - should decide itself whether to add either flag. - -["suspend"] ~ - |:suspend| command or |CTRL-Z| mapping is used. A terminal client (or - another client where it makes sense) could suspend itself. Other - clients can safely ignore it. - -["update_menu"] ~ - The menu mappings changed. - -["bell"] ~ -["visual_bell"] ~ - Notify the user with an audible or visual bell, respectively. - -["flush"] ~ - Nvim is done redrawing the screen. For an implementation that renders - to an internal buffer, this is the time to display the redrawn parts - to the user. - -============================================================================== -Grid Events (line-based) *ui-linegrid* - -Activated by the `ext_linegrid` |ui-option|. Recommended for all new UIs. -Deactivates |ui-grid-old| implicitly. - -Unlike |ui-grid-old|, this UI extension emits a single `grid_line` event to -update a screen-line (whereas the old protocol emitted separate cursor, -highlight and text events per screen-line). - -Most of these events take a `grid` index as first parameter. Grid 1 is the -global grid used by default for the entire editor screen state. The -`ext_linegrid` capability by itself will never cause any additional grids to -be created; to enable per-window grids, activate |ui-multigrid|. - -Highlight attribute groups are predefined. UIs should maintain a table to map -numerical highlight ids to the actual attributes. - -["grid_resize", grid, width, height] ~ - Resize a `grid`. If `grid` wasn't seen by the client before, a new grid is - being created with this size. - -["default_colors_set", rgb_fg, rgb_bg, rgb_sp, cterm_fg, cterm_bg] ~ - The first three arguments set the default foreground, background and - special colors respectively. `cterm_fg` and `cterm_bg` specifies the - default color codes to use in a 256-color terminal. - - The RGB values will always be valid colors, by default. If no - colors have been set, they will default to black and white, depending - on 'background'. By setting the `ext_termcolors` option, instead - -1 will be used for unset colors. This is mostly useful for a TUI - implementation, where using the terminal builtin ("ANSI") defaults - are expected. - - Note: Unlike the corresponding |ui-grid-old| events, the screen is not - always cleared after sending this event. The UI must repaint the - screen with changed background color itself. - - *ui-event-hl_attr_define* -["hl_attr_define", id, rgb_attr, cterm_attr, info] ~ - Add a highlight with `id` to the highlight table, with the - attributes specified by the `rgb_attr` and `cterm_attr` dicts, with the - following (all optional) keys. - - `foreground`: foreground color. - `background`: background color. - `special`: color to use for various underlines, when - present. - `reverse`: reverse video. Foreground and background colors - are switched. - `italic`: italic text. - `bold`: bold text. - `strikethrough`: struckthrough text. - `underline`: underlined text. The line has `special` color. - `undercurl`: undercurled text. The curl has `special` color. - `underdouble`: double underlined text. The lines have `special` color. - `underdotted`: underdotted text. The dots have `special` color. - `underdashed`: underdashed text. The dashes have `special` color. - `altfont`: alternative font. - `blend`: blend level (0-100). Could be used by UIs to - support blending floating windows to the - background or to signal a transparent cursor. - `url`: URL associated with this highlight. UIs should - present the region as a clickable hyperlink. - - For absent color keys the default color should be used. Don't store - the default value in the table, rather a sentinel value, so that - a changed default color will take effect. - All boolean keys default to false, and will only be sent when they - are true. - - Highlights are always transmitted both for both the RGB format and as - terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters - respectively. The |ui-rgb| option has no effect anymore. - Most external UIs will only need to store and use the `rgb_attr` - attributes. - - `id` 0 will always be used for the default highlight with colors defined - by `default_colors_set` and no styles applied. - - Note: Nvim may reuse `id` values if its internal highlight table is full. - In that case Nvim will always issue redraws of screen cells that are - affected by redefined ids, so UIs do not need to keep track of this - themselves. - - `info` is an empty array unless |ui-hlstate| is enabled. - -["hl_group_set", name, hl_id] ~ - The built-in highlight group `name` was set to use the attributes `hl_id` - defined by a previous `hl_attr_define` call. This event is not needed - to render the grids which use attribute ids directly, but is useful - for a UI who want to render its own elements with consistent - highlighting. For instance a UI using |ui-popupmenu| events, might - use the |hl-Pmenu| family of builtin highlights. - - *ui-event-grid_line* -["grid_line", grid, row, col_start, cells, wrap] ~ - Redraw a continuous part of a `row` on a `grid`, starting at the column - `col_start`. `cells` is an array of arrays each with 1 to 3 items: - `[text(, hl_id, repeat)]` . `text` is the UTF-8 text that should be put in - a cell, with the highlight `hl_id` defined by a previous `hl_attr_define` - call. If `hl_id` is not present the most recently seen `hl_id` in - the same call should be used (it is always sent for the first - cell in the event). If `repeat` is present, the cell should be - repeated `repeat` times (including the first time), otherwise just - once. - - The right cell of a double-width char will be represented as the empty - string. Double-width chars never use `repeat`. - - If the array of cell changes doesn't reach to the end of the line, the - rest should remain unchanged. A whitespace char, repeated - enough to cover the remaining line, will be sent when the rest of the - line should be cleared. - - `wrap` is a boolean indicating that this line wraps to the next row. - When redrawing a line which wraps to the next row, Nvim will emit a - `grid_line` event covering the last column of the line with `wrap` set - to true, followed immediately by a `grid_line` event starting at the - first column of the next row. - -["grid_clear", grid] ~ - Clear a `grid`. - -["grid_destroy", grid] ~ - `grid` will not be used anymore and the UI can free any data associated - with it. - -["grid_cursor_goto", grid, row, col] ~ - Makes `grid` the current grid and `row, col` the cursor position on this - grid. This event will be sent at most once in a `redraw` batch and - indicates the visible cursor position. - -["grid_scroll", grid, top, bot, left, right, rows, cols] ~ - Scroll a region of `grid`. This is semantically unrelated to editor - |scrolling|, rather this is an optimized way to say "copy these screen - cells". - - The following diagrams show what happens per scroll direction. - "===" represents the SR (scroll region) boundaries. - "---" represents the moved rectangles. - Note that dst and src share a common region. - - If `rows` is bigger than 0, move a rectangle in the SR up, this can - happen while scrolling down. -> - +-------------------------+ - | (clipped above SR) | ^ - |=========================| dst_top | - | dst (still in SR) | | - +-------------------------+ src_top | - | src (moved up) and dst | | - |-------------------------| dst_bot | - | src (invalid) | | - +=========================+ src_bot -< - If `rows` is less than zero, move a rectangle in the SR down, this can - happen while scrolling up. -> - +=========================+ src_top - | src (invalid) | | - |------------------------ | dst_top | - | src (moved down) and dst| | - +-------------------------+ src_bot | - | dst (still in SR) | | - |=========================| dst_bot | - | (clipped below SR) | v - +-------------------------+ -< - `cols` is always zero in this version of Nvim, and reserved for future - use. - - Note when updating code from |ui-grid-old| events: ranges are - end-exclusive, which is consistent with API conventions, but different - from `set_scroll_region` which was end-inclusive. - - The scrolled-in area will be filled using |ui-event-grid_line| directly - after the scroll event. The UI thus doesn't need to clear this area as - part of handling the scroll event. - -============================================================================== -Grid Events (cell-based) *ui-grid-old* - -This is the legacy representation of the screen grid, emitted if |ui-linegrid| -is not active. New UIs should implement |ui-linegrid| instead. - -["resize", width, height] ~ - The grid is resized to `width` and `height` cells. - -["clear"] ~ - Clear the grid. - -["eol_clear"] ~ - Clear from the cursor position to the end of the current line. - -["cursor_goto", row, col] ~ - Move the cursor to position (row, col). Currently, the same cursor is - used to define the position for text insertion and the visible cursor. - However, only the last cursor position, after processing the entire - array in the "redraw" event, is intended to be a visible cursor - position. - -["update_fg", color] ~ -["update_bg", color] ~ -["update_sp", color] ~ - Set the default foreground, background and special colors - respectively. - - *ui-event-highlight_set* -["highlight_set", attrs] ~ - Set the attributes that the next text put on the grid will have. - `attrs` is a dict with the keys below. Any absent key is reset - to its default value. Color defaults are set by the `update_fg` etc - updates. All boolean keys default to false. - - `foreground`: foreground color. - `background`: background color. - `special`: color to use for various underlines, when present. - `reverse`: reverse video. Foreground and background colors are - switched. - `italic`: italic text. - `bold`: bold text. - `strikethrough`: struckthrough text. - `underline`: underlined text. The line has `special` color. - `undercurl`: undercurled text. The curl has `special` color. - `underdouble`: double underlined text. The lines have `special` color. - `underdotted`: underdotted text. The dots have `special` color. - `underdashed`: underdashed text. The dashes have `special` color. - -["put", text] ~ - The (utf-8 encoded) string `text` is put at the cursor position - (and the cursor is advanced), with the highlights as set by the - last `highlight_set` update. - -["set_scroll_region", top, bot, left, right] ~ - Define the scroll region used by `scroll` below. - - Note: ranges are end-inclusive, which is inconsistent with API - conventions. - -["scroll", count] ~ - Scroll the text in the scroll region. The diagrams below illustrate - what will happen, depending on the scroll direction. "=" is used to - represent the SR(scroll region) boundaries and "-" the moved rectangles. - Note that dst and src share a common region. - - If count is bigger than 0, move a rectangle in the SR up, this can - happen while scrolling down. -> - +-------------------------+ - | (clipped above SR) | ^ - |=========================| dst_top | - | dst (still in SR) | | - +-------------------------+ src_top | - | src (moved up) and dst | | - |-------------------------| dst_bot | - | src (cleared) | | - +=========================+ src_bot -< - If count is less than zero, move a rectangle in the SR down, this can - happen while scrolling up. -> - +=========================+ src_top - | src (cleared) | | - |------------------------ | dst_top | - | src (moved down) and dst| | - +-------------------------+ src_bot | - | dst (still in SR) | | - |=========================| dst_bot | - | (clipped below SR) | v - +-------------------------+ -< -============================================================================== -Highlight Events *ui-hlstate* - -Activated by the `ext_hlstate` |ui-option|. -Activates |ui-linegrid| implicitly. - -If `ext_hlstate` is enabled, Nvim will emit detailed highlight state in -|ui-linegrid| events. Otherwise (by default) Nvim only describes grid cells -using the final calculated highlight attributes described at -|ui-event-highlight_set|. - -`ext_hlstate` provides a semantic description of active highlights for each -grid cell. Highlights are predefined in a table, see |ui-event-hl_attr_define| -and |ui-event-grid_line|. - -The `info` parameter in `hl_attr_define` contains a semantic description of -the highlights. Because highlight groups can be combined, this is an array -where the highest-priority item is last. Each item is a dict with these keys: - - `kind`: always present. One of the following values: - "ui": Builtin UI highlight. |highlight-groups| - "syntax": Highlight applied to a buffer by a syntax declaration or - other runtime/plugin functionality such as - |nvim_buf_set_extmark()| - "terminal": highlight from a process running in a |terminal-emulator|. - Contains no further semantic information. - `ui_name`: Highlight name from |highlight-groups|. Only for "ui" kind. - `hi_name`: Name of the final |:highlight| group where the used - attributes are defined. - `id`: Unique numeric id representing this item. - -Note: "ui" items will have both `ui_name` and `hi_name` present. These can -differ, because the builtin group was linked to another group |:hi-link| , or -because 'winhighlight' was used. UI items will be transmitted, even if the -highlight group is cleared, so `ui_name` can always be used to reliably identify -screen elements, even if no attributes have been applied. - -============================================================================== -Multigrid Events *ui-multigrid* - -Activated by the `ext_multigrid` |ui-option|. -Activates |ui-linegrid| implicitly. - -See |ui-linegrid| for grid events. -See |nvim_ui_try_resize_grid()| to request changing the grid size. -See |nvim_input_mouse()| for sending mouse events to Nvim. - -The multigrid extension gives UIs more control over how windows are displayed: -- UIs receive updates on a separate grid for each window. -- UIs can set the grid size independently of how much space the window - occupies on the global layout. So the UI could use a different font size - per-window. Or reserve space around the border of the window for its own - elements, such as scrollbars from the UI toolkit. -- A dedicated grid is used for messages, which may scroll over the window - area. (Alternatively |ui-messages| can be used). - -By default, the grid size is handled by Nvim and set to the outer grid size -(i.e. the size of the window frame in Nvim) whenever the split is created. -Once a UI sets a grid size, Nvim does not handle the size for that grid and -the UI must change the grid size whenever the outer size is changed. To -delegate grid-size handling back to Nvim, request the size (0, 0). - -A window can be hidden and redisplayed without its grid being deallocated. -This can happen multiple times for the same window, for instance when switching -tabs. - -["win_pos", grid, win, start_row, start_col, width, height] ~ - Set the position and size of the grid in Nvim (i.e. the outer grid - size). If the window was previously hidden, it should now be shown - again. - -["win_float_pos", grid, win, anchor, anchor_grid, anchor_row, anchor_col, mouse_enabled, zindex, compindex, screen_row, screen_col] ~ - Display or reconfigure floating window `win`. - - There are two alternative ways of positioning the window - - Manually - The window should be displayed above another grid - `anchor_grid` at the specified position `anchor_row` and - `anchor_col`. For the meaning of `anchor` and more details of - positioning, see |nvim_open_win()|. NOTE: you have to manually - ensure that the window fits the screen, possibly by further - reposition it. Ignore `screen_row` and `screen_col` in this case. - - Let nvim take care of the positioning - You can ignore `anchor` - and display the window at `screen_row` and `screen_col`. - - `mouse_enabled` is true if the window can receive mouse events. - - `zindex` is the configured zindex, while `compindex` is the exact - rendering order of the windows determined by nvim. To render exactly - like the TUI, first render all the non-floating windows, then render - in the `compindex` order, overwriting any floating window cells. - Finally, blend the floating window cells against the non-floating - background. To add more blending, you can group the windows by zindex, - and blend between the layers. But note that windows inside the same - zindex should still overwrite previous cells inside the same layer - without blending. This ensures that plugins that render multiple - windows, to add borders for example, work as expected. - -["win_external_pos", grid, win] ~ - Display or reconfigure external window `win`. The window should be - displayed as a separate top-level window in the desktop environment, - or something similar. - -["win_hide", grid] ~ - Stop displaying the window. The window can be shown again later. - -["win_close", grid] ~ - Close the window. - -["msg_set_pos", grid, row, scrolled, sep_char, zindex, compindex] ~ - Display messages on `grid`. The grid will be displayed at `row` on - the default grid (grid=1), covering the full column width. `scrolled` - indicates whether the message area has been scrolled to cover other - grids. It can be useful to draw a separator then |msgsep|. The Builtin - TUI draws a full line filled with `sep_char` ('fillchars' msgsep - field) and |hl-MsgSeparator| highlight. - - When |ui-messages| is active, no message grid is used, and this event - will not be sent. - - `zindex` and `compindex` have the same meaning as for `win_float_pos`. - The `zindex` always has a fixed value of 200 and included for - completeness. - -["win_viewport", grid, win, topline, botline, curline, curcol, line_count, scroll_delta] ~ - Indicates the range of buffer text displayed in the window, as well - as the cursor position in the buffer. All positions are zero-based. - `botline` is set to one more than the line count of the buffer, if - there are filler lines past the end. `scroll_delta` contains how much - the top line of a window moved since `win_viewport` was last emitted. - It is intended to be used to implement smooth scrolling. For this - purpose it only counts "virtual" or "displayed" lines, so folds - only count as one line. When scrolling more than a full screen it is - an approximate value. - - All updates, such as `grid_line`, in a batch affects the new viewport, - despite the fact that `win_viewport` is received after the updates. - Applications implementing, for example, smooth scrolling should take - this into account and keep the grid separated from what's displayed on - the screen and copy it to the viewport destination once `win_viewport` - is received. - -["win_viewport_margins", grid, win, top, bottom, left, right] ~ - Indicates the margins of a window grid which are _not_ part of the - viewport as indicated by the `win_viewport` event. This happens - e.g. in the presence of 'winbar' and floating window borders. - -["win_extmark", grid, win, ns_id, mark_id, row, col] ~ - Updates the position of an extmark which is currently visible in a - window. Only emitted if the mark has the `ui_watched` attribute. - -============================================================================== -Popupmenu Events *ui-popupmenu* - -Activated by the `ext_popupmenu` |ui-option|. - -This UI extension delegates presentation of the |popupmenu-completion| and -command-line 'wildmenu'. - -The UI decides how to present the menu. For example, depending on the last -`mode_change` event, command-line wildmenu may be presented horizontally, -while insert-mode completion would show a vertical popupmenu. - -["popupmenu_show", items, selected, row, col, grid] ~ - Show |popupmenu-completion|. `items` is an array of completion items - to show; each item is an array of the form [word, kind, menu, info] as - defined at |complete-items|, except that `word` is replaced by `abbr` - if present. `selected` is the initially-selected item, a zero-based - index into the array of items (-1 if no item is selected). `row` and - `col` give the anchor position, where the first character of the - completed word will be. When |ui-multigrid| is used, `grid` is the - grid for the anchor position. When `ext_cmdline` is active, `grid` is - set to -1 to indicate the popupmenu should be anchored to the external - cmdline. Then `col` will be a byte position in the cmdline text. - -["popupmenu_select", selected] ~ - Select an item in the current popupmenu. `selected` is a zero-based - index into the array of items from the last popupmenu_show event, or - -1 if no item is selected. - -["popupmenu_hide"] ~ - Hide the popupmenu. - -============================================================================== -Tabline Events *ui-tabline* - -Activated by the `ext_tabline` |ui-option|. - -["tabline_update", curtab, tabs, curbuf, buffers] ~ - Tabline was updated. UIs should present this data in a custom tabline - widget. Note: options `curbuf` + `buffers` were added in API7. - curtab: Current Tabpage - tabs: List of Dicts [{ "tab": Tabpage, "name": String }, ...] - curbuf: Current buffer handle. - buffers: List of Dicts [{ "buffer": buffer handle, "name": String}, ...] - -============================================================================== -Cmdline Events *ui-cmdline* - -Activated by the `ext_cmdline` |ui-option|. - -This UI extension delegates presentation of the |cmdline| (except 'wildmenu'). -For command-line 'wildmenu' UI events, activate |ui-popupmenu|. - -["cmdline_show", content, pos, firstc, prompt, indent, level, hl_id] ~ - content: List of [attrs, string, hl_id] - [[{}, "t", hl_id], [attrs, "est", hl_id], ...] - - Triggered when the cmdline is displayed or changed. - The `content` is the full content that should be displayed in the - cmdline, and the `pos` is the position of the cursor that in the - cmdline. The content is divided into chunks with different highlight - attributes represented as a dict (see |ui-event-highlight_set|). - - `firstc` and `prompt` are text, that if non-empty should be - displayed in front of the command line. `firstc` always indicates - built-in command lines such as `:` (ex command) and `/` `?` (search), - while `prompt` is an |input()| prompt, highlighted with `hl_id`. - `indent` tells how many spaces the content should be indented. - - The Nvim command line can be invoked recursively, for instance by - typing `<c-r>=` at the command line prompt. The `level` field is used - to distinguish different command lines active at the same time. The - first invoked command line has level 1, the next recursively-invoked - prompt has level 2. A command line invoked from the |cmdline-window| - has a higher level than the edited command line. - -["cmdline_pos", pos, level] ~ - Change the cursor position in the cmdline. - -["cmdline_special_char", c, shift, level] ~ - Display a special char in the cmdline at the cursor position. This is - typically used to indicate a pending state, e.g. after |c_CTRL-V|. If - `shift` is true the text after the cursor should be shifted, otherwise - it should overwrite the char at the cursor. - - Should be hidden at next cmdline_show. - -["cmdline_hide", level, abort] ~ - Hide the cmdline. `level` is the nesting level of the cmdline being hidden. - `abort` is true if the cmdline is hidden after an aborting condition - (|c_Esc| or |c_CTRL-C|). - -["cmdline_block_show", lines] ~ - Show a block of context to the current command line. For example if - the user defines a |:function| interactively: >vim - :function Foo() - : echo "foo" - : -< - `lines` is a list of lines of highlighted chunks, in the same form as - the "cmdline_show" `contents` parameter. - -["cmdline_block_append", line] ~ - Append a line at the end of the currently shown block. - -["cmdline_block_hide"] ~ - Hide the block. - -============================================================================== -Message/Dialog Events *ui-messages* - -Activated by the `ext_messages` |ui-option|. -Activates |ui-linegrid| and |ui-cmdline| implicitly. - -This UI extension delegates presentation of messages and dialogs. Messages -that would otherwise render in the message/cmdline screen space, are emitted -as UI events. - -Nvim will not allocate screen space for the cmdline or messages. 'cmdheight' -will be set to zero, but can be changed and used for the replacing cmdline or -message window. Cmdline state is emitted as |ui-cmdline| events, which the UI -must handle. - -["msg_show", kind, content, replace_last, history, append] ~ - Display a message to the user. - - kind - Name indicating the message kind: - "" (empty) Unknown (consider a |feature-request|) - "empty" Empty message (`:echo ""`), with empty `content`. - Should clear messages sharing the 'cmdheight' - area if it is the only message in a batch. - "bufwrite" |:write| message - "confirm" Message preceding a prompt (|:confirm|, - |confirm()|, |inputlist()|, |z=|, …) - "emsg" Error (|errors|, internal error, |:throw|, …) - "echo" |:echo| message - "echomsg" |:echomsg| message - "echoerr" |:echoerr| message - "completion" |ins-completion-menu| message - "list_cmd" List output for various commands (|:ls|, |:set|, …) - "lua_error" Error in |:lua| code - "lua_print" |print()| from |:lua| code - "rpc_error" Error response from |rpcrequest()| - "quickfix" Quickfix navigation message - "search_cmd" Entered search command - "search_count" Search count message ("S" flag of 'shortmess') - "shell_cmd" |:!cmd| executed command - "shell_err" |:!cmd| shell stderr output - "shell_out" |:!cmd| shell stdout output - "shell_ret" |:!cmd| shell return code - "undo" |:undo| and |:redo| message - "verbose" 'verbose' message - "wildlist" 'wildmode' "list" message - "wmsg" Warning ("search hit BOTTOM", |W10|, …) - New kinds may be added in the future; clients should treat unknown - kinds as the empty kind. - - content - Array of `[attr_id, text_chunk, hl_id]` tuples, building up the - message text of chunks of different highlights. No extra spacing - should be added between chunks, the `text_chunk` by itself - contains any necessary whitespace. Messages can contain line - breaks "\n". - - replace_last - Decides how multiple messages should be displayed: - false: Display the message together with all previous messages - that are still visible. - true: Replace the message in the most-recent `msg_show` call, - but any other visible message should still remain. - - history - True if the message was added to the |:messages| history. - - append - True if the message should be appeneded to the previous message, - rather than started on a new line. Is set for |:echon|. - -["msg_clear"] ~ - Clear all messages currently displayed by "msg_show", emitted after - clearing the screen (messages sent by other "msg_" events below should - not be affected). - -["msg_showmode", content] ~ - Shows 'showmode' and |recording| messages. `content` has the same - format as in "msg_show". This event is sent with empty `content` to - hide the last message. - -["msg_showcmd", content] ~ - Shows 'showcmd' messages. `content` has the same format as in "msg_show". - This event is sent with empty `content` to hide the last message. - -["msg_ruler", content] ~ - Used to display 'ruler' when there is no space for the ruler in a - statusline. `content` has the same format as in "msg_show". This event is - sent with empty `content` to hide the last message. - -["msg_history_show", entries, prev_cmd] ~ - Sent when |:messages| or |g<| command is invoked. History is sent as a - list of entries, where each entry is a `[kind, content, append]` tuple. - - prev_cmd - True when sent with |g<| command, false with |:messages|. - - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt @@ -588,7 +588,7 @@ after the substitute() call. FUNCTIONS *function-list* There are many functions. We will mention them here, grouped by what they are -used for. You can find an alphabetical list here: |builtin-function-details|. +used for. You can find an alphabetical list here: |vimscript-functions|. Use CTRL-] on the function name to jump to detailed help on it. String manipulation: *string-functions* diff --git a/runtime/doc/vimeval.txt b/runtime/doc/vimeval.txt @@ -1813,7 +1813,7 @@ functions. Scripts can also define |user-function|s. See |function-list| to browse functions by topic. The alphabetic list of all builtin functions and details are in a separate -help file: |builtin-functions|. +help file: |vimscript-functions|. ============================================================================== 5. Defining functions *user-function* diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt @@ -4,13 +4,13 @@ NVIM REFERENCE MANUAL -Vimscript functions *vimscript-functions* *builtin-functions* *builtin.txt* +Vimscript functions *vimscript-functions* *builtin.txt* For functions grouped by what they are used for see |function-list|. Type |gO| to see the table of contents. ============================================================================== -1. Details *builtin-function-details* +1. Details *vimscript-functions-details* abs({expr}) *abs()* Return the absolute value of {expr}. When {expr} evaluates to @@ -3165,8 +3165,7 @@ getchar([{expr} [, {opts}]]) *getchar()* Return zero otherwise. If {expr} is 1, only check if a character is available, it is not consumed. Return zero if no character available. - If you prefer always getting a string use |getcharstr()|, or - specify |FALSE| as "number" in {opts}. + To always get a string, specify "number" as |FALSE| in {opts}. Without {expr} and when {expr} is 0 a whole character or special key is returned. If it is a single character, the diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua @@ -619,10 +619,10 @@ vim.bo.bl = vim.bo.buflisted --- help help buffer (do not set this manually) --- nofile buffer is not related to a file, will not be written --- nowrite buffer will not be written +--- prompt buffer where only the last section can be edited, for +--- use by plugins. `prompt-buffer` --- quickfix list of errors `:cwindow` or locations `:lwindow` --- terminal `terminal-emulator` buffer ---- prompt buffer where only the last line can be edited, meant ---- to be used by a plugin, see `prompt-buffer` --- --- This option is used together with 'bufhidden' and 'swapfile' to --- specify special kinds of buffers. See `special-buffers`. diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua @@ -2828,8 +2828,7 @@ function vim.fn.getchangelist(buf) end --- Return zero otherwise. --- If {expr} is 1, only check if a character is available, it is --- not consumed. Return zero if no character available. ---- If you prefer always getting a string use |getcharstr()|, or ---- specify |FALSE| as "number" in {opts}. +--- To always get a string, specify "number" as |FALSE| in {opts}. --- --- Without {expr} and when {expr} is 0 a whole character or --- special key is returned. If it is a single character, the diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua @@ -21,12 +21,12 @@ local keymap = {} --- --- ```lua --- -- Map "x" to a Lua function: ---- vim.keymap.set('n', 'x', function() print("real lua function") end) +--- vim.keymap.set('n', 'x', function() print('real lua function') end) --- -- Map "<leader>x" to multiple modes for the current buffer: --- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true }) --- -- Map <Tab> to an expression (|:map-<expr>|): --- vim.keymap.set('i', '<Tab>', function() ---- return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" +--- return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>' --- end, { expr = true }) --- -- Map "[%%" to a <Plug> mapping: --- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)') diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua @@ -1653,14 +1653,12 @@ function lsp.with(handler, override_config) end end ---- Registry (a table) for client-side handlers, for custom server-commands that are not in the LSP ---- specification. +--- Map of client-defined handlers implementing custom (off-spec) commands which a server may +--- invoke. Each key is a unique command name; each value is a function which is called when an LSP +--- action (code action, code lenses, …) requests it by name. --- ---- If an LSP response contains a command which is not found in `vim.lsp.commands`, the command will ---- be executed via the LSP server using `workspace/executeCommand`. ---- ---- Each key in the table is a unique command name, and each value is a function which is called ---- when an LSP action (code action, code lenses, …) triggers the command. +--- If an LSP response requests a command not defined client-side, Nvim will forward it to the +--- server as `workspace/executeCommand`. --- --- - Argument 1 is the `Command`: --- ``` @@ -1686,7 +1684,7 @@ end --- end --- ``` --- ---- @type table<string,function> +--- @type table<string,fun(command: lsp.Command, ctx: table)> lsp.commands = setmetatable({}, { __newindex = function(tbl, key, value) assert(type(key) == 'string', 'The key for commands in `vim.lsp.commands` must be a string') diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua @@ -63,10 +63,7 @@ local validate = vim.validate --- ``` --- @field cmd_env? table --- ---- Client commands. Map of command names to user-defined functions. Commands passed to `start()` ---- take precedence over the global command registry. Each key must be a unique command name, and ---- the value is a function which is called if any LSP action (code action, code lenses, …) triggers ---- the command. +--- Map of client-defined commands overriding the global |vim.lsp.commands|. --- @field commands? table<string,fun(command: lsp.Command, ctx: table)> --- --- Daemonize the server process so that it runs in a separate process group from Nvim. diff --git a/src/gen/gen_eval_files.lua b/src/gen/gen_eval_files.lua @@ -858,13 +858,13 @@ local CONFIG = { '\t\t NVIM REFERENCE MANUAL', '', '', - 'Vimscript functions\t*vimscript-functions* *builtin-functions* *builtin.txt*', + 'Vimscript functions\t\t\t*vimscript-functions* *builtin.txt*', '', 'For functions grouped by what they are used for see |function-list|.', '', '\t\t\t\t Type |gO| to see the table of contents.', '==============================================================================', - '1. Details *builtin-function-details*', + '1. Details *vimscript-functions-details*', '', }, footer = { diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua @@ -88,8 +88,9 @@ local new_layout = { -- Map of new:old pages, to redirect renamed pages. local redirects = { ['credits'] = 'backers', - ['tui'] = 'term', ['terminal'] = 'nvim_terminal_emulator', + ['tui'] = 'term', + ['api-ui-events'] = 'ui', } -- TODO: These known invalid |links| require an update to the relevant docs. @@ -1343,7 +1344,10 @@ This document moved to: |%s| local redirect_to = ('%s/%s'):format(to_dir, get_helppage(redirect_from)) local redirect_html, _ = gen_one(redirect_from, redirect_text, redirect_to, false, commit or '?', parser_path) - assert(redirect_html:find(helpfile_tag)) + assert( + redirect_html:find(vim.pesc(helpfile_tag)), + ('not found in redirect html: %s'):format(helpfile_tag) + ) tofile(redirect_to, redirect_html) print( diff --git a/src/nvim/CMakeLists.txt b/src/nvim/CMakeLists.txt @@ -157,8 +157,7 @@ elseif(CMAKE_SYSTEM_NAME MATCHES "Darwin") target_link_libraries(nvim_bin PRIVATE "-framework CoreServices") # Actually export symbols - symbols may not be visible even though - # ENABLE_EXPORTS is set to true. See - # https://github.com/neovim/neovim/issues/25295 + # ENABLE_EXPORTS is set. https://github.com/neovim/neovim/issues/25295 target_link_options(nvim_bin PRIVATE "-Wl,-export_dynamic") elseif(CMAKE_SYSTEM_NAME MATCHES "OpenBSD") target_link_libraries(main_lib INTERFACE pthread c++abi) diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua @@ -3564,8 +3564,7 @@ M.funcs = { Return zero otherwise. If {expr} is 1, only check if a character is available, it is not consumed. Return zero if no character available. - If you prefer always getting a string use |getcharstr()|, or - specify |FALSE| as "number" in {opts}. + To always get a string, specify "number" as |FALSE| in {opts}. Without {expr} and when {expr} is 0 a whole character or special key is returned. If it is a single character, the diff --git a/src/nvim/options.lua b/src/nvim/options.lua @@ -903,10 +903,10 @@ local options = { help help buffer (do not set this manually) nofile buffer is not related to a file, will not be written nowrite buffer will not be written + prompt buffer where only the last section can be edited, for + use by plugins. |prompt-buffer| quickfix list of errors |:cwindow| or locations |:lwindow| terminal |terminal-emulator| buffer - prompt buffer where only the last line can be edited, meant - to be used by a plugin, see |prompt-buffer| This option is used together with 'bufhidden' and 'swapfile' to specify special kinds of buffers. See |special-buffers|. diff --git a/src/nvim/syntax.c b/src/nvim/syntax.c @@ -5252,6 +5252,7 @@ void ex_syntax(exarg_T *eap) } } +/// @deprecated void ex_ownsyntax(exarg_T *eap) { if (curwin->w_s == &curwin->w_buffer->b_s) { diff --git a/test/functional/lua/system_spec.lua b/test/functional/lua/system_spec.lua @@ -74,23 +74,12 @@ describe('vim.system', function() end) it('can set environment', function() - eq( - 'TESTVAL', - system( - { n.testprg('printenv-test'), 'TEST' }, - { env = { TEST = 'TESTVAL' }, text = true } - ).stdout - ) - end) + local function test_env(opt) + eq('TESTVAL', system({ n.testprg('printenv-test'), 'TEST' }, opt).stdout) + end - it('can set environment with clear_env = true', function() - eq( - 'TESTVAL', - system( - { n.testprg('printenv-test'), 'TEST' }, - { clear_env = true, env = { TEST = 'TESTVAL' }, text = true } - ).stdout - ) + test_env({ env = { TEST = 'TESTVAL' }, text = true }) + test_env({ clear_env = true, env = { TEST = 'TESTVAL' }, text = true }) end) it('can set environment with clear_env = true and env = nil', function() diff --git a/test/functional/vimscript/eval_spec.lua b/test/functional/vimscript/eval_spec.lua @@ -5,7 +5,7 @@ -- null_spec.lua -- operators_spec.lua -- --- Tests for the Vimscript |builtin-functions| library should live in: +-- Tests for the Vimscript |vimscript-functions| library should live in: -- test/functional/vimscript/<funcname>_spec.lua -- test/functional/vimscript/functions_spec.lua diff --git a/test/functional/vimscript/functions_spec.lua b/test/functional/vimscript/functions_spec.lua @@ -1,4 +1,4 @@ --- Tests for misc Vimscript |builtin-functions|. +-- Tests for misc Vimscript |vimscript-functions|. -- -- If a function is non-trivial, consider moving its spec to: -- test/functional/vimscript/<funcname>_spec.lua