diff options
Diffstat (limited to 'runtime/doc')
| -rw-r--r-- | runtime/doc/api.txt | 631 | ||||
| -rw-r--r-- | runtime/doc/autocmd.txt | 49 | ||||
| -rw-r--r-- | runtime/doc/change.txt | 6 | ||||
| -rw-r--r-- | runtime/doc/deprecated.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/dev_style.txt | 1159 | ||||
| -rw-r--r-- | runtime/doc/develop.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/diagnostic.txt | 225 | ||||
| -rw-r--r-- | runtime/doc/editing.txt | 50 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 482 | ||||
| -rw-r--r-- | runtime/doc/filetype.txt | 8 | ||||
| -rw-r--r-- | runtime/doc/helphelp.txt | 12 | ||||
| -rw-r--r-- | runtime/doc/intro.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/lsp.txt | 70 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 103 | ||||
| -rw-r--r-- | runtime/doc/mbyte.txt | 30 | ||||
| -rw-r--r-- | runtime/doc/nvim_terminal_emulator.txt | 6 | ||||
| -rw-r--r-- | runtime/doc/options.txt | 17 | ||||
| -rw-r--r-- | runtime/doc/pattern.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/pi_health.txt | 153 | ||||
| -rw-r--r-- | runtime/doc/print.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/starting.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/treesitter.txt | 8 | ||||
| -rw-r--r-- | runtime/doc/usr_22.txt | 24 | ||||
| -rw-r--r-- | runtime/doc/usr_41.txt | 6 | ||||
| -rw-r--r-- | runtime/doc/various.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 11 |
26 files changed, 2559 insertions, 509 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index df345e4981..1573bec7ac 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -130,7 +130,9 @@ end of a range, -1 denotes the last line/column. Exception: the following API functions use "mark-like" indexing (1-based lines, 0-based columns): + |nvim_get_mark()| |nvim_buf_get_mark()| + |nvim_buf_set_mark()| |nvim_win_get_cursor()| |nvim_win_set_cursor()| @@ -529,6 +531,20 @@ nvim__get_hl_defs({ns_id}) *nvim__get_hl_defs()* nvim__get_lib_dir() *nvim__get_lib_dir()* TODO: Documentation +nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* + Find files in runtime directories + + Attributes: ~ + {fast} + + Parameters: ~ + {pat} pattern of files to search for + {all} whether to return all matches or only the first + {options} is_lua: only search lua subdirs + + Return: ~ + list of absolute paths to the found files + nvim__id({obj}) *nvim__id()* Returns object given as argument. @@ -580,6 +596,9 @@ nvim__id_float({flt}) *nvim__id_float()* nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* TODO: Documentation +nvim__runtime_inspect() *nvim__runtime_inspect()* + TODO: Documentation + nvim__screenshot({path}) *nvim__screenshot()* TODO: Documentation @@ -706,7 +725,7 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* buf_open_scratch nvim_create_namespace({name}) *nvim_create_namespace()* - Creates a new namespace, or gets an existing one. + Creates a new *namespace* or gets an existing one. Namespaces are used for buffer highlights and virtual text, see |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|. @@ -735,6 +754,23 @@ nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* See also: ~ |nvim_set_keymap()| +nvim_del_mark({name}) *nvim_del_mark()* + Deletes a uppercase/file named mark. See |mark-motions|. + + Note: + fails with error if a lowercase or buffer local named mark + is used. + + Parameters: ~ + {name} Mark name + + Return: ~ + true if the mark was deleted, else false. + + See also: ~ + |nvim_buf_del_mark()| + |nvim_get_mark()| + nvim_del_var({name}) *nvim_del_var()* Removes a global (g:) variable. @@ -783,6 +819,39 @@ nvim_eval({expr}) *nvim_eval()* Return: ~ Evaluation result or expanded object +nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* + Evaluates statusline string. + + Attributes: ~ + {fast} + + Parameters: ~ + {str} Statusline string (see 'statusline'). + {opts} Optional parameters. + • winid: (number) |window-ID| of the window to use + as context for statusline. + • maxwidth: (number) Maximum width of statusline. + • fillchar: (string) Character to fill blank + spaces in the statusline (see 'fillchars'). + • highlights: (boolean) Return highlight + information. + • use_tabline: (boolean) Evaluate tabline instead + of statusline. When |TRUE|, {winid} is ignored. + + Return: ~ + Dictionary containing statusline information, with these + keys: + • str: (string) Characters that will be displayed on the + statusline. + • width: (number) Display width of the statusline. + • highlights: Array containing highlight information of + the statusline. Only included when the "highlights" key + in {opts} is |TRUE|. Each element of the array is a + |Dictionary| with these keys: + • start: (number) Byte index (0-based) of first + character that uses the highlight. + • group: (string) Name of highlight group. + nvim_exec({src}, {output}) *nvim_exec()* Executes Vimscript (multiline block of Ex-commands), like anonymous |:source|. @@ -828,7 +897,7 @@ nvim_feedkeys({keys}, {mode}, {escape_csi}) *nvim_feedkeys()* On execution error: does not fail, but updates v:errmsg. To input sequences like <C-o> use |nvim_replace_termcodes()| - (typically with escape_csi=true) to replace the keycodes. Then + (typically with escape_csi=true) to replace |keycodes|, then pass the result to nvim_feedkeys(). Example: > @@ -866,32 +935,33 @@ nvim_get_api_info() *nvim_get_api_info()* {fast} nvim_get_chan_info({chan}) *nvim_get_chan_info()* - Get information about a channel. + Gets information about a channel. Return: ~ Dictionary describing a channel, with these keys: - • "stream" the stream underlying the channel + • "id" Channel id. + • "argv" (optional) Job arguments list. + • "stream" Stream underlying the channel. • "stdio" stdin and stdout of this Nvim instance • "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" a |terminal| instance interprets ASCII - sequences - • "rpc" |RPC| communication on the channel is active - - • "pty" Name of pseudoterminal, if one is used (optional). - On a POSIX system, this will be a device path like - /dev/pts/1. Even if the name is unknown, the key will - still be present to indicate a pty is used. This is - currently the case when using winpty on windows. - • "buffer" buffer with connected |terminal| instance - (optional) - • "client" information about the client on the other end - of the RPC channel, if it has added it using - |nvim_set_client_info()|. (optional) + • "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 winpty on Windows). + • "buffer" (optional) Buffer with connected |terminal| + instance. + • "client" (optional) Info about the peer (client on the + other end of the RPC channel), if provided by it via + |nvim_set_client_info()|. nvim_get_color_by_name({name}) *nvim_get_color_by_name()* Returns the 24-bit RGB value of a |nvim_get_color_map()| color @@ -917,7 +987,7 @@ nvim_get_color_map() *nvim_get_color_map()* Return: ~ Map of color names and RGB values. -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 @@ -930,7 +1000,7 @@ nvim_get_commands({opts}) *nvim_get_commands()* Return: ~ Map of maps describing commands. -nvim_get_context({opts}) *nvim_get_context()* +nvim_get_context({*opts}) *nvim_get_context()* Gets a map of the current editor state. Parameters: ~ @@ -1008,6 +1078,27 @@ nvim_get_keymap({mode}) *nvim_get_keymap()* Array of maparg()-like dictionaries describing mappings. The "buffer" key is always zero. +nvim_get_mark({name}) *nvim_get_mark()* + Return a tuple (row, col, buffer, buffername) representing the + position of the uppercase/file named mark. See |mark-motions|. + + Marks are (1,0)-indexed. |api-indexing| + + Note: + fails with error if a lowercase or buffer local named mark + is used. + + Parameters: ~ + {name} Mark name + + Return: ~ + 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if + the mark is not set. + + See also: ~ + |nvim_buf_set_mark()| + |nvim_del_mark()| + nvim_get_mode() *nvim_get_mode()* Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for input. @@ -1079,10 +1170,6 @@ nvim_get_runtime_file({name}, {all}) *nvim_get_runtime_file()* It is not an error to not find any files. An empty array is returned then. - To find a directory, `name` must end with a forward slash, - like "rplugin/python/". Without the slash it would instead - look for an ordinary file called "rplugin/python". - Attributes: ~ {fast} @@ -1251,7 +1338,7 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* For instance, for a floating display, first create an empty buffer using |nvim_create_buf()|, then display it using |nvim_open_win()|, and then call this function. Then - |nvim_chan_send()| cal be called immediately to process + |nvim_chan_send()| can be called immediately to process sequences in a virtual terminal having the intended size. Parameters: ~ @@ -1261,156 +1348,6 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* Return: ~ Channel id, or 0 on error -nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* - Open a new window. - - Currently this is used to open floating and external windows. - Floats are windows that are drawn above the split layout, at - some anchor position in some other window. Floats can be drawn - internally or by external GUI with the |ui-multigrid| - extension. External windows are only supported with multigrid - GUIs, and are displayed as separate top-level windows. - - For a general overview of floats, see |api-floatwin|. - - Exactly one of `external` and `relative` must be specified. - The `width` and `height` of the new window must be specified. - - With relative=editor (row=0,col=0) refers to the top-left - corner of the screen-grid and (row=Lines-1,col=Columns-1) - refers to the bottom-right corner. Fractional values are - allowed, but the builtin implementation (used by non-multigrid - UIs) will always round down to nearest integer. - - Out-of-bounds values, and configurations that make the float - not fit inside the main editor, are allowed. The builtin - implementation truncates values so floats are fully within the - main screen grid. External GUIs could let floats hover outside - of the main window like a tooltip, but this should not be used - to specify arbitrary WM screen positions. - - Example (Lua): window-relative float > - vim.api.nvim_open_win(0, false, - {relative='win', row=3, col=3, width=12, height=3}) -< - - Example (Lua): buffer-relative float (travels as buffer is - scrolled) > - vim.api.nvim_open_win(0, false, - {relative='win', width=12, height=3, bufpos={100,10}}) -< - - Attributes: ~ - not allowed when |textlock| is active - - Parameters: ~ - {buffer} Buffer to display, or 0 for current buffer - {enter} Enter the window (make it the current window) - {config} Map defining the window configuration. Keys: - • `relative`: Sets the window layout to "floating", placed - at (row,col) coordinates relative to: - • "editor" The global editor grid - • "win" Window given by the `win` field, or - current window. - • "cursor" Cursor position in current window. - - • `win` : |window-ID| for relative="win". - • `anchor`: Decides which corner of the float to place - at (row,col): - • "NW" northwest (default) - • "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 `row=1` and - `col=0` (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 be fractional. - • `focusable` : Enable focus by user actions - (wincmds, mouse events). Defaults to true. - Non-focusable windows can be entered by - |nvim_set_current_win()|. - • `external` : GUI should display the window as - an external top-level window. Currently - accepts no other positioning configuration - together with this. - • `zindex`: Stacking order. floats with higher`zindex`go on top on floats with lower indices. Must - be larger than zero. The following screen - elements have hard-coded z-indices: - • 100: insert completion popupmenu - • 200: message scrollback - • 250: cmdline completion popupmenu (when - 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`: Configure the appearance of the window. - Currently only takes one non-empty value: - • "minimal" Nvim will display the window with - many UI options disabled. This is useful - when displaying a temporary float where the - text should not be edited. Disables - 'number', 'relativenumber', 'cursorline', - 'cursorcolumn', 'foldcolumn', 'spell' and - 'list' options. 'signcolumn' is changed to - `auto` and 'colorcolumn' is cleared. The - end-of-buffer region is hidden by setting - `eob` flag of 'fillchars' to a space char, - and clearing the |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.). - • "solid": Adds padding by a single whitespace - cell. - • "shadow": A drop shadow effect by blending - with the background. - • If it is an array, it should have a length - of eight or any divisor of eight. The array - will specifify 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 `VertSplit` when not defined. - It could also be specified by character: [ - {"+", "MyCorner"}, {"x", "MyBorder"} ]. - - • `noautocmd` : If true then no buffer-related - autocommand events such as |BufEnter|, - |BufLeave| or |BufWinEnter| may fire from - calling this function. - - Return: ~ - Window handle, or 0 on error - nvim_out_write({str}) *nvim_out_write()* Writes a message to the Vim output buffer. Does not append "\n", the message is buffered (won't display) until a linefeed @@ -1779,7 +1716,7 @@ nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()* default cterm attributes are same as attributes of gui color -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()|. @@ -1940,7 +1877,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* callbacks. {opts} Optional parameters. • on_lines: Lua callback invoked on change. - Return`true`to detach. Args: + Return `true` to detach. Args: • the string "lines" • buffer handle • b:changedtick @@ -1956,7 +1893,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • on_bytes: lua callback invoked on change. This callback receives more granular information about the change compared to - on_lines. Return`true`to detach. Args: + on_lines. Return `true` to detach. Args: • the string "bytes" • buffer handle • b:changedtick @@ -2063,6 +2000,24 @@ nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* See also: ~ |nvim_del_keymap()| +nvim_buf_del_mark({buffer}, {name}) *nvim_buf_del_mark()* + Deletes a named mark in the buffer. See |mark-motions|. + + Note: + only deletes marks set in the buffer, if the mark is not + set in the buffer it will return false. + + Parameters: ~ + {buffer} Buffer to set the mark on + {name} Mark name + + Return: ~ + true if the mark was deleted, else false. + + See also: ~ + |nvim_buf_set_mark()| + |nvim_del_mark()| + nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* Removes a buffer-scoped (b:) variable @@ -2107,7 +2062,7 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* Return: ~ `b:changedtick` value. -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: ~ @@ -2119,7 +2074,7 @@ nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()* *nvim_buf_get_extmark_by_id()* nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) - Gets the position (0-indexed) of an extmark {id}. + Gets the position (0-indexed) of an extmark. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -2170,12 +2125,12 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace id from |nvim_create_namespace()| - {start} Start of range, given as 0-indexed (row, col) or - valid extmark id (whose position defines the - bound) - {end} End of range (inclusive), given as 0-indexed - (row, col) or valid extmark id (whose position - defines the bound) + {start} Start of range: a 0-indexed (row, col) or valid + extmark id (whose position defines the bound). + |api-indexing| + {end} End of range (inclusive): a 0-indexed (row, col) + or valid extmark id (whose position defines the + bound). |api-indexing| {opts} Optional parameters. Keys: • limit: Maximum number of marks to return • details Whether to include the details dict @@ -2217,8 +2172,8 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) Array of lines, or empty array for unloaded buffer. nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* - Return a tuple (row,col) representing the position of the - named mark. + Returns a tuple (row,col) representing the position of the + named mark. See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| @@ -2227,7 +2182,12 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* {name} Mark name Return: ~ - (row, col) tuple + (row, col) tuple, (0, 0) if the mark is not set, or is an + uppercase/file mark set in another buffer. + + See also: ~ + |nvim_buf_set_mark()| + |nvim_buf_del_mark()| nvim_buf_get_name({buffer}) *nvim_buf_get_name()* Gets the full file name for the buffer @@ -2310,7 +2270,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()* Line count, or 0 for unloaded buffer. |api-buffer| *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. To create a new extmark, pass id=0. The extmark id will be @@ -2328,8 +2288,10 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {ns_id} Namespace id from |nvim_create_namespace()| - {line} Line where to place the mark, 0-based - {col} Column where to place the mark, 0-based + {line} Line where to place the mark, 0-based. + |api-indexing| + {col} Column where to place the mark, 0-based. + |api-indexing| {opts} Optional parameters. • id : id of the extmark to edit. • end_line : ending line of the mark, 0-based @@ -2338,6 +2300,10 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) exclusive. • hl_group : name of the highlight group used to highlight this mark. + • hl_eol : when true, for a multiline highlight + covering the EOL of a line, continue the + highlight for the rest of the screen line + (just like for diff and cursorline highlight). • virt_text : virtual text to link to this mark. A list of [text, highlight] tuples, each representing a text chunk with specified @@ -2366,17 +2332,35 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) • 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. + 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. - • hl_eol : when true, for a multiline highlight - covering the EOL of a line, continue the - highlight for the rest of the screen line - (just like for diff and cursorline highlight). + • 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 and + window options do not affect the display of + the text. In particular 'wrap' and 'linebreak' + options do not take effect, so the number of + extra screen lines will always match the size + of the array. However the 'tabstop' buffer + option is still used for hard tabs. By default + lines are placed below the buffer line + containing the mark. • Note: currently virtual lines are limited to + one block per buffer. Thus setting a new mark + disables any previous `virt_lines` decoration. + However plugins should not rely on this + behaviour, as this limitation is planned to be + removed. + • virt_lines_above: place virtual lines above + instead. + • virt_lines_leftcol: Place extmarks in the + leftmost column of the window, bypassing sign + and number columns. • ephemeral : for use with |nvim_set_decoration_provider| callbacks. The mark will only be used for the current redraw @@ -2399,7 +2383,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts}) Id of the created/updated extmark *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: ~ @@ -2435,6 +2419,29 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) error. {replacement} Array of lines to use as replacement + *nvim_buf_set_mark()* +nvim_buf_set_mark({buffer}, {name}, {line}, {col}) + Sets a named mark in the given buffer, all marks are allowed + file/uppercase, visual, last change, etc. See |mark-motions|. + + Marks are (1,0)-indexed. |api-indexing| + + Note: + Passing 0 as line deletes the mark + + Parameters: ~ + {buffer} Buffer to set the mark on + {name} Mark name + {line} Line number + {col} Column/row number + + Return: ~ + true if the mark was set, else false. + + See also: ~ + |nvim_buf_del_mark()| + |nvim_buf_get_mark()| + nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()* Sets the full file name for a buffer @@ -2534,20 +2541,6 @@ nvim_win_get_buf({window}) *nvim_win_get_buf()* Return: ~ Buffer handle -nvim_win_get_config({window}) *nvim_win_get_config()* - Gets window configuration. - - The returned value may be given to |nvim_open_win()|. - - `relative` is empty for normal windows. - - Parameters: ~ - {window} Window handle, or 0 for current window - - Return: ~ - Map defining the window configuration, see - |nvim_open_win()| - nvim_win_get_cursor({window}) *nvim_win_get_cursor()* Gets the (1,0)-indexed cursor position in the window. |api-indexing| @@ -2658,23 +2651,6 @@ nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* {window} Window handle, or 0 for current window {buffer} Buffer handle -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). - - When reconfiguring a floating window, absent option keys will - not be changed. `row` / `col` and `relative` must be - reconfigured together. - - Parameters: ~ - {window} Window handle, or 0 for current window - {config} Map defining the window configuration, see - |nvim_open_win()| - - See also: ~ - |nvim_open_win()| - nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* Sets the (1,0)-indexed cursor position in the window. |api-indexing| @@ -2718,6 +2694,195 @@ nvim_win_set_width({window}, {width}) *nvim_win_set_width()* ============================================================================== +Win_Config Functions *api-win_config* + +nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* + Open a new window. + + Currently this is used to open floating and external windows. + Floats are windows that are drawn above the split layout, at + some anchor position in some other window. Floats can be drawn + internally or by external GUI with the |ui-multigrid| + extension. External windows are only supported with multigrid + GUIs, and are displayed as separate top-level windows. + + For a general overview of floats, see |api-floatwin|. + + Exactly one of `external` and `relative` must be specified. + The `width` and `height` of the new window must be specified. + + With relative=editor (row=0,col=0) refers to the top-left + corner of the screen-grid and (row=Lines-1,col=Columns-1) + refers to the bottom-right corner. Fractional values are + allowed, but the builtin implementation (used by non-multigrid + UIs) will always round down to nearest integer. + + Out-of-bounds values, and configurations that make the float + not fit inside the main editor, are allowed. The builtin + implementation truncates values so floats are fully within the + main screen grid. External GUIs could let floats hover outside + of the main window like a tooltip, but this should not be used + to specify arbitrary WM screen positions. + + Example (Lua): window-relative float > + vim.api.nvim_open_win(0, false, + {relative='win', row=3, col=3, width=12, height=3}) +< + + Example (Lua): buffer-relative float (travels as buffer is + scrolled) > + vim.api.nvim_open_win(0, false, + {relative='win', width=12, height=3, bufpos={100,10}}) +< + + Attributes: ~ + not allowed when |textlock| is active + + Parameters: ~ + {buffer} Buffer to display, or 0 for current buffer + {enter} Enter the window (make it the current window) + {config} Map defining the window configuration. Keys: + • relative: Sets the window layout to + "floating", placed at (row,col) coordinates + relative to: + • "editor" The global editor grid + • "win" Window given by the `win` field, or + current window. + • "cursor" Cursor position in current window. + + • win: |window-ID| for relative="win". + • anchor: Decides which corner of the float to + place at (row,col): + • "NW" northwest (default) + • "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: + • `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 be fractional. + • focusable: Enable focus by user actions + (wincmds, mouse events). Defaults to true. + Non-focusable windows can be entered by + |nvim_set_current_win()|. + • external: GUI should display the window as an + external top-level window. Currently accepts + no other positioning configuration together + with this. + • zindex: Stacking order. floats with higher `zindex` go on top on floats with lower indices. Must + be larger than zero. The following screen + elements have hard-coded z-indices: + • 100: insert completion popupmenu + • 200: message scrollback + • 250: cmdline completion popupmenu (when + 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: Configure the appearance of the window. + Currently only takes one non-empty value: + • "minimal" Nvim will display the window with + many UI options disabled. This is useful + when displaying a temporary float where the + text should not be edited. Disables + 'number', 'relativenumber', 'cursorline', + 'cursorcolumn', 'foldcolumn', 'spell' and + 'list' options. 'signcolumn' is changed to + `auto` and 'colorcolumn' is cleared. The + end-of-buffer region is hidden by setting + `eob` flag of 'fillchars' to a space char, + and clearing the |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.). + • "solid": Adds padding by a single whitespace + cell. + • "shadow": A drop shadow effect by blending + with the background. + • If it is an array, it should have a length + of eight or any divisor of eight. The array + will specifify 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 `VertSplit` when not defined. + It could also be specified by character: [ + {"+", "MyCorner"}, {"x", "MyBorder"} ]. + + • noautocmd: If true then no buffer-related + autocommand events such as |BufEnter|, + |BufLeave| or |BufWinEnter| may fire from + calling this function. + + Return: ~ + Window handle, or 0 on error + +nvim_win_get_config({window}) *nvim_win_get_config()* + Gets window configuration. + + The returned value may be given to |nvim_open_win()|. + + `relative` is empty for normal windows. + + Parameters: ~ + {window} Window handle, or 0 for current window + + Return: ~ + Map defining the window configuration, see + |nvim_open_win()| + +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). + + When reconfiguring a floating window, absent option keys will + not be changed. `row` / `col` and `relative` must be + reconfigured together. + + Parameters: ~ + {window} Window handle, or 0 for current window + {config} Map defining the window configuration, see + |nvim_open_win()| + + See also: ~ + |nvim_open_win()| + + +============================================================================== Tabpage Functions *api-tabpage* nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 7a53f17a78..6c41dd3b10 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -519,11 +519,17 @@ DiffUpdated After diffs have been updated. Depending on change or when doing |:diffupdate|. *DirChanged* DirChanged After the |current-directory| was changed. + The pattern can be: + "window" to trigger on `:lcd` + "tabpage" to trigger on `:tcd` + "global" to trigger on `:cd` + "auto" to trigger on 'autochdir'. Sets these |v:event| keys: cwd: current working directory scope: "global", "tab", "window" changed_window: v:true if we fired the event switching window (or tab) + <afile> is set to the new directory name. Non-recursive (event cannot trigger itself). *FileAppendCmd* FileAppendCmd Before appending to a file. Should do the @@ -630,7 +636,7 @@ FilterReadPre Before reading a file from a filter command. *FilterWritePost* FilterWritePost After writing a file for a filter command or making a diff with an external diff (see - DiffUpdated for internal diff). + |DiffUpdated| for internal diff). Vim checks the pattern against the name of the current buffer as with FilterWritePre. Not triggered when 'shelltemp' is off. @@ -683,23 +689,6 @@ InsertCharPre When a character is typed in Insert mode, Cannot change the text. |textlock| Not triggered when 'paste' is set. - *TextYankPost* -TextYankPost Just after a |yank| or |deleting| command, but not - if the black hole register |quote_| is used nor - for |setreg()|. Pattern must be *. - Sets these |v:event| keys: - inclusive - operator - regcontents - regname - regtype - visual - The `inclusive` flag combined with the |'[| - and |']| marks can be used to calculate the - precise region of the operation. - - Non-recursive (event cannot trigger itself). - Cannot change the text. |textlock| *InsertEnter* InsertEnter Just before starting Insert mode. Also for Replace mode and Virtual Replace mode. The @@ -948,6 +937,23 @@ TextChangedP After a change was made to the text in the current buffer in Insert mode, only when the popup menu is visible. Otherwise the same as TextChanged. + *TextYankPost* +TextYankPost Just after a |yank| or |deleting| command, but not + if the black hole register |quote_| is used nor + for |setreg()|. Pattern must be *. + Sets these |v:event| keys: + inclusive + operator + regcontents + regname + regtype + visual + The `inclusive` flag combined with the |'[| + and |']| marks can be used to calculate the + precise region of the operation. + + Non-recursive (event cannot trigger itself). + Cannot change the text. |textlock| *User* User Not executed automatically. Use |:doautocmd| to trigger this, typically for "custom events" @@ -1232,6 +1238,13 @@ Example: > This prevents having the autocommands defined twice (e.g., after sourcing the vimrc file again). + *FileExplorer* +There is one group that is recognized by Vim: FileExplorer. If this group +exists Vim assumes that editing a directory is possible and will trigger a +plugin that lists the files in that directory. This is used by the |netrw| +plugin. This allows you to do: > + browse edit + ============================================================================== 9. Executing autocommands *autocmd-execute* diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index 2b799e3e27..ffdd8427f9 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -1129,9 +1129,6 @@ a register, a paste on a visual selected area will paste that single line on each of the selected lines (thus replacing the blockwise selected region by a block of the pasted line). -Use |zP|/|zp| to paste a blockwise yanked register without appending trailing -spaces. - *blockwise-register* If you use a blockwise Visual mode command to get the text into the register, the block of text will be inserted before ("P") or after ("p") the cursor @@ -1142,6 +1139,9 @@ this happen. However, if the width of the block is not a multiple of a <Tab> width and the text after the inserted block contains <Tab>s, that text may be misaligned. +Use |zP|/|zp| to paste a blockwise yanked register without appending trailing +spaces. + Note that after a charwise yank command, Vim leaves the cursor on the first yanked character that is closest to the start of the buffer. This means that "yl" doesn't move the cursor, but "yh" moves the cursor one character left. diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index a0c291964e..a7ce4135af 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -75,7 +75,9 @@ For each of the functions below, use the corresponding function in *vim.lsp.diagnostic.get_prev()* *vim.lsp.diagnostic.get_prev_pos()* *vim.lsp.diagnostic.get_virtual_text_chunks_for_line()* - Use |vim.diagnostic.get_virt_text_chunks()| instead. + No replacement. Use options provided by + |vim.diagnostic.config()| to customize + virtual text. *vim.lsp.diagnostic.goto_next()* *vim.lsp.diagnostic.goto_prev()* *vim.lsp.diagnostic.redraw()* Use |vim.diagnostic.show()| instead. diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt new file mode 100644 index 0000000000..82f279e781 --- /dev/null +++ b/runtime/doc/dev_style.txt @@ -0,0 +1,1159 @@ +*dev_style.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Nvim style guide *dev-style* + +This is style guide for developers working on Nvim's source code. + +License: CC-By 3.0 http://creativecommons.org/licenses/by/3.0/ + + Type |gO| to see the table of contents. + +============================================================================== +Background + +One way in which we keep the code base manageable is by enforcing consistency. +It is very important that any programmer be able to look at another's code and +quickly understand it. + +Maintaining a uniform style and following conventions means that we can more +easily use "pattern-matching" to infer what various symbols are and what +invariants are true about them. Creating common, required idioms and patterns +makes code much easier to understand. + +In some cases there might be good arguments for changing certain style rules, +but we nonetheless keep things as they are in order to preserve consistency. + + +============================================================================== +Header Files *dev-style-header* + + +The #define Guard ~ + +All header files should have `#define` guards to prevent multiple inclusion. +The format of the symbol name should be `NVIM_<DIRECTORY>_<FILE>_H`. + + In foo/bar.h: +> + #ifndef NVIM_FOO_BAR_H + #define NVIM_FOO_BAR_H + + ... + + #endif // NVIM_FOO_BAR_H +< + + +Names and Order of Includes ~ + +Use standard order for readability and to avoid hidden dependencies: C +library, other libraries' `.h`, your project's `.h`. + + In foo.c order your includes as follows: + + 1. C system files. + 2. Other libraries' `.h` files. + 3. Your project's `.h` files. + + Exception: sometimes, system-specific code needs conditional includes. + Such code can put conditional includes after other includes. Of course, + keep your system-specific code small and localized. + + +Constants ~ + +Do not use macros to define constants in headers. + +Macro constants in header files cannot be used by unit tests. + +However, you are allowed to define a macro that holds the same value as a +non-enum constant (defined in the same header) if the value of the constant +represents the size of an array. + + +============================================================================== +Scoping *dev-style-scope* + +Local Variables ~ + +Place a function's variables in the narrowest scope possible, and initialize +variables in the declaration. + +C99 allows you to declare variables anywhere in a function. Declare them in as +local a scope as possible, and as close to the first use as possible. This +makes it easier for the reader to find the declaration and see what type the +variable is and what it was initialized to. In particular, initialization +should be used instead of declaration and assignment, e.g. > + + int i; + i = f(); // BAD: initialization separate from declaration. + + int j = g(); // GOOD: declaration has initialization. + + +============================================================================== +Nvim-Specific Magic + +clint ~ + +Use `clint.py` to detect style errors. + +`src/clint.py` is a Python script that reads a source file and identifies +style errors. It is not perfect, and has both false positives and false +negatives, but it is still a valuable tool. False positives can be ignored by +putting `// NOLINT` at the end of the line. + +uncrustify ~ + +src/uncrustify.cfg is the authority for expected code formatting, for cases +not covered by clint.py. We remove checks in clint.py if they are covered by +uncrustify rules. + +============================================================================== +Other C Features *dev-style-features* + + +Variable-Length Arrays and alloca() ~ + +We do not allow variable-length arrays or `alloca()`. + +Variable-length arrays can cause hard to detect stack overflows. + + +Postincrement and Postdecrement ~ + +Use postfix form (`i++`) in statements. > + + for (int i = 0; i < 3; i++) { } + int j = ++i; // OK: ++i is used as an expression. + + for (int i = 0; i < 3; ++i) { } + ++i; // BAD: ++i is used as a statement. + + +Use of const ~ + +Use `const` pointers whenever possible. Avoid `const` on non-pointer parameter definitions. + + Where to put the const ~ + + Some people favor the form `int const *foo` to `const int *foo` . They + argue that this is more readable because it's more consistent: it keeps + the rule that `const` always follows the object it's describing. However, + this consistency argument doesn't apply in codebases with few + deeply-nested pointer expressions since most `const` expressions have only + one `const`, and it applies to the underlying value. In such cases, there's + no consistency to maintain. Putting the `const` first is arguably more + readable, since it follows English in putting the "adjective" (`const`) + before the "noun" (`int`). + + That said, while we encourage putting `const` first, we do not require it. + But be consistent with the code around you! > + + void foo(const char *p, int i); + } + + int foo(const int a, const bool b) { + } + + int foo(int *const p) { + } + + +Integer Types ~ + +Of the built-in integer types only use `char`, `int`, `uint8_t`, `int8_t`, +`uint16_t`, `int16_t`, `uint32_t`, `int32_t`, `uint64_t`, `int64_t`, +`uintmax_t`, `intmax_t`, `size_t`, `ssize_t`, `uintptr_t`, `intptr_t`, and +`ptrdiff_t`. + +Use `int` for error codes and local, trivial variables only. + +Use care when converting integer types. Integer conversions and promotions can +cause non-intuitive behavior. Note that the signedness of `char` is +implementation defined. + +Public facing types must have fixed width (`uint8_t`, etc.) + +There are no convenient `printf` format placeholders for fixed width types. +Cast to `uintmax_t` or `intmax_t` if you have to format fixed width integers. + +Type unsigned signed +`char` `%hhu` `%hhd` +`int` n/a `%d` +`(u)intmax_t` `%ju` `%jd` +`(s)size_t` `%zu` `%zd` +`ptrdiff_t` `%tu` `%td` + + +Booleans ~ + +Use `bool` to represent boolean values. > + + int loaded = 1; // BAD: loaded should have type bool. + + +Variable declarations ~ + +Declare only one variable per line. > + + int i, j = 1 + + +Conditions ~ + +Don't use "yoda-conditions". Use at most one assignment per condition. > + + if (1 == x) { + + if (x == 1) { //use this order + + if ((x = f()) && (y = g())) { + + +Function declarations ~ + +Every function must not have a separate declaration. + +Function declarations are created by the gendeclarations.lua script. > + + static void f(void); + + static void f(void) + { + ... + } + + +General translation unit layout ~ + +The definitions of public functions precede the definitions of static +functions. > + + <HEADER> + + <PUBLIC FUNCTION DEFINITIONS> + + <STATIC FUNCTION DEFINITIONS> + + +Integration with declarations generator ~ + +Every C file must contain #include of the generated header file, guarded by +#ifdef INCLUDE_GENERATED_DECLARATIONS. + +Include must go after other #includes and typedefs in .c files and after +everything else in header files. It is allowed to omit #include in a .c file +if .c file does not contain any static functions. + +Included file name consists of the .c file name without extension, preceded by +the directory name relative to src/nvim. Name of the file containing static +functions declarations ends with `.c.generated.h`, `*.h.generated.h` files +contain only non-static function declarations. > + + // src/nvim/foo.c file + #include <stddef.h> + + typedef int FooType; + + #ifdef INCLUDE_GENERATED_DECLARATIONS + # include "foo.c.generated.h" + #endif + + … + + + // src/nvim/foo.h file + #ifndef NVIM_FOO_H + #define NVIM_FOO_H + + … + + #ifdef INCLUDE_GENERATED_DECLARATIONS + # include "foo.h.generated.h" + #endif + #endif // NVIM_FOO_H + + +64-bit Portability ~ + +Code should be 64-bit and 32-bit friendly. Bear in mind problems of printing, +comparisons, and structure alignment. + +- Remember that `sizeof(void *)` != `sizeof(int)`. Use `intptr_t` if you want + a pointer-sized integer. + +- You may need to be careful with structure alignments, particularly for + structures being stored on disk. Any class/structure with a + `int64_t`/`uint64_t` member will by default end up being 8-byte aligned on a + 64-bit system. If you have such structures being shared on disk between + 32-bit and 64-bit code, you will need to ensure that they are packed the + same on both architectures. Most compilers offer a way to alter structure + alignment. For gcc, you can use `__attribute__((packed))`. MSVC offers + `#pragma pack()` and `__declspec(align())`. + +- Use the `LL` or `ULL` suffixes as needed to create 64-bit constants. For + example: > + + int64_t my_value = 0x123456789LL; + uint64_t my_mask = 3ULL << 48; + + +sizeof ~ + +Prefer `sizeof(varname)` to `sizeof(type)`. + +Use `sizeof(varname)` when you take the size of a particular variable. +`sizeof(varname)` will update appropriately if someone changes the variable +type either now or later. You may use `sizeof(type)` for code unrelated to any +particular variable, such as code that manages an external or internal data +format where a variable of an appropriate C type is not convenient. > + + Struct data; + memset(&data, 0, sizeof(data)); + + memset(&data, 0, sizeof(Struct)); + + if (raw_size < sizeof(int)) { + fprintf(stderr, "compressed record not big enough for count: %ju", raw_size); + return false; + } + + +============================================================================== +Naming *dev-style-naming* + +The most important consistency rules are those that govern naming. The style +of a name immediately informs us what sort of thing the named entity is: a +type, a variable, a function, a constant, a macro, etc., without requiring us +to search for the declaration of that entity. The pattern-matching engine in +our brains relies a great deal on these naming rules. + +Naming rules are pretty arbitrary, but we feel that consistency is more +important than individual preferences in this area, so regardless of whether +you find them sensible or not, the rules are the rules. + + +General Naming Rules ~ + +Function names, variable names, and filenames should be descriptive; eschew +abbreviation. + +Give as descriptive a name as possible, within reason. Do not worry about +saving horizontal space as it is far more important to make your code +immediately understandable by a new reader. Do not use abbreviations that are +ambiguous or unfamiliar to readers outside your project, and do not abbreviate +by deleting letters within a word. > + + int price_count_reader; // No abbreviation. + int num_errors; // "num" is a widespread convention. + int num_dns_connections; // Most people know what "DNS" stands for. + + int n; // Meaningless. + int nerr; // Ambiguous abbreviation. + int n_comp_conns; // Ambiguous abbreviation. + int wgc_connections; // Only your group knows what this stands for. + int pc_reader; // Lots of things can be abbreviated "pc". + int cstmr_id; // Deletes internal letters. + + +File Names ~ + +Filenames should be all lowercase and can include underscores (`_`). + +Use underscores to separate words. Examples of acceptable file names: > + + my_useful_file.c + getline_fix.c // OK: getline refers to the glibc function. + +C files should end in `.c` and header files should end in `.h`. + +Do not use filenames that already exist in `/usr/include`, such as `db.h`. + +In general, make your filenames very specific. For example, use +`http_server_logs.h` rather than `logs.h`. + + +Type Names ~ + +Typedef-ed structs and enums start with a capital letter and have a capital +letter for each new word, with no underscores: `MyExcitingStruct`. + +Non-Typedef-ed structs and enums are all lowercase with underscores between +words: `struct my_exciting_struct` . > + + struct my_struct { + ... + }; + typedef struct my_struct MyAwesomeStruct; + + +Variable Names ~ + +Variable names are all lowercase, with underscores between words. For +instance: `my_exciting_local_variable`. + + Common Variable names ~ + + For example: > + + string table_name; // OK: uses underscore. + string tablename; // OK: all lowercase. + + string tableName; // BAD: mixed case. +< + + Struct Variables ~ + + Data members in structs should be named like regular variables. > + + struct url_table_properties { + string name; + int num_entries; + } +< + + Global Variables ~ + + Don't use global variables unless absolutely necessary. Prefix global + variables with `g_`. + + +Constant Names ~ + +Use a `k` followed by mixed case: `kDaysInAWeek`. + +All compile-time constants, whether they are declared locally or globally, +follow a slightly different naming convention from other variables. Use a `k` +followed by words with uppercase first letters: > + + const int kDaysInAWeek = 7; + +Function Names ~ + +Function names are all lowercase, with underscores between words. For +instance: `my_exceptional_function()`. All functions in the same header file +should have a common prefix. + +In `os_unix.h`: > + + void unix_open(const char *path); + void unix_user_id(void); + +If your function crashes upon an error, you should append `or_die` to the +function name. This only applies to functions which could be used by +production code and to errors that are reasonably likely to occur during +normal operation. + + +Enumerator Names ~ + +Enumerators should be named like constants: `kEnumName`. > + + enum url_table_errors { + kOK = 0, + kErrorOutOfMemory, + kErrorMalformedInput, + }; + + +Macro Names ~ + +They're like this: `MY_MACRO_THAT_SCARES_CPP_DEVELOPERS`. > + + #define ROUND(x) ... + #define PI_ROUNDED 5.0 + + +============================================================================== +Comments *dev-style-comments* + +Comments are vital to keeping our code readable. The following rules describe +what you should comment and where. But remember: while comments are very +important, the best code is self-documenting. + +When writing your comments, write for your audience: the next contributor who +will need to understand your code. Be generous — the next one may be you! + +Nvim uses Doxygen comments. + + +Comment Style ~ + +Use the `//`-style syntax only. > + + // This is a comment spanning + // multiple lines + f(); + + +File Comments ~ + +Start each file with a description of its contents. + + Legal Notice ~ + + We have no such thing. These things are in LICENSE and only there. + + File Contents ~ + + Every file should have a comment at the top describing its contents. + + Generally a `.h` file will describe the variables and functions that are + declared in the file with an overview of what they are for and how they + are used. A `.c` file should contain more information about implementation + details or discussions of tricky algorithms. If you feel the + implementation details or a discussion of the algorithms would be useful + for someone reading the `.h`, feel free to put it there instead, but + mention in the `.c` that the documentation is in the `.h` file. + + Do not duplicate comments in both the `.h` and the `.c`. Duplicated + comments diverge. > + + /// A brief description of this file. + /// + /// A longer description of this file. + /// Be very generous here. + + +Struct Comments ~ + +Every struct definition should have accompanying comments that describes what +it is for and how it should be used. > + + /// Window info stored with a buffer. + /// + /// Two types of info are kept for a buffer which are associated with a + /// specific window: + /// 1. Each window can have a different line number associated with a + /// buffer. + /// 2. The window-local options for a buffer work in a similar way. + /// The window-info is kept in a list at g_wininfo. It is kept in + /// most-recently-used order. + struct win_info { + /// Next entry or NULL for last entry. + WinInfo *wi_next; + /// Previous entry or NULL for first entry. + WinInfo *wi_prev; + /// Pointer to window that did the wi_fpos. + Win *wi_win; + ... + }; + +If the field comments are short, you can also put them next to the field. But +be consistent within one struct. > + + struct wininfo_S { + WinInfo *wi_next; /// Next entry or NULL for last entry. + WinInfo *wi_prev; /// Previous entry or NULL for first entry. + Win *wi_win; /// Pointer to window that did the wi_fpos. + ... + }; + +If you have already described a struct in detail in the comments at the top of +your file feel free to simply state "See comment at top of file for a complete +description", but be sure to have some sort of comment. + +Document the synchronization assumptions the struct makes, if any. If an +instance of the struct can be accessed by multiple threads, take extra care to +document the rules and invariants surrounding multithreaded use. + + +Function Comments ~ + +Declaration comments describe use of the function; comments at the definition +of a function describe operation. + + Function Declarations ~ + + Every function declaration should have comments immediately preceding it + that describe what the function does and how to use it. These comments + should be descriptive ("Opens the file") rather than imperative ("Open the + file"); the comment describes the function, it does not tell the function + what to do. In general, these comments do not describe how the function + performs its task. Instead, that should be left to comments in the + function definition. + + Types of things to mention in comments at the function declaration: + + - If the function allocates memory that the caller must free. + - Whether any of the arguments can be a null pointer. + - If there are any performance implications of how a function is used. + - If the function is re-entrant. What are its synchronization assumptions? + > + /// Brief description of the function. + /// + /// Detailed description. + /// May span multiple paragraphs. + /// + /// @param arg1 Description of arg1 + /// @param arg2 Description of arg2. May span + /// multiple lines. + /// + /// @return Description of the return value. + Iterator *get_iterator(void *arg1, void *arg2); +< + + Function Definitions ~ + + If there is anything tricky about how a function does its job, the + function definition should have an explanatory comment. For example, in + the definition comment you might describe any coding tricks you use, give + an overview of the steps you go through, or explain why you chose to + implement the function in the way you did rather than using a viable + alternative. For instance, you might mention why it must acquire a lock + for the first half of the function but why it is not needed for the second + half. + + Note you should not just repeat the comments given with the function + declaration, in the `.h` file or wherever. It's okay to recapitulate + briefly what the function does, but the focus of the comments should be on + how it does it. > + + // Note that we don't use Doxygen comments here. + Iterator *get_iterator(void *arg1, void *arg2) + { + ... + } + + +Variable Comments ~ + +In general the actual name of the variable should be descriptive enough to +give a good idea of what the variable is used for. In certain cases, more +comments are required. + + Global Variables ~ + + All global variables should have a comment describing what they are and + what they are used for. For example: > + + /// The total number of tests cases that we run + /// through in this regression test. + const int kNumTestCases = 6; + + +Implementation Comments ~ + +In your implementation you should have comments in tricky, non-obvious, +interesting, or important parts of your code. + + Line Comments ~ + + Also, lines that are non-obvious should get a comment at the end of the + line. These end-of-line comments should be separated from the code by 2 + spaces. Example: > + + // If we have enough memory, mmap the data portion too. + mmap_budget = max<int64>(0, mmap_budget - index_->length()); + if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) { + return; // Error already logged. + } +< + Note that there are both comments that describe what the code is doing, + and comments that mention that an error has already been logged when the + function returns. + + If you have several comments on subsequent lines, it can often be more + readable to line them up: > + + do_something(); // Comment here so the comments line up. + do_something_else_that_is_longer(); // Comment here so there are two spaces between + // the code and the comment. + { // One space before comment when opening a new scope is allowed, + // thus the comment lines up with the following comments and code. + do_something_else(); // Two spaces before line comments normally. + } +< + + NULL, true/false, 1, 2, 3... ~ + + When you pass in a null pointer, boolean, or literal integer values to + functions, you should consider adding a comment about what they are, or + make your code self-documenting by using constants. For example, compare: + > + + bool success = calculate_something(interesting_value, + 10, + false, + NULL); // What are these arguments?? +< + + versus: > + + bool success = calculate_something(interesting_value, + 10, // Default base value. + false, // Not the first time we're calling this. + NULL); // No callback. +< + + Or alternatively, constants or self-describing variables: > + + const int kDefaultBaseValue = 10; + const bool kFirstTimeCalling = false; + Callback *null_callback = NULL; + bool success = calculate_something(interesting_value, + kDefaultBaseValue, + kFirstTimeCalling, + null_callback); +< + + Don'ts ~ + + Note that you should never describe the code itself. Assume that the + person reading the code knows C better than you do, even though he or she + does not know what you are trying to do: > + + // Now go through the b array and make sure that if i occurs, + // the next element is i+1. + ... // Geez. What a useless comment. + + +Punctuation, Spelling and Grammar ~ + +Pay attention to punctuation, spelling, and grammar; it is easier to read +well-written comments than badly written ones. + +Comments should be as readable as narrative text, with proper capitalization +and punctuation. In many cases, complete sentences are more readable than +sentence fragments. Shorter comments, such as comments at the end of a line of +code, can sometimes be less formal, but you should be consistent with your +style. + +Although it can be frustrating to have a code reviewer point out that you are +using a comma when you should be using a semicolon, it is very important that +source code maintain a high level of clarity and readability. Proper +punctuation, spelling, and grammar help with that goal. + + +TODO Comments ~ + +Use `TODO` comments for code that is temporary, a short-term solution, or +good-enough but not perfect. + +`TODO`s should include the string `TODO` in all caps, followed by the name, +email address, or other identifier of the person who can best provide context +about the problem referenced by the `TODO`. The main purpose is to have a +consistent `TODO` format that can be searched to find the person who can +provide more details upon request. A `TODO` is not a commitment that the +person referenced will fix the problem. Thus when you create a `TODO`, it is +almost always your name that is given. > + + // TODO(kl@gmail.com): Use a "*" here for concatenation operator. + // TODO(Zeke): change this to use relations. + +If your `TODO` is of the form "At a future date do something" make sure that +you either include a very specific date ("Fix by November 2005") or a very +specific event ("Remove this code when all clients can handle XML +responses."). + + +Deprecation Comments ~ + +Mark deprecated interface points with `@deprecated` docstring token. + +You can mark an interface as deprecated by writing a comment containing the +word `@deprecated` in all caps. The comment goes either before the declaration +of the interface or on the same line as the declaration. + +After `@deprecated`, write your name, email, or other identifier in +parentheses. + +A deprecation comment must include simple, clear directions for people to fix +their callsites. In C, you can implement a deprecated function as an inline +function that calls the new interface point. + +Marking an interface point `DEPRECATED` will not magically cause any callsites +to change. If you want people to actually stop using the deprecated facility, +you will have to fix the callsites yourself or recruit a crew to help you. + +New code should not contain calls to deprecated interface points. Use the new +interface point instead. If you cannot understand the directions, find the +person who created the deprecation and ask them for help using the new +interface point. + + +============================================================================== +Formatting *dev-style-format* + +Coding style and formatting are pretty arbitrary, but a project is much easier +to follow if everyone uses the same style. Individuals may not agree with +every aspect of the formatting rules, and some of the rules may take some +getting used to, but it is important that all project contributors follow the +style rules so that they can all read and understand everyone's code easily. + + +Line Length ~ + +Each line of text in your code should be at most 100 characters long. + +Exception: if a comment line contains an example command or a literal URL +longer than 100 characters, that line may be longer than 100 characters for ease +of cut and paste. + + +Non-ASCII Characters ~ + +Non-ASCII characters should be rare, and must use UTF-8 formatting. + +You shouldn't hard-code user-facing text in source (OR SHOULD YOU?), even +English, so use of non-ASCII characters should be rare. However, in certain +cases it is appropriate to include such words in your code. For example, if +your code parses data files from foreign sources, it may be appropriate to +hard-code the non-ASCII string(s) used in those data files as delimiters. More +commonly, unittest code (which does not need to be localized) might contain +non-ASCII strings. In such cases, you should use UTF-8, since that is an +encoding understood by most tools able to handle more than just ASCII. + +Hex encoding is also OK, and encouraged where it enhances readability — for +example, `"\uFEFF"`, is the Unicode zero-width no-break space character, which +would be invisible if included in the source as straight UTF-8. + + +Spaces vs. Tabs ~ + +Use only spaces, and indent 2 spaces at a time. Do not use tabs in your code. + + +Function Declarations and Definitions ~ + +Return type on the same line as function name, parameters on the same line if +they fit. + +Functions look like this: > + + ReturnType function_name(Type par_name1, Type par_name2) + { + do_something(); + ... + } + +If you have too much text to fit on one line: > + + ReturnType really_long_function_name(Type par_name1, Type par_name2, + Type par_name3) + { + do_something(); + ... + } + +or if you cannot fit even the first parameter (but only then): > + + ReturnType really_really_really_long_function_name( + Type par_name1, // 4 space indent + Type par_name2, + Type par_name3) + { + do_something(); // 2 space indent + ... + } + +Some points to note: + +- The open parenthesis is always on the same line as the function name. +- There is never a space between the function name and the open parenthesis. +- There is never a space between the parentheses and the parameters. +- The open curly brace is always on the next line. +- The close curly brace is always on the last line by itself. +- There should be a space between the close parenthesis and the open curly + brace. +- All parameters should be named, with identical names in the declaration and + implementation. +- All parameters should be aligned if possible. +- Default indentation is 2 spaces. +- Wrapped parameters have a 4 space indent. + + +Function Calls ~ + +On one line if it fits; otherwise, wrap arguments at the parenthesis. + +Function calls have the following format: > + + bool retval = do_something(argument1, argument2, argument3); + +If the arguments do not all fit on one line, they should be broken up onto +multiple lines, with each subsequent line aligned with the first argument. Do +not add spaces after the open paren or before the close paren: > + + bool retval = do_something(averyveryveryverylongargument1, + argument2, argument3); + +If the function has many arguments, consider having one per line if this makes +the code more readable: > + + bool retval = do_something(argument1, + argument2, + argument3, + argument4); + +Arguments may optionally all be placed on subsequent lines, with one line per +argument: > + + if (...) { + ... + ... + if (...) { + do_something( + argument1, // 4 space indent + argument2, + argument3, + argument4); + } + +In particular, this should be done if the function signature is so long that +it cannot fit within the maximum line length. + + +Braced Initializer Lists ~ + +Format a braced list exactly like you would format a function call in its +place but with one space after the `{` and one space before the `}` + +If the braced list follows a name (e.g. a type or variable name), format as if +the `{}` were the parentheses of a function call with that name. If there is +no name, assume a zero-length name. > + + struct my_struct m = { // Here, you could also break before {. + superlongvariablename1, + superlongvariablename2, + { short, interior, list }, + { interiorwrappinglist, + interiorwrappinglist2 } }; + + +Conditionals ~ + +Don't use spaces inside parentheses. Always use curly braces. > + + if (condition) { // no spaces inside parentheses + ... // 2 space indent. + } else if (...) { // The else goes on the same line as the closing brace. + ... + } else { + ... + } + +You must have a space between the `if` and the open parenthesis. You must also +have a space between the close parenthesis and the curly brace, if you're +using one. > + + if(condition) { // BAD: space missing after IF. + if (condition){ // BAD: space missing before {. + if (condition) { // GOOD: proper space after IF and before {. + + +Loops and Switch Statements ~ + +Annotate non-trivial fall-through between cases. Empty loop bodies should use +`{}` or `continue`. + +If not conditional on an enumerated value, switch statements should always +have a `default` case (in the case of an enumerated value, the compiler will +warn you if any values are not handled). If the default case should never +execute, simply `assert`: > + + switch (var) { + case 0: // 2 space indent + ... // 4 space indent + break; + case 1: + ... + break; + default: + assert(false); + } + +Empty loop bodies should use `{}` or `continue`, but not a single semicolon. > + + while (condition) { + // Repeat test until it returns false. + } + for (int i = 0; i < kSomeNumber; i++) {} // GOOD: empty body. + while (condition) continue; // GOOD: continue indicates no logic. + + while (condition); // BAD: looks like part of do/while loop. + +Pointer Expressions ~ + +No spaces around period or arrow. Pointer operators do not have trailing +spaces. + +The following are examples of correctly-formatted pointer and reference +expressions: > + + x = *p; + p = &x; + x = r.y; + x = r->y; + +Note that: + + - There are no spaces around the period or arrow when accessing a member. + - Pointer operators have no space after the * or &. + +When declaring a pointer variable or argument, place the asterisk adjacent to +the variable name: > + + char *c; + + char * c; // BAD: spaces on both sides of * + char* c; // BAD + + +Boolean Expressions ~ + +When you have a boolean expression that is longer than the standard line +length, keep operators at the start of the line. > + + if (this_one_thing > this_other_thing + && a_third_thing == a_fourth_thing + && yet_another && last_one) { + ... + } + +Also note that you should always use the punctuation operators, such as `&&` +and `~`, rather than the word operators, such as `and` and `compl`. + + +Return Values ~ + +Do not needlessly surround the `return` expression with parentheses. + +Use parentheses in `return expr`; only where you would use them in `x = +expr;`. > + + return result; + return (some_long_condition && another_condition); + + return (value); // You wouldn't write var = (value); + return(result); // return is not a function! + + +Preprocessor Directives ~ + +The hash mark that starts a preprocessor directive should always be at the +beginning of the line. + +Even when preprocessor directives are within the body of indented code, the +directives should start at the beginning of the line. + +Nested directives should add one spaces after the hash mark for each level of +indentation. + + // GOOD: directives at beginning of line > + if (lopsided_score) { + #if DISASTER_PENDING // Correct -- Starts at beginning of line + drop_everything(); + # if NOTIFY // One space after # + notify_client(); + # endif + #endif + BackToNormal(); + } + +< // BAD: indented directives > + if (lopsided_score) { + #if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line + drop_everything(); + #endif // Wrong! Do not indent "#endif" + back_to_normal(); + } + + +Horizontal Whitespace ~ + +Use of horizontal whitespace depends on location. Never put trailing +whitespace at the end of a line. + + General ~ +> + if (x) { // Open braces should always have a space before them. + ... + } + int i = 0; // Semicolons usually have no space before them. + int x[] = { 0 }; // Spaces inside braces for braced-init-list. +< + + Variables ~ +> + int long_variable = 0; // Don't align assignments. + int i = 1; + + struct my_struct { // Exception: struct arrays. + const char *boy; + const char *girl; + int pos; + } my_variable[] = { + { "Mia", "Michael", 8 }, + { "Elizabeth", "Aiden", 10 }, + { "Emma", "Mason", 2 }, + }; +< + + Macros ~ +> + #define FI(x) \ // Don't align \'s in macro definitions. + foo(); \ + bar(); \ + ... +< + + Loops and Conditionals ~ +> + if (b) { // Space after the keyword in condition. + } else { // Spaces around else. + } + while (test) {} // There is usually no space inside parentheses. + for (; i < 5; i++) { // For loops always have a space after the + ... // semicolon and no a space before the + ... // semicolon. + } + switch (i) { + case 1: // No space before colon in a switch case. + ... + case 2: break; // Space after a colon if there's code after it. +< + + Operators ~ +> + x = 0; // Assignment operators always have spaces around + // them. + x = -5; // No spaces separating unary operators and their + x++; // arguments. + if (x && !y) + ... + v = w*x + y/z; // Use spaces to indicate operator precedence. + v = w * (x + z); // Parentheses should have no spaces inside them. + i = (int)d; // No spaces after a cast operator. +< + +Vertical Whitespace ~ + +Minimize use of vertical whitespace. + +This is more a principle than a rule: don't use blank lines when you don't +have to. In particular, don't put more than one or two blank lines between +functions, resist starting functions with a blank line, don't end functions +with a blank line, and be discriminating with your use of blank lines inside +functions. + +The basic principle is: The more code that fits on one screen, the easier it +is to follow and understand the control flow of the program. Of course, +readability can suffer from code being too dense as well as too spread out, so +use your judgment. But in general, minimize use of vertical whitespace. + + +============================================================================== +Parting Words + +The style guide is intended to make the code more readable. If you think you +must violate its rules for the sake of clarity, do it! But please add a note +to your pull request explaining your reasoning. + + + vim:tw=78:ts=8:et:ft=help:norl: diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 14f35acce3..7127c74134 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -166,7 +166,7 @@ Docstring format: - Use `<pre>` for code samples. Example: the help for |nvim_open_win()| is generated from a docstring defined -in src/nvim/api/vim.c like this: > +in src/nvim/api/win_config.c like this: > /// Opens a new window. /// ... diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 59b73771a6..4d1e5ac997 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -47,6 +47,7 @@ A diagnostic is a Lua table with the following keys: end_col: The final column of the diagnostic severity: The severity of the diagnostic |vim.diagnostic.severity| message: The diagnostic text + source: The source of the diagnostic Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based rows and columns). |api-indexing| @@ -186,6 +187,11 @@ can be customized using the following: > sign define DiagnosticSignInfo text=I texthl=DiagnosticSignInfo linehl= numhl= sign define DiagnosticSignHint text=H texthl=DiagnosticSignHint linehl= numhl= +When the "severity_sort" option is set (see |vim.diagnostic.config()|) the +priority of each sign depends on the severity of the associated diagnostic. +Otherwise, all signs have the same priority (the value of the "priority" +option in the "signs" table of |vim.diagnostic.config()| or 10 if unset). + ============================================================================== EVENTS *diagnostic-events* @@ -195,7 +201,52 @@ DiagnosticsChanged After diagnostics have changed. Example: > autocmd User DiagnosticsChanged lua vim.diagnostic.setqflist({open = false }) < - +============================================================================== +CUSTOMIZATION *diagnostic-config* + +If you need more customization over the way diagnostics are displayed than the +built-in configuration options provide, you can override the display handler +explicitly. For example, use the following to only show a sign for the highest +severity diagnostic on a given line: > + + -- Disable the default signs handler + vim.diagnostic.config({signs = false}) + + -- Create a namespace. This won't be used to add any diagnostics, + -- only to display them. + local ns = vim.api.nvim_create_namespace("my_namespace") + + -- Create a reference to the original function + local orig_show = vim.diagnostic.show + + local function set_signs(bufnr) + -- Get all diagnostics from the current buffer + local diagnostics = vim.diagnostic.get(bufnr) + + -- Find the "worst" diagnostic per line + local max_severity_per_line = {} + for _, d in pairs(diagnostics) do + local m = max_severity_per_line[d.lnum] + if not m or d.severity < m.severity then + max_severity_per_line[d.lnum] = d + end + end + + -- Show the filtered diagnostics using the custom namespace. Use the + -- reference to the original function to avoid a loop. + local filtered_diagnostics = vim.tbl_values(max_severity_per_line) + orig_show(ns, bufnr, filtered_diagnostics, { + virtual_text=false, + underline=false, + signs=true + }) + end + + function vim.diagnostic.show(namespace, bufnr, ...) + orig_show(namespace, bufnr, ...) + set_signs(bufnr) + end +< ============================================================================== Lua module: vim.diagnostic *diagnostic-api* @@ -203,12 +254,31 @@ config({opts}, {namespace}) *vim.diagnostic.config()* Configure diagnostic options globally or for a specific diagnostic namespace. + Configuration can be specified globally, per-namespace, or + ephemerally (i.e. only for a single call to + |vim.diagnostic.set()| or |vim.diagnostic.show()|). Ephemeral + configuration has highest priority, followed by namespace + configuration, and finally global configuration. + + For example, if a user enables virtual text globally with > + + vim.diagnostic.config({virtual_text = true}) +< + + and a diagnostic producer sets diagnostics with > + + vim.diagnostic.set(ns, 0, diagnostics, {virtual_text = false}) +< + + then virtual text will not be enabled for those diagnostics. + Note: Each of the configuration options below accepts one of the following: • `false` : Disable this feature • `true` : Enable this feature, use default settings. - • `table` : Enable this feature with overrides. + • `table` : Enable this feature with overrides. Use an + empty table to use default values. • `function` : Function with signature (namespace, bufnr) that returns any of the above. @@ -226,12 +296,45 @@ config({opts}, {namespace}) *vim.diagnostic.config()* • severity: Only show virtual text for diagnostics matching the given severity |diagnostic-severity| + • source: (string) Include the diagnostic + source in virtual text. One of "always" + or "if_many". + • format: (function) A function that takes + a diagnostic as input and returns a + string. The return value is the text used + to display the diagnostic. Example: > + + function(diagnostic) + if diagnostic.severity == vim.diagnostic.severity.ERROR then + return string.format("E: %s", diagnostic.message) + end + return diagnostic.message + end +< • signs: (default true) Use signs for diagnostics. Options: • severity: Only show signs for diagnostics matching the given severity |diagnostic-severity| + • priority: (number, default 10) Base + priority to use for signs. When + {severity_sort} is used, the priority of + a sign is adjusted based on its severity. + Otherwise, all signs use the same + priority. + + • float: Options for floating windows: + • severity: See |diagnostic-severity|. + • show_header: (boolean, default true) Show + "Diagnostics:" header + • source: (string) Include the diagnostic + source in the message. One of "always" or + "if_many". + • format: (function) A function that takes + a diagnostic as input and returns a + string. The return value is the text used + to display the diagnostic. • update_in_insert: (default false) Update diagnostics in Insert mode (if false, @@ -291,6 +394,13 @@ get({bufnr}, {opts}) *vim.diagnostic.get()* Return: ~ table A list of diagnostic items |diagnostic-structure|. +get_namespaces() *vim.diagnostic.get_namespaces()* + Get current diagnostic namespaces. + + Return: ~ + table A list of active diagnostic namespaces + |vim.diagnostic|. + get_next({opts}) *vim.diagnostic.get_next()* Get the next diagnostic closest to the cursor position. @@ -329,26 +439,6 @@ get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()* Return: ~ table Previous diagnostic position as a (row, col) tuple. - *vim.diagnostic.get_virt_text_chunks()* -get_virt_text_chunks({line_diags}, {opts}) - Get virtual text chunks to display using - |nvim_buf_set_extmark()|. - - Parameters: ~ - {line_diags} table The diagnostics associated with the - line. - {opts} table|nil Configuration table with the - following keys: - • prefix: (string) Prefix to display before - virtual text on line. - • spacing: (number) Number of spaces to - insert before virtual text. - - Return: ~ - array of ({text}, {hl_group}) tuples. This can be passed - directly to the {virt_text} option of - |nvim_buf_set_extmark()|. - goto_next({opts}) *vim.diagnostic.goto_next()* Move to the next diagnostic. @@ -364,12 +454,10 @@ goto_next({opts}) *vim.diagnostic.goto_next()* • wrap: (boolean, default true) Whether to loop around file or not. Similar to 'wrapscan'. • severity: See |diagnostic-severity|. - • enable_popup: (boolean, default true) Call - |vim.diagnostic.show_line_diagnostics()| on - jump. - • popup_opts: (table) Table to pass as {opts} - parameter to - |vim.diagnostic.show_line_diagnostics()| + • float: (boolean or table, default true) If + "true", call |vim.diagnostic.open_float()| after + moving. If a table, pass the table as the {opts} + parameter to |vim.diagnostic.open_float()|. • win_id: (number, default 0) Window ID goto_prev({opts}) *vim.diagnostic.goto_prev()* @@ -401,8 +489,9 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) For example, consider a line of output from a linter: > WARNING filename:27:3: Variable 'foo' does not exist +< - < This can be parsed into a diagnostic |diagnostic-structure| + This can be parsed into a diagnostic |diagnostic-structure| with: > local s = "WARNING filename:27:3: Variable 'foo' does not exist" @@ -429,6 +518,46 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) diagnostic |diagnostic-structure| or `nil` if {pat} fails to match {str}. +open_float({bufnr}, {opts}) *vim.diagnostic.open_float()* + Show diagnostics in a floating window. + + Parameters: ~ + {bufnr} number|nil Buffer number. Defaults to the current + buffer. + {opts} table|nil Configuration table with the same keys + as |vim.lsp.util.open_floating_preview()| in + addition to the following: + • namespace: (number) Limit diagnostics to the + given namespace + • scope: (string, default "buffer") Show + diagnostics from the whole buffer ("buffer"), + the current cursor line ("line"), or the + current cursor position ("cursor"). + • pos: (number or table) If {scope} is "line" or + "cursor", use this position rather than the + cursor position. If a number, interpreted as a + line number; otherwise, a (row, col) tuple. + • severity_sort: (default false) Sort diagnostics + by severity. Overrides the setting from + |vim.diagnostic.config()|. + • severity: See |diagnostic-severity|. Overrides + the setting from |vim.diagnostic.config()|. + • show_header: (boolean, default true) Show + "Diagnostics:" header. Overrides the setting + from |vim.diagnostic.config()|. + • source: (string) Include the diagnostic source + in the message. One of "always" or "if_many". + Overrides the setting from + |vim.diagnostic.config()|. + • format: (function) A function that takes a + diagnostic as input and returns a string. The + return value is the text used to display the + diagnostic. Overrides the setting from + |vim.diagnostic.config()|. + + Return: ~ + tuple ({float_bufnr}, {win_id}) + reset({namespace}, {bufnr}) *vim.diagnostic.reset()* Remove all diagnostics from the given namespace. @@ -502,44 +631,6 @@ show({namespace}, {bufnr}, {diagnostics}, {opts}) {opts} table|nil Display options. See |vim.diagnostic.config()|. - *vim.diagnostic.show_line_diagnostics()* -show_line_diagnostics({opts}, {bufnr}, {lnum}) - Open a floating window with the diagnostics from the given - line. - - Parameters: ~ - {opts} table Configuration table. See - |vim.diagnostic.show_position_diagnostics()|. - {bufnr} number|nil Buffer number. Defaults to the current - buffer. - {lnum} number|nil Line number. Defaults to line number - of cursor. - - Return: ~ - tuple ({popup_bufnr}, {win_id}) - - *vim.diagnostic.show_position_diagnostics()* -show_position_diagnostics({opts}, {bufnr}, {position}) - Open a floating window with the diagnostics at the given - position. - - Parameters: ~ - {opts} table|nil Configuration table with the same - keys as |vim.lsp.util.open_floating_preview()| - in addition to the following: - • namespace: (number) Limit diagnostics to the - given namespace - • severity: See |diagnostic-severity|. - • show_header: (boolean, default true) Show - "Diagnostics:" header - {bufnr} number|nil Buffer number. Defaults to the - current buffer. - {position} table|nil The (0,0)-indexed position. Defaults - to the current cursor position. - - Return: ~ - tuple ({popup_bufnr}, {win_id}) - toqflist({diagnostics}) *vim.diagnostic.toqflist()* Convert a list of diagnostics to a list of quickfix items that can be passed to |setqflist()| or |setloclist()|. diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index 4700af41b7..4e3173cfa9 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -1183,7 +1183,8 @@ If you want to always use ":confirm", set the 'confirm' option. |:diffsplit|, |:diffpatch|, |:pedit|, |:redir|, |:source|, |:update|, |:visual|, |:vsplit|, and |:qall| if 'confirm' is set. - {only in Win32 GUI} + {only in Win32 GUI, in console `browse edit` works + if the FileExplorer autocommand group exists} When ":browse" is not possible you get an error message. If {command} doesn't support browsing, the {command} is executed without a dialog. @@ -1274,10 +1275,12 @@ exist, the next-higher scope in the hierarchy applies. *:chd* *:chdir* :chd[ir][!] [path] Same as |:cd|. - *:tc* *:tcd* *E5000* *E5001* *E5002* -:tc[d][!] {path} Like |:cd|, but set the current directory for the - current tab and window. The current directory for - other tabs and windows is not changed. + *:tc* *:tcd* +:tc[d][!] {path} Like |:cd|, but only set the directory for the current + tab. The current window will also use this directory. + The current directory is not changed for windows in + other tabs and for windows in the current tab that + have their own window-local directory. *:tcd-* :tc[d][!] - Change to the previous current directory (before the @@ -1301,23 +1304,39 @@ exist, the next-higher scope in the hierarchy applies. *:pw* *:pwd* *E187* :pw[d] Print the current directory name. Also see |getcwd()|. + *:pwd-verbose* + When 'verbose' is non-zero, |:pwd| will also display + what scope the current directory was set. Example: > -So long as no |:tcd| or |:lcd| command has been used, all windows share the -same "current directory". Using a command to jump to another window doesn't + " Set by :cd + :verbose pwd + [global] /path/to/current + + " Set by :lcd + :verbose pwd + [window] /path/to/current + + " Set by :tcd + :verbose pwd + [tabpage] /path/to/current + +So long as no |:lcd| or |:tcd| command has been used, all windows share the +same current directory. Using a command to jump to another window doesn't change anything for the current directory. When |:lcd| has been used for a window, the specified directory becomes the current directory for that window. Windows where the |:lcd| command has not been used stick to the global or tab-local directory. When jumping to another -window the current directory will become the last specified local current +window the current directory is changed to the last specified local current directory. If none was specified, the global or tab-local directory is used. When changing tabs the same behaviour applies. If the current tab has no -local working directory the global working directory is used. When a |:cd| -command is used, the current window and tab will lose their local current -directories and will use the global current directory from now on. When -a |:tcd| command is used, only the current window will lose its local working -directory. +local working directory the global working directory is used. + +When a |:cd| command is used, the current window and tab will lose their local +current directories and will use the global current directory from now on. +When a |:tcd| command is used, only the current window will lose its local +working directory. After using |:cd| the full path name will be used for reading and writing files. On some networked file systems this may cause problems. The result of @@ -1466,6 +1485,11 @@ It is also possible that you modified the file yourself, from another edit session or with another command (e.g., a filter command). Then you will know which version of the file you want to keep. +The accuracy of the time check depends on the filesystem. On Unix it is +usually sub-second. With old file sytems and on MS-Windows it is normally one +second. Use has('nanotime') check if sub-second time stamp checks are +available. + There is one situation where you get the message while there is nothing wrong: On a Win32 system on the day daylight saving time starts. There is something in the Win32 libraries that confuses Vim about the hour time difference. The diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index b3d5f4d7e9..6549d0b5f3 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -586,7 +586,7 @@ It is not necessary to use the "dict" attribute for a numbered function. If you get an error for a numbered function, you can find out what it is with a trick. Assuming the function is 42, the command is: > - :function {42} + :function g:42 Functions for Dictionaries ~ @@ -1204,7 +1204,7 @@ next method: > mylist->filter(filterexpr)->map(mapexpr)->sort()->join() < Example of using a lambda: > - GetPercentage->{x -> x * 100}()->printf('%d%%') + GetPercentage()->{x -> x * 100}()->printf('%d%%') < When using -> the |expr7| operators will be applied first, thus: > -1.234->string() @@ -1307,7 +1307,7 @@ A string constant accepts these special characters: \U.... same as \u but allows up to 8 hex numbers. \b backspace <BS> \e escape <Esc> -\f formfeed <FF> +\f formfeed 0x0C \n newline <NL> \r return <CR> \t tab <Tab> @@ -1316,7 +1316,7 @@ A string constant accepts these special characters: \<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use in mappings, the 0x80 byte is escaped. To use the double quote character it must be escaped: "<M-\">". - Don't use <Char-xxxx> to get a utf-8 character, use \uxxxx as + Don't use <Char-xxxx> to get a UTF-8 character, use \uxxxx as mentioned above. Note that "\xff" is stored as the byte 255, which may be invalid in some @@ -2313,9 +2313,10 @@ ceil({expr}) Float round {expr} up changenr() Number current change number chanclose({id}[, {stream}]) Number Closes a channel or one of its streams chansend({id}, {data}) Number Writes {data} to channel -char2nr({expr}[, {utf8}]) Number ASCII/UTF8 value of first char in {expr} +char2nr({expr}[, {utf8}]) Number ASCII/UTF-8 value of first char in {expr} charidx({string}, {idx} [, {countcc}]) Number char index of byte {idx} in {string} +chdir({dir}) String change current working directory cindent({lnum}) Number C indent for line {lnum} clearmatches([{win}]) none clear all matches col({expr}) Number column nr of cursor or mark @@ -2431,13 +2432,15 @@ getloclist({nr}) List list of location list items getloclist({nr}, {what}) Dict get specific location list properties getmarklist([{buf}]) List list of global/local marks getmatches([{win}]) List list of current matches +getmousepos() Dict last known mouse position getpid() Number process ID of Vim getpos({expr}) List position of cursor, mark, etc. getqflist() List list of quickfix items getqflist({what}) Dict get specific quickfix list properties getreg([{regname} [, 1 [, {list}]]]) - String or List contents of register -getregtype([{regname}]) String type of register + String or List contents of a register +getreginfo([{regname}]) Dict information about a register +getregtype([{regname}]) String type of a register gettabinfo([{expr}]) List list of tab pages gettabvar({nr}, {varname} [, {def}]) any variable {varname} in tab {nr} or {def} @@ -2458,7 +2461,8 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) has({feature}) Number |TRUE| if feature {feature} supported has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key} haslocaldir([{winnr} [, {tabnr}]]) - Number |TRUE| if current window executed |:lcd| + Number |TRUE| if the window executed |:lcd| or + the tab executed |:tcd| hasmapto({what} [, {mode} [, {abbr}]]) Number |TRUE| if mapping to {what} exists histadd({history}, {item}) String add an item to a history @@ -2503,7 +2507,7 @@ keys({dict}) List keys in {dict} len({expr}) Number the length of {expr} libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg} libcallnr({lib}, {func}, {arg}) Number idem, but return a Number -line({expr}) Number line nr of cursor, last line or mark +line({expr} [, {winid}]) Number line nr of cursor, last line or mark line2byte({lnum}) Number byte count of line {lnum} lispindent({lnum}) Number Lisp indent for line {lnum} list2str({list} [, {utf8}]) String turn numbers in {list} into a String @@ -2542,7 +2546,7 @@ mode([expr]) String current editing mode msgpackdump({list} [, {type}]) List/Blob dump objects to msgpack msgpackparse({data}) List parse msgpack to a list of objects nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} -nr2char({expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr} +nr2char({expr}[, {utf8}]) String single char with ASCII/UTF-8 value {expr} nvim_...({args}...) any call nvim |api| functions or({expr}, {expr}) Number bitwise OR pathshorten({expr}) String shorten directory names in a path @@ -2678,7 +2682,7 @@ stdioopen({dict}) Number open stdio in a headless instance. stdpath({what}) String/List returns the standard path(s) for {what} str2float({expr} [, {quoted}]) Float convert String to Float str2list({expr} [, {utf8}]) List convert each character of {expr} to - ASCII/UTF8 value + ASCII/UTF-8 value str2nr({expr} [, {base} [, {quoted}]]) Number convert String to Number strchars({expr} [, {skipcc}]) Number character length of the String {expr} @@ -3278,6 +3282,27 @@ charidx({string}, {idx} [, {countcc}]) echo charidx('áb́ć', 6, 1) returns 4 echo charidx('áb́ć', 16) returns -1 +chdir({dir}) *chdir()* + Change the current working directory to {dir}. The scope of + the directory change depends on the directory of the current + window: + - If the current window has a window-local directory + (|:lcd|), then changes the window local directory. + - Otherwise, if the current tabpage has a local + directory (|:tcd|) then changes the tabpage local + directory. + - Otherwise, changes the global directory. + If successful, returns the previous working directory. Pass + this to another chdir() to restore the directory. + On failure, returns an empty string. + + Example: > + let save_dir = chdir(newdir) + if save_dir + " ... do some work + call chdir(save_dir) + endif +< cindent({lnum}) *cindent()* Get the amount of indent for line {lnum} according the C indenting rules, as with 'cindent'. @@ -3417,6 +3442,8 @@ complete_info([{what}]) *complete_info()* "" Not in completion mode "keyword" Keyword completion |i_CTRL-X_CTRL-N| "ctrl_x" Just pressed CTRL-X |i_CTRL-X| + "scroll" Scrolling with |i_CTRL-X_CTRL-E| or + |i_CTRL-X_CTRL-Y| "whole_line" Whole lines |i_CTRL-X_CTRL-L| "files" File names |i_CTRL-X_CTRL-F| "tags" Tags |i_CTRL-X_CTRL-]| @@ -3827,6 +3854,9 @@ escape({string}, {chars}) *escape()* c:\\program\ files\\vim < Also see |shellescape()| and |fnameescape()|. + Can also be used as a |method|: > + GetText()->escape(' \') +< *eval()* eval({string}) Evaluate {string} and return the result. Especially useful to turn the result of |string()| back into the original value. @@ -3866,6 +3896,9 @@ executable({expr}) *executable()* -1 not implemented on this system |exepath()| can be used to get the full path of an executable. + Can also be used as a |method|: > + GetCommand()->executable() + execute({command} [, {silent}]) *execute()* Execute {command} and capture its output. If {command} is a |String|, returns {command} output. @@ -3893,12 +3926,18 @@ execute({command} [, {silent}]) *execute()* To execute a command in another window than the current one use `win_execute()`. + Can also be used as a |method|: > + GetCommand()->execute() + exepath({expr}) *exepath()* Returns the full path of {expr} if it is an executable and given as a (partial or full) path or is found in $PATH. Returns empty string otherwise. If {expr} starts with "./" the |current-directory| is used. + Can also be used as a |method|: > + GetCommand()->exepath() + *exists()* exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined, zero otherwise. @@ -3984,6 +4023,9 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is < This doesn't check for existence of the "bufcount" variable, but gets the value of "bufcount", and checks if that exists. + Can also be used as a |method|: > + Varname()->exists() + exp({expr}) *exp()* Return the exponential of {expr} as a |Float| in the range [0, inf]. @@ -4090,6 +4132,9 @@ expand({string} [, {nosuf} [, {list}]]) *expand()* See |glob()| for finding existing files. See |system()| for getting the raw output of an external command. + Can also be used as a |method|: > + Getpattern()->expand() + expandcmd({expr}) *expandcmd()* Expand special items in {expr} like what is done for an Ex command such as `:edit`. This expands special keywords, like @@ -4097,6 +4142,9 @@ expandcmd({expr}) *expandcmd()* {expr}. "~user" and "~/path" are only expanded at the start. Returns the expanded string. Example: > :echo expandcmd('make %<.o') + +< Can also be used as a |method|: > + GetCommand()->expandcmd() < extend({expr1}, {expr2} [, {expr3}]) *extend()* {expr1} and {expr2} must be both |Lists| or both @@ -4182,6 +4230,9 @@ feedkeys({string} [, {mode}]) *feedkeys()* Return value is always 0. + Can also be used as a |method|: > + GetInput()->feedkeys() + filereadable({file}) *filereadable()* The result is a Number, which is |TRUE| when a file with the name {file} exists, and can be read. If {file} doesn't exist, @@ -4195,12 +4246,17 @@ filereadable({file}) *filereadable()* echo filereadable(expand('~/.vimrc')) 1 +< Can also be used as a |method|: > + GetName()->filereadable() + filewritable({file}) *filewritable()* The result is a Number, which is 1 when a file with the name {file} exists, and can be written. If {file} doesn't exist, or is not writable, the result is 0. If {file} is a directory, and we can write to it, the result is 2. + Can also be used as a |method|: > + GetName()->filewriteable() filter({expr1}, {expr2}) *filter()* {expr1} must be a |List|, |Blob|, or a |Dictionary|. @@ -4271,6 +4327,9 @@ finddir({name} [, {path} [, {count}]]) *finddir()* This is quite similar to the ex-command `:find`. + Can also be used as a |method|: > + GetName()->finddir() + findfile({name} [, {path} [, {count}]]) *findfile()* Just like |finddir()|, but find a file instead of a directory. Uses 'suffixesadd'. @@ -4279,6 +4338,9 @@ findfile({name} [, {path} [, {count}]]) *findfile()* < Searches from the directory of the current file upwards until it finds the file "tags.vim". + Can also be used as a |method|: > + GetName()->findfile() + flatten({list} [, {maxdepth}]) *flatten()* Flatten {list} up to {maxdepth} levels. Without {maxdepth} the result is a |List| without nesting, as if {maxdepth} is @@ -4368,6 +4430,9 @@ fnameescape({string}) *fnameescape()* :exe "edit " . fnameescape(fname) < results in executing: > edit \+some\ str\%nge\|name +< + Can also be used as a |method|: > + GetName()->fnameescape() fnamemodify({fname}, {mods}) *fnamemodify()* Modify file name {fname} according to {mods}. {mods} is a @@ -4381,6 +4446,9 @@ fnamemodify({fname}, {mods}) *fnamemodify()* Note: Environment variables don't work in {fname}, use |expand()| first then. + Can also be used as a |method|: > + GetName()->fnamemodify(':p:h') + foldclosed({lnum}) *foldclosed()* The result is a Number. If the line {lnum} is in a closed fold, the result is the number of the first line in that fold. @@ -4388,6 +4456,9 @@ foldclosed({lnum}) *foldclosed()* {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. + Can also be used as a |method|: > + GetLnum()->foldclosed() + foldclosedend({lnum}) *foldclosedend()* The result is a Number. If the line {lnum} is in a closed fold, the result is the number of the last line in that fold. @@ -4395,6 +4466,9 @@ foldclosedend({lnum}) *foldclosedend()* {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. + Can also be used as a |method|: > + GetLnum()->foldclosedend() + foldlevel({lnum}) *foldlevel()* The result is a Number, which is the foldlevel of line {lnum} in the current buffer. For nested folds the deepest level is @@ -4407,6 +4481,9 @@ foldlevel({lnum}) *foldlevel()* {lnum} is used like with |getline()|. Thus "." is the current line, "'m" mark m, etc. + Can also be used as a |method|: > + GetLnum()->foldlevel() + *foldtext()* foldtext() Returns a String, to be displayed for a closed fold. This is the default function used for the 'foldtext' option and should @@ -4432,6 +4509,9 @@ foldtextresult({lnum}) *foldtextresult()* line, "'m" mark m, etc. Useful when exporting folded text, e.g., to HTML. + Can also be used as a |method|: > + GetLnum()->foldtextresult() +< *foreground()* foreground() Move the Vim window to the foreground. Useful when sent from a client to a Vim server. |remote_send()| @@ -4450,6 +4530,9 @@ funcref({name} [, {arglist}] [, {dict}]) Also for autoloaded functions. {name} cannot be a builtin function. + Can also be used as a |method|: > + GetFuncname()->funcref([arg]) +< *function()* *E700* *E922* *E923* function({name} [, {arglist}] [, {dict}]) Return a |Funcref| variable that refers to function {name}. @@ -4499,7 +4582,9 @@ function({name} [, {arglist}] [, {dict}]) call Func(500) < Invokes the function as with: > call context.Callback('one', 500) - +< + Can also be used as a |method|: > + GetFuncname()->function([arg]) garbagecollect([{atexit}]) *garbagecollect()* Cleanup unused |Lists| and |Dictionaries| that have circular @@ -4639,6 +4724,9 @@ getbufline({buf}, {lnum} [, {end}]) Example: > :let lines = getbufline(bufnr("myfile"), 1, "$") +< Can also be used as a |method|: > + GetBufnr()->getbufline(lnum) + getbufvar({buf}, {varname} [, {def}]) *getbufvar()* The result is the value of option or local buffer variable {varname} in buffer {buf}. Note that the name without "b:" @@ -4659,8 +4747,11 @@ getbufvar({buf}, {varname} [, {def}]) *getbufvar()* Examples: > :let bufmodified = getbufvar(1, "&mod") :echo "todo myvar = " . getbufvar("todo", "myvar") + +< Can also be used as a |method|: > + GetBufnr()->getbufvar(varname) < -getchangelist({buf}) *getchangelist()* +getchangelist([{buf}]) *getchangelist()* Returns the |changelist| for the buffer {buf}. For the use of {buf}, see |bufname()| above. If buffer {buf} doesn't exist, an empty list is returned. @@ -4676,6 +4767,9 @@ getchangelist({buf}) *getchangelist()* position refers to the position in the list. For other buffers, it is set to the length of the list. + Can also be used as a |method|: > + GetBufnr()->getchangelist() + getchar([expr]) *getchar()* Get a single character from the user or input stream. If [expr] is omitted, wait until a character is available. @@ -4708,7 +4802,8 @@ getchar([expr]) *getchar()* When the user clicks a mouse button, the mouse event will be returned. The position can then be found in |v:mouse_col|, |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. - Mouse move events will be ignored. + |getmousepos()| can also be used. Mouse move events will be + ignored. This example positions the mouse as it would normally happen: > let c = getchar() if c == "\<LeftMouse>" && v:mouse_win > 0 @@ -4885,6 +4980,9 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* If there are no matches, an empty list is returned. An invalid value for {type} produces an error. + Can also be used as a |method|: > + GetPattern()->getcompletion('color') +< *getcurpos()* getcurpos() Get the position of the cursor. This is like getpos('.'), but includes an extra "curswant" in the list: @@ -4912,6 +5010,12 @@ getcwd([{winnr}[, {tabnr}]]) *getcwd()* getcwd(0, 0) < If {winnr} is -1 it is ignored, only the tab is resolved. {winnr} can be the window number or the |window-ID|. + If both {winnr} and {tabnr} are -1 the global working + directory is returned. + Throw error if the arguments are invalid. |E5000| |E5001| |E5002| + + Can also be used as a |method|: > + GetWinnr()->getcwd() getenv({name}) *getenv()* Return the value of environment variable {name}. The {name} @@ -4922,6 +5026,9 @@ getenv({name}) *getenv()* is different from a variable set to an empty string. See also |expr-env|. + Can also be used as a |method|: > + GetVarname()->getenv() + getfontname([{name}]) *getfontname()* Without an argument returns the name of the normal font being used. Like what is used for the Normal highlight group @@ -4949,6 +5056,9 @@ getfperm({fname}) *getfperm()* < This will hopefully (from a security point of view) display the string "rw-r--r--" or even "rw-------". + Can also be used as a |method|: > + GetFilename()->getfperm() +< For setting permissions use |setfperm()|. getfsize({fname}) *getfsize()* @@ -4959,6 +5069,9 @@ getfsize({fname}) *getfsize()* If the size of {fname} is too big to fit in a Number then -2 is returned. + Can also be used as a |method|: > + GetFilename()->getfsize() + getftime({fname}) *getftime()* The result is a Number, which is the last modification time of the given file {fname}. The value is measured as seconds @@ -4966,6 +5079,9 @@ getftime({fname}) *getftime()* |localtime()| and |strftime()|. If the file {fname} can't be found -1 is returned. + Can also be used as a |method|: > + GetFilename()->getftime() + getftype({fname}) *getftype()* The result is a String, which is a description of the kind of file of the given file {fname}. @@ -4986,6 +5102,9 @@ getftype({fname}) *getftype()* systems that support it. On some systems only "dir" and "file" are returned. + Can also be used as a |method|: > + GetFilename()->getftype() + getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* Returns the |jumplist| for the specified window. @@ -5005,7 +5124,10 @@ getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* filename filename if available lnum line number - *getline()* + Can also be used as a |method|: > + GetWinnr()->getjumplist() + +< *getline()* getline({lnum} [, {end}]) Without {end} the result is a String, which is line {lnum} from the current buffer. Example: > @@ -5028,6 +5150,9 @@ getline({lnum} [, {end}]) :let end = search("^$") - 1 :let lines = getline(start, end) +< Can also be used as a |method|: > + ComputeLnum()->getline() + < To get lines from another buffer see |getbufline()| getloclist({nr},[, {what}]) *getloclist()* @@ -5098,6 +5223,35 @@ getmatches([{win}]) *getmatches()* 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > :unlet m < +getmousepos() *getmousepos()* + Returns a Dictionary with the last known position of the + mouse. This can be used in a mapping for a mouse click. The + items are: + screenrow screen row + screencol screen column + winid Window ID of the click + winrow row inside "winid" + wincol column inside "winid" + line text line inside "winid" + column text column inside "winid" + All numbers are 1-based. + + If not over a window, e.g. when in the command line, then only + "screenrow" and "screencol" are valid, the others are zero. + + When on the status line below a window or the vertical + separater right of a window, the "line" and "column" values + are zero. + + When the position is after the text then "column" is the + length of the text in bytes plus one. + + If the mouse is over a focusable floating window then that + window is used. + + When using |getchar()| the Vim variables |v:mouse_lnum|, + |v:mouse_col| and |v:mouse_winid| also provide these values. + *getpid()* getpid() Return a Number which is the process ID of the Vim process. This is a unique number, until Vim exits. @@ -5129,6 +5283,8 @@ getpos({expr}) Get the position for String {expr}. For possible values of call setpos("'a", save_a_mark) < Also see |getcurpos()| and |setpos()|. + Can also be used as a |method|: > + GetMark()->getpos() getqflist([{what}]) *getqflist()* Returns a |List| with all the current quickfix errors. Each @@ -5247,6 +5403,35 @@ getreg([{regname} [, 1 [, {list}]]]) *getreg()* If {regname} is not specified, |v:register| is used. + Can also be used as a |method|: > + GetRegname()->getreg() + +getreginfo([{regname}]) *getreginfo()* + Returns detailed information about register {regname} as a + Dictionary with the following entries: + regcontents List of lines contained in register + {regname}, like + |getreg|({regname}, 1, 1). + regtype the type of register {regname}, as in + |getregtype()|. + isunnamed Boolean flag, v:true if this register + is currently pointed to by the unnamed + register. + points_to for the unnamed register, gives the + single letter name of the register + currently pointed to (see |quotequote|). + For example, after deleting a line + with `dd`, this field will be "1", + which is the register that got the + deleted text. + + The {regname} argument is a string. If {regname} is invalid + or not set, an empty Dictionary will be returned. + If {regname} is not specified, |v:register| is used. + The returned Dictionary can be passed to |setreg()|. + + Can also be used as a |method|: > + GetRegname()->getreginfo() getregtype([{regname}]) *getregtype()* The result is a String, which is type of register {regname}. @@ -5259,6 +5444,9 @@ getregtype([{regname}]) *getregtype()* The {regname} argument is a string. If {regname} is not specified, |v:register| is used. + Can also be used as a |method|: > + GetRegname()->getregtype() + gettabinfo([{tabnr}]) *gettabinfo()* If {tabnr} is not specified, then information about all the tab pages is returned as a |List|. Each List item is a @@ -5272,6 +5460,9 @@ gettabinfo([{tabnr}]) *gettabinfo()* tabpage-local variables windows List of |window-ID|s in the tab page. + Can also be used as a |method|: > + GetTabnr()->gettabinfo() + gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* Get the value of a tab-local variable {varname} in tab page {tabnr}. |t:var| @@ -5282,6 +5473,9 @@ gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* When the tab or variable doesn't exist {def} or an empty string is returned, there is no error message. + Can also be used as a |method|: > + GetTabnr()->gettabvar(varname) + gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* Get the value of window-local variable {varname} in window {winnr} in tab page {tabnr}. @@ -5308,6 +5502,9 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* To obtain all window-local variables use: > gettabwinvar({tabnr}, {winnr}, '&') +< Can also be used as a |method|: > + GetTabnr()->gettabwinvar(winnr, varname) + gettagstack([{winnr}]) *gettagstack()* The result is a Dict, which is the tag stack of window {winnr}. {winnr} can be the window number or the |window-ID|. @@ -5336,6 +5533,9 @@ gettagstack([{winnr}]) *gettagstack()* See |tagstack| for more information about the tag stack. + Can also be used as a |method|: > + GetWinnr()->gettagstack() + getwininfo([{winid}]) *getwininfo()* Returns information about windows as a |List| with Dictionaries. @@ -5367,6 +5567,9 @@ getwininfo([{winid}]) *getwininfo()* winrow topmost screen line of the window; "row" from |win_screenpos()| + Can also be used as a |method|: > + GetWinnr()->getwininfo() + getwinpos([{timeout}]) *getwinpos()* The result is a |List| with two numbers, the result of |getwinposx()| and |getwinposy()| combined: @@ -5387,6 +5590,9 @@ getwinpos([{timeout}]) *getwinpos()* " Do some work here endwhile < + Can also be used as a |method|: > + GetTimeout()->getwinpos() +< *getwinposx()* getwinposx() The result is a Number, which is the X coordinate in pixels of the left hand side of the GUI Vim window. The result will be @@ -5404,6 +5610,9 @@ getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* Examples: > :let list_is_on = getwinvar(2, '&list') :echo "myvar = " . getwinvar(1, 'myvar') + +< Can also be used as a |method|: > + GetWinnr()->getwinvar(varname) < glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* Expand the file wildcards in {expr}. See |wildcards| for the @@ -5441,6 +5650,9 @@ glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* See |expand()| for expanding special Vim variables. See |system()| for getting the raw output of an external command. + Can also be used as a |method|: > + GetExpr()->glob() + glob2regpat({string}) *glob2regpat()* Convert a file pattern, as used by glob(), into a search pattern. The result can be used to match with a string that @@ -5453,7 +5665,9 @@ glob2regpat({string}) *glob2regpat()* Note that the result depends on the system. On MS-Windows a backslash usually means a path separator. - *globpath()* + Can also be used as a |method|: > + GetExpr()->glob2regpat() +< *globpath()* globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]]) Perform glob() for String {expr} on all directories in {path} and concatenate the results. Example: > @@ -5489,6 +5703,10 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]]) < Upwards search and limiting the depth of "**" is not supported, thus using 'path' will not always work properly. + Can also be used as a |method|, the base is passed as the + second argument: > + GetExpr()->globpath(&rtp) +< *has()* has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The {feature} argument is a feature name like "nvim-0.2.1" or @@ -5557,8 +5775,9 @@ has_key({dict}, {key}) *has_key()* mydict->has_key(key) haslocaldir([{winnr}[, {tabnr}]]) *haslocaldir()* - The result is a Number, which is 1 when the tabpage or window - has set a local path via |:tcd| or |:lcd|, otherwise 0. + The result is a Number, which is 1 when the window has set a + local path via |:lcd| or when {winnr} is -1 and the tabpage + has set a local path via |:tcd|, otherwise 0. Tabs and windows are identified by their respective numbers, 0 means current tab or window. Missing argument implies 0. @@ -5570,6 +5789,10 @@ haslocaldir([{winnr}[, {tabnr}]]) *haslocaldir()* With {winnr} and {tabnr} use the window in that tabpage. {winnr} can be the window number or the |window-ID|. If {winnr} is -1 it is ignored, only the tab is resolved. + Throw error if the arguments are invalid. |E5000| |E5001| |E5002| + + Can also be used as a |method|: > + GetWinnr()->haslocaldir() hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* The result is a Number, which is TRUE if there is a mapping @@ -5585,7 +5808,9 @@ hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* If no matching mapping is found FALSE is returned. The following characters are recognized in {mode}: n Normal mode - v Visual mode + v Visual and Select mode + x Visual mode + s Select mode o Operator-pending mode i Insert mode l Language-Argument ("r", "f", "t", etc.) @@ -5600,6 +5825,9 @@ hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* < This installs the mapping to "\ABCdoit" only if there isn't already a mapping to "\ABCdoit". + Can also be used as a |method|: > + GetRHS()->hasmapto() + histadd({history}, {item}) *histadd()* Add the String {item} to the history {history} which can be one of: *hist-names* @@ -5621,6 +5849,10 @@ histadd({history}, {item}) *histadd()* :let date=input("Enter date: ") < This function is not available in the |sandbox|. + Can also be used as a |method|, the base is used for the + second argument: > + GetPattern()->histadd('search') + histdel({history} [, {item}]) *histdel()* Clear {history}, i.e. delete all its entries. See |hist-names| for the possible values of {history}. @@ -5652,6 +5884,9 @@ histdel({history} [, {item}]) *histdel()* the "n" command and 'hlsearch': > :call histdel("search", -1) :let @/ = histget("search", -1) +< + Can also be used as a |method|: > + GetHistory()->histdel() histget({history} [, {index}]) *histget()* The result is a String, the entry with Number {index} from @@ -5668,6 +5903,9 @@ histget({history} [, {index}]) *histget()* the {num}th entry from the output of |:history|. > :command -nargs=1 H execute histget("cmd", 0+<args>) < + Can also be used as a |method|: > + GetHistory()->histget() + histnr({history}) *histnr()* The result is the Number of the current entry in {history}. See |hist-names| for the possible values of {history}. @@ -5675,6 +5913,9 @@ histnr({history}) *histnr()* Example: > :let inp_index = histnr("expr") + +< Can also be used as a |method|: > + GetHistory()->histnr() < hlexists({name}) *hlexists()* The result is a Number, which is TRUE if a highlight group @@ -5683,6 +5924,9 @@ hlexists({name}) *hlexists()* been defined for it, it may also have been used for a syntax item. + Can also be used as a |method|: > + GetName()->hlexists() +< *hlID()* hlID({name}) The result is a Number, which is the ID of the highlight group with name {name}. When the highlight group doesn't exist, @@ -5691,6 +5935,9 @@ hlID({name}) The result is a Number, which is the ID of the highlight group group. For example, to get the background color of the "Comment" group: > :echo synIDattr(synIDtrans(hlID("Comment")), "bg") +< + Can also be used as a |method|: > + GetName()->hlID() hostname() *hostname()* The result is a String, which is the name of the machine on @@ -5709,6 +5956,9 @@ iconv({string}, {from}, {to}) *iconv()* from/to UCS-2 is automatically changed to use UTF-8. You cannot use UCS-2 in a string anyway, because of the NUL bytes. + Can also be used as a |method|: > + GetText()->iconv('latin1', 'utf-8') +< *indent()* indent({lnum}) The result is a Number, which is indent of line {lnum} in the current buffer. The indent is counted in spaces, the value @@ -5716,6 +5966,8 @@ indent({lnum}) The result is a Number, which is indent of line {lnum} in the |getline()|. When {lnum} is invalid -1 is returned. + Can also be used as a |method|: > + GetLnum()->indent() index({object}, {expr} [, {start} [, {ic}]]) *index()* If {object} is a |List| return the lowest index where the item @@ -5736,6 +5988,8 @@ index({object}, {expr} [, {start} [, {ic}]]) *index()* :let idx = index(words, "the") :if index(numbers, 123) >= 0 +< Can also be used as a |method|: > + GetObject()->index(what) input({prompt} [, {text} [, {completion}]]) *input()* input({opts}) @@ -5848,6 +6102,9 @@ input({opts}) : call inputrestore() :endfunction +< Can also be used as a |method|: > + GetPrompt()->input() + inputlist({textlist}) *inputlist()* {textlist} must be a |List| of strings. This |List| is displayed, one string per line. The user will be prompted to @@ -5865,6 +6122,9 @@ inputlist({textlist}) *inputlist()* let color = inputlist(['Select color:', '1. red', \ '2. green', '3. blue']) +< Can also be used as a |method|: > + GetChoices()->inputlist() + inputrestore() *inputrestore()* Restore typeahead that was saved with a previous |inputsave()|. Should be called the same number of times inputsave() is @@ -5890,6 +6150,9 @@ inputsecret({prompt} [, {text}]) *inputsecret()* typed on the command-line in response to the issued prompt. NOTE: Command-line completion is not supported. + Can also be used as a |method|: > + GetPrompt()->inputsecret() + insert({object}, {item} [, {idx}]) *insert()* When {object} is a |List| or a |Blob| insert {item} at the start of it. @@ -5936,6 +6199,9 @@ isdirectory({directory}) *isdirectory()* exist, or isn't a directory, the result is |FALSE|. {directory} is any expression, which is used as a String. + Can also be used as a |method|: > + GetName()->isdirectory() + isinf({expr}) *isinf()* Return 1 if {expr} is a positive infinity, or -1 a negative infinity, otherwise 0. > @@ -5961,6 +6227,9 @@ islocked({expr}) *islocked()* *E786* < When {expr} is a variable that does not exist you get an error message. Use |exists()| to check for existence. + Can also be used as a |method|: > + GetName()->islocked() + id({expr}) *id()* Returns a |String| which is a unique identifier of the container type (|List|, |Dict|, |Blob| and |Partial|). It is @@ -6145,6 +6414,9 @@ json_decode({expr}) *json_decode()* recommended and the only one required to be supported. Non-UTF-8 characters are an error. + Can also be used as a |method|: > + ReadObject()->json_decode() + json_encode({expr}) *json_encode()* Convert {expr} into a JSON string. Accepts |msgpack-special-dict| as the input. Will not convert @@ -6157,6 +6429,9 @@ json_encode({expr}) *json_encode()* or special escapes like "\t", other are dumped as-is. |Blob|s are converted to arrays of the individual bytes. + Can also be used as a |method|: > + GetObject()->json_encode() + keys({dict}) *keys()* Return a |List| with all the keys of {dict}. The |List| is in arbitrary order. Also see |items()| and |values()|. @@ -6220,6 +6495,10 @@ libcall({libname}, {funcname}, {argument}) object code must be compiled as position-independent ('PIC'). Examples: > :echo libcall("libc.so", "getenv", "HOME") + +< Can also be used as a |method|, where the base is passed as + the argument to the called function: > + GetValue()->libcall("libc.so", "getenv") < *libcallnr()* libcallnr({libname}, {funcname}, {argument}) @@ -6230,8 +6509,12 @@ libcallnr({libname}, {funcname}, {argument}) :call libcallnr("libc.so", "printf", "Hello World!\n") :call libcallnr("libc.so", "sleep", 10) < - *line()* -line({expr}) The result is a Number, which is the line number of the file + Can also be used as a |method|, where the base is passed as + the argument to the called function: > + GetValue()->libcallnr("libc.so", "printf") +< +line({expr} [, {winid}]) *line()* + The result is a Number, which is the line number of the file position given with {expr}. The {expr} argument is a string. The accepted positions are: . the cursor position @@ -6250,10 +6533,16 @@ line({expr}) The result is a Number, which is the line number of the file then applies to another buffer. To get the column number use |col()|. To get both use |getpos()|. + With the optional {winid} argument the values are obtained for + that window instead of the current window. Examples: > line(".") line number of the cursor + line(".", winid) idem, in window "winid" line("'t") line number of mark t line("'" . marker) line number of mark marker +< + Can also be used as a |method|: > + GetValue()->line() line2byte({lnum}) *line2byte()* Return the byte count from the start of the buffer for line @@ -6268,6 +6557,9 @@ line2byte({lnum}) *line2byte()* |getline()|. When {lnum} is invalid -1 is returned. Also see |byte2line()|, |go| and |:goto|. + Can also be used as a |method|: > + GetLnum()->line2byte() + lispindent({lnum}) *lispindent()* Get the amount of indent for line {lnum} according the lisp indenting rules, as with 'lisp'. @@ -6275,6 +6567,9 @@ lispindent({lnum}) *lispindent()* relevant. {lnum} is used just like in |getline()|. When {lnum} is invalid, -1 is returned. + Can also be used as a |method|: > + GetLnum()->lispindent() + list2str({list} [, {utf8}]) *list2str()* Convert each number in {list} to a character string can concatenate them all. Examples: > @@ -6284,11 +6579,14 @@ list2str({list} [, {utf8}]) *list2str()* join(map(list, {nr, val -> nr2char(val)}), '') < |str2list()| does the opposite. - When {utf8} is omitted or zero, the current 'encoding' is used. - With {utf8} is 1, always return utf-8 characters. - With utf-8 composing characters work as expected: > + UTF-8 encoding is always used, {utf8} option has no effect, + and exists only for backwards-compatibility. + With UTF-8 composing characters work as expected: > list2str([97, 769]) returns "á" < + Can also be used as a |method|: > + GetList()->list2str() + localtime() *localtime()* Return the current time, measured as seconds since 1st Jan 1970. See also |strftime()|, |strptime()| and |getftime()|. @@ -6323,6 +6621,9 @@ luaeval({expr}[, {expr}]) Evaluate Lua expression {expr} and return its result converted to Vim data structures. See |lua-eval| for more details. + Can also be used as a |method|: > + GetExpr()->luaeval() + map({expr1}, {expr2}) *map()* {expr1} must be a |List|, |Blob| or |Dictionary|. Replace each item in {expr1} with the result of evaluating @@ -6430,6 +6731,8 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* mapped, and have it do the original mapping too. Sketch: > exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n') +< Can also be used as a |method|: > + GetKey()->maparg('n') mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* Check if there is a mapping that matches with {name} in mode @@ -6464,6 +6767,9 @@ mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* < This avoids adding the "_vv" mapping when there already is a mapping for "_v" or for "_vvv". + Can also be used as a |method|: > + GetKey()->mapcheck('n') + match({expr}, {pat} [, {start} [, {count}]]) *match()* When {expr} is a |List| then this returns the index of the first item where {pat} matches. Each item is used as a @@ -6526,6 +6832,9 @@ match({expr}, {pat} [, {start} [, {count}]]) *match()* zero matches at the start instead of a number of matches further down in the text. + Can also be used as a |method|: > + GetList()->match('word') +< *matchadd()* *E798* *E799* *E801* *E957* matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) Defines a pattern to be highlighted in the current window (a @@ -6581,6 +6890,9 @@ matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) available from |getmatches()|. All matches can be deleted in one operation by |clearmatches()|. + Can also be used as a |method|: > + GetGroup()->matchadd('TODO') +< *matchaddpos()* matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) Same as |matchadd()|, but requires a list of positions {pos} @@ -6619,6 +6931,9 @@ matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) < Matches added by |matchaddpos()| are returned by |getmatches()|. + Can also be used as a |method|: > + GetGroup()->matchaddpos([23, 11]) + matcharg({nr}) *matcharg()* Selects the {nr} match item, as set with a |:match|, |:2match| or |:3match| command. @@ -6631,6 +6946,9 @@ matcharg({nr}) *matcharg()* Highlighting matches using the |:match| commands are limited to three matches. |matchadd()| does not have this limitation. + Can also be used as a |method|: > + GetMatch()->matcharg() + matchdelete({id} [, {win}]) *matchdelete()* *E802* *E803* Deletes a match with ID {id} previously defined by |matchadd()| or one of the |:match| commands. Returns 0 if successful, @@ -6639,6 +6957,9 @@ matchdelete({id} [, {win}]) *matchdelete()* *E802* *E803* If {win} is specified, use the window with this number or window ID instead of the current window. + Can also be used as a |method|: > + GetMatch()->matchdelete() + matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()* Same as |match()|, but return the index of first character after the match. Example: > @@ -6658,6 +6979,9 @@ matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()* < result is "-1". When {expr} is a |List| the result is equal to |match()|. + Can also be used as a |method|: > + GetText()->matchend('word') + matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* Same as |match()|, but return a |List|. The first item in the list is the matched string, same as what matchstr() would @@ -6668,6 +6992,9 @@ matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] When there is no match an empty list is returned. + Can also be used as a |method|: > + GetList()->matchlist('word') + matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* Same as |match()|, but return the matched string. Example: > :echo matchstr("testing", "ing") @@ -6681,6 +7008,9 @@ matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* When {expr} is a |List| then the matching item is returned. The type isn't changed, it's not necessarily a String. + Can also be used as a |method|: > + GetText()->matchstr('word') + matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* Same as |matchstr()|, but return the matched string, the start position and the end position of the match. Example: > @@ -6699,6 +7029,9 @@ matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* < result is ["x", 1, 2, 3]. The type isn't changed, it's not necessarily a String. + Can also be used as a |method|: > + GetText()->matchstrpos('word') + *max()* max({expr}) Return the maximum value of all items in {expr}. {expr} can be a |List| or a |Dictionary|. For a Dictionary, @@ -6789,6 +7122,9 @@ mkdir({name} [, {path} [, {prot}]]) successful or FALSE if the directory creation failed or partly failed. + Can also be used as a |method|: > + GetName()->mkdir() +< *mode()* mode([expr]) Return a string that indicates the current mode. If [expr] is supplied and it evaluates to a non-zero Number or @@ -6804,30 +7140,34 @@ mode([expr]) Return a string that indicates the current mode. niI Normal using |i_CTRL-O| in |Insert-mode| niR Normal using |i_CTRL-O| in |Replace-mode| niV Normal using |i_CTRL-O| in |Virtual-Replace-mode| + nt Normal in |terminal-emulator| (insert goes to + Terminal mode) v Visual by character + vs Visual by character using |v_CTRL-O| in Select mode V Visual by line + Vs Visual by line using |v_CTRL-O| in Select mode CTRL-V Visual blockwise + CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode s Select by character S Select by line CTRL-S Select blockwise - vs Visual by character using |v_CTRL-O| from - Select mode - Vs Visual by line using |v_CTRL-O| from Select mode - CTRL-Vs Visual blockwise using |v_CTRL-O| from Select mode i Insert ic Insert mode completion |compl-generic| ix Insert mode |i_CTRL-X| completion R Replace |R| Rc Replace mode completion |compl-generic| - Rv Virtual Replace |gR| Rx Replace mode |i_CTRL-X| completion + Rv Virtual Replace |gR| + Rvc Virtual Replace mode completion |compl-generic| + Rvx Virtual Replace mode |i_CTRL-X| completion c Command-line editing cv Vim Ex mode |Q| or |gQ| r Hit-enter prompt rm The -- more -- prompt - r? |:confirm| query of some sort + r? A |:confirm| query of some sort ! Shell or external command is executing t Terminal mode: keys go to the job + This is useful in the 'statusline' option or when used with |remote_expr()| In most other places it always returns "c" or "n". @@ -6836,6 +7176,9 @@ mode([expr]) Return a string that indicates the current mode. the leading character(s). Also see |visualmode()|. + Can also be used as a |method|: > + DoFull()->mode() + msgpackdump({list} [, {type}]) *msgpackdump()* Convert a list of VimL objects to msgpack. Returned value is a |readfile()|-style list. When {type} contains "B", a |Blob| is @@ -6938,6 +7281,9 @@ nextnonblank({lnum}) *nextnonblank()* {lnum} is used like with |getline()|. See also |prevnonblank()|. + Can also be used as a |method|: > + GetLnum()->nextnonblank() + nr2char({expr} [, {utf8}]) *nr2char()* Return a string with a single character, which has the number value {expr}. Examples: > @@ -6952,6 +7298,9 @@ nr2char({expr} [, {utf8}]) *nr2char()* characters. nr2char(0) is a real NUL and terminates the string, thus results in an empty string. + Can also be used as a |method|: > + GetNumber()->nr2char() + nvim_...({...}) *E5555* *nvim_...()* *eval-api* Call nvim |api| functions. The type checking of arguments will be stricter than for most other builtins. For instance, @@ -6980,6 +7329,9 @@ pathshorten({path}) *pathshorten()* < ~/.c/n/a/file1.vim ~ It doesn't matter if the path exists or not. + Can also be used as a |method|: > + GetDirectories()->pathshorten() + perleval({expr}) *perleval()* Evaluate |perl| expression {expr} and return its result converted to Vim data structures. @@ -6995,6 +7347,9 @@ perleval({expr}) *perleval()* :echo perleval('[1 .. 4]') < [1, 2, 3, 4] + Can also be used as a |method|: > + GetExpr()->perleval() + pow({x}, {y}) *pow()* Return the power of {x} to the exponent {y} as a |Float|. {x} and {y} must evaluate to a |Float| or a |Number|. @@ -7018,6 +7373,8 @@ prevnonblank({lnum}) *prevnonblank()* {lnum} is used like with |getline()|. Also see |nextnonblank()|. + Can also be used as a |method|: > + GetLnum()->prevnonblank() printf({fmt}, {expr1} ...) *printf()* Return a String with {fmt}, where "%" items are replaced by @@ -7250,6 +7607,9 @@ prompt_setcallback({buf}, {expr}) *prompt_setcallback()* endif endfunc +< Can also be used as a |method|: > + GetBuffer()->prompt_setcallback(callback) + prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()* Set a callback for buffer {buf} to {expr}. When {expr} is an empty string the callback is removed. This has only effect if @@ -7259,12 +7619,18 @@ prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()* mode. Without setting a callback Vim will exit Insert mode, as in any buffer. + Can also be used as a |method|: > + GetBuffer()->prompt_setinterrupt(callback) + prompt_setprompt({buf}, {text}) *prompt_setprompt()* Set prompt for buffer {buf} to {text}. You most likely want {text} to end in a space. The result is only visible if {buf} has 'buftype' set to "prompt". Example: > call prompt_setprompt(bufnr(''), 'command: ') +< + Can also be used as a |method|: > + GetBuffer()->prompt_setprompt('command: ') pum_getpos() *pum_getpos()* If the popup menu (see |ins-completion-menu|) is not visible, @@ -7295,6 +7661,9 @@ py3eval({expr}) *py3eval()* Dictionaries are represented as Vim |Dictionary| type with keys converted to strings. + Can also be used as a |method|: > + GetExpr()->py3eval() +< *E858* *E859* pyeval({expr}) *pyeval()* Evaluate Python expression {expr} and return its result @@ -7305,12 +7674,18 @@ pyeval({expr}) *pyeval()* Dictionaries are represented as Vim |Dictionary| type, non-string keys result in error. + Can also be used as a |method|: > + GetExpr()->pyeval() + pyxeval({expr}) *pyxeval()* Evaluate Python expression {expr} and return its result converted to Vim data structures. Uses Python 2 or 3, see |python_x| and 'pyxversion'. See also: |pyeval()|, |py3eval()| + Can also be used as a |method|: > + GetExpr()->pyxeval() +< *E726* *E727* range({expr} [, {max} [, {stride}]]) *range()* Returns a |List| with Numbers: @@ -7330,6 +7705,9 @@ range({expr} [, {max} [, {stride}]]) *range()* range(0) " [] range(2, 0) " error! < + Can also be used as a |method|: > + GetExpr()->range() +< *readdir()* readdir({directory} [, {expr}]) Return a list with file and directory names in {directory}. @@ -7357,6 +7735,9 @@ readdir({directory} [, {expr}]) endfunction echo s:tree(".") < + Can also be used as a |method|: > + GetDirName()->readdir() +< *readfile()* readfile({fname} [, {type} [, {max}]]) Read file {fname} and return a |List|, each line of the file @@ -7390,6 +7771,9 @@ readfile({fname} [, {type} [, {max}]]) the result is an empty list. Also see |writefile()|. + Can also be used as a |method|: > + GetFileName()->readfile() + reg_executing() *reg_executing()* Returns the single letter name of the register being executed. Returns an empty string when no register is being executed. @@ -7417,6 +7801,9 @@ reltime([{start} [, {end}]]) *reltime()* The {start} and {end} arguments must be values returned by reltime(). + Can also be used as a |method|: > + GetStart()->reltime() +< Note: |localtime()| returns the current (non-relative) time. reltimefloat({time}) *reltimefloat()* @@ -7430,6 +7817,9 @@ reltimefloat({time}) *reltimefloat()* Also see |profiling|. If there is an error an empty string is returned + Can also be used as a |method|: > + reltime(start)->reltimefloat() + reltimestr({time}) *reltimestr()* Return a String that represents the time value of {time}. This is the number of seconds, a dot and the number of @@ -7444,6 +7834,9 @@ reltimestr({time}) *reltimestr()* < Also see |profiling|. If there is an error an empty string is returned + Can also be used as a |method|: > + reltime(start)->reltimestr() +< *remote_expr()* *E449* remote_expr({server}, {string} [, {idvar} [, {timeout}]]) Send the {string} to {server}. The string is sent as an @@ -7576,6 +7969,9 @@ rename({from}, {to}) *rename()* NOTE: If {to} exists it is overwritten without warning. This function is not available in the |sandbox|. + Can also be used as a |method|: > + GetOldName()->rename(newname) + repeat({expr}, {count}) *repeat()* Repeat {expr} {count} times and return the concatenated result. Example: > @@ -7602,6 +7998,9 @@ resolve({filename}) *resolve()* *E655* current directory (provided the result is still a relative path name) and also keeps a trailing path separator. + Can also be used as a |method|: > + GetName()->resolve() +< *reverse()* reverse({object}) Reverse the order of items in {object} in-place. @@ -7656,6 +8055,9 @@ rubyeval({expr}) *rubyeval()* Other objects are represented as strings resulted from their "Object#to_s" method. + Can also be used as a |method|: > + GetRubyExpr()->rubyeval() + screenattr({row}, {col}) *screenattr()* Like |screenchar()|, but return the attribute. This is a rather arbitrary number that can only be used to compare to the @@ -8219,6 +8621,9 @@ setfperm({fname}, {mode}) *setfperm()* *chmod* Returns non-zero for success, zero for failure. + Can also be used as a |method|: > + GetFilename()->setfperm(mode) +< To read permissions see |getfperm()|. setline({lnum}, {text}) *setline()* @@ -8435,8 +8840,8 @@ setreg({regname}, {value} [, {options}]) Set the register {regname} to {value}. The {regname} argument is a string. - {value} may be any value returned by |getreg()|, including - a |List|. + {value} may be any value returned by |getreg()| or + |getreginfo()|, including a |List| or |Dict|. If {options} contains "a" or {regname} is upper case, then the value is appended. @@ -8466,9 +8871,13 @@ setreg({regname}, {value} [, {options}]) :call setreg(v:register, @*) :call setreg('*', @%, 'ac') :call setreg('a', "1\n2\n3", 'b5') + :call setreg('"', { 'points_to': 'a'}) < This example shows using the functions to save and restore a register: > + :let var_a = getreginfo() + :call setreg('a', var_a) +< or: > :let var_a = getreg('a', 1, 1) :let var_amode = getregtype('a') .... @@ -8906,10 +9315,9 @@ str2list({string} [, {utf8}]) *str2list()* str2list("ABC") returns [65, 66, 67] < |list2str()| does the opposite. - When {utf8} is omitted or zero, the current 'encoding' is used. - With {utf8} set to TRUE, always treat the String as utf-8 - characters. With utf-8 composing characters are handled - properly: > + UTF-8 encoding is always used, {utf8} option has no effect, + and exists only for backwards-compatibility. + With UTF-8 composing characters are handled properly: > str2list("á") returns [97, 769] < Can also be used as a |method|: > @@ -10921,7 +11329,7 @@ text... literal then the items also cannot be changed: > const ll = [1, 2, 3] let ll[1] = 5 " Error! -< Nested references are not locked: > +< Nested references are not locked: > let lvar = ['a'] const lconst = [0, lvar] let lconst[0] = 2 " Error! diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 4d0fdd71cc..42a9993c8c 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -501,6 +501,14 @@ One command, :DiffGitCached, is provided to show a diff of the current commit in the preview window. It is equivalent to calling "git diff --cached" plus any arguments given to the command. +GPROF *ft-gprof-plugin* + +The gprof filetype plugin defines a mapping <C-]> to jump from a function +entry in the gprof flat profile or from a function entry in the call graph +to the details of that function in the call graph. + +The mapping can be disabled with: > + let g:no_gprof_maps = 1 MAIL *ft-mail-plugin* diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index 4a94701b2e..aaa2a35fe1 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -389,17 +389,5 @@ highlighting. So do these: You can find the details in $VIMRUNTIME/syntax/help.vim - *inclusion* -Vim is for everybody, no matter race, gender or anything. Some people make a -big deal about using "he" or "his" when referring to the user, thinking it -means we assume the user is male. That is not the case, it's just a habit of -writing help text, which quite often is many years old. Also, a lot of the -text is written by contributors for whom English is not their first language. -We do not make any assumptions about the gender of the user, no matter how the -text is phrased. Some people have suggested using "they", but that is not -regular English. We do not want to spend much time on this discussion. The -goal is that the reader understands how Vim works, the exact wording is -secondary. - vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index 2baf3a247f..a89263861b 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -55,7 +55,7 @@ Nvim on the interwebs *internet* Nvim home page: https://neovim.io/ Nvim FAQ: https://github.com/neovim/neovim/wiki/FAQ Downloads: https://github.com/neovim/neovim/releases - Vim FAQ: https://vimhelp.appspot.com/vim_faq.txt.html + Vim FAQ: https://vimhelp.org/vim_faq.txt.html *bugs* *bug-report* @@ -312,7 +312,6 @@ notation meaning equivalent decimal value(s) ~ <Tab> tab CTRL-I 9 *tab* *Tab* *linefeed* <NL> linefeed CTRL-J 10 (used for <Nul>) -<FF> formfeed CTRL-L 12 *formfeed* <CR> carriage return CTRL-M 13 *carriage-return* <Return> same as <CR> *<Return>* <Enter> same as <CR> *<Enter>* diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 48d65a22b6..5549d3c180 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -224,6 +224,11 @@ For |lsp-request|, each |lsp-handler| has this signature: > The ID of the |vim.lsp.client|. {bufnr} (Buffer) Buffer handle, or 0 for current. + + {params} (table|nil) + The parameters used in the original request + which resulted in this handler + call. {config} (table) Configuration for the handler. @@ -234,6 +239,7 @@ For |lsp-request|, each |lsp-handler| has this signature: > To configure a particular |lsp-handler|, see: |lsp-handler-configuration| + Returns: ~ The |lsp-handler| can respond by returning two values: `result, err` Where `err` must be shaped like an RPC error: @@ -622,6 +628,10 @@ client_is_stopped({client_id}) *vim.lsp.client_is_stopped()* flush({client}) *vim.lsp.flush()* TODO: Documentation + *vim.lsp.for_each_buffer_client()* +for_each_buffer_client({bufnr}, {fn}) + TODO: Documentation + get_active_clients() *vim.lsp.get_active_clients()* Gets all active clients. @@ -660,7 +670,7 @@ omnifunc({findstart}, {base}) *vim.lsp.omnifunc()* {base} If findstart=0, text to match against Return: ~ - (number) Decided by`findstart`: + (number) Decided by {findstart}: • findstart=0: column where the completion starts, or -2 or -3 • findstart=1: list of matches (actually just calls @@ -863,12 +873,17 @@ clear_references() *vim.lsp.buf.clear_references()* Removes document highlights from current buffer. code_action({context}) *vim.lsp.buf.code_action()* - Selects a code action from the input list that is available at - the current cursor position. + Selects a code action available at the current cursor + position. Parameters: ~ - {context} (table, optional) Valid `CodeActionContext` - object + {context} table|nil `CodeActionContext` of the LSP specification: + • diagnostics: (table|nil) LSP`Diagnostic[]` . Inferred from the current position if not + provided. + • only: (string|nil) LSP `CodeActionKind` used + to filter the code actions. Most language + servers support values like `refactor` or + `quickfix` . See also: ~ https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction @@ -1004,13 +1019,21 @@ outgoing_calls() *vim.lsp.buf.outgoing_calls()* cursor in the |quickfix| window. If the symbol can resolve to multiple items, the user can pick one in the |inputlist|. +prepare_rename({err}, {result}) *vim.lsp.buf.prepare_rename()* + TODO: Documentation + *vim.lsp.buf.range_code_action()* range_code_action({context}, {start_pos}, {end_pos}) Performs |vim.lsp.buf.code_action()| for a given range. Parameters: ~ - {context} (table, optional) Valid `CodeActionContext` - object + {context} table|nil `CodeActionContext` of the LSP specification: + • diagnostics: (table|nil) LSP`Diagnostic[]` . Inferred from the current position if not + provided. + • only: (string|nil) LSP `CodeActionKind` + used to filter the code actions. Most + language servers support values like + `refactor` or `quickfix` . {start_pos} ({number, number}, optional) mark-indexed position. Defaults to the start of the last visual selection. @@ -1235,8 +1258,8 @@ apply_text_edits({text_edits}, {bufnr}) Applies a list of text edits to a buffer. Parameters: ~ - {text_edits} (table) list of `TextEdit` objects - {buf_nr} (number) Buffer id + {text_edits} table list of `TextEdit` objects + {bufnr} number Buffer id See also: ~ https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit @@ -1456,6 +1479,13 @@ make_floating_popup_options({width}, {height}, {opts}) {width} (number) window width (in character cells) {height} (number) window height (in character cells) {opts} (table, optional) + • offset_x (number) offset to add to `col` + • offset_y (number) offset to add to `row` + • border (string or table) override `border` + • focusable (string or table) override + `focusable` + • zindex (string or table) override `zindex` , + defaults to 50 Return: ~ (table) Options @@ -1546,10 +1576,6 @@ open_floating_preview({contents}, {syntax}, {opts}) height when wrap is enabled • max_width maximal width of floating window • max_height maximal height of floating window - • pad_left number of columns to pad contents - at left - • pad_right number of columns to pad contents - at right • pad_top number of lines to pad contents at top • pad_bottom number of lines to pad contents @@ -1569,10 +1595,10 @@ parse_snippet({input}) *vim.lsp.util.parse_snippet()* Parses snippets in a completion entry. Parameters: ~ - {input} (string) unparsed snippet + {input} string unparsed snippet Return: ~ - (string) parsed snippet + string parsed snippet preview_location({location}, {opts}) *vim.lsp.util.preview_location()* Previews a location in a floating window @@ -1633,10 +1659,6 @@ stylize_markdown({bufnr}, {contents}, {opts}) height • max_width maximal width of floating window • max_height maximal height of floating window - • pad_left number of columns to pad contents - at left - • pad_right number of columns to pad contents - at right • pad_top number of lines to pad contents at top • pad_bottom number of lines to pad contents @@ -1703,6 +1725,16 @@ get_filename() *vim.lsp.log.get_filename()* Return: ~ (string) log filename +get_level() *vim.lsp.log.get_level()* + TODO: Documentation + +set_format_func({handle}) *vim.lsp.log.set_format_func()* + Sets formatting function used to format logs + + Parameters: ~ + {handle} function function to apply to logging arguments, + pass vim.inspect for multi-line formatting + set_level({level}) *vim.lsp.log.set_level()* Sets the current log level. diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 53d68fa5e6..fe94e89e2a 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -928,6 +928,7 @@ Example: > vim.g.foo = 5 -- Set the g:foo Vimscript variable. print(vim.g.foo) -- Get and print the g:foo Vimscript variable. vim.g.foo = nil -- Delete (:unlet) the Vimscript variable. + vim.b[2].foo = 6 -- Set b:foo for buffer 2 vim.g *vim.g* Global (|g:|) editor variables. @@ -935,15 +936,18 @@ vim.g *vim.g* vim.b *vim.b* Buffer-scoped (|b:|) variables for the current buffer. - Invalid or unset key returns `nil`. + Invalid or unset key returns `nil`. Can be indexed with + an integer to access variables for a specific buffer. vim.w *vim.w* Window-scoped (|w:|) variables for the current window. - Invalid or unset key returns `nil`. + Invalid or unset key returns `nil`. Can be indexed with + an integer to access variables for a specific window. vim.t *vim.t* Tabpage-scoped (|t:|) variables for the current tabpage. - Invalid or unset key returns `nil`. + Invalid or unset key returns `nil`. Can be indexed with + an integer to access variables for a specific tabpage. vim.v *vim.v* |v:| variables. @@ -1206,6 +1210,36 @@ notify({msg}, {log_level}, {_opts}) *vim.notify()* See also: ~ :help nvim_notify +on_key({fn}, {ns_id}) *vim.on_key()* + Adds Lua function {fn} with namespace id {ns_id} as a listener + to every, yes every, input key. + + The Nvim command-line option |-w| is related but does not + support callbacks and cannot be toggled dynamically. + + Note: + {fn} will not be cleared by |nvim_buf_clear_namespace()| + + Note: + {fn} will receive the keys after mappings have been + evaluated + + Parameters: ~ + {fn} function: Callback function. It should take one + string argument. On each key press, Nvim passes + the key char to fn(). |i_CTRL-V| If {fn} is nil, + it removes the callback for the associated + {ns_id} + {ns_id} number? Namespace ID. If nil or 0, generates and + returns a new |nvim_create_namesapce()| id. + + Return: ~ + number Namespace id associated with {fn}. Or count of all + callbacks if on_key() is called without arguments. + + Note: + {fn} will be removed if an error occurs while calling. + paste({lines}, {phase}) *vim.paste()* Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the |TUI|) pastes text into the editor. @@ -1268,8 +1302,7 @@ schedule_wrap({cb}) *vim.schedule_wrap()* deep_equal({a}, {b}) *vim.deep_equal()* Deep compare values for equality - Tables are compared recursively unless they both provide the `eq` methamethod. - All other types are compared using the equality `==` operator. + Tables are compared recursively unless they both provide the `eq` methamethod. All other types are compared using the equality `==` operator. Parameters: ~ {a} first value @@ -1373,20 +1406,25 @@ pesc({s}) *vim.pesc()* See also: ~ https://github.com/rxi/lume -split({s}, {sep}, {plain}) *vim.split()* +split({s}, {sep}, {kwargs}) *vim.split()* Splits a string at each instance of a separator. Examples: > - split(":aa::b:", ":") --> {'','aa','','b',''} - split("axaby", "ab?") --> {'','x','y'} - split(x*yz*o, "*", true) --> {'x','yz','o'} + + split(":aa::b:", ":") --> {'','aa','','b',''} + split("axaby", "ab?") --> {'','x','y'} + split("x*yz*o", "*", {plain=true}) --> {'x','yz','o'} + split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'} < Parameters: ~ - {s} String to split - {sep} Separator string or pattern - {plain} If `true` use `sep` literally (passed to - String.find) + {s} String to split + {sep} Separator string or pattern + {kwargs} Keyword arguments: + • plain: (boolean) If `true` use `sep` literally + (passed to string.find) + • trimempty: (boolean) If `true` remove empty + items from the front and back of the list Return: ~ List-like table of the split components. @@ -1484,7 +1522,7 @@ tbl_flatten({t}) *vim.tbl_flatten()* Flattened copy of the given list-like table. See also: ~ - Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua + From https://github.com/premake/premake-core/blob/master/src/base/table.lua tbl_isempty({t}) *vim.tbl_isempty()* Checks if a table is empty. @@ -1520,7 +1558,7 @@ tbl_keys({t}) *vim.tbl_keys()* list of keys See also: ~ - Fromhttps://github.com/premake/premake-core/blob/master/src/base/table.lua + From https://github.com/premake/premake-core/blob/master/src/base/table.lua tbl_map({func}, {t}) *vim.tbl_map()* Apply a function to all values of a table. @@ -1571,12 +1609,14 @@ validate({opt}) *vim.validate()* vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} => NOP (success) - - vim.validate{arg1={1, 'table'}} - => error('arg1: expected table, got number') - - vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} - => error('arg1: expected even number, got 3') +< +> + vim.validate{arg1={1, 'table'}} + => error('arg1: expected table, got number') +< +> + vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}} + => error('arg1: expected even number, got 3') < Parameters: ~ @@ -1645,4 +1685,25 @@ uri_to_fname({uri}) *vim.uri_to_fname()* Return: ~ Filename + +============================================================================== +Lua module: ui *lua-ui* + +select({items}, {opts}, {on_choice}) *vim.ui.select()* + Prompts the user to pick a single item from a collection of + entries + + Parameters: ~ + {items} table Arbitrary items + {opts} table Additional options + • prompt (string|nil) Text of the prompt. + Defaults to `Select one of:` + • format_item (function item -> text) + Function to format an individual item from + `items` . Defaults to `tostring` . + {on_choice} function ((item|nil, idx|nil) -> ()) Called + once the user made a choice. `idx` is the + 1-based index of `item` within `item` . `nil` + if the user aborted the dialog. + vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/mbyte.txt b/runtime/doc/mbyte.txt index a6c797a860..3bbf36c642 100644 --- a/runtime/doc/mbyte.txt +++ b/runtime/doc/mbyte.txt @@ -663,7 +663,7 @@ This file explains what characters are available in UTF-8 and CP1255 encodings, and what the keymaps are to get those characters: glyph encoding keymap ~ -Char utf-8 cp1255 hebrew hebrewp name ~ +Char UTF-8 cp1255 hebrew hebrewp name ~ א 0x5d0 0xe0 t a 'alef ב 0x5d1 0xe1 c b bet ג 0x5d2 0xe2 d g gimel @@ -716,11 +716,11 @@ Vowel marks and special punctuation: ױ 0x5f1 0xd5 VY VY vav-yod ײ 0x5f2 0xd6 YY YY yod-yod -The following are only available in utf-8 +The following are only available in UTF-8 Cantillation marks: glyph -Char utf-8 hebrew name +Char UTF-8 hebrew name ב֑ 0x591 C: etnahta ב֒ 0x592 Cs segol ב֓ 0x593 CS shalshelet @@ -803,7 +803,7 @@ ASCII. On MS-Windows UTF-16 is also used (previously UCS-2), which uses internally. Vim has comprehensive UTF-8 support. It works well in: -- xterm with utf-8 support enabled +- xterm with UTF-8 support enabled - MS-Windows GUI - several other platforms @@ -814,14 +814,14 @@ a space to fill the gap. *bom-bytes* When reading a file a BOM (Byte Order Mark) can be used to recognize the Unicode encoding: - EF BB BF utf-8 - FE FF utf-16 big endian - FF FE utf-16 little endian - 00 00 FE FF utf-32 big endian - FF FE 00 00 utf-32 little endian - -Utf-8 is the recommended encoding. Note that it's difficult to tell utf-16 -and utf-32 apart. Utf-16 is often used on MS-Windows, utf-32 is not + EF BB BF UTF-8 + FE FF UTF-16 big endian + FF FE UTF-16 little endian + 00 00 FE FF UTF-32 big endian + FF FE 00 00 UTF-32 little endian + +UTF-8 is the recommended encoding. Note that it's difficult to tell UTF-16 +and UTF-32 apart. UTF-16 is often used on MS-Windows, UTF-32 is not widespread as file format. @@ -888,10 +888,10 @@ Motif. Use the ":hi Menu font={fontname}" command for this. |:highlight| TYPING UTF-8 *utf-8-typing* If you are using X-Windows, you should find an input method that supports -utf-8. +UTF-8. -If your system does not provide support for typing utf-8, you can use the -'keymap' feature. This allows writing a keymap file, which defines a utf-8 +If your system does not provide support for typing UTF-8, you can use the +'keymap' feature. This allows writing a keymap file, which defines a UTF-8 character as a sequence of ASCII characters. See |mbyte-keymap|. If everything else fails, you can type any character as four hex bytes: > diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index 5ad69d1122..e83b17f9a0 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -53,7 +53,7 @@ next key is sent unless it is <C-N>. Use <C-\><C-N> to return to normal-mode. Terminal-mode forces these local options: - 'nocursorline' + 'cursorlineopt' = number 'nocursorcolumn' 'scrolloff' = 0 'sidescrolloff' = 0 @@ -171,7 +171,7 @@ program window A terminal window for the executed program. When "run" is The current window is used to show the source code. When gdb pauses the source file location will be displayed, if possible. A sign is used to -highlight the current position, using highlight group debugPC. +highlight the current position, using highlight group debugPC. If the buffer in the current window is modified, another window will be opened to display the current gdb position. @@ -222,7 +222,7 @@ Put focus on the gdb window and type: > run Vim will start running in the program window. Put focus there and type: > :help gui -Gdb will run into the ex_help breakpoint. The source window now shows the +Gdb will run into the ex_help breakpoint. The source window now shows the ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the breakpoint was set. The line where the debugger stopped is highlighted. You can now step through the program. You will see the highlighting move as the diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 853d774232..be397117b2 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -1159,9 +1159,9 @@ A jump table for the options with a short description can be found at |Q_op|. 'cdpath' 'cd' string (default: equivalent to $CDPATH or ",,") global This is a list of directories which will be searched when using the - |:cd| and |:lcd| commands, provided that the directory being searched - for has a relative path, not an absolute part starting with "/", "./" - or "../", the 'cdpath' option is not used then. + |:cd|, |:tcd| and |:lcd| commands, provided that the directory being + searched for has a relative path, not an absolute part starting with + "/", "./" or "../", the 'cdpath' option is not used then. The 'cdpath' option's value has the same form and semantics as |'path'|. Also see |file-searching|. The default value is taken from $CDPATH, with a "," prepended to look @@ -1409,9 +1409,9 @@ A jump table for the options with a short description can be found at |Q_op|. When this option is set it overrules 'shellslash' for completion: - When this option is set to "slash", a forward slash is used for path completion in insert mode. This is useful when editing HTML tag, or - Makefile with 'noshellslash' on Windows. + Makefile with 'noshellslash' on MS-Windows. - When this option is set to "backslash", backslash is used. This is - useful when editing a batch file with 'shellslash' set on Windows. + useful when editing a batch file with 'shellslash' set on MS-Windows. - When this option is empty, same character is used as for 'shellslash'. For Insert mode completion the buffer-local value is used. For @@ -5981,13 +5981,13 @@ A jump table for the options with a short description can be found at |Q_op|. return value of expr contains % items they will get expanded. The expression can contain the } character, the end of expression is denoted by %}. - The For example: > + For example: > func! Stl_filename() abort return "%t" endfunc < `stl=%{Stl_filename()}` results in `"%t"` `stl=%{%Stl_filename()%}` results in `"Name of current file"` - } - End of `{%` expression + %} - End of `{%` expression ( - Start of item group. Can be used for setting the width and alignment of a section. Must be followed by %) somewhere. ) - End of item group. No width fields allowed. @@ -6821,8 +6821,9 @@ A jump table for the options with a short description can be found at |Q_op|. More info here: |cmdline-completion|. The character is not recognized when used inside a macro. See 'wildcharm' for that. + Some keys will not work, such as CTRL-C, <CR> and Enter. Although 'wc' is a number option, you can set it to a special key: > - :set wc=<Esc> + :set wc=<Tab> < *'wildcharm'* *'wcm'* diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt index c49cc6d540..dfed39dba6 100644 --- a/runtime/doc/pattern.txt +++ b/runtime/doc/pattern.txt @@ -977,7 +977,7 @@ $ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on): /.*\%17v < Column 17 is highlighted by 'hlsearch' because there is another match where ".*" matches zero characters. -< + Character classes: \i identifier character (see 'isident' option) */\i* diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt index bb688770fc..179c1066cd 100644 --- a/runtime/doc/pi_health.txt +++ b/runtime/doc/pi_health.txt @@ -5,7 +5,7 @@ Author: TJ DeVries <devries.timothyj@gmail.com> Type |gO| to see the table of contents. ============================================================================== -Introduction *health* +Introduction *health* health.vim is a minimal framework to help with troubleshooting user configuration. Nvim ships with healthchecks for configuration, performance, @@ -18,65 +18,136 @@ To run the healthchecks, use this command: > Plugin authors are encouraged to write new healthchecks. |health-dev| ============================================================================== -Commands *health-commands* +Commands *health-commands* - *:checkhealth* *:CheckHealth* + *:checkhealth* *:CheckHealth* :checkhealth Run all healthchecks. - *E5009* - Nvim depends on |$VIMRUNTIME| and 'runtimepath' to find - the standard "runtime files" for syntax highlighting, - filetype-specific behavior, and standard plugins - (including :checkhealth). If the runtime files cannot - be found then those features will not work. + *E5009* + Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to + find the standard "runtime files" for syntax highlighting, + filetype-specific behavior, and standard plugins (including + :checkhealth). If the runtime files cannot be found then + those features will not work. :checkhealth {plugins} - Run healthcheck(s) for one or more plugins. E.g. to run - only the standard Nvim healthcheck: > + Run healthcheck(s) for one or more plugins. E.g. to run only + the standard Nvim healthcheck: > :checkhealth nvim -< To run the healthchecks for the "foo" and "bar" plugins - (assuming these plugins are on your 'runtimepath' and - they have implemented health#foo#check() and - health#bar#check(), respectively): > +< + To run the healthchecks for the "foo" and "bar" plugins + (assuming these plugins are on 'runtimepath' or 'packpath' and + they have implemented the Lua or Vimscript interface + require("foo.health").check() and health#bar#check(), + respectively): > :checkhealth foo bar < + To run healthchecks for lua submodules, use dot notation or + "*" to refer to all submodules. For example nvim provides + `vim.lsp` and `vim.treesitter` > + :checkhealth vim.lsp vim.treesitter + :checkhealth vim* +< ============================================================================== -Functions *health-functions* +Lua Functions *health-functions-lua* *health-lua* + +The Lua "health" module can be used to create new healthchecks (see also +|health-functions-vim|). To get started, simply use: > + local health = require('health') +< +health.report_start({name}) *health.report_start()* + Starts a new report. Most plugins should call this only once, but if + you want different sections to appear in your report, call this once + per section. + +health.report_info({msg}) *health.report_info()* + Reports an informational message. + +health.report_ok({msg}) *health.report_ok()* + Reports a "success" message. + +health.report_warn({msg} [, {advice}]) *health.report_warn()* + Reports a warning. {advice} is an optional List of suggestions. + +health.report_error({msg} [, {advice}]) *health.report_error()* + Reports an error. {advice} is an optional List of suggestions. + +============================================================================== +Create a Lua healthcheck *health-dev-lua* + +Healthchecks are functions that check the user environment, configuration, +etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/. -health.vim functions are for creating new healthchecks. They mostly just do -some layout and formatting, to give users a consistent presentation. +To add a new healthcheck for your own plugin, simply define a Lua module in +your plugin that returns a table with a "check()" function. |:checkhealth| +will automatically find and invoke this function. -health#report_start({name}) *health#report_start* - Starts a new report. Most plugins should call this only once, but if +If your plugin is named "foo", then its healthcheck module should be a file in +one of these locations on 'runtimepath' or 'packpath': + - lua/foo/health/init.lua + - lua/foo/health.lua + +If your plugin provides a submodule named "bar" for which you want a separate +healthcheck, define the healthcheck at one of these locations on 'runtimepath' +or 'packpath': + - lua/foo/bar/health/init.lua + - lua/foo/bar/health.lua + +All submodules should return a Lua table containing the method `check()`. + +Copy this sample code into `lua/foo/health/init.lua` or `lua/foo/health.lua`, +replacing "foo" in the path with your plugin name: > + + local M = {} + local health = require("health") + + M.check = function() + health.report_start("my_plugin report") + -- make sure setup function parameters are ok + if check_setup() then + health.report_ok("Setup function is correct") + else + health.report_error("Setup function is incorrect") + end + -- do some more checking + -- ... + end + + return M + +============================================================================== +Vimscript Functions *health-functions-vimscript* *health-vimscript* + +health.vim functions are for creating new healthchecks. (See also +|health-functions-lua|) + +health#report_start({name}) *health#report_start* + Starts a new report. Most plugins should call this only once, but if you want different sections to appear in your report, call this once per section. -health#report_info({msg}) *health#report_info* - Reports an informational message. +health#report_info({msg}) *health#report_info* + Reports an informational message. -health#report_ok({msg}) *health#report_ok* - Reports a "success" message. +health#report_ok({msg}) *health#report_ok* + Reports a "success" message. -health#report_warn({msg}, [{advice}]) *health#report_warn* +health#report_warn({msg} [, {advice}]) *health#report_warn* Reports a warning. {advice} is an optional List of suggestions. -health#report_error({msg}, [{advice}]) *health#report_error* +health#report_error({msg} [, {advice}]) *health#report_error* Reports an error. {advice} is an optional List of suggestions. -health#{plugin}#check() *health.user_checker* +health#{plugin}#check() *health.user_checker* Healthcheck function for {plugin}. Called by |:checkhealth| automatically. Example: > - function! health#my_plug#check() abort - silent call s:check_environment_vars() - silent call s:check_python_configuration() - endfunction + function! health#my_plug#check() abort + silent call s:check_environment_vars() + silent call s:check_python_configuration() + endfunction < - All output will be captured from the healthcheck. Use the - health#report_* functions so that your healthcheck has a format - consistent with the standard healthchecks. - ============================================================================== -Create a healthcheck *health-dev* +Create a healthcheck *health-dev-vim* Healthchecks are functions that check the user environment, configuration, etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/. @@ -88,8 +159,8 @@ health#{plugin}#check() function in autoload/health/{plugin}.vim. If your plugin is named "foo", then its healthcheck function must be > health#foo#check() -defined in this file on 'runtimepath': > - autoload/health/foo.vim +defined in this file on 'runtimepath' or 'packpath': + - autoload/health/foo.vim Copy this sample code into autoload/health/foo.vim and replace "foo" with your plugin name: > @@ -97,7 +168,7 @@ plugin name: > call health#report_start('sanity checks') " perform arbitrary checks " ... - + if looks_good call health#report_ok('found required dependencies') else @@ -106,6 +177,4 @@ plugin name: > endif endfunction -============================================================================== - -vim:tw=78:ts=8:ft=help:fdm=marker +vim:et:tw=78:ts=8:ft=help:fdm=marker diff --git a/runtime/doc/print.txt b/runtime/doc/print.txt index d9320ad315..f54d0429a6 100644 --- a/runtime/doc/print.txt +++ b/runtime/doc/print.txt @@ -690,7 +690,7 @@ There are a couple of points to bear in mind: ============================================================================== 8. Formfeed Characters *printing-formfeed* -By default Vim does not do any special processing of |formfeed| control +By default Vim does not do any special processing of formfeed control characters. Setting the 'printoptions' formfeed item will make Vim recognize formfeed characters and continue printing the current line at the beginning of the first line on a new page. The use of formfeed characters provides diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 87a48e6d2a..bb775ec884 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -90,10 +90,11 @@ argument. See |info-message| about capturing the text. *--clean* ---clean Equivalent to "-u NONE -i NONE": +--clean Mimics a fresh install of Nvim: - Skips initializations from files and environment variables. - No 'shada' file is read or written. - Excludes user directories from 'runtimepath' + - Loads builtin plugins, unlike "-u NONE -i NONE". *--noplugin* --noplugin Skip loading plugins. Resets the 'loadplugins' option. diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index ac10aeec88..441ae13df4 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -531,9 +531,11 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop}) for id, node in pairs(match) do local name = query.captures[id] -- `node` was captured by the `name` capture in the match - - local node_data = metadata[id] -- Node level metadata - +< +> + local node_data = metadata[id] -- Node level metadata +< +> ... use the info here ... end end diff --git a/runtime/doc/usr_22.txt b/runtime/doc/usr_22.txt index 56fe5ada2b..f53d578456 100644 --- a/runtime/doc/usr_22.txt +++ b/runtime/doc/usr_22.txt @@ -202,14 +202,28 @@ the other window. This is called a local directory. > :pwd /home/Bram/VeryLongFileName -So long as no ":lcd" command has been used, all windows share the same current -directory. Doing a ":cd" command in one window will also change the current +So long as no `:lcd` command has been used, all windows share the same current +directory. Doing a `:cd` command in one window will also change the current directory of the other window. - For a window where ":lcd" has been used a different current directory is -remembered. Using ":cd" or ":lcd" in other windows will not change it. - When using a ":cd" command in a window that uses a different current + For a window where `:lcd` has been used a different current directory is +remembered. Using `:cd` or `:lcd` in other windows will not change it. + When using a `:cd` command in a window that uses a different current directory, it will go back to using the shared directory. + +TAB LOCAL DIRECTORY + +When you open a new tab page, it uses the directory of the window in the +previous tab page from which the new tab page was opened. You can change the +directory of the current tab page using the `:tcd` command. All the windows in +a tab page share this directory except for windows with a window-local +directory. Any new windows opened in this tab page will use this directory as +the current working directory. Using a `:cd` command in a tab page will not +change the working directory of tab pages which have a tab local directory. +When the global working directory is changed using the ":cd" command in a tab +page, it will also change the current tab page working directory. + + ============================================================================== *22.3* Finding a file diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 5fddadcf01..6a9284dac9 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -785,9 +785,10 @@ System functions and manipulation of files: isdirectory() check if a directory exists getfsize() get the size of a file getcwd() get the current working directory - haslocaldir() check if current window used |:lcd| + haslocaldir() check if current window used |:lcd| or |:tcd| tempname() get the name of a temporary file mkdir() create a new directory + chdir() change current working directory delete() delete a file rename() rename a file system() get the result of a shell command as a string @@ -1025,6 +1026,7 @@ Various: *various-functions* undotree() return the state of the undo tree getreg() get contents of a register + getreginfo() get information about a register getregtype() get type of a register setreg() set contents and type of a register reg_executing() return the name of the register being executed @@ -1803,7 +1805,7 @@ First of all you must choose a name for your plugin. The features provided by the plugin should be clear from its name. And it should be unlikely that someone else writes a plugin with the same name but which does something different. And please limit the name to 8 characters, to avoid problems on -old Windows systems. +old MS-Windows systems. A script that corrects typing mistakes could be called "typecorr.vim". We will use it here as an example. diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index b06fa7518c..5484e27797 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -168,7 +168,7 @@ g8 Print the hex values of the bytes used in the *:z!* :[range]z![+-^.=][count] - Like ":z:", but when [count] is not specified, it + Like ":z", but when [count] is not specified, it defaults to the Vim window height minus one. :[range]z[!]#[+-^.=][count] *:z#* diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index 64824b2e3f..77bf1d29eb 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -248,6 +248,8 @@ Variables: Nvim always builds with all features, in contrast to Vim which may have certain features removed/added at compile-time. |feature-compile| +Some Vim features were changed in Nvim, and vice versa. + If a Python interpreter is available on your `$PATH`, |:python| and |:python3| are always available and may be used simultaneously. See |provider-python|. @@ -423,6 +425,15 @@ Vimscript compatibility: `shell_error` does not alias to |v:shell_error| `this_session` does not alias to |v:this_session| +Working directory (Vim implemented some of these later than Nvim): +- |DirChanged| can be triggered when switching to another window. +- |getcwd()| and |haslocaldir()| may throw errors if the tab page or window + cannot be found. *E5000* *E5001* *E5002* +- |haslocaldir()| only checks for tab-local directory when -1 is passed as + window number, and its only possible returns values are 0 and 1. +- `getcwd(-1)` is equivalent to `getcwd(-1, 0)` instead of returning the global + working directory. Use `getcwd(-1, -1)` to get the global working directory. + ============================================================================== 5. Missing legacy features *nvim-features-missing* |