diff options
| author | Lewis Russell <lewis6991@gmail.com> | 2024-02-15 17:16:04 +0000 |
|---|---|---|
| committer | Lewis Russell <me@lewisr.dev> | 2024-02-27 14:41:17 +0000 |
| commit | 9beb40a4db5613601fc1a4b828a44e5977eca046 (patch) | |
| tree | 314096d28ccdf2a2b035091783baa35193887d6a /runtime/doc/api.txt | |
| parent | 7ad2e3c64562bfb0ea2f7be305e4b0e6d2474d64 (diff) | |
| download | rneovim-9beb40a4db5613601fc1a4b828a44e5977eca046.tar.gz rneovim-9beb40a4db5613601fc1a4b828a44e5977eca046.tar.bz2 rneovim-9beb40a4db5613601fc1a4b828a44e5977eca046.zip | |
feat(docs): replace lua2dox.lua
Problem:
The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.
Solution:
Re-implement the flow using Lua, LPEG and treesitter.
- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
- LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
- LPEG for C parsing (see `scripts/cdoc_parser.lua`)
- Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
- Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
- `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 232 |
1 files changed, 105 insertions, 127 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index e994644be9..1b00777532 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -579,7 +579,7 @@ created for extmark changes. ============================================================================== Global Functions *api-global* -nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* +nvim__get_runtime({pat}, {all}, {opts}) *nvim__get_runtime()* Find files in runtime directories Attributes: ~ @@ -700,7 +700,7 @@ nvim_chan_send({chan}, {data}) *nvim_chan_send()* • {chan} id of the channel • {data} data to write. 8-bit clean: can contain NUL bytes. -nvim_complete_set({index}, {*opts}) *nvim_complete_set()* +nvim_complete_set({index}, {opts}) *nvim_complete_set()* Set info for the completion candidate index. if the info was shown in a window, then the window and buffer ids are returned for further customization. If the text was not shown, an empty dict is returned. @@ -766,7 +766,7 @@ nvim_del_var({name}) *nvim_del_var()* Parameters: ~ • {name} Variable name -nvim_echo({chunks}, {history}, {*opts}) *nvim_echo()* +nvim_echo({chunks}, {history}, {opts}) *nvim_echo()* Echo a message. Parameters: ~ @@ -797,7 +797,7 @@ nvim_err_writeln({str}) *nvim_err_writeln()* See also: ~ • nvim_err_write() -nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* +nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()* Evaluates statusline string. Attributes: ~ @@ -878,13 +878,13 @@ nvim_get_api_info() *nvim_get_api_info()* Returns a 2-tuple (Array), where item 0 is the current channel id and item 1 is the |api-metadata| map (Dictionary). - Return: ~ - 2-tuple [{channel-id}, {api-metadata}] - Attributes: ~ |api-fast| |RPC| only + Return: ~ + 2-tuple [{channel-id}, {api-metadata}] + nvim_get_chan_info({chan}) *nvim_get_chan_info()* Gets information about a channel. @@ -900,12 +900,10 @@ nvim_get_chan_info({chan}) *nvim_get_chan_info()* • "stderr" stderr of this Nvim instance • "socket" TCP/IP socket or named pipe • "job" Job with communication over its stdio. - • "mode" How data received on the channel is interpreted. • "bytes" Send and receive raw bytes. • "terminal" |terminal| instance interprets ASCII sequences. • "rpc" |RPC| communication on the channel is active. - • "pty" (optional) Name of pseudoterminal. On a POSIX system this is a device path like "/dev/pts/1". If the name is unknown, the key will still be present if a pty is used (e.g. for conpty on Windows). @@ -937,7 +935,7 @@ nvim_get_color_map() *nvim_get_color_map()* Return: ~ Map of color names and RGB values. -nvim_get_context({*opts}) *nvim_get_context()* +nvim_get_context({opts}) *nvim_get_context()* Gets a map of the current editor state. Parameters: ~ @@ -972,7 +970,7 @@ nvim_get_current_win() *nvim_get_current_win()* Return: ~ Window handle -nvim_get_hl({ns_id}, {*opts}) *nvim_get_hl()* +nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()* Gets all or specific highlight groups in a namespace. Note: ~ @@ -1001,7 +999,7 @@ nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* similar to |hlID()|, but allocates a new ID if not present. -nvim_get_hl_ns({*opts}) *nvim_get_hl_ns()* +nvim_get_hl_ns({opts}) *nvim_get_hl_ns()* Gets the active highlight namespace. Parameters: ~ @@ -1024,7 +1022,7 @@ nvim_get_keymap({mode}) *nvim_get_keymap()* Array of |maparg()|-like dictionaries describing mappings. The "buffer" key is always zero. -nvim_get_mark({name}, {*opts}) *nvim_get_mark()* +nvim_get_mark({name}, {opts}) *nvim_get_mark()* Returns a `(row, col, buffer, buffername)` tuple representing the position of the uppercase/file named mark. "End of line" column position is returned as |v:maxcol| (big number). See |mark-motions|. @@ -1050,12 +1048,12 @@ nvim_get_mode() *nvim_get_mode()* Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for input. - Return: ~ - Dictionary { "mode": String, "blocking": Boolean } - Attributes: ~ |api-fast| + Return: ~ + Dictionary { "mode": String, "blocking": Boolean } + nvim_get_proc({pid}) *nvim_get_proc()* Gets info describing process `pid`. @@ -1222,7 +1220,7 @@ nvim_notify({msg}, {log_level}, {opts}) *nvim_notify()* • {log_level} The log level • {opts} Reserved for future use. -nvim_open_term({buffer}, {*opts}) *nvim_open_term()* +nvim_open_term({buffer}, {opts}) *nvim_open_term()* Open a terminal instance in a buffer By default (and currently the only option) the terminal will not be @@ -1280,14 +1278,13 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* • {data} Multiline input. May be binary (containing NUL bytes). • {crlf} Also break lines at CR and CRLF. • {phase} -1: paste in a single call (i.e. without streaming). To - "stream" a paste, call `nvim_paste` sequentially - with these `phase` values: + "stream" a paste, call `nvim_paste` sequentially with these + `phase` values: • 1: starts the paste (exactly once) • 2: continues the paste (zero or more times) • 3: ends the paste (exactly once) Return: ~ - • true: Client may continue pasting. • false: Client must cancel the paste. @@ -1326,7 +1323,7 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) • cpoptions *nvim_select_popupmenu_item()* -nvim_select_popupmenu_item({item}, {insert}, {finish}, {*opts}) +nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) Selects an item in the completion popup menu. If neither |ins-completion| nor |cmdline-completion| popup menu is active @@ -1450,20 +1447,20 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Parameters: ~ • {window} Window handle -nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* +nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()* Sets a highlight group. Note: ~ - • Unlike the `:highlight` command which can update a highlight group, this - function completely replaces the definition. For example: + • Unlike the `:highlight` command which can update a highlight group, + this function completely replaces the definition. For example: `nvim_set_hl(0, 'Visual', {})` will clear the highlight group 'Visual'. - • The fg and bg keys also accept the string values `"fg"` or `"bg"` which - act as aliases to the corresponding foreground and background values - of the Normal group. If the Normal group has not been defined, using - these values results in an error. - • If `link` is used in combination with other attributes; only the `link` - will take effect (see |:hi-link|). + • The fg and bg keys also accept the string values `"fg"` or `"bg"` + which act as aliases to the corresponding foreground and background + values of the Normal group. If the Normal group has not been defined, + using these values results in an error. + • If `link` is used in combination with other attributes; only the + `link` will take effect (see |:hi-link|). Parameters: ~ • {ns_id} Namespace id for this highlight |nvim_create_namespace()|. @@ -1520,7 +1517,7 @@ nvim_set_hl_ns_fast({ns_id}) *nvim_set_hl_ns_fast()* Parameters: ~ • {ns_id} the namespace to activate -nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* +nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* Sets a global |mapping| for the given mode. To set a buffer-local mapping, use |nvim_buf_set_keymap()|. @@ -1537,8 +1534,8 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* < Parameters: ~ - • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or - "!" for |:map!|, or empty string for |:map|. "ia", "ca" or + • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) + or "!" for |:map!|, or empty string for |:map|. "ia", "ca" or "!a" for abbreviation in Insert mode, Cmdline mode, or both, respectively • {lhs} Left-hand-side |{lhs}| of the mapping. @@ -1651,7 +1648,7 @@ nvim_eval({expr}) *nvim_eval()* Return: ~ Evaluation result or expanded object -nvim_exec2({src}, {*opts}) *nvim_exec2()* +nvim_exec2({src}, {opts}) *nvim_exec2()* Executes Vimscript (multiline block of Ex commands), like anonymous |:source|. @@ -1704,18 +1701,16 @@ nvim_parse_expression({expr}, {flags}, {highlight}) region [start_col, end_col)). Return: ~ - • AST: top-level dictionary with these keys: • "error": Dictionary with error, present only if parser saw some error. Contains the following keys: • "message": String, error message in printf format, translated. Must contain exactly one "%.*s". • "arg": String, error message argument. - • "len": Amount of bytes successfully parsed. With flags equal to "" - that should be equal to the length of expr string. (“Successfully - parsed” here means “participated in AST creation”, not “till the - first error”.) + that should be equal to the length of expr string. ("Successfully + parsed" here means "participated in AST creation", not "till the + first error".) • "ast": AST, either nil or a dictionary with these keys: • "type": node type, one of the value names from ExprASTNodeType stringified without "kExprNode" prefix. @@ -1730,7 +1725,6 @@ nvim_parse_expression({expr}, {flags}, {highlight}) is zero, one or two children, key will not be present if node has no children. Maximum number of children may be found in node_maxchildren array. - • Local values (present only for certain nodes): • "scope": a single Integer, specifies scope for "Option" and "PlainIdentifier" nodes. For "Option" it is one of ExprOptScope @@ -1760,11 +1754,11 @@ nvim_parse_expression({expr}, {flags}, {highlight}) Command Functions *api-command* *nvim_buf_create_user_command()* -nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts}) +nvim_buf_create_user_command({buffer}, {name}, {command}, {opts}) Creates a buffer-local command |user-commands|. Parameters: ~ - • {buffer} Buffer handle, or 0 for current buffer. + • {buffer} Buffer handle, or 0 for current buffer. See also: ~ • nvim_create_user_command @@ -1780,7 +1774,7 @@ nvim_buf_del_user_command({buffer}, {name}) • {buffer} Buffer handle, or 0 for current buffer. • {name} Name of the command to delete. -nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* +nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* Gets a map of buffer-local |user-commands|. Parameters: ~ @@ -1790,7 +1784,7 @@ nvim_buf_get_commands({buffer}, {*opts}) *nvim_buf_get_commands()* Return: ~ Map of maps describing commands. -nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* +nvim_cmd({cmd}, {opts}) *nvim_cmd()* Executes an Ex command. Unlike |nvim_command()| this command takes a structured Dictionary instead @@ -1825,7 +1819,7 @@ nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* • |nvim_command()| *nvim_create_user_command()* -nvim_create_user_command({name}, {command}, {*opts}) +nvim_create_user_command({name}, {command}, {opts}) Creates a global |user-commands| command. For Lua usage see |lua-guide-commands-create|. @@ -1885,7 +1879,7 @@ nvim_del_user_command({name}) *nvim_del_user_command()* Parameters: ~ • {name} Name of the command to delete. -nvim_get_commands({*opts}) *nvim_get_commands()* +nvim_get_commands({opts}) *nvim_get_commands()* Gets a map of global (non-buffer-local) Ex commands. Currently only |user-commands| are supported, not builtin Ex commands. @@ -1899,7 +1893,7 @@ nvim_get_commands({*opts}) *nvim_get_commands()* See also: ~ • |nvim_get_all_options_info()| -nvim_parse_cmd({str}, {*opts}) *nvim_parse_cmd()* +nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* Parse command line. Doesn't check the validity of command arguments. @@ -1937,13 +1931,11 @@ nvim_parse_cmd({str}, {*opts}) *nvim_parse_cmd()* • bar: (boolean) The "|" character is treated as a command separator and the double quote character (") is treated as the start of a comment. - • mods: (dictionary) |:command-modifiers|. • filter: (dictionary) |:filter|. • pattern: (string) Filter pattern. Empty string if there is no filter. • force: (boolean) Whether filter is inverted or not. - • silent: (boolean) |:silent|. • emsg_silent: (boolean) |:silent!|. • unsilent: (boolean) |:unsilent|. @@ -1986,7 +1978,7 @@ nvim_get_all_options_info() *nvim_get_all_options_info()* See also: ~ • |nvim_get_commands()| -nvim_get_option_info2({name}, {*opts}) *nvim_get_option_info2()* +nvim_get_option_info2({name}, {opts}) *nvim_get_option_info2()* Gets the option information for one option from arbitrary buffer or window Resulting dictionary has keys: @@ -2020,7 +2012,7 @@ nvim_get_option_info2({name}, {*opts}) *nvim_get_option_info2()* Return: ~ Option Information -nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* +nvim_get_option_value({name}, {opts}) *nvim_get_option_value()* Gets the value of an option. The behavior of this function matches that of |:set|: the local value of an option is returned if it exists; otherwise, the global value is returned. Local values always correspond to the @@ -2043,7 +2035,7 @@ nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* Option value *nvim_set_option_value()* -nvim_set_option_value({name}, {value}, {*opts}) +nvim_set_option_value({name}, {value}, {opts}) Sets the value of an option. The behavior of this function matches that of |:set|: for global-local options, both the global and local value are set unless otherwise specified with {scope}. @@ -2069,16 +2061,16 @@ For more information on buffers, see |buffers|. Unloaded Buffers: ~ Buffers may be unloaded by the |:bunload| command or the buffer's -|'bufhidden'| option. When a buffer is unloaded its file contents are -freed from memory and vim cannot operate on the buffer lines until it is -reloaded (usually by opening the buffer again in a new window). API -methods such as |nvim_buf_get_lines()| and |nvim_buf_line_count()| will be -affected. +|'bufhidden'| option. When a buffer is unloaded its file contents are freed +from memory and vim cannot operate on the buffer lines until it is reloaded +(usually by opening the buffer again in a new window). API methods such as +|nvim_buf_get_lines()| and |nvim_buf_line_count()| will be affected. You can use |nvim_buf_is_loaded()| or |nvim_buf_line_count()| to check whether a buffer is loaded. -nvim_buf_attach({buffer}, {send_buffer}, {*opts}) *nvim_buf_attach()* + +nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua callbacks. Example (Lua): capture buffer updates in a global `events` variable (use @@ -2100,8 +2092,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {*opts}) *nvim_buf_attach()* callbacks. • {opts} Optional parameters. • on_lines: Lua callback invoked on change. Return a - truthy value (not `false` or `nil`) - to detach. Args: + truthy value (not `false` or `nil`) to detach. Args: • the string "lines" • buffer handle • b:changedtick @@ -2111,12 +2102,10 @@ nvim_buf_attach({buffer}, {send_buffer}, {*opts}) *nvim_buf_attach()* • byte count of previous contents • deleted_codepoints (if `utf_sizes` is true) • deleted_codeunits (if `utf_sizes` is true) - • on_bytes: Lua callback invoked on change. This callback receives more granular information about the change compared to on_lines. Return a truthy value - (not `false` or `nil`) to - detach. Args: + (not `false` or `nil`) to detach. Args: • the string "bytes" • buffer handle • b:changedtick @@ -2134,22 +2123,18 @@ nvim_buf_attach({buffer}, {send_buffer}, {*opts}) *nvim_buf_attach()* • new end column of the changed text (if new end row = 0, offset from start column) • new end byte length of the changed text - • on_changedtick: Lua callback invoked on changedtick increment without text change. Args: • the string "changedtick" • buffer handle • b:changedtick - • on_detach: Lua callback invoked on detach. Args: • the string "detach" • buffer handle - • on_reload: Lua callback invoked on reload. The entire buffer content should be considered changed. Args: • the string "reload" • buffer handle - • utf_sizes: include UTF-32 and UTF-16 size of the replaced region, as args to `on_lines`. • preview: also attach to command preview (i.e. @@ -2221,7 +2206,7 @@ nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* • {buffer} Buffer handle, or 0 for current buffer • {name} Variable name -nvim_buf_delete({buffer}, {*opts}) *nvim_buf_delete()* +nvim_buf_delete({buffer}, {opts}) *nvim_buf_delete()* Deletes the buffer. See |:bwipeout| Attributes: ~ @@ -2263,8 +2248,8 @@ nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()* Gets a list of buffer-local |mapping| definitions. Parameters: ~ - • {mode} Mode short-name ("n", "i", "v", ...) • {buffer} Buffer handle, or 0 for current buffer + • {mode} Mode short-name ("n", "i", "v", ...) Return: ~ Array of |maparg()|-like dictionaries describing mappings. The @@ -2338,7 +2323,7 @@ nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* *nvim_buf_get_text()* nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, - {*opts}) + {opts}) Gets a range from the buffer. This differs from |nvim_buf_get_lines()| in that it allows retrieving only @@ -2403,7 +2388,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Line count, or 0 for unloaded buffer. |api-buffer| *nvim_buf_set_keymap()* -nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {*opts}) +nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts}) Sets a buffer-local |mapping| for the given mode. Parameters: ~ @@ -2440,7 +2425,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) • |nvim_buf_set_text()| *nvim_buf_set_mark()* -nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {*opts}) +nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts}) Sets a named mark in the given buffer, all marks are allowed file/uppercase, visual, last change, etc. See |mark-motions|. @@ -2581,7 +2566,7 @@ nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()* true if the extmark was found, else false *nvim_buf_get_extmark_by_id()* -nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {*opts}) +nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) Gets the position (0-indexed) of an |extmark|. Parameters: ~ @@ -2597,7 +2582,7 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {*opts}) 0-indexed (row, col) tuple or empty list () if extmark id was absent *nvim_buf_get_extmarks()* -nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts}) +nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) Gets |extmarks| in "traversal order" from a |charwise| region defined by buffer positions (inclusive, 0-indexed |api-indexing|). @@ -2657,7 +2642,7 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts}) List of [extmark_id, row, col] tuples in "traversal order". *nvim_buf_set_extmark()* -nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) +nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) Creates or updates an |extmark|. By default a new extmark is created when no id is passed in, but it is @@ -2703,7 +2688,6 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) • "right_align": display right aligned in the window. • "inline": display at the specified column, and shift the buffer text to the right as needed. - • virt_text_win_col : position the virtual text at a fixed window column (starting from the first text column of the screen line) instead of "virt_text_pos". @@ -2715,14 +2699,12 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) wrapped lines. • hl_mode : control how highlights are combined with the highlights of the text. Currently only affects virt_text - highlights, but might affect `hl_group` in - later versions. + highlights, but might affect `hl_group` in later versions. • "replace": only show the virt_text color. This is the default. • "combine": combine with background text color. • "blend": blend with background text color. Not supported for "inline" virt_text. - • virt_lines : virtual lines to add next to this mark This should be an array over lines, where each line in turn is an array over [text, highlight] tuples. In general, buffer @@ -2815,7 +2797,7 @@ nvim_get_namespaces() *nvim_get_namespaces()* dict that maps from names to namespace ids. *nvim_set_decoration_provider()* -nvim_set_decoration_provider({ns_id}, {*opts}) +nvim_set_decoration_provider({ns_id}, {opts}) Set or change decoration provider for a |namespace| This is a very general purpose interface for having Lua callbacks being @@ -3066,7 +3048,7 @@ nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()* This takes precedence over the 'winhighlight' option. Parameters: ~ - • {ns_id} the namespace to use + • {ns_id} the namespace to use nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* Sets a window-scoped (w:) variable @@ -3084,7 +3066,7 @@ nvim_win_set_width({window}, {width}) *nvim_win_set_width()* • {window} Window handle, or 0 for current window • {width} Width as a count of columns -nvim_win_text_height({window}, {*opts}) *nvim_win_text_height()* +nvim_win_text_height({window}, {opts}) *nvim_win_text_height()* Computes the number of screen lines occupied by a range of text in a given window. Works for off-screen text and takes folds into account. @@ -3120,9 +3102,9 @@ nvim_win_text_height({window}, {*opts}) *nvim_win_text_height()* ============================================================================== -Win_Config Functions *api-win_config* +Win_config Functions *api-win_config* -nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* +nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* Opens a new split window, or a floating window if `relative` is specified, or an external window (managed by the UI) if `external` is specified. @@ -3188,7 +3170,6 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* window. • "cursor" Cursor position in current window. • "mouse" Mouse position - • win: |window-ID| window to split, or relative window when creating a float (relative="win"). • anchor: Decides which corner of the float to place at @@ -3197,17 +3178,15 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* • "NE" northeast • "SW" southwest • "SE" southeast - • width: Window width (in character cells). Minimum of 1. • height: Window height (in character cells). Minimum of 1. • bufpos: Places float relative to buffer text (only when relative="win"). Takes a tuple of zero-indexed [line, - column]. `row` and `col` if given are - applied relative to this position, else they default to: + column]. `row` and `col` if given are applied relative to + this position, else they default to: • `row=1` and `col=0` if `anchor` is "NW" or "NE" • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus like a tooltip near the buffer text). - • row: Row position in units of "screen cell height", may be fractional. • col: Column position in units of "screen cell width", may @@ -3228,7 +3207,6 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* wildoptions+=pum) The default value for floats are 50. In general, values below 100 are recommended, unless there is a good reason to overshadow builtin elements. - • style: (optional) Configure the appearance of the window. Currently only supports one value: • "minimal" Nvim will display the window with many UI @@ -3241,14 +3219,13 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* empty. The end-of-buffer region is hidden by setting `eob` flag of 'fillchars' to a space char, and clearing the |hl-EndOfBuffer| region in 'winhighlight'. - • border: Style of (optional) window border. This can either be a string or an array. The string values are • "none": No border (default). • "single": A single line box. • "double": A double line box. - • "rounded": Like "single", but with rounded corners ("╭" - etc.). + • "rounded": Like "single", but with rounded corners + ("╭" etc.). • "solid": Adds padding by a single whitespace cell. • "shadow": A drop shadow effect by blending with the background. @@ -3256,19 +3233,26 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* any divisor of eight. The array will specify the eight chars building up the border in a clockwise fashion starting with the top-left corner. As an example, the - double box style could be specified as [ "╔", "═" ,"╗", - "║", "╝", "═", "╚", "║" ]. If the number of chars are - less than eight, they will be repeated. Thus an ASCII - border could be specified as [ "/", "-", "\\", "|" ], or - all chars the same as [ "x" ]. An empty string can be - used to turn off a specific border, for instance, [ "", - "", "", ">", "", "", "", "<" ] will only make vertical - borders but not horizontal ones. By default, - `FloatBorder` highlight is used, which links to - `WinSeparator` when not defined. It could also be - specified by character: [ ["+", "MyCorner"], ["x", - "MyBorder"] ]. - + double box style could be specified as: > + [ "╔", "═" ,"╗", "║", "╝", "═", "╚", "║" ]. +< + If the number of chars are less than eight, they will be + repeated. Thus an ASCII border could be specified as > + [ "/", "-", \"\\\\\", "|" ], +< + or all chars the same as > + [ "x" ]. +< + An empty string can be used to turn off a specific border, + for instance, > + [ "", "", "", ">", "", "", "", "<" ] +< + will only make vertical borders but not horizontal ones. + By default, `FloatBorder` highlight is used, which links + to `WinSeparator` when not defined. It could also be + specified by character: > + [ ["+", "MyCorner"], ["x", "MyBorder"] ]. +< • title: Title (optional) in window border, string or list. List should consist of `[text, highlight]` tuples. If string, the default highlight group is `FloatTitle`. @@ -3306,7 +3290,7 @@ nvim_win_get_config({window}) *nvim_win_get_config()* Return: ~ Map defining the window configuration, see |nvim_open_win()| -nvim_win_set_config({window}, {*config}) *nvim_win_set_config()* +nvim_win_set_config({window}, {config}) *nvim_win_set_config()* Configures window layout. Currently only for floating and external windows (including changing a split window to those layouts). @@ -3397,7 +3381,7 @@ nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()* ============================================================================== Autocmd Functions *api-autocmd* -nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()* +nvim_clear_autocmds({opts}) *nvim_clear_autocmds()* Clears all autocommands selected by {opts}. To delete autocmds see |nvim_del_autocmd()|. @@ -3407,25 +3391,21 @@ nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()* • event: "pat1" • event: { "pat1" } • event: { "pat1", "pat2", "pat3" } - • pattern: (string|table) • pattern or patterns to match exactly. • For example, if you have `*.py` as that pattern for the autocmd, you must pass `*.py` exactly to clear it. `test.py` will not match the pattern. - • defaults to clearing all patterns. • NOTE: Cannot be used with {buffer} - • buffer: (bufnr) • clear only |autocmd-buflocal| autocommands. • NOTE: Cannot be used with {pattern} - • group: (string|int) The augroup name or id. • NOTE: If not passed, will only delete autocmds not in any group. -nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* +nvim_create_augroup({name}, {opts}) *nvim_create_augroup()* Create or get an autocommand group |autocmd-groups|. To get an existing group id, do: >lua @@ -3446,9 +3426,10 @@ nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* See also: ~ • |autocmd-groups| -nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* - Creates an |autocommand| event handler, defined by `callback` (Lua function - or Vimscript function name string) or `command` (Ex command string). +nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* + Creates an |autocommand| event handler, defined by `callback` (Lua + function or Vimscript function name string) or `command` (Ex command + string). Example using Lua callback: >lua vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { @@ -3487,8 +3468,8 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* • callback (function|string) optional: Lua function (or Vimscript function name, if string) called when the event(s) is triggered. Lua callback can return a truthy - value (not `false` or `nil`) to delete the - autocommand. Receives a table argument with these keys: + value (not `false` or `nil`) to delete the autocommand. + Receives a table argument with these keys: • id: (number) autocommand id • event: (string) name of the triggered event |autocmd-events| @@ -3498,7 +3479,6 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* • file: (string) expanded value of |<afile>| • data: (any) arbitrary data passed from |nvim_exec_autocmds()| - • command (string) optional: Vim command to execute on event. Cannot be used with {callback} • once (boolean) optional: defaults to false. Run the @@ -3548,7 +3528,7 @@ nvim_del_autocmd({id}) *nvim_del_autocmd()* Parameters: ~ • {id} Integer Autocommand id returned by |nvim_create_autocmd()| -nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* +nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()* Execute all autocommands for {event} that match the corresponding {opts} |autocmd-execute|. @@ -3569,7 +3549,7 @@ nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* See also: ~ • |:doautocmd| -nvim_get_autocmds({*opts}) *nvim_get_autocmds()* +nvim_get_autocmds({opts}) *nvim_get_autocmds()* Get all autocommands that match the corresponding {opts}. These examples will get autocommands matching ALL the given criteria: >lua @@ -3683,13 +3663,12 @@ nvim_ui_pum_set_height({height}) *nvim_ui_pum_set_height()* • {height} Popupmenu height, must be greater than zero. nvim_ui_set_focus({gained}) *nvim_ui_set_focus()* - Tells the nvim server if focus was gained or lost by the GUI. + Tells the nvim server if focus was gained or lost by the GUI Attributes: ~ |RPC| only nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* - TODO: Documentation Attributes: ~ |RPC| only @@ -3698,7 +3677,6 @@ nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()* Tells Nvim when a terminal event has occurred The following terminal events are supported: - • "termresponse": The terminal sent an OSC or DCS response sequence to Nvim. The payload is the received response. Sets |v:termresponse| and fires |TermResponse|. @@ -3707,11 +3685,10 @@ nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()* |RPC| only Parameters: ~ - • {event} Event name - • {payload} Event payload + • {event} Event name + • {value} Event payload nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* - TODO: Documentation Attributes: ~ |RPC| only @@ -3731,4 +3708,5 @@ nvim_ui_try_resize_grid({grid}, {width}, {height}) • {width} The new requested width. • {height} The new requested height. + vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: |