diff options
Diffstat (limited to 'runtime/doc')
100 files changed, 12834 insertions, 10499 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 0e1cc3c28c..ba3b7c0915 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -7,7 +7,7 @@ Nvim API *API* *api* Nvim exposes a powerful API that can be used by plugins and external processes -via |RPC|, |Lua| and VimL (|eval-api|). +via |RPC|, |Lua| and Vimscript (|eval-api|). Applications can also embed libnvim to work with the C API directly. @@ -17,8 +17,15 @@ Applications can also embed libnvim to work with the C API directly. API Usage *api-rpc* *RPC* *rpc* *msgpack-rpc* -RPC is the typical way to control Nvim programmatically. Nvim implements the -MessagePack-RPC protocol: +RPC is the main way to control Nvim programmatically. Nvim implements the +MessagePack-RPC protocol with these extra (out-of-spec) constraints: + +1. Responses must be given in reverse order of requests (like "unwinding + a stack"). +2. Nvim processes all messages (requests and notifications) in the order they + are received. + +MessagePack-RPC specification: https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md @@ -202,7 +209,7 @@ any of these approaches: nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)' < 3. Use the |api_info()| Vimscript function. >vim - :lua print(vim.inspect(vim.fn.api_info())) + :lua vim.print(vim.fn.api_info()) < Example using |filter()| to exclude non-deprecated API functions: >vim :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name') @@ -273,7 +280,7 @@ nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata}, changed but not the buffer contents. {linedata} contains the changed screen lines. This happens when 'inccommand' shows a buffer preview. - Properties:~ + Properties: ~ {buf} API buffer handle (buffer number) {changedtick} value of |b:changedtick| for the buffer. If you send an @@ -306,7 +313,7 @@ nvim_buf_changedtick_event[{buf}, {changedtick}] *nvim_buf_changedtick_event* When |b:changedtick| was incremented but no text was changed. Relevant for undo/redo. - Properties:~ + Properties: ~ {buf} API buffer handle (buffer number) {changedtick} new value of |b:changedtick| for the buffer @@ -319,7 +326,7 @@ nvim_buf_detach_event[{buf}] *nvim_buf_detach_event* |:checktime| or 'autoread'. - Generally: whenever the buffer contents are unloaded from memory. - Properties:~ + Properties: ~ {buf} API buffer handle (buffer number) @@ -356,6 +363,7 @@ In-process Lua plugins can receive buffer updates in the form of Lua callbacks. These callbacks are called frequently in various contexts; |textlock| prevents changing buffer contents and window layout (use |vim.schedule()| to defer such operations to the main loop instead). +Moving the cursor is allowed, but it is restored afterwards. |nvim_buf_attach()| will take keyword args for the callbacks. "on_lines" will receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline}, @@ -399,6 +407,23 @@ external highlighter plugin wants to add many highlights in a batch, performance can be improved by calling |nvim_buf_add_highlight()| as an asynchronous notification, after first (synchronously) requesting a source id. +|nvim_buf_add_highlight()| adds highlights as |extmarks|. If highlights need to +be tracked or manipulated after adding them, it is better to use +|nvim_buf_set_extmark()| directly, as this function returns the placed |extmark| +id. Thus, instead of >lua + vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end) +< +use >lua + -- create the highlight through an extmark + extid = vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = hl_group}) + + -- example: modify the extmark's highlight group + vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid}) + + -- example: change the highlight's position + vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid}) +< + Example using the Python API client (|pynvim|): >python src = vim.new_highlight_source() @@ -451,6 +476,11 @@ Buffer text can be highlighted by typical mechanisms (syntax highlighting, options from the current window; specify `style=minimal` in |nvim_open_win()| to disable various visual features such as the 'number' column. +Other highlight groups specific to floating windows: +- |hl-FloatBorder| for window's border +- |hl-FloatTitle| for window's title +- |hl-FloatFooter| for window's footer + Currently, floating windows don't support some widgets like scrollbar. The output of |:mksession| does not include commands for restoring floating @@ -464,7 +494,7 @@ Example: create a float with scratch buffer: >vim \ 'row': 1, 'anchor': 'NW', 'style': 'minimal'} let win = nvim_open_win(buf, 0, opts) " optional: change highlight, otherwise Pmenu is used - call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight') + call nvim_set_option_value('winhl', 'Normal:MyHighlight', {'win': win}) < ============================================================================== @@ -558,7 +588,7 @@ nvim__get_runtime({pat}, {all}, {*opts}) *nvim__get_runtime()* Parameters: ~ • {pat} pattern of files to search for • {all} whether to return all matches or only the first - • {opts} is_lua: only search lua subdirs + • {opts} is_lua: only search Lua subdirs Return: ~ list of absolute paths to the found files @@ -615,6 +645,10 @@ nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()* NB: if your UI doesn't use hlstate, this will not return hlstate first time. +nvim__invalidate_glyph_cache() *nvim__invalidate_glyph_cache()* + For testing. The condition in schar_cache_clear_if_full is hard to reach, + so this function can be used to force a cache clear in a test. + nvim__stats() *nvim__stats()* Gets internal stats. @@ -679,7 +713,7 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()* Buffer handle, or 0 on error See also: ~ - buf_open_scratch + • buf_open_scratch nvim_del_current_line() *nvim_del_current_line()* Deletes the current line. @@ -693,13 +727,13 @@ nvim_del_keymap({mode}, {lhs}) *nvim_del_keymap()* To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|. See also: ~ - |nvim_set_keymap()| + • |nvim_set_keymap()| nvim_del_mark({name}) *nvim_del_mark()* Deletes an uppercase/file named mark. See |mark-motions|. - Note: - fails with error if a lowercase or buffer local named mark is used. + Note: ~ + • Lowercase name (or other buffer-local mark) is an error. Parameters: ~ • {name} Mark name @@ -708,8 +742,8 @@ nvim_del_mark({name}) *nvim_del_mark()* true if the mark was deleted, else false. See also: ~ - |nvim_buf_del_mark()| - |nvim_get_mark()| + • |nvim_buf_del_mark()| + • |nvim_get_mark()| nvim_del_var({name}) *nvim_del_var()* Removes a global (g:) variable. @@ -746,7 +780,7 @@ nvim_err_writeln({str}) *nvim_err_writeln()* • {str} Message See also: ~ - nvim_err_write() + • nvim_err_write() nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* Evaluates statusline string. @@ -768,6 +802,8 @@ nvim_eval_statusline({str}, {*opts}) *nvim_eval_statusline()* • use_tabline: (boolean) Evaluate tabline instead of statusline. When true, {winid} is ignored. Mutually exclusive with {use_winbar}. + • use_statuscol_lnum: (number) Evaluate statuscolumn for this + line number instead of statusline. Return: ~ Dictionary containing statusline information, with these keys: @@ -820,8 +856,8 @@ nvim_feedkeys({keys}, {mode}, {escape_ks}) *nvim_feedkeys()* true otherwise. See also: ~ - feedkeys() - vim_strsave_escape_ks + • feedkeys() + • vim_strsave_escape_ks nvim_get_api_info() *nvim_get_api_info()* Returns a 2-tuple (Array), where item 0 is the current channel id and item @@ -918,37 +954,48 @@ nvim_get_current_win() *nvim_get_current_win()* Return: ~ Window handle -nvim_get_hl_by_id({hl_id}, {rgb}) *nvim_get_hl_by_id()* - Gets a highlight definition by id. |hlID()| - - Parameters: ~ - • {hl_id} Highlight id as returned by |hlID()| - • {rgb} Export RGB colors - - Return: ~ - Highlight definition map - - See also: ~ - nvim_get_hl_by_name +nvim_get_hl({ns_id}, {*opts}) *nvim_get_hl()* + Gets all or specific highlight groups in a namespace. -nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()* - Gets a highlight definition by name. + Note: ~ + • When the `link` attribute is defined in the highlight definition map, + other attributes will not be taking effect (see |:hi-link|). Parameters: ~ - • {name} Highlight group name - • {rgb} Export RGB colors + • {ns_id} Get highlight groups for namespace ns_id + |nvim_get_namespaces()|. Use 0 to get global highlight groups + |:highlight|. + • {opts} Options dict: + • name: (string) Get a highlight definition by name. + • id: (integer) Get a highlight definition by id. + • link: (boolean, default true) Show linked group name + instead of effective definition |:hi-link|. + • create: (boolean, default true) When highlight group + doesn't exist create it. Return: ~ - Highlight definition map - - See also: ~ - nvim_get_hl_by_id + Highlight groups as a map from group name to a highlight definition + map as in |nvim_set_hl()|, or only a single highlight definition map + if requested by name or id. nvim_get_hl_id_by_name({name}) *nvim_get_hl_id_by_name()* Gets a highlight group by name similar to |hlID()|, but allocates a new ID if not present. +nvim_get_hl_ns({*opts}) *nvim_get_hl_ns()* + Gets the active highlight namespace. + + Parameters: ~ + • {opts} Optional parameters + • winid: (number) |window-ID| for retrieving a window's + highlight namespace. A value of -1 is returned when + |nvim_win_set_hl_ns()| has not been called for the window + (or was called with a namespace of -1). + + Return: ~ + Namespace id, or -1 + nvim_get_keymap({mode}) *nvim_get_keymap()* Gets a list of global (non-buffer-local) |mapping| definitions. @@ -960,13 +1007,14 @@ nvim_get_keymap({mode}) *nvim_get_keymap()* "buffer" key is always zero. nvim_get_mark({name}, {opts}) *nvim_get_mark()* - Return a tuple (row, col, buffer, buffername) representing the position of - the uppercase/file named mark. See |mark-motions|. + Returns a `(row, col, buffer, buffername)` tuple representing the position + of the uppercase/file named mark. "End of line" column position is + returned as |v:maxcol| (big number). See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| - Note: - fails with error if a lowercase or buffer local named mark is used. + Note: ~ + • Lowercase name (or other buffer-local mark) is an error. Parameters: ~ • {name} Mark name @@ -977,8 +1025,8 @@ nvim_get_mark({name}, {opts}) *nvim_get_mark()* not set. See also: ~ - |nvim_buf_set_mark()| - |nvim_del_mark()| + • |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 @@ -1047,12 +1095,10 @@ nvim_input({keys}) *nvim_input()* On execution error: does not fail, but updates v:errmsg. - Note: - |keycodes| like <CR> are translated, so "<" is special. To input a + Note: ~ + • |keycodes| like <CR> are translated, so "<" is special. To input a literal "<", send <LT>. - - Note: - For mouse events use |nvim_input_mouse()|. The pseudokey form + • For mouse events use |nvim_input_mouse()|. The pseudokey form "<LeftMouse><col,row>" is deprecated since |api-level| 6. Attributes: ~ @@ -1072,8 +1118,8 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col}) Non-blocking: does not wait on any result, but queues the event to be processed soon by the event loop. - Note: - Currently this doesn't support "scripting" multiple mouse events by + Note: ~ + • Currently this doesn't support "scripting" multiple mouse events by calling it multiple times in a loop: the intermediate mouse positions will be ignored. It should be used to implement real-time mouse input in a GUI. The deprecated pseudokey form ("<LeftMouse><col,row>") of @@ -1113,7 +1159,7 @@ nvim_list_chans() *nvim_list_chans()* specified at |nvim_get_chan_info()|. nvim_list_runtime_paths() *nvim_list_runtime_paths()* - Gets the paths contained in 'runtimepath'. + Gets the paths contained in |runtime-search-path|. Return: ~ List of paths @@ -1173,10 +1219,13 @@ nvim_open_term({buffer}, {opts}) *nvim_open_term()* |nvim_chan_send()| can be called immediately to process sequences in a virtual terminal having the intended size. + Attributes: ~ + not allowed when |textlock| is active + Parameters: ~ • {buffer} the buffer to use (expected to be empty) • {opts} Optional parameters. - • on_input: lua callback for input sent, i e keypresses in + • on_input: Lua callback for input sent, i e keypresses in terminal mode. Note: keypresses are sent raw as they would be to the pty master end. For instance, a carriage return is sent as a "\r", not as a "\n". |textlock| applies. It @@ -1252,8 +1301,8 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special}) • {special} Replace |keycodes|, e.g. <CR> becomes a "\r" char. See also: ~ - replace_termcodes - cpoptions + • replace_termcodes + • cpoptions *nvim_select_popupmenu_item()* nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts}) @@ -1286,8 +1335,8 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) appropriate. Example: library first identifies the channel, then a plugin using that library later identifies itself. - Note: - "Something is better than nothing". You don't need to include all the + Note: ~ + • "Something is better than nothing". You don't need to include all the fields. Attributes: ~ @@ -1307,7 +1356,11 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) • {type} Must be one of the following values. Client libraries should default to "remote" unless overridden by the user. - • "remote" remote client connected to Nvim. + • "remote" remote client connected "Nvim flavored" + MessagePack-RPC (responses must be in reverse order of + requests). |msgpack-rpc| + • "msgpack-rpc" remote client connected to Nvim via + fully MessagePack-RPC compliant protocol. • "ui" gui frontend • "embedder" application using Nvim as a component (for example, IDE/editor implementing a vim mode). @@ -1338,7 +1391,7 @@ nvim_set_current_buf({buffer}) *nvim_set_current_buf()* Sets the current buffer. Attributes: ~ - not allowed when |textlock| is active + not allowed when |textlock| is active or in the |cmdwin| Parameters: ~ • {buffer} Buffer handle @@ -1362,7 +1415,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* Sets the current tabpage. Attributes: ~ - not allowed when |textlock| is active + not allowed when |textlock| is active or in the |cmdwin| Parameters: ~ • {tabpage} Tabpage handle @@ -1371,7 +1424,7 @@ nvim_set_current_win({window}) *nvim_set_current_win()* Sets the current window. Attributes: ~ - not allowed when |textlock| is active + not allowed when |textlock| is active or in the |cmdwin| Parameters: ~ • {window} Window handle @@ -1379,21 +1432,24 @@ nvim_set_current_win({window}) *nvim_set_current_win()* nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* Sets a highlight group. - Note: - Unlike the `:highlight` command which can update a highlight group, - this function completely replaces the definition. For example: + Note: ~ + • Unlike the `:highlight` command which can update a highlight group, this + function completely replaces the definition. For example: `nvim_set_hl(0, 'Visual', {})` will clear the highlight group 'Visual'. - - Note: - The fg and bg keys also accept the string values `"fg"` or `"bg"` - which act as aliases to the corresponding foreground and background - values of the Normal group. If the Normal group has not been defined, - using these values results in an error. + • The fg and bg keys also accept the string values `"fg"` or `"bg"` which + act as aliases to the corresponding foreground and background values + of the Normal group. If the Normal group has not been defined, using + these values results in an error. + • If `link` is used in combination with other attributes; only the `link` + will take effect (see |:hi-link|). Parameters: ~ • {ns_id} Namespace id for this highlight |nvim_create_namespace()|. Use 0 to set a highlight group globally |:highlight|. + Highlights from non-global namespaces are not active by + default, use |nvim_set_hl_ns()| or |nvim_win_set_hl_ns()| to + activate them. • {name} Highlight group name, e.g. "ErrorMsg" • {val} Highlight definition map, accepts the following keys: • fg (or foreground): color name or "#RRGGBB", see note. @@ -1419,16 +1475,19 @@ nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* • cterm: cterm attribute map, like |highlight-args|. If not set, cterm attributes will match those from the attribute map documented above. + • force: if true force update the highlight group when it + exists. nvim_set_hl_ns({ns_id}) *nvim_set_hl_ns()* - Set active namespace for highlights. This can be set for a single window, - see |nvim_win_set_hl_ns()|. + Set active namespace for highlights defined with |nvim_set_hl()|. This can + be set for a single window, see |nvim_win_set_hl_ns()|. Parameters: ~ • {ns_id} the namespace to use nvim_set_hl_ns_fast({ns_id}) *nvim_set_hl_ns_fast()* - Set active namespace for highlights while redrawing. + Set active namespace for highlights defined with |nvim_set_hl()| while + redrawing. This function meant to be called while redrawing, primarily from |nvim_set_decoration_provider()| on_win and on_line callbacks, which are @@ -1458,19 +1517,20 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* Parameters: ~ • {mode} Mode short-name (map command prefix: "n", "i", "v", "x", …) or - "!" for |:map!|, or empty string for |:map|. + "!" for |:map!|, or empty string for |:map|. "ia", "ca" or + "!a" for abbreviation in Insert mode, Cmdline mode, or both, + respectively • {lhs} Left-hand-side |{lhs}| of the mapping. • {rhs} Right-hand-side |{rhs}| of the mapping. - • {opts} Optional parameters map: keys are |:map-arguments|, values are - booleans (default false). Accepts all |:map-arguments| as keys - excluding |<buffer>| but including |:noremap| and "desc". - Unknown key is an error. "desc" can be used to give a - description to the mapping. When called from Lua, also accepts - a "callback" key that takes a Lua function to call when the - mapping is executed. When "expr" is true, "replace_keycodes" - (boolean) can be used to replace keycodes in the resulting - string (see |nvim_replace_termcodes()|), and a Lua callback - returning `nil` is equivalent to returning an empty string. + • {opts} Optional parameters map: Accepts all |:map-arguments| as keys + except |<buffer>|, values are booleans (default false). Also: + • "noremap" disables |recursive_mapping|, like |:noremap| + • "desc" human-readable description. + • "callback" Lua function called in place of {rhs}. + • "replace_keycodes" (boolean) When "expr" is true, replace + keycodes in the resulting string (see + |nvim_replace_termcodes()|). Returning nil from the Lua + "callback" is equivalent to returning an empty string. nvim_set_var({name}, {value}) *nvim_set_var()* Sets a global (g:) variable. @@ -1520,22 +1580,22 @@ Vimscript Functions *api-vimscript* *nvim_call_dict_function()* nvim_call_dict_function({dict}, {fn}, {args}) - Calls a VimL |Dictionary-function| with the given arguments. + Calls a Vimscript |Dictionary-function| with the given arguments. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ - • {dict} Dictionary, or String evaluating to a VimL |self| dict - • {fn} Name of the function defined on the VimL dict + • {dict} Dictionary, or String evaluating to a Vimscript |self| dict + • {fn} Name of the function defined on the Vimscript dict • {args} Function arguments packed in an Array Return: ~ Result of the function call nvim_call_function({fn}, {args}) *nvim_call_function()* - Calls a VimL function with the given arguments. + Calls a Vimscript function with the given arguments. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ • {fn} Function to call @@ -1547,54 +1607,56 @@ nvim_call_function({fn}, {args}) *nvim_call_function()* nvim_command({command}) *nvim_command()* Executes an Ex command. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. - Prefer using |nvim_cmd()| or |nvim_exec()| over this. To evaluate multiple - lines of Vim script or an Ex command directly, use |nvim_exec()|. To - construct an Ex command using a structured format and then execute it, use - |nvim_cmd()|. To modify an Ex command before evaluating it, use - |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. + Prefer using |nvim_cmd()| or |nvim_exec2()| over this. To evaluate + multiple lines of Vim script or an Ex command directly, use + |nvim_exec2()|. To construct an Ex command using a structured format and + then execute it, use |nvim_cmd()|. To modify an Ex command before + evaluating it, use |nvim_parse_cmd()| in conjunction with |nvim_cmd()|. Parameters: ~ • {command} Ex command string nvim_eval({expr}) *nvim_eval()* - Evaluates a VimL |expression|. Dictionaries and Lists are recursively + Evaluates a Vimscript |expression|. Dictionaries and Lists are recursively expanded. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ - • {expr} VimL expression string + • {expr} Vimscript expression string Return: ~ Evaluation result or expanded object -nvim_exec({src}, {output}) *nvim_exec()* +nvim_exec2({src}, {*opts}) *nvim_exec2()* Executes Vimscript (multiline block of Ex commands), like anonymous |:source|. Unlike |nvim_command()| this function supports heredocs, script-scope (s:), etc. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ - • {src} Vimscript code - • {output} Capture and return all (non-error, non-shell |:!|) output + • {src} Vimscript code + • {opts} Optional parameters. + • output: (boolean, default false) Whether to capture and + return all (non-error, non-shell |:!|) output. Return: ~ - Output (non-error, non-shell |:!|) if `output` is true, else empty - string. + Dictionary containing information about execution, with these keys: + • output: (string|nil) Output if `opts.output` is true. See also: ~ - |execute()| - |nvim_command()| - |nvim_cmd()| + • |execute()| + • |nvim_command()| + • |nvim_cmd()| *nvim_parse_expression()* nvim_parse_expression({expr}, {flags}, {highlight}) - Parse a VimL expression. + Parse a Vimscript expression. Attributes: ~ |api-fast| @@ -1638,8 +1700,8 @@ nvim_parse_expression({expr}, {flags}, {highlight}) stringified without "kExprNode" prefix. • "start": a pair [line, column] describing where node is "started" where "line" is always 0 (will not be 0 if you will be - using nvim_parse_viml() on e.g. ":let", but that is not present - yet). Both elements are Integers. + using this API on e.g. ":let", but that is not present yet). + Both elements are Integers. • "len": “length” of the node. This and "start" are there for debugging purposes primary (debugging parser and providing debug information). @@ -1678,13 +1740,13 @@ Command Functions *api-command* *nvim_buf_create_user_command()* nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts}) - Create a new user command |user-commands| in the given buffer. + Creates a buffer-local command |user-commands|. Parameters: ~ • {buffer} Buffer handle, or 0 for current buffer. See also: ~ - nvim_create_user_command + • nvim_create_user_command *nvim_buf_del_user_command()* nvim_buf_del_user_command({buffer}, {name}) @@ -1722,7 +1784,7 @@ nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* example, instead of `vim.cmd.bdelete{ count = 2 }`, you may do `vim.cmd.bdelete(2)`. - On execution error: fails with VimL error, updates v:errmsg. + On execution error: fails with Vimscript error, updates v:errmsg. Parameters: ~ • {cmd} Command to execute. Must be a Dictionary that can contain the @@ -1738,22 +1800,19 @@ nvim_cmd({*cmd}, {*opts}) *nvim_cmd()* empty string. See also: ~ - |nvim_exec()| - |nvim_command()| + • |nvim_exec2()| + • |nvim_command()| *nvim_create_user_command()* nvim_create_user_command({name}, {command}, {*opts}) - Create a new user command |user-commands| + Creates a global |user-commands| command. - {name} is the name of the new command. The name must begin with an - uppercase letter. - - {command} is the replacement text or Lua function to execute. + For Lua usage see |lua-guide-commands-create|. Example: >vim - :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {}) - :SayHello - Hello world! + :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true}) + :SayHello + Hello world! < Parameters: ~ @@ -1769,6 +1828,7 @@ nvim_create_user_command({name}, {command}, {*opts}) • fargs: (table) The args split by unescaped whitespace (when more than one argument is allowed), if any |<f-args>| + • nargs: (string) Number of arguments |:command-nargs| • bang: (boolean) "true" if the command was executed with a ! modifier |<bang>| • line1: (number) The starting line of the command range @@ -1783,19 +1843,20 @@ nvim_create_user_command({name}, {command}, {*opts}) • smods: (table) Command modifiers in a structured format. Has the same structure as the "mods" key of |nvim_parse_cmd()|. - • {opts} Optional command attributes. See |command-attributes| for - more details. To use boolean attributes (such as - |:command-bang| or |:command-bar|) set the value to "true". - In addition to the string options listed in - |:command-complete|, the "complete" key also accepts a Lua - function which works like the "customlist" completion mode - |:command-completion-customlist|. Additional parameters: - • desc: (string) Used for listing the command when a Lua - function is used for {command}. - • force: (boolean, default true) Override any previous - definition. - • preview: (function) Preview callback for 'inccommand' - |:command-preview| + • {opts} Optional |command-attributes|. + • Set boolean attributes such as |:command-bang| or + |:command-bar| to true (but not |:command-buffer|, use + |nvim_buf_create_user_command()| instead). + • "complete" |:command-complete| also accepts a Lua + function which works like + |:command-completion-customlist|. + • Other parameters: + • desc: (string) Used for listing the command when a Lua + function is used for {command}. + • force: (boolean, default true) Override any previous + definition. + • preview: (function) Preview callback for 'inccommand' + |:command-preview| nvim_del_user_command({name}) *nvim_del_user_command()* Delete a user-defined command. @@ -1814,6 +1875,9 @@ nvim_get_commands({*opts}) *nvim_get_commands()* Return: ~ Map of maps describing commands. + See also: ~ + • |nvim_get_all_options_info()| + nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* Parse command line. @@ -1889,45 +1953,20 @@ nvim_parse_cmd({str}, {opts}) *nvim_parse_cmd()* ============================================================================== Options Functions *api-options* -nvim_buf_get_option({buffer}, {name}) *nvim_buf_get_option()* - Gets a buffer option value - - Parameters: ~ - • {buffer} Buffer handle, or 0 for current buffer - • {name} Option name - - Return: ~ - Option value - -nvim_buf_set_option({buffer}, {name}, {value}) *nvim_buf_set_option()* - Sets a buffer option value. Passing `nil` as value deletes the option - (only works if there's a global fallback) - - Parameters: ~ - • {buffer} Buffer handle, or 0 for current buffer - • {name} Option name - • {value} Option value - nvim_get_all_options_info() *nvim_get_all_options_info()* Gets the option information for all options. The dictionary has the full option names as keys and option metadata - dictionaries as detailed at |nvim_get_option_info()|. + dictionaries as detailed at |nvim_get_option_info2()|. Return: ~ dictionary of all options -nvim_get_option({name}) *nvim_get_option()* - Gets the global value of an option. - - Parameters: ~ - • {name} Option name - - Return: ~ - Option value (global) + See also: ~ + • |nvim_get_commands()| -nvim_get_option_info({name}) *nvim_get_option_info()* - Gets the option information for one option +nvim_get_option_info2({name}, {*opts}) *nvim_get_option_info2()* + Gets the option information for one option from arbitrary buffer or window Resulting dictionary has keys: • name: Name of the option (like 'filetype') @@ -1943,8 +1982,19 @@ nvim_get_option_info({name}) *nvim_get_option_info()* • commalist: List of comma separated values • flaglist: List of single char flags + When {scope} is not provided, the last set information applies to the + local value in the current buffer or window if it is available, otherwise + the global value information is returned. This behavior can be disabled by + explicitly specifying {scope} in the {opts} table. + Parameters: ~ • {name} Option name + • {opts} Optional parameters + • scope: One of "global" or "local". Analogous to |:setglobal| + and |:setlocal|, respectively. + • win: |window-ID|. Used for getting window local options. + • buf: Buffer number. Used for getting buffer local options. + Implies {scope} is "local". Return: ~ Option Information @@ -1963,17 +2013,14 @@ nvim_get_option_value({name}, {*opts}) *nvim_get_option_value()* • win: |window-ID|. Used for getting window local options. • buf: Buffer number. Used for getting buffer local options. Implies {scope} is "local". + • filetype: |filetype|. Used to get the default option for a + specific filetype. Cannot be used with any other option. + Note: this will trigger |ftplugin| and all |FileType| + autocommands for the corresponding filetype. Return: ~ Option value -nvim_set_option({name}, {value}) *nvim_set_option()* - Sets the global value of an option. - - Parameters: ~ - • {name} Option name - • {value} New option value - *nvim_set_option_value()* nvim_set_option_value({name}, {value}, {*opts}) Sets the value of an option. The behavior of this function matches that of @@ -1991,25 +2038,6 @@ nvim_set_option_value({name}, {value}, {*opts}) • win: |window-ID|. Used for setting window local option. • buf: Buffer number. Used for setting buffer local option. -nvim_win_get_option({window}, {name}) *nvim_win_get_option()* - Gets a window option value - - Parameters: ~ - • {window} Window handle, or 0 for current window - • {name} Option name - - Return: ~ - Option value - -nvim_win_set_option({window}, {name}, {value}) *nvim_win_set_option()* - Sets a window option value. Passing `nil` as value deletes the option - (only works if there's a global fallback) - - Parameters: ~ - • {window} Window handle, or 0 for current window - • {name} Option name - • {value} Option value - ============================================================================== Buffer Functions *api-buffer* @@ -2017,7 +2045,7 @@ Buffer Functions *api-buffer* For more information on buffers, see |buffers|. -Unloaded Buffers:~ +Unloaded Buffers: ~ Buffers may be unloaded by the |:bunload| command or the buffer's |'bufhidden'| option. When a buffer is unloaded its file contents are @@ -2032,10 +2060,14 @@ whether a buffer is loaded. nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* Activates buffer-update events on a channel, or as Lua callbacks. - Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua - events = {} - vim.api.nvim_buf_attach(0, false, { - on_lines=function(...) table.insert(events, {...}) end}) + Example (Lua): capture buffer updates in a global `events` variable (use + "vim.print(events)" to see its contents): >lua + events = {} + vim.api.nvim_buf_attach(0, false, { + on_lines = function(...) + table.insert(events, {...}) + end, + }) < Parameters: ~ @@ -2057,7 +2089,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* • deleted_codepoints (if `utf_sizes` is true) • deleted_codeunits (if `utf_sizes` is true) - • on_bytes: lua callback invoked on change. This + • 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: • the string "bytes" @@ -2099,8 +2131,8 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()* otherwise True. TODO: LUA_API_NO_EVAL See also: ~ - |nvim_buf_detach()| - |api-buffer-updates-lua| + • |nvim_buf_detach()| + • |api-buffer-updates-lua| nvim_buf_call({buffer}, {fun}) *nvim_buf_call()* call a function with buffer as temporary current buffer @@ -2112,20 +2144,20 @@ nvim_buf_call({buffer}, {fun}) *nvim_buf_call()* a temporary scratch window (called the "autocmd window" for historical reasons) will be used. - This is useful e.g. to call vimL functions that only work with the current - buffer/window currently, like |termopen()|. + This is useful e.g. to call Vimscript functions that only work with the + current buffer/window currently, like |termopen()|. Attributes: ~ Lua |vim.api| only Parameters: ~ • {buffer} Buffer handle, or 0 for current buffer - • {fun} Function to call inside the buffer (currently lua callable + • {fun} Function to call inside the buffer (currently Lua callable only) Return: ~ - Return value of function. NB: will deepcopy lua values currently, use - upvalues to send lua references in and out. + Return value of function. NB: will deepcopy Lua values currently, use + upvalues to send Lua references in and out. nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* Unmaps a buffer-local |mapping| for the given mode. @@ -2134,13 +2166,13 @@ nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()* • {buffer} Buffer handle, or 0 for current buffer See also: ~ - |nvim_del_keymap()| + • |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 + Note: ~ + • only deletes marks set in the buffer, if the mark is not set in the buffer it will return false. Parameters: ~ @@ -2151,8 +2183,8 @@ nvim_buf_del_mark({buffer}, {name}) *nvim_buf_del_mark()* true if the mark was deleted, else false. See also: ~ - |nvim_buf_set_mark()| - |nvim_del_mark()| + • |nvim_buf_set_mark()| + • |nvim_del_mark()| nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()* Removes a buffer-scoped (b:) variable @@ -2165,7 +2197,7 @@ nvim_buf_delete({buffer}, {opts}) *nvim_buf_delete()* Deletes the buffer. See |:bwipeout| Attributes: ~ - not allowed when |textlock| is active + not allowed when |textlock| is active or in the |cmdwin| Parameters: ~ • {buffer} Buffer handle, or 0 for current buffer @@ -2187,8 +2219,8 @@ nvim_buf_detach({buffer}) *nvim_buf_detach()* True. See also: ~ - |nvim_buf_attach()| - |api-lua-detach| for detaching Lua callbacks + • |nvim_buf_attach()| + • |api-lua-detach| for detaching Lua callbacks nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()* Gets a changed tick of a buffer @@ -2231,7 +2263,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()* - Returns a tuple (row,col) representing the position of the named mark. See + Returns a `(row,col)` tuple representing the position of the named mark. + "End of line" column position is returned as |v:maxcol| (big number). See |mark-motions|. Marks are (1,0)-indexed. |api-indexing| @@ -2245,8 +2278,8 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* uppercase/file mark set in another buffer. See also: ~ - |nvim_buf_set_mark()| - |nvim_buf_del_mark()| + • |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 @@ -2322,8 +2355,8 @@ nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()* nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()* Checks if a buffer is valid. - Note: - Even if a buffer is valid it may have been unloaded. See |api-buffer| + Note: ~ + • Even if a buffer is valid it may have been unloaded. See |api-buffer| for more info about unloaded buffers. Parameters: ~ @@ -2349,7 +2382,7 @@ nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {*opts}) • {buffer} Buffer handle, or 0 for current buffer See also: ~ - |nvim_set_keymap()| + • |nvim_set_keymap()| *nvim_buf_set_lines()* nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) @@ -2376,7 +2409,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) • {replacement} Array of lines to use as replacement See also: ~ - |nvim_buf_set_text()| + • |nvim_buf_set_text()| *nvim_buf_set_mark()* nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts}) @@ -2385,8 +2418,8 @@ nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts}) Marks are (1,0)-indexed. |api-indexing| - Note: - Passing 0 as line deletes the mark + Note: ~ + • Passing 0 as line deletes the mark Parameters: ~ • {buffer} Buffer to set the mark on @@ -2399,8 +2432,8 @@ nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts}) true if the mark was set, else false. See also: ~ - |nvim_buf_del_mark()| - |nvim_buf_get_mark()| + • |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 @@ -2428,6 +2461,11 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire lines. + Prefer |nvim_put()| if you want to insert text at the cursor position. + + Attributes: ~ + not allowed when |textlock| is active + Parameters: ~ • {buffer} Buffer handle, or 0 for current buffer • {start_row} First line index @@ -2437,7 +2475,8 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, • {replacement} Array of lines to use as replacement See also: ~ - |nvim_buf_set_lines()| + • |nvim_buf_set_lines()| + • |nvim_put()| nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* Sets a buffer-scoped (b:) variable @@ -2523,43 +2562,50 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts}) • {id} Extmark id • {opts} Optional parameters. Keys: • details: Whether to include the details dict + • hl_name: Whether to include highlight group name instead + of id, true if omitted Return: ~ 0-indexed (row, col) tuple or empty list () if extmark id was absent *nvim_buf_get_extmarks()* -nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) - Gets |extmarks| in "traversal order" from a |charwise| region defined by - buffer positions (inclusive, 0-indexed |api-indexing|). +nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts}) + Gets |extmarks| (including |signs|) in "traversal order" from a |charwise| + region defined by buffer positions (inclusive, 0-indexed |api-indexing|). Region can be given as (row,col) tuples, or valid extmark ids (whose positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) respectively, thus the following are equivalent: >lua - vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) - vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {}) + vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {}) + vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {}) < If `end` is less than `start`, traversal works backwards. (Useful with `limit`, to get the first marks prior to a given position.) + Note: when using extmark ranges (marks with a end_row/end_col position) + the `overlap` option might be useful. Otherwise only the start position of + an extmark will be considered. + Example: >lua - local a = vim.api - local pos = a.nvim_win_get_cursor(0) - local ns = a.nvim_create_namespace('my-plugin') - -- Create new extmark at line 1, column 1. - local m1 = a.nvim_buf_set_extmark(0, ns, 0, 0, {}) - -- Create new extmark at line 3, column 1. - local m2 = a.nvim_buf_set_extmark(0, ns, 2, 0, {}) - -- Get extmarks only from line 3. - local ms = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) - -- Get all marks in this buffer + namespace. - local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {}) - print(vim.inspect(ms)) + local api = vim.api + local pos = api.nvim_win_get_cursor(0) + local ns = api.nvim_create_namespace('my-plugin') + -- Create new extmark at line 1, column 1. + local m1 = api.nvim_buf_set_extmark(0, ns, 0, 0, {}) + -- Create new extmark at line 3, column 1. + local m2 = api.nvim_buf_set_extmark(0, ns, 2, 0, {}) + -- Get extmarks only from line 3. + local ms = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {}) + -- Get all marks in this buffer + namespace. + local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {}) + vim.print(ms) < Parameters: ~ • {buffer} Buffer handle, or 0 for current buffer - • {ns_id} Namespace id from |nvim_create_namespace()| + • {ns_id} Namespace id from |nvim_create_namespace()| or -1 for all + namespaces • {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 @@ -2567,7 +2613,13 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts}) |api-indexing| • {opts} Optional parameters. Keys: • limit: Maximum number of marks to return - • details Whether to include the details dict + • details: Whether to include the details dict + • hl_name: Whether to include highlight group name instead + of id, true if omitted + • overlap: Also include marks which overlap the range, even + if their start position is less than `start` + • type: Filter marks by type: "highlight", "sign", + "virt_text" and "virt_lines" Return: ~ List of [extmark_id, row, col] tuples in "traversal order". @@ -2585,6 +2637,11 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) Using the optional arguments, it is possible to use this to highlight a range of text, and also to associate virtual text to the mark. + If present, the position defined by `end_col` and `end_row` should be + after the start position in order for the extmark to cover a range. An + earlier end position is not an error, but then it behaves like an empty + range (no highlighting). + Parameters: ~ • {buffer} Buffer handle, or 0 for current buffer • {ns_id} Namespace id from |nvim_create_namespace()| @@ -2608,23 +2665,28 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) string or as an integer, the latter which can be obtained using |nvim_get_hl_id_by_name()|. • virt_text_pos : position of virtual text. Possible values: - • "eol": right after eol character (default) + • "eol": right after eol character (default). • "overlay": display over the specified column, without shifting the underlying text. • "right_align": display right aligned in the window. + • "inline": display at the specified column, and shift the + buffer text to the right as needed. • virt_text_win_col : position the virtual text at a fixed - window column (starting from the first text column) + window column (starting from the first text column of the + screen line) instead of "virt_text_pos". • virt_text_hide : hide the virtual text when the background - text is selected or hidden due to horizontal scroll - 'nowrap' + text is selected or hidden because of scrolling with + 'nowrap' or 'smoothscroll'. Currently only affects + "overlay" virt_text. • 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. • "replace": only show the virt_text color. This is the - default - • "combine": combine with background text color - • "blend": blend with background text color. + default. + • "combine": combine with background text color. + • "blend": blend with background text color. Not supported + for "inline" virt_text. • virt_lines : virtual lines to add next to this mark This should be an array over lines, where each line in turn is @@ -2644,11 +2706,17 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts}) buffer. • right_gravity : boolean that indicates the direction the extmark will be shifted in when new text is inserted (true - for right, false for left). defaults to true. + for right, false for left). Defaults to true. • end_right_gravity : boolean that indicates the direction the extmark end position (if it exists) will be shifted in when new text is inserted (true for right, false for left). Defaults to false. + • undo_restore : Restore the exact position of the mark if + text around the mark was deleted and then restored by + undo. Defaults to true. + • invalidate : boolean that indicates whether to hide the + extmark if the entirety of its range is deleted. If + "undo_restore" is false, the extmark is deleted instead. • priority: a priority value for the highlight group or sign attribute. For example treesitter highlighting uses a value of 100. @@ -2712,14 +2780,14 @@ nvim_get_namespaces() *nvim_get_namespaces()* nvim_set_decoration_provider({ns_id}, {*opts}) Set or change decoration provider for a |namespace| - This is a very general purpose interface for having lua callbacks being + This is a very general purpose interface for having Lua callbacks being triggered during the redraw code. The expected usage is to set |extmarks| for the currently redrawn buffer. |nvim_buf_set_extmark()| can be called to add marks on a per-window or per-lines basis. Use the `ephemeral` key to only use the mark for the current screen redraw (the callback will be called again for the next - redraw ). + redraw). Note: this function should not be called often. Rather, the callbacks themselves can be used to throttle unneeded callbacks. the `on_start` @@ -2731,11 +2799,14 @@ nvim_set_decoration_provider({ns_id}, {*opts}) for the extmarks set/modified inside the callback anyway. Note: doing anything other than setting extmarks is considered - experimental. Doing things like changing options are not expliticly + experimental. Doing things like changing options are not explicitly forbidden, but is likely to have unexpected consequences (such as 100% CPU consumption). doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is quite dubious for the moment. + Note: It is not allowed to remove or update extmarks in 'on_line' + callbacks. + Attributes: ~ Lua |vim.api| only @@ -2747,7 +2818,9 @@ nvim_set_decoration_provider({ns_id}, {*opts}) • on_buf: called for each buffer being redrawn (before window callbacks) ["buf", bufnr, tick] • on_win: called when starting to redraw a specific window. - ["win", winid, bufnr, topline, botline_guess] + botline_guess is an approximation that does not exceed the + last line number. ["win", winid, bufnr, topline, + botline_guess] • on_line: called for each buffer line being redrawn. (The interaction with fold lines is subject to change) ["win", winid, bufnr, row] @@ -2765,16 +2838,16 @@ nvim_win_call({window}, {fun}) *nvim_win_call()* Parameters: ~ • {window} Window handle, or 0 for current window - • {fun} Function to call inside the window (currently lua callable + • {fun} Function to call inside the window (currently Lua callable only) Return: ~ - Return value of function. NB: will deepcopy lua values currently, use - upvalues to send lua references in and out. + Return value of function. NB: will deepcopy Lua values currently, use + upvalues to send Lua references in and out. See also: ~ - |win_execute()| - |nvim_buf_call()| + • |win_execute()| + • |nvim_buf_call()| nvim_win_close({window}, {force}) *nvim_win_close()* Closes the window (like |:close| with a |window-ID|). @@ -2815,6 +2888,9 @@ nvim_win_get_cursor({window}) *nvim_win_get_cursor()* Return: ~ (row, col) tuple + See also: ~ + • |getcurpos()| + nvim_win_get_height({window}) *nvim_win_get_height()* Gets the window height @@ -2919,8 +2995,9 @@ nvim_win_set_height({window}, {height}) *nvim_win_set_height()* • {height} Height as a count of rows nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()* - Set highlight namespace for a window. This will use highlights defined in - this namespace, but fall back to global highlights (ns=0) when missing. + Set highlight namespace for a window. This will use highlights defined + with |nvim_set_hl()| for this namespace, but fall back to global + highlights (ns=0) when missing. This takes precedence over the 'winhighlight' option. @@ -2943,6 +3020,40 @@ nvim_win_set_width({window}, {width}) *nvim_win_set_width()* • {window} Window handle, or 0 for current window • {width} Width as a count of columns +nvim_win_text_height({window}, {*opts}) *nvim_win_text_height()* + Computes the number of screen lines occupied by a range of text in a given + window. Works for off-screen text and takes folds into account. + + Diff filler or virtual lines above a line are counted as a part of that + line, unless the line is on "start_row" and "start_vcol" is specified. + + Diff filler or virtual lines below the last buffer line are counted in the + result when "end_row" is omitted. + + Line indexing is similar to |nvim_buf_get_text()|. + + Parameters: ~ + • {window} Window handle, or 0 for current window. + • {opts} Optional parameters: + • start_row: Starting line index, 0-based inclusive. When + omitted start at the very top. + • end_row: Ending line index, 0-based inclusive. When + omitted end at the very bottom. + • start_vcol: Starting virtual column index on "start_row", + 0-based inclusive, rounded down to full screen lines. When + omitted include the whole line. + • end_vcol: Ending virtual column index on "end_row", + 0-based exclusive, rounded up to full screen lines. When + omitted include the whole line. + + Return: ~ + Dictionary containing text height information, with these keys: + • all: The total number of screen lines occupied by the range. + • fill: The number of diff filler or virtual lines among them. + + See also: ~ + • |virtcol()| for text width. + ============================================================================== Win_Config Functions *api-win_config* @@ -2980,6 +3091,7 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua vim.api.nvim_open_win(0, false, {relative='win', width=12, height=3, bufpos={100,10}}) + }) < Attributes: ~ @@ -3035,8 +3147,8 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* 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: + • style: (optional) Configure the appearance of the window. + Currently only supports one 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. @@ -3059,7 +3171,7 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* • "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 + any divisor of eight. The array will specify the eight chars building up the border in a clockwise fashion starting with the top-left corner. As an example, the double box style could be specified as [ "╔", "═" ,"╗", @@ -3075,14 +3187,24 @@ nvim_open_win({buffer}, {enter}, {*config}) *nvim_open_win()* specified by character: [ ["+", "MyCorner"], ["x", "MyBorder"] ]. - • title: Title (optional) in window border, String or list. - List is [text, highlight] tuples. if is string the default - highlight group is `FloatTitle`. - • title_pos: Title position must set with title option. - value can be of `left` `center` `right` default is left. + • title: Title (optional) in window border, string or list. + List should consist of `[text, highlight]` tuples. If + string, the default highlight group is `FloatTitle`. + • title_pos: Title position. Must be set with `title` + option. Value can be one of "left", "center", or "right". + Default is `"left"`. + • footer: Footer (optional) in window border, string or + list. List should consist of `[text, highlight]` tuples. + If string, the default highlight group is `FloatFooter`. + • footer_pos: Footer position. Must be set with `footer` + option. Value can be one of "left", "center", or "right". + Default is `"left"`. • noautocmd: If true then no buffer-related autocommand events such as |BufEnter|, |BufLeave| or |BufWinEnter| may fire from calling this function. + • fixed: If true when anchor is NW or SW, the float window + would be kept fixed even if the window would be truncated. + • hide: If true the floating window will be hidden. Return: ~ Window handle, or 0 on error @@ -3112,7 +3234,7 @@ nvim_win_set_config({window}, {*config}) *nvim_win_set_config()* • {config} Map defining the window configuration, see |nvim_open_win()| See also: ~ - |nvim_open_win()| + • |nvim_open_win()| ============================================================================== @@ -3185,8 +3307,8 @@ nvim_tabpage_set_var({tabpage}, {name}, {value}) Autocmd Functions *api-autocmd* nvim_clear_autocmds({*opts}) *nvim_clear_autocmds()* - Clear all autocommands that match the corresponding {opts}. To delete a - particular autocmd, see |nvim_del_autocmd()|. + Clears all autocommands selected by {opts}. To delete autocmds see + |nvim_del_autocmd()|. Parameters: ~ • {opts} Parameters @@ -3230,7 +3352,7 @@ nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* Integer id of the created group. See also: ~ - |autocmd-groups| + • |autocmd-groups| nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string). @@ -3239,7 +3361,7 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { pattern = {"*.c", "*.h"}, callback = function(ev) - print(string.format('event fired: s', vim.inspect(ev))) + print(string.format('event fired: %s', vim.inspect(ev))) end }) < @@ -3251,9 +3373,9 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* }) < - Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like - "$HOME" and "~" must be expanded explicitly: >lua - pattern = vim.fn.expand("~") .. "/some/path/*.py" + Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), + thus names like "$HOME" and "~" must be expanded explicitly: >lua + pattern = vim.fn.expand("~") .. "/some/path/*.py" < Parameters: ~ @@ -3281,7 +3403,7 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* • match: (string) expanded value of |<amatch>| • buf: (number) expanded value of |<abuf>| • file: (string) expanded value of |<afile>| - • data: (any) arbitrary data passed to + • data: (any) arbitrary data passed from |nvim_exec_autocmds()| • command (string) optional: Vim command to execute on event. @@ -3295,8 +3417,8 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* Autocommand id (number) See also: ~ - |autocommand| - |nvim_del_autocmd()| + • |autocommand| + • |nvim_del_autocmd()| nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()* Delete an autocommand group by id. @@ -3311,8 +3433,8 @@ nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()* • {id} Integer The id of the group. See also: ~ - |nvim_del_augroup_by_name()| - |nvim_create_augroup()| + • |nvim_del_augroup_by_name()| + • |nvim_create_augroup()| nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()* Delete an autocommand group by name. @@ -3325,18 +3447,13 @@ nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()* • {name} String The name of the group. See also: ~ - |autocmd-groups| + • |autocmd-groups| nvim_del_autocmd({id}) *nvim_del_autocmd()* - Delete an autocommand by id. - - NOTE: Only autocommands created via the API have an id. + Deletes an autocommand by id. Parameters: ~ - • {id} Integer The id returned by nvim_create_autocmd - - See also: ~ - |nvim_create_autocmd()| + • {id} Integer Autocommand id returned by |nvim_create_autocmd()| nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* Execute all autocommands for {event} that match the corresponding {opts} @@ -3357,23 +3474,23 @@ nvim_exec_autocmds({event}, {*opts}) *nvim_exec_autocmds()* callback. See |nvim_create_autocmd()| for details. See also: ~ - |:doautocmd| + • |:doautocmd| nvim_get_autocmds({*opts}) *nvim_get_autocmds()* Get all autocommands that match the corresponding {opts}. These examples will get autocommands matching ALL the given criteria: >lua - -- Matches all criteria - autocommands = vim.api.nvim_get_autocmds({ - group = "MyGroup", - event = {"BufEnter", "BufWinEnter"}, - pattern = {"*.c", "*.h"} - }) - - -- All commands from one group - autocommands = vim.api.nvim_get_autocmds({ - group = "MyGroup", - }) + -- Matches all criteria + autocommands = vim.api.nvim_get_autocmds({ + group = "MyGroup", + event = {"BufEnter", "BufWinEnter"}, + pattern = {"*.c", "*.h"} + }) + + -- All commands from one group + autocommands = vim.api.nvim_get_autocmds({ + group = "MyGroup", + }) < NOTE: When multiple patterns or events are provided, it will find all the @@ -3420,8 +3537,8 @@ nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()* Implies that the client is ready to show the UI. Adds the client to the list of UIs. |nvim_list_uis()| - Note: - If multiple UI clients are attached, the global screen dimensions + Note: ~ + • If multiple UI clients are attached, the global screen dimensions degrade to the smallest client. E.g. if client A requests 80x40 but client B requests 200x100, the global screen has size 80x40. @@ -3484,6 +3601,22 @@ nvim_ui_set_option({name}, {value}) *nvim_ui_set_option()* Attributes: ~ |RPC| only +nvim_ui_term_event({event}, {value}) *nvim_ui_term_event()* + Tells Nvim when a terminal event has occurred + + The following terminal events are supported: + + • "termresponse": The terminal sent an OSC or DCS response sequence to + Nvim. The payload is the received response. Sets |v:termresponse| and + fires |TermResponse|. + + Attributes: ~ + |RPC| only + + Parameters: ~ + • {event} Event name + • {payload} Event payload + nvim_ui_try_resize({width}, {height}) *nvim_ui_try_resize()* TODO: Documentation diff --git a/runtime/doc/arabic.txt b/runtime/doc/arabic.txt index 0a80edb981..f9d7ee1a8a 100644 --- a/runtime/doc/arabic.txt +++ b/runtime/doc/arabic.txt @@ -231,7 +231,7 @@ o Enable Arabic settings [short-cut] - While in Left-to-right mode, enter ':set rl' in the command line ('rl' is the abbreviation for rightleft). - - Put the ':set rl' line in your vimrc file to start Vim in + - Put the ':set rl' line in your vimrc file to start Vim in right-to-left mode permanently. + Arabic right-to-left command-line Mode diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 8cc4754880..c6f6559e37 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -16,7 +16,7 @@ For a basic explanation, see section |40.3| in the user manual. You can specify commands to be executed automatically when reading or writing a file, when entering or leaving a buffer or window, and when exiting Vim. For example, you can create an autocommand to set the 'cindent' option for -files matching *.c. You can also use autocommands to implement advanced +files matching `*.c`. You can also use autocommands to implement advanced features, such as editing compressed files (see |gzip-example|). The usual place to put autocommands is in your vimrc file. @@ -118,7 +118,7 @@ manually. Mostly the screen will not scroll up, thus there is no hit-enter prompt. When one command outputs two messages this can happen anyway. ============================================================================== -3. Removing autocommands *autocmd-remove* +3. Removing autocommands *autocmd!* *autocmd-remove* :au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd} Remove all autocommands associated with {event} and @@ -197,7 +197,7 @@ For READING FILES there are four kinds of events possible: Vim uses only one of these four kinds when reading a file. The "Pre" and "Post" events are both triggered, before and after reading the file. -Note that the autocommands for the *ReadPre events and all the Filter events +Note that the autocommands for the "*ReadPre" events and all the Filter events are not allowed to change the current buffer (you will get an error message if this happens). This is to prevent the file to be read into the wrong buffer. @@ -212,28 +212,27 @@ events. Nvim recognizes the following events. Names are case-insensitive. *BufAdd* -BufAdd Just after creating a new buffer which is - added to the buffer list, or adding a buffer - to the buffer list, a buffer in the buffer - list was renamed. - Not triggered for the initial buffers created - during startup. +BufAdd After adding a new buffer or existing unlisted + buffer to the buffer list (except during + startup, see |VimEnter|), or renaming a listed + buffer. Before |BufEnter|. - NOTE: Current buffer "%" may be different from - the buffer being created "<afile>". + NOTE: Current buffer "%" is not the target + buffer "<afile>", "<abuf>". |<buffer=abuf>| *BufDelete* BufDelete Before deleting a buffer from the buffer list. The BufUnload may be called first (if the buffer was loaded). Also used just before a buffer in the buffer list is renamed. - NOTE: Current buffer "%" may be different from - the buffer being deleted "<afile>" and "<abuf>". + NOTE: Current buffer "%" is not the target + buffer "<afile>", "<abuf>". |<buffer=abuf>| Do not change to another buffer. *BufEnter* -BufEnter After entering a buffer. Useful for setting - options for a file type. Also executed when - starting to edit a buffer. +BufEnter After entering (visiting, switching-to) a new + or existing buffer. Useful for setting + filetype options. Compare |BufNew| which + does not trigger for existing buffers. After |BufAdd|. After |BufReadPost|. *BufFilePost* @@ -248,8 +247,8 @@ BufHidden Before a buffer becomes hidden: when there are the buffer is not unloaded or deleted. Not used for ":qa" or ":q" when exiting Vim. - NOTE: current buffer "%" may be different from - the buffer being unloaded "<afile>". + NOTE: Current buffer "%" is not the target + buffer "<afile>", "<abuf>". |<buffer=abuf>| *BufLeave* BufLeave Before leaving to another buffer. Also when leaving or closing the current window and the @@ -260,12 +259,14 @@ BufLeave Before leaving to another buffer. Also when BufModifiedSet After the `'modified'` value of a buffer has been changed. *BufNew* -BufNew Just after creating a new buffer. Also used - just after a buffer has been renamed. When - the buffer is added to the buffer list BufAdd - will be triggered too. - NOTE: Current buffer "%" may be different from - the buffer being created "<afile>". +BufNew After creating a new buffer (except during + startup, see |VimEnter|) or renaming an + existing buffer. Unlike |BufEnter|, visiting + (switching to) an existing buffer will not + trigger this again. + NOTE: Current buffer "%" is not the target + buffer "<afile>", "<abuf>". |<buffer=abuf>| + See also |BufAdd|, |BufNewFile|. *BufNewFile* BufNewFile When starting to edit a file that doesn't exist. Can be used to read in a skeleton @@ -292,14 +293,14 @@ BufReadPre When starting to edit a new buffer, before reading the file into the buffer. Not used if the file doesn't exist. *BufUnload* -BufUnload Before unloading a buffer, when the text in +BufUnload Before unloading a buffer, when the text in the buffer is going to be freed. After BufWritePost. Before BufDelete. Triggers for all loaded buffers when Vim is going to exit. - NOTE: Current buffer "%" may be different from - the buffer being unloaded "<afile>". + NOTE: Current buffer "%" is not the target + buffer "<afile>", "<abuf>". |<buffer=abuf>| Do not switch buffers or windows! Not triggered when exiting and v:dying is 2 or more. @@ -319,8 +320,8 @@ BufWinLeave Before a buffer is removed from a window. Not when it's still visible in another window. Also triggered when exiting. Before BufUnload, BufHidden. - NOTE: Current buffer "%" may be different from - the buffer being unloaded "<afile>". + NOTE: Current buffer "%" is not the target + buffer "<afile>", "<abuf>". |<buffer=abuf>| Not triggered when exiting and v:dying is 2 or more. *BufWipeout* @@ -330,8 +331,8 @@ BufWipeout Before completely deleting a buffer. The buffer list). Also used just before a buffer is renamed (also when it's not in the buffer list). - NOTE: Current buffer "%" may be different from - the buffer being deleted "<afile>". + NOTE: Current buffer "%" is not the target + buffer "<afile>", "<abuf>". |<buffer=abuf>| Do not change to another buffer. *BufWrite* *BufWritePre* BufWrite or BufWritePre Before writing the whole buffer to a file. @@ -380,6 +381,7 @@ CmdlineChanged After a change was made to the text inside CmdlineEnter After entering the command-line (including non-interactive use of ":" in a mapping: use |<Cmd>| instead to avoid this). + The pattern is matched against |cmdline-char|. <afile> expands to the |cmdline-char|. Sets these |v:event| keys: cmdlevel @@ -425,7 +427,7 @@ ColorSchemePre Before loading a color scheme. |:colorscheme| Useful to setup removing things added by a color scheme, before another one is loaded. -CompleteChanged *CompleteChanged* +CompleteChanged *CompleteChanged* After each time the Insert mode completion menu changed. Not fired on popup menu hide, use |CompleteDonePre| or |CompleteDone| for @@ -504,8 +506,7 @@ CursorMoved After the cursor was moved in Normal or Visual "x", "rx" or "p". Not always triggered when there is typeahead, while executing commands in a script file, or - when an operator is pending. Always triggered - when moving to another window. + when an operator is pending. For an example see |match-parens|. Note: Cannot be skipped with |:noautocmd|. Careful: This is triggered very often, don't @@ -589,7 +590,7 @@ FileChangedShell When Vim notices that the modification time of Triggered for each changed file, after: - executing a shell command - |:checktime| - - |FocusGained| + - |FocusGained| Not used when 'autoread' is set and the buffer was not changed. If a FileChangedShell @@ -597,8 +598,8 @@ FileChangedShell When Vim notices that the modification time of prompt is not given. |v:fcs_reason| indicates what happened. Set |v:fcs_choice| to control what happens next. - NOTE: Current buffer "%" may be different from - the buffer that was changed "<afile>". + NOTE: Current buffer "%" is not the target + buffer "<afile>" and "<abuf>". |<buffer=abuf>| *E246* *E811* Cannot switch, jump to or delete buffers. Non-recursive (event cannot trigger itself). @@ -703,7 +704,6 @@ InsertCharPre When a character is typed in Insert mode, inserted literally. Cannot change the text. |textlock| - Not triggered when 'paste' is set. *InsertEnter* InsertEnter Just before starting Insert mode. Also for Replace mode and Virtual Replace mode. The @@ -775,11 +775,13 @@ OptionSet After setting an option (except during the option. Similarly |v:option_oldglobal| is only set when |:set| or |:setglobal| was used. - Note that when setting a |global-local| string - option with |:set|, then |v:option_old| is the - old global value. However, for all other kinds - of options (local string options, global-local - number options, ...) it is the old local + This does not set |<abuf>|, you could use + |bufnr()|. + + Note that when setting a |global-local| option + with |:set|, then |v:option_old| is the old + global value. However, for all options that + are not global-local it is the old local value. OptionSet is not triggered on startup and for @@ -859,6 +861,27 @@ RecordingLeave When a macro stops recording. Sets these |v:event| keys: regcontents regname + *SafeState* +SafeState When nothing is pending, going to wait for the + user to type a character. + This will not be triggered when: + - an operator is pending + - a register was entered with "r + - halfway executing a command + - executing a mapping + - there is typeahead + - Insert mode completion is active + - Command line completion is active + You can use `mode()` to find out what state + Vim is in. That may be: + - VIsual mode + - Normal mode + - Insert mode + - Command-line mode + Depending on what you want to do, you may also + check more with `state()`, e.g. whether the + screen was scrolled for messages. + *SessionLoadPost* SessionLoadPost After loading the session file created using the |:mksession| command. @@ -964,12 +987,25 @@ TermClose When a |terminal| job ends. Sets these |v:event| keys: status *TermResponse* -TermResponse After the response to t_RV is received from - the terminal. The value of |v:termresponse| - can be used to do things depending on the - terminal version. May be triggered halfway - through another event (file I/O, a shell - command, or anything else that takes time). +TermResponse When Nvim receives an OSC or DCS response from + the terminal. Sets |v:termresponse|. When used + from Lua, the response string is included in + the "data" field of the autocommand callback. + May be triggered halfway through another event + (file I/O, a shell command, or anything else + that takes time). Example: >lua + + -- Query the terminal palette for the RGB value of color 1 + -- (red) using OSC 4 + vim.api.nvim_create_autocmd('TermResponse', { + once = true, + callback = function(args) + local resp = args.data + local r, g, b = resp:match("\x1b%]4;1;rgb:(%w+)/(%w+)/(%w+)") + end, + }) + io.stdout:write("\x1b]4;1;?\x1b\\") +< *TextChanged* TextChanged After a change was made to the text in the current buffer in Normal mode. That is after @@ -999,7 +1035,7 @@ TextChangedT After a change was made to the text in the *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 *. + for |setreg()|. Pattern must be "*". Sets these |v:event| keys: inclusive operator @@ -1162,7 +1198,7 @@ Set the 'cindent' option for C files in the /vim/src directory. > If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and you start editing "/tmp/test.c", this autocommand will match. -Note: To match part of a path, but not from the root directory, use a '*' as +Note: To match part of a path, but not from the root directory, use a "*" as the first character. Example: > :autocmd BufRead */doc/*.txt set tw=78 This autocommand will for example be executed for "/tmp/doc/xx.txt" and @@ -1415,8 +1451,8 @@ When there is a matching "*Cmd" autocommand, it is assumed it will do the writing. No further writing is done and the other events are not triggered. |Cmd-event| -Note that the *WritePost commands should undo any changes to the buffer that -were caused by the *WritePre commands; otherwise, writing the file will have +Note that the "*WritePost" commands should undo any changes to the buffer that +were caused by the "*WritePre" commands; otherwise, writing the file will have the side effect of changing the buffer. Before executing the autocommands, the buffer from which the lines are to be @@ -1424,15 +1460,15 @@ written temporarily becomes the current buffer. Unless the autocommands change the current buffer or delete the previously current buffer, the previously current buffer is made the current buffer again. -The *WritePre and *AppendPre autocommands must not delete the buffer from +The "*WritePre" and "*AppendPre" autocommands must not delete the buffer from which the lines are to be written. The '[ and '] marks have a special position: -- Before the *ReadPre event the '[ mark is set to the line just above where +- Before the "*ReadPre" event the '[ mark is set to the line just above where the new lines will be inserted. -- Before the *ReadPost event the '[ mark is set to the first line that was +- Before the "*ReadPost" event the '[ mark is set to the first line that was just read, the '] mark to the last line. -- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[ +- Before executing the "*WriteCmd", "*WritePre" and "*AppendPre" autocommands the '[ mark is set to the first line that will be written, the '] mark to the last line. Careful: '[ and '] change when using commands that change the buffer. @@ -1540,7 +1576,7 @@ To read a skeleton (template) file when opening a new file: > :autocmd BufNewFile *.h 0r ~/vim/skeleton.h :autocmd BufNewFile *.java 0r ~/vim/skeleton.java -To insert the current date and time in a *.html file when writing it: > +To insert the current date and time in a "*.html" file when writing it: > :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s :fun LastMod() diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 4d2c85b134..6ffb514487 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -1,7 +1,7 @@ *builtin.txt* Nvim - VIM REFERENCE MANUAL by Bram Moolenaar + NVIM REFERENCE MANUAL Builtin functions *vimscript-functions* *builtin-functions* @@ -9,633 +9,62 @@ Builtin functions *vimscript-functions* *builtin-functions* For functions grouped by what they are used for see |function-list|. Type |gO| to see the table of contents. - -============================================================================== -1. Overview *builtin-function-list* - -Use CTRL-] on the function name to jump to the full explanation. - -USAGE RESULT DESCRIPTION ~ - -abs({expr}) Float or Number absolute value of {expr} -acos({expr}) Float arc cosine of {expr} -add({object}, {item}) List/Blob append {item} to {object} -and({expr}, {expr}) Number bitwise AND -api_info() Dict api metadata -append({lnum}, {text}) Number append {text} below line {lnum} -appendbufline({expr}, {lnum}, {text}) - Number append {text} below line {lnum} - in buffer {expr} -argc([{winid}]) Number number of files in the argument list -argidx() Number current index in the argument list -arglistid([{winnr} [, {tabnr}]]) Number argument list id -argv({nr} [, {winid}]) String {nr} entry of the argument list -argv([-1, {winid}]) List the argument list -asin({expr}) Float arc sine of {expr} -assert_beeps({cmd}) Number assert {cmd} causes a beep -assert_equal({exp}, {act} [, {msg}]) - Number assert {exp} is equal to {act} -assert_equalfile({fname-one}, {fname-two} [, {msg}]) - Number assert file contents are equal -assert_exception({error} [, {msg}]) - Number assert {error} is in v:exception -assert_fails({cmd} [, {error}]) Number assert {cmd} fails -assert_false({actual} [, {msg}]) - Number assert {actual} is false -assert_inrange({lower}, {upper}, {actual} [, {msg}]) - Number assert {actual} is inside the range -assert_match({pat}, {text} [, {msg}]) - Number assert {pat} matches {text} -assert_nobeep({cmd}) Number assert {cmd} does not cause a beep -assert_notequal({exp}, {act} [, {msg}]) - Number assert {exp} is not equal {act} -assert_notmatch({pat}, {text} [, {msg}]) - Number assert {pat} not matches {text} -assert_report({msg}) Number report a test failure -assert_true({actual} [, {msg}]) Number assert {actual} is true -atan({expr}) Float arc tangent of {expr} -atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2} -browse({save}, {title}, {initdir}, {default}) - String put up a file requester -browsedir({title}, {initdir}) String put up a directory requester -bufadd({name}) Number add a buffer to the buffer list -bufexists({expr}) Number |TRUE| if buffer {expr} exists -buflisted({expr}) Number |TRUE| if buffer {expr} is listed -bufload({expr}) Number load buffer {expr} if not loaded yet -bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded -bufname([{expr}]) String Name of the buffer {expr} -bufnr([{expr} [, {create}]]) Number Number of the buffer {expr} -bufwinid({expr}) Number |window-ID| of buffer {expr} -bufwinnr({expr}) Number window number of buffer {expr} -byte2line({byte}) Number line number at byte count {byte} -byteidx({expr}, {nr}) Number byte index of {nr}th char in {expr} -byteidxcomp({expr}, {nr}) Number byte index of {nr}th char in {expr} -call({func}, {arglist} [, {dict}]) - any call {func} with arguments {arglist} -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/UTF-8 value of first char in {expr} -charclass({string}) Number character class of {string} -charcol({expr} [, {winid}]) Number column number of cursor or mark -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} [, {winid}]) Number column byte index of cursor or mark -complete({startcol}, {matches}) none set Insert mode completion -complete_add({expr}) Number add completion match -complete_check() Number check for key typed during completion -complete_info([{what}]) Dict get current completion information -confirm({msg} [, {choices} [, {default} [, {type}]]]) - Number number of choice picked by user -copy({expr}) any make a shallow copy of {expr} -cos({expr}) Float cosine of {expr} -cosh({expr}) Float hyperbolic cosine of {expr} -count({comp}, {expr} [, {ic} [, {start}]]) - Number count how many {expr} are in {comp} -ctxget([{index}]) Dict return the |context| dict at {index} -ctxpop() none pop and restore |context| from the - |context-stack| -ctxpush([{types}]) none push the current |context| to the - |context-stack| -ctxset({context} [, {index}]) none set |context| at {index} -ctxsize() Number return |context-stack| size -cursor({lnum}, {col} [, {off}]) - Number move cursor to {lnum}, {col}, {off} -cursor({list}) Number move cursor to position in {list} -debugbreak({pid}) Number interrupt process being debugged -deepcopy({expr} [, {noref}]) any make a full copy of {expr} -delete({fname} [, {flags}]) Number delete the file or directory {fname} -deletebufline({buf}, {first} [, {last}]) - Number delete lines from buffer {buf} -dictwatcheradd({dict}, {pattern}, {callback}) - Start watching a dictionary -dictwatcherdel({dict}, {pattern}, {callback}) - Stop watching a dictionary -did_filetype() Number |TRUE| if FileType autocommand event used -diff_filler({lnum}) Number diff filler lines about {lnum} -diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col} -digraph_get({chars}) String get the |digraph| of {chars} -digraph_getlist([{listall}]) List get all |digraph|s -digraph_set({chars}, {digraph}) Boolean register |digraph| -digraph_setlist({digraphlist}) Boolean register multiple |digraph|s -empty({expr}) Number |TRUE| if {expr} is empty -environ() Dict return environment variables -escape({string}, {chars}) String escape {chars} in {string} with '\' -eval({string}) any evaluate {string} into its value -eventhandler() Number |TRUE| if inside an event handler -executable({expr}) Number 1 if executable {expr} exists -execute({command}) String execute and capture output of {command} -exepath({expr}) String full path of the command {expr} -exists({expr}) Number |TRUE| if {expr} exists -exp({expr}) Float exponential of {expr} -expand({expr} [, {nosuf} [, {list}]]) - any expand special keywords in {expr} -expandcmd({string} [, {options}]) - String expand {string} like with `:edit` -extend({expr1}, {expr2} [, {expr3}]) - List/Dict insert items of {expr2} into {expr1} -feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer -filereadable({file}) Number |TRUE| if {file} is a readable file -filewritable({file}) Number |TRUE| if {file} is a writable file -filter({expr1}, {expr2}) List/Dict remove items from {expr1} where - {expr2} is 0 -finddir({name} [, {path} [, {count}]]) - String find directory {name} in {path} -findfile({name} [, {path} [, {count}]]) - String find file {name} in {path} -flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels -float2nr({expr}) Number convert Float {expr} to a Number -floor({expr}) Float round {expr} down -fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2} -fnameescape({fname}) String escape special characters in {fname} -fnamemodify({fname}, {mods}) String modify file name -foldclosed({lnum}) Number first line of fold at {lnum} if closed -foldclosedend({lnum}) Number last line of fold at {lnum} if closed -foldlevel({lnum}) Number fold level at {lnum} -foldtext() String line displayed for closed fold -foldtextresult({lnum}) String text for closed fold at {lnum} -fullcommand({name}) String get full command from {name} -funcref({name} [, {arglist}] [, {dict}]) - Funcref reference to function {name} -function({name} [, {arglist}] [, {dict}]) - Funcref named reference to function {name} -garbagecollect([{atexit}]) none free memory, breaking cyclic references -get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def} -get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def} -get({func}, {what}) any get property of funcref/partial {func} -getbufinfo([{buf}]) List information about buffers -getbufline({buf}, {lnum} [, {end}]) - List lines {lnum} to {end} of buffer {buf} -getbufoneline({buf}, {lnum}) String line {lnum} of buffer {buf} -getbufvar({buf}, {varname} [, {def}]) - any variable {varname} in buffer {buf} -getcellwidths() List get character cell width overrides -getchangelist([{buf}]) List list of change list items -getchar([expr]) Number or String - get one character from the user -getcharmod() Number modifiers for the last typed character -getcharpos({expr}) List position of cursor, mark, etc. -getcharsearch() Dict last character search -getcharstr([expr]) String get one character from the user -getcmdcompltype() String return the type of the current - command-line completion -getcmdline() String return the current command-line -getcmdpos() Number return cursor position in command-line -getcmdscreenpos() Number return cursor screen position in - command-line -getcmdtype() String return current command-line type -getcmdwintype() String return current command-line window type -getcompletion({pat}, {type} [, {filtered}]) - List list of cmdline completion matches -getcurpos([{winnr}]) List position of the cursor -getcursorcharpos([{winnr}]) List character position of the cursor -getcwd([{winnr} [, {tabnr}]]) String get the current working directory -getenv({name}) String return environment variable -getfontname([{name}]) String name of font being used -getfperm({fname}) String file permissions of file {fname} -getfsize({fname}) Number size in bytes of file {fname} -getftime({fname}) Number last modification time of file -getftype({fname}) String description of type of file {fname} -getjumplist([{winnr} [, {tabnr}]]) - List list of jump list items -getline({lnum}) String line {lnum} of current buffer -getline({lnum}, {end}) List lines {lnum} to {end} of current buffer -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 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} -gettabwinvar({tabnr}, {winnr}, {name} [, {def}]) - any {name} in {winnr} in tab page {tabnr} -gettagstack([{nr}]) Dict get the tag stack of window {nr} -gettext({text}) String lookup translation of {text} -getwininfo([{winid}]) List list of info about each window -getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window -getwinposx() Number X coord in pixels of Vim window -getwinposy() Number Y coord in pixels of Vim window -getwinvar({nr}, {varname} [, {def}]) - any variable {varname} in window {nr} -glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) - any expand file wildcards in {expr} -glob2regpat({expr}) String convert a glob pat into a search pat -globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) - String do glob({expr}) for all dirs in {path} -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 the window executed |:lcd| or - the tab executed |:tcd| -hasmapto({what} [, {mode} [, {abbr}]]) - Number |TRUE| if mapping to {what} exists -histadd({history}, {item}) Number add an item to a history -histdel({history} [, {item}]) Number remove an item from a history -histget({history} [, {index}]) String get the item {index} from a history -histnr({history}) Number highest index of a history -hlID({name}) Number syntax ID of highlight group {name} -hlexists({name}) Number |TRUE| if highlight group {name} exists -hostname() String name of the machine Vim is running on -iconv({expr}, {from}, {to}) String convert encoding of {expr} -indent({lnum}) Number indent of line {lnum} -index({object}, {expr} [, {start} [, {ic}]]) - Number index in {object} where {expr} appears -input({prompt} [, {text} [, {completion}]]) - String get input from the user -inputlist({textlist}) Number let the user pick from a choice list -inputrestore() Number restore typeahead -inputsave() Number save and clear typeahead -inputsecret({prompt} [, {text}]) - String like input() but hiding the text -insert({object}, {item} [, {idx}]) - List insert {item} in {object} [before {idx}] -interrupt() none interrupt script execution -invert({expr}) Number bitwise invert -isdirectory({directory}) Number |TRUE| if {directory} is a directory -isinf({expr}) Number determine if {expr} is infinity value - (positive or negative) -islocked({expr}) Number |TRUE| if {expr} is locked -isnan({expr}) Number |TRUE| if {expr} is NaN -id({expr}) String identifier of the container -items({dict}) List key-value pairs in {dict} -jobpid({id}) Number Returns pid of a job. -jobresize({id}, {width}, {height}) - Number Resize pseudo terminal window of a job -jobstart({cmd} [, {opts}]) Number Spawns {cmd} as a job -jobstop({id}) Number Stops a job -jobwait({ids} [, {timeout}]) Number Wait for a set of jobs -join({list} [, {sep}]) String join {list} items into one String -json_decode({expr}) any Convert {expr} from JSON -json_encode({expr}) String Convert {expr} to JSON -keys({dict}) List keys in {dict} -keytrans({string}) String translate internal keycodes to a form - that can be used by |:map| -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} [, {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 -localtime() Number current time -log({expr}) Float natural logarithm (base e) of {expr} -log10({expr}) Float logarithm of Float {expr} to base 10 -luaeval({expr} [, {expr}]) any evaluate |Lua| expression -map({expr1}, {expr2}) List/Dict change each item in {expr1} to {expr} -maparg({name} [, {mode} [, {abbr} [, {dict}]]]) - String or Dict - rhs of mapping {name} in mode {mode} -mapcheck({name} [, {mode} [, {abbr}]]) - String check for mappings matching {name} -mapset({mode}, {abbr}, {dict}) - none restore mapping from |maparg()| result -match({expr}, {pat} [, {start} [, {count}]]) - Number position where {pat} matches in {expr} -matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) - Number highlight {pattern} with {group} -matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) - Number highlight positions with {group} -matcharg({nr}) List arguments of |:match| -matchdelete({id} [, {win}]) Number delete match identified by {id} -matchend({expr}, {pat} [, {start} [, {count}]]) - Number position where {pat} ends in {expr} -matchfuzzy({list}, {str} [, {dict}]) - List fuzzy match {str} in {list} -matchfuzzypos({list}, {str} [, {dict}]) - List fuzzy match {str} in {list} -matchlist({expr}, {pat} [, {start} [, {count}]]) - List match and submatches of {pat} in {expr} -matchstr({expr}, {pat} [, {start} [, {count}]]) - String {count}th match of {pat} in {expr} -matchstrpos({expr}, {pat} [, {start} [, {count}]]) - List {count}th match of {pat} in {expr} -max({expr}) Number maximum value of items in {expr} -menu_get({path} [, {modes}]) List description of |menus| matched by {path} -menu_info({name} [, {mode}]) Dict get menu item information -min({expr}) Number minimum value of items in {expr} -mkdir({name} [, {path} [, {prot}]]) - Number create directory {name} -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/UTF-8 value {expr} -nvim_...({args}...) any call nvim |api| functions -or({expr}, {expr}) Number bitwise OR -pathshorten({expr} [, {len}]) String shorten directory names in a path -perleval({expr}) any evaluate |perl| expression -pow({x}, {y}) Float {x} to the power of {y} -prevnonblank({lnum}) Number line nr of non-blank line <= {lnum} -printf({fmt}, {expr1}...) String format text -prompt_getprompt({buf}) String get prompt text -prompt_setcallback({buf}, {expr}) none set prompt callback function -prompt_setinterrupt({buf}, {text}) none set prompt interrupt function -prompt_setprompt({buf}, {text}) none set prompt text -pum_getpos() Dict position and size of pum if visible -pumvisible() Number whether popup menu is visible -py3eval({expr}) any evaluate |python3| expression -pyeval({expr}) any evaluate |Python| expression -pyxeval({expr}) any evaluate |python_x| expression -rand([{expr}]) Number get pseudo-random number -range({expr} [, {max} [, {stride}]]) - List items from {expr} to {max} -readblob({fname}) Blob read a |Blob| from {fname} -readdir({dir} [, {expr}]) List file names in {dir} selected by {expr} -readfile({fname} [, {type} [, {max}]]) - List get list of lines from file {fname} -reduce({object}, {func} [, {initial}]) - any reduce {object} using {func} -reg_executing() String get the executing register name -reg_recorded() String get the last recorded register name -reg_recording() String get the recording register name -reltime([{start} [, {end}]]) List get time value -reltimefloat({time}) Float turn the time value into a Float -reltimestr({time}) String turn time value into a String -remove({list}, {idx} [, {end}]) any/List - remove items {idx}-{end} from {list} -remove({blob}, {idx} [, {end}]) Number/Blob - remove bytes {idx}-{end} from {blob} -remove({dict}, {key}) any remove entry {key} from {dict} -rename({from}, {to}) Number rename (move) file from {from} to {to} -repeat({expr}, {count}) String repeat {expr} {count} times -resolve({filename}) String get filename a shortcut points to -reverse({list}) List reverse {list} in-place -round({expr}) Float round off {expr} -rubyeval({expr}) any evaluate |Ruby| expression -rpcnotify({channel}, {event} [, {args}...]) - Sends an |RPC| notification to {channel} -rpcrequest({channel}, {method} [, {args}...]) - Sends an |RPC| request to {channel} -screenattr({row}, {col}) Number attribute at screen position -screenchar({row}, {col}) Number character at screen position -screenchars({row}, {col}) List List of characters at screen position -screencol() Number current cursor column -screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character -screenrow() Number current cursor row -screenstring({row}, {col}) String characters at screen position -search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) - Number search for {pattern} -searchcount([{options}]) Dict Get or update the last search count -searchdecl({name} [, {global} [, {thisblock}]]) - Number search for variable declaration -searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) - Number search for other end of start/end pair -searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) - List search for other end of start/end pair -searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) - List search for {pattern} -serverlist() String get a list of available servers -setbufline({expr}, {lnum}, {text}) - Number set line {lnum} to {text} in buffer - {expr} -setbufvar({buf}, {varname}, {val}) set {varname} in buffer {buf} to {val} -setcellwidths({list}) none set character cell width overrides -setcharpos({expr}, {list}) Number set the {expr} position to {list} -setcharsearch({dict}) Dict set character search from {dict} -setcmdline({str} [, {pos}]) Number set command-line -setcmdpos({pos}) Number set cursor position in command-line -setcursorcharpos({list}) Number move cursor to position in {list} -setenv({name}, {val}) none set environment variable -setfperm({fname}, {mode} Number set {fname} file permissions to {mode} -setline({lnum}, {line}) Number set line {lnum} to {line} -setloclist({nr}, {list} [, {action}]) - Number modify location list using {list} -setloclist({nr}, {list}, {action}, {what}) - Number modify specific location list props -setmatches({list} [, {win}]) Number restore a list of matches -setpos({expr}, {list}) Number set the {expr} position to {list} -setqflist({list} [, {action}]) Number modify quickfix list using {list} -setqflist({list}, {action}, {what}) - Number modify specific quickfix list props -setreg({n}, {v} [, {opt}]) Number set register to value and type -settabvar({nr}, {varname}, {val}) set {varname} in tab page {nr} to {val} -settabwinvar({tabnr}, {winnr}, {varname}, {val}) set {varname} in window - {winnr} in tab page {tabnr} to {val} -settagstack({nr}, {dict} [, {action}]) - Number modify tag stack using {dict} -setwinvar({nr}, {varname}, {val}) set {varname} in window {nr} to {val} -sha256({string}) String SHA256 checksum of {string} -shellescape({string} [, {special}]) - String escape {string} for use as shell - command argument -shiftwidth([{col}]) Number effective value of 'shiftwidth' -sign_define({name} [, {dict}]) Number define or update a sign -sign_define({list}) List define or update a list of signs -sign_getdefined([{name}]) List get a list of defined signs -sign_getplaced([{buf} [, {dict}]]) - List get a list of placed signs -sign_jump({id}, {group}, {buf}) - Number jump to a sign -sign_place({id}, {group}, {name}, {buf} [, {dict}]) - Number place a sign -sign_placelist({list}) List place a list of signs -sign_undefine([{name}]) Number undefine a sign -sign_undefine({list}) List undefine a list of signs -sign_unplace({group} [, {dict}]) - Number unplace a sign -sign_unplacelist({list}) List unplace a list of signs -simplify({filename}) String simplify filename as much as possible -sin({expr}) Float sine of {expr} -sinh({expr}) Float hyperbolic sine of {expr} -sockconnect({mode}, {address} [, {opts}]) - Number Connects to socket -sort({list} [, {func} [, {dict}]]) - List sort {list}, using {func} to compare -soundfold({word}) String sound-fold {word} -spellbadword() String badly spelled word at cursor -spellsuggest({word} [, {max} [, {capital}]]) - List spelling suggestions -split({expr} [, {pat} [, {keepempty}]]) - List make |List| from {pat} separated {expr} -sqrt({expr}) Float square root of {expr} -srand([{expr}]) List get seed for |rand()| -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/UTF-8 value -str2nr({expr} [, {base} [, {quoted}]]) - Number convert String to Number -strcharlen({expr}) Number character length of the String {expr} -strcharpart({str}, {start} [, {len}]) - String {len} characters of {str} at - character {start} -strchars({expr} [, {skipcc}]) Number character count of the String {expr} -strdisplaywidth({expr} [, {col}]) Number display length of the String {expr} -strftime({format} [, {time}]) String format time with a specified format -strgetchar({str}, {index}) Number get char {index} from {str} -stridx({haystack}, {needle} [, {start}]) - Number index of {needle} in {haystack} -string({expr}) String String representation of {expr} value -strlen({expr}) Number length of the String {expr} -strpart({str}, {start} [, {len} [, {chars}]]) - String {len} bytes/chars of {str} at - byte {start} -strptime({format}, {timestring}) - Number Convert {timestring} to unix timestamp -strridx({haystack}, {needle} [, {start}]) - Number last index of {needle} in {haystack} -strtrans({expr}) String translate string to make it printable -strwidth({expr}) Number display cell length of the String {expr} -submatch({nr} [, {list}]) String or List - specific match in ":s" or substitute() -substitute({expr}, {pat}, {sub}, {flags}) - String all {pat} in {expr} replaced with {sub} -swapinfo({fname}) Dict information about swap file {fname} -swapname({buf}) String swap file of buffer {buf} -synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col} -synIDattr({synID}, {what} [, {mode}]) - String attribute {what} of syntax ID {synID} -synIDtrans({synID}) Number translated syntax ID of {synID} -synconcealed({lnum}, {col}) List info about concealing -synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col} -system({cmd} [, {input}]) String output of shell command/filter {cmd} -systemlist({cmd} [, {input}]) List output of shell command/filter {cmd} -tabpagebuflist([{arg}]) List list of buffer numbers in tab page -tabpagenr([{arg}]) Number number of current or last tab page -tabpagewinnr({tabarg} [, {arg}]) - Number number of current window in tab page -tagfiles() List tags files used -taglist({expr} [, {filename}]) List list of tags matching {expr} -tan({expr}) Float tangent of {expr} -tanh({expr}) Float hyperbolic tangent of {expr} -tempname() String name for a temporary file -test_garbagecollect_now() none free memory right now for testing -timer_info([{id}]) List information about timers -timer_pause({id}, {pause}) none pause or unpause a timer -timer_start({time}, {callback} [, {options}]) - Number create a timer -timer_stop({timer}) none stop a timer -timer_stopall() none stop all timers -tolower({expr}) String the String {expr} switched to lowercase -toupper({expr}) String the String {expr} switched to uppercase -tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr} - to chars in {tostr} -trim({text} [, {mask} [, {dir}]]) - String trim characters in {mask} from {text} -trunc({expr}) Float truncate Float {expr} -type({name}) Number type of variable {name} -undofile({name}) String undo file name for {name} -undotree() List undo file tree -uniq({list} [, {func} [, {dict}]]) - List remove adjacent duplicates from a list -values({dict}) List values in {dict} -virtcol({expr}) Number screen column of cursor or mark -virtcol2col({winid}, {lnum}, {col}) - Number byte index of a character on screen -visualmode([expr]) String last visual mode used -wait({timeout}, {condition} [, {interval}]) - Number Wait until {condition} is satisfied -wildmenumode() Number whether 'wildmenu' mode is active -win_execute({id}, {command} [, {silent}]) - String execute {command} in window {id} -win_findbuf({bufnr}) List find windows containing {bufnr} -win_getid([{win} [, {tab}]]) Number get |window-ID| for {win} in {tab} -win_gettype([{nr}]) String type of window {nr} -win_gotoid({expr}) Number go to |window-ID| {expr} -win_id2tabwin({expr}) List get tab and window nr from |window-ID| -win_id2win({expr}) Number get window nr from |window-ID| -win_move_separator({nr}) Number move window vertical separator -win_move_statusline({nr}) Number move window status line -win_screenpos({nr}) List get screen position of window {nr} -win_splitmove({nr}, {target} [, {options}]) - Number move window {nr} to split of {target} -winbufnr({nr}) Number buffer number of window {nr} -wincol() Number window column of the cursor -windowsversion() String MS-Windows OS version -winheight({nr}) Number height of window {nr} -winlayout([{tabnr}]) List layout of windows in tab {tabnr} -winline() Number window line of the cursor -winnr([{expr}]) Number number of current window -winrestcmd() String returns command to restore window sizes -winrestview({dict}) none restore view of current window -winsaveview() Dict save view of current window -winwidth({nr}) Number width of window {nr} -wordcount() Dict get byte/char/word statistics -writefile({object}, {fname} [, {flags}]) - Number write |Blob| or |List| of lines to file -xor({expr}, {expr}) Number bitwise XOR - ============================================================================== -2. Details *builtin-function-details* - -Not all functions are here, some have been moved to a help file covering the -specific functionality. +1. Details *builtin-function-details* -abs({expr}) *abs()* +abs({expr}) *abs()* Return the absolute value of {expr}. When {expr} evaluates to a |Float| abs() returns a |Float|. When {expr} can be converted to a |Number| abs() returns a |Number|. Otherwise abs() gives an error message and returns -1. - Examples: > + Examples: >vim echo abs(1.456) -< 1.456 > +< 1.456 >vim echo abs(-5.456) -< 5.456 > +< 5.456 >vim echo abs(-4) < 4 - Can also be used as a |method|: > - Compute()->abs() - -acos({expr}) *acos()* +acos({expr}) *acos()* Return the arc cosine of {expr} measured in radians, as a |Float| in the range of [0, pi]. {expr} must evaluate to a |Float| or a |Number| in the range [-1, 1]. Returns NaN if {expr} is outside the range [-1, 1]. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo acos(0) -< 1.570796 > - :echo acos(-0.5) + Examples: >vim + echo acos(0) +< 1.570796 >vim + echo acos(-0.5) < 2.094395 - Can also be used as a |method|: > - Compute()->acos() - -add({object}, {expr}) *add()* +add({object}, {expr}) *add()* Append the item {expr} to |List| or |Blob| {object}. Returns - the resulting |List| or |Blob|. Examples: > - :let alist = add([1, 2, 3], item) - :call add(mylist, "woodstock") + the resulting |List| or |Blob|. Examples: >vim + let alist = add([1, 2, 3], item) + call add(mylist, "woodstock") < Note that when {expr} is a |List| it is appended as a single item. Use |extend()| to concatenate |Lists|. When {object} is a |Blob| then {expr} must be a number. Use |insert()| to add an item at another position. Returns 1 if {object} is not a |List| or a |Blob|. - Can also be used as a |method|: > - mylist->add(val1)->add(val2) - -and({expr}, {expr}) *and()* +and({expr}, {expr}) *and()* Bitwise AND on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. - Example: > - :let flag = and(bits, 0x80) -< Can also be used as a |method|: > - :let flag = bits->and(0x80) + Also see `or()` and `xor()`. + Example: >vim + let flag = and(bits, 0x80) +< -api_info() *api_info()* +api_info() *api_info()* Returns Dictionary of |api-metadata|. - View it in a nice human-readable format: > - :lua print(vim.inspect(vim.fn.api_info())) + View it in a nice human-readable format: >vim + lua vim.print(vim.fn.api_info()) +< -append({lnum}, {text}) *append()* +append({lnum}, {text}) *append()* When {text} is a |List|: Append each item of the |List| as a text line below line {lnum} in the current buffer. Otherwise append {text} as one text line below line {lnum} in @@ -644,14 +73,13 @@ append({lnum}, {text}) *append()* {lnum} can be zero to insert a line before the first one. {lnum} is used like with |getline()|. Returns 1 for failure ({lnum} out of range or out of memory), - 0 for success. Example: > - :let failed = append(line('$'), "# THE END") - :let failed = append(0, ["Chapter 1", "the beginning"]) - -< Can also be used as a |method| after a List: > - mylist->append(lnum) + 0 for success. When {text} is an empty list zero is returned, + no matter the value of {lnum}. Example: >vim + let failed = append(line('$'), "# THE END") + let failed = append(0, ["Chapter 1", "the beginning"]) +< -appendbufline({buf}, {lnum}, {text}) *appendbufline()* +appendbufline({buf}, {lnum}, {text}) *appendbufline()* Like |append()| but append the text in buffer {expr}. This function works only for loaded buffers. First call @@ -667,13 +95,12 @@ appendbufline({buf}, {lnum}, {text}) *appendbufline()* On success 0 is returned, on failure 1 is returned. If {buf} is not a valid buffer or {lnum} is not valid, an - error message is given. Example: > - :let failed = appendbufline(13, 0, "# THE START") -< - Can also be used as a |method| after a List: > - mylist->appendbufline(buf, lnum) + error message is given. Example: >vim + let failed = appendbufline(13, 0, "# THE START") +< However, when {text} is an empty list then no error is given + for an invalid {lnum}, since {lnum} isn't actually used. -argc([{winid}]) *argc()* +argc([{winid}]) *argc()* The result is the number of files in the argument list. See |arglist|. If {winid} is not supplied, the argument list of the current @@ -683,12 +110,11 @@ argc([{winid}]) *argc()* list is used: either the window number or the window ID. Returns -1 if the {winid} argument is invalid. - *argidx()* -argidx() The result is the current index in the argument list. 0 is +argidx() *argidx()* + The result is the current index in the argument list. 0 is the first file. argc() - 1 is the last one. See |arglist|. - *arglistid()* -arglistid([{winnr} [, {tabnr}]]) +arglistid([{winnr} [, {tabnr}]]) *arglistid()* Return the argument list ID. This is a number which identifies the argument list being used. Zero is used for the global argument list. See |arglist|. @@ -700,16 +126,15 @@ arglistid([{winnr} [, {tabnr}]]) page. {winnr} can be the window number or the |window-ID|. - *argv()* -argv([{nr} [, {winid}]]) +argv([{nr} [, {winid}]]) *argv()* The result is the {nr}th file in the argument list. See - |arglist|. "argv(0)" is the first one. Example: > - :let i = 0 - :while i < argc() - : let f = escape(fnameescape(argv(i)), '.') - : exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>' - : let i = i + 1 - :endwhile + |arglist|. "argv(0)" is the first one. Example: >vim + let i = 0 + while i < argc() + let f = escape(fnameescape(argv(i)), '.') + exe 'amenu Arg.' .. f .. ' :e ' .. f .. '<CR>' + let i = i + 1 + endwhile < Without the {nr} argument, or when {nr} is -1, a |List| with the whole |arglist| is returned. @@ -720,57 +145,193 @@ argv([{nr} [, {winid}]]) the argument list. Returns an empty List if the {winid} argument is invalid. -asin({expr}) *asin()* +asin({expr}) *asin()* Return the arc sine of {expr} measured in radians, as a |Float| in the range of [-pi/2, pi/2]. {expr} must evaluate to a |Float| or a |Number| in the range [-1, 1]. Returns NaN if {expr} is outside the range [-1, 1]. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo asin(0.8) -< 0.927295 > - :echo asin(-0.5) + Examples: >vim + echo asin(0.8) +< 0.927295 >vim + echo asin(-0.5) < -0.523599 - Can also be used as a |method|: > - Compute()->asin() - - -assert_ functions are documented here: |assert-functions-details| - - -atan({expr}) *atan()* +assert_beeps({cmd}) *assert_beeps()* + Run {cmd} and add an error message to |v:errors| if it does + NOT produce a beep or visual bell. + Also see |assert_fails()|, |assert_nobeep()| and + |assert-return|. + +assert_equal({expected}, {actual} [, {msg}]) *assert_equal()* + When {expected} and {actual} are not equal an error message is + added to |v:errors| and 1 is returned. Otherwise zero is + returned. |assert-return| + The error is in the form "Expected {expected} but got + {actual}". When {msg} is present it is prefixed to that. + + There is no automatic conversion, the String "4" is different + from the Number 4. And the number 4 is different from the + Float 4.0. The value of 'ignorecase' is not used here, case + always matters. + Example: >vim + assert_equal('foo', 'bar') +< Will result in a string to be added to |v:errors|: + test.vim line 12: Expected 'foo' but got 'bar' ~ + +assert_equalfile({fname-one}, {fname-two}) *assert_equalfile()* + When the files {fname-one} and {fname-two} do not contain + exactly the same text an error message is added to |v:errors|. + Also see |assert-return|. + When {fname-one} or {fname-two} does not exist the error will + mention that. + +assert_exception({error} [, {msg}]) *assert_exception()* + When v:exception does not contain the string {error} an error + message is added to |v:errors|. Also see |assert-return|. + This can be used to assert that a command throws an exception. + Using the error number, followed by a colon, avoids problems + with translations: >vim + try + commandthatfails + call assert_false(1, 'command should have failed') + catch + call assert_exception('E492:') + endtry +< + + *assert_fails()* +assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) + Run {cmd} and add an error message to |v:errors| if it does + NOT produce an error or when {error} is not found in the + error message. Also see |assert-return|. + + When {error} is a string it must be found literally in the + first reported error. Most often this will be the error code, + including the colon, e.g. "E123:". >vim + assert_fails('bad cmd', 'E987:') +< + When {error} is a |List| with one or two strings, these are + used as patterns. The first pattern is matched against the + first reported error: >vim + assert_fails('cmd', ['E987:.*expected bool']) +< The second pattern, if present, is matched against the last + reported error. To only match the last error use an empty + string for the first error: >vim + assert_fails('cmd', ['', 'E987:']) +< + If {msg} is empty then it is not used. Do this to get the + default message when passing the {lnum} argument. + + When {lnum} is present and not negative, and the {error} + argument is present and matches, then this is compared with + the line number at which the error was reported. That can be + the line number in a function or in a script. + + When {context} is present it is used as a pattern and matched + against the context (script name or function name) where + {lnum} is located in. + + Note that beeping is not considered an error, and some failing + commands only beep. Use |assert_beeps()| for those. + +assert_false({actual} [, {msg}]) *assert_false()* + When {actual} is not false an error message is added to + |v:errors|, like with |assert_equal()|. + The error is in the form "Expected False but got {actual}". + When {msg} is present it is prepended to that. + Also see |assert-return|. + + A value is false when it is zero. When {actual} is not a + number the assert fails. + +assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* + This asserts number and |Float| values. When {actual} is lower + than {lower} or higher than {upper} an error message is added + to |v:errors|. Also see |assert-return|. + The error is in the form "Expected range {lower} - {upper}, + but got {actual}". When {msg} is present it is prefixed to + that. + +assert_match({pattern}, {actual} [, {msg}]) *assert_match()* + When {pattern} does not match {actual} an error message is + added to |v:errors|. Also see |assert-return|. + The error is in the form "Pattern {pattern} does not match + {actual}". When {msg} is present it is prefixed to that. + + {pattern} is used as with |expr-=~|: The matching is always done + like 'magic' was set and 'cpoptions' is empty, no matter what + the actual value of 'magic' or 'cpoptions' is. + + {actual} is used as a string, automatic conversion applies. + Use "^" and "$" to match with the start and end of the text. + Use both to match the whole text. + + Example: >vim + assert_match('^f.*o$', 'foobar') +< Will result in a string to be added to |v:errors|: + test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~ + +assert_nobeep({cmd}) *assert_nobeep()* + Run {cmd} and add an error message to |v:errors| if it + produces a beep or visual bell. + Also see |assert_beeps()|. + +assert_notequal({expected}, {actual} [, {msg}]) *assert_notequal()* + The opposite of `assert_equal()`: add an error message to + |v:errors| when {expected} and {actual} are equal. + Also see |assert-return|. + +assert_notmatch({pattern}, {actual} [, {msg}]) *assert_notmatch()* + The opposite of `assert_match()`: add an error message to + |v:errors| when {pattern} matches {actual}. + Also see |assert-return|. + +assert_report({msg}) *assert_report()* + Report a test failure directly, using String {msg}. + Always returns one. + +assert_true({actual} [, {msg}]) *assert_true()* + When {actual} is not true an error message is added to + |v:errors|, like with |assert_equal()|. + Also see |assert-return|. + A value is |TRUE| when it is a non-zero number or |v:true|. + When {actual} is not a number or |v:true| the assert fails. + When {msg} is given it precedes the default message. + +atan({expr}) *atan()* Return the principal value of the arc tangent of {expr}, in the range [-pi/2, +pi/2] radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo atan(100) -< 1.560797 > - :echo atan(-4.01) + Examples: >vim + echo atan(100) +< 1.560797 >vim + echo atan(-4.01) < -1.326405 - Can also be used as a |method|: > - Compute()->atan() - -atan2({expr1}, {expr2}) *atan2()* +atan2({expr1}, {expr2}) *atan2()* Return the arc tangent of {expr1} / {expr2}, measured in radians, as a |Float| in the range [-pi, pi]. {expr1} and {expr2} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr1} or {expr2} is not a |Float| or a |Number|. - Examples: > - :echo atan2(-1, 1) -< -0.785398 > - :echo atan2(1, -1) + Examples: >vim + echo atan2(-1, 1) +< -0.785398 >vim + echo atan2(1, -1) < 2.356194 - Can also be used as a |method|: > - Compute()->atan2(1) +blob2list({blob}) *blob2list()* + Return a List containing the number value of each byte in Blob + {blob}. Examples: >vim + blob2list(0z0102.0304) " returns [1, 2, 3, 4] + blob2list(0z) " returns [] +< Returns an empty List on error. |list2blob()| does the + opposite. - *browse()* -browse({save}, {title}, {initdir}, {default}) +browse({save}, {title}, {initdir}, {default}) *browse()* Put up a file requester. This only works when "has("browse")" returns |TRUE| (only in some GUI versions). The input fields are: @@ -781,8 +342,7 @@ browse({save}, {title}, {initdir}, {default}) An empty string is returned when the "Cancel" button is hit, something went wrong, or browsing is not possible. - *browsedir()* -browsedir({title}, {initdir}) +browsedir({title}, {initdir}) *browsedir()* Put up a directory requester. This only works when "has("browse")" returns |TRUE| (only in some GUI versions). On systems where a directory browser is not supported a file @@ -794,7 +354,7 @@ browsedir({title}, {initdir}) When the "Cancel" button is hit, something went wrong, or browsing is not possible, an empty string is returned. -bufadd({name}) *bufadd()* +bufadd({name}) *bufadd()* Add a buffer to the buffer list with name {name} (must be a String). If a buffer for file {name} already exists, return that buffer @@ -802,15 +362,13 @@ bufadd({name}) *bufadd()* created buffer. When {name} is an empty string then a new buffer is always created. The buffer will not have 'buflisted' set and not be loaded - yet. To add some text to the buffer use this: > + yet. To add some text to the buffer use this: >vim let bufnr = bufadd('someName') call bufload(bufnr) call setbufline(bufnr, 1, ['some', 'text']) < Returns 0 on error. - Can also be used as a |method|: > - let bufnr = 'somename'->bufadd() -bufexists({buf}) *bufexists()* +bufexists({buf}) *bufexists()* The result is a Number, which is |TRUE| if a buffer called {buf} exists. If the {buf} argument is a number, buffer numbers are used. @@ -832,39 +390,27 @@ bufexists({buf}) *bufexists()* Use "bufexists(0)" to test for the existence of an alternate file name. - Can also be used as a |method|: > - let exists = 'somename'->bufexists() - -buflisted({buf}) *buflisted()* +buflisted({buf}) *buflisted()* The result is a Number, which is |TRUE| if a buffer called {buf} exists and is listed (has the 'buflisted' option set). The {buf} argument is used like with |bufexists()|. - Can also be used as a |method|: > - let listed = 'somename'->buflisted() - -bufload({buf}) *bufload()* +bufload({buf}) *bufload()* Ensure the buffer {buf} is loaded. When the buffer name refers to an existing file then the file is read. Otherwise the buffer will be empty. If the buffer was already loaded then there is no change. If the buffer is not related to a - file the no file is read (e.g., when 'buftype' is "nofile"). + file then no file is read (e.g., when 'buftype' is "nofile"). If there is an existing swap file for the file of the buffer, there will be no dialog, the buffer will be loaded anyway. The {buf} argument is used like with |bufexists()|. - Can also be used as a |method|: > - eval 'somename'->bufload() - -bufloaded({buf}) *bufloaded()* +bufloaded({buf}) *bufloaded()* The result is a Number, which is |TRUE| if a buffer called {buf} exists and is loaded (shown in a window or hidden). The {buf} argument is used like with |bufexists()|. - Can also be used as a |method|: > - let loaded = 'somename'->bufloaded() - -bufname([{buf}]) *bufname()* +bufname([{buf}]) *bufname()* The result is the name of a buffer. Mostly as it is displayed by the `:ls` command, but not using special names such as "[No Name]". @@ -885,65 +431,53 @@ bufname([{buf}]) *bufname()* with a listed buffer, that one is returned. Next unlisted buffers are searched for. If the {buf} is a String, but you want to use it as a buffer - number, force it to be a Number by adding zero to it: > - :echo bufname("3" + 0) -< Can also be used as a |method|: > - echo bufnr->bufname() - + number, force it to be a Number by adding zero to it: >vim + echo bufname("3" + 0) < If the buffer doesn't exist, or doesn't have a name, an empty - string is returned. > - bufname("#") alternate buffer name - bufname(3) name of buffer 3 - bufname("%") name of current buffer - bufname("file2") name of buffer where "file2" matches. -< - *bufnr()* -bufnr([{buf} [, {create}]]) + string is returned. >vim + echo bufname("#") " alternate buffer name + echo bufname(3) " name of buffer 3 + echo bufname("%") " name of current buffer + echo bufname("file2") " name of buffer where "file2" matches. +< + +bufnr([{buf} [, {create}]]) *bufnr()* The result is the number of a buffer, as it is displayed by the `:ls` command. For the use of {buf}, see |bufname()| above. If the buffer doesn't exist, -1 is returned. Or, if the {create} argument is present and TRUE, a new, unlisted, buffer is created and its number is returned. - bufnr("$") is the last buffer: > - :let last_buffer = bufnr("$") + bufnr("$") is the last buffer: >vim + let last_buffer = bufnr("$") < The result is a Number, which is the highest buffer number of existing buffers. Note that not all buffers with a smaller number necessarily exist, because ":bwipeout" may have removed them. Use bufexists() to test for the existence of a buffer. - Can also be used as a |method|: > - echo bufref->bufnr() - -bufwinid({buf}) *bufwinid()* +bufwinid({buf}) *bufwinid()* The result is a Number, which is the |window-ID| of the first window associated with buffer {buf}. For the use of {buf}, see |bufname()| above. If buffer {buf} doesn't exist or - there is no such window, -1 is returned. Example: > + there is no such window, -1 is returned. Example: >vim - echo "A window containing buffer 1 is " .. (bufwinid(1)) + echo "A window containing buffer 1 is " .. (bufwinid(1)) < Only deals with the current tab page. See |win_findbuf()| for finding more. - Can also be used as a |method|: > - FindBuffer()->bufwinid() - -bufwinnr({buf}) *bufwinnr()* +bufwinnr({buf}) *bufwinnr()* Like |bufwinid()| but return the window number instead of the |window-ID|. If buffer {buf} doesn't exist or there is no such window, -1 - is returned. Example: > + is returned. Example: >vim - echo "A window containing buffer 1 is " .. (bufwinnr(1)) + echo "A window containing buffer 1 is " .. (bufwinnr(1)) < The number can be used with |CTRL-W_w| and ":wincmd w" |:wincmd|. - Can also be used as a |method|: > - FindBuffer()->bufwinnr() - -byte2line({byte}) *byte2line()* +byte2line({byte}) *byte2line()* Return the line number that contains the character at byte count {byte} in the current buffer. This includes the end-of-line character, depending on the 'fileformat' option @@ -953,10 +487,7 @@ byte2line({byte}) *byte2line()* Returns -1 if the {byte} value is invalid. - Can also be used as a |method|: > - GetOffset()->byte2line() - -byteidx({expr}, {nr}) *byteidx()* +byteidx({expr}, {nr} [, {utf16}]) *byteidx()* Return byte index of the {nr}th character in the String {expr}. Use zero for the first character, it then returns zero. @@ -966,10 +497,17 @@ byteidx({expr}, {nr}) *byteidx()* length is added to the preceding base character. See |byteidxcomp()| below for counting composing characters separately. - Example : > + When {utf16} is present and TRUE, {nr} is used as the UTF-16 + index in the String {expr} instead of as the character index. + The UTF-16 index is the index in the string when it is encoded + with 16-bit words. If the specified UTF-16 index is in the + middle of a character (e.g. in a 4-byte character), then the + byte index of the first byte in the character is returned. + Refer to |string-offset-encoding| for more information. + Example : >vim echo matchstr(str, ".", byteidx(str, 3)) < will display the fourth character. Another way to do the - same: > + same: >vim let s = strpart(str, byteidx(str, 3)) echo strpart(s, 0, byteidx(s, 1)) < Also see |strgetchar()| and |strcharpart()|. @@ -977,13 +515,17 @@ byteidx({expr}, {nr}) *byteidx()* If there are less than {nr} characters -1 is returned. If there are exactly {nr} characters the length of the string in bytes is returned. + See |charidx()| and |utf16idx()| for getting the character and + UTF-16 index respectively from the byte index. + Examples: >vim + echo byteidx('a😊😊', 2) " returns 5 + echo byteidx('a😊😊', 2, 1) " returns 1 + echo byteidx('a😊😊', 3, 1) " returns 5 +< - Can also be used as a |method|: > - GetName()->byteidx(idx) - -byteidxcomp({expr}, {nr}) *byteidxcomp()* +byteidxcomp({expr}, {nr} [, {utf16}]) *byteidxcomp()* Like byteidx(), except that a composing character is counted - as a separate character. Example: > + as a separate character. Example: >vim let s = 'e' .. nr2char(0x301) echo byteidx(s, 1) echo byteidxcomp(s, 1) @@ -992,10 +534,7 @@ byteidxcomp({expr}, {nr}) *byteidxcomp()* character is 3 bytes), the second echo results in 1 ('e' is one byte). - Can also be used as a |method|: > - GetName()->byteidxcomp(idx) - -call({func}, {arglist} [, {dict}]) *call()* *E699* +call({func}, {arglist} [, {dict}]) *call()* *E699* Call function {func} with the items in |List| {arglist} as arguments. {func} can either be a |Funcref| or the name of a function. @@ -1004,36 +543,21 @@ call({func}, {arglist} [, {dict}]) *call()* *E699* {dict} is for functions with the "dict" attribute. It will be used to set the local variable "self". |Dictionary-function| - Can also be used as a |method|: > - GetFunc()->call([arg, arg], dict) - -ceil({expr}) *ceil()* +ceil({expr}) *ceil()* Return the smallest integral value greater than or equal to {expr} as a |Float| (round up). {expr} must evaluate to a |Float| or a |Number|. - Examples: > + Examples: >vim echo ceil(1.456) -< 2.0 > +< 2.0 >vim echo ceil(-5.456) -< -5.0 > +< -5.0 >vim echo ceil(4.0) < 4.0 Returns 0.0 if {expr} is not a |Float| or a |Number|. - Can also be used as a |method|: > - Compute()->ceil() - -changenr() *changenr()* - Return the number of the most recent change. This is the same - number as what is displayed with |:undolist| and can be used - with the |:undo| command. - When a change was made it is the number of that change. After - redo it is the number of the redone change. After undo it is - one less than the number of the undone change. - Returns 0 if the undo list is empty. - -chanclose({id} [, {stream}]) *chanclose()* +chanclose({id} [, {stream}]) *chanclose()* Close a channel or a specific stream associated with it. For a job, {stream} can be one of "stdin", "stdout", "stderr" or "rpc" (closes stdin/stdout for a job started @@ -1043,7 +567,16 @@ chanclose({id} [, {stream}]) *chanclose()* For a socket, there is only one stream, and {stream} should be omitted. -chansend({id}, {data}) *chansend()* +changenr() *changenr()* + Return the number of the most recent change. This is the same + number as what is displayed with |:undolist| and can be used + with the |:undo| command. + When a change was made it is the number of that change. After + redo it is the number of the redone change. After undo it is + one less than the number of the undone change. + Returns 0 if the undo list is empty. + +chansend({id}, {data}) *chansend()* Send data to channel {id}. For a job, it writes it to the stdin of the process. For the stdio channel |channel-stdio|, it writes to Nvim's stdout. Returns the number of bytes @@ -1053,23 +586,22 @@ chansend({id}, {data}) *chansend()* {data} may be a string, string convertible, |Blob|, or a list. If {data} is a list, the items will be joined by newlines; any newlines in an item will be sent as NUL. To send a final - newline, include a final empty string. Example: > - :call chansend(id, ["abc", "123\n456", ""]) -< will send "abc<NL>123<NUL>456<NL>". + newline, include a final empty string. Example: >vim + call chansend(id, ["abc", "123\n456", ""]) +< will send "abc<NL>123<NUL>456<NL>". chansend() writes raw data, not RPC messages. If the channel was created with `"rpc":v:true` then the channel expects RPC messages, use |rpcnotify()| and |rpcrequest()| instead. - -char2nr({string} [, {utf8}]) *char2nr()* +char2nr({string} [, {utf8}]) *char2nr()* Return Number value of the first char in {string}. - Examples: > - char2nr(" ") returns 32 - char2nr("ABC") returns 65 - char2nr("á") returns 225 - char2nr("á"[0]) returns 195 - char2nr("\<M-x>") returns 128 + Examples: >vim + echo char2nr(" ") " returns 32 + echo char2nr("ABC") " returns 65 + echo char2nr("á") " returns 225 + echo char2nr("á"[0]) " returns 195 + echo char2nr("\<M-x>") " returns 128 < Non-ASCII characters are always treated as UTF-8 characters. {utf8} is ignored, it exists only for backwards-compatibility. A combining character is a separate character. @@ -1077,10 +609,7 @@ char2nr({string} [, {utf8}]) *char2nr()* Returns 0 if {string} is not a |String|. - Can also be used as a |method|: > - GetChar()->char2nr() - -charclass({string}) *charclass()* +charclass({string}) *charclass()* Return the character class of the first character in {string}. The character class is one of: 0 blank @@ -1091,46 +620,50 @@ charclass({string}) *charclass()* The class is used in patterns and word motions. Returns 0 if {string} is not a |String|. - -charcol({expr} [, {winid}]) *charcol()* +charcol({expr} [, {winid}]) *charcol()* Same as |col()| but returns the character index of the column position given with {expr} instead of the byte position. Example: - With the cursor on '세' in line 5 with text "여보세요": > - charcol('.') returns 3 - col('.') returns 7 + With the cursor on '세' in line 5 with text "여보세요": >vim + echo charcol('.') " returns 3 + echo col('.') " returns 7 -< Can also be used as a |method|: > - GetPos()->col() -< - *charidx()* -charidx({string}, {idx} [, {countcc}]) +charidx({string}, {idx} [, {countcc} [, {utf16}]]) *charidx()* Return the character index of the byte at {idx} in {string}. The index of the first character is zero. If there are no multibyte characters the returned value is equal to {idx}. + When {countcc} is omitted or |FALSE|, then composing characters - are not counted separately, their byte length is - added to the preceding base character. + are not counted separately, their byte length is added to the + preceding base character. When {countcc} is |TRUE|, then composing characters are counted as separate characters. - Returns -1 if the arguments are invalid or if {idx} is greater - than the index of the last byte in {string}. An error is - given if the first argument is not a string, the second - argument is not a number or when the third argument is present - and is not zero or one. + + When {utf16} is present and TRUE, {idx} is used as the UTF-16 + index in the String {expr} instead of as the byte index. + + Returns -1 if the arguments are invalid or if there are less + than {idx} bytes. If there are exactly {idx} bytes the length + of the string in characters is returned. + + An error is given and -1 is returned if the first argument is + not a string, the second argument is not a number or when the + third argument is present and is not zero or one. + See |byteidx()| and |byteidxcomp()| for getting the byte index - from the character index. - Examples: > - echo charidx('áb́ć', 3) returns 1 - echo charidx('áb́ć', 6, 1) returns 4 - echo charidx('áb́ć', 16) returns -1 + from the character index and |utf16idx()| for getting the + UTF-16 index from the character index. + Refer to |string-offset-encoding| for more information. + Examples: >vim + echo charidx('áb́ć', 3) " returns 1 + echo charidx('áb́ć', 6, 1) " returns 4 + echo charidx('áb́ć', 16) " returns -1 + echo charidx('a😊😊', 4, 0, 1) " returns 2 < - Can also be used as a |method|: > - GetName()->charidx(idx) -chdir({dir}) *chdir()* +chdir({dir}) *chdir()* Change the current working directory to {dir}. The scope of the directory change depends on the directory of the current window: @@ -1145,17 +678,14 @@ chdir({dir}) *chdir()* this to another chdir() to restore the directory. On failure, returns an empty string. - Example: > + Example: >vim let save_dir = chdir(newdir) if save_dir != "" " ... do some work call chdir(save_dir) endif -< Can also be used as a |method|: > - GetDir()->chdir() -< -cindent({lnum}) *cindent()* +cindent({lnum}) *cindent()* Get the amount of indent for line {lnum} according the C indenting rules, as with 'cindent'. The indent is counted in spaces, the value of 'tabstop' is @@ -1163,19 +693,13 @@ cindent({lnum}) *cindent()* When {lnum} is invalid -1 is returned. See |C-indenting|. - Can also be used as a |method|: > - GetLnum()->cindent() - -clearmatches([{win}]) *clearmatches()* +clearmatches([{win}]) *clearmatches()* Clears all matches previously defined for the current window by |matchadd()| and the |:match| commands. 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|: > - GetWin()->clearmatches() -< -col({expr} [, {winid}) *col()* +col({expr} [, {winid}]) *col()* The result is a Number, which is the byte index of the column position given with {expr}. The accepted positions are: . the cursor position @@ -1198,11 +722,11 @@ col({expr} [, {winid}) *col()* For the screen column position use |virtcol()|. For the character position use |charcol()|. Note that only marks in the current file can be used. - Examples: > - col(".") column of cursor - col("$") length of cursor line plus one - col("'t") column of mark t - col("'" .. markname) column of mark markname + Examples: >vim + echo col(".") " column of cursor + echo col("$") " length of cursor line plus one + echo col("'t") " column of mark t + echo col("'" .. markname) " column of mark markname < The first column is 1. Returns 0 if {expr} is invalid or when the window with ID {winid} is not found. For an uppercase mark the column may actually be in another @@ -1210,14 +734,10 @@ col({expr} [, {winid}) *col()* For the cursor position, when 'virtualedit' is active, the column is one higher if the cursor is after the end of the line. Also, when using a <Cmd> mapping the cursor isn't - moved, this can be used to obtain the column in Insert mode: > - :imap <F2> <Cmd>echo col(".").."\n"<CR> - -< Can also be used as a |method|: > - GetPos()->col() -< + moved, this can be used to obtain the column in Insert mode: >vim + imap <F2> <Cmd>echo col(".").."\n"<CR> -complete({startcol}, {matches}) *complete()* *E785* +complete({startcol}, {matches}) *complete()* *E785* Set the matches for Insert mode completion. Can only be used in Insert mode. You need to use a mapping with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O @@ -1235,23 +755,19 @@ complete({startcol}, {matches}) *complete()* *E785* The match can be selected with CTRL-N and CTRL-P as usual with Insert mode completion. The popup menu will appear if specified, see |ins-completion-menu|. - Example: > - inoremap <F5> <C-R>=ListMonths()<CR> - - func! ListMonths() - call complete(col('.'), ['January', 'February', 'March', - \ 'April', 'May', 'June', 'July', 'August', 'September', - \ 'October', 'November', 'December']) - return '' - endfunc + Example: >vim + inoremap <F5> <C-R>=ListMonths()<CR> + + func ListMonths() + call complete(col('.'), ['January', 'February', 'March', + \ 'April', 'May', 'June', 'July', 'August', 'September', + \ 'October', 'November', 'December']) + return '' + endfunc < This isn't very useful, but it shows how it works. Note that an empty string is returned to avoid a zero being inserted. - Can also be used as a |method|, the base is passed as the - second argument: > - GetMatches()->complete(col('.')) - -complete_add({expr}) *complete_add()* +complete_add({expr}) *complete_add()* Add {expr} to the list of matches. Only to be used by the function specified with the 'completefunc' option. Returns 0 for failure (empty string or out of memory), @@ -1260,10 +776,7 @@ complete_add({expr}) *complete_add()* See |complete-functions| for an explanation of {expr}. It is the same as one item in the list that 'omnifunc' would return. - Can also be used as a |method|: > - GetMoreMatches()->complete_add() - -complete_check() *complete_check()* +complete_check() *complete_check()* Check for a key typed while looking for completion matches. This is to be used when looking for matches takes some time. Returns |TRUE| when searching for matches is to be aborted, @@ -1271,8 +784,7 @@ complete_check() *complete_check()* Only to be used by the function specified with the 'completefunc' option. - -complete_info([{what}]) *complete_info()* +complete_info([{what}]) *complete_info()* Returns a |Dictionary| with information about Insert mode completion. See |ins-completion|. The items are: @@ -1322,7 +834,7 @@ complete_info([{what}]) *complete_info()* Returns an empty |Dictionary| on error. - Examples: > + Examples: >vim " Get all items call complete_info() " Get only 'mode' @@ -1330,11 +842,7 @@ complete_info([{what}]) *complete_info()* " Get only 'mode' and 'pum_visible' call complete_info(['mode', 'pum_visible']) -< Can also be used as a |method|: > - GetItems()->complete_info() -< - *confirm()* -confirm({msg} [, {choices} [, {default} [, {type}]]]) +confirm({msg} [, {choices} [, {default} [, {type}]]]) *confirm()* confirm() offers the user a dialog, from which a choice can be made. It returns the number of the choice. For the first choice this is 1. @@ -1346,11 +854,11 @@ confirm({msg} [, {choices} [, {default} [, {type}]]]) some systems the string is wrapped when it doesn't fit. {choices} is a String, with the individual choices separated - by '\n', e.g. > + by '\n', e.g. >vim confirm("Save changes?", "&Yes\n&No\n&Cancel") < The letter after the '&' is the shortcut key for that choice. Thus you can type 'c' to select "Cancel". The shortcut does - not need to be the first letter: > + not need to be the first letter: >vim confirm("file has been modified", "&Save\nSave &All") < For the console, the first letter of each choice is used as the default shortcut key. Case is ignored. @@ -1369,7 +877,7 @@ confirm({msg} [, {choices} [, {default} [, {type}]]]) If the user aborts the dialog by pressing <Esc>, CTRL-C, or another valid interrupt key, confirm() returns 0. - An example: > + An example: >vim let choice = confirm("What do you want?", \ "&Apples\n&Oranges\n&Bananas", 2) if choice == 0 @@ -1386,11 +894,8 @@ confirm({msg} [, {choices} [, {default} [, {type}]]]) don't fit, a vertical layout is used anyway. For some systems the horizontal layout is always used. - Can also be used as a |method|in: > - BuildMessage()->confirm("&Yes\n&No") -< - *copy()* -copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't +copy({expr}) *copy()* + Make a copy of {expr}. For Numbers and Strings this isn't different from using {expr} directly. When {expr} is a |List| a shallow copy is created. This means that the original |List| can be changed without changing the @@ -1398,37 +903,29 @@ copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't changing an item changes the contents of both |Lists|. A |Dictionary| is copied in a similar way as a |List|. Also see |deepcopy()|. - Can also be used as a |method|: > - mylist->copy() -cos({expr}) *cos()* +cos({expr}) *cos()* Return the cosine of {expr}, measured in radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo cos(100) -< 0.862319 > - :echo cos(-4.01) + Examples: >vim + echo cos(100) +< 0.862319 >vim + echo cos(-4.01) < -0.646043 - Can also be used as a |method|: > - Compute()->cos() - -cosh({expr}) *cosh()* +cosh({expr}) *cosh()* Return the hyperbolic cosine of {expr} as a |Float| in the range [1, inf]. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo cosh(0.5) -< 1.127626 > - :echo cosh(-0.5) + Examples: >vim + echo cosh(0.5) +< 1.127626 >vim + echo cosh(-0.5) < -1.127626 - Can also be used as a |method|: > - Compute()->cosh() - -count({comp}, {expr} [, {ic} [, {start}]]) *count()* +count({comp}, {expr} [, {ic} [, {start}]]) *count()* *E706* Return the number of times an item with value {expr} appears in |String|, |List| or |Dictionary| {comp}. @@ -1441,36 +938,33 @@ count({comp}, {expr} [, {ic} [, {start}]]) *count()* occurrences of {expr} is returned. Zero is returned when {expr} is an empty string. - Can also be used as a |method|: > - mylist->count(val) -< -ctxget([{index}]) *ctxget()* +ctxget([{index}]) *ctxget()* Returns a |Dictionary| representing the |context| at {index} from the top of the |context-stack| (see |context-dict|). If {index} is not given, it is assumed to be 0 (i.e.: top). -ctxpop() *ctxpop()* +ctxpop() *ctxpop()* Pops and restores the |context| at the top of the |context-stack|. -ctxpush([{types}]) *ctxpush()* +ctxpush([{types}]) *ctxpush()* Pushes the current editor state (|context|) on the |context-stack|. If {types} is given and is a |List| of |String|s, it specifies which |context-types| to include in the pushed context. Otherwise, all context types are included. -ctxset({context} [, {index}]) *ctxset()* +ctxset({context} [, {index}]) *ctxset()* Sets the |context| at {index} from the top of the |context-stack| to that represented by {context}. {context} is a Dictionary with context data (|context-dict|). If {index} is not given, it is assumed to be 0 (i.e.: top). -ctxsize() *ctxsize()* +ctxsize() *ctxsize()* Returns the size of the |context-stack|. -cursor({lnum}, {col} [, {off}]) *cursor()* -cursor({list}) +cursor({lnum}, {col} [, {off}]) +cursor({list}) *cursor()* Positions the cursor at the column (byte count) {col} in the line {lnum}. The first column is one. @@ -1482,7 +976,7 @@ cursor({list}) This is like the return value of |getpos()| or |getcurpos()|, but without the first item. - To position the cursor using the character count, use + To position the cursor using {col} as the character count, use |setcursorcharpos()|. Does not change the jumplist. @@ -1502,10 +996,7 @@ cursor({list}) position within a <Tab> or after the last character. Returns 0 when the position could be set, -1 otherwise. - Can also be used as a |method|: > - GetCursorPos()->cursor() - -debugbreak({pid}) *debugbreak()* +debugbreak({pid}) *debugbreak()* Specifically used to interrupt a program being debugged. It will cause process {pid} to get a SIGTRAP. Behavior for other processes is undefined. See |terminal-debug|. @@ -1514,10 +1005,7 @@ debugbreak({pid}) *debugbreak()* Returns |TRUE| if successfully interrupted the program. Otherwise returns |FALSE|. - Can also be used as a |method|: > - GetPid()->debugbreak() - -deepcopy({expr} [, {noref}]) *deepcopy()* *E698* +deepcopy({expr} [, {noref}]) *deepcopy()* *E698* Make a copy of {expr}. For Numbers and Strings this isn't different from using {expr} directly. When {expr} is a |List| a full copy is created. This means @@ -1537,10 +1025,7 @@ deepcopy({expr} [, {noref}]) *deepcopy()* *E698* {noref} set to 1 will fail. Also see |copy()|. - Can also be used as a |method|: > - GetObject()->deepcopy() - -delete({fname} [, {flags}]) *delete()* +delete({fname} [, {flags}]) *delete()* Without {flags} or with {flags} empty: Deletes the file by the name {fname}. @@ -1559,10 +1044,7 @@ delete({fname} [, {flags}]) *delete()* operation was successful and -1/true when the deletion failed or partly failed. - Can also be used as a |method|: > - GetName()->delete() - -deletebufline({buf}, {first} [, {last}]) *deletebufline()* +deletebufline({buf}, {first} [, {last}]) *deletebufline()* Delete lines {first} to {last} (inclusive) from buffer {buf}. If {last} is omitted then delete line {first} only. On success 0 is returned, on failure 1 is returned. @@ -1576,10 +1058,7 @@ deletebufline({buf}, {first} [, {last}]) *deletebufline()* when using |line()| this refers to the current buffer. Use "$" to refer to the last line in buffer {buf}. - Can also be used as a |method|: > - GetBuffer()->deletebufline(1) -< -dictwatcheradd({dict}, {pattern}, {callback}) *dictwatcheradd()* +dictwatcheradd({dict}, {pattern}, {callback}) *dictwatcheradd()* Adds a watcher to a dictionary. A dictionary watcher is identified by three components: @@ -1590,7 +1069,7 @@ dictwatcheradd({dict}, {pattern}, {callback}) *dictwatcheradd()* After this is called, every change on {dict} and on keys matching {pattern} will result in {callback} being invoked. - For example, to watch all global variables: > + For example, to watch all global variables: >vim silent! call dictwatcherdel(g:, '*', 'OnDictChanged') function! OnDictChanged(d,k,z) echomsg string(a:k) string(a:z) @@ -1619,13 +1098,13 @@ dictwatcheradd({dict}, {pattern}, {callback}) *dictwatcheradd()* This function can be used by plugins to implement options with validation and parsing logic. -dictwatcherdel({dict}, {pattern}, {callback}) *dictwatcherdel()* +dictwatcherdel({dict}, {pattern}, {callback}) *dictwatcherdel()* Removes a watcher added with |dictwatcheradd()|. All three arguments must match the ones passed to |dictwatcheradd()| in order for the watcher to be successfully deleted. - *did_filetype()* -did_filetype() Returns |TRUE| when autocommands are being executed and the +did_filetype() *did_filetype()* + Returns |TRUE| when autocommands are being executed and the FileType event has been triggered at least once. Can be used to avoid triggering the FileType event again in the scripts that detect the file type. |FileType| @@ -1636,7 +1115,7 @@ did_filetype() Returns |TRUE| when autocommands are being executed and the editing another buffer to set 'filetype' and load a syntax file. -diff_filler({lnum}) *diff_filler()* +diff_filler({lnum}) *diff_filler()* Returns the number of filler lines above line {lnum}. These are the lines that were inserted at this point in another diff'ed window. These filler lines are shown in the @@ -1645,10 +1124,7 @@ diff_filler({lnum}) *diff_filler()* line, "'m" mark m, etc. Returns 0 if the current window is not in diff mode. - Can also be used as a |method|: > - GetLnum()->diff_filler() - -diff_hlID({lnum}, {col}) *diff_hlID()* +diff_hlID({lnum}, {col}) *diff_hlID()* Returns the highlight ID for diff mode at line {lnum} column {col} (byte index). When the current line does not have a diff change zero is returned. @@ -1659,11 +1135,7 @@ diff_hlID({lnum}, {col}) *diff_hlID()* The highlight ID can be used with |synIDattr()| to obtain syntax information about the highlighting. - Can also be used as a |method|: > - GetLnum()->diff_hlID(col) -< - -digraph_get({chars}) *digraph_get()* *E1214* +digraph_get({chars}) *digraph_get()* *E1214* Return the digraph of {chars}. This should be a string with exactly two characters. If {chars} are not just two characters, or the digraph of {chars} does not exist, an error @@ -1671,37 +1143,31 @@ digraph_get({chars}) *digraph_get()* *E1214* Also see |digraph_getlist()|. - Examples: > + Examples: >vim " Get a built-in digraph - :echo digraph_get('00') " Returns '∞' + echo digraph_get('00') " Returns '∞' " Get a user-defined digraph - :call digraph_set('aa', 'あ') - :echo digraph_get('aa') " Returns 'あ' -< - Can also be used as a |method|: > - GetChars()->digraph_get() + call digraph_set('aa', 'あ') + echo digraph_get('aa') " Returns 'あ' < -digraph_getlist([{listall}]) *digraph_getlist()* +digraph_getlist([{listall}]) *digraph_getlist()* Return a list of digraphs. If the {listall} argument is given and it is TRUE, return all digraphs, including the default digraphs. Otherwise, return only user-defined digraphs. Also see |digraph_get()|. - Examples: > + Examples: >vim " Get user-defined digraphs - :echo digraph_getlist() + echo digraph_getlist() " Get all the digraphs, including default digraphs - :echo digraph_getlist(1) -< - Can also be used as a |method|: > - GetNumber()->digraph_getlist() + echo digraph_getlist(1) < -digraph_set({chars}, {digraph}) *digraph_set()* +digraph_set({chars}, {digraph}) *digraph_set()* Add digraph {chars} to the list. {chars} must be a string with two characters. {digraph} is a string with one UTF-8 encoded character. *E1215* @@ -1715,33 +1181,33 @@ digraph_set({chars}, {digraph}) *digraph_set()* If you want to define multiple digraphs at once, you can use |digraph_setlist()|. - Example: > + Example: >vim call digraph_set(' ', 'あ') < - Can be used as a |method|: > + Can be used as a |method|: >vim GetString()->digraph_set('あ') < -digraph_setlist({digraphlist}) *digraph_setlist()* +digraph_setlist({digraphlist}) *digraph_setlist()* Similar to |digraph_set()| but this function can add multiple digraphs at once. {digraphlist} is a list composed of lists, where each list contains two strings with {chars} and {digraph} as in |digraph_set()|. *E1216* - Example: > + Example: >vim call digraph_setlist([['aa', 'あ'], ['ii', 'い']]) < - It is similar to the following: > + It is similar to the following: >vim for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']] call digraph_set(chars, digraph) endfor < Except that the function returns after the first error, following digraphs will not be added. - Can be used as a |method|: > + Can be used as a |method|: >vim GetList()->digraph_setlist() < -empty({expr}) *empty()* +empty({expr}) *empty()* Return the Number 1 if {expr} is empty, zero otherwise. - A |List| or |Dictionary| is empty when it does not have any items. @@ -1750,45 +1216,37 @@ empty({expr}) *empty()* - |v:false| and |v:null| are empty, |v:true| is not. - A |Blob| is empty when its length is zero. - Can also be used as a |method|: > - mylist->empty() - -environ() *environ()* +environ() *environ()* Return all of environment variables as dictionary. You can - check if an environment variable exists like this: > - :echo has_key(environ(), 'HOME') + check if an environment variable exists like this: >vim + echo has_key(environ(), 'HOME') < Note that the variable name may be CamelCase; to ignore case - use this: > - :echo index(keys(environ()), 'HOME', 0, 1) != -1 + use this: >vim + echo index(keys(environ()), 'HOME', 0, 1) != -1 +< -escape({string}, {chars}) *escape()* +escape({string}, {chars}) *escape()* Escape the characters in {chars} that occur in {string} with a - backslash. Example: > - :echo escape('c:\program files\vim', ' \') + backslash. Example: >vim + echo escape('c:\program files\vim', ' \') < results in: > 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 +eval({string}) *eval()* + Evaluate {string} and return the result. Especially useful to turn the result of |string()| back into the original value. This works for Numbers, Floats, Strings, Blobs and composites of them. Also works for |Funcref|s that refer to existing functions. - Can also be used as a |method|: > - argv->join()->eval() - -eventhandler() *eventhandler()* +eventhandler() *eventhandler()* Returns 1 when inside an event handler. That is that Vim got interrupted while waiting for the user to type a character, e.g., when dropping a file on Vim. This means interactive commands cannot be used. Otherwise zero is returned. -executable({expr}) *executable()* +executable({expr}) *executable()* This function checks if an executable with the name {expr} exists. {expr} must be the name of the program without any arguments. @@ -1811,16 +1269,14 @@ 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} [, {silent}]) *execute()* Execute {command} and capture its output. If {command} is a |String|, returns {command} output. If {command} is a |List|, returns concatenated outputs. - Examples: > + Line continuations in {command} are not recognized. + Examples: >vim echo execute('echon "foo"') -< foo > +< foo >vim echo execute(['echon "foo"', 'echon "bar"']) < foobar @@ -1831,7 +1287,7 @@ execute({command} [, {silent}]) *execute()* The default is "silent". Note that with "silent!", unlike `:redir`, error messages are dropped. - To get a list of lines use |split()| on the result: > + To get a list of lines use `split()` on the result: >vim execute('args')->split("\n") < This function is not available in the |sandbox|. @@ -1841,20 +1297,14 @@ 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()* +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 +exists({expr}) *exists()* + The result is a Number, which is |TRUE| if {expr} is defined, zero otherwise. For checking for a supported feature use |has()|. @@ -1867,11 +1317,11 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is entries, |List| items, etc. Beware that evaluating an index may cause an error message for an invalid - expression. E.g.: > - :let l = [1, 2, 3] - :echo exists("l[5]") -< 0 > - :echo exists("l[xx]") + expression. E.g.: >vim + let l = [1, 2, 3] + echo exists("l[5]") +< 0 >vim + echo exists("l[xx]") < E121: Undefined variable: xx 0 &option-name Vim option (only checks if it exists, @@ -1880,7 +1330,7 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is $ENVNAME environment variable (could also be done by comparing with an empty string) - *funcname built-in function (see |functions|) + `*funcname` built-in function (see |functions|) or user defined function (see |user-function|). Also works for a variable that is a Funcref. @@ -1911,55 +1361,49 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is ##event autocommand for this event is supported. - Examples: > - exists("&mouse") - exists("$HOSTNAME") - exists("*strftime") - exists("*s:MyFunc") - exists("*MyFunc") - exists("bufcount") - exists(":Make") - exists("#CursorHold") - exists("#BufReadPre#*.gz") - exists("#filetypeindent") - exists("#filetypeindent#FileType") - exists("#filetypeindent#FileType#*") - exists("##ColorScheme") + Examples: >vim + echo exists("&mouse") + echo exists("$HOSTNAME") + echo exists("*strftime") + echo exists("*s:MyFunc") + echo exists("*MyFunc") + echo exists("bufcount") + echo exists(":Make") + echo exists("#CursorHold") + echo exists("#BufReadPre#*.gz") + echo exists("#filetypeindent") + echo exists("#filetypeindent#FileType") + echo exists("#filetypeindent#FileType#*") + echo exists("##ColorScheme") < There must be no space between the symbol (&/$/*/#) and the name. There must be no extra characters after the name, although in a few cases this is ignored. That may become stricter in the future, thus don't count on it! - Working example: > - exists(":make") -< NOT working example: > - exists(":make install") + Working example: >vim + echo exists(":make") +< NOT working example: >vim + echo exists(":make install") < Note that the argument must be a string, not the name of the - variable itself. For example: > - exists(bufcount) + variable itself. For example: >vim + echo exists(bufcount) < 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()* +exp({expr}) *exp()* Return the exponential of {expr} as a |Float| in the range [0, inf]. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo exp(2) -< 7.389056 > - :echo exp(-1) + Examples: >vim + echo exp(2) +< 7.389056 >vim + echo exp(-1) < 0.367879 - Can also be used as a |method|: > - Compute()->exp() - -expand({string} [, {nosuf} [, {list}]]) *expand()* - Expand wildcards and the following special keywords in +expand({string} [, {nosuf} [, {list}]]) *expand()* + Expand wildcards and the following special keywords in {string}. 'wildignorecase' applies. If {list} is given and it is |TRUE|, a List will be returned. @@ -2003,18 +1447,18 @@ expand({string} [, {nosuf} [, {list}]]) *expand()* :r root (one extension removed) :e extension only - Example: > - :let &tags = expand("%:p:h") .. "/tags" + Example: >vim + let &tags = expand("%:p:h") .. "/tags" < Note that when expanding a string that starts with '%', '#' or - '<', any following text is ignored. This does NOT work: > - :let doesntwork = expand("%:h.bak") -< Use this: > - :let doeswork = expand("%:h") .. ".bak" + '<', any following text is ignored. This does NOT work: >vim + let doesntwork = expand("%:h.bak") +< Use this: >vim + let doeswork = expand("%:h") .. ".bak" < Also note that expanding "<cfile>" and others only returns the referenced file name without further expansion. If "<cfile>" is "~/.cshrc", you need to do another expand() to have the - "~/" expanded into the path of the home directory: > - :echo expand(expand("<cfile>")) + "~/" expanded into the path of the home directory: >vim + echo expand(expand("<cfile>")) < There cannot be white space between the variables and the following modifier. The |fnamemodify()| function can be used @@ -2034,8 +1478,8 @@ expand({string} [, {nosuf} [, {list}]]) *expand()* {nosuf} argument is given and it is |TRUE|. Names for non-existing files are included. The "**" item can be used to search in a directory tree. For example, to find - all "README" files in the current directory and below: > - :echo expand("**/README") + all "README" files in the current directory and below: >vim + echo expand("**/README") < expand() can also be used to expand variables and environment variables that are only known in a shell. But this can be @@ -2049,10 +1493,7 @@ 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({string} [, {options}]) *expandcmd()* +expandcmd({string} [, {options}]) *expandcmd()* Expand special items in String {string} like what is done for an Ex command such as `:edit`. This expands special keywords, like with |expand()|, and environment variables, anywhere in @@ -2068,15 +1509,15 @@ expandcmd({string} [, {options}]) *expandcmd()* Returns the expanded string. If an error is encountered during expansion, the unmodified {string} is returned. - Example: > - :echo expandcmd('make %<.o') + Example: >vim + echo expandcmd('make %<.o') +< > make /path/runtime/doc/builtin.o - :echo expandcmd('make %<.o', {'errmsg': v:true}) +< >vim + echo expandcmd('make %<.o', {'errmsg': v:true}) < - Can also be used as a |method|: > - GetCommand()->expandcmd() -< -extend({expr1}, {expr2} [, {expr3}]) *extend()* + +extend({expr1}, {expr2} [, {expr3}]) *extend()* {expr1} and {expr2} must be both |Lists| or both |Dictionaries|. @@ -2085,16 +1526,16 @@ extend({expr1}, {expr2} [, {expr3}]) *extend()* item with index {expr3} in {expr1}. When {expr3} is zero insert before the first item. When {expr3} is equal to len({expr1}) then {expr2} is appended. - Examples: > - :echo sort(extend(mylist, [7, 5])) - :call extend(mylist, [2, 3], 1) + Examples: >vim + echo sort(extend(mylist, [7, 5])) + call extend(mylist, [2, 3], 1) < When {expr1} is the same List as {expr2} then the number of items copied is equal to the original length of the List. E.g., when {expr3} is 1 you get N new copies of the first item (where N is the original length of the List). Use |add()| to concatenate one item to a list. To concatenate - two lists into a new list use the + operator: > - :let newlist = [1, 2, 3] + [4, 5] + two lists into a new list use the + operator: >vim + let newlist = [1, 2, 3] + [4, 5] < If they are |Dictionaries|: Add all entries from {expr2} to {expr1}. @@ -2112,10 +1553,12 @@ extend({expr1}, {expr2} [, {expr3}]) *extend()* fails. Returns {expr1}. Returns 0 on error. - Can also be used as a |method|: > - mylist->extend(otherlist) +extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()* + Like |extend()| but instead of adding items to {expr1} a new + List or Dictionary is created and returned. {expr1} remains + unchanged. -feedkeys({string} [, {mode}]) *feedkeys()* +feedkeys({string} [, {mode}]) *feedkeys()* Characters in {string} are queued for processing as if they come from a mapping or were typed by the user. @@ -2160,39 +1603,35 @@ feedkeys({string} [, {mode}]) *feedkeys()* Return value is always 0. - Can also be used as a |method|: > - GetInput()->feedkeys() - -filereadable({file}) *filereadable()* +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, or is a directory, the result is |FALSE|. {file} is any expression, which is used as a String. If you don't care about the file being readable you can use |glob()|. - {file} is used as-is, you may want to expand wildcards first: > + {file} is used as-is, you may want to expand wildcards first: >vim echo filereadable('~/.vimrc') +< > 0 +< >vim echo filereadable(expand('~/.vimrc')) +< > 1 +< -< Can also be used as a |method|: > - GetName()->filereadable() - -filewritable({file}) *filewritable()* +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()->filewritable() - -filter({expr1}, {expr2}) *filter()* - {expr1} must be a |List|, |Blob|, or a |Dictionary|. +filter({expr1}, {expr2}) *filter()* + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. For each item in {expr1} evaluate {expr2} and when the result - is zero remove the item from the |List| or |Dictionary|. For a - |Blob| each byte is removed. + is zero or false remove the item from the |List| or + |Dictionary|. Similarly for each byte in a |Blob| and each + character in a |String|. {expr2} must be a |string| or |Funcref|. @@ -2200,13 +1639,13 @@ filter({expr1}, {expr2}) *filter()* of the current item. For a |Dictionary| |v:key| has the key of the current item and for a |List| |v:key| has the index of the current item. For a |Blob| |v:key| has the index of the - current byte. - - Examples: > + current byte. For a |String| |v:key| has the index of the + current character. + Examples: >vim call filter(mylist, 'v:val !~ "OLD"') -< Removes the items where "OLD" appears. > +< Removes the items where "OLD" appears. >vim call filter(mydict, 'v:key >= 8') -< Removes the items with a key below 8. > +< Removes the items with a key below 8. >vim call filter(var, 0) < Removes all the items, thus clears the |List| or |Dictionary|. @@ -2218,30 +1657,29 @@ filter({expr1}, {expr2}) *filter()* 1. the key or the index of the current item. 2. the value of the current item. The function must return |TRUE| if the item should be kept. - Example that keeps the odd items of a list: > + Example that keeps the odd items of a list: >vim func Odd(idx, val) return a:idx % 2 == 1 endfunc call filter(mylist, function('Odd')) -< It is shorter when using a |lambda|: > +< It is shorter when using a |lambda|: >vim call filter(myList, {idx, val -> idx * val <= 42}) -< If you do not use "val" you can leave it out: > +< If you do not use "val" you can leave it out: >vim call filter(myList, {idx -> idx % 2 == 1}) < - The operation is done in-place. If you want a |List| or - |Dictionary| to remain unmodified make a copy first: > - :let l = filter(copy(mylist), 'v:val =~ "KEEP"') + For a |List| and a |Dictionary| the operation is done + in-place. If you want it to remain unmodified make a copy + first: >vim + let l = filter(copy(mylist), 'v:val =~ "KEEP"') -< Returns {expr1}, the |List|, |Blob| or |Dictionary| that was - filtered. When an error is encountered while evaluating - {expr2} no further items in {expr1} are processed. When - {expr2} is a Funcref errors inside a function are ignored, +< Returns {expr1}, the |List| or |Dictionary| that was filtered, + or a new |Blob| or |String|. + When an error is encountered while evaluating {expr2} no + further items in {expr1} are processed. + When {expr2} is a Funcref errors inside a function are ignored, unless it was defined with the "abort" flag. - Can also be used as a |method|: > - mylist->filter(expr2) - -finddir({name} [, {path} [, {count}]]) *finddir()* +finddir({name} [, {path} [, {count}]]) *finddir()* Find directory {name} in {path}. Supports both downwards and upwards recursive directory searches. See |file-searching| for the syntax of {path}. @@ -2259,25 +1697,19 @@ 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()* +findfile({name} [, {path} [, {count}]]) *findfile()* Just like |finddir()|, but find a file instead of a directory. Uses 'suffixesadd'. - Example: > - :echo findfile("tags.vim", ".;") + Example: >vim + echo findfile("tags.vim", ".;") < 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} [, {maxdepth}]) *flatten()* Flatten {list} up to {maxdepth} levels. Without {maxdepth} the result is a |List| without nesting, as if {maxdepth} is a very large number. - The {list} is changed in place, make a copy first if you do + The {list} is changed in place, use |flattennew()| if you do not want that. *E900* {maxdepth} means how deep in nested lists changes are made. @@ -2286,16 +1718,16 @@ flatten({list} [, {maxdepth}]) *flatten()* If there is an error the number zero is returned. - Example: > - :echo flatten([1, [2, [3, 4]], 5]) -< [1, 2, 3, 4, 5] > - :echo flatten([1, [2, [3, 4]], 5], 1) + Example: >vim + echo flatten([1, [2, [3, 4]], 5]) +< [1, 2, 3, 4, 5] >vim + echo flatten([1, [2, [3, 4]], 5], 1) < [1, 2, [3, 4], 5] - Can also be used as a |method|: > - mylist->flatten() -< -float2nr({expr}) *float2nr()* +flattennew({list} [, {maxdepth}]) *flattennew()* + Like |flatten()| but first make a copy of {list}. + +float2nr({expr}) *float2nr()* Convert {expr} to a Number by omitting the part after the decimal point. {expr} must evaluate to a |Float| or a |Number|. @@ -2305,38 +1737,32 @@ float2nr({expr}) *float2nr()* 64-bit Number support is enabled, 0x7fffffffffffffff or -0x7fffffffffffffff). NaN results in -0x80000000 (or when 64-bit Number support is enabled, -0x8000000000000000). - Examples: > + Examples: >vim echo float2nr(3.95) -< 3 > +< 3 >vim echo float2nr(-23.45) -< -23 > +< -23 >vim echo float2nr(1.0e100) -< 2147483647 (or 9223372036854775807) > +< 2147483647 (or 9223372036854775807) >vim echo float2nr(-1.0e150) -< -2147483647 (or -9223372036854775807) > +< -2147483647 (or -9223372036854775807) >vim echo float2nr(1.0e-100) < 0 - Can also be used as a |method|: > - Compute()->float2nr() - -floor({expr}) *floor()* +floor({expr}) *floor()* Return the largest integral value less than or equal to {expr} as a |Float| (round down). {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > + Examples: >vim echo floor(1.856) -< 1.0 > +< 1.0 >vim echo floor(-5.456) -< -6.0 > +< -6.0 >vim echo floor(4.0) < 4.0 - Can also be used as a |method|: > - Compute()->floor() - -fmod({expr1}, {expr2}) *fmod()* +fmod({expr1}, {expr2}) *fmod()* Return the remainder of {expr1} / {expr2}, even if the division is not representable. Returns {expr1} - i * {expr2} for some integer i such that if {expr2} is non-zero, the @@ -2346,18 +1772,15 @@ fmod({expr1}, {expr2}) *fmod()* {expr1} and {expr2} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr1} or {expr2} is not a |Float| or a |Number|. - Examples: > - :echo fmod(12.33, 1.22) -< 0.13 > - :echo fmod(-12.33, 1.22) + Examples: >vim + echo fmod(12.33, 1.22) +< 0.13 >vim + echo fmod(-12.33, 1.22) < -0.13 - Can also be used as a |method|: > - Compute()->fmod(1.22) - -fnameescape({string}) *fnameescape()* +fnameescape({string}) *fnameescape()* Escape {string} for use as file name command argument. All - characters that have a special meaning, such as '%' and '|' + characters that have a special meaning, such as `'%'` and `'|'` are escaped with a backslash. For most systems the characters escaped are " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash @@ -2365,21 +1788,19 @@ fnameescape({string}) *fnameescape()* A leading '+' and '>' is also escaped (special after |:edit| and |:write|). And a "-" by itself (special after |:cd|). Returns an empty string on error. - Example: > - :let fname = '+some str%nge|name' - :exe "edit " .. fnameescape(fname) -< results in executing: > + Example: >vim + let fname = '+some str%nge|name' + exe "edit " .. fnameescape(fname) +< results in executing: >vim edit \+some\ str\%nge\|name < - Can also be used as a |method|: > - GetName()->fnameescape() -fnamemodify({fname}, {mods}) *fnamemodify()* +fnamemodify({fname}, {mods}) *fnamemodify()* Modify file name {fname} according to {mods}. {mods} is a string of characters like it is used for file names on the command line. See |filename-modifiers|. - Example: > - :echo fnamemodify("main.c", ":p:h") + Example: >vim + echo fnamemodify("main.c", ":p:h") < results in: > /home/user/vim/vim/src < If {mods} is empty or an unsupported modifier is used then @@ -2391,30 +1812,21 @@ 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()* +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. If the line {lnum} is not in a closed fold, -1 is returned. {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()* +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. If the line {lnum} is not in a closed fold, -1 is returned. {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()* +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 returned. If there is no fold at line {lnum}, zero is @@ -2426,11 +1838,8 @@ 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 +foldtext() *foldtext()* + Returns a String, to be displayed for a closed fold. This is the default function used for the 'foldtext' option and should only be called from evaluating 'foldtext'. It uses the |v:foldstart|, |v:foldend| and |v:folddashes| variables. @@ -2446,7 +1855,7 @@ foldtext() Returns a String, to be displayed for a closed fold. This is setting. Returns an empty string when there is no fold. -foldtextresult({lnum}) *foldtextresult()* +foldtextresult({lnum}) *foldtextresult()* Returns the text that is displayed for the closed fold at line {lnum}. Evaluates 'foldtext' in the appropriate context. When there is no closed fold at {lnum} an empty string is @@ -2455,10 +1864,8 @@ 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() -< -fullcommand({name}) *fullcommand()* + +fullcommand({name}) *fullcommand()* Get the full command name from a short abbreviated command name; see |20.2| for details on command abbreviations. @@ -2470,11 +1877,7 @@ fullcommand({name}) *fullcommand()* For example `fullcommand('s')`, `fullcommand('sub')`, `fullcommand(':%substitute')` all return "substitute". - Can also be used as a |method|: > - GetName()->fullcommand() -< - *funcref()* -funcref({name} [, {arglist}] [, {dict}]) +funcref({name} [, {arglist}] [, {dict}]) *funcref()* Just like |function()|, but the returned Funcref will lookup the function by reference, not by name. This matters when the function {name} is redefined later. @@ -2486,18 +1889,14 @@ funcref({name} [, {arglist}] [, {dict}]) instead). {name} cannot be a builtin function. Returns 0 on error. - Can also be used as a |method|: > - GetFuncname()->funcref([arg]) -< - *function()* *partial* *E700* *E922* *E923* -function({name} [, {arglist}] [, {dict}]) +function({name} [, {arglist}] [, {dict}]) *function()* *partial* *E700* *E923* Return a |Funcref| variable that refers to function {name}. {name} can be the name of a user defined function or an internal function. {name} can also be a Funcref or a partial. When it is a partial the dict stored in it will be used and the {dict} - argument is not allowed. E.g.: > + argument is not allowed. E.g.: >vim let FuncWithArg = function(dict.Func, [arg]) let Broken = function(dict.Func, [arg], dict) < @@ -2510,38 +1909,41 @@ function({name} [, {arglist}] [, {dict}]) the Funcref and will be used when the Funcref is called. The arguments are passed to the function in front of other - arguments, but after any argument from |method|. Example: > + arguments, but after any argument from |method|. Example: >vim func Callback(arg1, arg2, name) "... + endfunc let Partial = function('Callback', ['one', 'two']) "... call Partial('name') -< Invokes the function as with: > +< Invokes the function as with: >vim call Callback('one', 'two', 'name') -< With a |method|: > +< With a |method|: >vim func Callback(one, two, three) "... + endfunc let Partial = function('Callback', ['two']) "... eval 'one'->Partial('three') -< Invokes the function as with: > +< Invokes the function as with: >vim call Callback('one', 'two', 'three') < The function() call can be nested to add more arguments to the Funcref. The extra arguments are appended to the list of - arguments. Example: > + arguments. Example: >vim func Callback(arg1, arg2, name) "... + endfunc let Func = function('Callback', ['one']) let Func2 = function(Func, ['two']) "... call Func2('name') -< Invokes the function as with: > +< Invokes the function as with: >vim call Callback('one', 'two', 'name') < The Dictionary is only useful when calling a "dict" function. - In that case the {dict} is passed in as "self". Example: > + In that case the {dict} is passed in as "self". Example: >vim function Callback() dict echo "called for " .. self.name endfunction @@ -2552,26 +1954,24 @@ function({name} [, {arglist}] [, {dict}]) call Func() " will echo: called for example < The use of function() is not needed when there are no extra arguments, these two are equivalent, if Callback() is defined - as context.Callback(): > + as context.Callback(): >vim let Func = function('Callback', context) let Func = context.Callback -< The argument list and the Dictionary can be combined: > +< The argument list and the Dictionary can be combined: >vim function Callback(arg1, count) dict "... + endfunction let context = {"name": "example"} let Func = function('Callback', ['one'], context) "... call Func(500) -< Invokes the function as with: > +< Invokes the function as with: >vim call context.Callback('one', 500) < Returns 0 on error. - Can also be used as a |method|: > - GetFuncname()->function([arg]) - -garbagecollect([{atexit}]) *garbagecollect()* +garbagecollect([{atexit}]) *garbagecollect()* Cleanup unused |Lists| and |Dictionaries| that have circular references. @@ -2591,23 +1991,24 @@ garbagecollect([{atexit}]) *garbagecollect()* it's safe to perform. This is when waiting for the user to type a character. -get({list}, {idx} [, {default}]) *get()* +get({list}, {idx} [, {default}]) *get()* Get item {idx} from |List| {list}. When this item is not available return {default}. Return zero when {default} is omitted. - Can also be used as a |method|: > - mylist->get(idx) + get({blob}, {idx} [, {default}]) Get byte {idx} from |Blob| {blob}. When this byte is not available return {default}. Return -1 when {default} is omitted. + get({dict}, {key} [, {default}]) Get item with key {key} from |Dictionary| {dict}. When this item is not available return {default}. Return zero when - {default} is omitted. Useful example: > + {default} is omitted. Useful example: >vim let val = get(g:, 'var_name', 'default') < This gets the value of g:var_name if it exists, and uses "default" when it does not exist. + get({func}, {what}) Get item {what} from Funcref {func}. Possible values for {what} are: @@ -2617,9 +2018,8 @@ get({func}, {what}) "args" The list with arguments Returns zero on error. - *getbufinfo()* getbufinfo([{buf}]) -getbufinfo([{dict}]) +getbufinfo([{dict}]) *getbufinfo()* Get information about buffers as a List of Dictionaries. Without an argument information about all the buffers is @@ -2653,8 +2053,8 @@ getbufinfo([{dict}]) displayed in the window in the past. If you want the line number of the last known cursor position in a given - window, use |line()|: > - :echo line('.', {winid}) + window, use |line()|: >vim + echo line('.', {winid}) < linecount Number of lines in the buffer (only valid when loaded) @@ -2671,25 +2071,21 @@ getbufinfo([{dict}]) windows List of |window-ID|s that display this buffer - Examples: > + Examples: >vim for buf in getbufinfo() echo buf.name endfor for buf in getbufinfo({'buflisted':1}) if buf.changed - .... + " .... endif endfor < - To get buffer-local options use: > + To get buffer-local options use: >vim getbufvar({bufnr}, '&option_name') < - Can also be used as a |method|: > - GetBufnr()->getbufinfo() -< - *getbufline()* -getbufline({buf}, {lnum} [, {end}]) +getbufline({buf}, {lnum} [, {end}]) *getbufline()* Return a |List| with the lines starting from {lnum} to {end} (inclusive) in the buffer {buf}. If {end} is omitted, a |List| with only the line {lnum} is returned. See @@ -2711,18 +2107,14 @@ getbufline({buf}, {lnum} [, {end}]) This function works only for loaded buffers. For unloaded and non-existing buffers, an empty |List| is returned. - Example: > - :let lines = getbufline(bufnr("myfile"), 1, "$") + Example: >vim + let lines = getbufline(bufnr("myfile"), 1, "$") -< Can also be used as a |method|: > - GetBufnr()->getbufline(lnum) -< - *getbufoneline()* -getbufoneline({buf}, {lnum}) +getbufoneline({buf}, {lnum}) *getbufoneline()* Just like `getbufline()` but only get one line and return it as a string. -getbufvar({buf}, {varname} [, {def}]) *getbufvar()* +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:" must be used. @@ -2739,21 +2131,17 @@ getbufvar({buf}, {varname} [, {def}]) *getbufvar()* For the use of {buf}, see |bufname()| above. When the buffer or variable doesn't exist {def} or an empty string is returned, there is no error message. - Examples: > - :let bufmodified = getbufvar(1, "&mod") - :echo "todo myvar = " .. getbufvar("todo", "myvar") + Examples: >vim + let bufmodified = getbufvar(1, "&mod") + echo "todo myvar = " .. getbufvar("todo", "myvar") -< Can also be used as a |method|: > - GetBufnr()->getbufvar(varname) -< -getcellwidths() *getcellwidths()* +getcellwidths() *getcellwidths()* Returns a |List| of cell widths of character ranges overridden by |setcellwidths()|. The format is equal to the argument of |setcellwidths()|. If no character ranges have their cell widths overridden, an empty List is returned. - -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. @@ -2769,10 +2157,7 @@ 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()* +getchar([expr]) *getchar()* Get a single character from the user or input stream. If [expr] is omitted, wait until a character is available. If [expr] is 0, only get a character when one is available. @@ -2806,7 +2191,7 @@ getchar([expr]) *getchar()* |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. |getmousepos()| can also be used. Mouse move events will be ignored. - This example positions the mouse as it would normally happen: > + This example positions the mouse as it would normally happen: >vim let c = getchar() if c == "\<LeftMouse>" && v:mouse_win > 0 exe v:mouse_win .. "wincmd w" @@ -2821,22 +2206,23 @@ getchar([expr]) *getchar()* There is no mapping for the character. Key codes are replaced, thus when the user presses the <Del> key you get the code for the <Del> key, not the raw character - sequence. Examples: > + sequence. Examples: >vim getchar() == "\<Del>" getchar() == "\<S-Left>" -< This example redefines "f" to ignore case: > - :nmap f :call FindChar()<CR> - :function FindChar() - : let c = nr2char(getchar()) - : while col('.') < col('$') - 1 - : normal l - : if getline('.')[col('.') - 1] ==? c - : break - : endif - : endwhile - :endfunction -< -getcharmod() *getcharmod()* +< This example redefines "f" to ignore case: >vim + nmap f :call FindChar()<CR> + function FindChar() + let c = nr2char(getchar()) + while col('.') < col('$') - 1 + normal l + if getline('.')[col('.') - 1] ==? c + break + endif + endwhile + endfunction +< + +getcharmod() *getcharmod()* The result is a Number which is the state of the modifiers for the last obtained character with getchar() or in another way. These values are added together: @@ -2852,21 +2238,21 @@ getcharmod() *getcharmod()* character itself are obtained. Thus Shift-a results in "A" without a modifier. Returns 0 if no modifiers are used. - *getcharpos()* -getcharpos({expr}) +getcharpos({expr}) *getcharpos()* Get the position for String {expr}. Same as |getpos()| but the column number in the returned List is a character index instead of a byte index. + If |getpos()| returns a very large column number, equal to + |v:maxcol|, then getcharpos() will return the character index + of the last character. Example: - With the cursor on '세' in line 5 with text "여보세요": > + With the cursor on '세' in line 5 with text "여보세요": >vim getcharpos('.') returns [0, 5, 3, 0] getpos('.') returns [0, 5, 7, 0] < - Can also be used as a |method|: > - GetMark()->getcharpos() -getcharsearch() *getcharsearch()* +getcharsearch() *getcharsearch()* Return the current character search information as a {dict} with the following entries: @@ -2881,13 +2267,12 @@ getcharsearch() *getcharsearch()* This can be useful to always have |;| and |,| search forward/backward regardless of the direction of the previous - character search: > - :nnoremap <expr> ; getcharsearch().forward ? ';' : ',' - :nnoremap <expr> , getcharsearch().forward ? ',' : ';' + character search: >vim + nnoremap <expr> ; getcharsearch().forward ? ';' : ',' + nnoremap <expr> , getcharsearch().forward ? ',' : ';' < Also see |setcharsearch()|. - -getcharstr([expr]) *getcharstr()* +getcharstr([expr]) *getcharstr()* Get a single character from the user or input stream as a string. If [expr] is omitted, wait until a character is available. @@ -2899,7 +2284,7 @@ getcharstr([expr]) *getcharstr()* Otherwise this works like |getchar()|, except that a number result is converted to a string. -getcmdcompltype() *getcmdcompltype()* +getcmdcompltype() *getcmdcompltype()* Return the type of the current command-line completion. Only works when the command line is being edited, thus requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. @@ -2908,18 +2293,18 @@ getcmdcompltype() *getcmdcompltype()* |setcmdline()|. Returns an empty string when completion is not defined. -getcmdline() *getcmdline()* +getcmdline() *getcmdline()* Return the current command-line. Only works when the command line is being edited, thus requires use of |c_CTRL-\_e| or |c_CTRL-R_=|. - Example: > - :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR> + Example: >vim + cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR> < Also see |getcmdtype()|, |getcmdpos()|, |setcmdpos()| and |setcmdline()|. Returns an empty string when entering a password or using |inputsecret()|. -getcmdpos() *getcmdpos()* +getcmdpos() *getcmdpos()* Return the position of the cursor in the command line as a byte count. The first column is 1. Only works when editing the command line, thus requires use of @@ -2928,7 +2313,7 @@ getcmdpos() *getcmdpos()* Also see |getcmdtype()|, |setcmdpos()|, |getcmdline()| and |setcmdline()|. -getcmdscreenpos() *getcmdscreenpos()* +getcmdscreenpos() *getcmdscreenpos()* Return the screen position of the cursor in the command line as a byte count. The first column is 1. Instead of |getcmdpos()|, it adds the prompt position. @@ -2938,7 +2323,7 @@ getcmdscreenpos() *getcmdscreenpos()* Also see |getcmdpos()|, |setcmdpos()|, |getcmdline()| and |setcmdline()|. -getcmdtype() *getcmdtype()* +getcmdtype() *getcmdtype()* Return the current command-line type. Possible return values are: : normal Ex command @@ -2946,19 +2331,19 @@ getcmdtype() *getcmdtype()* / forward search command ? backward search command @ |input()| command - - |:insert| or |:append| command + `-` |:insert| or |:append| command = |i_CTRL-R_=| Only works when editing the command line, thus requires use of |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. Returns an empty string otherwise. Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|. -getcmdwintype() *getcmdwintype()* +getcmdwintype() *getcmdwintype()* Return the current |command-line-window| type. Possible return values are the same as |getcmdtype()|. Returns an empty string when not in the command-line window. -getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* +getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* Return a list of command-line completion matches. The String {type} argument specifies what for. The following completion types are supported: @@ -2966,13 +2351,14 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* arglist file names in argument list augroup autocmd groups buffer buffer names - behave |:behave| suboptions breakpoint |:breakadd| and |:breakdel| suboptions cmdline |cmdline-completion| result color color schemes command Ex command compiler compilers - diff_buffer |:diffget| and |:diffput| completion + custom,{func} custom completion, defined via {func} + customlist,{func} custom completion, defined via {func} + diff_buffer |:diffget| and |:diffput| completion dir directory names environment environment variable names event autocommand events @@ -2991,6 +2377,7 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* messages |:messages| suboptions option options packadd optional package |pack-add| names + runtime |:runtime| completion scriptnames sourced script names |:scriptnames| shellcmd Shell command sign |:sign| suboptions @@ -3018,22 +2405,19 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* If {type} is "cmdline", then the |cmdline-completion| result is returned. For example, to complete the possible values after - a ":call" command: > + a ":call" command: >vim echo getcompletion('call ', 'cmdline') < 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([{winid}]) +getcurpos([{winid}]) *getcurpos()* Get the position of the cursor. This is like getpos('.'), but - includes an extra "curswant" in the list: + includes an extra "curswant" item in the list: [0, lnum, col, off, curswant] ~ The "curswant" number is the preferred column when moving the - cursor vertically. Also see |getcursorcharpos()| and + cursor vertically. After |$| command it will be a very large + number equal to |v:maxcol|. Also see |getcursorcharpos()| and |getpos()|. The first "bufnum" item is always zero. The byte position of the cursor is returned in "col". To get the character @@ -3045,37 +2429,31 @@ getcurpos([{winid}]) current value of the buffer if it is not the current window. If {winid} is invalid a list with zeroes is returned. - This can be used to save and restore the cursor position: > + This can be used to save and restore the cursor position: >vim let save_cursor = getcurpos() MoveTheCursorAround call setpos('.', save_cursor) < Note that this only works within the window. See |winrestview()| for restoring more state. - Can also be used as a |method|: > - GetWinid()->getcurpos() -< - *getcursorcharpos()* -getcursorcharpos([{winid}]) +getcursorcharpos([{winid}]) *getcursorcharpos()* Same as |getcurpos()| but the column number in the returned List is a character index instead of a byte index. Example: - With the cursor on '보' in line 3 with text "여보세요": > - getcursorcharpos() returns [0, 3, 2, 0, 3] - getcurpos() returns [0, 3, 4, 0, 3] + With the cursor on '보' in line 3 with text "여보세요": >vim + getcursorcharpos() " returns [0, 3, 2, 0, 3] + getcurpos() " returns [0, 3, 4, 0, 3] < - Can also be used as a |method|: > - GetWinid()->getcursorcharpos() -getcwd([{winnr} [, {tabnr}]]) *getcwd()* +getcwd([{winnr} [, {tabnr}]]) *getcwd()* With no arguments, returns the name of the effective |current-directory|. With {winnr} or {tabnr} the working directory of that scope is returned, and 'autochdir' is ignored. Tabs and windows are identified by their respective numbers, 0 means current tab or window. Missing tab number implies 0. - Thus the following are equivalent: > + Thus the following are equivalent: >vim getcwd(0) getcwd(0, 0) < If {winnr} is -1 it is ignored, only the tab is resolved. @@ -3084,22 +2462,16 @@ getcwd([{winnr} [, {tabnr}]]) *getcwd()* 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()* +getenv({name}) *getenv()* Return the value of environment variable {name}. The {name} - argument is a string, without a leading '$'. Example: > + argument is a string, without a leading '$'. Example: >vim myHome = getenv('HOME') < When the variable does not exist |v:null| is returned. That 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()* +getfontname([{name}]) *getfontname()* Without an argument returns the name of the normal font being used. Like what is used for the Normal highlight group |hl-Normal|. @@ -3111,7 +2483,7 @@ getfontname([{name}]) *getfontname()* gvimrc file. Use the |GUIEnter| autocommand to use this function just after the GUI has started. -getfperm({fname}) *getfperm()* +getfperm({fname}) *getfperm()* The result is a String, which is the read, write, and execute permissions of the given file {fname}. If {fname} does not exist or its directory cannot be read, an @@ -3120,18 +2492,15 @@ getfperm({fname}) *getfperm()* "rwx" flags represent, in turn, the permissions of the owner of the file, the group the file belongs to, and other users. If a user does not have a given permission the flag for this - is replaced with the string "-". Examples: > - :echo getfperm("/etc/passwd") - :echo getfperm(expand("~/.config/nvim/init.vim")) + is replaced with the string "-". Examples: >vim + echo getfperm("/etc/passwd") + echo getfperm(expand("~/.config/nvim/init.vim")) < 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()* +getfsize({fname}) *getfsize()* The result is a Number, which is the size in bytes of the given file {fname}. If {fname} is a directory, 0 is returned. @@ -3139,20 +2508,14 @@ 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()* +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 since 1st Jan 1970, and may be passed to strftime(). See also |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()* +getftype({fname}) *getftype()* The result is a String, which is a description of the kind of file of the given file {fname}. If {fname} does not exist an empty string is returned. @@ -3166,16 +2529,13 @@ getftype({fname}) *getftype()* Socket "socket" FIFO "fifo" All other "other" - Example: > + Example: >vim getftype("/home") < Note that a type such as "link" will only be returned on 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()* +getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* Returns the |jumplist| for the specified window. Without arguments use the current window. @@ -3195,17 +2555,13 @@ getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* filename filename if available lnum line number - Can also be used as a |method|: > - GetWinnr()->getjumplist() - -< *getline()* -getline({lnum} [, {end}]) +getline({lnum} [, {end}]) *getline()* Without {end} the result is a String, which is line {lnum} - from the current buffer. Example: > + from the current buffer. Example: >vim getline(1) < When {lnum} is a String that doesn't start with a digit, |line()| is called to translate the String into a Number. - To get the line under the cursor: > + To get the line under the cursor: >vim getline(".") < When {lnum} is a number smaller than 1 or bigger than the number of lines in the buffer, an empty string is returned. @@ -3216,18 +2572,15 @@ getline({lnum} [, {end}]) {end} is used in the same way as {lnum}. Non-existing lines are silently omitted. When {end} is before {lnum} an empty |List| is returned. - Example: > - :let start = line('.') - :let end = search("^$") - 1 - :let lines = getline(start, end) - -< Can also be used as a |method|: > - ComputeLnum()->getline() + Example: >vim + let start = line('.') + let end = search("^$") - 1 + let lines = getline(start, end) < To get lines from another buffer see |getbufline()| and |getbufoneline()| -getloclist({nr} [, {what}]) *getloclist()* +getloclist({nr} [, {what}]) *getloclist()* Returns a |List| with all the entries in the location list for window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is zero the current window is used. @@ -3254,12 +2607,12 @@ getloclist({nr} [, {what}]) *getloclist()* location list for the window {nr}. Returns an empty Dictionary if window {nr} does not exist. - Examples (See also |getqflist-examples|): > - :echo getloclist(3, {'all': 0}) - :echo getloclist(5, {'filewinid': 0}) - + Examples (See also |getqflist-examples|): >vim + echo getloclist(3, {'all': 0}) + echo getloclist(5, {'filewinid': 0}) +< -getmarklist([{buf}]) *getmarklist()* +getmarklist([{buf}]) *getmarklist()* Without the {buf} argument returns a |List| with information about all the global marks. |mark| @@ -3278,10 +2631,7 @@ getmarklist([{buf}]) *getmarklist()* Refer to |getpos()| for getting information about a specific mark. - Can also be used as a |method|: > - GetBufnr()->getmarklist() - -getmatches([{win}]) *getmatches()* +getmatches([{win}]) *getmatches()* Returns a |List| with all matches previously defined for the current window by |matchadd()| and the |:match| commands. |getmatches()| is useful in combination with |setmatches()|, @@ -3290,24 +2640,31 @@ getmatches([{win}]) *getmatches()* If {win} is specified, use the window with this number or window ID instead of the current window. If {win} is invalid, an empty list is returned. - Example: > - :echo getmatches() -< [{"group": "MyGroup1", "pattern": "TODO", + Example: >vim + echo getmatches() +< > + [{"group": "MyGroup1", "pattern": "TODO", "priority": 10, "id": 1}, {"group": "MyGroup2", - "pattern": "FIXME", "priority": 10, "id": 2}] > - :let m = getmatches() - :call clearmatches() - :echo getmatches() -< [] > - :call setmatches(m) - :echo getmatches() -< [{"group": "MyGroup1", "pattern": "TODO", + "pattern": "FIXME", "priority": 10, "id": 2}] +< >vim + let m = getmatches() + call clearmatches() + echo getmatches() +< > + [] +< >vim + call setmatches(m) + echo getmatches() +< > + [{"group": "MyGroup1", "pattern": "TODO", "priority": 10, "id": 1}, {"group": "MyGroup2", - "pattern": "FIXME", "priority": 10, "id": 2}] > - :unlet m + "pattern": "FIXME", "priority": 10, "id": 2}] +< >vim + unlet m < -getmousepos() *getmousepos()* - Returns a Dictionary with the last known position of the + +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 @@ -3317,6 +2674,8 @@ getmousepos() *getmousepos()* wincol column inside "winid" line text line inside "winid" column text column inside "winid" + coladd offset (in screen columns) from the + start of the clicked char All numbers are 1-based. If not over a window, e.g. when in the command line, then only @@ -3335,12 +2694,12 @@ getmousepos() *getmousepos()* 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. +getpid() *getpid()* + Return a Number which is the process ID of the Vim process. This is a unique number, until Vim exits. - *getpos()* -getpos({expr}) Get the position for String {expr}. For possible values of +getpos({expr}) *getpos()* + Get the position for String {expr}. For possible values of {expr} see |line()|. For getting the cursor position see |getcurpos()|. The result is a |List| with four numbers: @@ -3355,23 +2714,20 @@ getpos({expr}) Get the position for String {expr}. For possible values of character. Note that for '< and '> Visual mode matters: when it is "V" (visual line mode) the column of '< is zero and the column of - '> is a large number. + '> is a large number equal to |v:maxcol|. The column number in the returned List is the byte position within the line. To get the character position in the line, use |getcharpos()|. - The column number can be very large, e.g. 2147483647, in which - case it means "after the end of the line". + A very large column number equal to |v:maxcol| can be returned, + in which case it means "after the end of the line". If {expr} is invalid, returns a list with all zeros. - This can be used to save and restore the position of a mark: > + This can be used to save and restore the position of a mark: >vim let save_a_mark = getpos("'a") - ... + " ... call setpos("'a", save_a_mark) < Also see |getcharpos()|, |getcurpos()| and |setpos()|. - Can also be used as a |method|: > - GetMark()->getpos() - -getqflist([{what}]) *getqflist()* +getqflist([{what}]) *getqflist()* Returns a |List| with all the current quickfix errors. Each list item is a dictionary with these entries: bufnr number of buffer that has the file name, use @@ -3389,6 +2745,9 @@ getqflist([{what}]) *getqflist()* text description of the error type type of the error, 'E', '1', etc. valid |TRUE|: recognized error message + user_data + custom data associated with the item, can be + any type. When there is no error list or it's empty, an empty list is returned. Quickfix list entries with a non-existing buffer @@ -3397,11 +2756,11 @@ getqflist([{what}]) *getqflist()* you may need to explicitly check for zero). Useful application: Find pattern matches in multiple files and - do something with them: > - :vimgrep /theword/jg *.c - :for d in getqflist() - : echo bufname(d.bufnr) ':' d.lnum '=' d.text - :endfor + do something with them: >vim + vimgrep /theword/jg *.c + for d in getqflist() + echo bufname(d.bufnr) ':' d.lnum '=' d.text + endfor < If the optional {what} dictionary argument is supplied, then returns only the items listed in {what} as a dictionary. The @@ -3466,15 +2825,16 @@ getqflist([{what}]) *getqflist()* to "". winid quickfix |window-ID|. If not present, set to 0 - Examples (See also |getqflist-examples|): > - :echo getqflist({'all': 1}) - :echo getqflist({'nr': 2, 'title': 1}) - :echo getqflist({'lines' : ["F1:10:L10"]}) + Examples (See also |getqflist-examples|): >vim + echo getqflist({'all': 1}) + echo getqflist({'nr': 2, 'title': 1}) + echo getqflist({'lines' : ["F1:10:L10"]}) < -getreg([{regname} [, 1 [, {list}]]]) *getreg()* + +getreg([{regname} [, 1 [, {list}]]]) *getreg()* The result is a String, which is the contents of register - {regname}. Example: > - :let cliptext = getreg('*') + {regname}. Example: >vim + let cliptext = getreg('*') < When register {regname} was not set the result is an empty string. The {regname} argument must be a string. @@ -3494,10 +2854,7 @@ 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()* +getreginfo([{regname}]) *getreginfo()* Returns detailed information about register {regname} as a Dictionary with the following entries: regcontents List of lines contained in register @@ -3521,10 +2878,7 @@ getreginfo([{regname}]) *getreginfo()* 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()* +getregtype([{regname}]) *getregtype()* The result is a String, which is type of register {regname}. The value will be one of: "v" for |charwise| text @@ -3535,10 +2889,44 @@ 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()* +getscriptinfo([{opts}]) *getscriptinfo()* + Returns a |List| with information about all the sourced Vim + scripts in the order they were sourced, like what + `:scriptnames` shows. + + The optional Dict argument {opts} supports the following + optional items: + name Script name match pattern. If specified, + and "sid" is not specified, information about + scripts with a name that match the pattern + "name" are returned. + sid Script ID |<SID>|. If specified, only + information about the script with ID "sid" is + returned and "name" is ignored. + + Each item in the returned List is a |Dict| with the following + items: + autoload Always set to FALSE. + functions List of script-local function names defined in + the script. Present only when a particular + script is specified using the "sid" item in + {opts}. + name Vim script file name. + sid Script ID |<SID>|. + variables A dictionary with the script-local variables. + Present only when a particular script is + specified using the "sid" item in {opts}. + Note that this is a copy, the value of + script-local variables cannot be changed using + this dictionary. + version Vim script version, always 1 + + Examples: >vim + echo getscriptinfo({'name': 'myscript'}) + echo getscriptinfo({'sid': 15}).variables +< + +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 |Dictionary|. Otherwise, {tabnr} specifies the tab page @@ -3551,10 +2939,7 @@ 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()* +gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* Get the value of a tab-local variable {varname} in tab page {tabnr}. |t:var| Tabs are numbered starting with one. @@ -3564,10 +2949,7 @@ 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()* +gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* Get the value of window-local variable {varname} in window {winnr} in tab page {tabnr}. The {varname} argument is a string. When {varname} is empty a @@ -3586,17 +2968,15 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* or buffer-local variable. When the tab, window or variable doesn't exist {def} or an empty string is returned, there is no error message. - Examples: > - :let list_is_on = gettabwinvar(1, 2, '&list') - :echo "myvar = " .. gettabwinvar(3, 1, 'myvar') + Examples: >vim + let list_is_on = gettabwinvar(1, 2, '&list') + echo "myvar = " .. gettabwinvar(3, 1, 'myvar') < - To obtain all window-local variables use: > + To obtain all window-local variables use: >vim gettabwinvar({tabnr}, {winnr}, '&') +< -< Can also be used as a |method|: > - GetTabnr()->gettabwinvar(winnr, varname) - -gettagstack([{winnr}]) *gettagstack()* +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|. When {winnr} is not specified, the current window is used. @@ -3624,11 +3004,7 @@ gettagstack([{winnr}]) *gettagstack()* See |tagstack| for more information about the tag stack. - Can also be used as a |method|: > - GetWinnr()->gettagstack() - - -gettext({text}) *gettext()* +gettext({text}) *gettext()* Translate String {text} if possible. This is mainly for use in the distributed Vim scripts. When generating message translations the {text} is extracted by @@ -3639,8 +3015,7 @@ gettext({text}) *gettext()* xgettext does not understand escaping in single quoted strings. - -getwininfo([{winid}]) *getwininfo()* +getwininfo([{winid}]) *getwininfo()* Returns information about windows as a |List| with Dictionaries. If {winid} is given Information about the window with that ID @@ -3674,10 +3049,7 @@ 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()* +getwinpos([{timeout}]) *getwinpos()* The result is a |List| with two numbers, the result of |getwinposx()| and |getwinposy()| combined: [x-pos, y-pos] @@ -3688,7 +3060,7 @@ getwinpos([{timeout}]) *getwinpos()* When using a value less than 10 and no response is received within that time, a previously reported position is returned, if available. This can be used to poll for the position and - do some work in the meantime: > + do some work in the meantime: >vim while 1 let res = getwinpos(1) if res[0] >= 0 @@ -3697,31 +3069,26 @@ 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 + +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 -1 if the information is not available. The value can be used with `:winpos`. - *getwinposy()* -getwinposy() The result is a Number, which is the Y coordinate in pixels of +getwinposy() *getwinposy()* + The result is a Number, which is the Y coordinate in pixels of the top of the GUI Vim window. The result will be -1 if the information is not available. The value can be used with `:winpos`. -getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* +getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* Like |gettabwinvar()| for the current tabpage. - Examples: > - :let list_is_on = getwinvar(2, '&list') - :echo "myvar = " .. getwinvar(1, 'myvar') + Examples: >vim + 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()* +glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* Expand the file wildcards in {expr}. See |wildcards| for the use of special characters. @@ -3748,37 +3115,35 @@ glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* |TRUE| then all symbolic links are included. For most systems backticks can be used to get files names from - any external command. Example: > - :let tagfiles = glob("`find . -name tags -print`") - :let &tags = substitute(tagfiles, "\n", ",", "g") + any external command. Example: >vim + let tagfiles = glob("`find . -name tags -print`") + let &tags = substitute(tagfiles, "\n", ",", "g") < The result of the program inside the backticks should be one item per line. Spaces inside an item are allowed. 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()* +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 - is a file name. E.g. > + is a file name. E.g. >vim if filename =~ glob2regpat('Make*.mak') -< This is equivalent to: > + " ... + endif +< This is equivalent to: >vim if filename =~ '^Make.*\.mak$' + " ... + endif < When {string} is an empty string the result is "^$", match an empty string. Note that the result depends on the system. On MS-Windows a backslash usually means a path separator. - Can also be used as a |method|: > - GetExpr()->glob2regpat() -< *globpath()* -globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]]) +globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]]) *globpath()* Perform glob() for String {expr} on all directories in {path} - and concatenate the results. Example: > - :echo globpath(&rtp, "syntax/c.vim") + and concatenate the results. Example: >vim + echo globpath(&rtp, "syntax/c.vim") < {path} is a comma-separated list of directory names. Each directory name is prepended to {expr} and expanded like with @@ -3798,35 +3163,31 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {allinks}]]]) with all matching files. The advantage of using a List is, you also get filenames containing newlines correctly. Otherwise the result is a String and when there are several matches, - they are separated by <NL> characters. Example: > - :echo globpath(&rtp, "syntax/c.vim", 0, 1) + they are separated by <NL> characters. Example: >vim + echo globpath(&rtp, "syntax/c.vim", 0, 1) < {allinks} is used as with |glob()|. The "**" item can be used to search in a directory tree. For example, to find all "README.txt" files in the directories - in 'runtimepath' and below: > - :echo globpath(&rtp, "**/README.txt") + in 'runtimepath' and below: >vim + echo globpath(&rtp, "**/README.txt") < 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 +has({feature}) *has()* + Returns 1 if {feature} is supported, 0 otherwise. The {feature} argument is a feature name like "nvim-0.2.1" or "win32", see below. See also |exists()|. - To get the system name use |vim.loop|.os_uname() in Lua: > - :lua print(vim.loop.os_uname().sysname) + To get the system name use |vim.uv|.os_uname() in Lua: >lua + print(vim.uv.os_uname().sysname) < If the code has a syntax error then Vimscript may skip the rest of the line. Put |:if| and |:endif| on separate lines to - avoid the syntax error: > + avoid the syntax error: >vim if has('feature') - let x = this->breaks->without->the->feature + let x = this_breaks_without_the_feature() endif < Vim's compile-time feature-names (prefixed with "+") are not @@ -3835,12 +3196,16 @@ has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The Feature names can be: 1. Nvim version. For example the "nvim-0.2.1" feature means - that Nvim is version 0.2.1 or later: > - :if has("nvim-0.2.1") + that Nvim is version 0.2.1 or later: >vim + if has("nvim-0.2.1") + " ... + endif < 2. Runtime condition or other pseudo-feature. For example the - "win32" feature checks if the current system is Windows: > - :if has("win32") + "win32" feature checks if the current system is Windows: >vim + if has("win32") + " ... + endif < *feature-list* List of supported pseudo-feature names: acl |ACL| support. @@ -3848,6 +3213,7 @@ has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The clipboard |clipboard| provider is available. fname_case Case in file names matters (for Darwin and MS-Windows this is not present). + gui_running Nvim has a GUI. iconv Can use |iconv()| for conversion. linux Linux system. mac MacOS system. @@ -3865,43 +3231,41 @@ has({feature}) Returns 1 if {feature} is supported, 0 otherwise. The *has-patch* 3. Vim patch. For example the "patch123" feature means that - Vim patch 123 at the current |v:version| was included: > - :if v:version > 602 || v:version == 602 && has("patch148") + Vim patch 123 at the current |v:version| was included: >vim + if v:version > 602 || v:version == 602 && has("patch148") + " ... + endif < 4. Vim version. For example the "patch-7.4.237" feature means - that Nvim is Vim-compatible to version 7.4.237 or later. > - :if has("patch-7.4.237") - + that Nvim is Vim-compatible to version 7.4.237 or later. >vim + if has("patch-7.4.237") + " ... + endif +< -has_key({dict}, {key}) *has_key()* +has_key({dict}, {key}) *has_key()* The result is a Number, which is TRUE if |Dictionary| {dict} has an entry with key {key}. FALSE otherwise. The {key} argument is a string. - Can also be used as a |method|: > - mydict->has_key(key) - -haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* +haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* 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. - Thus the following are equivalent: > - haslocaldir() - haslocaldir(0) - haslocaldir(0, 0) + Thus the following are equivalent: >vim + echo haslocaldir() + echo haslocaldir(0) + echo haslocaldir(0, 0) < With {winnr} use that window in the current tabpage. 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()* +hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* The result is a Number, which is TRUE if there is a mapping that contains {what} in somewhere in the rhs (what it is mapped to) and this mapping exists in one of the modes @@ -3925,17 +3289,14 @@ hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* When {mode} is omitted, "nvo" is used. This function is useful to check if a mapping already exists - to a function in a Vim script. Example: > - :if !hasmapto('\ABCdoit') - : map <Leader>d \ABCdoit - :endif + to a function in a Vim script. Example: >vim + if !hasmapto('\ABCdoit') + map <Leader>d \ABCdoit + endif < 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()* +histadd({history}, {item}) *histadd()* Add the String {item} to the history {history} which can be one of: *hist-names* "cmd" or ":" command line history @@ -3951,16 +3312,12 @@ histadd({history}, {item}) *histadd()* The result is a Number: TRUE if the operation was successful, otherwise FALSE is returned. - Example: > - :call histadd("input", strftime("%Y %b %d")) - :let date=input("Enter date: ") + Example: >vim + call histadd("input", strftime("%Y %b %d")) + let date=input("Enter date: ") < This function is not available in the |sandbox|. - Can also be used as a |method|, the base is passed as the - second argument: > - GetHistory()->histadd('search') - -histdel({history} [, {item}]) *histdel()* +histdel({history} [, {item}]) *histdel()* Clear {history}, i.e. delete all its entries. See |hist-names| for the possible values of {history}. @@ -3976,26 +3333,24 @@ histdel({history} [, {item}]) *histdel()* is returned. Examples: - Clear expression register history: > - :call histdel("expr") + Clear expression register history: >vim + call histdel("expr") < - Remove all entries starting with "*" from the search history: > - :call histdel("/", '^\*') + Remove all entries starting with "*" from the search history: >vim + call histdel("/", '^\*') < - The following three are equivalent: > - :call histdel("search", histnr("search")) - :call histdel("search", -1) - :call histdel("search", '^' .. histget("search", -1) .. '$') + The following three are equivalent: >vim + call histdel("search", histnr("search")) + call histdel("search", -1) + call histdel("search", '^' .. histget("search", -1) .. '$') < To delete the last search pattern and use the last-but-one for - the "n" command and 'hlsearch': > - :call histdel("search", -1) - :let @/ = histget("search", -1) + the "n" command and 'hlsearch': >vim + call histdel("search", -1) + let @/ = histget("search", -1) < - Can also be used as a |method|: > - GetHistory()->histdel() -histget({history} [, {index}]) *histget()* +histget({history} [, {index}]) *histget()* The result is a String, the entry with Number {index} from {history}. See |hist-names| for the possible values of {history}, and |:history-indexing| for {index}. If there is @@ -4003,55 +3358,45 @@ histget({history} [, {index}]) *histget()* omitted, the most recent item from the history is used. Examples: - Redo the second last search from history. > - :execute '/' .. histget("search", -2) + Redo the second last search from history. >vim + execute '/' .. histget("search", -2) < Define an Ex command ":H {num}" that supports re-execution of - the {num}th entry from the output of |:history|. > - :command -nargs=1 H execute histget("cmd", 0+<args>) + the {num}th entry from the output of |:history|. >vim + command -nargs=1 H execute histget("cmd", 0+<args>) < - Can also be used as a |method|: > - GetHistory()->histget() -histnr({history}) *histnr()* +histnr({history}) *histnr()* The result is the Number of the current entry in {history}. See |hist-names| for the possible values of {history}. If an error occurred, -1 is returned. - Example: > - :let inp_index = histnr("expr") + Example: >vim + let inp_index = histnr("expr") -< Can also be used as a |method|: > - GetHistory()->histnr() +hlID({name}) *hlID()* + The result is a Number, which is the ID of the highlight group + with name {name}. When the highlight group doesn't exist, + zero is returned. + This can be used to retrieve information about the highlight + group. For example, to get the background color of the + "Comment" group: >vim + echo synIDattr(synIDtrans(hlID("Comment")), "bg") < -hlexists({name}) *hlexists()* + +hlexists({name}) *hlexists()* The result is a Number, which is TRUE if a highlight group called {name} exists. This is when the group has been defined in some way. Not necessarily when highlighting has 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, - zero is returned. - This can be used to retrieve information about the highlight - 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()* +hostname() *hostname()* The result is a String, which is the name of the machine on which Vim is currently running. Machine names greater than 256 characters long are truncated. -iconv({string}, {from}, {to}) *iconv()* +iconv({string}, {from}, {to}) *iconv()* The result is a String, which is the text {string} converted from encoding {from} to encoding {to}. When the conversion completely fails an empty string is @@ -4063,42 +3408,97 @@ 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 +id({expr}) *id()* + Returns a |String| which is a unique identifier of the + container type (|List|, |Dict|, |Blob| and |Partial|). It is + guaranteed that for the mentioned types `id(v1) ==# id(v2)` + returns true iff `type(v1) == type(v2) && v1 is v2`. + Note that `v:_null_string`, `v:_null_list`, `v:_null_dict` and + `v:_null_blob` have the same `id()` with different types + because they are internally represented as NULL pointers. + `id()` returns a hexadecimal representanion of the pointers to + the containers (i.e. like `0x994a40`), same as `printf("%p", + {expr})`, but it is advised against counting on the exact + format of the return value. + + It is not guaranteed that `id(no_longer_existing_container)` + will not be equal to some other `id()`: new containers may + reuse identifiers of the garbage-collected ones. + +indent({lnum}) *indent()* + The result is a Number, which is indent of line {lnum} in the current buffer. The indent is counted in spaces, the value of 'tabstop' is relevant. {lnum} is used just like in |getline()|. When {lnum} is invalid -1 is returned. - Can also be used as a |method|: > - GetLnum()->indent() +index({object}, {expr} [, {start} [, {ic}]]) *index()* + Find {expr} in {object} and return its index. See + |indexof()| for using a lambda to select the item. -index({object}, {expr} [, {start} [, {ic}]]) *index()* If {object} is a |List| return the lowest index where the item has a value equal to {expr}. There is no automatic conversion, so the String "4" is different from the Number 4. And the Number 4 is different from the Float 4.0. The value - of 'ignorecase' is not used here, case always matters. + of 'ignorecase' is not used here, case matters as indicated by + the {ic} argument. If {object} is a |Blob| return the lowest index where the byte value is equal to {expr}. If {start} is given then start looking at the item with index {start} (may be negative for an item relative to the end). + When {ic} is given and it is |TRUE|, ignore case. Otherwise case must match. + -1 is returned when {expr} is not found in {object}. - Example: > - :let idx = index(words, "the") - :if index(numbers, 123) >= 0 + Example: >vim + let idx = index(words, "the") + if index(numbers, 123) >= 0 + " ... + endif + +indexof({object}, {expr} [, {opts}]) *indexof()* + Returns the index of an item in {object} where {expr} is + v:true. {object} must be a |List| or a |Blob|. -< Can also be used as a |method|: > - GetObject()->index(what) + If {object} is a |List|, evaluate {expr} for each item in the + List until the expression is v:true and return the index of + this item. + + If {object} is a |Blob| evaluate {expr} for each byte in the + Blob until the expression is v:true and return the index of + this byte. + + {expr} must be a |string| or |Funcref|. + + If {expr} is a |string|: If {object} is a |List|, inside + {expr} |v:key| has the index of the current List item and + |v:val| has the value of the item. If {object} is a |Blob|, + inside {expr} |v:key| has the index of the current byte and + |v:val| has the byte value. + + If {expr} is a |Funcref| it must take two arguments: + 1. the key or the index of the current item. + 2. the value of the current item. + The function must return |TRUE| if the item is found and the + search should stop. + + The optional argument {opts} is a Dict and supports the + following items: + startidx start evaluating {expr} at the item with this + index; may be negative for an item relative to + the end + Returns -1 when {expr} evaluates to v:false for all the items. + Example: >vim + let l = [#{n: 10}, #{n: 20}, #{n: 30}] + echo indexof(l, "v:val.n == 20") + echo indexof(l, {i, v -> v.n == 30}) + echo indexof(l, "v:val.n == 20", #{startidx: 1}) + +input({prompt} [, {text} [, {completion}]]) *input()* -input({prompt} [, {text} [, {completion}]]) *input()* input({opts}) The result is a String, which is whatever the user typed on the command-line. The {prompt} argument is either a prompt @@ -4120,22 +3520,22 @@ input({opts}) The input is entered just like a command-line, with the same editing commands and mappings. There is a separate history for lines typed for input(). - Example: > - :if input("Coffee or beer? ") == "beer" - : echo "Cheers!" - :endif + Example: >vim + if input("Coffee or beer? ") == "beer" + echo "Cheers!" + endif < If the optional {text} argument is present and not empty, this is used for the default reply, as if the user typed this. - Example: > - :let color = input("Color? ", "white") + Example: >vim + let color = input("Color? ", "white") < The optional {completion} argument specifies the type of completion supported for the input. Without it completion is not performed. The supported completion types are the same as that can be supplied to a user-defined command using the "-complete=" argument. Refer to |:command-completion| for - more information. Example: > + more information. Example: >vim let fname = input("File: ", "", "file") < *input()-highlight* *E5400* *E5402* @@ -4156,7 +3556,7 @@ input({opts}) sections must be ordered so that next hl_start_col is greater then or equal to previous hl_end_col. - Example (try some input with parentheses): > + Example (try some input with parentheses): >vim highlight RBP1 guibg=Red ctermbg=red highlight RBP2 guibg=Yellow ctermbg=yellow highlight RBP3 guibg=Green ctermbg=green @@ -4201,18 +3601,15 @@ input({opts}) that further characters follow in the mapping, e.g., by using |:execute| or |:normal|. - Example with a mapping: > - :nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR> - :function GetFoo() - : call inputsave() - : let g:Foo = input("enter search pattern: ") - : call inputrestore() - :endfunction - -< Can also be used as a |method|: > - GetPrompt()->input() + Example with a mapping: >vim + nmap \x :call GetFoo()<CR>:exe "/" .. Foo<CR> + function GetFoo() + call inputsave() + let g:Foo = input("enter search pattern: ") + call inputrestore() + endfunction -inputlist({textlist}) *inputlist()* +inputlist({textlist}) *inputlist()* {textlist} must be a |List| of strings. This |List| is displayed, one string per line. The user will be prompted to enter a number, which is returned. @@ -4225,20 +3622,17 @@ inputlist({textlist}) *inputlist()* Make sure {textlist} has less than 'lines' entries, otherwise it won't work. It's a good idea to put the entry number at the start of the string. And put a prompt in the first item. - Example: > + Example: >vim let color = inputlist(['Select color:', '1. red', \ '2. green', '3. blue']) -< Can also be used as a |method|: > - GetChoices()->inputlist() - -inputrestore() *inputrestore()* +inputrestore() *inputrestore()* Restore typeahead that was saved with a previous |inputsave()|. Should be called the same number of times inputsave() is called. Calling it more often is harmless though. Returns TRUE when there is nothing to restore, FALSE otherwise. -inputsave() *inputsave()* +inputsave() *inputsave()* Preserve typeahead (also from mappings) and clear it, so that a following prompt gets input from the user. Should be followed by a matching inputrestore() after the prompt. Can @@ -4246,7 +3640,7 @@ inputsave() *inputsave()* many inputrestore() calls. Returns TRUE when out of memory, FALSE otherwise. -inputsecret({prompt} [, {text}]) *inputsecret()* +inputsecret({prompt} [, {text}]) *inputsecret()* This function acts much like the |input()| function with but two exceptions: a) the user's response will be displayed as a sequence of @@ -4257,10 +3651,7 @@ 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()* +insert({object}, {item} [, {idx}]) *insert()* When {object} is a |List| or a |Blob| insert {item} at the start of it. @@ -4269,129 +3660,96 @@ insert({object}, {item} [, {idx}]) *insert()* like omitting {idx}. A negative {idx} is also possible, see |list-index|. -1 inserts just before the last item. - Returns the resulting |List| or |Blob|. Examples: > - :let mylist = insert([2, 3, 5], 1) - :call insert(mylist, 4, -1) - :call insert(mylist, 6, len(mylist)) + Returns the resulting |List| or |Blob|. Examples: >vim + let mylist = insert([2, 3, 5], 1) + call insert(mylist, 4, -1) + call insert(mylist, 6, len(mylist)) < The last example can be done simpler with |add()|. Note that when {item} is a |List| it is inserted as a single item. Use |extend()| to concatenate |Lists|. - Can also be used as a |method|: > - mylist->insert(item) - -interrupt() *interrupt()* +interrupt() *interrupt()* Interrupt script execution. It works more or less like the user typing CTRL-C, most commands won't execute and control returns to the user. This is useful to abort execution - from lower down, e.g. in an autocommand. Example: > - :function s:check_typoname(file) - : if fnamemodify(a:file, ':t') == '[' - : echomsg 'Maybe typo' - : call interrupt() - : endif - :endfunction - :au BufWritePre * call s:check_typoname(expand('<amatch>')) - -invert({expr}) *invert()* + from lower down, e.g. in an autocommand. Example: >vim + function s:check_typoname(file) + if fnamemodify(a:file, ':t') == '[' + echomsg 'Maybe typo' + call interrupt() + endif + endfunction + au BufWritePre * call s:check_typoname(expand('<amatch>')) +< + +invert({expr}) *invert()* Bitwise invert. The argument is converted to a number. A - List, Dict or Float argument causes an error. Example: > - :let bits = invert(bits) -< Can also be used as a |method|: > - :let bits = bits->invert() + List, Dict or Float argument causes an error. Example: >vim + let bits = invert(bits) +< -isdirectory({directory}) *isdirectory()* +isdirectory({directory}) *isdirectory()* The result is a Number, which is |TRUE| when a directory with the name {directory} exists. If {directory} doesn't 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()* +isinf({expr}) *isinf()* Return 1 if {expr} is a positive infinity, or -1 a negative - infinity, otherwise 0. > - :echo isinf(1.0 / 0.0) -< 1 > - :echo isinf(-1.0 / 0.0) + infinity, otherwise 0. >vim + echo isinf(1.0 / 0.0) +< 1 >vim + echo isinf(-1.0 / 0.0) < -1 - Can also be used as a |method|: > - Compute()->isinf() - -islocked({expr}) *islocked()* *E786* +islocked({expr}) *islocked()* *E786* The result is a Number, which is |TRUE| when {expr} is the name of a locked variable. The string argument {expr} must be the name of a variable, |List| item or |Dictionary| entry, not the variable itself! - Example: > - :let alist = [0, ['a', 'b'], 2, 3] - :lockvar 1 alist - :echo islocked('alist') " 1 - :echo islocked('alist[1]') " 0 + Example: >vim + let alist = [0, ['a', 'b'], 2, 3] + lockvar 1 alist + echo islocked('alist') " 1 + echo islocked('alist[1]') " 0 < 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 - guaranteed that for the mentioned types `id(v1) ==# id(v2)` - returns true iff `type(v1) == type(v2) && v1 is v2`. - Note that |v:_null_string|, |v:_null_list|, |v:_null_dict| and - |v:_null_blob| have the same `id()` with different types - because they are internally represented as NULL pointers. - `id()` returns a hexadecimal representanion of the pointers to - the containers (i.e. like `0x994a40`), same as `printf("%p", - {expr})`, but it is advised against counting on the exact - format of the return value. - - It is not guaranteed that `id(no_longer_existing_container)` - will not be equal to some other `id()`: new containers may - reuse identifiers of the garbage-collected ones. +isnan({expr}) *isnan()* + Return |TRUE| if {expr} is a float with value NaN. >vim + echo isnan(0.0 / 0.0) +< 1 -items({dict}) *items()* +items({dict}) *items()* Return a |List| with all the key-value pairs of {dict}. Each |List| item is a list with two items: the key of a {dict} entry and the value of this entry. The |List| is in arbitrary order. Also see |keys()| and |values()|. - Example: > + Example: >vim for [key, value] in items(mydict) echo key .. ': ' .. value endfor -< Can also be used as a |method|: > - mydict->items() - -isnan({expr}) *isnan()* - Return |TRUE| if {expr} is a float with value NaN. > - echo isnan(0.0 / 0.0) -< 1 - - Can also be used as a |method|: > - Compute()->isnan() - -jobpid({job}) *jobpid()* +jobpid({job}) *jobpid()* Return the PID (process id) of |job-id| {job}. -jobresize({job}, {width}, {height}) *jobresize()* +jobresize({job}, {width}, {height}) *jobresize()* Resize the pseudo terminal window of |job-id| {job} to {width} columns and {height} rows. Fails if the job was not started with `"pty":v:true`. -jobstart({cmd} [, {opts}]) *jobstart()* +jobstart({cmd} [, {opts}]) *jobstart()* + Note: Prefer |vim.system()| in Lua (unless using the `pty` option). + Spawns {cmd} as a job. If {cmd} is a List it runs directly (no 'shell'). - If {cmd} is a String it runs in the 'shell', like this: > - :call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) + If {cmd} is a String it runs in the 'shell', like this: >vim + call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) < (See |shell-unquoting| for details.) - Example: > - :call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}}) + Example: >vim + call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}}) < Returns |job-id| on success, 0 on invalid arguments (or job table is full), -1 if {cmd}[0] or 'shell' is not executable. @@ -4404,10 +3762,10 @@ jobstart({cmd} [, {opts}]) *jobstart()* NOTE: on Windows if {cmd} is a List: - cmd[0] must be an executable (not a "built-in"). If it is - in $PATH it can be called by name, without an extension: > - :call jobstart(['ping', 'neovim.io']) -< If it is a full or partial path, extension is required: > - :call jobstart(['System32\ping.exe', 'neovim.io']) + in $PATH it can be called by name, without an extension: >vim + call jobstart(['ping', 'neovim.io']) +< If it is a full or partial path, extension is required: >vim + call jobstart(['System32\ping.exe', 'neovim.io']) < - {cmd} is collapsed to a string of quoted args as expected by CommandLineToArgvW https://msdn.microsoft.com/bb776391 unless cmd[0] is some form of "cmd.exe". @@ -4439,11 +3797,9 @@ jobstart({cmd} [, {opts}]) *jobstart()* stdout data. |on_stderr|: (function) Callback invoked when the job emits stderr data. - overlapped: (boolean) Set FILE_FLAG_OVERLAPPED for the - standard input/output passed to the child process. - Normally you do not need to set this. - (Only available on MS-Windows, On other - platforms, this option is silently ignored.) + overlapped: (boolean) Sets FILE_FLAG_OVERLAPPED for the + stdio passed to the child process. Only on + MS-Windows; ignored on other platforms. pty: (boolean) Connect the job to a new pseudo terminal, and its streams to the master file descriptor. `on_stdout` receives all output, @@ -4469,7 +3825,7 @@ jobstart({cmd} [, {opts}]) *jobstart()* - -1 if {cmd}[0] is not executable. See also |job-control|, |channel|, |msgpack-rpc|. -jobstop({id}) *jobstop()* +jobstop({id}) *jobstop()* Stop |job-id| {id} by sending SIGTERM to the job process. If the process does not terminate after a timeout then SIGKILL will be sent. When the job terminates its |on_exit| handler @@ -4479,14 +3835,14 @@ jobstop({id}) *jobstop()* Returns 1 for valid job id, 0 for invalid id, including jobs have exited or stopped. -jobwait({jobs} [, {timeout}]) *jobwait()* +jobwait({jobs} [, {timeout}]) *jobwait()* Waits for jobs and their |on_exit| handlers to complete. {jobs} is a List of |job-id|s to wait for. {timeout} is the maximum waiting time in milliseconds. If omitted or -1, wait forever. - Timeout of 0 can be used to check the status of a job: > + Timeout of 0 can be used to check the status of a job: >vim let running = jobwait([{job-id}], 0)[0] == -1 < During jobwait() callbacks for jobs not in the {jobs} list may @@ -4500,21 +3856,18 @@ jobwait({jobs} [, {timeout}]) *jobwait()* -2 if the job was interrupted (by |CTRL-C|) -3 if the job-id is invalid -join({list} [, {sep}]) *join()* +join({list} [, {sep}]) *join()* Join the items in {list} together into one String. When {sep} is specified it is put in between the items. If {sep} is omitted a single space is used. Note that {sep} is not added at the end. You might want to - add it there too: > + add it there too: >vim let lines = join(mylist, "\n") .. "\n" < String items are used as-is. |Lists| and |Dictionaries| are converted into a string like with |string()|. The opposite function is |split()|. - Can also be used as a |method|: > - mylist->join() - -json_decode({expr}) *json_decode()* +json_decode({expr}) *json_decode()* Convert {expr} from JSON object. Accepts |readfile()|-style list as the input, as well as regular string. May output any Vim value. In the following cases it will output @@ -4530,10 +3883,7 @@ 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()* +json_encode({expr}) *json_encode()* Convert {expr} into a JSON string. Accepts |msgpack-special-dict| as the input. Will not convert |Funcref|s, mappings with non-string keys (can be created as @@ -4545,28 +3895,19 @@ 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()* +keys({dict}) *keys()* Return a |List| with all the keys of {dict}. The |List| is in arbitrary order. Also see |items()| and |values()|. - Can also be used as a |method|: > - mydict->keys() - -keytrans({string}) *keytrans()* +keytrans({string}) *keytrans()* Turn the internal byte representation of keys into a form that - can be used for |:map|. E.g. > - :let xx = "\<C-Home>" - :echo keytrans(xx) + can be used for |:map|. E.g. >vim + let xx = "\<C-Home>" + echo keytrans(xx) < <C-Home> - Can also be used as a |method|: > - "\<C-Home>"->keytrans() - -< *len()* *E701* -len({expr}) The result is a Number, which is the length of the argument. +len({expr}) *len()* *E701* + The result is a Number, which is the length of the argument. When {expr} is a String or a Number the length in bytes is used, as with |strlen()|. When {expr} is a |List| the number of items in the |List| is @@ -4576,11 +3917,7 @@ len({expr}) The result is a Number, which is the length of the argument. |Dictionary| is returned. Otherwise an error is given and returns zero. - Can also be used as a |method|: > - mylist->len() - -< *libcall()* *E364* *E368* -libcall({libname}, {funcname}, {argument}) +libcall({libname}, {funcname}, {argument}) *libcall()* *E364* *E368* Call function {funcname} in the run-time library {libname} with single argument {argument}. This is useful to call functions in a library that you @@ -4619,27 +3956,19 @@ libcall({libname}, {funcname}, {argument}) the DLL is not in the usual places. For Unix: When compiling your own plugins, remember that the object code must be compiled as position-independent ('PIC'). - Examples: > - :echo libcall("libc.so", "getenv", "HOME") + Examples: >vim + echo libcall("libc.so", "getenv", "HOME") -< Can also be used as a |method|, the base is passed as the - third argument: > - GetValue()->libcall("libc.so", "getenv") -< - *libcallnr()* -libcallnr({libname}, {funcname}, {argument}) +libcallnr({libname}, {funcname}, {argument}) *libcallnr()* Just like |libcall()|, but used for a function that returns an int instead of a string. - Examples: > - :echo libcallnr("/usr/lib/libc.so", "getpid", "") - :call libcallnr("libc.so", "printf", "Hello World!\n") - :call libcallnr("libc.so", "sleep", 10) -< - Can also be used as a |method|, the base is passed as the - third argument: > - GetValue()->libcallnr("libc.so", "printf") + Examples: >vim + echo libcallnr("/usr/lib/libc.so", "getpid", "") + call libcallnr("libc.so", "printf", "Hello World!\n") + call libcallnr("libc.so", "sleep", 10) < -line({expr} [, {winid}]) *line()* + +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: @@ -4662,116 +3991,110 @@ line({expr} [, {winid}]) *line()* With the optional {winid} argument the values are obtained for that window instead of the current window. Returns 0 for invalid values of {expr} and {winid}. - 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 + Examples: >vim + echo line(".") " line number of the cursor + echo line(".", winid) " idem, in window "winid" + echo line("'t") " line number of mark t + echo line("'" .. marker) " line number of mark marker < To jump to the last known position when opening a file see |last-position-jump|. - Can also be used as a |method|: > - GetValue()->line() - -line2byte({lnum}) *line2byte()* +line2byte({lnum}) *line2byte()* Return the byte count from the start of the buffer for line {lnum}. This includes the end-of-line character, depending on the 'fileformat' option for the current buffer. The first line returns 1. UTF-8 encoding is used, 'fileencoding' is ignored. This can also be used to get the byte count for the - line just below the last line: > - line2byte(line("$") + 1) + line just below the last line: >vim + echo line2byte(line("$") + 1) < This is the buffer size plus one. If 'fileencoding' is empty it is the file size plus one. {lnum} is used like with |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()* +lispindent({lnum}) *lispindent()* Get the amount of indent for line {lnum} according the lisp indenting rules, as with 'lisp'. The indent is counted in spaces, the value of 'tabstop' is relevant. {lnum} is used just like in |getline()|. When {lnum} is invalid, -1 is returned. - Can also be used as a |method|: > - GetLnum()->lispindent() +list2blob({list}) *list2blob()* + Return a Blob concatenating all the number values in {list}. + Examples: >vim + echo list2blob([1, 2, 3, 4]) " returns 0z01020304 + echo list2blob([]) " returns 0z +< Returns an empty Blob on error. If one of the numbers is + negative or more than 255 error *E1239* is given. + + |blob2list()| does the opposite. -list2str({list} [, {utf8}]) *list2str()* +list2str({list} [, {utf8}]) *list2str()* Convert each number in {list} to a character string can - concatenate them all. Examples: > - list2str([32]) returns " " - list2str([65, 66, 67]) returns "ABC" -< The same can be done (slowly) with: > - join(map(list, {nr, val -> nr2char(val)}), '') + concatenate them all. Examples: >vim + echo list2str([32]) " returns " " + echo list2str([65, 66, 67]) " returns "ABC" +< The same can be done (slowly) with: >vim + echo join(map(list, {nr, val -> nr2char(val)}), '') < |str2list()| does the opposite. 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 "á" + With UTF-8 composing characters work as expected: >vim + echo list2str([97, 769]) " returns "á" < Returns an empty string on error. - Can also be used as a |method|: > - GetList()->list2str() - -localtime() *localtime()* +localtime() *localtime()* Return the current time, measured as seconds since 1st Jan 1970. See also |strftime()|, |strptime()| and |getftime()|. - -log({expr}) *log()* +log({expr}) *log()* Return the natural logarithm (base e) of {expr} as a |Float|. {expr} must evaluate to a |Float| or a |Number| in the range (0, inf]. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo log(10) -< 2.302585 > - :echo log(exp(5)) + Examples: >vim + echo log(10) +< 2.302585 >vim + echo log(exp(5)) < 5.0 - Can also be used as a |method|: > - Compute()->log() - -log10({expr}) *log10()* +log10({expr}) *log10()* Return the logarithm of Float {expr} to base 10 as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo log10(1000) -< 3.0 > - :echo log10(0.01) + Examples: >vim + echo log10(1000) +< 3.0 >vim + echo log10(0.01) < -2.0 - Can also be used as a |method|: > - Compute()->log10() - -luaeval({expr} [, {expr}]) +luaeval({expr} [, {expr}]) *luaeval()* 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 - {expr2}. For a |Blob| each byte is replaced. +map({expr1}, {expr2}) *map()* + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. + When {expr1} is a |List|| or |Dictionary|, replace each + item in {expr1} with the result of evaluating {expr2}. + For a |Blob| each byte is replaced. + For a |String|, each character, including composing + characters, is replaced. + If the item type changes you may want to use |mapnew()| to + create a new List or Dictionary. - {expr2} must be a |string| or |Funcref|. + {expr2} must be a |String| or |Funcref|. - If {expr2} is a |string|, inside {expr2} |v:val| has the value + If {expr2} is a |String|, inside {expr2} |v:val| has the value of the current item. For a |Dictionary| |v:key| has the key of the current item and for a |List| |v:key| has the index of the current item. For a |Blob| |v:key| has the index of the - current byte. - Example: > - :call map(mylist, '"> " .. v:val .. " <"') + current byte. For a |String| |v:key| has the index of the + current character. + Example: >vim + call map(mylist, '"> " .. v:val .. " <"') < This puts "> " before and " <" after each item in "mylist". Note that {expr2} is the result of an expression and is then @@ -4783,37 +4106,35 @@ map({expr1}, {expr2}) *map()* 1. The key or the index of the current item. 2. the value of the current item. The function must return the new value of the item. Example - that changes each value by "key-value": > + that changes each value by "key-value": >vim func KeyValue(key, val) return a:key .. '-' .. a:val endfunc call map(myDict, function('KeyValue')) -< It is shorter when using a |lambda|: > +< It is shorter when using a |lambda|: >vim call map(myDict, {key, val -> key .. '-' .. val}) -< If you do not use "val" you can leave it out: > +< If you do not use "val" you can leave it out: >vim call map(myDict, {key -> 'item: ' .. key}) -< If you do not use "key" you can use a short name: > +< If you do not use "key" you can use a short name: >vim call map(myDict, {_, val -> 'item: ' .. val}) < - The operation is done in-place. If you want a |List| or - |Dictionary| to remain unmodified make a copy first: > - :let tlist = map(copy(mylist), ' v:val .. "\t"') + The operation is done in-place for a |List| and |Dictionary|. + If you want it to remain unmodified make a copy first: >vim + let tlist = map(copy(mylist), ' v:val .. "\t"') -< Returns {expr1}, the |List|, |Blob| or |Dictionary| that was - filtered. When an error is encountered while evaluating - {expr2} no further items in {expr1} are processed. When - {expr2} is a Funcref errors inside a function are ignored, +< Returns {expr1}, the |List| or |Dictionary| that was filtered, + or a new |Blob| or |String|. + When an error is encountered while evaluating {expr2} no + further items in {expr1} are processed. + When {expr2} is a Funcref errors inside a function are ignored, unless it was defined with the "abort" flag. - Can also be used as a |method|: > - mylist->map(expr2) - - -maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* +maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* When {dict} is omitted or zero: Return the rhs of mapping {name} in mode {mode}. The returned String has special characters translated like in the output of the ":map" command - listing. + listing. When {dict} is TRUE a dictionary is returned, see + below. To get a list of all mappings see |maplist()|. When there is no mapping for {name}, an empty String is returned if {dict} is FALSE, otherwise returns an empty Dict. @@ -4841,11 +4162,11 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* When {dict} is there and it is |TRUE| return a dictionary containing all the information of the mapping with the - following items: + following items: *mapping-dict* "lhs" The {lhs} of the mapping as it would be typed "lhsraw" The {lhs} of the mapping as raw bytes "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate - form, only present when it differs from "lhsraw" + form, only present when it differs from "lhsraw" "rhs" The {rhs} of the mapping as typed. "silent" 1 for a |:map-silent| mapping, else 0. "noremap" 1 if the {rhs} of the mapping is not remappable. @@ -4859,10 +4180,17 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* "!" Insert and Commandline mode (|mapmode-ic|) "sid" The script local ID, used for <sid> mappings - (|<SID>|). + (|<SID>|). Negative for special contexts. + "scriptversion" The version of the script, always 1. "lnum" The line number in "sid", zero if unknown. "nowait" Do not wait for other, longer mappings. (|:map-<nowait>|). + "abbr" True if this is an |abbreviation|. + "mode_bits" Nvim's internal binary representation of "mode". + |mapset()| ignores this; only "mode" is used. + See |maplist()| for usage examples. The values + are from src/nvim/state_defs.h and may change in + the future. The dictionary can be used to restore a mapping with |mapset()|. @@ -4870,13 +4198,10 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* The mappings local to the current buffer are checked first, then the global mappings. This function can be used to map a key even when it's already - mapped, and have it do the original mapping too. Sketch: > + mapped, and have it do the original mapping too. Sketch: >vim exe 'nnoremap <Tab> ==' .. maparg('<Tab>', 'n') -< Can also be used as a |method|: > - GetKey()->maparg('n') - -mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* +mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* Check if there is a mapping that matches with {name} in mode {mode}. See |maparg()| for {mode} and special names in {name}. @@ -4902,33 +4227,87 @@ mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* The mappings local to the current buffer are checked first, then the global mappings. This function can be used to check if a mapping can be added - without being ambiguous. Example: > - :if mapcheck("_vv") == "" - : map _vv :set guifont=7x13<CR> - :endif + without being ambiguous. Example: >vim + if mapcheck("_vv") == "" + map _vv :set guifont=7x13<CR> + endif < 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') - -mapset({mode}, {abbr}, {dict}) *mapset()* - Restore a mapping from a dictionary returned by |maparg()|. - {mode} and {abbr} should be the same as for the call to - |maparg()|. *E460* +maplist([{abbr}]) *maplist()* + Returns a |List| of all mappings. Each List item is a |Dict|, + the same as what is returned by |maparg()|, see + |mapping-dict|. When {abbr} is there and it is |TRUE| use + abbreviations instead of mappings. + + Example to show all mappings with "MultiMatch" in rhs: >vim + echo maplist()->filter({_, m -> + \ match(get(m, 'rhs', ''), 'MultiMatch') >= 0 + \ }) +< It can be tricky to find mappings for particular |:map-modes|. + |mapping-dict|'s "mode_bits" can simplify this. For example, + the mode_bits for Normal, Insert or Command-line modes are + 0x19. To find all the mappings available in those modes you + can do: >vim + let saved_maps = [] + for m in maplist() + if and(m.mode_bits, 0x19) != 0 + eval saved_maps->add(m) + endif + endfor + echo saved_maps->mapnew({_, m -> m.lhs}) +< The values of the mode_bits are defined in Nvim's + src/nvim/state_defs.h file and they can be discovered at + runtime using |:map-commands| and "maplist()". Example: >vim + omap xyzzy <Nop> + let op_bit = maplist()->filter( + \ {_, m -> m.lhs == 'xyzzy'})[0].mode_bits + ounmap xyzzy + echo printf("Operator-pending mode bit: 0x%x", op_bit) + +mapnew({expr1}, {expr2}) *mapnew()* + Like |map()| but instead of replacing items in {expr1} a new + List or Dictionary is created and returned. {expr1} remains + unchanged. Items can still be changed by {expr2}, if you + don't want that use |deepcopy()| first. + +mapset({mode}, {abbr}, {dict}) *mapset()* + Restore a mapping from a dictionary, possibly returned by + |maparg()| or |maplist()|. A buffer mapping, when dict.buffer + is true, is set on the current buffer; it is up to the caller + to ensure that the intended buffer is the current buffer. This + feature allows copying mappings from one buffer to another. + The dict.mode value may restore a single mapping that covers + more than one mode, like with mode values of '!', ' ', "nox", + or 'v'. *E1276* + + In the first form, {mode} and {abbr} should be the same as + for the call to |maparg()|. *E460* {mode} is used to define the mode in which the mapping is set, not the "mode" entry in {dict}. - Example for saving and restoring a mapping: > + Example for saving and restoring a mapping: >vim let save_map = maparg('K', 'n', 0, 1) nnoremap K somethingelse - ... + " ... call mapset('n', 0, save_map) < Note that if you are going to replace a map in several modes, - e.g. with `:map!`, you need to save the mapping for all of - them, since they can differ. - + e.g. with `:map!`, you need to save/restore the mapping for + all of them, when they might differ. + + In the second form, with {dict} as the only argument, mode + and abbr are taken from the dict. + Example: >vim + let save_maps = maplist()->filter( + \ {_, m -> m.lhs == 'K'}) + nnoremap K somethingelse + cnoremap K somethingelse2 + " ... + unmap K + for d in save_maps + call mapset(d) + endfor -match({expr}, {pat} [, {start} [, {count}]]) *match()* +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 String, |Lists| and |Dictionaries| are used as echoed. @@ -4941,27 +4320,27 @@ match({expr}, {pat} [, {start} [, {count}]]) *match()* If there is no match -1 is returned. For getting submatches see |matchlist()|. - Example: > - :echo match("testing", "ing") " results in 4 - :echo match([1, 'x'], '\a') " results in 1 + Example: >vim + echo match("testing", "ing") " results in 4 + echo match([1, 'x'], '\a') " results in 1 < See |string-match| for how {pat} is used. *strpbrk()* - Vim doesn't have a strpbrk() function. But you can do: > - :let sepidx = match(line, '[.,;: \t]') + Vim doesn't have a strpbrk() function. But you can do: >vim + let sepidx = match(line, '[.,;: \t]') < *strcasestr()* Vim doesn't have a strcasestr() function. But you can add - "\c" to the pattern to ignore case: > - :let idx = match(haystack, '\cneedle') + "\c" to the pattern to ignore case: >vim + let idx = match(haystack, '\cneedle') < If {start} is given, the search starts from byte index {start} in a String or item {start} in a |List|. The result, however, is still the index counted from the - first character/item. Example: > - :echo match("testing", "ing", 2) -< result is again "4". > - :echo match("testing", "ing", 4) -< result is again "4". > - :echo match("testing", "t", 2) + first character/item. Example: >vim + echo match("testing", "ing", 2) +< result is again "4". >vim + echo match("testing", "ing", 4) +< result is again "4". >vim + echo match("testing", "t", 2) < result is "3". For a String, if {start} > 0 then it is like the string starts {start} bytes later, thus "^" will match at {start}. Except @@ -4975,7 +4354,7 @@ match({expr}, {pat} [, {start} [, {count}]]) *match()* When {count} is given use the {count}th match. When a match is found in a String the search for the next one starts one - character further. Thus this example results in 1: > + character further. Thus this example results in 1: >vim echo match("testing", "..", 0, 2) < In a |List| the search continues in the next item. Note that when {count} is added the way {start} works changes, @@ -4990,11 +4369,7 @@ 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|: > - GetText()->match('word') - GetList()->match('word') -< - *matchadd()* *E798* *E799* *E801* *E957* + *matchadd()* *E798* *E799* *E801* *E957* matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) Defines a pattern to be highlighted in the current window (a "match"). It will be highlighted with {group}. Returns an @@ -5043,21 +4418,17 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) Returns -1 on error. - Example: > - :highlight MyGroup ctermbg=green guibg=green - :let m = matchadd("MyGroup", "TODO") -< Deletion of the pattern: > - :call matchdelete(m) + Example: >vim + highlight MyGroup ctermbg=green guibg=green + let m = matchadd("MyGroup", "TODO") +< Deletion of the pattern: >vim + call matchdelete(m) < A list of matches defined by |matchadd()| and |:match| are 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}]]]) +matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) *matchaddpos()* Same as |matchadd()|, but requires a list of positions {pos} instead of a pattern. This command is faster than |matchadd()| because it does not require to handle regular expressions and @@ -5085,19 +4456,16 @@ matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) Returns -1 on error. - Example: > - :highlight MyGroup ctermbg=green guibg=green - :let m = matchaddpos("MyGroup", [[23, 24], 34]) -< Deletion of the pattern: > - :call matchdelete(m) + Example: >vim + highlight MyGroup ctermbg=green guibg=green + let m = matchaddpos("MyGroup", [[23, 24], 34]) +< Deletion of the pattern: >vim + call matchdelete(m) < Matches added by |matchaddpos()| are returned by |getmatches()|. - Can also be used as a |method|: > - GetGroup()->matchaddpos([23, 11]) - -matcharg({nr}) *matcharg()* +matcharg({nr}) *matcharg()* Selects the {nr} match item, as set with a |:match|, |:2match| or |:3match| command. Return a |List| with two elements: @@ -5109,10 +4477,7 @@ 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* +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, otherwise -1. See example for |matchadd()|. All matches can @@ -5120,32 +4485,26 @@ 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()* +matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()* Same as |match()|, but return the index of first character - after the match. Example: > - :echo matchend("testing", "ing") + after the match. Example: >vim + echo matchend("testing", "ing") < results in "7". *strspn()* *strcspn()* Vim doesn't have a strspn() or strcspn() function, but you can - do it with matchend(): > - :let span = matchend(line, '[a-zA-Z]') - :let span = matchend(line, '[^a-zA-Z]') + do it with matchend(): >vim + let span = matchend(line, '[a-zA-Z]') + let span = matchend(line, '[^a-zA-Z]') < Except that -1 is returned when there are no matches. - The {start}, if given, has the same meaning as for |match()|. > - :echo matchend("testing", "ing", 2) -< results in "7". > - :echo matchend("testing", "ing", 5) + The {start}, if given, has the same meaning as for |match()|. >vim + echo matchend("testing", "ing", 2) +< results in "7". >vim + echo matchend("testing", "ing", 5) < result is "-1". When {expr} is a |List| the result is equal to |match()|. - Can also be used as a |method|: > - GetText()->matchend('word') - -matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* +matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* If {list} is a list of strings, then returns a |List| with all the strings in {list} that fuzzy match {str}. The strings in the returned list are sorted based on the matching score. @@ -5186,29 +4545,29 @@ matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* Refer to |fuzzy-matching| for more information about fuzzy matching strings. - Example: > - :echo matchfuzzy(["clay", "crow"], "cay") -< results in ["clay"]. > - :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl") -< results in a list of buffer names fuzzy matching "ndl". > - :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'}) + Example: >vim + echo matchfuzzy(["clay", "crow"], "cay") +< results in ["clay"]. >vim + echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl") +< results in a list of buffer names fuzzy matching "ndl". >vim + echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'}) < results in a list of buffer information dicts with buffer - names fuzzy matching "ndl". > - :echo getbufinfo()->matchfuzzy("spl", + names fuzzy matching "ndl". >vim + echo getbufinfo()->matchfuzzy("spl", \ {'text_cb' : {v -> v.name}}) < results in a list of buffer information dicts with buffer - names fuzzy matching "spl". > - :echo v:oldfiles->matchfuzzy("test") -< results in a list of file names fuzzy matching "test". > - :let l = readfile("buffer.c")->matchfuzzy("str") -< results in a list of lines in "buffer.c" fuzzy matching "str". > - :echo ['one two', 'two one']->matchfuzzy('two one') -< results in `['two one', 'one two']` . > - :echo ['one two', 'two one']->matchfuzzy('two one', + names fuzzy matching "spl". >vim + echo v:oldfiles->matchfuzzy("test") +< results in a list of file names fuzzy matching "test". >vim + let l = readfile("buffer.c")->matchfuzzy("str") +< results in a list of lines in "buffer.c" fuzzy matching "str". >vim + echo ['one two', 'two one']->matchfuzzy('two one') +< results in `['two one', 'one two']` . >vim + echo ['one two', 'two one']->matchfuzzy('two one', \ {'matchseq': 1}) -< results in ['two one']. +< results in `['two one']`. -matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()* +matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()* Same as |matchfuzzy()|, but returns the list of matched strings, the list of character positions where characters in {str} matches and a list of matching scores. You can @@ -5221,95 +4580,81 @@ matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()* If there are no matching strings or there is an error, then a list with three empty list items is returned. - Example: > - :echo matchfuzzypos(['testing'], 'tsg') -< results in [["testing"], [[0, 2, 6]], [99]] > - :echo matchfuzzypos(['clay', 'lacy'], 'la') -< results in [["lacy", "clay"], [[0, 1], [1, 2]], [153, 133]] > - :echo [{'text': 'hello', 'id' : 10}] + Example: >vim + echo matchfuzzypos(['testing'], 'tsg') +< results in [["testing"], [[0, 2, 6]], [99]] >vim + echo matchfuzzypos(['clay', 'lacy'], 'la') +< results in [["lacy", "clay"], [[0, 1], [1, 2]], [153, 133]] >vim + echo [{'text': 'hello', 'id' : 10}] \ ->matchfuzzypos('ll', {'key' : 'text'}) -< results in [[{"id": 10, "text": "hello"}], [[2, 3]], [127]] +< results in `[[{"id": 10, "text": "hello"}], [[2, 3]], [127]]` -matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* +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 return. Following items are submatches, like "\1", "\2", etc. in |:substitute|. When an optional submatch didn't match an - empty string is used. Example: > + empty string is used. Example: >vim echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)') < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] When there is no match an empty list is returned. You can pass in a List, but that is not very useful. - Can also be used as a |method|: > - GetText()->matchlist('word') - -matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* - Same as |match()|, but return the matched string. Example: > - :echo matchstr("testing", "ing") +matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* + Same as |match()|, but return the matched string. Example: >vim + echo matchstr("testing", "ing") < results in "ing". When there is no match "" is returned. - The {start}, if given, has the same meaning as for |match()|. > - :echo matchstr("testing", "ing", 2) -< results in "ing". > - :echo matchstr("testing", "ing", 5) + The {start}, if given, has the same meaning as for |match()|. >vim + echo matchstr("testing", "ing", 2) +< results in "ing". >vim + echo matchstr("testing", "ing", 5) < result is "". 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()* +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: > - :echo matchstrpos("testing", "ing") + position and the end position of the match. Example: >vim + echo matchstrpos("testing", "ing") < results in ["ing", 4, 7]. When there is no match ["", -1, -1] is returned. - The {start}, if given, has the same meaning as for |match()|. > - :echo matchstrpos("testing", "ing", 2) -< results in ["ing", 4, 7]. > - :echo matchstrpos("testing", "ing", 5) + The {start}, if given, has the same meaning as for |match()|. >vim + echo matchstrpos("testing", "ing", 2) +< results in ["ing", 4, 7]. >vim + echo matchstrpos("testing", "ing", 5) < result is ["", -1, -1]. When {expr} is a |List| then the matching item, the index of first item where {pat} matches, the start position and the - end position of the match are returned. > - :echo matchstrpos([1, '__x'], '\a') + end position of the match are returned. >vim + echo matchstrpos([1, '__x'], '\a') < 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}. Example: > +max({expr}) *max()* + Return the maximum value of all items in {expr}. Example: >vim echo max([apples, pears, oranges]) < {expr} can be a |List| or a |Dictionary|. For a Dictionary, it returns the maximum of all values in the Dictionary. If {expr} is neither a List nor a Dictionary, or one of the items in {expr} cannot be used as a Number this results in - an error. An empty |List| or |Dictionary| results in zero. - - Can also be used as a |method|: > - mylist->max() + an error. An empty |List| or |Dictionary| results in zero. - -menu_get({path} [, {modes}]) *menu_get()* +menu_get({path} [, {modes}]) *menu_get()* Returns a |List| of |Dictionaries| describing |menus| (defined by |:menu|, |:amenu|, …), including |hidden-menus|. {path} matches a menu by name, or all menus if {path} is an - empty string. Example: > - :echo menu_get('File','') - :echo menu_get('') + empty string. Example: >vim + echo menu_get('File','') + echo menu_get('') < {modes} is a string of zero or more modes (see |maparg()| or |creating-menus| for the list of modes). "a" means "all". - Example: > + Example: >vim nnoremenu &Test.Test inormal inoremenu Test.Test insert vnoremenu Test.Test x @@ -5343,7 +4688,7 @@ menu_get({path} [, {modes}]) *menu_get()* } ] < -menu_info({name} [, {mode}]) *menu_info()* +menu_info({name} [, {mode}]) *menu_info()* Return information about the specified menu {name} in mode {mode}. The menu name should be specified without the shortcut character ('&'). If {name} is "", then the top-level @@ -5395,9 +4740,9 @@ menu_info({name} [, {mode}]) *menu_info()* Returns an empty dictionary if the menu item is not found. - Examples: > - :echo menu_info('Edit.Cut') - :echo menu_info('File.Save', 'n') + Examples: >vim + echo menu_info('Edit.Cut') + echo menu_info('File.Save', 'n') " Display the entire menu hierarchy in a buffer func ShowMenu(name, pfx) @@ -5413,12 +4758,9 @@ menu_info({name} [, {mode}]) *menu_info()* call ShowMenu(topmenu, '') endfor < - Can also be used as a |method|: > - GetMenuName()->menu_info('v') - -< *min()* -min({expr}) Return the minimum value of all items in {expr}. Example: > +min({expr}) *min()* + Return the minimum value of all items in {expr}. Example: >vim echo min([apples, pears, oranges]) < {expr} can be a |List| or a |Dictionary|. For a Dictionary, @@ -5427,42 +4769,55 @@ min({expr}) Return the minimum value of all items in {expr}. Example: > items in {expr} cannot be used as a Number this results in an error. An empty |List| or |Dictionary| results in zero. - Can also be used as a |method|: > - mylist->min() - -< *mkdir()* *E739* -mkdir({name} [, {path} [, {prot}]]) +mkdir({name} [, {flags} [, {prot}]]) *mkdir()* *E739* Create directory {name}. - If {path} is "p" then intermediate directories are created as - necessary. Otherwise it must be "". + When {flags} is present it must be a string. An empty string + has no effect. + + If {flags} contains "p" then intermediate directories are + created as necessary. + If {flags} contains "D" then {name} is deleted at the end of + the current function, as with: >vim + defer delete({name}, 'd') +< + If {flags} contains "R" then {name} is deleted recursively at + the end of the current function, as with: >vim + defer delete({name}, 'rf') +< Note that when {name} has more than one part and "p" is used + some directories may already exist. Only the first one that + is created and what it contains is scheduled to be deleted. + E.g. when using: >vim + call mkdir('subdir/tmp/autoload', 'pR') +< and "subdir" already exists then "subdir/tmp" will be + scheduled for deletion, like with: >vim + defer delete('subdir/tmp', 'rf') +< If {prot} is given it is used to set the protection bits of the new directory. The default is 0o755 (rwxr-xr-x: r/w for the user, readable for others). Use 0o700 to make it unreadable for others. {prot} is applied for all parts of {name}. Thus if you create - /tmp/foo/bar then /tmp/foo will be created with 0o700. Example: > - :call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700) + /tmp/foo/bar then /tmp/foo will be created with 0o700. Example: >vim + call mkdir($HOME .. "/tmp/foo/bar", "p", 0o700) < This function is not available in the |sandbox|. - If you try to create an existing directory with {path} set to + If you try to create an existing directory with {flags} set to "p" mkdir() will silently exit. The function result is a Number, which is TRUE if the call was 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. +mode([expr]) *mode()* + Return a string that indicates the current mode. If [expr] is supplied and it evaluates to a non-zero Number or a non-empty String (|non-zero-arg|), then the full mode is returned, otherwise only the first letter is returned. + Also see |state()|. n Normal no Operator-pending @@ -5495,7 +4850,9 @@ mode([expr]) Return a string that indicates the current mode. Rvc Virtual Replace mode completion |compl-generic| Rvx Virtual Replace mode |i_CTRL-X| completion c Command-line editing + cr Command-line editing overstrike mode |c_<Insert>| cv Vim Ex mode |gQ| + cvr Vim Ex mode while in overstrike mode |c_<Insert>| r Hit-enter prompt rm The -- more -- prompt r? A |:confirm| query of some sort @@ -5509,15 +4866,12 @@ 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 +msgpackdump({list} [, {type}]) *msgpackdump()* + Convert a list of Vimscript objects to msgpack. Returned value is a |readfile()|-style list. When {type} contains "B", a |Blob| is - returned instead. Example: > + returned instead. Example: >vim call writefile(msgpackdump([{}]), 'fname.mpack', 'b') -< or, using a |Blob|: > +< or, using a |Blob|: >vim call writefile(msgpackdump([{}], 'B'), 'fname.mpack') < This will write the single 0x80 byte to a `fname.mpack` file @@ -5531,10 +4885,10 @@ msgpackdump({list} [, {type}]) *msgpackdump()* 4. Other strings and |Blob|s are always dumped as BIN strings. 5. Points 3. and 4. do not apply to |msgpack-special-dict|s. -msgpackparse({data}) *msgpackparse()* +msgpackparse({data}) *msgpackparse()* Convert a |readfile()|-style list or a |Blob| to a list of - VimL objects. - Example: > + Vimscript objects. + Example: >vim let fname = expand('~/.config/nvim/shada/main.shada') let mpack = readfile(fname, 'b') let shada_objects = msgpackparse(mpack) @@ -5605,36 +4959,31 @@ msgpackparse({data}) *msgpackparse()* representing extension type. Second is |readfile()|-style list of strings. -nextnonblank({lnum}) *nextnonblank()* +nextnonblank({lnum}) *nextnonblank()* Return the line number of the first line at or below {lnum} - that is not blank. Example: > - if getline(nextnonblank(1)) =~ "Java" + that is not blank. Example: >vim + if getline(nextnonblank(1)) =~ "Java" | endif < When {lnum} is invalid or there is no non-blank line at or below it, zero is returned. {lnum} is used like with |getline()|. See also |prevnonblank()|. - Can also be used as a |method|: > - GetLnum()->nextnonblank() - -nr2char({expr} [, {utf8}]) *nr2char()* +nr2char({expr} [, {utf8}]) *nr2char()* Return a string with a single character, which has the number - value {expr}. Examples: > - nr2char(64) returns "@" - nr2char(32) returns " " -< Example for "utf-8": > - nr2char(300) returns I with bow character -< UTF-8 encoding is always used, {utf8} option has no effect, + value {expr}. Examples: >vim + echo nr2char(64) " returns '@' + echo nr2char(32) " returns ' ' +< Example for "utf-8": >vim + echo nr2char(300) " returns I with bow character +< + UTF-8 encoding is always used, {utf8} option has no effect, and exists only for backwards-compatibility. Note that a NUL character in the file is specified with nr2char(10), because NULs are represented with newline 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* +nvim_...({...}) *nvim_...()* *E5555* *eval-api* Call nvim |api| functions. The type checking of arguments will be stricter than for most other builtins. For instance, if Integer is expected, a |Number| must be passed in, a @@ -5645,39 +4994,33 @@ nvim_...({...}) *E5555* *nvim_...()* *eval-api* also take the numerical value 0 to indicate the current (focused) object. -or({expr}, {expr}) *or()* +or({expr}, {expr}) *or()* Bitwise OR on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. Also see `and()` and `xor()`. - Example: > - :let bits = or(bits, 0x80) -< Can also be used as a |method|: > - :let bits = bits->or(0x80) + Example: >vim + let bits = or(bits, 0x80) < Rationale: The reason this is a function and not using the "|" character like many languages, is that Vi has always used "|" to separate commands. In many places it would not be clear if "|" is an operator or a command separator. - -pathshorten({path} [, {len}]) *pathshorten()* +pathshorten({path} [, {len}]) *pathshorten()* Shorten directory names in the path {path} and return the result. The tail, the file name, is kept as-is. The other components in the path are reduced to {len} letters in length. If {len} is omitted or smaller than 1 then 1 is used (single - letters). Leading '~' and '.' characters are kept. Examples: > - :echo pathshorten('~/.config/nvim/autoload/file1.vim') + letters). Leading '~' and '.' characters are kept. Examples: >vim + echo pathshorten('~/.config/nvim/autoload/file1.vim') < ~/.c/n/a/file1.vim ~ -> - :echo pathshorten('~/.config/nvim/autoload/file2.vim', 2) +>vim + echo pathshorten('~/.config/nvim/autoload/file2.vim', 2) < ~/.co/nv/au/file2.vim ~ It doesn't matter if the path exists or not. Returns an empty string on error. - Can also be used as a |method|: > - GetDirectories()->pathshorten() - -perleval({expr}) *perleval()* +perleval({expr}) *perleval()* Evaluate |perl| expression {expr} and return its result converted to Vim data structures. Numbers and strings are returned as they are (strings are @@ -5688,49 +5031,40 @@ perleval({expr}) *perleval()* Note: If you want an array or hash, {expr} must return a reference to it. - Example: > - :echo perleval('[1 .. 4]') + Example: >vim + echo perleval('[1 .. 4]') < [1, 2, 3, 4] - Can also be used as a |method|: > - GetExpr()->perleval() - -pow({x}, {y}) *pow()* +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|. Returns 0.0 if {x} or {y} is not a |Float| or a |Number|. - Examples: > - :echo pow(3, 3) -< 27.0 > - :echo pow(2, 16) -< 65536.0 > - :echo pow(32, 0.20) + Examples: >vim + echo pow(3, 3) +< 27.0 >vim + echo pow(2, 16) +< 65536.0 >vim + echo pow(32, 0.20) < 2.0 - Can also be used as a |method|: > - Compute()->pow(3) - -prevnonblank({lnum}) *prevnonblank()* +prevnonblank({lnum}) *prevnonblank()* Return the line number of the first line at or above {lnum} - that is not blank. Example: > + that is not blank. Example: >vim let ind = indent(prevnonblank(v:lnum - 1)) < When {lnum} is invalid or there is no non-blank line at or above it, zero is returned. {lnum} is used like with |getline()|. Also see |nextnonblank()|. - Can also be used as a |method|: > - GetLnum()->prevnonblank() - -printf({fmt}, {expr1} ...) *printf()* +printf({fmt}, {expr1} ...) *printf()* Return a String with {fmt}, where "%" items are replaced by - the formatted form of their respective arguments. Example: > - printf("%4d: E%d %.30s", lnum, errno, msg) + the formatted form of their respective arguments. Example: >vim + echo printf("%4d: E%d %.30s", lnum, errno, msg) < May result in: " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~ When used as a |method| the base is passed as the second - argument: > + argument: >vim Compute()->printf("result: %d") < You can use `call()` to pass the items as a list. @@ -5766,7 +5100,11 @@ printf({fmt}, {expr1} ...) *printf()* The "%" starts a conversion specification. The following arguments appear in sequence: - % [flags] [field-width] [.precision] type + % [pos-argument] [flags] [field-width] [.precision] type + + pos-argument + At most one positional argument specifier. These + take the form {n$}, where n is >= 1. flags Zero or more of the following flags: @@ -5826,15 +5164,21 @@ printf({fmt}, {expr1} ...) *printf()* be applied, see below. A field width or precision, or both, may be indicated by an - asterisk '*' instead of a digit string. In this case, a + asterisk "*" instead of a digit string. In this case, a Number argument supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field width; a negative precision is - treated as though it were missing. Example: > - :echo printf("%d: %.*s", nr, width, line) + treated as though it were missing. Example: >vim + echo printf("%d: %.*s", nr, width, line) < This limits the length of the text used from "line" to "width" bytes. + If the argument to be formatted is specified using a posional + argument specifier, and a '*' is used to indicate that a + number argument is to be used to specify the width or + precision, the argument(s) to be used must also be specified + using a {n$} positional argument specifier. See |printf-$|. + The conversion specifiers and their meanings are: *printf-d* *printf-b* *printf-B* *printf-o* *printf-x* *printf-X* @@ -5851,8 +5195,13 @@ printf({fmt}, {expr1} ...) *printf()* than the field width, the field is expanded to contain the conversion result. The 'h' modifier indicates the argument is 16 bits. - The 'l' modifier indicates the argument is 32 bits. - The 'L' modifier indicates the argument is 64 bits. + The 'l' modifier indicates the argument is a long + integer. The size will be 32 bits or 64 bits + depending on your platform. + The "ll" modifier indicates the argument is 64 bits. + The b and B conversion specifiers never take a width + modifier and always assume their argument is a 64 bit + integer. Generally, these modifiers are not useful. They are ignored when type is known from the argument. @@ -5886,7 +5235,7 @@ printf({fmt}, {expr1} ...) *printf()* (out of range or dividing by zero) results in "inf" or "-inf" with %f (INF or -INF with %F). "0.0 / 0.0" results in "nan" with %f (NAN with %F). - Example: > + Example: >vim echo printf("%.2f", 12.115) < 12.12 Note that roundoff depends on the system libraries. @@ -5922,17 +5271,119 @@ printf({fmt}, {expr1} ...) *printf()* of "%" items. If there are not sufficient or too many arguments an error is given. Up to 18 arguments can be used. -prompt_getprompt({buf}) *prompt_getprompt()* + *printf-$* + In certain languages, error and informative messages are + more readable when the order of words is different from the + corresponding message in English. To accommodate translations + having a different word order, positional arguments may be + used to indicate this. For instance: >vim + + #, c-format + msgid "%s returning %s" + msgstr "waarde %2$s komt terug van %1$s" +< + In this example, the sentence has its 2 string arguments + reversed in the output. >vim + + echo printf( + "In The Netherlands, vim's creator's name is: %1$s %2$s", + "Bram", "Moolenaar") +< In The Netherlands, vim's creator's name is: Bram Moolenaar >vim + + echo printf( + "In Belgium, vim's creator's name is: %2$s %1$s", + "Bram", "Moolenaar") +< In Belgium, vim's creator's name is: Moolenaar Bram + + Width (and precision) can be specified using the '*' specifier. + In this case, you must specify the field width position in the + argument list. >vim + + echo printf("%1$*2$.*3$d", 1, 2, 3) +< 001 >vim + echo printf("%2$*3$.*1$d", 1, 2, 3) +< 2 >vim + echo printf("%3$*1$.*2$d", 1, 2, 3) +< 03 >vim + echo printf("%1$*2$.*3$g", 1.4142, 2, 3) +< 1.414 + + You can mix specifying the width and/or precision directly + and via positional arguments: >vim + + echo printf("%1$4.*2$f", 1.4142135, 6) +< 1.414214 >vim + echo printf("%1$*2$.4f", 1.4142135, 6) +< 1.4142 >vim + echo printf("%1$*2$.*3$f", 1.4142135, 6, 2) +< 1.41 + + *E1500* + You cannot mix positional and non-positional arguments: >vim + echo printf("%s%1$s", "One", "Two") +< E1500: Cannot mix positional and non-positional arguments: + %s%1$s + + *E1501* + You cannot skip a positional argument in a format string: >vim + echo printf("%3$s%1$s", "One", "Two", "Three") +< E1501: format argument 2 unused in $-style format: + %3$s%1$s + + *E1502* + You can re-use a [field-width] (or [precision]) argument: >vim + echo printf("%1$d at width %2$d is: %01$*2$d", 1, 2) +< 1 at width 2 is: 01 + + However, you can't use it as a different type: >vim + echo printf("%1$d at width %2$ld is: %01$*2$d", 1, 2) +< E1502: Positional argument 2 used as field width reused as + different type: long int/int + + *E1503* + When a positional argument is used, but not the correct number + or arguments is given, an error is raised: >vim + echo printf("%1$d at width %2$d is: %01$*2$.*3$d", 1, 2) +< E1503: Positional argument 3 out of bounds: %1$d at width + %2$d is: %01$*2$.*3$d + + Only the first error is reported: >vim + echo printf("%01$*2$.*3$d %4$d", 1, 2) +< E1503: Positional argument 3 out of bounds: %01$*2$.*3$d + %4$d + + *E1504* + A positional argument can be used more than once: >vim + echo printf("%1$s %2$s %1$s", "One", "Two") +< One Two One + + However, you can't use a different type the second time: >vim + echo printf("%1$s %2$s %1$d", "One", "Two") +< E1504: Positional argument 1 type used inconsistently: + int/string + + *E1505* + Various other errors that lead to a format string being + wrongly formatted lead to: >vim + echo printf("%1$d at width %2$d is: %01$*2$.3$d", 1, 2) +< E1505: Invalid format specifier: %1$d at width %2$d is: + %01$*2$.3$d + + *E1507* + This internal error indicates that the logic to parse a + positional format argument ran into a problem that couldn't be + otherwise reported. Please file a bug against Vim if you run + into this, copying the exact format string and parameters that + were used. + +prompt_getprompt({buf}) *prompt_getprompt()* Returns the effective prompt text for buffer {buf}. {buf} can be a buffer name or number. See |prompt-buffer|. If the buffer doesn't exist or isn't a prompt buffer, an empty string is returned. - Can also be used as a |method|: > - GetBuffer()->prompt_getprompt() - -prompt_setcallback({buf}, {expr}) *prompt_setcallback()* +prompt_setcallback({buf}, {expr}) *prompt_setcallback()* Set prompt callback for buffer {buf} to {expr}. When {expr} is an empty string the callback is removed. This has only effect if {buf} has 'buftype' set to "prompt". @@ -5948,23 +5399,23 @@ prompt_setcallback({buf}, {expr}) *prompt_setcallback()* The callback is invoked with one argument, which is the text that was entered at the prompt. This can be an empty string if the user only typed Enter. - Example: > - call prompt_setcallback(bufnr(''), function('s:TextEntered')) + Example: >vim func s:TextEntered(text) if a:text == 'exit' || a:text == 'quit' stopinsert + " Reset 'modified' to allow the buffer to be closed. + " We assume there is nothing useful to be saved. + set nomodified close else + " Do something useful with "a:text". In this example + " we just repeat it. call append(line('$') - 1, 'Entered: "' .. a:text .. '"') - " Reset 'modified' to allow the buffer to be closed. - set nomodified endif endfunc + call prompt_setcallback(bufnr(), function('s:TextEntered')) -< Can also be used as a |method|: > - GetBuffer()->prompt_setcallback(callback) - -prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()* +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 {buf} has 'buftype' set to "prompt". @@ -5973,20 +5424,15 @@ 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()* +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: > + "prompt". Example: >vim call prompt_setprompt(bufnr(''), 'command: ') < - Can also be used as a |method|: > - GetBuffer()->prompt_setprompt('command: ') -pum_getpos() *pum_getpos()* +pum_getpos() *pum_getpos()* If the popup menu (see |ins-completion-menu|) is not visible, returns an empty |Dictionary|, otherwise, returns a |Dictionary| with the following keys: @@ -5999,13 +5445,13 @@ pum_getpos() *pum_getpos()* The values are the same as in |v:event| during |CompleteChanged|. -pumvisible() *pumvisible()* +pumvisible() *pumvisible()* Returns non-zero when the popup menu is visible, zero otherwise. See |ins-completion-menu|. This can be used to avoid some things that would remove the popup menu. -py3eval({expr}) *py3eval()* +py3eval({expr}) *py3eval()* Evaluate Python expression {expr} and return its result converted to Vim data structures. Numbers and strings are returned as they are (strings are @@ -6015,11 +5461,7 @@ 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()* +pyeval({expr}) *pyeval()* *E858* *E859* Evaluate Python expression {expr} and return its result converted to Vim data structures. Numbers and strings are returned as they are (strings are @@ -6028,20 +5470,29 @@ 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()* +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() +rand([{expr}]) *rand()* + Return a pseudo-random Number generated with an xoshiro128** + algorithm using seed {expr}. The returned number is 32 bits, + also on 64 bits systems, for consistency. + {expr} can be initialized by |srand()| and will be updated by + rand(). If {expr} is omitted, an internal seed value is used + and updated. + Returns -1 if {expr} is invalid. + + Examples: >vim + echo rand() + let seed = srand() + echo rand(seed) + echo rand(seed) % 16 " random number 0 - 15 < - *E726* *E727* -range({expr} [, {max} [, {stride}]]) *range()* + +range({expr} [, {max} [, {stride}]]) *range()* *E726* *E727* Returns a |List| with Numbers: - If only {expr} is specified: [0, 1, ..., {expr} - 1] - If {max} is specified: [{expr}, {expr} + 1, ..., {max}] @@ -6051,45 +5502,40 @@ range({expr} [, {max} [, {stride}]]) *range()* When the maximum is one before the start the result is an empty list. When the maximum is more than one before the start this is an error. - Examples: > - range(4) " [0, 1, 2, 3] - range(2, 4) " [2, 3, 4] - range(2, 9, 3) " [2, 5, 8] - range(2, -2, -1) " [2, 1, 0, -1, -2] - range(0) " [] - range(2, 0) " error! -< - Can also be used as a |method|: > - GetExpr()->range() -< -rand([{expr}]) *rand()* - Return a pseudo-random Number generated with an xoshiro128** - algorithm using seed {expr}. The returned number is 32 bits, - also on 64 bits systems, for consistency. - {expr} can be initialized by |srand()| and will be updated by - rand(). If {expr} is omitted, an internal seed value is used - and updated. - Returns -1 if {expr} is invalid. - - Examples: > - :echo rand() - :let seed = srand() - :echo rand(seed) - :echo rand(seed) % 16 " random number 0 - 15 -< - Can also be used as a |method|: > - seed->rand() + Examples: >vim + echo range(4) " [0, 1, 2, 3] + echo range(2, 4) " [2, 3, 4] + echo range(2, 9, 3) " [2, 5, 8] + echo range(2, -2, -1) " [2, 1, 0, -1, -2] + echo range(0) " [] + echo range(2, 0) " error! < -readblob({fname}) *readblob()* +readblob({fname} [, {offset} [, {size}]]) *readblob()* Read file {fname} in binary mode and return a |Blob|. - When the file can't be opened an error message is given and + If {offset} is specified, read the file from the specified + offset. If it is a negative value, it is used as an offset + from the end of the file. E.g., to read the last 12 bytes: >vim + echo readblob('file.bin', -12) +< If {size} is specified, only the specified size will be read. + E.g. to read the first 100 bytes of a file: >vim + echo readblob('file.bin', 0, 100) +< If {size} is -1 or omitted, the whole data starting from + {offset} will be read. + This can be also used to read the data from a character device + on Unix when {size} is explicitly set. Only if the device + supports seeking {offset} can be used. Otherwise it should be + zero. E.g. to read 10 bytes from a serial console: >vim + echo readblob('/dev/ttyS0', 0, 10) +< When the file can't be opened an error message is given and the result is an empty |Blob|. + When the offset is beyond the end of the file the result is an + empty blob. + When trying to read more bytes than are available the result + is truncated. Also see |readfile()| and |writefile()|. - - *readdir()* -readdir({directory} [, {expr}]) +readdir({directory} [, {expr}]) *readdir()* Return a list with file and directory names in {directory}. You can also use |glob()| if you don't need to do complicated things, such as limiting the number of matches. @@ -6104,27 +5550,22 @@ readdir({directory} [, {expr}]) to the list. Each time {expr} is evaluated |v:val| is set to the entry name. When {expr} is a function the name is passed as the argument. - For example, to get a list of files ending in ".txt": > - readdir(dirname, {n -> n =~ '.txt$'}) -< To skip hidden and backup files: > - readdir(dirname, {n -> n !~ '^\.\|\~$'}) - -< If you want to get a directory tree: > - function! s:tree(dir) - return {a:dir : map(readdir(a:dir), + For example, to get a list of files ending in ".txt": >vim + echo readdir(dirname, {n -> n =~ '.txt$'}) +< To skip hidden and backup files: >vim + echo readdir(dirname, {n -> n !~ '^\.\|\~$'}) + +< If you want to get a directory tree: >vim + function! s:tree(dir) + return {a:dir : map(readdir(a:dir), \ {_, x -> isdirectory(x) ? \ {x : s:tree(a:dir .. '/' .. x)} : x})} - endfunction - echo s:tree(".") + endfunction + echo s:tree(".") < Returns an empty List on error. - Can also be used as a |method|: > - GetDirName()->readdir() -< - - *readfile()* -readfile({fname} [, {type} [, {max}]]) +readfile({fname} [, {type} [, {max}]]) *readfile()* Read file {fname} and return a |List|, each line of the file as an item. Lines are broken at NL characters. Macintosh files separated with CR will result in a single long line @@ -6140,10 +5581,10 @@ readfile({fname} [, {type} [, {max}]]) - Any UTF-8 byte order mark is removed from the text. When {max} is given this specifies the maximum number of lines to be read. Useful if you only want to check the first ten - lines of a file: > - :for line in readfile(fname, '', 10) - : if line =~ 'Date' | echo line | endif - :endfor + lines of a file: >vim + for line in readfile(fname, '', 10) + if line =~ 'Date' | echo line | endif + endfor < When {max} is negative -{max} lines from the end of the file are returned, or as many as there are. When {max} is zero the result is an empty list. @@ -6157,45 +5598,41 @@ readfile({fname} [, {type} [, {max}]]) the result is an empty list. Also see |writefile()|. - Can also be used as a |method|: > - GetFileName()->readfile() - -reduce({object}, {func} [, {initial}]) *reduce()* *E998* +reduce({object}, {func} [, {initial}]) *reduce()* *E998* {func} is called for every item in {object}, which can be a - |List| or a |Blob|. {func} is called with two arguments: the - result so far and current item. After processing all items - the result is returned. + |String|, |List| or a |Blob|. {func} is called with two + arguments: the result so far and current item. After + processing all items the result is returned. {initial} is the initial result. When omitted, the first item in {object} is used and {func} is first called for the second item. If {initial} is not given and {object} is empty no result can be computed, an E998 error is given. - Examples: > + Examples: >vim echo reduce([1, 3, 5], { acc, val -> acc + val }) echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a') echo reduce(0z1122, { acc, val -> 2 * acc + val }) + echo reduce('xyz', { acc, val -> acc .. ',' .. val }) < - Can also be used as a |method|: > - echo mylist->reduce({ acc, val -> acc + val }, 0) -reg_executing() *reg_executing()* +reg_executing() *reg_executing()* Returns the single letter name of the register being executed. Returns an empty string when no register is being executed. See |@|. -reg_recorded() *reg_recorded()* +reg_recorded() *reg_recorded()* Returns the single letter name of the last recorded register. Returns an empty string when nothing was recorded yet. See |q| and |Q|. -reg_recording() *reg_recording()* +reg_recording() *reg_recording()* Returns the single letter name of the register being recorded. Returns an empty string when not recording. See |q|. reltime() reltime({start}) -reltime({start}, {end}) *reltime()* +reltime({start}, {end}) *reltime()* Return an item that represents a time value. The item is a list with items that depend on the system. The item can be passed to |reltimestr()| to convert it to a @@ -6213,12 +5650,9 @@ reltime({start}, {end}) *reltime()* The {start} and {end} arguments must be values returned by reltime(). Returns zero on error. - Can also be used as a |method|: > - GetStart()->reltime() -< Note: |localtime()| returns the current (non-relative) time. -reltimefloat({time}) *reltimefloat()* +reltimefloat({time}) *reltimefloat()* Return a Float that represents the time value of {time}. Unit of time is seconds. Example: @@ -6229,28 +5663,22 @@ 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()* +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 - microseconds. Example: > + microseconds. Example: >vim let start = reltime() call MyFunction() echo reltimestr(reltime(start)) < Note that overhead for the commands will be added to the time. Leading spaces are used to make the string align nicely. You - can use split() to remove it. > + can use split() to remove it. >vim echo split(reltimestr(reltime(start)))[0] < Also see |profiling|. If there is an error an empty string is returned - Can also be used as a |method|: > - reltime(start)->reltimestr() -< remove({list}, {idx}) -remove({list}, {idx}, {end}) *remove()* +remove({list}, {idx}, {end}) *remove()* Without {end}: Remove the item at {idx} from |List| {list} and return the item. With {end}: Remove items from {idx} to {end} (inclusive) and @@ -6259,15 +5687,12 @@ remove({list}, {idx}, {end}) *remove()* points to an item before {idx} this is an error. See |list-index| for possible values of {idx} and {end}. Returns zero on error. - Example: > - :echo "last item: " .. remove(mylist, -1) - :call remove(mylist, 0, 9) + Example: >vim + echo "last item: " .. remove(mylist, -1) + call remove(mylist, 0, 9) < Use |delete()| to remove a file. - Can also be used as a |method|: > - mylist->remove(idx) - remove({blob}, {idx}) remove({blob}, {idx}, {end}) Without {end}: Remove the byte at {idx} from |Blob| {blob} and @@ -6277,18 +5702,19 @@ remove({blob}, {idx}, {end}) byte as {end} a |Blob| with one byte is returned. When {end} points to a byte before {idx} this is an error. Returns zero on error. - Example: > - :echo "last byte: " .. remove(myblob, -1) - :call remove(mylist, 0, 9) + Example: >vim + echo "last byte: " .. remove(myblob, -1) + call remove(mylist, 0, 9) +< remove({dict}, {key}) Remove the entry from {dict} with key {key} and return it. - Example: > - :echo "removed " .. remove(dict, "one") + Example: >vim + echo "removed " .. remove(dict, "one") < If there is no {key} in {dict} this is an error. Returns zero on error. -rename({from}, {to}) *rename()* +rename({from}, {to}) *rename()* Rename the file by the name {from} to the name {to}. This should also work to move files across file systems. The result is a Number, which is 0 if the file was renamed @@ -6296,23 +5722,17 @@ 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}) *repeat()* Repeat {expr} {count} times and return the concatenated - result. Example: > - :let separator = repeat('-', 80) + result. Example: >vim + let separator = repeat('-', 80) < When {count} is zero or negative the result is empty. - When {expr} is a |List| the result is {expr} concatenated - {count} times. Example: > - :let longlist = repeat(['a', 'b'], 3) + When {expr} is a |List| or a |Blob| the result is {expr} + concatenated {count} times. Example: >vim + let longlist = repeat(['a', 'b'], 3) < Results in ['a', 'b', 'a', 'b', 'a', 'b']. - Can also be used as a |method|: > - mylist->repeat(count) - -resolve({filename}) *resolve()* *E655* +resolve({filename}) *resolve()* *E655* On MS-Windows, when {filename} is a shortcut (a .lnk file), returns the path the shortcut points to in a simplified form. On Unix, repeat resolving symbolic links in all path @@ -6325,56 +5745,53 @@ 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. - {object} can be a |List| or a |Blob|. - Returns {object}. - Returns zero if {object} is not a List or a Blob. - If you want an object to remain unmodified make a copy first: > - :let revlist = reverse(copy(mylist)) -< Can also be used as a |method|: > - mylist->reverse() - -round({expr}) *round()* +reverse({object}) *reverse()* + Reverse the order of items in {object}. {object} can be a + |List|, a |Blob| or a |String|. For a List and a Blob the + items are reversed in-place and {object} is returned. + For a String a new String is returned. + Returns zero if {object} is not a List, Blob or a String. + If you want a List or Blob to remain unmodified make a copy + first: >vim + let revlist = reverse(copy(mylist)) +< + +round({expr}) *round()* Round off {expr} to the nearest integral value and return it as a |Float|. If {expr} lies halfway between two integral values, then use the larger one (away from zero). {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > + Examples: >vim echo round(0.456) -< 0.0 > +< 0.0 >vim echo round(4.5) -< 5.0 > +< 5.0 >vim echo round(-4.5) < -5.0 - Can also be used as a |method|: > - Compute()->round() - -rpcnotify({channel}, {event} [, {args}...]) *rpcnotify()* +rpcnotify({channel}, {event} [, {args}...]) *rpcnotify()* Sends {event} to {channel} via |RPC| and returns immediately. If {channel} is 0, the event is broadcast to all channels. - Example: > - :au VimLeave call rpcnotify(0, "leaving") + Example: >vim + au VimLeave call rpcnotify(0, "leaving") +< -rpcrequest({channel}, {method} [, {args}...]) *rpcrequest()* +rpcrequest({channel}, {method} [, {args}...]) *rpcrequest()* Sends a request to {channel} to invoke {method} via |RPC| and blocks until a response is received. - Example: > - :let result = rpcrequest(rpc_chan, "func", 1, 2, 3) + Example: >vim + let result = rpcrequest(rpc_chan, "func", 1, 2, 3) +< -rpcstart({prog} [, {argv}]) *rpcstart()* - Deprecated. Replace > - :let id = rpcstart('prog', ['arg1', 'arg2']) -< with > - :let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true}) +rpcstart({prog} [, {argv}]) *rpcstart()* + Deprecated. Replace >vim + let id = rpcstart('prog', ['arg1', 'arg2']) +< with >vim + let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true}) +< -rubyeval({expr}) *rubyeval()* +rubyeval({expr}) *rubyeval()* Evaluate Ruby expression {expr} and return its result converted to Vim data structures. Numbers, floats and strings are returned as they are (strings @@ -6384,19 +5801,13 @@ 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()* +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 attribute at other positions. Returns -1 when row or col is out of range. - Can also be used as a |method|: > - GetRow()->screenattr(col) - -screenchar({row}, {col}) *screenchar()* +screenchar({row}, {col}) *screenchar()* The result is a Number, which is the character at position [row, col] on the screen. This works for every possible screen position, also status lines, window separators and the @@ -6406,20 +5817,14 @@ screenchar({row}, {col}) *screenchar()* This is mainly to be used for testing. Returns -1 when row or col is out of range. - Can also be used as a |method|: > - GetRow()->screenchar(col) - -screenchars({row}, {col}) *screenchars()* - The result is a List of Numbers. The first number is the same +screenchars({row}, {col}) *screenchars()* + The result is a |List| of Numbers. The first number is the same as what |screenchar()| returns. Further numbers are composing characters on top of the base character. This is mainly to be used for testing. Returns an empty List when row or col is out of range. - Can also be used as a |method|: > - GetRow()->screenchars(col) - -screencol() *screencol()* +screencol() *screencol()* The result is a Number, which is the current screen column of the cursor. The leftmost column has number 1. This function is mainly used for testing. @@ -6428,12 +5833,13 @@ screencol() *screencol()* in a command (e.g. ":echo screencol()") it will return the column inside the command line, which is 1 when the command is executed. To get the cursor position in the file use one of - the following mappings: > + the following mappings: >vim nnoremap <expr> GG ":echom " .. screencol() .. "\n" nnoremap <silent> GG :echom screencol()<CR> noremap GG <Cmd>echom screencol()<Cr> < -screenpos({winid}, {lnum}, {col}) *screenpos()* + +screenpos({winid}, {lnum}, {col}) *screenpos()* The result is a Dict with the screen position of the text character in window {winid} at buffer line {lnum} and column {col}. {col} is a one-based byte index. @@ -6453,12 +5859,11 @@ screenpos({winid}, {lnum}, {col}) *screenpos()* as if 'conceallevel' is zero. You can set the cursor to the right position and use |screencol()| to get the value with |conceal| taken into account. + If the position is in a closed fold the screen position of the + first character is returned, {col} is not used. Returns an empty Dict if {winid} is invalid. - Can also be used as a |method|: > - GetWinid()->screenpos(lnum, col) - -screenrow() *screenrow()* +screenrow() *screenrow()* The result is a Number, which is the current screen row of the cursor. The top line has number one. This function is mainly used for testing. @@ -6466,7 +5871,7 @@ screenrow() *screenrow()* Note: Same restrictions as with |screencol()|. -screenstring({row}, {col}) *screenstring()* +screenstring({row}, {col}) *screenstring()* The result is a String that contains the base character and any composing characters at position [row, col] on the screen. This is like |screenchars()| but returning a String with the @@ -6474,11 +5879,7 @@ screenstring({row}, {col}) *screenstring()* This is mainly to be used for testing. Returns an empty String when row or col is out of range. - Can also be used as a |method|: > - GetRow()->screenstring(col) -< - *search()* -search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) +search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) *search()* Search for regexp pattern {pattern}. The search starts at the cursor position (you can use |cursor()| to set it). @@ -6519,7 +5920,7 @@ search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) When the {stopline} argument is given then the search stops after searching this line. This is useful to restrict the - search to a range of lines. Examples: > + search to a range of lines. Examples: >vim let match = search('(', 'b', line("w0")) let end = search('END', '', line("w$")) < When {stopline} is used and it is not zero this also implies @@ -6550,24 +5951,24 @@ search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) The cursor will be positioned at the match, unless the 'n' flag is used. - Example (goes over all files in the argument list): > - :let n = 1 - :while n <= argc() " loop over all files in arglist - : exe "argument " .. n - : " start at the last char in the file and wrap for the - : " first search to find match at start of file - : normal G$ - : let flags = "w" - : while search("foo", flags) > 0 - : s/foo/bar/g - : let flags = "W" - : endwhile - : update " write the file if modified - : let n = n + 1 - :endwhile -< - Example for using some flags: > - :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe') + Example (goes over all files in the argument list): >vim + let n = 1 + while n <= argc() " loop over all files in arglist + exe "argument " .. n + " start at the last char in the file and wrap for the + " first search to find match at start of file + normal G$ + let flags = "w" + while search("foo", flags) > 0 + s/foo/bar/g + let flags = "W" + endwhile + update " write the file if modified + let n = n + 1 + endwhile +< + Example for using some flags: >vim + echo search('\<if\|\(else\)\|\(endif\)', 'ncpe') < This will search for the keywords "if", "else", and "endif" under or after the cursor. Because of the 'p' flag, it returns 1, 2, or 3 depending on which keyword is found, or 0 @@ -6579,15 +5980,12 @@ search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) without the 'e' flag if the cursor is on the "f" of "if". The 'n' flag tells the function not to move the cursor. - Can also be used as a |method|: > - GetPattern()->search() - -searchcount([{options}]) *searchcount()* +searchcount([{options}]) *searchcount()* Get or update the last search count, like what is displayed without the "S" flag in 'shortmess'. This works even if 'shortmess' does contain the "S" flag. - This returns a Dictionary. The dictionary is empty if the + This returns a |Dictionary|. The dictionary is empty if the previous pattern was not set and "pattern" was not specified. key type meaning ~ @@ -6607,7 +6005,7 @@ searchcount([{options}]) *searchcount()* this function with `recompute: 0` . This sometimes returns wrong information because |n| and |N|'s maximum count is 99. If it exceeded 99 the result must be max count + 1 (100). If - you want to get correct information, specify `recompute: 1`: > + you want to get correct information, specify `recompute: 1`: >vim " result == maxcount + 1 (100) when many matches let result = searchcount(#{recompute: 0}) @@ -6616,7 +6014,7 @@ searchcount([{options}]) *searchcount()* " to 1) let result = searchcount() < - The function is useful to add the count to 'statusline': > + The function is useful to add the count to 'statusline': >vim function! LastSearchCount() abort let result = searchcount(#{recompute: 0}) if empty(result) @@ -6645,7 +6043,7 @@ searchcount([{options}]) *searchcount()* " \ '%{v:hlsearch ? LastSearchCount() : ""}' < You can also update the search count, which can be useful in a - |CursorMoved| or |CursorMovedI| autocommand: > + |CursorMoved| or |CursorMovedI| autocommand: >vim autocmd CursorMoved,CursorMovedI * \ let s:searchcount_timer = timer_start( @@ -6659,7 +6057,7 @@ searchcount([{options}]) *searchcount()* endfunction < This can also be used to count matched texts with specified - pattern in the current buffer using "pattern": > + pattern in the current buffer using "pattern": >vim " Count '\<foo\>' in this buffer " (Note that it also updates search count) @@ -6669,7 +6067,7 @@ searchcount([{options}]) *searchcount()* " search again call searchcount() < - {options} must be a Dictionary. It can contain: + {options} must be a |Dictionary|. It can contain: key type meaning ~ recompute |Boolean| if |TRUE|, recompute the count like |n| or |N| was executed. @@ -6683,7 +6081,7 @@ searchcount([{options}]) *searchcount()* and different with |@/|. this works as same as the below command is executed - before calling this function > + before calling this function >vim let @/ = pattern < (default: |@/|) timeout |Number| 0 or negative number is no @@ -6703,10 +6101,7 @@ searchcount([{options}]) *searchcount()* value. see |cursor()|, |getpos()| (default: cursor's position) - Can also be used as a |method|: > - GetSearchOpts()->searchcount() -< -searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()* +searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()* Search for the declaration of {name}. With a non-zero {global} argument it works like |gD|, find @@ -6719,17 +6114,14 @@ searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()* Moves the cursor to the found match. Returns zero for success, non-zero for failure. - Example: > + Example: >vim if searchdecl('myvar') == 0 echo getline('.') endif < - Can also be used as a |method|: > - GetName()->searchdecl() -< - *searchpair()* -searchpair({start}, {middle}, {end} [, {flags} [, {skip} - [, {stopline} [, {timeout}]]]]) + + *searchpair()* +searchpair({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline} [, {timeout}]]]]) Search for the match of a nested start-end pair. This can be used to find the "endif" that matches an "if", while other if/endif pairs in between are ignored. @@ -6744,8 +6136,8 @@ searchpair({start}, {middle}, {end} [, {flags} [, {skip} must not contain \( \) pairs. Use of \%( \) is allowed. When {middle} is not empty, it is found when searching from either direction, but only when not in a nested start-end pair. A - typical use is: > - searchpair('\<if\>', '\<else\>', '\<endif\>') + typical use is: >vim + echo searchpair('\<if\>', '\<else\>', '\<endif\>') < By leaving {middle} empty the "else" is skipped. {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with @@ -6775,7 +6167,7 @@ searchpair({start}, {middle}, {end} [, {flags} [, {skip} The search starts exactly at the cursor. A match with {start}, {middle} or {end} at the next character, in the - direction of searching, is the first one found. Example: > + direction of searching, is the first one found. Example: >vim if 1 if 2 endif 2 @@ -6791,9 +6183,9 @@ searchpair({start}, {middle}, {end} [, {flags} [, {skip} that when the cursor is inside a match with the end it finds the matching start. - Example, to find the "endif" command in a Vim script: > + Example, to find the "endif" command in a Vim script: >vim - :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W', + echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W', \ 'getline(".") =~ "^\\s*\""') < The cursor must be at or after the "if" for which a match is @@ -6802,56 +6194,54 @@ searchpair({start}, {middle}, {end} [, {flags} [, {skip} catches comments at the start of a line, not after a command. Also, a word "en" or "if" halfway through a line is considered a match. - Another example, to search for the matching "{" of a "}": > + Another example, to search for the matching "{" of a "}": >vim - :echo searchpair('{', '', '}', 'bW') + echo searchpair('{', '', '}', 'bW') < This works when the cursor is at or before the "}" for which a match is to be found. To reject matches that syntax - highlighting recognized as strings: > + highlighting recognized as strings: >vim - :echo searchpair('{', '', '}', 'bW', - \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"') + echo searchpair('{', '', '}', 'bW', + \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"') < - *searchpairpos()* -searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} - [, {stopline} [, {timeout}]]]]) + + *searchpairpos()* +searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline} [, {timeout}]]]]) Same as |searchpair()|, but returns a |List| with the line and column position of the match. The first element of the |List| is the line number and the second element is the byte index of the column position of the match. If no match is found, - returns [0, 0]. > + returns [0, 0]. >vim - :let [lnum,col] = searchpairpos('{', '', '}', 'n') + let [lnum,col] = searchpairpos('{', '', '}', 'n') < See |match-parens| for a bigger and more useful example. - *searchpos()* + *searchpos()* searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) Same as |search()|, but returns a |List| with the line and column position of the match. The first element of the |List| is the line number and the second element is the byte index of the column position of the match. If no match is found, returns [0, 0]. - Example: > - :let [lnum, col] = searchpos('mypattern', 'n') + Example: >vim + let [lnum, col] = searchpos('mypattern', 'n') < When the 'p' flag is given then there is an extra item with - the sub-pattern match number |search()-sub-match|. Example: > - :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np') + the sub-pattern match number |search()-sub-match|. Example: >vim + let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np') < In this example "submatch" is 2 when a lowercase letter is found |/\l|, 3 when an uppercase letter is found |/\u|. - Can also be used as a |method|: > - GetPattern()->searchpos() - -serverlist() *serverlist()* +serverlist() *serverlist()* Returns a list of server addresses, or empty if all servers were stopped. |serverstart()| |serverstop()| - Example: > - :echo serverlist() + Example: >vim + echo serverlist() +< -serverstart([{address}]) *serverstart()* +serverstart([{address}]) *serverstart()* Opens a socket or named pipe at {address} and listens for |RPC| messages. Clients can send |API| commands to the returned address to control Nvim. @@ -6864,32 +6254,34 @@ serverstart([{address}]) *serverstart()* assigns a random port). - Else {address} is the path to a named pipe (except on Windows). - If {address} has no slashes ("/") it is treated as the - "name" part of a generated path in this format: > + "name" part of a generated path in this format: >vim stdpath("run").."/{name}.{pid}.{counter}" -< - If {address} is omitted the name is "nvim". > - :echo serverstart() +< - If {address} is omitted the name is "nvim". >vim + echo serverstart() +< > => /tmp/nvim.bram/oknANW/nvim.15430.5 - -< Example bash command to list all Nvim servers: > +< + Example bash command to list all Nvim servers: >bash ls ${XDG_RUNTIME_DIR:-${TMPDIR}nvim.${USER}}/*/nvim.*.0 -< Example named pipe: > +< Example named pipe: >vim if has('win32') echo serverstart('\\.\pipe\nvim-pipe-1234') else echo serverstart('nvim.sock') endif < - Example TCP/IP address: > + Example TCP/IP address: >vim echo serverstart('::1:12345') +< -serverstop({address}) *serverstop()* +serverstop({address}) *serverstop()* Closes the pipe or socket at {address}. Returns TRUE if {address} is valid, else FALSE. If |v:servername| is stopped it is set to the next available address in |serverlist()|. -setbufline({buf}, {lnum}, {text}) *setbufline()* +setbufline({buf}, {lnum}, {text}) *setbufline()* Set line {lnum} to {text} in buffer {buf}. This works like |setline()| for the specified buffer. @@ -6898,9 +6290,10 @@ setbufline({buf}, {lnum}, {text}) *setbufline()* To insert lines use |appendbufline()|. - {text} can be a string to set one line, or a list of strings - to set multiple lines. If the list extends below the last - line then those lines are added. + {text} can be a string to set one line, or a List of strings + to set multiple lines. If the List extends below the last + line then those lines are added. If the List is empty then + nothing is changed and zero is returned. For the use of {buf}, see |bufname()| above. @@ -6913,11 +6306,7 @@ setbufline({buf}, {lnum}, {text}) *setbufline()* If {buf} is not a valid buffer or {lnum} is not valid, an error message is given. - Can also be used as a |method|, the base is passed as the - third argument: > - GetText()->setbufline(buf, lnum) - -setbufvar({buf}, {varname}, {val}) *setbufvar()* +setbufvar({buf}, {varname}, {val}) *setbufvar()* Set option or local variable {varname} in buffer {buf} to {val}. This also works for a global or local window option, but it @@ -6926,21 +6315,16 @@ setbufvar({buf}, {varname}, {val}) *setbufvar()* For the use of {buf}, see |bufname()| above. The {varname} argument is a string. Note that the variable name without "b:" must be used. - Examples: > - :call setbufvar(1, "&mod", 1) - :call setbufvar("todo", "myvar", "foobar") + Examples: >vim + call setbufvar(1, "&mod", 1) + call setbufvar("todo", "myvar", "foobar") < This function is not available in the |sandbox|. - Can also be used as a |method|, the base is passed as the - third argument: > - GetValue()->setbufvar(buf, varname) - - -setcellwidths({list}) *setcellwidths()* +setcellwidths({list}) *setcellwidths()* Specify overrides for cell widths of character ranges. This tells Vim how wide characters are when displayed in the terminal, counted in screen cells. The values override - 'ambiwidth'. Example: > + 'ambiwidth'. Example: >vim call setcellwidths([ \ [0x111, 0x111, 1], \ [0x2194, 0x2199, 2], @@ -6956,12 +6340,12 @@ setcellwidths({list}) *setcellwidths()* {width} must be either 1 or 2, indicating the character width in screen cells. *E1112* An error is given if the argument is invalid, also when a - range overlaps with another. *E1113* + range overlaps with another. *E1113* If the new value causes 'fillchars' or 'listchars' to become invalid it is rejected and an error is given. - To clear the overrides pass an empty {list}: > + To clear the overrides pass an empty {list}: >vim call setcellwidths([]) < You can use the script $VIMRUNTIME/tools/emoji_list.vim to see @@ -6970,22 +6354,18 @@ setcellwidths({list}) *setcellwidths()* match with what Vim knows about each emoji. If it doesn't look right you need to adjust the {list} argument. - -setcharpos({expr}, {list}) *setcharpos()* +setcharpos({expr}, {list}) *setcharpos()* Same as |setpos()| but uses the specified column number as the character index instead of the byte index in the line. Example: - With the text "여보세요" in line 8: > + With the text "여보세요" in line 8: >vim call setcharpos('.', [0, 8, 4, 0]) -< positions the cursor on the fourth character '요'. > +< positions the cursor on the fourth character '요'. >vim call setpos('.', [0, 8, 4, 0]) < positions the cursor on the second character '보'. - Can also be used as a |method|: > - GetPosition()->setcharpos('.') - -setcharsearch({dict}) *setcharsearch()* +setcharsearch({dict}) *setcharsearch()* Set the current character search information to {dict}, which contains one or more of the following entries: @@ -6999,26 +6379,20 @@ setcharsearch({dict}) *setcharsearch()* character search This can be useful to save/restore a user's character search - from a script: > - :let prevsearch = getcharsearch() - :" Perform a command which clobbers user's search - :call setcharsearch(prevsearch) + from a script: >vim + let prevsearch = getcharsearch() + " Perform a command which clobbers user's search + call setcharsearch(prevsearch) < Also see |getcharsearch()|. - Can also be used as a |method|: > - SavedSearch()->setcharsearch() - -setcmdline({str} [, {pos}]) *setcmdline()* +setcmdline({str} [, {pos}]) *setcmdline()* Set the command line to {str} and set the cursor position to {pos}. If {pos} is omitted, the cursor is positioned after the text. Returns 0 when successful, 1 when not editing the command line. - Can also be used as a |method|: > - GetText()->setcmdline() - -setcmdpos({pos}) *setcmdpos()* +setcmdpos({pos}) *setcmdpos()* Set the cursor position in the command line to byte position {pos}. The first position is 1. Use |getcmdpos()| to obtain the current position. @@ -7033,36 +6407,26 @@ setcmdpos({pos}) *setcmdpos()* Returns 0 when successful, 1 when not editing the command line. - Can also be used as a |method|: > - GetPos()->setcmdpos() - -setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()* -setcursorcharpos({list}) +setcursorcharpos({lnum}, {col} [, {off}]) +setcursorcharpos({list}) *setcursorcharpos()* Same as |cursor()| but uses the specified column number as the character index instead of the byte index in the line. Example: - With the text "여보세요" in line 4: > + With the text "여보세요" in line 4: >vim call setcursorcharpos(4, 3) -< positions the cursor on the third character '세'. > +< positions the cursor on the third character '세'. >vim call cursor(4, 3) < positions the cursor on the first character '여'. - Can also be used as a |method|: > - GetCursorPos()->setcursorcharpos() - -setenv({name}, {val}) *setenv()* - Set environment variable {name} to {val}. Example: > +setenv({name}, {val}) *setenv()* + Set environment variable {name} to {val}. Example: >vim call setenv('HOME', '/home/myhome') < When {val} is |v:null| the environment variable is deleted. See also |expr-env|. - Can also be used as a |method|, the base is passed as the - second argument: > - GetPath()->setenv('PATH') - -setfperm({fname}, {mode}) *setfperm()* *chmod* +setfperm({fname}, {mode}) *setfperm()* *chmod* Set the file permissions for {fname} to {mode}. {mode} must be a string with 9 characters. It is of the form "rwxrwxrwx", where each group of "rwx" flags represent, in @@ -7077,12 +6441,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()* +setline({lnum}, {text}) *setline()* Set line {lnum} of the current buffer to {text}. To insert lines use |append()|. To set lines in another buffer use |setbufline()|. @@ -7091,29 +6452,26 @@ setline({lnum}, {text}) *setline()* When {lnum} is just below the last line the {text} will be added below the last line. {text} can be any type or a List of any type, each item is - converted to a String. + converted to a String. When {text} is an empty List then + nothing is changed and FALSE is returned. If this succeeds, FALSE is returned. If this fails (most likely because {lnum} is invalid) TRUE is returned. - Example: > - :call setline(5, strftime("%c")) + Example: >vim + call setline(5, strftime("%c")) < When {text} is a |List| then line {lnum} and following lines - will be set to the items in the list. Example: > - :call setline(5, ['aaa', 'bbb', 'ccc']) -< This is equivalent to: > - :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']] - : call setline(n, l) - :endfor + will be set to the items in the list. Example: >vim + call setline(5, ['aaa', 'bbb', 'ccc']) +< This is equivalent to: >vim + for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']] + call setline(n, l) + endfor < Note: The '[ and '] marks are not set. - Can also be used as a |method|, the base is passed as the - second argument: > - GetText()->setline(lnum) - -setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()* +setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()* Create or replace or add to the location list for window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is zero the current window is used. @@ -7129,11 +6487,7 @@ setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()* only the items listed in {what} are set. Refer to |setqflist()| for the list of supported keys in {what}. - Can also be used as a |method|, the base is passed as the - second argument: > - GetLoclist()->setloclist(winnr) - -setmatches({list} [, {win}]) *setmatches()* +setmatches({list} [, {win}]) *setmatches()* Restores a list of matches saved by |getmatches()| for the current window. Returns 0 if successful, otherwise -1. All current matches are cleared before the list is restored. See @@ -7141,11 +6495,7 @@ setmatches({list} [, {win}]) *setmatches()* 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|: > - GetMatches()->setmatches() -< - *setpos()* -setpos({expr}, {list}) +setpos({expr}, {list}) *setpos()* Set the position for String {expr}. Possible values: . the cursor 'x mark x @@ -7194,10 +6544,7 @@ setpos({expr}, {list}) also set the preferred column. Also see the "curswant" key in |winrestview()|. - Can also be used as a |method|: > - GetPosition()->setpos('.') - -setqflist({list} [, {action} [, {what}]]) *setqflist()* +setqflist({list} [, {action} [, {what}]]) *setqflist()* Create or replace or add to the quickfix list. If the optional {what} dictionary argument is supplied, then @@ -7227,6 +6574,9 @@ setqflist({list} [, {action} [, {what}]]) *setqflist()* text description of the error type single-character error type, 'E', 'W', etc. valid recognized error message + user_data + custom data associated with the item, can be + any type. The "col", "vcol", "nr", "type" and "text" entries are optional. Either "lnum" or "pattern" entry can be used to @@ -7250,8 +6600,8 @@ setqflist({list} [, {action} [, {what}]]) *setqflist()* 'r' The items from the current quickfix list are replaced with the items from {list}. This can also be used to - clear the list: > - :call setqflist([], 'r') + clear the list: >vim + call setqflist([], 'r') < 'f' All the quickfix lists in the quickfix stack are freed. @@ -7297,10 +6647,10 @@ setqflist({list} [, {action} [, {what}]]) *setqflist()* list is modified, "id" should be used instead of "nr" to specify the list. - Examples (See also |setqflist-examples|): > - :call setqflist([], 'r', {'title': 'My search'}) - :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'}) - :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]}) + Examples (See also |setqflist-examples|): >vim + call setqflist([], 'r', {'title': 'My search'}) + call setqflist([], 'r', {'nr': 2, 'title': 'Errors'}) + call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]}) < Returns zero for success, -1 for failure. @@ -7308,12 +6658,7 @@ setqflist({list} [, {action} [, {what}]]) *setqflist()* independent of the 'errorformat' setting. Use a command like `:cc 1` to jump to the first position. - Can also be used as a |method|, the base is passed as the - second argument: > - GetErrorlist()->setqflist() -< - *setreg()* -setreg({regname}, {value} [, {options}]) +setreg({regname}, {value} [, {options}]) *setreg()* Set the register {regname} to {value}. If {regname} is "" or "@", the unnamed register '"' is used. The {regname} argument is a string. @@ -7345,35 +6690,31 @@ setreg({regname}, {value} [, {options}]) set search and expression registers. Lists containing no items act like empty strings. - Examples: > - :call setreg(v:register, @*) - :call setreg('*', @%, 'ac') - :call setreg('a', "1\n2\n3", 'b5') - :call setreg('"', { 'points_to': 'a'}) + Examples: >vim + 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') - .... - :call setreg('a', var_a, var_amode) + register: >vim + let var_a = getreginfo() + call setreg('a', var_a) +< or: >vim + let var_a = getreg('a', 1, 1) + let var_amode = getregtype('a') + " .... + call setreg('a', var_a, var_amode) < Note: you may not reliably restore register value without using the third argument to |getreg()| as without it newlines are represented as newlines AND Nul bytes are represented as newlines as well, see |NL-used-for-Nul|. You can also change the type of a register by appending - nothing: > - :call setreg('a', '', 'al') - -< Can also be used as a |method|, the base is passed as the - second argument: > - GetText()->setreg('a') + nothing: >vim + call setreg('a', '', 'al') -settabvar({tabnr}, {varname}, {val}) *settabvar()* +settabvar({tabnr}, {varname}, {val}) *settabvar()* Set tab-local variable {varname} to {val} in tab page {tabnr}. |t:var| The {varname} argument is a string. @@ -7381,11 +6722,7 @@ settabvar({tabnr}, {varname}, {val}) *settabvar()* Tabs are numbered starting with one. This function is not available in the |sandbox|. - Can also be used as a |method|, the base is passed as the - third argument: > - GetValue()->settabvar(tab, name) - -settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* +settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* Set option or local variable {varname} in window {winnr} to {val}. Tabs are numbered starting with one. For the current tabpage @@ -7396,16 +6733,12 @@ settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* doesn't work for a global or local buffer variable. For a local buffer option the global value is unchanged. Note that the variable name without "w:" must be used. - Examples: > - :call settabwinvar(1, 1, "&list", 0) - :call settabwinvar(3, 2, "myvar", "foobar") + Examples: >vim + call settabwinvar(1, 1, "&list", 0) + call settabwinvar(3, 2, "myvar", "foobar") < This function is not available in the |sandbox|. - Can also be used as a |method|, the base is passed as the - fourth argument: > - GetValue()->settabwinvar(tab, winnr, name) - -settagstack({nr}, {dict} [, {action}]) *settagstack()* +settagstack({nr}, {dict} [, {action}]) *settagstack()* Modify the tag stack of the window {nr} using {dict}. {nr} can be the window number or the |window-ID|. @@ -7429,37 +6762,27 @@ settagstack({nr}, {dict} [, {action}]) *settagstack()* Returns zero for success, -1 for failure. Examples (for more examples see |tagstack-examples|): - Empty the tag stack of window 3: > + Empty the tag stack of window 3: >vim call settagstack(3, {'items' : []}) -< Save and restore the tag stack: > +< Save and restore the tag stack: >vim let stack = gettagstack(1003) " do something else call settagstack(1003, stack) unlet stack < - Can also be used as a |method|, the base is passed as the - second argument: > - GetStack()->settagstack(winnr) -setwinvar({nr}, {varname}, {val}) *setwinvar()* +setwinvar({nr}, {varname}, {val}) *setwinvar()* Like |settabwinvar()| for the current tab page. - Examples: > - :call setwinvar(1, "&list", 0) - :call setwinvar(2, "myvar", "foobar") + Examples: >vim + call setwinvar(1, "&list", 0) + call setwinvar(2, "myvar", "foobar") -< Can also be used as a |method|, the base is passed as the - third argument: > - GetValue()->setwinvar(winnr, name) - -sha256({string}) *sha256()* +sha256({string}) *sha256()* Returns a String with 64 hex characters, which is the SHA256 checksum of {string}. - Can also be used as a |method|: > - GetText()->sha256() - -shellescape({string} [, {special}]) *shellescape()* +shellescape({string} [, {special}]) *shellescape()* Escape {string} for use as a shell command argument. On Windows when 'shellslash' is not set, encloses {string} in @@ -7483,21 +6806,18 @@ shellescape({string} [, {special}]) *shellescape()* be escaped because in fish it is used as an escape character inside single quotes. - Example of use with a |:!| command: > - :exe '!dir ' .. shellescape(expand('<cfile>'), 1) + Example of use with a |:!| command: >vim + exe '!dir ' .. shellescape(expand('<cfile>'), 1) < This results in a directory listing for the file under the - cursor. Example of use with |system()|: > - :call system("chmod +w -- " .. shellescape(expand("%"))) + cursor. Example of use with |system()|: >vim + call system("chmod +w -- " .. shellescape(expand("%"))) < See also |::S|. - Can also be used as a |method|: > - GetCommand()->shellescape() - -shiftwidth([{col}]) *shiftwidth()* +shiftwidth([{col}]) *shiftwidth()* Returns the effective value of 'shiftwidth'. This is the 'shiftwidth' value unless it is zero, in which case it is the 'tabstop' value. To be backwards compatible in indent - plugins, use this: > + plugins, use this: >vim if exists('*shiftwidth') func s:sw() return shiftwidth() @@ -7514,12 +6834,370 @@ shiftwidth([{col}]) *shiftwidth()* 'vartabstop' feature. If no {col} argument is given, column 1 will be assumed. - Can also be used as a |method|: > - GetColumn()->shiftwidth() +sign_define({name} [, {dict}]) +sign_define({list}) *sign_define()* + Define a new sign named {name} or modify the attributes of an + existing sign. This is similar to the |:sign-define| command. + + Prefix {name} with a unique text to avoid name collisions. + There is no {group} like with placing signs. + + The {name} can be a String or a Number. The optional {dict} + argument specifies the sign attributes. The following values + are supported: + icon full path to the bitmap file for the sign. + linehl highlight group used for the whole line the + sign is placed in. + numhl highlight group used for the line number where + the sign is placed. + text text that is displayed when there is no icon + or the GUI is not being used. + texthl highlight group used for the text item + culhl highlight group used for the text item when + the cursor is on the same line as the sign and + 'cursorline' is enabled. + + If the sign named {name} already exists, then the attributes + of the sign are updated. + + The one argument {list} can be used to define a list of signs. + Each list item is a dictionary with the above items in {dict} + and a "name" item for the sign name. + + Returns 0 on success and -1 on failure. When the one argument + {list} is used, then returns a List of values one for each + defined sign. + + Examples: >vim + call sign_define("mySign", { + \ "text" : "=>", + \ "texthl" : "Error", + \ "linehl" : "Search"}) + call sign_define([ + \ {'name' : 'sign1', + \ 'text' : '=>'}, + \ {'name' : 'sign2', + \ 'text' : '!!'} + \ ]) +< + +sign_getdefined([{name}]) *sign_getdefined()* + Get a list of defined signs and their attributes. + This is similar to the |:sign-list| command. + + If the {name} is not supplied, then a list of all the defined + signs is returned. Otherwise the attribute of the specified + sign is returned. + + Each list item in the returned value is a dictionary with the + following entries: + icon full path to the bitmap file of the sign + linehl highlight group used for the whole line the + sign is placed in; not present if not set. + name name of the sign + numhl highlight group used for the line number where + the sign is placed; not present if not set. + text text that is displayed when there is no icon + or the GUI is not being used. + texthl highlight group used for the text item; not + present if not set. + culhl highlight group used for the text item when + the cursor is on the same line as the sign and + 'cursorline' is enabled; not present if not + set. + + Returns an empty List if there are no signs and when {name} is + not found. + + Examples: >vim + " Get a list of all the defined signs + echo sign_getdefined() + + " Get the attribute of the sign named mySign + echo sign_getdefined("mySign") +< + +sign_getplaced([{buf} [, {dict}]]) *sign_getplaced()* + Return a list of signs placed in a buffer or all the buffers. + This is similar to the |:sign-place-list| command. + + If the optional buffer name {buf} is specified, then only the + list of signs placed in that buffer is returned. For the use + of {buf}, see |bufname()|. The optional {dict} can contain + the following entries: + group select only signs in this group + id select sign with this identifier + lnum select signs placed in this line. For the use + of {lnum}, see |line()|. + If {group} is "*", then signs in all the groups including the + global group are returned. If {group} is not supplied or is an + empty string, then only signs in the global group are + returned. If no arguments are supplied, then signs in the + global group placed in all the buffers are returned. + See |sign-group|. + + Each list item in the returned value is a dictionary with the + following entries: + bufnr number of the buffer with the sign + signs list of signs placed in {bufnr}. Each list + item is a dictionary with the below listed + entries + + The dictionary for each sign contains the following entries: + group sign group. Set to '' for the global group. + id identifier of the sign + lnum line number where the sign is placed + name name of the defined sign + priority sign priority + + The returned signs in a buffer are ordered by their line + number and priority. + + Returns an empty list on failure or if there are no placed + signs. + + Examples: >vim + " Get a List of signs placed in eval.c in the + " global group + echo sign_getplaced("eval.c") + + " Get a List of signs in group 'g1' placed in eval.c + echo sign_getplaced("eval.c", {'group' : 'g1'}) + + " Get a List of signs placed at line 10 in eval.c + echo sign_getplaced("eval.c", {'lnum' : 10}) + + " Get sign with identifier 10 placed in a.py + echo sign_getplaced("a.py", {'id' : 10}) + + " Get sign with id 20 in group 'g1' placed in a.py + echo sign_getplaced("a.py", {'group' : 'g1', + \ 'id' : 20}) + + " Get a List of all the placed signs + echo sign_getplaced() +< + +sign_jump({id}, {group}, {buf}) *sign_jump()* + Open the buffer {buf} or jump to the window that contains + {buf} and position the cursor at sign {id} in group {group}. + This is similar to the |:sign-jump| command. + + If {group} is an empty string, then the global group is used. + For the use of {buf}, see |bufname()|. + + Returns the line number of the sign. Returns -1 if the + arguments are invalid. + + Example: >vim + " Jump to sign 10 in the current buffer + call sign_jump(10, '', '') +< + +sign_place({id}, {group}, {name}, {buf} [, {dict}]) *sign_place()* + Place the sign defined as {name} at line {lnum} in file or + buffer {buf} and assign {id} and {group} to sign. This is + similar to the |:sign-place| command. + + If the sign identifier {id} is zero, then a new identifier is + allocated. Otherwise the specified number is used. {group} is + the sign group name. To use the global sign group, use an + empty string. {group} functions as a namespace for {id}, thus + two groups can use the same IDs. Refer to |sign-identifier| + and |sign-group| for more information. + + {name} refers to a defined sign. + {buf} refers to a buffer name or number. For the accepted + values, see |bufname()|. -sign_ functions are documented here: |sign-functions-details| + The optional {dict} argument supports the following entries: + lnum line number in the file or buffer + {buf} where the sign is to be placed. + For the accepted values, see |line()|. + priority priority of the sign. See + |sign-priority| for more information. -simplify({filename}) *simplify()* + If the optional {dict} is not specified, then it modifies the + placed sign {id} in group {group} to use the defined sign + {name}. + + Returns the sign identifier on success and -1 on failure. + + Examples: >vim + " Place a sign named sign1 with id 5 at line 20 in + " buffer json.c + call sign_place(5, '', 'sign1', 'json.c', + \ {'lnum' : 20}) + + " Updates sign 5 in buffer json.c to use sign2 + call sign_place(5, '', 'sign2', 'json.c') + + " Place a sign named sign3 at line 30 in + " buffer json.c with a new identifier + let id = sign_place(0, '', 'sign3', 'json.c', + \ {'lnum' : 30}) + + " Place a sign named sign4 with id 10 in group 'g3' + " at line 40 in buffer json.c with priority 90 + call sign_place(10, 'g3', 'sign4', 'json.c', + \ {'lnum' : 40, 'priority' : 90}) +< + +sign_placelist({list}) *sign_placelist()* + Place one or more signs. This is similar to the + |sign_place()| function. The {list} argument specifies the + List of signs to place. Each list item is a dict with the + following sign attributes: + buffer Buffer name or number. For the accepted + values, see |bufname()|. + group Sign group. {group} functions as a namespace + for {id}, thus two groups can use the same + IDs. If not specified or set to an empty + string, then the global group is used. See + |sign-group| for more information. + id Sign identifier. If not specified or zero, + then a new unique identifier is allocated. + Otherwise the specified number is used. See + |sign-identifier| for more information. + lnum Line number in the buffer where the sign is to + be placed. For the accepted values, see + |line()|. + name Name of the sign to place. See |sign_define()| + for more information. + priority Priority of the sign. When multiple signs are + placed on a line, the sign with the highest + priority is used. If not specified, the + default value of 10 is used. See + |sign-priority| for more information. + + If {id} refers to an existing sign, then the existing sign is + modified to use the specified {name} and/or {priority}. + + Returns a List of sign identifiers. If failed to place a + sign, the corresponding list item is set to -1. + + Examples: >vim + " Place sign s1 with id 5 at line 20 and id 10 at line + " 30 in buffer a.c + let [n1, n2] = sign_placelist([ + \ {'id' : 5, + \ 'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 20}, + \ {'id' : 10, + \ 'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 30} + \ ]) + + " Place sign s1 in buffer a.c at line 40 and 50 + " with auto-generated identifiers + let [n1, n2] = sign_placelist([ + \ {'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 40}, + \ {'name' : 's1', + \ 'buffer' : 'a.c', + \ 'lnum' : 50} + \ ]) +< + +sign_undefine([{name}]) +sign_undefine({list}) *sign_undefine()* + Deletes a previously defined sign {name}. This is similar to + the |:sign-undefine| command. If {name} is not supplied, then + deletes all the defined signs. + + The one argument {list} can be used to undefine a list of + signs. Each list item is the name of a sign. + + Returns 0 on success and -1 on failure. For the one argument + {list} call, returns a list of values one for each undefined + sign. + + Examples: >vim + " Delete a sign named mySign + call sign_undefine("mySign") + + " Delete signs 'sign1' and 'sign2' + call sign_undefine(["sign1", "sign2"]) + + " Delete all the signs + call sign_undefine() +< + +sign_unplace({group} [, {dict}]) *sign_unplace()* + Remove a previously placed sign in one or more buffers. This + is similar to the |:sign-unplace| command. + + {group} is the sign group name. To use the global sign group, + use an empty string. If {group} is set to "*", then all the + groups including the global group are used. + The signs in {group} are selected based on the entries in + {dict}. The following optional entries in {dict} are + supported: + buffer buffer name or number. See |bufname()|. + id sign identifier + If {dict} is not supplied, then all the signs in {group} are + removed. + + Returns 0 on success and -1 on failure. + + Examples: >vim + " Remove sign 10 from buffer a.vim + call sign_unplace('', {'buffer' : "a.vim", 'id' : 10}) + + " Remove sign 20 in group 'g1' from buffer 3 + call sign_unplace('g1', {'buffer' : 3, 'id' : 20}) + + " Remove all the signs in group 'g2' from buffer 10 + call sign_unplace('g2', {'buffer' : 10}) + + " Remove sign 30 in group 'g3' from all the buffers + call sign_unplace('g3', {'id' : 30}) + + " Remove all the signs placed in buffer 5 + call sign_unplace('*', {'buffer' : 5}) + + " Remove the signs in group 'g4' from all the buffers + call sign_unplace('g4') + + " Remove sign 40 from all the buffers + call sign_unplace('*', {'id' : 40}) + + " Remove all the placed signs from all the buffers + call sign_unplace('*') + +sign_unplacelist({list}) *sign_unplacelist()* + Remove previously placed signs from one or more buffers. This + is similar to the |sign_unplace()| function. + + The {list} argument specifies the List of signs to remove. + Each list item is a dict with the following sign attributes: + buffer buffer name or number. For the accepted + values, see |bufname()|. If not specified, + then the specified sign is removed from all + the buffers. + group sign group name. If not specified or set to an + empty string, then the global sign group is + used. If set to "*", then all the groups + including the global group are used. + id sign identifier. If not specified, then all + the signs in the specified group are removed. + + Returns a List where an entry is set to 0 if the corresponding + sign was successfully removed or -1 on failure. + + Example: >vim + " Remove sign with id 10 from buffer a.vim and sign + " with id 20 from buffer b.vim + call sign_unplacelist([ + \ {'id' : 10, 'buffer' : "a.vim"}, + \ {'id' : 20, 'buffer' : 'b.vim'}, + \ ]) +< + +simplify({filename}) *simplify()* Simplify the file name as much as possible without changing the meaning. Shortcuts (on MS-Windows) or symbolic links (on Unix) are not resolved. If the first path component in @@ -7528,7 +7206,7 @@ simplify({filename}) *simplify()* not removed either. On Unix "//path" is unchanged, but "///path" is simplified to "/path" (this follows the Posix standard). - Example: > + Example: >vim simplify("./dir/.././/file/") == "./file/" < Note: The combination "dir/.." is only removed if "dir" is a searchable directory or does not exist. On Unix, it is also @@ -7536,42 +7214,46 @@ simplify({filename}) *simplify()* directory. In order to resolve all the involved symbolic links before simplifying the path name, use |resolve()|. - Can also be used as a |method|: > - GetName()->simplify() - -sin({expr}) *sin()* +sin({expr}) *sin()* Return the sine of {expr}, measured in radians, as a |Float|. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo sin(100) -< -0.506366 > - :echo sin(-4.01) + Examples: >vim + echo sin(100) +< -0.506366 >vim + echo sin(-4.01) < 0.763301 - Can also be used as a |method|: > - Compute()->sin() - -sinh({expr}) *sinh()* +sinh({expr}) *sinh()* Return the hyperbolic sine of {expr} as a |Float| in the range [-inf, inf]. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo sinh(0.5) -< 0.521095 > - :echo sinh(-0.9) + Examples: >vim + echo sinh(0.5) +< 0.521095 >vim + echo sinh(-0.9) < -1.026517 - Can also be used as a |method|: > - Compute()->sinh() +slice({expr}, {start} [, {end}]) *slice()* + Similar to using a |slice| "expr[start : end]", but "end" is + used exclusive. And for a string the indexes are used as + character indexes instead of byte indexes. + Also, composing characters are not counted. + When {end} is omitted the slice continues to the last item. + When {end} is -1 the last item is omitted. + Returns an empty value if {start} or {end} are invalid. -sockconnect({mode}, {address} [, {opts}]) *sockconnect()* +sockconnect({mode}, {address} [, {opts}]) *sockconnect()* Connect a socket to an address. If {mode} is "pipe" then - {address} should be the path of a named pipe. If {mode} is - "tcp" then {address} should be of the form "host:port" where - the host should be an ip adderess or host name, and port the - port number. + {address} should be the path of a local domain socket (on + unix) or named pipe (on Windows). If {mode} is "tcp" then + {address} should be of the form "host:port" where the host + should be an ip address or host name, and port the port + number. + + For "pipe" mode, see |luv-pipe-handle|. For "tcp" mode, see + |luv-tcp-handle|. Returns a |channel| ID. Close the socket with |chanclose()|. Use |chansend()| to send data over a bytes socket, and @@ -7587,50 +7269,51 @@ sockconnect({mode}, {address} [, {opts}]) *sockconnect()* - The channel ID on success (greater than zero) - 0 on invalid arguments or connection failure. -sort({list} [, {func} [, {dict}]]) *sort()* *E702* +sort({list} [, {how} [, {dict}]]) *sort()* *E702* Sort the items in {list} in-place. Returns {list}. - If you want a list to remain unmodified make a copy first: > - :let sortedlist = sort(copy(mylist)) + If you want a list to remain unmodified make a copy first: >vim + let sortedlist = sort(copy(mylist)) -< When {func} is omitted, is empty or zero, then sort() uses the +< When {how} is omitted or is a string, then sort() uses the string representation of each item to sort on. Numbers sort after Strings, |Lists| after Numbers. For sorting text in the current buffer use |:sort|. - When {func} is given and it is '1' or 'i' then case is - ignored. + When {how} is given and it is 'i' then case is ignored. + For backwards compatibility, the value one can be used to + ignore case. Zero means to not ignore case. - When {func} is given and it is 'l' then the current collation + When {how} is given and it is 'l' then the current collation locale is used for ordering. Implementation details: strcoll() is used to compare strings. See |:language| check or set the collation locale. |v:collate| can also be used to check the current locale. Sorting using the locale typically ignores - case. Example: > + case. Example: >vim " ö is sorted similarly to o with English locale. - :language collate en_US.UTF8 - :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') + language collate en_US.UTF8 + echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') < ['n', 'o', 'O', 'ö', 'p', 'z'] ~ -> +>vim " ö is sorted after z with Swedish locale. - :language collate sv_SE.UTF8 - :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') + language collate sv_SE.UTF8 + echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') < ['n', 'o', 'O', 'p', 'z', 'ö'] ~ This does not work properly on Mac. - When {func} is given and it is 'n' then all items will be + When {how} is given and it is 'n' then all items will be sorted numerical (Implementation detail: this uses the strtod() function to parse numbers, Strings, Lists, Dicts and Funcrefs will be considered as being 0). - When {func} is given and it is 'N' then all items will be + When {how} is given and it is 'N' then all items will be sorted numerical. This is like 'n' but a string containing digits will be used as the number they represent. - When {func} is given and it is 'f' then all items will be + When {how} is given and it is 'f' then all items will be sorted numerical. All values must be a Number or a Float. - When {func} is a |Funcref| or a function name, this function + When {how} is a |Funcref| or a function name, this function is called to compare items. The function is invoked with two items as argument and must return zero if they are equal, 1 or bigger if the first one sorts after the second one, -1 or @@ -7644,26 +7327,22 @@ sort({list} [, {func} [, {dict}]]) *sort()* *E702* on numbers, text strings will sort next to each other, in the same order as they were originally. - Can also be used as a |method|: > - mylist->sort() - -< Also see |uniq()|. - Example: > + Example: >vim func MyCompare(i1, i2) return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 endfunc eval mylist->sort("MyCompare") < A shorter compare version for this specific simple case, which - ignores overflow: > + ignores overflow: >vim func MyCompare(i1, i2) return a:i1 - a:i2 endfunc -< For a simple expression you can use a lambda: > +< For a simple expression you can use a lambda: >vim eval mylist->sort({i1, i2 -> i1 - i2}) < - *soundfold()* -soundfold({word}) + +soundfold({word}) *soundfold()* Return the sound-folded equivalent of {word}. Uses the first language in 'spelllang' for the current window that supports soundfolding. 'spell' must be set. When no sound folding is @@ -7671,11 +7350,7 @@ soundfold({word}) This can be used for making spelling suggestions. Note that the method can be quite slow. - Can also be used as a |method|: > - GetWord()->soundfold() -< - *spellbadword()* -spellbadword([{sentence}]) +spellbadword([{sentence}]) *spellbadword()* Without argument: The result is the badly spelled word under or after the cursor. The cursor is moved to the start of the bad word. When no bad word is found in the cursor line the @@ -7692,18 +7367,14 @@ spellbadword([{sentence}]) "rare" rare word "local" word only valid in another region "caps" word should start with Capital - Example: > + Example: >vim echo spellbadword("the quik brown fox") < ['quik', 'bad'] ~ The spelling information for the current window and the value of 'spelllang' are used. - Can also be used as a |method|: > - GetText()->spellbadword() -< - *spellsuggest()* -spellsuggest({word} [, {max} [, {capital}]]) +spellsuggest({word} [, {max} [, {capital}]]) *spellsuggest()* Return a |List| with spelling suggestions to replace {word}. When {max} is given up to this number of suggestions are returned. Otherwise up to 25 suggestions are returned. @@ -7724,10 +7395,7 @@ spellsuggest({word} [, {max} [, {capital}]]) The spelling information for the current window is used. The values of 'spelllang' and 'spellsuggest' are used. - Can also be used as a |method|: > - GetWord()->spellsuggest() - -split({string} [, {pattern} [, {keepempty}]]) *split()* +split({string} [, {pattern} [, {keepempty}]]) *split()* Make a |List| out of {string}. When {pattern} is omitted or empty each white-separated sequence of characters becomes an item. @@ -7738,38 +7406,34 @@ split({string} [, {pattern} [, {keepempty}]]) *split()* {keepempty} argument is given and it's non-zero. Other empty items are kept when {pattern} matches at least one character or when {keepempty} is non-zero. - Example: > - :let words = split(getline('.'), '\W\+') -< To split a string in individual characters: > - :for c in split(mystring, '\zs') + Example: >vim + let words = split(getline('.'), '\W\+') +< To split a string in individual characters: >vim + for c in split(mystring, '\zs') | endfor < If you want to keep the separator you can also use '\zs' at - the end of the pattern: > - :echo split('abc:def:ghi', ':\zs') -< ['abc:', 'def:', 'ghi'] ~ - Splitting a table where the first element can be empty: > - :let items = split(line, ':', 1) + the end of the pattern: >vim + echo split('abc:def:ghi', ':\zs') +< > + ['abc:', 'def:', 'ghi'] +< + Splitting a table where the first element can be empty: >vim + let items = split(line, ':', 1) < The opposite function is |join()|. - Can also be used as a |method|: > - GetString()->split() - -sqrt({expr}) *sqrt()* +sqrt({expr}) *sqrt()* Return the non-negative square root of Float {expr} as a |Float|. {expr} must evaluate to a |Float| or a |Number|. When {expr} is negative the result is NaN (Not a Number). Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo sqrt(100) -< 10.0 > - :echo sqrt(-4.01) + Examples: >vim + echo sqrt(100) +< 10.0 >vim + echo sqrt(-4.01) < str2float("nan") NaN may be different, it depends on system libraries. - Can also be used as a |method|: > - Compute()->sqrt() - -srand([{expr}]) *srand()* +srand([{expr}]) *srand()* Initialize seed used by |rand()|: - If {expr} is not given, seed values are initialized by reading from /dev/urandom, if possible, or using time(NULL) @@ -7778,15 +7442,43 @@ srand([{expr}]) *srand()* initialize the seed values. This is useful for testing or when a predictable sequence is intended. - Examples: > - :let seed = srand() - :let seed = srand(userinput) - :echo rand(seed) -< - Can also be used as a |method|: > - userinput->srand() - -stdioopen({opts}) *stdioopen()* + Examples: >vim + let seed = srand() + let seed = srand(userinput) + echo rand(seed) +< + +state([{what}]) *state()* + Return a string which contains characters indicating the + current state. Mostly useful in callbacks that want to do + work that may not always be safe. Roughly this works like: + - callback uses state() to check if work is safe to do. + Yes: then do it right away. + No: add to work queue and add a |SafeState| autocommand. + - When SafeState is triggered and executes your autocommand, + check with `state()` if the work can be done now, and if yes + remove it from the queue and execute. + Remove the autocommand if the queue is now empty. + Also see |mode()|. + + When {what} is given only characters in this string will be + added. E.g, this checks if the screen has scrolled: >vim + if state('s') == '' + " screen has not scrolled +< + These characters indicate the state, generally indicating that + something is busy: + m halfway a mapping, :normal command, feedkeys() or + stuffed command + o operator pending, e.g. after |d| + a Insert mode autocomplete active + x executing an autocommand + S not triggering SafeState, e.g. after |f| or a count + c callback invoked, including timer (repeats for + recursiveness up to "ccc") + s screen has scrolled for messages + +stdioopen({opts}) *stdioopen()* With |--headless| this opens stdin and stdout as a |channel|. May be called only once. See |channel-stdio|. stderr is not handled by this function, see |v:stderr|. @@ -7807,8 +7499,7 @@ stdioopen({opts}) *stdioopen()* - |channel-id| on success (value is always 1) - 0 on invalid arguments - -stdpath({what}) *stdpath()* *E6100* +stdpath({what}) *stdpath()* *E6100* Returns |standard-path| locations of various default files and directories. @@ -7826,11 +7517,11 @@ stdpath({what}) *stdpath()* *E6100* state String Session state directory: storage for file drafts, swap, undo, |shada|. - Example: > - :echo stdpath("config") - + Example: >vim + echo stdpath("config") +< -str2float({string} [, {quoted}]) *str2float()* +str2float({string} [, {quoted}]) *str2float()* Convert String {string} to a Float. This mostly works the same as when using a floating point number in an expression, see |floating-point-format|. But it's a bit more permissive. @@ -7844,30 +7535,24 @@ str2float({string} [, {quoted}]) *str2float()* The decimal point is always '.', no matter what the locale is set to. A comma ends the number: "12,345.67" is converted to 12.0. You can strip out thousands separators with - |substitute()|: > + |substitute()|: >vim let f = str2float(substitute(text, ',', '', 'g')) < Returns 0.0 if the conversion fails. - Can also be used as a |method|: > - let f = text->substitute(',', '', 'g')->str2float() - -str2list({string} [, {utf8}]) *str2list()* +str2list({string} [, {utf8}]) *str2list()* Return a list containing the number values which represent - each character in String {string}. Examples: > - str2list(" ") returns [32] - str2list("ABC") returns [65, 66, 67] + each character in String {string}. Examples: >vim + echo str2list(" ") " returns [32] + echo str2list("ABC") " returns [65, 66, 67] < |list2str()| does the opposite. 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|: > - GetString()->str2list() + With UTF-8 composing characters are handled properly: >vim + echo str2list("á") " returns [97, 769] -str2nr({string} [, {base}]) *str2nr()* +str2nr({string} [, {base}]) *str2nr()* Convert string {string} to a number. {base} is the conversion base, it can be 2, 8, 10 or 16. When {quoted} is present and non-zero then embedded single @@ -7875,7 +7560,7 @@ str2nr({string} [, {base}]) *str2nr()* When {base} is omitted base 10 is used. This also means that a leading zero doesn't cause octal conversion to be used, as - with the default String to Number conversion. Example: > + with the default String to Number conversion. Example: >vim let nr = str2nr('0123') < When {base} is 16 a leading "0x" or "0X" is ignored. With a @@ -7886,11 +7571,7 @@ str2nr({string} [, {base}]) *str2nr()* Returns 0 if {string} is empty or on error. - Can also be used as a |method|: > - GetText()->str2nr() - - -strcharlen({string}) *strcharlen()* +strcharlen({string}) *strcharlen()* The result is a Number, which is the number of characters in String {string}. Composing characters are ignored. |strchars()| can count the number of characters, counting @@ -7900,26 +7581,22 @@ strcharlen({string}) *strcharlen()* Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. - Can also be used as a |method|: > - GetText()->strcharlen() - - -strcharpart({src}, {start} [, {len}]) *strcharpart()* +strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* Like |strpart()| but using character index and length instead - of byte index and length. Composing characters are counted - separately. + of byte index and length. + When {skipcc} is omitted or zero, composing characters are + counted separately. + When {skipcc} set to 1, Composing characters are ignored, + similar to |slice()|. When a character index is used where a character does not - exist it is assumed to be one character. For example: > - strcharpart('abc', -1, 2) + exist it is omitted and counted as one character. For + example: >vim + echo strcharpart('abc', -1, 2) < results in 'a'. Returns an empty string on error. - Can also be used as a |method|: > - GetText()->strcharpart(5) - - -strchars({string} [, {skipcc}]) *strchars()* +strchars({string} [, {skipcc}]) *strchars()* The result is a Number, which is the number of characters in String {string}. When {skipcc} is omitted or zero, composing characters are @@ -7932,7 +7609,7 @@ strchars({string} [, {skipcc}]) *strchars()* Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. {skipcc} is only available after 7.4.755. For backward - compatibility, you can define a wrapper function: > + compatibility, you can define a wrapper function: >vim if has("patch-7.4.755") function s:strchars(str, skipcc) return strchars(a:str, a:skipcc) @@ -7947,10 +7624,8 @@ strchars({string} [, {skipcc}]) *strchars()* endfunction endif < - Can also be used as a |method|: > - GetText()->strchars() -strdisplaywidth({string} [, {col}]) *strdisplaywidth()* +strdisplaywidth({string} [, {col}]) *strdisplaywidth()* The result is a Number, which is the number of display cells String {string} occupies on the screen when it starts at {col} (first column is zero). When {col} is omitted zero is used. @@ -7964,10 +7639,7 @@ strdisplaywidth({string} [, {col}]) *strdisplaywidth()* Returns zero on error. Also see |strlen()|, |strwidth()| and |strchars()|. - Can also be used as a |method|: > - GetText()->strdisplaywidth() - -strftime({format} [, {time}]) *strftime()* +strftime({format} [, {time}]) *strftime()* The result is a String, which is a formatted date and time, as specified by the {format} string. The given {time} is used, or the current time if no time is given. The accepted @@ -7976,18 +7648,15 @@ strftime({format} [, {time}]) *strftime()* format. The maximum length of the result is 80 characters. See also |localtime()|, |getftime()| and |strptime()|. The language can be changed with the |:language| command. - Examples: > - :echo strftime("%c") Sun Apr 27 11:49:23 1997 - :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25 - :echo strftime("%y%m%d %T") 970427 11:53:55 - :echo strftime("%H:%M") 11:55 - :echo strftime("%c", getftime("file.c")) - Show mod time of file.c. - -< Can also be used as a |method|: > - GetFormat()->strftime() - -strgetchar({str}, {index}) *strgetchar()* + Examples: >vim + echo strftime("%c") " Sun Apr 27 11:49:23 1997 + echo strftime("%Y %b %d %X") " 1997 Apr 27 11:53:25 + echo strftime("%y%m%d %T") " 970427 11:53:55 + echo strftime("%H:%M") " 11:55 + echo strftime("%c", getftime("file.c")) + " Show mod time of file.c. + +strgetchar({str}, {index}) *strgetchar()* Get a Number corresponding to the character at {index} in {str}. This uses a zero-based character index, not a byte index. Composing characters are considered separate @@ -7996,33 +7665,27 @@ strgetchar({str}, {index}) *strgetchar()* Returns -1 if {index} is invalid. Also see |strcharpart()| and |strchars()|. - Can also be used as a |method|: > - GetText()->strgetchar(5) - -stridx({haystack}, {needle} [, {start}]) *stridx()* +stridx({haystack}, {needle} [, {start}]) *stridx()* The result is a Number, which gives the byte index in {haystack} of the first occurrence of the String {needle}. If {start} is specified, the search starts at index {start}. - This can be used to find a second match: > - :let colon1 = stridx(line, ":") - :let colon2 = stridx(line, ":", colon1 + 1) + This can be used to find a second match: >vim + let colon1 = stridx(line, ":") + let colon2 = stridx(line, ":", colon1 + 1) < The search is done case-sensitive. For pattern searches use |match()|. -1 is returned if the {needle} does not occur in {haystack}. See also |strridx()|. - Examples: > - :echo stridx("An Example", "Example") 3 - :echo stridx("Starting point", "Start") 0 - :echo stridx("Starting point", "start") -1 + Examples: >vim + echo stridx("An Example", "Example") " 3 + echo stridx("Starting point", "Start") " 0 + echo stridx("Starting point", "start") " -1 < *strstr()* *strchr()* stridx() works similar to the C function strstr(). When used with a single character it works similar to strchr(). - Can also be used as a |method|: > - GetHaystack()->stridx(needle) -< - *string()* -string({expr}) Return {expr} converted to a String. If {expr} is a Number, +string({expr}) *string()* + Return {expr} converted to a String. If {expr} is a Number, Float, String, Blob or a composition of them, then the result can be parsed back with |eval()|. {expr} type result ~ @@ -8033,7 +7696,7 @@ string({expr}) Return {expr} converted to a String. If {expr} is a Number, Funcref `function('name')` Blob 0z00112233.44556677.8899 List [item, item] - Dictionary {key: value, key: value} + Dictionary `{key: value, key: value}` Note that in String values the ' character is doubled. Also see |strtrans()|. Note 2: Output format is mostly compatible with YAML, except @@ -8045,10 +7708,7 @@ string({expr}) Return {expr} converted to a String. If {expr} is a Number, method, use |msgpackdump()| or |json_encode()| if you need to share data with other application. - Can also be used as a |method|: > - mylist->string() - -strlen({string}) *strlen()* +strlen({string}) *strlen()* The result is a Number, which is the length of the String {string} in bytes. If the argument is a Number it is first converted to a String. @@ -8057,10 +7717,7 @@ strlen({string}) *strlen()* |strchars()|. Also see |len()|, |strdisplaywidth()| and |strwidth()|. - Can also be used as a |method|: > - GetString()->strlen() - -strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* +strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* The result is a String, which is part of {src}, starting from byte {start}, with the byte length {len}. When {chars} is present and TRUE then {len} is the number of @@ -8073,22 +7730,19 @@ strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* When bytes are selected which do not exist, this doesn't result in an error, the bytes are simply omitted. If {len} is missing, the copy continues from {start} till the - end of the {src}. > - strpart("abcdefg", 3, 2) == "de" - strpart("abcdefg", -2, 4) == "ab" - strpart("abcdefg", 5, 4) == "fg" - strpart("abcdefg", 3) == "defg" + end of the {src}. >vim + echo strpart("abcdefg", 3, 2) " returns 'de' + echo strpart("abcdefg", -2, 4) " returns 'ab' + echo strpart("abcdefg", 5, 4) " returns 'fg' + echo strpart("abcdefg", 3) " returns 'defg' < Note: To get the first character, {start} must be 0. For - example, to get the character under the cursor: > + example, to get the character under the cursor: >vim strpart(getline("."), col(".") - 1, 1, v:true) < Returns an empty string on error. - Can also be used as a |method|: > - GetText()->strpart(5) - -strptime({format}, {timestring}) *strptime()* +strptime({format}, {timestring}) *strptime()* The result is a Number, which is a unix timestamp representing the date and time in {timestring}, which is expected to match the format specified in {format}. @@ -8104,52 +7758,63 @@ strptime({format}, {timestring}) *strptime()* result. See also |strftime()|. - Examples: > - :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23") -< 862156163 > - :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55")) -< Sun Apr 27 11:53:55 1997 > - :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600) + Examples: >vim + echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23") +< 862156163 >vim + echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55")) +< Sun Apr 27 11:53:55 1997 >vim + echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600) < Sun Apr 27 12:53:55 1997 - Can also be used as a |method|: > - GetFormat()->strptime(timestring) -< -strridx({haystack}, {needle} [, {start}]) *strridx()* +strridx({haystack}, {needle} [, {start}]) *strridx()* The result is a Number, which gives the byte index in {haystack} of the last occurrence of the String {needle}. When {start} is specified, matches beyond this index are ignored. This can be used to find a match before a previous - match: > - :let lastcomma = strridx(line, ",") - :let comma2 = strridx(line, ",", lastcomma - 1) + match: >vim + let lastcomma = strridx(line, ",") + let comma2 = strridx(line, ",", lastcomma - 1) < The search is done case-sensitive. For pattern searches use |match()|. -1 is returned if the {needle} does not occur in {haystack}. If the {needle} is empty the length of {haystack} is returned. - See also |stridx()|. Examples: > - :echo strridx("an angry armadillo", "an") 3 + See also |stridx()|. Examples: >vim + echo strridx("an angry armadillo", "an") 3 < *strrchr()* When used with a single character it works similar to the C function strrchr(). - Can also be used as a |method|: > - GetHaystack()->strridx(needle) - -strtrans({string}) *strtrans()* +strtrans({string}) *strtrans()* The result is a String, which is {string} with all unprintable characters translated into printable characters |'isprint'|. - Like they are shown in a window. Example: > + Like they are shown in a window. Example: >vim echo strtrans(@a) < This displays a newline in register a as "^@" instead of starting a new line. Returns an empty string on error. - Can also be used as a |method|: > - GetString()->strtrans() +strutf16len({string} [, {countcc}]) *strutf16len()* + The result is a Number, which is the number of UTF-16 code + units in String {string} (after converting it to UTF-16). -strwidth({string}) *strwidth()* + When {countcc} is TRUE, composing characters are counted + separately. + When {countcc} is omitted or FALSE, composing characters are + ignored. + + Returns zero on error. + + Also see |strlen()| and |strcharlen()|. + Examples: >vim + echo strutf16len('a') " returns 1 + echo strutf16len('©') " returns 1 + echo strutf16len('😊') " returns 2 + echo strutf16len('ą́') " returns 1 + echo strutf16len('ą́', v:true) " returns 3 +< + +strwidth({string}) *strwidth()* The result is a Number, which is the number of display cells String {string} occupies. A Tab character is counted as one cell, alternatively use |strdisplaywidth()|. @@ -8158,10 +7823,7 @@ strwidth({string}) *strwidth()* Returns zero on error. Also see |strlen()|, |strdisplaywidth()| and |strchars()|. - Can also be used as a |method|: > - GetString()->strwidth() - -submatch({nr} [, {list}]) *submatch()* *E935* +submatch({nr} [, {list}]) *submatch()* *E935* Only for an expression in a |:substitute| command or substitute() function. Returns the {nr}th submatch of the matched text. When {nr} @@ -8183,16 +7845,13 @@ submatch({nr} [, {list}]) *submatch()* *E935* Returns an empty string or list on error. - Examples: > - :s/\d\+/\=submatch(0) + 1/ - :echo substitute(text, '\d\+', '\=submatch(0) + 1', '') + Examples: >vim + s/\d\+/\=submatch(0) + 1/ + echo substitute(text, '\d\+', '\=submatch(0) + 1', '') < This finds the first number in the line and adds one to it. A line break is included as a newline character. - Can also be used as a |method|: > - GetNr()->submatch() - -substitute({string}, {pat}, {sub}, {flags}) *substitute()* +substitute({string}, {pat}, {sub}, {flags}) *substitute()* The result is a String, which is a copy of {string}, in which the first match of {pat} is replaced with {sub}. When {flags} is "g", all matches of {pat} in {string} are @@ -8214,39 +7873,47 @@ substitute({string}, {pat}, {sub}, {flags}) *substitute()* When {pat} does not match in {string}, {string} is returned unmodified. - Example: > - :let &path = substitute(&path, ",\\=[^,]*$", "", "") -< This removes the last component of the 'path' option. > - :echo substitute("testing", ".*", "\\U\\0", "") + Example: >vim + let &path = substitute(&path, ",\\=[^,]*$", "", "") +< This removes the last component of the 'path' option. >vim + echo substitute("testing", ".*", "\\U\\0", "") < results in "TESTING". When {sub} starts with "\=", the remainder is interpreted as - an expression. See |sub-replace-expression|. Example: > - :echo substitute(s, '%\(\x\x\)', + an expression. See |sub-replace-expression|. Example: >vim + echo substitute(s, '%\(\x\x\)', \ '\=nr2char("0x" .. submatch(1))', 'g') < When {sub} is a Funcref that function is called, with one - optional argument. Example: > - :echo substitute(s, '%\(\x\x\)', SubNr, 'g') + optional argument. Example: >vim + echo substitute(s, '%\(\x\x\)', SubNr, 'g') < The optional argument is a list which contains the whole matched string and up to nine submatches, like what - |submatch()| returns. Example: > - :echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g') + |submatch()| returns. Example: >vim + echo substitute(s, '%\(\x\x\)', {m -> '0x' .. m[1]}, 'g') < Returns an empty string on error. - Can also be used as a |method|: > - GetString()->substitute(pat, sub, flags) - -swapinfo({fname}) *swapinfo()* +swapfilelist() *swapfilelist()* + Returns a list of swap file names, like what "vim -r" shows. + See the |-r| command argument. The 'directory' option is used + for the directories to inspect. If you only want to get a + list of swap files in the current directory then temporarily + set 'directory' to a dot: >vim + let save_dir = &directory + let &directory = '.' + let swapfiles = swapfilelist() + let &directory = save_dir + +swapinfo({fname}) *swapinfo()* The result is a dictionary, which holds information about the swapfile {fname}. The available fields are: version Vim version user user name host host name fname original file name - pid PID of the Vim process that created the swap - file + pid PID of the Nvim process that created the swap + file, or zero if not running. mtime last modification time in seconds inode Optional: INODE number of the file dirty 1 if file was modified, 0 if not @@ -8256,20 +7923,14 @@ swapinfo({fname}) *swapinfo()* Not a swap file: does not contain correct block ID Magic number mismatch: Info in first block is invalid - Can also be used as a |method|: > - GetFilename()->swapinfo() - -swapname({buf}) *swapname()* +swapname({buf}) *swapname()* The result is the swap file path of the buffer {buf}. For the use of {buf}, see |bufname()| above. If buffer {buf} is the current buffer, the result is equal to |:swapname| (unless there is no swap file). If buffer {buf} has no swap file, returns an empty string. - Can also be used as a |method|: > - GetBufname()->swapname() - -synID({lnum}, {col}, {trans}) *synID()* +synID({lnum}, {col}, {trans}) *synID()* The result is a Number, which is the syntax ID at the position {lnum} and {col} in the current window. The syntax ID can be used with |synIDattr()| and @@ -8291,11 +7952,11 @@ synID({lnum}, {col}, {trans}) *synID()* Returns zero on error. - Example (echoes the name of the syntax item under the cursor): > - :echo synIDattr(synID(line("."), col("."), 1), "name") + Example (echoes the name of the syntax item under the cursor): >vim + echo synIDattr(synID(line("."), col("."), 1), "name") < -synIDattr({synID}, {what} [, {mode}]) *synIDattr()* +synIDattr({synID}, {what} [, {mode}]) *synIDattr()* The result is a String, which is the {what} attribute of syntax ID {synID}. This can be used to obtain information about a syntax item. @@ -8334,13 +7995,14 @@ synIDattr({synID}, {what} [, {mode}]) *synIDattr()* Returns an empty string on error. Example (echoes the color of the syntax item under the - cursor): > - :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg") + cursor): >vim + echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg") +< + Can also be used as a |method|: >vim + echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") < - Can also be used as a |method|: > - :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") -synIDtrans({synID}) *synIDtrans()* +synIDtrans({synID}) *synIDtrans()* The result is a Number, which is the translated syntax ID of {synID}. This is the syntax group ID of what is being used to highlight the character. Highlight links given with @@ -8348,10 +8010,7 @@ synIDtrans({synID}) *synIDtrans()* Returns zero on error. - Can also be used as a |method|: > - :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") - -synconcealed({lnum}, {col}) *synconcealed()* +synconcealed({lnum}, {col}) *synconcealed()* The result is a |List| with currently three items: 1. The first item in the list is 0 if the character at the position {lnum} and {col} is not part of a concealable @@ -8376,8 +8035,7 @@ synconcealed({lnum}, {col}) *synconcealed()* synconcealed(lnum, 5) [1, 'X', 2] synconcealed(lnum, 6) [0, '', 0] - -synstack({lnum}, {col}) *synstack()* +synstack({lnum}, {col}) *synstack()* Return a |List|, which is the stack of syntax items at the position {lnum} and {col} in the current window. {lnum} is used like with |getline()|. Each item in the List is an ID @@ -8387,7 +8045,7 @@ synstack({lnum}, {col}) *synstack()* returns, unless not the whole item is highlighted or it is a transparent item. This function is useful for debugging a syntax file. - Example that shows the syntax stack under the cursor: > + Example that shows the syntax stack under the cursor: >vim for id in synstack(line("."), col(".")) echo synIDattr(id, "name") endfor @@ -8396,13 +8054,15 @@ synstack({lnum}, {col}) *synstack()* character in a line and the first column in an empty line are valid positions. -system({cmd} [, {input}]) *system()* *E677* +system({cmd} [, {input}]) *system()* *E677* + Note: Prefer |vim.system()| in Lua. + Gets the output of {cmd} as a |string| (|systemlist()| returns a |List|) and sets |v:shell_error| to the error code. {cmd} is treated as in |jobstart()|: If {cmd} is a List it runs directly (no 'shell'). - If {cmd} is a String it runs in the 'shell', like this: > - :call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) + If {cmd} is a String it runs in the 'shell', like this: >vim + call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}']) < Not to be used for interactive commands. @@ -8410,8 +8070,8 @@ system({cmd} [, {input}]) *system()* *E677* - <CR><NL> is replaced with <NL> - NUL characters are replaced with SOH (0x01) - Example: > - :echo system(['ls', expand('%:h')]) + Example: >vim + echo system(['ls', expand('%:h')]) < If {input} is a string it is written to a pipe and passed as stdin to the command. The string is written as-is, line @@ -8425,8 +8085,8 @@ system({cmd} [, {input}]) *system()* *E677* terminated by NL (and NUL where the text has NL). *E5677* Note: system() cannot write to or read from backgrounded ("&") - shell commands, e.g.: > - :echo system("cat - &", "foo") + shell commands, e.g.: >vim + echo system("cat - &", "foo") < which is equivalent to: > $ echo foo | bash -c 'cat - &' < The pipes are disconnected (unless overridden by shell @@ -8436,17 +8096,14 @@ system({cmd} [, {input}]) *system()* *E677* Note: Use |shellescape()| or |::S| with |expand()| or |fnamemodify()| to escape special characters in a command argument. 'shellquote' and 'shellxquote' must be properly - configured. Example: > - :echo system('ls '..shellescape(expand('%:h'))) - :echo system('ls '..expand('%:h:S')) + configured. Example: >vim + echo system('ls '..shellescape(expand('%:h'))) + echo system('ls '..expand('%:h:S')) < Unlike ":!cmd" there is no automatic check for changed files. Use |:checktime| to force a check. - Can also be used as a |method|: > - :echo GetCmd()->system() - -systemlist({cmd} [, {input} [, {keepempty}]]) *systemlist()* +systemlist({cmd} [, {input} [, {keepempty}]]) *systemlist()* Same as |system()|, but returns a |List| with lines (parts of output separated by NL) with NULs transformed into NLs. Output is the same as |readfile()| will output with {binary} argument @@ -8455,31 +8112,25 @@ systemlist({cmd} [, {input} [, {keepempty}]]) *systemlist()* Note that on MS-Windows you may get trailing CR characters. To see the difference between "echo hello" and "echo -n hello" - use |system()| and |split()|: > + use |system()| and |split()|: >vim echo split(system('echo hello'), '\n', 1) < Returns an empty string on error. - Can also be used as a |method|: > - :echo GetCmd()->systemlist() - -tabpagebuflist([{arg}]) *tabpagebuflist()* +tabpagebuflist([{arg}]) *tabpagebuflist()* The result is a |List|, where each item is the number of the buffer associated with each window in the current tab page. {arg} specifies the number of the tab page to be used. When omitted the current tab page is used. When {arg} is invalid the number zero is returned. - To get a list of all buffers in all tabs use this: > + To get a list of all buffers in all tabs use this: >vim let buflist = [] for i in range(tabpagenr('$')) call extend(buflist, tabpagebuflist(i + 1)) endfor < Note that a buffer may appear in more than one window. - Can also be used as a |method|: > - GetTabpage()->tabpagebuflist() - -tabpagenr([{arg}]) *tabpagenr()* +tabpagenr([{arg}]) *tabpagenr()* The result is a Number, which is the number of the current tab page. The first tab page has number 1. @@ -8493,7 +8144,7 @@ tabpagenr([{arg}]) *tabpagenr()* Returns zero on error. -tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()* +tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()* Like |winnr()| but for tab page {tabarg}. {tabarg} specifies the number of tab page to be used. {arg} is used like with |winnr()|: @@ -8501,20 +8152,16 @@ tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()* the window which will be used when going to this tab page. - When "$" the number of windows is returned. - When "#" the previous window nr is returned. - Useful examples: > + Useful examples: >vim tabpagewinnr(1) " current window of tab page 1 tabpagewinnr(4, '$') " number of windows in tab page 4 < When {tabarg} is invalid zero is returned. - Can also be used as a |method|: > - GetTabpage()->tabpagewinnr() -< - *tagfiles()* -tagfiles() Returns a |List| with the file names used to search for tags +tagfiles() *tagfiles()* + Returns a |List| with the file names used to search for tags for the current buffer. This is the 'tags' option expanded. - -taglist({expr} [, {filename}]) *taglist()* +taglist({expr} [, {filename}]) *taglist()* Returns a |List| of tags matching the regular expression {expr}. If {filename} is passed it is used to prioritize the results @@ -8557,60 +8204,59 @@ taglist({expr} [, {filename}]) *taglist()* located by Vim. Refer to |tags-file-format| for the format of the tags file generated by the different ctags tools. - Can also be used as a |method|: > - GetTagpattern()->taglist() - -tempname() *tempname()* *temp-file-name* - The result is a String, which is the name of a file that - doesn't exist. It can be used for a temporary file. Example: > - :let tmpfile = tempname() - :exe "redir > " .. tmpfile -< For Unix, the file will be in a private directory |tempfile|. - For MS-Windows forward slashes are used when the 'shellslash' - option is set or when 'shellcmdflag' starts with '-'. - -termopen({cmd} [, {opts}]) *termopen()* - Spawns {cmd} in a new pseudo-terminal session connected - to the current (unmodified) buffer. Parameters and behavior - are the same as |jobstart()| except "pty", "width", "height", - and "TERM" are ignored: "height" and "width" are taken from - the current window. - Returns the same values as |jobstart()|. - - Terminal environment is initialized as in ||jobstart-env|, - except $TERM is set to "xterm-256color". Full behavior is - described in |terminal|. - -tan({expr}) *tan()* +tan({expr}) *tan()* Return the tangent of {expr}, measured in radians, as a |Float| in the range [-inf, inf]. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo tan(10) -< 0.648361 > - :echo tan(-4.01) + Examples: >vim + echo tan(10) +< 0.648361 >vim + echo tan(-4.01) < -1.181502 - Can also be used as a |method|: > - Compute()->tan() - -tanh({expr}) *tanh()* +tanh({expr}) *tanh()* Return the hyperbolic tangent of {expr} as a |Float| in the range [-1, 1]. {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > - :echo tanh(0.5) -< 0.462117 > - :echo tanh(-1) + Examples: >vim + echo tanh(0.5) +< 0.462117 >vim + echo tanh(-1) < -0.761594 - Can also be used as a |method|: > - Compute()->tanh() +tempname() *tempname()* + Generates a (non-existent) filename located in the Nvim root + |tempdir|. Scripts can use the filename as a temporary file. + Example: >vim + let tmpfile = tempname() + exe "redir > " .. tmpfile < - *timer_info()* -timer_info([{id}]) + +termopen({cmd} [, {opts}]) *termopen()* + Spawns {cmd} in a new pseudo-terminal session connected + to the current (unmodified) buffer. Parameters and behavior + are the same as |jobstart()| except "pty", "width", "height", + and "TERM" are ignored: "height" and "width" are taken from + the current window. Note that termopen() implies a "pty" arg + to jobstart(), and thus has the implications documented at + |jobstart()|. + + Returns the same values as jobstart(). + + Terminal environment is initialized as in |jobstart-env|, + except $TERM is set to "xterm-256color". Full behavior is + described in |terminal|. + +test_garbagecollect_now() *test_garbagecollect_now()* + Like |garbagecollect()|, but executed right away. This must + only be called directly to avoid any structure to exist + internally, and |v:testing| must have been set before calling + any function. + + +timer_info([{id}]) *timer_info()* Return a list with information about timers. When {id} is given only information about this timer is returned. When timer {id} does not exist an empty list is @@ -8625,10 +8271,7 @@ timer_info([{id}]) -1 means forever "callback" the callback - Can also be used as a |method|: > - GetTimer()->timer_info() -< -timer_pause({timer}, {paused}) *timer_pause()* +timer_pause({timer}, {paused}) *timer_pause()* Pause or unpause a timer. A paused timer does not invoke its callback when its time expires. Unpausing a timer may cause the callback to be invoked almost immediately if enough time @@ -8641,16 +8284,14 @@ timer_pause({timer}, {paused}) *timer_pause()* String, then the timer is paused, otherwise it is unpaused. See |non-zero-arg|. - Can also be used as a |method|: > - GetTimer()->timer_pause(1) -< - *timer_start()* *timer* *timers* -timer_start({time}, {callback} [, {options}]) +timer_start({time}, {callback} [, {options}]) *timer_start()* *timer* Create a timer and return the timer ID. {time} is the waiting time in milliseconds. This is the minimum time before invoking the callback. When the system is busy or Vim is not waiting for input the time will be longer. + Zero can be used to execute the callback when Vim is back in + the main loop. {callback} is the function to call. It can be the name of a function or a |Funcref|. It is called with one argument, which @@ -8665,7 +8306,7 @@ timer_start({time}, {callback} [, {options}]) Returns -1 on error. - Example: > + Example: >vim func MyHandler(timer) echo 'Handler called' endfunc @@ -8673,41 +8314,27 @@ timer_start({time}, {callback} [, {options}]) \ {'repeat': 3}) < This invokes MyHandler() three times at 500 msec intervals. - Can also be used as a |method|: > - GetMsec()->timer_start(callback) - -< Not available in the |sandbox|. - -timer_stop({timer}) *timer_stop()* +timer_stop({timer}) *timer_stop()* Stop a timer. The timer callback will no longer be invoked. {timer} is an ID returned by timer_start(), thus it must be a Number. If {timer} does not exist there is no error. - Can also be used as a |method|: > - GetTimer()->timer_stop() -< -timer_stopall() *timer_stopall()* +timer_stopall() *timer_stopall()* Stop all timers. The timer callbacks will no longer be invoked. Useful if some timers is misbehaving. If there are no timers there is no error. -tolower({expr}) *tolower()* +tolower({expr}) *tolower()* The result is a copy of the String given, with all uppercase characters turned into lowercase (just like applying |gu| to the string). Returns an empty string on error. - Can also be used as a |method|: > - GetText()->tolower() - -toupper({expr}) *toupper()* +toupper({expr}) *toupper()* The result is a copy of the String given, with all lowercase characters turned into uppercase (just like applying |gU| to the string). Returns an empty string on error. - Can also be used as a |method|: > - GetText()->toupper() - -tr({src}, {fromstr}, {tostr}) *tr()* +tr({src}, {fromstr}, {tostr}) *tr()* The result is a copy of the {src} string with all characters which appear in {fromstr} replaced by the character in that position in the {tostr} string. Thus the first character in @@ -8717,90 +8344,81 @@ tr({src}, {fromstr}, {tostr}) *tr()* Returns an empty string on error. - Examples: > + Examples: >vim echo tr("hello there", "ht", "HT") -< returns "Hello THere" > +< returns "Hello THere" >vim echo tr("<blob>", "<>", "{}") < returns "{blob}" - Can also be used as a |method|: > - GetText()->tr(from, to) - -trim({text} [, {mask} [, {dir}]]) *trim()* +trim({text} [, {mask} [, {dir}]]) *trim()* Return {text} as a String where any character in {mask} is removed from the beginning and/or end of {text}. - If {mask} is not given, {mask} is all characters up to 0x20, - which includes Tab, space, NL and CR, plus the non-breaking - space character 0xa0. + + If {mask} is not given, or is an empty string, {mask} is all + characters up to 0x20, which includes Tab, space, NL and CR, + plus the non-breaking space character 0xa0. + The optional {dir} argument specifies where to remove the characters: 0 remove from the beginning and end of {text} 1 remove only at the beginning of {text} 2 remove only at the end of {text} When omitted both ends are trimmed. + This function deals with multibyte characters properly. Returns an empty string on error. - Examples: > + Examples: >vim echo trim(" some text ") -< returns "some text" > +< returns "some text" >vim echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") .. "_TAIL" -< returns "RESERVE_TAIL" > +< returns "RESERVE_TAIL" >vim echo trim("rm<Xrm<>X>rrm", "rm<>") -< returns "Xrm<>X" (characters in the middle are not removed) > +< returns "Xrm<>X" (characters in the middle are not removed) >vim echo trim(" vim ", " ", 2) < returns " vim" - Can also be used as a |method|: > - GetText()->trim() - -trunc({expr}) *trunc()* +trunc({expr}) *trunc()* Return the largest integral value with magnitude less than or equal to {expr} as a |Float| (truncate towards zero). {expr} must evaluate to a |Float| or a |Number|. Returns 0.0 if {expr} is not a |Float| or a |Number|. - Examples: > + Examples: >vim echo trunc(1.456) -< 1.0 > +< 1.0 >vim echo trunc(-5.456) -< -5.0 > +< -5.0 >vim echo trunc(4.0) < 4.0 - Can also be used as a |method|: > - Compute()->trunc() - -type({expr}) *type()* +type({expr}) *type()* The result is a Number representing the type of {expr}. Instead of using the number directly, it is better to use the v:t_ variable that has the value: - Number: 0 (|v:t_number|) - String: 1 (|v:t_string|) - Funcref: 2 (|v:t_func|) - List: 3 (|v:t_list|) - Dictionary: 4 (|v:t_dict|) - Float: 5 (|v:t_float|) - Boolean: 6 (|v:true| and |v:false|) - Null: 7 (|v:null|) - Blob: 10 (|v:t_blob|) - For backward compatibility, this method can be used: > - :if type(myvar) == type(0) - :if type(myvar) == type("") - :if type(myvar) == type(function("tr")) - :if type(myvar) == type([]) - :if type(myvar) == type({}) - :if type(myvar) == type(0.0) - :if type(myvar) == type(v:true) + Number: 0 |v:t_number| + String: 1 |v:t_string| + Funcref: 2 |v:t_func| + List: 3 |v:t_list| + Dictionary: 4 |v:t_dict| + Float: 5 |v:t_float| + Boolean: 6 |v:t_bool| (|v:false| and |v:true|) + Null: 7 (|v:null|) + Blob: 10 |v:t_blob| + For backward compatibility, this method can be used: >vim + if type(myvar) == type(0) | endif + if type(myvar) == type("") | endif + if type(myvar) == type(function("tr")) | endif + if type(myvar) == type([]) | endif + if type(myvar) == type({}) | endif + if type(myvar) == type(0.0) | endif + if type(myvar) == type(v:true) | endif < In place of checking for |v:null| type it is better to check - for |v:null| directly as it is the only value of this type: > - :if myvar is v:null -< To check if the v:t_ variables exist use this: > - :if exists('v:t_number') + for |v:null| directly as it is the only value of this type: >vim + if myvar is v:null | endif +< To check if the v:t_ variables exist use this: >vim + if exists('v:t_number') | endif -< Can also be used as a |method|: > - mylist->type() - -undofile({name}) *undofile()* +undofile({name}) *undofile()* Return the name of the undo file that would be used for a file with name {name} when writing. This uses the 'undodir' option, finding directories that exist. It does not check if @@ -8811,12 +8429,10 @@ undofile({name}) *undofile()* buffer without a file name will not write an undo file. Useful in combination with |:wundo| and |:rundo|. - Can also be used as a |method|: > - GetFilename()->undofile() - -undotree() *undotree()* - Return the current state of the undo tree in a dictionary with - the following items: +undotree([{buf}]) *undotree()* + Return the current state of the undo tree for the current + buffer, or for a specific buffer if {buf} is given. The + result is a dictionary with the following items: "seq_last" The highest undo sequence number used. "seq_cur" The sequence number of the current position in the undo tree. This differs from "seq_last" @@ -8857,28 +8473,50 @@ undotree() *undotree()* blocks. Each item may again have an "alt" item. -uniq({list} [, {func} [, {dict}]]) *uniq()* *E882* +uniq({list} [, {func} [, {dict}]]) *uniq()* *E882* Remove second and succeeding copies of repeated adjacent {list} items in-place. Returns {list}. If you want a list - to remain unmodified make a copy first: > - :let newlist = uniq(copy(mylist)) + to remain unmodified make a copy first: >vim + let newlist = uniq(copy(mylist)) < The default compare function uses the string representation of each item. For the use of {func} and {dict} see |sort()|. Returns zero if {list} is not a |List|. - Can also be used as a |method|: > - mylist->uniq() +utf16idx({string}, {idx} [, {countcc} [, {charidx}]]) *utf16idx()* + Same as |charidx()| but returns the UTF-16 code unit index of + the byte at {idx} in {string} (after converting it to UTF-16). + + When {charidx} is present and TRUE, {idx} is used as the + character index in the String {string} instead of as the byte + index. + An {idx} in the middle of a UTF-8 sequence is rounded + downwards to the beginning of that sequence. -values({dict}) *values()* + Returns -1 if the arguments are invalid or if there are less + than {idx} bytes in {string}. If there are exactly {idx} bytes + the length of the string in UTF-16 code units is returned. + + See |byteidx()| and |byteidxcomp()| for getting the byte index + from the UTF-16 index and |charidx()| for getting the + character index from the UTF-16 index. + Refer to |string-offset-encoding| for more information. + Examples: >vim + echo utf16idx('a😊😊', 3) " returns 2 + echo utf16idx('a😊😊', 7) " returns 4 + echo utf16idx('a😊😊', 1, 0, 1) " returns 2 + echo utf16idx('a😊😊', 2, 0, 1) " returns 4 + echo utf16idx('aą́c', 6) " returns 2 + echo utf16idx('aą́c', 6, 1) " returns 4 + echo utf16idx('a😊😊', 9) " returns -1 +< + +values({dict}) *values()* Return a |List| with all the values of {dict}. The |List| is in arbitrary order. Also see |items()| and |keys()|. Returns zero if {dict} is not a |Dict|. - Can also be used as a |method|: > - mydict->values() - -virtcol({expr}) *virtcol()* +virtcol({expr} [, {list} [, {winid}]]) *virtcol()* The result is a Number, which is the screen column of the file position given with {expr}. That is, the last screen position occupied by the character at that position, when the screen @@ -8887,13 +8525,17 @@ virtcol({expr}) *virtcol()* the <Tab>. For example, for a <Tab> in column 1, with 'ts' set to 8, it returns 8. |conceal| is ignored. For the byte position use |col()|. + For the use of {expr} see |col()|. - When 'virtualedit' is used {expr} can be [lnum, col, off], where - "off" is the offset in screen columns from the start of the - character. E.g., a position within a <Tab> or after the last - character. When "off" is omitted zero is used. - When Virtual editing is active in the current mode, a position - beyond the end of the line can be returned. |'virtualedit'| + + When 'virtualedit' is used {expr} can be [lnum, col, off], + where "off" is the offset in screen columns from the start of + the character. E.g., a position within a <Tab> or after the + last character. When "off" is omitted zero is used. When + Virtual editing is active in the current mode, a position + beyond the end of the line can be returned. Also see + |'virtualedit'| + The accepted positions are: . the cursor position $ the end of the cursor line (the result is the @@ -8905,28 +8547,44 @@ virtcol({expr}) *virtcol()* cursor is the end). When not in Visual mode returns the cursor position. Differs from |'<| in that it's updated right away. + + If {list} is present and non-zero then virtcol() returns a + List with the first and last screen position occupied by the + character. + + With the optional {winid} argument the values are obtained for + that window instead of the current window. + Note that only marks in the current file can be used. - Examples: > - virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5 - virtcol("$") with text "foo^Lbar", returns 9 - virtcol("'t") with text " there", with 't at 'h', returns 6 -< The first column is 1. 0 is returned for an error. + Examples: >vim + " With text "foo^Lbar" and cursor on the "^L": + + echo virtcol(".") " returns 5 + echo virtcol(".", 1) " returns [4, 5] + echo virtcol("$") " returns 9 + + " With text " there", with 't at 'h': + + echo virtcol("'t") " returns 6 +< The first column is 1. 0 or [0, 0] is returned for an error. A more advanced example that echoes the maximum length of - all lines: > + all lines: >vim echo max(map(range(1, line('$')), "virtcol([v:val, '$'])")) -< Can also be used as a |method|: > - GetPos()->virtcol() - -virtcol2col({winid}, {lnum}, {col}) *virtcol2col()* +virtcol2col({winid}, {lnum}, {col}) *virtcol2col()* The result is a Number, which is the byte index of the character in window {winid} at buffer line {lnum} and virtual column {col}. + If buffer line {lnum} is an empty line, 0 is returned. + If {col} is greater than the last virtual column in line {lnum}, then the byte index of the character at the last virtual column is returned. + For a multi-byte character, the column number of the first + byte in the character is returned. + The {winid} argument can be the window number or the |window-ID|. If this is zero, then the current window is used. @@ -8935,18 +8593,15 @@ virtcol2col({winid}, {lnum}, {col}) *virtcol2col()* See also |screenpos()|, |virtcol()| and |col()|. - Can also be used as a |method|: > - GetWinid()->virtcol2col(lnum, col) - -visualmode([{expr}]) *visualmode()* +visualmode([{expr}]) *visualmode()* The result is a String, which describes the last Visual mode used in the current buffer. Initially it returns an empty string, but once Visual mode has been used, it returns "v", "V", or "<CTRL-V>" (a single CTRL-V character) for character-wise, line-wise, or block-wise Visual mode respectively. - Example: > - :exe "normal " .. visualmode() + Example: >vim + exe "normal " .. visualmode() < This enters the same Visual mode as before. It is also useful in scripts if you wish to act differently depending on the Visual mode that was used. @@ -8956,7 +8611,7 @@ visualmode([{expr}]) *visualmode()* a non-empty String, then the Visual mode will be cleared and the old value is returned. See |non-zero-arg|. -wait({timeout}, {condition} [, {interval}]) *wait()* +wait({timeout}, {condition} [, {interval}]) *wait()* Waits until {condition} evaluates to |TRUE|, where {condition} is a |Funcref| or |string| containing an expression. @@ -8972,24 +8627,24 @@ wait({timeout}, {condition} [, {interval}]) *wait()* -2 if the function was interrupted (by |CTRL-C|) -3 if an error occurred -wildmenumode() *wildmenumode()* +wildmenumode() *wildmenumode()* Returns |TRUE| when the wildmenu is active and |FALSE| otherwise. See 'wildmenu' and 'wildmode'. This can be used in mappings to handle the 'wildcharm' option gracefully. (Makes only sense with |mapmode-c| mappings). - For example to make <c-j> work like <down> in wildmode, use: > - :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>" + For example to make <c-j> work like <down> in wildmode, use: >vim + cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>" < (Note, this needs the 'wildcharm' option set appropriately). -win_execute({id}, {command} [, {silent}]) *win_execute()* +win_execute({id}, {command} [, {silent}]) *win_execute()* Like `execute()` but in the context of window {id}. The window will temporarily be made the current window, without triggering autocommands or changing directory. When executing {command} autocommands will be triggered, this may - have unexpected side effects. Use |:noautocmd| if needed. - Example: > + have unexpected side effects. Use `:noautocmd` if needed. + Example: >vim call win_execute(winid, 'syntax enable') < Doing the same with `setwinvar()` would not trigger autocommands and not actually show syntax highlighting. @@ -8997,18 +8652,11 @@ win_execute({id}, {command} [, {silent}]) *win_execute()* When window {id} does not exist then no error is given and an empty string is returned. - Can also be used as a |method|, the base is passed as the - second argument: > - GetCommand()->win_execute(winid) - -win_findbuf({bufnr}) *win_findbuf()* +win_findbuf({bufnr}) *win_findbuf()* Returns a |List| with |window-ID|s for windows that contain buffer {bufnr}. When there is none the list is empty. - Can also be used as a |method|: > - GetBufnr()->win_findbuf() - -win_getid([{win} [, {tab}]]) *win_getid()* +win_getid([{win} [, {tab}]]) *win_getid()* Get the |window-ID| for the specified window. When {win} is missing use the current window. With {win} this is the window number. The top window has @@ -9017,10 +8665,7 @@ win_getid([{win} [, {tab}]]) *win_getid()* number {tab}. The first tab has number one. Return zero if the window cannot be found. - Can also be used as a |method|: > - GetWinnr()->win_getid() - -win_gettype([{nr}]) *win_gettype()* +win_gettype([{nr}]) *win_gettype()* Return the type of the window: "autocmd" autocommand window. Temporary window used to execute autocommands. @@ -9038,33 +8683,21 @@ win_gettype([{nr}]) *win_gettype()* Also see the 'buftype' option. - Can also be used as a |method|: > - GetWinid()->win_gettype() -< -win_gotoid({expr}) *win_gotoid()* +win_gotoid({expr}) *win_gotoid()* Go to window with ID {expr}. This may also change the current tabpage. Return TRUE if successful, FALSE if the window cannot be found. - Can also be used as a |method|: > - GetWinid()->win_gotoid() - -win_id2tabwin({expr}) *win_id2tabwin()* +win_id2tabwin({expr}) *win_id2tabwin()* Return a list with the tab number and window number of window with ID {expr}: [tabnr, winnr]. Return [0, 0] if the window cannot be found. - Can also be used as a |method|: > - GetWinid()->win_id2tabwin() - -win_id2win({expr}) *win_id2win()* +win_id2win({expr}) *win_id2win()* Return the window number of window with ID {expr}. Return 0 if the window cannot be found in the current tabpage. - Can also be used as a |method|: > - GetWinid()->win_id2win() - -win_move_separator({nr}, {offset}) *win_move_separator()* +win_move_separator({nr}, {offset}) *win_move_separator()* Move window {nr}'s vertical separator (i.e., the right border) by {offset} columns, as if being dragged by the mouse. {nr} can be a window number or |window-ID|. A positive {offset} @@ -9079,10 +8712,7 @@ win_move_separator({nr}, {offset}) *win_move_separator()* window, since it has no separator on the right. Only works for the current tab page. *E1308* - Can also be used as a |method|: > - GetWinnr()->win_move_separator(offset) - -win_move_statusline({nr}, {offset}) *win_move_statusline()* +win_move_statusline({nr}, {offset}) *win_move_statusline()* Move window {nr}'s status line (i.e., the bottom border) by {offset} rows, as if being dragged by the mouse. {nr} can be a window number or |window-ID|. A positive {offset} moves down @@ -9094,10 +8724,7 @@ win_move_statusline({nr}, {offset}) *win_move_statusline()* be found and FALSE otherwise. Only works for the current tab page. - Can also be used as a |method|: > - GetWinnr()->win_move_statusline(offset) - -win_screenpos({nr}) *win_screenpos()* +win_screenpos({nr}) *win_screenpos()* Return the screen position of window {nr} as a list with two numbers: [row, col]. The first window always has position [1, 1], unless there is a tabline, then it is [2, 1]. @@ -9106,10 +8733,7 @@ win_screenpos({nr}) *win_screenpos()* Returns [0, 0] if the window cannot be found in the current tabpage. - Can also be used as a |method|: > - GetWinid()->win_screenpos() -< -win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* +win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* Move the window {nr} to a new split of the window {target}. This is similar to moving to {target}, creating a new window using |:split| but having the same contents as window {nr}, and @@ -9129,48 +8753,39 @@ win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* present, the values of 'splitbelow' and 'splitright' are used. - Can also be used as a |method|: > - GetWinid()->win_splitmove(target) -< - *winbufnr()* -winbufnr({nr}) The result is a Number, which is the number of the buffer +winbufnr({nr}) *winbufnr()* + The result is a Number, which is the number of the buffer associated with window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is zero, the number of the buffer in the current window is returned. When window {nr} doesn't exist, -1 is returned. - Example: > - :echo "The file in the current window is " .. bufname(winbufnr(0)) -< - Can also be used as a |method|: > - FindWindow()->winbufnr()->bufname() + Example: >vim + echo "The file in the current window is " .. bufname(winbufnr(0)) < - *wincol()* -wincol() The result is a Number, which is the virtual column of the + +wincol() *wincol()* + The result is a Number, which is the virtual column of the cursor in the window. This is counting screen cells from the left side of the window. The leftmost column is one. - *windowsversion()* -windowsversion() +windowsversion() *windowsversion()* The result is a String. For MS-Windows it indicates the OS version. E.g, Windows 10 is "10.0", Windows 8 is "6.2", Windows XP is "5.1". For non-MS-Windows systems the result is an empty string. -winheight({nr}) *winheight()* +winheight({nr}) *winheight()* The result is a Number, which is the height of window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is zero, the height of the current window is returned. When window {nr} doesn't exist, -1 is returned. An existing window always has a height of zero or more. This excludes any window toolbar line. - Examples: > - :echo "The current window has " .. winheight(0) .. " lines." + Examples: >vim + echo "The current window has " .. winheight(0) .. " lines." -< Can also be used as a |method|: > - GetWinid()->winheight() -< -winlayout([{tabnr}]) *winlayout()* +winlayout([{tabnr}]) *winlayout()* The result is a nested List containing the layout of windows in a tabpage. @@ -9178,40 +8793,44 @@ winlayout([{tabnr}]) *winlayout()* with number {tabnr}. If the tabpage {tabnr} is not found, returns an empty list. - For a leaf window, it returns: + For a leaf window, it returns: > ["leaf", {winid}] +< For horizontally split windows, which form a column, it - returns: + returns: > ["col", [{nested list of windows}]] - For vertically split windows, which form a row, it returns: +< For vertically split windows, which form a row, it returns: > ["row", [{nested list of windows}]] - - Example: > +< + Example: >vim " Only one window in the tab page - :echo winlayout() + echo winlayout() +< > ['leaf', 1000] +< >vim " Two horizontally split windows - :echo winlayout() + echo winlayout() +< > ['col', [['leaf', 1000], ['leaf', 1001]]] +< >vim " The second tab page, with three horizontally split " windows, with two vertically split windows in the " middle window - :echo winlayout(2) + echo winlayout(2) +< > ['col', [['leaf', 1002], ['row', [['leaf', 1003], ['leaf', 1001]]], ['leaf', 1000]]] < - Can also be used as a |method|: > - GetTabnr()->winlayout() -< - *winline()* -winline() The result is a Number, which is the screen line of the cursor + +winline() *winline()* + The result is a Number, which is the screen line of the cursor in the window. This is counting screen lines from the top of the window. The first line is one. If the cursor was moved the view on the file will be updated first, this may cause a scroll. - *winnr()* -winnr([{arg}]) The result is a Number, which is the number of the current +winnr([{arg}]) *winnr()* + The result is a Number, which is the number of the current window. The top window has number 1. Returns zero for a popup window. @@ -9234,32 +8853,29 @@ winnr([{arg}]) The result is a Number, which is the number of the current |:wincmd|. When {arg} is invalid an error is given and zero is returned. Also see |tabpagewinnr()| and |win_getid()|. - Examples: > + Examples: >vim let window_count = winnr('$') let prev_window = winnr('#') let wnum = winnr('3k') -< Can also be used as a |method|: > - GetWinval()->winnr() -< - *winrestcmd()* -winrestcmd() Returns a sequence of |:resize| commands that should restore +winrestcmd() *winrestcmd()* + Returns a sequence of |:resize| commands that should restore the current window sizes. Only works properly when no windows are opened or closed and the current window and tab page is unchanged. - Example: > - :let cmd = winrestcmd() - :call MessWithWindowSizes() - :exe cmd + Example: >vim + let cmd = winrestcmd() + call MessWithWindowSizes() + exe cmd < - *winrestview()* -winrestview({dict}) + +winrestview({dict}) *winrestview()* Uses the |Dictionary| returned by |winsaveview()| to restore the view of the current window. Note: The {dict} does not have to contain all values, that are returned by |winsaveview()|. If values are missing, those - settings won't be restored. So you can use: > - :call winrestview({'curswant': 4}) + settings won't be restored. So you can use: >vim + call winrestview({'curswant': 4}) < This will only set the curswant value (the column the cursor wants to move on vertical movements) of the cursor to column 5 @@ -9269,11 +8885,8 @@ winrestview({dict}) If you have changed the values the result is unpredictable. If the window size changed the result won't be the same. - Can also be used as a |method|: > - GetView()->winrestview() -< - *winsaveview()* -winsaveview() Returns a |Dictionary| that contains information to restore +winsaveview() *winsaveview()* + Returns a |Dictionary| that contains information to restore the view of the current window. Use |winrestview()| to restore the view. This is useful if you have a mapping that jumps around in the @@ -9284,10 +8897,14 @@ winsaveview() Returns a |Dictionary| that contains information to restore The return value includes: lnum cursor line number col cursor column (Note: the first column - zero, as opposed to what getpos() + zero, as opposed to what |getcurpos()| returns) coladd cursor column offset for 'virtualedit' - curswant column for vertical movement + curswant column for vertical movement (Note: + the first column is zero, as opposed + to what |getcurpos()| returns). After + |$| command it will be a very large + number equal to |v:maxcol|. topline first line in the window topfill filler lines, only in diff mode leftcol first column displayed; only used when @@ -9295,25 +8912,21 @@ winsaveview() Returns a |Dictionary| that contains information to restore skipcol columns skipped Note that no option values are saved. - -winwidth({nr}) *winwidth()* +winwidth({nr}) *winwidth()* The result is a Number, which is the width of window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is zero, the width of the current window is returned. When window {nr} doesn't exist, -1 is returned. An existing window always has a width of zero or more. - Examples: > - :echo "The current window has " .. winwidth(0) .. " columns." - :if winwidth(0) <= 50 - : 50 wincmd | - :endif + Examples: >vim + echo "The current window has " .. winwidth(0) .. " columns." + if winwidth(0) <= 50 + 50 wincmd | + endif < For getting the terminal or screen size, see the 'columns' option. - Can also be used as a |method|: > - GetWinid()->winwidth() - -wordcount() *wordcount()* +wordcount() *wordcount()* The result is a dictionary of byte/chars/word statistics for the current buffer. This is the same info as provided by |g_CTRL-G| @@ -9334,57 +8947,62 @@ wordcount() *wordcount()* visual_words Number of words visually selected (only in Visual mode) - - *writefile()* -writefile({object}, {fname} [, {flags}]) +writefile({object}, {fname} [, {flags}]) *writefile()* When {object} is a |List| write it to file {fname}. Each list item is separated with a NL. Each list item must be a String or Number. - When {flags} contains "b" then binary mode is used: There will - not be a NL after the last list item. An empty item at the - end does cause the last line in the file to end in a NL. + All NL characters are replaced with a NUL character. + Inserting CR characters needs to be done before passing {list} + to writefile(). When {object} is a |Blob| write the bytes to file {fname} - unmodified. + unmodified, also when binary mode is not specified. + + {flags} must be a String. These characters are recognized: + + 'b' Binary mode is used: There will not be a NL after the + last list item. An empty item at the end does cause the + last line in the file to end in a NL. - When {flags} contains "a" then append mode is used, lines are - appended to the file: > - :call writefile(["foo"], "event.log", "a") - :call writefile(["bar"], "event.log", "a") + 'a' Append mode is used, lines are appended to the file: >vim + call writefile(["foo"], "event.log", "a") + call writefile(["bar"], "event.log", "a") < - When {flags} contains "S" fsync() call is not used, with "s" - it is used, 'fsync' option applies by default. No fsync() - means that writefile() will finish faster, but writes may be - left in OS buffers and not yet written to disk. Such changes - will disappear if system crashes before OS does writing. + 'D' Delete the file when the current function ends. This + works like: >vim + defer delete({fname}) +< Fails when not in a function. Also see |:defer|. + + 's' fsync() is called after writing the file. This flushes + the file to disk, if possible. This takes more time but + avoids losing the file if the system crashes. + + 'S' fsync() is not called, even when 'fsync' is set. + + When {flags} does not contain "S" or "s" then fsync() is + called if the 'fsync' option is set. - All NL characters are replaced with a NUL character. - Inserting CR characters needs to be done before passing {list} - to writefile(). An existing file is overwritten, if possible. + When the write fails -1 is returned, otherwise 0. There is an error message if the file can't be created or when writing fails. - Also see |readfile()|. - To copy a file byte for byte: > - :let fl = readfile("foo", "b") - :call writefile(fl, "foocopy", "b") -< Can also be used as a |method|: > - GetText()->writefile("thefile") + Also see |readfile()|. + To copy a file byte for byte: >vim + let fl = readfile("foo", "b") + call writefile(fl, "foocopy", "b") -xor({expr}, {expr}) *xor()* +xor({expr}, {expr}) *xor()* Bitwise XOR on the two arguments. The arguments are converted to a number. A List, Dict or Float argument causes an error. Also see `and()` and `or()`. - Example: > - :let bits = xor(bits, 0x80) -< - Can also be used as a |method|: > - :let bits = bits->xor(0x80) + Example: >vim + let bits = xor(bits, 0x80) < + ============================================================================== -3. Matching a pattern in a String *string-match* +2. Matching a pattern in a String *string-match* This is common between several functions. A regexp pattern as explained at |pattern| is normally used to find a match in the buffer lines. When a @@ -9392,14 +9010,14 @@ pattern is used to find a match in a String, almost everything works in the same way. The difference is that a String is handled like it is one line. When it contains a "\n" character, this is not seen as a line break for the pattern. It can be matched with a "\n" in the pattern, or with ".". Example: -> - :let a = "aaaa\nxxxx" - :echo matchstr(a, "..\n..") - aa - xx - :echo matchstr(a, "a.x") - a - x +>vim + let a = "aaaa\nxxxx" + echo matchstr(a, "..\n..") + " aa + " xx + echo matchstr(a, "a.x") + " a + " x Don't forget that "^" will only match at the first character of the String and "$" at the last character of the string. They don't match after or before a diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt index 990ba3d8fd..e1bb7c5fc7 100644 --- a/runtime/doc/change.txt +++ b/runtime/doc/change.txt @@ -196,6 +196,7 @@ gR Enter Virtual Replace mode: Each character you type *v_r* {Visual}r{char} Replace all selected characters by {char}. + CTRL-C will be inserted literally. *v_C* {Visual}["x]C Delete the highlighted lines [into register x] and @@ -276,7 +277,9 @@ gr{char} Replace the virtual characters under the cursor with {char}. This replaces in screen space, not file space. See |gR| and |Virtual-Replace-mode| for more details. As with |r| a count may be given. - {char} can be entered like with |r|. + {char} can be entered like with |r|, but characters + that have a special meaning in Insert mode, such as + most CTRL-keys, cannot be used. *digraph-arg* The argument for Normal mode commands like |r| and |t| is a single character. @@ -425,6 +428,11 @@ Note similarly, when 'nrformats' includes "bin", binary numbers with a leading '0x' or '0X' can be interpreted as hexadecimal rather than binary since '0b' are valid hexadecimal digits. +When the number under the cursor is too big to fit into 64 bits, it will be +rounded off to the nearest number that can be represented, and the +addition/subtraction is skipped. E.g. CTRL-X on 18446744073709551616 results +in 18446744073709551615. Same for larger numbers, such as 18446744073709551618. + The CTRL-A command is very useful in a macro. Example: Use the following steps to make a numbered list. @@ -574,18 +582,29 @@ with ".". Vim does not recognize a comment (starting with '"') after the {Visual}= Filter the highlighted lines like with ={motion}. - *tempfile* *setuid* -Vim uses temporary files for filtering, generating diffs and also for -tempname(). For Unix, the file will be in a private directory (only -accessible by the current user) to avoid security problems (e.g., a symlink -attack or other people reading your file). When Vim exits the directory and -all files in it are deleted. When Vim has the setuid bit set this may cause -problems, the temp file is owned by the setuid user but the filter command -probably runs as the original user. -Directory for temporary files is created in the first possible directory of: + *tempdir* *tempfile* *setuid* +Nvim uses temporary files for filtering and generating diffs. Plugins also +commonly use |tempname()| for their own purposes. On the first request for +a temporary file, Nvim creates a common directory (the "Nvim tempdir"), to +serve as storage for all temporary files (including `stdpath("run")` files +|$XDG_RUNTIME_DIR|) in the current session. + +The Nvim tempdir is created in the first available system tempdir: Unix: $TMPDIR, /tmp, current-dir, $HOME. Windows: $TMPDIR, $TMP, $TEMP, $USERPROFILE, current-dir. +On unix the tempdir is created with permissions 0700 (only accessible by the +current user) to avoid security problems (e.g. symlink attacks). On exit, +Nvim deletes the tempdir and its contents. + *E5431* +If you see an error or |log| message like: > + E5431: tempdir disappeared (2 times) +this means an external process on your system deleted the Nvim tempdir. +Typically this is caused by "antivirus" or a misconfigured cleanup service. + +If Nvim has the setuid bit set this may cause problems: the temp file +is owned by the setuid user but the filter command probably runs as the +original user. 4.2 Substitute *:substitute* @@ -600,9 +619,9 @@ Directory for temporary files is created in the first possible directory of: current line only. When [count] is given, replace in [count] lines, starting with the last line in [range]. When [range] is omitted start in the current line. - *E939* - [count] must be a positive number. Also see - |cmdline-ranges|. + *E939* *E1510* + [count] must be a positive number (max 2147483647) + Also see |cmdline-ranges|. See |:s_flags| for [flags]. The delimiter doesn't need to be /, see @@ -976,7 +995,7 @@ inside of strings can change! Also see 'softtabstop' option. > < to display registers '1' and 'a'. Spaces are allowed in {arg}. - *:di* *:display* + *:di* *:dis* *:display* :di[splay] [arg] Same as :registers. *y* *yank* @@ -1472,7 +1491,7 @@ white space). Three types of comments can be used: lines. An example is this list with dashes. - Three-piece comments that have a start string, an end string, and optional lines in between. The strings for the start, middle and end are different. - An example is the C style comment: + An example is the C style comment: > /* * this is a C comment */ @@ -1547,20 +1566,20 @@ When you hit Return in a C-comment, Vim will insert the middle comment leader for the new line: " * ". To close this comment you just have to type "/" before typing anything else on the new line. This will replace the middle-comment leader with the end-comment leader and apply any specified -alignment, leaving just " */". There is no need to hit Backspace first. +alignment, leaving just `" */"`. There is no need to hit Backspace first. When there is a match with a middle part, but there also is a matching end part which is longer, the end part is used. This makes a C style comment work without requiring the middle part to end with a space. Here is an example of alignment flags at work to make a comment stand out -(kind of looks like a 1 too). Consider comment string: > +(kind of looks like a 1 too). Consider comment string: >vim :set comments=sr:/***,m:**,ex-2:******/ -< +> /*** ~ **<--right aligned from "r" flag ~ ** ~ -offset 2 spaces for the "-2" flag--->** ~ + offset 2 spaces for the "-2" flag-->** ~ ******/ ~ In this case, the first comment was typed, then return was pressed 4 times, then "/" was pressed to end the comment. @@ -1712,8 +1731,6 @@ Note that when 'textwidth' is 0, Vim does no automatic formatting anyway (but does insert comment leaders according to the 'comments' option). An exception is when the 'a' flag is present. |auto-format| -Note that when 'paste' is on, Vim does no formatting at all. - Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping; 'textwidth' is still useful for formatting with "gq". @@ -1725,10 +1742,10 @@ happens with formatting and auto-wrapping. Opening a line after a line starting with "/*" or "*" and containing "*/", will cause no comment leader to be inserted, and the indent of the new line is taken from the line containing the start of the comment. -E.g.: - /* ~ - * Your typical comment. ~ - */ ~ +E.g.: > + /* + * Your typical comment. + */ The indent on this line is the same as the start of the above comment. diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt index 1c52b2d692..7184151cda 100644 --- a/runtime/doc/channel.txt +++ b/runtime/doc/channel.txt @@ -82,7 +82,7 @@ only bytes can be written to Nvim's own stderr. thus the first and last items in the {data} list may be partial lines. Empty string completes the previous partial line. Examples (not including the final `['']` emitted at EOF): - - `foobar` may arrive as `['fo'], ['obar']` + - `foobar` may arrive as `['fo'], ['obar']` - `foo\nbar` may arrive as - `['foo','bar']` - or `['foo',''], ['bar']` @@ -117,7 +117,7 @@ simple example, echoing some data through a cat-process: call chansend(id, "hello!") < -Here is a example of setting a buffer to the result of grep, but only after +Here is an example of setting a buffer to the result of grep, but only after all data has been processed: >vim function! s:OnEvent(id, data, event) dict @@ -151,7 +151,7 @@ from the host TTY, or if Nvim is |--headless| it uses default values: >vim When channels are opened with the `rpc` option set to true, the channel can be used for remote method calls in both directions, see |msgpack-rpc|. Note that rpc channels are implicitly trusted and the process at the other end can -invoke any |api| function! +invoke any |API| function! ============================================================================== 4. Standard IO channel *channel-stdio* diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt index b4923b0d70..8bed8a9ffc 100644 --- a/runtime/doc/cmdline.txt +++ b/runtime/doc/cmdline.txt @@ -81,9 +81,11 @@ CTRL-SHIFT-Q Works just like CTRL-V, but do not try to include the CTRL modifier into the key. *c_<Left>* *c_Left* -<Left> cursor left +<Left> cursor left. See 'wildmenu' for behavior during wildmenu + completion mode. *c_<Right>* *c_Right* -<Right> cursor right +<Right> cursor right. See 'wildmenu' for behavior during wildmenu + completion mode. *c_<S-Left>* <S-Left> or <C-Left> *c_<C-Left>* cursor one WORD left @@ -93,14 +95,15 @@ CTRL-SHIFT-Q Works just like CTRL-V, but do not try to include the CTRL CTRL-B or <Home> *c_CTRL-B* *c_<Home>* *c_Home* cursor to beginning of command-line CTRL-E or <End> *c_CTRL-E* *c_<End>* *c_End* - cursor to end of command-line + cursor to end of command-line. See 'wildmenu' for behavior + during wildmenu completion mode. *c_<LeftMouse>* <LeftMouse> Move the cursor to the position of the mouse click. *c_<MiddleMouse>* <MiddleMouse> Paste the contents of the clipboard (for X11 the primary - selection). This is similar to using CTRL-R *, but no CR + selection). This is similar to using `CTRL-R *`, but no CR characters are inserted between lines. CTRL-H *c_<BS>* *c_CTRL-H* *c_BS* @@ -143,7 +146,7 @@ CTRL-R {register} *c_CTRL-R* *c_<C-R>* the last delete or yank '%' the current file name '#' the alternate file name - '*' the clipboard contents (X11: primary selection) + "*" the clipboard contents (X11: primary selection) '+' the clipboard contents '/' the last search pattern ':' the last command-line @@ -190,8 +193,8 @@ CTRL-R CTRL-L *c_CTRL-R_CTRL-L* *c_<C-R>_<C-L>* *c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>* *c_CTRL-R_CTRL-O* *c_<C-R>_<C-O>* -CTRL-R CTRL-R {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L} -CTRL-R CTRL-O {register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L} +CTRL-R CTRL-R `{register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}` +CTRL-R CTRL-O `{register CTRL-F CTRL-P CTRL-W CTRL-A CTRL-L}` Insert register or object under the cursor. Works like |c_CTRL-R| but inserts the text literally. For example, if register a contains "xy^Hz" (where ^H is a backspace), @@ -226,6 +229,7 @@ CTRL-\ e {expr} *c_CTRL-\_e* CTRL-Y When there is a modeless selection, copy the selection into the clipboard. If there is no selection CTRL-Y is inserted as a character. + See 'wildmenu' for behavior during wildmenu completion mode. *c_CTRL-Z* CTRL-Z Trigger 'wildmode'. Same as 'wildcharm', but always available. @@ -248,10 +252,12 @@ CTRL-C quit command-line without executing *c_<Up>* *c_Up* <Up> recall older command-line from history, whose beginning - matches the current command-line (see below). + matches the current command-line (see below). See 'wildmenu' + for behavior during wildmenu completion mode. *c_<Down>* *c_Down* <Down> recall more recent command-line from history, whose beginning - matches the current command-line (see below). + matches the current command-line (see below). See 'wildmenu' + for behavior during wildmenu completion mode. *c_<S-Up>* *c_<PageUp>* <S-Up> or <PageUp> @@ -333,6 +339,7 @@ terminals) A positive number represents the absolute index of an entry as it is given in the first column of a :history listing. This number remains fixed even if other entries are deleted. + (see |E1510|) A negative number means the relative position of an entry, counted from the newest entry (which has index -1) backwards. @@ -358,6 +365,7 @@ When editing the command-line, a few commands can be used to complete the word before the cursor. This is available for: - Command names: At the start of the command-line. +- |++opt| values. - Tags: Only after the ":tag" command. - File names: Only after a command that accepts a file name or a setting for an option that can be set to a file name. This is called file name @@ -431,19 +439,24 @@ CTRL-T When 'incsearch' is set, entering a search pattern for "/" or keyboard T is above G. The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in -a previous version <Esc> was used). In the pattern standard wildcards '*' and -'?' are accepted when matching file names. '*' matches any string, '?' +a previous version <Esc> was used). In the pattern standard wildcards "*" and +'?' are accepted when matching file names. "*" matches any string, '?' matches exactly one character. When repeating 'wildchar' or CTRL-N you cycle through the matches, eventually ending up back to what was typed. If the first match is not what you wanted, you can use <S-Tab> or CTRL-P to go straight back to what you typed. -The 'wildignorecase' option can be set to ignore case in filenames. - The 'wildmenu' option can be set to show the matches just above the command line. +The 'wildoptions' option provides additional configuration to use a popup menu +for 'wildmenu', and to use fuzzy matching. + +The 'wildignorecase' option can be set to ignore case in filenames. For +completing other texts (e.g. command names), the 'ignorecase' option is used +instead (fuzzy matching always ignores case, however). + If you like tcsh's autolist completion, you can use this mapping: :cnoremap X <C-L><C-D> (Where X is the command key to use, <C-L> is CTRL-L and <C-D> is CTRL-D) @@ -493,16 +506,26 @@ example, to match only files that end in ".c": > :e *.c$ This will not match a file ending in ".cpp". Without the "$" it does match. -The old value of an option can be obtained by hitting 'wildchar' just after -the '='. For example, typing 'wildchar' after ":set dir=" will insert the -current value of 'dir'. This overrules file name completion for the options -that take a file name. - If you would like using <S-Tab> for CTRL-P in an xterm, put this command in your .cshrc: > xmodmap -e "keysym Tab = Tab Find" And this in your vimrc: > :cmap <Esc>[1~ <C-P> +< *complete-set-option* +When setting an option using |:set=|, the old value of an option can be +obtained by hitting 'wildchar' just after the '='. For example, typing +'wildchar' after ":set dir=" will insert the current value of 'dir'. This +overrules file name completion for the options that take a file name. + +When using |:set=|, |:set+=|, or |:set^=|, string options that have +pre-defined names or syntax (e.g. 'diffopt', 'listchars') or are a list of +single-character flags (e.g. 'shortmess') will also present a list of possible +values for completion when using 'wildchar'. + +When using |:set-=|, comma-separated options like 'diffopt' or 'backupdir' +will show each item separately. Flag list options like 'shortmess' will show +both the entire old value and the individual flags. Otherwise completion will +just fill in with the entire old value. ============================================================================== 3. Ex command-lines *cmdline-lines* @@ -584,6 +607,7 @@ followed by another Vim command: :registers :read ! :sign + :tabdo :terminal :vglobal :windo @@ -731,7 +755,7 @@ An example for subtracting (which isn't very useful): > On this text: 1 one ~ 2 two ~ - 3 three FOLDED~ + 3 three FOLDED ~ 4 four FOLDED ~ 5 five FOLDED ~ 6 six FOLDED ~ @@ -891,7 +915,7 @@ Note: these are typed literally, they are not special keys! to form a C expression. E.g., when the cursor is on "arg" of "ptr->arg" then the result is "ptr->arg"; when the cursor is on "]" of "list[idx]" then the result is - "list[idx]". This is used for |v:beval_text|. + "list[idx]". *:<cfile>* *<cfile>* <cfile> is replaced with the path name under the cursor (like what |gf| uses) @@ -901,9 +925,10 @@ Note: these are typed literally, they are not special keys! write. *E495* *:<abuf>* *<abuf>* <abuf> When executing autocommands, is replaced with the currently - effective buffer number (for ":r file" and ":so file" it is - the current buffer, the file being read/sourced is not in a - buffer). *E496* + effective buffer number. It is not set for all events, + also see |bufnr()|. For ":r file" and ":so file" it is the + current buffer, the file being read/sourced is not in a + buffer. *E496* *:<amatch>* *<amatch>* <amatch> When executing autocommands, is replaced with the match for which this autocommand was executed. *E497* @@ -979,7 +1004,7 @@ These modifiers can be given, in this order: precede any :r or :e. :r Root of the file name (the last extension removed). When there is only an extension (file name that starts with '.', - e.g., ".nvimrc"), it is not removed. Can be repeated to + e.g., ".nvimrc"), it is not removed. Can be repeated to remove several extensions (last one first). :e Extension of the file name. Only makes sense when used alone. When there is no extension the result is empty. @@ -1056,7 +1081,7 @@ But expansion is only done if there are any wildcards before expanding the '%', '#', etc.. This avoids expanding wildcards inside a file name. If you want to expand the result of <cfile>, add a wildcard character to it. Examples: (alternate file name is "?readme?") - command expands to ~ + command expands to > :e # :e ?readme? :e `ls #` :e {files matching "?readme?"} :e #.* :e {files matching "?readme?.*"} @@ -1228,6 +1253,6 @@ The character used for the pattern indicates the type of command-line: ? backward search string = expression for "= |expr-register| @ string for |input()| - - text for |:insert| or |:append| + `-` text for |:insert| or |:append| vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt index 1bdd13ac0c..0a07f06c75 100644 --- a/runtime/doc/deprecated.txt +++ b/runtime/doc/deprecated.txt @@ -15,8 +15,18 @@ Deprecated features API - *nvim_buf_clear_highlight()* Use |nvim_buf_clear_namespace()| instead. - *nvim_buf_set_virtual_text()* Use |nvim_buf_set_extmark()| instead. -- *nvim_command_output()* Use |nvim_exec()| instead. +- *nvim_command_output()* Use |nvim_exec2()| instead. - *nvim_execute_lua()* Use |nvim_exec_lua()| instead. +- *nvim_get_hl_by_name()* Use |nvim_get_hl()| instead. +- *nvim_get_hl_by_id()* Use |nvim_get_hl()| instead. +- *nvim_exec()* Use |nvim_exec2()| instead. +- *nvim_get_option_info()* Use |nvim_get_option_info2()| instead. +- *nvim_buf_get_option()* Use |nvim_get_option_value()| instead. +- *nvim_buf_set_option()* Use |nvim_set_option_value()| instead. +- *nvim_get_option()* Use |nvim_get_option_value()| instead. +- *nvim_set_option()* Use |nvim_set_option_value()| instead. +- *nvim_win_get_option()* Use |nvim_get_option_value()| instead. +- *nvim_win_set_option()* Use |nvim_set_option_value()| instead. COMMANDS - *:rv* *:rviminfo* Deprecated alias to |:rshada| command. @@ -50,11 +60,11 @@ FUNCTIONS - *buffer_name()* Obsolete name for |bufname()|. - *buffer_number()* Obsolete name for |bufnr()|. - *file_readable()* Obsolete name for |filereadable()|. -- *health#report_error* Use Lua |vim.health.report_error()| instead. -- *health#report_info* Use Lua |vim.health.report_info()| instead. -- *health#report_ok* Use Lua |vim.health.report_ok()| instead. -- *health#report_start* Use Lua |vim.health.report_start()| instead. -- *health#report_warn* Use Lua |vim.health.report_warn()| instead. +- *health#report_error* *vim.health.report_error()* Use |vim.health.error()| instead. +- *health#report_info* *vim.health.report_info()* Use |vim.health.info()| instead. +- *health#report_ok* *vim.health.report_ok()* Use |vim.health.ok()| instead. +- *health#report_start* *vim.health.report_start()* Use |vim.health.start()| instead. +- *health#report_warn* *vim.health.report_warn()* Use |vim.health.warn()| instead. - *highlight_exists()* Obsolete name for |hlexists()|. - *highlightID()* Obsolete name for |hlID()|. - *inputdialog()* Use |input()| instead. @@ -107,20 +117,53 @@ internally and are no longer exposed as part of the API. Instead, use - *vim.lsp.diagnostic.set_virtual_text()* LSP FUNCTIONS -- *vim.lsp.buf.range_code_action()* Use |vim.lsp.buf.code_action()| with - the `range` parameter. -- *vim.lsp.util.diagnostics_to_items()* Use |vim.diagnostic.toqflist()| instead. -- *vim.lsp.util.set_qflist()* Use |setqflist()| instead. -- *vim.lsp.util.set_loclist()* Use |setloclist()| instead. -- *vim.lsp.buf_get_clients()* Use |vim.lsp.get_active_clients()| with - {buffer = bufnr} instead. -- *vim.lsp.buf.formatting()* Use |vim.lsp.buf.format()| with - {async = true} instead. -- *vim.lsp.buf.range_formatting()* Use |vim.lsp.formatexpr()| - or |vim.lsp.buf.format()| instead. +- *vim.lsp.buf.server_ready()* + Use |LspAttach| instead, depending on your use-case. "Server ready" is not + part of the LSP spec, so the Nvim LSP client cannot meaningfully implement + it. "Ready" is ambiguous because: + - Language servers may finish analyzing the workspace, but edits can always + re-trigger analysis/builds. + - Language servers can serve some requests even while processing changes. +- *vim.lsp.buf.range_code_action()* Use |vim.lsp.buf.code_action()| with + the `range` parameter. +- *vim.lsp.util.diagnostics_to_items()* Use |vim.diagnostic.toqflist()| instead. +- *vim.lsp.util.set_qflist()* Use |setqflist()| instead. +- *vim.lsp.util.set_loclist()* Use |setloclist()| instead. +- *vim.lsp.buf_get_clients()* Use |vim.lsp.get_clients()| with + {buffer=bufnr} instead. +- *vim.lsp.buf.formatting()* Use |vim.lsp.buf.format()| with + {async=true} instead. +- *vim.lsp.buf.formatting_sync()* Use |vim.lsp.buf.format()| with + {async=false} instead. +- *vim.lsp.buf.range_formatting()* Use |vim.lsp.formatexpr()| + or |vim.lsp.buf.format()| instead. +- *vim.lsp.util.get_progress_messages()* Use |vim.lsp.status()| or access + `progress` of |vim.lsp.client| +- *vim.lsp.get_active_clients()* Use |vim.lsp.get_clients()| +- *vim.lsp.for_each_buffer_client()* Use |vim.lsp.get_clients()| +- *vim.lsp.util.trim_empty_lines()* Use |vim.split()| with `trimempty` instead. +- *vim.lsp.util.try_trim_markdown_code_blocks()* +- *vim.lsp.util.set_lines()* +- *vim.lsp.util.extract_completion_items()* +- *vim.lsp.util.parse_snippet()* +- *vim.lsp.util.text_document_completion_list_to_complete_items()* + +TREESITTER FUNCTIONS +- *vim.treesitter.language.require_language()* Use |vim.treesitter.language.add()| + instead. +- *vim.treesitter.get_node_at_pos()* Use |vim.treesitter.get_node()| + instead. +- *vim.treesitter.get_node_at_cursor()* Use |vim.treesitter.get_node()| + and |TSNode:type()| instead. +- *vim.treesitter.query.get_query()* Use |vim.treesitter.query.get()| + instead. +- *LanguageTree:for_each_child()* Use |LanguageTree:children()| + (non-recursive) instead. LUA -- *vim.register_keystroke_callback()* Use |vim.on_key()| instead. +- vim.register_keystroke_callback() Use |vim.on_key()| instead. +- *vim.pretty_print()* Use |vim.print()| instead. +- *vim.loop* Use |vim.uv| instead. NORMAL COMMANDS - *]f* *[f* Same as "gf". @@ -137,6 +180,21 @@ OPTIONS - 'viewoptions' Flags "unix", "slash" are ignored and always enabled. - *'viminfo'* Deprecated alias to 'shada' option. - *'viminfofile'* Deprecated alias to 'shadafile' option. +- *'paste'* *'nopaste'* Just Paste It.™ The 'paste' option is obsolete: + |paste| is handled automatically when you paste text + using your terminal's or GUI's paste feature + (CTRL-SHIFT-v, CMD-v (macOS), middle-click, …). + Enables "paste mode": + - Disables mappings in Insert, Cmdline mode. + - Disables abbreviations. + - Resets 'autoindent' 'expandtab' 'revins' 'ruler' + 'showmatch' 'smartindent' 'smarttab' 'softtabstop' + 'textwidth' 'wrapmargin'. + - Treats 'formatoptions' as empty. + - Disables the effect of these options: + - 'cindent' + - 'indentexpr' + - 'lisp' UI EXTENSIONS - *ui-wildmenu* Use |ui-cmdline| with |ui-popupmenu| instead. Enabled @@ -144,6 +202,8 @@ UI EXTENSIONS - `["wildmenu_show", items]` - `["wildmenu_select", selected]` - `["wildmenu_hide"]` +- *term_background* Unused. The terminal background color is now detected + by the Nvim core directly instead of the TUI. VARIABLES - *b:terminal_job_pid* PID of the top-level process in a |:terminal|. diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt index b96b01dbff..cb28f1a845 100644 --- a/runtime/doc/dev_style.txt +++ b/runtime/doc/dev_style.txt @@ -32,19 +32,13 @@ but we nonetheless keep things as they are in order to preserve consistency. Header Files *dev-style-header* -The #define Guard ~ +Header guard ~ -All header files should have `#define` guards to prevent multiple inclusion. -The format of the symbol name should be `NVIM_<DIRECTORY>_<FILE>_H`. +All header files should start with `#pragma once` to prevent multiple inclusion. In foo/bar.h: >c - #ifndef NVIM_FOO_BAR_H - #define NVIM_FOO_BAR_H - - ... - - #endif // NVIM_FOO_BAR_H + #pragma once < @@ -245,15 +239,13 @@ contain only non-static function declarations. >c // src/nvim/foo.h file - #ifndef NVIM_FOO_H - #define NVIM_FOO_H + #pragma once … #ifdef INCLUDE_GENERATED_DECLARATIONS # include "foo.h.generated.h" #endif - #endif // NVIM_FOO_H 64-bit Portability ~ @@ -846,7 +838,7 @@ Annotate non-trivial fall-through between cases. 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`: >c +execute, simply use `abort()`: >c switch (var) { case 0: @@ -856,8 +848,54 @@ execute, simply `assert`: >c ... break; default: - assert(false); + abort(); + } + +Switch statements that are conditional on an enumerated value should not have +a `default` case if it is exhaustive. Explicit case labels are preferred over +`default`, even if it leads to multiple case labels for the same code. For +example, instead of: >c + + case A: + ... + case B: + ... + case C: + ... + default: + ... + +You should use: >c + + case A: + ... + case B: + ... + case C: + ... + case D: + case E: + case F: + ... + +Certain compilers do not recognize an exhaustive enum switch statement as +exhaustive, which causes compiler warnings when there is a return statement in +every case of a switch statement, but no catch-all return statement. To fix +these spurious errors, you are advised to use `UNREACHABLE` after the switch +statement to explicitly tell the compiler that the switch statement always +returns and any code after it is unreachable. For example: >c + + enum { A, B, C } var; + ... + switch (var) { + case A: + return 1; + case B: + return 2; + case C: + return 3; } + UNREACHABLE; Return Values ~ diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index ff48ae3e26..f1d74326c7 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -81,7 +81,7 @@ include the kitchen sink... but it's good for plumbing." Developer guidelines *dev-guidelines* -PROVIDERS *dev-provider* +PROVIDERS *dev-provider* A primary goal of Nvim is to allow extension of the editor without special knowledge in the core. Some core functions are delegated to "providers" @@ -99,8 +99,8 @@ Examples: scripting is performed by an external host process implemented in ~2k lines of Python. -The provider framework invokes VimL from C. It is composed of two functions -in eval.c: +The provider framework invokes Vimscript from C. It is composed of two +functions in eval.c: - eval_call_provider(name, method, arguments, discard): calls provider#{name}#Call with the method and arguments. If discard is true, any @@ -130,8 +130,24 @@ DOCUMENTATION *dev-doc* (docstrings, user manual, website materials, newsletters, …). Don't mince words. Personality and flavor, used sparingly, are welcome--but in general, optimize for the reader's time and energy: be "precise yet concise". - - See https://developers.google.com/style/tone - Prefer the active voice: "Foo does X", not "X is done by Foo". + - "The words you choose are an essential part of the user experience." + https://developer.apple.com/design/human-interface-guidelines/writing + - "...without being overly colloquial or frivolous." + https://developers.google.com/style/tone +- Write docstrings (as opposed to inline comments) with present tense ("Gets"), + not imperative ("Get"). This tends to reduce ambiguity and improve clarity + by describing "What" instead of "How". > + GOOD: + /// Gets a highlight definition. + BAD: + /// Get a highlight definition. +- Avoid starting docstrings with "The" or "A" unless needed to avoid + ambiguity. This is a visual aid and reduces noise. > + GOOD: + /// @param dirname Path fragment before `pend` + BAD: + /// @param dirname The path fragment before `pend` - Vim differences: - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog differences from Vim; no other distinction is necessary. @@ -143,13 +159,6 @@ DOCUMENTATION *dev-doc* not "the user host terminal". - Use "tui-" to prefix help tags related to the host terminal, and "TUI" in prose if possible. -- Docstrings: do not start parameter descriptions with "The" or "A" unless it - is critical to avoid ambiguity. > - GOOD: - /// @param dirname Path fragment before `pend` - BAD: - /// @param dirname The path fragment before `pend` -< Documentation format ~ @@ -159,14 +168,14 @@ https://neovim.io/doc/user ). Strict "vimdoc" subset: -- Use lists (like this!) prefixed with "-", "*", or "•", for adjacent lines - that you don't want auto-wrapped. Lists are always rendered with "flow" - (soft-wrapped) layout instead of preformatted (hard-wrapped) layout common - in legacy :help docs. +- Use lists (like this!) prefixed with "-" or "•", for adjacent lines that you + don't want to auto-wrap. Lists are always rendered with "flow" layout + (soft-wrapped) instead of preformatted (hard-wrapped) layout common in + legacy :help docs. - Limitation: currently the parser https://github.com/neovim/tree-sitter-vimdoc does not understand numbered listitems, so use a bullet symbol (- or •) - before numbered items, e.g. "- 1." instead of "1.". -- Separate blocks (paragraphs) of content by a blank line(s). + before numbered items, e.g. "• 1." instead of "1.". +- Separate blocks (paragraphs) of content by a blank line. - Do not use indentation in random places—that prevents the page from using "flow" layout. If you need a preformatted section, put it in a |help-codeblock| starting with ">". @@ -183,7 +192,7 @@ Docstring format: `@note`, `@param`, `@returns` - Limited markdown is supported. - List-items start with `-` (useful to nest or "indent") -- Use `<pre>` for code samples. +- Use ``` for code samples. Code samples can be annotated as `vim` or `lua` Example: the help for |nvim_open_win()| is generated from a docstring defined @@ -193,10 +202,16 @@ in src/nvim/api/win_config.c like this: > /// ... /// /// Example (Lua): window-relative float - /// <pre>lua - /// vim.api.nvim_open_win(0, false, - /// {relative='win', row=3, col=3, width=12, height=3}) - /// </pre> + /// + /// ```lua + /// vim.api.nvim_open_win(0, false, { + /// relative='win', + /// row=3, + /// col=3, + /// width=12, + /// height=3, + /// }) + /// ``` /// /// @param buffer Buffer to display /// @param enter Enter the window @@ -217,13 +232,13 @@ Lua documentation lives in the source code, as docstrings on the function definitions. The |lua-vim| :help is generated from the docstrings. Docstring format: -- Lines in the main description start with `---` -- Special tokens start with `---@` followed by the token name: - `---@see`, `---@param`, `---@returns` +- Use LuaCATS annotations: https://luals.github.io/wiki/annotations/ - Limited markdown is supported. - List-items start with `-` (useful to nest or "indent") -- Use `<pre>` for code samples. +- Use ``` for code samples. Code samples can be annotated as `vim` or `lua` +- Use `@nodoc` to prevent documentation generation. +- Files which has `@meta` are only used for typing and documentation. Example: the help for |vim.paste()| is generated from a docstring decorating vim.paste in runtime/lua/vim/_editor.lua like this: > @@ -232,21 +247,24 @@ vim.paste in runtime/lua/vim/_editor.lua like this: > --- (such as the |TUI|) pastes text into the editor. --- --- Example: To remove ANSI color codes when pasting: - --- <pre>lua + --- + --- ```lua --- vim.paste = (function() --- local overridden = vim.paste --- ... --- end)() - --- </pre> + --- ``` --- - ---@see |paste| + --- @see |paste| --- - ---@param lines ... - ---@param phase ... - ---@returns false if client should cancel the paste. + --- @param lines ... + --- @param phase ... + --- @returns false if client should cancel the paste. + +LUA STDLIB DESIGN GUIDELINES *dev-lua* -LUA *dev-lua* +See also |dev-naming|. - Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or pseudo-OOP designs. Plugin authors just want functions to call, not a big, @@ -255,10 +273,38 @@ LUA *dev-lua* tables or values are easier to serialize, easier to construct from literals, easier to inspect and print, and inherently compatible with all Lua plugins. (This guideline doesn't apply to opaque, non-data objects like `vim.cmd`.) +- stdlib functions should follow these common patterns: + - accept iterable instead of table + - exception: in some cases iterable doesn't make sense, e.g. spair() sorts + the input by definition, so there is no reason for it to accept an + iterable, because the input needs to be "hydrated", it can't operate on + a "stream". + - return iterable instead of table + - mimic the pairs() or ipairs() interface if the function is intended to be + used in a "for" loop. + +Interface conventions ~ + +- When accepting a buffer id, etc., 0 means "current buffer", nil means "all + buffers". Likewise for window id, tabpage id, etc. + - Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()| +- Any function signature that accepts a callback function should define the + callback as the LAST parameter, if possible. This improves readability of + calls by placing the less "noisy" arguments near the start. > + GOOD: + filter(table, opts, function() … end) + BAD: + filter(function() … end, table, opts) +API DESIGN GUIDELINES *dev-api* -API *dev-api* +See also |dev-naming|. +- When adding an API, check the following: + - What precedents did you draw from? How does your solution compare to them? + - Does your new API allow future expansion? How? Or why not? + - Is the new API similar to existing APIs? Do we need to deprecate the old ones? + - Did you cross-reference related concepts in the docs? - Avoid "mutually exclusive" parameters--via constraints or limitations, if necessary. For example nvim_create_autocmd() has mutually exclusive "callback" and "command" args; but the "command" arg could be eliminated by @@ -266,66 +312,102 @@ API *dev-api* "callback" arg as an Ex command (which can call Vimscript functions). The "buffer" arg could also be eliminated by treating a number "pattern" as a buffer number. +- Avoid functions that depend on cursor position, current buffer, etc. Instead + the function should take a position parameter, buffer parameter, etc. - *dev-api-naming* -Use this format to name new RPC |API| functions: +Where things go ~ - nvim_{thing}_{action}_{arbitrary-qualifiers} +- API (libnvim/RPC): exposes low-level internals, or fundamental things (such + as `nvim_exec_lua()`) needed by clients or C consumers. +- Lua stdlib = high-level functionality that builds on top of the API. -If the function acts on an object then {thing} is the name of that object -(e.g. "buf" or "win"). If the function operates in a "global" context then -{thing} is usually omitted (but consider "namespacing" your global operations -with a {thing} that groups functions under a common concept). - -Use existing common {action} names if possible: - - add Append to, or insert into, a collection - - call Call a function - - create Create a new (non-trivial) thing - - del Delete a thing (or group of things) - - eval Evaluate an expression - - exec Execute code - - fmt Format - - get Get things (often by a query) - - open Open - - parse Parse something into a structured form - - set Set a thing (or group of things) +NAMING GUIDELINES *dev-naming* + +Naming is exceedingly important: the name of a thing is the primary interface +for uses it, discusses it, searches for it, shares it... Consistent +naming in the stdlib, API, and UI helps both users and developers discover and +intuitively understand related concepts ("families"), and reduces cognitive +burden. Discoverability encourages code re-use and likewise avoids redundant, +overlapping mechanisms, which reduces code surface-area, and thereby minimizes +bugs... + +Naming conventions ~ + +In general, look for precedent when choosing a name, that is, look at existing +(non-deprecated) functions. In particular, see below... + + *dev-name-common* +Use existing common {verb} names (actions) if possible: + - add: Appends or inserts into a collection + - attach: Listens to something to get events from it (TODO: rename to "on"?) + - call: Calls a function + - clear: Clears state but does not destroy the container + - create: Creates a new (non-trivial) thing (TODO: rename to "def"?) + - del: Deletes a thing (or group of things) + - detach: Dispose attached listener (TODO: rename to "un"?) + - eval: Evaluates an expression + - exec: Executes code + - fmt: Formats + - get: Gets things (often by a query) + - inspect: Presents a high-level, often interactive, view + - open: Opens something (a buffer, window, …) + - parse: Parses something into a structured form + - set: Sets a thing (or group of things) + - try_{verb}: Best-effort operation, failure returns null or error obj Do NOT use these deprecated verbs: - - list Redundant with "get" + - list: Redundant with "get" + - show: Redundant with "print", "echo" + - notify: Redundant with "print", "echo" -Use consistent names for {thing} (nouns) in API functions: buffer is called +Use consistent names for {noun} (nouns) in API functions: buffer is called "buf" everywhere, not "buffer" in some places and "buf" in others. - - buf Buffer - - chan |channel| - - cmd Command - - cmdline Command-line UI or input - - fn Function - - hl Highlight - - pos Position - - proc System process - - tabpage Tabpage - - win Window + - buf: Buffer + - chan: |channel| + - cmd: Command + - cmdline: Command-line UI or input + - fn: Function + - hl: Highlight + - pos: Position + - proc: System process + - tabpage: Tabpage + - win: Window Do NOT use these deprecated nouns: - buffer + - callback Use on_foo instead - command - window -Example: - `nvim_get_keymap('v')` operates in a global context (first parameter is not - a Buffer). The "get" {action} indicates that it gets anything matching the - given filter parameter. There is no need for a "list" action because - `nvim_get_keymap('')` (i.e., empty filter) returns all items. + *dev-name-events* +Use the "on_" prefix to name event-handling callbacks and also the interface for +"registering" such handlers (on_key). The dual nature is acceptable to avoid +a confused collection of naming conventions for these related concepts. -Example: - `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter) - and uses the "del" {action}. +Editor |events| (autocommands) are historically named like: > + {Noun}{Event} -Use this format to name new API events: - nvim_{thing}_{event}_event +Use this format to name API (RPC) events: > + nvim_{noun}_{event-name}_event + +Example: > + nvim_buf_changedtick_event +< + *dev-name-api* +Use this format to name new RPC |API| functions: > + nvim_{noun}_{verb}_{arbitrary-qualifiers} + +If the function acts on an object then {noun} is the name of that object +(e.g. "buf" or "win"). If the function operates in a "global" context then +{noun} is usually omitted (but consider "namespacing" your global operations +with a {noun} that groups functions under a common concept). -Example: - `nvim_buf_changedtick_event` +- Example: `nvim_get_keymap('v')` operates in a global context (first + parameter is not a Buffer). The "get" verb indicates that it gets anything + matching the given filter parameter. A "list" verb is unnecessary because + `nvim_get_keymap('')` (empty filter) returns all items. +- Example: `nvim_buf_del_mark` acts on a `Buffer` object (the first parameter) + and uses the "del" {verb}. API-CLIENT *dev-api-client* @@ -366,7 +448,7 @@ Examples of API-client package names: - GOOD: nvim-racket - GOOD: pynvim - BAD: python-client -- BAD: neovim +- BAD: neovim_ API client implementation guidelines ~ @@ -391,7 +473,7 @@ API client implementation guidelines ~ https://github.com/msgpack-rpc/msgpack-rpc -EXTERNAL UI *dev-ui* +EXTERNAL UI *dev-ui* External UIs should be aware of the |api-contract|. In particular, future versions of Nvim may add new items to existing events. The API is strongly @@ -415,21 +497,8 @@ External UIs are expected to implement these common features: - Consider the "option_set" |ui-global| event as a hint for other GUI behaviors. Various UI-related options ('guifont', 'ambiwidth', …) are published in this event. See also "mouse_on", "mouse_off". - - -NAMING *dev-naming* - -Naming is important. Consistent naming in the API and UI helps both users and -developers discover and intuitively understand related concepts ("families"), -and reduces cognitive burden. Discoverability encourages code re-use and -likewise avoids redundant, overlapping mechanisms, which reduces code -surface-area, and thereby minimizes bugs... - -Naming conventions ~ - -Use the "on_" prefix to name event handlers and also the interface for -"registering" such handlers (on_key). The dual nature is acceptable to avoid -a confused collection of naming conventions for these related concepts. +- UIs generally should NOT set |$NVIM_APPNAME| (unless explicitly requested by + the user). vim:tw=78:ts=8:sw=4:et:ft=help:norl: diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt index 7066a3739a..7f5c809ac3 100644 --- a/runtime/doc/diagnostic.txt +++ b/runtime/doc/diagnostic.txt @@ -40,15 +40,15 @@ requires a namespace. *diagnostic-structure* A diagnostic is a Lua table with the following keys. Required keys are -indicated with (*): +indicated with (+): bufnr: Buffer number - lnum(*): The starting line of the diagnostic + lnum(+): The starting line of the diagnostic end_lnum: The final line of the diagnostic - col(*): The starting column of the diagnostic + col(+): The starting column of the diagnostic end_col: The final column of the diagnostic severity: The severity of the diagnostic |vim.diagnostic.severity| - message(*): The diagnostic text + message(+): The diagnostic text source: The source of the diagnostic code: The diagnostic code user_data: Arbitrary data plugins or users can add @@ -66,7 +66,7 @@ The "severity" key in a diagnostic is one of the values defined in vim.diagnostic.severity.HINT Functions that take a severity as an optional parameter (e.g. -|vim.diagnostic.get()|) accept one of two forms: +|vim.diagnostic.get()|) accept one of three forms: 1. A single |vim.diagnostic.severity| value: >lua @@ -75,8 +75,17 @@ Functions that take a severity as an optional parameter (e.g. 2. A table with a "min" or "max" key (or both): >lua vim.diagnostic.get(0, { severity = { min = vim.diagnostic.severity.WARN } }) +< + This form allows users to specify a range of severities. + +3. A list-like table: >lua -The latter form allows users to specify a range of severities. + vim.diagnostic.get(0, { severity = { + vim.diagnostic.severity.WARN, + vim.diagnostic.severity.INFO, + } }) +< + This form allows users to filter for specific severities ============================================================================== HANDLERS *diagnostic-handlers* @@ -295,6 +304,14 @@ DiagnosticSignHint DiagnosticSignOk Used for "Ok" signs in sign column. + *hl-DiagnosticDeprecated* +DiagnosticDeprecated + Used for deprecated or obsolete code. + + *hl-DiagnosticUnnecessary* +DiagnosticUnnecessary + Used for unnecessary or unused code. + ============================================================================== SIGNS *diagnostic-signs* @@ -325,7 +342,7 @@ Example: >lua vim.api.nvim_create_autocmd('DiagnosticChanged', { callback = function(args) local diagnostics = args.data.diagnostics - vim.pretty_print(diagnostics) + vim.print(diagnostics) end, }) < @@ -342,19 +359,17 @@ config({opts}, {namespace}) *vim.diagnostic.config()* followed by namespace configuration, and finally global configuration. For example, if a user enables virtual text globally with >lua - - vim.diagnostic.config({ virtual_text = true }) + vim.diagnostic.config({ virtual_text = true }) < and a diagnostic producer sets diagnostics with >lua - - vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false }) + 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: + 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. Use an empty table to @@ -374,7 +389,10 @@ config({opts}, {namespace}) *vim.diagnostic.config()* • virtual_text: (default true) Use virtual text for diagnostics. If multiple diagnostics are set for a namespace, one prefix per diagnostic + the last - diagnostic message are shown. Options: + diagnostic message are shown. In addition to the + options listed below, the "virt_text" options of + |nvim_buf_set_extmark()| may also be used here (e.g. + "virt_text_pos" and "hl_mode"). Options: • severity: Only show virtual text for diagnostics matching the given severity |diagnostic-severity| • source: (boolean or string) Include the diagnostic @@ -384,8 +402,14 @@ config({opts}, {namespace}) *vim.diagnostic.config()* always show the diagnostic source. • spacing: (number) Amount of empty spaces inserted at the beginning of the virtual text. - • prefix: (string) Prepend diagnostic message with - prefix. + • prefix: (string or function) prepend diagnostic + message with prefix. If a function, it must have the + signature (diagnostic, i, total) -> string, where + {diagnostic} is of type |diagnostic-structure|, {i} + is the index of the diagnostic being evaluated, and + {total} is the total number of diagnostics for the + line. This can be used to render diagnostic symbols + or error codes. • suffix: (string or function) Append diagnostic message with suffix. If a function, it must have the signature (diagnostic) -> string, where {diagnostic} @@ -423,32 +447,32 @@ config({opts}, {namespace}) *vim.diagnostic.config()* severities are displayed before lower severities (e.g. ERROR is displayed before WARN). Options: • reverse: (boolean) Reverse sort order - • {namespace} (number|nil) Update the options for the given namespace. + • {namespace} (integer|nil) Update the options for the given namespace. When omitted, update the global diagnostic options. disable({bufnr}, {namespace}) *vim.diagnostic.disable()* Disable diagnostics in the given buffer. Parameters: ~ - • {bufnr} (number|nil) Buffer number, or 0 for current buffer. When - omitted, disable diagnostics in all buffers. - • {namespace} (number|nil) Only disable diagnostics for the given + • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. + When omitted, disable diagnostics in all buffers. + • {namespace} (integer|nil) Only disable diagnostics for the given namespace. enable({bufnr}, {namespace}) *vim.diagnostic.enable()* Enable diagnostics in the given buffer. Parameters: ~ - • {bufnr} (number|nil) Buffer number, or 0 for current buffer. When - omitted, enable diagnostics in all buffers. - • {namespace} (number|nil) Only enable diagnostics for the given + • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. + When omitted, enable diagnostics in all buffers. + • {namespace} (integer|nil) Only enable diagnostics for the given namespace. fromqflist({list}) *vim.diagnostic.fromqflist()* Convert a list of quickfix items to a list of diagnostics. Parameters: ~ - • {list} (table) A list of quickfix items from |getqflist()| or + • {list} table[] List of quickfix items from |getqflist()| or |getloclist()|. Return: ~ @@ -457,9 +481,12 @@ fromqflist({list}) *vim.diagnostic.fromqflist()* get({bufnr}, {opts}) *vim.diagnostic.get()* Get current diagnostics. + Modifying diagnostics in the returned table has no effect. To set + diagnostics in a buffer, use |vim.diagnostic.set()|. + Parameters: ~ - • {bufnr} (number|nil) Buffer number to get diagnostics from. Use 0 for - current buffer or nil for all buffers. + • {bufnr} (integer|nil) Buffer number to get diagnostics from. Use 0 + for current buffer or nil for all buffers. • {opts} (table|nil) A table with the following keys: • namespace: (number) Limit diagnostics to the given namespace. @@ -467,13 +494,13 @@ get({bufnr}, {opts}) *vim.diagnostic.get()* • severity: See |diagnostic-severity|. Return: ~ - Diagnostic [] table A list of diagnostic items |diagnostic-structure|. + Diagnostic [] table A list of diagnostic items |diagnostic-structure|. Keys `bufnr` , `end_lnum` , `end_col` , and `severity` are guaranteed to be present. get_namespace({namespace}) *vim.diagnostic.get_namespace()* Get namespace metadata. Parameters: ~ - • {namespace} (number) Diagnostic namespace + • {namespace} (integer) Diagnostic namespace Return: ~ (table) Namespace metadata @@ -560,17 +587,17 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()* |vim.diagnostic.disable()|. Parameters: ~ - • {namespace} (number|nil) Diagnostic namespace. When omitted, hide diagnostics from all + • {namespace} (integer|nil) Diagnostic namespace. When omitted, hide diagnostics from all namespaces. - • {bufnr} (number|nil) Buffer number, or 0 for current buffer. When - omitted, hide diagnostics in all buffers. + • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. + When omitted, hide diagnostics in all buffers. is_disabled({bufnr}, {namespace}) *vim.diagnostic.is_disabled()* Check whether diagnostics are disabled in a given buffer. Parameters: ~ - • {bufnr} (number|nil) Buffer number, or 0 for current buffer. - • {namespace} (number|nil) Diagnostic namespace. When omitted, checks if all diagnostics are + • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. + • {namespace} (integer|nil) Diagnostic namespace. When omitted, checks if all diagnostics are disabled in {bufnr}. Otherwise, only checks if diagnostics from {namespace} are disabled. @@ -582,16 +609,14 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults}) Parse a diagnostic from a string. For example, consider a line of output from a linter: > - - WARNING filename:27:3: Variable 'foo' does not exist + WARNING filename:27:3: Variable 'foo' does not exist < This can be parsed into a diagnostic |diagnostic-structure| with: >lua - - local s = "WARNING filename:27:3: Variable 'foo' does not exist" - local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" - local groups = { "severity", "lnum", "col", "message" } - vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN }) + local s = "WARNING filename:27:3: Variable 'foo' does not exist" + local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$" + local groups = { "severity", "lnum", "col", "message" } + vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN }) < Parameters: ~ @@ -663,7 +688,7 @@ open_float({opts}, {...}) *vim.diagnostic.open_float()* from |vim.diagnostic.config()|. Return: ~ - number|nil, number|nil: ({float_bufnr}, {win_id}) + integer|nil, integer|nil: ({float_bufnr}, {win_id}) reset({namespace}, {bufnr}) *vim.diagnostic.reset()* Remove all diagnostics from the given namespace. @@ -674,17 +699,17 @@ reset({namespace}, {bufnr}) *vim.diagnostic.reset()* re-displayed, use |vim.diagnostic.hide()|. Parameters: ~ - • {namespace} (number|nil) Diagnostic namespace. When omitted, remove diagnostics from all + • {namespace} (integer|nil) Diagnostic namespace. When omitted, remove diagnostics from all namespaces. - • {bufnr} (number|nil) Remove diagnostics for the given buffer. + • {bufnr} (integer|nil) Remove diagnostics for the given buffer. When omitted, diagnostics are removed for all buffers. set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()* Set diagnostics for the given namespace and buffer. Parameters: ~ - • {namespace} (number) The diagnostic namespace - • {bufnr} (number) Buffer number + • {namespace} (integer) The diagnostic namespace + • {bufnr} (integer) Buffer number • {diagnostics} (table) A list of diagnostic items |diagnostic-structure| • {opts} (table|nil) Display options to pass to @@ -723,9 +748,9 @@ show({namespace}, {bufnr}, {diagnostics}, {opts}) Display diagnostics for the given namespace and buffer. Parameters: ~ - • {namespace} (number|nil) Diagnostic namespace. When omitted, show diagnostics from all + • {namespace} (integer|nil) Diagnostic namespace. When omitted, show diagnostics from all namespaces. - • {bufnr} (number|nil) Buffer number, or 0 for current buffer. + • {bufnr} (integer|nil) Buffer number, or 0 for current buffer. When omitted, show diagnostics in all buffers. • {diagnostics} (table|nil) The diagnostics to display. When omitted, use the saved diagnostics for the given namespace and diff --git a/runtime/doc/diff.txt b/runtime/doc/diff.txt index 382d025d3c..2f174a404e 100644 --- a/runtime/doc/diff.txt +++ b/runtime/doc/diff.txt @@ -125,7 +125,7 @@ file for a moment and come back to the same file and be in diff mode again. buffers. The `:diffoff` command resets the relevant options to the values they had when -using `:diffsplit`, `:diffpatch` , `:diffthis`. or starting Vim in diff mode. +using `:diffsplit`, `:diffpatch`, `:diffthis`. or starting Vim in diff mode. When using `:diffoff` twice the last saved values are restored. Otherwise they are set to their default value: @@ -396,7 +396,9 @@ If the 'diffexpr' expression starts with s: or |<SID>|, then it is replaced with the script ID (|local-function|). Example: > set diffexpr=s:MyDiffExpr() set diffexpr=<SID>SomeDiffExpr() -< +Otherwise, the expression is evaluated in the context of the script where the +option was set, thus script-local items are available. + *E810* *E97* Vim will do a test if the diff output looks alright. If it doesn't, you will get an error message. Possible causes: @@ -452,5 +454,8 @@ If the 'patchexpr' expression starts with s: or |<SID>|, then it is replaced with the script ID (|local-function|). Example: > set patchexpr=s:MyPatchExpr() set patchexpr=<SID>SomePatchExpr() -< +Otherwise, the expression is evaluated in the context of the script where the +option was set, thus script-local items are available. + + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/digraph.txt b/runtime/doc/digraph.txt index ce0a929bc1..1e91e5e4b8 100644 --- a/runtime/doc/digraph.txt +++ b/runtime/doc/digraph.txt @@ -168,1312 +168,1322 @@ ROUBLE The rouble sign was added in 2014 as 0x20bd. Vim supports the digraphs =R and =P for this. Note that R= and P= are other characters. +QUADRUPLE PRIME + +The quadruple prime using the digraph 4' was added in 2023. Although it is +not part of RFC 1345, it supplements the existing digraph implementation as +there already exist digraphs for PRIME, DOUBLE PRIME and TRIPLE PRIME using +the 1', 2' and 3' digraphs. + *digraph-table* *digraph-table-mbyte* -char digraph hex dec official name ~ -^@ NU 0x00 0 NULL (NUL) -^A SH 0x01 1 START OF HEADING (SOH) -^B SX 0x02 2 START OF TEXT (STX) -^C EX 0x03 3 END OF TEXT (ETX) -^D ET 0x04 4 END OF TRANSMISSION (EOT) -^E EQ 0x05 5 ENQUIRY (ENQ) -^F AK 0x06 6 ACKNOWLEDGE (ACK) -^G BL 0x07 7 BELL (BEL) -^H BS 0x08 8 BACKSPACE (BS) -^I HT 0x09 9 CHARACTER TABULATION (HT) -^@ LF 0x0a 10 LINE FEED (LF) -^K VT 0x0b 11 LINE TABULATION (VT) -^L FF 0x0c 12 FORM FEED (FF) -^M CR 0x0d 13 CARRIAGE RETURN (CR) -^N SO 0x0e 14 SHIFT OUT (SO) -^O SI 0x0f 15 SHIFT IN (SI) -^P DL 0x10 16 DATALINK ESCAPE (DLE) -^Q D1 0x11 17 DEVICE CONTROL ONE (DC1) -^R D2 0x12 18 DEVICE CONTROL TWO (DC2) -^S D3 0x13 19 DEVICE CONTROL THREE (DC3) -^T D4 0x14 20 DEVICE CONTROL FOUR (DC4) -^U NK 0x15 21 NEGATIVE ACKNOWLEDGE (NAK) -^V SY 0x16 22 SYNCHRONOUS IDLE (SYN) -^W EB 0x17 23 END OF TRANSMISSION BLOCK (ETB) -^X CN 0x18 24 CANCEL (CAN) -^Y EM 0x19 25 END OF MEDIUM (EM) -^Z SB 0x1a 26 SUBSTITUTE (SUB) -^[ EC 0x1b 27 ESCAPE (ESC) -^\ FS 0x1c 28 FILE SEPARATOR (IS4) -^] GS 0x1d 29 GROUP SEPARATOR (IS3) -^^ RS 0x1e 30 RECORD SEPARATOR (IS2) -^_ US 0x1f 31 UNIT SEPARATOR (IS1) +> + char digraph hex dec official name + ^@ NU 0x00 0 NULL (NUL) + ^A SH 0x01 1 START OF HEADING (SOH) + ^B SX 0x02 2 START OF TEXT (STX) + ^C EX 0x03 3 END OF TEXT (ETX) + ^D ET 0x04 4 END OF TRANSMISSION (EOT) + ^E EQ 0x05 5 ENQUIRY (ENQ) + ^F AK 0x06 6 ACKNOWLEDGE (ACK) + ^G BL 0x07 7 BELL (BEL) + ^H BS 0x08 8 BACKSPACE (BS) + ^I HT 0x09 9 CHARACTER TABULATION (HT) + ^@ LF 0x0a 10 LINE FEED (LF) + ^K VT 0x0b 11 LINE TABULATION (VT) + ^L FF 0x0c 12 FORM FEED (FF) + ^M CR 0x0d 13 CARRIAGE RETURN (CR) + ^N SO 0x0e 14 SHIFT OUT (SO) + ^O SI 0x0f 15 SHIFT IN (SI) + ^P DL 0x10 16 DATALINK ESCAPE (DLE) + ^Q D1 0x11 17 DEVICE CONTROL ONE (DC1) + ^R D2 0x12 18 DEVICE CONTROL TWO (DC2) + ^S D3 0x13 19 DEVICE CONTROL THREE (DC3) + ^T D4 0x14 20 DEVICE CONTROL FOUR (DC4) + ^U NK 0x15 21 NEGATIVE ACKNOWLEDGE (NAK) + ^V SY 0x16 22 SYNCHRONOUS IDLE (SYN) + ^W EB 0x17 23 END OF TRANSMISSION BLOCK (ETB) + ^X CN 0x18 24 CANCEL (CAN) + ^Y EM 0x19 25 END OF MEDIUM (EM) + ^Z SB 0x1a 26 SUBSTITUTE (SUB) + ^[ EC 0x1b 27 ESCAPE (ESC) + ^\ FS 0x1c 28 FILE SEPARATOR (IS4) + ^] GS 0x1d 29 GROUP SEPARATOR (IS3) + ^^ RS 0x1e 30 RECORD SEPARATOR (IS2) + ^_ US 0x1f 31 UNIT SEPARATOR (IS1) SP 0x20 32 SPACE -# Nb 0x23 35 NUMBER SIGN -$ DO 0x24 36 DOLLAR SIGN -@ At 0x40 64 COMMERCIAL AT -[ <( 0x5b 91 LEFT SQUARE BRACKET -\ // 0x5c 92 REVERSE SOLIDUS -] )> 0x5d 93 RIGHT SQUARE BRACKET -^ '> 0x5e 94 CIRCUMFLEX ACCENT -` '! 0x60 96 GRAVE ACCENT -{ (! 0x7b 123 LEFT CURLY BRACKET -| !! 0x7c 124 VERTICAL LINE -} !) 0x7d 125 RIGHT CURLY BRACKET -~ '? 0x7e 126 TILDE -^? DT 0x7f 127 DELETE (DEL) -~@ PA 0x80 128 PADDING CHARACTER (PAD) -~A HO 0x81 129 HIGH OCTET PRESET (HOP) -~B BH 0x82 130 BREAK PERMITTED HERE (BPH) -~C NH 0x83 131 NO BREAK HERE (NBH) -~D IN 0x84 132 INDEX (IND) -~E NL 0x85 133 NEXT LINE (NEL) -~F SA 0x86 134 START OF SELECTED AREA (SSA) -~G ES 0x87 135 END OF SELECTED AREA (ESA) -~H HS 0x88 136 CHARACTER TABULATION SET (HTS) -~I HJ 0x89 137 CHARACTER TABULATION WITH JUSTIFICATION (HTJ) -~J VS 0x8a 138 LINE TABULATION SET (VTS) -~K PD 0x8b 139 PARTIAL LINE FORWARD (PLD) -~L PU 0x8c 140 PARTIAL LINE BACKWARD (PLU) -~M RI 0x8d 141 REVERSE LINE FEED (RI) -~N S2 0x8e 142 SINGLE-SHIFT TWO (SS2) -~O S3 0x8f 143 SINGLE-SHIFT THREE (SS3) -~P DC 0x90 144 DEVICE CONTROL STRING (DCS) -~Q P1 0x91 145 PRIVATE USE ONE (PU1) -~R P2 0x92 146 PRIVATE USE TWO (PU2) -~S TS 0x93 147 SET TRANSMIT STATE (STS) -~T CC 0x94 148 CANCEL CHARACTER (CCH) -~U MW 0x95 149 MESSAGE WAITING (MW) -~V SG 0x96 150 START OF GUARDED AREA (SPA) -~W EG 0x97 151 END OF GUARDED AREA (EPA) -~X SS 0x98 152 START OF STRING (SOS) -~Y GC 0x99 153 SINGLE GRAPHIC CHARACTER INTRODUCER (SGCI) -~Z SC 0x9a 154 SINGLE CHARACTER INTRODUCER (SCI) -~[ CI 0x9b 155 CONTROL SEQUENCE INTRODUCER (CSI) -~\ ST 0x9c 156 STRING TERMINATOR (ST) -~] OC 0x9d 157 OPERATING SYSTEM COMMAND (OSC) -~^ PM 0x9e 158 PRIVACY MESSAGE (PM) -~_ AC 0x9f 159 APPLICATION PROGRAM COMMAND (APC) -| NS 0xa0 160 NO-BREAK SPACE -¡ !I 0xa1 161 INVERTED EXCLAMATION MARK -¢ Ct 0xa2 162 CENT SIGN -£ Pd 0xa3 163 POUND SIGN -¤ Cu 0xa4 164 CURRENCY SIGN -¥ Ye 0xa5 165 YEN SIGN -¦ BB 0xa6 166 BROKEN BAR -§ SE 0xa7 167 SECTION SIGN -¨ ': 0xa8 168 DIAERESIS -© Co 0xa9 169 COPYRIGHT SIGN -ª -a 0xaa 170 FEMININE ORDINAL INDICATOR -« << 0xab 171 LEFT-POINTING DOUBLE ANGLE QUOTATION MARK -¬ NO 0xac 172 NOT SIGN - -- 0xad 173 SOFT HYPHEN -® Rg 0xae 174 REGISTERED SIGN -¯ 'm 0xaf 175 MACRON -° DG 0xb0 176 DEGREE SIGN -± +- 0xb1 177 PLUS-MINUS SIGN -² 2S 0xb2 178 SUPERSCRIPT TWO -³ 3S 0xb3 179 SUPERSCRIPT THREE -´ '' 0xb4 180 ACUTE ACCENT -µ My 0xb5 181 MICRO SIGN -¶ PI 0xb6 182 PILCROW SIGN -· .M 0xb7 183 MIDDLE DOT -¸ ', 0xb8 184 CEDILLA -¹ 1S 0xb9 185 SUPERSCRIPT ONE -º -o 0xba 186 MASCULINE ORDINAL INDICATOR -» >> 0xbb 187 RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK -¼ 14 0xbc 188 VULGAR FRACTION ONE QUARTER -½ 12 0xbd 189 VULGAR FRACTION ONE HALF -¾ 34 0xbe 190 VULGAR FRACTION THREE QUARTERS -¿ ?I 0xbf 191 INVERTED QUESTION MARK -À A! 0xc0 192 LATIN CAPITAL LETTER A WITH GRAVE -Á A' 0xc1 193 LATIN CAPITAL LETTER A WITH ACUTE - A> 0xc2 194 LATIN CAPITAL LETTER A WITH CIRCUMFLEX -à A? 0xc3 195 LATIN CAPITAL LETTER A WITH TILDE -Ä A: 0xc4 196 LATIN CAPITAL LETTER A WITH DIAERESIS -Å AA 0xc5 197 LATIN CAPITAL LETTER A WITH RING ABOVE -Æ AE 0xc6 198 LATIN CAPITAL LETTER AE -Ç C, 0xc7 199 LATIN CAPITAL LETTER C WITH CEDILLA -È E! 0xc8 200 LATIN CAPITAL LETTER E WITH GRAVE -É E' 0xc9 201 LATIN CAPITAL LETTER E WITH ACUTE -Ê E> 0xca 202 LATIN CAPITAL LETTER E WITH CIRCUMFLEX -Ë E: 0xcb 203 LATIN CAPITAL LETTER E WITH DIAERESIS -Ì I! 0xcc 204 LATIN CAPITAL LETTER I WITH GRAVE -Í I' 0xcd 205 LATIN CAPITAL LETTER I WITH ACUTE -Î I> 0xce 206 LATIN CAPITAL LETTER I WITH CIRCUMFLEX -Ï I: 0xcf 207 LATIN CAPITAL LETTER I WITH DIAERESIS -Ð D- 0xd0 208 LATIN CAPITAL LETTER ETH (Icelandic) -Ñ N? 0xd1 209 LATIN CAPITAL LETTER N WITH TILDE -Ò O! 0xd2 210 LATIN CAPITAL LETTER O WITH GRAVE -Ó O' 0xd3 211 LATIN CAPITAL LETTER O WITH ACUTE -Ô O> 0xd4 212 LATIN CAPITAL LETTER O WITH CIRCUMFLEX -Õ O? 0xd5 213 LATIN CAPITAL LETTER O WITH TILDE -Ö O: 0xd6 214 LATIN CAPITAL LETTER O WITH DIAERESIS -× *X 0xd7 215 MULTIPLICATION SIGN -Ø O/ 0xd8 216 LATIN CAPITAL LETTER O WITH STROKE -Ù U! 0xd9 217 LATIN CAPITAL LETTER U WITH GRAVE -Ú U' 0xda 218 LATIN CAPITAL LETTER U WITH ACUTE -Û U> 0xdb 219 LATIN CAPITAL LETTER U WITH CIRCUMFLEX -Ü U: 0xdc 220 LATIN CAPITAL LETTER U WITH DIAERESIS -Ý Y' 0xdd 221 LATIN CAPITAL LETTER Y WITH ACUTE -Þ TH 0xde 222 LATIN CAPITAL LETTER THORN (Icelandic) -ß ss 0xdf 223 LATIN SMALL LETTER SHARP S (German) -à a! 0xe0 224 LATIN SMALL LETTER A WITH GRAVE -á a' 0xe1 225 LATIN SMALL LETTER A WITH ACUTE -â a> 0xe2 226 LATIN SMALL LETTER A WITH CIRCUMFLEX -ã a? 0xe3 227 LATIN SMALL LETTER A WITH TILDE -ä a: 0xe4 228 LATIN SMALL LETTER A WITH DIAERESIS -å aa 0xe5 229 LATIN SMALL LETTER A WITH RING ABOVE -æ ae 0xe6 230 LATIN SMALL LETTER AE -ç c, 0xe7 231 LATIN SMALL LETTER C WITH CEDILLA -è e! 0xe8 232 LATIN SMALL LETTER E WITH GRAVE -é e' 0xe9 233 LATIN SMALL LETTER E WITH ACUTE -ê e> 0xea 234 LATIN SMALL LETTER E WITH CIRCUMFLEX -ë e: 0xeb 235 LATIN SMALL LETTER E WITH DIAERESIS -ì i! 0xec 236 LATIN SMALL LETTER I WITH GRAVE -í i' 0xed 237 LATIN SMALL LETTER I WITH ACUTE -î i> 0xee 238 LATIN SMALL LETTER I WITH CIRCUMFLEX -ï i: 0xef 239 LATIN SMALL LETTER I WITH DIAERESIS -ð d- 0xf0 240 LATIN SMALL LETTER ETH (Icelandic) -ñ n? 0xf1 241 LATIN SMALL LETTER N WITH TILDE -ò o! 0xf2 242 LATIN SMALL LETTER O WITH GRAVE -ó o' 0xf3 243 LATIN SMALL LETTER O WITH ACUTE -ô o> 0xf4 244 LATIN SMALL LETTER O WITH CIRCUMFLEX -õ o? 0xf5 245 LATIN SMALL LETTER O WITH TILDE -ö o: 0xf6 246 LATIN SMALL LETTER O WITH DIAERESIS -÷ -: 0xf7 247 DIVISION SIGN -ø o/ 0xf8 248 LATIN SMALL LETTER O WITH STROKE -ù u! 0xf9 249 LATIN SMALL LETTER U WITH GRAVE -ú u' 0xfa 250 LATIN SMALL LETTER U WITH ACUTE -û u> 0xfb 251 LATIN SMALL LETTER U WITH CIRCUMFLEX -ü u: 0xfc 252 LATIN SMALL LETTER U WITH DIAERESIS -ý y' 0xfd 253 LATIN SMALL LETTER Y WITH ACUTE -þ th 0xfe 254 LATIN SMALL LETTER THORN (Icelandic) -ÿ y: 0xff 255 LATIN SMALL LETTER Y WITH DIAERESIS -Ā A- 0100 0256 LATIN CAPITAL LETTER A WITH MACRON -ā a- 0101 0257 LATIN SMALL LETTER A WITH MACRON -Ă A( 0102 0258 LATIN CAPITAL LETTER A WITH BREVE -ă a( 0103 0259 LATIN SMALL LETTER A WITH BREVE -Ą A; 0104 0260 LATIN CAPITAL LETTER A WITH OGONEK -ą a; 0105 0261 LATIN SMALL LETTER A WITH OGONEK -Ć C' 0106 0262 LATIN CAPITAL LETTER C WITH ACUTE -ć c' 0107 0263 LATIN SMALL LETTER C WITH ACUTE -Ĉ C> 0108 0264 LATIN CAPITAL LETTER C WITH CIRCUMFLEX -ĉ c> 0109 0265 LATIN SMALL LETTER C WITH CIRCUMFLEX -Ċ C. 010A 0266 LATIN CAPITAL LETTER C WITH DOT ABOVE -ċ c. 010B 0267 LATIN SMALL LETTER C WITH DOT ABOVE -Č C< 010C 0268 LATIN CAPITAL LETTER C WITH CARON -č c< 010D 0269 LATIN SMALL LETTER C WITH CARON -Ď D< 010E 0270 LATIN CAPITAL LETTER D WITH CARON -ď d< 010F 0271 LATIN SMALL LETTER D WITH CARON -Đ D/ 0110 0272 LATIN CAPITAL LETTER D WITH STROKE -đ d/ 0111 0273 LATIN SMALL LETTER D WITH STROKE -Ē E- 0112 0274 LATIN CAPITAL LETTER E WITH MACRON -ē e- 0113 0275 LATIN SMALL LETTER E WITH MACRON -Ĕ E( 0114 0276 LATIN CAPITAL LETTER E WITH BREVE -ĕ e( 0115 0277 LATIN SMALL LETTER E WITH BREVE -Ė E. 0116 0278 LATIN CAPITAL LETTER E WITH DOT ABOVE -ė e. 0117 0279 LATIN SMALL LETTER E WITH DOT ABOVE -Ę E; 0118 0280 LATIN CAPITAL LETTER E WITH OGONEK -ę e; 0119 0281 LATIN SMALL LETTER E WITH OGONEK -Ě E< 011A 0282 LATIN CAPITAL LETTER E WITH CARON -ě e< 011B 0283 LATIN SMALL LETTER E WITH CARON -Ĝ G> 011C 0284 LATIN CAPITAL LETTER G WITH CIRCUMFLEX -ĝ g> 011D 0285 LATIN SMALL LETTER G WITH CIRCUMFLEX -Ğ G( 011E 0286 LATIN CAPITAL LETTER G WITH BREVE -ğ g( 011F 0287 LATIN SMALL LETTER G WITH BREVE -Ġ G. 0120 0288 LATIN CAPITAL LETTER G WITH DOT ABOVE -ġ g. 0121 0289 LATIN SMALL LETTER G WITH DOT ABOVE -Ģ G, 0122 0290 LATIN CAPITAL LETTER G WITH CEDILLA -ģ g, 0123 0291 LATIN SMALL LETTER G WITH CEDILLA -Ĥ H> 0124 0292 LATIN CAPITAL LETTER H WITH CIRCUMFLEX -ĥ h> 0125 0293 LATIN SMALL LETTER H WITH CIRCUMFLEX -Ħ H/ 0126 0294 LATIN CAPITAL LETTER H WITH STROKE -ħ h/ 0127 0295 LATIN SMALL LETTER H WITH STROKE -Ĩ I? 0128 0296 LATIN CAPITAL LETTER I WITH TILDE -ĩ i? 0129 0297 LATIN SMALL LETTER I WITH TILDE -Ī I- 012A 0298 LATIN CAPITAL LETTER I WITH MACRON -ī i- 012B 0299 LATIN SMALL LETTER I WITH MACRON -Ĭ I( 012C 0300 LATIN CAPITAL LETTER I WITH BREVE -ĭ i( 012D 0301 LATIN SMALL LETTER I WITH BREVE -Į I; 012E 0302 LATIN CAPITAL LETTER I WITH OGONEK -į i; 012F 0303 LATIN SMALL LETTER I WITH OGONEK -İ I. 0130 0304 LATIN CAPITAL LETTER I WITH DOT ABOVE -ı i. 0131 0305 LATIN SMALL LETTER DOTLESS I -IJ IJ 0132 0306 LATIN CAPITAL LIGATURE IJ -ij ij 0133 0307 LATIN SMALL LIGATURE IJ -Ĵ J> 0134 0308 LATIN CAPITAL LETTER J WITH CIRCUMFLEX -ĵ j> 0135 0309 LATIN SMALL LETTER J WITH CIRCUMFLEX -Ķ K, 0136 0310 LATIN CAPITAL LETTER K WITH CEDILLA -ķ k, 0137 0311 LATIN SMALL LETTER K WITH CEDILLA -ĸ kk 0138 0312 LATIN SMALL LETTER KRA -Ĺ L' 0139 0313 LATIN CAPITAL LETTER L WITH ACUTE -ĺ l' 013A 0314 LATIN SMALL LETTER L WITH ACUTE -Ļ L, 013B 0315 LATIN CAPITAL LETTER L WITH CEDILLA -ļ l, 013C 0316 LATIN SMALL LETTER L WITH CEDILLA -Ľ L< 013D 0317 LATIN CAPITAL LETTER L WITH CARON -ľ l< 013E 0318 LATIN SMALL LETTER L WITH CARON -Ŀ L. 013F 0319 LATIN CAPITAL LETTER L WITH MIDDLE DOT -ŀ l. 0140 0320 LATIN SMALL LETTER L WITH MIDDLE DOT -Ł L/ 0141 0321 LATIN CAPITAL LETTER L WITH STROKE -ł l/ 0142 0322 LATIN SMALL LETTER L WITH STROKE -Ń N' 0143 0323 LATIN CAPITAL LETTER N WITH ACUTE ` -ń n' 0144 0324 LATIN SMALL LETTER N WITH ACUTE ` -Ņ N, 0145 0325 LATIN CAPITAL LETTER N WITH CEDILLA ` -ņ n, 0146 0326 LATIN SMALL LETTER N WITH CEDILLA ` -Ň N< 0147 0327 LATIN CAPITAL LETTER N WITH CARON ` -ň n< 0148 0328 LATIN SMALL LETTER N WITH CARON ` -ʼn 'n 0149 0329 LATIN SMALL LETTER N PRECEDED BY APOSTROPHE ` -Ŋ NG 014A 0330 LATIN CAPITAL LETTER ENG -ŋ ng 014B 0331 LATIN SMALL LETTER ENG -Ō O- 014C 0332 LATIN CAPITAL LETTER O WITH MACRON -ō o- 014D 0333 LATIN SMALL LETTER O WITH MACRON -Ŏ O( 014E 0334 LATIN CAPITAL LETTER O WITH BREVE -ŏ o( 014F 0335 LATIN SMALL LETTER O WITH BREVE -Ő O" 0150 0336 LATIN CAPITAL LETTER O WITH DOUBLE ACUTE -ő o" 0151 0337 LATIN SMALL LETTER O WITH DOUBLE ACUTE -Œ OE 0152 0338 LATIN CAPITAL LIGATURE OE -œ oe 0153 0339 LATIN SMALL LIGATURE OE -Ŕ R' 0154 0340 LATIN CAPITAL LETTER R WITH ACUTE -ŕ r' 0155 0341 LATIN SMALL LETTER R WITH ACUTE -Ŗ R, 0156 0342 LATIN CAPITAL LETTER R WITH CEDILLA -ŗ r, 0157 0343 LATIN SMALL LETTER R WITH CEDILLA -Ř R< 0158 0344 LATIN CAPITAL LETTER R WITH CARON -ř r< 0159 0345 LATIN SMALL LETTER R WITH CARON -Ś S' 015A 0346 LATIN CAPITAL LETTER S WITH ACUTE -ś s' 015B 0347 LATIN SMALL LETTER S WITH ACUTE -Ŝ S> 015C 0348 LATIN CAPITAL LETTER S WITH CIRCUMFLEX -ŝ s> 015D 0349 LATIN SMALL LETTER S WITH CIRCUMFLEX -Ş S, 015E 0350 LATIN CAPITAL LETTER S WITH CEDILLA -ş s, 015F 0351 LATIN SMALL LETTER S WITH CEDILLA -Š S< 0160 0352 LATIN CAPITAL LETTER S WITH CARON -š s< 0161 0353 LATIN SMALL LETTER S WITH CARON -Ţ T, 0162 0354 LATIN CAPITAL LETTER T WITH CEDILLA -ţ t, 0163 0355 LATIN SMALL LETTER T WITH CEDILLA -Ť T< 0164 0356 LATIN CAPITAL LETTER T WITH CARON -ť t< 0165 0357 LATIN SMALL LETTER T WITH CARON -Ŧ T/ 0166 0358 LATIN CAPITAL LETTER T WITH STROKE -ŧ t/ 0167 0359 LATIN SMALL LETTER T WITH STROKE -Ũ U? 0168 0360 LATIN CAPITAL LETTER U WITH TILDE -ũ u? 0169 0361 LATIN SMALL LETTER U WITH TILDE -Ū U- 016A 0362 LATIN CAPITAL LETTER U WITH MACRON -ū u- 016B 0363 LATIN SMALL LETTER U WITH MACRON -Ŭ U( 016C 0364 LATIN CAPITAL LETTER U WITH BREVE -ŭ u( 016D 0365 LATIN SMALL LETTER U WITH BREVE -Ů U0 016E 0366 LATIN CAPITAL LETTER U WITH RING ABOVE -ů u0 016F 0367 LATIN SMALL LETTER U WITH RING ABOVE -Ű U" 0170 0368 LATIN CAPITAL LETTER U WITH DOUBLE ACUTE -ű u" 0171 0369 LATIN SMALL LETTER U WITH DOUBLE ACUTE -Ų U; 0172 0370 LATIN CAPITAL LETTER U WITH OGONEK -ų u; 0173 0371 LATIN SMALL LETTER U WITH OGONEK -Ŵ W> 0174 0372 LATIN CAPITAL LETTER W WITH CIRCUMFLEX -ŵ w> 0175 0373 LATIN SMALL LETTER W WITH CIRCUMFLEX -Ŷ Y> 0176 0374 LATIN CAPITAL LETTER Y WITH CIRCUMFLEX -ŷ y> 0177 0375 LATIN SMALL LETTER Y WITH CIRCUMFLEX -Ÿ Y: 0178 0376 LATIN CAPITAL LETTER Y WITH DIAERESIS -Ź Z' 0179 0377 LATIN CAPITAL LETTER Z WITH ACUTE -ź z' 017A 0378 LATIN SMALL LETTER Z WITH ACUTE -Ż Z. 017B 0379 LATIN CAPITAL LETTER Z WITH DOT ABOVE -ż z. 017C 0380 LATIN SMALL LETTER Z WITH DOT ABOVE -Ž Z< 017D 0381 LATIN CAPITAL LETTER Z WITH CARON -ž z< 017E 0382 LATIN SMALL LETTER Z WITH CARON -Ơ O9 01A0 0416 LATIN CAPITAL LETTER O WITH HORN -ơ o9 01A1 0417 LATIN SMALL LETTER O WITH HORN -Ƣ OI 01A2 0418 LATIN CAPITAL LETTER OI -ƣ oi 01A3 0419 LATIN SMALL LETTER OI -Ʀ yr 01A6 0422 LATIN LETTER YR -Ư U9 01AF 0431 LATIN CAPITAL LETTER U WITH HORN -ư u9 01B0 0432 LATIN SMALL LETTER U WITH HORN -Ƶ Z/ 01B5 0437 LATIN CAPITAL LETTER Z WITH STROKE -ƶ z/ 01B6 0438 LATIN SMALL LETTER Z WITH STROKE -Ʒ ED 01B7 0439 LATIN CAPITAL LETTER EZH -Ǎ A< 01CD 0461 LATIN CAPITAL LETTER A WITH CARON -ǎ a< 01CE 0462 LATIN SMALL LETTER A WITH CARON -Ǐ I< 01CF 0463 LATIN CAPITAL LETTER I WITH CARON -ǐ i< 01D0 0464 LATIN SMALL LETTER I WITH CARON -Ǒ O< 01D1 0465 LATIN CAPITAL LETTER O WITH CARON -ǒ o< 01D2 0466 LATIN SMALL LETTER O WITH CARON -Ǔ U< 01D3 0467 LATIN CAPITAL LETTER U WITH CARON -ǔ u< 01D4 0468 LATIN SMALL LETTER U WITH CARON -Ǟ A1 01DE 0478 LATIN CAPITAL LETTER A WITH DIAERESIS AND MACRON -ǟ a1 01DF 0479 LATIN SMALL LETTER A WITH DIAERESIS AND MACRON -Ǡ A7 01E0 0480 LATIN CAPITAL LETTER A WITH DOT ABOVE AND MACRON -ǡ a7 01E1 0481 LATIN SMALL LETTER A WITH DOT ABOVE AND MACRON -Ǣ A3 01E2 0482 LATIN CAPITAL LETTER AE WITH MACRON -ǣ a3 01E3 0483 LATIN SMALL LETTER AE WITH MACRON -Ǥ G/ 01E4 0484 LATIN CAPITAL LETTER G WITH STROKE -ǥ g/ 01E5 0485 LATIN SMALL LETTER G WITH STROKE -Ǧ G< 01E6 0486 LATIN CAPITAL LETTER G WITH CARON -ǧ g< 01E7 0487 LATIN SMALL LETTER G WITH CARON -Ǩ K< 01E8 0488 LATIN CAPITAL LETTER K WITH CARON -ǩ k< 01E9 0489 LATIN SMALL LETTER K WITH CARON -Ǫ O; 01EA 0490 LATIN CAPITAL LETTER O WITH OGONEK -ǫ o; 01EB 0491 LATIN SMALL LETTER O WITH OGONEK -Ǭ O1 01EC 0492 LATIN CAPITAL LETTER O WITH OGONEK AND MACRON -ǭ o1 01ED 0493 LATIN SMALL LETTER O WITH OGONEK AND MACRON -Ǯ EZ 01EE 0494 LATIN CAPITAL LETTER EZH WITH CARON -ǯ ez 01EF 0495 LATIN SMALL LETTER EZH WITH CARON -ǰ j< 01F0 0496 LATIN SMALL LETTER J WITH CARON -Ǵ G' 01F4 0500 LATIN CAPITAL LETTER G WITH ACUTE -ǵ g' 01F5 0501 LATIN SMALL LETTER G WITH ACUTE -ʿ ;S 02BF 0703 MODIFIER LETTER LEFT HALF RING -ˇ '< 02C7 0711 CARON -˘ '( 02D8 0728 BREVE -˙ '. 02D9 0729 DOT ABOVE -˚ '0 02DA 0730 RING ABOVE -˛ '; 02DB 0731 OGONEK -˝ '" 02DD 0733 DOUBLE ACUTE ACCENT -Ά A% 0386 0902 GREEK CAPITAL LETTER ALPHA WITH TONOS -Έ E% 0388 0904 GREEK CAPITAL LETTER EPSILON WITH TONOS -Ή Y% 0389 0905 GREEK CAPITAL LETTER ETA WITH TONOS -Ί I% 038A 0906 GREEK CAPITAL LETTER IOTA WITH TONOS -Ό O% 038C 0908 GREEK CAPITAL LETTER OMICRON WITH TONOS -Ύ U% 038E 0910 GREEK CAPITAL LETTER UPSILON WITH TONOS -Ώ W% 038F 0911 GREEK CAPITAL LETTER OMEGA WITH TONOS -ΐ i3 0390 0912 GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS -Α A* 0391 0913 GREEK CAPITAL LETTER ALPHA -Β B* 0392 0914 GREEK CAPITAL LETTER BETA -Γ G* 0393 0915 GREEK CAPITAL LETTER GAMMA -Δ D* 0394 0916 GREEK CAPITAL LETTER DELTA -Ε E* 0395 0917 GREEK CAPITAL LETTER EPSILON -Ζ Z* 0396 0918 GREEK CAPITAL LETTER ZETA -Η Y* 0397 0919 GREEK CAPITAL LETTER ETA -Θ H* 0398 0920 GREEK CAPITAL LETTER THETA -Ι I* 0399 0921 GREEK CAPITAL LETTER IOTA -Κ K* 039A 0922 GREEK CAPITAL LETTER KAPPA -Λ L* 039B 0923 GREEK CAPITAL LETTER LAMDA -Μ M* 039C 0924 GREEK CAPITAL LETTER MU -Ν N* 039D 0925 GREEK CAPITAL LETTER NU -Ξ C* 039E 0926 GREEK CAPITAL LETTER XI -Ο O* 039F 0927 GREEK CAPITAL LETTER OMICRON -Π P* 03A0 0928 GREEK CAPITAL LETTER PI -Ρ R* 03A1 0929 GREEK CAPITAL LETTER RHO -Σ S* 03A3 0931 GREEK CAPITAL LETTER SIGMA -Τ T* 03A4 0932 GREEK CAPITAL LETTER TAU -Υ U* 03A5 0933 GREEK CAPITAL LETTER UPSILON -Φ F* 03A6 0934 GREEK CAPITAL LETTER PHI -Χ X* 03A7 0935 GREEK CAPITAL LETTER CHI -Ψ Q* 03A8 0936 GREEK CAPITAL LETTER PSI -Ω W* 03A9 0937 GREEK CAPITAL LETTER OMEGA -Ϊ J* 03AA 0938 GREEK CAPITAL LETTER IOTA WITH DIALYTIKA -Ϋ V* 03AB 0939 GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA -ά a% 03AC 0940 GREEK SMALL LETTER ALPHA WITH TONOS -έ e% 03AD 0941 GREEK SMALL LETTER EPSILON WITH TONOS -ή y% 03AE 0942 GREEK SMALL LETTER ETA WITH TONOS -ί i% 03AF 0943 GREEK SMALL LETTER IOTA WITH TONOS -ΰ u3 03B0 0944 GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS -α a* 03B1 0945 GREEK SMALL LETTER ALPHA -β b* 03B2 0946 GREEK SMALL LETTER BETA -γ g* 03B3 0947 GREEK SMALL LETTER GAMMA -δ d* 03B4 0948 GREEK SMALL LETTER DELTA -ε e* 03B5 0949 GREEK SMALL LETTER EPSILON -ζ z* 03B6 0950 GREEK SMALL LETTER ZETA -η y* 03B7 0951 GREEK SMALL LETTER ETA -θ h* 03B8 0952 GREEK SMALL LETTER THETA -ι i* 03B9 0953 GREEK SMALL LETTER IOTA -κ k* 03BA 0954 GREEK SMALL LETTER KAPPA -λ l* 03BB 0955 GREEK SMALL LETTER LAMDA -μ m* 03BC 0956 GREEK SMALL LETTER MU -ν n* 03BD 0957 GREEK SMALL LETTER NU -ξ c* 03BE 0958 GREEK SMALL LETTER XI -ο o* 03BF 0959 GREEK SMALL LETTER OMICRON -π p* 03C0 0960 GREEK SMALL LETTER PI -ρ r* 03C1 0961 GREEK SMALL LETTER RHO -ς *s 03C2 0962 GREEK SMALL LETTER FINAL SIGMA -σ s* 03C3 0963 GREEK SMALL LETTER SIGMA -τ t* 03C4 0964 GREEK SMALL LETTER TAU -υ u* 03C5 0965 GREEK SMALL LETTER UPSILON -φ f* 03C6 0966 GREEK SMALL LETTER PHI -χ x* 03C7 0967 GREEK SMALL LETTER CHI -ψ q* 03C8 0968 GREEK SMALL LETTER PSI -ω w* 03C9 0969 GREEK SMALL LETTER OMEGA -ϊ j* 03CA 0970 GREEK SMALL LETTER IOTA WITH DIALYTIKA -ϋ v* 03CB 0971 GREEK SMALL LETTER UPSILON WITH DIALYTIKA -ό o% 03CC 0972 GREEK SMALL LETTER OMICRON WITH TONOS -ύ u% 03CD 0973 GREEK SMALL LETTER UPSILON WITH TONOS -ώ w% 03CE 0974 GREEK SMALL LETTER OMEGA WITH TONOS -Ϙ 'G 03D8 0984 GREEK LETTER ARCHAIC KOPPA -ϙ ,G 03D9 0985 GREEK SMALL LETTER ARCHAIC KOPPA -Ϛ T3 03DA 0986 GREEK LETTER STIGMA -ϛ t3 03DB 0987 GREEK SMALL LETTER STIGMA -Ϝ M3 03DC 0988 GREEK LETTER DIGAMMA -ϝ m3 03DD 0989 GREEK SMALL LETTER DIGAMMA -Ϟ K3 03DE 0990 GREEK LETTER KOPPA -ϟ k3 03DF 0991 GREEK SMALL LETTER KOPPA -Ϡ P3 03E0 0992 GREEK LETTER SAMPI -ϡ p3 03E1 0993 GREEK SMALL LETTER SAMPI -ϴ '% 03F4 1012 GREEK CAPITAL THETA SYMBOL -ϵ j3 03F5 1013 GREEK LUNATE EPSILON SYMBOL -Ё IO 0401 1025 CYRILLIC CAPITAL LETTER IO -Ђ D% 0402 1026 CYRILLIC CAPITAL LETTER DJE -Ѓ G% 0403 1027 CYRILLIC CAPITAL LETTER GJE -Є IE 0404 1028 CYRILLIC CAPITAL LETTER UKRAINIAN IE -Ѕ DS 0405 1029 CYRILLIC CAPITAL LETTER DZE -І II 0406 1030 CYRILLIC CAPITAL LETTER BYELORUSSIAN-UKRAINIAN I -Ї YI 0407 1031 CYRILLIC CAPITAL LETTER YI -Ј J% 0408 1032 CYRILLIC CAPITAL LETTER JE -Љ LJ 0409 1033 CYRILLIC CAPITAL LETTER LJE -Њ NJ 040A 1034 CYRILLIC CAPITAL LETTER NJE -Ћ Ts 040B 1035 CYRILLIC CAPITAL LETTER TSHE -Ќ KJ 040C 1036 CYRILLIC CAPITAL LETTER KJE -Ў V% 040E 1038 CYRILLIC CAPITAL LETTER SHORT U -Џ DZ 040F 1039 CYRILLIC CAPITAL LETTER DZHE -А A= 0410 1040 CYRILLIC CAPITAL LETTER A -Б B= 0411 1041 CYRILLIC CAPITAL LETTER BE -В V= 0412 1042 CYRILLIC CAPITAL LETTER VE -Г G= 0413 1043 CYRILLIC CAPITAL LETTER GHE -Д D= 0414 1044 CYRILLIC CAPITAL LETTER DE -Е E= 0415 1045 CYRILLIC CAPITAL LETTER IE -Ж Z% 0416 1046 CYRILLIC CAPITAL LETTER ZHE -З Z= 0417 1047 CYRILLIC CAPITAL LETTER ZE -И I= 0418 1048 CYRILLIC CAPITAL LETTER I -Й J= 0419 1049 CYRILLIC CAPITAL LETTER SHORT I -К K= 041A 1050 CYRILLIC CAPITAL LETTER KA -Л L= 041B 1051 CYRILLIC CAPITAL LETTER EL -М M= 041C 1052 CYRILLIC CAPITAL LETTER EM -Н N= 041D 1053 CYRILLIC CAPITAL LETTER EN -О O= 041E 1054 CYRILLIC CAPITAL LETTER O -П P= 041F 1055 CYRILLIC CAPITAL LETTER PE -Р R= 0420 1056 CYRILLIC CAPITAL LETTER ER -С S= 0421 1057 CYRILLIC CAPITAL LETTER ES -Т T= 0422 1058 CYRILLIC CAPITAL LETTER TE -У U= 0423 1059 CYRILLIC CAPITAL LETTER U -Ф F= 0424 1060 CYRILLIC CAPITAL LETTER EF -Х H= 0425 1061 CYRILLIC CAPITAL LETTER HA -Ц C= 0426 1062 CYRILLIC CAPITAL LETTER TSE -Ч C% 0427 1063 CYRILLIC CAPITAL LETTER CHE -Ш S% 0428 1064 CYRILLIC CAPITAL LETTER SHA -Щ Sc 0429 1065 CYRILLIC CAPITAL LETTER SHCHA -Ъ =" 042A 1066 CYRILLIC CAPITAL LETTER HARD SIGN -Ы Y= 042B 1067 CYRILLIC CAPITAL LETTER YERU -Ь %" 042C 1068 CYRILLIC CAPITAL LETTER SOFT SIGN -Э JE 042D 1069 CYRILLIC CAPITAL LETTER E -Ю JU 042E 1070 CYRILLIC CAPITAL LETTER YU -Я JA 042F 1071 CYRILLIC CAPITAL LETTER YA -а a= 0430 1072 CYRILLIC SMALL LETTER A -б b= 0431 1073 CYRILLIC SMALL LETTER BE -в v= 0432 1074 CYRILLIC SMALL LETTER VE -г g= 0433 1075 CYRILLIC SMALL LETTER GHE -д d= 0434 1076 CYRILLIC SMALL LETTER DE -е e= 0435 1077 CYRILLIC SMALL LETTER IE -ж z% 0436 1078 CYRILLIC SMALL LETTER ZHE -з z= 0437 1079 CYRILLIC SMALL LETTER ZE -и i= 0438 1080 CYRILLIC SMALL LETTER I -й j= 0439 1081 CYRILLIC SMALL LETTER SHORT I -к k= 043A 1082 CYRILLIC SMALL LETTER KA -л l= 043B 1083 CYRILLIC SMALL LETTER EL -м m= 043C 1084 CYRILLIC SMALL LETTER EM -н n= 043D 1085 CYRILLIC SMALL LETTER EN -о o= 043E 1086 CYRILLIC SMALL LETTER O -п p= 043F 1087 CYRILLIC SMALL LETTER PE -р r= 0440 1088 CYRILLIC SMALL LETTER ER -с s= 0441 1089 CYRILLIC SMALL LETTER ES -т t= 0442 1090 CYRILLIC SMALL LETTER TE -у u= 0443 1091 CYRILLIC SMALL LETTER U -ф f= 0444 1092 CYRILLIC SMALL LETTER EF -х h= 0445 1093 CYRILLIC SMALL LETTER HA -ц c= 0446 1094 CYRILLIC SMALL LETTER TSE -ч c% 0447 1095 CYRILLIC SMALL LETTER CHE -ш s% 0448 1096 CYRILLIC SMALL LETTER SHA -щ sc 0449 1097 CYRILLIC SMALL LETTER SHCHA -ъ =' 044A 1098 CYRILLIC SMALL LETTER HARD SIGN -ы y= 044B 1099 CYRILLIC SMALL LETTER YERU -ь %' 044C 1100 CYRILLIC SMALL LETTER SOFT SIGN -э je 044D 1101 CYRILLIC SMALL LETTER E -ю ju 044E 1102 CYRILLIC SMALL LETTER YU -я ja 044F 1103 CYRILLIC SMALL LETTER YA -ё io 0451 1105 CYRILLIC SMALL LETTER IO -ђ d% 0452 1106 CYRILLIC SMALL LETTER DJE -ѓ g% 0453 1107 CYRILLIC SMALL LETTER GJE -є ie 0454 1108 CYRILLIC SMALL LETTER UKRAINIAN IE -ѕ ds 0455 1109 CYRILLIC SMALL LETTER DZE -і ii 0456 1110 CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I -ї yi 0457 1111 CYRILLIC SMALL LETTER YI -ј j% 0458 1112 CYRILLIC SMALL LETTER JE -љ lj 0459 1113 CYRILLIC SMALL LETTER LJE -њ nj 045A 1114 CYRILLIC SMALL LETTER NJE -ћ ts 045B 1115 CYRILLIC SMALL LETTER TSHE -ќ kj 045C 1116 CYRILLIC SMALL LETTER KJE -ў v% 045E 1118 CYRILLIC SMALL LETTER SHORT U -џ dz 045F 1119 CYRILLIC SMALL LETTER DZHE -Ѣ Y3 0462 1122 CYRILLIC CAPITAL LETTER YAT -ѣ y3 0463 1123 CYRILLIC SMALL LETTER YAT -Ѫ O3 046A 1130 CYRILLIC CAPITAL LETTER BIG YUS -ѫ o3 046B 1131 CYRILLIC SMALL LETTER BIG YUS -Ѳ F3 0472 1138 CYRILLIC CAPITAL LETTER FITA -ѳ f3 0473 1139 CYRILLIC SMALL LETTER FITA -Ѵ V3 0474 1140 CYRILLIC CAPITAL LETTER IZHITSA -ѵ v3 0475 1141 CYRILLIC SMALL LETTER IZHITSA -Ҁ C3 0480 1152 CYRILLIC CAPITAL LETTER KOPPA -ҁ c3 0481 1153 CYRILLIC SMALL LETTER KOPPA -Ґ G3 0490 1168 CYRILLIC CAPITAL LETTER GHE WITH UPTURN -ґ g3 0491 1169 CYRILLIC SMALL LETTER GHE WITH UPTURN -א A+ 05D0 1488 HEBREW LETTER ALEF -ב B+ 05D1 1489 HEBREW LETTER BET -ג G+ 05D2 1490 HEBREW LETTER GIMEL -ד D+ 05D3 1491 HEBREW LETTER DALET -ה H+ 05D4 1492 HEBREW LETTER HE -ו W+ 05D5 1493 HEBREW LETTER VAV -ז Z+ 05D6 1494 HEBREW LETTER ZAYIN -ח X+ 05D7 1495 HEBREW LETTER HET -ט Tj 05D8 1496 HEBREW LETTER TET -י J+ 05D9 1497 HEBREW LETTER YOD -ך K% 05DA 1498 HEBREW LETTER FINAL KAF -כ K+ 05DB 1499 HEBREW LETTER KAF -ל L+ 05DC 1500 HEBREW LETTER LAMED -ם M% 05DD 1501 HEBREW LETTER FINAL MEM -מ M+ 05DE 1502 HEBREW LETTER MEM -ן N% 05DF 1503 HEBREW LETTER FINAL NUN ` -נ N+ 05E0 1504 HEBREW LETTER NUN ` -ס S+ 05E1 1505 HEBREW LETTER SAMEKH -ע E+ 05E2 1506 HEBREW LETTER AYIN -ף P% 05E3 1507 HEBREW LETTER FINAL PE -פ P+ 05E4 1508 HEBREW LETTER PE -ץ Zj 05E5 1509 HEBREW LETTER FINAL TSADI -צ ZJ 05E6 1510 HEBREW LETTER TSADI -ק Q+ 05E7 1511 HEBREW LETTER QOF -ר R+ 05E8 1512 HEBREW LETTER RESH -ש Sh 05E9 1513 HEBREW LETTER SHIN -ת T+ 05EA 1514 HEBREW LETTER TAV -، ,+ 060C 1548 ARABIC COMMA -؛ ;+ 061B 1563 ARABIC SEMICOLON -؟ ?+ 061F 1567 ARABIC QUESTION MARK -ء H' 0621 1569 ARABIC LETTER HAMZA -آ aM 0622 1570 ARABIC LETTER ALEF WITH MADDA ABOVE -أ aH 0623 1571 ARABIC LETTER ALEF WITH HAMZA ABOVE -ؤ wH 0624 1572 ARABIC LETTER WAW WITH HAMZA ABOVE -إ ah 0625 1573 ARABIC LETTER ALEF WITH HAMZA BELOW -ئ yH 0626 1574 ARABIC LETTER YEH WITH HAMZA ABOVE -ا a+ 0627 1575 ARABIC LETTER ALEF -ب b+ 0628 1576 ARABIC LETTER BEH -ة tm 0629 1577 ARABIC LETTER TEH MARBUTA -ت t+ 062A 1578 ARABIC LETTER TEH -ث tk 062B 1579 ARABIC LETTER THEH -ج g+ 062C 1580 ARABIC LETTER JEEM -ح hk 062D 1581 ARABIC LETTER HAH -خ x+ 062E 1582 ARABIC LETTER KHAH -د d+ 062F 1583 ARABIC LETTER DAL -ذ dk 0630 1584 ARABIC LETTER THAL -ر r+ 0631 1585 ARABIC LETTER REH -ز z+ 0632 1586 ARABIC LETTER ZAIN -س s+ 0633 1587 ARABIC LETTER SEEN -ش sn 0634 1588 ARABIC LETTER SHEEN -ص c+ 0635 1589 ARABIC LETTER SAD -ض dd 0636 1590 ARABIC LETTER DAD -ط tj 0637 1591 ARABIC LETTER TAH -ظ zH 0638 1592 ARABIC LETTER ZAH -ع e+ 0639 1593 ARABIC LETTER AIN -غ i+ 063A 1594 ARABIC LETTER GHAIN -ـ ++ 0640 1600 ARABIC TATWEEL -ف f+ 0641 1601 ARABIC LETTER FEH -ق q+ 0642 1602 ARABIC LETTER QAF -ك k+ 0643 1603 ARABIC LETTER KAF -ل l+ 0644 1604 ARABIC LETTER LAM -م m+ 0645 1605 ARABIC LETTER MEEM -ن n+ 0646 1606 ARABIC LETTER NOON -ه h+ 0647 1607 ARABIC LETTER HEH -و w+ 0648 1608 ARABIC LETTER WAW -ى j+ 0649 1609 ARABIC LETTER ALEF MAKSURA -ي y+ 064A 1610 ARABIC LETTER YEH -ً :+ 064B 1611 ARABIC FATHATAN -ٌ "+ 064C 1612 ARABIC DAMMATAN -ٍ =+ 064D 1613 ARABIC KASRATAN -َ /+ 064E 1614 ARABIC FATHA -ُ '+ 064F 1615 ARABIC DAMMA -ِ 1+ 0650 1616 ARABIC KASRA -ّ 3+ 0651 1617 ARABIC SHADDA -ْ 0+ 0652 1618 ARABIC SUKUN -ٰ aS 0670 1648 ARABIC LETTER SUPERSCRIPT ALEF -پ p+ 067E 1662 ARABIC LETTER PEH -ڤ v+ 06A4 1700 ARABIC LETTER VEH -گ gf 06AF 1711 ARABIC LETTER GAF -۰ 0a 06F0 1776 EXTENDED ARABIC-INDIC DIGIT ZERO -۱ 1a 06F1 1777 EXTENDED ARABIC-INDIC DIGIT ONE -۲ 2a 06F2 1778 EXTENDED ARABIC-INDIC DIGIT TWO -۳ 3a 06F3 1779 EXTENDED ARABIC-INDIC DIGIT THREE -۴ 4a 06F4 1780 EXTENDED ARABIC-INDIC DIGIT FOUR -۵ 5a 06F5 1781 EXTENDED ARABIC-INDIC DIGIT FIVE -۶ 6a 06F6 1782 EXTENDED ARABIC-INDIC DIGIT SIX -۷ 7a 06F7 1783 EXTENDED ARABIC-INDIC DIGIT SEVEN -۸ 8a 06F8 1784 EXTENDED ARABIC-INDIC DIGIT EIGHT -۹ 9a 06F9 1785 EXTENDED ARABIC-INDIC DIGIT NINE -Ḃ B. 1E02 7682 LATIN CAPITAL LETTER B WITH DOT ABOVE -ḃ b. 1E03 7683 LATIN SMALL LETTER B WITH DOT ABOVE -Ḇ B_ 1E06 7686 LATIN CAPITAL LETTER B WITH LINE BELOW -ḇ b_ 1E07 7687 LATIN SMALL LETTER B WITH LINE BELOW -Ḋ D. 1E0A 7690 LATIN CAPITAL LETTER D WITH DOT ABOVE -ḋ d. 1E0B 7691 LATIN SMALL LETTER D WITH DOT ABOVE -Ḏ D_ 1E0E 7694 LATIN CAPITAL LETTER D WITH LINE BELOW -ḏ d_ 1E0F 7695 LATIN SMALL LETTER D WITH LINE BELOW -Ḑ D, 1E10 7696 LATIN CAPITAL LETTER D WITH CEDILLA -ḑ d, 1E11 7697 LATIN SMALL LETTER D WITH CEDILLA -Ḟ F. 1E1E 7710 LATIN CAPITAL LETTER F WITH DOT ABOVE -ḟ f. 1E1F 7711 LATIN SMALL LETTER F WITH DOT ABOVE -Ḡ G- 1E20 7712 LATIN CAPITAL LETTER G WITH MACRON -ḡ g- 1E21 7713 LATIN SMALL LETTER G WITH MACRON -Ḣ H. 1E22 7714 LATIN CAPITAL LETTER H WITH DOT ABOVE -ḣ h. 1E23 7715 LATIN SMALL LETTER H WITH DOT ABOVE -Ḧ H: 1E26 7718 LATIN CAPITAL LETTER H WITH DIAERESIS -ḧ h: 1E27 7719 LATIN SMALL LETTER H WITH DIAERESIS -Ḩ H, 1E28 7720 LATIN CAPITAL LETTER H WITH CEDILLA -ḩ h, 1E29 7721 LATIN SMALL LETTER H WITH CEDILLA -Ḱ K' 1E30 7728 LATIN CAPITAL LETTER K WITH ACUTE -ḱ k' 1E31 7729 LATIN SMALL LETTER K WITH ACUTE -Ḵ K_ 1E34 7732 LATIN CAPITAL LETTER K WITH LINE BELOW -ḵ k_ 1E35 7733 LATIN SMALL LETTER K WITH LINE BELOW -Ḻ L_ 1E3A 7738 LATIN CAPITAL LETTER L WITH LINE BELOW -ḻ l_ 1E3B 7739 LATIN SMALL LETTER L WITH LINE BELOW -Ḿ M' 1E3E 7742 LATIN CAPITAL LETTER M WITH ACUTE -ḿ m' 1E3F 7743 LATIN SMALL LETTER M WITH ACUTE -Ṁ M. 1E40 7744 LATIN CAPITAL LETTER M WITH DOT ABOVE -ṁ m. 1E41 7745 LATIN SMALL LETTER M WITH DOT ABOVE -Ṅ N. 1E44 7748 LATIN CAPITAL LETTER N WITH DOT ABOVE ` -ṅ n. 1E45 7749 LATIN SMALL LETTER N WITH DOT ABOVE ` -Ṉ N_ 1E48 7752 LATIN CAPITAL LETTER N WITH LINE BELOW ` -ṉ n_ 1E49 7753 LATIN SMALL LETTER N WITH LINE BELOW ` -Ṕ P' 1E54 7764 LATIN CAPITAL LETTER P WITH ACUTE -ṕ p' 1E55 7765 LATIN SMALL LETTER P WITH ACUTE -Ṗ P. 1E56 7766 LATIN CAPITAL LETTER P WITH DOT ABOVE -ṗ p. 1E57 7767 LATIN SMALL LETTER P WITH DOT ABOVE -Ṙ R. 1E58 7768 LATIN CAPITAL LETTER R WITH DOT ABOVE -ṙ r. 1E59 7769 LATIN SMALL LETTER R WITH DOT ABOVE -Ṟ R_ 1E5E 7774 LATIN CAPITAL LETTER R WITH LINE BELOW -ṟ r_ 1E5F 7775 LATIN SMALL LETTER R WITH LINE BELOW -Ṡ S. 1E60 7776 LATIN CAPITAL LETTER S WITH DOT ABOVE -ṡ s. 1E61 7777 LATIN SMALL LETTER S WITH DOT ABOVE -Ṫ T. 1E6A 7786 LATIN CAPITAL LETTER T WITH DOT ABOVE -ṫ t. 1E6B 7787 LATIN SMALL LETTER T WITH DOT ABOVE -Ṯ T_ 1E6E 7790 LATIN CAPITAL LETTER T WITH LINE BELOW -ṯ t_ 1E6F 7791 LATIN SMALL LETTER T WITH LINE BELOW -Ṽ V? 1E7C 7804 LATIN CAPITAL LETTER V WITH TILDE -ṽ v? 1E7D 7805 LATIN SMALL LETTER V WITH TILDE -Ẁ W! 1E80 7808 LATIN CAPITAL LETTER W WITH GRAVE -ẁ w! 1E81 7809 LATIN SMALL LETTER W WITH GRAVE -Ẃ W' 1E82 7810 LATIN CAPITAL LETTER W WITH ACUTE -ẃ w' 1E83 7811 LATIN SMALL LETTER W WITH ACUTE -Ẅ W: 1E84 7812 LATIN CAPITAL LETTER W WITH DIAERESIS -ẅ w: 1E85 7813 LATIN SMALL LETTER W WITH DIAERESIS -Ẇ W. 1E86 7814 LATIN CAPITAL LETTER W WITH DOT ABOVE -ẇ w. 1E87 7815 LATIN SMALL LETTER W WITH DOT ABOVE -Ẋ X. 1E8A 7818 LATIN CAPITAL LETTER X WITH DOT ABOVE -ẋ x. 1E8B 7819 LATIN SMALL LETTER X WITH DOT ABOVE -Ẍ X: 1E8C 7820 LATIN CAPITAL LETTER X WITH DIAERESIS -ẍ x: 1E8D 7821 LATIN SMALL LETTER X WITH DIAERESIS -Ẏ Y. 1E8E 7822 LATIN CAPITAL LETTER Y WITH DOT ABOVE -ẏ y. 1E8F 7823 LATIN SMALL LETTER Y WITH DOT ABOVE -Ẑ Z> 1E90 7824 LATIN CAPITAL LETTER Z WITH CIRCUMFLEX -ẑ z> 1E91 7825 LATIN SMALL LETTER Z WITH CIRCUMFLEX -Ẕ Z_ 1E94 7828 LATIN CAPITAL LETTER Z WITH LINE BELOW -ẕ z_ 1E95 7829 LATIN SMALL LETTER Z WITH LINE BELOW -ẖ h_ 1E96 7830 LATIN SMALL LETTER H WITH LINE BELOW -ẗ t: 1E97 7831 LATIN SMALL LETTER T WITH DIAERESIS -ẘ w0 1E98 7832 LATIN SMALL LETTER W WITH RING ABOVE -ẙ y0 1E99 7833 LATIN SMALL LETTER Y WITH RING ABOVE -Ả A2 1EA2 7842 LATIN CAPITAL LETTER A WITH HOOK ABOVE -ả a2 1EA3 7843 LATIN SMALL LETTER A WITH HOOK ABOVE -Ẻ E2 1EBA 7866 LATIN CAPITAL LETTER E WITH HOOK ABOVE -ẻ e2 1EBB 7867 LATIN SMALL LETTER E WITH HOOK ABOVE -Ẽ E? 1EBC 7868 LATIN CAPITAL LETTER E WITH TILDE -ẽ e? 1EBD 7869 LATIN SMALL LETTER E WITH TILDE -Ỉ I2 1EC8 7880 LATIN CAPITAL LETTER I WITH HOOK ABOVE -ỉ i2 1EC9 7881 LATIN SMALL LETTER I WITH HOOK ABOVE -Ỏ O2 1ECE 7886 LATIN CAPITAL LETTER O WITH HOOK ABOVE -ỏ o2 1ECF 7887 LATIN SMALL LETTER O WITH HOOK ABOVE -Ủ U2 1EE6 7910 LATIN CAPITAL LETTER U WITH HOOK ABOVE -ủ u2 1EE7 7911 LATIN SMALL LETTER U WITH HOOK ABOVE -Ỳ Y! 1EF2 7922 LATIN CAPITAL LETTER Y WITH GRAVE -ỳ y! 1EF3 7923 LATIN SMALL LETTER Y WITH GRAVE -Ỷ Y2 1EF6 7926 LATIN CAPITAL LETTER Y WITH HOOK ABOVE -ỷ y2 1EF7 7927 LATIN SMALL LETTER Y WITH HOOK ABOVE -Ỹ Y? 1EF8 7928 LATIN CAPITAL LETTER Y WITH TILDE -ỹ y? 1EF9 7929 LATIN SMALL LETTER Y WITH TILDE -ἀ ;' 1F00 7936 GREEK SMALL LETTER ALPHA WITH PSILI -ἁ ,' 1F01 7937 GREEK SMALL LETTER ALPHA WITH DASIA -ἂ ;! 1F02 7938 GREEK SMALL LETTER ALPHA WITH PSILI AND VARIA -ἃ ,! 1F03 7939 GREEK SMALL LETTER ALPHA WITH DASIA AND VARIA -ἄ ?; 1F04 7940 GREEK SMALL LETTER ALPHA WITH PSILI AND OXIA -ἅ ?, 1F05 7941 GREEK SMALL LETTER ALPHA WITH DASIA AND OXIA -ἆ !: 1F06 7942 GREEK SMALL LETTER ALPHA WITH PSILI AND PERISPOMENI -ἇ ?: 1F07 7943 GREEK SMALL LETTER ALPHA WITH DASIA AND PERISPOMENI - 1N 2002 8194 EN SPACE - 1M 2003 8195 EM SPACE - 3M 2004 8196 THREE-PER-EM SPACE - 4M 2005 8197 FOUR-PER-EM SPACE - 6M 2006 8198 SIX-PER-EM SPACE - 1T 2009 8201 THIN SPACE - 1H 200A 8202 HAIR SPACE -‐ -1 2010 8208 HYPHEN -– -N 2013 8211 EN DASH ` -— -M 2014 8212 EM DASH -― -3 2015 8213 HORIZONTAL BAR -‖ !2 2016 8214 DOUBLE VERTICAL LINE -‗ =2 2017 8215 DOUBLE LOW LINE -‘ '6 2018 8216 LEFT SINGLE QUOTATION MARK -’ '9 2019 8217 RIGHT SINGLE QUOTATION MARK -‚ .9 201A 8218 SINGLE LOW-9 QUOTATION MARK -‛ 9' 201B 8219 SINGLE HIGH-REVERSED-9 QUOTATION MARK -“ "6 201C 8220 LEFT DOUBLE QUOTATION MARK -” "9 201D 8221 RIGHT DOUBLE QUOTATION MARK -„ :9 201E 8222 DOUBLE LOW-9 QUOTATION MARK -‟ 9" 201F 8223 DOUBLE HIGH-REVERSED-9 QUOTATION MARK -† /- 2020 8224 DAGGER -‡ /= 2021 8225 DOUBLE DAGGER -• oo 2022 8226 BULLET -‥ .. 2025 8229 TWO DOT LEADER -… ,. 2026 8230 HORIZONTAL ELLIPSIS -‰ %0 2030 8240 PER MILLE SIGN -′ 1' 2032 8242 PRIME -″ 2' 2033 8243 DOUBLE PRIME -‴ 3' 2034 8244 TRIPLE PRIME -‵ 1" 2035 8245 REVERSED PRIME -‶ 2" 2036 8246 REVERSED DOUBLE PRIME -‷ 3" 2037 8247 REVERSED TRIPLE PRIME -‸ Ca 2038 8248 CARET -‹ <1 2039 8249 SINGLE LEFT-POINTING ANGLE QUOTATION MARK -› >1 203A 8250 SINGLE RIGHT-POINTING ANGLE QUOTATION MARK -※ :X 203B 8251 REFERENCE MARK -‾ '- 203E 8254 OVERLINE -⁄ /f 2044 8260 FRACTION SLASH -⁰ 0S 2070 8304 SUPERSCRIPT ZERO -⁴ 4S 2074 8308 SUPERSCRIPT FOUR -⁵ 5S 2075 8309 SUPERSCRIPT FIVE -⁶ 6S 2076 8310 SUPERSCRIPT SIX -⁷ 7S 2077 8311 SUPERSCRIPT SEVEN -⁸ 8S 2078 8312 SUPERSCRIPT EIGHT -⁹ 9S 2079 8313 SUPERSCRIPT NINE -⁺ +S 207A 8314 SUPERSCRIPT PLUS SIGN -⁻ -S 207B 8315 SUPERSCRIPT MINUS -⁼ =S 207C 8316 SUPERSCRIPT EQUALS SIGN -⁽ (S 207D 8317 SUPERSCRIPT LEFT PARENTHESIS -⁾ )S 207E 8318 SUPERSCRIPT RIGHT PARENTHESIS -ⁿ nS 207F 8319 SUPERSCRIPT LATIN SMALL LETTER N ` -₀ 0s 2080 8320 SUBSCRIPT ZERO -₁ 1s 2081 8321 SUBSCRIPT ONE -₂ 2s 2082 8322 SUBSCRIPT TWO -₃ 3s 2083 8323 SUBSCRIPT THREE -₄ 4s 2084 8324 SUBSCRIPT FOUR -₅ 5s 2085 8325 SUBSCRIPT FIVE -₆ 6s 2086 8326 SUBSCRIPT SIX -₇ 7s 2087 8327 SUBSCRIPT SEVEN -₈ 8s 2088 8328 SUBSCRIPT EIGHT -₉ 9s 2089 8329 SUBSCRIPT NINE -₊ +s 208A 8330 SUBSCRIPT PLUS SIGN -₋ -s 208B 8331 SUBSCRIPT MINUS -₌ =s 208C 8332 SUBSCRIPT EQUALS SIGN -₍ (s 208D 8333 SUBSCRIPT LEFT PARENTHESIS -₎ )s 208E 8334 SUBSCRIPT RIGHT PARENTHESIS -₤ Li 20A4 8356 LIRA SIGN -₧ Pt 20A7 8359 PESETA SIGN -₩ W= 20A9 8361 WON SIGN -€ Eu 20AC 8364 EURO SIGN -₽ =R 20BD 8381 ROUBLE SIGN -₽ =P 20BD 8381 ROUBLE SIGN -℃ oC 2103 8451 DEGREE CELSIUS -℅ co 2105 8453 CARE OF -℉ oF 2109 8457 DEGREE FAHRENHEIT -№ N0 2116 8470 NUMERO SIGN -℗ PO 2117 8471 SOUND RECORDING COPYRIGHT -℞ Rx 211E 8478 PRESCRIPTION TAKE -℠ SM 2120 8480 SERVICE MARK -™ TM 2122 8482 TRADE MARK SIGN -Ω Om 2126 8486 OHM SIGN -Å AO 212B 8491 ANGSTROM SIGN -⅓ 13 2153 8531 VULGAR FRACTION ONE THIRD -⅔ 23 2154 8532 VULGAR FRACTION TWO THIRDS -⅕ 15 2155 8533 VULGAR FRACTION ONE FIFTH -⅖ 25 2156 8534 VULGAR FRACTION TWO FIFTHS -⅗ 35 2157 8535 VULGAR FRACTION THREE FIFTHS -⅘ 45 2158 8536 VULGAR FRACTION FOUR FIFTHS -⅙ 16 2159 8537 VULGAR FRACTION ONE SIXTH -⅚ 56 215A 8538 VULGAR FRACTION FIVE SIXTHS -⅛ 18 215B 8539 VULGAR FRACTION ONE EIGHTH -⅜ 38 215C 8540 VULGAR FRACTION THREE EIGHTHS -⅝ 58 215D 8541 VULGAR FRACTION FIVE EIGHTHS -⅞ 78 215E 8542 VULGAR FRACTION SEVEN EIGHTHS -Ⅰ 1R 2160 8544 ROMAN NUMERAL ONE -Ⅱ 2R 2161 8545 ROMAN NUMERAL TWO -Ⅲ 3R 2162 8546 ROMAN NUMERAL THREE -Ⅳ 4R 2163 8547 ROMAN NUMERAL FOUR -Ⅴ 5R 2164 8548 ROMAN NUMERAL FIVE -Ⅵ 6R 2165 8549 ROMAN NUMERAL SIX -Ⅶ 7R 2166 8550 ROMAN NUMERAL SEVEN -Ⅷ 8R 2167 8551 ROMAN NUMERAL EIGHT -Ⅸ 9R 2168 8552 ROMAN NUMERAL NINE -Ⅹ aR 2169 8553 ROMAN NUMERAL TEN -Ⅺ bR 216A 8554 ROMAN NUMERAL ELEVEN -Ⅻ cR 216B 8555 ROMAN NUMERAL TWELVE -ⅰ 1r 2170 8560 SMALL ROMAN NUMERAL ONE -ⅱ 2r 2171 8561 SMALL ROMAN NUMERAL TWO -ⅲ 3r 2172 8562 SMALL ROMAN NUMERAL THREE -ⅳ 4r 2173 8563 SMALL ROMAN NUMERAL FOUR -ⅴ 5r 2174 8564 SMALL ROMAN NUMERAL FIVE -ⅵ 6r 2175 8565 SMALL ROMAN NUMERAL SIX -ⅶ 7r 2176 8566 SMALL ROMAN NUMERAL SEVEN -ⅷ 8r 2177 8567 SMALL ROMAN NUMERAL EIGHT -ⅸ 9r 2178 8568 SMALL ROMAN NUMERAL NINE -ⅹ ar 2179 8569 SMALL ROMAN NUMERAL TEN -ⅺ br 217A 8570 SMALL ROMAN NUMERAL ELEVEN -ⅻ cr 217B 8571 SMALL ROMAN NUMERAL TWELVE -← <- 2190 8592 LEFTWARDS ARROW -↑ -! 2191 8593 UPWARDS ARROW -→ -> 2192 8594 RIGHTWARDS ARROW -↓ -v 2193 8595 DOWNWARDS ARROW -↔ <> 2194 8596 LEFT RIGHT ARROW -↕ UD 2195 8597 UP DOWN ARROW -⇐ <= 21D0 8656 LEFTWARDS DOUBLE ARROW -⇒ => 21D2 8658 RIGHTWARDS DOUBLE ARROW -⇔ == 21D4 8660 LEFT RIGHT DOUBLE ARROW -∀ FA 2200 8704 FOR ALL -∂ dP 2202 8706 PARTIAL DIFFERENTIAL -∃ TE 2203 8707 THERE EXISTS -∅ /0 2205 8709 EMPTY SET -∆ DE 2206 8710 INCREMENT -∇ NB 2207 8711 NABLA -∈ (- 2208 8712 ELEMENT OF -∋ -) 220B 8715 CONTAINS AS MEMBER -∏ *P 220F 8719 N-ARY PRODUCT ` -∑ +Z 2211 8721 N-ARY SUMMATION ` -− -2 2212 8722 MINUS SIGN -∓ -+ 2213 8723 MINUS-OR-PLUS SIGN -∗ *- 2217 8727 ASTERISK OPERATOR -∘ Ob 2218 8728 RING OPERATOR -∙ Sb 2219 8729 BULLET OPERATOR -√ RT 221A 8730 SQUARE ROOT -∝ 0( 221D 8733 PROPORTIONAL TO -∞ 00 221E 8734 INFINITY -∟ -L 221F 8735 RIGHT ANGLE -∠ -V 2220 8736 ANGLE -∥ PP 2225 8741 PARALLEL TO -∧ AN 2227 8743 LOGICAL AND -∨ OR 2228 8744 LOGICAL OR -∩ (U 2229 8745 INTERSECTION -∪ )U 222A 8746 UNION -∫ In 222B 8747 INTEGRAL -∬ DI 222C 8748 DOUBLE INTEGRAL -∮ Io 222E 8750 CONTOUR INTEGRAL -∴ .: 2234 8756 THEREFORE -∵ :. 2235 8757 BECAUSE -∶ :R 2236 8758 RATIO -∷ :: 2237 8759 PROPORTION -∼ ?1 223C 8764 TILDE OPERATOR -∾ CG 223E 8766 INVERTED LAZY S -≃ ?- 2243 8771 ASYMPTOTICALLY EQUAL TO -≅ ?= 2245 8773 APPROXIMATELY EQUAL TO -≈ ?2 2248 8776 ALMOST EQUAL TO -≌ =? 224C 8780 ALL EQUAL TO -≓ HI 2253 8787 IMAGE OF OR APPROXIMATELY EQUAL TO -≠ != 2260 8800 NOT EQUAL TO -≡ =3 2261 8801 IDENTICAL TO -≤ =< 2264 8804 LESS-THAN OR EQUAL TO -≥ >= 2265 8805 GREATER-THAN OR EQUAL TO -≪ <* 226A 8810 MUCH LESS-THAN -≫ *> 226B 8811 MUCH GREATER-THAN -≮ !< 226E 8814 NOT LESS-THAN -≯ !> 226F 8815 NOT GREATER-THAN -⊂ (C 2282 8834 SUBSET OF -⊃ )C 2283 8835 SUPERSET OF -⊆ (_ 2286 8838 SUBSET OF OR EQUAL TO -⊇ )_ 2287 8839 SUPERSET OF OR EQUAL TO -⊙ 0. 2299 8857 CIRCLED DOT OPERATOR -⊚ 02 229A 8858 CIRCLED RING OPERATOR -⊥ -T 22A5 8869 UP TACK -⋅ .P 22C5 8901 DOT OPERATOR -⋮ :3 22EE 8942 VERTICAL ELLIPSIS -⋯ .3 22EF 8943 MIDLINE HORIZONTAL ELLIPSIS -⌂ Eh 2302 8962 HOUSE -⌈ <7 2308 8968 LEFT CEILING -⌉ >7 2309 8969 RIGHT CEILING -⌊ 7< 230A 8970 LEFT FLOOR -⌋ 7> 230B 8971 RIGHT FLOOR -⌐ NI 2310 8976 REVERSED NOT SIGN -⌒ (A 2312 8978 ARC -⌕ TR 2315 8981 TELEPHONE RECORDER -⌠ Iu 2320 8992 TOP HALF INTEGRAL -⌡ Il 2321 8993 BOTTOM HALF INTEGRAL -〈 </ 2329 9001 LEFT-POINTING ANGLE BRACKET -〉 /> 232A 9002 RIGHT-POINTING ANGLE BRACKET -␣ Vs 2423 9251 OPEN BOX -⑀ 1h 2440 9280 OCR HOOK -⑁ 3h 2441 9281 OCR CHAIR -⑂ 2h 2442 9282 OCR FORK -⑃ 4h 2443 9283 OCR INVERTED FORK -⑆ 1j 2446 9286 OCR BRANCH BANK IDENTIFICATION -⑇ 2j 2447 9287 OCR AMOUNT OF CHECK -⑈ 3j 2448 9288 OCR DASH -⑉ 4j 2449 9289 OCR CUSTOMER ACCOUNT NUMBER -⒈ 1. 2488 9352 DIGIT ONE FULL STOP -⒉ 2. 2489 9353 DIGIT TWO FULL STOP -⒊ 3. 248A 9354 DIGIT THREE FULL STOP -⒋ 4. 248B 9355 DIGIT FOUR FULL STOP -⒌ 5. 248C 9356 DIGIT FIVE FULL STOP -⒍ 6. 248D 9357 DIGIT SIX FULL STOP -⒎ 7. 248E 9358 DIGIT SEVEN FULL STOP -⒏ 8. 248F 9359 DIGIT EIGHT FULL STOP -⒐ 9. 2490 9360 DIGIT NINE FULL STOP -─ hh 2500 9472 BOX DRAWINGS LIGHT HORIZONTAL -━ HH 2501 9473 BOX DRAWINGS HEAVY HORIZONTAL -│ vv 2502 9474 BOX DRAWINGS LIGHT VERTICAL -┃ VV 2503 9475 BOX DRAWINGS HEAVY VERTICAL -┄ 3- 2504 9476 BOX DRAWINGS LIGHT TRIPLE DASH HORIZONTAL -┅ 3_ 2505 9477 BOX DRAWINGS HEAVY TRIPLE DASH HORIZONTAL -┆ 3! 2506 9478 BOX DRAWINGS LIGHT TRIPLE DASH VERTICAL -┇ 3/ 2507 9479 BOX DRAWINGS HEAVY TRIPLE DASH VERTICAL -┈ 4- 2508 9480 BOX DRAWINGS LIGHT QUADRUPLE DASH HORIZONTAL -┉ 4_ 2509 9481 BOX DRAWINGS HEAVY QUADRUPLE DASH HORIZONTAL -┊ 4! 250A 9482 BOX DRAWINGS LIGHT QUADRUPLE DASH VERTICAL -┋ 4/ 250B 9483 BOX DRAWINGS HEAVY QUADRUPLE DASH VERTICAL -┌ dr 250C 9484 BOX DRAWINGS LIGHT DOWN AND RIGHT -┍ dR 250D 9485 BOX DRAWINGS DOWN LIGHT AND RIGHT HEAVY -┎ Dr 250E 9486 BOX DRAWINGS DOWN HEAVY AND RIGHT LIGHT -┏ DR 250F 9487 BOX DRAWINGS HEAVY DOWN AND RIGHT -┐ dl 2510 9488 BOX DRAWINGS LIGHT DOWN AND LEFT -┑ dL 2511 9489 BOX DRAWINGS DOWN LIGHT AND LEFT HEAVY -┒ Dl 2512 9490 BOX DRAWINGS DOWN HEAVY AND LEFT LIGHT -┓ LD 2513 9491 BOX DRAWINGS HEAVY DOWN AND LEFT -└ ur 2514 9492 BOX DRAWINGS LIGHT UP AND RIGHT -┕ uR 2515 9493 BOX DRAWINGS UP LIGHT AND RIGHT HEAVY -┖ Ur 2516 9494 BOX DRAWINGS UP HEAVY AND RIGHT LIGHT -┗ UR 2517 9495 BOX DRAWINGS HEAVY UP AND RIGHT -┘ ul 2518 9496 BOX DRAWINGS LIGHT UP AND LEFT -┙ uL 2519 9497 BOX DRAWINGS UP LIGHT AND LEFT HEAVY -┚ Ul 251A 9498 BOX DRAWINGS UP HEAVY AND LEFT LIGHT -┛ UL 251B 9499 BOX DRAWINGS HEAVY UP AND LEFT -├ vr 251C 9500 BOX DRAWINGS LIGHT VERTICAL AND RIGHT -┝ vR 251D 9501 BOX DRAWINGS VERTICAL LIGHT AND RIGHT HEAVY -┠ Vr 2520 9504 BOX DRAWINGS VERTICAL HEAVY AND RIGHT LIGHT -┣ VR 2523 9507 BOX DRAWINGS HEAVY VERTICAL AND RIGHT -┤ vl 2524 9508 BOX DRAWINGS LIGHT VERTICAL AND LEFT -┥ vL 2525 9509 BOX DRAWINGS VERTICAL LIGHT AND LEFT HEAVY -┨ Vl 2528 9512 BOX DRAWINGS VERTICAL HEAVY AND LEFT LIGHT -┫ VL 252B 9515 BOX DRAWINGS HEAVY VERTICAL AND LEFT -┬ dh 252C 9516 BOX DRAWINGS LIGHT DOWN AND HORIZONTAL -┯ dH 252F 9519 BOX DRAWINGS DOWN LIGHT AND HORIZONTAL HEAVY -┰ Dh 2530 9520 BOX DRAWINGS DOWN HEAVY AND HORIZONTAL LIGHT -┳ DH 2533 9523 BOX DRAWINGS HEAVY DOWN AND HORIZONTAL -┴ uh 2534 9524 BOX DRAWINGS LIGHT UP AND HORIZONTAL -┷ uH 2537 9527 BOX DRAWINGS UP LIGHT AND HORIZONTAL HEAVY -┸ Uh 2538 9528 BOX DRAWINGS UP HEAVY AND HORIZONTAL LIGHT -┻ UH 253B 9531 BOX DRAWINGS HEAVY UP AND HORIZONTAL -┼ vh 253C 9532 BOX DRAWINGS LIGHT VERTICAL AND HORIZONTAL -┿ vH 253F 9535 BOX DRAWINGS VERTICAL LIGHT AND HORIZONTAL HEAVY -╂ Vh 2542 9538 BOX DRAWINGS VERTICAL HEAVY AND HORIZONTAL LIGHT -╋ VH 254B 9547 BOX DRAWINGS HEAVY VERTICAL AND HORIZONTAL -╱ FD 2571 9585 BOX DRAWINGS LIGHT DIAGONAL UPPER RIGHT TO LOWER LEFT -╲ BD 2572 9586 BOX DRAWINGS LIGHT DIAGONAL UPPER LEFT TO LOWER RIGHT -▀ TB 2580 9600 UPPER HALF BLOCK -▄ LB 2584 9604 LOWER HALF BLOCK -█ FB 2588 9608 FULL BLOCK -▌ lB 258C 9612 LEFT HALF BLOCK -▐ RB 2590 9616 RIGHT HALF BLOCK -░ .S 2591 9617 LIGHT SHADE -▒ :S 2592 9618 MEDIUM SHADE -▓ ?S 2593 9619 DARK SHADE -■ fS 25A0 9632 BLACK SQUARE -□ OS 25A1 9633 WHITE SQUARE -▢ RO 25A2 9634 WHITE SQUARE WITH ROUNDED CORNERS -▣ Rr 25A3 9635 WHITE SQUARE CONTAINING BLACK SMALL SQUARE -▤ RF 25A4 9636 SQUARE WITH HORIZONTAL FILL -▥ RY 25A5 9637 SQUARE WITH VERTICAL FILL -▦ RH 25A6 9638 SQUARE WITH ORTHOGONAL CROSSHATCH FILL -▧ RZ 25A7 9639 SQUARE WITH UPPER LEFT TO LOWER RIGHT FILL -▨ RK 25A8 9640 SQUARE WITH UPPER RIGHT TO LOWER LEFT FILL -▩ RX 25A9 9641 SQUARE WITH DIAGONAL CROSSHATCH FILL -▪ sB 25AA 9642 BLACK SMALL SQUARE -▬ SR 25AC 9644 BLACK RECTANGLE -▭ Or 25AD 9645 WHITE RECTANGLE -▲ UT 25B2 9650 BLACK UP-POINTING TRIANGLE -△ uT 25B3 9651 WHITE UP-POINTING TRIANGLE -▶ PR 25B6 9654 BLACK RIGHT-POINTING TRIANGLE -▷ Tr 25B7 9655 WHITE RIGHT-POINTING TRIANGLE -▼ Dt 25BC 9660 BLACK DOWN-POINTING TRIANGLE -▽ dT 25BD 9661 WHITE DOWN-POINTING TRIANGLE -◀ PL 25C0 9664 BLACK LEFT-POINTING TRIANGLE -◁ Tl 25C1 9665 WHITE LEFT-POINTING TRIANGLE -◆ Db 25C6 9670 BLACK DIAMOND -◇ Dw 25C7 9671 WHITE DIAMOND -◊ LZ 25CA 9674 LOZENGE -○ 0m 25CB 9675 WHITE CIRCLE -◎ 0o 25CE 9678 BULLSEYE -● 0M 25CF 9679 BLACK CIRCLE -◐ 0L 25D0 9680 CIRCLE WITH LEFT HALF BLACK -◑ 0R 25D1 9681 CIRCLE WITH RIGHT HALF BLACK -◘ Sn 25D8 9688 INVERSE BULLET -◙ Ic 25D9 9689 INVERSE WHITE CIRCLE -◢ Fd 25E2 9698 BLACK LOWER RIGHT TRIANGLE -◣ Bd 25E3 9699 BLACK LOWER LEFT TRIANGLE -★ *2 2605 9733 BLACK STAR -☆ *1 2606 9734 WHITE STAR -☜ <H 261C 9756 WHITE LEFT POINTING INDEX -☞ >H 261E 9758 WHITE RIGHT POINTING INDEX -☺ 0u 263A 9786 WHITE SMILING FACE -☻ 0U 263B 9787 BLACK SMILING FACE -☼ SU 263C 9788 WHITE SUN WITH RAYS -♀ Fm 2640 9792 FEMALE SIGN -♂ Ml 2642 9794 MALE SIGN -♠ cS 2660 9824 BLACK SPADE SUIT -♡ cH 2661 9825 WHITE HEART SUIT -♢ cD 2662 9826 WHITE DIAMOND SUIT -♣ cC 2663 9827 BLACK CLUB SUIT -♩ Md 2669 9833 QUARTER NOTE ` -♪ M8 266A 9834 EIGHTH NOTE ` -♫ M2 266B 9835 BEAMED EIGHTH NOTES -♭ Mb 266D 9837 MUSIC FLAT SIGN -♮ Mx 266E 9838 MUSIC NATURAL SIGN -♯ MX 266F 9839 MUSIC SHARP SIGN -✓ OK 2713 10003 CHECK MARK -✗ XX 2717 10007 BALLOT X -✠ -X 2720 10016 MALTESE CROSS - IS 3000 12288 IDEOGRAPHIC SPACE -、 ,_ 3001 12289 IDEOGRAPHIC COMMA -。 ._ 3002 12290 IDEOGRAPHIC FULL STOP -〃 +" 3003 12291 DITTO MARK -〄 +_ 3004 12292 JAPANESE INDUSTRIAL STANDARD SYMBOL -々 *_ 3005 12293 IDEOGRAPHIC ITERATION MARK -〆 ;_ 3006 12294 IDEOGRAPHIC CLOSING MARK -〇 0_ 3007 12295 IDEOGRAPHIC NUMBER ZERO -《 <+ 300A 12298 LEFT DOUBLE ANGLE BRACKET -》 >+ 300B 12299 RIGHT DOUBLE ANGLE BRACKET -「 <' 300C 12300 LEFT CORNER BRACKET -」 >' 300D 12301 RIGHT CORNER BRACKET -『 <" 300E 12302 LEFT WHITE CORNER BRACKET -』 >" 300F 12303 RIGHT WHITE CORNER BRACKET -【 (" 3010 12304 LEFT BLACK LENTICULAR BRACKET -】 )" 3011 12305 RIGHT BLACK LENTICULAR BRACKET -〒 =T 3012 12306 POSTAL MARK -〓 =_ 3013 12307 GETA MARK -〔 (' 3014 12308 LEFT TORTOISE SHELL BRACKET -〕 )' 3015 12309 RIGHT TORTOISE SHELL BRACKET -〖 (I 3016 12310 LEFT WHITE LENTICULAR BRACKET -〗 )I 3017 12311 RIGHT WHITE LENTICULAR BRACKET -〜 -? 301C 12316 WAVE DASH -ぁ A5 3041 12353 HIRAGANA LETTER SMALL A -あ a5 3042 12354 HIRAGANA LETTER A -ぃ I5 3043 12355 HIRAGANA LETTER SMALL I -い i5 3044 12356 HIRAGANA LETTER I -ぅ U5 3045 12357 HIRAGANA LETTER SMALL U -う u5 3046 12358 HIRAGANA LETTER U -ぇ E5 3047 12359 HIRAGANA LETTER SMALL E -え e5 3048 12360 HIRAGANA LETTER E -ぉ O5 3049 12361 HIRAGANA LETTER SMALL O -お o5 304A 12362 HIRAGANA LETTER O -か ka 304B 12363 HIRAGANA LETTER KA -が ga 304C 12364 HIRAGANA LETTER GA -き ki 304D 12365 HIRAGANA LETTER KI -ぎ gi 304E 12366 HIRAGANA LETTER GI -く ku 304F 12367 HIRAGANA LETTER KU -ぐ gu 3050 12368 HIRAGANA LETTER GU -け ke 3051 12369 HIRAGANA LETTER KE -げ ge 3052 12370 HIRAGANA LETTER GE -こ ko 3053 12371 HIRAGANA LETTER KO -ご go 3054 12372 HIRAGANA LETTER GO -さ sa 3055 12373 HIRAGANA LETTER SA -ざ za 3056 12374 HIRAGANA LETTER ZA -し si 3057 12375 HIRAGANA LETTER SI -じ zi 3058 12376 HIRAGANA LETTER ZI -す su 3059 12377 HIRAGANA LETTER SU -ず zu 305A 12378 HIRAGANA LETTER ZU -せ se 305B 12379 HIRAGANA LETTER SE -ぜ ze 305C 12380 HIRAGANA LETTER ZE -そ so 305D 12381 HIRAGANA LETTER SO -ぞ zo 305E 12382 HIRAGANA LETTER ZO -た ta 305F 12383 HIRAGANA LETTER TA -だ da 3060 12384 HIRAGANA LETTER DA -ち ti 3061 12385 HIRAGANA LETTER TI -ぢ di 3062 12386 HIRAGANA LETTER DI -っ tU 3063 12387 HIRAGANA LETTER SMALL TU -つ tu 3064 12388 HIRAGANA LETTER TU -づ du 3065 12389 HIRAGANA LETTER DU -て te 3066 12390 HIRAGANA LETTER TE -で de 3067 12391 HIRAGANA LETTER DE -と to 3068 12392 HIRAGANA LETTER TO -ど do 3069 12393 HIRAGANA LETTER DO -な na 306A 12394 HIRAGANA LETTER NA -に ni 306B 12395 HIRAGANA LETTER NI -ぬ nu 306C 12396 HIRAGANA LETTER NU -ね ne 306D 12397 HIRAGANA LETTER NE -の no 306E 12398 HIRAGANA LETTER NO -は ha 306F 12399 HIRAGANA LETTER HA -ば ba 3070 12400 HIRAGANA LETTER BA -ぱ pa 3071 12401 HIRAGANA LETTER PA -ひ hi 3072 12402 HIRAGANA LETTER HI -び bi 3073 12403 HIRAGANA LETTER BI -ぴ pi 3074 12404 HIRAGANA LETTER PI -ふ hu 3075 12405 HIRAGANA LETTER HU -ぶ bu 3076 12406 HIRAGANA LETTER BU -ぷ pu 3077 12407 HIRAGANA LETTER PU -へ he 3078 12408 HIRAGANA LETTER HE -べ be 3079 12409 HIRAGANA LETTER BE -ぺ pe 307A 12410 HIRAGANA LETTER PE -ほ ho 307B 12411 HIRAGANA LETTER HO -ぼ bo 307C 12412 HIRAGANA LETTER BO -ぽ po 307D 12413 HIRAGANA LETTER PO -ま ma 307E 12414 HIRAGANA LETTER MA -み mi 307F 12415 HIRAGANA LETTER MI -む mu 3080 12416 HIRAGANA LETTER MU -め me 3081 12417 HIRAGANA LETTER ME -も mo 3082 12418 HIRAGANA LETTER MO -ゃ yA 3083 12419 HIRAGANA LETTER SMALL YA -や ya 3084 12420 HIRAGANA LETTER YA -ゅ yU 3085 12421 HIRAGANA LETTER SMALL YU -ゆ yu 3086 12422 HIRAGANA LETTER YU -ょ yO 3087 12423 HIRAGANA LETTER SMALL YO -よ yo 3088 12424 HIRAGANA LETTER YO -ら ra 3089 12425 HIRAGANA LETTER RA -り ri 308A 12426 HIRAGANA LETTER RI -る ru 308B 12427 HIRAGANA LETTER RU -れ re 308C 12428 HIRAGANA LETTER RE -ろ ro 308D 12429 HIRAGANA LETTER RO -ゎ wA 308E 12430 HIRAGANA LETTER SMALL WA -わ wa 308F 12431 HIRAGANA LETTER WA -ゐ wi 3090 12432 HIRAGANA LETTER WI -ゑ we 3091 12433 HIRAGANA LETTER WE -を wo 3092 12434 HIRAGANA LETTER WO -ん n5 3093 12435 HIRAGANA LETTER N ` -ゔ vu 3094 12436 HIRAGANA LETTER VU -゛ "5 309B 12443 KATAKANA-HIRAGANA VOICED SOUND MARK -゜ 05 309C 12444 KATAKANA-HIRAGANA SEMI-VOICED SOUND MARK -ゝ *5 309D 12445 HIRAGANA ITERATION MARK -ゞ +5 309E 12446 HIRAGANA VOICED ITERATION MARK -ァ a6 30A1 12449 KATAKANA LETTER SMALL A -ア A6 30A2 12450 KATAKANA LETTER A -ィ i6 30A3 12451 KATAKANA LETTER SMALL I -イ I6 30A4 12452 KATAKANA LETTER I -ゥ u6 30A5 12453 KATAKANA LETTER SMALL U -ウ U6 30A6 12454 KATAKANA LETTER U -ェ e6 30A7 12455 KATAKANA LETTER SMALL E -エ E6 30A8 12456 KATAKANA LETTER E -ォ o6 30A9 12457 KATAKANA LETTER SMALL O -オ O6 30AA 12458 KATAKANA LETTER O -カ Ka 30AB 12459 KATAKANA LETTER KA -ガ Ga 30AC 12460 KATAKANA LETTER GA -キ Ki 30AD 12461 KATAKANA LETTER KI -ギ Gi 30AE 12462 KATAKANA LETTER GI -ク Ku 30AF 12463 KATAKANA LETTER KU -グ Gu 30B0 12464 KATAKANA LETTER GU -ケ Ke 30B1 12465 KATAKANA LETTER KE -ゲ Ge 30B2 12466 KATAKANA LETTER GE -コ Ko 30B3 12467 KATAKANA LETTER KO -ゴ Go 30B4 12468 KATAKANA LETTER GO -サ Sa 30B5 12469 KATAKANA LETTER SA -ザ Za 30B6 12470 KATAKANA LETTER ZA -シ Si 30B7 12471 KATAKANA LETTER SI -ジ Zi 30B8 12472 KATAKANA LETTER ZI -ス Su 30B9 12473 KATAKANA LETTER SU -ズ Zu 30BA 12474 KATAKANA LETTER ZU -セ Se 30BB 12475 KATAKANA LETTER SE -ゼ Ze 30BC 12476 KATAKANA LETTER ZE -ソ So 30BD 12477 KATAKANA LETTER SO -ゾ Zo 30BE 12478 KATAKANA LETTER ZO -タ Ta 30BF 12479 KATAKANA LETTER TA -ダ Da 30C0 12480 KATAKANA LETTER DA -チ Ti 30C1 12481 KATAKANA LETTER TI -ヂ Di 30C2 12482 KATAKANA LETTER DI -ッ TU 30C3 12483 KATAKANA LETTER SMALL TU -ツ Tu 30C4 12484 KATAKANA LETTER TU -ヅ Du 30C5 12485 KATAKANA LETTER DU -テ Te 30C6 12486 KATAKANA LETTER TE -デ De 30C7 12487 KATAKANA LETTER DE -ト To 30C8 12488 KATAKANA LETTER TO -ド Do 30C9 12489 KATAKANA LETTER DO -ナ Na 30CA 12490 KATAKANA LETTER NA -ニ Ni 30CB 12491 KATAKANA LETTER NI -ヌ Nu 30CC 12492 KATAKANA LETTER NU -ネ Ne 30CD 12493 KATAKANA LETTER NE -ノ No 30CE 12494 KATAKANA LETTER NO -ハ Ha 30CF 12495 KATAKANA LETTER HA -バ Ba 30D0 12496 KATAKANA LETTER BA -パ Pa 30D1 12497 KATAKANA LETTER PA -ヒ Hi 30D2 12498 KATAKANA LETTER HI -ビ Bi 30D3 12499 KATAKANA LETTER BI -ピ Pi 30D4 12500 KATAKANA LETTER PI -フ Hu 30D5 12501 KATAKANA LETTER HU -ブ Bu 30D6 12502 KATAKANA LETTER BU -プ Pu 30D7 12503 KATAKANA LETTER PU -ヘ He 30D8 12504 KATAKANA LETTER HE -ベ Be 30D9 12505 KATAKANA LETTER BE -ペ Pe 30DA 12506 KATAKANA LETTER PE -ホ Ho 30DB 12507 KATAKANA LETTER HO -ボ Bo 30DC 12508 KATAKANA LETTER BO -ポ Po 30DD 12509 KATAKANA LETTER PO -マ Ma 30DE 12510 KATAKANA LETTER MA -ミ Mi 30DF 12511 KATAKANA LETTER MI -ム Mu 30E0 12512 KATAKANA LETTER MU -メ Me 30E1 12513 KATAKANA LETTER ME -モ Mo 30E2 12514 KATAKANA LETTER MO -ャ YA 30E3 12515 KATAKANA LETTER SMALL YA -ヤ Ya 30E4 12516 KATAKANA LETTER YA -ュ YU 30E5 12517 KATAKANA LETTER SMALL YU -ユ Yu 30E6 12518 KATAKANA LETTER YU -ョ YO 30E7 12519 KATAKANA LETTER SMALL YO -ヨ Yo 30E8 12520 KATAKANA LETTER YO -ラ Ra 30E9 12521 KATAKANA LETTER RA -リ Ri 30EA 12522 KATAKANA LETTER RI -ル Ru 30EB 12523 KATAKANA LETTER RU -レ Re 30EC 12524 KATAKANA LETTER RE -ロ Ro 30ED 12525 KATAKANA LETTER RO -ヮ WA 30EE 12526 KATAKANA LETTER SMALL WA -ワ Wa 30EF 12527 KATAKANA LETTER WA -ヰ Wi 30F0 12528 KATAKANA LETTER WI -ヱ We 30F1 12529 KATAKANA LETTER WE -ヲ Wo 30F2 12530 KATAKANA LETTER WO -ン N6 30F3 12531 KATAKANA LETTER N ` -ヴ Vu 30F4 12532 KATAKANA LETTER VU -ヵ KA 30F5 12533 KATAKANA LETTER SMALL KA -ヶ KE 30F6 12534 KATAKANA LETTER SMALL KE -ヷ Va 30F7 12535 KATAKANA LETTER VA -ヸ Vi 30F8 12536 KATAKANA LETTER VI -ヹ Ve 30F9 12537 KATAKANA LETTER VE -ヺ Vo 30FA 12538 KATAKANA LETTER VO -・ .6 30FB 12539 KATAKANA MIDDLE DOT -ー -6 30FC 12540 KATAKANA-HIRAGANA PROLONGED SOUND MARK -ヽ *6 30FD 12541 KATAKANA ITERATION MARK -ヾ +6 30FE 12542 KATAKANA VOICED ITERATION MARK -ㄅ b4 3105 12549 BOPOMOFO LETTER B -ㄆ p4 3106 12550 BOPOMOFO LETTER P -ㄇ m4 3107 12551 BOPOMOFO LETTER M -ㄈ f4 3108 12552 BOPOMOFO LETTER F -ㄉ d4 3109 12553 BOPOMOFO LETTER D -ㄊ t4 310A 12554 BOPOMOFO LETTER T -ㄋ n4 310B 12555 BOPOMOFO LETTER N ` -ㄌ l4 310C 12556 BOPOMOFO LETTER L -ㄍ g4 310D 12557 BOPOMOFO LETTER G -ㄎ k4 310E 12558 BOPOMOFO LETTER K -ㄏ h4 310F 12559 BOPOMOFO LETTER H -ㄐ j4 3110 12560 BOPOMOFO LETTER J -ㄑ q4 3111 12561 BOPOMOFO LETTER Q -ㄒ x4 3112 12562 BOPOMOFO LETTER X -ㄓ zh 3113 12563 BOPOMOFO LETTER ZH -ㄔ ch 3114 12564 BOPOMOFO LETTER CH -ㄕ sh 3115 12565 BOPOMOFO LETTER SH -ㄖ r4 3116 12566 BOPOMOFO LETTER R -ㄗ z4 3117 12567 BOPOMOFO LETTER Z -ㄘ c4 3118 12568 BOPOMOFO LETTER C -ㄙ s4 3119 12569 BOPOMOFO LETTER S -ㄚ a4 311A 12570 BOPOMOFO LETTER A -ㄛ o4 311B 12571 BOPOMOFO LETTER O -ㄜ e4 311C 12572 BOPOMOFO LETTER E -ㄞ ai 311E 12574 BOPOMOFO LETTER AI -ㄟ ei 311F 12575 BOPOMOFO LETTER EI -ㄠ au 3120 12576 BOPOMOFO LETTER AU -ㄡ ou 3121 12577 BOPOMOFO LETTER OU -ㄢ an 3122 12578 BOPOMOFO LETTER AN -ㄣ en 3123 12579 BOPOMOFO LETTER EN -ㄤ aN 3124 12580 BOPOMOFO LETTER ANG -ㄥ eN 3125 12581 BOPOMOFO LETTER ENG -ㄦ er 3126 12582 BOPOMOFO LETTER ER -ㄧ i4 3127 12583 BOPOMOFO LETTER I -ㄨ u4 3128 12584 BOPOMOFO LETTER U -ㄩ iu 3129 12585 BOPOMOFO LETTER IU -ㄪ v4 312A 12586 BOPOMOFO LETTER V -ㄫ nG 312B 12587 BOPOMOFO LETTER NG -ㄬ gn 312C 12588 BOPOMOFO LETTER GN -㈠ 1c 3220 12832 PARENTHESIZED IDEOGRAPH ONE -㈡ 2c 3221 12833 PARENTHESIZED IDEOGRAPH TWO -㈢ 3c 3222 12834 PARENTHESIZED IDEOGRAPH THREE -㈣ 4c 3223 12835 PARENTHESIZED IDEOGRAPH FOUR -㈤ 5c 3224 12836 PARENTHESIZED IDEOGRAPH FIVE -㈥ 6c 3225 12837 PARENTHESIZED IDEOGRAPH SIX -㈦ 7c 3226 12838 PARENTHESIZED IDEOGRAPH SEVEN -㈧ 8c 3227 12839 PARENTHESIZED IDEOGRAPH EIGHT -㈨ 9c 3228 12840 PARENTHESIZED IDEOGRAPH NINE -ff ff FB00 64256 LATIN SMALL LIGATURE FF -fi fi FB01 64257 LATIN SMALL LIGATURE FI -fl fl FB02 64258 LATIN SMALL LIGATURE FL -ſt ft FB05 64261 LATIN SMALL LIGATURE LONG S T -st st FB06 64262 LATIN SMALL LIGATURE ST + # Nb 0x23 35 NUMBER SIGN + $ DO 0x24 36 DOLLAR SIGN + @ At 0x40 64 COMMERCIAL AT + [ <( 0x5b 91 LEFT SQUARE BRACKET + \ // 0x5c 92 REVERSE SOLIDUS + ] )> 0x5d 93 RIGHT SQUARE BRACKET + ^ '> 0x5e 94 CIRCUMFLEX ACCENT + ` '! 0x60 96 GRAVE ACCENT + { (! 0x7b 123 LEFT CURLY BRACKET + | !! 0x7c 124 VERTICAL LINE + } !) 0x7d 125 RIGHT CURLY BRACKET + ~ '? 0x7e 126 TILDE + ^? DT 0x7f 127 DELETE (DEL) + ~@ PA 0x80 128 PADDING CHARACTER (PAD) + ~A HO 0x81 129 HIGH OCTET PRESET (HOP) + ~B BH 0x82 130 BREAK PERMITTED HERE (BPH) + ~C NH 0x83 131 NO BREAK HERE (NBH) + ~D IN 0x84 132 INDEX (IND) + ~E NL 0x85 133 NEXT LINE (NEL) + ~F SA 0x86 134 START OF SELECTED AREA (SSA) + ~G ES 0x87 135 END OF SELECTED AREA (ESA) + ~H HS 0x88 136 CHARACTER TABULATION SET (HTS) + ~I HJ 0x89 137 CHARACTER TABULATION WITH JUSTIFICATION (HTJ) + ~J VS 0x8a 138 LINE TABULATION SET (VTS) + ~K PD 0x8b 139 PARTIAL LINE FORWARD (PLD) + ~L PU 0x8c 140 PARTIAL LINE BACKWARD (PLU) + ~M RI 0x8d 141 REVERSE LINE FEED (RI) + ~N S2 0x8e 142 SINGLE-SHIFT TWO (SS2) + ~O S3 0x8f 143 SINGLE-SHIFT THREE (SS3) + ~P DC 0x90 144 DEVICE CONTROL STRING (DCS) + ~Q P1 0x91 145 PRIVATE USE ONE (PU1) + ~R P2 0x92 146 PRIVATE USE TWO (PU2) + ~S TS 0x93 147 SET TRANSMIT STATE (STS) + ~T CC 0x94 148 CANCEL CHARACTER (CCH) + ~U MW 0x95 149 MESSAGE WAITING (MW) + ~V SG 0x96 150 START OF GUARDED AREA (SPA) + ~W EG 0x97 151 END OF GUARDED AREA (EPA) + ~X SS 0x98 152 START OF STRING (SOS) + ~Y GC 0x99 153 SINGLE GRAPHIC CHARACTER INTRODUCER (SGCI) + ~Z SC 0x9a 154 SINGLE CHARACTER INTRODUCER (SCI) + ~[ CI 0x9b 155 CONTROL SEQUENCE INTRODUCER (CSI) + ~\ ST 0x9c 156 STRING TERMINATOR (ST) + ~] OC 0x9d 157 OPERATING SYSTEM COMMAND (OSC) + ~^ PM 0x9e 158 PRIVACY MESSAGE (PM) + ~_ AC 0x9f 159 APPLICATION PROGRAM COMMAND (APC) + | NS 0xa0 160 NO-BREAK SPACE + ¡ !I 0xa1 161 INVERTED EXCLAMATION MARK + ¢ Ct 0xa2 162 CENT SIGN + £ Pd 0xa3 163 POUND SIGN + ¤ Cu 0xa4 164 CURRENCY SIGN + ¥ Ye 0xa5 165 YEN SIGN + ¦ BB 0xa6 166 BROKEN BAR + § SE 0xa7 167 SECTION SIGN + ¨ ': 0xa8 168 DIAERESIS + © Co 0xa9 169 COPYRIGHT SIGN + ª -a 0xaa 170 FEMININE ORDINAL INDICATOR + « << 0xab 171 LEFT-POINTING DOUBLE ANGLE QUOTATION MARK + ¬ NO 0xac 172 NOT SIGN + -- 0xad 173 SOFT HYPHEN + ® Rg 0xae 174 REGISTERED SIGN + ¯ 'm 0xaf 175 MACRON + ° DG 0xb0 176 DEGREE SIGN + ± +- 0xb1 177 PLUS-MINUS SIGN + ² 2S 0xb2 178 SUPERSCRIPT TWO + ³ 3S 0xb3 179 SUPERSCRIPT THREE + ´ '' 0xb4 180 ACUTE ACCENT + µ My 0xb5 181 MICRO SIGN + ¶ PI 0xb6 182 PILCROW SIGN + · .M 0xb7 183 MIDDLE DOT + ¸ ', 0xb8 184 CEDILLA + ¹ 1S 0xb9 185 SUPERSCRIPT ONE + º -o 0xba 186 MASCULINE ORDINAL INDICATOR + » >> 0xbb 187 RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK + ¼ 14 0xbc 188 VULGAR FRACTION ONE QUARTER + ½ 12 0xbd 189 VULGAR FRACTION ONE HALF + ¾ 34 0xbe 190 VULGAR FRACTION THREE QUARTERS + ¿ ?I 0xbf 191 INVERTED QUESTION MARK + À A! 0xc0 192 LATIN CAPITAL LETTER A WITH GRAVE + Á A' 0xc1 193 LATIN CAPITAL LETTER A WITH ACUTE +  A> 0xc2 194 LATIN CAPITAL LETTER A WITH CIRCUMFLEX + à A? 0xc3 195 LATIN CAPITAL LETTER A WITH TILDE + Ä A: 0xc4 196 LATIN CAPITAL LETTER A WITH DIAERESIS + Å AA 0xc5 197 LATIN CAPITAL LETTER A WITH RING ABOVE + Æ AE 0xc6 198 LATIN CAPITAL LETTER AE + Ç C, 0xc7 199 LATIN CAPITAL LETTER C WITH CEDILLA + È E! 0xc8 200 LATIN CAPITAL LETTER E WITH GRAVE + É E' 0xc9 201 LATIN CAPITAL LETTER E WITH ACUTE + Ê E> 0xca 202 LATIN CAPITAL LETTER E WITH CIRCUMFLEX + Ë E: 0xcb 203 LATIN CAPITAL LETTER E WITH DIAERESIS + Ì I! 0xcc 204 LATIN CAPITAL LETTER I WITH GRAVE + Í I' 0xcd 205 LATIN CAPITAL LETTER I WITH ACUTE + Î I> 0xce 206 LATIN CAPITAL LETTER I WITH CIRCUMFLEX + Ï I: 0xcf 207 LATIN CAPITAL LETTER I WITH DIAERESIS + Ð D- 0xd0 208 LATIN CAPITAL LETTER ETH (Icelandic) + Ñ N? 0xd1 209 LATIN CAPITAL LETTER N WITH TILDE + Ò O! 0xd2 210 LATIN CAPITAL LETTER O WITH GRAVE + Ó O' 0xd3 211 LATIN CAPITAL LETTER O WITH ACUTE + Ô O> 0xd4 212 LATIN CAPITAL LETTER O WITH CIRCUMFLEX + Õ O? 0xd5 213 LATIN CAPITAL LETTER O WITH TILDE + Ö O: 0xd6 214 LATIN CAPITAL LETTER O WITH DIAERESIS + × *X 0xd7 215 MULTIPLICATION SIGN + Ø O/ 0xd8 216 LATIN CAPITAL LETTER O WITH STROKE + Ù U! 0xd9 217 LATIN CAPITAL LETTER U WITH GRAVE + Ú U' 0xda 218 LATIN CAPITAL LETTER U WITH ACUTE + Û U> 0xdb 219 LATIN CAPITAL LETTER U WITH CIRCUMFLEX + Ü U: 0xdc 220 LATIN CAPITAL LETTER U WITH DIAERESIS + Ý Y' 0xdd 221 LATIN CAPITAL LETTER Y WITH ACUTE + Þ TH 0xde 222 LATIN CAPITAL LETTER THORN (Icelandic) + ß ss 0xdf 223 LATIN SMALL LETTER SHARP S (German) + à a! 0xe0 224 LATIN SMALL LETTER A WITH GRAVE + á a' 0xe1 225 LATIN SMALL LETTER A WITH ACUTE + â a> 0xe2 226 LATIN SMALL LETTER A WITH CIRCUMFLEX + ã a? 0xe3 227 LATIN SMALL LETTER A WITH TILDE + ä a: 0xe4 228 LATIN SMALL LETTER A WITH DIAERESIS + å aa 0xe5 229 LATIN SMALL LETTER A WITH RING ABOVE + æ ae 0xe6 230 LATIN SMALL LETTER AE + ç c, 0xe7 231 LATIN SMALL LETTER C WITH CEDILLA + è e! 0xe8 232 LATIN SMALL LETTER E WITH GRAVE + é e' 0xe9 233 LATIN SMALL LETTER E WITH ACUTE + ê e> 0xea 234 LATIN SMALL LETTER E WITH CIRCUMFLEX + ë e: 0xeb 235 LATIN SMALL LETTER E WITH DIAERESIS + ì i! 0xec 236 LATIN SMALL LETTER I WITH GRAVE + í i' 0xed 237 LATIN SMALL LETTER I WITH ACUTE + î i> 0xee 238 LATIN SMALL LETTER I WITH CIRCUMFLEX + ï i: 0xef 239 LATIN SMALL LETTER I WITH DIAERESIS + ð d- 0xf0 240 LATIN SMALL LETTER ETH (Icelandic) + ñ n? 0xf1 241 LATIN SMALL LETTER N WITH TILDE + ò o! 0xf2 242 LATIN SMALL LETTER O WITH GRAVE + ó o' 0xf3 243 LATIN SMALL LETTER O WITH ACUTE + ô o> 0xf4 244 LATIN SMALL LETTER O WITH CIRCUMFLEX + õ o? 0xf5 245 LATIN SMALL LETTER O WITH TILDE + ö o: 0xf6 246 LATIN SMALL LETTER O WITH DIAERESIS + ÷ -: 0xf7 247 DIVISION SIGN + ø o/ 0xf8 248 LATIN SMALL LETTER O WITH STROKE + ù u! 0xf9 249 LATIN SMALL LETTER U WITH GRAVE + ú u' 0xfa 250 LATIN SMALL LETTER U WITH ACUTE + û u> 0xfb 251 LATIN SMALL LETTER U WITH CIRCUMFLEX + ü u: 0xfc 252 LATIN SMALL LETTER U WITH DIAERESIS + ý y' 0xfd 253 LATIN SMALL LETTER Y WITH ACUTE + þ th 0xfe 254 LATIN SMALL LETTER THORN (Icelandic) + ÿ y: 0xff 255 LATIN SMALL LETTER Y WITH DIAERESIS + Ā A- 0100 0256 LATIN CAPITAL LETTER A WITH MACRON + ā a- 0101 0257 LATIN SMALL LETTER A WITH MACRON + Ă A( 0102 0258 LATIN CAPITAL LETTER A WITH BREVE + ă a( 0103 0259 LATIN SMALL LETTER A WITH BREVE + Ą A; 0104 0260 LATIN CAPITAL LETTER A WITH OGONEK + ą a; 0105 0261 LATIN SMALL LETTER A WITH OGONEK + Ć C' 0106 0262 LATIN CAPITAL LETTER C WITH ACUTE + ć c' 0107 0263 LATIN SMALL LETTER C WITH ACUTE + Ĉ C> 0108 0264 LATIN CAPITAL LETTER C WITH CIRCUMFLEX + ĉ c> 0109 0265 LATIN SMALL LETTER C WITH CIRCUMFLEX + Ċ C. 010A 0266 LATIN CAPITAL LETTER C WITH DOT ABOVE + ċ c. 010B 0267 LATIN SMALL LETTER C WITH DOT ABOVE + Č C< 010C 0268 LATIN CAPITAL LETTER C WITH CARON + č c< 010D 0269 LATIN SMALL LETTER C WITH CARON + Ď D< 010E 0270 LATIN CAPITAL LETTER D WITH CARON + ď d< 010F 0271 LATIN SMALL LETTER D WITH CARON + Đ D/ 0110 0272 LATIN CAPITAL LETTER D WITH STROKE + đ d/ 0111 0273 LATIN SMALL LETTER D WITH STROKE + Ē E- 0112 0274 LATIN CAPITAL LETTER E WITH MACRON + ē e- 0113 0275 LATIN SMALL LETTER E WITH MACRON + Ĕ E( 0114 0276 LATIN CAPITAL LETTER E WITH BREVE + ĕ e( 0115 0277 LATIN SMALL LETTER E WITH BREVE + Ė E. 0116 0278 LATIN CAPITAL LETTER E WITH DOT ABOVE + ė e. 0117 0279 LATIN SMALL LETTER E WITH DOT ABOVE + Ę E; 0118 0280 LATIN CAPITAL LETTER E WITH OGONEK + ę e; 0119 0281 LATIN SMALL LETTER E WITH OGONEK + Ě E< 011A 0282 LATIN CAPITAL LETTER E WITH CARON + ě e< 011B 0283 LATIN SMALL LETTER E WITH CARON + Ĝ G> 011C 0284 LATIN CAPITAL LETTER G WITH CIRCUMFLEX + ĝ g> 011D 0285 LATIN SMALL LETTER G WITH CIRCUMFLEX + Ğ G( 011E 0286 LATIN CAPITAL LETTER G WITH BREVE + ğ g( 011F 0287 LATIN SMALL LETTER G WITH BREVE + Ġ G. 0120 0288 LATIN CAPITAL LETTER G WITH DOT ABOVE + ġ g. 0121 0289 LATIN SMALL LETTER G WITH DOT ABOVE + Ģ G, 0122 0290 LATIN CAPITAL LETTER G WITH CEDILLA + ģ g, 0123 0291 LATIN SMALL LETTER G WITH CEDILLA + Ĥ H> 0124 0292 LATIN CAPITAL LETTER H WITH CIRCUMFLEX + ĥ h> 0125 0293 LATIN SMALL LETTER H WITH CIRCUMFLEX + Ħ H/ 0126 0294 LATIN CAPITAL LETTER H WITH STROKE + ħ h/ 0127 0295 LATIN SMALL LETTER H WITH STROKE + Ĩ I? 0128 0296 LATIN CAPITAL LETTER I WITH TILDE + ĩ i? 0129 0297 LATIN SMALL LETTER I WITH TILDE + Ī I- 012A 0298 LATIN CAPITAL LETTER I WITH MACRON + ī i- 012B 0299 LATIN SMALL LETTER I WITH MACRON + Ĭ I( 012C 0300 LATIN CAPITAL LETTER I WITH BREVE + ĭ i( 012D 0301 LATIN SMALL LETTER I WITH BREVE + Į I; 012E 0302 LATIN CAPITAL LETTER I WITH OGONEK + į i; 012F 0303 LATIN SMALL LETTER I WITH OGONEK + İ I. 0130 0304 LATIN CAPITAL LETTER I WITH DOT ABOVE + ı i. 0131 0305 LATIN SMALL LETTER DOTLESS I + IJ IJ 0132 0306 LATIN CAPITAL LIGATURE IJ + ij ij 0133 0307 LATIN SMALL LIGATURE IJ + Ĵ J> 0134 0308 LATIN CAPITAL LETTER J WITH CIRCUMFLEX + ĵ j> 0135 0309 LATIN SMALL LETTER J WITH CIRCUMFLEX + Ķ K, 0136 0310 LATIN CAPITAL LETTER K WITH CEDILLA + ķ k, 0137 0311 LATIN SMALL LETTER K WITH CEDILLA + ĸ kk 0138 0312 LATIN SMALL LETTER KRA + Ĺ L' 0139 0313 LATIN CAPITAL LETTER L WITH ACUTE + ĺ l' 013A 0314 LATIN SMALL LETTER L WITH ACUTE + Ļ L, 013B 0315 LATIN CAPITAL LETTER L WITH CEDILLA + ļ l, 013C 0316 LATIN SMALL LETTER L WITH CEDILLA + Ľ L< 013D 0317 LATIN CAPITAL LETTER L WITH CARON + ľ l< 013E 0318 LATIN SMALL LETTER L WITH CARON + Ŀ L. 013F 0319 LATIN CAPITAL LETTER L WITH MIDDLE DOT + ŀ l. 0140 0320 LATIN SMALL LETTER L WITH MIDDLE DOT + Ł L/ 0141 0321 LATIN CAPITAL LETTER L WITH STROKE + ł l/ 0142 0322 LATIN SMALL LETTER L WITH STROKE + Ń N' 0143 0323 LATIN CAPITAL LETTER N WITH ACUTE ` + ń n' 0144 0324 LATIN SMALL LETTER N WITH ACUTE ` + Ņ N, 0145 0325 LATIN CAPITAL LETTER N WITH CEDILLA ` + ņ n, 0146 0326 LATIN SMALL LETTER N WITH CEDILLA ` + Ň N< 0147 0327 LATIN CAPITAL LETTER N WITH CARON ` + ň n< 0148 0328 LATIN SMALL LETTER N WITH CARON ` + ʼn 'n 0149 0329 LATIN SMALL LETTER N PRECEDED BY APOSTROPHE ` + Ŋ NG 014A 0330 LATIN CAPITAL LETTER ENG + ŋ ng 014B 0331 LATIN SMALL LETTER ENG + Ō O- 014C 0332 LATIN CAPITAL LETTER O WITH MACRON + ō o- 014D 0333 LATIN SMALL LETTER O WITH MACRON + Ŏ O( 014E 0334 LATIN CAPITAL LETTER O WITH BREVE + ŏ o( 014F 0335 LATIN SMALL LETTER O WITH BREVE + Ő O" 0150 0336 LATIN CAPITAL LETTER O WITH DOUBLE ACUTE + ő o" 0151 0337 LATIN SMALL LETTER O WITH DOUBLE ACUTE + Œ OE 0152 0338 LATIN CAPITAL LIGATURE OE + œ oe 0153 0339 LATIN SMALL LIGATURE OE + Ŕ R' 0154 0340 LATIN CAPITAL LETTER R WITH ACUTE + ŕ r' 0155 0341 LATIN SMALL LETTER R WITH ACUTE + Ŗ R, 0156 0342 LATIN CAPITAL LETTER R WITH CEDILLA + ŗ r, 0157 0343 LATIN SMALL LETTER R WITH CEDILLA + Ř R< 0158 0344 LATIN CAPITAL LETTER R WITH CARON + ř r< 0159 0345 LATIN SMALL LETTER R WITH CARON + Ś S' 015A 0346 LATIN CAPITAL LETTER S WITH ACUTE + ś s' 015B 0347 LATIN SMALL LETTER S WITH ACUTE + Ŝ S> 015C 0348 LATIN CAPITAL LETTER S WITH CIRCUMFLEX + ŝ s> 015D 0349 LATIN SMALL LETTER S WITH CIRCUMFLEX + Ş S, 015E 0350 LATIN CAPITAL LETTER S WITH CEDILLA + ş s, 015F 0351 LATIN SMALL LETTER S WITH CEDILLA + Š S< 0160 0352 LATIN CAPITAL LETTER S WITH CARON + š s< 0161 0353 LATIN SMALL LETTER S WITH CARON + Ţ T, 0162 0354 LATIN CAPITAL LETTER T WITH CEDILLA + ţ t, 0163 0355 LATIN SMALL LETTER T WITH CEDILLA + Ť T< 0164 0356 LATIN CAPITAL LETTER T WITH CARON + ť t< 0165 0357 LATIN SMALL LETTER T WITH CARON + Ŧ T/ 0166 0358 LATIN CAPITAL LETTER T WITH STROKE + ŧ t/ 0167 0359 LATIN SMALL LETTER T WITH STROKE + Ũ U? 0168 0360 LATIN CAPITAL LETTER U WITH TILDE + ũ u? 0169 0361 LATIN SMALL LETTER U WITH TILDE + Ū U- 016A 0362 LATIN CAPITAL LETTER U WITH MACRON + ū u- 016B 0363 LATIN SMALL LETTER U WITH MACRON + Ŭ U( 016C 0364 LATIN CAPITAL LETTER U WITH BREVE + ŭ u( 016D 0365 LATIN SMALL LETTER U WITH BREVE + Ů U0 016E 0366 LATIN CAPITAL LETTER U WITH RING ABOVE + ů u0 016F 0367 LATIN SMALL LETTER U WITH RING ABOVE + Ű U" 0170 0368 LATIN CAPITAL LETTER U WITH DOUBLE ACUTE + ű u" 0171 0369 LATIN SMALL LETTER U WITH DOUBLE ACUTE + Ų U; 0172 0370 LATIN CAPITAL LETTER U WITH OGONEK + ų u; 0173 0371 LATIN SMALL LETTER U WITH OGONEK + Ŵ W> 0174 0372 LATIN CAPITAL LETTER W WITH CIRCUMFLEX + ŵ w> 0175 0373 LATIN SMALL LETTER W WITH CIRCUMFLEX + Ŷ Y> 0176 0374 LATIN CAPITAL LETTER Y WITH CIRCUMFLEX + ŷ y> 0177 0375 LATIN SMALL LETTER Y WITH CIRCUMFLEX + Ÿ Y: 0178 0376 LATIN CAPITAL LETTER Y WITH DIAERESIS + Ź Z' 0179 0377 LATIN CAPITAL LETTER Z WITH ACUTE + ź z' 017A 0378 LATIN SMALL LETTER Z WITH ACUTE + Ż Z. 017B 0379 LATIN CAPITAL LETTER Z WITH DOT ABOVE + ż z. 017C 0380 LATIN SMALL LETTER Z WITH DOT ABOVE + Ž Z< 017D 0381 LATIN CAPITAL LETTER Z WITH CARON + ž z< 017E 0382 LATIN SMALL LETTER Z WITH CARON + Ơ O9 01A0 0416 LATIN CAPITAL LETTER O WITH HORN + ơ o9 01A1 0417 LATIN SMALL LETTER O WITH HORN + Ƣ OI 01A2 0418 LATIN CAPITAL LETTER OI + ƣ oi 01A3 0419 LATIN SMALL LETTER OI + Ʀ yr 01A6 0422 LATIN LETTER YR + Ư U9 01AF 0431 LATIN CAPITAL LETTER U WITH HORN + ư u9 01B0 0432 LATIN SMALL LETTER U WITH HORN + Ƶ Z/ 01B5 0437 LATIN CAPITAL LETTER Z WITH STROKE + ƶ z/ 01B6 0438 LATIN SMALL LETTER Z WITH STROKE + Ʒ ED 01B7 0439 LATIN CAPITAL LETTER EZH + Ǎ A< 01CD 0461 LATIN CAPITAL LETTER A WITH CARON + ǎ a< 01CE 0462 LATIN SMALL LETTER A WITH CARON + Ǐ I< 01CF 0463 LATIN CAPITAL LETTER I WITH CARON + ǐ i< 01D0 0464 LATIN SMALL LETTER I WITH CARON + Ǒ O< 01D1 0465 LATIN CAPITAL LETTER O WITH CARON + ǒ o< 01D2 0466 LATIN SMALL LETTER O WITH CARON + Ǔ U< 01D3 0467 LATIN CAPITAL LETTER U WITH CARON + ǔ u< 01D4 0468 LATIN SMALL LETTER U WITH CARON + Ǟ A1 01DE 0478 LATIN CAPITAL LETTER A WITH DIAERESIS AND MACRON + ǟ a1 01DF 0479 LATIN SMALL LETTER A WITH DIAERESIS AND MACRON + Ǡ A7 01E0 0480 LATIN CAPITAL LETTER A WITH DOT ABOVE AND MACRON + ǡ a7 01E1 0481 LATIN SMALL LETTER A WITH DOT ABOVE AND MACRON + Ǣ A3 01E2 0482 LATIN CAPITAL LETTER AE WITH MACRON + ǣ a3 01E3 0483 LATIN SMALL LETTER AE WITH MACRON + Ǥ G/ 01E4 0484 LATIN CAPITAL LETTER G WITH STROKE + ǥ g/ 01E5 0485 LATIN SMALL LETTER G WITH STROKE + Ǧ G< 01E6 0486 LATIN CAPITAL LETTER G WITH CARON + ǧ g< 01E7 0487 LATIN SMALL LETTER G WITH CARON + Ǩ K< 01E8 0488 LATIN CAPITAL LETTER K WITH CARON + ǩ k< 01E9 0489 LATIN SMALL LETTER K WITH CARON + Ǫ O; 01EA 0490 LATIN CAPITAL LETTER O WITH OGONEK + ǫ o; 01EB 0491 LATIN SMALL LETTER O WITH OGONEK + Ǭ O1 01EC 0492 LATIN CAPITAL LETTER O WITH OGONEK AND MACRON + ǭ o1 01ED 0493 LATIN SMALL LETTER O WITH OGONEK AND MACRON + Ǯ EZ 01EE 0494 LATIN CAPITAL LETTER EZH WITH CARON + ǯ ez 01EF 0495 LATIN SMALL LETTER EZH WITH CARON + ǰ j< 01F0 0496 LATIN SMALL LETTER J WITH CARON + Ǵ G' 01F4 0500 LATIN CAPITAL LETTER G WITH ACUTE + ǵ g' 01F5 0501 LATIN SMALL LETTER G WITH ACUTE + ʿ ;S 02BF 0703 MODIFIER LETTER LEFT HALF RING + ˇ '< 02C7 0711 CARON + ˘ '( 02D8 0728 BREVE + ˙ '. 02D9 0729 DOT ABOVE + ˚ '0 02DA 0730 RING ABOVE + ˛ '; 02DB 0731 OGONEK + ˝ '" 02DD 0733 DOUBLE ACUTE ACCENT + Ά A% 0386 0902 GREEK CAPITAL LETTER ALPHA WITH TONOS + Έ E% 0388 0904 GREEK CAPITAL LETTER EPSILON WITH TONOS + Ή Y% 0389 0905 GREEK CAPITAL LETTER ETA WITH TONOS + Ί I% 038A 0906 GREEK CAPITAL LETTER IOTA WITH TONOS + Ό O% 038C 0908 GREEK CAPITAL LETTER OMICRON WITH TONOS + Ύ U% 038E 0910 GREEK CAPITAL LETTER UPSILON WITH TONOS + Ώ W% 038F 0911 GREEK CAPITAL LETTER OMEGA WITH TONOS + ΐ i3 0390 0912 GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS + Α A* 0391 0913 GREEK CAPITAL LETTER ALPHA + Β B* 0392 0914 GREEK CAPITAL LETTER BETA + Γ G* 0393 0915 GREEK CAPITAL LETTER GAMMA + Δ D* 0394 0916 GREEK CAPITAL LETTER DELTA + Ε E* 0395 0917 GREEK CAPITAL LETTER EPSILON + Ζ Z* 0396 0918 GREEK CAPITAL LETTER ZETA + Η Y* 0397 0919 GREEK CAPITAL LETTER ETA + Θ H* 0398 0920 GREEK CAPITAL LETTER THETA + Ι I* 0399 0921 GREEK CAPITAL LETTER IOTA + Κ K* 039A 0922 GREEK CAPITAL LETTER KAPPA + Λ L* 039B 0923 GREEK CAPITAL LETTER LAMDA (aka LAMBDA) + Μ M* 039C 0924 GREEK CAPITAL LETTER MU + Ν N* 039D 0925 GREEK CAPITAL LETTER NU + Ξ C* 039E 0926 GREEK CAPITAL LETTER XI + Ο O* 039F 0927 GREEK CAPITAL LETTER OMICRON + Π P* 03A0 0928 GREEK CAPITAL LETTER PI + Ρ R* 03A1 0929 GREEK CAPITAL LETTER RHO + Σ S* 03A3 0931 GREEK CAPITAL LETTER SIGMA + Τ T* 03A4 0932 GREEK CAPITAL LETTER TAU + Υ U* 03A5 0933 GREEK CAPITAL LETTER UPSILON + Φ F* 03A6 0934 GREEK CAPITAL LETTER PHI + Χ X* 03A7 0935 GREEK CAPITAL LETTER CHI + Ψ Q* 03A8 0936 GREEK CAPITAL LETTER PSI + Ω W* 03A9 0937 GREEK CAPITAL LETTER OMEGA + Ϊ J* 03AA 0938 GREEK CAPITAL LETTER IOTA WITH DIALYTIKA + Ϋ V* 03AB 0939 GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA + ά a% 03AC 0940 GREEK SMALL LETTER ALPHA WITH TONOS + έ e% 03AD 0941 GREEK SMALL LETTER EPSILON WITH TONOS + ή y% 03AE 0942 GREEK SMALL LETTER ETA WITH TONOS + ί i% 03AF 0943 GREEK SMALL LETTER IOTA WITH TONOS + ΰ u3 03B0 0944 GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS + α a* 03B1 0945 GREEK SMALL LETTER ALPHA + β b* 03B2 0946 GREEK SMALL LETTER BETA + γ g* 03B3 0947 GREEK SMALL LETTER GAMMA + δ d* 03B4 0948 GREEK SMALL LETTER DELTA + ε e* 03B5 0949 GREEK SMALL LETTER EPSILON + ζ z* 03B6 0950 GREEK SMALL LETTER ZETA + η y* 03B7 0951 GREEK SMALL LETTER ETA + θ h* 03B8 0952 GREEK SMALL LETTER THETA + ι i* 03B9 0953 GREEK SMALL LETTER IOTA + κ k* 03BA 0954 GREEK SMALL LETTER KAPPA + λ l* 03BB 0955 GREEK SMALL LETTER LAMDA (aka LAMBDA) + μ m* 03BC 0956 GREEK SMALL LETTER MU + ν n* 03BD 0957 GREEK SMALL LETTER NU + ξ c* 03BE 0958 GREEK SMALL LETTER XI + ο o* 03BF 0959 GREEK SMALL LETTER OMICRON + π p* 03C0 0960 GREEK SMALL LETTER PI + ρ r* 03C1 0961 GREEK SMALL LETTER RHO + ς *s 03C2 0962 GREEK SMALL LETTER FINAL SIGMA + σ s* 03C3 0963 GREEK SMALL LETTER SIGMA + τ t* 03C4 0964 GREEK SMALL LETTER TAU + υ u* 03C5 0965 GREEK SMALL LETTER UPSILON + φ f* 03C6 0966 GREEK SMALL LETTER PHI + χ x* 03C7 0967 GREEK SMALL LETTER CHI + ψ q* 03C8 0968 GREEK SMALL LETTER PSI + ω w* 03C9 0969 GREEK SMALL LETTER OMEGA + ϊ j* 03CA 0970 GREEK SMALL LETTER IOTA WITH DIALYTIKA + ϋ v* 03CB 0971 GREEK SMALL LETTER UPSILON WITH DIALYTIKA + ό o% 03CC 0972 GREEK SMALL LETTER OMICRON WITH TONOS + ύ u% 03CD 0973 GREEK SMALL LETTER UPSILON WITH TONOS + ώ w% 03CE 0974 GREEK SMALL LETTER OMEGA WITH TONOS + Ϙ 'G 03D8 0984 GREEK LETTER ARCHAIC KOPPA + ϙ ,G 03D9 0985 GREEK SMALL LETTER ARCHAIC KOPPA + Ϛ T3 03DA 0986 GREEK LETTER STIGMA + ϛ t3 03DB 0987 GREEK SMALL LETTER STIGMA + Ϝ M3 03DC 0988 GREEK LETTER DIGAMMA + ϝ m3 03DD 0989 GREEK SMALL LETTER DIGAMMA + Ϟ K3 03DE 0990 GREEK LETTER KOPPA + ϟ k3 03DF 0991 GREEK SMALL LETTER KOPPA + Ϡ P3 03E0 0992 GREEK LETTER SAMPI + ϡ p3 03E1 0993 GREEK SMALL LETTER SAMPI + ϴ '% 03F4 1012 GREEK CAPITAL THETA SYMBOL + ϵ j3 03F5 1013 GREEK LUNATE EPSILON SYMBOL + Ё IO 0401 1025 CYRILLIC CAPITAL LETTER IO + Ђ D% 0402 1026 CYRILLIC CAPITAL LETTER DJE + Ѓ G% 0403 1027 CYRILLIC CAPITAL LETTER GJE + Є IE 0404 1028 CYRILLIC CAPITAL LETTER UKRAINIAN IE + Ѕ DS 0405 1029 CYRILLIC CAPITAL LETTER DZE + І II 0406 1030 CYRILLIC CAPITAL LETTER BYELORUSSIAN-UKRAINIAN I + Ї YI 0407 1031 CYRILLIC CAPITAL LETTER YI + Ј J% 0408 1032 CYRILLIC CAPITAL LETTER JE + Љ LJ 0409 1033 CYRILLIC CAPITAL LETTER LJE + Њ NJ 040A 1034 CYRILLIC CAPITAL LETTER NJE + Ћ Ts 040B 1035 CYRILLIC CAPITAL LETTER TSHE + Ќ KJ 040C 1036 CYRILLIC CAPITAL LETTER KJE + Ў V% 040E 1038 CYRILLIC CAPITAL LETTER SHORT U + Џ DZ 040F 1039 CYRILLIC CAPITAL LETTER DZHE + А A= 0410 1040 CYRILLIC CAPITAL LETTER A + Б B= 0411 1041 CYRILLIC CAPITAL LETTER BE + В V= 0412 1042 CYRILLIC CAPITAL LETTER VE + Г G= 0413 1043 CYRILLIC CAPITAL LETTER GHE + Д D= 0414 1044 CYRILLIC CAPITAL LETTER DE + Е E= 0415 1045 CYRILLIC CAPITAL LETTER IE + Ж Z% 0416 1046 CYRILLIC CAPITAL LETTER ZHE + З Z= 0417 1047 CYRILLIC CAPITAL LETTER ZE + И I= 0418 1048 CYRILLIC CAPITAL LETTER I + Й J= 0419 1049 CYRILLIC CAPITAL LETTER SHORT I + К K= 041A 1050 CYRILLIC CAPITAL LETTER KA + Л L= 041B 1051 CYRILLIC CAPITAL LETTER EL + М M= 041C 1052 CYRILLIC CAPITAL LETTER EM + Н N= 041D 1053 CYRILLIC CAPITAL LETTER EN + О O= 041E 1054 CYRILLIC CAPITAL LETTER O + П P= 041F 1055 CYRILLIC CAPITAL LETTER PE + Р R= 0420 1056 CYRILLIC CAPITAL LETTER ER + С S= 0421 1057 CYRILLIC CAPITAL LETTER ES + Т T= 0422 1058 CYRILLIC CAPITAL LETTER TE + У U= 0423 1059 CYRILLIC CAPITAL LETTER U + Ф F= 0424 1060 CYRILLIC CAPITAL LETTER EF + Х H= 0425 1061 CYRILLIC CAPITAL LETTER HA + Ц C= 0426 1062 CYRILLIC CAPITAL LETTER TSE + Ч C% 0427 1063 CYRILLIC CAPITAL LETTER CHE + Ш S% 0428 1064 CYRILLIC CAPITAL LETTER SHA + Щ Sc 0429 1065 CYRILLIC CAPITAL LETTER SHCHA + Ъ =" 042A 1066 CYRILLIC CAPITAL LETTER HARD SIGN + Ы Y= 042B 1067 CYRILLIC CAPITAL LETTER YERU + Ь %" 042C 1068 CYRILLIC CAPITAL LETTER SOFT SIGN + Э JE 042D 1069 CYRILLIC CAPITAL LETTER E + Ю JU 042E 1070 CYRILLIC CAPITAL LETTER YU + Я JA 042F 1071 CYRILLIC CAPITAL LETTER YA + а a= 0430 1072 CYRILLIC SMALL LETTER A + б b= 0431 1073 CYRILLIC SMALL LETTER BE + в v= 0432 1074 CYRILLIC SMALL LETTER VE + г g= 0433 1075 CYRILLIC SMALL LETTER GHE + д d= 0434 1076 CYRILLIC SMALL LETTER DE + е e= 0435 1077 CYRILLIC SMALL LETTER IE + ж z% 0436 1078 CYRILLIC SMALL LETTER ZHE + з z= 0437 1079 CYRILLIC SMALL LETTER ZE + и i= 0438 1080 CYRILLIC SMALL LETTER I + й j= 0439 1081 CYRILLIC SMALL LETTER SHORT I + к k= 043A 1082 CYRILLIC SMALL LETTER KA + л l= 043B 1083 CYRILLIC SMALL LETTER EL + м m= 043C 1084 CYRILLIC SMALL LETTER EM + н n= 043D 1085 CYRILLIC SMALL LETTER EN + о o= 043E 1086 CYRILLIC SMALL LETTER O + п p= 043F 1087 CYRILLIC SMALL LETTER PE + р r= 0440 1088 CYRILLIC SMALL LETTER ER + с s= 0441 1089 CYRILLIC SMALL LETTER ES + т t= 0442 1090 CYRILLIC SMALL LETTER TE + у u= 0443 1091 CYRILLIC SMALL LETTER U + ф f= 0444 1092 CYRILLIC SMALL LETTER EF + х h= 0445 1093 CYRILLIC SMALL LETTER HA + ц c= 0446 1094 CYRILLIC SMALL LETTER TSE + ч c% 0447 1095 CYRILLIC SMALL LETTER CHE + ш s% 0448 1096 CYRILLIC SMALL LETTER SHA + щ sc 0449 1097 CYRILLIC SMALL LETTER SHCHA + ъ =' 044A 1098 CYRILLIC SMALL LETTER HARD SIGN + ы y= 044B 1099 CYRILLIC SMALL LETTER YERU + ь %' 044C 1100 CYRILLIC SMALL LETTER SOFT SIGN + э je 044D 1101 CYRILLIC SMALL LETTER E + ю ju 044E 1102 CYRILLIC SMALL LETTER YU + я ja 044F 1103 CYRILLIC SMALL LETTER YA + ё io 0451 1105 CYRILLIC SMALL LETTER IO + ђ d% 0452 1106 CYRILLIC SMALL LETTER DJE + ѓ g% 0453 1107 CYRILLIC SMALL LETTER GJE + є ie 0454 1108 CYRILLIC SMALL LETTER UKRAINIAN IE + ѕ ds 0455 1109 CYRILLIC SMALL LETTER DZE + і ii 0456 1110 CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I + ї yi 0457 1111 CYRILLIC SMALL LETTER YI + ј j% 0458 1112 CYRILLIC SMALL LETTER JE + љ lj 0459 1113 CYRILLIC SMALL LETTER LJE + њ nj 045A 1114 CYRILLIC SMALL LETTER NJE + ћ ts 045B 1115 CYRILLIC SMALL LETTER TSHE + ќ kj 045C 1116 CYRILLIC SMALL LETTER KJE + ў v% 045E 1118 CYRILLIC SMALL LETTER SHORT U + џ dz 045F 1119 CYRILLIC SMALL LETTER DZHE + Ѣ Y3 0462 1122 CYRILLIC CAPITAL LETTER YAT + ѣ y3 0463 1123 CYRILLIC SMALL LETTER YAT + Ѫ O3 046A 1130 CYRILLIC CAPITAL LETTER BIG YUS + ѫ o3 046B 1131 CYRILLIC SMALL LETTER BIG YUS + Ѳ F3 0472 1138 CYRILLIC CAPITAL LETTER FITA + ѳ f3 0473 1139 CYRILLIC SMALL LETTER FITA + Ѵ V3 0474 1140 CYRILLIC CAPITAL LETTER IZHITSA + ѵ v3 0475 1141 CYRILLIC SMALL LETTER IZHITSA + Ҁ C3 0480 1152 CYRILLIC CAPITAL LETTER KOPPA + ҁ c3 0481 1153 CYRILLIC SMALL LETTER KOPPA + Ґ G3 0490 1168 CYRILLIC CAPITAL LETTER GHE WITH UPTURN + ґ g3 0491 1169 CYRILLIC SMALL LETTER GHE WITH UPTURN + א A+ 05D0 1488 HEBREW LETTER ALEF + ב B+ 05D1 1489 HEBREW LETTER BET + ג G+ 05D2 1490 HEBREW LETTER GIMEL + ד D+ 05D3 1491 HEBREW LETTER DALET + ה H+ 05D4 1492 HEBREW LETTER HE + ו W+ 05D5 1493 HEBREW LETTER VAV + ז Z+ 05D6 1494 HEBREW LETTER ZAYIN + ח X+ 05D7 1495 HEBREW LETTER HET + ט Tj 05D8 1496 HEBREW LETTER TET + י J+ 05D9 1497 HEBREW LETTER YOD + ך K% 05DA 1498 HEBREW LETTER FINAL KAF + כ K+ 05DB 1499 HEBREW LETTER KAF + ל L+ 05DC 1500 HEBREW LETTER LAMED + ם M% 05DD 1501 HEBREW LETTER FINAL MEM + מ M+ 05DE 1502 HEBREW LETTER MEM + ן N% 05DF 1503 HEBREW LETTER FINAL NUN ` + נ N+ 05E0 1504 HEBREW LETTER NUN ` + ס S+ 05E1 1505 HEBREW LETTER SAMEKH + ע E+ 05E2 1506 HEBREW LETTER AYIN + ף P% 05E3 1507 HEBREW LETTER FINAL PE + פ P+ 05E4 1508 HEBREW LETTER PE + ץ Zj 05E5 1509 HEBREW LETTER FINAL TSADI + צ ZJ 05E6 1510 HEBREW LETTER TSADI + ק Q+ 05E7 1511 HEBREW LETTER QOF + ר R+ 05E8 1512 HEBREW LETTER RESH + ש Sh 05E9 1513 HEBREW LETTER SHIN + ת T+ 05EA 1514 HEBREW LETTER TAV + ، ,+ 060C 1548 ARABIC COMMA + ؛ ;+ 061B 1563 ARABIC SEMICOLON + ؟ ?+ 061F 1567 ARABIC QUESTION MARK + ء H' 0621 1569 ARABIC LETTER HAMZA + آ aM 0622 1570 ARABIC LETTER ALEF WITH MADDA ABOVE + أ aH 0623 1571 ARABIC LETTER ALEF WITH HAMZA ABOVE + ؤ wH 0624 1572 ARABIC LETTER WAW WITH HAMZA ABOVE + إ ah 0625 1573 ARABIC LETTER ALEF WITH HAMZA BELOW + ئ yH 0626 1574 ARABIC LETTER YEH WITH HAMZA ABOVE + ا a+ 0627 1575 ARABIC LETTER ALEF + ب b+ 0628 1576 ARABIC LETTER BEH + ة tm 0629 1577 ARABIC LETTER TEH MARBUTA + ت t+ 062A 1578 ARABIC LETTER TEH + ث tk 062B 1579 ARABIC LETTER THEH + ج g+ 062C 1580 ARABIC LETTER JEEM + ح hk 062D 1581 ARABIC LETTER HAH + خ x+ 062E 1582 ARABIC LETTER KHAH + د d+ 062F 1583 ARABIC LETTER DAL + ذ dk 0630 1584 ARABIC LETTER THAL + ر r+ 0631 1585 ARABIC LETTER REH + ز z+ 0632 1586 ARABIC LETTER ZAIN + س s+ 0633 1587 ARABIC LETTER SEEN + ش sn 0634 1588 ARABIC LETTER SHEEN + ص c+ 0635 1589 ARABIC LETTER SAD + ض dd 0636 1590 ARABIC LETTER DAD + ط tj 0637 1591 ARABIC LETTER TAH + ظ zH 0638 1592 ARABIC LETTER ZAH + ع e+ 0639 1593 ARABIC LETTER AIN + غ i+ 063A 1594 ARABIC LETTER GHAIN + ـ ++ 0640 1600 ARABIC TATWEEL + ف f+ 0641 1601 ARABIC LETTER FEH + ق q+ 0642 1602 ARABIC LETTER QAF + ك k+ 0643 1603 ARABIC LETTER KAF + ل l+ 0644 1604 ARABIC LETTER LAM + م m+ 0645 1605 ARABIC LETTER MEEM + ن n+ 0646 1606 ARABIC LETTER NOON + ه h+ 0647 1607 ARABIC LETTER HEH + و w+ 0648 1608 ARABIC LETTER WAW + ى j+ 0649 1609 ARABIC LETTER ALEF MAKSURA + ي y+ 064A 1610 ARABIC LETTER YEH + ً :+ 064B 1611 ARABIC FATHATAN + ٌ "+ 064C 1612 ARABIC DAMMATAN + ٍ =+ 064D 1613 ARABIC KASRATAN + َ /+ 064E 1614 ARABIC FATHA + ُ '+ 064F 1615 ARABIC DAMMA + ِ 1+ 0650 1616 ARABIC KASRA + ّ 3+ 0651 1617 ARABIC SHADDA + ْ 0+ 0652 1618 ARABIC SUKUN + ٰ aS 0670 1648 ARABIC LETTER SUPERSCRIPT ALEF + پ p+ 067E 1662 ARABIC LETTER PEH + ڤ v+ 06A4 1700 ARABIC LETTER VEH + گ gf 06AF 1711 ARABIC LETTER GAF + ۰ 0a 06F0 1776 EXTENDED ARABIC-INDIC DIGIT ZERO + ۱ 1a 06F1 1777 EXTENDED ARABIC-INDIC DIGIT ONE + ۲ 2a 06F2 1778 EXTENDED ARABIC-INDIC DIGIT TWO + ۳ 3a 06F3 1779 EXTENDED ARABIC-INDIC DIGIT THREE + ۴ 4a 06F4 1780 EXTENDED ARABIC-INDIC DIGIT FOUR + ۵ 5a 06F5 1781 EXTENDED ARABIC-INDIC DIGIT FIVE + ۶ 6a 06F6 1782 EXTENDED ARABIC-INDIC DIGIT SIX + ۷ 7a 06F7 1783 EXTENDED ARABIC-INDIC DIGIT SEVEN + ۸ 8a 06F8 1784 EXTENDED ARABIC-INDIC DIGIT EIGHT + ۹ 9a 06F9 1785 EXTENDED ARABIC-INDIC DIGIT NINE + Ḃ B. 1E02 7682 LATIN CAPITAL LETTER B WITH DOT ABOVE + ḃ b. 1E03 7683 LATIN SMALL LETTER B WITH DOT ABOVE + Ḇ B_ 1E06 7686 LATIN CAPITAL LETTER B WITH LINE BELOW + ḇ b_ 1E07 7687 LATIN SMALL LETTER B WITH LINE BELOW + Ḋ D. 1E0A 7690 LATIN CAPITAL LETTER D WITH DOT ABOVE + ḋ d. 1E0B 7691 LATIN SMALL LETTER D WITH DOT ABOVE + Ḏ D_ 1E0E 7694 LATIN CAPITAL LETTER D WITH LINE BELOW + ḏ d_ 1E0F 7695 LATIN SMALL LETTER D WITH LINE BELOW + Ḑ D, 1E10 7696 LATIN CAPITAL LETTER D WITH CEDILLA + ḑ d, 1E11 7697 LATIN SMALL LETTER D WITH CEDILLA + Ḟ F. 1E1E 7710 LATIN CAPITAL LETTER F WITH DOT ABOVE + ḟ f. 1E1F 7711 LATIN SMALL LETTER F WITH DOT ABOVE + Ḡ G- 1E20 7712 LATIN CAPITAL LETTER G WITH MACRON + ḡ g- 1E21 7713 LATIN SMALL LETTER G WITH MACRON + Ḣ H. 1E22 7714 LATIN CAPITAL LETTER H WITH DOT ABOVE + ḣ h. 1E23 7715 LATIN SMALL LETTER H WITH DOT ABOVE + Ḧ H: 1E26 7718 LATIN CAPITAL LETTER H WITH DIAERESIS + ḧ h: 1E27 7719 LATIN SMALL LETTER H WITH DIAERESIS + Ḩ H, 1E28 7720 LATIN CAPITAL LETTER H WITH CEDILLA + ḩ h, 1E29 7721 LATIN SMALL LETTER H WITH CEDILLA + Ḱ K' 1E30 7728 LATIN CAPITAL LETTER K WITH ACUTE + ḱ k' 1E31 7729 LATIN SMALL LETTER K WITH ACUTE + Ḵ K_ 1E34 7732 LATIN CAPITAL LETTER K WITH LINE BELOW + ḵ k_ 1E35 7733 LATIN SMALL LETTER K WITH LINE BELOW + Ḻ L_ 1E3A 7738 LATIN CAPITAL LETTER L WITH LINE BELOW + ḻ l_ 1E3B 7739 LATIN SMALL LETTER L WITH LINE BELOW + Ḿ M' 1E3E 7742 LATIN CAPITAL LETTER M WITH ACUTE + ḿ m' 1E3F 7743 LATIN SMALL LETTER M WITH ACUTE + Ṁ M. 1E40 7744 LATIN CAPITAL LETTER M WITH DOT ABOVE + ṁ m. 1E41 7745 LATIN SMALL LETTER M WITH DOT ABOVE + Ṅ N. 1E44 7748 LATIN CAPITAL LETTER N WITH DOT ABOVE ` + ṅ n. 1E45 7749 LATIN SMALL LETTER N WITH DOT ABOVE ` + Ṉ N_ 1E48 7752 LATIN CAPITAL LETTER N WITH LINE BELOW ` + ṉ n_ 1E49 7753 LATIN SMALL LETTER N WITH LINE BELOW ` + Ṕ P' 1E54 7764 LATIN CAPITAL LETTER P WITH ACUTE + ṕ p' 1E55 7765 LATIN SMALL LETTER P WITH ACUTE + Ṗ P. 1E56 7766 LATIN CAPITAL LETTER P WITH DOT ABOVE + ṗ p. 1E57 7767 LATIN SMALL LETTER P WITH DOT ABOVE + Ṙ R. 1E58 7768 LATIN CAPITAL LETTER R WITH DOT ABOVE + ṙ r. 1E59 7769 LATIN SMALL LETTER R WITH DOT ABOVE + Ṟ R_ 1E5E 7774 LATIN CAPITAL LETTER R WITH LINE BELOW + ṟ r_ 1E5F 7775 LATIN SMALL LETTER R WITH LINE BELOW + Ṡ S. 1E60 7776 LATIN CAPITAL LETTER S WITH DOT ABOVE + ṡ s. 1E61 7777 LATIN SMALL LETTER S WITH DOT ABOVE + Ṫ T. 1E6A 7786 LATIN CAPITAL LETTER T WITH DOT ABOVE + ṫ t. 1E6B 7787 LATIN SMALL LETTER T WITH DOT ABOVE + Ṯ T_ 1E6E 7790 LATIN CAPITAL LETTER T WITH LINE BELOW + ṯ t_ 1E6F 7791 LATIN SMALL LETTER T WITH LINE BELOW + Ṽ V? 1E7C 7804 LATIN CAPITAL LETTER V WITH TILDE + ṽ v? 1E7D 7805 LATIN SMALL LETTER V WITH TILDE + Ẁ W! 1E80 7808 LATIN CAPITAL LETTER W WITH GRAVE + ẁ w! 1E81 7809 LATIN SMALL LETTER W WITH GRAVE + Ẃ W' 1E82 7810 LATIN CAPITAL LETTER W WITH ACUTE + ẃ w' 1E83 7811 LATIN SMALL LETTER W WITH ACUTE + Ẅ W: 1E84 7812 LATIN CAPITAL LETTER W WITH DIAERESIS + ẅ w: 1E85 7813 LATIN SMALL LETTER W WITH DIAERESIS + Ẇ W. 1E86 7814 LATIN CAPITAL LETTER W WITH DOT ABOVE + ẇ w. 1E87 7815 LATIN SMALL LETTER W WITH DOT ABOVE + Ẋ X. 1E8A 7818 LATIN CAPITAL LETTER X WITH DOT ABOVE + ẋ x. 1E8B 7819 LATIN SMALL LETTER X WITH DOT ABOVE + Ẍ X: 1E8C 7820 LATIN CAPITAL LETTER X WITH DIAERESIS + ẍ x: 1E8D 7821 LATIN SMALL LETTER X WITH DIAERESIS + Ẏ Y. 1E8E 7822 LATIN CAPITAL LETTER Y WITH DOT ABOVE + ẏ y. 1E8F 7823 LATIN SMALL LETTER Y WITH DOT ABOVE + Ẑ Z> 1E90 7824 LATIN CAPITAL LETTER Z WITH CIRCUMFLEX + ẑ z> 1E91 7825 LATIN SMALL LETTER Z WITH CIRCUMFLEX + Ẕ Z_ 1E94 7828 LATIN CAPITAL LETTER Z WITH LINE BELOW + ẕ z_ 1E95 7829 LATIN SMALL LETTER Z WITH LINE BELOW + ẖ h_ 1E96 7830 LATIN SMALL LETTER H WITH LINE BELOW + ẗ t: 1E97 7831 LATIN SMALL LETTER T WITH DIAERESIS + ẘ w0 1E98 7832 LATIN SMALL LETTER W WITH RING ABOVE + ẙ y0 1E99 7833 LATIN SMALL LETTER Y WITH RING ABOVE + Ả A2 1EA2 7842 LATIN CAPITAL LETTER A WITH HOOK ABOVE + ả a2 1EA3 7843 LATIN SMALL LETTER A WITH HOOK ABOVE + Ẻ E2 1EBA 7866 LATIN CAPITAL LETTER E WITH HOOK ABOVE + ẻ e2 1EBB 7867 LATIN SMALL LETTER E WITH HOOK ABOVE + Ẽ E? 1EBC 7868 LATIN CAPITAL LETTER E WITH TILDE + ẽ e? 1EBD 7869 LATIN SMALL LETTER E WITH TILDE + Ỉ I2 1EC8 7880 LATIN CAPITAL LETTER I WITH HOOK ABOVE + ỉ i2 1EC9 7881 LATIN SMALL LETTER I WITH HOOK ABOVE + Ỏ O2 1ECE 7886 LATIN CAPITAL LETTER O WITH HOOK ABOVE + ỏ o2 1ECF 7887 LATIN SMALL LETTER O WITH HOOK ABOVE + Ủ U2 1EE6 7910 LATIN CAPITAL LETTER U WITH HOOK ABOVE + ủ u2 1EE7 7911 LATIN SMALL LETTER U WITH HOOK ABOVE + Ỳ Y! 1EF2 7922 LATIN CAPITAL LETTER Y WITH GRAVE + ỳ y! 1EF3 7923 LATIN SMALL LETTER Y WITH GRAVE + Ỷ Y2 1EF6 7926 LATIN CAPITAL LETTER Y WITH HOOK ABOVE + ỷ y2 1EF7 7927 LATIN SMALL LETTER Y WITH HOOK ABOVE + Ỹ Y? 1EF8 7928 LATIN CAPITAL LETTER Y WITH TILDE + ỹ y? 1EF9 7929 LATIN SMALL LETTER Y WITH TILDE + ἀ ;' 1F00 7936 GREEK SMALL LETTER ALPHA WITH PSILI + ἁ ,' 1F01 7937 GREEK SMALL LETTER ALPHA WITH DASIA + ἂ ;! 1F02 7938 GREEK SMALL LETTER ALPHA WITH PSILI AND VARIA + ἃ ,! 1F03 7939 GREEK SMALL LETTER ALPHA WITH DASIA AND VARIA + ἄ ?; 1F04 7940 GREEK SMALL LETTER ALPHA WITH PSILI AND OXIA + ἅ ?, 1F05 7941 GREEK SMALL LETTER ALPHA WITH DASIA AND OXIA + ἆ !: 1F06 7942 GREEK SMALL LETTER ALPHA WITH PSILI AND PERISPOMENI + ἇ ?: 1F07 7943 GREEK SMALL LETTER ALPHA WITH DASIA AND PERISPOMENI + 1N 2002 8194 EN SPACE + 1M 2003 8195 EM SPACE + 3M 2004 8196 THREE-PER-EM SPACE + 4M 2005 8197 FOUR-PER-EM SPACE + 6M 2006 8198 SIX-PER-EM SPACE + 1T 2009 8201 THIN SPACE + 1H 200A 8202 HAIR SPACE + ‐ -1 2010 8208 HYPHEN + – -N 2013 8211 EN DASH ` + — -M 2014 8212 EM DASH + ― -3 2015 8213 HORIZONTAL BAR + ‖ !2 2016 8214 DOUBLE VERTICAL LINE + ‗ =2 2017 8215 DOUBLE LOW LINE + ‘ '6 2018 8216 LEFT SINGLE QUOTATION MARK + ’ '9 2019 8217 RIGHT SINGLE QUOTATION MARK + ‚ .9 201A 8218 SINGLE LOW-9 QUOTATION MARK + ‛ 9' 201B 8219 SINGLE HIGH-REVERSED-9 QUOTATION MARK + “ "6 201C 8220 LEFT DOUBLE QUOTATION MARK + ” "9 201D 8221 RIGHT DOUBLE QUOTATION MARK + „ :9 201E 8222 DOUBLE LOW-9 QUOTATION MARK + ‟ 9" 201F 8223 DOUBLE HIGH-REVERSED-9 QUOTATION MARK + † /- 2020 8224 DAGGER + ‡ /= 2021 8225 DOUBLE DAGGER + • oo 2022 8226 BULLET + ‥ .. 2025 8229 TWO DOT LEADER + … ,. 2026 8230 HORIZONTAL ELLIPSIS + ‰ %0 2030 8240 PER MILLE SIGN + ′ 1' 2032 8242 PRIME + ″ 2' 2033 8243 DOUBLE PRIME + ‴ 3' 2034 8244 TRIPLE PRIME + ⁗ 4' 2057 8279 QUADRUPLE PRIME + ‵ 1" 2035 8245 REVERSED PRIME + ‶ 2" 2036 8246 REVERSED DOUBLE PRIME + ‷ 3" 2037 8247 REVERSED TRIPLE PRIME + ‸ Ca 2038 8248 CARET + ‹ <1 2039 8249 SINGLE LEFT-POINTING ANGLE QUOTATION MARK + › >1 203A 8250 SINGLE RIGHT-POINTING ANGLE QUOTATION MARK + ※ :X 203B 8251 REFERENCE MARK + ‾ '- 203E 8254 OVERLINE + ⁄ /f 2044 8260 FRACTION SLASH + ⁰ 0S 2070 8304 SUPERSCRIPT ZERO + ⁴ 4S 2074 8308 SUPERSCRIPT FOUR + ⁵ 5S 2075 8309 SUPERSCRIPT FIVE + ⁶ 6S 2076 8310 SUPERSCRIPT SIX + ⁷ 7S 2077 8311 SUPERSCRIPT SEVEN + ⁸ 8S 2078 8312 SUPERSCRIPT EIGHT + ⁹ 9S 2079 8313 SUPERSCRIPT NINE + ⁺ +S 207A 8314 SUPERSCRIPT PLUS SIGN + ⁻ -S 207B 8315 SUPERSCRIPT MINUS + ⁼ =S 207C 8316 SUPERSCRIPT EQUALS SIGN + ⁽ (S 207D 8317 SUPERSCRIPT LEFT PARENTHESIS + ⁾ )S 207E 8318 SUPERSCRIPT RIGHT PARENTHESIS + ⁿ nS 207F 8319 SUPERSCRIPT LATIN SMALL LETTER N ` + ₀ 0s 2080 8320 SUBSCRIPT ZERO + ₁ 1s 2081 8321 SUBSCRIPT ONE + ₂ 2s 2082 8322 SUBSCRIPT TWO + ₃ 3s 2083 8323 SUBSCRIPT THREE + ₄ 4s 2084 8324 SUBSCRIPT FOUR + ₅ 5s 2085 8325 SUBSCRIPT FIVE + ₆ 6s 2086 8326 SUBSCRIPT SIX + ₇ 7s 2087 8327 SUBSCRIPT SEVEN + ₈ 8s 2088 8328 SUBSCRIPT EIGHT + ₉ 9s 2089 8329 SUBSCRIPT NINE + ₊ +s 208A 8330 SUBSCRIPT PLUS SIGN + ₋ -s 208B 8331 SUBSCRIPT MINUS + ₌ =s 208C 8332 SUBSCRIPT EQUALS SIGN + ₍ (s 208D 8333 SUBSCRIPT LEFT PARENTHESIS + ₎ )s 208E 8334 SUBSCRIPT RIGHT PARENTHESIS + ₤ Li 20A4 8356 LIRA SIGN + ₧ Pt 20A7 8359 PESETA SIGN + ₩ W= 20A9 8361 WON SIGN + € Eu 20AC 8364 EURO SIGN + ₽ =R 20BD 8381 ROUBLE SIGN + ₽ =P 20BD 8381 ROUBLE SIGN + ℃ oC 2103 8451 DEGREE CELSIUS + ℅ co 2105 8453 CARE OF + ℉ oF 2109 8457 DEGREE FAHRENHEIT + № N0 2116 8470 NUMERO SIGN + ℗ PO 2117 8471 SOUND RECORDING COPYRIGHT + ℞ Rx 211E 8478 PRESCRIPTION TAKE + ℠ SM 2120 8480 SERVICE MARK + ™ TM 2122 8482 TRADE MARK SIGN + Ω Om 2126 8486 OHM SIGN + Å AO 212B 8491 ANGSTROM SIGN + ⅓ 13 2153 8531 VULGAR FRACTION ONE THIRD + ⅔ 23 2154 8532 VULGAR FRACTION TWO THIRDS + ⅕ 15 2155 8533 VULGAR FRACTION ONE FIFTH + ⅖ 25 2156 8534 VULGAR FRACTION TWO FIFTHS + ⅗ 35 2157 8535 VULGAR FRACTION THREE FIFTHS + ⅘ 45 2158 8536 VULGAR FRACTION FOUR FIFTHS + ⅙ 16 2159 8537 VULGAR FRACTION ONE SIXTH + ⅚ 56 215A 8538 VULGAR FRACTION FIVE SIXTHS + ⅛ 18 215B 8539 VULGAR FRACTION ONE EIGHTH + ⅜ 38 215C 8540 VULGAR FRACTION THREE EIGHTHS + ⅝ 58 215D 8541 VULGAR FRACTION FIVE EIGHTHS + ⅞ 78 215E 8542 VULGAR FRACTION SEVEN EIGHTHS + Ⅰ 1R 2160 8544 ROMAN NUMERAL ONE + Ⅱ 2R 2161 8545 ROMAN NUMERAL TWO + Ⅲ 3R 2162 8546 ROMAN NUMERAL THREE + Ⅳ 4R 2163 8547 ROMAN NUMERAL FOUR + Ⅴ 5R 2164 8548 ROMAN NUMERAL FIVE + Ⅵ 6R 2165 8549 ROMAN NUMERAL SIX + Ⅶ 7R 2166 8550 ROMAN NUMERAL SEVEN + Ⅷ 8R 2167 8551 ROMAN NUMERAL EIGHT + Ⅸ 9R 2168 8552 ROMAN NUMERAL NINE + Ⅹ aR 2169 8553 ROMAN NUMERAL TEN + Ⅺ bR 216A 8554 ROMAN NUMERAL ELEVEN + Ⅻ cR 216B 8555 ROMAN NUMERAL TWELVE + ⅰ 1r 2170 8560 SMALL ROMAN NUMERAL ONE + ⅱ 2r 2171 8561 SMALL ROMAN NUMERAL TWO + ⅲ 3r 2172 8562 SMALL ROMAN NUMERAL THREE + ⅳ 4r 2173 8563 SMALL ROMAN NUMERAL FOUR + ⅴ 5r 2174 8564 SMALL ROMAN NUMERAL FIVE + ⅵ 6r 2175 8565 SMALL ROMAN NUMERAL SIX + ⅶ 7r 2176 8566 SMALL ROMAN NUMERAL SEVEN + ⅷ 8r 2177 8567 SMALL ROMAN NUMERAL EIGHT + ⅸ 9r 2178 8568 SMALL ROMAN NUMERAL NINE + ⅹ ar 2179 8569 SMALL ROMAN NUMERAL TEN + ⅺ br 217A 8570 SMALL ROMAN NUMERAL ELEVEN + ⅻ cr 217B 8571 SMALL ROMAN NUMERAL TWELVE + ← <- 2190 8592 LEFTWARDS ARROW + ↑ -! 2191 8593 UPWARDS ARROW + → -> 2192 8594 RIGHTWARDS ARROW + ↓ -v 2193 8595 DOWNWARDS ARROW + ↔ <> 2194 8596 LEFT RIGHT ARROW + ↕ UD 2195 8597 UP DOWN ARROW + ⇐ <= 21D0 8656 LEFTWARDS DOUBLE ARROW + ⇒ => 21D2 8658 RIGHTWARDS DOUBLE ARROW + ⇔ == 21D4 8660 LEFT RIGHT DOUBLE ARROW + ∀ FA 2200 8704 FOR ALL + ∂ dP 2202 8706 PARTIAL DIFFERENTIAL + ∃ TE 2203 8707 THERE EXISTS + ∅ /0 2205 8709 EMPTY SET + ∆ DE 2206 8710 INCREMENT + ∇ NB 2207 8711 NABLA + ∈ (- 2208 8712 ELEMENT OF + ∋ -) 220B 8715 CONTAINS AS MEMBER + ∏ *P 220F 8719 N-ARY PRODUCT ` + ∑ +Z 2211 8721 N-ARY SUMMATION ` + − -2 2212 8722 MINUS SIGN + ∓ -+ 2213 8723 MINUS-OR-PLUS SIGN + ∗ *- 2217 8727 ASTERISK OPERATOR + ∘ Ob 2218 8728 RING OPERATOR + ∙ Sb 2219 8729 BULLET OPERATOR + √ RT 221A 8730 SQUARE ROOT + ∝ 0( 221D 8733 PROPORTIONAL TO + ∞ 00 221E 8734 INFINITY + ∟ -L 221F 8735 RIGHT ANGLE + ∠ -V 2220 8736 ANGLE + ∥ PP 2225 8741 PARALLEL TO + ∧ AN 2227 8743 LOGICAL AND + ∨ OR 2228 8744 LOGICAL OR + ∩ (U 2229 8745 INTERSECTION + ∪ )U 222A 8746 UNION + ∫ In 222B 8747 INTEGRAL + ∬ DI 222C 8748 DOUBLE INTEGRAL + ∮ Io 222E 8750 CONTOUR INTEGRAL + ∴ .: 2234 8756 THEREFORE + ∵ :. 2235 8757 BECAUSE + ∶ :R 2236 8758 RATIO + ∷ :: 2237 8759 PROPORTION + ∼ ?1 223C 8764 TILDE OPERATOR + ∾ CG 223E 8766 INVERTED LAZY S + ≃ ?- 2243 8771 ASYMPTOTICALLY EQUAL TO + ≅ ?= 2245 8773 APPROXIMATELY EQUAL TO + ≈ ?2 2248 8776 ALMOST EQUAL TO + ≌ =? 224C 8780 ALL EQUAL TO + ≓ HI 2253 8787 IMAGE OF OR APPROXIMATELY EQUAL TO + ≠ != 2260 8800 NOT EQUAL TO + ≡ =3 2261 8801 IDENTICAL TO + ≤ =< 2264 8804 LESS-THAN OR EQUAL TO + ≥ >= 2265 8805 GREATER-THAN OR EQUAL TO + ≪ <* 226A 8810 MUCH LESS-THAN + ≫ *> 226B 8811 MUCH GREATER-THAN + ≮ !< 226E 8814 NOT LESS-THAN + ≯ !> 226F 8815 NOT GREATER-THAN + ⊂ (C 2282 8834 SUBSET OF + ⊃ )C 2283 8835 SUPERSET OF + ⊆ (_ 2286 8838 SUBSET OF OR EQUAL TO + ⊇ )_ 2287 8839 SUPERSET OF OR EQUAL TO + ⊙ 0. 2299 8857 CIRCLED DOT OPERATOR + ⊚ 02 229A 8858 CIRCLED RING OPERATOR + ⊥ -T 22A5 8869 UP TACK + ⋅ .P 22C5 8901 DOT OPERATOR + ⋮ :3 22EE 8942 VERTICAL ELLIPSIS + ⋯ .3 22EF 8943 MIDLINE HORIZONTAL ELLIPSIS + ⌂ Eh 2302 8962 HOUSE + ⌈ <7 2308 8968 LEFT CEILING + ⌉ >7 2309 8969 RIGHT CEILING + ⌊ 7< 230A 8970 LEFT FLOOR + ⌋ 7> 230B 8971 RIGHT FLOOR + ⌐ NI 2310 8976 REVERSED NOT SIGN + ⌒ (A 2312 8978 ARC + ⌕ TR 2315 8981 TELEPHONE RECORDER + ⌠ Iu 2320 8992 TOP HALF INTEGRAL + ⌡ Il 2321 8993 BOTTOM HALF INTEGRAL + 〈 </ 2329 9001 LEFT-POINTING ANGLE BRACKET + 〉 /> 232A 9002 RIGHT-POINTING ANGLE BRACKET + ␣ Vs 2423 9251 OPEN BOX + ⑀ 1h 2440 9280 OCR HOOK + ⑁ 3h 2441 9281 OCR CHAIR + ⑂ 2h 2442 9282 OCR FORK + ⑃ 4h 2443 9283 OCR INVERTED FORK + ⑆ 1j 2446 9286 OCR BRANCH BANK IDENTIFICATION + ⑇ 2j 2447 9287 OCR AMOUNT OF CHECK + ⑈ 3j 2448 9288 OCR DASH + ⑉ 4j 2449 9289 OCR CUSTOMER ACCOUNT NUMBER + ⒈ 1. 2488 9352 DIGIT ONE FULL STOP + ⒉ 2. 2489 9353 DIGIT TWO FULL STOP + ⒊ 3. 248A 9354 DIGIT THREE FULL STOP + ⒋ 4. 248B 9355 DIGIT FOUR FULL STOP + ⒌ 5. 248C 9356 DIGIT FIVE FULL STOP + ⒍ 6. 248D 9357 DIGIT SIX FULL STOP + ⒎ 7. 248E 9358 DIGIT SEVEN FULL STOP + ⒏ 8. 248F 9359 DIGIT EIGHT FULL STOP + ⒐ 9. 2490 9360 DIGIT NINE FULL STOP + ─ hh 2500 9472 BOX DRAWINGS LIGHT HORIZONTAL + ━ HH 2501 9473 BOX DRAWINGS HEAVY HORIZONTAL + │ vv 2502 9474 BOX DRAWINGS LIGHT VERTICAL + ┃ VV 2503 9475 BOX DRAWINGS HEAVY VERTICAL + ┄ 3- 2504 9476 BOX DRAWINGS LIGHT TRIPLE DASH HORIZONTAL + ┅ 3_ 2505 9477 BOX DRAWINGS HEAVY TRIPLE DASH HORIZONTAL + ┆ 3! 2506 9478 BOX DRAWINGS LIGHT TRIPLE DASH VERTICAL + ┇ 3/ 2507 9479 BOX DRAWINGS HEAVY TRIPLE DASH VERTICAL + ┈ 4- 2508 9480 BOX DRAWINGS LIGHT QUADRUPLE DASH HORIZONTAL + ┉ 4_ 2509 9481 BOX DRAWINGS HEAVY QUADRUPLE DASH HORIZONTAL + ┊ 4! 250A 9482 BOX DRAWINGS LIGHT QUADRUPLE DASH VERTICAL + ┋ 4/ 250B 9483 BOX DRAWINGS HEAVY QUADRUPLE DASH VERTICAL + ┌ dr 250C 9484 BOX DRAWINGS LIGHT DOWN AND RIGHT + ┍ dR 250D 9485 BOX DRAWINGS DOWN LIGHT AND RIGHT HEAVY + ┎ Dr 250E 9486 BOX DRAWINGS DOWN HEAVY AND RIGHT LIGHT + ┏ DR 250F 9487 BOX DRAWINGS HEAVY DOWN AND RIGHT + ┐ dl 2510 9488 BOX DRAWINGS LIGHT DOWN AND LEFT + ┑ dL 2511 9489 BOX DRAWINGS DOWN LIGHT AND LEFT HEAVY + ┒ Dl 2512 9490 BOX DRAWINGS DOWN HEAVY AND LEFT LIGHT + ┓ LD 2513 9491 BOX DRAWINGS HEAVY DOWN AND LEFT + └ ur 2514 9492 BOX DRAWINGS LIGHT UP AND RIGHT + ┕ uR 2515 9493 BOX DRAWINGS UP LIGHT AND RIGHT HEAVY + ┖ Ur 2516 9494 BOX DRAWINGS UP HEAVY AND RIGHT LIGHT + ┗ UR 2517 9495 BOX DRAWINGS HEAVY UP AND RIGHT + ┘ ul 2518 9496 BOX DRAWINGS LIGHT UP AND LEFT + ┙ uL 2519 9497 BOX DRAWINGS UP LIGHT AND LEFT HEAVY + ┚ Ul 251A 9498 BOX DRAWINGS UP HEAVY AND LEFT LIGHT + ┛ UL 251B 9499 BOX DRAWINGS HEAVY UP AND LEFT + ├ vr 251C 9500 BOX DRAWINGS LIGHT VERTICAL AND RIGHT + ┝ vR 251D 9501 BOX DRAWINGS VERTICAL LIGHT AND RIGHT HEAVY + ┠ Vr 2520 9504 BOX DRAWINGS VERTICAL HEAVY AND RIGHT LIGHT + ┣ VR 2523 9507 BOX DRAWINGS HEAVY VERTICAL AND RIGHT + ┤ vl 2524 9508 BOX DRAWINGS LIGHT VERTICAL AND LEFT + ┥ vL 2525 9509 BOX DRAWINGS VERTICAL LIGHT AND LEFT HEAVY + ┨ Vl 2528 9512 BOX DRAWINGS VERTICAL HEAVY AND LEFT LIGHT + ┫ VL 252B 9515 BOX DRAWINGS HEAVY VERTICAL AND LEFT + ┬ dh 252C 9516 BOX DRAWINGS LIGHT DOWN AND HORIZONTAL + ┯ dH 252F 9519 BOX DRAWINGS DOWN LIGHT AND HORIZONTAL HEAVY + ┰ Dh 2530 9520 BOX DRAWINGS DOWN HEAVY AND HORIZONTAL LIGHT + ┳ DH 2533 9523 BOX DRAWINGS HEAVY DOWN AND HORIZONTAL + ┴ uh 2534 9524 BOX DRAWINGS LIGHT UP AND HORIZONTAL + ┷ uH 2537 9527 BOX DRAWINGS UP LIGHT AND HORIZONTAL HEAVY + ┸ Uh 2538 9528 BOX DRAWINGS UP HEAVY AND HORIZONTAL LIGHT + ┻ UH 253B 9531 BOX DRAWINGS HEAVY UP AND HORIZONTAL + ┼ vh 253C 9532 BOX DRAWINGS LIGHT VERTICAL AND HORIZONTAL + ┿ vH 253F 9535 BOX DRAWINGS VERTICAL LIGHT AND HORIZONTAL HEAVY + ╂ Vh 2542 9538 BOX DRAWINGS VERTICAL HEAVY AND HORIZONTAL LIGHT + ╋ VH 254B 9547 BOX DRAWINGS HEAVY VERTICAL AND HORIZONTAL + ╱ FD 2571 9585 BOX DRAWINGS LIGHT DIAGONAL UPPER RIGHT TO LOWER LEFT + ╲ BD 2572 9586 BOX DRAWINGS LIGHT DIAGONAL UPPER LEFT TO LOWER RIGHT + ▀ TB 2580 9600 UPPER HALF BLOCK + ▄ LB 2584 9604 LOWER HALF BLOCK + █ FB 2588 9608 FULL BLOCK + ▌ lB 258C 9612 LEFT HALF BLOCK + ▐ RB 2590 9616 RIGHT HALF BLOCK + ░ .S 2591 9617 LIGHT SHADE + ▒ :S 2592 9618 MEDIUM SHADE + ▓ ?S 2593 9619 DARK SHADE + ■ fS 25A0 9632 BLACK SQUARE + □ OS 25A1 9633 WHITE SQUARE + ▢ RO 25A2 9634 WHITE SQUARE WITH ROUNDED CORNERS + ▣ Rr 25A3 9635 WHITE SQUARE CONTAINING BLACK SMALL SQUARE + ▤ RF 25A4 9636 SQUARE WITH HORIZONTAL FILL + ▥ RY 25A5 9637 SQUARE WITH VERTICAL FILL + ▦ RH 25A6 9638 SQUARE WITH ORTHOGONAL CROSSHATCH FILL + ▧ RZ 25A7 9639 SQUARE WITH UPPER LEFT TO LOWER RIGHT FILL + ▨ RK 25A8 9640 SQUARE WITH UPPER RIGHT TO LOWER LEFT FILL + ▩ RX 25A9 9641 SQUARE WITH DIAGONAL CROSSHATCH FILL + ▪ sB 25AA 9642 BLACK SMALL SQUARE + ▬ SR 25AC 9644 BLACK RECTANGLE + ▭ Or 25AD 9645 WHITE RECTANGLE + ▲ UT 25B2 9650 BLACK UP-POINTING TRIANGLE + △ uT 25B3 9651 WHITE UP-POINTING TRIANGLE + ▶ PR 25B6 9654 BLACK RIGHT-POINTING TRIANGLE + ▷ Tr 25B7 9655 WHITE RIGHT-POINTING TRIANGLE + ▼ Dt 25BC 9660 BLACK DOWN-POINTING TRIANGLE + ▽ dT 25BD 9661 WHITE DOWN-POINTING TRIANGLE + ◀ PL 25C0 9664 BLACK LEFT-POINTING TRIANGLE + ◁ Tl 25C1 9665 WHITE LEFT-POINTING TRIANGLE + ◆ Db 25C6 9670 BLACK DIAMOND + ◇ Dw 25C7 9671 WHITE DIAMOND + ◊ LZ 25CA 9674 LOZENGE + ○ 0m 25CB 9675 WHITE CIRCLE + ◎ 0o 25CE 9678 BULLSEYE + ● 0M 25CF 9679 BLACK CIRCLE + ◐ 0L 25D0 9680 CIRCLE WITH LEFT HALF BLACK + ◑ 0R 25D1 9681 CIRCLE WITH RIGHT HALF BLACK + ◘ Sn 25D8 9688 INVERSE BULLET + ◙ Ic 25D9 9689 INVERSE WHITE CIRCLE + ◢ Fd 25E2 9698 BLACK LOWER RIGHT TRIANGLE + ◣ Bd 25E3 9699 BLACK LOWER LEFT TRIANGLE + ★ *2 2605 9733 BLACK STAR + ☆ *1 2606 9734 WHITE STAR + ☜ <H 261C 9756 WHITE LEFT POINTING INDEX + ☞ >H 261E 9758 WHITE RIGHT POINTING INDEX + ☺ 0u 263A 9786 WHITE SMILING FACE + ☻ 0U 263B 9787 BLACK SMILING FACE + ☼ SU 263C 9788 WHITE SUN WITH RAYS + ♀ Fm 2640 9792 FEMALE SIGN + ♂ Ml 2642 9794 MALE SIGN + ♠ cS 2660 9824 BLACK SPADE SUIT + ♡ cH 2661 9825 WHITE HEART SUIT + ♢ cD 2662 9826 WHITE DIAMOND SUIT + ♣ cC 2663 9827 BLACK CLUB SUIT + ♩ Md 2669 9833 QUARTER NOTE ` + ♪ M8 266A 9834 EIGHTH NOTE ` + ♫ M2 266B 9835 BEAMED EIGHTH NOTES + ♭ Mb 266D 9837 MUSIC FLAT SIGN + ♮ Mx 266E 9838 MUSIC NATURAL SIGN + ♯ MX 266F 9839 MUSIC SHARP SIGN + ✓ OK 2713 10003 CHECK MARK + ✗ XX 2717 10007 BALLOT X + ✠ -X 2720 10016 MALTESE CROSS + IS 3000 12288 IDEOGRAPHIC SPACE + 、 ,_ 3001 12289 IDEOGRAPHIC COMMA + 。 ._ 3002 12290 IDEOGRAPHIC FULL STOP + 〃 +" 3003 12291 DITTO MARK + 〄 +_ 3004 12292 JAPANESE INDUSTRIAL STANDARD SYMBOL + 々 *_ 3005 12293 IDEOGRAPHIC ITERATION MARK + 〆 ;_ 3006 12294 IDEOGRAPHIC CLOSING MARK + 〇 0_ 3007 12295 IDEOGRAPHIC NUMBER ZERO + 《 <+ 300A 12298 LEFT DOUBLE ANGLE BRACKET + 》 >+ 300B 12299 RIGHT DOUBLE ANGLE BRACKET + 「 <' 300C 12300 LEFT CORNER BRACKET + 」 >' 300D 12301 RIGHT CORNER BRACKET + 『 <" 300E 12302 LEFT WHITE CORNER BRACKET + 』 >" 300F 12303 RIGHT WHITE CORNER BRACKET + 【 (" 3010 12304 LEFT BLACK LENTICULAR BRACKET + 】 )" 3011 12305 RIGHT BLACK LENTICULAR BRACKET + 〒 =T 3012 12306 POSTAL MARK + 〓 =_ 3013 12307 GETA MARK + 〔 (' 3014 12308 LEFT TORTOISE SHELL BRACKET + 〕 )' 3015 12309 RIGHT TORTOISE SHELL BRACKET + 〖 (I 3016 12310 LEFT WHITE LENTICULAR BRACKET + 〗 )I 3017 12311 RIGHT WHITE LENTICULAR BRACKET + 〜 -? 301C 12316 WAVE DASH + ぁ A5 3041 12353 HIRAGANA LETTER SMALL A + あ a5 3042 12354 HIRAGANA LETTER A + ぃ I5 3043 12355 HIRAGANA LETTER SMALL I + い i5 3044 12356 HIRAGANA LETTER I + ぅ U5 3045 12357 HIRAGANA LETTER SMALL U + う u5 3046 12358 HIRAGANA LETTER U + ぇ E5 3047 12359 HIRAGANA LETTER SMALL E + え e5 3048 12360 HIRAGANA LETTER E + ぉ O5 3049 12361 HIRAGANA LETTER SMALL O + お o5 304A 12362 HIRAGANA LETTER O + か ka 304B 12363 HIRAGANA LETTER KA + が ga 304C 12364 HIRAGANA LETTER GA + き ki 304D 12365 HIRAGANA LETTER KI + ぎ gi 304E 12366 HIRAGANA LETTER GI + く ku 304F 12367 HIRAGANA LETTER KU + ぐ gu 3050 12368 HIRAGANA LETTER GU + け ke 3051 12369 HIRAGANA LETTER KE + げ ge 3052 12370 HIRAGANA LETTER GE + こ ko 3053 12371 HIRAGANA LETTER KO + ご go 3054 12372 HIRAGANA LETTER GO + さ sa 3055 12373 HIRAGANA LETTER SA + ざ za 3056 12374 HIRAGANA LETTER ZA + し si 3057 12375 HIRAGANA LETTER SI + じ zi 3058 12376 HIRAGANA LETTER ZI + す su 3059 12377 HIRAGANA LETTER SU + ず zu 305A 12378 HIRAGANA LETTER ZU + せ se 305B 12379 HIRAGANA LETTER SE + ぜ ze 305C 12380 HIRAGANA LETTER ZE + そ so 305D 12381 HIRAGANA LETTER SO + ぞ zo 305E 12382 HIRAGANA LETTER ZO + た ta 305F 12383 HIRAGANA LETTER TA + だ da 3060 12384 HIRAGANA LETTER DA + ち ti 3061 12385 HIRAGANA LETTER TI + ぢ di 3062 12386 HIRAGANA LETTER DI + っ tU 3063 12387 HIRAGANA LETTER SMALL TU + つ tu 3064 12388 HIRAGANA LETTER TU + づ du 3065 12389 HIRAGANA LETTER DU + て te 3066 12390 HIRAGANA LETTER TE + で de 3067 12391 HIRAGANA LETTER DE + と to 3068 12392 HIRAGANA LETTER TO + ど do 3069 12393 HIRAGANA LETTER DO + な na 306A 12394 HIRAGANA LETTER NA + に ni 306B 12395 HIRAGANA LETTER NI + ぬ nu 306C 12396 HIRAGANA LETTER NU + ね ne 306D 12397 HIRAGANA LETTER NE + の no 306E 12398 HIRAGANA LETTER NO + は ha 306F 12399 HIRAGANA LETTER HA + ば ba 3070 12400 HIRAGANA LETTER BA + ぱ pa 3071 12401 HIRAGANA LETTER PA + ひ hi 3072 12402 HIRAGANA LETTER HI + び bi 3073 12403 HIRAGANA LETTER BI + ぴ pi 3074 12404 HIRAGANA LETTER PI + ふ hu 3075 12405 HIRAGANA LETTER HU + ぶ bu 3076 12406 HIRAGANA LETTER BU + ぷ pu 3077 12407 HIRAGANA LETTER PU + へ he 3078 12408 HIRAGANA LETTER HE + べ be 3079 12409 HIRAGANA LETTER BE + ぺ pe 307A 12410 HIRAGANA LETTER PE + ほ ho 307B 12411 HIRAGANA LETTER HO + ぼ bo 307C 12412 HIRAGANA LETTER BO + ぽ po 307D 12413 HIRAGANA LETTER PO + ま ma 307E 12414 HIRAGANA LETTER MA + み mi 307F 12415 HIRAGANA LETTER MI + む mu 3080 12416 HIRAGANA LETTER MU + め me 3081 12417 HIRAGANA LETTER ME + も mo 3082 12418 HIRAGANA LETTER MO + ゃ yA 3083 12419 HIRAGANA LETTER SMALL YA + や ya 3084 12420 HIRAGANA LETTER YA + ゅ yU 3085 12421 HIRAGANA LETTER SMALL YU + ゆ yu 3086 12422 HIRAGANA LETTER YU + ょ yO 3087 12423 HIRAGANA LETTER SMALL YO + よ yo 3088 12424 HIRAGANA LETTER YO + ら ra 3089 12425 HIRAGANA LETTER RA + り ri 308A 12426 HIRAGANA LETTER RI + る ru 308B 12427 HIRAGANA LETTER RU + れ re 308C 12428 HIRAGANA LETTER RE + ろ ro 308D 12429 HIRAGANA LETTER RO + ゎ wA 308E 12430 HIRAGANA LETTER SMALL WA + わ wa 308F 12431 HIRAGANA LETTER WA + ゐ wi 3090 12432 HIRAGANA LETTER WI + ゑ we 3091 12433 HIRAGANA LETTER WE + を wo 3092 12434 HIRAGANA LETTER WO + ん n5 3093 12435 HIRAGANA LETTER N ` + ゔ vu 3094 12436 HIRAGANA LETTER VU + ゛ "5 309B 12443 KATAKANA-HIRAGANA VOICED SOUND MARK + ゜ 05 309C 12444 KATAKANA-HIRAGANA SEMI-VOICED SOUND MARK + ゝ *5 309D 12445 HIRAGANA ITERATION MARK + ゞ +5 309E 12446 HIRAGANA VOICED ITERATION MARK + ァ a6 30A1 12449 KATAKANA LETTER SMALL A + ア A6 30A2 12450 KATAKANA LETTER A + ィ i6 30A3 12451 KATAKANA LETTER SMALL I + イ I6 30A4 12452 KATAKANA LETTER I + ゥ u6 30A5 12453 KATAKANA LETTER SMALL U + ウ U6 30A6 12454 KATAKANA LETTER U + ェ e6 30A7 12455 KATAKANA LETTER SMALL E + エ E6 30A8 12456 KATAKANA LETTER E + ォ o6 30A9 12457 KATAKANA LETTER SMALL O + オ O6 30AA 12458 KATAKANA LETTER O + カ Ka 30AB 12459 KATAKANA LETTER KA + ガ Ga 30AC 12460 KATAKANA LETTER GA + キ Ki 30AD 12461 KATAKANA LETTER KI + ギ Gi 30AE 12462 KATAKANA LETTER GI + ク Ku 30AF 12463 KATAKANA LETTER KU + グ Gu 30B0 12464 KATAKANA LETTER GU + ケ Ke 30B1 12465 KATAKANA LETTER KE + ゲ Ge 30B2 12466 KATAKANA LETTER GE + コ Ko 30B3 12467 KATAKANA LETTER KO + ゴ Go 30B4 12468 KATAKANA LETTER GO + サ Sa 30B5 12469 KATAKANA LETTER SA + ザ Za 30B6 12470 KATAKANA LETTER ZA + シ Si 30B7 12471 KATAKANA LETTER SI + ジ Zi 30B8 12472 KATAKANA LETTER ZI + ス Su 30B9 12473 KATAKANA LETTER SU + ズ Zu 30BA 12474 KATAKANA LETTER ZU + セ Se 30BB 12475 KATAKANA LETTER SE + ゼ Ze 30BC 12476 KATAKANA LETTER ZE + ソ So 30BD 12477 KATAKANA LETTER SO + ゾ Zo 30BE 12478 KATAKANA LETTER ZO + タ Ta 30BF 12479 KATAKANA LETTER TA + ダ Da 30C0 12480 KATAKANA LETTER DA + チ Ti 30C1 12481 KATAKANA LETTER TI + ヂ Di 30C2 12482 KATAKANA LETTER DI + ッ TU 30C3 12483 KATAKANA LETTER SMALL TU + ツ Tu 30C4 12484 KATAKANA LETTER TU + ヅ Du 30C5 12485 KATAKANA LETTER DU + テ Te 30C6 12486 KATAKANA LETTER TE + デ De 30C7 12487 KATAKANA LETTER DE + ト To 30C8 12488 KATAKANA LETTER TO + ド Do 30C9 12489 KATAKANA LETTER DO + ナ Na 30CA 12490 KATAKANA LETTER NA + ニ Ni 30CB 12491 KATAKANA LETTER NI + ヌ Nu 30CC 12492 KATAKANA LETTER NU + ネ Ne 30CD 12493 KATAKANA LETTER NE + ノ No 30CE 12494 KATAKANA LETTER NO + ハ Ha 30CF 12495 KATAKANA LETTER HA + バ Ba 30D0 12496 KATAKANA LETTER BA + パ Pa 30D1 12497 KATAKANA LETTER PA + ヒ Hi 30D2 12498 KATAKANA LETTER HI + ビ Bi 30D3 12499 KATAKANA LETTER BI + ピ Pi 30D4 12500 KATAKANA LETTER PI + フ Hu 30D5 12501 KATAKANA LETTER HU + ブ Bu 30D6 12502 KATAKANA LETTER BU + プ Pu 30D7 12503 KATAKANA LETTER PU + ヘ He 30D8 12504 KATAKANA LETTER HE + ベ Be 30D9 12505 KATAKANA LETTER BE + ペ Pe 30DA 12506 KATAKANA LETTER PE + ホ Ho 30DB 12507 KATAKANA LETTER HO + ボ Bo 30DC 12508 KATAKANA LETTER BO + ポ Po 30DD 12509 KATAKANA LETTER PO + マ Ma 30DE 12510 KATAKANA LETTER MA + ミ Mi 30DF 12511 KATAKANA LETTER MI + ム Mu 30E0 12512 KATAKANA LETTER MU + メ Me 30E1 12513 KATAKANA LETTER ME + モ Mo 30E2 12514 KATAKANA LETTER MO + ャ YA 30E3 12515 KATAKANA LETTER SMALL YA + ヤ Ya 30E4 12516 KATAKANA LETTER YA + ュ YU 30E5 12517 KATAKANA LETTER SMALL YU + ユ Yu 30E6 12518 KATAKANA LETTER YU + ョ YO 30E7 12519 KATAKANA LETTER SMALL YO + ヨ Yo 30E8 12520 KATAKANA LETTER YO + ラ Ra 30E9 12521 KATAKANA LETTER RA + リ Ri 30EA 12522 KATAKANA LETTER RI + ル Ru 30EB 12523 KATAKANA LETTER RU + レ Re 30EC 12524 KATAKANA LETTER RE + ロ Ro 30ED 12525 KATAKANA LETTER RO + ヮ WA 30EE 12526 KATAKANA LETTER SMALL WA + ワ Wa 30EF 12527 KATAKANA LETTER WA + ヰ Wi 30F0 12528 KATAKANA LETTER WI + ヱ We 30F1 12529 KATAKANA LETTER WE + ヲ Wo 30F2 12530 KATAKANA LETTER WO + ン N6 30F3 12531 KATAKANA LETTER N ` + ヴ Vu 30F4 12532 KATAKANA LETTER VU + ヵ KA 30F5 12533 KATAKANA LETTER SMALL KA + ヶ KE 30F6 12534 KATAKANA LETTER SMALL KE + ヷ Va 30F7 12535 KATAKANA LETTER VA + ヸ Vi 30F8 12536 KATAKANA LETTER VI + ヹ Ve 30F9 12537 KATAKANA LETTER VE + ヺ Vo 30FA 12538 KATAKANA LETTER VO + ・ .6 30FB 12539 KATAKANA MIDDLE DOT + ー -6 30FC 12540 KATAKANA-HIRAGANA PROLONGED SOUND MARK + ヽ *6 30FD 12541 KATAKANA ITERATION MARK + ヾ +6 30FE 12542 KATAKANA VOICED ITERATION MARK + ㄅ b4 3105 12549 BOPOMOFO LETTER B + ㄆ p4 3106 12550 BOPOMOFO LETTER P + ㄇ m4 3107 12551 BOPOMOFO LETTER M + ㄈ f4 3108 12552 BOPOMOFO LETTER F + ㄉ d4 3109 12553 BOPOMOFO LETTER D + ㄊ t4 310A 12554 BOPOMOFO LETTER T + ㄋ n4 310B 12555 BOPOMOFO LETTER N ` + ㄌ l4 310C 12556 BOPOMOFO LETTER L + ㄍ g4 310D 12557 BOPOMOFO LETTER G + ㄎ k4 310E 12558 BOPOMOFO LETTER K + ㄏ h4 310F 12559 BOPOMOFO LETTER H + ㄐ j4 3110 12560 BOPOMOFO LETTER J + ㄑ q4 3111 12561 BOPOMOFO LETTER Q + ㄒ x4 3112 12562 BOPOMOFO LETTER X + ㄓ zh 3113 12563 BOPOMOFO LETTER ZH + ㄔ ch 3114 12564 BOPOMOFO LETTER CH + ㄕ sh 3115 12565 BOPOMOFO LETTER SH + ㄖ r4 3116 12566 BOPOMOFO LETTER R + ㄗ z4 3117 12567 BOPOMOFO LETTER Z + ㄘ c4 3118 12568 BOPOMOFO LETTER C + ㄙ s4 3119 12569 BOPOMOFO LETTER S + ㄚ a4 311A 12570 BOPOMOFO LETTER A + ㄛ o4 311B 12571 BOPOMOFO LETTER O + ㄜ e4 311C 12572 BOPOMOFO LETTER E + ㄞ ai 311E 12574 BOPOMOFO LETTER AI + ㄟ ei 311F 12575 BOPOMOFO LETTER EI + ㄠ au 3120 12576 BOPOMOFO LETTER AU + ㄡ ou 3121 12577 BOPOMOFO LETTER OU + ㄢ an 3122 12578 BOPOMOFO LETTER AN + ㄣ en 3123 12579 BOPOMOFO LETTER EN + ㄤ aN 3124 12580 BOPOMOFO LETTER ANG + ㄥ eN 3125 12581 BOPOMOFO LETTER ENG + ㄦ er 3126 12582 BOPOMOFO LETTER ER + ㄧ i4 3127 12583 BOPOMOFO LETTER I + ㄨ u4 3128 12584 BOPOMOFO LETTER U + ㄩ iu 3129 12585 BOPOMOFO LETTER IU + ㄪ v4 312A 12586 BOPOMOFO LETTER V + ㄫ nG 312B 12587 BOPOMOFO LETTER NG + ㄬ gn 312C 12588 BOPOMOFO LETTER GN + ㈠ 1c 3220 12832 PARENTHESIZED IDEOGRAPH ONE + ㈡ 2c 3221 12833 PARENTHESIZED IDEOGRAPH TWO + ㈢ 3c 3222 12834 PARENTHESIZED IDEOGRAPH THREE + ㈣ 4c 3223 12835 PARENTHESIZED IDEOGRAPH FOUR + ㈤ 5c 3224 12836 PARENTHESIZED IDEOGRAPH FIVE + ㈥ 6c 3225 12837 PARENTHESIZED IDEOGRAPH SIX + ㈦ 7c 3226 12838 PARENTHESIZED IDEOGRAPH SEVEN + ㈧ 8c 3227 12839 PARENTHESIZED IDEOGRAPH EIGHT + ㈨ 9c 3228 12840 PARENTHESIZED IDEOGRAPH NINE + ff ff FB00 64256 LATIN SMALL LIGATURE FF + fi fi FB01 64257 LATIN SMALL LIGATURE FI + fl fl FB02 64258 LATIN SMALL LIGATURE FL + ſt ft FB05 64261 LATIN SMALL LIGATURE LONG S T + st st FB06 64262 LATIN SMALL LIGATURE ST +< vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt index f77db5fab3..7df2eb9742 100644 --- a/runtime/doc/editing.txt +++ b/runtime/doc/editing.txt @@ -169,33 +169,26 @@ If you want to keep the changed buffer without saving it, switch on the 2. Editing a file *edit-a-file* *:e* *:edit* *reload* -:e[dit] [++opt] [+cmd] Edit the current file. This is useful to re-edit the +:e[dit][!] [++opt] [+cmd] + Edit the current file. This is useful to re-edit the current file, when it has been changed outside of Vim. - This fails when changes have been made to the current - buffer and 'autowriteall' isn't set or the file can't - be written. - Also see |++opt| and |+cmd|. - *:edit!* *discard* -:e[dit]! [++opt] [+cmd] - Edit the current file always. Discard any changes to - the current buffer. This is useful if you want to - start all over again. + If [!] is given, unsaved changes in the current buffer + are discarded. Without [!] the command fails if there + are unsaved changes, unless 'autowriteall' is set and + the file can be written. Also see |++opt| and |+cmd|. *:edit_f* -:e[dit] [++opt] [+cmd] {file} +:e[dit][!] [++opt] [+cmd] {file} Edit {file}. - This fails when changes have been made to the current - buffer, unless 'hidden' is set or 'autowriteall' is - set and the file can be written. - Also see |++opt| and |+cmd|. - *:edit!_f* -:e[dit]! [++opt] [+cmd] {file} - Edit {file} always. Discard any changes to the - current buffer. + If [!] is given, unsaved changes in the current buffer + are discarded. Without [!] the command fails if there + are unsaved changes, unless 'hidden' is set or + 'autowriteall' is set and the file can be written. Also see |++opt| and |+cmd|. + *:edit_#* *:e#* :e[dit] [++opt] [+cmd] #[count] Edit the [count]th buffer (as shown by |:files|). @@ -356,7 +349,9 @@ as a wildcard when "[" is in the 'isfname' option. A simple way to avoid this is to use "path\[[]abc]", this matches the file "path\[abc]". *starstar-wildcard* -Expanding "**" is possible on Unix, Win32, macOS and a few other systems. +Expanding "**" is possible on Unix, Win32, macOS and a few other systems (but +it may depend on your 'shell' setting on Unix and macOS. It's known to work +correctly for zsh; for bash this requires at least bash version >= 4.X). This allows searching a directory tree. This goes up to 100 directories deep. Note there are some commands where this works slightly differently, see |file-searching|. @@ -539,10 +534,10 @@ set to "dos", otherwise it is set to "unix". When 'fileformats' includes "mac". If the 'fileformat' option is set to "dos" on non-MS-Windows systems the -message "[dos format]" is shown to remind you that something unusual is -happening. On MS-Windows systems you get the message "[unix format]" if -'fileformat' is set to "unix". On all systems but the Macintosh you get the -message "[mac format]" if 'fileformat' is set to "mac". +message "[dos]" is shown to remind you that something unusual is happening. On +MS-Windows systems you get the message "[unix]" if 'fileformat' is set to +"unix". On all systems you get the message "[mac]" if 'fileformat' is set to +"mac". If the 'fileformats' option is empty and DOS format is used, but while reading a file some lines did not end in <CR><NL>, "[CR missing]" will be included in @@ -804,8 +799,8 @@ first line (the last line in Ex mode). *{arglist}* The wildcards in the argument list are expanded and the file names are sorted. -Thus you can use the command "vim *.c" to edit all the C files. From within -Vim the command ":n *.c" does the same. +Thus you can use the command `vim *.c` to edit all the C files. From within +Vim the command `:n *.c` does the same. White space is used to separate file names. Put a backslash before a space or tab to include it in a file name. E.g., to edit the single file "foo bar": > @@ -820,12 +815,10 @@ by the shell before executing the find program. When there is an argument list you can see which file you are editing in the title of the window (if there is one and 'title' is on) and with the file message you get with the "CTRL-G" command. You will see something like - (file 4 of 11) -If 'shortmess' contains 'f' it will be (4 of 11) If you are not really editing the file at the current position in the argument list it will be - (file (4) of 11) + ((4) of 11) This means that you are position 4 in the argument list, but not editing the fourth file in the argument list. This happens when you do ":e file". @@ -889,7 +882,7 @@ Example: > :args *.c :argdo set ff=unix | update This sets the 'fileformat' option to "unix" and writes the file if it is now -changed. This is done for all *.c files. +changed. This is done for all `*.c` files. Example: > :args *.[ch] @@ -1058,14 +1051,14 @@ lost the original file. *DOS-format-write* If the 'fileformat' is "dos", <CR><NL> is used for <EOL>. This is default -for Windows. On other systems the message "[dos format]" is shown to +for Windows. On other systems the message "[dos]" is shown to remind you that an unusual <EOL> was used. *Unix-format-write* If the 'fileformat' is "unix", <NL> is used for <EOL>. On Windows -the message "[unix format]" is shown. +the message "[unix]" is shown. *Mac-format-write* -If the 'fileformat' is "mac", <CR> is used for <EOL>. On non-Mac systems the -message "[mac format]" is shown. +If the 'fileformat' is "mac", <CR> is used for <EOL>. The +message "[mac]" is shown. See also |file-formats| and the 'fileformat' and 'fileformats' options. @@ -1078,6 +1071,13 @@ will get the ACL info of the original file. The ACL info is also used to check if a file is read-only (when opening the file). + *xattr* *E1506* *E1508* *E1509* +xattr stands for Extended Attributes. It is an advanced way to save metadata +alongside the file in the filesystem. It depends on the actual filesystem +being used and Vim supports it only on a Linux system. + Vim attempts to preserve the extended attribute info when writing a file. +The backup file will get the extended attribute of the original file. + *read-only-share* When MS-Windows shares a drive on the network it can be marked as read-only. This means that even if the file read-only attribute is absent, and the ACL @@ -1217,10 +1217,10 @@ MULTIPLE WINDOWS AND BUFFERS *window-exit* *:confirm* *:conf* :conf[irm] {command} Execute {command}, and use a dialog when an operation has to be confirmed. Can be used on the - |:q|, |:qa| and |:w| commands (the latter to override - a read-only setting), and any other command that can - fail in such a way, such as |:only|, |:buffer|, - |:bdelete|, etc. + |:edit|, |:q|, |:qa| and |:w| commands (the latter to + override a read-only setting), and any commands that + can fail because of unsaved changes, such as |:only|, + |:buffer|, |:bdelete|, etc. Examples: > :confirm w foo @@ -1245,8 +1245,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, in console `browse edit` works - if the FileExplorer autocommand group exists} + Note: 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. @@ -1581,7 +1581,7 @@ There are three different types of searching: so they work on all operating systems. Note that "**" only acts as a special wildcard when it is at the start of a name. - The usage of '*' is quite simple: It matches 0 or more characters. In a + The usage of "*" is quite simple: It matches 0 or more characters. In a search pattern this would be ".*". Note that the "." is not used for file searching. @@ -1668,29 +1668,26 @@ There are three different types of searching: ============================================================================== 12. Trusted Files *trust* -Nvim has the ability to execute arbitrary code through the 'exrc' option. In -order to prevent executing code from untrusted sources, Nvim has the concept of -"trusted files". An untrusted file will not be executed without the user's -consent, and a user can permanently mark a file as trusted or untrusted using -the |:trust| command or the |vim.secure.read()| function. +Nvim executes arbitrary code found on the filesystem if 'exrc' is enabled. To +prevent executing malicious code, only "trusted files" are executed. You can +mark a file as trusted or untrusted using the |:trust| command or the +|vim.secure.read()| function. *:trust* *E5570* -:trust [++deny] [++remove] [{file}] - - Manage files in the trust database. Without any options - or arguments, :trust adds the file associated with the - current buffer to the trust database, along with the - SHA256 hash of its contents. - - [++deny] marks the file associated with the current - buffer (or {file}, if given) as denied; no prompts will - be displayed to the user and the file will never be - executed. - - [++remove] removes the file associated with the current - buffer (or {file}, if given) from the trust database. - Future attempts to read the file in a secure setting - (i.e. with 'exrc' or |vim.secure.read()|) will prompt - the user if the file is trusted. +:trust [++deny] [++remove] [file] + + Manage trusted files. Without ++ options, :trust marks + the current buffer as trusted, keyed on a hash of its + contents. The trust list is stored on disk, Nvim will + re-use it after restarting. + + [++deny] marks [file] (or current buffer if no [file]) as + untrusted: it will never be executed, 'exrc' will + ignore it. + + [++remove] removes [file] (or current buffer if no + [file]) from the trust list. When the file is + discovered by 'exrc' or |vim.secure.read()|, the user + will be asked whether to trust or deny the file. vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/editorconfig.txt b/runtime/doc/editorconfig.txt index 04a057e5ff..7c6e8fb95f 100644 --- a/runtime/doc/editorconfig.txt +++ b/runtime/doc/editorconfig.txt @@ -6,25 +6,21 @@ EditorConfig integration *editorconfig* -Nvim natively supports EditorConfig. When a file is opened, Nvim searches -upward through all of the parent directories of that file looking for -".editorconfig" files. Each of these is parsed and any properties that match -the opened file are applied. - -For more information on EditorConfig, see https://editorconfig.org/. +Nvim supports EditorConfig. When a file is opened, Nvim searches all parent +directories of that file for ".editorconfig" files, parses them, and applies +any properties that match the opened file. Think of it like 'modeline' for an +entire (recursive) directory. For more information see +https://editorconfig.org/. *g:editorconfig* *b:editorconfig* -EditorConfig integration can be disabled globally by adding >lua +EditorConfig is enabled by default. To disable it, add to your config: >lua vim.g.editorconfig = false < -to the user's |init.lua| file (or the Vimscript equivalent to |init.vim|). It -can also be disabled per-buffer by setting the |b:editorconfig| buffer-local -variable to `false`. +(Vimscript: `let g:editorconfig = v:false`). It can also be disabled +per-buffer by setting the |b:editorconfig| buffer-local variable to `false`. -When Nvim finds a valid .editorconfig file it will store the applied -properties in the buffer variable |b:editorconfig| if it was not already set to -`false` by the user. +Nvim stores the applied properties in |b:editorconfig| if it is not `false`. *editorconfig-properties* The following properties are supported by default: @@ -52,7 +48,7 @@ indent_style One of "tab" or "space". Sets the 'expandtab' option. indent_size A number indicating the size of a single indent. Alternatively, use the value "tab" to use the value of the tab_width property. Sets the 'shiftwidth' and - 'softtabstop'. + 'softtabstop' options. *editorconfig_insert_final_newline* insert_final_newline "true" or "false" to ensure the file always has a @@ -88,4 +84,4 @@ Example: >lua vim.b[bufnr].foo = val end < - vim:tw=78:ts=8:noet:ft=help:norl: + vim:tw=78:ts=8:et:sw=4:ft=help:norl: diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 58759a6053..a73932be00 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -39,7 +39,7 @@ List An ordered sequence of items, see |List| for details. Dictionary An associative, unordered array: Each entry has a key and a value. |Dictionary| - Examples: + Examples: > {"blue": "#0000ff", "red": "#ff0000"} #{blue: "#0000ff", red: "#ff0000"} @@ -93,7 +93,27 @@ non-zero number it means TRUE: > :" executed To test for a non-empty string, use empty(): > :if !empty("foo") -< + +< *falsy* *truthy* +An expression can be used as a condition, ignoring the type and only using +whether the value is "sort of true" or "sort of false". Falsy is: + the number zero + empty string, blob, list or dictionary +Other values are truthy. Examples: + 0 falsy + 1 truthy + -1 truthy + 0.0 falsy + 0.1 truthy + '' falsy + 'x' truthy + [] falsy + [0] truthy + {} falsy + #{x: 1} truthy + 0z falsy + 0z00 truthy + *non-zero-arg* Function arguments often behave slightly different from |TRUE|: If the argument is present and it evaluates to a non-zero Number, |v:true| or a @@ -119,7 +139,7 @@ You will not get an error if you try to change the type of a variable. 1.2 Function references ~ - *Funcref* *E695* *E718* + *Funcref* *E695* *E718* *E1192* A Funcref variable is obtained with the |function()| function, the |funcref()| function or created with the lambda expression |expr-lambda|. It can be used in an expression in the place of a function name, before the parenthesis @@ -250,6 +270,9 @@ similar to -1. > :let shortlist = mylist[2:2] " List with one item: [3] :let otherlist = mylist[:] " make a copy of the List +Notice that the last index is inclusive. If you prefer using an exclusive +index use the |slice()| method. + If the first index is beyond the last item of the List or the second item is before the first item, the result is an empty list. There is no error message. @@ -818,19 +841,19 @@ Expression syntax summary, from least to most significant: |expr9| number number constant "string" string constant, backslash is special - 'string' string constant, ' is doubled + `'string'` string constant, ' is doubled [expr1, ...] |List| - {expr1: expr1, ...} |Dictionary| + `{expr1: expr1, ...}` |Dictionary| #{key: expr1, ...} |Dictionary| &option option value (expr1) nested expression variable internal variable va{ria}ble internal variable with curly braces $VAR environment variable - @r contents of register 'r' + @r contents of register "r" function(expr1, ...) function call func{ti}on(expr1, ...) function call with curly braces - {args -> expr1} lambda expression + `{args -> expr1}` lambda expression "..." indicates that the operations in this level can be concatenated. @@ -841,9 +864,12 @@ All expressions within one level are parsed from left to right. ------------------------------------------------------------------------------ -expr1 *expr1* *ternary* *E109* +expr1 *expr1* *ternary* *falsy-operator* *??* *E109* + +The ternary operator: expr2 ? expr1 : expr1 +The falsy operator: expr2 ?? expr1 -expr2 ? expr1 : expr1 +Ternary operator ~ The expression before the '?' is evaluated to a number. If it evaluates to |TRUE|, the result is the value of the expression between the '?' and ':', @@ -866,6 +892,23 @@ To keep this readable, using |line-continuation| is suggested: > You should always put a space before the ':', otherwise it can be mistaken for use in a variable such as "a:1". +Falsy operator ~ + +This is also known as the "null coalescing operator", but that's too +complicated, thus we just call it the falsy operator. + +The expression before the '??' is evaluated. If it evaluates to +|truthy|, this is used as the result. Otherwise the expression after the '??' +is evaluated and used as the result. This is most useful to have a default +value for an expression that may result in zero or empty: > + echo theList ?? 'list is empty' + echo GetName() ?? 'unknown' + +These are similar, but not equal: > + expr2 ?? expr1 + expr2 ? expr2 : expr1 +In the second line "expr2" is evaluated twice. + ------------------------------------------------------------------------------ expr2 and expr3 *expr2* *expr3* @@ -1044,7 +1087,7 @@ That works, since the String "190" is automatically converted to the Number 1 . 90 * 90.0 Should be read as: > 1 . (90 * 90.0) -Since '.' has lower precedence than '*'. This does NOT work, since this +Since '.' has lower precedence than "*". This does NOT work, since this attempts to concatenate a Float and a String. When dividing a Number by zero the result depends on the value: @@ -1112,6 +1155,8 @@ text column numbers start with one! Example, to get the byte under the cursor: > :let c = getline(".")[col(".") - 1] +Index zero gives the first byte. Careful: text column numbers start with one! + If the length of the String is less than the index, the result is an empty String. A negative index always results in an empty string (reason: backward compatibility). Use [-1:] to get the last byte. @@ -1136,6 +1181,9 @@ In legacy Vim script the indexes are byte indexes. This doesn't recognize multibyte encodings, see |byteidx()| for computing the indexes. If expr8 is a Number it is first converted to a String. +The item at index expr1b is included, it is inclusive. For an exclusive index +use the |slice()| function. + If expr1a is omitted zero is used. If expr1b is omitted the length of the string minus one is used. @@ -1196,7 +1244,7 @@ Note that the dot is also used for String concatenation. To avoid confusion always put spaces around the dot for String concatenation. -expr8(expr1, ...) |Funcref| function call +expr8(expr1, ...) |Funcref| function call *E1085* When expr8 is a |Funcref| type variable, invoke the function it refers to. @@ -1367,6 +1415,60 @@ to be doubled. These two commands are equivalent: > ------------------------------------------------------------------------------ +interpolated-string *$quote* *interpolated-string* + +$"string" interpolated string constant *expr-$quote* +$'string' interpolated literal string constant *expr-$'* + +Interpolated strings are an extension of the |string| and |literal-string|, +allowing the inclusion of Vim script expressions (see |expr1|). Any +expression returning a value can be enclosed between curly braces. The value +is converted to a string. All the text and results of the expressions +are concatenated to make a new string. + *E1278* +To include an opening brace '{' or closing brace '}' in the string content +double it. For double quoted strings using a backslash also works. A single +closing brace '}' will result in an error. + +Examples: > + let your_name = input("What's your name? ") +< What's your name? Peter ~ +> + echo + echo $"Hello, {your_name}!" +< Hello, Peter! ~ +> + echo $"The square root of {{9}} is {sqrt(9)}" +< The square root of {9} is 3.0 ~ + + *string-offset-encoding* +A string consists of multiple characters. UTF-8 uses one byte for ASCII +characters, two bytes for other latin characters and more bytes for other +characters. + +A string offset can count characters or bytes. Other programs may use +UTF-16 encoding (16-bit words) and an offset of UTF-16 words. Some functions +use byte offsets, usually for UTF-8 encoding. Other functions use character +offsets, in which case the encoding doesn't matter. + +The different offsets for the string "a©😊" are below: + + UTF-8 offsets: + [0]: 61, [1]: C2, [2]: A9, [3]: F0, [4]: 9F, [5]: 98, [6]: 8A + UTF-16 offsets: + [0]: 0061, [1]: 00A9, [2]: D83D, [3]: DE0A + UTF-32 (character) offsets: + [0]: 00000061, [1]: 000000A9, [2]: 0001F60A + +You can use the "g8" and "ga" commands on a character to see the +decimal/hex/octal values. + +The functions |byteidx()|, |utf16idx()| and |charidx()| can be used to convert +between these indices. The functions |strlen()|, |strutf16len()| and +|strcharlen()| return the number of bytes, UTF-16 code units and characters in +a string respectively. + +------------------------------------------------------------------------------ option *expr-option* *E112* *E113* &option option value, local value if possible @@ -1445,7 +1547,7 @@ See below |functions|. ------------------------------------------------------------------------------ lambda expression *expr-lambda* *lambda* -{args -> expr1} lambda expression +`{args -> expr1}` lambda expression *E451* A lambda expression creates a new unnamed function which returns the result of evaluating |expr1|. Lambda expressions differ from |user-function|s in @@ -1670,38 +1772,6 @@ v:argv The command line arguments Vim was invoked with. This is a list of strings. The first item is the Vim command. See |v:progpath| for the command with full path. - *v:beval_col* *beval_col-variable* -v:beval_col The number of the column, over which the mouse pointer is. - This is the byte index in the |v:beval_lnum| line. - Only valid while evaluating the 'balloonexpr' option. - - *v:beval_bufnr* *beval_bufnr-variable* -v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only - valid while evaluating the 'balloonexpr' option. - - *v:beval_lnum* *beval_lnum-variable* -v:beval_lnum The number of the line, over which the mouse pointer is. Only - valid while evaluating the 'balloonexpr' option. - - *v:beval_text* *beval_text-variable* -v:beval_text The text under or after the mouse pointer. Usually a word as - it is useful for debugging a C program. 'iskeyword' applies, - but a dot and "->" before the position is included. When on a - ']' the text before it is used, including the matching '[' and - word before it. When on a Visual area within one line the - highlighted text is used. Also see |<cexpr>|. - Only valid while evaluating the 'balloonexpr' option. - - *v:beval_winnr* *beval_winnr-variable* -v:beval_winnr The number of the window, over which the mouse pointer is. Only - valid while evaluating the 'balloonexpr' option. The first - window has number zero (unlike most other places where a - window gets a number). - - *v:beval_winid* *beval_winid-variable* -v:beval_winid The |window-ID| of the window, over which the mouse pointer - is. Otherwise like v:beval_winnr. - *v:char* *char-variable* v:char Argument for evaluating 'formatexpr' and used for the typed character when using <expr> in an abbreviation |:map-<expr>|. @@ -1776,7 +1846,7 @@ v:ctype The current locale setting for characters of the runtime v:dying Normally zero. When a deadly signal is caught it's set to one. When multiple signals are caught the number increases. Can be used in an autocommand to check if Vim didn't - terminate normally. {only works on Unix} + terminate normally. Example: > :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif < Note: if another deadly signal is caught when v:dying is one, @@ -1826,7 +1896,7 @@ v:event Dictionary of event data for the current |autocommand|. Valid abort Whether the event triggered during an aborting condition (e.g. |c_Esc| or |c_CTRL-C| for |CmdlineLeave|). - chan |channel-id| or 0 for "internal". + chan |channel-id| cmdlevel Level of cmdline. cmdtype Type of cmdline, |cmdline-char|. cwd Current working directory. @@ -1849,18 +1919,18 @@ v:event Dictionary of event data for the current |autocommand|. Valid completed_item Current selected complete item on |CompleteChanged|, Is `{}` when no complete item selected. - height Height of popup menu on |CompleteChanged| - width width of popup menu on |CompleteChanged| - row Row count of popup menu on |CompleteChanged|, + height Height of popup menu on |CompleteChanged| + width width of popup menu on |CompleteChanged| + row Row count of popup menu on |CompleteChanged|, relative to screen. - col Col count of popup menu on |CompleteChanged|, + col Col count of popup menu on |CompleteChanged|, relative to screen. - size Total number of completion items on + size Total number of completion items on |CompleteChanged|. - scrollbar Is |v:true| if popup menu have scrollbar, or + scrollbar Is |v:true| if popup menu have scrollbar, or |v:false| if not. - changed_window Is |v:true| if the the event fired - while changing window (or tab) on |DirChanged|. + changed_window Is |v:true| if the event fired while + changing window (or tab) on |DirChanged|. status Job status or exit code, -1 means "unknown". |TermClose| *v:exception* *exception-variable* @@ -2011,6 +2081,11 @@ v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr', v:lua Prefix for calling Lua functions from expressions. See |v:lua-call| for more information. + *v:maxcol* *maxcol-variable* +v:maxcol Maximum line length. Depending on where it is used it can be + screen columns, characters or bytes. The value currently is + 2147483647 on all systems. + *v:mouse_win* *mouse_win-variable* v:mouse_win Window number for a mouse click obtained with |getchar()|. First window has number 1, like with |winnr()|. The value is @@ -2135,7 +2210,7 @@ v:register The name of the register in effect for the current normal mode (use this in custom commands that take a register). If none is supplied it is the default register '"', unless 'clipboard' contains "unnamed" or "unnamedplus", then it is - '*' or '+'. + "*" or '+'. Also see |getreg()| and |setreg()| *v:relnum* *relnum-variable* @@ -2201,12 +2276,13 @@ v:stderr |channel-id| corresponding to stderr. The value is always 2; :call chansend(v:stderr, "error: toaster empty\n") < *v:swapname* *swapname-variable* -v:swapname Only valid when executing |SwapExists| autocommands: Name of - the swap file found. Read-only. +v:swapname Name of the swapfile found. + Only valid during |SwapExists| event. + Read-only. *v:swapchoice* *swapchoice-variable* v:swapchoice |SwapExists| autocommands can set this to the selected choice - for handling an existing swap file: + for handling an existing swapfile: 'o' Open read-only 'e' Edit anyway 'r' Recover @@ -2242,18 +2318,10 @@ v:t_string Value of |String| type. Read-only. See: |type()| v:t_blob Value of |Blob| type. Read-only. See: |type()| *v:termresponse* *termresponse-variable* -v:termresponse The escape sequence returned by the terminal for the DA - (request primary device attributes) control sequence. It is - set when Vim receives an escape sequence that starts with ESC - [ or CSI and ends in a 'c', with only digits, ';' and '.' in - between. - When this option is set, the TermResponse autocommand event is - fired, so that you can react to the response from the - terminal. - The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp - is the terminal type: 0 for vt100 and 1 for vt220. Pv is the - patch level (since this was introduced in patch 95, it's - always 95 or bigger). Pc is always zero. +v:termresponse The value of the most recent OSC or DCS escape sequence + received by Nvim from the terminal. This can be read in a + |TermResponse| event handler after querying the terminal using + another escape sequence. *v:testing* *testing-variable* v:testing Must be set before using `test_garbagecollect_now()`. @@ -2418,7 +2486,7 @@ This does NOT work: > *:let/=* *:let%=* *:let.=* *:let..=* *E734* :let {var} += {expr1} Like ":let {var} = {var} + {expr1}". :let {var} -= {expr1} Like ":let {var} = {var} - {expr1}". -:let {var} *= {expr1} Like ":let {var} = {var} * {expr1}". +`:let {var} *= {expr1}` Like ":let {var} = {var} * {expr1}". :let {var} /= {expr1} Like ":let {var} = {var} / {expr1}". :let {var} %= {expr1} Like ":let {var} = {var} % {expr1}". :let {var} .= {expr1} Like ":let {var} = {var} . {expr1}". @@ -2526,15 +2594,31 @@ This does NOT work: > |List| item. *:let=<<* *:let-heredoc* - *E990* *E991* *E172* *E221* -:let {var-name} =<< [trim] {endmarker} + *E990* *E991* *E172* *E221* *E1145* +:let {var-name} =<< [trim] [eval] {endmarker} text... text... {endmarker} Set internal variable {var-name} to a |List| containing the lines of text bounded by the string - {endmarker}. The lines of text is used as a - |literal-string|. + {endmarker}. + + If "eval" is not specified, then each line of text is + used as a |literal-string|, except that single quotes + does not need to be doubled. + If "eval" is specified, then any Vim expression in the + form {expr} is evaluated and the result replaces the + expression, like with |interpolated-string|. + Example where $HOME is expanded: > + let lines =<< trim eval END + some text + See the file {$HOME}/.vimrc + more text + END +< There can be multiple Vim expressions in a single line + but an expression cannot span multiple lines. If any + expression evaluation fails, then the assignment fails. + {endmarker} must not contain white space. {endmarker} cannot start with a lower case character. The last line should end only with the {endmarker} @@ -2584,6 +2668,13 @@ text... 1 2 3 4 5 6 7 8 DATA + + let code =<< trim eval CODE + let v = {10 + 20} + let h = "{$HOME}" + let s = "{Str1()} abc {Str2()}" + let n = {MyFunc(3, 4)} + CODE < *E121* :let {var-name} .. List the value of variable {var-name}. Multiple @@ -2700,8 +2791,8 @@ text... Example with [depth] 0: > let mylist = [1, 2, 3] lockvar 0 mylist - let mylist[0] = 77 " OK - call add(mylist, 4] " OK + let mylist[0] = 77 " OK + call add(mylist, 4) " OK let mylist = [7, 8, 9] " Error! < *E743* For unlimited depth use [!] and omit [depth]. @@ -4172,10 +4263,10 @@ The input is in the variable "line", the results in the variables "file", getting the scriptnames in a Dictionary ~ *scriptnames-dictionary* -The |:scriptnames| command can be used to get a list of all script files that -have been sourced. There is no equivalent function or variable for this -(because it's rarely needed). In case you need to manipulate the list this -code can be used: > +The `:scriptnames` command can be used to get a list of all script files that +have been sourced. There is also the `getscriptinfo()` function, but the +information returned is not exactly the same. In case you need to manipulate +the output of `scriptnames` this code can be used: > " Get the output of ":scriptnames" in the scriptnames_output variable. let scriptnames_output = '' redir => scriptnames_output @@ -4244,8 +4335,8 @@ Textlock *textlock* In a few situations it is not allowed to change the text in the buffer, jump to another window and some other things that might confuse or break what Vim is currently doing. This mostly applies to things that happen when Vim is -actually doing something else. For example, evaluating the 'balloonexpr' may -happen any moment the mouse cursor is resting at some position. +actually doing something else. For example, a TextYankPost autocommand cannot +edit the text it is yanking. This is not allowed when the textlock is active: - changing the buffer text @@ -4255,6 +4346,33 @@ This is not allowed when the textlock is active: - etc. ============================================================================== +Vim script library *vim-script-library* + +Vim comes bundled with a Vim script library, that can be used by runtime, +script authors. Currently, it only includes very few functions, but it may +grow over time. + + *dist#vim* +The functions make use of the autoloaded prefix "dist#vim". + +The following functions are available: + +dist#vim#IsSafeExecutable(filetype, executable) ~ + +This function takes a filetype and an executable and checks whether it is safe +to execute the given executable. For security reasons users may not want to +have Vim execute random executables or may have forbidden to do so for +specific filetypes by setting the "<filetype>_exec" variable (|plugin_exec|). + +It returns |TRUE| or |FALSE| to indicate whether the plugin should run the given +exectuable. It takes the following arguments: + + argument type ~ + + filetype string + executable string + +============================================================================== Command-line expressions highlighting *expr-highlight* Expressions entered by the user in |i_CTRL-R_=|, |c_CTRL-\_e|, |quote=| are diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index a53c287d48..ed21dc1c37 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -54,9 +54,9 @@ you can either set the 'filetype' option manually, or add a modeline to your file. Example, for an IDL file use the command: > :set filetype=idl -or add this |modeline| to the file: - /* vim: set filetype=idl : */ ~ - +or add this |modeline| to the file: > + /* vim: set filetype=idl : */ +< *:filetype-plugin-on* You can enable loading the plugin files for specific file types with: > :filetype plugin on @@ -136,37 +136,42 @@ what kind of file it is. This doesn't always work. A number of global variables can be used to overrule the filetype used for certain extensions: file name variable ~ - *.asa g:filetype_asa |ft-aspvbs-syntax| |ft-aspperl-syntax| - *.asm g:asmsyntax |ft-asm-syntax| - *.asp g:filetype_asp |ft-aspvbs-syntax| |ft-aspperl-syntax| - *.bas g:filetype_bas |ft-basic-syntax| - *.cfg g:filetype_cfg - *.cls g:filetype_cls - *.csh g:filetype_csh |ft-csh-syntax| - *.dat g:filetype_dat - *.frm g:filetype_frm |ft-form-syntax| - *.fs g:filetype_fs |ft-forth-syntax| - *.i g:filetype_i |ft-progress-syntax| - *.inc g:filetype_inc - *.lsl g:filetype_lsl - *.m g:filetype_m |ft-mathematica-syntax| - *.mod g:filetype_mod - *.p g:filetype_p |ft-pascal-syntax| - *.pl g:filetype_pl - *.pp g:filetype_pp |ft-pascal-syntax| - *.prg g:filetype_prg - *.r g:filetype_r - *.sig g:filetype_sig - *.sql g:filetype_sql |ft-sql-syntax| - *.src g:filetype_src - *.sys g:filetype_sys - *.sh g:bash_is_sh |ft-sh-syntax| - *.tex g:tex_flavor |ft-tex-plugin| - *.w g:filetype_w |ft-cweb-syntax| + `*.asa` g:filetype_asa |ft-aspperl-syntax| + |ft-aspvbs-syntax| + `*.asm` g:asmsyntax |ft-asm-syntax| + `*.asp` g:filetype_asp |ft-aspperl-syntax| + |ft-aspvbs-syntax| + `*.bas` g:filetype_bas |ft-basic-syntax| + `*.cfg` g:filetype_cfg + `*.cls` g:filetype_cls + `*.csh` g:filetype_csh |ft-csh-syntax| + `*.dat` g:filetype_dat + `*.f` g:filetype_f |ft-forth-syntax| + `*.frm` g:filetype_frm |ft-form-syntax| + `*.fs` g:filetype_fs |ft-forth-syntax| + `*.h` g:c_syntax_for_h |ft-c-syntax| + `*.i` g:filetype_i |ft-progress-syntax| + `*.inc` g:filetype_inc + `*.lsl` g:filetype_lsl + `*.m` g:filetype_m |ft-mathematica-syntax| + `*.mod` g:filetype_mod + `*.p` g:filetype_p |ft-pascal-syntax| + `*.pl` g:filetype_pl + `*.pp` g:filetype_pp |ft-pascal-syntax| + `*.prg` g:filetype_prg + `*.r` g:filetype_r + `*.sig` g:filetype_sig + `*.sql` g:filetype_sql |ft-sql-syntax| + `*.src` g:filetype_src + `*.sys` g:filetype_sys + `*.sh` g:bash_is_sh |ft-sh-syntax| + `*.tex` g:tex_flavor |ft-tex-plugin| + `*.typ` g:filetype_typ + `*.w` g:filetype_w |ft-cweb-syntax| For a few filetypes the global variable is used only when the filetype could not be detected: - *.r g:filetype_r |ft-rexx-syntax| + `*.r` g:filetype_r |ft-rexx-syntax| *filetype-ignore* To avoid that certain files are being inspected, the g:ft_ignore_pat variable @@ -356,7 +361,7 @@ ways to change this: You must create a new filetype plugin in a directory early in 'runtimepath'. For Unix, for example you could use this file: > vim ~/.config/nvim/ftplugin/fortran.vim -< You can set those settings and mappings that you would like to add. Note +< You can set those settings and mappings that you would like to add. Note that the global plugin will be loaded after this, it may overrule the settings that you do here. If this is the case, you need to use one of the following two methods. @@ -365,7 +370,7 @@ ways to change this: You must put the copy in a directory early in 'runtimepath'. For Unix, for example, you could do this: > cp $VIMRUNTIME/ftplugin/fortran.vim ~/.config/nvim/ftplugin/fortran.vim -< Then you can edit the copied file to your liking. Since the b:did_ftplugin +< Then you can edit the copied file to your liking. Since the b:did_ftplugin variable will be set, the global plugin will not be loaded. A disadvantage of this method is that when the distributed plugin gets improved, you will have to copy and modify it again. @@ -374,17 +379,30 @@ ways to change this: You must create a new filetype plugin in a directory from the end of 'runtimepath'. For Unix, for example, you could use this file: > vim ~/.config/nvim/after/ftplugin/fortran.vim -< In this file you can change just those settings that you want to change. +< In this file you can change just those settings that you want to change. ============================================================================== 3. Docs for the default filetype plugins. *ftplugin-docs* + *plugin_exec* *g:plugin_exec* +Enable executing of external commands. This was done historically for e.g. +the perl filetype plugin (and a few others) to set the search path. +Disabled by default for security reasons: > + :let g:plugin_exec = 1 +It is also possible to enable this only for certain filetypes: > + :let g:<filetype>_exec = 1 +So to enable this only for ruby, set the following variable: > + :let g:ruby_exec = 1 + +If both, the global `plugin_exec` and the `<filetype>_exec` specific variable +are set, the filetype specific variable should have precedent. + AWK *ft-awk-plugin* Support for features specific to GNU Awk, like @include, can be enabled by setting: > - let g:awk_is_gawk = 1 + :let g:awk_is_gawk = 1 CHANGELOG *ft-changelog-plugin* @@ -618,7 +636,7 @@ To use Nvim as a manpager: > export MANPAGER='nvim +Man!' Note that when running `man` from the shell and with that `MANPAGER` in your -environment, `man` will pre-format the manpage using `groff`. Thus, Neovim +environment, `man` will pre-format the manpage using `groff`. Thus, Nvim will inevitably display the manual page as it was passed to it from stdin. One of the caveats of this is that the width will _always_ be hard-wrapped and not soft wrapped as with `g:man_hardwrap=0`. You can set in your environment: > @@ -634,7 +652,10 @@ MARKDOWN *ft-markdown-plugin* To enable folding use this: > let g:markdown_folding = 1 -< + +'expandtab' will be set by default. If you do not want that use this: > + let g:markdown_recommended_style = 0 + PDF *ft-pdf-plugin* @@ -660,6 +681,19 @@ To disable this behavior, set the following variable in your vimrc: > let g:python_recommended_style = 0 +QUERY *ft-query-plugin* + + +Linting of tree-sitter queries for installed parsers using +|vim.treesitter.query.lint()| is enabled by default on `BufEnter` and +`BufWrite`. To change the events that trigger linting, use >lua + + vim.g.query_lint_on = { 'InsertLeave', 'TextChanged' } +< +To disable linting completely, set >lua + + vim.g.query_lint_on = {} +< QF QUICKFIX *qf.vim* *ft-qf-plugin* @@ -708,7 +742,7 @@ file: |pi_spec.txt|. SHADA *ft-shada* -Allows editing binary |shada-file|s in a nice way. Opened binary files are +Allows editing binary |shada-file|s in a nice way. Opened binary files are displayed in the following format: > Type with timestamp YYYY-mm-ddTHH:MM:SS: @@ -723,31 +757,31 @@ displayed in the following format: > # Unexpected type: type instead of map = {msgpack-value} -Filetype plugin defines all |Cmd-event|s. Defined |SourceCmd| event makes -"source file.shada" be equivalent to "|:rshada| file.shada". |BufWriteCmd|, -|FileWriteCmd| and |FileAppendCmd| events are affected by the following +Filetype plugin defines all |Cmd-event|s. Defined |SourceCmd| event makes +"source file.shada" be equivalent to "|:rshada| file.shada". |BufWriteCmd|, +|FileWriteCmd| and |FileAppendCmd| events are affected by the following settings: -*g:shada#keep_old_header* Boolean, if set to false all header entries +*g:shada#keep_old_header* Boolean, if set to false all header entries are ignored when writing. Defaults to 1. -*g:shada#add_own_header* Boolean, if set to true first written entry - will always be header entry with two values in - a map with attached data: |v:version| attached - to "version" key and "shada.vim" attached to +*g:shada#add_own_header* Boolean, if set to true first written entry + will always be header entry with two values in + a map with attached data: |v:version| attached + to "version" key and "shada.vim" attached to "generator" key. Defaults to 1. Format description: -1. `#` starts a comment. Lines starting with space characters and then `#` - are ignored. Plugin may only add comment lines to indicate some errors in - ShaDa format. Lines containing no non-whitespace characters are also +1. `#` starts a comment. Lines starting with space characters and then `#` + are ignored. Plugin may only add comment lines to indicate some errors in + ShaDa format. Lines containing no non-whitespace characters are also ignored. -2. Each entry starts with line that has format "{type} with timestamp - {timestamp}:". {timestamp} is |strftime()|-formatted string representing +2. Each entry starts with line that has format "{type} with timestamp + {timestamp}:". {timestamp} is |strftime()|-formatted string representing actual Unix timestamp value. First strftime() argument is equal to - `%Y-%m-%dT%H:%M:%S`. When writing this timestamp is parsed using - |msgpack#strptime()|, with caching (it remembers which timestamp produced - particular strftime() output and uses this value if you did not change + `%Y-%m-%dT%H:%M:%S`. When writing this timestamp is parsed using + |msgpack#strptime()|, with caching (it remembers which timestamp produced + particular strftime() output and uses this value if you did not change timestamp). {type} is one of 1 - Header 2 - Search pattern @@ -762,28 +796,28 @@ Format description: 11 - Change * - Unknown (0x{type-hex}) - Each type may be represented using Unknown entry: "Jump with timestamp ..." + Each type may be represented using Unknown entry: "Jump with timestamp ..." is the same as "Unknown (0x8) with timestamp ....". 3. After header there is one of the following lines: - 1. " % Key__ Description__ Value": map header. After mapping header - follows a table which may contain comments and lines consisting of - " +", key, description and |{msgpack-value}|. Key is separated by at - least two spaces with description, description is separated by at least - two spaces with the value. Each key in the map must be at most as wide - as "Key__" header: "Key" allows at most 3-byte keys, "Key__" allows at - most 5-byte keys. If keys actually occupy less bytes then the rest is - filled with spaces. Keys cannot be empty, end with spaces, contain two - consequent spaces inside of them or contain multibyte characters (use - "=" format if you need this). Descriptions have the same restrictions - on width and contents, except that empty descriptions are allowed. + 1. " % Key__ Description__ Value": map header. After mapping header + follows a table which may contain comments and lines consisting of + " +", key, description and |{msgpack-value}|. Key is separated by at + least two spaces with description, description is separated by at least + two spaces with the value. Each key in the map must be at most as wide + as "Key__" header: "Key" allows at most 3-byte keys, "Key__" allows at + most 5-byte keys. If keys actually occupy less bytes then the rest is + filled with spaces. Keys cannot be empty, end with spaces, contain two + consequent spaces inside of them or contain multibyte characters (use + "=" format if you need this). Descriptions have the same restrictions + on width and contents, except that empty descriptions are allowed. Description column may be omitted. - When writing description is ignored. Keys with values |msgpack#equal| - to default ones are ignored. Order of keys is preserved. All keys are + When writing description is ignored. Keys with values |msgpack#equal| + to default ones are ignored. Order of keys is preserved. All keys are treated as strings (not binary strings). - Note: specifically for buffer list entries it is allowed to have more - then one map header. Each map header starts a new map entry inside + Note: specifically for buffer list entries it is allowed to have more + then one map header. Each map header starts a new map entry inside buffer list because ShaDa buffer list entry is an array of maps. I.e. > Buffer list with timestamp 1970-01-01T00:00:00: @@ -811,7 +845,7 @@ Format description: Buffer list with timestamp 1970-01-01T00:00:00: = [{="f": "/foo"}, {="f": "/bar"}] < - Note 2: specifically for register entries special syntax for arrays was + Note 2: specifically for register entries special syntax for arrays was designed: > Register with timestamp 1970-01-01T00:00:00: @@ -826,10 +860,10 @@ Format description: % Key Description Value + rc contents ["line1", "line2"] < - Such syntax is automatically used if array representation appears to be + Such syntax is automatically used if array representation appears to be too lengthy. - 2. " @ Description__ Value": array header. Same as map, but key is - omitted and description cannot be omitted. Array entries start with + 2. " @ Description__ Value": array header. Same as map, but key is + omitted and description cannot be omitted. Array entries start with " -". Example: > History entry with timestamp 1970-01-01T00:00:00: @@ -844,8 +878,8 @@ Format description: = [SEARCH, "foo", '/'] < Note: special array syntax for register entries is not recognized here. - 3. " = {msgpack-value}": raw values. |{msgpack-value}| in this case may - have absolutely any type. Special array syntax for register entries is + 3. " = {msgpack-value}": raw values. |{msgpack-value}| in this case may + have absolutely any type. Special array syntax for register entries is not recognized here as well. @@ -863,7 +897,7 @@ file: |ft_sql.txt|. TEX *ft-tex-plugin* *g:tex_flavor* -If the first line of a *.tex file has the form > +If the first line of a `*.tex` file has the form > %&<format> then this determined the file type: plaintex (for plain TeX), context (for ConTeXt), or tex (for LaTeX). Otherwise, the file is searched for keywords to diff --git a/runtime/doc/fold.txt b/runtime/doc/fold.txt index 35a3be35fb..8f7393f5e3 100644 --- a/runtime/doc/fold.txt +++ b/runtime/doc/fold.txt @@ -195,7 +195,7 @@ non-matching marker pairs. Example: > /* funcB() {{{2 */ void funcB() {} - +< *{{{* *}}}* A fold starts at a "{{{" marker. The following number specifies the fold level. What happens depends on the difference between the current fold level and the level given by the marker: @@ -253,7 +253,7 @@ This does not work properly when: know what to do. - Folds nearby use a level number in their marker which gets in the way. - The line is inside a comment, 'commentstring' isn't empty and nested - comments don't work. For example with C: adding /* {{{ */ inside a comment + comments don't work. For example with C: adding `/* {{{ */` inside a comment will truncate the existing comment. Either put the marker before or after the comment, or add the marker manually. Generally it's not a good idea to let Vim create markers when you already have @@ -346,7 +346,8 @@ zC Close all folds under the cursor recursively. Folds that 'foldenable' will be set. *za* -za When on a closed fold: open it. When folds are nested, you +za Summary: Toggle the fold under the cursor. + When on a closed fold: open it. When folds are nested, you may have to use "za" several times. When a count is given, that many closed folds are opened. When on an open fold: close it and set 'foldenable'. This @@ -519,8 +520,10 @@ expression. It can use these special Vim variables: foldlevel. v:foldlevel the foldlevel of the fold -In the result a TAB is replaced with a space and unprintable characters are -made into printable characters. +If the result is a |List|, it is parsed and drawn like "overlay" virtual text +(see |nvim_buf_set_extmark()|), otherwise the result is converted to a string +where a TAB is replaced with a space and unprintable characters are made into +printable characters. The resulting line is truncated to fit in the window, it never wraps. When there is room after the text, it is filled with the character specified diff --git a/runtime/doc/ft_ada.txt b/runtime/doc/ft_ada.txt index 3321228009..3b7d6a73dd 100644 --- a/runtime/doc/ft_ada.txt +++ b/runtime/doc/ft_ada.txt @@ -112,8 +112,8 @@ NOTE: "gnat xref -v" is very tricky to use as it has almost no diagnostic your .ali files. 2) "gnat xref -v ../Include/adacl.ads" won't work - use the "gnat xref -v -aI../Include adacl.ads" instead. -3) "gnat xref -v -aI../Include *.ad?" won't work - use "cd ../Include" and - then "gnat xref -v *.ad?" +3) `gnat xref -v -aI../Include *.ad?` won't work - use "cd ../Include" and + then `gnat xref -v *.ad?` 4) Project manager support is completely broken - don't even try "gnat xref -Padacl.gpr". 5) Vim is faster when the tags file is sorted - use "sort --unique diff --git a/runtime/doc/ft_raku.txt b/runtime/doc/ft_raku.txt index 3d1179ed4e..c9bbe4bd04 100644 --- a/runtime/doc/ft_raku.txt +++ b/runtime/doc/ft_raku.txt @@ -35,10 +35,10 @@ Some of them are available with standard Vim digraphs: (- ∈ ?= ≅ != ≠ ~ -) ∋ ?- ≃ ~ -The Greek alphabet is available with '*' followed by a similar Latin symbol: - *p π ~ - *t τ ~ - *X × ~ +The Greek alphabet is available with "*" followed by a similar Latin symbol: > + *p π + *t τ + *X × Numbers, subscripts and superscripts are available with 's' and 'S': 0s ₀ 0S ⁰ ~ diff --git a/runtime/doc/ft_rust.txt b/runtime/doc/ft_rust.txt index a5d5b558dc..159ff7d5f6 100644 --- a/runtime/doc/ft_rust.txt +++ b/runtime/doc/ft_rust.txt @@ -1,72 +1,74 @@ -*ft_rust.txt* Nvim - -This is documentation for the Rust filetype plugin. +*ft_rust.txt* Filetype plugin for Rust ============================================================================== -CONTENTS *rust* +CONTENTS *rust* -1. Introduction |rust-intro| -2. Settings |rust-settings| -3. Commands |rust-commands| -4. Mappings |rust-mappings| +1. Introduction |rust-intro| +2. Settings |rust-settings| +3. Commands |rust-commands| +4. Mappings |rust-mappings| ============================================================================== -INTRODUCTION *rust-intro* +INTRODUCTION *rust-intro* This plugin provides syntax and supporting functionality for the Rust -filetype. +filetype. It requires Vim 8 or higher for full functionality. Some commands +will not work on earlier versions. ============================================================================== -SETTINGS *rust-settings* +SETTINGS *rust-settings* This plugin has a few variables you can define in your vimrc that change the behavior of the plugin. - *g:rustc_path* -g:rustc_path~ +Some variables can be set buffer local (`:b` prefix), and the buffer local +will take precedence over the global `g:` counterpart. + + *g:rustc_path* +g:rustc_path ~ Set this option to the path to rustc for use in the |:RustRun| and - |:RustExpand| commands. If unset, "rustc" will be located in $PATH: > - let g:rustc_path = $HOME .. "/bin/rustc" + |:RustExpand| commands. If unset, `rustc` will be located in $PATH: >vim + let g:rustc_path = $HOME."/bin/rustc" < - *g:rustc_makeprg_no_percent* -g:rustc_makeprg_no_percent~ - Set this option to 1 to have 'makeprg' default to "rustc" instead of - "rustc %": > + *g:rustc_makeprg_no_percent* +g:rustc_makeprg_no_percent ~ + Set this option to 1 to have 'makeprg' default to `rustc` instead of + `rustc %`: >vim let g:rustc_makeprg_no_percent = 1 < - *g:rust_conceal* -g:rust_conceal~ - Set this option to turn on the basic |conceal| support: > + *g:rust_conceal* +g:rust_conceal ~ + Set this option to turn on the basic |conceal| support: >vim let g:rust_conceal = 1 < - *g:rust_conceal_mod_path* -g:rust_conceal_mod_path~ + *g:rust_conceal_mod_path* +g:rust_conceal_mod_path ~ Set this option to turn on |conceal| for the path connecting token - "::": > + "::": >vim let g:rust_conceal_mod_path = 1 < - *g:rust_conceal_pub* -g:rust_conceal_pub~ - Set this option to turn on |conceal| for the "pub" token: > + *g:rust_conceal_pub* +g:rust_conceal_pub ~ + Set this option to turn on |conceal| for the "pub" token: >vim let g:rust_conceal_pub = 1 < - *g:rust_recommended_style* -g:rust_recommended_style~ - Set this option to enable vim indentation and textwidth settings to - conform to style conventions of the rust standard library (i.e. use 4 - spaces for indents and sets 'textwidth' to 99). This option is enabled - by default. To disable it: > + *g:rust_recommended_style* +g:rust_recommended_style ~ + Set this option to enable vim indentation and textwidth settings to + conform to style conventions of the rust standard library (i.e. use 4 + spaces for indents and sets 'textwidth' to 99). This option is enabled + by default. To disable it: >vim let g:rust_recommended_style = 0 < - *g:rust_fold* -g:rust_fold~ - Set this option to turn on |folding|: > + *g:rust_fold* +g:rust_fold ~ + Set this option to turn on |folding|: >vim let g:rust_fold = 1 < Value Effect ~ @@ -77,62 +79,296 @@ g:rust_fold~ global value (all folds are closed by default). *g:rust_bang_comment_leader* -g:rust_bang_comment_leader~ +g:rust_bang_comment_leader ~ Set this option to 1 to preserve the leader on multi-line doc comments - using the /*! syntax: > + using the `/*!` syntax: >vim let g:rust_bang_comment_leader = 1 < - *g:ftplugin_rust_source_path* -g:ftplugin_rust_source_path~ + *g:rust_use_custom_ctags_defs* +g:rust_use_custom_ctags_defs ~ + Set this option to 1 if you have customized ctags definitions for Rust + and do not wish for those included with rust.vim to be used: >vim + let g:rust_use_custom_ctags_defs = 1 +< + + NOTE: rust.vim's built-in definitions are only used for the Tagbar Vim + plugin, if you have it installed, AND if Universal Ctags is not + detected. This is because Universal Ctags already has built-in + support for Rust when used with Tagbar. + + Also, note that when using ctags other than Universal Ctags, it is not + automatically used when generating |tags| files that Vim can use to + navigate to definitions across different source files. Feel free to + copy `rust.vim/ctags/rust.ctags` into your own `~/.ctags` if you wish + to generate |tags| files. + + *g:ftplugin_rust_source_path* +g:ftplugin_rust_source_path ~ Set this option to a path that should be prepended to 'path' for Rust - source files: > - let g:ftplugin_rust_source_path = $HOME .. '/dev/rust' + source files: >vim + let g:ftplugin_rust_source_path = $HOME . '/dev/rust' < *g:rustfmt_command* -g:rustfmt_command~ +g:rustfmt_command ~ Set this option to the name of the "rustfmt" executable in your $PATH. If - not specified it defaults to "rustfmt" : > + not specified it defaults to "rustfmt" : >vim let g:rustfmt_command = 'rustfmt' < *g:rustfmt_autosave* -g:rustfmt_autosave~ +g:rustfmt_autosave ~ Set this option to 1 to run |:RustFmt| automatically when saving a - buffer. If not specified it defaults to 0 : > + buffer. If not specified it defaults to 0 : >vim let g:rustfmt_autosave = 0 < + There is also a buffer-local b:rustfmt_autosave that can be set for + the same purpose, and can override the global setting. + + *g:rustfmt_autosave_if_config_present* +g:rustfmt_autosave_if_config_present ~ + Set this option to 1 to have *b:rustfmt_autosave* be set automatically + if a `rustfmt.toml` file is present in any parent directly leading to + the file being edited. If not set, default to 0: >vim + let g:rustfmt_autosave_if_config_present = 0 +< + This is useful to have `rustfmt` only execute on save, on projects + that have `rustfmt.toml` configuration. + + There is also a buffer-local b:rustfmt_autosave_if_config_present + that can be set for the same purpose, which can overrides the global + setting. + *g:rustfmt_fail_silently* -g:rustfmt_fail_silently~ +g:rustfmt_fail_silently ~ Set this option to 1 to prevent "rustfmt" from populating the - |location-list| with errors. If not specified it defaults to 0: > + |location-list| with errors. If not specified it defaults to 0: >vim let g:rustfmt_fail_silently = 0 < *g:rustfmt_options* -g:rustfmt_options~ +g:rustfmt_options ~ Set this option to a string of options to pass to "rustfmt". The write-mode is already set to "overwrite". If not specified it - defaults to '' : > + defaults to '' : >vim let g:rustfmt_options = '' < + *g:rustfmt_emit_files* +g:rustfmt_emit_files ~ + If not specified rust.vim tries to detect the right parameter to + pass to rustfmt based on its reported version. Otherwise, it + determines whether to run rustfmt with '--emit=files' (when 1 is + provided) instead of '--write-mode=overwrite'. >vim + let g:rustfmt_emit_files = 0 +< *g:rust_playpen_url* -g:rust_playpen_url~ - Set this option to override the URL for the playpen to use: > +g:rust_playpen_url ~ + Set this option to override the url for the playpen to use: >vim let g:rust_playpen_url = 'https://play.rust-lang.org/' < *g:rust_shortener_url* -g:rust_shortener_url~ - Set this option to override the URL for the URL shortener: > +g:rust_shortener_url ~ + Set this option to override the url for the url shortener: >vim let g:rust_shortener_url = 'https://is.gd/' < + *g:rust_clip_command* +g:rust_clip_command ~ + Set this option to the command used in your OS to copy the Rust Play + url to the clipboard: >vim + let g:rust_clip_command = 'xclip -selection clipboard' +< + *g:cargo_makeprg_params* +g:cargo_makeprg_params ~ + Set this option to the string of parameters to pass to cargo. If not + specified it defaults to `$*` : >vim + let g:cargo_makeprg_params = 'build' +< + + *g:cargo_shell_command_runner* +g:cargo_shell_command_runner ~ + Set this option to change how to run shell commands for cargo commands + |:Cargo|, |:Cbuild|, |:Crun|, ... + By default, |:terminal| is used to run shell command in terminal window + asynchronously. But if you prefer |:!| for running the commands, it can + be specified: >vim + let g:cargo_shell_command_runner = '!' +< + +------------------------------------------------------------------------------ +Integration with Syntastic *rust-syntastic* + +This plugin automatically integrates with the Syntastic checker. There are two +checkers provided: `rustc`, and `cargo`. The latter invokes `cargo` in order to +build code, and the former delivers a single edited '.rs' file as a compilation +target directly to the Rust compiler, `rustc`. + +Because Cargo is almost exclusively being used for building Rust code these +days, `cargo` is the default checker. >vim + + let g:syntastic_rust_checkers = ['cargo'] +< +If you would like to change it, you can set `g:syntastic_rust_checkers` to a +different value. + *g:rust_cargo_avoid_whole_workspace* + *b:rust_cargo_avoid_whole_workspace* +g:rust_cargo_avoid_whole_workspace ~ + When editing a crate that is part of a Cargo workspace, and this + option is set to 1 (the default), then `cargo` will be executed + directly in that crate directory instead of in the workspace + directory. Setting 0 prevents this behavior - however be aware that if + you are working in large workspace, Cargo commands may take more time, + plus the Syntastic error list may include all the crates in the + workspace. >vim + let g:rust_cargo_avoid_whole_workspace = 0 +< + *g:rust_cargo_check_all_targets* + *b:rust_cargo_check_all_targets* +g:rust_cargo_check_all_targets ~ + When set to 1, the `--all-targets` option will be passed to cargo when + Syntastic executes it, allowing the linting of all targets under the + package. + The default is 0. + + *g:rust_cargo_check_all_features* + *b:rust_cargo_check_all_features* +g:rust_cargo_check_all_features ~ + When set to 1, the `--all-features` option will be passed to cargo when + Syntastic executes it, allowing the linting of all features of the + package. + The default is 0. + + *g:rust_cargo_check_examples* + *b:rust_cargo_check_examples* +g:rust_cargo_check_examples ~ + When set to 1, the `--examples` option will be passed to cargo when + Syntastic executes it, to prevent the exclusion of examples from + linting. The examples are normally under the `examples/` directory of + the crate. + The default is 0. + + *g:rust_cargo_check_tests* + *b:rust_cargo_check_tests* +g:rust_cargo_check_tests ~ + When set to 1, the `--tests` option will be passed to cargo when + Syntastic executes it, to prevent the exclusion of tests from linting. + The tests are normally under the `tests/` directory of the crate. + The default is 0. + + *g:rust_cargo_check_benches* + *b:rust_cargo_check_benches* +g:rust_cargo_check_benches ~ + When set to 1, the `--benches` option will be passed to cargo when + Syntastic executes it. The benches are normally under the `benches/` + directory of the crate. + The default is 0. + +------------------------------------------------------------------------------ +Integration with auto-pairs *rust-auto-pairs* + +This plugin automatically configures the auto-pairs plugin not to duplicate +single quotes, which are used more often for lifetime annotations than for +single character literals. + + *g:rust_keep_autopairs_default* +g:rust_keep_autopairs_default ~ + + Don't override auto-pairs default for the Rust filetype. The default + is 0. ============================================================================== -COMMANDS *rust-commands* +COMMANDS *rust-commands* + +Invoking Cargo ~ + +This plug defines very simple shortcuts for invoking Cargo from with Vim. + +:Cargo <args> *:Cargo* + Runs `cargo` with the provided arguments. + +:Cbuild <args> *:Cbuild* + Shortcut for `cargo build` . + +:Cclean <args> *:Cclean* + Shortcut for `cargo clean` . + +:Cdoc <args> *:Cdoc* + Shortcut for `cargo doc` . + +:Cinit <args> *:Cinit* + Shortcut for `cargo init` . + +:Crun <args> *:Crun* + Shortcut for `cargo run` . + +:Ctest <args> *:Ctest* + Shortcut for `cargo test` . + +:Cupdate <args> *:Cupdate* + Shortcut for `cargo update` . + +:Cbench <args> *:Cbench* + Shortcut for `cargo bench` . + +:Csearch <args> *:Csearch* + Shortcut for `cargo search` . + +:Cpublish <args> *:Cpublish* + Shortcut for `cargo publish` . + +:Cinstall <args> *:Cinstall* + Shortcut for `cargo install` . + +:Cruntarget <args> *:Cruntarget* + Shortcut for `cargo run --bin` or `cargo run --example`, + depending on the currently open buffer. + +Formatting ~ + +:RustFmt *:RustFmt* + Runs |g:rustfmt_command| on the current buffer. If + |g:rustfmt_options| is set then those will be passed to the + executable. + + If |g:rustfmt_fail_silently| is 0 (the default) then it + will populate the |location-list| with the errors from + |g:rustfmt_command|. If |g:rustfmt_fail_silently| is set to 1 + then it will not populate the |location-list|. -:RustRun [args] *:RustRun* +:RustFmtRange *:RustFmtRange* + Runs |g:rustfmt_command| with selected range. See + |:RustFmt| for any other information. + + +Playpen integration ~ + +:RustPlay *:RustPlay* + This command will only work if you have web-api.vim installed + (available at https://github.com/mattn/webapi-vim). It sends the + current selection, or if nothing is selected, the entirety of the + current buffer to the Rust playpen, and emits a message with the + shortened URL to the playpen. + + |g:rust_playpen_url| is the base URL to the playpen, by default + "https://play.rust-lang.org/". + + |g:rust_shortener_url| is the base url for the shorterner, by + default "https://is.gd/" + + |g:rust_clip_command| is the command to run to copy the + playpen url to the clipboard of your system. + + +Evaluation of a single Rust file ~ + +NOTE: These commands are useful only when working with standalone Rust files, +which is usually not the case for common Rust development. If you wish to +building Rust crates from with Vim can should use Vim's make, Syntastic, or +functionality from other plugins. + + +:RustRun [args] *:RustRun* :RustRun! [rustc-args] [--] [args] Compiles and runs the current file. If it has unsaved changes, it will be saved first using |:update|. If the current file is @@ -150,26 +386,26 @@ COMMANDS *rust-commands* If |g:rustc_path| is defined, it is used as the path to rustc. Otherwise it is assumed rustc can be found in $PATH. -:RustExpand [args] *:RustExpand* +:RustExpand [args] *:RustExpand* :RustExpand! [TYPE] [args] - Expands the current file using --pretty and displays the + Expands the current file using `--pretty` and displays the results in a new split. If the current file has unsaved changes, it will be saved first using |:update|. If the current file is an unnamed buffer, it will be written to a temporary file first. The arguments given to |:RustExpand| will be passed to rustc. - This is largely intended for specifying various --cfg + This is largely intended for specifying various `--cfg` configurations. If ! is specified, the first argument is the expansion type to - pass to rustc --pretty. Otherwise it will default to + pass to `rustc --pretty` . Otherwise it will default to "expanded". If |g:rustc_path| is defined, it is used as the path to rustc. Otherwise it is assumed rustc can be found in $PATH. -:RustEmitIr [args] *:RustEmitIr* +:RustEmitIr [args] *:RustEmitIr* Compiles the current file to LLVM IR and displays the results in a new split. If the current file has unsaved changes, it will be saved first using |:update|. If the current file is an @@ -180,7 +416,7 @@ COMMANDS *rust-commands* If |g:rustc_path| is defined, it is used as the path to rustc. Otherwise it is assumed rustc can be found in $PATH. -:RustEmitAsm [args] *:RustEmitAsm* +:RustEmitAsm [args] *:RustEmitAsm* Compiles the current file to assembly and displays the results in a new split. If the current file has unsaved changes, it will be saved first using |:update|. If the current file is an @@ -191,49 +427,52 @@ COMMANDS *rust-commands* If |g:rustc_path| is defined, it is used as the path to rustc. Otherwise it is assumed rustc can be found in $PATH. -:RustPlay *:RustPlay* - This command will only work if you have web-api.vim installed - (available at https://github.com/mattn/webapi-vim). It sends the - current selection, or if nothing is selected, the entirety of the - current buffer to the Rust playpen, and emits a message with the - shortened URL to the playpen. - |g:rust_playpen_url| is the base URL to the playpen, by default - "https://play.rust-lang.org/". +Running test(s) ~ - |g:rust_shortener_url| is the base URL for the shortener, by - default "https://is.gd/" +:[N]RustTest[!] [options] *:RustTest* + Runs a test under the cursor when the current buffer is in a + cargo project with "cargo test" command. If the command did + not find any test function under the cursor, it stops with an + error message. -:RustFmt *:RustFmt* - Runs |g:rustfmt_command| on the current buffer. If - |g:rustfmt_options| is set then those will be passed to the - executable. + When N is given, adjust the size of the new window to N lines + or columns. - If |g:rustfmt_fail_silently| is 0 (the default) then it - will populate the |location-list| with the errors from - |g:rustfmt_command|. If |g:rustfmt_fail_silently| is set to 1 - then it will not populate the |location-list|. + When ! is given, runs all tests regardless of current cursor + position. -:RustFmtRange *:RustFmtRange* - Runs |g:rustfmt_command| with selected range. See - |:RustFmt| for any other information. + When [options] is given, it is passed to "cargo" command + arguments. -============================================================================== -MAPPINGS *rust-mappings* + When the current buffer is outside cargo project, the command + runs `rustc --test` command instead of "cargo test" as + fallback. All tests are run regardless of adding ! since there + is no way to run specific test function with rustc. [options] + is passed to `rustc` command arguments in the case. -This plugin defines mappings for |[[| and |]]| to support hanging indents. + Takes optional modifiers (see |<mods>|): >vim + :tab RustTest + :belowright 16RustTest + :leftabove vert 80RustTest +< +rust.vim Debugging ~ -It also has a few other mappings: +:RustInfo *:RustInfo* + Emits debugging info of the Vim Rust plugin. - *rust_<D-r>* -<D-r> Executes |:RustRun| with no arguments. - Note: This binding is only available in MacVim. +:RustInfoToClipboard *:RustInfoClipboard* + Saves debugging info of the Vim Rust plugin to the default + register. - *rust_<D-R>* -<D-R> Populates the command line with |:RustRun|! using the - arguments given to the last invocation, but does not - execute it. - Note: This binding is only available in MacVim. +:RustInfoToFile [filename] *:RustInfoToFile* + Saves debugging info of the Vim Rust plugin to the given file, + overwriting it. ============================================================================== - vim:tw=78:sw=4:ts=8:noet:ft=help:norl: +MAPPINGS *rust-mappings* + +This plugin defines mappings for |[[| and |]]| to support hanging indents. + + +vim:tw=78:sw=4:noet:ts=8:ft=help:norl: diff --git a/runtime/doc/ft_sql.txt b/runtime/doc/ft_sql.txt index 21a244e67a..68e26d2a5b 100644 --- a/runtime/doc/ft_sql.txt +++ b/runtime/doc/ft_sql.txt @@ -728,7 +728,7 @@ You can create as many additional key maps as you like. Generally, the maps will be specifying different syntax highlight groups. If you do not wish the default maps created or the key choices do not work on -your platform (often a case on *nix) you define the following variable in +your platform (often a case on unix) you define the following variable in your |init.vim|: > let g:omni_sql_no_default_maps = 1 @@ -738,7 +738,7 @@ which allows you to make customizations without changing the files that are included with the Vim distribution. If you wish to customize the maps create an after/ftplugin/sql.vim (see |after-directory|) and place the same maps from the ftplugin/sql.vim in it using your own key strokes. <C-C> was -chosen since it will work on both Windows and *nix platforms. On the windows +chosen since it will work on both Windows and unix platforms. On the windows platform you can also use <C-Space> or ALT keys. diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 1fce9fa491..bf62dba539 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -33,7 +33,7 @@ Example: this sets "g:gui" to the value of the UI's "rgb" field: > remembered until the window is opened. The position is adjusted to make the window fit on the screen (if possible). - *:win* *:winsize* *E465* + *:wi* *:win* *:winsize* *E465* :win[size] {width} {height} Set the window height to {width} by {height} characters. Obsolete, use ":set lines=11 columns=22". @@ -466,12 +466,11 @@ If no argument is given after :menu at all, then ALL menu items are shown for the appropriate mode (e.g., Command-line mode for :cmenu). Special characters in the list, just before the rhs: -* The menu was defined with "nore" to disallow remapping. -& The menu was defined with "<script>" to allow remapping script-local - mappings only. -s The menu was defined with "<silent>" to avoid showing what it is - mapped to when triggered. -- The menu was disabled. +• * Menu was defined with "nore" to disallow remapping. +• & Menu was defined with "<script>" to allow remapping script-local mappings. +• s Menu was defined with "<silent>" to avoid showing what it is mapped to + when triggered. +• - Menu was disabled. Note that hitting <Tab> while entering a menu name after a menu command may be used to complete the name of the menu item. diff --git a/runtime/doc/hebrew.txt b/runtime/doc/hebrew.txt index 76266d777f..e38385e13a 100644 --- a/runtime/doc/hebrew.txt +++ b/runtime/doc/hebrew.txt @@ -30,17 +30,10 @@ Details + 'rightleft' ('rl') sets window orientation to right-to-left. This means that the logical text 'ABC' will be displayed as 'CBA', and will start drawing at the right edge of the window, not the left edge. - + 'hkmap' ('hk') sets keyboard mapping to Hebrew, in insert/replace modes. - + 'aleph' ('al'), numeric, holds the decimal code of Aleph, for keyboard - mapping. - + 'hkmapp' ('hkp') sets keyboard mapping to "phonetic hebrew" - - NOTE: these three ('hkmap', 'hkmapp' and 'aleph') are obsolete. You should - use ":set keymap=hebrewp" instead. - - + 'delcombine' ('deco'), boolean, if editing UTF-8 encoded Hebrew, allows - one to remove the niqud or te`amim by pressing 'x' on a character (with - associated niqud). + + 'keymap' ('kmp') sets keyboard mapping. use values "hebrew" or "heprewp" + (the latter option enables phonetic mapping) + + 'delcombine' ('deco'), boolean, allows one to remove the niqud or + te`amim by pressing 'x' on a character (with associated niqud). + 'rightleftcmd' ('rlc') makes the command-prompt for searches show up on the right side. It only takes effect if the window is 'rightleft'. @@ -62,10 +55,10 @@ Details + CTRL-_ in insert/replace modes toggles 'revins' and 'hkmap' as follows: - When in rightleft window, 'revins' and 'nohkmap' are toggled, since + When in rightleft window, 'revins' is toggled, since English will likely be inserted in this case. - When in norightleft window, 'revins' 'hkmap' are toggled, since Hebrew + When in norightleft window, 'revins' is toggled, since Hebrew will likely be inserted in this case. CTRL-_ moves the cursor to the end of the typed text. diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index 07f898f99c..b8526b55e9 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -100,12 +100,12 @@ ADVANCED EDITING ------------------------------------------------------------------------------ API (EXTENSIBILITY/SCRIPTING/PLUGINS) -|api| Nvim API via RPC, Lua and VimL +|api| Nvim API via RPC, Lua and Vimscript |ui| Nvim UI protocol |lua-guide| Nvim Lua guide |lua| Lua API |luaref| Lua reference manual -|luvref| Luv (|vim.loop|) reference manual +|luvref| Luv (|vim.uv|) reference manual |autocmd| Event handlers |job-control| Spawn and control multiple processes |channel| Nvim asynchronous IO @@ -120,15 +120,15 @@ PROGRAMMING LANGUAGE SUPPORT |lsp| Language Server Protocol (LSP) |diagnostic-api| Diagnostic framework |treesitter| Incremental syntax parsing -|indent.txt| automatic indenting for C and other languages +|indent.txt| automatic indenting for C and other languages |syntax| syntax highlighting |filetype| Settings for specific types of files |quickfix| Commands for a quick edit-compile-fix cycle -|ft_ada.txt| Ada filetype plugin -|ft_ps1.txt| PowerShell filetype plugin -|ft_raku.txt| Raku filetype plugin -|ft_rust.txt| Rust filetype plugin -|ft_sql.txt| SQL filetype plugin +|ft_ada.txt| Ada filetype plugin +|ft_ps1.txt| PowerShell filetype plugin +|ft_raku.txt| Raku filetype plugin +|ft_rust.txt| Rust filetype plugin +|ft_sql.txt| SQL filetype plugin ------------------------------------------------------------------------------ UI @@ -169,19 +169,19 @@ DEVELOPING NVIM |dev-style| Development style guidelines |debug.txt| Debugging Vim itself - *standard-plugin-list* Standard plugins ~ -|matchit.txt| Extended |%| matching -|pi_gzip.txt| Reading and writing compressed files -|pi_health.txt| Healthcheck framework -|pi_msgpack.txt| msgpack utilities -|pi_netrw.txt| Reading and writing files over a network -|pi_paren.txt| Highlight matching parens -|pi_spec.txt| Filetype plugin to work with rpm spec files -|pi_tar.txt| Tar file explorer -|pi_zip.txt| Zip archive explorer - -LOCAL ADDITIONS: *local-additions* + *standard-plugin-list* +|pi_gzip.txt| Reading and writing compressed files +|pi_health.txt| Healthcheck framework +|pi_msgpack.txt| msgpack utilities +|pi_netrw.txt| Reading and writing files over a network +|pi_paren.txt| Highlight matching parens +|pi_spec.txt| Filetype plugin to work with rpm spec files +|pi_tar.txt| Tar file explorer +|pi_zip.txt| Zip archive explorer + +Local additions ~ + *local-additions* ------------------------------------------------------------------------------ *bars* Bars example diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt index da307dd241..efcc6afae9 100644 --- a/runtime/doc/helphelp.txt +++ b/runtime/doc/helphelp.txt @@ -167,7 +167,7 @@ The initial height of the help window can be set with the 'helpheight' option *help-buffer-options* When the help buffer is created, several local options are set to make sure the help text is displayed as it was intended: - 'iskeyword' nearly all ASCII chars except ' ', '*', '"' and '|' + 'iskeyword' nearly all ASCII chars except ' ', "*", '"' and '|' 'foldmethod' "manual" 'tabstop' 8 'arabic' off @@ -317,9 +317,9 @@ standard Vim help files, except for the first line. If you are writing a new help file it's best to copy one of the existing files and use it as a template. -The first line in a help file should have the following format: +The first line in a help file should have the following format: > -*plugin_name.txt* {short description of the plugin} + *plugin_name.txt* {short description of the plugin} The first field is a help tag where ":help plugin_name" will jump to. The remainder of the line, after a Tab, describes the plugin purpose in a short @@ -357,10 +357,11 @@ parameter, surround it in backticks, eg. `~/.path/to/init.vim`. HIGHLIGHTING -To define a column heading, use a tilde character at the end of the line. -This will highlight the column heading in a different color. E.g. +To define a column heading, use a tilde character at the end of the line, +preceded by a space. This will highlight the column heading in a different +color. E.g. -Column heading~ +Column heading ~ To separate sections in a help file, place a series of '=' characters in a line starting from the first column. The section separator line is highlighted @@ -383,8 +384,8 @@ The following are highlighted differently in a Vim help file: The word "Note", "Notes" and similar automagically receive distinctive highlighting. So do these: - *Todo something to do - *Error something wrong + Todo something to do + Error something wrong You can find the details in $VIMRUNTIME/syntax/help.vim diff --git a/runtime/doc/if_perl.txt b/runtime/doc/if_perl.txt index 3787ca69ba..1fa96e2657 100644 --- a/runtime/doc/if_perl.txt +++ b/runtime/doc/if_perl.txt @@ -19,7 +19,7 @@ See |provider-perl| for more information. working: > :perl print "Hello" -:[range]perl << [endmarker] +:[range]perl << [trim] [{endmarker}] {script} {endmarker} Execute perl script {script}. @@ -108,7 +108,7 @@ to the next. ============================================================================== 2. The VIM module *perl-vim* -Perl code gets all of its access to Neovim via the "VIM" module. +Perl code gets all of its access to Nvim via the "VIM" module. Overview > print "Hello" # displays a message @@ -116,7 +116,7 @@ Overview > VIM::SetOption("ai") # sets a vim option $nbuf = VIM::Buffers() # returns the number of buffers @buflist = VIM::Buffers() # returns array of all buffers - $mybuf = (VIM::Buffers('a.c'))[0] # returns buffer object for 'a.c' + $mybuf = (VIM::Buffers('a.c'))[0] # returns buffer object for 'a.c' @winlist = VIM::Windows() # returns array of all windows $nwin = VIM::Windows() # returns the number of windows ($success, $v) = VIM::Eval('&path') # $v: option 'path', $success: 1 diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt index 4c184ddf94..0836ec54d8 100644 --- a/runtime/doc/if_pyth.txt +++ b/runtime/doc/if_pyth.txt @@ -17,26 +17,25 @@ Commands *python-commands* :[range]py[thon] {stmt} Execute Python statement {stmt}. A simple check if the `:python` command is working: >vim - :python print "Hello" + :python print("Hello") -:[range]py[thon] << [endmarker] +:[range]py[thon] << [trim] [{endmarker}] {script} {endmarker} Execute Python script {script}. Useful for including python code in Vim scripts. Requires Python, see |script-here|. -The {endmarker} below the {script} must NOT be preceded by any white space. - If [endmarker] is omitted from after the "<<", a dot '.' must be used after -{script}, like for the |:append| and |:insert| commands. +{script}, like for the |:append| and |:insert| commands. Refer to +|:let-heredoc| for more information. Example: >vim function! IcecreamInitialize() python << EOF class StrawberryIcecream: def __call__(self): - print 'EAT ME' + print('EAT ME') EOF endfunction @@ -101,11 +100,9 @@ To pass arguments you need to set sys.argv[] explicitly. Example: >vim Here are some examples *python-examples* >vim - :python from vim import * - :python from string import upper - :python current.line = upper(current.line) - :python print "Hello" + :python current.line = str.upper(current.line) + :python print("Hello") :python str = current.buffer[42] Note that changes (such as the "import" statements) persist from one command @@ -113,26 +110,16 @@ to the next, just like the Python REPL. *script-here* When using a script language in-line, you might want to skip this when the -language isn't supported. Note that this mechanism doesn't work: +language isn't supported. >vim if has('python') python << EOF - this will NOT work! + print("python works") EOF endif - -Instead, put the Python command in a function and call that function: ->vim - if has('python') - function DefPython() - python << EOF - this works - EOF - endfunction - call DefPython() - endif - -Note that "EOF" must be at the start of the line. +< +Note that "EOF" must be at the start of the line without preceding white +space. ============================================================================== The vim module *python-vim* @@ -144,7 +131,7 @@ module before using it: >vim :python import vim Overview >vim - :py print "Hello" # displays a message + :py print("Hello") # displays a message :py vim.command(cmd) # execute an Ex command :py w = vim.windows[n] # gets window "n" :py cw = vim.current.window # gets the current window @@ -176,10 +163,6 @@ vim.command(str) *python-command* # Note the use of single quotes to delimit a string containing # double quotes normal('"a2dd"aP') -< *E659* - The ":python" command cannot be used recursively with Python 2.2 and - older. This only works with Python 2.3 and later: >vim - :py vim.command("python print 'Hello again Python'") vim.eval(str) *python-eval* Evaluates the expression str using the vim internal expression @@ -191,8 +174,8 @@ vim.eval(str) *python-eval* Examples: >vim :py text_width = vim.eval("&tw") :py str = vim.eval("12+12") # NB result is a string! Use - # string.atoi() to convert to - # a number. + # int() to convert to a + # number. vim.strwidth(str) *python-strwidth* Like |strwidth()|: returns number of display cells str occupies, tab @@ -204,8 +187,8 @@ vim.foreach_rtp(callable) *python-foreach_rtp* are no longer paths. If stopped in case callable returned non-None, vim.foreach_rtp function returns the value returned by callable. -vim.chdir(*args, **kwargs) *python-chdir* -vim.fchdir(*args, **kwargs) *python-fchdir* +`vim.chdir(*args, **kwargs)` *python-chdir* +`vim.fchdir(*args, **kwargs)` *python-fchdir* Run os.chdir or os.fchdir, then all appropriate vim stuff. Note: you should not use these functions directly, use os.chdir and os.fchdir instead. Behavior of vim.fchdir is undefined in case @@ -468,7 +451,7 @@ A trailing '\n' is allowed and ignored, so that you can do: >vim Buffer object type is available using "Buffer" attribute of vim module. Examples (assume b is the current buffer) >vim - :py print b.name # write the buffer file name + :py print(b.name) # write the buffer file name :py b[0] = "hello!!!" # replace the top line :py b[:] = None # delete the whole buffer :py del b[:] # delete the whole buffer @@ -592,17 +575,17 @@ Python 3 *python3* As Python 3 is the only supported version in Nvim, "python" is synonymous with "python3" in the current version. However, code that aims to support older -versions of Neovim, as well as Vim, should prefer to use "python3" -variants explicitly if Python 3 is required. +versions of Nvim, as well as Vim, should prefer to use "python3" variants +explicitly if Python 3 is required. *:py3* *:python3* :[range]py3 {stmt} -:[range]py3 << [endmarker] +:[range]py3 << [trim] [{endmarker}] {script} {endmarker} :[range]python3 {stmt} -:[range]python3 << [endmarker] +:[range]python3 << [trim] [{endmarker}] {script} {endmarker} The `:py3` and `:python3` commands work similar to `:python`. A @@ -629,7 +612,7 @@ You can test if Python is available with: >vim if has('pythonx') echo 'there is Python' endif - if has('python3') + if has('python3') echo 'there is Python 3.x' endif @@ -652,7 +635,7 @@ To see what version of Python is being used: >vim :pyx print(sys.version) < *:pyxfile* *python_x-special-comments* -`:pyxfile` works the same as `:py3file`. +`:pyxfile` works the same as `:py3file`. *:pyxdo* `:pyxdo` works the same as `:py3do`. diff --git a/runtime/doc/if_ruby.txt b/runtime/doc/if_ruby.txt index d88f59eb73..a5aaac1a5f 100644 --- a/runtime/doc/if_ruby.txt +++ b/runtime/doc/if_ruby.txt @@ -19,15 +19,15 @@ downloading Ruby there. :rub[y] {cmd} Execute Ruby command {cmd}. A command to try it out: > :ruby print "Hello" -:rub[y] << [endmarker] +:rub[y] << [trim] [{endmarker}] {script} {endmarker} Execute Ruby script {script}. - The {endmarker} after {script} must NOT be preceded by - any white space. If [endmarker] is omitted, it defaults to a dot '.' - like for the |:append| and |:insert| commands. + like for the |:append| and |:insert| commands. Refer + to |:let-heredoc| for more information. + This form of the |:ruby| command is mainly useful for including ruby code in vim scripts. diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt index f3e196b426..853facdaa0 100644 --- a/runtime/doc/indent.txt +++ b/runtime/doc/indent.txt @@ -112,7 +112,7 @@ e Reindent a line that starts with "else" when you type the second 'e'. =~word Like =word, but ignore case. If you really want to reindent when you type 'o', 'O', 'e', '0', '<', '>', -'*', ':' or '!', use "<o>", "<O>", "<e>", "<0>", "<<>", "<>>", "<*>", "<:>" or +"*", ':' or '!', use "<o>", "<O>", "<e>", "<0>", "<<>", "<>>", "<*>", "<:>" or "<!>", respectively, for those keys. For an emacs-style indent mode where lines aren't indented every time you @@ -553,9 +553,9 @@ The examples below assume a 'shiftwidth' of 4. 20 lines). *cino-star* - *N Vim searches for unclosed comments at most N lines away. This + `*N` Vim searches for unclosed comments at most N lines away. This limits the time needed to search for the start of a comment. - If your /* */ comments stop indenting after N lines this is the + If your `/* */` comments stop indenting after N lines this is the value you will want to change. (default 70 lines). @@ -574,7 +574,7 @@ The examples below assume a 'shiftwidth' of 4. them like every other preprocessor directive. -The defaults, spelled out in full, are: +The defaults, spelled out in full, are: > cinoptions=>s,e0,n0,f0,{0,}0,^0,L-1,:s,=s,l0,b0,gs,hs,N0,E0,ps,ts,is,+s, c3,C0,/0,(2s,us,U0,w0,W0,k0,m0,j0,J0,)20,*70,#0,P0 @@ -1060,19 +1060,19 @@ be configured by setting the following keys in the |Dictionary| b:sh_indent_defaults to a specific amount or to a |Funcref| that references a function that will return the amount desired: -b:sh_indent_options['default'] Default amount of indent. +b:sh_indent_options["default"] Default amount of indent. -b:sh_indent_options['continuation-line'] +b:sh_indent_options["continuation-line"] Amount of indent to add to a continued line. -b:sh_indent_options['case-labels'] +b:sh_indent_options["case-labels"] Amount of indent to add for case labels. (not actually implemented) -b:sh_indent_options['case-statements'] +b:sh_indent_options["case-statements"] Amount of indent to add for case statements. -b:sh_indent_options['case-breaks'] +b:sh_indent_options["case-breaks"] Amount of indent to add (or more likely remove) for case breaks. diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index a6aa036b55..75b12fece2 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -220,7 +220,7 @@ tag char note action in Normal mode ~ |CTRL-\_CTRL-N| CTRL-\ CTRL-N go to Normal mode (no-op) |CTRL-\_CTRL-G| CTRL-\ CTRL-G go to Normal mode (no-op) CTRL-\ a - z reserved for extensions - CTRL-\ others not used + CTRL-\ others not used |CTRL-]| CTRL-] :ta to ident under cursor |CTRL-^| CTRL-^ edit Nth alternate file (equivalent to ":e #N") @@ -233,7 +233,7 @@ tag char note action in Normal mode ~ 2 filter Nmove text through the {filter} command |!!| !!{filter} 2 filter N lines through the {filter} command -|quote| "{register} use {register} for next delete, yank or put +|quote| "{register} use {register} for next delete, yank or put ({.%#:} only work with put) |#| # 1 search backward for the Nth occurrence of the ident under the cursor @@ -475,7 +475,7 @@ tag command action in op-pending and Visual mode ~ |v_a)| a) same as ab |v_a<| a< "a <>" from '<' to the matching '>' |v_a>| a> same as a< -|v_aB| aB "a Block" from "[{" to "]}" (with brackets) +|v_aB| aB "a Block" from `[{` to `]}` (with brackets) |v_aW| aW "a WORD" (with white space) |v_a[| a[ "a []" from '[' to the matching ']' |v_a]| a] same as a[ @@ -493,7 +493,7 @@ tag command action in op-pending and Visual mode ~ |v_i)| i) same as ib |v_i<| i< "inner <>" from '<' to the matching '>' |v_i>| i> same as i< -|v_iB| iB "inner Block" from "[{" and "]}" +|v_iB| iB "inner Block" from `[{` and `]}` |v_iW| iW "inner WORD" |v_i[| i[ "inner []" from '[' to the matching ']' |v_i]| i] same as i[ @@ -1096,6 +1096,22 @@ tag command action in Command-line editing mode ~ |c_<Insert>| <Insert> toggle insert/overstrike mode |c_<LeftMouse>| <LeftMouse> cursor at mouse click +commands in wildmenu mode (see 'wildmenu') + + <Up> move up to parent + <Down> move down to submenu + <Left> select the previous match + <Right> select the next match + <CR> move into submenu when doing menu completion + CTRL-E stop completion and go back to original text + CTRL-Y accept selected match and stop completion + other stop completion and insert the typed character + +commands in wildmenu mode with 'wildoptions' set to "pum" + + <PageUp> select a match several entries back + <PageDown> select a match several entries forward + ============================================================================== 5. Terminal mode *terminal-mode-index* @@ -1110,7 +1126,7 @@ to terminal mode. You found it, Arthur! *holy-grail* ============================================================================== -6. EX commands *ex-commands* *ex-cmd-index* *:index* +6. EX commands *Ex-commands* *ex-cmd-index* *:index* This is a brief but complete listing of all the ":" commands, without mentioning any arguments. The optional part of the command name is inside []. @@ -1159,7 +1175,6 @@ tag command action ~ |:badd| :bad[d] add buffer to the buffer list |:balt| :balt like ":badd" but also set the alternate file |:bdelete| :bd[elete] remove a buffer from the buffer list -|:behave| :be[have] set mouse and selection behavior |:belowright| :bel[owright] make split window appear right or below |:bfirst| :bf[irst] go to first buffer in the buffer list |:blast| :bl[ast] go to last buffer in the buffer list @@ -1289,6 +1304,7 @@ tag command action ~ |:execute| :exe[cute] execute result of expressions |:exit| :exi[t] same as ":xit" |:exusage| :exu[sage] overview of Ex commands +|:fclose| :fc[lose] close floating window |:file| :f[ile] show or set the current file name |:files| :files list all files in the buffer list |:filetype| :filet[ype] switch file type detection on/off diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index e608b431f2..ce2ec36ca3 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -114,12 +114,16 @@ CTRL-R {register} *i_CTRL-R* the last delete or yank '%' the current file name '#' the alternate file name - '*' the clipboard contents (X11: primary selection) + "*" the clipboard contents (X11: primary selection) '+' the clipboard contents '/' the last search pattern ':' the last command-line '.' the last inserted text + *i_CTRL-R_-* '-' the last small (less than a line) delete + register. This is repeatable using |.| since + it remembers the register to put instead of + the literal text to insert. *i_CTRL-R_=* '=' the expression register: you are prompted to enter an expression (see |expression|) @@ -221,11 +225,11 @@ CTRL-Y Insert the character which is above the cursor. able to copy characters from a long line. *i_CTRL-_* -CTRL-_ Switch between languages, as follows: - - When in a rightleft window, revins and nohkmap are toggled, +CTRL-_ Switch between insert direction, by toggling 'revins', as follows: + - When in a rightleft window, 'revins' is toggled, since English will likely be inserted in this case. - - When in a norightleft window, revins and hkmap are toggled, - since Hebrew will likely be inserted in this case. + - When in a norightleft window, 'revins' is toggled, + since a rightleft language will likely be inserted in this case. CTRL-_ moves the cursor to the end of the typed text. @@ -1081,6 +1085,26 @@ Stop completion *compl-stop* CTRL-X CTRL-Z Stop completion without changing the text. +AUTO-COMPLETION *compl-autocomplete* + +To get basic "autocompletion" without installing a plugin, try this script: >lua + + local triggers = {"."} + vim.api.nvim_create_autocmd("InsertCharPre", { + buffer = vim.api.nvim_get_current_buf(), + callback = function() + if vim.fn.pumvisible() == 1 or vim.fn.state("m") == "m" then + return + end + local char = vim.v.char + if vim.list_contains(triggers, char) then + local key = vim.keycode("<C-x><C-n>") + vim.api.nvim_feedkeys(key, "m", false) + end + end + }) +< + FUNCTIONS FOR FINDING COMPLETIONS *complete-functions* This applies to 'completefunc', 'thesaurusfunc' and 'omnifunc'. @@ -1101,8 +1125,8 @@ cursor column will be replaced with the matches. If the returned value is larger than the cursor column, the cursor column is used. Negative return values: - -2 To cancel silently and stay in completion mode. - -3 To cancel silently and leave completion mode. + -2 To cancel silently and stay in completion mode. + -3 To cancel silently and leave completion mode. Another negative value: completion starts at the cursor column On the second invocation the arguments are: @@ -1154,7 +1178,7 @@ items: item with the same word is already present. empty when non-zero this match will be added even when it is an empty string - user_data custom data which is associated with the item and + user_data custom data which is associated with the item and available in |v:completed_item|; it can be any type; defaults to an empty string @@ -1392,7 +1416,7 @@ other versions of HTML. Features: - after "<" complete tag name depending on context (no div suggestion inside of an a tag); '/>' indicates empty tags - inside of tag complete proper attributes (no width attribute for an a tag); - show also type of attribute; '*' indicates required attributes + show also type of attribute; "*" indicates required attributes - when attribute has limited number of possible values help to complete them - complete names of entities - complete values of "class" and "id" attributes with data obtained from diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index 6bf6850ccf..85115fc22b 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -22,8 +22,7 @@ is not located in the default place. You can jump to subjects like with tags: Use CTRL-] to jump to a subject under the cursor, use CTRL-T to jump back. *pronounce* -Vim is pronounced as one word, like Jim. So Nvim is N-Jim, which sounds like -"Ninja". Starting Nvim is like performing a roundhouse kick. +Vim is pronounced as one word, like Jim. So Nvim is "En-Vim", two syllables. This manual is a reference for all Nvim editor and API features. It is not an introduction; instead for beginners, there is a hands-on |tutor| and a user @@ -83,14 +82,14 @@ For the most recent information about sponsoring look on the Vim web site: https://www.vim.org/sponsor/ -Neovim development is funded separately from Vim: +Nvim development is funded separately from Vim: https://neovim.io/#sponsor ============================================================================== -Credits *credits* +Credits *credits* -Most of Vim was written by Bram Moolenaar <Bram@vim.org>. +Most of Vim was written by Bram Moolenaar <Bram@vim.org> |Bram-Moolenaar|. Parts of the documentation come from several Vi manuals, written by: W.N. Joy @@ -121,7 +120,7 @@ Vim would never have become what it is now, without the help of these people! Eric Fischer Mac port, 'cindent', and other improvements Benji Fisher Answering lots of user questions Bill Foster Athena GUI port (later removed) - Google Lets me work on Vim one day a week + Google Let Bram work on Vim one day a week Loic Grenie xvim (ideas for multi windows version) Sven Guckes Vim promoter and previous WWW page maintainer Darren Hiebert Exuberant ctags @@ -194,6 +193,19 @@ Elvis Another Vi clone, made by Steve Kirkendall. Very compact but isn't Vim Nvim is based on Vim. https://www.vim.org/ ============================================================================== +Bram Moolenaar *Bram* *Moolenaar* *Bram-Moolenaar* *brammool* + +Nvim is a fork of the Vim ("Vi IMproved") text editor, which was originally +developed by Bram Moolenaar. Searching his name within the source code of +Nvim will reveal just how much of his work still remains in Nvim. +On August 3, 2023, he passed away at the age of 62. If Vim or Nvim have been +of use to you in your life, please read |Uganda| and consider honoring his +memory however you may see fit. + +Obituary Articles: https://github.com/vim/vim/discussions/12742 +Say Farewell: https://github.com/vim/vim/discussions/12737 + +============================================================================== Notation *notation* When syntax highlighting is used to read this, text that is not typed @@ -358,7 +370,7 @@ notation meaning equivalent decimal value(s) ~ <kOrigin> keypad origin (middle) *keypad-origin* <kPageUp> keypad page-up (upper right) *keypad-page-up* <kPageDown> keypad page-down (lower right) *keypad-page-down* -<kDel> keypad delete *keypad-delete* +<kDel> keypad delete *keypad-delete* <kPlus> keypad + *keypad-plus* <kMinus> keypad - *keypad-minus* <kMultiply> keypad * *keypad-multiply* @@ -372,6 +384,7 @@ notation meaning equivalent decimal value(s) ~ <C-…> control-key *control* *ctrl* *<C-* <M-…> alt-key or meta-key *META* *ALT* *<M-* <A-…> same as <M-…> *<A-* +<T-…> meta-key when it's not alt *<T-* <D-…> command-key or "super" key *<D-* ----------------------------------------------------------------------- ~ @@ -382,10 +395,10 @@ Note: - If numlock is on the |TUI| receives plain ASCII values, so mapping <k0>, <k1>, ..., <k9> and <kPoint> will not work. - Nvim supports mapping multibyte chars with modifiers such as `<M-ä>`. Which - combinations actually work depends on the the UI or host terminal. + combinations actually work depends on the UI or host terminal. - When a key is pressed using a meta or alt modifier and no mapping exists for that keypress, Nvim may behave as though <Esc> was pressed before the key. -- It is possible to notate combined modifiers (e.g. <C-A-T> for CTRL-ALT-T), +- It is possible to notate combined modifiers (e.g. <M-C-T> for CTRL-ALT-T), but your terminal must encode the input for that to work. |tui-input| *<>* @@ -517,16 +530,15 @@ CTRL-O in Insert mode you get a beep but you are still in Insert mode, type <Esc> again. *i_esc* - TO mode ~ - Normal Visual Select Insert Replace Cmd-line Ex ~ -FROM mode ~ -Normal v V ^V `*4` *1 R gR : / ? ! Q -Visual `*2` ^G c C -- : -- -Select `*5` ^O ^G `*6` -- -- -- -Insert <Esc> -- -- <Insert> -- -- -Replace <Esc> -- -- <Insert> -- -- -Command-line `*3` -- -- :start -- -- -Ex :vi -- -- -- -- -- + FROM mode TO mode ~ + Normal Visual Select Insert Replace Cmd-line Ex > + Normal v V ^V *4 *1 R gR : / ? ! Q + Visual *2 ^G c C -- : -- + Select *5 ^O ^G *6 -- -- -- + Insert <Esc> -- -- <Insert> -- -- + Replace <Esc> -- -- <Insert> -- -- + Command-line `*3` -- -- :start -- -- + Ex :vi -- -- -- -- -- -- not possible diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt index 37a4e2ebb1..d99c76ab22 100644 --- a/runtime/doc/job_control.txt +++ b/runtime/doc/job_control.txt @@ -134,9 +134,6 @@ To send data to the job's stdin, use |chansend()|: >vim :call chansend(job1, "invalid-command\n") :call chansend(job1, "exit\n") < -A job may be killed with |jobstop()|: >vim - :call jobstop(job1) -< A job may be killed at any time with the |jobstop()| function: >vim :call jobstop(job1) diff --git a/runtime/doc/lsp-extension.txt b/runtime/doc/lsp-extension.txt deleted file mode 100644 index fe72e9eb18..0000000000 --- a/runtime/doc/lsp-extension.txt +++ /dev/null @@ -1,129 +0,0 @@ -*lsp-extension.txt* LSP Extension - - NVIM REFERENCE MANUAL - - -The `vim.lsp` Lua module is a framework for building LSP plugins. - - 1. Start with |vim.lsp.start_client()| and |vim.lsp.buf_attach_client()|. - 2. Peek at the API: >vim - :lua print(vim.inspect(vim.lsp)) -< 3. See |lsp-extension-example| for a full example. - -================================================================================ -LSP EXAMPLE *lsp-extension-example* - -This example is for plugin authors or users who want a lot of control. If you -are just getting started see |lsp-quickstart|. - -For more advanced configurations where just filtering by filetype isn't -sufficient, you can use the `vim.lsp.start_client()` and -`vim.lsp.buf_attach_client()` commands to easily customize the configuration -however you please. For example, if you want to do your own filtering, or -start a new LSP client based on the root directory for working with multiple -projects in a single session. To illustrate, the following is a fully working -Lua example. - -The example will: -1. Check for each new buffer whether or not we want to start an LSP client. -2. Try to find a root directory by ascending from the buffer's path. -3. Create a new LSP for that root directory if one doesn't exist. -4. Attach the buffer to the client for that root directory. - ->lua - -- Some path manipulation utilities - local function is_dir(filename) - local stat = vim.loop.fs_stat(filename) - return stat and stat.type == 'directory' or false - end - - local path_sep = vim.loop.os_uname().sysname == "Windows" and "\\" or "/" - -- Assumes filepath is a file. - local function dirname(filepath) - local is_changed = false - local result = filepath:gsub(path_sep.."([^"..path_sep.."]+)$", function() - is_changed = true - return "" - end) - return result, is_changed - end - - local function path_join(...) - return table.concat(vim.tbl_flatten {...}, path_sep) - end - - -- Ascend the buffer's path until we find the rootdir. - -- is_root_path is a function which returns bool - local function buffer_find_root_dir(bufnr, is_root_path) - local bufname = vim.api.nvim_buf_get_name(bufnr) - if vim.fn.filereadable(bufname) == 0 then - return nil - end - local dir = bufname - -- Just in case our algorithm is buggy, don't infinite loop. - for _ = 1, 100 do - local did_change - dir, did_change = dirname(dir) - if is_root_path(dir, bufname) then - return dir, bufname - end - -- If we can't ascend further, then stop looking. - if not did_change then - return nil - end - end - end - - -- A table to store our root_dir to client_id lookup. We want one LSP per - -- root directory, and this is how we assert that. - local javascript_lsps = {} - -- Which filetypes we want to consider. - local javascript_filetypes = { - ["javascript.jsx"] = true; - ["javascript"] = true; - ["typescript"] = true; - ["typescript.jsx"] = true; - } - - -- Create a template configuration for a server to start, minus the root_dir - -- which we will specify later. - local javascript_lsp_config = { - name = "javascript"; - cmd = { path_join(os.getenv("JAVASCRIPT_LANGUAGE_SERVER_DIRECTORY"), "lib", "language-server-stdio.js") }; - } - - -- This needs to be global so that we can call it from the autocmd. - function check_start_javascript_lsp() - local bufnr = vim.api.nvim_get_current_buf() - -- Filter which files we are considering. - if not javascript_filetypes[vim.api.nvim_buf_get_option(bufnr, 'filetype')] then - return - end - -- Try to find our root directory. We will define this as a directory which contains - -- node_modules. Another choice would be to check for `package.json`, or for `.git`. - local root_dir = buffer_find_root_dir(bufnr, function(dir) - return is_dir(path_join(dir, 'node_modules')) - -- return vim.fn.filereadable(path_join(dir, 'package.json')) == 1 - -- return is_dir(path_join(dir, '.git')) - end) - -- We couldn't find a root directory, so ignore this file. - if not root_dir then return end - - -- Check if we have a client already or start and store it. - local client_id = javascript_lsps[root_dir] - if not client_id then - local new_config = vim.tbl_extend("error", javascript_lsp_config, { - root_dir = root_dir; - }) - client_id = vim.lsp.start_client(new_config) - javascript_lsps[root_dir] = client_id - end - -- Finally, attach to the buffer to track changes. This will do nothing if we - -- are already attached. - vim.lsp.buf_attach_client(bufnr, client_id) - end - - vim.api.nvim_command [[autocmd BufReadPost * lua check_start_javascript_lsp()]] -< - - vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 215515a2d9..5e97628f42 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -24,57 +24,62 @@ QUICKSTART *lsp-quickstart* Nvim provides an LSP client, but the servers are provided by third parties. Follow these steps to get LSP features: - 1. Install language servers using your package manager or by - following the upstream installation instruction. +1. Install language servers using your package manager or by following the + upstream installation instruction. You can find language servers here: + https://microsoft.github.io/language-server-protocol/implementors/servers/ - A list of language servers is available at: +2. Configure the LSP client per language server. See |vim.lsp.start()| or use + this minimal example as a guide: >lua - https://microsoft.github.io/language-server-protocol/implementors/servers/ - - 2. Configure the LSP client per language server. - A minimal example: ->lua vim.lsp.start({ name = 'my-server-name', cmd = {'name-of-language-server-executable'}, root_dir = vim.fs.dirname(vim.fs.find({'setup.py', 'pyproject.toml'}, { upward = true })[1]), }) < - See |vim.lsp.start()| for details. +3. Check that the server attached to the buffer: > + :lua =vim.lsp.get_clients() - 3. Configure keymaps and autocmds to utilize LSP features. - See |lsp-config|. +4. Configure keymaps and autocmds to use LSP features. See |lsp-config|. *lsp-config* - -Starting a LSP client will automatically report diagnostics via -|vim.diagnostic|. Read |vim.diagnostic.config()| to learn how to customize the -display. - -It also sets some buffer options if the options are otherwise empty and if the -language server supports the functionality. - -- 'omnifunc' is set to |vim.lsp.omnifunc()|. This allows to trigger completion - using |i_CTRL-X_CTRL-O| + *lsp-defaults* +When the LSP client starts it enables diagnostics |vim.diagnostic| (see +|vim.diagnostic.config()| to customize). It also sets various default options, +listed below, if (1) the language server supports the functionality and (2) +the options are empty or were set by the builtin runtime (ftplugin) files. The +options are not restored when the LSP client is stopped or detached. + +- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger + completion. - 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|, |CTRL-W_}| to utilize the language server. -- 'formatexpr' is set to |vim.lsp.formatexpr()| if both 'formatprg' and - 'formatexpr' are empty. This allows to format lines via |gq| if the language - server supports it. +- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via + |gq| if the language server supports it. + - To opt out of this use |gw| instead of gq, or set 'formatexpr' on LspAttach. +- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or + a custom keymap for `K` exists. + + *lsp-defaults-disable* +To override the above defaults, set or unset the options on |LspAttach|: >lua + vim.api.nvim_create_autocmd('LspAttach', { + callback = function(ev) + vim.bo[ev.buf].formatexpr = nil + vim.bo[ev.buf].omnifunc = nil + vim.keymap.del("n", "K", { buffer = ev.buf }) + end, + }) -To use other LSP features like hover, rename, etc. you can setup some -additional keymaps. It's recommended to setup them in a |LspAttach| autocmd to -ensure they're only active if there is a LSP client running. An example: ->lua +To use other LSP features like hover, rename, etc. you can set other keymaps +on |LspAttach|. Example: >lua vim.api.nvim_create_autocmd('LspAttach', { callback = function(args) vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf }) end, }) -< -The most used functions are: +The most common functions are: - |vim.lsp.buf.hover()| - |vim.lsp.buf.format()| @@ -98,11 +103,9 @@ calls behind capability checks: < To learn what capabilities are available you can run the following command in -a buffer with a started LSP client: +a buffer with a started LSP client: >vim ->vim - :lua =vim.lsp.get_active_clients()[1].server_capabilities -< + :lua =vim.lsp.get_clients()[1].server_capabilities Full list of features provided by default can be found in |lsp-buf|. @@ -110,35 +113,28 @@ Full list of features provided by default can be found in |lsp-buf|. FAQ *lsp-faq* - Q: How to force-reload LSP? - A: Stop all clients, then reload the buffer. >vim - - :lua vim.lsp.stop_client(vim.lsp.get_active_clients()) +- A: Stop all clients, then reload the buffer. >vim + :lua vim.lsp.stop_client(vim.lsp.get_clients()) :edit - Q: Why isn't completion working? - A: In the buffer where you want to use LSP, check that 'omnifunc' is set to - "v:lua.vim.lsp.omnifunc": >vim - - :verbose set omnifunc? - -< Some other plugin may be overriding the option. To avoid that, you could - set the option in an |after-directory| ftplugin, e.g. - "after/ftplugin/python.vim". +- A: In the buffer where you want to use LSP, check that 'omnifunc' is set to + "v:lua.vim.lsp.omnifunc": `:verbose set omnifunc?` + - Some other plugin may be overriding the option. To avoid that you could + set the option in an |after-directory| ftplugin, e.g. + "after/ftplugin/python.vim". - Q: How do I run a request synchronously (e.g. for formatting on file save)? - A: Check if the function has an `async` parameter and set the value to - false. - - E.g. code formatting: >vim +- A: Check if the function has an `async` parameter and set the value to + false. E.g. code formatting: >vim " Auto-format *.rs (rust) files prior to saving them " (async = false is the default for format) autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false }) - < *lsp-vs-treesitter* - Q: How do LSP and Treesitter compare? - A: LSP requires a client and language server. The language server uses +- A: LSP requires a client and language server. The language server uses semantic analysis to understand code at a project level. This provides language servers with the ability to rename across files, find definitions in external libraries and more. @@ -161,128 +157,85 @@ The `vim.lsp.buf_…` functions perform operations for all LSP clients attached to the given buffer. |lsp-buf| LSP request/response handlers are implemented as Lua functions (see -|lsp-handler|). The |vim.lsp.handlers| table defines default handlers used -when creating a new client. Keys are LSP method names: >vim - - :lua print(vim.inspect(vim.tbl_keys(vim.lsp.handlers))) -< +|lsp-handler|). *lsp-method* -Methods are the names of requests and notifications as defined by the LSP -specification. These LSP requests/notifications are defined by default: - - callHierarchy/incomingCalls - callHierarchy/outgoingCalls - textDocument/codeAction - textDocument/completion - textDocument/declaration* - textDocument/definition - textDocument/documentHighlight - textDocument/documentSymbol - textDocument/formatting - textDocument/hover - textDocument/implementation* - textDocument/publishDiagnostics - textDocument/rangeFormatting - textDocument/references - textDocument/rename - textDocument/signatureHelp - textDocument/typeDefinition* - window/logMessage - window/showMessage - window/showDocument - window/showMessageRequest - workspace/applyEdit - workspace/symbol - -* NOTE: These are sometimes not implemented by servers. - - *lsp-handler* +Requests and notifications defined by the LSP specification are referred to as +"LSP methods". The Nvim LSP client provides default handlers in the global +|vim.lsp.handlers| table, you can list them with this command: >vim -lsp-handlers are functions with special signatures that are designed to handle -responses and notifications from LSP servers. - -For |lsp-request|, each |lsp-handler| has this signature: > - - function(err, result, ctx, config) + :lua vim.print(vim.tbl_keys(vim.lsp.handlers)) < - Parameters: ~ - {err} (table|nil) - When the language server is unable to complete a - request, a table with information about the error is - sent. Otherwise, it is `nil`. See |lsp-response|. - {result} (Result | Params | nil) - When the language server is able to successfully - complete a request, this contains the `result` key of - the response. See |lsp-response|. - {ctx} (table) - Context describes additional calling state associated - with the handler. It consists of the following key, - value pairs: - - {method} (string) - The |lsp-method| name. - {client_id} (number) - 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. - - Each handler can define its own configuration table - that allows users to customize the behavior of a - particular handler. - - 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: - `{ code, message, data? }` +They are also listed below. Note that handlers depend on server support: they +won't run if your server doesn't support them. + +- callHierarchy/incomingCalls +- callHierarchy/outgoingCalls +- textDocument/codeAction +- textDocument/completion +- textDocument/declaration* +- textDocument/definition +- textDocument/diagnostic +- textDocument/documentHighlight +- textDocument/documentSymbol +- textDocument/formatting +- textDocument/hover +- textDocument/implementation* +- textDocument/inlayHint +- textDocument/publishDiagnostics +- textDocument/rangeFormatting +- textDocument/references +- textDocument/rename +- textDocument/semanticTokens/full +- textDocument/semanticTokens/full/delta +- textDocument/signatureHelp +- textDocument/typeDefinition* +- window/logMessage +- window/showMessage +- window/showDocument +- window/showMessageRequest +- workspace/applyEdit +- workspace/configuration +- workspace/executeCommand +- workspace/inlayHint/refresh +- workspace/symbol +- workspace/workspaceFolders - You can use |vim.lsp.rpc.rpc_response_error()| to create this object. + *lsp-handler* +LSP handlers are functions that handle |lsp-response|s to requests made by Nvim +to the server. (Notifications, as opposed to requests, are fire-and-forget: +there is no response, so they can't be handled. |lsp-notification|) -For |lsp-notification|, each |lsp-handler| has this signature: > +Each response handler has this signature: > - function(err, result, ctx, config) + function(err, result, ctx, config) < Parameters: ~ - {err} (nil) - This is always `nil`. - See |lsp-notification| - {result} (Result) - This contains the `params` key of the notification. - See |lsp-notification| - {ctx} (table) - Context describes additional calling state associated - with the handler. It consists of the following key, - value pairs: - - {method} (string) - The |lsp-method| name. - {client_id} (number) - The ID of the |vim.lsp.client|. - {config} (table) - Configuration for the handler. - - Each handler can define its own configuration table - that allows users to customize the behavior of a - particular handler. - - For an example, see: - |vim.lsp.diagnostic.on_publish_diagnostics()| - - To configure a particular |lsp-handler|, see: - |lsp-handler-configuration| + - {err} (table|nil) Error info dict, or `nil` if the request + completed. + - {result} (Result | Params | nil) `result` key of the |lsp-response| or + `nil` if the request failed. + - {ctx} (table) Table of calling state associated with the + handler, with these keys: + - {method} (string) |lsp-method| name. + - {client_id} (number) |vim.lsp.client| identifier. + - {bufnr} (Buffer) Buffer handle. + - {params} (table|nil) Request parameters table. + - {version} (number) Document version at time of + request. Handlers can compare this to the + current document version to check if the + response is "stale". See also |b:changedtick|. + - {config} (table) Handler-defined configuration table, which allows + users to customize handler behavior. + For an example, see: + |vim.lsp.diagnostic.on_publish_diagnostics()| + To configure a particular |lsp-handler|, see: + |lsp-handler-configuration| Returns: ~ - The |lsp-handler|'s return value will be ignored. + Two values `result, err` where `err` is shaped like an RPC error: > + { code, message, data? } +< You can use |vim.lsp.rpc.rpc_response_error()| to create this object. *lsp-handler-configuration* @@ -355,42 +308,37 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method Handlers can be set by: - Setting a field in vim.lsp.handlers. *vim.lsp.handlers* - vim.lsp.handlers is a global table that contains the default mapping of - |lsp-method| names to |lsp-handlers|. - - To override the handler for the `"textDocument/definition"` method: >lua + vim.lsp.handlers is a global table that contains the default mapping of + |lsp-method| names to |lsp-handlers|. To override the handler for the + `"textDocument/definition"` method: >lua vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition < -- The {handlers} parameter for |vim.lsp.start_client()|. - This will set the |lsp-handler| as the default handler for this server. +- The {handlers} parameter of |vim.lsp.start()|. This sets the default + |lsp-handler| for the server being started. Example: >lua - For example: >lua - - vim.lsp.start_client { + vim.lsp.start { ..., -- Other configuration omitted. handlers = { ["textDocument/definition"] = my_custom_server_definition }, } -- The {handler} parameter for |vim.lsp.buf_request()|. - This will set the |lsp-handler| ONLY for the current request. +- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets + the |lsp-handler| ONLY for the given request(s). Example: >lua - For example: >lua - - vim.lsp.buf_request( + vim.lsp.buf_request_all( 0, "textDocument/definition", - definition_params, - my_request_custom_definition + my_request_params, + my_handler ) < In summary, the |lsp-handler| will be chosen based on the current |lsp-method| in the following order: -1. Handler passed to |vim.lsp.buf_request()|, if any. -2. Handler defined in |vim.lsp.start_client()|, if any. +1. Handler passed to |vim.lsp.buf_request_all()|, if any. +2. Handler defined in |vim.lsp.start()|, if any. 3. Handler defined in |vim.lsp.handlers|, if any. *vim.lsp.log_levels* @@ -411,12 +359,12 @@ name: >lua < *lsp-response* -For the format of the response message, see: - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage +LSP response shape: +https://microsoft.github.io/language-server-protocol/specifications/specification-current/#responseMessage *lsp-notification* -For the format of the notification message, see: - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage +LSP notification shape: +https://microsoft.github.io/language-server-protocol/specifications/specification-current/#notificationMessage *lsp-on-list-handler* @@ -459,6 +407,8 @@ LspReferenceText used for highlighting "text" references LspReferenceRead used for highlighting "read" references *hl-LspReferenceWrite* LspReferenceWrite used for highlighting "write" references + *hl-LspInlayHint* +LspInlayHint used for highlighting inlay hints *lsp-highlight-codelens* @@ -482,13 +432,78 @@ LspSignatureActiveParameter Used to highlight the active parameter in the signature help. See |vim.lsp.handlers.signature_help()|. +------------------------------------------------------------------------------ +LSP SEMANTIC HIGHLIGHTS *lsp-semantic-highlight* + +When available, the LSP client highlights code using |lsp-semantic_tokens|, +which are another way that LSP servers can provide information about source +code. Note that this is in addition to treesitter syntax highlighting; +semantic highlighting does not replace syntax highlighting. + +The server will typically provide one token per identifier in the source code. +The token will have a `type` such as "function" or "variable", and 0 or more +`modifier`s such as "readonly" or "deprecated." The standard types and +modifiers are described here: +https://microsoft.github.io/language-server-protocol/specification/#textDocument_semanticTokens +LSP servers may also use off-spec types and modifiers. + +The LSP client adds one or more highlights for each token. The highlight +groups are derived from the token's type and modifiers: + • `@lsp.type.<type>.<ft>` for the type + • `@lsp.mod.<mod>.<ft>` for each modifier + • `@lsp.typemod.<type>.<mod>.<ft>` for each modifier +Use |:Inspect| to view the highlights for a specific token. Use |:hi| or +|nvim_set_hl()| to change the appearance of semantic highlights: >vim + + hi @lsp.type.function guifg=Yellow " function names are yellow + hi @lsp.type.variable.lua guifg=Green " variables in lua are green + hi @lsp.mod.deprecated gui=strikethrough " deprecated is crossed out + hi @lsp.typemod.function.async guifg=Blue " async functions are blue +< +The value |vim.highlight.priorities|`.semantic_tokens` is the priority of the +`@lsp.type.*` highlights. The `@lsp.mod.*` and `@lsp.typemod.*` highlights +have priorities one and two higher, respectively. + +You can disable semantic highlights by clearing the highlight groups: >lua + + -- Hide semantic highlights for functions + vim.api.nvim_set_hl(0, '@lsp.type.function', {}) + + -- Hide all semantic highlights + for _, group in ipairs(vim.fn.getcompletion("@lsp", "highlight")) do + vim.api.nvim_set_hl(0, group, {}) + end +< +You probably want these inside a |ColorScheme| autocommand. + +Use |LspTokenUpdate| and |vim.lsp.semantic_tokens.highlight_token()| for more +complex highlighting. + +The following groups are linked by default to standard |group-name|s: +> + @lsp.type.class Structure + @lsp.type.decorator Function + @lsp.type.enum Structure + @lsp.type.enumMember Constant + @lsp.type.function Function + @lsp.type.interface Structure + @lsp.type.macro Macro + @lsp.type.method Function + @lsp.type.namespace Structure + @lsp.type.parameter Identifier + @lsp.type.property Identifier + @lsp.type.struct Structure + @lsp.type.type Type + @lsp.type.typeParameter TypeDef + @lsp.type.variable Identifier +< ============================================================================== EVENTS *lsp-events* - *LspAttach* -After an LSP client attaches to a buffer. The |autocmd-pattern| is the -name of the buffer. When used from Lua, the client ID is passed to the -callback in the "data" table. Example: >lua +LspAttach *LspAttach* + After an LSP client attaches to a buffer. The |autocmd-pattern| is the + name of the buffer. When used from Lua, the client ID is passed to the + callback in the "data" table. Example: >lua vim.api.nvim_create_autocmd("LspAttach", { callback = function(args) @@ -503,10 +518,11 @@ callback in the "data" table. Example: >lua end, }) < - *LspDetach* -Just before an LSP client detaches from a buffer. The |autocmd-pattern| is the -name of the buffer. When used from Lua, the client ID is passed to the -callback in the "data" table. Example: >lua + +LspDetach *LspDetach* + Just before an LSP client detaches from a buffer. The |autocmd-pattern| + is the name of the buffer. When used from Lua, the client ID is passed + to the callback in the "data" table. Example: >lua vim.api.nvim_create_autocmd("LspDetach", { callback = function(args) @@ -516,20 +532,105 @@ callback in the "data" table. Example: >lua end, }) < -Also the following |User| |autocommand|s are provided: -LspProgressUpdate *LspProgressUpdate* - Upon receipt of a progress notification from the server. See - |vim.lsp.util.get_progress_messages()|. +LspNotify *LspNotify* + This event is triggered after each successful notification sent to an + LSP server. + + When used from Lua, the client_id, LSP method, and parameters are sent + in the "data" table. Example: >lua + + vim.api.nvim_create_autocmd('LspNotify', { + callback = function(args) + local bufnr = args.buf + local client_id = args.data.client_id + local method = args.data.method + local params = args.data.params + + -- do something with the notification + if method == 'textDocument/...' then + update_buffer(bufnr) + end + end, + }) +< + +LspProgress *LspProgress* + Upon receipt of a progress notification from the server. Notifications can + be polled from a `progress` ring buffer of a |vim.lsp.client| or use + |vim.lsp.status()| to get an aggregate message + + If the server sends a "work done progress", the `pattern` is set to `kind` + (one of `begin`, `report` or `end`). + + When used from Lua, the event contains a `data` table with `client_id` and + `result` properties. `result` will contain the request params sent by the + server. + + Example: >vim + autocmd LspProgress * redrawstatus +< LspRequest *LspRequest* - After a change to the active set of pending LSP requests. See {requests} - in |vim.lsp.client|. + For each request sent to an LSP server, this event is triggered for + every change to the request's status. The status can be one of + `pending`, `complete`, or `cancel` and is sent as the {type} on the + "data" table passed to the callback function. + + It triggers when the initial request is sent ({type} == `pending`) and + when the LSP server responds ({type} == `complete`). If a cancellation + is requested using `client.cancel_request(request_id)`, then this event + will trigger with {type} == `cancel`. + + When used from Lua, the client ID, request ID, and request are sent in + the "data" table. See {requests} in |vim.lsp.client| for details on the + {request} value. If the request type is `complete`, the request will be + deleted from the client's pending requests table immediately after + calling the event's callbacks. Example: >lua + + vim.api.nvim_create_autocmd('LspRequest', { + callback = function(args) + local bufnr = args.buf + local client_id = args.data.client_id + local request_id = args.data.request_id + local request = args.data.request + if request.type == 'pending' then + -- do something with pending requests + track_pending(client_id, bufnr, request_id, request) + elseif request.type == 'cancel' then + -- do something with pending cancel requests + track_canceling(client_id, bufnr, request_id, request) + elseif request.type == 'complete' then + -- do something with finished requests. this pending + -- request entry is about to be removed since it is complete + track_finish(client_id, bufnr, request_id, request) + end + end, + }) +< + +LspTokenUpdate *LspTokenUpdate* + When a visible semantic token is sent or updated by the LSP server, or + when an existing token becomes visible for the first time. The + |autocmd-pattern| is the name of the buffer. When used from Lua, the + token and client ID are passed to the callback in the "data" table. The + token fields are documented in |vim.lsp.semantic_tokens.get_at_pos()|. + Example: + >lua -Example: >vim - autocmd User LspProgressUpdate redrawstatus - autocmd User LspRequest redrawstatus + vim.api.nvim_create_autocmd('LspTokenUpdate', { + callback = function(args) + local token = args.data.token + if token.type == 'variable' and not token.modifiers.readonly then + vim.lsp.semantic_tokens.highlight_token( + token, args.buf, args.data.client_id, 'MyMutableVariableHighlight' + ) + end + end, + }) < + Note: doing anything other than calling + |vim.lsp.semantic_tokens.highlight_token()| is considered experimental. ============================================================================== Lua module: vim.lsp *lsp-core* @@ -541,8 +642,12 @@ buf_attach_client({bufnr}, {client_id}) *vim.lsp.buf_attach_client()* Without calling this, the server won't be notified of changes to a buffer. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current - • {client_id} (number) Client id + • {bufnr} (integer) Buffer handle, or 0 for current + • {client_id} (integer) Client id + + Return: ~ + (boolean) success `true` if client was attached successfully; `false` + otherwise buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()* Detaches client from the specified buffer. Note: While the server is @@ -550,66 +655,65 @@ buf_detach_client({bufnr}, {client_id}) *vim.lsp.buf_detach_client()* send notifications should it ignore this notification. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current - • {client_id} (number) Client id + • {bufnr} (integer) Buffer handle, or 0 for current + • {client_id} (integer) Client id buf_is_attached({bufnr}, {client_id}) *vim.lsp.buf_is_attached()* Checks if a buffer is attached for a particular client. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current - • {client_id} (number) the client id + • {bufnr} (integer) Buffer handle, or 0 for current + • {client_id} (integer) the client id buf_notify({bufnr}, {method}, {params}) *vim.lsp.buf_notify()* Send a notification to a server Parameters: ~ - • {bufnr} (number|nil) The number of the buffer + • {bufnr} (integer|nil) The number of the buffer • {method} (string) Name of the request method • {params} (any) Arguments to send to the server Return: ~ - true if any client returns true; false otherwise + (boolean) success true if any client returns true; false otherwise *vim.lsp.buf_request_all()* -buf_request_all({bufnr}, {method}, {params}, {callback}) - Sends an async request for all active clients attached to the buffer. - Executes the callback on the combined result. Parameters are the same as - |vim.lsp.buf_request()| but the return result and callback are different. +buf_request_all({bufnr}, {method}, {params}, {handler}) + Sends an async request for all active clients attached to the buffer and + executes the `handler` callback with the combined result. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current. - • {method} (string) LSP method name - • {params} (table|nil) Parameters to send to the server - • {callback} (function) The callback to call when all requests are - finished. + • {bufnr} (integer) Buffer handle, or 0 for current. + • {method} (string) LSP method name + • {params} (table|nil) Parameters to send to the server + • {handler} (function) Handler called after all requests are completed. + Server results are passed as a `client_id:result` map. Return: ~ - (function) A function that will cancel all requests which is the same - as the one returned from `buf_request`. + (function) cancel Function that cancels all requests. *vim.lsp.buf_request_sync()* buf_request_sync({bufnr}, {method}, {params}, {timeout_ms}) Sends a request to all server and waits for the response of all of them. Calls |vim.lsp.buf_request_all()| but blocks Nvim while awaiting the - result. Parameters are the same as |vim.lsp.buf_request()| but the return - result is different. Wait maximum of {timeout_ms} (default 1000) ms. + result. Parameters are the same as |vim.lsp.buf_request_all()| but the + result is different. Waits a maximum of {timeout_ms} (default 1000) ms. Parameters: ~ - • {bufnr} (number) Buffer handle, or 0 for current. + • {bufnr} (integer) Buffer handle, or 0 for current. • {method} (string) LSP method name • {params} (table|nil) Parameters to send to the server - • {timeout_ms} (number|nil) Maximum time in milliseconds to wait for a + • {timeout_ms} (integer|nil) Maximum time in milliseconds to wait for a result. Defaults to 1000 - Return: ~ - Map of client_id:request_result. On timeout, cancel or error, returns - `(nil, err)` where `err` is a string describing the failure reason. + Return (multiple): ~ + (table) result Map of client_id:request_result. + (string|nil) err On timeout, cancel, or error, `err` is a string + describing the failure reason, and `result` is nil. client() *vim.lsp.client* LSP client object. You can get an active client object via - |vim.lsp.get_client_by_id()| or |vim.lsp.get_active_clients()|. + |vim.lsp.get_client_by_id()| or |vim.lsp.get_clients()|. • Methods: • request(method, params, [handler], bufnr) Sends a request to the @@ -658,35 +762,42 @@ client() *vim.lsp.client* server. Entries are key-value pairs with the key being the request ID while the value is a table with `type`, `bufnr`, and `method` key-value pairs. `type` is either "pending" for an active request, or - "cancel" for a cancel request. + "cancel" for a cancel request. It will be "complete" ephemerally while + executing |LspRequest| autocmds when replies are received from the + server. • {config} (table): copy of the table that was passed by the user to |vim.lsp.start_client()|. • {server_capabilities} (table): Response from the server sent on `initialize` describing the server's capabilities. + • {progress} A ring buffer (|vim.ringbuf()|) containing progress + messages sent by the server. client_is_stopped({client_id}) *vim.lsp.client_is_stopped()* Checks whether a client is stopped. Parameters: ~ - • {client_id} (number) + • {client_id} (integer) Return: ~ - true if client is stopped, false otherwise. + (boolean) stopped true if client is stopped, false otherwise. - *vim.lsp.for_each_buffer_client()* -for_each_buffer_client({bufnr}, {fn}) - Invokes a function for each LSP client attached to a buffer. +commands *vim.lsp.commands* + Registry for client side commands. This is an extension point for plugins + to handle custom commands which are not part of the core language server + protocol specification. - Parameters: ~ - • {bufnr} (number) Buffer number - • {fn} (function) Function to run on each client attached to buffer - {bufnr}. The function takes the client, client ID, and buffer - number as arguments. Example: >lua + The registry is a table where the key is a unique command name, and the + value is a function which is called if any LSP action (code action, code + lenses, ...) triggers the command. - vim.lsp.for_each_buffer_client(0, function(client, client_id, bufnr) - print(vim.inspect(client)) - end) -< + If a LSP response contains a command for which no matching entry is + available in this registry, the command will be executed via the LSP + server using `workspace/executeCommand`. + + The first argument to the function will be the `Command`: Command title: + String command: String arguments?: any[] + + The second argument is the `ctx` of |lsp-handler| formatexpr({opts}) *vim.lsp.formatexpr()* Provides an interface between the built-in client and a `formatexpr` @@ -694,8 +805,8 @@ formatexpr({opts}) *vim.lsp.formatexpr()* Currently only supports a single client. This can be set via `setlocal formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in - `on_attach` via `vim.api.nvim_buf_set_option(bufnr, 'formatexpr', - 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})')`. + `on_attach` via `vim.bo[bufnr].formatexpr = + 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`. Parameters: ~ • {opts} (table) options for customizing the formatting expression @@ -703,62 +814,64 @@ formatexpr({opts}) *vim.lsp.formatexpr()* • timeout_ms (default 500ms). The timeout period for the formatting request. -get_active_clients({filter}) *vim.lsp.get_active_clients()* - Get active clients. - - Parameters: ~ - • {filter} (table|nil) A table with key-value pairs used to filter the - returned clients. The available keys are: - • id (number): Only return clients with the given id - • bufnr (number): Only return clients attached to this - buffer - • name (string): Only return clients with the given name - - Return: ~ - (table) List of |vim.lsp.client| objects - *vim.lsp.get_buffers_by_client_id()* get_buffers_by_client_id({client_id}) Returns list of buffers attached to client_id. Parameters: ~ - • {client_id} (number) client id + • {client_id} (integer) client id Return: ~ - (list) of buffer ids + integer[] buffers list of buffer ids get_client_by_id({client_id}) *vim.lsp.get_client_by_id()* Gets a client by id, or nil if the id is invalid. The returned client may not yet be fully initialized. Parameters: ~ - • {client_id} (number) client id + • {client_id} (integer) client id + + Return: ~ + (nil|lsp.Client) client rpc object + +get_clients({filter}) *vim.lsp.get_clients()* + Get active clients. + + Parameters: ~ + • {filter} (table|nil) A table with key-value pairs used to filter the + returned clients. The available keys are: + • id (number): Only return clients with the given id + • bufnr (number): Only return clients attached to this + buffer + • name (string): Only return clients with the given name + • method (string): Only return clients supporting the given + method Return: ~ - |vim.lsp.client| object, or nil + lsp.Client []: List of |vim.lsp.client| objects get_log_path() *vim.lsp.get_log_path()* Gets the path of the logfile used by the LSP client. Return: ~ - (String) Path to logfile. + (string) path to log file omnifunc({findstart}, {base}) *vim.lsp.omnifunc()* Implements 'omnifunc' compatible LSP completion. Parameters: ~ - • {findstart} (number) 0 or 1, decides behavior - • {base} (number) findstart=0, text to match against + • {findstart} (integer) 0 or 1, decides behavior + • {base} (integer) findstart=0, text to match against Return: ~ - (number) Decided by {findstart}: + integer|table Decided by {findstart}: • findstart=0: column where the completion starts, or -2 or -3 • findstart=1: list of matches (actually just calls |complete()|) See also: ~ - |complete-functions| - |complete-items| - |CompleteDone| + • |complete-functions| + • |complete-items| + • |CompleteDone| set_log_level({level}) *vim.lsp.set_log_level()* Sets the global log level for LSP logging. @@ -770,10 +883,10 @@ set_log_level({level}) *vim.lsp.set_log_level()* Use `lsp.log_levels` for reverse lookup. Parameters: ~ - • {level} (number|string) the case insensitive level name or number + • {level} (integer|string) the case insensitive level name or number See also: ~ - |vim.lsp.log_levels| + • |vim.lsp.log_levels| start({config}, {opts}) *vim.lsp.start()* Create a new LSP client and start a language server or reuses an already @@ -781,12 +894,11 @@ start({config}, {opts}) *vim.lsp.start()* the current buffer to the client. Example: >lua - - vim.lsp.start({ - name = 'my-server-name', - cmd = {'name-of-language-server-executable'}, - root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]), - }) + vim.lsp.start({ + name = 'my-server-name', + cmd = {'name-of-language-server-executable'}, + root_dir = vim.fs.dirname(vim.fs.find({'pyproject.toml', 'setup.py'}, { upward = true })[1]), + }) < See |vim.lsp.start_client()| for all available options. The most important @@ -818,7 +930,7 @@ start({config}, {opts}) *vim.lsp.start()* Parameters: ~ • {config} (table) Same configuration as documented in |vim.lsp.start_client()| - • {opts} nil|table Optional keyword arguments: + • {opts} (nil|lsp.StartOpts) Optional keyword arguments: • reuse_client (fun(client: client, config: table): boolean) Predicate used to decide if a client should be re-used. Used on all running clients. The default implementation @@ -827,7 +939,7 @@ start({config}, {opts}) *vim.lsp.start()* re-using a client (0 for current). Return: ~ - (number|nil) client_id + (integer|nil) client_id start_client({config}) *vim.lsp.start_client()* Starts and initializes a client with the given configuration. @@ -835,24 +947,23 @@ start_client({config}) *vim.lsp.start_client()* Field `cmd` in {config} is required. Parameters: ~ - • {config} (table) Configuration for the server: - • cmd: (table|string|fun(dispatchers: table):table) command - string or list treated like |jobstart()|. The command must - launch the language server process. `cmd` can also be a - function that creates an RPC client. The function receives - a dispatchers table and must return a table with the - functions `request`, `notify`, `is_closing` and + • {config} ( lsp.ClientConfig ) Configuration for the server: + • cmd: (string[]|fun(dispatchers: table):table) command a + list of strings treated like |jobstart()|. The command + must launch the language server process. `cmd` can also be + a function that creates an RPC client. The function + receives a dispatchers table and must return a table with + the functions `request`, `notify`, `is_closing` and `terminate` See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()| For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()| • cmd_cwd: (string, default=|getcwd()|) Directory to launch the `cmd` process. Not related to `root_dir`. • cmd_env: (table) Environment flags to pass to the LSP on - spawn. Can be specified using keys like a map or as a list - with `k=v` pairs or both. Non-string values are coerced to string. - Example: > + spawn. Must be specified using a table. Non-string values + are coerced to string. Example: > - { "PRODUCTION=true"; "TEST=123"; PORT = 8080; HOST = "0.0.0.0"; } + { PORT = 8080; HOST = "0.0.0.0"; } < • detached: (boolean, default true) Daemonize the server process so that it runs in a separate process group from @@ -869,8 +980,7 @@ start_client({config}) *vim.lsp.start_client()* passed to the language server on initialization. Hint: use make_client_capabilities() and modify its result. • Note: To send an empty dictionary use - `{[vim.type_idx]=vim.types.dictionary}`, else it will be - encoded as an array. + |vim.empty_dict()|, else it will be encoded as an array. • handlers: Map of language server method names to |lsp-handler| @@ -912,8 +1022,8 @@ start_client({config}) *vim.lsp.start_client()* if `capabilities.offsetEncoding` was sent to it. You can only modify the `client.offset_encoding` here before any notifications are sent. Most language servers expect to be - sent client specified settings after initialization. - Neovim does not make this assumption. A + sent client specified settings after initialization. Nvim + does not make this assumption. A `workspace/didChangeConfiguration` notification should be sent to the server during on_init. • on_exit Callback (code, signal, client_id) invoked on @@ -946,27 +1056,34 @@ start_client({config}) *vim.lsp.start_client()* initialization. Return: ~ - Client id. |vim.lsp.get_client_by_id()| Note: client may not be fully - initialized. Use `on_init` to do any actions once the client has been - initialized. + (integer|nil) client_id. |vim.lsp.get_client_by_id()| Note: client may + not be fully initialized. Use `on_init` to do any actions once the + client has been initialized. + +status() *vim.lsp.status()* + Consumes the latest progress messages from all clients and formats them as + a string. Empty if there are no clients or if no new messages + + Return: ~ + (string) stop_client({client_id}, {force}) *vim.lsp.stop_client()* Stops a client(s). - You can also use the `stop()` function on a |vim.lsp.client| object. To stop all clients: >lua - - vim.lsp.stop_client(vim.lsp.get_active_clients()) + You can also use the `stop()` function on a |vim.lsp.client| object. To + stop all clients: >lua + vim.lsp.stop_client(vim.lsp.get_clients()) < By default asks the server to shutdown, unless stop was requested already for this client, then force-shutdown is attempted. Parameters: ~ - • {client_id} number|table id or |vim.lsp.client| object, or list + • {client_id} integer|table id or |vim.lsp.client| object, or list thereof • {force} (boolean|nil) shutdown forcefully -tagfunc({...}) *vim.lsp.tagfunc()* +tagfunc({pattern}, {flags}) *vim.lsp.tagfunc()* Provides an interface between the built-in client and 'tagfunc'. When used with normal mode commands (e.g. |CTRL-]|) this will invoke the @@ -979,7 +1096,7 @@ tagfunc({...}) *vim.lsp.tagfunc()* • {flags} (string) See |tag-function| Return: ~ - A list of matching tags + table[] tags A list of matching tags with({handler}, {override_config}) *vim.lsp.with()* Function to manage overriding defaults for LSP handlers. @@ -1008,7 +1125,8 @@ code_action({options}) *vim.lsp.buf.code_action()* • {options} (table|nil) Optional table which holds the following optional fields: • context: (table|nil) Corresponds to `CodeActionContext` of the LSP specification: - • diagnostics (table|nil): LSP`Diagnostic[]` . Inferred from the current position if not provided. + • diagnostics (table|nil): LSP `Diagnostic[]`. Inferred + from the current position if not provided. • only (table|nil): List of LSP `CodeActionKind`s used to filter the code actions. Most language servers support values like `refactor` or `quickfix`. @@ -1023,38 +1141,39 @@ code_action({options}) *vim.lsp.buf.code_action()* • range: (table|nil) Range for which code actions should be requested. If in visual mode this defaults to the active selection. Table must contain `start` and `end` keys with - {row, col} tuples using mark-like indexing. See + {row,col} tuples using mark-like indexing. See |api-indexing| See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction - vim.lsp.protocol.constants.CodeActionTriggerKind + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_codeAction + • vim.lsp.protocol.CodeActionTriggerKind completion({context}) *vim.lsp.buf.completion()* Retrieves the completion items at the current cursor position. Can only be called in Insert mode. Parameters: ~ - • {context} (context support not yet implemented) Additional + • {context} (table) (context support not yet implemented) Additional information about the context in which a completion was triggered (how it was triggered, and by which trigger character, if applicable) See also: ~ - vim.lsp.protocol.constants.CompletionTriggerKind + • vim.lsp.protocol.CompletionTriggerKind declaration({options}) *vim.lsp.buf.declaration()* Jumps to the declaration of the symbol under the cursor. - Note: - Many servers do not implement this method. Generally, see + + Note: ~ + • Many servers do not implement this method. Generally, see |vim.lsp.buf.definition()| instead. Parameters: ~ • {options} (table|nil) additional options • reuse_win: (boolean) Jump to existing window if buffer is already open. - • on_list: (function) handler for list results. See - |lsp-on-list-handler| + • on_list: (function) |lsp-on-list-handler| replacing the + default handler. Called for any non-empty result. definition({options}) *vim.lsp.buf.definition()* Jumps to the definition of the symbol under the cursor. @@ -1063,16 +1182,16 @@ definition({options}) *vim.lsp.buf.definition()* • {options} (table|nil) additional options • reuse_win: (boolean) Jump to existing window if buffer is already open. - • on_list: (function) handler for list results. See - |lsp-on-list-handler| + • on_list: (function) |lsp-on-list-handler| replacing the + default handler. Called for any non-empty result. document_highlight() *vim.lsp.buf.document_highlight()* Send request to the server to resolve document highlights for the current text document position. This request can be triggered by a key mapping or - by events such as `CursorHold` , e.g.: >vim - autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight() - autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight() - autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references() + by events such as `CursorHold`, e.g.: >vim + autocmd CursorHold <buffer> lua vim.lsp.buf.document_highlight() + autocmd CursorHoldI <buffer> lua vim.lsp.buf.document_highlight() + autocmd CursorMoved <buffer> lua vim.lsp.buf.clear_references() < Note: Usage of |vim.lsp.buf.document_highlight()| requires the following @@ -1095,19 +1214,18 @@ execute_command({command_params}) *vim.lsp.buf.execute_command()* • {command_params} (table) A valid `ExecuteCommandParams` object See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#workspace_executeCommand format({options}) *vim.lsp.buf.format()* Formats a buffer using the attached (and optionally filtered) language server clients. Parameters: ~ - • {options} table|nil Optional table which holds the following optional - fields: + • {options} (table|nil) Optional table which holds the following + optional fields: • formatting_options (table|nil): Can be used to specify FormattingOptions. Some unspecified options will be - automatically derived from the current Neovim options. - See https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#formattingOptions + automatically derived from the current Nvim options. See https://microsoft.github.io/language-server-protocol/specification/#formattingOptions • timeout_ms (integer|nil, default 1000): Time in milliseconds to block for formatting requests. No effect if async=true @@ -1116,12 +1234,12 @@ format({options}) *vim.lsp.buf.format()* buffer (0). • filter (function|nil): Predicate used to filter clients. Receives a client as argument and must return a boolean. - Clients matching the predicate are included. Example: • >lua + Clients matching the predicate are included. Example: >lua - -- Never request typescript-language-server for formatting - vim.lsp.buf.format { - filter = function(client) return client.name ~= "tsserver" end - } + -- Never request typescript-language-server for formatting + vim.lsp.buf.format { + filter = function(client) return client.name ~= "tsserver" end + } < • async boolean|nil If true the method won't block. Defaults to false. Editing the buffer while formatting @@ -1131,7 +1249,7 @@ format({options}) *vim.lsp.buf.format()* • name (string|nil): Restrict formatting to the client with name (client.name) matching this field. • range (table|nil) Range to format. Table must contain - `start` and `end` keys with {row, col} tuples using (1,0) + `start` and `end` keys with {row,col} tuples using (1,0) indexing. Defaults to current selection in visual mode Defaults to `nil` in other modes, formatting the full buffer @@ -1146,8 +1264,8 @@ implementation({options}) *vim.lsp.buf.implementation()* Parameters: ~ • {options} (table|nil) additional options - • on_list: (function) handler for list results. See - |lsp-on-list-handler| + • on_list: (function) |lsp-on-list-handler| replacing the + default handler. Called for any non-empty result. incoming_calls() *vim.lsp.buf.incoming_calls()* Lists all the call sites of the symbol under the cursor in the |quickfix| @@ -1173,7 +1291,7 @@ references({context}, {options}) *vim.lsp.buf.references()* |lsp-on-list-handler| See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_references *vim.lsp.buf.remove_workspace_folder()* remove_workspace_folder({workspace_folder}) @@ -1193,13 +1311,6 @@ rename({new_name}, {options}) *vim.lsp.buf.rename()* • name (string|nil): Restrict clients used for rename to ones where client.name matches this field. -server_ready() *vim.lsp.buf.server_ready()* - Checks whether the language servers attached to the current buffer are - ready. - - Return: ~ - `true` if server responds. - signature_help() *vim.lsp.buf.signature_help()* Displays signature information about the symbol under the cursor in a floating window. @@ -1211,8 +1322,8 @@ type_definition({options}) *vim.lsp.buf.type_definition()* • {options} (table|nil) additional options • reuse_win: (boolean) Jump to existing window if buffer is already open. - • on_list: (function) handler for list results. See - |lsp-on-list-handler| + • on_list: (function) |lsp-on-list-handler| replacing the + default handler. Called for any non-empty result. workspace_symbol({query}, {options}) *vim.lsp.buf.workspace_symbol()* Lists all symbols in the current workspace in the quickfix window. @@ -1222,7 +1333,7 @@ workspace_symbol({query}, {options}) *vim.lsp.buf.workspace_symbol()* string means no filtering is done. Parameters: ~ - • {query} (string, optional) + • {query} (string|nil) optional • {options} (table|nil) additional options • on_list: (function) handler for list results. See |lsp-on-list-handler| @@ -1231,12 +1342,43 @@ workspace_symbol({query}, {options}) *vim.lsp.buf.workspace_symbol()* ============================================================================== Lua module: vim.lsp.diagnostic *lsp-diagnostic* -get_namespace({client_id}) *vim.lsp.diagnostic.get_namespace()* + *vim.lsp.diagnostic.get_namespace()* +get_namespace({client_id}, {is_pull}) Get the diagnostic namespace associated with an LSP client - |vim.diagnostic|. + |vim.diagnostic| for diagnostics + + Parameters: ~ + • {client_id} (integer) The id of the LSP client + • {is_pull} boolean? Whether the namespace is for a pull or push + client. Defaults to push + + *vim.lsp.diagnostic.on_diagnostic()* +on_diagnostic({_}, {result}, {ctx}, {config}) + |lsp-handler| for the method "textDocument/diagnostic" + + See |vim.diagnostic.config()| for configuration options. Handler-specific + configuration can be set using |vim.lsp.with()|: >lua + vim.lsp.handlers["textDocument/diagnostic"] = vim.lsp.with( + vim.lsp.diagnostic.on_diagnostic, { + -- Enable underline, use default values + underline = true, + -- Enable virtual text, override spacing to 4 + virtual_text = { + spacing = 4, + }, + -- Use a function to dynamically turn signs off + -- and on, using buffer local variables + signs = function(namespace, bufnr) + return vim.b[bufnr].show_signs == true + end, + -- Disable a feature + update_in_insert = false, + } + ) +< Parameters: ~ - • {client_id} (number) The id of the LSP client + • {config} (table) Configuration table (see |vim.diagnostic.config()|). *vim.lsp.diagnostic.on_publish_diagnostics()* on_publish_diagnostics({_}, {result}, {ctx}, {config}) @@ -1244,24 +1386,23 @@ on_publish_diagnostics({_}, {result}, {ctx}, {config}) See |vim.diagnostic.config()| for configuration options. Handler-specific configuration can be set using |vim.lsp.with()|: >lua - - vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with( - vim.lsp.diagnostic.on_publish_diagnostics, { - -- Enable underline, use default values - underline = true, - -- Enable virtual text, override spacing to 4 - virtual_text = { - spacing = 4, - }, - -- Use a function to dynamically turn signs off - -- and on, using buffer local variables - signs = function(namespace, bufnr) - return vim.b[bufnr].show_signs == true - end, - -- Disable a feature - update_in_insert = false, - } - ) + vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with( + vim.lsp.diagnostic.on_publish_diagnostics, { + -- Enable underline, use default values + underline = true, + -- Enable virtual text, override spacing to 4 + virtual_text = { + spacing = 4, + }, + -- Use a function to dynamically turn signs off + -- and on, using buffer local variables + signs = function(namespace, bufnr) + return vim.b[bufnr].show_signs == true + end, + -- Disable a feature + update_in_insert = false, + } + ) < Parameters: ~ @@ -1275,25 +1416,26 @@ clear({client_id}, {bufnr}) *vim.lsp.codelens.clear()* Clear the lenses Parameters: ~ - • {client_id} (number|nil) filter by client_id. All clients if nil - • {bufnr} (number|nil) filter by buffer. All buffers if nil + • {client_id} (integer|nil) filter by client_id. All clients if nil + • {bufnr} (integer|nil) filter by buffer. All buffers if nil display({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.display()* Display the lenses using virtual text Parameters: ~ - • {lenses} (table) of lenses to display (`CodeLens[] | null`) - • {bufnr} (number) - • {client_id} (number) + • {lenses} lsp.CodeLens[]|nil lenses to display + • {bufnr} (integer) + • {client_id} (integer) get({bufnr}) *vim.lsp.codelens.get()* Return all lenses for the given buffer Parameters: ~ - • {bufnr} (number) Buffer number. 0 can be used for the current buffer. + • {bufnr} (integer) Buffer number. 0 can be used for the current + buffer. Return: ~ - (table) (`CodeLens[]`) + lsp.CodeLens[] *vim.lsp.codelens.on_codelens()* on_codelens({err}, {result}, {ctx}, {_}) @@ -1305,7 +1447,7 @@ refresh() *vim.lsp.codelens.refresh()* It is recommended to trigger this using an autocmd or via keymap. Example: >vim - autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh() + autocmd BufEnter,CursorHold,InsertLeave <buffer> lua vim.lsp.codelens.refresh() < run() *vim.lsp.codelens.run()* @@ -1315,9 +1457,64 @@ save({lenses}, {bufnr}, {client_id}) *vim.lsp.codelens.save()* Store lenses for a specific buffer and client Parameters: ~ - • {lenses} (table) of lenses to store (`CodeLens[] | null`) - • {bufnr} (number) - • {client_id} (number) + • {lenses} lsp.CodeLens[]|nil lenses to store + • {bufnr} (integer) + • {client_id} (integer) + + +============================================================================== +Lua module: vim.lsp.inlay_hint *lsp-inlay_hint* + +enable({bufnr}, {enable}) *vim.lsp.inlay_hint.enable()* + Enable/disable/toggle inlay hints for a buffer + + Note: ~ + This API is pre-release (unstable). + + Parameters: ~ + • {bufnr} (integer|nil) Buffer handle, or 0 or nil for current + • {enable} (boolean|nil) true/nil to enable, false to disable + +get({filter}) *vim.lsp.inlay_hint.get()* + Get the list of inlay hints, (optionally) restricted by buffer or range. + + Example usage: >lua + local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer + + local client = vim.lsp.get_client_by_id(hint.client_id) + resolved_hint = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0).result + vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding) + + location = resolved_hint.label[1].location + client.request('textDocument/hover', { + textDocument = { uri = location.uri }, + position = location.range.start, + }) +< + + Note: ~ + This API is pre-release (unstable). + + Parameters: ~ + • {filter} vim.lsp.inlay_hint.get.filter ? Optional filters |kwargs|: + • bufnr (integer?): 0 for current buffer + • range (lsp.Range?) + + Return: ~ + vim.lsp.inlay_hint.get.ret [] Each list item is a table with the following fields: + • bufnr (integer) + • client_id (integer) + • inlay_hint (lsp.InlayHint) + +is_enabled({bufnr}) *vim.lsp.inlay_hint.is_enabled()* + Note: ~ + This API is pre-release (unstable). + + Parameters: ~ + • {bufnr} (integer|nil) Buffer handle, or 0 or nil for current + + Return: ~ + (boolean) ============================================================================== @@ -1330,7 +1527,8 @@ force_refresh({bufnr}) *vim.lsp.semantic_tokens.force_refresh()* highlighting (|vim.lsp.semantic_tokens.start()| has been called for it) Parameters: ~ - • {bufnr} (nil|number) default: current buffer + • {bufnr} (integer|nil) filter by buffer. All buffers if nil, current + buffer if 0 *vim.lsp.semantic_tokens.get_at_pos()* get_at_pos({bufnr}, {row}, {col}) @@ -1338,12 +1536,39 @@ get_at_pos({bufnr}, {row}, {col}) arguments, returns the token under the cursor. Parameters: ~ - • {bufnr} (number|nil) Buffer number (0 for current buffer, default) - • {row} (number|nil) Position row (default cursor position) - • {col} (number|nil) Position column (default cursor position) + • {bufnr} (integer|nil) Buffer number (0 for current buffer, default) + • {row} (integer|nil) Position row (default cursor position) + • {col} (integer|nil) Position column (default cursor position) Return: ~ - (table|nil) List of tokens at position + (table|nil) List of tokens at position. Each token has the following + fields: + • line (integer) line number, 0-based + • start_col (integer) start column, 0-based + • end_col (integer) end column, 0-based + • type (string) token type as string, e.g. "variable" + • modifiers (table) token modifiers as a set. E.g., { static = true, + readonly = true } + + *vim.lsp.semantic_tokens.highlight_token()* +highlight_token({token}, {bufnr}, {client_id}, {hl_group}, {opts}) + Highlight a semantic token. + + Apply an extmark with a given highlight group for a semantic token. The + mark will be deleted by the semantic token engine when appropriate; for + example, when the LSP sends updated tokens. This function is intended for + use inside |LspTokenUpdate| callbacks. + + Parameters: ~ + • {token} (table) a semantic token, found as `args.data.token` in + |LspTokenUpdate|. + • {bufnr} (integer) the buffer to highlight + • {client_id} (integer) The ID of the |vim.lsp.client| + • {hl_group} (string) Highlight group name + • {opts} (table|nil) Optional parameters. + • priority: (integer|nil) Priority for the applied + extmark. Defaults to + `vim.highlight.priorities.semantic_tokens + 3` start({bufnr}, {client_id}, {opts}) *vim.lsp.semantic_tokens.start()* Start the semantic token highlighting engine for the given buffer with the @@ -1354,15 +1579,14 @@ start({bufnr}, {client_id}, {opts}) *vim.lsp.semantic_tokens.start()* server that supports it, you can delete the semanticTokensProvider table from the {server_capabilities} of your client in your |LspAttach| callback or your configuration's `on_attach` callback: >lua - - client.server_capabilities.semanticTokensProvider = nil + client.server_capabilities.semanticTokensProvider = nil < Parameters: ~ - • {bufnr} (number) - • {client_id} (number) + • {bufnr} (integer) + • {client_id} (integer) • {opts} (nil|table) Optional keyword arguments - • debounce (number, default: 200): Debounce token + • debounce (integer, default: 200): Debounce token requests to the server by the given number in milliseconds @@ -1376,8 +1600,8 @@ stop({bufnr}, {client_id}) *vim.lsp.semantic_tokens.stop()* from the buffer. Parameters: ~ - • {bufnr} (number) - • {client_id} (number) + • {bufnr} (integer) + • {client_id} (integer) ============================================================================== @@ -1385,41 +1609,44 @@ Lua module: vim.lsp.handlers *lsp-handlers* hover({_}, {result}, {ctx}, {config}) *vim.lsp.handlers.hover()* |lsp-handler| for the method "textDocument/hover" >lua - - vim.lsp.handlers["textDocument/hover"] = vim.lsp.with( - vim.lsp.handlers.hover, { - -- Use a sharp border with `FloatBorder` highlights - border = "single", - -- add the title in hover float window - title = "hover" - } - ) + vim.lsp.handlers["textDocument/hover"] = vim.lsp.with( + vim.lsp.handlers.hover, { + -- Use a sharp border with `FloatBorder` highlights + border = "single", + -- add the title in hover float window + title = "hover" + } + ) < Parameters: ~ • {config} (table) Configuration table. • border: (default=nil) • Add borders to the floating window - • See |nvim_open_win()| + • See |vim.lsp.util.open_floating_preview()| for more + options. *vim.lsp.handlers.signature_help()* signature_help({_}, {result}, {ctx}, {config}) - |lsp-handler| for the method "textDocument/signatureHelp". The active - parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua - - vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with( - vim.lsp.handlers.signature_help, { - -- Use a sharp border with `FloatBorder` highlights - border = "single" - } - ) + |lsp-handler| for the method "textDocument/signatureHelp". + + The active parameter is highlighted with |hl-LspSignatureActiveParameter|. >lua + vim.lsp.handlers["textDocument/signatureHelp"] = vim.lsp.with( + vim.lsp.handlers.signature_help, { + -- Use a sharp border with `FloatBorder` highlights + border = "single" + } + ) < Parameters: ~ + • {result} (table) Response from the language server + • {ctx} (table) Client context • {config} (table) Configuration table. • border: (default=nil) • Add borders to the floating window - • See |nvim_open_win()| + • See |vim.lsp.util.open_floating_preview()| for more + options ============================================================================== @@ -1432,11 +1659,11 @@ apply_text_document_edit({text_document_edit}, {index}, {offset_encoding}) Parameters: ~ • {text_document_edit} (table) a `TextDocumentEdit` object - • {index} (number) Optional index of the edit, if from a + • {index} (integer) Optional index of the edit, if from a list of edits (or nil, if not from a list) See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentEdit *vim.lsp.util.apply_text_edits()* apply_text_edits({text_edits}, {bufnr}, {offset_encoding}) @@ -1444,11 +1671,11 @@ apply_text_edits({text_edits}, {bufnr}, {offset_encoding}) Parameters: ~ • {text_edits} (table) list of `TextEdit` objects - • {bufnr} (number) Buffer id + • {bufnr} (integer) Buffer id • {offset_encoding} (string) utf-8|utf-16|utf-32 See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textEdit *vim.lsp.util.apply_workspace_edit()* apply_workspace_edit({workspace_edit}, {offset_encoding}) @@ -1462,35 +1689,35 @@ buf_clear_references({bufnr}) *vim.lsp.util.buf_clear_references()* Removes document highlights from a buffer. Parameters: ~ - • {bufnr} (number) Buffer id + • {bufnr} (integer|nil) Buffer id *vim.lsp.util.buf_highlight_references()* buf_highlight_references({bufnr}, {references}, {offset_encoding}) Shows a list of document highlights for a certain buffer. Parameters: ~ - • {bufnr} (number) Buffer id + • {bufnr} (integer) Buffer id • {references} (table) List of `DocumentHighlight` objects to highlight • {offset_encoding} (string) One of "utf-8", "utf-16", "utf-32". See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentContentChangeEvent + • https://microsoft.github.io/language-server-protocol/specification/#textDocumentContentChangeEvent *vim.lsp.util.character_offset()* character_offset({buf}, {row}, {col}, {offset_encoding}) Returns the UTF-32 and UTF-16 offsets for a position in a certain buffer. Parameters: ~ - • {buf} (number) buffer number (0 for current) + • {buf} (integer) buffer number (0 for current) • {row} 0-indexed line • {col} 0-indexed byte offset in line - • {offset_encoding} (string) utf-8|utf-16|utf-32|nil defaults to + • {offset_encoding} (string) utf-8|utf-16|utf-32 defaults to `offset_encoding` of first client of `buf` Return: ~ - (number, number) `offset_encoding` index of the character in line - {row} column {col} in buffer {buf} + (integer) `offset_encoding` index of the character in line {row} + column {col} in buffer {buf} *vim.lsp.util.convert_input_to_markdown_lines()* convert_input_to_markdown_lines({input}, {contents}) @@ -1499,58 +1726,50 @@ convert_input_to_markdown_lines({input}, {contents}) window for `textDocument/hover`, for parsing the result of `textDocument/signatureHelp`, and potentially others. + Note that if the input is of type `MarkupContent` and its kind is + `plaintext`, then the corresponding value is returned without further + modifications. + Parameters: ~ • {input} (`MarkedString` | `MarkedString[]` | `MarkupContent`) • {contents} (table|nil) List of strings to extend with converted lines. Defaults to {}. Return: ~ - {contents}, extended with lines of converted markdown. + string[] extended with lines of converted markdown. See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_hover *vim.lsp.util.convert_signature_help_to_markdown_lines()* convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers}) - Converts `textDocument/SignatureHelp` response to markdown lines. + Converts `textDocument/signatureHelp` response to markdown lines. Parameters: ~ - • {signature_help} Response of `textDocument/SignatureHelp` - • {ft} optional filetype that will be use as the `lang` for - the label markdown code block - • {triggers} optional list of trigger characters from the lsp + • {signature_help} (table) Response of `textDocument/SignatureHelp` + • {ft} (string|nil) filetype that will be use as the `lang` + for the label markdown code block + • {triggers} (table|nil) list of trigger characters from the lsp server. used to better determine parameter offsets - Return: ~ - (list) of lines of converted markdown. - - See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp - - *vim.lsp.util.extract_completion_items()* -extract_completion_items({result}) - Can be used to extract the completion items from a `textDocument/completion` request, which may return one of `CompletionItem[]` , `CompletionList` or null. - - Parameters: ~ - • {result} (table) The result of a `textDocument/completion` request - - Return: ~ - (table) List of completion items + Return (multiple): ~ + (table|nil) table list of lines of converted markdown. + (table|nil) table of active hl See also: ~ - https://microsoft.github.io/language-server-protocol/specification#textDocument_completion + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()* Returns indentation size. Parameters: ~ - • {bufnr} (number|nil) Buffer handle, defaults to current + • {bufnr} (integer|nil) Buffer handle, defaults to current Return: ~ - (number) indentation size + (integer) indentation size See also: ~ - 'shiftwidth' + • 'shiftwidth' *vim.lsp.util.jump_to_location()* jump_to_location({location}, {offset_encoding}, {reuse_win}) @@ -1558,7 +1777,7 @@ jump_to_location({location}, {offset_encoding}, {reuse_win}) Parameters: ~ • {location} (table) (`Location`|`LocationLink`) - • {offset_encoding} "utf-8" | "utf-16" | "utf-32" + • {offset_encoding} (string|nil) utf-8|utf-16|utf-32 • {reuse_win} (boolean|nil) Jump to existing window if buffer is already open. @@ -1570,13 +1789,17 @@ locations_to_items({locations}, {offset_encoding}) Returns the items with the byte position calculated correctly and in sorted order, for display in quickfix and location lists. + The `user_data` field of each resulting item will contain the original + `Location` or `LocationLink` it was computed from. + The result can be passed to the {list} argument of |setqflist()| or |setloclist()|. Parameters: ~ • {locations} (table) list of `Location`s or `LocationLink`s • {offset_encoding} (string) offset_encoding for locations - utf-8|utf-16|utf-32 + utf-8|utf-16|utf-32 default to first client of + buffer Return: ~ (table) list of items @@ -1585,11 +1808,11 @@ lookup_section({settings}, {section}) *vim.lsp.util.lookup_section()* Helper function to return nested values in language server settings Parameters: ~ - • {settings} a table of language server settings - • {section} a string indicating the field of the settings table + • {settings} (table) language server settings + • {section} string indicating the field of the settings table Return: ~ - (table or string) The value of settings accessed via section + table|string The value of settings accessed via section *vim.lsp.util.make_floating_popup_options()* make_floating_popup_options({width}, {height}, {opts}) @@ -1597,15 +1820,22 @@ make_floating_popup_options({width}, {height}, {opts}) table can be passed to |nvim_open_win()|. Parameters: ~ - • {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` + • {width} (integer) window width (in character cells) + • {height} (integer) window height (in character cells) + • {opts} (table) optional + • offset_x (integer) offset to add to `col` + • offset_y (integer) 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 • relative ("mouse"|"cursor") defaults to "cursor" + • anchor_bias ("auto"|"above"|"below") defaults to "auto" + • "auto": place window based on which side of the cursor + has more lines + • "above": place the window above the cursor unless there + are not enough lines to display the full window height. + • "below": place the window below the cursor unless there + are not enough lines to display the full window height. Return: ~ (table) Options @@ -1622,7 +1852,7 @@ make_formatting_params({options}) `DocumentFormattingParams` object See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_formatting *vim.lsp.util.make_given_range_params()* make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding}) @@ -1630,18 +1860,18 @@ make_given_range_params({start_pos}, {end_pos}, {bufnr}, {offset_encoding}) similar to |vim.lsp.util.make_range_params()|. Parameters: ~ - • {start_pos} number[]|nil {row, col} mark-indexed position. + • {start_pos} integer[]|nil {row,col} mark-indexed position. Defaults to the start of the last visual selection. - • {end_pos} number[]|nil {row, col} mark-indexed position. + • {end_pos} integer[]|nil {row,col} mark-indexed position. Defaults to the end of the last visual selection. - • {bufnr} (number|nil) buffer handle or 0 for current, + • {bufnr} (integer|nil) buffer handle or 0 for current, defaults to current • {offset_encoding} "utf-8"|"utf-16"|"utf-32"|nil defaults to `offset_encoding` of first client of `bufnr` Return: ~ - { textDocument = { uri = `current_file_uri` }, range = { start = - `start_position`, end = `end_position` } } + (table) { textDocument = { uri = `current_file_uri` }, range = { start + = `start_position`, end = `end_position` } } *vim.lsp.util.make_position_params()* make_position_params({window}, {offset_encoding}) @@ -1649,17 +1879,17 @@ make_position_params({window}, {offset_encoding}) cursor position. Parameters: ~ - • {window} (number|nil) window handle or 0 for current, + • {window} (integer|nil) window handle or 0 for current, defaults to current • {offset_encoding} (string|nil) utf-8|utf-16|utf-32|nil defaults to `offset_encoding` of first client of buffer of `window` Return: ~ - `TextDocumentPositionParams` object + (table) `TextDocumentPositionParams` object See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams *vim.lsp.util.make_range_params()* make_range_params({window}, {offset_encoding}) @@ -1669,36 +1899,36 @@ make_range_params({window}, {offset_encoding}) `textDocument/rangeFormatting`. Parameters: ~ - • {window} (number|nil) window handle or 0 for current, + • {window} (integer|nil) window handle or 0 for current, defaults to current • {offset_encoding} "utf-8"|"utf-16"|"utf-32"|nil defaults to `offset_encoding` of first client of buffer of `window` Return: ~ - { textDocument = { uri = `current_file_uri` }, range = { start = - `current_position`, end = `current_position` } } + (table) { textDocument = { uri = `current_file_uri` }, range = { start + = `current_position`, end = `current_position` } } *vim.lsp.util.make_text_document_params()* make_text_document_params({bufnr}) Creates a `TextDocumentIdentifier` object for the current buffer. Parameters: ~ - • {bufnr} (number|nil) Buffer handle, defaults to current + • {bufnr} (integer|nil) Buffer handle, defaults to current Return: ~ - `TextDocumentIdentifier` + (table) `TextDocumentIdentifier` See also: ~ - https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentIdentifier *vim.lsp.util.make_workspace_params()* make_workspace_params({added}, {removed}) Create the workspace params Parameters: ~ - • {added} - • {removed} + • {added} (table) + • {removed} (table) *vim.lsp.util.open_floating_preview()* open_floating_preview({contents}, {syntax}, {opts}) @@ -1707,18 +1937,16 @@ open_floating_preview({contents}, {syntax}, {opts}) Parameters: ~ • {contents} (table) of lines to show in window • {syntax} (string) of syntax to set for opened buffer - • {opts} (table) with optional fields (additional keys are passed - on to |nvim_open_win()|) - • height: (number) height of floating window - • width: (number) width of floating window + • {opts} (table) with optional fields (additional keys are filtered + with |vim.lsp.util.make_floating_popup_options()| before + they are passed on to |nvim_open_win()|) + • height: (integer) height of floating window + • width: (integer) width of floating window • wrap: (boolean, default true) wrap long lines - • wrap_at: (number) character to wrap at for computing + • wrap_at: (integer) character to wrap at for computing height when wrap is enabled - • max_width: (number) maximal width of floating window - • max_height: (number) maximal height of floating window - • pad_top: (number) number of lines to pad contents at top - • pad_bottom: (number) number of lines to pad contents at - bottom + • max_width: (integer) maximal width of floating window + • max_height: (integer) maximal height of floating window • focus_id: (string) if a popup with this id is opened, then focus it • close_events: (table) list of events that closes the @@ -1728,18 +1956,9 @@ open_floating_preview({contents}, {syntax}, {opts}) {focusable} is also `true`, focus an existing floating window with the same {focus_id} - Return: ~ - bufnr,winnr buffer and window number of the newly created floating - preview window - -parse_snippet({input}) *vim.lsp.util.parse_snippet()* - Parses snippets in a completion entry. - - Parameters: ~ - • {input} (string) unparsed snippet - - Return: ~ - (string) parsed snippet + Return (multiple): ~ + (integer) bufnr of newly created float window + (integer) winid of newly created float window preview window preview_location({location}, {opts}) *vim.lsp.util.preview_location()* Previews a location in a floating window @@ -1750,10 +1969,11 @@ preview_location({location}, {opts}) *vim.lsp.util.preview_location()* definition) Parameters: ~ - • {location} a single `Location` or `LocationLink` + • {location} (table) a single `Location` or `LocationLink` - Return: ~ - (bufnr,winnr) buffer and window number of floating window or nil + Return (multiple): ~ + (integer|nil) buffer id of float window + (integer|nil) window id of float window rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()* Rename old_fname to new_fname @@ -1761,27 +1981,13 @@ rename({old_fname}, {new_fname}, {opts}) *vim.lsp.util.rename()* Parameters: ~ • {opts} (table) -set_lines({lines}, {A}, {B}, {new_lines}) *vim.lsp.util.set_lines()* - Replaces text in a range with new text. - - CAUTION: Changes in-place! - - Parameters: ~ - • {lines} (table) Original list of strings - • {A} (table) Start position; a 2-tuple of {line, col} numbers - • {B} (table) End position; a 2-tuple of {line, col} numbers - • {new_lines} A list of strings to replace the original - - Return: ~ - (table) The modified {lines} object - *vim.lsp.util.show_document()* show_document({location}, {offset_encoding}, {opts}) Shows document and optionally jumps to the location. Parameters: ~ • {location} (table) (`Location`|`LocationLink`) - • {offset_encoding} "utf-8" | "utf-16" | "utf-32" + • {offset_encoding} (string|nil) utf-8|utf-16|utf-32 • {opts} (table|nil) options • reuse_win (boolean) Jump to existing window if buffer is already open. @@ -1805,63 +2011,22 @@ stylize_markdown({bufnr}, {contents}, {opts}) Parameters: ~ • {contents} (table) of lines to show in window - • {opts} dictionary with optional fields + • {opts} (table) with optional fields • height of floating window • width of floating window • wrap_at character to wrap at for computing height • max_width maximal width of floating window • max_height maximal height of floating window - • pad_top number of lines to pad contents at top - • pad_bottom number of lines to pad contents at bottom • separator insert separator after code block Return: ~ - width,height size of float + (table) stripped content symbols_to_items({symbols}, {bufnr}) *vim.lsp.util.symbols_to_items()* Converts symbols to quickfix list items. Parameters: ~ - • {symbols} DocumentSymbol[] or SymbolInformation[] - - *vim.lsp.util.text_document_completion_list_to_complete_items()* -text_document_completion_list_to_complete_items({result}, {prefix}) - Turns the result of a `textDocument/completion` request into - vim-compatible |complete-items|. - - Parameters: ~ - • {result} The result of a `textDocument/completion` call, e.g. from - |vim.lsp.buf.completion()|, which may be one of - `CompletionItem[]`, `CompletionList` or `null` - • {prefix} (string) the prefix to filter the completion items - - Return: ~ - { matches = complete-items table, incomplete = bool } - - See also: ~ - |complete-items| - -trim_empty_lines({lines}) *vim.lsp.util.trim_empty_lines()* - Removes empty lines from the beginning and end. - - Parameters: ~ - • {lines} (table) list of lines to trim - - Return: ~ - (table) trimmed list of lines - - *vim.lsp.util.try_trim_markdown_code_blocks()* -try_trim_markdown_code_blocks({lines}) - Accepts markdown lines and tries to reduce them to a filetype if they - comprise just a single code block. - - CAUTION: Modifies the input in-place! - - Parameters: ~ - • {lines} (table) list of lines - - Return: ~ - (string) filetype or "markdown" if it was unchanged. + • {symbols} (table) DocumentSymbol[] or SymbolInformation[] ============================================================================== @@ -1877,7 +2042,7 @@ get_level() *vim.lsp.log.get_level()* Gets the current log level. Return: ~ - (string) current log level + (integer) current log level set_format_func({handle}) *vim.lsp.log.set_format_func()* Sets formatting function used to format logs @@ -1890,13 +2055,13 @@ set_level({level}) *vim.lsp.log.set_level()* Sets the current log level. Parameters: ~ - • {level} (string|number) One of `vim.lsp.log.levels` + • {level} (string|integer) One of `vim.lsp.log.levels` should_log({level}) *vim.lsp.log.should_log()* Checks whether the level is sufficient for logging. Parameters: ~ - • {level} (number) log level + • {level} (integer) log level Return: ~ (bool) true if would log, false if not @@ -1911,7 +2076,7 @@ connect({host}, {port}) *vim.lsp.rpc.connect()* Parameters: ~ • {host} (string) - • {port} (number) + • {port} (integer) Return: ~ (function) @@ -1933,7 +2098,7 @@ notify({method}, {params}) *vim.lsp.rpc.notify()* • {params} (table|nil) Parameters for the invoked LSP method Return: ~ - (bool) `true` if notification could be sent, `false` if not + (boolean) `true` if notification could be sent, `false` if not *vim.lsp.rpc.request()* request({method}, {params}, {callback}, {notify_reply_callback}) @@ -1943,20 +2108,21 @@ request({method}, {params}, {callback}, {notify_reply_callback}) • {method} (string) The invoked LSP method • {params} (table|nil) Parameters for the invoked LSP method - • {callback} (function) Callback to invoke + • {callback} fun(err: lsp.ResponseError | nil, result: + any) Callback to invoke • {notify_reply_callback} (function|nil) Callback to invoke as soon as a request is no longer pending Return: ~ - (bool, number) `(true, message_id)` if request could be sent, `false` - if not + (boolean) success, integer|nil request_id true, message_id if request + could be sent, `false` if not *vim.lsp.rpc.rpc_response_error()* rpc_response_error({code}, {message}, {data}) Creates an RPC response object/table. Parameters: ~ - • {code} (number) RPC error code defined in + • {code} (integer) RPC error code defined in `vim.lsp.protocol.ErrorCodes` • {message} (string|nil) arbitrary message to send to server • {data} any|nil arbitrary data to send to server @@ -1986,8 +2152,7 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params}) for LSP server process Return: ~ - Client RPC object. - Methods: + (table|nil) Client RPC object, with these methods: • `notify()` |vim.lsp.rpc.notify()| • `request()` |vim.lsp.rpc.request()| • `is_closing()` returns a boolean indicating if the RPC is closing. @@ -1995,27 +2160,6 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params}) ============================================================================== -Lua module: vim.lsp.sync *lsp-sync* - - *vim.lsp.sync.compute_diff()* -compute_diff({___MissingCloseParenHere___}) - Returns the range table for the difference between prev and curr lines - - Parameters: ~ - • {prev_lines} (table) list of lines - • {curr_lines} (table) list of lines - • {firstline} (number) line to begin search for first difference - • {lastline} (number) line to begin search in old_lines for last - difference - • {new_lastline} (number) line to begin search in new_lines for last - difference - • {offset_encoding} (string) encoding requested by language server - - Return: ~ - (table) TextDocumentContentChangeEvent see https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentContentChangeEvent - - -============================================================================== Lua module: vim.lsp.protocol *lsp-protocol* *vim.lsp.protocol.make_client_capabilities()* @@ -2023,6 +2167,15 @@ make_client_capabilities() Gets a new ClientCapabilities object describing the LSP client capabilities. + Return: ~ + lsp.ClientCapabilities + +Methods *vim.lsp.protocol.Methods* + LSP method names. + + See also: ~ + • https://microsoft.github.io/language-server-protocol/specifications/specification-current/#metaModel + *vim.lsp.protocol.resolve_capabilities()* resolve_capabilities({server_capabilities}) Creates a normalized object describing LSP server capabilities. @@ -2032,6 +2185,6 @@ resolve_capabilities({server_capabilities}) server Return: ~ - (table) Normalized table of capabilities + (table|nil) Normalized table of capabilities vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt index b971a7d2ad..c15b1b0495 100644 --- a/runtime/doc/lua-guide.txt +++ b/runtime/doc/lua-guide.txt @@ -10,16 +10,16 @@ ============================================================================== Introduction *lua-guide* -This guide will go through the basics of using Lua in Neovim. It is not meant +This guide will go through the basics of using Lua in Nvim. It is not meant to be a comprehensive encyclopedia of all available features, nor will it detail all intricacies. Think of it as a survival kit -- the bare minimum -needed to know to comfortably get started on using Lua in Neovim. +needed to know to comfortably get started on using Lua in Nvim. An important thing to note is that this isn't a guide to the Lua language -itself. Rather, this is a guide on how to configure and modify Neovim through +itself. Rather, this is a guide on how to configure and modify Nvim through the Lua language and the functions we provide to help with this. Take a look at |luaref| and |lua-concepts| if you'd like to learn more about Lua itself. -Similarly, this guide assumes some familiarity with the basics of Neovim +Similarly, this guide assumes some familiarity with the basics of Nvim (commands, options, mappings, autocommands), which are covered in the |user-manual|. @@ -27,22 +27,22 @@ Similarly, this guide assumes some familiarity with the basics of Neovim Some words on the API *lua-guide-api* The purpose of this guide is to introduce the different ways of interacting -with Neovim through Lua (the "API"). This API consists of three different +with Nvim through Lua (the "API"). This API consists of three different layers: -1. The "Vim API" inherited from Vim: |ex-commands| and |builtin-functions| as +1. The "Vim API" inherited from Vim: |Ex-commands| and |builtin-functions| as well as |user-function|s in Vimscript. These are accessed through |vim.cmd()| and |vim.fn| respectively, which are discussed under |lua-guide-vimscript| below. -2. The "Neovim API" written in C for use in remote plugins and GUIs; see |api|. +2. The "Nvim API" written in C for use in remote plugins and GUIs; see |api|. These functions are accessed through |vim.api|. 3. The "Lua API" written in and specifically for Lua. These are any other functions accessible through `vim.*` not mentioned already; see |lua-stdlib|. This distinction is important, as API functions inherit behavior from their -original layer: For example, Neovim API functions always need all arguments to +original layer: For example, Nvim API functions always need all arguments to be specified even if Lua itself allows omitting arguments (which are then passed as `nil`); and Vim API functions can use 0-based indexing even if Lua arrays are 1-indexed by default. @@ -58,7 +58,7 @@ convenient to use from Lua. ============================================================================== Using Lua *lua-guide-using-Lua* -To run Lua code from the Neovim command line, use the |:lua| command: +To run Lua code from the Nvim command line, use the |:lua| command: >vim :lua print("Hello!") < @@ -69,10 +69,10 @@ local keyword are not accessible outside of the command. This won't work: :lua print(foo) " prints "nil" instead of "1" < -You can also use `:lua=`, which is the same as `:lua vim.pretty_print(...)`, -to conveniently check the value of a variable or a table: ->lua - :lua=package +You can also use `:lua=`, which is equivalent to `:lua vim.print(...)`, to +conveniently check the value of a variable or a table: +>vim + :lua =package < To run a Lua script in an external file, you can use the |:source| command exactly like for a Vimscript file: @@ -80,7 +80,7 @@ exactly like for a Vimscript file: :source ~/programs/baz/myluafile.lua < Finally, you can include Lua code in a Vimscript file by putting it inside a -|lua-heredoc| block: +|:lua-heredoc| block: >vim lua << EOF local tbl = {1, 2, 3} @@ -92,7 +92,7 @@ Finally, you can include Lua code in a Vimscript file by putting it inside a ------------------------------------------------------------------------------ Using Lua files on startup *lua-guide-config* -Neovim supports using `init.vim` or `init.lua` as the configuration file, but +Nvim supports using `init.vim` or `init.lua` as the configuration file, but not both at the same time. This should be placed in your |config| directory, which is typically `~/.config/nvim` for Linux, BSD, or macOS, and `~/AppData/Local/nvim/` for Windows. Note that you can use Lua in `init.vim` @@ -114,10 +114,10 @@ Let's assume you have the following directory structure: |-- after/ |-- ftplugin/ |-- lua/ - | |-- myluamodule.lua - | |-- other_modules/ - | |-- anothermodule.lua - | |-- init.lua + | |-- myluamodule.lua + | |-- other_modules/ + | |-- anothermodule.lua + | |-- init.lua |-- plugin/ |-- syntax/ |-- init.vim @@ -167,8 +167,8 @@ the cache manually first: < ------------------------------------------------------------------------------ See also: -• |lua-require| -• |luaref-pcall()| +• |lua-module-load| +• |pcall()| ============================================================================== Using Vim commands and functions from Lua *lua-guide-vimscript* @@ -186,7 +186,7 @@ Note that special characters will need to be escaped with backslashes: >lua vim.cmd("%s/\\Vfoo/bar/g") < -An alternative is to use a literal string (see |luaref-literal|) delimited by +An alternative is to use a literal string (see |lua-literal|) delimited by double brackets `[[ ]]` as in >lua vim.cmd([[%s/\Vfoo/bar/g]]) @@ -199,8 +199,8 @@ this allows you to pass multiple commands to a single call of |vim.cmd()|: highlight link Warning Error ]]) < -This is the converse of |lua-heredoc| and allows you to include Vimscript code in -your `init.lua`. +This is the converse of |:lua-heredoc| and allows you to include Vimscript +code in your `init.lua`. If you want to build your Vim command programmatically, the following form can be useful (all these are equivalent to the corresponding line above): @@ -218,7 +218,7 @@ Vimscript are automatically converted: print(vim.fn.printf('Hello from %s', 'Lua')) local reversed_list = vim.fn.reverse({ 'a', 'b', 'c' }) - print(vim.inspect(reversed_list)) -- { "c", "b", "a" } + vim.print(reversed_list) -- { "c", "b", "a" } local function print_stdout(chan_id, data, name) print(data[1]) @@ -261,7 +261,7 @@ Data types are converted automatically. For example: key2 = 300 } - print(vim.inspect(vim.g.some_global_variable)) + vim.print(vim.g.some_global_variable) --> { key1 = "value", key2 = 300 } < You can target specific buffers (via number), windows (via |window-ID|), or @@ -279,7 +279,7 @@ Note that you cannot directly change fields of array variables. This won't work: >lua vim.g.some_global_variable.key2 = 400 - vim.pretty_print(vim.g.some_global_variable) + vim.print(vim.g.some_global_variable) --> { key1 = "value", key2 = 300 } < Instead, you need to create an intermediate Lua table and change this: @@ -287,7 +287,7 @@ Instead, you need to create an intermediate Lua table and change this: local temp_table = vim.g.some_global_variable temp_table.key2 = 400 vim.g.some_global_variable = temp_table - vim.pretty_print(vim.g.some_global_variable) + vim.print(vim.g.some_global_variable) --> { key1 = "value", key2 = 400 } < To delete a variable, simply set it to `nil`: @@ -350,7 +350,7 @@ use |vim.opt:get()|: --> {...} (big table) print(vim.opt.smarttab:get()) --> false - vim.pretty_print(vim.opt.listchars:get()) + vim.print(vim.opt.listchars:get()) --> { space = '_', tab = '>~' } < ------------------------------------------------------------------------------ @@ -363,7 +363,7 @@ and `:let &listchars='space:_,tab:>~'`: • |vim.o|: behaves like |:set| • |vim.go|: behaves like |:setglobal| • |vim.bo|: for buffer-scoped options -• |vim.wo|: for window-scoped options +• |vim.wo|: for window-scoped options (can be double indexed) For example: >lua @@ -386,6 +386,9 @@ window is used: >lua vim.bo[4].expandtab = true -- sets expandtab to true in buffer 4 vim.wo.number = true -- sets number to true in current window + vim.wo[0].number = true -- same as above + vim.wo[0][0].number = true -- sets number to true in current buffer + -- in current window only print(vim.wo[0].number) --> true < ------------------------------------------------------------------------------ @@ -459,9 +462,9 @@ useful options: vim.keymap.set('n', '<Leader>pl1', require('plugin').action, { desc = 'Execute action from plugin' }) < -• `remap`: By default, all mappings are nonrecursive by default (i.e., - |vim.keymap.set()| behaves like |:noremap|). If the {rhs} is itself a mapping - that should be executed, set `remap = true`: >lua +• `remap`: By default, all mappings are nonrecursive (i.e., |vim.keymap.set()| + behaves like |:noremap|). If the {rhs} is itself a mapping that should be + executed, set `remap = true`: >lua vim.keymap.set('n', '<Leader>ex1', '<cmd>echo "Example 1"<cr>') -- add a shorter mapping vim.keymap.set('n', 'e', '<Leader>ex1', { remap = true }) @@ -488,7 +491,7 @@ Autocommands *lua-guide-autocommands* An |autocommand| is a Vim command or a Lua function that is automatically executed whenever one or more |events| are triggered, e.g., when a file is read or written, or when a window is created. These are accessible from Lua -through the Neovim API. +through the Nvim API. ------------------------------------------------------------------------------ Creating autocommands *lua-guide-autocommand-create* @@ -530,7 +533,7 @@ Examples: }) < -Neovim will always call a Lua function with a single table containing information +Nvim will always call a Lua function with a single table containing information about the triggered autocommand. The most useful keys are • `match`: a string that matched the `pattern` (see |<amatch>|) • `buf`: the number of the buffer the event was triggered in (see |<abuf>|) @@ -539,7 +542,7 @@ about the triggered autocommand. The most useful keys are For example, this allows you to set buffer-local mappings for some filetypes: >lua - vim.api.nvim.create_autocmd("FileType", { + vim.api.nvim_create_autocmd("FileType", { pattern = "lua", callback = function(args) vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf }) @@ -624,9 +627,9 @@ in a different file: >lua local mygroup = vim.api.nvim_create_augroup('vimrc', { clear = false }) vim.api.nvim_create_autocmd({ 'BufNewFile', 'BufRead' }, { - pattern = '*.html', + pattern = '*.c', group = mygroup, - command = 'set shiftwidth=4', + command = 'set noexpandtab', }) < ------------------------------------------------------------------------------ @@ -657,7 +660,7 @@ See also • |nvim_exec_autocmds()|: execute all matching autocommands ============================================================================== -User commands *lua-guide-usercommands* +User commands *lua-guide-commands* |user-commands| are custom Vim commands that call a Vimscript or Lua function. Just like built-in commands, they can have arguments, act on ranges, or have @@ -665,11 +668,10 @@ custom completion of arguments. As these are most useful for plugins, we will cover only the basics of this advanced topic. ------------------------------------------------------------------------------ -Creating user commands *lua-guide-usercommands-create* +Creating user commands *lua-guide-commands-create* -User commands can be created through the Neovim API with -`vim.api.`|nvim_create_user_command()|. This function takes three mandatory -arguments: +User commands can be created via |nvim_create_user_command()|. This function +takes three mandatory arguments: • a string that is the name of the command (which must start with an uppercase letter to distinguish it from builtin commands); • a string containing Vim commands or a Lua function that is executed when the @@ -734,7 +736,7 @@ the remaining arguments are the same as for |nvim_create_user_command()|: { nargs = 1 }) < ------------------------------------------------------------------------------ -Deleting user commands *lua-guide-usercommands-delete* +Deleting user commands *lua-guide-commands-delete* User commands can be deleted with `vim.api.`|nvim_del_user_command()|. The only argument is the name of the command: diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 47249a484b..a35d70cae8 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -14,7 +14,7 @@ INTRODUCTION *lua-intro* The Lua 5.1 script engine is builtin and always available. Try this command to get an idea of what lurks beneath: >vim - :lua print(vim.inspect(package.loaded)) + :lua vim.print(package.loaded) Nvim includes a "standard library" |lua-stdlib| for Lua. It complements the "editor stdlib" (|builtin-functions| and |Ex-commands|) and the |API|, all of @@ -33,6 +33,22 @@ Lua 5.1, not worry about forward-compatibility with future Lua versions. If Nvim ever ships with Lua 5.4+, a Lua 5.1 compatibility shim will be provided so that old plugins continue to work transparently. + *lua-luajit* +Nvim is built with luajit on platforms which support it, which provides +extra functionality. Lua code in |init.lua| and plugins can assume its presence +on installations on common platforms. For maximum compatibility with less +common platforms, availability can be checked using the `jit` global variable: >lua + if jit then + -- code for luajit + else + -- code for plain lua 5.1 + end +< + *lua-bit* +In particular, the luajit "bit" extension module is _always_ available. +A fallback implementation is included when nvim is built with PUC Lua 5.1, +and will be transparently used when `require("bit")` is invoked. + ============================================================================== LUA CONCEPTS AND IDIOMS *lua-concepts* @@ -46,15 +62,32 @@ programming": tables, closures, and coroutines. https://www.lua.org/doc/cacm2018.pdf - Tables are the "object" or container datastructure: they represent both lists and maps, you can extend them to represent your own datatypes and - change their behavior using |luaref-metatable| (like Python's "datamodel"). + change their behavior using |metatable|s (like Python's "datamodel"). - EVERY scope in Lua is a closure: a function is a closure, a module is - a closure, a `do` block (|luaref-do|) is a closure--and they all work the - same. A Lua module is literally just a big closure discovered on the "path" + a closure, a `do` block (|lua-do|) is a closure--and they all work the same. + A Lua module is literally just a big closure discovered on the "path" (where your modules are found: |package.cpath|). - Stackful coroutines enable cooperative multithreading, generators, and versatile control for both Lua and its host (Nvim). - *lua-call-function* + *iterator* +An iterator is just a function that can be called repeatedly to get the "next" +value of a collection (or any other |iterable|). This interface is expected by +|for-in| loops, produced by |pairs()|, supported by |vim.iter|, etc. +https://www.lua.org/pil/7.1.html + + *iterable* +An "iterable" is anything that |vim.iter()| can consume: tables, dicts, lists, +iterator functions, tables implementing the |__call()| metamethod, and +|vim.iter()| objects. + + *list-iterator* +Iterators on |lua-list| tables have a "middle" and "end", whereas iterators in +general may be logically infinite. Therefore some |vim.iter| operations (e.g. +|Iter:rev()|) make sense only on list-like tables (which are finite by +definition). + + *lua-function-call* Lua functions can be called in multiple ways. Consider the function: >lua local foo = function(a, b) print("A: ", a) @@ -67,21 +100,19 @@ The first way to call this function is: >lua -- A: 1 -- B: 2 -This way of calling a function is familiar from most scripting languages. -In Lua, any missing arguments are passed as `nil`. Example: >lua +This way of calling a function is familiar from most scripting languages. In +Lua, any missing arguments are passed as `nil`, and extra parameters are +silently discarded. Example: >lua foo(1) -- ==== Result ==== -- A: 1 -- B: nil - -Furthermore it is not an error if extra parameters are passed, they are just -discarded. - +< *kwargs* When calling a function, you can omit the parentheses if the function takes exactly one string literal (`"foo"`) or table literal (`{1,2,3}`). The latter -is often used to approximate "named parameters" ("kwargs" or "keyword args") -as in languages like Python and C#. Example: >lua +is often used to mimic "named parameters" ("kwargs" or "keyword args") as in +languages like Python and C#. Example: >lua local func_with_opts = function(opts) local will_do_foo = opts.foo local filename = opts.filename @@ -92,21 +123,16 @@ as in languages like Python and C#. Example: >lua < There's nothing special going on here except that parentheses are treated as whitespace. But visually, this small bit of sugar gets reasonably close to -a "keyword args" interface. - -It is of course also valid to call the function with parentheses: >lua - func_with_opts({ foo = true, filename = "hello.world" }) -< -Nvim tends to prefer the keyword args style. +a "keyword args" interface. Nvim code tends to prefer this style. ------------------------------------------------------------------------------ LUA PATTERNS *lua-patterns* Lua intentionally does not support regular expressions, instead it has limited -"patterns" |luaref-patterns| which avoid the performance pitfalls of extended +"patterns" |lua-pattern| which avoid the performance pitfalls of extended regex. Lua scripts can also use Vim regex via |vim.regex()|. -These examples use |string.match()| to demonstrate Lua patterns: >lua +Examples: >lua print(string.match("foo123bar123", "%d+")) -- 123 @@ -118,7 +144,7 @@ These examples use |string.match()| to demonstrate Lua patterns: >lua -- .bar ============================================================================== -IMPORTING LUA MODULES *require()* *lua-require* +IMPORTING LUA MODULES *lua-module-load* Modules are searched for under the directories specified in 'runtimepath', in the order they appear. Any "." in the module name is treated as a directory @@ -132,7 +158,7 @@ back to Lua's default search mechanism. The first script found is run and The return value is cached after the first call to `require()` for each module, with subsequent calls returning the cached value without searching for, or -executing any script. For further details on `require()`, see |luaref-require()|. +executing any script. For further details see |require()|. For example, if 'runtimepath' is `foo,bar` and |package.cpath| was `./?.so;./?.dll` at startup, `require('mod')` searches these paths in order @@ -217,11 +243,11 @@ command calls. The |lua-stdlib| modules, user modules, and anything else on The Lua print() function redirects its output to the Nvim message area, with arguments separated by " " (space) instead of "\t" (tab). - *:lua* + *:lua=* *:lua* :lua {chunk} Executes Lua chunk {chunk}. If {chunk} starts with "=" the rest of the - chunk is evaluated as an expression and printed. `:lua =expr` is - equivalent to `:lua print(vim.inspect(expr))` + chunk is evaluated as an expression and printed. `:lua =expr` or `:=expr` is + equivalent to `:lua print(vim.inspect(expr))`. Examples: >vim :lua vim.api.nvim_command('echo "Hello, Nvim!"') @@ -231,12 +257,12 @@ arguments separated by " " (space) instead of "\t" (tab). :lua =jit.version < *:lua-heredoc* -:lua << [endmarker] +:lua << [trim] [{endmarker}] {script} {endmarker} - Executes Lua script {script} from within Vimscript. {endmarker} must NOT - be preceded by whitespace. You can omit [endmarker] after the "<<" and use - a dot "." after {script} (similar to |:append|, |:insert|). + Executes Lua script {script} from within Vimscript. You can omit + [endmarker] after the "<<" and use a dot "." after {script} (similar to + |:append|, |:insert|). Refer to |:let-heredoc| for more information. Example: >vim function! CurrentLineInfo() @@ -280,7 +306,7 @@ arguments separated by " " (space) instead of "\t" (tab). < ============================================================================== -luaeval() *lua-eval* *luaeval()* +luaeval() *lua-eval* The (dual) equivalent of "vim.eval" for passing Lua values to Nvim is "luaeval". "luaeval" takes an expression string and an optional argument used @@ -305,14 +331,16 @@ Example: >vim :echo luaeval('string.match(_A, "[a-z]+")', 'XYXfoo123') " foo < + *lua-table-ambiguous* Lua tables are used as both dictionaries and lists, so it is impossible to determine whether empty table is meant to be empty list or empty dictionary. Additionally Lua does not have integer numbers. To distinguish between these cases there is the following agreement: - + *lua-list* 0. Empty table is empty list. -1. Table with N incrementally growing integral numbers, starting from 1 and - ending with N is considered to be a list. +1. Table with N consecutive integer indices starting from 1 and ending with + N is considered a list. See also |list-iterator|. + *lua-dict* 2. Table with string keys, none of which contains NUL byte, is considered to be a dictionary. 3. Table with string keys, at least one of which contains NUL byte, is also @@ -383,7 +411,7 @@ For example consider the following Lua omnifunc handler: >lua return {'stuff', 'steam', 'strange things'} end end - vim.api.nvim_buf_set_option(0, 'omnifunc', 'v:lua.mymod.omnifunc') + vim.bo[buf].omnifunc = 'v:lua.mymod.omnifunc' Note: The module ("mymod" in the above example) must either be a Lua global, or use require() as shown above to access it from a package. @@ -405,7 +433,7 @@ is unnecessary. You can peek at the module properties: >vim - :lua print(vim.inspect(vim)) + :lua vim.print(vim) Result is something like this: > @@ -431,29 +459,24 @@ Note that underscore-prefixed functions (e.g. "_os_proc_children") are internal/private and must not be used by plugins. ------------------------------------------------------------------------------ -VIM.LOOP *lua-loop* *vim.loop* +VIM.UV *lua-loop* *vim.uv* -`vim.loop` exposes all features of the Nvim event-loop. This is a low-level -API that provides functionality for networking, filesystem, and process -management. Try this command to see available functions: >vim - - :lua print(vim.inspect(vim.loop)) -< -Internally, `vim.loop` wraps the "luv" Lua bindings for the LibUV library; -see |luv-intro| for a full reference manual. +`vim.uv` exposes the "luv" Lua bindings for the libUV library that Nvim uses +for networking, filesystem, and process management, see |luvref.txt|. +In particular, it allows interacting with the main Nvim |luv-event-loop|. *E5560* *lua-loop-callbacks* It is an error to directly invoke `vim.api` functions (except |api-fast|) in -`vim.loop` callbacks. For example, this is an error: >lua +`vim.uv` callbacks. For example, this is an error: >lua - local timer = vim.loop.new_timer() + local timer = vim.uv.new_timer() timer:start(1000, 0, function() vim.api.nvim_command('echomsg "test"') end) < To avoid the error use |vim.schedule_wrap()| to defer the callback: >lua - local timer = vim.loop.new_timer() + local timer = vim.uv.new_timer() timer:start(1000, 0, vim.schedule_wrap(function() vim.api.nvim_command('echomsg "test"') end)) @@ -466,7 +489,7 @@ Example: repeating timer 2. Execute it with ":luafile %". >lua -- Create a timer handle (implementation detail: uv_timer_t). - local timer = vim.loop.new_timer() + local timer = vim.uv.new_timer() local i = 0 -- Waits 1000ms, then repeats every 750ms until timer:close(). timer:start(1000, 750, function() @@ -486,7 +509,7 @@ Example: File-change detection *watch-file* 5. Observe that the file reloads in Nvim (because on_change() calls |:checktime|). >lua - local w = vim.loop.new_fs_event() + local w = vim.uv.new_fs_event() local function on_change(err, fname, status) -- Do work... vim.api.nvim_command('checktime') @@ -510,11 +533,11 @@ Example: TCP echo-server *tcp-server* 4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >lua local function create_server(host, port, on_connect) - local server = vim.loop.new_tcp() + local server = vim.uv.new_tcp() server:bind(host, port) server:listen(128, function(err) assert(not err, err) -- Check for errors. - local sock = vim.loop.new_tcp() + local sock = vim.uv.new_tcp() server:accept(sock) -- Accept client connection. on_connect(sock) -- Start reading messages. end) @@ -535,105 +558,139 @@ Example: TCP echo-server *tcp-server* Multithreading *lua-loop-threading* Plugins can perform work in separate (os-level) threads using the threading -APIs in luv, for instance `vim.loop.new_thread`. Note that every thread -gets its own separate lua interpreter state, with no access to lua globals +APIs in luv, for instance `vim.uv.new_thread`. Note that every thread +gets its own separate Lua interpreter state, with no access to Lua globals in the main thread. Neither can the state of the editor (buffers, windows, etc) be directly accessed from threads. A subset of the `vim.*` API is available in threads. This includes: -- `vim.loop` with a separate event loop per thread. +- `vim.uv` with a separate event loop per thread. - `vim.mpack` and `vim.json` (useful for serializing messages between threads) -- `require` in threads can use lua packages from the global |package.path| +- `require` in threads can use Lua packages from the global |package.path| - `print()` and `vim.inspect` - `vim.diff` -- most utility functions in `vim.*` for working with pure lua values +- most utility functions in `vim.*` for working with pure Lua values like `vim.split`, `vim.tbl_*`, `vim.list_*`, and so on. - `vim.is_thread()` returns true from a non-main thread. ------------------------------------------------------------------------------ -VIM.HIGHLIGHT *lua-highlight* +VIM.LPEG *lua-lpeg* + + *vim.lpeg* *vim.re* +The Lpeg library for parsing expression grammars is being included as +`vim.lpeg` (https://www.inf.puc-rio.br/~roberto/lpeg/). In addition, its regex-like +interface is available as `vim.re` (https://www.inf.puc-rio.br/~roberto/lpeg/re.html). -Nvim includes a function for highlighting a selection on yank (see for example -https://github.com/machakann/vim-highlightedyank). To enable it, add ->vim +============================================================================== +VIM.HIGHLIGHT *vim.highlight* + + +Nvim includes a function for highlighting a selection on yank. + +To enable it, add the following to your `init.vim`: >vim au TextYankPost * silent! lua vim.highlight.on_yank() + < -to your `init.vim`. You can customize the highlight group and the duration of -the highlight via ->vim + +You can customize the highlight group and the duration of the highlight +via: >vim au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150} + < -If you want to exclude visual selections from highlighting on yank, use ->vim + +If you want to exclude visual selections from highlighting on yank, use: >vim au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} + < + vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* - Highlights the yanked text. The fields of the optional dict {opts} - control the highlight: - - {higroup} highlight group for yanked region (default |hl-IncSearch|) - - {timeout} time in ms before highlight is cleared (default `150`) - - {on_macro} highlight when executing macro (default `false`) - - {on_visual} highlight when yanking visual selection (default `true`) - - {event} event structure (default |v:event|) - -vim.highlight.range({bufnr}, {ns}, {hlgroup}, {start}, {finish}, {opts}) - *vim.highlight.range()* + Highlight the yanked text + + Parameters: ~ + • {opts} (table|nil) Optional parameters + • higroup highlight group for yanked region (default + "IncSearch") + • timeout time in ms before highlight is cleared (default 150) + • on_macro highlight when executing macro (default false) + • on_visual highlight when yanking visual selection (default + true) + • event event structure (default vim.v.event) + • priority integer priority (default + |vim.highlight.priorities|`.user`) + +vim.highlight.priorities *vim.highlight.priorities* + Table with default priorities used for highlighting: + • `syntax`: `50`, used for standard syntax highlighting + • `treesitter`: `100`, used for tree-sitter-based highlighting + • `semantic_tokens`: `125`, used for LSP semantic token highlighting + • `diagnostics`: `150`, used for code analysis such as diagnostics + • `user`: `200`, used for user-triggered highlights such as LSP document + symbols or `on_yank` autocommands + *vim.highlight.range()* +vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) Apply highlight group to range of text. - Parameters: ~ - • {bufnr} buffer number - • {ns} namespace for highlights - • {hlgroup} highlight group name - • {start} starting position (tuple {line,col}) - • {finish} finish position (tuple {line,col}) - • {opts} optional parameters: - • `regtype`: type of range (characterwise, linewise, - or blockwise, see |setreg()|), default `'v'` - • `inclusive`: range includes end position, - default `false` - • `priority`: priority of highlight, default - `vim.highlight.user` (see below) + Parameters: ~ + • {bufnr} (integer) Buffer number to apply highlighting to + • {ns} (integer) Namespace to add highlight to + • {higroup} (string) Highlight group to use for highlighting + • {start} integer[]|string Start of region as a (line, column) tuple + or string accepted by |getpos()| + • {finish} integer[]|string End of region as a (line, column) tuple or + string accepted by |getpos()| + • {opts} (table|nil) Optional parameters + • regtype type of range (see |setreg()|, default charwise) + • inclusive boolean indicating whether the range is + end-inclusive (default false) + • priority number indicating priority of highlight (default + priorities.user) -vim.highlight.priorities *vim.highlight.priorities* - Table with default priorities used for highlighting: - • `syntax`: `50`, used for standard syntax highlighting - • `treesitter`: `100`, used for tree-sitter-based highlighting - • `semantic_tokens`: `125`, used for LSP semantic token highlighting - • `diagnostics`: `150`, used for code analysis such as diagnostics - • `user`: `200`, used for user-triggered highlights such as LSP document - symbols or `on_yank` autocommands +============================================================================== +VIM.REGEX *vim.regex* ------------------------------------------------------------------------------- -VIM.REGEX *lua-regex* -Vim regexes can be used directly from lua. Currently they only allow +Vim regexes can be used directly from Lua. Currently they only allow matching within a single line. + vim.regex({re}) *vim.regex()* Parse the Vim regex {re} and return a regex object. Regexes are "magic" and case-sensitive by default, regardless of 'magic' and 'ignorecase'. They can be controlled with flags, see |/magic| and |/ignorecase|. -Methods on the regex object: + Parameters: ~ + • {re} (string) -regex:match_str({str}) *regex:match_str()* - Match the string against the regex. If the string should match the regex - precisely, surround the regex with `^` and `$`. If the was a match, the - byte indices for the beginning and end of the match is returned. When - there is no match, `nil` is returned. As any integer is truth-y, - `regex:match()` can be directly used as a condition in an if-statement. + Return: ~ + vim.regex -regex:match_line({bufnr}, {line_idx} [, {start}, {end}]) *regex:match_line()* + *regex:match_line()* +vim.regex:match_line({bufnr}, {line_idx}, {start}, {end_}) Match line {line_idx} (zero-based) in buffer {bufnr}. If {start} and {end} are supplied, match only this byte index range. Otherwise see |regex:match_str()|. If {start} is used, then the returned byte indices will be relative {start}. ------------------------------------------------------------------------------- -VIM.DIFF *lua-diff* + Parameters: ~ + • {bufnr} (integer) + • {line_idx} (integer) + • {start} (integer|nil) + • {end_} (integer|nil) + +vim.regex:match_str({str}) *regex:match_str()* + Match the string against the regex. If the string should match the regex + precisely, surround the regex with `^` and `$` . If there was a match, the byte indices for the beginning and end of the + match are returned. When there is no match, `nil` is returned. Because any integer is "truthy", `regex:match_str()` can be directly used as a condition in an if-statement. + + Parameters: ~ + • {str} (string) + + +============================================================================== +VIM.DIFF *vim.diff* vim.diff({a}, {b}, {opts}) *vim.diff()* Run diff on strings {a} and {b}. Any indices returned by this function, @@ -653,82 +710,135 @@ vim.diff({a}, {b}, {opts}) *vim.diff()* -- {1, 1, 1, 2} -- } < + Parameters: ~ - • {a} First string to compare - • {b} Second string to compare - • {opts} Optional parameters: - • `on_hunk` (callback): - Invoked for each hunk in the diff. Return a negative number - to cancel the callback for any remaining hunks. - Args: - • `start_a` (integer): Start line of hunk in {a}. - • `count_a` (integer): Hunk size in {a}. - • `start_b` (integer): Start line of hunk in {b}. - • `count_b` (integer): Hunk size in {b}. - • `result_type` (string): Form of the returned diff: - • "unified": (default) String in unified format. - • "indices": Array of hunk locations. - Note: This option is ignored if `on_hunk` is used. - • `linematch` (boolean): Run linematch on the resulting hunks - from xdiff. Requires `result_type = indices`, ignored - otherwise. - • `algorithm` (string): - Diff algorithm to use. Values: - • "myers" the default algorithm - • "minimal" spend extra time to generate the - smallest possible diff - • "patience" patience diff algorithm - • "histogram" histogram diff algorithm - • `ctxlen` (integer): Context length - • `interhunkctxlen` (integer): - Inter hunk context length - • `ignore_whitespace` (boolean): - Ignore whitespace - • `ignore_whitespace_change` (boolean): - Ignore whitespace change - • `ignore_whitespace_change_at_eol` (boolean) - Ignore whitespace change at end-of-line. - • `ignore_cr_at_eol` (boolean) - Ignore carriage return at end-of-line - • `ignore_blank_lines` (boolean) - Ignore blank lines - • `indent_heuristic` (boolean): - Use the indent heuristic for the internal - diff library. - - Return: ~ - See {opts.result_type}. nil if {opts.on_hunk} is given. + • {a} (string) First string to compare + • {b} (string) Second string to compare + • {opts} table<string,any> Optional parameters: + • `on_hunk` (callback): Invoked for each hunk in the diff. Return a + negative number to cancel the callback for any remaining + hunks. Args: + • `start_a` (integer): Start line of hunk in {a}. + • `count_a` (integer): Hunk size in {a}. + • `start_b` (integer): Start line of hunk in {b}. + • `count_b` (integer): Hunk size in {b}. + + • `result_type` (string): Form of the returned diff: + • "unified": (default) String in unified format. + • "indices": Array of hunk locations. Note: This option is + ignored if `on_hunk` is used. + + • `linematch` (boolean|integer): Run linematch on the + resulting hunks from xdiff. When integer, only hunks upto + this size in lines are run through linematch. Requires + `result_type = indices`, ignored otherwise. + • `algorithm` (string): Diff algorithm to use. Values: + • "myers" the default algorithm + • "minimal" spend extra time to generate the smallest + possible diff + • "patience" patience diff algorithm + • "histogram" histogram diff algorithm + + • `ctxlen` (integer): Context length + • `interhunkctxlen` (integer): Inter hunk context length + • `ignore_whitespace` (boolean): Ignore whitespace + • `ignore_whitespace_change` (boolean): Ignore whitespace + change + • `ignore_whitespace_change_at_eol` (boolean) Ignore + whitespace change at end-of-line. + • `ignore_cr_at_eol` (boolean) Ignore carriage return at + end-of-line + • `ignore_blank_lines` (boolean) Ignore blank lines + • `indent_heuristic` (boolean): Use the indent heuristic for + the internal diff library. ------------------------------------------------------------------------------- -VIM.MPACK *lua-mpack* + Return: ~ + string|table|nil See {opts.result_type}. `nil` if {opts.on_hunk} is + given. -The *vim.mpack* module provides encoding and decoding of Lua objects to and -from msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. -vim.mpack.encode({obj}) *vim.mpack.encode* - Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. +============================================================================== +VIM.MPACK *vim.mpack* + -vim.mpack.decode({str}) *vim.mpack.decode* +This module provides encoding and decoding of Lua objects to and from +msgpack-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. + +vim.mpack.decode({str}) *vim.mpack.decode()* Decodes (or "unpacks") the msgpack-encoded {str} to a Lua object. ------------------------------------------------------------------------------- -VIM.JSON *lua-json* + Parameters: ~ + • {str} (string) -The *vim.json* module provides encoding and decoding of Lua objects to and -from JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. +vim.mpack.encode({obj}) *vim.mpack.encode()* + Encodes (or "packs") Lua object {obj} as msgpack in a Lua string. -vim.json.encode({obj}) *vim.json.encode* - Encodes (or "packs") Lua object {obj} as JSON in a Lua string. -vim.json.decode({str}[, {opts}]) *vim.json.decode* +============================================================================== +VIM.JSON *vim.json* + + +This module provides encoding and decoding of Lua objects to and from +JSON-encoded strings. Supports |vim.NIL| and |vim.empty_dict()|. + +vim.json.decode({str}, {opts}) *vim.json.decode()* Decodes (or "unpacks") the JSON-encoded {str} to a Lua object. - {opts} is a table with the key `luanil = { object: bool, array: bool }` - that controls whether `null` in JSON objects or arrays should be converted - to Lua `nil` instead of `vim.NIL`. + • Decodes JSON "null" as |vim.NIL| (controllable by {opts}, see below). + • Decodes empty object as |vim.empty_dict()|. + • Decodes empty array as `{}` (empty Lua table). ------------------------------------------------------------------------------- -VIM.SPELL *lua-spell* + Example: >lua + vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}')) + -- { bar = {}, foo = vim.empty_dict(), zub = vim.NIL } +< + + Parameters: ~ + • {str} (string) Stringified JSON data. + • {opts} table<string,any>|nil Options table with keys: + • luanil: (table) Table with keys: + • object: (boolean) When true, converts `null` in JSON + objects to Lua `nil` instead of |vim.NIL|. + • array: (boolean) When true, converts `null` in JSON arrays + to Lua `nil` instead of |vim.NIL|. + + Return: ~ + any + +vim.json.encode({obj}) *vim.json.encode()* + Encodes (or "packs") Lua object {obj} as JSON in a Lua string. + + Parameters: ~ + • {obj} any + + Return: ~ + (string) + + +============================================================================== +VIM.BASE64 *vim.base64* + +vim.base64.decode({str}) *vim.base64.decode()* + Decode a Base64 encoded string. + + Parameters: ~ + • {str} (string) Base64 encoded string + + Return: ~ + (string) Decoded string + +vim.base64.encode({str}) *vim.base64.encode()* + Encode {str} using Base64. + + Parameters: ~ + • {str} (string) String to encode + + Return: ~ + (string) Encoded string + + +============================================================================== +VIM.SPELL *vim.spell* vim.spell.check({str}) *vim.spell.check()* Check {str} for spelling errors. Similar to the Vimscript function @@ -745,268 +855,359 @@ vim.spell.check({str}) *vim.spell.check()* -- {'quik', 'bad', 5} -- } < + Parameters: ~ - • {str} String to spell check. + • {str} (string) Return: ~ - List of tuples with three items: - - The badly spelled word. - - The type of the spelling error: - "bad" spelling mistake - "rare" rare word - "local" word only valid in another region - "caps" word should start with Capital - - The position in {str} where the word begins. + `{[1]: string, [2]: string, [3]: string}[]` List of tuples with three items: + • The badly spelled word. + • The type of the spelling error: "bad" spelling mistake "rare" rare + word "local" word only valid in another region "caps" word should + start with Capital + • The position in {str} where the word begins. ------------------------------------------------------------------------------- -VIM *lua-builtin* -vim.api.{func}({...}) *vim.api* +============================================================================== +VIM *vim.builtin* + + +vim.api.{func}({...}) *vim.api* Invokes Nvim |API| function {func} with arguments {...}. Example: call the "nvim_get_current_line()" API function: >lua print(tostring(vim.api.nvim_get_current_line())) -vim.version() *vim.version* - Gets the version of the current Nvim build. - -vim.in_fast_event() *vim.in_fast_event()* - Returns true if the code is executing as part of a "fast" event handler, - where most of the API is disabled. These are low-level events (e.g. - |lua-loop-callbacks|) which can be invoked whenever Nvim polls for input. - When this is `false` most API functions are callable (but may be subject - to other restrictions such as |textlock|). - -vim.NIL *vim.NIL* +vim.NIL *vim.NIL* Special value representing NIL in |RPC| and |v:null| in Vimscript conversion, and similar cases. Lua `nil` cannot be used as part of a Lua table representing a Dictionary or Array, because it is treated as missing: `{"foo", nil}` is the same as `{"foo"}`. +vim.type_idx *vim.type_idx* + Type index for use in |lua-special-tbl|. Specifying one of the values from + |vim.types| allows typing the empty table (it is unclear whether empty Lua + table represents empty list or empty array) and forcing integral numbers + to be |Float|. See |lua-special-tbl| for more details. + +vim.val_idx *vim.val_idx* + Value index for tables representing |Float|s. A table representing + floating-point value 1.0 looks like this: >lua + { + [vim.type_idx] = vim.types.float, + [vim.val_idx] = 1.0, + } +< See also |vim.type_idx| and |lua-special-tbl|. + +vim.types *vim.types* + Table with possible values for |vim.type_idx|. Contains two sets of + key-value pairs: first maps possible values for |vim.type_idx| to + human-readable strings, second maps human-readable type names to values + for |vim.type_idx|. Currently contains pairs for `float`, `array` and + `dictionary` types. + + Note: One must expect that values corresponding to `vim.types.float`, + `vim.types.array` and `vim.types.dictionary` fall under only two following + assumptions: + 1. Value may serve both as a key and as a value in a table. Given the + properties of Lua tables this basically means “value is not `nil`”. + 2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the + same as `value`. + No other restrictions are put on types, and it is not guaranteed that + values corresponding to `vim.types.float`, `vim.types.array` and + `vim.types.dictionary` will not change or that `vim.types` table will only + contain values for these three types. + + *log_levels* *vim.log.levels* +Log levels are one of the values defined in `vim.log.levels`: + + vim.log.levels.DEBUG + vim.log.levels.ERROR + vim.log.levels.INFO + vim.log.levels.TRACE + vim.log.levels.WARN + vim.log.levels.OFF + vim.empty_dict() *vim.empty_dict()* - Creates a special empty table (marked with a metatable), which Nvim to an - empty dictionary when translating Lua values to Vimscript or API types. - Nvim by default converts an empty table `{}` without this metatable to an - list/array. + Creates a special empty table (marked with a metatable), which Nvim + converts to an empty dictionary when translating Lua values to Vimscript + or API types. Nvim by default converts an empty table `{}` without this + metatable to an list/array. Note: If numeric keys are present in the table, Nvim ignores the metatable marker and converts the dict to a list/array anyway. -vim.rpcnotify({channel}, {method} [, {args}...]) *vim.rpcnotify()* +vim.iconv({str}, {from}, {to}, {opts}) *vim.iconv()* + The result is a String, which is the text {str} converted from encoding + {from} to encoding {to}. When the conversion fails `nil` is returned. When + some characters could not be converted they are replaced with "?". The + encoding names are whatever the iconv() library function can accept, see + ":Man 3 iconv". + + Parameters: ~ + • {str} (string) Text to convert + • {from} (number) Encoding of {str} + • {to} (number) Target encoding + • {opts} table<string,any>|nil + + Return: ~ + (string|nil) Converted string if conversion succeeds, `nil` otherwise. + +vim.in_fast_event() *vim.in_fast_event()* + Returns true if the code is executing as part of a "fast" event handler, + where most of the API is disabled. These are low-level events (e.g. + |lua-loop-callbacks|) which can be invoked whenever Nvim polls for input. + When this is `false` most API functions are callable (but may be subject + to other restrictions such as |textlock|). + +vim.rpcnotify({channel}, {method}, {args}, {...}) *vim.rpcnotify()* Sends {event} to {channel} via |RPC| and returns immediately. If {channel} is 0, the event is broadcast to all channels. This function also works in a fast callback |lua-loop-callbacks|. -vim.rpcrequest({channel}, {method} [, {args}...]) *vim.rpcrequest()* + Parameters: ~ + • {channel} (integer) + • {method} (string) + • {args} any[]|nil + • {...} any|nil + +vim.rpcrequest({channel}, {method}, {args}, {...}) *vim.rpcrequest()* Sends a request to {channel} to invoke {method} via |RPC| and blocks until a response is received. Note: NIL values as part of the return value is represented as |vim.NIL| special value -vim.stricmp({a}, {b}) *vim.stricmp()* - Compares strings case-insensitively. Returns 0, 1 or -1 if strings are - equal, {a} is greater than {b} or {a} is lesser than {b}, respectively. + Parameters: ~ + • {channel} (integer) + • {method} (string) + • {args} any[]|nil + • {...} any|nil -vim.str_utfindex({str} [, {index}]) *vim.str_utfindex()* - Convert byte index to UTF-32 and UTF-16 indices. If {index} is not - supplied, the length of the string is used. All indices are zero-based. - Returns two values: the UTF-32 and UTF-16 indices respectively. +vim.schedule({fn}) *vim.schedule()* + Schedules {fn} to be invoked soon by the main event-loop. Useful to avoid + |textlock| or other temporary restrictions. - Embedded NUL bytes are treated as terminating the string. Invalid UTF-8 - bytes, and embedded surrogates are counted as one code point each. An - {index} in the middle of a UTF-8 sequence is rounded upwards to the end of - that sequence. + Parameters: ~ + • {fn} (function) -vim.str_byteindex({str}, {index} [, {use_utf16}]) *vim.str_byteindex()* +vim.str_byteindex({str}, {index}, {use_utf16}) *vim.str_byteindex()* Convert UTF-32 or UTF-16 {index} to byte index. If {use_utf16} is not supplied, it defaults to false (use UTF-32). Returns the byte index. - Invalid UTF-8 and NUL is treated like by |vim.str_byteindex()|. - An {index} in the middle of a UTF-16 sequence is rounded upwards to - the end of that sequence. + Invalid UTF-8 and NUL is treated like by |vim.str_byteindex()|. An {index} + in the middle of a UTF-16 sequence is rounded upwards to the end of that + sequence. -vim.iconv({str}, {from}, {to}[, {opts}]) *vim.iconv()* - The result is a String, which is the text {str} converted from - encoding {from} to encoding {to}. When the conversion fails `nil` is - returned. When some characters could not be converted they - are replaced with "?". - The encoding names are whatever the iconv() library function - can accept, see ":Man 3 iconv". + Parameters: ~ + • {str} (string) + • {index} (number) + • {use_utf16} any|nil + +vim.str_utf_end({str}, {index}) *vim.str_utf_end()* + Gets the distance (in bytes) from the last byte of the codepoint + (character) that {index} points to. - Parameters: ~ - • {str} (string) Text to convert - • {from} (string) Encoding of {str} - • {to} (string) Target encoding + Examples: >lua + -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8) - Returns: ~ - Converted string if conversion succeeds, `nil` otherwise. + -- Returns 0 because the index is pointing at the last byte of a character + vim.str_utf_end('æ', 2) -vim.schedule({callback}) *vim.schedule()* - Schedules {callback} to be invoked soon by the main event-loop. Useful - to avoid |textlock| or other temporary restrictions. + -- Returns 1 because the index is pointing at the penultimate byte of a character + vim.str_utf_end('æ', 1) +< + Parameters: ~ + • {str} (string) + • {index} (number) + + Return: ~ + (number) -vim.defer_fn({fn}, {timeout}) *vim.defer_fn* - Defers calling {fn} until {timeout} ms passes. Use to do a one-shot timer - that calls {fn}. +vim.str_utf_pos({str}) *vim.str_utf_pos()* + Gets a list of the starting byte positions of each UTF-8 codepoint in the + given string. - Note: The {fn} is |vim.schedule_wrap()|ped automatically, so API functions are - safe to call. + Embedded NUL bytes are treated as terminating the string. Parameters: ~ - • {fn} Callback to call once {timeout} expires - • {timeout} Time in ms to wait before calling {fn} + • {str} (string) - Returns: ~ - |vim.loop|.new_timer() object + Return: ~ + (table) -vim.wait({time} [, {callback}, {interval}, {fast_only}]) *vim.wait()* - Wait for {time} in milliseconds until {callback} returns `true`. +vim.str_utf_start({str}, {index}) *vim.str_utf_start()* + Gets the distance (in bytes) from the starting byte of the codepoint + (character) that {index} points to. - Executes {callback} immediately and at approximately {interval} - milliseconds (default 200). Nvim still processes other events during - this time. + The result can be added to {index} to get the starting byte of a + character. + + Examples: >lua + -- The character 'æ' is stored as the bytes '\xc3\xa6' (using UTF-8) + + -- Returns 0 because the index is pointing at the first byte of a character + vim.str_utf_start('æ', 1) + + -- Returns -1 because the index is pointing at the second byte of a character + vim.str_utf_start('æ', 2) +< Parameters: ~ - • {time} Number of milliseconds to wait - • {callback} Optional callback. Waits until {callback} returns true - • {interval} (Approximate) number of milliseconds to wait between polls - • {fast_only} If true, only |api-fast| events will be processed. - If called from while in an |api-fast| event, will - automatically be set to `true`. + • {str} (string) + • {index} (number) - Returns: ~ - If {callback} returns `true` during the {time}: - `true, nil` + Return: ~ + (number) - If {callback} never returns `true` during the {time}: - `false, -1` +vim.str_utfindex({str}, {index}) *vim.str_utfindex()* + Convert byte index to UTF-32 and UTF-16 indices. If {index} is not + supplied, the length of the string is used. All indices are zero-based. - If {callback} is interrupted during the {time}: - `false, -2` + Embedded NUL bytes are treated as terminating the string. Invalid UTF-8 + bytes, and embedded surrogates are counted as one code point each. An + {index} in the middle of a UTF-8 sequence is rounded upwards to the end of + that sequence. - If {callback} errors, the error is raised. + Parameters: ~ + • {str} (string) + • {index} (number|nil) - Examples: >lua + Return (multiple): ~ + (integer) UTF-32 index + (integer) UTF-16 index - --- - -- Wait for 100 ms, allowing other events to process - vim.wait(100, function() end) +vim.stricmp({a}, {b}) *vim.stricmp()* + Compares strings case-insensitively. - --- - -- Wait for 100 ms or until global variable set. - vim.wait(100, function() return vim.g.waiting_for_var end) + Parameters: ~ + • {a} (string) + • {b} (string) - --- - -- Wait for 1 second or until global variable set, checking every ~500 ms - vim.wait(1000, function() return vim.g.waiting_for_var end, 500) + Return: ~ + 0|1|-1 if strings are equal, {a} is greater than {b} or {a} is lesser + than {b}, respectively. + +vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()* + Attach to ui events, similar to |nvim_ui_attach()| but receive events as + Lua callback. Can be used to implement screen elements like popupmenu or + message handling in Lua. + + {options} should be a dictionary-like table, where `ext_...` options + should be set to true to receive events for the respective external + element. + + {callback} receives event name plus additional parameters. See + |ui-popupmenu| and the sections below for event format for respective + events. + + WARNING: This api is considered experimental. Usability will vary for + different screen elements. In particular `ext_messages` behavior is + subject to further changes and usability improvements. This is expected to + be used to handle messages when setting 'cmdheight' to zero (which is + likewise experimental). - --- - -- Schedule a function to set a value in 100ms - vim.defer_fn(function() vim.g.timer_result = true end, 100) + Example (stub for a |ui-popupmenu| implementation): >lua + ns = vim.api.nvim_create_namespace('my_fancy_pum') - -- Would wait ten seconds if results blocked. Actually only waits 100 ms - if vim.wait(10000, function() return vim.g.timer_result end) then - print('Only waiting a little bit of time!') - end + vim.ui_attach(ns, {ext_popupmenu=true}, function(event, ...) + if event == "popupmenu_show" then + local items, selected, row, col, grid = ... + print("display pum ", #items) + elseif event == "popupmenu_select" then + local selected = ... + print("selected", selected) + elseif event == "popupmenu_hide" then + print("FIN") + end + end) < -vim.ui_attach({ns}, {options}, {callback}) *vim.ui_attach()* - Attach to ui events, similar to |nvim_ui_attach()| but receive events - as lua callback. Can be used to implement screen elements like - popupmenu or message handling in lua. + Parameters: ~ + • {ns} (integer) + • {options} table<string, any> + • {callback} fun() - {options} should be a dictionary-like table, where `ext_...` options should - be set to true to receive events for the respective external element. +vim.ui_detach({ns}) *vim.ui_detach()* + Detach a callback previously attached with |vim.ui_attach()| for the given + namespace {ns}. - {callback} receives event name plus additional parameters. See |ui-popupmenu| - and the sections below for event format for respective events. + Parameters: ~ + • {ns} (integer) - WARNING: This api is considered experimental. Usability will vary for - different screen elements. In particular `ext_messages` behavior is subject - to further changes and usability improvements. This is expected to be - used to handle messages when setting 'cmdheight' to zero (which is - likewise experimental). +vim.wait({time}, {callback}, {interval}, {fast_only}) *vim.wait()* + Wait for {time} in milliseconds until {callback} returns `true`. - Example (stub for a |ui-popupmenu| implementation): >lua + Executes {callback} immediately and at approximately {interval} + milliseconds (default 200). Nvim still processes other events during this + time. - ns = vim.api.nvim_create_namespace('my_fancy_pum') - - vim.ui_attach(ns, {ext_popupmenu=true}, function(event, ...) - if event == "popupmenu_show" then - local items, selected, row, col, grid = ... - print("display pum ", #items) - elseif event == "popupmenu_select" then - local selected = ... - print("selected", selected) - elseif event == "popupmenu_hide" then - print("FIN") - end - end) + Cannot be called while in an |api-fast| event. -vim.ui_detach({ns}) *vim.ui_detach()* - Detach a callback previously attached with |vim.ui_attach()| for the - given namespace {ns}. + Examples: >lua + --- + -- Wait for 100 ms, allowing other events to process + vim.wait(100, function() end) -vim.type_idx *vim.type_idx* - Type index for use in |lua-special-tbl|. Specifying one of the values from - |vim.types| allows typing the empty table (it is unclear whether empty Lua - table represents empty list or empty array) and forcing integral numbers - to be |Float|. See |lua-special-tbl| for more details. + --- + -- Wait for 100 ms or until global variable set. + vim.wait(100, function() return vim.g.waiting_for_var end) -vim.val_idx *vim.val_idx* - Value index for tables representing |Float|s. A table representing - floating-point value 1.0 looks like this: >lua - { - [vim.type_idx] = vim.types.float, - [vim.val_idx] = 1.0, - } -< See also |vim.type_idx| and |lua-special-tbl|. + --- + -- Wait for 1 second or until global variable set, checking every ~500 ms + vim.wait(1000, function() return vim.g.waiting_for_var end, 500) -vim.types *vim.types* - Table with possible values for |vim.type_idx|. Contains two sets of - key-value pairs: first maps possible values for |vim.type_idx| to - human-readable strings, second maps human-readable type names to values - for |vim.type_idx|. Currently contains pairs for `float`, `array` and - `dictionary` types. + --- + -- Schedule a function to set a value in 100ms + vim.defer_fn(function() vim.g.timer_result = true end, 100) - Note: One must expect that values corresponding to `vim.types.float`, - `vim.types.array` and `vim.types.dictionary` fall under only two following - assumptions: - 1. Value may serve both as a key and as a value in a table. Given the - properties of Lua tables this basically means “value is not `nil`”. - 2. For each value in `vim.types` table `vim.types[vim.types[value]]` is the - same as `value`. - No other restrictions are put on types, and it is not guaranteed that - values corresponding to `vim.types.float`, `vim.types.array` and - `vim.types.dictionary` will not change or that `vim.types` table will only - contain values for these three types. + -- Would wait ten seconds if results blocked. Actually only waits 100 ms + if vim.wait(10000, function() return vim.g.timer_result end) then + print('Only waiting a little bit of time!') + end +< - *log_levels* *vim.log.levels* -Log levels are one of the values defined in `vim.log.levels`: + Parameters: ~ + • {time} (integer) Number of milliseconds to wait + • {callback} fun():|nil boolean Optional callback. Waits until + {callback} returns true + • {interval} (integer|nil) (Approximate) number of milliseconds to + wait between polls + • {fast_only} (boolean|nil) If true, only |api-fast| events will be + processed. - vim.log.levels.DEBUG - vim.log.levels.ERROR - vim.log.levels.INFO - vim.log.levels.TRACE - vim.log.levels.WARN - vim.log.levels.OFF + Return: ~ + boolean, nil|-1|-2 + • If {callback} returns `true` during the {time}: `true, nil` + • If {callback} never returns `true` during the {time}: `false, -1` + • If {callback} is interrupted during the {time}: `false, -2` + • If {callback} errors, the error is raised. ------------------------------------------------------------------------------- + +============================================================================== LUA-VIMSCRIPT BRIDGE *lua-vimscript* -Nvim Lua provides an interface to Vimscript variables and functions, and -editor commands and options. -See also https://github.com/nanotee/nvim-lua-guide. +Nvim Lua provides an interface or "bridge" to Vimscript variables and +functions, and editor commands and options. + +Objects passed over this bridge are COPIED (marshalled): there are no +"references". |lua-guide-variables| For example, using `vim.fn.remove()` +on a Lua list copies the list object to Vimscript and does NOT modify the +Lua list: >lua + local list = { 1, 2, 3 } + vim.fn.remove(list, 0) + vim.print(list) --> "{ 1, 2, 3 }" + +< vim.call({func}, {...}) *vim.call()* Invokes |vim-function| or |user-function| {func} with arguments {...}. See also |vim.fn|. Equivalent to: >lua vim.fn[func]({...}) - +< vim.cmd({command}) See |vim.cmd()|. @@ -1079,16 +1280,7 @@ vim.v *vim.v* |v:| variables. Invalid or unset key returns `nil`. -vim.env *vim.env* - Environment variables defined in the editor session. - See |expand-env| and |:let-environment| for the Vimscript behavior. - Invalid or unset key returns `nil`. - Example: >lua - vim.env.FOO = 'bar' - print(vim.env.TERM) -< - - *lua-options* +` ` *lua-options* *lua-vim-options* *lua-vim-set* *lua-vim-setlocal* @@ -1111,66 +1303,10 @@ window-scoped options. Note that this must NOT be confused with |local-options| and |:setlocal|. There is also |vim.go| that only accesses the global value of a |global-local| option, see |:setglobal|. -vim.o *vim.o* - Get or set |options|. Like `:set`. Invalid key is an error. - - Note: this works on both buffer-scoped and window-scoped options using the - current buffer and window. - - Example: >lua - vim.o.cmdheight = 4 - print(vim.o.columns) - print(vim.o.foo) -- error: invalid key -< -vim.go *vim.go* - Get or set global |options|. Like `:setglobal`. Invalid key is - an error. - - Note: this is different from |vim.o| because this accesses the global - option value and thus is mostly useful for use with |global-local| - options. - - Example: >lua - vim.go.cmdheight = 4 - print(vim.go.columns) - print(vim.go.bar) -- error: invalid key -< -vim.bo[{bufnr}] *vim.bo* - Get or set buffer-scoped |options| for the buffer with number {bufnr}. - Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current - buffer is used. Invalid {bufnr} or key is an error. - - Note: this is equivalent to both `:set` and `:setlocal`. - - Example: >lua - local bufnr = vim.api.nvim_get_current_buf() - vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true - print(vim.bo.comments) - print(vim.bo.baz) -- error: invalid key -< -vim.wo[{winid}] *vim.wo* - Get or set window-scoped |options| for the window with handle {winid}. - Like `:set`. If [{winid}] is omitted then the current window is used. - Invalid {winid} or key is an error. - - Note: this does not access |local-options| (`:setlocal`) instead use: >lua - nvim_get_option_value(OPTION, { scope = 'local', win = winid }) - nvim_set_option_value(OPTION, VALUE, { scope = 'local', win = winid } -< - Example: >lua - local winid = vim.api.nvim_get_current_win() - vim.wo[winid].number = true -- same as vim.wo.number = true - print(vim.wo.foldmarker) - print(vim.wo.quux) -- error: invalid key -< - - - - *vim.opt_local* +` ` *vim.opt_local* *vim.opt_global* *vim.opt* - A special interface |vim.opt| exists for conveniently interacting with list- and map-style option from Lua: It allows accessing them as Lua tables and offers object-oriented method for adding and removing entries. @@ -1223,26 +1359,33 @@ which is accessed through |vim.opt:get()|: print(vim.o.wildignore) < In Lua using `vim.opt`: >lua - vim.pretty_print(vim.opt.wildignore:get()) + vim.print(vim.opt.wildignore:get()) < In any of the above examples, to replicate the behavior |:setlocal|, use `vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use `vim.opt_global`. +Option:append({value}) *vim.opt:append()* + Append a value to string-style options. See |:set+=| + These are equivalent: >lua + vim.opt.formatoptions:append('j') + vim.opt.formatoptions = vim.opt.formatoptions + 'j' +< - *vim.opt:get()* -Option:get() + Parameters: ~ + • {value} (string) Value to append - Returns a lua-representation of the option. Boolean, number and string +Option:get() *vim.opt:get()* + Returns a Lua-representation of the option. Boolean, number and string values will be returned in exactly the same fashion. For values that are comma-separated lists, an array will be returned with the values as entries in the array: >lua vim.cmd [[set wildignore=*.pyc,*.o]] - vim.pretty_print(vim.opt.wildignore:get()) + vim.print(vim.opt.wildignore:get()) -- { "*.pyc", "*.o", } for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do @@ -1251,22 +1394,24 @@ Option:get() -- Will ignore: *.pyc -- Will ignore: *.o < + For values that are comma-separated maps, a table will be returned with the names as keys and the values as entries: >lua vim.cmd [[set listchars=space:_,tab:>~]] - vim.pretty_print(vim.opt.listchars:get()) + vim.print(vim.opt.listchars:get()) -- { space = "_", tab = ">~", } for char, representation in pairs(vim.opt.listchars:get()) do print(char, "=>", representation) end < + For values that are lists of flags, a set will be returned with the flags as keys and `true` as entries. >lua vim.cmd [[set formatoptions=njtcroql]] - vim.pretty_print(vim.opt.formatoptions:get()) + vim.print(vim.opt.formatoptions:get()) -- { n = true, j = true, c = true, ... } local format_opts = vim.opt.formatoptions:get() @@ -1274,27 +1419,22 @@ Option:get() print("J is enabled!") end < - *vim.opt:append()* -Option:append(value) - Append a value to string-style options. See |:set+=| - - These are equivalent: >lua - vim.opt.formatoptions:append('j') - vim.opt.formatoptions = vim.opt.formatoptions + 'j' -< - *vim.opt:prepend()* -Option:prepend(value) + Return: ~ + string|integer|boolean|nil value of option +Option:prepend({value}) *vim.opt:prepend()* Prepend a value to string-style options. See |:set^=| These are equivalent: >lua vim.opt.wildignore:prepend('*.o') vim.opt.wildignore = vim.opt.wildignore ^ '*.o' < - *vim.opt:remove()* -Option:remove(value) + Parameters: ~ + • {value} (string) Value to prepend + +Option:remove({value}) *vim.opt:remove()* Remove a value from string-style options. See |:set-=| These are equivalent: >lua @@ -1302,93 +1442,191 @@ Option:remove(value) vim.opt.wildignore = vim.opt.wildignore - '*.pyc' < -============================================================================== -Lua module: vim *lua-vim* + Parameters: ~ + • {value} (string) Value to remove -cmd({command}) *vim.cmd()* - Execute Vim script commands. +vim.bo *vim.bo* + Get or set buffer-scoped |options| for the buffer with number {bufnr}. + Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current + buffer is used. Invalid {bufnr} or key is an error. - Note that `vim.cmd` can be indexed with a command name to return a - callable function to the command. + Note: this is equivalent to both `:set` and `:setlocal`. + + Example: >lua + local bufnr = vim.api.nvim_get_current_buf() + vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true + print(vim.bo.comments) + print(vim.bo.baz) -- error: invalid key +< + +vim.env *vim.env* + Environment variables defined in the editor session. See |expand-env| and + |:let-environment| for the Vimscript behavior. Invalid or unset key + returns `nil`. + + Example: >lua + vim.env.FOO = 'bar' + print(vim.env.TERM) +< + + Parameters: ~ + • {var} (string) + +vim.go *vim.go* + Get or set global |options|. Like `:setglobal`. Invalid key is an error. + + Note: this is different from |vim.o| because this accesses the global + option value and thus is mostly useful for use with |global-local| + options. Example: >lua + vim.go.cmdheight = 4 + print(vim.go.columns) + print(vim.go.bar) -- error: invalid key +< - vim.cmd('echo 42') - vim.cmd([[ - augroup My_group - autocmd! - autocmd FileType c setlocal cindent - augroup END - ]]) +vim.o *vim.o* + Get or set |options|. Like `:set`. Invalid key is an error. - -- Ex command :echo "foo" - -- Note string literals need to be double quoted. - vim.cmd('echo "foo"') - vim.cmd { cmd = 'echo', args = { '"foo"' } } - vim.cmd.echo({ args = { '"foo"' } }) - vim.cmd.echo('"foo"') + Note: this works on both buffer-scoped and window-scoped options using the + current buffer and window. - -- Ex command :write! myfile.txt - vim.cmd('write! myfile.txt') - vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true } - vim.cmd.write { args = { "myfile.txt" }, bang = true } - vim.cmd.write { "myfile.txt", bang = true } + Example: >lua + vim.o.cmdheight = 4 + print(vim.o.columns) + print(vim.o.foo) -- error: invalid key +< + +vim.wo *vim.wo* + Get or set window-scoped |options| for the window with handle {winid} and + buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like + `:set` otherwise. If [{winid}] is omitted then the current window is used. + Invalid {winid}, {bufnr} or key is an error. - -- Ex command :colorscheme blue - vim.cmd('colorscheme blue') - vim.cmd.colorscheme('blue') + Note: only {bufnr} with value `0` (the current buffer in the window) is + supported. + + Example: >lua + local winid = vim.api.nvim_get_current_win() + vim.wo[winid].number = true -- same as vim.wo.number = true + print(vim.wo.foldmarker) + print(vim.wo.quux) -- error: invalid key + vim.wo[winid][0].spell = false -- like ':setlocal nospell' +< + + +============================================================================== +Lua module: vim *lua-vim* + +vim.cmd *vim.cmd()* + Executes Vim script commands. + + Note that `vim.cmd` can be indexed with a command name to return a + callable function to the command. + + Example: >lua + vim.cmd('echo 42') + vim.cmd([[ + augroup My_group + autocmd! + autocmd FileType c setlocal cindent + augroup END + ]]) + + -- Ex command :echo "foo" + -- Note string literals need to be double quoted. + vim.cmd('echo "foo"') + vim.cmd { cmd = 'echo', args = { '"foo"' } } + vim.cmd.echo({ args = { '"foo"' } }) + vim.cmd.echo('"foo"') + + -- Ex command :write! myfile.txt + vim.cmd('write! myfile.txt') + vim.cmd { cmd = 'write', args = { "myfile.txt" }, bang = true } + vim.cmd.write { args = { "myfile.txt" }, bang = true } + vim.cmd.write { "myfile.txt", bang = true } + + -- Ex command :colorscheme blue + vim.cmd('colorscheme blue') + vim.cmd.colorscheme('blue') < Parameters: ~ • {command} string|table Command(s) to execute. If a string, executes multiple lines of Vim script at once. In this case, it is - an alias to |nvim_exec()|, where `output` is set to false. - Thus it works identical to |:source|. If a table, executes - a single command. In this case, it is an alias to + an alias to |nvim_exec2()|, where `opts.output` is set to + false. Thus it works identical to |:source|. If a table, + executes a single command. In this case, it is an alias to |nvim_cmd()| where `opts` is empty. See also: ~ - |ex-cmd-index| - - *vim.connection_failure_errmsg()* -connection_failure_errmsg({consequence}) - TODO: Documentation + • |ex-cmd-index| -defer_fn({fn}, {timeout}) *vim.defer_fn()* - Defers calling `fn` until `timeout` ms passes. +vim.defer_fn({fn}, {timeout}) *vim.defer_fn()* + Defers calling {fn} until {timeout} ms passes. - Use to do a one-shot timer that calls `fn` Note: The {fn} is |vim.schedule_wrap()|ped automatically, so API functions - are safe to call. + Use to do a one-shot timer that calls {fn} Note: The {fn} is + |vim.schedule_wrap()|ped automatically, so API functions are safe to call. Parameters: ~ • {fn} (function) Callback to call once `timeout` expires - • {timeout} integer Number of milliseconds to wait before calling `fn` + • {timeout} (integer) Number of milliseconds to wait before calling + `fn` Return: ~ (table) timer luv timer object *vim.deprecate()* -deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) - Display a deprecation notification to the user. +vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) + Shows a deprecation message to the user. Parameters: ~ - • {name} string Deprecated function. - • {alternative} (string|nil) Preferred alternative function. - • {version} string Version in which the deprecated function will be - removed. - • {plugin} string|nil Plugin name that the function will be - removed from. Defaults to "Nvim". + • {name} string Deprecated feature (function, API, etc.). + • {alternative} (string|nil) Suggested alternative feature. + • {version} string Version when the deprecated function will be removed. + • {plugin} string|nil Name of the plugin that owns the deprecated + feature. Defaults to "Nvim". • {backtrace} boolean|nil Prints backtrace. Defaults to true. -inspect({object}, {options}) *vim.inspect()* + Return: ~ + (string|nil) Deprecated message, or nil if no message was shown. + +vim.inspect *vim.inspect()* Gets a human-readable representation of the given object. + Return: ~ + (string) + See also: ~ - https://github.com/kikito/inspect.lua - https://github.com/mpeterv/vinspect + • |vim.print()| + • https://github.com/kikito/inspect.lua + • https://github.com/mpeterv/vinspect -notify({msg}, {level}, {opts}) *vim.notify()* - Display a notification to the user. +vim.keycode({str}) *vim.keycode()* + Translates keycodes. + + Example: >lua + local k = vim.keycode + vim.g.mapleader = k'<bs>' +< + + Parameters: ~ + • {str} (string) String to be converted. + + Return: ~ + (string) + + See also: ~ + • |nvim_replace_termcodes()| + +vim.lua_omnifunc({find_start}, {_}) *vim.lua_omnifunc()* + Omnifunc for completing Lua values from the runtime Lua interpreter, + similar to the builtin completion for the `:lua` command. + + Activate using `set omnifunc=v:lua.vim.lua_omnifunc` in a Lua buffer. + +vim.notify({msg}, {level}, {opts}) *vim.notify()* + Displays a notification to the user. This function can be overridden by plugins to display notifications using a custom provider (such as the system notification provider). By default, @@ -1396,66 +1634,60 @@ notify({msg}, {level}, {opts}) *vim.notify()* Parameters: ~ • {msg} (string) Content of the notification to show to the user. - • {level} (number|nil) One of the values from |vim.log.levels|. + • {level} (integer|nil) One of the values from |vim.log.levels|. • {opts} (table|nil) Optional parameters. Unused by default. -notify_once({msg}, {level}, {opts}) *vim.notify_once()* - Display a notification only one time. +vim.notify_once({msg}, {level}, {opts}) *vim.notify_once()* + Displays a notification only one time. Like |vim.notify()|, but subsequent calls with the same message will not display a notification. Parameters: ~ • {msg} (string) Content of the notification to show to the user. - • {level} (number|nil) One of the values from |vim.log.levels|. + • {level} (integer|nil) One of the values from |vim.log.levels|. • {opts} (table|nil) Optional parameters. Unused by default. Return: ~ (boolean) true if message was displayed, else false -on_key({fn}, {ns_id}) *vim.on_key()* +vim.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 + Note: ~ + • {fn} will be removed on error. + • {fn} will not be cleared by |nvim_buf_clear_namespace()| + • {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 + • {fn} fun(key: string) Function invoked on every key press. + |i_CTRL-V| Returning nil removes the callback associated with + namespace {ns_id}. + • {ns_id} integer? Namespace ID. If nil or 0, generates and returns a new |nvim_create_namespace()| id. Return: ~ - (number) Namespace id associated with {fn}. Or count of all callbacks + (integer) 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()* +vim.paste({lines}, {phase}) *vim.paste()* Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the |TUI|) pastes text into the editor. Example: To remove ANSI color codes when pasting: >lua - - vim.paste = (function(overridden) - return function(lines, phase) - for i,line in ipairs(lines) do - -- Scrub ANSI color codes from paste input. - lines[i] = line:gsub('\27%[[0-9;mK]+', '') - end - overridden(lines, phase) - end - end)(vim.paste) + vim.paste = (function(overridden) + return function(lines, phase) + for i,line in ipairs(lines) do + -- Scrub ANSI color codes from paste input. + lines[i] = line:gsub('\27%[[0-9;mK]+', '') + end + overridden(lines, phase) + end + end)(vim.paste) < Parameters: ~ @@ -1468,68 +1700,163 @@ paste({lines}, {phase}) *vim.paste()* • 3: ends the paste (exactly once) Return: ~ - (boolean) # false if client should cancel the paste. + (boolean) result false if client should cancel the paste. See also: ~ - |paste| @alias paste_phase -1 | 1 | 2 | 3 + • |paste| @alias paste_phase -1 | 1 | 2 | 3 -pretty_print({...}) *vim.pretty_print()* - Prints given arguments in human-readable format. Example: >lua - -- Print highlight group Normal and store it's contents in a variable. - local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true)) +vim.print({...}) *vim.print()* + "Pretty prints" the given arguments and returns them unmodified. + + Example: >lua + local hl_normal = vim.print(vim.api.nvim_get_hl(0, { name = 'Normal' })) < Return: ~ - any # given arguments. + any given arguments. See also: ~ - |vim.inspect()| + • |vim.inspect()| + • |:=| -region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) *vim.region()* - Get a table of lines with start, end columns for a region marked by two - points + *vim.region()* +vim.region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive}) + Gets a dict of line segment ("chunk") positions for the region from `pos1` + to `pos2`. + + Input and output positions are byte positions, (0,0)-indexed. "End of + line" column position (for example, |linewise| visual selection) is + returned as |v:maxcol| (big number). Parameters: ~ - • {bufnr} (number) of buffer - • {pos1} integer[] (line, column) tuple marking beginning of - region - • {pos2} integer[] (line, column) tuple marking end of region - • {regtype} (string) type of selection, see |setreg()| - • {inclusive} (boolean) indicating whether the selection is - end-inclusive + • {bufnr} (integer) Buffer number, or 0 for current buffer + • {pos1} integer[]|string Start of region as a (line, column) + tuple or |getpos()|-compatible string + • {pos2} integer[]|string End of region as a (line, column) tuple + or |getpos()|-compatible string + • {regtype} (string) |setreg()|-style selection type + • {inclusive} (boolean) Controls whether the ending column is inclusive + (see also 'selection'). Return: ~ - (table) region Table of the form `{linenr = {startcol,endcol}}` + (table) region Dict of the form `{linenr = {startcol,endcol}}`. + `endcol` is exclusive, and whole lines are returned as + `{startcol,endcol} = {0,-1}`. + +vim.schedule_wrap({fn}) *vim.schedule_wrap()* + Returns a function which calls {fn} via |vim.schedule()|. -schedule_wrap({cb}) *vim.schedule_wrap()* - Defers callback `cb` until the Nvim API is safe to call. + The returned function passes all arguments to {fn}. + + Example: >lua + function notify_readable(_err, readable) + vim.notify("readable? " .. tostring(readable)) + end + vim.uv.fs_access(vim.fn.stdpath("config"), "R", vim.schedule_wrap(notify_readable)) +< Parameters: ~ - • {cb} (function) + • {fn} (function) Return: ~ (function) See also: ~ - |lua-loop-callbacks| - |vim.schedule()| - |vim.in_fast_event()| + • |lua-loop-callbacks| + • |vim.schedule()| + • |vim.in_fast_event()| + +vim.system({cmd}, {opts}, {on_exit}) *vim.system()* + Runs a system command or throws an error if {cmd} cannot be run. + + Examples: >lua + local on_exit = function(obj) + print(obj.code) + print(obj.signal) + print(obj.stdout) + print(obj.stderr) + end + + -- Runs asynchronously: + vim.system({'echo', 'hello'}, { text = true }, on_exit) + + -- Runs synchronously: + local obj = vim.system({'echo', 'hello'}, { text = true }):wait() + -- { code = 0, signal = 0, stdout = 'hello', stderr = '' } +< + + See |uv.spawn()| for more details. Note: unlike |uv.spawn()|, vim.system + throws an error if {cmd} cannot be run. + + Parameters: ~ + • {cmd} (string[]) Command to execute + • {opts} (SystemOpts|nil) Options: + • cwd: (string) Set the current working directory for the + sub-process. + • env: table<string,string> Set environment variables for + the new process. Inherits the current environment with + `NVIM` set to |v:servername|. + • clear_env: (boolean) `env` defines the job environment + exactly, instead of merging current environment. + • stdin: (string|string[]|boolean) If `true`, then a pipe + to stdin is opened and can be written to via the + `write()` method to SystemObj. If string or string[] then + will be written to stdin and closed. Defaults to `false`. + • stdout: (boolean|function) Handle output from stdout. + When passed as a function must have the signature + `fun(err: string, data: string)`. Defaults to `true` + • stderr: (boolean|function) Handle output from stderr. + When passed as a function must have the signature + `fun(err: string, data: string)`. Defaults to `true`. + • text: (boolean) Handle stdout and stderr as text. + Replaces `\r\n` with `\n`. + • timeout: (integer) Run the command with a time limit. + Upon timeout the process is sent the TERM signal (15) and + the exit code is set to 124. + • detach: (boolean) If true, spawn the child process in a + detached state - this will make it a process group + leader, and will effectively enable the child to keep + running after the parent exits. Note that the child + process will still keep the parent's event loop alive + unless the parent process calls |uv.unref()| on the + child's process handle. + • {on_exit} (function|nil) Called when subprocess exits. When provided, + the command runs asynchronously. Receives SystemCompleted + object, see return of SystemObj:wait(). + + Return: ~ + vim.SystemObj Object with the fields: + • pid (integer) Process ID + • wait (fun(timeout: integer|nil): SystemCompleted) Wait for the + process to complete. Upon timeout the process is sent the KILL + signal (9) and the exit code is set to 124. Cannot be called in + |api-fast|. + • SystemCompleted is an object with the fields: + • code: (integer) + • signal: (integer) + • stdout: (string), nil if stdout argument is passed + • stderr: (string), nil if stderr argument is passed + + • kill (fun(signal: integer|string)) + • write (fun(data: string|nil)) Requires `stdin=true`. Pass `nil` to + close the stream. + • is_closing (fun(): boolean) ============================================================================== -Lua module: inspector *lua-inspector* +Lua module: vim.inspector *vim.inspector* -inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* +vim.inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* Get all the items at a given buffer position. Can also be pretty-printed with `:Inspect!`. *:Inspect!* Parameters: ~ - • {bufnr} (number|nil) defaults to the current buffer - • {row} (number|nil) row to inspect, 0-based. Defaults to the row of - the current cursor - • {col} (number|nil) col to inspect, 0-based. Defaults to the col of - the current cursor + • {bufnr} (integer|nil) defaults to the current buffer + • {row} (integer|nil) row to inspect, 0-based. Defaults to the row + of the current cursor + • {col} (integer|nil) col to inspect, 0-based. Defaults to the col + of the current cursor • {filter} (table|nil) a table with key-value pairs to filter the items • syntax (boolean): include syntax based highlight groups (defaults to true) @@ -1552,23 +1879,23 @@ inspect_pos({bufnr}, {row}, {col}, {filter}) *vim.inspect_pos()* • row: the row used to get the items • col: the col used to get the items -show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* +vim.show_pos({bufnr}, {row}, {col}, {filter}) *vim.show_pos()* Show all the items at a given buffer position. Can also be shown with `:Inspect`. *:Inspect* Parameters: ~ - • {bufnr} (number|nil) defaults to the current buffer - • {row} (number|nil) row to inspect, 0-based. Defaults to the row of - the current cursor - • {col} (number|nil) col to inspect, 0-based. Defaults to the col of - the current cursor + • {bufnr} (integer|nil) defaults to the current buffer + • {row} (integer|nil) row to inspect, 0-based. Defaults to the row + of the current cursor + • {col} (integer|nil) col to inspect, 0-based. Defaults to the col + of the current cursor • {filter} (table|nil) see |vim.inspect_pos()| -deep_equal({a}, {b}) *vim.deep_equal()* +vim.deep_equal({a}, {b}) *vim.deep_equal()* Deep compare values for equality Tables are compared recursively unless they both provide the `eq` metamethod. All other types are compared using the equality `==` operator. @@ -1580,7 +1907,7 @@ deep_equal({a}, {b}) *vim.deep_equal()* Return: ~ (boolean) `true` if values are equals, else `false` -deepcopy({orig}) *vim.deepcopy()* +vim.deepcopy({orig}) *vim.deepcopy()* Returns a deep copy of the given object. Non-table objects are copied as in a typical Lua assignment, whereas table objects are copied recursively. Functions are naively copied, so functions in the copied table point to @@ -1593,30 +1920,24 @@ deepcopy({orig}) *vim.deepcopy()* Return: ~ (table) Table of copied keys and (nested) values. -defaulttable({create}) *vim.defaulttable()* - Creates a table whose members are automatically created when accessed, if - they don't already exist. - - They mimic defaultdict in python. +vim.defaulttable({createfn}) *vim.defaulttable()* + Creates a table whose missing keys are provided by {createfn} (like + Python's "defaultdict"). - If {create} is `nil`, this will create a defaulttable whose constructor - function is this function, effectively allowing to create nested tables on - the fly: - - >lua - - local a = vim.defaulttable() - a.b.c = 1 + If {createfn} is `nil` it defaults to defaulttable() itself, so accessing + nested keys creates nested tables: >lua + local a = vim.defaulttable() + a.b.c = 1 < Parameters: ~ - • {create} (function|nil) The function called to create a missing - value. + • {createfn} function?(key:any):any Provides the value for a missing + `key`. Return: ~ - (table) Empty table with metamethod + (table) Empty table with `__index` metamethod. -endswith({s}, {suffix}) *vim.endswith()* +vim.endswith({s}, {suffix}) *vim.endswith()* Tests if `s` ends with `suffix`. Parameters: ~ @@ -1626,25 +1947,42 @@ endswith({s}, {suffix}) *vim.endswith()* Return: ~ (boolean) `true` if `suffix` is a suffix of `s` -gsplit({s}, {sep}, {plain}) *vim.gsplit()* - Splits a string at each instance of a separator. +vim.gsplit({s}, {sep}, {opts}) *vim.gsplit()* + Gets an |iterator| that splits a string at each instance of a separator, + in "lazy" fashion (as opposed to |vim.split()| which is "eager"). + + Example: >lua + for s in vim.gsplit(':aa::b:', ':', {plain=true}) do + print(s) + end +< + + If you want to also inspect the separator itself (instead of discarding + it), use |string.gmatch()|. Example: >lua + for word, num in ('foo111bar222'):gmatch('([^0-9]*)(%d*)') do + print(('word: %s num: %s'):format(word, num)) + end +< Parameters: ~ - • {s} (string) String to split - • {sep} (string) Separator or pattern - • {plain} (boolean|nil) If `true` use `sep` literally (passed to - string.find) + • {s} (string) String to split + • {sep} (string) Separator or pattern + • {opts} (table|nil) Keyword arguments |kwargs|: + • plain: (boolean) Use `sep` literally (as in string.find). + • trimempty: (boolean) Discard empty segments at start and end + of the sequence. Return: ~ (function) Iterator over the split components See also: ~ - |vim.split()| - |luaref-patterns| - https://www.lua.org/pil/20.2.html - http://lua-users.org/wiki/StringLibraryTutorial + • |string.gmatch()| + • |vim.split()| + • |lua-patterns| + • https://www.lua.org/pil/20.2.html + • http://lua-users.org/wiki/StringLibraryTutorial -is_callable({f}) *vim.is_callable()* +vim.is_callable({f}) *vim.is_callable()* Returns true if object `f` can be called as a function. Parameters: ~ @@ -1653,7 +1991,20 @@ is_callable({f}) *vim.is_callable()* Return: ~ (boolean) `true` if `f` is callable, else `false` -list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* +vim.list_contains({t}, {value}) *vim.list_contains()* + Checks if a list-like table (integer keys without gaps) contains `value`. + + Parameters: ~ + • {t} (table) Table to check (must be list-like, not validated) + • {value} any Value to compare + + Return: ~ + (boolean) `true` if `t` contains `value` + + See also: ~ + • |vim.tbl_contains()| for checking values in general tables + +vim.list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* Extends a list-like table with the values of another list-like table. NOTE: This mutates dst! @@ -1661,28 +2012,28 @@ list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()* Parameters: ~ • {dst} (table) List which will be modified and appended to • {src} (table) List from which values will be inserted - • {start} (number|nil) Start index on src. Defaults to 1 - • {finish} (number|nil) Final index on src. Defaults to `#src` + • {start} (integer|nil) Start index on src. Defaults to 1 + • {finish} (integer|nil) Final index on src. Defaults to `#src` Return: ~ (table) dst See also: ~ - |vim.tbl_extend()| + • |vim.tbl_extend()| -list_slice({list}, {start}, {finish}) *vim.list_slice()* +vim.list_slice({list}, {start}, {finish}) *vim.list_slice()* Creates a copy of a table containing only elements from start to end (inclusive) Parameters: ~ • {list} (list) Table - • {start} (number|nil) Start range of slice - • {finish} (number|nil) End range of slice + • {start} (integer|nil) Start range of slice + • {finish} (integer|nil) End range of slice Return: ~ (list) Copy of table sliced from start to finish (inclusive) -pesc({s}) *vim.pesc()* +vim.pesc({s}) *vim.pesc()* Escapes magic chars in |lua-patterns|. Parameters: ~ @@ -1692,47 +2043,97 @@ pesc({s}) *vim.pesc()* (string) %-escaped pattern string See also: ~ - https://github.com/rxi/lume + • https://github.com/rxi/lume + +vim.ringbuf({size}) *vim.ringbuf()* + Create a ring buffer limited to a maximal number of items. Once the buffer + is full, adding a new entry overrides the oldest entry. >lua + local ringbuf = vim.ringbuf(4) + ringbuf:push("a") + ringbuf:push("b") + ringbuf:push("c") + ringbuf:push("d") + ringbuf:push("e") -- overrides "a" + print(ringbuf:pop()) -- returns "b" + print(ringbuf:pop()) -- returns "c" + + -- Can be used as iterator. Pops remaining items: + for val in ringbuf do + print(val) + end +< + + Returns a Ringbuf instance with the following methods: -spairs({t}) *vim.spairs()* - Enumerate a table sorted by its keys. + • |Ringbuf:push()| + • |Ringbuf:pop()| + • |Ringbuf:peek()| + • |Ringbuf:clear()| Parameters: ~ - • {t} (table) List-like table + • {size} (integer) + + Return: ~ + (table) + +vim.Ringbuf:clear() *Ringbuf:clear()* + Clear all items. + +vim.Ringbuf:peek() *Ringbuf:peek()* + Returns the first unread item without removing it + + Return: ~ + any?|nil + +vim.Ringbuf:pop() *Ringbuf:pop()* + Removes and returns the first unread item + + Return: ~ + any?|nil + +vim.Ringbuf:push({item}) *Ringbuf:push()* + Adds an item, overriding the oldest item if the buffer is full. + + Parameters: ~ + • {item} any + +vim.spairs({t}) *vim.spairs()* + Enumerates key-value pairs of a table, ordered by key. + + Parameters: ~ + • {t} (table) Dict-like table Return: ~ - iterator over sorted keys and their values + (function) |for-in| iterator over sorted keys and their values See also: ~ - Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua + • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua -split({s}, {sep}, {kwargs}) *vim.split()* - Splits a string at each instance of a separator. +vim.split({s}, {sep}, {opts}) *vim.split()* + Splits a string at each instance of a separator and returns the result as + a table (unlike |vim.gsplit()|). Examples: >lua - - 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'} + 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) String to split - • {sep} (string) Separator or pattern - • {kwargs} (table|nil) 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 + • {s} (string) String to split + • {sep} (string) Separator or pattern + • {opts} (table|nil) Keyword arguments |kwargs| accepted by + |vim.gsplit()| Return: ~ string[] List of split components See also: ~ - |vim.gsplit()| + • |vim.gsplit()| + • |string.gmatch()| -startswith({s}, {prefix}) *vim.startswith()* +vim.startswith({s}, {prefix}) *vim.startswith()* Tests if `s` starts with `prefix`. Parameters: ~ @@ -1742,7 +2143,7 @@ startswith({s}, {prefix}) *vim.startswith()* Return: ~ (boolean) `true` if `prefix` is a prefix of `s` -tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* +vim.tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* Add the reverse lookup values to an existing table. For example: `tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }` @@ -1754,36 +2155,47 @@ tbl_add_reverse_lookup({o}) *vim.tbl_add_reverse_lookup()* Return: ~ (table) o -tbl_contains({t}, {value}) *vim.tbl_contains()* - Checks if a list-like (vector) table contains `value`. +vim.tbl_contains({t}, {value}, {opts}) *vim.tbl_contains()* + Checks if a table contains a given value, specified either directly or via + a predicate that is checked for each value. + + Example: >lua + vim.tbl_contains({ 'a', { 'b', 'c' } }, function(v) + return vim.deep_equal(v, { 'b', 'c' }) + end, { predicate = true }) + -- true +< Parameters: ~ • {t} (table) Table to check - • {value} any Value to compare + • {value} any Value to compare or predicate function reference + • {opts} (table|nil) Keyword arguments |kwargs|: + • predicate: (boolean) `value` is a function reference to be + checked (default false) Return: ~ (boolean) `true` if `t` contains `value` -tbl_count({t}) *vim.tbl_count()* - Counts the number of non-nil values in table `t`. - - >lua + See also: ~ + • |vim.list_contains()| for checking values in list-like tables - vim.tbl_count({ a=1, b=2 }) --> 2 - vim.tbl_count({ 1, 2 }) --> 2 +vim.tbl_count({t}) *vim.tbl_count()* + Counts the number of non-nil values in table `t`. >lua + vim.tbl_count({ a=1, b=2 }) --> 2 + vim.tbl_count({ 1, 2 }) --> 2 < Parameters: ~ • {t} (table) Table Return: ~ - (number) Number of non-nil values in table + (integer) Number of non-nil values in table See also: ~ - https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua + • https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua -tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* - Merges recursively two or more map-like tables. +vim.tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* + Merges recursively two or more tables. Parameters: ~ • {behavior} (string) Decides what to do if a key is found in more than @@ -1791,16 +2203,16 @@ tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* • "error": raise an error • "keep": use value from the leftmost map • "force": use value from the rightmost map - • {...} (table) Two or more map-like tables + • {...} (table) Two or more tables Return: ~ (table) Merged table See also: ~ - |vim.tbl_extend()| + • |vim.tbl_extend()| -tbl_extend({behavior}, {...}) *vim.tbl_extend()* - Merges two or more map-like tables. +vim.tbl_extend({behavior}, {...}) *vim.tbl_extend()* + Merges two or more tables. Parameters: ~ • {behavior} (string) Decides what to do if a key is found in more than @@ -1808,15 +2220,15 @@ tbl_extend({behavior}, {...}) *vim.tbl_extend()* • "error": raise an error • "keep": use value from the leftmost map • "force": use value from the rightmost map - • {...} (table) Two or more map-like tables + • {...} (table) Two or more tables Return: ~ (table) Merged table See also: ~ - |extend()| + • |extend()| -tbl_filter({func}, {t}) *vim.tbl_filter()* +vim.tbl_filter({func}, {t}) *vim.tbl_filter()* Filter a table using a predicate function Parameters: ~ @@ -1826,7 +2238,7 @@ tbl_filter({func}, {t}) *vim.tbl_filter()* Return: ~ (table) Table of filtered values -tbl_flatten({t}) *vim.tbl_flatten()* +vim.tbl_flatten({t}) *vim.tbl_flatten()* Creates a copy of a list-like table such that any nested tables are "unrolled" and appended to the result. @@ -1837,27 +2249,45 @@ tbl_flatten({t}) *vim.tbl_flatten()* (table) Flattened copy of the given list-like table See also: ~ - From https://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_get({o}, {...}) *vim.tbl_get()* +vim.tbl_get({o}, {...}) *vim.tbl_get()* Index into a table (first argument) via string keys passed as subsequent arguments. Return `nil` if the key does not exist. Examples: >lua - - vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true - vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil + vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true + vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil < Parameters: ~ • {o} (table) Table to index - • {...} (string) Optional strings (0 or more, variadic) via which to - index the table + • {...} any Optional keys (0 or more, variadic) via which to index the + table Return: ~ any Nested value indexed by key (if it exists), else nil -tbl_isempty({t}) *vim.tbl_isempty()* +vim.tbl_isarray({t}) *vim.tbl_isarray()* + Tests if `t` is an "array": a table indexed only by integers (potentially non-contiguous). + + If the indexes start from 1 and are contiguous then the array is also a + list. |vim.tbl_islist()| + + Empty table `{}` is an array, unless it was created by |vim.empty_dict()| + or returned as a dict-like |API| or Vimscript result, for example from + |rpcrequest()| or |vim.fn|. + + Parameters: ~ + • {t} (table) + + Return: ~ + (boolean) `true` if array-like table, else `false`. + + See also: ~ + • https://github.com/openresty/luajit2#tableisarray + +vim.tbl_isempty({t}) *vim.tbl_isempty()* Checks if a table is empty. Parameters: ~ @@ -1867,22 +2297,26 @@ tbl_isempty({t}) *vim.tbl_isempty()* (boolean) `true` if `t` is empty See also: ~ - https://github.com/premake/premake-core/blob/master/src/base/table.lua + • https://github.com/premake/premake-core/blob/master/src/base/table.lua -tbl_islist({t}) *vim.tbl_islist()* - Tests if a Lua table can be treated as an array. +vim.tbl_islist({t}) *vim.tbl_islist()* + Tests if `t` is a "list": a table indexed only by contiguous integers starting from 1 (what |lua-length| calls a "regular + array"). - Empty table `{}` is assumed to be an array, unless it was created by - |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result, - for example from |rpcrequest()| or |vim.fn|. + Empty table `{}` is a list, unless it was created by |vim.empty_dict()| or + returned as a dict-like |API| or Vimscript result, for example from + |rpcrequest()| or |vim.fn|. Parameters: ~ - • {t} (table) Table + • {t} (table) Return: ~ - (boolean) `true` if array-like table, else `false` + (boolean) `true` if list-like table, else `false`. + + See also: ~ + • |vim.tbl_isarray()| -tbl_keys({t}) *vim.tbl_keys()* +vim.tbl_keys({t}) *vim.tbl_keys()* Return a list of all keys used in a table. However, the order of the return table of keys is not guaranteed. @@ -1893,9 +2327,9 @@ tbl_keys({t}) *vim.tbl_keys()* (list) List of keys See also: ~ - From https://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()* +vim.tbl_map({func}, {t}) *vim.tbl_map()* Apply a function to all values of a table. Parameters: ~ @@ -1905,7 +2339,7 @@ tbl_map({func}, {t}) *vim.tbl_map()* Return: ~ (table) Table of transformed values -tbl_values({t}) *vim.tbl_values()* +vim.tbl_values({t}) *vim.tbl_values()* Return a list of all values used in a table. However, the order of the return table of values is not guaranteed. @@ -1915,7 +2349,7 @@ tbl_values({t}) *vim.tbl_values()* Return: ~ (list) List of values -trim({s}) *vim.trim()* +vim.trim({s}) *vim.trim()* Trim whitespace (Lua pattern "%s") from both sides of a string. Parameters: ~ @@ -1925,43 +2359,40 @@ trim({s}) *vim.trim()* (string) String with whitespace removed from its beginning and end See also: ~ - |luaref-patterns| - https://www.lua.org/pil/20.2.html + • |lua-patterns| + • https://www.lua.org/pil/20.2.html -validate({opt}) *vim.validate()* +vim.validate({opt}) *vim.validate()* Validates a parameter specification (types and values). Usage example: >lua - - function user.new(name, age, hobbies) - vim.validate{ - name={name, 'string'}, - age={age, 'number'}, - hobbies={hobbies, 'table'}, - } - ... - end + function user.new(name, age, hobbies) + vim.validate{ + name={name, 'string'}, + age={age, 'number'}, + hobbies={hobbies, 'table'}, + } + ... + end < Examples with explicit argument values (can be run directly): >lua + vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} + --> NOP (success) - vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}} - --> NOP (success) - - vim.validate{arg1={1, 'table'}} - --> error('arg1: expected table, got number') + 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={3, function(a) return (a % 2) == 0 end, 'even number'}} + --> error('arg1: expected even number, got 3') < If multiple types are valid they can be given as a list. >lua + vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}} + -- NOP (success) - vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}} - --> NOP (success) - - vim.validate{arg1={1, {'string', table'}}} - --> error('arg1: expected string|table, got number') + vim.validate{arg1={1, {'string', 'table'}}} + -- error('arg1: expected string|table, got number') < Parameters: ~ @@ -1984,19 +2415,85 @@ validate({opt}) *vim.validate()* ============================================================================== -Lua module: uri *lua-uri* +Lua module: vim.loader *vim.loader* + +vim.loader.disable() *vim.loader.disable()* + Disables the experimental Lua module loader: + • removes the loaders + • adds the default Nvim loader + +vim.loader.enable() *vim.loader.enable()* + Enables the experimental Lua module loader: + • overrides loadfile + • adds the Lua loader using the byte-compilation cache + • adds the libs loader + • removes the default Nvim loader + +vim.loader.find({modname}, {opts}) *vim.loader.find()* + Finds Lua modules for the given module name. + + Parameters: ~ + • {modname} (string) Module name, or `"*"` to find the top-level + modules instead + • {opts} (table|nil) Options for finding a module: + • rtp: (boolean) Search for modname in the runtime path + (defaults to `true`) + • paths: (string[]) Extra paths to search for modname + (defaults to `{}`) + • patterns: (string[]) List of patterns to use when + searching for modules. A pattern is a string added to the + basename of the Lua module being searched. (defaults to + `{"/init.lua", ".lua"}`) + • all: (boolean) Return all matches instead of just the + first one (defaults to `false`) + + Return: ~ + (list) A list of results with the following properties: + • modpath: (string) the path to the module + • modname: (string) the name of the module + • stat: (table|nil) the fs_stat of the module path. Won't be returned + for `modname="*"` + +vim.loader.reset({path}) *vim.loader.reset()* + Resets the cache for the path, or all the paths if path is nil. + + Parameters: ~ + • {path} string? path to reset + + +============================================================================== +Lua module: vim.uri *vim.uri* + +vim.uri_decode({str}) *vim.uri_decode()* + URI-decodes a string containing percent escapes. + + Parameters: ~ + • {str} (string) string to decode + + Return: ~ + (string) decoded string + +vim.uri_encode({str}, {rfc}) *vim.uri_encode()* + URI-encodes a string using percent escapes. + + Parameters: ~ + • {str} (string) string to encode + • {rfc} "rfc2396" | "rfc2732" | "rfc3986" | nil + + Return: ~ + (string) encoded string -uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* - Get a URI from a bufnr +vim.uri_from_bufnr({bufnr}) *vim.uri_from_bufnr()* + Gets a URI from a bufnr. Parameters: ~ - • {bufnr} (number) + • {bufnr} (integer) Return: ~ (string) URI -uri_from_fname({path}) *vim.uri_from_fname()* - Get a URI from a file path. +vim.uri_from_fname({path}) *vim.uri_from_fname()* + Gets a URI from a file path. Parameters: ~ • {path} (string) Path to file @@ -2004,18 +2501,18 @@ uri_from_fname({path}) *vim.uri_from_fname()* Return: ~ (string) URI -uri_to_bufnr({uri}) *vim.uri_to_bufnr()* - Get the buffer for a uri. Creates a new unloaded buffer if no buffer for +vim.uri_to_bufnr({uri}) *vim.uri_to_bufnr()* + Gets the buffer for a uri. Creates a new unloaded buffer if no buffer for the uri already exists. Parameters: ~ • {uri} (string) Return: ~ - (number) bufnr + (integer) bufnr -uri_to_fname({uri}) *vim.uri_to_fname()* - Get a filename from a URI +vim.uri_to_fname({uri}) *vim.uri_to_fname()* + Gets a filename from a URI. Parameters: ~ • {uri} (string) @@ -2025,16 +2522,16 @@ uri_to_fname({uri}) *vim.uri_to_fname()* ============================================================================== -Lua module: ui *lua-ui* +Lua module: vim.ui *vim.ui* -input({opts}, {on_confirm}) *vim.ui.input()* - Prompts the user for input +vim.ui.input({opts}, {on_confirm}) *vim.ui.input()* + Prompts the user for input, allowing arbitrary (potentially asynchronous) + work until `on_confirm`. Example: >lua - - vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input) - vim.o.shiftwidth = tonumber(input) - end) + vim.ui.input({ prompt = 'Enter value for shiftwidth: ' }, function(input) + vim.o.shiftwidth = tonumber(input) + end) < Parameters: ~ @@ -2052,23 +2549,46 @@ input({opts}, {on_confirm}) *vim.ui.input()* typed (it might be an empty string if nothing was entered), or `nil` if the user aborted the dialog. -select({items}, {opts}, {on_choice}) *vim.ui.select()* - Prompts the user to pick a single item from a collection of entries +vim.ui.open({path}) *vim.ui.open()* + Opens `path` with the system default handler (macOS `open`, Windows + `explorer.exe`, Linux `xdg-open`, …), or returns (but does not show) an + error message on failure. - Example: >lua + Expands "~/" and environment variables in filesystem paths. - vim.ui.select({ 'tabs', 'spaces' }, { - prompt = 'Select tabs or spaces:', - format_item = function(item) - return "I'd like to choose " .. item - end, - }, function(choice) - if choice == 'spaces' then - vim.o.expandtab = true - else - vim.o.expandtab = false - end - end) + Examples: >lua + vim.ui.open("https://neovim.io/") + vim.ui.open("~/path/to/file") + vim.ui.open("$VIMRUNTIME") +< + + Parameters: ~ + • {path} (string) Path or URL to open + + Return (multiple): ~ + vim.SystemCompleted|nil Command result, or nil if not found. + (string|nil) Error message on failure + + See also: ~ + • |vim.system()| + +vim.ui.select({items}, {opts}, {on_choice}) *vim.ui.select()* + Prompts the user to pick from a list of items, allowing arbitrary + (potentially asynchronous) work until `on_choice`. + + Example: >lua + vim.ui.select({ 'tabs', 'spaces' }, { + prompt = 'Select tabs or spaces:', + format_item = function(item) + return "I'd like to choose " .. item + end, + }, function(choice) + if choice == 'spaces' then + vim.o.expandtab = true + else + vim.o.expandtab = false + end + end) < Parameters: ~ @@ -2089,9 +2609,9 @@ select({items}, {opts}, {on_choice}) *vim.ui.select()* ============================================================================== -Lua module: filetype *lua-filetype* +Lua module: vim.filetype *vim.filetype* -add({filetypes}) *vim.filetype.add()* +vim.filetype.add({filetypes}) *vim.filetype.add()* Add new filetype mappings. Filetype mappings can be added either by extension or by filename (either @@ -2107,7 +2627,8 @@ add({filetypes}) *vim.filetype.add()* matched pattern, if any) and should return a string that will be used as the buffer's filetype. Optionally, the function can return a second function value which, when called, modifies the state of the buffer. This - can be used to, for example, set filetype-specific buffer variables. + can be used to, for example, set filetype-specific buffer variables. This + function will be called by Nvim before setting the buffer's filetype. Filename patterns can specify an optional priority to resolve cases when a file path matches multiple patterns. Higher priorities are matched first. @@ -2119,65 +2640,86 @@ add({filetypes}) *vim.filetype.add()* See $VIMRUNTIME/lua/vim/filetype.lua for more examples. Example: >lua - - vim.filetype.add({ - extension = { - foo = 'fooscript', - bar = function(path, bufnr) - if some_condition() then - return 'barscript', function(bufnr) - -- Set a buffer variable - vim.b[bufnr].barscript_version = 2 + vim.filetype.add({ + extension = { + foo = 'fooscript', + bar = function(path, bufnr) + if some_condition() then + return 'barscript', function(bufnr) + -- Set a buffer variable + vim.b[bufnr].barscript_version = 2 + end end - end - return 'bar' - end, - }, - filename = { - ['.foorc'] = 'toml', - ['/etc/foo/config'] = 'toml', - }, - pattern = { - ['.*/etc/foo/.*'] = 'fooscript', - -- Using an optional priority - ['.*/etc/foo/.*%.conf'] = { 'dosini', { priority = 10 } }, - -- A pattern containing an environment variable - ['${XDG_CONFIG_HOME}/foo/git'] = 'git', - ['README.(a+)$'] = function(path, bufnr, ext) - if ext == 'md' then - return 'markdown' - elseif ext == 'rst' then - return 'rst' - end - end, - }, - }) + return 'bar' + end, + }, + filename = { + ['.foorc'] = 'toml', + ['/etc/foo/config'] = 'toml', + }, + pattern = { + ['.*‍/etc/foo/.*'] = 'fooscript', + -- Using an optional priority + ['.*‍/etc/foo/.*%.conf'] = { 'dosini', { priority = 10 } }, + -- A pattern containing an environment variable + ['${XDG_CONFIG_HOME}/foo/git'] = 'git', + ['README.(%a+)$'] = function(path, bufnr, ext) + if ext == 'md' then + return 'markdown' + elseif ext == 'rst' then + return 'rst' + end + end, + }, + }) < To add a fallback match on contents, use >lua - - vim.filetype.add { - pattern = { - ['.*'] = { - priority = -math.huge, - function(path, bufnr) - local content = vim.filetype.getlines(bufnr, 1) - if vim.filetype.matchregex(content, [[^#!.*\<mine\>]]) then - return 'mine' - elseif vim.filetype.matchregex(content, [[\<drawing\>]]) then - return 'drawing' - end - end, - }, - }, - } + vim.filetype.add { + pattern = { + ['.*'] = { + priority = -math.huge, + function(path, bufnr) + local content = vim.api.nvim_buf_get_lines(bufnr, 0, 1, false)[1] or '' + if vim.regex([[^#!.*\\<mine\\>]]):match_str(content) ~= nil then + return 'mine' + elseif vim.regex([[\\<drawing\\>]]):match_str(content) ~= nil then + return 'drawing' + end + end, + }, + }, + } < Parameters: ~ • {filetypes} (table) A table containing new filetype maps (see example). -match({args}) *vim.filetype.match()* + *vim.filetype.get_option()* +vim.filetype.get_option({filetype}, {option}) + Get the default option value for a {filetype}. + + The returned value is what would be set in a new buffer after 'filetype' + is set, meaning it should respect all FileType autocmds and ftplugin + files. + + Example: >lua + vim.filetype.get_option('vim', 'commentstring') +< + + Note: this uses |nvim_get_option_value()| but caches the result. This + means |ftplugin| and |FileType| autocommands are only triggered once and + may not reflect later changes. + + Parameters: ~ + • {filetype} (string) Filetype + • {option} (string) Option name + + Return: ~ + string|boolean|integer: Option value + +vim.filetype.match({args}) *vim.filetype.match()* Perform filetype detection. The filetype can be detected using one of three methods: @@ -2192,21 +2734,18 @@ match({args}) *vim.filetype.match()* the filetype. Each of the three options is specified using a key to the single argument - of this function. Example: - - >lua - - -- Using a buffer number - vim.filetype.match({ buf = 42 }) + of this function. Example: >lua + -- Using a buffer number + vim.filetype.match({ buf = 42 }) - -- Override the filename of the given buffer - vim.filetype.match({ buf = 42, filename = 'foo.c' }) + -- Override the filename of the given buffer + vim.filetype.match({ buf = 42, filename = 'foo.c' }) - -- Using a filename without a buffer - vim.filetype.match({ filename = 'main.lua' }) + -- Using a filename without a buffer + vim.filetype.match({ filename = 'main.lua' }) - -- Using file contents - vim.filetype.match({ contents = {'#!/usr/bin/env bash'} }) + -- Using file contents + vim.filetype.match({ contents = {'#!/usr/bin/env bash'} }) < Parameters: ~ @@ -2225,7 +2764,7 @@ match({args}) *vim.filetype.match()* contents to use for matching. Can be used with {filename}. Mutually exclusive with {buf}. - Return: ~ + Return (multiple): ~ (string|nil) If a match was found, the matched filetype. (function|nil) A function that modifies buffer state when called (for example, to set some filetype specific buffer variables). The function @@ -2233,138 +2772,145 @@ match({args}) *vim.filetype.match()* ============================================================================== -Lua module: keymap *lua-keymap* +Lua module: vim.keymap *vim.keymap* -del({modes}, {lhs}, {opts}) *vim.keymap.del()* +vim.keymap.del({modes}, {lhs}, {opts}) *vim.keymap.del()* Remove an existing mapping. Examples: >lua + vim.keymap.del('n', 'lhs') - vim.keymap.del('n', 'lhs') - - vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 }) + vim.keymap.del({'n', 'i', 'v'}, '<leader>w', { buffer = 5 }) < Parameters: ~ • {opts} (table|nil) A table of optional arguments: - • buffer: (number or boolean) Remove a mapping from the given - buffer. When "true" or 0, use the current buffer. + • "buffer": (integer|boolean) Remove a mapping from the given + buffer. When `0` or `true`, use the current buffer. See also: ~ - |vim.keymap.set()| - -set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* - Add a new |mapping|. Examples: >lua - - -- Can add mapping to Lua functions - vim.keymap.set('n', 'lhs', function() print("real lua function") end) - - -- Can use it to map multiple modes - vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer=true }) - - -- Can add mapping for specific buffer - vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 }) - - -- Expr mappings - vim.keymap.set('i', '<Tab>', function() - return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" - end, { expr = true }) - -- <Plug> mappings - vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)') -< - - Note that in a mapping like: >lua - - vim.keymap.set('n', 'asdf', require('jkl').my_fun) -< - - the `require('jkl')` gets evaluated during this call in order to access the function. If you - want to avoid this cost at startup you can wrap it in a function, for - example: >lua - - vim.keymap.set('n', 'asdf', function() return require('jkl').my_fun() end) + • |vim.keymap.set()| + +vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()* + Adds a new |mapping|. Examples: >lua + -- Map to a Lua function: + vim.keymap.set('n', 'lhs', function() print("real lua function") end) + -- Map to multiple modes: + vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, { buffer = true }) + -- Buffer-local mapping: + vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", { silent = true, buffer = 5 }) + -- Expr mapping: + vim.keymap.set('i', '<Tab>', function() + return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>" + end, { expr = true }) + -- <Plug> mapping: + vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)') < Parameters: ~ - • {mode} string|table Same mode short names as |nvim_set_keymap()|. Can + • {mode} string|table Mode short-name, see |nvim_set_keymap()|. Can also be list of modes to create mapping on multiple modes. • {lhs} (string) Left-hand side |{lhs}| of the mapping. - • {rhs} string|function Right-hand side |{rhs}| of the mapping. Can - also be a Lua function. - • {opts} (table|nil) A table of |:map-arguments|. - • Accepts options accepted by the {opts} parameter in - |nvim_set_keymap()|, with the following notable differences: - • replace_keycodes: Defaults to `true` if "expr" is `true`. - • noremap: Always overridden with the inverse of "remap" - (see below). - - • In addition to those options, the table accepts the - following keys: - • buffer: (number or boolean) Add a mapping to the given - buffer. When `0` or `true`, use the current buffer. - • remap: (boolean) Make the mapping recursive. This is the - inverse of the "noremap" option from |nvim_set_keymap()|. - Defaults to `false`. + • {rhs} string|function Right-hand side |{rhs}| of the mapping, can be + a Lua function. + • {opts} (table|nil) Table of |:map-arguments|. + • Same as |nvim_set_keymap()| {opts}, except: + • "replace_keycodes" defaults to `true` if "expr" is `true`. + • "noremap": inverse of "remap" (see below). + + • Also accepts: + • "buffer": (integer|boolean) Creates buffer-local mapping, + `0` or `true` for current buffer. + • "remap": (boolean) Make the mapping recursive. Inverse of + "noremap". Defaults to `false`. See also: ~ - |nvim_set_keymap()| + • |nvim_set_keymap()| + • |maparg()| + • |mapcheck()| + • |mapset()| ============================================================================== -Lua module: fs *lua-fs* +Lua module: vim.fs *vim.fs* -basename({file}) *vim.fs.basename()* - Return the basename of the given file or directory +vim.fs.basename({file}) *vim.fs.basename()* + Return the basename of the given path Parameters: ~ - • {file} (string) File or directory + • {file} (string) Path Return: ~ - (string) Basename of {file} + (string|nil) Basename of {file} -dir({path}, {opts}) *vim.fs.dir()* - Return an iterator over the files and directories located in {path} +vim.fs.dir({path}, {opts}) *vim.fs.dir()* + Return an iterator over the items located in {path} Parameters: ~ • {path} (string) An absolute or relative path to the directory to iterate over. The path is first normalized |vim.fs.normalize()|. - • {opts} table|nil Optional keyword arguments: + • {opts} (table|nil) Optional keyword arguments: • depth: integer|nil How deep the traverse (default 1) • skip: (fun(dir_name: string): boolean)|nil Predicate to control traversal. Return false to stop searching the current directory. Only useful when depth > 1 Return: ~ - Iterator over files and directories in {path}. Each iteration yields - two values: name and type. Each "name" is the basename of the file or - directory relative to {path}. Type is one of "file" or "directory". + Iterator over items in {path}. Each iteration yields two values: + "name" and "type". "name" is the basename of the item relative to + {path}. "type" is one of the following: "file", "directory", "link", + "fifo", "socket", "char", "block", "unknown". -dirname({file}) *vim.fs.dirname()* - Return the parent directory of the given file or directory +vim.fs.dirname({file}) *vim.fs.dirname()* + Return the parent directory of the given path Parameters: ~ - • {file} (string) File or directory + • {file} (string) Path Return: ~ - (string) Parent directory of {file} + (string|nil) Parent directory of {file} -find({names}, {opts}) *vim.fs.find()* - Find files or directories in the given path. +vim.fs.find({names}, {opts}) *vim.fs.find()* + Find files or directories (or other items as specified by `opts.type`) in + the given path. - Finds any files or directories given in {names} starting from {path}. If - {upward} is "true" then the search traverses upward through parent - directories; otherwise, the search traverses downward. Note that downward - searches are recursive and may search through many directories! If {stop} - is non-nil, then the search stops when the directory given in {stop} is - reached. The search terminates when {limit} (default 1) matches are found. - The search can be narrowed to find only files or only directories by - specifying {type} to be "file" or "directory", respectively. + Finds items given in {names} starting from {path}. If {upward} is "true" + then the search traverses upward through parent directories; otherwise, + the search traverses downward. Note that downward searches are recursive + and may search through many directories! If {stop} is non-nil, then the + search stops when the directory given in {stop} is reached. The search + terminates when {limit} (default 1) matches are found. You can set {type} + to "file", "directory", "link", "socket", "char", "block", or "fifo" to + narrow the search to find only that type. + + Examples: >lua + -- location of Cargo.toml from the current buffer's path + local cargo = vim.fs.find('Cargo.toml', { + upward = true, + stop = vim.uv.os_homedir(), + path = vim.fs.dirname(vim.api.nvim_buf_get_name(0)), + }) + + -- list all test directories under the runtime directory + local test_dirs = vim.fs.find( + {'test', 'tst', 'testdir'}, + {limit = math.huge, type = 'directory', path = './runtime/'} + ) + + -- get all files ending with .cpp or .hpp inside lib/ + local cpp_hpp = vim.fs.find(function(name, path) + return name:match('.*%.[ch]pp$') and path:match('[/\\\\]lib$') + end, {limit = math.huge, type = 'file'}) +< Parameters: ~ - • {names} (string|table|fun(name: string): boolean) Names of the files - and directories to find. Must be base names, paths and globs - are not supported. The function is called per file and - directory within the traversed directories to test if they - match {names}. + • {names} (string|string[]|fun(name: string, path: string): boolean) + Names of the items to find. Must be base names, paths and + globs are not supported when {names} is a string or a table. + If {names} is a function, it is called for each traversed + item with args: + • name: base name of the current item + • path: full path of the current item The function should + return `true` if the given item is considered a match. • {opts} (table) Optional keyword arguments: • path (string): Path to begin searching from. If omitted, the |current-directory| is used. @@ -2373,70 +2919,81 @@ find({names}, {opts}) *vim.fs.find()* directories (recursively). • stop (string): Stop searching when this directory is reached. The directory itself is not searched. - • type (string): Find only files ("file") or directories - ("directory"). If omitted, both files and directories that - match {names} are included. + • type (string): Find only items of the given type. If + omitted, all items that match {names} are included. • limit (number, default 1): Stop the search after finding this many matches. Use `math.huge` to place no limit on the number of matches. Return: ~ - (table) Normalized paths |vim.fs.normalize()| of all matching files or - directories + (string[]) Normalized paths |vim.fs.normalize()| of all matching items + +vim.fs.joinpath({...}) *vim.fs.joinpath()* + Concatenate directories and/or file paths into a single path with + normalization (e.g., `"foo/"` and `"bar"` get joined to `"foo/bar"`) + + Parameters: ~ + • {...} (string) + + Return: ~ + (string) -normalize({path}) *vim.fs.normalize()* +vim.fs.normalize({path}, {opts}) *vim.fs.normalize()* Normalize a path to a standard format. A tilde (~) character at the beginning of the path is expanded to the user's home directory and any backslash (\) characters are converted to forward slashes (/). Environment variables are also expanded. Examples: >lua + vim.fs.normalize('C:\\\\Users\\\\jdoe') + -- 'C:/Users/jdoe' - vim.fs.normalize('C:\\Users\\jdoe') - --> 'C:/Users/jdoe' - - vim.fs.normalize('~/src/neovim') - --> '/home/jdoe/src/neovim' + vim.fs.normalize('~/src/neovim') + -- '/home/jdoe/src/neovim' - vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim') - --> '/Users/jdoe/.config/nvim/init.vim' + vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim') + -- '/Users/jdoe/.config/nvim/init.vim' < Parameters: ~ • {path} (string) Path to normalize + • {opts} (table|nil) Options: + • expand_env: boolean Expand environment variables (default: + true) Return: ~ (string) Normalized path -parents({start}) *vim.fs.parents()* - Iterate over all the parents of the given file or directory. +vim.fs.parents({start}) *vim.fs.parents()* + Iterate over all the parents of the given path. Example: >lua + local root_dir + for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do + if vim.fn.isdirectory(dir .. "/.git") == 1 then + root_dir = dir + break + end + end - local root_dir - for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do - if vim.fn.isdirectory(dir .. "/.git") == 1 then - root_dir = dir - break - end - end - - if root_dir then - print("Found git repository at", root_dir) - end + if root_dir then + print("Found git repository at", root_dir) + end < Parameters: ~ - • {start} (string) Initial file or directory. + • {start} (string) Initial path. - Return: ~ - (function) Iterator + Return (multiple): ~ + fun(_, dir: string): string? Iterator + nil + (string|nil) ============================================================================== -Lua module: secure *lua-secure* +Lua module: vim.secure *vim.secure* -read({path}) *vim.secure.read()* +vim.secure.read({path}) *vim.secure.read()* Attempt to read the file at {path} prompting the user if the file should be trusted. The user's choice is persisted in a trust database at $XDG_STATE_HOME/nvim/trust. @@ -2449,9 +3006,9 @@ read({path}) *vim.secure.read()* trusted, or nil otherwise. See also: ~ - |:trust| + • |:trust| -trust({opts}) *vim.secure.trust()* +vim.secure.trust({opts}) *vim.secure.trust()* Manage the trust database. The trust database is located at |$XDG_STATE_HOME|/nvim/trust. @@ -2467,9 +3024,743 @@ trust({opts}) *vim.secure.trust()* • bufnr (number|nil): Buffer number to update. Mutually exclusive with {path}. + Return (multiple): ~ + (boolean) success true if operation was successful + (string) msg full path if operation was successful, else error message + + +============================================================================== +Lua module: vim.version *vim.version* + + +The `vim.version` module provides functions for comparing versions and +ranges conforming to the + +https://semver.org + +spec. Plugins, and plugin managers, can use this to check available tools +and dependencies on the current system. + +Example: >lua + local v = vim.version.parse(vim.fn.system({'tmux', '-V'}), {strict=false}) + if vim.version.gt(v, {3, 2, 0}) then + -- ... + end + +< + +*vim.version()* returns the version of the current Nvim process. + +VERSION RANGE SPEC *version-range* + +A version "range spec" defines a semantic version range which can be +tested against a version, using |vim.version.range()|. + +Supported range specs are shown in the following table. Note: suffixed +versions (1.2.3-rc1) are not matched. > + 1.2.3 is 1.2.3 + =1.2.3 is 1.2.3 + >1.2.3 greater than 1.2.3 + <1.2.3 before 1.2.3 + >=1.2.3 at least 1.2.3 + ~1.2.3 is >=1.2.3 <1.3.0 "reasonably close to 1.2.3" + ^1.2.3 is >=1.2.3 <2.0.0 "compatible with 1.2.3" + ^0.2.3 is >=0.2.3 <0.3.0 (0.x.x is special) + ^0.0.1 is =0.0.1 (0.0.x is special) + ^1.2 is >=1.2.0 <2.0.0 (like ^1.2.0) + ~1.2 is >=1.2.0 <1.3.0 (like ~1.2.0) + ^1 is >=1.0.0 <2.0.0 "compatible with 1" + ~1 same "reasonably close to 1" + 1.x same + 1.* same + 1 same + * any version + x same + + 1.2.3 - 2.3.4 is >=1.2.3 <=2.3.4 + + Partial right: missing pieces treated as x (2.3 => 2.3.x). + 1.2.3 - 2.3 is >=1.2.3 <2.4.0 + 1.2.3 - 2 is >=1.2.3 <3.0.0 + + Partial left: missing pieces treated as 0 (1.2 => 1.2.0). + 1.2 - 2.3.0 is 1.2.0 - 2.3.0 + +< + +vim.version.cmp({v1}, {v2}) *vim.version.cmp()* + Parses and compares two version objects (the result of + |vim.version.parse()|, or specified literally as a `{major, minor, patch}` + tuple, e.g. `{1, 0, 3}`). + + Example: >lua + if vim.version.cmp({1,0,3}, {0,2,1}) == 0 then + -- ... + end + local v1 = vim.version.parse('1.0.3-pre') + local v2 = vim.version.parse('0.2.1') + if vim.version.cmp(v1, v2) == 0 then + -- ... + end +< + + Note: ~ + • Per semver, build metadata is ignored when comparing two + otherwise-equivalent versions. + + Parameters: ~ + • {v1} Version|number[] Version object. + • {v2} Version|number[] Version to compare with `v1` . + + Return: ~ + (integer) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`. + +vim.version.eq({v1}, {v2}) *vim.version.eq()* + Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage. + + Parameters: ~ + • {v1} Version|number[] + • {v2} Version|number[] + + Return: ~ + (boolean) + +vim.version.gt({v1}, {v2}) *vim.version.gt()* + Returns `true` if `v1 > v2` . See |vim.version.cmp()| for usage. + + Parameters: ~ + • {v1} Version|number[] + • {v2} Version|number[] + + Return: ~ + (boolean) + +vim.version.last({versions}) *vim.version.last()* + TODO: generalize this, move to func.lua + + Parameters: ~ + • {versions} Version [] + + Return: ~ + Version ?|nil + +vim.version.lt({v1}, {v2}) *vim.version.lt()* + Returns `true` if `v1 < v2` . See |vim.version.cmp()| for usage. + + Parameters: ~ + • {v1} Version|number[] + • {v2} Version|number[] + + Return: ~ + (boolean) + +vim.version.parse({version}, {opts}) *vim.version.parse()* + Parses a semantic version string and returns a version object which can be + used with other `vim.version` functions. For example "1.0.1-rc1+build.2" + returns: > + { major = 1, minor = 0, patch = 1, prerelease = "rc1", build = "build.2" } +< + + Parameters: ~ + • {version} (string) Version string to parse. + • {opts} (table|nil) Optional keyword arguments: + • strict (boolean): Default false. If `true`, no coercion + is attempted on input not conforming to semver v2.0.0. If + `false`, `parse()` attempts to coerce input such as + "1.0", "0-x", "tmux 3.2a" into valid versions. + + Return: ~ + (table|nil) parsed_version Version object or `nil` if input is invalid. + + See also: ~ + • # https://semver.org/spec/v2.0.0.html + +vim.version.range({spec}) *vim.version.range()* + Parses a semver |version-range| "spec" and returns a range object: > + { + from: Version + to: Version + has(v: string|Version) + } +< + + `:has()` checks if a version is in the range (inclusive `from`, exclusive + `to`). + + Example: >lua + local r = vim.version.range('1.0.0 - 2.0.0') + print(r:has('1.9.9')) -- true + print(r:has('2.0.0')) -- false + print(r:has(vim.version())) -- check against current Nvim version +< + + Or use cmp(), eq(), lt(), and gt() to compare `.to` and `.from` directly: >lua + local r = vim.version.range('1.0.0 - 2.0.0') + print(vim.version.gt({1,0,3}, r.from) and vim.version.lt({1,0,3}, r.to)) +< + + Parameters: ~ + • {spec} (string) Version range "spec" + + See also: ~ + • # https://github.com/npm/node-semver#ranges + + +============================================================================== +Lua module: vim.iter *vim.iter* + + +*vim.iter()* is an interface for |iterable|s: it wraps a table or function +argument into an *Iter* object with methods (such as |Iter:filter()| and +|Iter:map()|) that transform the underlying source data. These methods can +be chained to create iterator "pipelines": the output of each pipeline +stage is input to the next stage. The first stage depends on the type +passed to `vim.iter()`: + +• List tables (arrays, |lua-list|) yield only the value of each element. + • Use |Iter:enumerate()| to also pass the index to the next stage. + • Or initialize with ipairs(): `vim.iter(ipairs(…))`. + +• Non-list tables (|lua-dict|) yield both the key and value of each + element. +• Function |iterator|s yield all values returned by the underlying + function. +• Tables with a |__call()| metamethod are treated as function iterators. + +The iterator pipeline terminates when the underlying |iterable| is +exhausted (for function iterators this means it returned nil). + +Note: `vim.iter()` scans table input to decide if it is a list or a dict; +to avoid this cost you can wrap the table with an iterator e.g. +`vim.iter(ipairs({…}))`, but that precludes the use of |list-iterator| +operations such as |Iter:rev()|). + +Examples: >lua + local it = vim.iter({ 1, 2, 3, 4, 5 }) + it:map(function(v) + return v * 3 + end) + it:rev() + it:skip(2) + it:totable() + -- { 9, 6, 3 } + + -- ipairs() is a function iterator which returns both the index (i) and the value (v) + vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v) + if i > 2 then return v end + end):totable() + -- { 3, 4, 5 } + + local it = vim.iter(vim.gsplit('1,2,3,4,5', ',')) + it:map(function(s) return tonumber(s) end) + for i, d in it:enumerate() do + print(string.format("Column %d is %d", i, d)) + end + -- Column 1 is 1 + -- Column 2 is 2 + -- Column 3 is 3 + -- Column 4 is 4 + -- Column 5 is 5 + + vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v) + return k == 'z' + end) + -- true + + local rb = vim.ringbuf(3) + rb:push("a") + rb:push("b") + vim.iter(rb):totable() + -- { "a", "b" } + +< + +In addition to the |vim.iter()| function, the |vim.iter| module provides +convenience functions like |vim.iter.filter()| and |vim.iter.totable()|. + +filter({f}, {src}, {...}) *vim.iter.filter()* + Filters a table or other |iterable|. >lua + -- Equivalent to: + vim.iter(src):filter(f):totable() +< + + Parameters: ~ + • {f} function(...):bool Filter function. Accepts the current + iterator or table values as arguments and returns true if those + values should be kept in the final table + • {src} table|function Table or iterator function to filter + + Return: ~ + (table) + + See also: ~ + • |Iter:filter()| + +Iter:all({pred}) *Iter:all()* + Returns true if all items in the iterator match the given predicate. + + Parameters: ~ + • {pred} function(...):bool Predicate function. Takes all values + returned from the previous stage in the pipeline as arguments + and returns true if the predicate matches. + +Iter:any({pred}) *Iter:any()* + Returns true if any of the items in the iterator match the given + predicate. + + Parameters: ~ + • {pred} function(...):bool Predicate function. Takes all values + returned from the previous stage in the pipeline as arguments + and returns true if the predicate matches. + +Iter:each({f}) *Iter:each()* + Calls a function once for each item in the pipeline, draining the + iterator. + + For functions with side effects. To modify the values in the iterator, use + |Iter:map()|. + + Parameters: ~ + • {f} function(...) Function to execute for each item in the pipeline. + Takes all of the values returned by the previous stage in the + pipeline as arguments. + +Iter:enumerate() *Iter:enumerate()* + Yields the item index (count) and value for each item of an iterator + pipeline. + + For list tables, this is more efficient: >lua + vim.iter(ipairs(t)) +< + + instead of: >lua + vim.iter(t):enumerate() +< + + Example: >lua + local it = vim.iter(vim.gsplit('abc', '')):enumerate() + it:next() + -- 1 'a' + it:next() + -- 2 'b' + it:next() + -- 3 'c' +< + + Return: ~ + Iter + +Iter:filter({f}) *Iter:filter()* + Filters an iterator pipeline. + + Example: >lua + local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded) +< + + Parameters: ~ + • {f} function(...):bool Takes all values returned from the previous + stage in the pipeline and returns false or nil if the current + iterator element should be removed. + + Return: ~ + Iter + +Iter:find({f}) *Iter:find()* + Find the first value in the iterator that satisfies the given predicate. + + Advances the iterator. Returns nil and drains the iterator if no value is + found. + + Examples: >lua + local it = vim.iter({ 3, 6, 9, 12 }) + it:find(12) + -- 12 + + local it = vim.iter({ 3, 6, 9, 12 }) + it:find(20) + -- nil + + local it = vim.iter({ 3, 6, 9, 12 }) + it:find(function(v) return v % 4 == 0 end) + -- 12 +< + + Return: ~ + any + +Iter:fold({init}, {f}) *Iter:fold()* + Folds ("reduces") an iterator into a single value. + + Examples: >lua + -- Create a new table with only even values + local t = { a = 1, b = 2, c = 3, d = 4 } + local it = vim.iter(t) + it:filter(function(k, v) return v % 2 == 0 end) + it:fold({}, function(t, k, v) + t[k] = v + return t + end) + -- { b = 2, d = 4 } +< + + Parameters: ~ + • {init} any Initial value of the accumulator. + • {f} function(acc:any, ...):A Accumulation function. + + Return: ~ + any + +Iter:last() *Iter:last()* + Drains the iterator and returns the last item. + + Example: >lua + local it = vim.iter(vim.gsplit('abcdefg', '')) + it:last() + -- 'g' + + local it = vim.iter({ 3, 6, 9, 12, 15 }) + it:last() + -- 15 +< + + Return: ~ + any + +Iter:map({f}) *Iter:map()* + Maps the items of an iterator pipeline to the values returned by `f`. + + If the map function returns nil, the value is filtered from the iterator. + + Example: >lua + local it = vim.iter({ 1, 2, 3, 4 }):map(function(v) + if v % 2 == 0 then + return v * 3 + end + end) + it:totable() + -- { 6, 12 } +< + + Parameters: ~ + • {f} function(...):any Mapping function. Takes all values returned + from the previous stage in the pipeline as arguments and returns + one or more new values, which are used in the next pipeline + stage. Nil return values are filtered from the output. + + Return: ~ + Iter + +Iter:next() *Iter:next()* + Gets the next value from the iterator. + + Example: >lua + local it = vim.iter(string.gmatch('1 2 3', '%d+')):map(tonumber) + it:next() + -- 1 + it:next() + -- 2 + it:next() + -- 3 +< + + Return: ~ + any + +Iter:nextback() *Iter:nextback()* + "Pops" a value from a |list-iterator| (gets the last value and decrements + the tail). + + Example: >lua + local it = vim.iter({1, 2, 3, 4}) + it:nextback() + -- 4 + it:nextback() + -- 3 +< + + Return: ~ + any + +Iter:nth({n}) *Iter:nth()* + Gets the nth value of an iterator (and advances to it). + + Example: >lua + local it = vim.iter({ 3, 6, 9, 12 }) + it:nth(2) + -- 6 + it:nth(2) + -- 12 +< + + Parameters: ~ + • {n} (number) The index of the value to return. + + Return: ~ + any + +Iter:nthback({n}) *Iter:nthback()* + Gets the nth value from the end of a |list-iterator| (and advances to it). + + Example: >lua + local it = vim.iter({ 3, 6, 9, 12 }) + it:nthback(2) + -- 9 + it:nthback(2) + -- 3 +< + + Parameters: ~ + • {n} (number) The index of the value to return. + + Return: ~ + any + +Iter:peek() *Iter:peek()* + Gets the next value in a |list-iterator| without consuming it. + + Example: >lua + local it = vim.iter({ 3, 6, 9, 12 }) + it:peek() + -- 3 + it:peek() + -- 3 + it:next() + -- 3 +< + + Return: ~ + any + +Iter:peekback() *Iter:peekback()* + Gets the last value of a |list-iterator| without consuming it. + + See also |Iter:last()|. + + Example: >lua + local it = vim.iter({1, 2, 3, 4}) + it:peekback() + -- 4 + it:peekback() + -- 4 + it:nextback() + -- 4 +< + + Return: ~ + any + +Iter:rev() *Iter:rev()* + Reverses a |list-iterator| pipeline. + + Example: >lua + local it = vim.iter({ 3, 6, 9, 12 }):rev() + it:totable() + -- { 12, 9, 6, 3 } +< + + Return: ~ + Iter + +Iter:rfind({f}) *Iter:rfind()* + Gets the first value in a |list-iterator| that satisfies a predicate, + starting from the end. + + Advances the iterator. Returns nil and drains the iterator if no value is + found. + + Examples: >lua + local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate() + it:rfind(1) + -- 5 1 + it:rfind(1) + -- 1 1 +< + + Return: ~ + any + + See also: ~ + • Iter.find + +Iter:skip({n}) *Iter:skip()* + Skips `n` values of an iterator pipeline. + + Example: >lua + local it = vim.iter({ 3, 6, 9, 12 }):skip(2) + it:next() + -- 9 +< + + Parameters: ~ + • {n} (number) Number of values to skip. + + Return: ~ + Iter + +Iter:skipback({n}) *Iter:skipback()* + Skips `n` values backwards from the end of a |list-iterator| pipeline. + + Example: >lua + local it = vim.iter({ 1, 2, 3, 4, 5 }):skipback(2) + it:next() + -- 1 + it:nextback() + -- 3 +< + + Parameters: ~ + • {n} (number) Number of values to skip. + + Return: ~ + Iter + +Iter:slice({first}, {last}) *Iter:slice()* + Sets the start and end of a |list-iterator| pipeline. + + Equivalent to `:skip(first - 1):skipback(len - last + 1)`. + + Parameters: ~ + • {first} (number) + • {last} (number) + + Return: ~ + Iter + +Iter:totable() *Iter:totable()* + Collect the iterator into a table. + + The resulting table depends on the initial source in the iterator + pipeline. List-like tables and function iterators will be collected into a + list-like table. If multiple values are returned from the final stage in + the iterator pipeline, each value will be included in a table. + + Examples: >lua + vim.iter(string.gmatch('100 20 50', '%d+')):map(tonumber):totable() + -- { 100, 20, 50 } + + vim.iter({ 1, 2, 3 }):map(function(v) return v, 2 * v end):totable() + -- { { 1, 2 }, { 2, 4 }, { 3, 6 } } + + vim.iter({ a = 1, b = 2, c = 3 }):filter(function(k, v) return v % 2 ~= 0 end):totable() + -- { { 'a', 1 }, { 'c', 3 } } +< + + The generated table is a list-like table with consecutive, numeric + indices. To create a map-like table with arbitrary keys, use + |Iter:fold()|. + + Return: ~ + (table) + +map({f}, {src}, {...}) *vim.iter.map()* + Maps a table or other |iterable|. >lua + -- Equivalent to: + vim.iter(src):map(f):totable() +< + + Parameters: ~ + • {f} function(...):?any Map function. Accepts the current iterator + or table values as arguments and returns one or more new + values. Nil values are removed from the final table. + • {src} table|function Table or iterator function to filter + + Return: ~ + (table) + + See also: ~ + • |Iter:map()| + +totable({f}, {...}) *vim.iter.totable()* + Collects an |iterable| into a table. >lua + -- Equivalent to: + vim.iter(f):totable() +< + + Parameters: ~ + • {f} (function) Iterator function + + Return: ~ + (table) + + +============================================================================== +Lua module: vim.snippet *vim.snippet* + +vim.snippet.active() *vim.snippet.active()* + Returns `true` if there's an active snippet in the current buffer. + + Return: ~ + (boolean) + +vim.snippet.exit() *vim.snippet.exit()* + Exits the current snippet. + +vim.snippet.expand({input}) *vim.snippet.expand()* + Expands the given snippet text. Refer to https://microsoft.github.io/language-server-protocol/specification/#snippet_syntax for the specification of valid input. + + Tabstops are highlighted with hl-SnippetTabstop. + + Parameters: ~ + • {input} (string) + +vim.snippet.jump({direction}) *vim.snippet.jump()* + Jumps within the active snippet in the given direction. If the jump isn't + possible, the function call does nothing. + + You can use this function to navigate a snippet as follows: >lua + vim.keymap.set({ 'i', 's' }, '<Tab>', function() + if vim.snippet.jumpable(1) then + return '<cmd>lua vim.snippet.jump(1)<cr>' + else + return '<Tab>' + end + end, { expr = true }) +< + + Parameters: ~ + • {direction} (vim.snippet.Direction) Navigation direction. -1 for + previous, 1 for next. + +vim.snippet.jumpable({direction}) *vim.snippet.jumpable()* + Returns `true` if there is an active snippet which can be jumped in the + given direction. You can use this function to navigate a snippet as + follows: >lua + vim.keymap.set({ 'i', 's' }, '<Tab>', function() + if vim.snippet.jumpable(1) then + return '<cmd>lua vim.snippet.jump(1)<cr>' + else + return '<Tab>' + end + end, { expr = true }) +< + + Parameters: ~ + • {direction} (vim.snippet.Direction) Navigation direction. -1 for + previous, 1 for next. + + Return: ~ + (boolean) + + +============================================================================== +Lua module: vim.text *vim.text* + +vim.text.hexdecode({enc}) *vim.text.hexdecode()* + Hex decode a string. + + Parameters: ~ + • {enc} (string) String to decode + + Return: ~ + (string) Decoded string + +vim.text.hexencode({str}) *vim.text.hexencode()* + Hex encode a string. + + Parameters: ~ + • {str} (string) String to encode + Return: ~ - (boolean, string) success, msg: - • true and full path of target file if operation was successful - • false and error message on failure + (string) Hex encoded string vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt index aafdd5c43e..467b5760cf 100644 --- a/runtime/doc/luaref.txt +++ b/runtime/doc/luaref.txt @@ -1,5 +1,5 @@ *luaref.txt* Nvim - *luaref* *Lua-Reference* + *luaref* LUA REFERENCE MANUAL @@ -16,14 +16,14 @@ Copyright (c) 2006 Lua.org, PUC-Rio. - See |luaref-doc| for information on this manual. - See |luaref-copyright| for copyright and licenses. + See |lua-ref-doc| for information on this manual. + See |lua-ref-copyright| for copyright and licenses. Type |gO| to see the table of contents. ============================================================================== -1 INTRODUCTION *luaref-intro* +1 INTRODUCTION *luaref-intro* Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good @@ -47,13 +47,13 @@ Lua's official web site, www.lua.org. Like any other reference manual, this document is dry in places. For a discussion of the decisions behind the design of Lua, see references at -|luaref-bibliography|. For a detailed introduction to programming in Lua, see +|lua-ref-bibliography|. For a detailed introduction to programming in Lua, see Roberto's book, Programming in Lua. Lua means "moon" in Portuguese and is pronounced LOO-ah. ============================================================================== -2 THE LANGUAGE *luaref-language* +2 THE LANGUAGE *lua-language* This section describes the lexis, the syntax, and the semantics of Lua. In other words, this section describes which tokens are valid, how they can be @@ -63,9 +63,9 @@ The language constructs will be explained using the usual extended BNF notation, in which `{ a }` means 0 or more `a`'s, and `[ a ]` means an optional `a`. ============================================================================== -2.1 Lexical Conventions *luaref-langLexConv* +2.1 Lexical Conventions *lua-lexical* - *luaref-names* *luaref-identifiers* + *lua-names* *lua-identifiers* Names (also called identifiers) in Lua can be any string of letters, digits, and underscores, not beginning with a digit. This coincides with the definition of identifiers in most languages. (The definition of letter depends @@ -92,7 +92,7 @@ The following strings denote other tokens: ( ) { } [ ] ; : , . .. ... < - *luaref-literal* + *lua-literal* Literal strings can be delimited by matching single or double quotes, and can contain the following C-like escape sequences: @@ -146,14 +146,14 @@ coded as 49), the five literals below denote the same string: alo 123"]==] < - *luaref-numconstant* + *lua-numconstant* A numerical constant may be written with an optional decimal part and an optional decimal exponent. Lua also accepts integer hexadecimal constants, by prefixing them with `0x`. Examples of valid numerical constants are > 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56 < - *luaref-comment* + *lua-comment* A comment starts with a double hyphen (`--`) anywhere outside a string. If the text immediately after `--` is not an opening long bracket, the comment is a short comment, which runs until the end of the line. Otherwise, it is a long @@ -161,7 +161,7 @@ comment, which runs until the corresponding closing long bracket. Long comments are frequently used to disable code temporarily. ============================================================================== -2.2 Values and Types *luaref-langValTypes* +2.2 Values and Types *lua-values* Lua is a dynamically typed language. This means that variables do not have types; only values do. There are no type definitions in the language. All @@ -171,9 +171,9 @@ All values in Lua are first-class values. This means that all values can be stored in variables, passed as arguments to other functions, and returned as results. - *luaref-types* *luaref-nil* - *luaref-true* *luaref-false* - *luaref-number* *luaref-string* + *lua-types* *lua-nil* + *lua-true* *lua-false* + *lua-number* *lua-string* There are eight basic types in Lua: `nil`, `boolean`, `number`, `string`, `function`, `userdata`, `thread`, and `table`. Nil is the type of the value `nil`, whose main property is to be different from any other value; it usually @@ -184,27 +184,27 @@ numbers. (It is easy to build Lua interpreters that use other internal representations for numbers, such as single-precision float or long integers; see file `luaconf.h`.) String represents arrays of characters. Lua is 8-bit clean: strings may contain any 8-bit character, including embedded zeros -(`\0`) (see |luaref-literal|). +(`\0`) (see |lua-literal|). Lua can call (and manipulate) functions written in Lua and functions written -in C (see |luaref-langFuncCalls|). +in C (see |lua-function|). - *luaref-userdatatype* + *lua-userdatatype* The type userdata is provided to allow arbitrary C data to be stored in Lua variables. This type corresponds to a block of raw memory and has no pre-defined operations in Lua, except assignment and identity test. However, by using metatables, the programmer can define operations for userdata values -(see |luaref-langMetatables|). Userdata values cannot be created or modified -in Lua, only through the C API. This guarantees the integrity of data owned by -the host program. +(see |lua-metatable|). Userdata values cannot be created or modified in Lua, +only through the C API. This guarantees the integrity of data owned by the +host program. - *luaref-thread* + *lua-thread* The type `thread` represents independent threads of execution and it is used to -implement coroutines (see |luaref-langCoro|). Do not confuse Lua threads with +implement coroutines (see |lua-coroutine|). Do not confuse Lua threads with operating-system threads. Lua supports coroutines on all systems, even those that do not support threads. - *luaref-table* + *lua-table* The type `table` implements associative arrays, that is, arrays that can be indexed not only with numbers, but with any value (except `nil`). Tables can be heterogeneous; that is, they can contain values of all types (except @@ -213,11 +213,11 @@ used to represent ordinary arrays, symbol tables, sets, records, graphs, trees, etc. To represent records, Lua uses the field name as an index. The language supports this representation by providing `a.name` as syntactic sugar for `a["name"]`. There are several convenient ways to create tables in Lua -(see |luaref-langTableConst|). +(see |lua-tableconstructor|). Like indices, the value of a table field can be of any type (except `nil`). In particular, because functions are first-class values, table fields may contain -functions. Thus tables may also carry methods (see |luaref-langFuncDefs|). +functions. Thus tables may also carry methods (see |lua-function-define|). Tables, functions, threads and (full) userdata values are objects: variables do not actually contain these values, only references to them. Assignment, @@ -225,10 +225,10 @@ parameter passing, and function returns always manipulate references to such values; these operations do not imply any kind of copy. The library function `type` returns a string describing the type of a given -value (see |luaref-type()|). +value (see |lua-type()|). ------------------------------------------------------------------------------ -2.2.1 Coercion *luaref-langCoercion* +2.2.1 Coercion *lua-coercion* Lua provides automatic conversion between string and number values at run time. Any arithmetic operation applied to a string tries to convert that @@ -239,7 +239,7 @@ converted to strings, use the `format` function from the string library (see |string.format()|). ============================================================================== -2.3 Variables *luaref-langVariables* +2.3 Variables *lua-variables* Variables are places that store values. There are three kinds of variables in Lua: global variables, local variables, and table fields. @@ -249,12 +249,12 @@ function's formal parameter, which is a particular form of local variable): > var ::= Name < -Name denotes identifiers, as defined in |luaref-langLexConv|. +Name denotes identifiers, as defined in |lua-lexical|. Any variable is assumed to be global unless explicitly declared as a local -(see |luaref-langLocalDec|). Local variables are lexically scoped: local +(see |lua-local|). Local variables are lexically scoped: local variables can be freely accessed by functions defined inside their scope (see -|luaref-langVisibRules|). +|lua-visibility|). Before the first assignment to a variable, its value is `nil`. @@ -265,21 +265,21 @@ Square brackets are used to index a table: The first expression (`prefixexp`) should result in a table value; the second expression (`exp`) identifies a specific entry inside that table. The expression denoting the table to be indexed has a restricted syntax; see -|luaref-langExpressions| for details. +|lua-expressions| for details. The syntax `var.NAME` is just syntactic sugar for `var["NAME"]` : > var ::= prefixexp . Name < All global variables live as fields in ordinary Lua tables, called environment -tables or simply environments (see |luaref-langEnvironments|). Each function +tables or simply environments (see |lua-environments|). Each function has its own reference to an environment, so that all global variables in this function will refer to this environment table. When a function is created, it inherits the environment from the function that created it. To get the environment table of a Lua function, you call `getfenv` (see -|lua_getfenv()|). To replace it, you call `setfenv` (see |luaref-setfenv()|). +|lua_getfenv()|). To replace it, you call `setfenv` (see |setfenv()|). (You can only manipulate the environment of C functions through the debug -library; see |luaref-libDebug|.) +library; see |lua-lib-debug|.) An access to a global variable `x` is equivalent to `_env.x`, which in turn is equivalent to @@ -291,19 +291,19 @@ not defined in Lua. We use it here only for explanatory purposes.) The meaning of accesses to global variables and table fields can be changed via metatables. An access to an indexed variable `t[i]` is equivalent to a -call `gettable_event(t,i)`. (See |luaref-langMetatables| for a complete -description of the `gettable_event` function. This function is not defined or -callable in Lua. We use it here only for explanatory purposes.) +call `gettable_event(t,i)`. (See |lua-metatable| for a complete description of +the `gettable_event` function. This function is not defined or callable in +Lua. We use it here only for explanatory purposes.) ============================================================================== -2.4 Statements *luaref-langStats* +2.4 Statements *lua-statement* Lua supports an almost conventional set of statements, similar to those in Pascal or C. This set includes assignment, control structures, function calls, and variable declarations. ------------------------------------------------------------------------------ -2.4.1 Chunks *luaref-chunk* *luaref-langChunks* +2.4.1 Chunks *lua-chunk* The unit of execution of Lua is called a chunk. A chunk is simply a sequence of statements, which are executed sequentially. Each statement can be @@ -314,7 +314,7 @@ optionally followed by a semicolon: There are no empty statements and thus `;;` is not legal. Lua handles a chunk as the body of an anonymous function with a variable -number of arguments (see |luaref-langFuncDefs|). As such, chunks can define +number of arguments (see |lua-function-define|). As such, chunks can define local variables, receive arguments, and return values. A chunk may be stored in a file or in a string inside the host program. When a @@ -327,24 +327,24 @@ details. Programs in source and compiled forms are interchangeable; Lua automatically detects the file type and acts accordingly. ------------------------------------------------------------------------------ -2.4.2 Blocks *luaref-block* *luaref-langBlocks* +2.4.2 Blocks *lua-block* A block is a list of statements; syntactically, a block is the same as a chunk: > block ::= chunk < - *luaref-do* *luaref-end* + *lua-do* *lua-end* A block may be explicitly delimited to produce a single statement: > stat ::= do block end < Explicit blocks are useful to control the scope of variable declarations. Explicit blocks are also sometimes used to add a `return` or `break` statement -in the middle of another block (see |luaref-langContStructs|). +in the middle of another block (see |lua-control|). ------------------------------------------------------------------------------ -2.4.3 Assignment *luaref-langAssign* +2.4.3 Assignment *lua-assign* Lua allows multiple assignment. Therefore, the syntax for assignment defines a list of variables on the left side and a list of expressions on the right @@ -354,7 +354,7 @@ side. The elements in both lists are separated by commas: varlist1 ::= var { , var } explist1 ::= exp { , exp } < -Expressions are discussed in |luaref-langExpressions|. +Expressions are discussed in |lua-expressions|. Before the assignment, the list of values is adjusted to the length of the list of variables. If there are more values than needed, the excess values are @@ -362,7 +362,7 @@ thrown away. If there are fewer values than needed, the list is extended with as many `nil`s as needed. If the list of expressions ends with a function call, then all values returned by this call enter in the list of values, before the adjustment (except when the call is enclosed in parentheses; see -|luaref-langExpressions|). +|lua-expressions|). The assignment statement first evaluates all its expressions and only then are the assignments performed. Thus the code @@ -379,9 +379,9 @@ exchanges the values of `x` and `y`. The meaning of assignments to global variables and table fields can be changed via metatables. An assignment to an indexed variable `t[i] = val` is -equivalent to `settable_event(t,i,val)`. (See |luaref-langMetatables| for a -complete description of the `settable_event` function. This function is not -defined or callable in Lua. We use it here only for explanatory purposes.) +equivalent to `settable_event(t,i,val)`. (See |lua-metatable| for a complete +description of the `settable_event` function. This function is not defined or +callable in Lua. We use it here only for explanatory purposes.) An assignment to a global variable `x = val` is equivalent to the assignment `_env.x = val`, which in turn is equivalent to @@ -392,10 +392,10 @@ where `_env` is the environment of the running function. (The `_env` variable is not defined in Lua. We use it here only for explanatory purposes.) ------------------------------------------------------------------------------ -2.4.4 Control Structures *luaref-langContStructs* +2.4.4 Control Structures *lua-control* - *luaref-if* *luaref-then* *luaref-else* *luaref-elseif* - *luaref-while* *luaref-repeat* *luaref-until* + *lua-if* *lua-then* *lua-else* *lua-elseif* + *lua-while* *lua-repeat* *lua-until* The control structures `if`, `while`, and `repeat` have the usual meaning and familiar syntax: > @@ -404,7 +404,7 @@ familiar syntax: stat ::= if exp then block { elseif exp then block } [ else block ] end < -Lua also has a `for` statement, in two flavors (see |luaref-langForStat|). +Lua also has a `for` statement, in two flavors (see |lua-for|). The condition expression of a control structure may return any value. Both `false` and `nil` are considered false. All values different @@ -415,14 +415,14 @@ In the `repeat-until` loop, the inner block does not end at the `until` keyword, but only after the condition. So, the condition can refer to local variables declared inside the loop block. - *luaref-return* + *lua-return* The `return` statement is used to return values from a function or a chunk (which is just a function). Functions and chunks may return more than one value, so the syntax for the `return` statement is `stat ::=` `return` `[explist1]` - *luaref-break* + *lua-break* The `break` statement is used to terminate the execution of a `while`, `repeat`, or `for` loop, skipping to the next statement after the loop: @@ -437,7 +437,7 @@ middle of a block, then an explicit inner block can be used, as in the idioms the last statements in their (inner) blocks. ------------------------------------------------------------------------------ -2.4.5 For Statement *luaref-for* *luaref-langForStat* +2.4.5 For Statement *for* *lua-for* The `for` statement has two forms: one numeric and one generic. @@ -477,8 +477,8 @@ Note the following: after the `for` ends or is broken. If you need this value, assign it to another variable before breaking or exiting the loop. - *luaref-in* -The generic `for` statement works over functions, called iterators. On each + *for-in* +The generic `for` statement works over functions, called |iterator|s. On each iteration, the iterator function is called to produce a new value, stopping when this new value is `nil`. The generic `for` loop has the following syntax: > @@ -513,17 +513,17 @@ Note the following: them to other variables before breaking or exiting the loop. ------------------------------------------------------------------------------ -2.4.6 Function Calls as Statements *luaref-langFuncStat* +2.4.6 Function Calls as Statements *lua-funcstatement* To allow possible side-effects, function calls can be executed as statements: > stat ::= functioncall < In this case, all returned values are thrown away. Function calls are -explained in |luaref-langFuncCalls|. +explained in |lua-function|. ------------------------------------------------------------------------------ -2.4.7 Local Declarations *luaref-local* *luaref-langLocalDec* +2.4.7 Local Declarations *lua-local* Local variables may be declared anywhere inside a block. The declaration may include an initial assignment: @@ -532,18 +532,17 @@ include an initial assignment: namelist ::= Name { , Name } < If present, an initial assignment has the same semantics of a multiple -assignment (see |luaref-langAssign|). Otherwise, all variables are initialized +assignment (see |lua-assign|). Otherwise, all variables are initialized with `nil`. -A chunk is also a block (see |luaref-langChunks|), and so local variables can be +A chunk is also a block (see |lua-chunk|), and so local variables can be declared in a chunk outside any explicit block. The scope of such local variables extends until the end of the chunk. -The visibility rules for local variables are explained in -|luaref-langVisibRules|. +The visibility rules for local variables are explained in |lua-visibility|. ============================================================================== -2.5 Expressions *luaref-langExpressions* +2.5 Expressions *lua-expressions* The basic expressions in Lua are the following: > @@ -558,22 +557,21 @@ The basic expressions in Lua are the following: exp ::= unop exp prefixexp ::= var | functioncall | ( exp ) < -Numbers and literal strings are explained in |luaref-langLexConv|; variables are -explained in |luaref-langVariables|; function definitions are explained in -|luaref-langFuncDefs|; function calls are explained in |luaref-langFuncCalls|; -table constructors are explained in |luaref-langTableConst|. Vararg expressions, +Numbers and literal strings are explained in |lua-lexical|; variables are +explained in |lua-variables|; function definitions are explained in +|lua-function-define|; function calls are explained in |lua-function|; +table constructors are explained in |lua-tableconstructor|. Vararg expressions, denoted by three dots (`...`), can only be used inside vararg functions; -they are explained in |luaref-langFuncDefs|. +they are explained in |lua-function-define|. -Binary operators comprise arithmetic operators (see |luaref-langArithOp|), -relational operators (see |luaref-langRelOp|), logical operators (see -|luaref-langLogOp|), and the concatenation operator (see |luaref-langConcat|). -Unary operators comprise the unary minus (see |luaref-langArithOp|), the unary -`not` (see |luaref-langLogOp|), and the unary length operator (see -|luaref-langLength|). +Binary operators comprise arithmetic operators (see |lua-arithmetic|), +relational operators (see |lua-relational|), logical operators (see +|lua-logicalop|), and the concatenation operator (see |lua-concat|). +Unary operators comprise the unary minus (see |lua-arithmetic|), the unary +`not` (see |lua-logicalop|), and the unary length operator (see |lua-length|). Both function calls and vararg expressions may result in multiple values. If -the expression is used as a statement (see |luaref-langFuncStat|) +the expression is used as a statement (see |lua-funcstatement|) (only possible for function calls), then its return list is adjusted to zero elements, thus discarding all returned values. If the expression is used as the last (or the only) element of a list of expressions, then no adjustment is @@ -606,12 +604,12 @@ An expression enclosed in parentheses always results in only one value. Thus, return any values.) ------------------------------------------------------------------------------ -2.5.1 Arithmetic Operators *luaref-langArithOp* +2.5.1 Arithmetic Operators *lua-arithmetic* Lua supports the usual arithmetic operators: the binary `+` (addition), `-` (subtraction), `*` (multiplication), `/` (division), `%` (modulo) and `^` (exponentiation); and unary `-` (negation). If the operands are numbers, -or strings that can be converted to numbers (see |luaref-langCoercion|), then all +or strings that can be converted to numbers (see |lua-coercion|), then all operations have the usual meaning. Exponentiation works for any exponent. For instance, `x^(-0.5)` computes the inverse of the square root of `x`. Modulo is defined as @@ -622,7 +620,7 @@ That is, it is the remainder of a division that rounds the quotient towards minus infinity. ------------------------------------------------------------------------------ -2.5.2 Relational Operators *luaref-langRelOp* +2.5.2 Relational Operators *lua-relational* The relational operators in Lua are > @@ -639,9 +637,9 @@ create a new object (a table, userdata, or function), this new object is different from any previously existing object. You can change the way that Lua compares tables and userdata using the "eq" -metamethod (see |luaref-langMetatables|). +metamethod (see |lua-metatable|). -The conversion rules of coercion |luaref-langCoercion| do not apply to +The conversion rules of coercion |lua-coercion| do not apply to equality comparisons. Thus, `"0"==0` evaluates to `false`, and `t[0]` and `t["0"]` denote different entries in a table. @@ -650,19 +648,19 @@ The operator `~=` is exactly the negation of equality (`==`). The order operators work as follows. If both arguments are numbers, then they are compared as such. Otherwise, if both arguments are strings, then their values are compared according to the current locale. Otherwise, Lua tries to -call the "lt" or the "le" metamethod (see |luaref-langMetatables|). +call the "lt" or the "le" metamethod (see |lua-metatable|). ------------------------------------------------------------------------------ -2.5.3 Logical Operators *luaref-langLogOp* +2.5.3 Logical Operators *lua-logicalop* The logical operators in Lua are > and or not < -Like the control structures (see |luaref-langContStructs|), all logical operators +Like the control structures (see |lua-control|), all logical operators consider both `false` and `nil` as false and anything else as true. - *luaref-not* *luaref-and* *luaref-or* + *lua-not* *lua-and* *lua-or* The negation operator `not` always returns `false` or `true`. The conjunction operator `and` returns its first argument if this value is `false` or `nil`; otherwise, `and` returns its second argument. The disjunction @@ -683,15 +681,15 @@ evaluated only if necessary. Here are some examples: (In this manual, `-->` indicates the result of the preceding expression.) ------------------------------------------------------------------------------ -2.5.4 Concatenation *luaref-langConcat* +2.5.4 Concatenation *lua-concat* The string concatenation operator in Lua is denoted by two dots (`..`). If both operands are strings or numbers, then they are converted to strings -according to the rules mentioned in |luaref-langCoercion|. Otherwise, the -"concat" metamethod is called (see |luaref-langMetatables|). +according to the rules mentioned in |lua-coercion|. Otherwise, the +"concat" metamethod is called (see |lua-metatable|). ------------------------------------------------------------------------------ -2.5.5 The Length Operator *luaref-langLength* +2.5.5 The Length Operator *lua-#* *lua-length* The length operator is denoted by the unary operator `#`. The length of a string is its number of bytes (that is, the usual meaning of string length @@ -706,7 +704,7 @@ indices that directly precedes a `nil` value (that is, it may consider any such `nil` value as the end of the array). ------------------------------------------------------------------------------ -2.5.6 Precedence *luaref-langPrec* +2.5.6 Precedence *lua-precedence* Operator precedence in Lua follows the table below, from lower to higher priority: @@ -725,7 +723,7 @@ The concatenation (`..`) and exponentiation (`^`) operators are right associative. All other binary operators are left associative. ------------------------------------------------------------------------------ -2.5.7 Table Constructors *luaref-langTableConst* +2.5.7 Table Constructors *lua-tableconstructor* Table constructors are expressions that create tables. Every time a constructor is evaluated, a new table is created. Constructors can be used to @@ -761,14 +759,14 @@ is equivalent to < If the last field in the list has the form `exp` and the expression is a function call, then all values returned by the call enter the list -consecutively (see |luaref-langFuncCalls|). To avoid this, enclose the function -call in parentheses (see |luaref-langExpressions|). +consecutively (see |lua-function|). To avoid this, enclose the function +call in parentheses (see |lua-expressions|). The field list may have an optional trailing separator, as a convenience for machine-generated code. ------------------------------------------------------------------------------ -2.5.8 Function Calls *luaref-function* *luaref-langFuncCalls* +2.5.8 Function Calls *lua-function* A function call in Lua has the following syntax: > @@ -778,7 +776,7 @@ In a function call, first `prefixexp` and `args` are evaluated. If the value of `prefixexp` has type `function`, then this function is called with the given arguments. Otherwise, the `prefixexp` "call" metamethod is called, having as first parameter the value of `prefixexp`, followed by the original call -arguments (see |luaref-langMetatables|). +arguments (see |lua-metatable|). The form > @@ -810,7 +808,7 @@ Lua would see that as a single statement, `a = f(g).x(a)`. So, if you want two statements, you must add a semi-colon between them. If you actually want to call `f`, you must remove the line break before `(g)`. - *luaref-tailcall* + *lua-tailcall* A call of the form `return` `functioncall` is called a tail call. Lua implements proper tail calls (or proper tail recursion): in a tail call, the called function reuses the stack entry of the calling function. Therefore, @@ -829,7 +827,7 @@ of the following examples are tail calls: < ------------------------------------------------------------------------------ -2.5.9 Function Definitions *luaref-langFuncDefs* +2.5.9 Function Definitions *lua-function-define* The syntax for function definition is > @@ -873,7 +871,7 @@ not to (This only makes a difference when the body of the function contains references to `f`.) - *luaref-closure* + *lua-closure* A function definition is an executable expression, whose value has type `function`. When Lua pre-compiles a chunk, all its function bodies are pre-compiled too. Then, whenever Lua executes the function definition, the @@ -887,7 +885,7 @@ values: > parlist1 ::= namelist [ , ... ] | ... < - *luaref-vararg* + *lua-vararg* When a function is called, the list of arguments is adjusted to the length of the list of parameters, unless the function is a variadic or vararg function, which is indicated by three dots (`...`) at the end of its parameter list. A @@ -922,11 +920,11 @@ vararg expression: g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 g(5, r()) a=5, b=1, ... --> 2 3 < -Results are returned using the `return` statement (see |luaref-langContStructs|). +Results are returned using the `return` statement (see |lua-control|). If control reaches the end of a function without encountering a `return` statement, then the function returns with no results. - *luaref-colonsyntax* + *lua-colonsyntax* The colon syntax is used for defining methods, that is, functions that have an implicit extra parameter `self`. Thus, the statement @@ -937,7 +935,7 @@ is syntactic sugar for `t.a.b.c:f = function (self, (` `params` `)` `body` `end` ============================================================================== -2.6 Visibility Rules *luaref-langVisibRules* +2.6 Visibility Rules *lua-visibility* Lua is a lexically scoped language. The scope of variables begins at the first statement after their declaration and lasts until the end of the innermost @@ -959,7 +957,7 @@ block that includes the declaration. Consider the following example: Notice that, in a declaration like `local x = x`, the new `x` being declared is not in scope yet, and so the second `x` refers to the outside variable. - *luaref-upvalue* + *lua-upvalue* Because of the lexical scoping rules, local variables can be freely accessed by functions defined inside their scope. A local variable used by an inner function is called an upvalue, or external local variable, inside the inner @@ -980,7 +978,7 @@ function). Each of these closures uses a different `y` variable, while all of them share the same `x`. ============================================================================== -2.7 Error Handling *luaref-langError* +2.7 Error Handling *lua-errors* Because Lua is an embedded extension language, all Lua actions start from C code in the host program calling a function from the Lua library (see @@ -989,11 +987,11 @@ execution, control returns to C, which can take appropriate measures (such as print an error message). Lua code can explicitly generate an error by calling the `error` function (see -|luaref-error()|). If you need to catch errors in Lua, you can use -the `pcall` function (see |luaref-pcall()|). +|error()|). If you need to catch errors in Lua, you can use the `pcall` +function (see |pcall()|). ============================================================================== -2.8 Metatables *luaref-metatable* *luaref-langMetatables* +2.8 Metatables *metatable* *lua-metatable* Every value in Lua may have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original table and userdata under @@ -1008,10 +1006,10 @@ previous example, the event is "add" and the metamethod is the function that performs the addition. You can query the metatable of any value through the `getmetatable` function -(see |luaref-getmetatable()|). +(see |getmetatable()|). You can replace the metatable of tables through the `setmetatable` function (see -|luaref-setmetatable()|). You cannot change the metatable of other types from Lua +|setmetatable()|). You cannot change the metatable of other types from Lua (except using the debug library); you must use the C API for that. Tables and userdata have individual metatables (although multiple tables and @@ -1037,7 +1035,7 @@ by a Lua function describing how the interpreter executes that operation. The code shown here in Lua is only illustrative; the real behavior is hard coded in the interpreter and it is much more efficient than this simulation. All functions used in these descriptions (`rawget`, `tonumber`, etc.) are -described in |luaref-libBasic|. In particular, to retrieve the metamethod of a +described in |lua-lib-core|. In particular, to retrieve the metamethod of a given object, we use the expression > metatable(obj)[event] @@ -1307,7 +1305,7 @@ called when Lua calls a value. < ============================================================================== -2.9 Environments *luaref-environment* *luaref-langEnvironments* +2.9 Environments *lua-environments* Besides metatables, objects of types thread, function, and userdata have another table associated with them, called their environment. Like metatables, @@ -1319,16 +1317,15 @@ convenience feature for programmers to associate a table to a userdata. Environments associated with threads are called global environments. They are used as the default environment for their threads and non-nested functions -created by the thread (through `loadfile` |luaref-loadfile()|, `loadstring` -|luaref-loadstring()| or `load` |luaref-load()|) and can be directly accessed by C -code (see |luaref-apiPseudoIndices|). +created by the thread (through |loadfile()|, |loadstring()| or |load()|) and +can be directly accessed by C code (see |lua-pseudoindex|). Environments associated with C functions can be directly accessed by C code -(see |luaref-apiPseudoIndices|). They are used as the default environment for +(see |lua-pseudoindex|). They are used as the default environment for other C functions created by the function. Environments associated with Lua functions are used to resolve all accesses to -global variables within the function (see |luaref-langVariables|). They are +global variables within the function (see |lua-variables|). They are used as the default environment for other Lua functions created by the function. @@ -1339,7 +1336,7 @@ environment of other objects (userdata, C functions, other threads) you must use the C API. ============================================================================== -2.10 Garbage Collection *luaref-langGC* +2.10 Garbage Collection *lua-gc* Lua performs automatic memory management. This means that you do not have to worry neither about allocating memory for new objects nor about freeing it @@ -1367,16 +1364,16 @@ The default, 2, means that the collector runs at "twice" the speed of memory allocation. You can change these numbers by calling `lua_gc` (see |lua_gc()|) in C or -`collectgarbage` (see |luaref-collectgarbage()|) in Lua. Both get percentage -points as arguments (so an argument of 100 means a real value of 1). With -these functions you can also control the collector directly (e.g., stop and -restart it). +`collectgarbage` (see |collectgarbage()|) in Lua. Both get percentage points +as arguments (so an argument of 100 means a real value of 1). With these +functions you can also control the collector directly (e.g., stop and restart +it). ------------------------------------------------------------------------------ -2.10.1 Garbage-Collection Metamethods *luaref-langGCMeta* +2.10.1 Garbage-Collection Metamethods *lua-gc-meta* Using the C API, you can set garbage-collector metamethods for userdata (see -|luaref-langMetatables|). These metamethods are also called finalizers. +|lua-metatable|). These metamethods are also called finalizers. Finalizers allow you to coordinate Lua's garbage collection with external resource management (such as closing files, network or database connections, or freeing your own memory). @@ -1400,7 +1397,7 @@ cycle. That is, the first finalizer to be called is the one associated with the userdata created last in the program. ------------------------------------------------------------------------------ -2.10.2 - Weak Tables *luaref-weaktable* *luaref-langWeaktables* +2.10.2 - Weak Tables *lua-weaktable* A weak table is a table whose elements are weak references. A weak reference is ignored by the garbage collector. In other words, if the only references to @@ -1422,7 +1419,7 @@ field `__mode`. Otherwise, the weak behavior of the tables controlled by this metatable is undefined. ============================================================================== -2.11 Coroutines *luaref-coroutine* *luaref-langCoro* +2.11 Coroutines *lua-coroutine* Lua supports coroutines, also called collaborative multithreading. A coroutine in Lua represents an independent thread of execution. Unlike threads in @@ -1502,7 +1499,7 @@ When you run it, it produces the following output: < ============================================================================== -3 THE APPLICATION PROGRAM INTERFACE *luaref-API* +3 THE APPLICATION PROGRAM INTERFACE *lua-API* This section describes the C API for Lua, that is, the set of C functions available to the host program to communicate with Lua. All API functions and @@ -1519,7 +1516,7 @@ Lua with a proper definition for the macro `luai_apicheck`,in file `luaconf.h`. ============================================================================== -3.1 The Stack *luaref-stack* *luaref-apiStack* +3.1 The Stack *lua-stack* *lua-apiStack* Lua uses a virtual stack to pass values to and from C. Each element in this stack represents a Lua value (`nil`, number, string, etc.). @@ -1528,9 +1525,9 @@ Whenever Lua calls C, the called function gets a new stack, which is independent of previous stacks and of stacks of C functions that are still active. This stack initially contains any arguments to the C function and it is where the C function pushes its results to be returned to the caller (see -|lua_CFunction()|). +|lua_CFunction|). - *luaref-stackindex* + *lua-stackindex* For convenience, most query operations in the API do not follow a strict stack discipline. Instead, they can refer to any element in the stack by using an index: a positive index represents an absolute stack position (starting at 1); @@ -1543,7 +1540,7 @@ We say that an index is valid if it lies between 1 and the stack top (that is, if `1 <= abs(index) <= top`). ============================================================================== -3.2 Stack Size *luaref-apiStackSize* +3.2 Stack Size *lua-apiStackSize* When you interact with Lua API, you are responsible for ensuring consistency. In particular, you are responsible for controlling stack overflow. You can @@ -1565,13 +1562,13 @@ we define an acceptable index as follows: Note that 0 is never an acceptable index. ============================================================================== -3.3 Pseudo-Indices *luaref-pseudoindex* *luaref-apiPseudoIndices* +3.3 Pseudo-Indices *lua-pseudoindex* Unless otherwise noted, any function that accepts valid indices can also be called with pseudo-indices, which represent some Lua values that are accessible to the C code but which are not in the stack. Pseudo-indices are used to access the thread environment, the function environment, the registry, -and the upvalues of a C function (see |luaref-apiCClosures|). +and the upvalues of a C function (see |lua-cclosure|). The thread environment (where global variables live) is always at pseudo-index `LUA_GLOBALSINDEX`. The environment of the running C function is always at @@ -1585,7 +1582,7 @@ global variable, do < ============================================================================== -3.4 C Closures *luaref-cclosure* *luaref-apiCClosures* +3.4 C Closures *lua-cclosure* When a C function is created, it is possible to associate some values with it, thus creating a C closure; these values are called upvalues and are accessible @@ -1599,7 +1596,7 @@ where `n` is greater than the number of upvalues of the current function, produces an acceptable (but invalid) index. ============================================================================== -3.5 Registry *luaref-registry* *luaref-apiRegistry* +3.5 Registry *lua-registry* Lua provides a registry, a pre-defined table that can be used by any C code to store whatever Lua value it needs to store. This table is always located at @@ -1614,7 +1611,7 @@ implemented by the auxiliary library, and therefore should not be used for other purposes. ============================================================================== -3.6 Error Handling in C *luaref-apiError* +3.6 Error Handling in C *lua-apiError* Internally, Lua uses the C `longjmp` facility to handle errors. (You can also choose to use exceptions if you use C++; see file `luaconf.h`.) When Lua faces @@ -1634,11 +1631,11 @@ Inside a C function you can raise an error by calling `lua_error` (see |lua_error()|). ============================================================================== -3.7 Functions and Types *luaref-apiFunctions* +3.7 Functions and Types *lua-apiFunctions* Here we list all functions and types from the C API in alphabetical order. -lua_Alloc *lua_Alloc()* +lua_Alloc *lua_Alloc* >c typedef void * (*lua_Alloc) (void *ud, void *ptr, @@ -1736,7 +1733,7 @@ lua_call *lua_call()* to its original configuration. This is considered good programming practice. -lua_CFunction *luaref-cfunction* *lua_CFunction()* +lua_CFunction *lua-cfunction* *lua_CFunction* >c typedef int (*lua_CFunction) (lua_State *L); < @@ -1755,7 +1752,7 @@ lua_CFunction *luaref-cfunction* *lua_CFunction()* be properly discarded by Lua. Like a Lua function, a C function called by Lua can also return many results. - *luaref-cfunctionexample* + *lua-cfunctionexample* As an example, the following function receives a variable number of numerical arguments and returns their average and sum: >c @@ -1805,7 +1802,7 @@ lua_concat *lua_concat()* leaves the result at the top. If `n` is 1, the result is the single string on the stack (that is, the function does nothing); if `n` is 0, the result is the empty string. Concatenation is done following the - usual semantics of Lua (see |luaref-langConcat|). + usual semantics of Lua (see |lua-concat|). lua_cpcall *lua_cpcall()* >c @@ -1836,7 +1833,7 @@ lua_dump *lua_dump()* of the stack and produces a binary chunk that, if loaded again, results in a function equivalent to the one dumped. As it produces parts of the chunk, `lua_dump` calls function `writer` (see - |lua_Writer()|) with the given `data` to write them. + |lua_Writer|) with the given `data` to write them. The value returned is the error code returned by the last call to the writer; 0 means no errors. @@ -1884,12 +1881,12 @@ lua_gc *lua_gc()* function returns 1 if the step finished a garbage-collection cycle. - `LUA_GCSETPAUSE` sets `data` /100 as the new value for the - `pause` of the collector (see |luaref-langGC|). + `pause` of the collector (see |lua-gc|). The function returns the previous value of the pause. - `LUA_GCSETSTEPMUL`sets `data` /100 as the new value for the `step` `multiplier` of the collector (see - |luaref-langGC|). The function returns the + |lua-gc|). The function returns the previous value of the step multiplier. lua_getallocf *lua_getallocf()* @@ -1913,7 +1910,7 @@ lua_getfield *lua_getfield()* < Pushes onto the stack the value `t[k]`, where `t` is the value at the given valid index `index`. As in Lua, this function may trigger a - metamethod for the "index" event (see |luaref-langMetatables|). + metamethod for the "index" event (see |lua-metatable|). lua_getglobal *lua_getglobal()* >c @@ -1944,7 +1941,7 @@ lua_gettable *lua_gettable()* This function pops the key from the stack (putting the resulting value in its place). As in Lua, this function may trigger a metamethod for - the "index" event (see |luaref-langMetatables|). + the "index" event (see |lua-metatable|). lua_gettop *lua_gettop()* >c @@ -1963,7 +1960,7 @@ lua_insert *lua_insert()* elements above this index to open space. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position. -lua_Integer *lua_Integer()* +lua_Integer *lua_Integer* >c typedef ptrdiff_t lua_Integer; < @@ -2072,11 +2069,11 @@ lua_load *lua_load()* and loads it accordingly (see program `luac`). The `lua_load` function uses a user-supplied `reader` function to read - the chunk (see |lua_Reader()|). The `data` argument is an opaque + the chunk (see |lua_Reader|). The `data` argument is an opaque value passed to the reader function. The `chunkname` argument gives a name to the chunk, which is used for - error messages and in debug information (see |luaref-apiDebug|). + error messages and in debug information (see |lua-apiDebug|). lua_newstate *lua_newstate()* >c @@ -2101,7 +2098,7 @@ lua_newthread *lua_newthread()* lua_State *lua_newthread (lua_State *L); < Creates a new thread, pushes it on the stack, and returns a pointer to - a `lua_State` (see |lua_State()|) that represents this new + a `lua_State` (see |lua_State|) that represents this new thread. The new state returned by this function shares with the original state all global objects (such as tables), but has an independent execution stack. @@ -2116,7 +2113,7 @@ lua_newuserdata *lua_newuserdata()* This function allocates a new block of memory with the given size, pushes onto the stack a new full userdata with the block address, and returns this address. - *luaref-userdata* + *userdata* Userdata represents C values in Lua. A full userdata represents a block of memory. It is an object (like a table): you must create it, it can have its own metatable, and you can detect when it is being @@ -2136,7 +2133,7 @@ lua_next *lua_next()* no more elements in the table, then `lua_next` returns 0 (and pushes nothing). - *luaref-tabletraversal* + *lua-tabletraversal* A typical traversal looks like this: >c /* table is in the stack at index 't' */ @@ -2155,7 +2152,7 @@ lua_next *lua_next()* key is actually a string. Recall that `lua_tolstring` `changes` the value at the given index; this confuses the next call to `lua_next`. -lua_Number *lua_Number()* +lua_Number *lua_Number* >c typedef double lua_Number; < @@ -2228,7 +2225,7 @@ lua_pushcclosure *lua_pushcclosure()* Pushes a new C closure onto the stack. When a C function is created, it is possible to associate some values - with it, thus creating a C closure (see |luaref-apiCClosures|); these + with it, thus creating a C closure (see |lua-cclosure|); these values are then accessible to the function whenever it is called. To associate values with a C function, first these values should be pushed onto the stack (when there are multiple values, the first value @@ -2247,7 +2244,7 @@ lua_pushcfunction *lua_pushcfunction()* Any function to be registered in Lua must follow the correct protocol to receive its parameters and return its results (see - |lua_CFunction()|). + |lua_CFunction|). `lua_pushcfunction` is defined as a macro: >c @@ -2284,7 +2281,7 @@ lua_pushlightuserdata *lua_pushlightuserdata()* void lua_pushlightuserdata (lua_State *L, void *p); < Pushes a light userdata onto the stack. - *luaref-lightuserdata* + *lua-lightuserdata* Userdata represents C values in Lua. A light userdata represents a pointer. It is a value (like a number): you do not create it, it has no individual metatable, and it is not collected (as it was never @@ -2386,7 +2383,7 @@ lua_rawseti *lua_rawseti()* This function pops the value from the stack. The assignment is raw; that is, it does not invoke metamethods. -lua_Reader *lua_Reader()* +lua_Reader *lua_Reader* >c typedef const char * (*lua_Reader) (lua_State *L, void *data, @@ -2476,7 +2473,7 @@ lua_setfield *lua_setfield()* This function pops the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event (see - |luaref-langMetatables|). + |lua-metatable|). lua_setglobal *lua_setglobal()* >c @@ -2505,7 +2502,7 @@ lua_settable *lua_settable()* This function pops both the key and the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event - (see |luaref-langMetatables|). + (see |lua-metatable|). lua_settop *lua_settop()* >c @@ -2516,7 +2513,7 @@ lua_settop *lua_settop()* elements are filled with `nil`. If `index` is 0, then all stack elements are removed. -lua_State *lua_State()* +lua_State *lua_State* >c typedef struct lua_State lua_State; < @@ -2561,9 +2558,9 @@ lua_tointeger *lua_tointeger()* lua_Integer lua_tointeger (lua_State *L, int idx); < Converts the Lua value at the given acceptable index to the signed - integral type `lua_Integer` (see |lua_Integer()|). The Lua value + integral type `lua_Integer` (see |lua_Integer|). The Lua value must be a number or a string convertible to a number (see - |luaref-langCoercion|); otherwise, `lua_tointeger` returns 0. + |lua-coercion|); otherwise, `lua_tointeger` returns 0. If the number is not an integer, it is truncated in some non-specified way. @@ -2592,8 +2589,8 @@ lua_tonumber *lua_tonumber()* lua_Number lua_tonumber (lua_State *L, int index); < Converts the Lua value at the given acceptable index to the C type - `lua_Number` (see |lua_Number()|). The Lua value must be a number - or a string convertible to a number (see |luaref-langCoercion|); + `lua_Number` (see |lua_Number|). The Lua value must be a number + or a string convertible to a number (see |lua-coercion|); otherwise, `lua_tonumber` returns 0. lua_topointer *lua_topointer()* @@ -2620,7 +2617,7 @@ lua_tothread *lua_tothread()* lua_State *lua_tothread (lua_State *L, int index); < Converts the value at the given acceptable index to a Lua thread - (represented as `lua_State*` |lua_State()|). This value must be a + (represented as `lua_State*` |lua_State|). This value must be a thread; otherwise, the function returns `NULL`. lua_touserdata *lua_touserdata()* @@ -2649,7 +2646,7 @@ lua_typename *lua_typename()* Returns the name of the type encoded by the value `tp`, which must be one the values returned by `lua_type`. -lua_Writer *lua_Writer()* +lua_Writer *lua_Writer* >c typedef int (*lua_Writer) (lua_State *L, const void* p, @@ -2690,7 +2687,7 @@ lua_yield *lua_yield()* parameter `nresults` is the number of values from the stack that are passed as results to `lua_resume`. - *luaref-stackexample* + *lua-stackexample* As an example of stack manipulation, if the stack starts as `10 20 30 40 50*` (from bottom to top; the `*` marks the top), then > @@ -2706,14 +2703,14 @@ lua_yield *lua_yield()* < ============================================================================== -3.8 The Debug Interface *luaref-apiDebug* +3.8 The Debug Interface *lua-apiDebug* Lua has no built-in debugging facilities. Instead, it offers a special interface by means of functions and hooks. This interface allows the construction of different kinds of debuggers, profilers, and other tools that need "inside information" from the interpreter. -lua_Debug *lua_Debug()* +lua_Debug *lua_Debug* >c typedef struct lua_Debug { @@ -2737,7 +2734,7 @@ function. `lua_getstack` (see |lua_getstack()|) fills only the private part of this structure, for later use. To fill the other fields of `lua_Debug` with useful information, call `lua_getinfo` (see |lua_getinfo()|). -The fields of `lua_Debug` have the following meaning: +The fields of `lua_Debug` have the following meaning: - `source` If the function was defined in a string, then `source` is that string. If the function was defined in a file, then @@ -2794,7 +2791,7 @@ lua_getinfo *lua_getinfo()* To get information about a function invocation, the parameter `ar` must be a valid activation record that was filled by a previous call to `lua_getstack` (see |lua_getstack()|) or given as argument to - a hook (see |lua_Hook()|). + a hook (see |lua_Hook|). To get information about a function you push it onto the stack and start the `what` string with the character `>`. (In that case, @@ -2832,7 +2829,7 @@ lua_getlocal *lua_getlocal()* Gets information about a local variable of a given activation record. The parameter `ar` must be a valid activation record that was filled by a previous call to `lua_getstack` (see |lua_getstack()|) or - given as argument to a hook (see |lua_Hook()|). The index `n` + given as argument to a hook (see |lua_Hook|). The index `n` selects which local variable to inspect (1 is the first parameter or active local variable, and so on, until the last active local variable). `lua_getlocal` pushes the variable's value onto the stack @@ -2851,7 +2848,7 @@ lua_getstack *lua_getstack()* < Gets information about the interpreter runtime stack. - This function fills parts of a `lua_Debug` (see |lua_Debug()|) + This function fills parts of a `lua_Debug` (see |lua_Debug|) structure with an identification of the `activation record` of the function executing at a given level. Level 0 is the current running function, whereas level `n+1` is the function that has called level @@ -2874,7 +2871,7 @@ lua_getupvalue *lua_getupvalue()* number of upvalues. For C functions, this function uses the empty string `""` as a name for all upvalues. -lua_Hook *lua_Hook()* +lua_Hook *lua_Hook* >c typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); < @@ -2950,7 +2947,7 @@ lua_setupvalue *lua_setupvalue()* Returns `NULL` (and pops nothing) when the index is greater than the number of upvalues. - *luaref-debugexample* + *lua-debugexample* As an example, the following function lists the names of all local variables and upvalues for a function at a given level of the stack: >c @@ -2976,7 +2973,7 @@ lua_setupvalue *lua_setupvalue()* < ============================================================================== -4 THE AUXILIARY LIBRARY *luaref-aux* +4 THE AUXILIARY LIBRARY *lua-aux* The auxiliary library provides several convenient functions to interface C with Lua. While the basic API provides the primitive functions for all @@ -2996,7 +2993,7 @@ message is formatted for arguments (e.g., "bad argument #1"), you should not use these functions for other stack values. ============================================================================== -4.1 Functions and Types *luaref-auxFunctions* +4.1 Functions and Types *lua-auxFunctions* Here we list all functions and types from the auxiliary library in alphabetical order. @@ -3005,20 +3002,20 @@ luaL_addchar *luaL_addchar()* >c void luaL_addchar (luaL_Buffer *B, char c); < - Adds the character `c` to the buffer `B` (see |luaL_Buffer()|). + Adds the character `c` to the buffer `B` (see |luaL_Buffer|). luaL_addlstring *luaL_addlstring()* >c void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l); < Adds the string pointed to by `s` with length `l` to the buffer `B` - (see |luaL_Buffer()|). The string may contain embedded zeros. + (see |luaL_Buffer|). The string may contain embedded zeros. luaL_addsize *luaL_addsize()* >c void luaL_addsize (luaL_Buffer *B, size_t n); < - Adds to the buffer `B` (see |luaL_Buffer()|) a string of length + Adds to the buffer `B` (see |luaL_Buffer|) a string of length `n` previously copied to the buffer area (see |luaL_prepbuffer()|). @@ -3027,14 +3024,14 @@ luaL_addstring *luaL_addstring()* void luaL_addstring (luaL_Buffer *B, const char *s); < Adds the zero-terminated string pointed to by `s` to the buffer `B` - (see |luaL_Buffer()|). The string may not contain embedded zeros. + (see |luaL_Buffer|). The string may not contain embedded zeros. luaL_addvalue *luaL_addvalue()* >c void luaL_addvalue (luaL_Buffer *B); < Adds the value at the top of the stack to the buffer `B` (see - |luaL_Buffer()|). Pops the value. + |luaL_Buffer|). Pops the value. This is the only function on string buffers that can (and must) be called with an extra element on the stack, which is the value to be @@ -3065,7 +3062,7 @@ luaL_argerror *luaL_argerror()* This function never returns, but it is an idiom to use it in C functions as `return luaL_argerror(` `args` `)`. -luaL_Buffer *luaL_Buffer()* +luaL_Buffer *luaL_Buffer* >c typedef struct luaL_Buffer luaL_Buffer; < @@ -3099,7 +3096,7 @@ luaL_buffinit *luaL_buffinit()* void luaL_buffinit (lua_State *L, luaL_Buffer *B); < Initializes a buffer `B`. This function does not allocate any space; - the buffer must be declared as a variable (see |luaL_Buffer()|). + the buffer must be declared as a variable (see |luaL_Buffer|). luaL_callmeta *luaL_callmeta()* >c @@ -3133,7 +3130,7 @@ luaL_checkinteger *luaL_checkinteger()* lua_Integer luaL_checkinteger (lua_State *L, int narg); < Checks whether the function argument `narg` is a number and returns - this number cast to a `lua_Integer` (see |lua_Integer()|). + this number cast to a `lua_Integer` (see |lua_Integer|). luaL_checklong *luaL_checklong()* >c @@ -3154,7 +3151,7 @@ luaL_checknumber *luaL_checknumber()* lua_Number luaL_checknumber (lua_State *L, int narg); < Checks whether the function argument `narg` is a number and returns - this number (see |lua_Number()|). + this number (see |lua_Number|). luaL_checkoption *luaL_checkoption()* >c @@ -3334,7 +3331,7 @@ luaL_openlibs *luaL_openlibs()* void luaL_openlibs (lua_State *L); < Opens all standard Lua libraries into the given state. See also - |luaref-openlibs| for details on how to open individual libraries. + |lua-openlibs| for details on how to open individual libraries. luaL_optint *luaL_optint()* >c @@ -3351,7 +3348,7 @@ luaL_optinteger *luaL_optinteger()* lua_Integer d); < If the function argument `narg` is a number, returns this number cast - to a `lua_Integer` (see |lua_Integer()|). If this argument is + to a `lua_Integer` (see |lua_Integer|). If this argument is absent or is `nil`, returns `d`. Otherwise, raises an error. luaL_optlong *luaL_optlong()* @@ -3398,7 +3395,7 @@ luaL_prepbuffer *luaL_prepbuffer()* char *luaL_prepbuffer (luaL_Buffer *B); < Returns an address to a space of size `LUAL_BUFFERSIZE` where you can - copy a string to be added to buffer `B` (see |luaL_Buffer()|). + copy a string to be added to buffer `B` (see |luaL_Buffer|). After copying the string into this space you must call `luaL_addsize` (see |luaL_addsize()|) with the size of the string to actually add it to the buffer. @@ -3428,7 +3425,7 @@ luaL_ref *luaL_ref()* constant `LUA_REFNIL`. The constant `LUA_NOREF` is guaranteed to be different from any reference returned by `luaL_ref`. -luaL_Reg *luaL_Reg()* +luaL_Reg *luaL_Reg* >c typedef struct luaL_Reg { const char *name; @@ -3449,7 +3446,7 @@ luaL_register *luaL_register()* Opens a library. When called with `libname` equal to `NULL`, it simply registers all - functions in the list `l` (see |luaL_Reg()|) into the table on + functions in the list `l` (see |luaL_Reg|) into the table on the top of the stack. When called with a non-null `libname`, `luaL_register` creates a new @@ -3507,7 +3504,7 @@ luaL_where *luaL_where()* This function is used to build a prefix for error messages. ============================================================================== -5 STANDARD LIBRARIES *luaref-Lib* +5 STANDARD LIBRARIES *lua-lib* The standard libraries provide useful functions that are implemented directly through the C API. Some of these functions provide essential services to the @@ -3531,7 +3528,7 @@ separate C modules. Currently, Lua has the following standard libraries: Except for the basic and package libraries, each library provides all its functions as fields of a global table or as methods of its objects. - *luaref-openlibs* + *lua-openlibs* To have access to these libraries, the C host program should call the `luaL_openlibs` function, which opens all standard libraries (see |luaL_openlibs()|). Alternatively, the host program can open the libraries @@ -3544,18 +3541,18 @@ declared in `lualib.h` and should not be called directly: you must call them like any other Lua C function, e.g., by using `lua_call` (see |lua_call()|). ============================================================================== -5.1 Basic Functions *luaref-libBasic* +5.1 Basic Functions *lua-lib-core* The basic library provides some core functions to Lua. If you do not include this library in your application, you should check carefully whether you need to provide implementations for some of its facilities. -assert({v} [, {message}]) *luaref-assert()* +assert({v} [, {message}]) *assert()* Issues an error when the value of its argument `v` is false (i.e., `nil` or `false`); otherwise, returns all its arguments. `message` is an error message; when absent, it defaults to "assertion failed!" -collectgarbage({opt} [, {arg}]) *luaref-collectgarbage()* +collectgarbage({opt} [, {arg}]) *collectgarbage()* This function is a generic interface to the garbage collector. It performs different functions according to its first argument, {opt}: @@ -3569,18 +3566,18 @@ collectgarbage({opt} [, {arg}]) *luaref-collectgarbage()* you must experimentally tune the value of {arg}. Returns `true` if the step finished a collection cycle. `"setpause"` sets {arg} /100 as the new value for the `pause` of - the collector (see |luaref-langGC|). + the collector (see |lua-gc|). `"setstepmul"` sets {arg} /100 as the new value for the `step - multiplier` of the collector (see |luaref-langGC|). + multiplier` of the collector (see |lua-gc|). -dofile({filename}) *luaref-dofile()* +dofile({filename}) *dofile()* Opens the named file and executes its contents as a Lua chunk. When called without arguments, `dofile` executes the contents of the standard input (`stdin`). Returns all values returned by the chunk. In case of errors, `dofile` propagates the error to its caller (that is, `dofile` does not run in protected mode). -error({message} [, {level}]) *luaref-error()* +error({message} [, {level}]) *error()* Terminates the last protected function called and returns `message` as the error message. Function {error} never returns. @@ -3592,27 +3589,27 @@ error({message} [, {level}]) *luaref-error()* a level 0 avoids the addition of error position information to the message. -_G *luaref-_G()* +_G *_G* A global variable (not a function) that holds the global environment (that is, `_G._G = _G`). Lua itself does not use this variable; changing its value does not affect any environment, nor vice-versa. (Use `setfenv` to change environments.) -getfenv({f}) *luaref-getfenv()* +getfenv({f}) *getfenv()* Returns the current environment in use by the function. {f} can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function calling `getfenv`. If the given function is not a Lua function, or if {f} is 0, `getfenv` returns the global environment. The default for {f} is 1. -getmetatable({object}) *luaref-getmetatable()* +getmetatable({object}) *getmetatable()* If {object} does not have a metatable, returns `nil`. Otherwise, if the object's metatable has a `"__metatable"` field, returns the associated value. Otherwise, returns the metatable of the given object. -ipairs({t}) *luaref-ipairs()* - Returns three values: an iterator function, the table {t}, and 0, so +ipairs({t}) *ipairs()* + Returns three values: an |iterator| function, the table {t}, and 0, so that the construction `for i,v in ipairs(t) do` `body` `end` @@ -3620,7 +3617,7 @@ ipairs({t}) *luaref-ipairs()* will iterate over the pairs (`1,t[1]`), (`2,t[2]`), ..., up to the first integer key absent from the table. -load({func} [, {chunkname}]) *luaref-load()* +load({func} [, {chunkname}]) *load()* Loads a chunk using function {func} to get its pieces. Each call to {func} must return a string that concatenates with previous results. A return of `nil` (or no value) signals the end of the chunk. @@ -3632,12 +3629,12 @@ load({func} [, {chunkname}]) *luaref-load()* {chunkname} is used as the chunk name for error messages and debug information. -loadfile([{filename}]) *luaref-loadfile()* - Similar to `load` (see |luaref-load()|), but gets the chunk from file +loadfile([{filename}]) *loadfile()* + Similar to `load` (see |load()|), but gets the chunk from file {filename} or from the standard input, if no file name is given. -loadstring({string} [, {chunkname}]) *luaref-loadstring()* - Similar to `load` (see |luaref-load()|), but gets the chunk from the +loadstring({string} [, {chunkname}]) *loadstring()* + Similar to `load` (see |load()|), but gets the chunk from the given {string}. To load and run a given string, use the idiom @@ -3645,7 +3642,7 @@ loadstring({string} [, {chunkname}]) *luaref-loadstring()* assert(loadstring(s))() < -next({table} [, {index}]) *luaref-next()* +next({table} [, {index}]) *next()* Allows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. `next` returns the next index of the table and its associated value. When @@ -3655,23 +3652,23 @@ next({table} [, {index}]) *luaref-next()* argument is absent, then it is interpreted as `nil`. In particular, you can use `next(t)` to check whether a table is empty. - The order in which the indices are enumerated is not specified, `even - for` `numeric indices`. (To traverse a table in numeric order, use a - numerical `for` or the `ipairs` |luaref-ipairs()| function.) + The order in which the indices are enumerated is not specified, even + for numeric indices. (To traverse a table in numeric order, use a + numerical `for` or the |ipairs()| function.) The behavior of `next` is `undefined` if, during the traversal, you assign any value to a non-existent field in the table. You may however modify existing fields. In particular, you may clear existing fields. -pairs({t}) *luaref-pairs()* - Returns three values: the `next` |luaref-next()| function, the table - {t}, and `nil`, so that the construction +pairs({t}) *pairs()* + Returns three values: the |next()| function, the table {t}, and `nil`, + so that the construction `for k,v in pairs(t) do` `body` `end` will iterate over all key-value pairs of table {t}. -pcall({f}, {arg1}, {...}) *luaref-pcall()* +pcall({f}, {arg1}, {...}) *pcall()* Calls function {f} with the given arguments in `protected mode`. This means that any error inside {f} is not propagated; instead, `pcall` catches the error and returns a status code. Its first result is the @@ -3680,34 +3677,34 @@ pcall({f}, {arg1}, {...}) *luaref-pcall()* after this first result. In case of any error, `pcall` returns `false` plus the error message. -print({...}) *luaref-print()* +print({...}) *print()* Receives any number of arguments, and prints their values to `stdout`, - using the `tostring` |luaref-tostring()| function to convert them to + using the `tostring` |tostring()| function to convert them to strings. `print` is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use `string.format` (see |string.format()|). -rawequal({v1}, {v2}) *luaref-rawequal()* +rawequal({v1}, {v2}) *rawequal()* Checks whether {v1} is equal to {v2}, without invoking any metamethod. Returns a boolean. -rawget({table}, {index}) *luaref-rawget()* +rawget({table}, {index}) *rawget()* Gets the real value of `table[index]`, without invoking any metamethod. {table} must be a table; {index} may be any value. -rawset({table}, {index}, {value}) *luaref-rawset()* +rawset({table}, {index}, {value}) *rawset()* Sets the real value of `table[index]` to {value}, without invoking any metamethod. {table} must be a table, {index} any value different from `nil`, and {value} any Lua value. This function returns {table}. -select({index}, {...}) *luaref-select()* +select({index}, {...}) *select()* If {index} is a number, returns all arguments after argument number {index}. Otherwise, {index} must be the string `"#"`, and `select` returns the total number of extra arguments it received. -setfenv({f}, {table}) *luaref-setfenv()* +setfenv({f}, {table}) *setfenv()* Sets the environment to be used by the given function. {f} can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function calling `setfenv`. `setfenv` returns @@ -3716,7 +3713,7 @@ setfenv({f}, {table}) *luaref-setfenv()* As a special case, when {f} is 0 `setfenv` changes the environment of the running thread. In this case, `setfenv` returns no values. -setmetatable({table}, {metatable}) *luaref-setmetatable()* +setmetatable({table}, {metatable}) *setmetatable()* Sets the metatable for the given table. (You cannot change the metatable of other types from Lua, only from C.) If {metatable} is `nil`, removes the metatable of the given table. If the original @@ -3724,7 +3721,7 @@ setmetatable({table}, {metatable}) *luaref-setmetatable()* This function returns {table}. -tonumber({e} [, {base}]) *luaref-tonumber()* +tonumber({e} [, {base}]) *tonumber()* Tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then `tonumber` returns this number; otherwise, it returns `nil`. @@ -3734,26 +3731,26 @@ tonumber({e} [, {base}]) *luaref-tonumber()* 10, the letter `A` (in either upper or lower case) represents 10, `B` represents 11, and so forth, with `Z'` representing 35. In base 10 (the default), the number may have a decimal part, as well as an - optional exponent part (see |luaref-langLexConv|). In other bases, + optional exponent part (see |lua-lexical|). In other bases, only unsigned integers are accepted. -tostring({e}) *luaref-tostring()* +tostring({e}) *tostring()* Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, use `string.format` (see |string.format()|). - *__tostring* + *__tostring* If the metatable of {e} has a `"__tostring"` field, `tostring` calls the corresponding value with {e} as argument, and uses the result of the call as its result. -type({v}) *luaref-type()* +type({v}) *lua-type()* Returns the type of its only argument, coded as a string. The possible results of this function are `"nil"` (a string, not the value `nil`), `"number"`, `"string"`, `"boolean`, `"table"`, `"function"`, `"thread"`, and `"userdata"`. -unpack({list} [, {i} [, {j}]]) *luaref-unpack()* +unpack({list} [, {i} [, {j}]]) *unpack()* Returns the elements from the given table. This function is equivalent to >lua @@ -3761,16 +3758,16 @@ unpack({list} [, {i} [, {j}]]) *luaref-unpack()* < except that the above code can be written only for a fixed number of elements. By default, {i} is 1 and {j} is the length of the list, as - defined by the length operator(see |luaref-langLength|). + defined by the length operator (see |lua-length|). -_VERSION *luaref-_VERSION()* +_VERSION *_VERSION* A global variable (not a function) that holds a string containing the current interpreter version. The current contents of this string is `"Lua 5.1"` . -xpcall({f}, {err}) *luaref-xpcall()* - This function is similar to `pcall` (see |luaref-pcall()|), except that - you can set a new error handler. +xpcall({f}, {err}) *xpcall()* + This function is similar to `pcall` (see |pcall()|), except that you + can set a new error handler. `xpcall` calls function {f} in protected mode, using {err} as the error handler. Any error inside {f} is not propagated; instead, @@ -3782,10 +3779,10 @@ xpcall({f}, {err}) *luaref-xpcall()* `false` plus the result from {err}. ============================================================================== -5.2 Coroutine Manipulation *luaref-libCoro* +5.2 Coroutine Manipulation *lua-lib-coroutine* The operations related to coroutines comprise a sub-library of the basic -library and come inside the table `coroutine`. See |luaref-langCoro| for a +library and come inside the table `coroutine`. See |lua-coroutine| for a general description of coroutines. coroutine.create({f}) *coroutine.create()* @@ -3826,18 +3823,18 @@ coroutine.wrap({f}) *coroutine.wrap()* coroutine.yield({...}) *coroutine.yield()* Suspends the execution of the calling coroutine. The coroutine cannot - be running a C function, a metamethod, or an iterator. Any arguments + be running a C function, a metamethod, or an |iterator|. Any arguments to `yield` are passed as extra results to `resume`. ============================================================================== -5.3 - Modules *luaref-libModule* +5.3 Modules *lua-modules* The package library provides basic facilities for loading and building modules in Lua. It exports two of its functions directly in the global environment: -`require` and `module` (see |luaref-require()| and |luaref-module()|). Everything else is +`require` and `module` (see |require()| and |module()|). Everything else is exported in a table `package`. -module({name} [, {...}]) *luaref-module()* +module({name} [, {...}]) *module()* Creates a module. If there is a table in `package.loaded[name]`, this table is the module. Otherwise, if there is a global table `t` with the given name, this table is the module. Otherwise creates a new @@ -3847,8 +3844,7 @@ module({name} [, {...}]) *luaref-module()* `t._PACKAGE` with the package name (the full module name minus last component; see below). Finally, `module` sets `t` as the new environment of the current function and the new value of - `package.loaded[name]`, so that `require` (see |luaref-require()|) - returns `t`. + `package.loaded[name]`, so that |require()| returns `t`. If {name} is a compound name (that is, one with components separated by dots), `module` creates (or reuses, if they already exist) tables @@ -3858,7 +3854,7 @@ module({name} [, {...}]) *luaref-module()* This function may receive optional `options` after the module name, where each option is a function to be applied over the module. -require({modname}) *luaref-require()* +require({modname}) *require()* Loads the given module. The function starts by looking into the `package.loaded` table to determine whether {modname} is already loaded. If it is, then `require` returns the value stored at @@ -3901,7 +3897,7 @@ require({modname}) *luaref-require()* If there is any error loading or running the module, or if it cannot find any loader for the module, then `require` signals an error. -package.cpath *package.cpath* +package.cpath *package.cpath* The path used by `require` to search for a C loader. Lua initializes the C path `package.cpath` in the same way it @@ -3914,11 +3910,11 @@ package.loaded *package.loaded()* When you require a module `modname` and `package.loaded[modname]` is not false, `require` simply returns the value stored there. -package.loadlib({libname}, {funcname}) *package.loadlib()* +package.loadlib({libname}, {funcname}) *package.loadlib()* Dynamically links the host program with the C library {libname}. Inside this library, looks for a function {funcname} and returns this function as a C function. (So, {funcname} must follow the protocol - (see |lua_CFunction()|)). + (see |lua_CFunction|)). This is a low-level function. It completely bypasses the package and module system. Unlike `require`, it does not perform any path @@ -3931,7 +3927,7 @@ package.loadlib({libname}, {funcname}) *package.loadlib()* available on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the `dlfcn` standard). -package.path *package.path* +package.path *package.path* The path used by `require` to search for a Lua loader. At start-up, Lua initializes this variable with the value of the @@ -3952,7 +3948,7 @@ package.path *package.path* order. package.preload *package.preload()* - A table to store loaders for specific modules (see |luaref-require()|). + A table to store loaders for specific modules (see |require()|). package.seeall({module}) *package.seeall()* Sets a metatable for {module} with its `__index` field referring to @@ -3960,7 +3956,7 @@ package.seeall({module}) *package.seeall()* global environment. To be used as an option to function {module}. ============================================================================== -5.4 - String Manipulation *luaref-libString* +5.4 String Manipulation *lua-lib-string* This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a @@ -3992,7 +3988,7 @@ string.char({...}) *string.char()* string.dump({function}) *string.dump()* Returns a string containing a binary representation of the given - function, so that a later |luaref-loadstring()| on this string returns a + function, so that a later |loadstring()| on this string returns a copy of the function. {function} must be a Lua function without upvalues. @@ -4036,7 +4032,7 @@ string.format({formatstring}, {...}) *string.format()* This function does not accept string values containing embedded zeros. string.gmatch({s}, {pattern}) *string.gmatch()* - Returns an iterator function that, each time it is called, returns the + Returns an |iterator| function that, each time it is called, returns the next captures from {pattern} over string {s}. If {pattern} specifies no captures, then the whole match is produced @@ -4060,7 +4056,7 @@ string.gmatch({s}, {pattern}) *string.gmatch()* end < -string.gsub({s}, {pattern}, {repl} [, {n}]) *string.gsub()* +string.gsub({s}, {pattern}, {repl} [, {n}]) *string.gsub()* Returns a copy of {s} in which all occurrences of the {pattern} have been replaced by a replacement string specified by {repl}, which may be a string, a table, or a function. `gsub` also returns, as its @@ -4101,16 +4097,16 @@ string.gsub({s}, {pattern}, {repl} [, {n}]) *string.gsub()* x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from" - x = string.gsub("home = `HOME, user = ` USER", "%$(%w+)", os.getenv) + x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) --> x="home = /home/roberto, user = roberto" - x = string.gsub("4+5 = `return 4+5` ", "% `(.-)%` ", function (s) + x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) return loadstring(s)() end) --> x="4+5 = 9" local t = {name="lua", version="5.1"} - x = string.gsub(" `name%-` version.tar.gz", "%$(%w+)", t) + x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t) --> x="lua-5.1.tar.gz" < @@ -4154,7 +4150,7 @@ string.upper({s}) *string.upper()* locale. ------------------------------------------------------------------------------ -5.4.1 Patterns *luaref-patterns* *luaref-libStringPat* +5.4.1 Patterns *lua-patterns A character class is used to represent a set of characters. The following combinations are allowed in describing a character class: @@ -4199,9 +4195,8 @@ instance, `%S` represents all non-space characters. The definitions of letter, space, and other character groups depend on the current locale. In particular, the class `[a-z]` may not be equivalent to `%l`. - *luaref-patternitem* -Pattern Item:~ -------------- +PATTERN ITEM *lua-patternitem* + A pattern item may be - a single character class, which matches any single character in the @@ -4226,17 +4221,15 @@ A pattern item may be `y` where the count reaches 0. For instance, the item `%b()` matches expressions with balanced parentheses. - *luaref-pattern* -Pattern:~ --------- +PATTERN *lua-pattern* + A pattern is a sequence of pattern items. A `^` at the beginning of a pattern anchors the match at the beginning of the subject string. A `$` at the end of a pattern anchors the match at the end of the subject string. At other positions, `^` and `$` have no special meaning and represent themselves. - *luaref-capture* -Captures:~ ---------- +CAPTURES *lua-capture* + A pattern may contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use. Captures are numbered @@ -4252,7 +4245,7 @@ string `"flaaap"`, there will be two captures: 3 and 5. A pattern cannot contain embedded zeros. Use `%z` instead. ============================================================================== -5.5 Table Manipulation *luaref-libTable* +5.5 Table Manipulation *lua-lib-table* This library provides generic functions for table manipulation. It provides all its functions inside the table `table`. @@ -4268,15 +4261,15 @@ table.concat({table} [, {sep} [, {i} [, {j}]]]) *table.concat()* for {j} is the length of the table. If {i} is greater than {j}, returns the empty string. -table.foreach({table}, {f}) *table.foreach()* +table.foreach({table}, {f}) *table.foreach()* Executes the given {f} over all elements of {table}. For each element, {f} is called with the index and respective value as arguments. If {f} returns a non-`nil` value, then the loop is broken, and this value is returned as the final value of `table.foreach`. - See |luaref-next()| for extra information about table traversals. + See |next()| for extra information about table traversals. -table.foreachi({table}, {f}) *table.foreachi()* +table.foreachi({table}, {f}) *table.foreachi()* Executes the given {f} over the numerical indices of {table}. For each index, {f} is called with the index and respective value as arguments. Indices are visited in sequential order, from 1 to `n`, where `n` is @@ -4288,7 +4281,7 @@ table.insert({table}, [{pos},] {value}) *table.insert()* Inserts element {value} at position {pos} in {table}, shifting up other elements to open space, if necessary. The default value for {pos} is `n+1`, where `n` is the length of the table (see - |luaref-langLength|), so that a call `table.insert(t,x)` inserts `x` + |lua-length|), so that a call `table.insert(t,x)` inserts `x` at the end of table `t`. table.maxn({table}) *table.maxn()* @@ -4296,27 +4289,26 @@ table.maxn({table}) *table.maxn()* zero if the table has no positive numerical indices. (To do its job this function does a linear traversal of the whole table.) -table.remove({table} [, {pos}]) *table.remove()* +table.remove({table} [, {pos}]) *table.remove()* Removes from {table} the element at position {pos}, shifting down other elements to close the space, if necessary. Returns the value of the removed element. The default value for {pos} is `n`, where `n` is - the length of the table (see |luaref-langLength|), so that a call + the length of the table (see |lua-length|), so that a call `table.remove(t)` removes the last element of table `t`. -table.sort({table} [, {comp}]) *table.sort()* +table.sort({table} [, {comp}]) *table.sort()* Sorts table elements in a given order, `in-place`, from `table[1]` to - `table[n]`, where `n` is the length of the table (see - |luaref-langLength|). If {comp} is given, then it must be a function - that receives two table elements, and returns true when the first is - less than the second (so that `not comp(a[i+1],a[i])` will be true - after the sort). If {comp} is not given, then the standard Lua - operator `<` is used instead. + `table[n]`, where `n` is the length of the table (see |lua-length|). + If {comp} is given, then it must be a function that receives two table + elements, and returns true when the first is less than the second (so + that `not comp(a[i+1],a[i])` will be true after the sort). If {comp} + is not given, then the standard Lua operator `<` is used instead. The sort algorithm is `not` stable, that is, elements considered equal by the given order may have their relative positions changed by the sort. ============================================================================== -5.6 Mathematical Functions *luaref-libMath* +5.6 Mathematical Functions *lua-lib-math* This library is an interface to most of the functions of the standard C math library. It provides all its functions inside the table `math`. @@ -4364,7 +4356,7 @@ math.frexp({x}) *math.frexp()* absolute value of `m` is in the range `[0.5, 1)` (or zero when {x} is zero). -math.huge *math.huge()* +math.huge *math.huge* The value `HUGE_VAL`, a value larger than or equal to any other numerical value. @@ -4387,7 +4379,7 @@ math.modf({x}) *math.modf()* Returns two numbers, the integral part of {x} and the fractional part of {x}. -math.pi *math.pi()* +math.pi *math.pi* The value of `pi`. math.pow({x}, {y}) *math.pow()* @@ -4429,7 +4421,7 @@ math.tanh({x}) *math.tanh()* Returns the hyperbolic tangent of {x}. ============================================================================== -5.6 Input and Output Facilities *luaref-libIO* +5.6 Input and Output Facilities *lua-lib-io* The I/O library provides two different styles for file manipulation. The first one uses implicit file descriptors; that is, there are operations to set a @@ -4467,7 +4459,7 @@ io.input([{file}]) *io.input()* an error code. io.lines([{filename}]) *io.lines()* - Opens the given file name in read mode and returns an iterator + Opens the given file name in read mode and returns an |iterator| function that, each time it is called, returns a new line from the file. Therefore, the construction @@ -4527,16 +4519,16 @@ io.type({obj}) *io.type()* io.write({...}) *io.write()* Equivalent to `io.output():write`. -file:close() *luaref-file:close()* +file:close() *file:close()* Closes `file`. Note that files are automatically closed when their handles are garbage collected, but that takes an unpredictable amount of time to happen. -file:flush() *luaref-file:flush()* +file:flush() *file:flush()* Saves any written data to `file`. -file:lines() *luaref-file:lines()* - Returns an iterator function that, each time it is called, returns a +file:lines() *file:lines()* + Returns an |iterator| function that, each time it is called, returns a new line from the file. Therefore, the construction `for line in file:lines() do` `body` `end` @@ -4544,7 +4536,7 @@ file:lines() *luaref-file:lines()* will iterate over all lines of the file. (Unlike `io.lines`, this function does not close the file when the loop ends.) -file:read({...}) *luaref-file:read()* +file:read({...}) *file:read()* Reads the file `file`, according to the given formats, which specify what to read. For each format, the function returns a string (or a number) with the characters read, or `nil` if it cannot read data with @@ -4563,7 +4555,7 @@ file:read({...}) *luaref-file:read()* returning `nil` on end of file. If number is zero, it reads nothing and returns an empty string, or `nil` on end of file. -file:seek([{whence}] [, {offset}]) *luaref-file:seek()* +file:seek([{whence}] [, {offset}]) *file:seek()* Sets and gets the file position, measured from the beginning of the file, to the position given by {offset} plus a base specified by the string {whence}, as follows: @@ -4583,7 +4575,7 @@ file:seek([{whence}] [, {offset}]) *luaref-file:seek()* `file:seek("end")` sets the position to the end of the file, and returns its size. -file:setvbuf({mode} [, {size}]) *luaref-file:setvbuf()* +file:setvbuf({mode} [, {size}]) *file:setvbuf()* Sets the buffering mode for an output file. There are three available modes: @@ -4599,14 +4591,14 @@ file:setvbuf({mode} [, {size}]) *luaref-file:setvbuf()* For the last two cases, {size} specifies the size of the buffer, in bytes. The default is an appropriate size. -file:write({...}) *luaref-file:write()* +file:write({...}) *file:write()* Writes the value of each of its arguments to `file`. The arguments must be strings or numbers. To write other values, use `tostring` - |luaref-tostring()| or `string.format` |string.format()| before + |tostring()| or `string.format` |string.format()| before `write`. ============================================================================== -5.8 Operating System Facilities *luaref-libOS* +5.8 Operating System Facilities *lua-lib-os* This library is implemented through table `os`. @@ -4691,7 +4683,7 @@ os.tmpname() *os.tmpname()* removed when no longer needed. ============================================================================== -5.9 The Debug Library *luaref-libDebug* +5.9 The Debug Library *lua-lib-debug* This library provides the functionality of the debug interface to Lua programs. You should exert care when using this library. The functions @@ -4765,7 +4757,7 @@ debug.getmetatable({object}) *debug.getmetatable()* have a metatable. debug.getregistry() *debug.getregistry()* - Returns the registry table (see |luaref-apiRegistry|). + Returns the registry table (see |lua-registry|). debug.getupvalue({func}, {up}) *debug.getupvalue()* This function returns the name and the value of the upvalue with index @@ -4826,7 +4818,7 @@ debug.traceback([{thread},] [{message}] [,{level}]) *debug.traceback()* (default is 1, the function calling `traceback`). ============================================================================== -A BIBLIOGRAPHY *luaref-bibliography* +A BIBLIOGRAPHY *lua-ref-bibliography* This help file is a minor adaptation from this main reference: @@ -4852,7 +4844,7 @@ Lua is discussed in these references: "Proc. of V Brazilian Symposium on Programming Languages" (2001) B-14-B-28. ============================================================================== -B COPYRIGHT AND LICENSES *luaref-copyright* +B COPYRIGHT AND LICENSES *lua-ref-copyright* This help file has the same copyright and license as Lua 5.1 and the Lua 5.1 manual: @@ -4878,12 +4870,12 @@ copies or substantial portions of the Software. SOFTWARE. ============================================================================== -C LUAREF DOC *luarefvim* *luarefvimdoc* *luaref-help* *luaref-doc* +C LUAREF DOC *lua-ref-doc* This is a Vim help file containing a reference for Lua 5.1, and it is -- with a few exceptions and adaptations -- a copy of the Lua 5.1 Reference Manual -(see |luaref-bibliography|). For usage information, refer to -|luaref-doc|. For copyright information, see |luaref-copyright|. +(see |lua-ref-bibliography|). For usage information, refer to +|lua-ref-doc|. For copyright information, see |lua-ref-copyright|. The main ideas and concepts on how to implement this reference were taken from Christian Habermann's CRefVim project diff --git a/runtime/doc/luvref.txt b/runtime/doc/luvref.txt index 859e75e4af..915b69efe3 100644 --- a/runtime/doc/luvref.txt +++ b/runtime/doc/luvref.txt @@ -3,10 +3,10 @@ LUV REFERENCE MANUAL - *luvref* + *luvref* This file documents the Lua bindings for the LibUV library which is used for -Nvim's event-loop and is accessible from Lua via |vim.loop| (e.g., |uv.version()| -is exposed as `vim.loop.version()`). +Nvim's event-loop and is accessible from Lua via |vim.uv| (e.g., |uv.version()| +is exposed as `vim.uv.version()`). For information about this manual, see |luv-credits|. @@ -24,12 +24,12 @@ be used in other Lua environments. More information about the core libuv library can be found at the original libuv documentation page (https://docs.libuv.org/). -TCP Echo Server Example~ +TCP Echo Server Example ~ Here is a small example showing a TCP echo server: >lua - local uv = vim.loop + local uv = vim.uv local server = uv.new_tcp() server:bind("127.0.0.1", 1337) @@ -51,15 +51,15 @@ Here is a small example showing a TCP echo server: uv.run() -- an explicit run call is necessary outside of luvit < -Module Layout~ +Module Layout ~ The luv library contains a single Lua module referred to hereafter as `uv` for simplicity. This module consists mostly of functions with names corresponding to their original libuv versions. For example, the libuv function -`uv_tcp_bind` has a luv version at |uv.tcp_bind()|. Currently, only one -non-function field exists: `uv.constants`, which is a table. +`uv_tcp_bind` has a luv version at |uv.tcp_bind()|. Currently, only two +non-function fields exists: `uv.constants` and `uv.errno`, which are tables. -Functions vs Methods~ +Functions vs Methods ~ In addition to having simple functions, luv provides an optional method-style API. For example, `uv.tcp_bind(server, host, port)` can alternatively be @@ -67,7 +67,7 @@ called as `server:bind(host, port)` . Note that the first argument `server` becomes the object and `tcp_` is removed from the function name. Method forms are documented below where they exist. -Synchronous vs Asynchronous Functions~ +Synchronous vs Asynchronous Functions ~ Functions that accept a callback are asynchronous. These functions may immediately return results to the caller to indicate their initial status, but @@ -82,7 +82,7 @@ Some (generally FS and DNS) functions can behave either synchronously or asynchronously. If a callback is provided to these functions, they behave asynchronously; if no callback is provided, they behave synchronously. -Pseudo-Types~ +Pseudo-Types ~ Some unique types are defined. These are not actual types in Lua, but they are used here to facilitate documenting consistent behavior: @@ -91,7 +91,7 @@ used here to facilitate documenting consistent behavior: metamethod - `buffer`: a `string` or a sequential `table` of `string`s - `threadargs`: variable arguments (`...`) of type `nil`, `boolean`, `number`, - `string`, or `userdata` + `string`, or `userdata`; number of arguments limited to 9. ============================================================================== CONTENTS *luv-contents* @@ -133,10 +133,10 @@ module. ============================================================================== ERROR HANDLING *luv-error-handling* -In libuv, errors are negative numbered constants; however, these errors and -the functions used to handle them are not exposed to luv users. Instead, if an -internal error is encountered, the luv function will return to the caller an -assertable `nil, err, name` tuple. +In libuv, errors are negative numbered constants; however, while those errors +are exposed through `uv.errno`, the functions used to handle them are not +exposed to luv users. Instead, if an internal error is encountered, the luv +function will return to the caller an assertable `nil, err, name` tuple. - `nil` idiomatically indicates failure - `err` is a string with the format `{name}: {message}` @@ -151,6 +151,94 @@ When a function is called successfully, it will return either a value that is relevant to the operation of the function, or the integer `0` to indicate success, or sometimes nothing at all. These cases are documented below. +`uv.errno` *uv.errno* + +A table value which exposes error constants as a map, where the key is the +error name (without the `UV_` prefix) and its value is a negative number. +See Libuv's "Error constants" page for further details. +(https://docs.libuv.org/en/v1.x/errors.html#error-constants) + +- `E2BIG`: argument list too long. +- `EACCES`: permission denied. +- `EADDRINUSE`: address already in use. +- `EADDRNOTAVAIL`: address not available. +- `EAFNOSUPPORT`: address family not supported. +- `EAGAIN`: resource temporarily unavailable. +- `EAI_ADDRFAMILY`: address family not supported. +- `EAI_AGAIN`: temporary failure. +- `EAI_BADFLAGS`: bad ai_flags value. +- `EAI_BADHINTS`: invalid value for hints. +- `EAI_CANCELED`: request canceled. +- `EAI_FAIL`: permanent failure. +- `EAI_FAMILY`: ai_family not supported. +- `EAI_MEMORY`: out of memory. +- `EAI_NODATA`: no address. +- `EAI_NONAME`: unknown node or service. +- `EAI_OVERFLOW`: argument buffer overflow. +- `EAI_PROTOCOL`: resolved protocol is unknown. +- `EAI_SERVICE`: service not available for socket type. +- `EAI_SOCKTYPE`: socket type not supported. +- `EALREADY`: connection already in progress. +- `EBADF`: bad file descriptor. +- `EBUSY`: resource busy or locked. +- `ECANCELED`: operation canceled. +- `ECHARSET`: invalid Unicode character. +- `ECONNABORTED`: software caused connection abort. +- `ECONNREFUSED`: connection refused. +- `ECONNRESET`: connection reset by peer. +- `EDESTADDRREQ`: destination address required. +- `EEXIST`: file already exists. +- `EFAULT`: bad address in system call argument. +- `EFBIG`: file too large. +- `EHOSTUNREACH`: host is unreachable. +- `EINTR`: interrupted system call. +- `EINVAL`: invalid argument. +- `EIO`: i/o error. +- `EISCONN`: socket is already connected. +- `EISDIR`: illegal operation on a directory. +- `ELOOP`: too many symbolic links encountered. +- `EMFILE`: too many open files. +- `EMSGSIZE`: message too long. +- `ENAMETOOLONG`: name too long. +- `ENETDOWN`: network is down. +- `ENETUNREACH`: network is unreachable. +- `ENFILE`: file table overflow. +- `ENOBUFS`: no buffer space available. +- `ENODEV`: no such device. +- `ENOENT`: no such file or directory. +- `ENOMEM`: not enough memory. +- `ENONET`: machine is not on the network. +- `ENOPROTOOPT`: protocol not available. +- `ENOSPC`: no space left on device. +- `ENOSYS`: function not implemented. +- `ENOTCONN`: socket is not connected. +- `ENOTDIR`: not a directory. +- `ENOTEMPTY`: directory not empty. +- `ENOTSOCK`: socket operation on non-socket. +- `ENOTSUP`: operation not supported on socket. +- `EOVERFLOW`: value too large for defined data type. +- `EPERM`: operation not permitted. +- `EPIPE`: broken pipe. +- `EPROTO`: protocol error. +- `EPROTONOSUPPORT`: protocol not supported. +- `EPROTOTYPE`: protocol wrong type for socket. +- `ERANGE`: result too large. +- `EROFS`: read-only file system. +- `ESHUTDOWN`: cannot send after transport endpoint shutdown. +- `ESPIPE`: invalid seek. +- `ESRCH`: no such process. +- `ETIMEDOUT`: connection timed out. +- `ETXTBSY`: text file is busy. +- `EXDEV`: cross-device link not permitted. +- `UNKNOWN`: unknown error. +- `EOF`: end of file. +- `ENXIO`: no such device or address. +- `EMLINK`: too many links. +- `ENOTTY`: inappropriate ioctl for device. +- `EFTYPE`: inappropriate file type or format. +- `EILSEQ`: illegal byte sequence. +- `ESOCKTNOSUPPORT`: socket type not supported. + ============================================================================== VERSION CHECKING *luv-version-checking* @@ -1213,11 +1301,11 @@ uv.spawn({path}, {options}, {on_exit}) *uv.spawn()* The `options` table accepts the following fields: - `options.args` - Command line arguments as a list of - string. The first string should be the path to the - program. On Windows, this uses CreateProcess which - concatenates the arguments into a string. This can cause - some strange errors. (See `options.verbatim` below for - Windows.) + strings. The first string should not be the path to the + program, since that is already provided via `path`. On + Windows, this uses CreateProcess which concatenates the + arguments into a string. This can cause some strange + errors (see `options.verbatim` below for Windows). - `options.stdio` - Set the file descriptors that will be made available to the child process. The convention is that the first entries are stdin, stdout, and stderr. @@ -1267,7 +1355,7 @@ uv.process_kill({process}, {signum}) *uv.process_kill()* Parameters: - `process`: `uv_process_t userdata` - - `signum`: `integer` or `string` + - `signum`: `integer` or `string` or `nil` (default: `sigterm`) Sends the specified signal to the given process handle. Check the documentation on |uv_signal_t| for signal support, @@ -1279,7 +1367,7 @@ uv.kill({pid}, {signum}) *uv.kill()* Parameters: - `pid`: `integer` - - `signum`: `integer` or `string` + - `signum`: `integer` or `string` or `nil` (default: `sigterm`) Sends the specified signal to the given PID. Check the documentation on |uv_signal_t| for signal support, specially @@ -1976,6 +2064,69 @@ uv.pipe({read_flags}, {write_flags}) *uv.pipe()* end) < +uv.pipe_bind2({pipe}, {name}, {flags}) *uv.pipe_bind2()* + + > method form `pipe:pipe_bind(name, flags)` + + Parameters: + - `pipe`: `uv_pipe_t userdata` + - `name`: `string` + - `flags`: `integer` or `table` or `nil`(default: 0) + + Flags: + - If `type(flags)` is `number`, it must be `0` or + `uv.constants.PIPE_NO_TRUNCATE`. + - If `type(flags)` is `table`, it must be `{}` or + `{ no_trunate = true|false }`. + - If `type(flags)` is `nil`, it use default value `0`. + - Returns `EINVAL` for unsupported flags without performing the + bind. + + Bind the pipe to a file path (Unix) or a name (Windows). + + Supports Linux abstract namespace sockets. namelen must include + the leading '\0' byte but not the trailing nul byte. + + Returns: `0` or `fail` + + *Note*: + 1. Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) + bytes, typically between 92 and 108 bytes. + 2. New in version 1.46.0. + +uv.pipe_connect2(pipe, name, [flags], [callback]) *uv.pipe_connect2()* + + > method form `pipe:connect2(name, [flags], [callback])` + + Parameters: + - `pipe`: `uv_pipe_t userdata` + - `name`: `string` + - `flags`: `integer` or `table` or `nil`(default: 0) + - `callback`: `callable` or `nil` + - `err`: `nil` or `string` + + `Flags`: + + - If `type(flags)` is `number`, it must be `0` or + `uv.constants.PIPE_NO_TRUNCATE`. + - If `type(flags)` is `table`, it must be `{}` or + `{ no_trunate = true|false }`. + - If `type(flags)` is `nil`, it use default value `0`. + - Returns `EINVAL` for unsupported flags without performing the + bind operation. + + Connect to the Unix domain socket or the named pipe. + + Supports Linux abstract namespace sockets. namelen must include + the leading nul byte but not the trailing nul byte. + + Returns: `uv_connect_t userdata` or `fail` + + *Note*: + 1. Paths on Unix get truncated to sizeof(sockaddr_un.sun_path) + bytes, typically between 92 and 108 bytes. + 2. New in version 1.46.0. + ============================================================================== `uv_tty_t` — TTY handle *luv-tty-handle* *uv_tty_t* @@ -2488,7 +2639,7 @@ uv.fs_poll_start({fs_poll}, {path}, {interval}, {callback}) *uv.fs_poll_start()* > method form `fs_poll:start(path, interval, callback)` Parameters: - - `fs_event`: `uv_fs_event_t userdata` + - `fs_poll`: `uv_fs_poll_t userdata` - `path`: `string` - `interval`: `integer` - `callback`: `callable` @@ -2829,7 +2980,7 @@ uv.fs_fstat({fd} [, {callback}]) *uv.fs_fstat()* uv.fs_lstat({path} [, {callback}]) *uv.fs_lstat()* Parameters: - - `fd`: `integer` + - `path`: `string` - `callback`: `callable` (async version) or `nil` (sync version) - `err`: `nil` or `string` @@ -3272,14 +3423,17 @@ file system operations, as well as `getaddrinfo` and `getnameinfo` requests. uv.new_work({work_callback}, {after_work_callback}) *uv.new_work()* Parameters: - - `work_callback`: `function` + - `work_callback`: `function` or `string` - `...`: `threadargs` passed to/from `uv.queue_work(work_ctx, ...)` - `after_work_callback`: `function` - `...`: `threadargs` returned from `work_callback` Creates and initializes a new `luv_work_ctx_t` (not - `uv_work_t`). Returns the Lua userdata wrapping it. + `uv_work_t`). + `work_callback` is a Lua function or a string containing Lua + code or bytecode dumped from a function. Returns the Lua + userdata wrapping it. Returns: `luv_work_ctx_t userdata` @@ -3380,19 +3534,22 @@ uv.new_thread([{options}, ] {entry}, {...}) *uv.new_thread()* Parameters: - `options`: `table` or `nil` - `stack_size`: `integer` or `nil` - - `entry`: `function` + - `entry`: `function` or `string` - `...`: `threadargs` passed to `entry` Creates and initializes a `luv_thread_t` (not `uv_thread_t`). Returns the Lua userdata wrapping it and asynchronously - executes `entry`, which can be either a Lua function or a Lua - function dumped to a string. Additional arguments `...` are - passed to the `entry` function and an optional `options` table - may be provided. Currently accepted `option` fields are - `stack_size`. + executes `entry`, which can be either a Lua function or a + string containing Lua code or bytecode dumped from a function. + Additional arguments `...` are passed to the `entry` function + and an optional `options` table may be provided. Currently + accepted `option` fields are `stack_size`. Returns: `luv_thread_t userdata` or `fail` + Note: unsafe, please make sure that the thread's end of life + is before Lua state is closed. + uv.thread_equal({thread}, {other_thread}) *uv.thread_equal()* > method form `thread:equal(other_thread)` @@ -3405,6 +3562,73 @@ uv.thread_equal({thread}, {other_thread}) *uv.thread_equal()* This function is equivalent to the `__eq` metamethod. Returns: `boolean` + *uv.thread_setaffinity()* +uv.thread_setaffinity({thread}, {affinity} [, {get_old_affinity}]) + + > method form `thread:setaffinity(affinity, [get_old_affinity])` + + Parameters: + - `thread`: `luv_thread_t userdata` + - `affinity`: `table` + - `[1, 2, 3, ..., n]` : `boolean` + - `get_old_affinity`: `boolean` + + Sets the specified thread's affinity setting. + + `affinity` must be a table where each of the keys are a CPU + number and the values are booleans that represent whether the + `thread` should be eligible to run on that CPU. If the length + of the `affinity` table is not greater than or equal to + |uv.cpumask_size()|, any CPU numbers missing from the table + will have their affinity set to `false`. If setting the + affinity of more than |uv.cpumask_size()| CPUs is desired, + `affinity` must be an array-like table with no gaps, since + `#affinity` will be used as the `cpumask_size` if it is + greater than |uv.cpumask_size()|. + + If `get_old_affinity` is `true`, the previous affinity + settings for the `thread` will be returned. Otherwise, `true` + is returned after a successful call. + + Note: Thread affinity setting is not atomic on Windows. + Unsupported on macOS. + + Returns: `table` or `boolean` or `fail` + - `[1, 2, 3, ..., n]` : `boolean` + + +uv.thread_getaffinity({thread} [, {mask_size}]) *uv.thread_getaffinity()* + + > method form `thread:getaffinity([mask_size])` + + Parameters: + - `thread`: `luv_thread_t userdata` + - `mask_size`: `integer` + + Gets the specified thread's affinity setting. + + If `mask_size` is provided, it must be greater than or equal + to `uv.cpumask_size()`. If the `mask_size` parameter is + omitted, then the return of `uv.cpumask_size()` will be used. + Returns an array-like table where each of the keys correspond + to a CPU number and the values are booleans that represent + whether the `thread` is eligible to run on that CPU. + + Note: Thread affinity getting is not atomic on Windows. + Unsupported on macOS. + + Returns: `table` or `fail` + - `[1, 2, 3, ..., n]` : `boolean` + +uv.thread_getcpu() *uv.thread_getcpu()* + + Gets the CPU number on which the calling thread is running. + + Note: The first CPU will be returned as the number 1, not 0. + This allows for the number to correspond with the table keys + used in `uv.thread_getaffinity` and `uv.thread_setaffinity`. + + Returns: `integer` or `fail` uv.thread_self() *uv.thread_self()* @@ -3494,6 +3718,16 @@ uv.get_constrained_memory() *uv.get_constrained_memory()* Returns: `number` +uv.get_available_memory() *uv.get_available_memory()* + + Gets the amount of free memory that is still available to the + process (in bytes). This differs from `uv.get_free_memory()` + in that it takes into account any limits imposed by the OS. If + there is no such constraint, or the constraint is unknown, the + amount returned will be identical to `uv.get_free_memory()`. + + Returns: `number` + uv.resident_set_memory() *uv.resident_set_memory()* Returns the resident set size (RSS) for the current process. @@ -3558,6 +3792,14 @@ uv.cpu_info() *uv.cpu_info()* - `idle` : `number` - `irq` : `number` +uv.cpumask_size() *uv.cpumask_size()* + + Returns the maximum size of the mask used for process/thread + affinities, or `ENOTSUP` if affinities are not supported on + the current platform. + + Returns: `integer` or `fail` + uv.getpid() *uv.getpid()* DEPRECATED: Please use |uv.os_getpid()| instead. @@ -3614,6 +3856,25 @@ uv.hrtime() *uv.hrtime()* Returns: `number` +uv.clock_gettime({clock_id}) *uv.clock_gettime()* + + Parameters: + - `clock_id`: `string` + + Obtain the current system time from a high-resolution + real-time or monotonic clock source. `clock_id` can be the + string `"monotonic"` or `"realtime"`. + + The real-time clock counts from the UNIX epoch (1970-01-01) + and is subject to time adjustments; it can jump back in time. + + The monotonic clock counts from an arbitrary point in the past + and never jumps back in time. + + Returns: `table` or `fail` + - `sec`: `integer` + - `nsec`: `integer` + uv.uptime() *uv.uptime()* Returns the current system uptime in seconds. @@ -3752,7 +4013,12 @@ uv.os_setenv({name}, {value}) *uv.os_setenv()* WARNING: This function is not thread safe. -uv.os_unsetenv() *uv.os_unsetenv()* +uv.os_unsetenv({name}) *uv.os_unsetenv()* + + Parameters: + - `name`: `string` + + Unsets the environmental variable specified by `name`. Returns: `boolean` or `fail` @@ -3885,14 +4151,28 @@ uv.metrics_idle_time() *uv.metrics_idle_time()* Returns: `number` +uv.metrics_info() *uv.metrics_info()* + + Get the metrics table from current set of event loop metrics. + It is recommended to retrieve these metrics in a `prepare` + callback (see |uv.new_prepare()|, |uv.prepare_start()|) in order + to make sure there are no inconsistencies with the metrics + counters. + + Returns: `table` + + - `loop_count` : `integer` + - `events` : `integer` + - `events_waiting` : `integer` + ============================================================================== CREDITS *luv-credits* -This document is a reformatted version of the LUV documentation, based on -commit c51e705 (5 May 2022) of the luv repository -https://github.com/luvit/luv/commit/c51e7052ec4f0a25058f70c1b4ee99dd36180e59. +This document is a reformatted version of the LUV documentation, up-to-date +with commit dcd1a1c (23 Aug 2023) of the luv repository +https://github.com/luvit/luv/commit/dcd1a1cad5b05634a7691402d6ca2f214fb4ae76. -Included from https://github.com/nanotee/luv-vimdocs with kind permission. +Based on https://github.com/nanotee/luv-vimdocs with kind permission. vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index cb8b162eb6..6f61259af0 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -290,7 +290,7 @@ Therefore the following is blocked for <expr> mappings: - Moving the cursor is allowed, but it is restored afterwards. - If the cmdline is changed, the old text and cursor position are restored. If you want the mapping to do any of these let the returned characters do -that. (Or use a |<Cmd>| mapping instead.) +that, or use a |<Cmd>| mapping instead. You can use getchar(), it consumes typeahead if there is any. E.g., if you have these mappings: > @@ -324,20 +324,22 @@ be seen as a special key. *<Cmd>* *:map-cmd* The <Cmd> pseudokey begins a "command mapping", which executes the command -directly (without changing modes). Where you might use ":...<CR>" in the +directly without changing modes. Where you might use ":...<CR>" in the {rhs} of a mapping, you can instead use "<Cmd>...<CR>". Example: > - noremap x <Cmd>echo mode(1)<cr> + noremap x <Cmd>echo mode(1)<CR> < -This is more flexible than `:<C-U>` in visual and operator-pending mode, or -`<C-O>:` in insert-mode, because the commands are executed directly in the -current mode (instead of always going to normal-mode). Visual-mode is +This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or +`<C-O>:` in Insert mode, because the commands are executed directly in the +current mode, instead of always going to Normal mode. Visual mode is preserved, so tricks with |gv| are not needed. Commands can be invoked -directly in cmdline-mode (which would otherwise require timer hacks). +directly in Command-line mode (which would otherwise require timer hacks). +Example of using <Cmd> halfway Insert mode: > + nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc> Unlike <expr> mappings, there are no special restrictions on the <Cmd> command: it is executed as if an (unrestricted) |autocommand| was invoked -or an async event event was processed. +or an async event was processed. Note: - Because <Cmd> avoids mode-changes (unlike ":") it does not trigger @@ -347,10 +349,10 @@ Note: - The command is not echo'ed, no need for <silent>. - The {rhs} is not subject to abbreviations nor to other mappings, even if the mapping is recursive. -- In Visual mode you can use `line('v')` and `col('v')` to get one end of the +- In Visual mode you can use `line('v')` and `col('v')` to get one end of the Visual area, the cursor is at the other end. - *E5520* + *E1255* *E1136* <Cmd> commands must terminate, that is, they must be followed by <CR> in the {rhs} of the mapping definition. |Command-line| mode is never entered. @@ -540,28 +542,10 @@ See |:verbose-cmd| for more information. 1.5 MAPPING SPECIAL KEYS *:map-special-keys* -There are two ways to map a special key: -1. The Vi-compatible method: Map the key code. Often this is a sequence that - starts with <Esc>. To enter a mapping like this you type ":map " and then - you have to type CTRL-V before hitting the function key. Note that when - the key code for the key is in the |terminfo| entry, it will automatically - be translated into the internal code and become the second way of mapping. -2. The second method is to use the internal code for the function key. To - enter such a mapping type CTRL-K and then hit the function key, or use - the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc. - (see table of keys |key-notation|, all keys from <Up> can be used). The - first ten function keys can be defined in two ways: Just the number, like - "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0" - refers to function key 10. - -DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it -isn't the terminal key codes are tried. If a terminal code is found it is -replaced with the internal code. Then the check for a mapping is done again -(so you can map an internal code to something else). What is written into the -script file depends on what is recognized. If the terminal key code was -recognized as a mapping the key code itself is written to the script file. If -it was recognized as a terminal code the internal code is written to the -script file. +To map a function key, use the internal code for it. To enter such a mapping +type CTRL-K and then hit the function key, or use the form "<F2>", "<F10>", +"<Up>", "<S-Down>", "<S-F7>", etc. (see table of keys |key-notation|, all keys +from <Up> can be used). 1.6 SPECIAL CHARACTERS *:map-special-chars* @@ -654,6 +638,7 @@ not to be matched with any key sequence. This is useful in plugins *<MouseMove>* The special key name "<MouseMove>" can be used to handle mouse movement. It needs to be enabled with 'mousemoveevent'. +The |getmousepos()| function can be used to obtain the mouse position. *<Char>* *<Char->* To map a character by its decimal, octal or hexadecimal number the <Char> @@ -695,8 +680,7 @@ this (see |<>|). Example: > :map _ls :!ls -l %:S<CR>:echo "the end"<CR> To avoid mapping of the characters you type in insert or Command-line mode, -type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste' -option is on. +type a CTRL-V first. *map-error* Note that when an error is encountered (that causes an error message or might cause a beep) the rest of the mapping is not executed. This is Vi-compatible. @@ -764,7 +748,7 @@ option). After that it assumes that the 'q' is to be interpreted as such. If you type slowly, or your system is slow, reset the 'timeout' option. Then you might want to set the 'ttimeout' option. - *map-precedence* + *map-precedence* Buffer-local mappings (defined using |:map-<buffer>|) take precedence over global mappings. When a buffer-local mapping is the same as a global mapping, Vim will use the buffer-local mapping. In addition, Vim will use a complete @@ -838,6 +822,11 @@ in the original Vi, you would get back the text before the first undo). 1.10 MAPPING ALT-KEYS *:map-alt-keys* +For a readable mapping command the <A-k> form can be used. Note that <A-k> +and <A-K> are different, the latter will use an upper case letter. Actually, +<A-K> and <A-S-K> are the same. Instead of "A" you can use "M". If you have +an actual Meta modifier key, please see |:map-meta-keys|. + In the GUI Nvim handles the |ALT| key itself, thus mapping keys with ALT should always work. But in a terminal Nvim gets a sequence of bytes and has to figure out whether ALT was pressed. Terminals may use ESC to indicate that @@ -847,7 +836,21 @@ milliseconds, the ESC is interpreted as: otherwise it is interpreted as two key presses: <ESC> {key} -1.11 MAPPING AN OPERATOR *:map-operator* +1.11 MAPPING META-KEYS *:map-meta-keys* + +Mapping keys with the Meta modifier works very similar to using the Alt key. +What key on your keyboard produces the Meta modifier depends on your keyboard +and configuration. + +Note that mapping <M-a> actually is for using the Alt key. That can be +confusing! It cannot be changed, it would not be backwards compatible. + +For the Meta modifier the "T" character is used. For example, to map Meta-b +in Insert mode: > + :imap <T-b> terrible + + +1.12 MAPPING AN OPERATOR *:map-operator* An operator is used before a {motion} command. To define your own operator you must create a mapping that first sets the 'operatorfunc' option and then @@ -952,7 +955,7 @@ operator to add quotes around text in the current line: > \ ->setline(".")}'<CR>g@ ============================================================================== -2. Abbreviations *abbreviations* *Abbreviations* +2. Abbreviations *abbreviation* *abbreviations* *Abbreviations* Abbreviations are used in Insert mode, Replace mode and Command-line mode. If you enter a word that is an abbreviation, it is replaced with the word it @@ -984,7 +987,7 @@ non-id The "non-id" type ends in a non-keyword character, the other Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r" An abbreviation is only recognized when you type a non-keyword character. -This can also be the <Esc> that ends insert mode or the <CR> that ends a +This can also be the <Esc> that ends Insert mode or the <CR> that ends a command. The non-keyword character which ends the abbreviation is inserted after the expanded abbreviation. An exception to this is the character <C-]>, which is used to expand an abbreviation without inserting any extra @@ -1048,10 +1051,7 @@ typed after an abbreviation: > There are no default abbreviations. Abbreviations are never recursive. You can use ":ab f f-o-o" without any -problem. But abbreviations can be mapped. {some versions of Vi support -recursive abbreviations, for no apparent reason} - -Abbreviations are disabled if the 'paste' option is on. +problem. But abbreviations can be mapped. *:abbreviate-local* *:abbreviate-<buffer>* Just like mappings, abbreviations can be local to a buffer. This is mostly @@ -1186,12 +1186,14 @@ functions used in one script use the same name as in other scripts. To avoid this, they can be made local to the script. *<SID>* *<SNR>* *E81* -The string "<SID>" can be used in a mapping or menu. +The string "<SID>" can be used in a mapping or menu. This is useful if you +have a script-local function that you want to call from a mapping in the same +script. When executing the map command, Vim will replace "<SID>" with the special key code <SNR>, followed by a number that's unique for the script, and an underscore. Example: > :map <SID>Add -could define a mapping "<SNR>23_Add". +would define a mapping "<SNR>23_Add". When defining a function in a script, "s:" can be prepended to the name to make it local to the script. But when a mapping is executed from outside of @@ -1322,6 +1324,11 @@ can have arguments, or have a range specified. Arguments are subject to completion as filenames, buffers, etc. Exactly how this works depends upon the command's attributes, which are specified when the command is defined. +When defining a user command in a script, it will be able to call functions +local to the script and use mappings local to the script. When the user +invokes the user command, it will run in the context of the script it was +defined in. This matters if |<SID>| is used in a command. + There are a number of attributes, split into four categories: argument handling, completion behavior, range handling, and special cases. The attributes are described below, by category. @@ -1383,7 +1390,7 @@ completion can be enabled: -complete=highlight highlight groups -complete=history :history suboptions -complete=locale locale names (as output of locale -a) - -complete=lua Lua expression + -complete=lua Lua expression |:lua| -complete=mapclear buffer argument -complete=mapping mapping name -complete=menu menus @@ -1484,7 +1491,7 @@ which by default correspond to the current line, last line and the whole buffer, relate to arguments, (loaded) buffers, windows or tab pages. Possible values are (second column is the short name used in listing): - -addr=lines Range of lines (this is the default for -range) + -addr=lines Range of lines (this is the default for -range) -addr=arguments arg Range for arguments -addr=buffers buf Range for buffers (also not loaded buffers) -addr=loaded_buffers load Range for loaded buffers @@ -1538,6 +1545,7 @@ supports incremental command preview: -- If invoked as a preview callback, performs 'inccommand' preview by -- highlighting trailing whitespace in the current buffer. local function trim_space_preview(opts, preview_ns, preview_buf) + vim.cmd('hi clear Whitespace') local line1 = opts.line1 local line2 = opts.line2 local buf = vim.api.nvim_get_current_buf() @@ -1722,7 +1730,11 @@ remains unmodified. Also see |f-args-example| below. Overview: XX a\\\ b 'a\ b' XX a\\\\b 'a\\b' XX a\\\\ b 'a\\', 'b' + XX [nothing] + +Note that if the "no arguments" situation is to be handled, you have to make +sure that the function can be called without arguments. Examples for user commands: > @@ -1770,9 +1782,5 @@ errors and the "update" command to write modified buffers): > This will invoke: > :call Allargs("%s/foo/bar/ge|update") < -When defining a user command in a script, it will be able to call functions -local to the script and use mappings local to the script. When the user -invokes the user command, it will run in the context of the script it was -defined in. This matters if |<SID>| is used in a command. vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/mbyte.txt b/runtime/doc/mbyte.txt index 99dfa54218..0a7e0baad3 100644 --- a/runtime/doc/mbyte.txt +++ b/runtime/doc/mbyte.txt @@ -358,150 +358,6 @@ conversion needs to be done. These conversions are supported: Try getting another iconv() implementation. ============================================================================== -Input on X11 *mbyte-XIM* - -X INPUT METHOD (XIM) BACKGROUND *XIM* *xim* *x-input-method* - -XIM is an international input module for X. There are two kinds of structures, -Xlib unit type and |IM-server| (Input-Method server) type. |IM-server| type -is suitable for complex input, such as CJK. - -- IM-server - *IM-server* - In |IM-server| type input structures, the input event is handled by either - of the two ways: FrontEnd system and BackEnd system. In the FrontEnd - system, input events are snatched by the |IM-server| first, then |IM-server| - give the application the result of input. On the other hand, the BackEnd - system works reverse order. MS-Windows adopt BackEnd system. In X, most of - |IM-server|s adopt FrontEnd system. The demerit of BackEnd system is the - large overhead in communication, but it provides safe synchronization with - no restrictions on applications. - -- Conversion Server - *conversion-server* - Some system needs additional server: conversion server. Most of Japanese - |IM-server|s need it, Kana-Kanji conversion server. For Chinese inputting, - it depends on the method of inputting, in some methods, PinYin or ZhuYin to - HanZi conversion server is needed. For Korean inputting, if you want to - input Hanja, Hangul-Hanja conversion server is needed. - - For example, the Japanese inputting process is divided into 2 steps. First - we pre-input Hira-gana, second Kana-Kanji conversion. There are so many - Kanji characters (6349 Kanji characters are defined in JIS X 0208) and the - number of Hira-gana characters are 76. So, first, we pre-input text as - pronounced in Hira-gana, second, we convert Hira-gana to Kanji or Kata-Kana, - if needed. There are some Kana-Kanji conversion server: jserver - (distributed with Wnn, see below) and canna. Canna can be found at: - http://canna.sourceforge.jp/ - -There is a good input system: Wnn4.2. Wnn 4.2 contains, - xwnmo (|IM-server|) - jserver (Japanese Kana-Kanji conversion server) - cserver (Chinese PinYin or ZhuYin to simplified HanZi conversion server) - tserver (Chinese PinYin or ZhuYin to traditional HanZi conversion server) - kserver (Hangul-Hanja conversion server) -Wnn 4.2 for several systems can be found at various places on the internet. -Use the RPM or port for your system. - - -- Input Style - *xim-input-style* - When inputting CJK, there are four areas: - 1. The area to display of the input while it is being composed - 2. The area to display the currently active input mode. - 3. The area to display the next candidate for the selection. - 4. The area to display other tools. - - The third area is needed when converting. For example, in Japanese - inputting, multiple Kanji characters could have the same pronunciation, so - a sequence of Hira-gana characters could map to a distinct sequence of Kanji - characters. - - The first and second areas are defined in international input of X with the - names of "Preedit Area", "Status Area" respectively. The third and fourth - areas are not defined and are left to be managed by the |IM-server|. In the - international input, four input styles have been defined using combinations - of Preedit Area and Status Area: |OnTheSpot|, |OffTheSpot|, |OverTheSpot| - and |Root|. - - Currently, GUI Vim supports three styles, |OverTheSpot|, |OffTheSpot| and - |Root|. - -*. on-the-spot *OnTheSpot* - Preedit Area and Status Area are performed by the client application in - the area of application. The client application is directed by the - |IM-server| to display all pre-edit data at the location of text - insertion. The client registers callbacks invoked by the input method - during pre-editing. -*. over-the-spot *OverTheSpot* - Status Area is created in a fixed position within the area of application, - in case of Vim, the position is the additional status line. Preedit Area - is made at present input position of application. The input method - displays pre-edit data in a window which it brings up directly over the - text insertion position. -*. off-the-spot *OffTheSpot* - Preedit Area and Status Area are performed in the area of application, in - case of Vim, the area is additional status line. The client application - provides display windows for the pre-edit data to the input method which - displays into them directly. -*. root-window *Root* - Preedit Area and Status Area are outside of the application. The input - method displays all pre-edit data in a separate area of the screen in a - window specific to the input method. - - -USING XIM *multibyte-input* *E284* *E285* *E286* *E287* - *E288* *E289* - -Note that Display and Input are independent. It is possible to see your -language even though you have no input method for it. But when your Display -method doesn't match your Input method, the text will be displayed wrong. - -To input your language you should run the |IM-server| which supports your -language and |conversion-server| if needed. - -The next 3 lines should be put in your ~/.Xdefaults file. They are common for -all X applications which uses |XIM|. If you already use |XIM|, you can skip -this. > - - *international: True - *.inputMethod: your_input_server_name - *.preeditType: your_input_style -< -input_server_name is your |IM-server| name (check your |IM-server| - manual). -your_input_style is one of |OverTheSpot|, |OffTheSpot|, |Root|. See - also |xim-input-style|. - -*international may not be necessary if you use X11R6. -*.inputMethod and *.preeditType are optional if you use X11R6. - -For example, when you are using kinput2 as |IM-server|, > - - *international: True - *.inputMethod: kinput2 - *.preeditType: OverTheSpot -< -When using |OverTheSpot|, GUI Vim always connects to the IM Server even in -Normal mode, so you can input your language with commands like "f" and "r". -But when using one of the other two methods, GUI Vim connects to the IM Server -only if it is not in Normal mode. - -If your IM Server does not support |OverTheSpot|, and if you want to use your -language with some Normal mode command like "f" or "r", then you should use a -localized xterm or an xterm which supports |XIM| - -If needed, you can set the XMODIFIERS environment variable: - - sh: export XMODIFIERS="@im=input_server_name" - csh: setenv XMODIFIERS "@im=input_server_name" - -For example, when you are using kinput2 as |IM-server| and sh, > - - export XMODIFIERS="@im=kinput2" -< - -============================================================================== Input with a keymap *mbyte-keymap* When the keyboard doesn't produce the characters you want to enter in your @@ -790,7 +646,8 @@ widespread as file format. A composing or combining character is used to change the meaning of the character before it. The combining characters are drawn on top of the preceding character. -Up to six combining characters can be displayed. +Too big combined characters cannot be displayed, but they can still be +inspected using the |g8| and |ga| commands described below. When editing text a composing character is mostly considered part of the preceding character. For example "x" will delete a character and its following composing characters by default. diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt index dffdb5950f..9f06e8c931 100644 --- a/runtime/doc/message.txt +++ b/runtime/doc/message.txt @@ -127,6 +127,8 @@ This happens when an Ex command executes an Ex command that executes an Ex command, etc. The limit is 200 or the value of 'maxfuncdepth', whatever is larger. When it's more there probably is an endless loop. Probably a |:execute| or |:source| command is involved. +Can also happen with a recursive callback function (|channel-callback|). +A limit of 20 is used here. *E254* > Cannot allocate color {name} @@ -327,7 +329,7 @@ You can switch the 'write' option on with ":set write". *E25* > Nvim does not have a built-in GUI -Neovim does not have a built in GUI, so `:gvim` and `:gui` don't work. +Nvim does not have a built in GUI, so `:gvim` and `:gui` don't work. *E49* > Invalid scroll size @@ -820,13 +822,13 @@ Type effect ~ the clipboard ("* and "+ registers) {menu-entry} what the menu is defined to in Cmdline-mode. - <LeftMouse> next page (*) + <LeftMouse> next page* Any other key causes the meaning of the keys to be displayed. -(*) Clicking the left mouse button only works: - - For the GUI: in the last line of the screen. - - When 'r' is included in 'mouse' (but then selecting text won't work). +* Clicking the left mouse button only works: + - For the GUI: in the last line of the screen. + - When 'r' is included in 'mouse' (but then selecting text won't work). Note: The typed key is directly obtained from the terminal, it is not mapped diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt index 929efee19f..aa18e44225 100644 --- a/runtime/doc/motion.txt +++ b/runtime/doc/motion.txt @@ -233,8 +233,8 @@ gM Like "g0", but to halfway the text of the line. Thus "10gM" is near the start of the text and "90gM" is near the end of the text. - *g$* *g<End>* -g$ or g<End> When lines wrap ('wrap' on): To the last character of + *g$* +g$ When lines wrap ('wrap' on): To the last character of the screen line and [count - 1] screen lines downward |inclusive|. Differs from "$" when a line is wider than the screen. @@ -247,6 +247,10 @@ g$ or g<End> When lines wrap ('wrap' on): To the last character of When 'virtualedit' is enabled moves to the end of the screen line. + *g<End>* *g<kEnd>* +g<End> Like |g$| but to the last non-blank character + instead of the last character. + *bar* | To screen column [count] in the current line. |exclusive| motion. Ceci n'est pas une pipe. @@ -566,14 +570,16 @@ a] *v_a]* *v_a[* *a]* *a[* a[ "a [] block", select [count] '[' ']' blocks. This goes backwards to the [count] unclosed '[', and finds the matching ']'. The enclosed text is selected, - including the '[' and ']'. + including the '[' and ']'. The |cpo-M| option flag + is used to handle escaped brackets. When used in Visual mode it is made charwise. i] *v_i]* *v_i[* *i]* *i[* i[ "inner [] block", select [count] '[' ']' blocks. This goes backwards to the [count] unclosed '[', and finds the matching ']'. The enclosed text is selected, - excluding the '[' and ']'. + excluding the '[' and ']'. The |cpo-M| option flag + is used to handle escaped brackets. When used in Visual mode it is made charwise. a) *v_a)* *a)* *a(* @@ -581,7 +587,8 @@ a( *vab* *v_ab* *v_a(* *ab* ab "a block", select [count] blocks, from "[count] [(" to the matching ')', including the '(' and ')' (see |[(|). Does not include white space outside of the - parenthesis. + parenthesis. The |cpo-M| option flag is used to + handle escaped parenthesis. When used in Visual mode it is made charwise. i) *v_i)* *i)* *i(* @@ -589,19 +596,22 @@ i( *vib* *v_ib* *v_i(* *ib* ib "inner block", select [count] blocks, from "[count] [(" to the matching ')', excluding the '(' and ')' (see |[(|). If the cursor is not inside a () block, then - find the next "(". + find the next "(". The |cpo-M| option flag + is used to handle escaped parenthesis. When used in Visual mode it is made charwise. a> *v_a>* *v_a<* *a>* *a<* a< "a <> block", select [count] <> blocks, from the [count]'th unmatched '<' backwards to the matching - '>', including the '<' and '>'. + '>', including the '<' and '>'. The |cpo-M| option flag + is used to handle escaped '<' and '>'. When used in Visual mode it is made charwise. i> *v_i>* *v_i<* *i>* *i<* i< "inner <> block", select [count] <> blocks, from the [count]'th unmatched '<' backwards to the matching - '>', excluding the '<' and '>'. + '>', excluding the '<' and '>'. The |cpo-M| option flag + is used to handle escaped '<' and '>'. When used in Visual mode it is made charwise. *v_at* *at* @@ -620,16 +630,18 @@ it "inner tag block", select [count] tag blocks, from the a} *v_a}* *a}* *a{* a{ *v_aB* *v_a{* *aB* -aB "a Block", select [count] Blocks, from "[count] [{" to - the matching '}', including the '{' and '}' (see - |[{|). +aB "a Block", select [count] Blocks, from `[count] [{` to + the matching "}", including the "{" and "}" (see + |[{|). The |cpo-M| option flag is used to handle + escaped braces. When used in Visual mode it is made charwise. i} *v_i}* *i}* *i{* i{ *v_iB* *v_i{* *iB* -iB "inner Block", select [count] Blocks, from "[count] [{" - to the matching '}', excluding the '{' and '}' (see - |[{|). +iB "inner Block", select [count] Blocks, from `[count] [{` + to the matching "}", excluding the "{" and "}" (see + |[{|). The |cpo-M| option flag is used to handle + escaped braces. When used in Visual mode it is made charwise. a" *v_aquote* *aquote* @@ -656,6 +668,7 @@ i` *v_i`* *i`* Special case: With a count of 2 the quotes are included, but no extra white space as with a"/a'/a`. + *o_object-select* When used after an operator: For non-block objects: For the "a" commands: The operator applies to the object and the white @@ -671,6 +684,7 @@ For a block object: the surrounding braces are excluded. For the "a" commands, the braces are included. + *v_object-select* When used in Visual mode: When start and end of the Visual area are the same (just after typing "v"): One object is selected, the same as for using an operator. @@ -892,7 +906,7 @@ was made yet in the current file. for each opened file. Only one position is remembered per buffer, not one for each window. As long as the buffer is visible in - a window the position won't be changed. Mark is also + a window the position won't be changed. Mark is also reset when |:wshada| is run. *'^* *`^* @@ -1026,6 +1040,12 @@ CTRL-O Go to [count] Older cursor position in jump list CTRL-I Go to [count] newer cursor position in jump list (not a motion command). + NOTE: In the GUI and in a terminal supporting + |tui-modifyOtherKeys| or |tui-csiu|, CTRL-I can be + mapped separately from <Tab>, on the condition that + both keys are mapped, otherwise the mapping applies to + both. + *:ju* *:jumps* :ju[mps] Print the jump list (not a motion command). @@ -1038,14 +1058,14 @@ can go to cursor positions before older jumps, and back again. Thus you can move up and down the list. There is a separate jump list for each window. The maximum number of entries is fixed at 100. -For example, after three jump commands you have this jump list: - - jump line col file/text ~ - 3 1 0 some text ~ - 2 70 0 another line ~ - 1 1154 23 end. ~ - > ~ +For example, after three jump commands you have this jump list: > + jump line col file/text + 3 1 0 some text + 2 70 0 another line + 1 1154 23 end. + > +< The "file/text" column shows the file name, or the text at the jump if it is in the current file (an indent is removed and a long line is truncated to fit in the window). @@ -1054,14 +1074,14 @@ The marker ">" indicates the current position in the jumplist. It may not be shown when filtering the |:jumps| command using |:filter| You are currently in line 1167. If you then use the CTRL-O command, the -cursor is put in line 1154. This results in: - - jump line col file/text ~ - 2 1 0 some text ~ - 1 70 0 another line ~ - > 0 1154 23 end. ~ - 1 1167 0 foo bar ~ +cursor is put in line 1154. This results in: > + jump line col file/text + 2 1 0 some text + 1 70 0 another line + > 0 1154 23 end. + 1 1167 0 foo bar +< The pointer will be set at the last used jump position. The next CTRL-O command will use the entry above it, the next CTRL-I command will use the entry below it. If the pointer is below the last entry, this indicates that @@ -1085,15 +1105,15 @@ command. You can explicitly add a jump by setting the ' mark with "m'". Note that calling setpos() does not do this. After the CTRL-O command that got you into line 1154 you could give another -jump command (e.g., "G"). The jump list would then become: - - jump line col file/text ~ - 4 1 0 some text ~ - 3 70 0 another line ~ - 2 1167 0 foo bar ~ - 1 1154 23 end. ~ - > ~ - +jump command (e.g., "G"). The jump list would then become: > + + jump line col file/text + 4 1 0 some text + 3 70 0 another line + 2 1167 0 foo bar + 1 1154 23 end. + > +< The line numbers will be adjusted for deleted and inserted lines. This fails if you stop editing a file without writing, like with ":n!". @@ -1103,60 +1123,44 @@ If you have included the ' item in the 'shada' option the jumplist will be stored in the ShaDa file and restored when starting Vim. *jumplist-stack* -When jumpoptions includes "stack", the jumplist behaves like the history in a -web browser and like the tag stack. When jumping to a new location from the -middle of the jumplist, the locations after the current position will be -discarded. - -This behavior corresponds to the following situation in a web browser. -Navigate to first.com, second.com, third.com, fourth.com and then fifth.com. -Then navigate backwards twice so that third.com is displayed. At that point, -the history is: -- first.com -- second.com -- third.com <-- -- fourth.com -- fifth.com - -Finally, navigate to a different webpage, new.com. The history is -- first.com -- second.com -- third.com -- new.com <-- - -When the jumpoptions includes "stack", this is the behavior of Nvim as well. -That is, given a jumplist like the following in which CTRL-O has been used to -move back three times to location X - - jump line col file/text - 2 1260 8 src/nvim/mark.c <-- location X-2 - 1 685 0 src/nvim/option_defs.h <-- location X-1 -> 0 462 36 src/nvim/option_defs.h <-- location X - 1 479 39 src/nvim/option_defs.h - 2 213 2 src/nvim/mark.c - 3 181 0 src/nvim/mark.c - +When 'jumpoptions' option includes "stack", the jumplist behaves like the tag +stack. When jumping to a new location from the middle of the jumplist, the +locations after the current position will be discarded. With this option set +you can move through a tree of jump locations. When going back up a branch and +then down another branch, CTRL-O still takes you further up the tree. + +Given a jumplist like the following in which CTRL-O has been used to move back +three times to location X: > + + jump line col file/text + 2 1260 8 mark.c <-- location X-2 + 1 685 0 eval.c <-- location X-1 + > 0 462 36 eval.c <-- location X + 1 479 39 eval.c + 2 213 2 mark.c + 3 181 0 mark.c +< jumping to (new) location Y results in the locations after the current -locations being removed: - - jump line col file/text - 3 1260 8 src/nvim/mark.c - 2 685 0 src/nvim/option_defs.h - 1 462 36 src/nvim/option_defs.h <-- location X -> +locations being removed: > + jump line col file/text + 3 1260 8 mark.c <-- location X-2 + 2 685 0 eval.c <-- location X-1 + 1 462 36 eval.c <-- location X + > +< Then, when yet another location Z is jumped to, the new location Y appears directly after location X in the jumplist and location X remains in the same -position relative to the locations (X-1, X-2, etc., ...) that had been before it -prior to the original jump from X to Y: - - jump line col file/text - 4 1260 8 src/nvim/mark.c <-- location X-2 - 3 685 0 src/nvim/option_defs.h <-- location X-1 - 2 462 36 src/nvim/option_defs.h <-- location X - 1 100 0 src/nvim/option_defs.h <-- location Y -> - +position relative to the locations (X-1, X-2, etc., ...) that had been before +it prior to the original jump from X to Y: > + + jump line col file/text + 4 1260 8 mark.c <-- location X-2 + 3 685 0 eval.c <-- location X-1 + 2 462 36 eval.c <-- location X + 1 100 0 buffer.c <-- location Y + > +< CHANGE LIST JUMPS *changelist* *change-list-jumps* *E664* When making a change the cursor position is remembered. One position is @@ -1230,7 +1234,7 @@ remembered. ([{}]) parenthesis or (curly/square) brackets (this can be changed with the 'matchpairs' option) - /* */ start or end of C-style comment + `/* */` start or end of C-style comment #if, #ifdef, #else, #elif, #endif C preprocessor conditionals (when the cursor is on the # or no ([{ @@ -1279,9 +1283,9 @@ remembered. |exclusive| motion. The above four commands can be used to go to the start or end of the current -code block. It is like doing "%" on the '(', ')', '{' or '}' at the other +code block. It is like doing "%" on the "(", ")", "{" or "}" at the other end of the code block, but you can do this from anywhere in the code block. -Very useful for C programs. Example: When standing on "case x:", "[{" will +Very useful for C programs. Example: When standing on "case x:", `[{` will bring you back to the switch statement. *]m* diff --git a/runtime/doc/news-0.9.txt b/runtime/doc/news-0.9.txt new file mode 100644 index 0000000000..789bc9e0bc --- /dev/null +++ b/runtime/doc/news-0.9.txt @@ -0,0 +1,323 @@ +*news-0.9.txt* Nvim + + + NVIM REFERENCE MANUAL + + +Notable changes in Nvim 0.9 from 0.8 *news-0.9* + + Type |gO| to see the table of contents. + +============================================================================== +BREAKING CHANGES + +The following changes may require adaptations in user config or plugins. + +• Cscope support is now removed (see |cscope| and |nvim-removed|): + - Commands removed: + - `:cscope` + - `:lcscope` + - `:scscope` + - `:cstag` + - Options removed: + - `cscopepathcomp` + - `cscopeprg` + - `cscopequickfix` + - `cscoperelative` + - `cscopetag` + - `cscopetagorder` + - `cscopeverbose` + - Eval functions removed: + - `cscope_connection()` + + Note: support for |ctags| remains with no plans to remove. + + See https://github.com/neovim/neovim/pull/20545 for more information. + +• `:hardcopy` is now removed (see |hardcopy| and |nvim-removed|): + - Commands removed: + - `:hardcopy` + - Options removed: + - `printdevice` + - `printencoding` + - `printexpr` + - `printfont` + - `printheader` + - `printmbcharset` + +• 'paste' option is now deprecated and 'pastetoggle' is removed. |paste| works + automatically in GUI and terminal (TUI) Nvim. Just Paste It.™ + +• Changes to |vim.treesitter.get_node_text()|: + - It now returns `string`, as opposed to `string|string[]|nil`. + - The `concat` option has been removed as it was not consistently applied. + - Invalid ranges now cause an error instead of returning `nil`. + +• `help` treesitter parser was renamed to `vimdoc`. The only user-visible + change is that language-specific highlight groups need to be renamed from + `@foo.help` to `@foo.vimdoc`. + +• The default value of 'commentstring' is now empty instead of "/*%s*/". + +• libiconv and intl are now required build dependencies. + +============================================================================== +NEW FEATURES + +The following new APIs or features were added. + +• Treesitter syntax highlighting for `help` files now supports highlighted + code examples. To enable, create a `.config/nvim/ftplugin/help.lua` with + the contents >lua + vim.treesitter.start() +< + Note: Highlighted code examples are only available in the Nvim manual, not + in help files taken from Vim. The treesitter `vimdoc` parser is also work in + progress and not guaranteed to correctly highlight every help file in the + wild. + +• Added support for semantic token highlighting to the LSP client. This + functionality is enabled by default when a client that supports this feature + is attached to a buffer. Opt-out can be performed by deleting the + `semanticTokensProvider` from the LSP client's {server_capabilities} in the + `LspAttach` callback. + + See |lsp-semantic-highlight| for more information. + +• |vim.inspect_pos()|, |vim.show_pos()| and |:Inspect| allow a user to get or show items + at a given buffer position. Currently this includes treesitter captures, + LSP semantic tokens, syntax groups and extmarks. + +• |vim.treesitter.inspect_tree()| and |:InspectTree| opens a split window + showing a text representation of the nodes in a language tree for the current + buffer. + +• |'statuscolumn'| option to customize the area to the side of a window, + normally containing the fold, sign and number columns. This new option follows + the 'statusline' syntax and can be used to transform the line numbers, create + mouse click callbacks for |signs|, introduce a custom margin or separator etc. + +• |vim.secure.trust()|, |:trust| allows the user to manage files in trust database. + |vim.secure.read()| reads a file and prompts the user if it should be + trusted and, if so, returns the file's contents. Used by 'exrc' + +• EditorConfig support is now builtin. This is enabled by default and happens + automatically. To disable it, users should add >lua + + vim.g.editorconfig = false +< + (or the Vimscript equivalent) to their |config| file. + +• A new environment variable named NVIM_APPNAME enables configuring the + directories where Nvim should find its configuration and state files. See + `:help $NVIM_APPNAME` . + +• Added support for running Lua scripts from shell using |-l|. > + nvim -l foo.lua --arg1 --arg2 +< Also works with stdin: > + echo "print(42)" | nvim -l - + +• Added an omnifunc implementation for Lua, |vim.lua_omnifunc()| + +• Added a new experimental |vim.loader| that byte-compiles and caches Lua files. + To enable the new loader, add the following at the top of your |init.lua|: >lua + vim.loader.enable() + +• Added |vim.version| for parsing and comparing version strings conforming to + the semver specification. + +• When using Nvim inside tmux 3.2 or later, the default clipboard provider + will now copy to the system clipboard. |provider-clipboard| + +• |'showcmdloc'| option to display the 'showcmd' information in the + status line or tab line. A new %S statusline item is available to place + the 'showcmd' text in a custom 'statusline'. Useful for when |'cmdheight'| + is set to 0. + +• |'splitkeep'| option to control the scroll behavior of horizontal splits. + +• |'diffopt'| now includes a `linematch` option to enable a second-stage diff + on individual hunks to provide much more accurate diffs. This option is also + available to |vim.diff()| + + See https://github.com/neovim/neovim/pull/14537. + +• |--remote-ui| option was added to connect to a remote instance and display + in it in a |TUI| in the local terminal. This can be used run a headless nvim + instance in the background and display its UI on demand, which previously + only was possible using an external UI implementation. + +• Added a |vim.lsp.codelens.clear()| function to clear codelenses. + +• Added support for the `willSave` and `willSaveWaitUntil` capabilities to the + LSP client. `willSaveWaitUntil` allows a server to modify a document before it + gets saved. Example use-cases by language servers include removing unused + imports, or formatting the file. + +• Added preliminary support for the `workspace/didChangeWatchedFiles` capability + to the LSP client to notify servers of file changes on disk. The feature is + disabled by default and can be enabled by setting the + `workspace.didChangeWatchedFiles.dynamicRegistration=true` capability. + +• |vim.diagnostic| now supports LSP DiagnosticsTag. + See: https://microsoft.github.io/language-server-protocol/specification/#diagnosticTag + +• |vim.diagnostic.is_disabled()| checks if diagnostics are disabled in a given + buffer or namespace. + +• Treesitter captures can now be transformed by directives. This will allow + more complicated dynamic language injections. + +• |vim.treesitter.get_node_text()| now accepts a `metadata` option for + writing custom directives using |vim.treesitter.query.add_directive()|. + +• |vim.treesitter.language.add()| replaces `vim.treesitter.language.require_language`. + +• |vim.treesitter.foldexpr()| can be used for 'foldexpr' to use treesitter for folding. + +• Expanded the TSNode API with: + - |TSNode:tree()| + - |TSNode:has_changes()| + - |TSNode:extra()| + - |TSNode:equal()| + + Additionally |TSNode:range()| now takes an optional {include_bytes} argument. + +• Treesitter injection queries now use the format described at + https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection . + Support for the previous format will be removed in a future release. + +• Added |nvim_get_hl()| for getting highlight group definitions in a format + compatible with |nvim_set_hl()|. + +• |vim.filetype.get_option()| to get the default option value for a specific + filetype. This is a wrapper around |nvim_get_option_value()| with caching. + +• `require'bit'` is now always available |lua-bit| + +============================================================================== +CHANGED FEATURES + +The following changes to existing APIs or features add new behavior. + +• 'exrc' now supports `.nvim.lua` file. +• 'exrc' is no longer marked deprecated. + +• The |TUI| is changed to run in a separate process (previously, a separate + thread was used). This is not supposed to be a visible change to the user, + but might be the cause of subtle changes of behavior and bugs. + + Previously, the TUI could be disabled as a build time feature (+tui/-tui), + resulting in a nvim binary which only could be run headless or embedded + in an external process. As of this version, TUI is always available. + +• Vim's `has('gui_running')` is now supported as a way for plugins to check if + a GUI (not the |TUI|) is attached to Nvim. |has()| + +• |msgsep| is now always enabled even if 'display' doesn't contain the "msgsep" + flag. It is no longer possible to scroll the whole screen when showing + messages longer than 'cmdheight'. + +• API calls now show more information about where an exception happened. + +• The `win_viewport` UI event now contains information about virtual lines, + meaning that smooth scrolling can now be implemented more consistently. + +• The `:= {expr}` syntax can be used to evaluate a Lua expression, as + a shorter form of `:lua ={expr}`. `:=` and `:[range]=` without argument + are unchanged. However `:=#` and similar variants using |ex-flags| + are no longer supported. + +• Unsaved changes are now preserved rather than discarded when |channel-stdio| + is closed. + +• |nvim_open_win()| now accepts a relative `mouse` option to open a floating win + relative to the mouse. Note that the mouse doesn't update frequently without + setting `vim.o.mousemoveevent = true` + +• |nvim_eval_statusline()| supports evaluating the |'statuscolumn'| through a + new `opts` field: `use_statuscol_lnum`. + +• |nvim_buf_get_extmarks()| now accepts a -1 `ns_id` to request extmarks from + all namespaces and adds the namespace id to the details array. + Other missing properties have been added to the details array and marks can + be filtered by type. + +• |vim.diagnostic.open_float()| (and therefore |vim.diagnostic.config()|) now + accepts a `suffix` option which, by default, renders LSP error codes. + Similarly, the `virtual_text` configuration in |vim.diagnostic.config()| now + has a `suffix` option which does nothing by default. + +• |vim.fs.dir()| now has a `opts` argument with a depth field to allow + recursively searching a directory tree. + +• |vim.gsplit()| supports all features of |vim.split()|. + +• |:highlight| now supports an additional attribute "altfont". + +• |:Man| manpage viewer supports manpage names containing spaces. + +• |nvim_select_popupmenu_item()| now supports |cmdline-completion| popup menu. + +• |nvim_list_uis()| reports all |ui-option| fields. + +• |nvim_get_option_value()| now has a `filetype` option so it can return the + default option for a specific filetype. + +• build: Several improvements were made to make the code generation scripts more + deterministic, and a `LUA_GEN_PRG` build parameter has been introduced to + allow for a workaround for some remaining reproducibility problems. + +============================================================================== +REMOVED FEATURES + +The following deprecated functions or APIs were removed. + +• `filetype.vim` is removed in favor of |vim.filetype| + (Note that filetype logic and tests still align with Vim, so additions or + changes need to be contributed there first.) + See https://github.com/neovim/neovim/pull/20674. + +• 'hkmap', 'hkmapp' and 'aleph' options were removed. Use 'keymap' option instead. + +• |LanguageTree:parse()| no longer returns changed regions. Please use the + `on_changedtree` callbacks instead. + +• `vim.highlight.create()`, `vim.highlight.link()` were removed, use |nvim_set_hl()| instead. + +• `require'health'` was removed. Use |vim.health| instead. + +============================================================================== +DEPRECATIONS + +The following functions are now deprecated and will be removed in the next +release. + +• |vim.treesitter.language.add()| replaces `vim.treesitter.language.require_language()` + +• |vim.treesitter.get_node_at_pos()| and |vim.treesitter.get_node_at_cursor()| + are both deprecated in favor of |vim.treesitter.get_node()|. + +• `vim.api.nvim_get_hl_by_name()`, `vim.api.nvim_get_hl_by_id()` were deprecated, use |nvim_get_hl()| instead. + +• The following top level Treesitter functions have been moved: + `vim.treesitter.inspect_language()` -> `vim.treesitter.language.inspect()` + `vim.treesitter.get_query_files()` -> `vim.treesitter.query.get_files()` + `vim.treesitter.set_query()` -> `vim.treesitter.query.set()` + `vim.treesitter.query.set_query()` -> `vim.treesitter.query.set()` + `vim.treesitter.get_query()` -> `vim.treesitter.query.get()` + `vim.treesitter.query.get_query()` -> `vim.treesitter.query.get()` + `vim.treesitter.parse_query()` -> `vim.treesitter.query.parse()` + `vim.treesitter.query.parse_query()` -> `vim.treesitter.query.parse()` + `vim.treesitter.add_predicate()` -> `vim.treesitter.query.add_predicate()` + `vim.treesitter.add_directive()` -> `vim.treesitter.query.add_directive()` + `vim.treesitter.list_predicates()` -> `vim.treesitter.query.list_predicates()` + `vim.treesitter.list_directives()` -> `vim.treesitter.query.list_directives()` + `vim.treesitter.query.get_range()` -> `vim.treesitter.get_range()` + `vim.treesitter.query.get_node_text()` -> `vim.treesitter.get_node_text()` + +• |nvim_exec()| is now deprecated in favor of |nvim_exec2()|. + +• Renamed |vim.pretty_print()| to |vim.print()|. + + vim:tw=78:ts=8:sw=2:et:ft=help:norl: diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 5c234677ef..825e5ba41f 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -1,10 +1,12 @@ *news.txt* Nvim - NVIM REFERENCE MANUAL + NVIM REFERENCE MANUAL -Notable changes in Nvim 0.9 from 0.8 *news* +Notable changes in Nvim 0.10 from 0.9 *news* + +For changes in Nvim 0.9, see |news-0.9|. Type |gO| to see the table of contents. @@ -13,182 +15,373 @@ BREAKING CHANGES *news-breaking* The following changes may require adaptations in user config or plugins. -• Cscope support is now removed (see |cscope| and |nvim-features-removed|): - - Commands removed: - - `:cscope` - - `:lcscope` - - `:scscope` - - `:cstag` - - Options removed: - - `cscopepathcomp` - - `cscopeprg` - - `cscopequickfix` - - `cscoperelative` - - `cscopetag` - - `cscopetagorder` - - `cscopeverbose` - - Eval functions removed: - - `cscope_connection()` - - Note: support for |ctags| remains with no plans to remove. - - See https://github.com/neovim/neovim/pull/20545 for more information. - -• `:hardcopy` is now removed (see |hardcopy| and |nvim-features-removed|): - - Commands removed: - - `:hardcopy` - - Options removed: - - `printdevice` - - `printencoding` - - `printexpr` - - `printfont` - - `printheader` - - `printmbcharset` - -• libiconv is now a required build dependency. +• In some cases, the cursor in the Nvim |TUI| would blink even without + configuring 'guicursor' as mentioned in |cursor-blinking|. This was a bug + that has now been fixed. If your cursor has stopped blinking, add the + following (or similar, adapted to user preference) to your |config| file: >vim + + set guicursor+=n-v-c:blinkon500-blinkoff500 +< +• |vim.tbl_islist()| now checks whether a table is actually list-like (i.e., + has integer keys without gaps and starting from 1). For the previous + behavior (only check for integer keys, allow gaps or not starting with 1), + use |vim.tbl_isarray()|. + +• "#" followed by a digit no longer stands for a function key at the start of + the lhs of a mapping. + +• `:behave` was removed. + - If you used `:behave xterm`, the following is equivalent: >vim + + set mousemodel=extend +< + - If you used `:behave mswin`, the following is equivalent: >vim + + set selection=exclusive + set selectmode=mouse,key + set mousemodel=popup + set keymodel=startsel,stopsel +< +• When switching windows, |CursorMoved| autocommands trigger when Nvim is back + in the main loop rather than immediately. This is more compatible with Vim. + +• |-l| ensures output ends with a newline if the script prints messages and + doesn't cause Nvim to exit. + +• |LspRequest| and LspProgressUpdate (renamed to |LspProgress|) autocmds were + promoted from a |User| autocmd to first class citizen. + +• Renamed `vim.treesitter.playground` to `vim.treesitter.dev`. + +• Removed functions from the |vim.json| module: + • Unnecessary, undocumented functions which caused global side-effects. + • `vim.json.null` is redundant with `vim.NIL`. + • `vim.json.array_mt` (and related) is redundant with `vim.empty_dict()`. + +• Removed some Vim 5.0<= option compatibilities: + • |'backspace'| no longer supports number values. Instead: + • for `backspace=0` set `backspace=` (empty) + • for `backspace=1` set `backspace=indent,eol` + • for `backspace=2` set `backspace=indent,eol,start` (default behavior in Nvim) + • for `backspace=3` set `backspace=indent,eol,nostop` + • |'backupdir'| and |'directory'| will no longer remove a `>` at the start + of the option. + +• |LanguageTree:parse()| will no longer parse injections by default and + now requires an explicit range argument to be passed. If injections are + required, provide an explicit range via `parser:parse({ start_row, end_row })`. + +• Float window support hide and show by setting `hide` on `nvim_open_win` and + `nvim_win_set_config`. + +• |vim.lsp.util.parse_snippet()| will now strictly follow the snippet grammar + defined by LSP, and hence previously parsed snippets might now be considered + invalid input. + +• |OptionSet| autocommand args |v:option_new|, |v:option_old|, + |v:option_oldlocal|, |v:option_oldglobal| now have the type of the option + instead of always being strings. |v:option_old| is now the old global value + for all global-local options, instead of just string global-local options. + +• Local value for a global-local number/boolean option is now unset when + the option is set (e.g. using |:set| or |nvim_set_option_value()|) without a + scope, which means they now behave the same way as string options. + +• Signs placed through the legacy |sign-commands| are now stored and displayed + as |extmarks| internally. Along with the following changes: + • A sign placed twice in the same group with the same identifier will be moved. + • Legacy signs are always deleted along with the line it is placed on. + • Legacy and extmark signs will show up in both |:sign-place-list| and |nvim_buf_get_extmarks()|. + • Legacy and extmark signs are displayed and listed with the same priority: + line number -> priority -> sign id -> recently placed + +============================================================================== +BREAKING CHANGES IN HEAD *news-breaking-dev* + +The following breaking changes were made during the development cycle to +unreleased features on Nvim HEAD. + +• ... +• ... ============================================================================== NEW FEATURES *news-features* -The following new APIs or features were added. +The following new APIs and features were added. + +• Performance: + • 'diffopt' "linematch" scoring algorithm now favours larger and less groups + https://github.com/neovim/neovim/pull/23611 + • Treesitter highlighting now parses injections incrementally during + screen redraws only for the line range being rendered. This significantly + improves performance in large files with many injections. + +• |vim.iter()| provides a generic iterator interface for tables and Lua + iterators |for-in|. + +• Added |vim.ringbuf()| to create ring buffers. -• |nvim_open_win()| now accepts a relative `mouse` option to open a floating win - relative to the mouse. Note that the mouse doesn't update frequently without - setting `vim.o.mousemoveevent = true` +• Added |vim.keycode()| for translating keycodes in a string. -• EditorConfig support is now builtin. This is enabled by default and happens - automatically. To disable it, users should add >lua +• |'smoothscroll'| option to scroll by screen line rather than by text line + when |'wrap'| is set. - vim.g.editorconfig = false -< - (or the Vimscript equivalent) to their |config| file. +• Added inline virtual text support to |nvim_buf_set_extmark()|. -• Run Lua scripts from your shell using |-l|. > - nvim -l foo.lua --arg1 --arg2 -< Also works with stdin: > - echo "print(42)" | nvim -l - +• 'foldtext' now supports virtual text format. |fold-foldtext| -• Added a |vim.lsp.codelens.clear()| function to clear codelenses. +• The terminal buffer now supports reflow (wrapped lines adapt when the buffer + is resized horizontally). Note: Lines that are not visible and kept in + |'scrollback'| are not reflown. -• |vim.inspect_pos()|, |vim.show_pos()| and |:Inspect| allow a user to get or show items - at a given buffer position. Currently this includes treesitter captures, - semantic tokens, syntax groups and extmarks. +• |vim.system()| for running system commands. -• Added support for semantic token highlighting to the LSP client. This - functionality is enabled by default when a client that supports this feature - is attached to a buffer. Opt-out can be performed by deleting the - `semanticTokensProvider` from the LSP client's {server_capabilities} in the - `LspAttach` callback. +• Added |nvim_win_text_height()| to compute the number of screen lines occupied + by a range of text in a given window. - See |lsp-semantic_tokens| for more information. +• |nvim_set_keymap()| and |nvim_del_keymap()| now support abbreviations. -• |vim.treesitter.show_tree()| opens a split window showing a text - representation of the nodes in a language tree for the current buffer. +• Better cmdline completion for string option value. |complete-set-option| -• Added support for the `willSave` and `willSaveWaitUntil` capabilities to the - LSP client. `willSaveWaitUntil` allows a server to modify a document before it - gets saved. Example use-cases by language servers include removing unused - imports, or formatting the file. +• Builtin TUI can now recognize "super" (|<D-|) and "meta" (|<T-|) modifiers in a + terminal emulator that supports |tui-csiu|. -• Treesitter syntax highlighting for `help` files now supports highlighted - code examples. To enable, create a `.config/nvim/ftplugin/help.lua` with - the contents >lua - vim.treesitter.start() -< - Note: Highlighted code examples are only available in the Nvim manual, not - in help files taken from Vim. The treesitter `help` parser is also work in - progress and not guaranteed to correctly highlight every help file in the - wild. +• Editor + • By default, the swapfile "ATTENTION" |E325| dialog is skipped if the + swapfile is owned by a running Nvim process, instead of prompting. If you + always want the swapfile dialog, delete the default SwapExists handler: + `autocmd! nvim_swapfile`. |default-autocmds| + +• LSP + • LSP method names are available in |vim.lsp.protocol.Methods|. + • Implemented LSP inlay hints: |lsp-inlay_hint| + https://microsoft.github.io/language-server-protocol/specification/#textDocument_inlayHint + • Implemented pull diagnostic textDocument/diagnostic: |vim.lsp.diagnostic.on_diagnostic()| + https://microsoft.github.io/language-server-protocol/specification/#textDocument_diagnostic + • Added |vim.lsp.status()| to consume the last progress messages as a string. + • LSP client now always saves and restores named buffer marks when applying + text edits. + • LSP client now supports the `positionEncoding` server capability. If a server + responds with the `positionEncoding` capability in its initialization + response, Nvim automatically sets the client's `offset_encoding` field. + • Dynamic registration of LSP capabilities. An implication of this change is + that checking a client's `server_capabilities` is no longer a sufficient + indicator to see if a server supports a feature. Instead use + `client.supports_method(<method>)`. It considers both the dynamic + capabilities and static `server_capabilities`. + • Added a new `anchor_bias` option to |lsp-handlers| to aid in positioning of + floating windows. + +• Treesitter + • Bundled parsers and queries (highlight, folds) for Markdown, Python, and + Bash. + • Added |vim.treesitter.query.omnifunc()| for treesitter query files (set by + default). + • |Query:iter_matches()| now has the ability to set the maximum start depth + for matches. + • `@injection.language` now has smarter resolution and will now fallback to language aliases and/or attempt lower case variants of the text. + language via aliases (e.g., filetype) registered via + `vim.treesitter.language.register`. + • The `#set!` directive now supports `injection.self` and `injection.parent` for injecting either the current node's language + or the parent LanguageTree's language, respectively. + • Added `vim.treesitter.query.edit()`, for live editing of treesitter + queries. + • Improved error messages for query parsing. + • Added |vim.treesitter.foldtext()| to apply treesitter highlighting to + foldtext. + +• |vim.ui.open()| opens URIs using the system default handler (macOS `open`, + Windows `explorer`, Linux `xdg-open`, etc.) + +• |vim.wo| can now be double indexed for |:setlocal| behaviour. Currently only + `0` for the buffer index is currently supported. -• |vim.secure.trust()|, |:trust| allows the user to manage files in trust - database. +• Lua type annotations for: + • `vim.*` + • `vim.fn.*` + • `vim.api.*` -• |vim.diagnostic.open_float()| (and therefore |vim.diagnostic.config()|) now - accepts a `suffix` option which, by default, renders LSP error codes. - Similarly, the `virtual_text` configuration in |vim.diagnostic.config()| now - has a `suffix` option which does nothing by default. +• Improved messages for type errors in `vim.api.*` calls (including `opts` params) -• |vim.fs.dir()| now has a `opts` argument with a depth field to allow - recursively searching a directory tree. +• Functions that take a severity as an optional parameter (e.g. + |vim.diagnostic.get()|) now also accept a list of severities |vim.diagnostic.severity| -• |vim.secure.read()| reads a file and prompts the user if it should be - trusted and, if so, returns the file's contents. +• New RPC client type `msgpack-rpc` is added for `nvim_set_client_info` to + support fully MessagePack-RPC compliant clients. -• When using Nvim inside tmux 3.2 or later, the default clipboard provider - will now copy to the system clipboard. |provider-clipboard| +• Floating windows can now show footer with new `footer` and `footer_pos` + config fields. Uses |hl-FloatFooter| by default. -• |'showcmdloc'| option to display the 'showcmd' information in the - status line or tab line. A new %S statusline item is available to place - the 'showcmd' text in a custom 'statusline'. Useful for when |'cmdheight'| - is set to 0. +• The |:terminal| command now accepts some |:command-modifiers| (specifically + |:horizontal| and those that affect splitting a window). -• |'splitkeep'| option to control the scroll behavior of horizontal splits. +• |vim.lsp.util.locations_to_items()| sets the `user_data` of each item to the + original LSP `Location` or `LocationLink`. -• |'statuscolumn'| option to customize the area to the side of a window, - normally containing the fold, sign and number columns. This new option follows - the 'statusline' syntax and can be used to transform the line numbers, create - mouse click callbacks for |signs|, introduce a custom margin or separator etc. +• |$NVIM_APPNAME| can be set to a relative path instead of only a name. -• |nvim_select_popupmenu_item()| now supports |cmdline-completion| popup menu. +• Added |:fclose| command. -• |'diffopt'| now includes a `linematch` option to enable a second-stage diff - on individual hunks to provide much more accurate diffs. This option is also - available to |vim.diff()| +• Added |vim.snippet| for snippet expansion support. - See https://github.com/neovim/neovim/pull/14537. +• 'complete' option supports "f" flag for completing buffer names. -• |vim.diagnostic.is_disabled()| checks if diagnostics are disabled in a given - buffer or namespace. +• Added |vim.base64.encode()| and |vim.base64.decode()| for encoding and decoding + strings using Base64 encoding. -• |--remote-ui| option was added to connect to a remote instance and display - in it in a |TUI| in the local terminal. This can be used run a headless nvim - instance in the background and display its UI on demand, which previously - only was possible using an external UI implementation. +• The |TermResponse| autocommand event can be used with |v:termresponse| to + read escape sequence responses from the terminal. -• Several improvements were made to make the code generation scripts more - deterministic, and a `LUA_GEN_PRG` build parameter has been introduced to - allow for a workaround for some remaining reproducibility problems. +• A clipboard provider which uses OSC 52 to copy the selection to the system + clipboard is now bundled by default and will be automatically enabled under + certain conditions. |clipboard-osc52| -• |:highlight| now supports an additional attribute "altfont". +• The 'termsync' option asks the terminal emulator to buffer screen updates + until the redraw cycle is complete. Requires support from the terminal. + +• Added |vim.text.hexencode()| and |vim.text.hexdecode()| to convert strings + to and from byte representations. ============================================================================== -CHANGED FEATURES *news-changes* +CHANGED FEATURES *news-changed* The following changes to existing APIs or features add new behavior. -• 'exrc' now supports `.nvim.lua` file. -• 'exrc' is no longer marked deprecated. +• |vim.tbl_contains()| now works for general tables and allows specifying a + predicate function that is checked for each value. (Use |vim.list_contains()| + for checking list-like tables (integer keys without gaps) for literal values.) -• The |TUI| is changed to run in a separate process (previously, a separate - thread was used). This is not supposed to be a visible change to the user, - but might be the cause of subtle changes of behavior and bugs. +• |vim.region()| can use a string accepted by |getpos()| as position. - Previously, the TUI could be disabled as a build time feature (+tui/-tui), - resulting in a nvim binary which only could be run headless or embedded - in an external process. As of this version, TUI is always available. +• vim.diagnostic.config() now accepts a function for the virtual_text.prefix + option, which allows for rendering e.g., diagnostic severities differently. -• API calls now show more information about where an exception happened. +• Defaults: + • On Windows 'isfname' does not include ":". Drive letters are handled + correctly without it. (Use |gF| for filepaths suffixed with ":line:col"). + • 'comments' includes "fb:•". + • 'shortmess' includes the "C" flag. + • Automatic linting of treesitter query files (see |ft-query-plugin|). + Can be disabled via: >lua + vim.g.query_lint_on = {} +< + • Enabled treesitter highlighting for treesitter query files. + +• The `workspace/didChangeWatchedFiles` LSP client capability is now enabled + by default. + +• |LspRequest| autocmd callbacks now contain additional information about the LSP + request status update that occurred. + +• `:source` without arguments treats a buffer with its 'filetype' set to "lua" + as Lua code regardless of its extension. + +• |:checkhealth| buffer now implements |folding|. The initial folding status is + defined by the 'foldenable' option. + +• |:Man| now respects 'wrapmargin' + +• |gx| now uses |vim.ui.open()| and not netrw. To customize, you can redefine + `vim.ui.open` or remap `gx`. To continue using netrw (deprecated): >vim + :call netrw#BrowseX(expand(exists("g:netrw_gx")? g:netrw_gx : '<cfile>'), netrw#CheckIfRemote())<CR> + +• |vim.lsp.start()| now maps |K| to use |vim.lsp.buf.hover()| if the server + supports it, unless |'keywordprg'| was customized before calling + |vim.lsp.start()|. + +• Terminal buffers started with no arguments (and use 'shell') close + automatically if the job exited without error, eliminating the (often + unwanted) "[Process exited 0]" message. + +• |vim.diagnostic.config()| now accepts virtual text relevant options to + |nvim_buf_set_extmark()| (e.g. "virt_text_pos" and "hl_mode") in its + "virtual_text" table, which gives users more control over how diagnostic + virtual text is displayed. + +• Extmarks now fully support multi-line ranges, and a single extmark can be + used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()| + API function already allowed you to define such ranges, but highlight regions + were not rendered consistently for a range that covers more than one line break. + This has now been fixed. Signs defined as part of a multi-line extmark also + apply to every line in the range, not just the first. + In addition, |nvim_buf_get_extmarks()| has gained an "overlap" option to + return such ranges even if they started before the specified position. + +• Extmarks can opt-out of precise undo tracking using the new "undo_restore" + flag to |nvim_buf_set_extmark()| + +• Extmarks can be automatically hidden or removed using the new "invalidate" + flag to |nvim_buf_set_extmark()| + +• LSP hover and signature help now use Treesitter for highlighting of Markdown + content. + Note that syntax highlighting of code examples requires a matching parser + and may be affected by custom queries. + +• Support for rendering multibyte characters using composing characters has been + enhanced. The maximum limit have been increased from 1+6 codepoints to + 31 bytes, which is guaranteed to fit all chars from before but often more. + + NOTE: the regexp engine still has a hard-coded limit of considering + 6 composing chars only. + +• |vim.wait()| is no longer allowed to be called in |api-fast|. ============================================================================== REMOVED FEATURES *news-removed* The following deprecated functions or APIs were removed. -• It is no longer possible to scroll the whole screen when showing messages - longer than 'cmdheight'. |msgsep| is now always enabled even if 'display' - doesn't contain the "msgsep" flag. +• Vimball support is removed. + - :Vimuntar command removed. -• `filetype.vim` is removed in favor of |lua-filetype| - (Note that filetype logic and tests still align with Vim, so additions or - changes need to be contributed there first.) - See https://github.com/neovim/neovim/pull/20674. +• Support for legacy treesitter injection queries is removed. + +• Removed 'shortmess' flags: + - |shm-f|. Always uses "(3 of 5)", never "(file 3 of 5)" + - |shm-i|. Always use "[noeol]". + - |shm-x|. Always use "[dos]", "[unix]" and "[mac]" + - |shm-n|. Always use "[New]". ============================================================================== DEPRECATIONS *news-deprecations* -The following functions are now deprecated and will be removed in the next +The following functions are now deprecated and will be removed in a future release. - +• Checkhealth functions: + - |health#report_error|, |vim.health.report_error()| Use |vim.health.error()| instead. + - |health#report_info|, |vim.health.report_info()| Use |vim.health.info()| instead. + - |health#report_ok|, |vim.health.report_ok()| Use |vim.health.ok()| instead. + - |health#report_start|, |vim.health.report_start()| Use |vim.health.start()| instead. + - |health#report_warn|, |vim.health.report_warn()| Use |vim.health.warn()| instead. + +• |API| functions: + - |nvim_buf_get_option()| Use |nvim_get_option_value()| instead. + - |nvim_buf_set_option()| Use |nvim_set_option_value()| instead. + - |nvim_get_option()| Use |nvim_get_option_value()| instead. + - |nvim_set_option()| Use |nvim_set_option_value()| instead. + - |nvim_win_get_option()| Use |nvim_get_option_value()| instead. + - |nvim_win_set_option()| Use |nvim_set_option_value()| instead. + +• vim.lsp functions: + - |vim.lsp.util.get_progress_messages()| Use |vim.lsp.status()| instead. + - |vim.lsp.get_active_clients()| Use |vim.lsp.get_clients()| instead. + - |vim.lsp.for_each_buffer_client()| Use |vim.lsp.get_clients()| instead. + - |vim.lsp.util.trim_empty_lines()| Use |vim.split()| with `trimempty` instead. + - |vim.lsp.util.try_trim_markdown_code_blocks()| + - |vim.lsp.util.set_lines()| + - |vim.lsp.util.extract_completion_items()| + - |vim.lsp.util.parse_snippet()| + - |vim.lsp.util.text_document_completion_list_to_complete_items()| + +• `vim.loop` has been renamed to `vim.uv`. + +• vim.treesitter.languagetree functions: + - |LanguageTree:for_each_child()| Use |LanguageTree:children()| (non-recursive) instead. + +• The "term_background" UI option |ui-ext-options| is deprecated and no longer + populated. Background color detection is now performed in Lua by the Nvim + core, not the TUI. vim:tw=78:ts=8:sw=2:et:ft=help:norl: diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt index 96f99528ed..dbc14f5a44 100644 --- a/runtime/doc/nvim_terminal_emulator.txt +++ b/runtime/doc/nvim_terminal_emulator.txt @@ -115,7 +115,7 @@ You can change the defaults with a TermOpen autocommand: >vim TERMINAL COLORS ~ The `{g,b}:terminal_color_x` variables control the terminal color palette, -where `x` is the color index between 0 and 255 inclusive. The variables are +where `x` is the color index between 0 and 15 inclusive. The variables are read during |TermOpen|. The value must be a color name or hexadecimal string. Example: >vim let g:terminal_color_4 = '#ff0000' @@ -239,7 +239,7 @@ gdb window and use a "print" command, e.g.: > print *eap If mouse pointer movements are working, Vim will also show a balloon when the mouse rests on text that can be evaluated by gdb. -You can also use the "K" mapping that will either use neovim floating windows +You can also use the "K" mapping that will either use Nvim floating windows if available to show the results or print below the status bar. Now go back to the source window and put the cursor on the first line after @@ -317,6 +317,18 @@ This is similar to using "print" in the gdb window. You can usually shorten `:Evaluate` to `:Ev`. +Navigating stack frames ~ + *termdebug-frames* *:Frame* *:Up* *:Down* + `:Frame` [frame] select frame [frame], which is a frame number, + address, or function name (default: current frame) + `:Up` [count] go up [count] frames (default: 1; the frame that + called the current) + `+` same (see |termdebug_map_plus| to disable) + `:Down` [count] go down [count] frames (default: 1; the frame called + by the current) + `-` same (see |termdebug_map_minus| to disable) + + Other commands ~ *termdebug-commands* *:Gdb* jump to the gdb window @@ -325,7 +337,9 @@ Other commands ~ isn't one *:Asm* jump to the window with the disassembly, create it if there isn't one - + *:Var* jump to the window with the local and argument variables, + create it if there isn't one. This window updates whenever the + program is stopped Events ~ *termdebug-events* @@ -385,20 +399,48 @@ Prompt mode can be used with: >vim If there is no g:termdebug_config you can use: >vim let g:termdebug_use_prompt = 1 < - *termdebug_map_K* -The K key is normally mapped to :Evaluate. If you do not want this use: >vim +Mappings ~ + *termdebug_map_K* *termdebug-mappings* +The K key is normally mapped to |:Evaluate| unless a buffer local (|:map-local|) +mapping to K already exists. If you do not want this use: >vim let g:termdebug_config['map_K'] = 0 If there is no g:termdebug_config you can use: >vim let g:termdebug_map_K = 0 < + *termdebug_map_minus* +The - key is normally mapped to |:Down| unless a buffer local mapping to the - +key already exists. If you do not want this use: >vim + let g:termdebug_config['map_minus'] = 0 +< + *termdebug_map_plus* +The + key is normally mapped to |:Up| unless a buffer local mapping to the + +key already exists. If you do not want this use: >vim + let g:termdebug_config['map_plus'] = 0 +< *termdebug_disasm_window* -If you want the Asm window shown by default, set the flag to 1. -the "disasm_window_height" entry can be used to set the window height: >vim +If you want the Asm window shown by default, set the "disasm_window" flag to +1. The "disasm_window_height" entry can be used to set the window height: >vim let g:termdebug_config['disasm_window'] = 1 let g:termdebug_config['disasm_window_height'] = 15 If there is no g:termdebug_config you can use: >vim let g:termdebug_disasm_window = 15 Any value greater than 1 will set the Asm window height to that value. +If the current window has enough horizontal space, it will be vertically split +and the Asm window will be shown side by side with the source code window (and +the height option won't be used). + + *termdebug_variables_window* +If you want the Var window shown by default, set the "variables_window" flag +to 1. The "variables_window_height" entry can be used to set the window +height: >vim + let g:termdebug_config['variables_window'] = 1 + let g:termdebug_config['variables_window_height'] = 15 +If there is no g:termdebug_config you can use: >vim + let g:termdebug_variables_window = 15 +Any value greater than 1 will set the Var window height to that value. +If the current window has enough horizontal space, it will be vertically split +and the Var window will be shown side by side with the source code window (and +the height options won't be used). Communication ~ *termdebug-communication* @@ -428,14 +470,14 @@ If the command needs an argument use a List: >vim If there is no g:termdebug_config you can use: >vim let g:termdebugger = ['rr', 'replay', '--'] -To not use neovim floating windows for previewing variable evaluation, set the +To not use Nvim floating windows for previewing variable evaluation, set the `g:termdebug_useFloatingHover` variable like this: >vim let g:termdebug_useFloatingHover = 0 If you are a mouse person, you can also define a mapping using your right click to one of the terminal command like evaluate the variable under the cursor: >vim - nnoremap <RightMouse> :Evaluate<CR> + nnoremap <RightMouse> :Evaluate<CR> or set/unset a breakpoint: >vim nnoremap <RightMouse> :Break<CR> @@ -451,7 +493,7 @@ The function will be called with the list of arguments so far, and a second argument that is the name of the pty. *gdb-version* Only debuggers fully compatible with gdb will work. Vim uses the GDB/MI -interface. The "new-ui" command requires gdb version 7.12 or later. if you +interface. The "new-ui" command requires gdb version 7.12 or later. If you get this error: Undefined command: "new-ui". Try "help".~ Then your gdb is too old. @@ -493,6 +535,20 @@ If there is no g:termdebug_config you can use: >vim let g:termdebug_popup = 0 +Change default signs ~ + *termdebug_signs* +Termdebug uses the hex number of the breakpoint ID in the signcolumn to +represent breakpoints. if it is greater than "0xFF", then it will be displayed +as "F+", due to we really only have two screen cells for the sign. + +If you want to customize the breakpoint signs: >vim + let g:termdebug_config['sign'] = '>>' +If there is no g:terminal_config yet you can use: >vim + let g:termdebug_config = {'sign': '>>'} + +After this, breakpoints will be displayed as `>>` in the signcolumn. + + Vim window width ~ *termdebug_wide* To change the width of the Vim window when debugging starts and use a vertical diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 2bdff2fbb2..c6fe18eb04 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -52,14 +52,16 @@ achieve special effects. These options come in three forms: 'lines' Warning: This may have a lot of side effects. - *:set-args* *E487* *E521* + *:set-args* *:set=* *E487* *E521* :se[t] {option}={value} or :se[t] {option}:{value} Set string or number option to {value}. For numeric options the value can be given in decimal, hex (preceded with 0x) or octal (preceded with '0'). The old value can be inserted by typing 'wildchar' (by - default this is a <Tab>). See |cmdline-completion|. + default this is a <Tab>). Many string options with + fixed syntax also support completing known values. + See |cmdline-completion| and |complete-set-option|. White space between {option} and '=' is allowed and will be ignored. White space between '=' and {value} is not allowed. @@ -93,6 +95,9 @@ achieve special effects. These options come in three forms: When the option is a list of flags, {value} must be exactly as they appear in the option. Remove flags one by one to avoid problems. + The individual values from a comma separated list or + list of flags can be inserted by typing 'wildchar'. + See |complete-set-option|. Also see |:set-args| above. The {option} arguments to ":set" may be repeated. For example: > @@ -131,10 +136,26 @@ To include white space in a string option value it has to be preceded with a backslash. To include a backslash you have to use two. Effectively this means that the number of backslashes in an option value is halved (rounded down). +In options 'path', 'cdpath', and 'tags', spaces have to be preceded with three +backslashes instead because they can be separated by either commas or spaces. +Comma-separated options like 'backupdir' and 'tags' will also require commas +to be escaped with two backslashes, whereas this is not needed for +non-comma-separated ones like 'makeprg'. +When setting options using |:let| and |literal-string|, you need to use one +fewer layer of backslash. A few examples: > - :set tags=tags\ /usr/tags results in "tags /usr/tags" - :set tags=tags\\,file results in "tags\,file" - :set tags=tags\\\ file results in "tags\ file" + :set makeprg=make\ file results in "make file" + :let &makeprg='make file' (same as above) + :set makeprg=make\\\ file results in "make\ file" + :set tags=tags\ /usr/tags results in "tags" and "/usr/tags" + :set tags=tags\\\ file results in "tags file" + :let &tags='tags\ file' (same as above) + + :set makeprg=make,file results in "make,file" + :set makeprg=make\\,file results in "make\,file" + :set tags=tags,file results in "tags" and "file" + :set tags=tags\\,file results in "tags,file" + :let &tags='tags\,file' (same as above) The "|" character separates a ":set" command from a following command. To include the "|" in the option value, use "\|" instead. This example sets the @@ -189,6 +210,8 @@ opt+=val" the expansion is done before the adding or removing. Handling of local options *local-options* +Note: The following also applies to |global-local| options. + Some of the options only apply to a window or buffer. Each window or buffer has its own copy of this option, thus each can have its own value. This allows you to set 'list' in one window but not in another. And set @@ -238,6 +261,30 @@ The options local to a window are remembered for each buffer. This also happens when the buffer is not loaded, but they are lost when the buffer is wiped out |:bwipe|. +Special local window options *local-noglobal* + +The following local window options won't be copied over when new windows are +created, thus they behave slightly differently: + + Option Reason ~ + 'previewwindow' there can only be a single one + 'scroll' specific to existing window + 'winfixheight' specific to existing window + 'winfixwidth' specific to existing window + +Special local buffer options + +The following local buffer options won't be copied over when new buffers are +created, thus they behave slightly differently: + + Option Reason ~ + 'filetype' explicitly set by autocommands + 'syntax' explicitly set by autocommands + 'bufhidden' denote |special-buffers| + 'buftype' denote |special-buffers| + 'readonly' will be detected automatically + 'modified' will be detected automatically + *:setl* *:setlocal* :setl[ocal][!] ... Like ":set" but set only the value local to the current buffer or window. Not all options have a @@ -311,7 +358,6 @@ used. Thus it does the same as: > Note: In the future more global options can be made |global-local|. Using ":setlocal" on a global option might work differently then. - *option-value-function* Some options ('completefunc', 'omnifunc', 'operatorfunc', 'quickfixtextfunc', 'tagfunc' and 'thesaurusfunc') are set to a function name or a function @@ -401,20 +447,15 @@ the system, mostly it is something like 256 or 1024 characters. ============================================================================== 2. Automatically setting options *auto-setting* -Besides changing options with the ":set" command, there are three alternatives -to set options automatically for one or more files: - -1. When starting Vim initializations are read from various places. See - |initialization|. Most of them are performed for all editing sessions, - and some of them depend on the directory where Vim is started. - You can create an initialization file with |:mkvimrc|, |:mkview| and - |:mksession|. -2. If you start editing a new file, the automatic commands are executed. - This can be used to set options for files matching a particular pattern and - many other things. See |autocommand|. -3. If you start editing a new file, and the 'modeline' option is on, a - number of lines at the beginning and end of the file are checked for - modelines. This is explained here. +Besides changing options with the ":set" command, you can set options +automatically in various ways: + +1. With a |config| file or a |startup| argument. You can create an + initialization file with |:mkvimrc|, |:mkview| and |:mksession|. +2. |autocommand|s executed when you edit a file. +3. ".nvim.lua" files in the current directory, if 'exrc' is enabled. +4. |editorconfig| in the current buffer's directory or ancestors. +5. 'modeline' settings found at the beginning or end of the file. See below. *modeline* *vim:* *vi:* *ex:* *E520* There are two forms of modelines. The first form: @@ -580,16 +621,6 @@ supported use something like this: > *E355* A jump table for the options with a short description can be found at |Q_op|. - *'aleph'* *'al'* *aleph* *Aleph* -'aleph' 'al' number (default 224) - global - The ASCII code for the first letter of the Hebrew alphabet. The - routine that maps the keyboard in Hebrew mode, both in Insert mode - (when hkmap is set) and on the command-line (when hitting CTRL-_) - outputs the Hebrew characters in the range [aleph..aleph+26]. - aleph=128 applies to PC code, and aleph=224 applies to ISO 8859-8. - See |rileft.txt|. - *'allowrevins'* *'ari'* *'noallowrevins'* *'noari'* 'allowrevins' 'ari' boolean (default off) global @@ -599,7 +630,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'revins'. *'ambiwidth'* *'ambw'* -'ambiwidth' 'ambw' string (default: "single") +'ambiwidth' 'ambw' string (default "single") global Tells Vim what to do with characters with East Asian Width Class Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek @@ -632,18 +663,8 @@ A jump table for the options with a short description can be found at |Q_op|. set to one of CJK locales. See Unicode Standard Annex #11 (https://www.unicode.org/reports/tr11). - *'autochdir'* *'acd'* *'noautochdir'* *'noacd'* -'autochdir' 'acd' boolean (default off) - global - When on, Vim will change the current working directory whenever you - open a file, switch buffers, delete a buffer or open/close a window. - It will change to the directory containing the file which was opened - or selected. When a buffer has no name it also has no directory, thus - the current directory won't change when navigating to it. - Note: When this option is on some plugins may not work. - *'arabic'* *'arab'* *'noarabic'* *'noarab'* -'arabic' 'arab' boolean (default off) +'arabic' 'arab' boolean (default off) local to window This option can be set to start editing Arabic text. Setting this option will: @@ -660,9 +681,8 @@ A jump table for the options with a short description can be found at |Q_op|. option). Also see |arabic.txt|. - *'arabicshape'* *'arshape'* - *'noarabicshape'* *'noarshape'* -'arabicshape' 'arshape' boolean (default on) + *'arabicshape'* *'arshape'* *'noarabicshape'* *'noarshape'* +'arabicshape' 'arshape' boolean (default on) global When on and 'termbidi' is off, the required visual character corrections that need to take place for displaying the Arabic language @@ -677,6 +697,16 @@ A jump table for the options with a short description can be found at |Q_op|. Arabic is a complex language which requires other settings, for further details see |arabic.txt|. + *'autochdir'* *'acd'* *'noautochdir'* *'noacd'* +'autochdir' 'acd' boolean (default off) + global + When on, Vim will change the current working directory whenever you + open a file, switch buffers, delete a buffer or open/close a window. + It will change to the directory containing the file which was opened + or selected. When a buffer has no name it also has no directory, thus + the current directory won't change when navigating to it. + Note: When this option is on some plugins may not work. + *'autoindent'* *'ai'* *'noautoindent'* *'noai'* 'autoindent' 'ai' boolean (default on) local to buffer @@ -691,13 +721,8 @@ A jump table for the options with a short description can be found at |Q_op|. line. When 'smartindent' or 'cindent' is on the indent is changed in a different way. - The 'autoindent' option is reset when the 'paste' option is set and - restored when 'paste' is reset. - {small difference from Vi: After the indent is deleted when typing - <Esc> or <CR>, the cursor position when moving up or down is after the - deleted indent; Vi puts the cursor somewhere in the deleted indent}. - *'autoread'* *'ar'* *'noautoread'* *'noar'* + *'autoread'* *'ar'* *'noautoread'* *'noar'* 'autoread' 'ar' boolean (default on) global or local to buffer |global-local| When a file has been detected to have been changed outside of Vim and @@ -709,7 +734,8 @@ A jump table for the options with a short description can be found at |Q_op|. using the global value: > :set autoread< < - *'autowrite'* *'aw'* *'noautowrite'* *'noaw'* + + *'autowrite'* *'aw'* *'noautowrite'* *'noaw'* 'autowrite' 'aw' boolean (default off) global Write the contents of the file, if it has been modified, on each @@ -723,8 +749,11 @@ A jump table for the options with a short description can be found at |Q_op|. 'autowriteall' for that. Some buffers will not be written, specifically when 'buftype' is "nowrite", "nofile", "terminal" or "prompt". + USE WITH CARE: If you make temporary changes to a buffer that you + don't want to be saved this option may cause it to be saved anyway. + Renaming the buffer with ":file {name}" may help avoid this. - *'autowriteall'* *'awa'* *'noautowriteall'* *'noawa'* + *'autowriteall'* *'awa'* *'noautowriteall'* *'noawa'* 'autowriteall' 'awa' boolean (default off) global Like 'autowrite', but also used for commands ":edit", ":enew", ":quit", @@ -732,7 +761,7 @@ A jump table for the options with a short description can be found at |Q_op|. Setting this option also implies that Vim behaves like 'autowrite' has been set. - *'background'* *'bg'* + *'background'* *'bg'* 'background' 'bg' string (default "dark") global When set to "dark" or "light", adjusts the default color groups for @@ -762,7 +791,7 @@ A jump table for the options with a short description can be found at |Q_op|. option, you must load syntax.vim again to see the result. This can be done with ":syntax on". - *'backspace'* *'bs'* + *'backspace'* *'bs'* 'backspace' 'bs' string (default "indent,eol,start") global Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert @@ -779,13 +808,6 @@ A jump table for the options with a short description can be found at |Q_op|. When the value is empty, Vi compatible backspacing is used, none of the ways mentioned for the items above are possible. - For backwards compatibility with version 5.4 and earlier: - value effect ~ - 0 same as ":set backspace=" (Vi compatible) - 1 same as ":set backspace=indent,eol" - 2 same as ":set backspace=indent,eol,start" - 3 same as ":set backspace=indent,eol,nostop" - *'backup'* *'bk'* *'nobackup'* *'nobk'* 'backup' 'bk' boolean (default off) global @@ -801,7 +823,7 @@ A jump table for the options with a short description can be found at |Q_op|. oldest version of a file. *'backupcopy'* *'bkc'* -'backupcopy' 'bkc' string (default: "auto") +'backupcopy' 'bkc' string (default "auto") global or local to buffer |global-local| When writing a file and a backup is made, this option tells how it's done. This is a comma-separated list of words. @@ -897,8 +919,7 @@ A jump table for the options with a short description can be found at |Q_op|. - Careful with '\' characters, type one before a space, type two to get one in the option (see |option-backslash|), for example: > :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces -< - For backwards compatibility with Vim version 3.0 a '>' at the start - of the option is removed. +< See also 'backup' and 'writebackup' options. If you want to hide your backup files on Unix, consider this value: > :set backupdir=./.backup,~/.backup,.,/tmp @@ -910,7 +931,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'backupext'* *'bex'* *E589* + *'backupext'* *'bex'* *E589* 'backupext' 'bex' string (default "~") global String which is appended to a file name to make the name of the @@ -918,7 +939,7 @@ A jump table for the options with a short description can be found at |Q_op|. accidentally overwriting existing files with a backup file. You might prefer using ".bak", but make sure that you don't have files with ".bak" that you want to keep. - Only normal file name characters can be used; "/\*?[|<>" are illegal. + Only normal file name characters can be used; `/\*?[|<>` are illegal. If you like to keep a lot of backups, you could use a BufWritePre autocommand to change 'backupext' just before writing the file to @@ -927,9 +948,9 @@ A jump table for the options with a short description can be found at |Q_op|. < Use 'backupdir' to put the backup in a different directory. *'backupskip'* *'bsk'* -'backupskip' 'bsk' string (default: "$TMPDIR/*,$TMP/*,$TEMP/*" - Unix: "/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*" - Mac: "/private/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*") +'backupskip' 'bsk' string (default "$TMPDIR/*,$TMP/*,$TEMP/*" + Unix: "/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*" + Mac: "/private/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*") global A list of file patterns. When one of the patterns matches with the name of the file which is written, no backup file is created. Both @@ -945,7 +966,7 @@ A jump table for the options with a short description can be found at |Q_op|. backups if you don't care about losing the file. Note that environment variables are not expanded. If you want to use - $HOME you must expand it explicitly, e.g.: > + $HOME you must expand it explicitly, e.g.: >vim :let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*' < Note that the default also makes sure that "crontab -e" works (when a @@ -990,7 +1011,7 @@ A jump table for the options with a short description can be found at |Q_op|. indicate that an error occurred. It can be silenced by adding the "error" keyword. - *'binary'* *'bin'* *'nobinary'* *'nobin'* + *'binary'* *'bin'* *'nobinary'* *'nobin'* 'binary' 'bin' boolean (default off) local to buffer This option should be set before editing a binary file. You can also @@ -1020,7 +1041,7 @@ A jump table for the options with a short description can be found at |Q_op|. the last line if there is none; this would make the file longer). See the 'endofline' option. - *'bomb'* *'nobomb'* + *'bomb'* *'nobomb'* 'bomb' boolean (default off) local to buffer When writing a file and the following conditions are met, a BOM (Byte @@ -1046,14 +1067,14 @@ A jump table for the options with a short description can be found at |Q_op|. break if 'linebreak' is on. Only works for ASCII characters. *'breakindent'* *'bri'* *'nobreakindent'* *'nobri'* -'breakindent' 'bri' boolean (default off) +'breakindent' 'bri' boolean (default off) local to window Every wrapped line will continue visually indented (same amount of space as the beginning of that line), thus preserving horizontal blocks of text. - *'breakindentopt'* *'briopt'* -'breakindentopt' 'briopt' string (default empty) + *'breakindentopt'* *'briopt'* +'breakindentopt' 'briopt' string (default "") local to window Settings for 'breakindent'. It can consist of the following optional items and must be separated by a comma: @@ -1084,7 +1105,7 @@ A jump table for the options with a short description can be found at |Q_op|. (default: off) *'browsedir'* *'bsdir'* -'browsedir' 'bsdir' string (default: "last") +'browsedir' 'bsdir' string (default "last") global Which directory to use for the file browser: last Use same directory as with last file browser, where a @@ -1094,8 +1115,8 @@ A jump table for the options with a short description can be found at |Q_op|. {path} Use the specified directory *'bufhidden'* *'bh'* -'bufhidden' 'bh' string (default: "") - local to buffer +'bufhidden' 'bh' string (default "") + local to buffer |local-noglobal| This option specifies what happens when a buffer is no longer displayed in a window: <empty> follow the global 'hidden' option @@ -1117,7 +1138,7 @@ A jump table for the options with a short description can be found at |Q_op|. special kinds of buffers. See |special-buffers|. *'buflisted'* *'bl'* *'nobuflisted'* *'nobl'* *E85* -'buflisted' 'bl' boolean (default: on) +'buflisted' 'bl' boolean (default on) local to buffer When this option is set, the buffer shows up in the buffer list. If it is reset it is not used for ":bnext", "ls", the Buffers menu, etc. @@ -1126,8 +1147,8 @@ A jump table for the options with a short description can be found at |Q_op|. But not when moving to a buffer with ":buffer". *'buftype'* *'bt'* *E382* -'buftype' 'bt' string (default: "") - local to buffer +'buftype' 'bt' string (default "") + local to buffer |local-noglobal| The value of this option specifies the type of a buffer: <empty> normal buffer acwrite buffer will always be written with |BufWriteCmd|s @@ -1174,7 +1195,7 @@ A jump table for the options with a short description can be found at |Q_op|. |FileWriteCmd| or |FileAppendCmd| autocommands. *'casemap'* *'cmp'* -'casemap' 'cmp' string (default: "internal,keepascii") +'casemap' 'cmp' string (default "internal,keepascii") global Specifies details about changing the case of letters. It may contain these words, separated by a comma: @@ -1186,16 +1207,18 @@ A jump table for the options with a short description can be found at |Q_op|. case mapping, the current locale is not effective. This probably only matters for Turkish. - *'cdhome'* *'cdh'* -'cdhome' 'cdh' boolean (default: off) + *'cdhome'* *'cdh'* *'nocdhome'* *'nocdh'* +'cdhome' 'cdh' boolean (default off) global When on, |:cd|, |:tcd| and |:lcd| without an argument changes the current working directory to the |$HOME| directory like in Unix. When off, those commands just print the current directory name. On Unix this option has no effect. + This option cannot be set from a |modeline| or in the |sandbox|, for + security reasons. - *'cdpath'* *'cd'* *E344* *E346* -'cdpath' 'cd' string (default: equivalent to $CDPATH or ",,") + *'cdpath'* *'cd'* *E344* *E346* +'cdpath' 'cd' string (default equivalent to $CDPATH or ",,") global This is a list of directories which will be searched when using the |:cd|, |:tcd| and |:lcd| commands, provided that the directory being @@ -1213,8 +1236,8 @@ A jump table for the options with a short description can be found at |Q_op|. security reasons. (parts of 'cdpath' can be passed to the shell to expand file names). - *'cedit'* -'cedit' string (default: CTRL-F) + *'cedit'* +'cedit' string (default CTRL-F) global The key used in Command-line Mode to open the command-line window. Only non-printable keys are allowed. @@ -1225,15 +1248,15 @@ A jump table for the options with a short description can be found at |Q_op|. < |Nvi| also has this option, but it only uses the first character. See |cmdwin|. - *'channel'* -'channel' number (default: 0) + *'channel'* +'channel' number (default 0) local to buffer |channel| connected to the buffer, or 0 if no channel is connected. In a |:terminal| buffer this is the terminal channel. Read-only. *'charconvert'* *'ccv'* *E202* *E214* *E513* -'charconvert' 'ccv' string (default "") +'charconvert' 'ccv' string (default "") global An expression that is used for character encoding conversion. It is evaluated when a file that is to be read or has been written has a @@ -1268,7 +1291,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'cindent'* *'cin'* *'nocindent'* *'nocin'* + *'cindent'* *'cin'* *'nocindent'* *'nocin'* 'cindent' 'cin' boolean (default off) local to buffer Enables automatic C program indenting. See 'cinkeys' to set the keys @@ -1281,9 +1304,8 @@ A jump table for the options with a short description can be found at |Q_op|. See |C-indenting|. When you don't like the way 'cindent' works, try the 'smartindent' option or 'indentexpr'. - This option is not used when 'paste' is set. - *'cinkeys'* *'cink'* + *'cinkeys'* *'cink'* 'cinkeys' 'cink' string (default "0{,0},0),0],:,0#,!^F,o,O,e") local to buffer A list of keys that, when typed in Insert mode, cause reindenting of @@ -1299,6 +1321,14 @@ A jump table for the options with a short description can be found at |Q_op|. program. See |cinoptions-values| for the values of this option, and |C-indenting| for info on C indenting in general. + *'cinscopedecls'* *'cinsd'* +'cinscopedecls' 'cinsd' string (default "public,protected,private") + local to buffer + Keywords that are interpreted as a C++ scope declaration by |cino-g|. + Useful e.g. for working with the Qt framework that defines additional + scope declarations "signals", "public slots" and "private slots": > + set cinscopedecls+=signals,public\ slots,private\ slots +< *'cinwords'* *'cinw'* 'cinwords' 'cinw' string (default "if,else,while,do,for,switch") @@ -1310,15 +1340,7 @@ A jump table for the options with a short description can be found at |Q_op|. matter, include the keyword both the uppercase and lowercase: "if,If,IF". - *'cinscopedecls'* *'cinsd'* -'cinscopedecls' 'cinsd' string (default "public,protected,private") - local to buffer - Keywords that are interpreted as a C++ scope declaration by |cino-g|. - Useful e.g. for working with the Qt framework that defines additional - scope declarations "signals", "public slots" and "private slots": > - set cinscopedecls+=signals,public\ slots,private\ slots - -< *'clipboard'* *'cb'* + *'clipboard'* *'cb'* 'clipboard' 'cb' string (default "") global This option is a list of comma-separated names. @@ -1342,11 +1364,11 @@ A jump table for the options with a short description can be found at |Q_op|. register. When "unnamed" is also included to the option, yank and delete operations (but not put) will additionally copy the text into register - '*'. See |clipboard|. + "*". See |clipboard|. *'cmdheight'* *'ch'* 'cmdheight' 'ch' number (default 1) - global or local to tab page + global or local to tab page |global-local| Number of screen lines to use for the command-line. Helps avoiding |hit-enter| prompts. The value of this option is stored with the tab page, so that each tab @@ -1377,7 +1399,7 @@ A jump table for the options with a short description can be found at |Q_op|. The screen column can be an absolute number, or a number preceded with '+' or '-', which is added to or subtracted from 'textwidth'. > - :set cc=+1 " highlight column after 'textwidth' + :set cc=+1 " highlight column after 'textwidth' :set cc=+1,+2,+3 " highlight three columns after 'textwidth' :hi ColorColumn ctermbg=lightgrey guibg=lightgrey < @@ -1401,22 +1423,21 @@ A jump table for the options with a short description can be found at |Q_op|. < Minimum value is 12, maximum value is 10000. *'comments'* *'com'* *E524* *E525* -'comments' 'com' string (default - "s1:/*,mb:*,ex:*/,://,b:#,:%,:XCOMM,n:>,fb:-") +'comments' 'com' string (default "s1:/*,mb:*,ex:*/,://,b:#,:%,:XCOMM,n:>,fb:-,fb:•") local to buffer A comma-separated list of strings that can start a comment line. See |format-comments|. See |option-backslash| about using backslashes to insert a space. *'commentstring'* *'cms'* *E537* -'commentstring' 'cms' string (default "/*%s*/") +'commentstring' 'cms' string (default "") local to buffer A template for a comment. The "%s" in the value is replaced with the - comment text. Currently only used to add markers for folding, see - |fold-marker|. + comment text. For example, C uses "/*%s*/". Currently only used to + add markers for folding, see |fold-marker|. *'complete'* *'cpt'* *E535* -'complete' 'cpt' string (default: ".,w,b,u,t") +'complete' 'cpt' string (default ".,w,b,u,t") local to buffer This option specifies how keyword completion |ins-completion| works when CTRL-P or CTRL-N are used. It is also used for whole-line @@ -1440,6 +1461,7 @@ A jump table for the options with a short description can be found at |Q_op|. |i_CTRL-X_CTRL-D| ] tag completion t same as "]" + f scan the buffer names (as opposed to buffer contents) Unloaded buffers are not loaded, thus their autocmds |:autocmd| are not executed, this may lead to unexpected completions from some files @@ -1451,7 +1473,7 @@ A jump table for the options with a short description can be found at |Q_op|. |i_CTRL-X_CTRL-I|, tags |i_CTRL-X_CTRL-]| and normal expansions). *'completefunc'* *'cfu'* -'completefunc' 'cfu' string (default: empty) +'completefunc' 'cfu' string (default "") local to buffer This option specifies a function to be used for Insert mode completion with CTRL-X CTRL-U. |i_CTRL-X_CTRL-U| @@ -1462,23 +1484,8 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'completeslash'* *'csl'* -'completeslash' 'csl' string (default: "") - local to buffer - {only for MS-Windows} - 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 MS-Windows. - - When this option is set to "backslash", backslash is used. This is - 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 - command line completion the global value is used. - *'completeopt'* *'cot'* -'completeopt' 'cot' string (default: "menu,preview") +'completeopt' 'cot' string (default "menu,preview") global A comma-separated list of options for Insert mode completion |ins-completion|. The supported values are: @@ -1509,9 +1516,23 @@ A jump table for the options with a short description can be found at |Q_op|. select one from the menu. Only works in combination with "menu" or "menuone". + *'completeslash'* *'csl'* +'completeslash' 'csl' string (default "") + local to buffer + only for MS-Windows + 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 MS-Windows. + - When this option is set to "backslash", backslash is used. This is + 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 + command line completion the global value is used. - *'concealcursor'* *'cocu'* -'concealcursor' 'cocu' string (default: "") + *'concealcursor'* *'cocu'* +'concealcursor' 'cocu' string (default "") local to window Sets the modes in which text in the cursor line can also be concealed. When the current mode is listed then concealing happens just like in @@ -1529,9 +1550,8 @@ A jump table for the options with a short description can be found at |Q_op|. Keep in mind that the cursor position is not always where it's displayed. E.g., when moving vertically it may change column. - *'conceallevel'* *'cole'* -'conceallevel' 'cole' number (default 0) +'conceallevel' 'cole' number (default 0) local to window Determine how text with the "conceal" syntax attribute |:syn-conceal| is shown: @@ -1553,7 +1573,7 @@ A jump table for the options with a short description can be found at |Q_op|. option. *'confirm'* *'cf'* *'noconfirm'* *'nocf'* -'confirm' 'cf' boolean (default off) +'confirm' 'cf' boolean (default off) global When 'confirm' is on, certain operations that would normally fail because of unsaved changes to a buffer, e.g. ":q" and ":e", @@ -1578,7 +1598,7 @@ A jump table for the options with a short description can be found at |Q_op|. See 'preserveindent'. *'cpoptions'* *'cpo'* *cpo* -'cpoptions' 'cpo' string (default: "aABceFs_") +'cpoptions' 'cpo' string (default "aABceFs_") global A sequence of single character flags. When a character is present this indicates Vi-compatible behavior. This is used for things where @@ -1812,7 +1832,7 @@ A jump table for the options with a short description can be found at |Q_op|. whitespace following the word in the motion. *'cursorbind'* *'crb'* *'nocursorbind'* *'nocrb'* -'cursorbind' 'crb' boolean (default off) +'cursorbind' 'crb' boolean (default off) local to window When this option is set, as the cursor in the current window moves other cursorbound windows (windows that also have @@ -1822,7 +1842,6 @@ A jump table for the options with a short description can be found at |Q_op|. inserted and deleted lines (though not characters within a line) are taken into account. - *'cursorcolumn'* *'cuc'* *'nocursorcolumn'* *'nocuc'* 'cursorcolumn' 'cuc' boolean (default off) local to window @@ -1843,9 +1862,8 @@ A jump table for the options with a short description can be found at |Q_op|. When Visual mode is active the highlighting isn't used to make it easier to see the selected text. - - *'cursorlineopt'* *'culopt'* -'cursorlineopt' 'culopt' string (default: "number,line") + *'cursorlineopt'* *'culopt'* +'cursorlineopt' 'culopt' string (default "both") local to window Comma-separated list of settings for how 'cursorline' is displayed. Valid values: @@ -1861,8 +1879,7 @@ A jump table for the options with a short description can be found at |Q_op|. "line" and "screenline" cannot be used together. - - *'debug'* + *'debug'* 'debug' string (default "") global These values can be used: @@ -1877,17 +1894,16 @@ A jump table for the options with a short description can be found at |Q_op|. 'indentexpr'. *'define'* *'def'* -'define' 'def' string (default "^\s*#\s*define") +'define' 'def' string (default "") global or local to buffer |global-local| Pattern to be used to find a macro definition. It is a search pattern, just like for the "/" command. This option is used for the commands like "[i" and "[d" |include-search|. The 'isident' option is - used to recognize the defined name after the match: + used to recognize the defined name after the match: > {match with 'define'}{non-ID chars}{defined name}{non-ID char} - See |option-backslash| about inserting backslashes to include a space +< See |option-backslash| about inserting backslashes to include a space or backslash. - The default value is for C programs. For C++ this value would be - useful, to include const type declarations: > + For C++ this value would be useful, to include const type declarations: > ^\(#\s*define\|[a-z]*\s*const\s*[a-z]*\) < You can also use "\ze" just before the name and continue the pattern to check what is following. E.g. for Javascript, if a function is @@ -1901,7 +1917,7 @@ A jump table for the options with a short description can be found at |Q_op|. < *'delcombine'* *'deco'* *'nodelcombine'* *'nodeco'* -'delcombine' 'deco' boolean (default off) +'delcombine' 'deco' boolean (default off) global If editing Unicode and this option is set, backspace and Normal mode "x" delete each combining character on its own. When it is off (the @@ -1939,13 +1955,13 @@ A jump table for the options with a short description can be found at |Q_op|. uses another default. Backticks cannot be used in this option for security reasons. - *'diff'* *'nodiff'* + *'diff'* *'nodiff'* 'diff' boolean (default off) local to window Join the current window in the group of windows that shows differences between files. See |diff-mode|. - *'dex'* *'diffexpr'* + *'diffexpr'* *'dex'* 'diffexpr' 'dex' string (default "") global Expression which is evaluated to obtain a diff file (either ed-style @@ -1953,7 +1969,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'dip'* *'diffopt'* + *'diffopt'* *'dip'* 'diffopt' 'dip' string (default "internal,filler,closeoff") global Option settings for diff mode. It can consist of the following items. @@ -1970,7 +1986,8 @@ A jump table for the options with a short description can be found at |Q_op|. When omitted a context of six lines is used. When using zero the context is actually one, since folds require a line in between, also - for a deleted line. + for a deleted line. Set it to a very large + value (999999) to disable folding completely. See |fold-diff|. iblank Ignore changes where lines are all blank. Adds @@ -2046,7 +2063,7 @@ A jump table for the options with a short description can be found at |Q_op|. hunks of up to 30 lines each, or a 3 buffer diff with hunks of up to 20 lines each. - algorithm:{text} Use the specified diff algorithm with the + algorithm:{text} Use the specified diff algorithm with the internal diff engine. Currently supported algorithms are: myers the default algorithm @@ -2061,7 +2078,8 @@ A jump table for the options with a short description can be found at |Q_op|. :set diffopt=internal,filler,foldcolumn:3 :set diffopt-=internal " do NOT use the internal diff parser < - *'digraph'* *'dg'* *'nodigraph'* *'nodg'* + + *'digraph'* *'dg'* *'nodigraph'* *'nodg'* 'digraph' 'dg' boolean (default off) global Enable the entering of digraphs in Insert mode with {char1} <BS> @@ -2074,7 +2092,7 @@ A jump table for the options with a short description can be found at |Q_op|. Possible items: - The swap file will be created in the first directory where this is - possible. If it is not possible in any directory, but last + possible. If it is not possible in any directory, but last directory listed in the option does not exist, it is created. - Empty means that no swap file will be used (recovery is impossible!) and no |E303| error will be given. @@ -2103,23 +2121,17 @@ A jump table for the options with a short description can be found at |Q_op|. - Careful with '\' characters, type one before a space, type two to get one in the option (see |option-backslash|), for example: > :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces -< - For backwards compatibility with Vim version 3.0 a '>' at the start - of the option is removed. - Using "." first in the list is recommended. This means that editing - the same file twice will result in a warning. Using "/tmp" on Unix is - discouraged: When the system crashes you lose the swap file. - "/var/tmp" is often not cleared when rebooting, thus is a better - choice than "/tmp". But others on the computer may be able to see the - files, and it can contain a lot of files, your swap files get lost in - the crowd. That is why a "tmp" directory in your home directory is - tried first. - The use of |:set+=| and |:set-=| is preferred when adding or removing - directories from the list. This avoids problems when a future version - uses another default. +< + Editing the same file twice will result in a warning. Using "/tmp" on + is discouraged: if the system crashes you lose the swap file. And + others on the computer may be able to see the files. + Use |:set+=| and |:set-=| when adding or removing directories from the + list, this avoids problems if the Nvim default is changed. + This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'display'* *'dy'* + *'display'* *'dy'* 'display' 'dy' string (default "lastline") global Change the way text is displayed. This is a comma-separated list of @@ -2148,8 +2160,8 @@ A jump table for the options with a short description can be found at |Q_op|. hor horizontally, height of windows is not affected both width and height of windows is affected - *'emoji'* *'emo'* *'noemoji'* *'noemo'* -'emoji' 'emo' boolean (default: on) + *'emoji'* *'emo'* *'noemoji'* *'noemo'* +'emoji' 'emo' boolean (default on) global When on all Unicode emoji characters are considered to be full width. This excludes "text emoji" characters, which are normally displayed as @@ -2157,8 +2169,9 @@ A jump table for the options with a short description can be found at |Q_op|. and it has been determined on trial-and-error basis. Use the |setcellwidths()| function to change the behavior. - *'encoding'* *'enc'* *E543* -'encoding' 'enc' + *'encoding'* *'enc'* +'encoding' 'enc' string (default "utf-8") + global String-encoding used internally and for |RPC| communication. Always UTF-8. @@ -2190,7 +2203,7 @@ A jump table for the options with a short description can be found at |Q_op|. be kept. But you can change it if you want to. See |eol-and-eof| for example settings. - *'equalalways'* *'ea'* *'noequalalways'* *'noea'* + *'equalalways'* *'ea'* *'noequalalways'* *'noea'* 'equalalways' 'ea' boolean (default on) global When on, all the windows are automatically made the same size after @@ -2229,7 +2242,7 @@ A jump table for the options with a short description can be found at |Q_op|. or do nothing. See 'belloff' to finetune when to ring the bell. *'errorfile'* *'ef'* -'errorfile' 'ef' string (default: "errors.err") +'errorfile' 'ef' string (default "errors.err") global Name of the errorfile for the QuickFix mode (see |:cf|). When the "-q" command-line argument is used, 'errorfile' is set to the @@ -2255,34 +2268,31 @@ A jump table for the options with a short description can be found at |Q_op|. Otherwise this is a comma-separated list of event names. Example: > :set ei=WinEnter,WinLeave < - *'expandtab'* *'et'* *'noexpandtab'* *'noet'* + + *'expandtab'* *'et'* *'noexpandtab'* *'noet'* 'expandtab' 'et' boolean (default off) local to buffer In Insert mode: Use the appropriate number of spaces to insert a <Tab>. Spaces are used in indents with the '>' and '<' commands and when 'autoindent' is on. To insert a real tab when 'expandtab' is on, use CTRL-V<Tab>. See also |:retab| and |ins-expandtab|. - This option is reset when the 'paste' option is set and restored when - the 'paste' option is reset. *'exrc'* *'ex'* *'noexrc'* *'noex'* -'exrc' 'ex' boolean (default off) +'exrc' 'ex' boolean (default off) global - Enables the reading of .nvim.lua, .nvimrc, and .exrc files in the current - directory. - - The file is only sourced if the user indicates the file is trusted. If - it is, the SHA256 hash of the file contents and the full path of the - file are persisted to a trust database. The user is only prompted - again if the file contents change. See |vim.secure.read()|. + Automatically execute .nvim.lua, .nvimrc, and .exrc files in the + current directory, if the file is in the |trust| list. Use |:trust| to + manage trusted files. See also |vim.secure.read()|. - Use |:trust| to manage the trusted file database. + Compare 'exrc' to |editorconfig|: + - 'exrc' can execute any code; editorconfig only specifies settings. + - 'exrc' is Nvim-specific; editorconfig works in other editors. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'fileencoding'* *'fenc'* *E213* -'fileencoding' 'fenc' string (default: "") + *'fileencoding'* *'fenc'* *E213* +'fileencoding' 'fenc' string (default "") local to buffer File-content encoding for the current buffer. Conversion is done with iconv() or as specified with 'charconvert'. @@ -2323,7 +2333,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be changed when 'modifiable' is off. *'fileencodings'* *'fencs'* -'fileencodings' 'fencs' string (default: "ucs-bom,utf-8,default,latin1") +'fileencodings' 'fencs' string (default "ucs-bom,utf-8,default,latin1") global This is a list of character encodings considered when starting to edit an existing file. When a file is read, Vim tries to use the first @@ -2372,9 +2382,8 @@ A jump table for the options with a short description can be found at |Q_op|. Setting this option does not have an effect until the next time a file is read. - *'fileformat'* *'ff'* -'fileformat' 'ff' string (Windows default: "dos", - Unix default: "unix") + *'fileformat'* *'ff'* +'fileformat' 'ff' string (default Windows: "dos", Unix: "unix") local to buffer This gives the <EOL> of the current buffer, which is used for reading/writing the buffer from/to a file: @@ -2392,10 +2401,8 @@ A jump table for the options with a short description can be found at |Q_op|. option is set, because the file would be different when written. This option cannot be changed when 'modifiable' is off. - *'fileformats'* *'ffs'* -'fileformats' 'ffs' string (default: - Win32: "dos,unix", - Unix: "unix,dos") + *'fileformats'* *'ffs'* +'fileformats' 'ffs' string (default Windows: "dos,unix", Unix: "unix,dos") global This gives the end-of-line (<EOL>) formats that will be tried when starting to edit a new buffer and when reading a file into an existing @@ -2445,14 +2452,14 @@ A jump table for the options with a short description can be found at |Q_op|. *'fileignorecase'* *'fic'* *'nofileignorecase'* *'nofic'* 'fileignorecase' 'fic' boolean (default on for systems where case in file - names is normally ignored) + names is normally ignored) global When set case is ignored when using file names and directories. See 'wildignorecase' for only ignoring case when doing completion. - *'filetype'* *'ft'* -'filetype' 'ft' string (default: "") - local to buffer + *'filetype'* *'ft'* +'filetype' 'ft' string (default "") + local to buffer |local-noglobal| When this option is set, the FileType autocommand event is triggered. All autocommands that match with the value of this option will be executed. Thus the value of 'filetype' is used in place of the file @@ -2473,7 +2480,7 @@ A jump table for the options with a short description can be found at |Q_op|. one dot may appear. This option is not copied to another buffer, independent of the 's' or 'S' flag in 'cpoptions'. - Only normal file name characters can be used, "/\*?[|<>" are illegal. + Only normal file name characters can be used, `/\*?[|<>` are illegal. *'fillchars'* *'fcs'* 'fillchars' 'fcs' string (default "") @@ -2484,8 +2491,8 @@ A jump table for the options with a short description can be found at |Q_op|. and the value of that item: item default Used for ~ - stl ' ' or '^' statusline of the current window - stlnc ' ' or '=' statusline of the non-current windows + stl ' ' statusline of the current window + stlnc ' ' statusline of the non-current windows wbr ' ' window bar horiz '─' or '-' horizontal separators |:split| horizup '┴' or '-' upwards facing horizontal separator @@ -2505,9 +2512,7 @@ A jump table for the options with a short description can be found at |Q_op|. colorcol ' ' character to display in the colorcolumn lastline '@' 'display' contains lastline/truncate - Any one that is omitted will fall back to the default. For "stl" and - "stlnc" the space will be used when there is highlighting, '^' or '=' - otherwise. + Any one that is omitted will fall back to the default. Note that "horiz", "horizup", "horizdown", "vertleft", "vertright" and "verthoriz" are only used when 'laststatus' is 3, since only vertical @@ -2518,10 +2523,8 @@ A jump table for the options with a short description can be found at |Q_op|. default to single-byte alternatives. Example: > - :set fillchars=stl:^,stlnc:=,vert:│,fold:·,diff:- -< This is similar to the default, except that these characters will also - be used when there is highlighting. - + :set fillchars=stl:\ ,stlnc:\ ,vert:│,fold:·,diff:- +< For the "stl", "stlnc", "foldopen", "foldclose" and "foldsep" items single-byte and multibyte characters are supported. But double-width characters are not supported. @@ -2556,25 +2559,25 @@ A jump table for the options with a short description can be found at |Q_op|. See |eol-and-eof| for example settings. *'foldclose'* *'fcl'* -'foldclose' 'fcl' string (default "") +'foldclose' 'fcl' string (default "") global When set to "all", a fold is closed when the cursor isn't in it and its level is higher than 'foldlevel'. Useful if you want folds to automatically close when moving out of them. *'foldcolumn'* *'fdc'* -'foldcolumn' 'fdc' string (default "0") +'foldcolumn' 'fdc' string (default "0") local to window When and how to draw the foldcolumn. Valid values are: "auto": resize to the minimum amount of folds to display. "auto:[1-9]": resize to accommodate multiple folds up to the selected level - 0: to disable foldcolumn + "0": to disable foldcolumn "[1-9]": to display a fixed number of columns See |folding|. *'foldenable'* *'fen'* *'nofoldenable'* *'nofen'* -'foldenable' 'fen' boolean (default on) +'foldenable' 'fen' boolean (default on) local to window When off, all folds are open. This option can be used to quickly switch between showing all text unfolded and viewing the text with @@ -2585,10 +2588,12 @@ A jump table for the options with a short description can be found at |Q_op|. See |folding|. *'foldexpr'* *'fde'* -'foldexpr' 'fde' string (default: "0") +'foldexpr' 'fde' string (default "0") local to window The expression used for when 'foldmethod' is "expr". It is evaluated - for each line to obtain its fold level. See |fold-expr|. + for each line to obtain its fold level. The context is set to the + script where 'foldexpr' was set, script-local items can be accessed. + See |fold-expr| for the usage. The expression will be evaluated in the |sandbox| if set from a modeline, see |sandbox-option|. @@ -2599,7 +2604,7 @@ A jump table for the options with a short description can be found at |Q_op|. evaluating 'foldexpr' |textlock|. *'foldignore'* *'fdi'* -'foldignore' 'fdi' string (default: "#") +'foldignore' 'fdi' string (default "#") local to window Used only when 'foldmethod' is "indent". Lines starting with characters in 'foldignore' will get their fold level from surrounding @@ -2607,7 +2612,7 @@ A jump table for the options with a short description can be found at |Q_op|. The default "#" works well for C programs. See |fold-indent|. *'foldlevel'* *'fdl'* -'foldlevel' 'fdl' number (default: 0) +'foldlevel' 'fdl' number (default 0) local to window Sets the fold level: Folds with a higher level will be closed. Setting this option to zero will close all folds. Higher numbers will @@ -2615,8 +2620,8 @@ A jump table for the options with a short description can be found at |Q_op|. This option is set by commands like |zm|, |zM| and |zR|. See |fold-foldlevel|. - *'foldlevelstart'* *'fdls'* -'foldlevelstart' 'fdls' number (default: -1) + *'foldlevelstart'* *'fdls'* +'foldlevelstart' 'fdls' number (default -1) global Sets 'foldlevel' when starting to edit another buffer in a window. Useful to always start editing with all folds closed (value zero), @@ -2628,8 +2633,8 @@ A jump table for the options with a short description can be found at |Q_op|. overrule the 'foldlevel' value for specific files. When the value is negative, it is not used. - *'foldmarker'* *'fmr'* *E536* -'foldmarker' 'fmr' string (default: "{{{,}}}") + *'foldmarker'* *'fmr'* *E536* +'foldmarker' 'fmr' string (default "{{{,}}}") local to window The start and end marker used when 'foldmethod' is "marker". There must be one comma, which separates the start and end marker. The @@ -2637,7 +2642,7 @@ A jump table for the options with a short description can be found at |Q_op|. See |fold-marker|. *'foldmethod'* *'fdm'* -'foldmethod' 'fdm' string (default: "manual") +'foldmethod' 'fdm' string (default "manual") local to window The kind of folding used for the current window. Possible values: |fold-manual| manual Folds are created manually. @@ -2648,7 +2653,7 @@ A jump table for the options with a short description can be found at |Q_op|. |fold-diff| diff Fold text that is not changed. *'foldminlines'* *'fml'* -'foldminlines' 'fml' number (default: 1) +'foldminlines' 'fml' number (default 1) local to window Sets the number of screen lines above which a fold can be displayed closed. Also for manually closed folds. With the default value of @@ -2659,15 +2664,14 @@ A jump table for the options with a short description can be found at |Q_op|. than 'foldminlines', a following "zc" may close a containing fold. *'foldnestmax'* *'fdn'* -'foldnestmax' 'fdn' number (default: 20) +'foldnestmax' 'fdn' number (default 20) local to window Sets the maximum nesting of folds for the "indent" and "syntax" methods. This avoids that too many folds will be created. Using more than 20 doesn't work, because the internal limit is 20. *'foldopen'* *'fdo'* -'foldopen' 'fdo' string (default: "block,hor,mark,percent,quickfix, - search,tag,undo") +'foldopen' 'fdo' string (default "block,hor,mark,percent,quickfix,search,tag,undo") global Specifies for which type of commands folds will be opened, if the command moves the cursor into a closed fold. It is a comma-separated @@ -2678,7 +2682,7 @@ A jump table for the options with a short description can be found at |Q_op|. item commands ~ all any - block "(", "{", "[[", "[{", etc. + block (, {, [[, [{, etc. hor horizontal movements: "l", "w", "fx", etc. insert any command in Insert mode jump far jumps: "G", "gg", etc. @@ -2701,10 +2705,12 @@ A jump table for the options with a short description can be found at |Q_op|. set the 'foldclose' option to "all". *'foldtext'* *'fdt'* -'foldtext' 'fdt' string (default: "foldtext()") +'foldtext' 'fdt' string (default "foldtext()") local to window An expression which is used to specify the text displayed for a closed - fold. See |fold-foldtext|. + fold. The context is set to the script where 'foldexpr' was set, + script-local items can be accessed. See |fold-foldtext| for the + usage. The expression will be evaluated in the |sandbox| if set from a modeline, see |sandbox-option|. @@ -2714,7 +2720,7 @@ A jump table for the options with a short description can be found at |Q_op|. evaluating 'foldtext' |textlock|. *'formatexpr'* *'fex'* -'formatexpr' 'fex' string (default "") +'formatexpr' 'fex' string (default "") local to buffer Expression which is evaluated to format a range of lines for the |gq| operator or automatic formatting (see 'formatoptions'). When this @@ -2745,15 +2751,17 @@ A jump table for the options with a short description can be found at |Q_op|. the script ID (|local-function|). Example: > set formatexpr=s:MyFormatExpr() set formatexpr=<SID>SomeFormatExpr() -< +< Otherwise, the expression is evaluated in the context of the script + where the option was set, thus script-local items are available. + The expression will be evaluated in the |sandbox| when set from a modeline, see |sandbox-option|. That stops the option from working, since changing the buffer text is not allowed. This option cannot be set in a modeline when 'modelineexpr' is off. NOTE: This option is set to "" when 'compatible' is set. - *'formatlistpat'* *'flp'* -'formatlistpat' 'flp' string (default: "^\s*\d\+[\]:.)}\t ]\s*") + *'formatlistpat'* *'flp'* +'formatlistpat' 'flp' string (default "^\s*\d\+[\]:.)}\t ]\s*") local to buffer A pattern that is used to recognize a list header. This is used for the "n" flag in 'formatoptions'. @@ -2765,18 +2773,18 @@ A jump table for the options with a short description can be found at |Q_op|. The default recognizes a number, followed by an optional punctuation character and white space. - *'formatoptions'* *'fo'* -'formatoptions' 'fo' string (default: "tcqj") + *'formatoptions'* *'fo'* +'formatoptions' 'fo' string (default "tcqj") local to buffer This is a sequence of letters which describes how automatic - formatting is to be done. See |fo-table|. When the 'paste' option is - on, no formatting is done (like 'formatoptions' is empty). Commas can - be inserted for readability. + formatting is to be done. + See |fo-table| for possible values and |gq| for how to format text. + Commas can be inserted for readability. To avoid problems with flags that are added in the future, use the "+=" and "-=" feature of ":set" |add-option-flags|. *'formatprg'* *'fp'* -'formatprg' 'fp' string (default "") +'formatprg' 'fp' string (default "") global or local to buffer |global-local| The name of an external program that will be used to format the lines selected with the |gq| operator. The program must take the input on @@ -2791,11 +2799,11 @@ A jump table for the options with a short description can be found at |Q_op|. security reasons. *'fsync'* *'fs'* *'nofsync'* *'nofs'* -'fsync' 'fs' boolean (default off) +'fsync' 'fs' boolean (default on) global When on, the OS function fsync() will be called after saving a file - (|:write|, |writefile()|, …), |swap-file| and |shada-file|. This - flushes the file to disk, ensuring that it is safely written. + (|:write|, |writefile()|, …), |swap-file|, |undo-persistence| and |shada-file|. + This flushes the file to disk, ensuring that it is safely written. Slow on some systems: writing buffers, quitting Nvim, and other operations may sometimes take a few seconds. @@ -2808,7 +2816,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'gdefault'* *'gd'* *'nogdefault'* *'nogd'* + *'gdefault'* *'gd'* *'nogdefault'* *'nogd'* 'gdefault' 'gd' boolean (default off) global When on, the ":substitute" flag 'g' is default on. This means that @@ -2834,7 +2842,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'grepprg'* *'gp'* 'grepprg' 'gp' string (default "grep -n ", - Unix: "grep -n $* /dev/null") + Unix: "grep -n $* /dev/null") global or local to buffer |global-local| Program to use for the |:grep| command. This option may contain '%' and '#' characters, which are expanded like when used in a command- @@ -2852,7 +2860,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'guicursor'* *'gcr'* *E545* *E546* *E548* *E549* + *'guicursor'* *'gcr'* *E545* *E546* *E548* *E549* 'guicursor' 'gcr' string (default "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20") global Configures the cursor style for each mode. Works in the GUI and many @@ -2918,10 +2926,10 @@ A jump table for the options with a short description can be found at |Q_op|. n-v-c-sm:block,i-ci-ve:ver25-Cursor,r-cr-o:hor20 In Normal et al. modes, use a block cursor with the default colors defined by the host - terminal. In Insert-likes modes, use + terminal. In Insert-like modes, use a vertical bar cursor with colors from - "Cursor" highlight group. In Replace-likes - modes, use a underline cursor with + "Cursor" highlight group. In Replace-like + modes, use an underline cursor with default colors. i-ci:ver30-iCursor-blinkwait300-blinkon200-blinkoff150 In Insert and Command-line Insert mode, use a @@ -2938,8 +2946,8 @@ A jump table for the options with a short description can be found at |Q_op|. :highlight Cursor gui=reverse guifg=NONE guibg=NONE :highlight Cursor gui=NONE guifg=bg guibg=fg < - *'guifont'* *'gfn'* - *E235* *E596* + + *'guifont'* *'gfn'* *E235* *E596* 'guifont' 'gfn' string (default "") global This is a list of fonts which will be used for the GUI version of Vim. @@ -2999,6 +3007,7 @@ A jump table for the options with a short description can be found at |Q_op|. :set guifont=courier_new:h12:w5:b:cRUSSIAN :set guifont=Andale_Mono:h7.5:w4.5 < + *'guifontwide'* *'gfw'* *E231* *E533* *E534* 'guifontwide' 'gfw' string (default "") global @@ -3114,7 +3123,7 @@ A jump table for the options with a short description can be found at |Q_op|. removing GUI components. *'guitablabel'* *'gtl'* -'guitablabel' 'gtl' string (default empty) +'guitablabel' 'gtl' string (default "") global When non-empty describes the text to use in a label of the GUI tab pages line. When empty and when the result is empty Vim will use a @@ -3131,7 +3140,7 @@ A jump table for the options with a short description can be found at |Q_op|. used. *'guitabtooltip'* *'gtt'* -'guitabtooltip' 'gtt' string (default empty) +'guitabtooltip' 'gtt' string (default "") global When non-empty describes the text to use in a tooltip for the GUI tab pages line. When empty Vim will use a default tooltip. @@ -3142,7 +3151,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'helpfile'* *'hf'* 'helpfile' 'hf' string (default (MS-Windows) "$VIMRUNTIME\doc\help.txt" - (others) "$VIMRUNTIME/doc/help.txt") + (others) "$VIMRUNTIME/doc/help.txt") global Name of the main help file. All distributed help files should be placed together in one directory. Additionally, all "doc" directories @@ -3164,7 +3173,7 @@ A jump table for the options with a short description can be found at |Q_op|. set to 'helpheight'. Set to zero to disable. *'helplang'* *'hlg'* -'helplang' 'hlg' string (default: messages language or empty) +'helplang' 'hlg' string (default messages language or empty) global Comma-separated list of languages. Vim will use the first language for which the desired help can be found. The English help will always @@ -3179,7 +3188,7 @@ A jump table for the options with a short description can be found at |Q_op|. try to find the tag in the current language before using this option. See |help-translated|. - *'hidden'* *'hid'* *'nohidden'* *'nohid'* + *'hidden'* *'hid'* *'nohidden'* *'nohid'* 'hidden' 'hid' boolean (default on) global When off a buffer is unloaded (including loss of undo information) @@ -3198,28 +3207,14 @@ A jump table for the options with a short description can be found at |Q_op|. 'hidden' is set for one command with ":hide {command}" |:hide|. *'history'* *'hi'* -'history' 'hi' number (default: 10000) +'history' 'hi' number (default 10000) global A history of ":" commands, and a history of previous search patterns is remembered. This option decides how many entries may be stored in each of these histories (see |cmdline-editing|). The maximum value is 10000. - *'hkmap'* *'hk'* *'nohkmap'* *'nohk'* -'hkmap' 'hk' boolean (default off) - global - When on, the keyboard is mapped for the Hebrew character set. - Normally you would set 'allowrevins' and use CTRL-_ in insert mode to - toggle this option. See |rileft.txt|. - - *'hkmapp'* *'hkp'* *'nohkmapp'* *'nohkp'* -'hkmapp' 'hkp' boolean (default off) - global - When on, phonetic keyboard mapping is used. 'hkmap' must also be on. - This is useful if you have a non-Hebrew keyboard. - See |rileft.txt|. - - *'hlsearch'* *'hls'* *'nohlsearch'* *'nohls'* + *'hlsearch'* *'hls'* *'nohlsearch'* *'nohls'* 'hlsearch' 'hls' boolean (default on) global When there is a previous search pattern, highlight all its matches. @@ -3251,7 +3246,7 @@ A jump table for the options with a short description can be found at |Q_op|. Overridden by the 'iconstring' option. Only works if the terminal supports setting window icons. - *'iconstring'* + *'iconstring'* 'iconstring' string (default "") global When this option is not empty, it will be used for the icon text of @@ -3265,14 +3260,14 @@ A jump table for the options with a short description can be found at |Q_op|. *'ignorecase'* *'ic'* *'noignorecase'* *'noic'* 'ignorecase' 'ic' boolean (default off) global - Ignore case in search patterns. Also used when searching in the tags - file. + Ignore case in search patterns, |cmdline-completion|, when + searching in the tags file, and |expr-==|. Also see 'smartcase' and 'tagcase'. Can be overruled by using "\c" or "\C" in the pattern, see |/ignorecase|. - *'imcmdline'* *'imc'* *'noimcmdline'* *'noimc'* -'imcmdline' 'imc' boolean (default off) + *'imcmdline'* *'imc'* *'noimcmdline'* *'noimc'* +'imcmdline' 'imc' boolean (default off) global When set the Input Method is always on when starting to edit a command line, unless entering a search pattern (see 'imsearch' for that). @@ -3280,8 +3275,8 @@ A jump table for the options with a short description can be found at |Q_op|. English characters directly, e.g., when it's used to type accented characters with dead keys. - *'imdisable'* *'imd'* *'noimdisable'* *'noimd'* -'imdisable' 'imd' boolean (default off, on for some systems (SGI)) + *'imdisable'* *'imd'* *'noimdisable'* *'noimd'* +'imdisable' 'imd' boolean (default off, on for some systems (SGI)) global When set the Input Method is never used. This is useful to disable the IM when it doesn't work properly. @@ -3289,7 +3284,7 @@ A jump table for the options with a short description can be found at |Q_op|. may change in later releases. *'iminsert'* *'imi'* -'iminsert' 'imi' number (default 0) +'iminsert' 'imi' number (default 0) local to buffer Specifies whether :lmap or an Input Method (IM) is to be used in Insert mode. Valid values: @@ -3307,7 +3302,7 @@ A jump table for the options with a short description can be found at |Q_op|. It is also used for the argument of commands like "r" and "f". *'imsearch'* *'ims'* -'imsearch' 'ims' number (default -1) +'imsearch' 'ims' number (default -1) local to buffer Specifies whether :lmap or an Input Method (IM) is to be used when entering a search pattern. Valid values: @@ -3324,7 +3319,6 @@ A jump table for the options with a short description can be found at |Q_op|. *'inccommand'* *'icm'* 'inccommand' 'icm' string (default "nosplit") global - When nonempty, shows the effects of |:substitute|, |:smagic|, |:snomagic| and user commands with the |:command-preview| flag as you type. @@ -3340,12 +3334,11 @@ A jump table for the options with a short description can be found at |Q_op|. |Command-line-mode| is done. *'include'* *'inc'* -'include' 'inc' string (default "^\s*#\s*include") +'include' 'inc' string (default "") global or local to buffer |global-local| Pattern to be used to find an include command. It is a search - pattern, just like for the "/" command (See |pattern|). The default - value is for C programs. This option is used for the commands "[i", - "]I", "[d", etc. + pattern, just like for the "/" command (See |pattern|). This option + is used for the commands "[i", "]I", "[d", etc. Normally the 'isfname' option is used to recognize the file name that comes after the matched pattern. But if "\zs" appears in the pattern then the text matched from "\zs" to the end, or until "\ze" if it @@ -3372,9 +3365,11 @@ A jump table for the options with a short description can be found at |Q_op|. If the expression starts with s: or |<SID>|, then it is replaced with the script ID (|local-function|). Example: > - set includeexpr=s:MyIncludeExpr(v:fname) - set includeexpr=<SID>SomeIncludeExpr(v:fname) -< + setlocal includeexpr=s:MyIncludeExpr(v:fname) + setlocal includeexpr=<SID>SomeIncludeExpr(v:fname) +< Otherwise, the expression is evaluated in the context of the script + where the option was set, thus script-local items are available. + The expression will be evaluated in the |sandbox| when set from a modeline, see |sandbox-option|. This option cannot be set in a modeline when 'modelineexpr' is off. @@ -3382,7 +3377,7 @@ A jump table for the options with a short description can be found at |Q_op|. It is not allowed to change text or jump to another window while evaluating 'includeexpr' |textlock|. - *'incsearch'* *'is'* *'noincsearch'* *'nois'* + *'incsearch'* *'is'* *'noincsearch'* *'nois'* 'incsearch' 'is' boolean (default on) global While typing a search command, show where the pattern, as it was typed @@ -3426,15 +3421,17 @@ A jump table for the options with a short description can be found at |Q_op|. When this option is not empty, it overrules the 'cindent' and 'smartindent' indenting. When 'lisp' is set, this option is is only used when 'lispoptions' contains "expr:1". - When 'paste' is set this option is not used for indenting. The expression is evaluated with |v:lnum| set to the line number for which the indent is to be computed. The cursor is also in this line when the expression is evaluated (but it may be moved around). + If the expression starts with s: or |<SID>|, then it is replaced with the script ID (|local-function|). Example: > set indentexpr=s:MyIndentExpr() set indentexpr=<SID>SomeIndentExpr() -< +< Otherwise, the expression is evaluated in the context of the script + where the option was set, thus script-local items are available. + The expression must return the number of spaces worth of indent. It can return "-1" to keep the current indent (this means 'autoindent' is used for the indent). @@ -3456,7 +3453,6 @@ A jump table for the options with a short description can be found at |Q_op|. It is not allowed to change text or jump to another window while evaluating 'indentexpr' |textlock|. - *'indentkeys'* *'indk'* 'indentkeys' 'indk' string (default "0{,0},0),0],:,0#,!^F,o,O,e") local to buffer @@ -3479,8 +3475,8 @@ A jump table for the options with a short description can be found at |Q_op|. *'isfname'* *'isf'* 'isfname' 'isf' string (default for Windows: - "@,48-57,/,\,.,-,_,+,,,#,$,%,{,},[,],:,@-@,!,~,=" - otherwise: "@,48-57,/,.,-,_,+,,,#,$,%,~,=") + "@,48-57,/,\,.,-,_,+,,,#,$,%,{,},[,],@-@,!,~,=" + otherwise: "@,48-57,/,.,-,_,+,,,#,$,%,~,=") global The characters specified by this option are included in file names and path names. Filenames are used for commands like "gf", "[i" and in @@ -3530,8 +3526,8 @@ A jump table for the options with a short description can be found at |Q_op|. *'isident'* *'isi'* 'isident' 'isi' string (default for Windows: - "@,48-57,_,128-167,224-235" - otherwise: "@,48-57,_,192-255") + "@,48-57,_,128-167,224-235" + otherwise: "@,48-57,_,192-255") global The characters given by this option are included in identifiers. Identifiers are used in recognizing environment variables and after a @@ -3544,7 +3540,7 @@ A jump table for the options with a short description can be found at |Q_op|. change 'iskeyword' instead. *'iskeyword'* *'isk'* -'iskeyword' 'isk' string (default: @,48-57,_,192-255) +'iskeyword' 'isk' string (default "@,48-57,_,192-255") local to buffer Keywords are used in searching and recognizing with many commands: "w", "*", "[i", etc. It is also used for "\k" in a |pattern|. See @@ -3553,14 +3549,14 @@ A jump table for the options with a short description can be found at |Q_op|. that is not white space or punctuation). For C programs you could use "a-z,A-Z,48-57,_,.,-,>". For a help file it is set to all non-blank printable characters except - '*', '"' and '|' (so that CTRL-] on a command finds the help for that + "*", '"' and '|' (so that CTRL-] on a command finds the help for that command). When the 'lisp' option is on the '-' character is always included. This option also influences syntax highlighting, unless the syntax uses |:syn-iskeyword|. *'isprint'* *'isp'* -'isprint' 'isp' string (default: "@,161-255") +'isprint' 'isp' string (default "@,161-255") global The characters given by this option are displayed directly on the screen. It is also used for "\p" in a |pattern|. The characters from @@ -3589,37 +3585,36 @@ A jump table for the options with a short description can be found at |Q_op|. Unprintable and zero-width Unicode characters are displayed as <xxxx>. There is no option to specify these characters. + *'joinspaces'* *'js'* *'nojoinspaces'* *'nojs'* +'joinspaces' 'js' boolean (default off) + global + Insert two spaces after a '.', '?' and '!' with a join command. + Otherwise only one space is inserted. + *'jumpoptions'* *'jop'* 'jumpoptions' 'jop' string (default "") global List of words that change the behavior of the |jumplist|. - stack Make the jumplist behave like the tagstack or like a - web browser. Relative location of entries in the - jumplist is preserved at the cost of discarding - subsequent entries when navigating backwards in the - jumplist and then jumping to a location. - |jumplist-stack| + stack Make the jumplist behave like the tagstack. + Relative location of entries in the jumplist is + preserved at the cost of discarding subsequent entries + when navigating backwards in the jumplist and then + jumping to a location. |jumplist-stack| view When moving through the jumplist, |changelist|, |alternate-file| or using |mark-motions| try to restore the |mark-view| in which the action occurred. - *'joinspaces'* *'js'* *'nojoinspaces'* *'nojs'* -'joinspaces' 'js' boolean (default off) - global - Insert two spaces after a '.', '?' and '!' with a join command. - Otherwise only one space is inserted. - - *'keymap'* *'kmp'* *E544* + *'keymap'* *'kmp'* 'keymap' 'kmp' string (default "") local to buffer Name of a keyboard mapping. See |mbyte-keymap|. Setting this option to a valid keymap name has the side effect of setting 'iminsert' to one, so that the keymap becomes effective. 'imsearch' is also set to one, unless it was -1 - Only normal file name characters can be used, "/\*?[|<>" are illegal. + Only normal file name characters can be used, `/\*?[|<>` are illegal. - *'keymodel'* *'km'* + *'keymodel'* *'km'* 'keymodel' 'km' string (default "") global List of comma-separated words, which enable special things that keys @@ -3630,9 +3625,8 @@ A jump table for the options with a short description can be found at |Q_op|. stopsel Using a not-shifted special key stops selection. Special keys in this context are the cursor keys, <End>, <Home>, <PageUp> and <PageDown>. - The 'keymodel' option is set by the |:behave| command. - *'keywordprg'* *'kp'* + *'keywordprg'* *'kp'* 'keywordprg' 'kp' string (default ":Man", Windows: ":help") global or local to buffer |global-local| Program to use for the |K| command. Environment variables are @@ -3693,7 +3687,7 @@ A jump table for the options with a short description can be found at |Q_op|. allowing to switch between mappings for different languages/encodings. Use a mapping to avoid having to type it each time! - *'langmenu'* *'lm'* + *'langmenu'* *'lm'* 'langmenu' 'lm' string (default "") global Language to use for menu translation. Tells which file is loaded @@ -3703,7 +3697,7 @@ A jump table for the options with a short description can be found at |Q_op|. matter what $LANG is set to: > :set langmenu=nl_NL.ISO_8859-1 < When 'langmenu' is empty, |v:lang| is used. - Only normal file name characters can be used, "/\*?[|<>" are illegal. + Only normal file name characters can be used, `/\*?[|<>` are illegal. If your $LANG is set to a non-English language but you do want to use the English menus: > :set langmenu=none @@ -3716,13 +3710,13 @@ A jump table for the options with a short description can be found at |Q_op|. < Warning: This deletes all menus that you defined yourself! *'langremap'* *'lrm'* *'nolangremap'* *'nolrm'* -'langremap' 'lrm' boolean (default off) +'langremap' 'lrm' boolean (default off) global When off, setting 'langmap' does not apply to characters resulting from a mapping. If setting 'langmap' disables some of your mappings, make sure this option is off. - *'laststatus'* *'ls'* + *'laststatus'* *'ls'* 'laststatus' 'ls' number (default 2) global The value of this option influences when the last window will have a @@ -3758,7 +3752,7 @@ A jump table for the options with a short description can be found at |Q_op|. Note that <Tab> characters after an <EOL> are mostly not displayed with the right amount of white space. - *'lines'* *E593* + *'lines'* *E593* 'lines' number (default 24 or terminal height) global Number of lines of the Vim window. @@ -3775,7 +3769,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'linespace'* *'lsp'* 'linespace' 'lsp' number (default 0) global - {only in the GUI} + only in the GUI Number of pixel lines inserted between characters. Useful if the font uses the full character cell height, making lines touch each other. When non-zero there is room for underlining. @@ -3795,7 +3789,6 @@ A jump table for the options with a short description can be found at |Q_op|. The '-' character is included in keyword characters. Redefines the "=" operator to use this same indentation algorithm rather than calling an external program if 'equalprg' is empty. - This option is not used when 'paste' is set. *'lispoptions'* *'lop'* 'lispoptions' 'lop' string (default "") @@ -3825,14 +3818,14 @@ A jump table for the options with a short description can be found at |Q_op|. The cursor is displayed at the start of the space a Tab character occupies, not at the end as usual in Normal mode. To get this cursor position while displaying Tabs with spaces, use: > - :set list lcs=tab:\ \ + :set list lcs=tab:\ \ < Note that list mode will also affect formatting (set with 'textwidth' or 'wrapmargin') when 'cpoptions' includes 'L'. See 'listchars' for changing the way tabs are displayed. *'listchars'* *'lcs'* -'listchars' 'lcs' string (default: "tab:> ,trail:-,nbsp:+") +'listchars' 'lcs' string (default "tab:> ,trail:-,nbsp:+") global or local to window |global-local| Strings to use in 'list' mode and for the |:list| command. It is a comma-separated list of string settings. @@ -3867,8 +3860,8 @@ A jump table for the options with a short description can be found at |Q_op|. are left blank. *lcs-multispace* multispace:c... - One or more characters to use cyclically to show for - multiple consecutive spaces. Overrides the "space" + One or more characters to use cyclically to show for + multiple consecutive spaces. Overrides the "space" setting, except for single spaces. When omitted, the "space" setting is used. For example, `:set listchars=multispace:---+` shows ten consecutive @@ -3931,7 +3924,7 @@ A jump table for the options with a short description can be found at |Q_op|. "precedes". |hl-Whitespace| for "nbsp", "space", "tab", "multispace", "lead" and "trail". - *'lpl'* *'nolpl'* *'loadplugins'* *'noloadplugins'* + *'loadplugins'* *'lpl'* *'noloadplugins'* *'nolpl'* 'loadplugins' 'lpl' boolean (default on) global When on the plugin scripts are loaded when starting up |load-plugins|. @@ -3952,7 +3945,7 @@ A jump table for the options with a short description can be found at |Q_op|. when you want to |/\M|. *'makeef'* *'mef'* -'makeef' 'mef' string (default: "") +'makeef' 'mef' string (default "") global Name of the errorfile for the |:make| command (see |:make_makeprg|) and the |:grep| command. @@ -3966,7 +3959,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'makeencoding'* *'menc'* + *'makeencoding'* *'menc'* 'makeencoding' 'menc' string (default "") global or local to buffer |global-local| Encoding used for reading the output of external commands. When empty, @@ -3980,6 +3973,7 @@ A jump table for the options with a short description can be found at |Q_op|. setting to the system locale encoding. Example: > :set makeencoding=char " system locale is used < + *'makeprg'* *'mp'* 'makeprg' 'mp' string (default "make") global or local to buffer |global-local| @@ -4036,7 +4030,7 @@ A jump table for the options with a short description can be found at |Q_op|. command recursion, see |E169|. See also |:function|. - *'maxmapdepth'* *'mmd'* *E223* + *'maxmapdepth'* *'mmd'* *E223* 'maxmapdepth' 'mmd' number (default 1000) global Maximum number of times a mapping is done without resulting in a @@ -4077,9 +4071,9 @@ A jump table for the options with a short description can be found at |Q_op|. per word depends very much on how similar the words are, that's why this tuning is complicated. - There are three numbers, separated by commas: + There are three numbers, separated by commas: > {start},{inc},{added} - +< For most languages the uncompressed word tree fits in memory. {start} gives the amount of memory in Kbyte that can be used before any compression is done. It should be a bit smaller than the amount of @@ -4104,17 +4098,18 @@ A jump table for the options with a short description can be found at |Q_op|. < If you have less than 512 Mbyte |:mkspell| may fail for some languages, no matter what you set 'mkspellmem' to. - This option cannot be set from a |modeline| or in the |sandbox|. + This option cannot be set from a |modeline| or in the |sandbox|, for + security reasons. - *'modeline'* *'ml'* *'nomodeline'* *'noml'* -'modeline' 'ml' boolean (default: on (off for root)) + *'modeline'* *'ml'* *'nomodeline'* *'noml'* +'modeline' 'ml' boolean (default on (off for root)) local to buffer If 'modeline' is on 'modelines' gives the number of lines that is checked for set commands. If 'modeline' is off or 'modelines' is zero no lines are checked. See |modeline|. - *'modelineexpr'* *'mle'* *'nomodelineexpr'* *'nomle'* -'modelineexpr' 'mle' boolean (default: off) + *'modelineexpr'* *'mle'* *'nomodelineexpr'* *'nomle'* +'modelineexpr' 'mle' boolean (default off) global When on allow some options that are an expression to be set in the modeline. Check the option for whether it is affected by @@ -4129,8 +4124,8 @@ A jump table for the options with a short description can be found at |Q_op|. checked for set commands. If 'modeline' is off or 'modelines' is zero no lines are checked. See |modeline|. - *'modifiable'* *'ma'* *'nomodifiable'* *'noma'* - *E21* + + *'modifiable'* *'ma'* *'nomodifiable'* *'noma'* *E21* 'modifiable' 'ma' boolean (default on) local to buffer When off the buffer contents cannot be changed. The 'fileformat' and @@ -4139,7 +4134,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'modified'* *'mod'* *'nomodified'* *'nomod'* 'modified' 'mod' boolean (default off) - local to buffer + local to buffer |local-noglobal| When on, the buffer is considered to be modified. This option is set when: 1. A change was made to the text since it was last written. Using the @@ -4163,16 +4158,15 @@ A jump table for the options with a short description can be found at |Q_op|. when using "rA" on an "A". *'more'* *'nomore'* -'more' boolean (default: on) +'more' boolean (default on) global When on, listings pause when the whole screen is filled. You will get the |more-prompt|. When this option is off there are no pauses, the listing continues until finished. - *'mouse'* + *'mouse'* 'mouse' string (default "nvi") global - Enables mouse support. For example, to enable the mouse in Normal mode and Visual mode: > :set mouse=nv @@ -4210,22 +4204,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'mousehide' hide mouse pointer while typing text 'selectmode' whether to start Select mode or Visual mode - The :behave command provides some "profiles" for mouse behavior. - *:behave* *:be* - :be[have] {model} Set behavior for mouse and selection. Valid - arguments are: - mswin MS-Windows behavior - xterm Xterm behavior - - Using ":behave" changes these options: - option mswin xterm ~ - 'selectmode' "mouse,key" "" - 'mousemodel' "popup" "extend" - 'keymodel' "startsel,stopsel" "" - 'selection' "exclusive" "inclusive" - - - *'mousefocus'* *'mousef'* *'nomousefocus'* *'nomousef'* + *'mousefocus'* *'mousef'* *'nomousefocus'* *'nomousef'* 'mousefocus' 'mousef' boolean (default off) global The window that the mouse pointer is on is automatically activated. @@ -4234,10 +4213,10 @@ A jump table for the options with a short description can be found at |Q_op|. default because it makes using the pull down menus a little goofy, as a pointer transit may activate a window unintentionally. - *'mousehide'* *'mh'* *'nomousehide'* *'nomh'* + *'mousehide'* *'mh'* *'nomousehide'* *'nomh'* 'mousehide' 'mh' boolean (default on) global - {only works in the GUI} + only in the GUI When on, the mouse pointer is hidden when characters are typed. The mouse pointer is restored when the mouse is moved. @@ -4292,10 +4271,8 @@ A jump table for the options with a short description can be found at |Q_op|. "g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click) "g<RightMouse>" is "<C-RightMouse> ("CTRL-T") - The 'mousemodel' option is set by the |:behave| command. - - *'mousemoveevent'* *'mousemev'* -'mousemoveevent' 'mousemev' boolean (default off) + *'mousemoveevent'* *'mousemev'* *'nomousemoveevent'* *'nomousemev'* +'mousemoveevent' 'mousemev' boolean (default off) global When on, mouse move events are delivered to the input queue and are available for mapping. The default, off, avoids the mouse movement @@ -4303,12 +4280,13 @@ A jump table for the options with a short description can be found at |Q_op|. Warning: Setting this option can make pending mappings to be aborted when the mouse is moved. - *'mousescroll'* + *'mousescroll'* *E5080* 'mousescroll' string (default "ver:3,hor:6") global This option controls the number of lines / columns to scroll by when - scrolling with a mouse. The option is a comma separated list of parts. - Each part consists of a direction and a count as follows: + scrolling with a mouse wheel (|scroll-mouse-wheel|). The option is + a comma-separated list. Each part consists of a direction and a count + as follows: direction:count,direction:count Direction is one of either "hor" or "ver". "hor" controls horizontal scrolling and "ver" controls vertical scrolling. Count sets the amount @@ -4325,7 +4303,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'mouseshape'* *'mouses'* *E547* 'mouseshape' 'mouses' string (default "i:beam,r:beam,s:updown,sd:cross, - m:no,ml:up-arrow,v:rightup-arrow") + m:no,ml:up-arrow,v:rightup-arrow") global This option tells Vim what the mouse pointer should look like in different modes. The option is a comma-separated list of parts, much @@ -4392,7 +4370,7 @@ A jump table for the options with a short description can be found at |Q_op|. Defines the maximum time in msec between two mouse clicks for the second click to be recognized as a multi click. - *'nrformats'* *'nf'* + *'nrformats'* *'nf'* 'nrformats' 'nf' string (default "bin,hex") local to buffer This defines what bases Vim will consider for numbers when using the @@ -4440,14 +4418,15 @@ A jump table for the options with a short description can be found at |Q_op|. 'nonu' 'nu' 'nonu' 'nu' 'nornu' 'nornu' 'rnu' 'rnu' -> + > |apple | 1 apple | 2 apple | 2 apple |pear | 2 pear | 1 pear | 1 pear |nobody | 3 nobody | 0 nobody |3 nobody |there | 4 there | 1 there | 1 there < + *'numberwidth'* *'nuw'* -'numberwidth' 'nuw' number (default: 4) +'numberwidth' 'nuw' number (default 4) local to window Minimal number of columns to use for the line number. Only relevant when the 'number' or 'relativenumber' option is set or printing lines @@ -4461,7 +4440,7 @@ A jump table for the options with a short description can be found at |Q_op|. The minimum value is 1, the maximum value is 20. *'omnifunc'* *'ofu'* -'omnifunc' 'ofu' string (default: empty) +'omnifunc' 'ofu' string (default "") local to buffer This option specifies a function to be used for Insert mode omni completion with CTRL-X CTRL-O. |i_CTRL-X_CTRL-O| @@ -4474,20 +4453,18 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - - *'opendevice'* *'odev'* *'noopendevice'* *'noodev'* + *'opendevice'* *'odev'* *'noopendevice'* *'noodev'* 'opendevice' 'odev' boolean (default off) global - {only for Windows} + only for Windows Enable reading and writing from devices. This may get Vim stuck on a device that can be opened but doesn't actually do the I/O. Therefore it is off by default. Note that on Windows editing "aux.h", "lpt1.txt" and the like also result in editing a device. - - *'operatorfunc'* *'opfunc'* -'operatorfunc' 'opfunc' string (default: empty) + *'operatorfunc'* *'opfunc'* +'operatorfunc' 'opfunc' string (default "") global This option specifies a function to be called by the |g@| operator. See |:map-operator| for more info and an example. The value can be @@ -4497,10 +4474,13 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'packpath'* *'pp'* -'packpath' 'pp' string (default: see 'runtimepath') - Directories used to find packages. See |packages| and |rtp-packages|. - + *'packpath'* *'pp'* +'packpath' 'pp' string (default see 'runtimepath') + global + Directories used to find packages. + See |packages| and |packages-runtimepath|. + This option cannot be set from a |modeline| or in the |sandbox|, for + security reasons. *'paragraphs'* *'para'* 'paragraphs' 'para' string (default "IPLPPPQPP TPHPLIPpLpItpplpipbp") @@ -4508,82 +4488,13 @@ A jump table for the options with a short description can be found at |Q_op|. Specifies the nroff macros that separate paragraphs. These are pairs of two letters (see |object-motions|). - *'paste'* *'nopaste'* -'paste' boolean (default off) - global - This option is obsolete; |bracketed-paste-mode| is built-in. - - Put Vim in Paste mode. This is useful if you want to cut or copy - some text from one window and paste it in Vim. This will avoid - unexpected effects. - Setting this option is useful when using Vim in a terminal, where Vim - cannot distinguish between typed text and pasted text. In the GUI, Vim - knows about pasting and will mostly do the right thing without 'paste' - being set. The same is true for a terminal where Vim handles the - mouse clicks itself. - This option is reset when starting the GUI. Thus if you set it in - your vimrc it will work in a terminal, but not in the GUI. Setting - 'paste' in the GUI has side effects: e.g., the Paste toolbar button - will no longer work in Insert mode, because it uses a mapping. - When the 'paste' option is switched on (also when it was already on): - - mapping in Insert mode and Command-line mode is disabled - - abbreviations are disabled - - 'autoindent' is reset - - 'expandtab' is reset - - 'hkmap' is reset - - 'revins' is reset - - 'ruler' is reset - - 'showmatch' is reset - - 'smarttab' is reset - - 'softtabstop' is set to 0 - - 'textwidth' is set to 0 - - 'wrapmargin' is set to 0 - - 'varsofttabstop' is made empty - These options keep their value, but their effect is disabled: - - 'cindent' - - 'formatoptions' is used like it is empty - - 'indentexpr' - - 'lisp' - - 'smartindent' - NOTE: When you start editing another file while the 'paste' option is - on, settings from the modelines or autocommands may change the - settings again, causing trouble when pasting text. You might want to - set the 'paste' option again. - When the 'paste' option is reset the mentioned options are restored to - the value before the moment 'paste' was switched from off to on. - Resetting 'paste' before ever setting it does not have any effect. - Since mapping doesn't work while 'paste' is active, you need to use - the 'pastetoggle' option to toggle the 'paste' option with some key. - - *'pastetoggle'* *'pt'* -'pastetoggle' 'pt' string (default "") - global - When non-empty, specifies the key sequence that toggles the 'paste' - option. This is like specifying a mapping: > - :map {keys} :set invpaste<CR> -< Where {keys} is the value of 'pastetoggle'. - The difference is that it will work even when 'paste' is set. - 'pastetoggle' works in Insert mode and Normal mode, but not in - Command-line mode. - Mappings are checked first, thus overrule 'pastetoggle'. However, - when 'paste' is on mappings are ignored in Insert mode, thus you can do - this: > - :map <F10> :set paste<CR> - :map <F11> :set nopaste<CR> - :imap <F10> <C-O>:set paste<CR> - :imap <F11> <nop> - :set pastetoggle=<F11> -< This will make <F10> start paste mode and <F11> stop paste mode. - Note that typing <F10> in paste mode inserts "<F10>", since in paste - mode everything is inserted literally, except the 'pastetoggle' key - sequence. - When the value has several bytes 'ttimeoutlen' applies. - - *'pex'* *'patchexpr'* + *'patchexpr'* *'pex'* 'patchexpr' 'pex' string (default "") global Expression which is evaluated to apply a patch to a file and generate the resulting new version of the file. See |diff-patchexpr|. + This option cannot be set from a |modeline| or in the |sandbox|, for + security reasons. *'patchmode'* *'pm'* *E205* *E206* 'patchmode' 'pm' string (default "") @@ -4603,11 +4514,10 @@ A jump table for the options with a short description can be found at |Q_op|. Using 'patchmode' for compressed files appends the extension at the end (e.g., "file.gz.orig"), thus the resulting name isn't always recognized as a compressed file. - Only normal file name characters can be used, "/\*?[|<>" are illegal. + Only normal file name characters can be used, `/\*?[|<>` are illegal. *'path'* *'pa'* *E343* *E345* *E347* *E854* -'path' 'pa' string (default on Unix: ".,/usr/include,," - other systems: ".,,") +'path' 'pa' string (default ".,,") global or local to buffer |global-local| This is a list of directories which will be searched when using the |gf|, [f, ]f, ^Wf, |:find|, |:sfind|, |:tabfind| and other commands, @@ -4616,9 +4526,9 @@ A jump table for the options with a short description can be found at |Q_op|. option may be relative or absolute. - Use commas to separate directory names: > :set path=.,/usr/local/include,/usr/include -< - Spaces can also be used to separate directory names (for backwards - compatibility with version 3.0). To have a space in a directory - name, precede it with an extra backslash, and escape the space: > +< - Spaces can also be used to separate directory names. To have a + space in a directory name, precede it with an extra backslash, and + escape the space: > :set path=.,/dir/with\\\ space < - To include a comma in a directory name precede it with an extra backslash: > @@ -4657,7 +4567,7 @@ A jump table for the options with a short description can be found at |Q_op|. < Replace the ';' with a ':' or whatever separator is used. Note that this doesn't work when $INCL contains a comma or white space. - *'preserveindent'* *'pi'* *'nopreserveindent'* *'nopi'* + *'preserveindent'* *'pi'* *'nopreserveindent'* *'nopi'* 'preserveindent' 'pi' boolean (default off) local to buffer When changing the indent of the current line, preserve as much of the @@ -4673,16 +4583,15 @@ A jump table for the options with a short description can be found at |Q_op|. Also see 'copyindent'. Use |:retab| to clean up white space. - *'previewheight'* *'pvh'* -'previewheight' 'pvh' number (default 12) + *'previewheight'* *'pvh'* +'previewheight' 'pvh' number (default 12) global Default height for a preview window. Used for |:ptag| and associated commands. Used for |CTRL-W_}| when no count is given. - *'previewwindow'* *'nopreviewwindow'* - *'pvw'* *'nopvw'* *E590* -'previewwindow' 'pvw' boolean (default off) - local to window + *'previewwindow'* *'pvw'* *'nopreviewwindow'* *'nopvw'* *E590* +'previewwindow' 'pvw' boolean (default off) + local to window |local-noglobal| Identifies the preview window. Only one window can have this option set. It's normally not set directly, but by using one of the commands |:ptag|, |:pedit|, etc. @@ -4726,8 +4635,8 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'quickfixtextfunc'* *'qftf'* -'quickfixtextfunc' 'qftf' string (default "") + *'quickfixtextfunc'* *'qftf'* +'quickfixtextfunc' 'qftf' string (default "") global This option specifies a function to be used to get the text to display in the quickfix and location list windows. This can be used to @@ -4750,9 +4659,9 @@ A jump table for the options with a short description can be found at |Q_op|. the following character will be skipped. The default value makes the text "foo\"bar\\" considered to be one string. - *'readonly'* *'ro'* *'noreadonly'* *'noro'* + *'readonly'* *'ro'* *'noreadonly'* *'noro'* 'readonly' 'ro' boolean (default off) - local to buffer + local to buffer |local-noglobal| If on, writes fail unless you use a '!'. Protects you from accidentally overwriting a file. Default on when Vim is started in read-only mode ("vim -R") or when the executable is called "view". @@ -4763,12 +4672,12 @@ A jump table for the options with a short description can be found at |Q_op|. See 'modifiable' for disallowing changes to the buffer. *'redrawdebug'* *'rdb'* -'redrawdebug' 'rdb' string (default '') +'redrawdebug' 'rdb' string (default "") global Flags to change the way redrawing works, for debugging purposes. Most useful with 'writedelay' set to some reasonable value. Supports the following flags: - compositor Indicate what redraws come from the compositor + compositor Indicate each redraw event handled by the compositor by briefly flashing the redrawn regions in colors indicating the redraw type. These are the highlight groups used (and their default colors): @@ -4780,6 +4689,11 @@ A jump table for the options with a short description can be found at |Q_op|. RedrawDebugRecompose guibg=Red redraw generated by the compositor itself, due to a grid being moved or deleted. + line introduce a delay after each line drawn on the screen. + When using the TUI or another single-grid UI, "compositor" + gives more information and should be preferred (every + line is processed as a separate event by the compositor) + flush introduce a delay after each "flush" event. nothrottle Turn off throttling of the message grid. This is an optimization that joins many small scrolls to one larger scroll when drawing the message area (with @@ -4789,7 +4703,7 @@ A jump table for the options with a short description can be found at |Q_op|. useful when running nvim inside a debugger (and the test suite). nodelta Send all internally redrawn cells to the UI, even if - they are unchanged from the already displayed state. + they are unchanged from the already displayed state. *'redrawtime'* *'rdt'* 'redrawtime' 'rdt' number (default 2000) @@ -4841,7 +4755,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'number', see |number_relativenumber| for all combinations of the two options. - *'report'* + *'report'* 'report' number (default 2) global Threshold for reporting number of lines changed. When the number of @@ -4856,10 +4770,8 @@ A jump table for the options with a short description can be found at |Q_op|. Inserting characters in Insert mode will work backwards. See "typing backwards" |ins-reverse|. This option can be toggled with the CTRL-_ command in Insert mode, when 'allowrevins' is set. - This option is reset when 'paste' is set and restored when 'paste' is - reset. - *'rightleft'* *'rl'* *'norightleft'* *'norl'* + *'rightleft'* *'rl'* *'norightleft'* *'norl'* 'rightleft' 'rl' boolean (default off) local to window When on, display orientation becomes right-to-left, i.e., characters @@ -4872,7 +4784,7 @@ A jump table for the options with a short description can be found at |Q_op|. and left-to-right strings so that both sets are displayed properly in different windows). Also see |rileft.txt|. - *'rightleftcmd'* *'rlc'* + *'rightleftcmd'* *'rlc'* 'rightleftcmd' 'rlc' string (default "search") local to window Each word in this option enables the command line editing to work in @@ -4883,7 +4795,7 @@ A jump table for the options with a short description can be found at |Q_op|. This is useful for languages such as Hebrew, Arabic and Farsi. The 'rightleft' option must be set for 'rightleftcmd' to take effect. - *'ruler'* *'ru'* *'noruler'* *'noru'* + *'ruler'* *'ru'* *'noruler'* *'noru'* 'ruler' 'ru' boolean (default on) global Show the line and column number of the cursor position, separated by a @@ -4906,13 +4818,11 @@ A jump table for the options with a short description can be found at |Q_op|. separated with a dash. For an empty line "0-1" is shown. For an empty buffer the line number will also be zero: "0,0-1". - This option is reset when 'paste' is set and restored when 'paste' is - reset. If you don't want to see the ruler all the time but want to know where you are, use "g CTRL-G" |g_CTRL-G|. *'rulerformat'* *'ruf'* -'rulerformat' 'ruf' string (default empty) +'rulerformat' 'ruf' string (default "") global When this option is not empty, it determines the content of the ruler string, as displayed for the 'ruler' option. @@ -4924,24 +4834,25 @@ A jump table for the options with a short description can be found at |Q_op|. Example: > :set rulerformat=%15(%c%V\ %p%%%) < - *'runtimepath'* *'rtp'* *vimfiles* -'runtimepath' 'rtp' string (default: "$XDG_CONFIG_HOME/nvim, - $XDG_CONFIG_DIRS[1]/nvim, - $XDG_CONFIG_DIRS[2]/nvim, - … - $XDG_DATA_HOME/nvim[-data]/site, - $XDG_DATA_DIRS[1]/nvim/site, - $XDG_DATA_DIRS[2]/nvim/site, - … - $VIMRUNTIME, - … - $XDG_DATA_DIRS[2]/nvim/site/after, - $XDG_DATA_DIRS[1]/nvim/site/after, - $XDG_DATA_HOME/nvim[-data]/site/after, - … - $XDG_CONFIG_DIRS[2]/nvim/after, - $XDG_CONFIG_DIRS[1]/nvim/after, - $XDG_CONFIG_HOME/nvim/after") + + *'runtimepath'* *'rtp'* *vimfiles* +'runtimepath' 'rtp' string (default "$XDG_CONFIG_HOME/nvim, + $XDG_CONFIG_DIRS[1]/nvim, + $XDG_CONFIG_DIRS[2]/nvim, + … + $XDG_DATA_HOME/nvim[-data]/site, + $XDG_DATA_DIRS[1]/nvim/site, + $XDG_DATA_DIRS[2]/nvim/site, + … + $VIMRUNTIME, + … + $XDG_DATA_DIRS[2]/nvim/site/after, + $XDG_DATA_DIRS[1]/nvim/site/after, + $XDG_DATA_HOME/nvim[-data]/site/after, + … + $XDG_CONFIG_DIRS[2]/nvim/after, + $XDG_CONFIG_DIRS[1]/nvim/after, + $XDG_CONFIG_HOME/nvim/after") global List of directories to be searched for these runtime files: filetype.lua filetypes |new-filetype| @@ -4958,7 +4869,7 @@ A jump table for the options with a short description can be found at |Q_op|. pack/ packages |:packadd| parser/ |treesitter| syntax parsers plugin/ plugin scripts |write-plugin| - query/ |treesitter| queries + queries/ |treesitter| queries rplugin/ |remote-plugin| scripts spell/ spell checking files |spell| syntax/ syntax files |mysyntaxfile| @@ -4969,7 +4880,7 @@ A jump table for the options with a short description can be found at |Q_op|. Defaults are setup to search these locations: 1. Your home directory, for personal preferences. Given by `stdpath("config")`. |$XDG_CONFIG_HOME| - 2. Directories which must contain configuration files according to + 2. Directories which must contain configuration files according to |xdg| ($XDG_CONFIG_DIRS, defaults to /etc/xdg). This also contains preferences from system administrator. 3. Data home directory, for plugins installed by user. @@ -5011,8 +4922,8 @@ A jump table for the options with a short description can be found at |Q_op|. With |--clean| the home directory entries are not included. *'scroll'* *'scr'* -'scroll' 'scr' number (default: half the window height) - local to window +'scroll' 'scr' number (default half the window height) + local to window |local-noglobal| Number of lines to scroll with CTRL-U and CTRL-D commands. Will be set to half the number of lines in the window when the window size changes. This may happen when enabling the |status-line| or @@ -5022,19 +4933,22 @@ A jump table for the options with a short description can be found at |Q_op|. height with ":set scroll=0". *'scrollback'* *'scbk'* -'scrollback' 'scbk' number (default: 10000) +'scrollback' 'scbk' number (default 10000) local to buffer Maximum number of lines kept beyond the visible screen. Lines at the top are deleted if new lines exceed this limit. Minimum is 1, maximum is 100000. Only in |terminal| buffers. + Note: Lines that are not visible and kept in scrollback are not + reflown when the terminal buffer is resized horizontally. + *'scrollbind'* *'scb'* *'noscrollbind'* *'noscb'* -'scrollbind' 'scb' boolean (default off) +'scrollbind' 'scb' boolean (default off) local to window - See also |scroll-binding|. When this option is set, the current - window scrolls as other scrollbind windows (windows that also have - this option set) scroll. This option is useful for viewing the + See also |scroll-binding|. When this option is set, scrolling the + current window also scrolls other scrollbind windows (windows that + also have this option set). This option is useful for viewing the differences between two versions of a file, see 'diff'. See |'scrollopt'| for options that determine how this option should be interpreted. @@ -5125,8 +5039,6 @@ A jump table for the options with a short description can be found at |Q_op|. backwards, you cannot include the last character of a line, when starting in Normal mode and 'virtualedit' empty. - The 'selection' option is set by the |:behave| command. - *'selectmode'* *'slm'* 'selectmode' 'slm' string (default "") global @@ -5137,11 +5049,9 @@ A jump table for the options with a short description can be found at |Q_op|. key when using shifted special keys cmd when using "v", "V" or CTRL-V See |Select-mode|. - The 'selectmode' option is set by the |:behave| command. - *'sessionoptions'* *'ssop'* -'sessionoptions' 'ssop' string (default: "blank,buffers,curdir,folds, - help,tabpages,winsize,terminal") + *'sessionoptions'* *'ssop'* +'sessionoptions' 'ssop' string (default "blank,buffers,curdir,folds,help,tabpages,winsize,terminal") global Changes the effect of the |:mksession| command. It is a comma- separated list of words. Each word enables saving and restoring @@ -5180,10 +5090,11 @@ A jump table for the options with a short description can be found at |Q_op|. filenames are stored as absolute paths. If you leave out "options" many things won't work well after restoring the session. - *'shada'* *'sd'* *E526* *E527* *E528* + + *'shada'* *'sd'* *E526* *E527* *E528* 'shada' 'sd' string (default for - Win32: !,'100,<50,s10,h,rA:,rB: - others: !,'100,<50,s10,h) + Win32: !,'100,<50,s10,h,rA:,rB: + others: !,'100,<50,s10,h) global When non-empty, the shada file is read upon startup and written when exiting Vim (see |shada-file|). The string should be a comma- @@ -5209,8 +5120,8 @@ A jump table for the options with a short description can be found at |Q_op|. % When included, save and restore the buffer list. If Vim is started with a file name argument, the buffer list is not restored. If Vim is started without a file name argument, the - buffer list is restored from the shada file. Quickfix - ('buftype'), unlisted ('buflisted'), unnamed and buffers on + buffer list is restored from the shada file. Quickfix + ('buftype'), unlisted ('buflisted'), unnamed and buffers on removable media (|shada-r|) are not saved. When followed by a number, the number specifies the maximum number of buffers that are stored. Without a number all @@ -5238,8 +5149,8 @@ A jump table for the options with a short description can be found at |Q_op|. @ Maximum number of items in the input-line history to be saved. When not included, the value of 'history' is used. *shada-c* - c Dummy option, kept for compatibility reasons. Has no actual - effect: ShaDa always uses UTF-8 and 'encoding' value is fixed + c Dummy option, kept for compatibility reasons. Has no actual + effect: ShaDa always uses UTF-8 and 'encoding' value is fixed to UTF-8 as well. *shada-f* f Whether file marks need to be stored. If zero, file marks ('0 @@ -5264,13 +5175,13 @@ A jump table for the options with a short description can be found at |Q_op|. could use "ra:,rb:". You can also use it for temp files, e.g., for Unix: "r/tmp". Case is ignored. *shada-s* - s Maximum size of an item contents in KiB. If zero then nothing - is saved. Unlike Vim this applies to all items, except for - the buffer list and header. Full item size is off by three - unsigned integers: with `s10` maximum item size may be 1 byte - (type: 7-bit integer) + 9 bytes (timestamp: up to 64-bit - integer) + 3 bytes (item size: up to 16-bit integer because - 2^8 < 10240 < 2^16) + 10240 bytes (requested maximum item + s Maximum size of an item contents in KiB. If zero then nothing + is saved. Unlike Vim this applies to all items, except for + the buffer list and header. Full item size is off by three + unsigned integers: with `s10` maximum item size may be 1 byte + (type: 7-bit integer) + 9 bytes (timestamp: up to 64-bit + integer) + 3 bytes (item size: up to 16-bit integer because + 2^8 < 10240 < 2^16) + 10240 bytes (requested maximum item contents size) = 10253 bytes. Example: > @@ -5280,7 +5191,7 @@ A jump table for the options with a short description can be found at |Q_op|. edited. <1000 Contents of registers (up to 1000 lines each) will be remembered. - s100 Items with contents occupying more then 100 KiB are + s100 Items with contents occupying more then 100 KiB are skipped. :0 Command-line history will not be saved. n~/nvim/shada The name of the file to use is "~/nvim/shada". @@ -5296,8 +5207,8 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'shadafile'* *'sdf'* -'shadafile' 'sdf' string (default: "") + *'shadafile'* *'sdf'* +'shadafile' 'sdf' string (default "") global When non-empty, overrides the file name used for |shada| (viminfo). When equal to "NONE" no shada file will be read or written. @@ -5319,44 +5230,44 @@ A jump table for the options with a short description can be found at |Q_op|. If the name of the shell contains a space, you need to enclose it in quotes. Example with quotes: > :set shell=\"c:\program\ files\unix\sh.exe\"\ -f -< Note the backslash before each quote (to avoid starting a comment) and - each space (to avoid ending the option value), so better use |:let-&| +< Note the backslash before each quote (to avoid starting a comment) and + each space (to avoid ending the option value), so better use |:let-&| like this: > :let &shell='"C:\Program Files\unix\sh.exe" -f' -< Also note that the "-f" is not inside the quotes, because it is not +< Also note that the "-f" is not inside the quotes, because it is not part of the command name. *shell-unquoting* Rules regarding quotes: - 1. Option is split on space and tab characters that are not inside - quotes: "abc def" runs shell named "abc" with additional argument - "def", '"abc def"' runs shell named "abc def" with no additional - arguments (here and below: additional means “additional to + 1. Option is split on space and tab characters that are not inside + quotes: "abc def" runs shell named "abc" with additional argument + "def", '"abc def"' runs shell named "abc def" with no additional + arguments (here and below: additional means “additional to 'shellcmdflag'”). - 2. Quotes in option may be present in any position and any number: - '"abc"', '"a"bc', 'a"b"c', 'ab"c"' and '"a"b"c"' are all equivalent + 2. Quotes in option may be present in any position and any number: + '"abc"', '"a"bc', 'a"b"c', 'ab"c"' and '"a"b"c"' are all equivalent to just "abc". - 3. Inside quotes backslash preceding backslash means one backslash. - Backslash preceding quote means one quote. Backslash preceding - anything else means backslash and next character literally: - '"a\\b"' is the same as "a\b", '"a\\"b"' runs shell named literally + 3. Inside quotes backslash preceding backslash means one backslash. + Backslash preceding quote means one quote. Backslash preceding + anything else means backslash and next character literally: + '"a\\b"' is the same as "a\b", '"a\\"b"' runs shell named literally 'a"b', '"a\b"' is the same as "a\b" again. - 4. Outside of quotes backslash always means itself, it cannot be used + 4. Outside of quotes backslash always means itself, it cannot be used to escape quote: 'a\"b"' is the same as "a\b". - Note that such processing is done after |:set| did its own round of + Note that such processing is done after |:set| did its own round of unescaping, so to keep yourself sane use |:let-&| like shown above. *shell-powershell* To use PowerShell: > let &shell = executable('pwsh') ? 'pwsh' : 'powershell' - let &shellcmdflag = '-NoLogo -NoProfile -ExecutionPolicy RemoteSigned -Command [Console]::InputEncoding=[Console]::OutputEncoding=[System.Text.Encoding]::UTF8;' - let &shellredir = '2>&1 | Out-File -Encoding UTF8 %s; exit $LastExitCode' - let &shellpipe = '2>&1 | Out-File -Encoding UTF8 %s; exit $LastExitCode' + let &shellcmdflag = '-NoLogo -ExecutionPolicy RemoteSigned -Command [Console]::InputEncoding=[Console]::OutputEncoding=[System.Text.UTF8Encoding]::new();$PSDefaultParameterValues[''Out-File:Encoding'']=''utf8'';Remove-Alias -Force -ErrorAction SilentlyContinue tee;' + let &shellredir = '2>&1 | %%{ "$_" } | Out-File %s; exit $LastExitCode' + let &shellpipe = '2>&1 | %%{ "$_" } | tee %s; exit $LastExitCode' set shellquote= shellxquote= < This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. *'shellcmdflag'* *'shcf'* -'shellcmdflag' 'shcf' string (default: "-c"; Windows: "/s /c") +'shellcmdflag' 'shcf' string (default "-c"; Windows: "/s /c") global Flag passed to the shell to execute "!" and ":!" commands; e.g., `bash.exe -c ls` or `cmd.exe /s /c "dir"`. For MS-Windows, the @@ -5365,14 +5276,13 @@ A jump table for the options with a short description can be found at |Q_op|. On Unix it can have more than one flag. Each white space separated part is passed as an argument to the shell command. See |option-backslash| about including spaces and backslashes. - See |shell-unquoting| which talks about separating this option into + See |shell-unquoting| which talks about separating this option into multiple arguments. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. *'shellpipe'* *'sp'* -'shellpipe' 'sp' string (default ">", ">%s 2>&1", "| tee", "|& tee" or - "2>&1| tee") +'shellpipe' 'sp' string (default ">", "| tee", "|& tee" or "2>&1| tee") global String to be used to put the output of the ":make" command in the error file. See also |:make_makeprg|. See |option-backslash| about @@ -5380,8 +5290,8 @@ A jump table for the options with a short description can be found at |Q_op|. The name of the temporary file can be represented by "%s" if necessary (the file name is appended automatically if no %s appears in the value of this option). - For MS-Windows the default is ">%s 2>&1". The output is directly - saved in a file and not echoed to the screen. + For MS-Windows the default is "2>&1| tee". The stdout and stderr are + saved in a file and echoed to the screen. For Unix the default is "| tee". The stdout of the compiler is saved in a file and echoed to the screen. If the 'shell' option is "csh" or "tcsh" after initializations, the default becomes "|& tee". If the @@ -5404,8 +5314,8 @@ A jump table for the options with a short description can be found at |Q_op|. security reasons. *'shellquote'* *'shq'* -'shellquote' 'shq' string (default: ""; Windows, when 'shell' - contains "sh" somewhere: "\"") +'shellquote' 'shq' string (default ""; Windows, when 'shell' + contains "sh" somewhere: "\"") global Quoting character(s), put around the command passed to the shell, for the "!" and ":!" commands. The redirection is kept outside of the @@ -5447,7 +5357,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'shellslash'* *'ssl'* *'noshellslash'* *'nossl'* 'shellslash' 'ssl' boolean (default off) global - {only for MS-Windows} + only for MS-Windows When set, a forward slash is used when expanding file names. This is useful when a Unix-like shell is used instead of cmd.exe. Backward slashes can still be typed, but they are changed to forward slashes by @@ -5475,14 +5385,16 @@ A jump table for the options with a short description can be found at |Q_op|. |system()| does not respect this option, it always uses pipes. *'shellxescape'* *'sxe'* -'shellxescape' 'sxe' string (default: "") +'shellxescape' 'sxe' string (default "") global When 'shellxquote' is set to "(" then the characters listed in this option will be escaped with a '^' character. This makes it possible to execute most external commands with cmd.exe. + This option cannot be set from a |modeline| or in the |sandbox|, for + security reasons. *'shellxquote'* *'sxq'* -'shellxquote' 'sxq' string (default: "", Windows: "\"") +'shellxquote' 'sxq' string (default "", Windows: "\"") global Quoting character(s), put around the command passed to the shell, for the "!" and ":!" commands. Includes the redirection. See @@ -5506,27 +5418,21 @@ A jump table for the options with a short description can be found at |Q_op|. local to buffer Number of spaces to use for each step of (auto)indent. Used for |'cindent'|, |>>|, |<<|, etc. - When zero the 'ts' value will be used. Use the |shiftwidth()| + When zero the 'tabstop' value will be used. Use the |shiftwidth()| function to get the effective shiftwidth value. - *'shortmess'* *'shm'* -'shortmess' 'shm' string (default "filnxtToOF") + *'shortmess'* *'shm'* *E1336* +'shortmess' 'shm' string (default "ltToOCF") global This option helps to avoid all the |hit-enter| prompts caused by file messages, for example with CTRL-G, and to avoid some other messages. It is a list of flags: flag meaning when present ~ - f use "(3 of 5)" instead of "(file 3 of 5)" *shm-f* - i use "[noeol]" instead of "[Incomplete last line]" *shm-i* l use "999L, 888B" instead of "999 lines, 888 bytes" *shm-l* m use "[+]" instead of "[Modified]" *shm-m* - n use "[New]" instead of "[New File]" *shm-n* r use "[RO]" instead of "[readonly]" *shm-r* w use "[w]" instead of "written" for file write message *shm-w* and "[a]" instead of "appended" for ':w >> file' command - x use "[dos]" instead of "[dos format]", "[unix]" *shm-x* - instead of "[unix format]" and "[mac]" instead of "[mac - format]" a all of the above abbreviations *shm-a* o overwrite message for writing a file with subsequent *shm-o* @@ -5548,7 +5454,7 @@ A jump table for the options with a short description can be found at |Q_op|. A don't give the "ATTENTION" message when an existing *shm-A* swap file is found I don't give the intro message when starting Vim, *shm-I* - see |:intro| + see |:intro| c don't give |ins-completion-menu| messages; for *shm-c* example, "-- XXX completion (YYY)", "match 1 of 2", "The only match", "Pattern not found", "Back at original", etc. @@ -5557,8 +5463,8 @@ A jump table for the options with a short description can be found at |Q_op|. q use "recording" instead of "recording @a" *shm-q* F don't give the file info when editing a file, like *shm-F* `:silent` was used for the command - S do not show search count message when searching, e.g. *shm-S* - "[1/5]" + S do not show search count message when searching, e.g. *shm-S* + "[1/5]" This gives you the opportunity to avoid that a change between buffers requires you to hit <Enter>, but still gives as useful a message as @@ -5569,14 +5475,12 @@ A jump table for the options with a short description can be found at |Q_op|. shm=a Abbreviation, but no loss of information. shm=at Abbreviation, and truncate message when necessary. - *'showbreak'* *'sbr'* *E595* + *'showbreak'* *'sbr'* *E595* 'showbreak' 'sbr' string (default "") global or local to window |global-local| String to put at the start of lines that have been wrapped. Useful values are "> " or "+++ ": > - :set showbreak=>\ -< Note the backslash to escape the trailing space. It's easier like - this: > + :let &showbreak = "> " :let &showbreak = '+++ ' < Only printable single-cell characters are allowed, excluding <Tab> and comma (in a future version the comma might be used to separate the @@ -5589,8 +5493,9 @@ A jump table for the options with a short description can be found at |Q_op|. set and you want no value in the current window use NONE: > :setlocal showbreak=NONE < - *'showcmd'* *'sc'* *'noshowcmd'* *'nosc'* -'showcmd' 'sc' boolean (default: on) + + *'showcmd'* *'sc'* *'noshowcmd'* *'nosc'* +'showcmd' 'sc' boolean (default on) global Show (partial) command in the last line of the screen. Set this option off if your terminal is slow. @@ -5604,7 +5509,7 @@ A jump table for the options with a short description can be found at |Q_op|. This information can be displayed in an alternative location using the 'showcmdloc' option, useful when 'cmdheight' is 0. - *'showcmdloc'* *'sloc'* + *'showcmdloc'* *'sloc'* 'showcmdloc' 'sloc' string (default "last") global This option can be used to display the (partially) entered command in @@ -5620,7 +5525,7 @@ A jump table for the options with a short description can be found at |Q_op|. displayed in a convenient location. *'showfulltag'* *'sft'* *'noshowfulltag'* *'nosft'* -'showfulltag' 'sft' boolean (default off) +'showfulltag' 'sft' boolean (default off) global When completing a word in insert mode (see |ins-completion|) from the tags file, show both the tag name and a tidied-up form of the search @@ -5631,7 +5536,7 @@ A jump table for the options with a short description can be found at |Q_op|. 'completeopt', because the completion from the search pattern may not match the typed text. - *'showmatch'* *'sm'* *'noshowmatch'* *'nosm'* + *'showmatch'* *'sm'* *'noshowmatch'* *'nosm'* 'showmatch' 'sm' boolean (default off) global When a bracket is inserted, briefly jump to the matching one. The @@ -5639,8 +5544,6 @@ A jump table for the options with a short description can be found at |Q_op|. show the match can be set with 'matchtime'. A Beep is given if there is no match (no matter if the match can be seen or not). - This option is reset when 'paste' is set and restored when 'paste' is - reset. When the 'm' flag is not included in 'cpoptions', typing a character will immediately move the cursor back to where it belongs. See the "sm" field in 'guicursor' for setting the cursor shape and @@ -5652,8 +5555,8 @@ A jump table for the options with a short description can be found at |Q_op|. around |pi_paren.txt|. Note: Use of the short form is rated PG. - *'showmode'* *'smd'* *'noshowmode'* *'nosmd'* -'showmode' 'smd' boolean (default: on) + *'showmode'* *'smd'* *'noshowmode'* *'nosmd'* +'showmode' 'smd' boolean (default on) global If in Insert, Replace or Visual mode put a message on the last line. The |hl-ModeMsg| highlight group determines the highlighting. @@ -5680,8 +5583,8 @@ A jump table for the options with a short description can be found at |Q_op|. When using a slow terminal set it to a large number or 0. Not used for "zh" and "zl" commands. - *'sidescrolloff'* *'siso'* -'sidescrolloff' 'siso' number (default 0) + *'sidescrolloff'* *'siso'* +'sidescrolloff' 'siso' number (default 0) global or local to window |global-local| The minimal number of screen columns to keep to the left and to the right of the cursor if 'nowrap' is set. Setting this option to a @@ -5703,11 +5606,12 @@ A jump table for the options with a short description can be found at |Q_op|. :set nowrap sidescroll=1 listchars=extends:>,precedes:< :set sidescrolloff=1 < + *'signcolumn'* *'scl'* 'signcolumn' 'scl' string (default "auto") local to window When and how to draw the signcolumn. Valid values are: - "auto" only when there is a sign to display + "auto" only when there is a sign to display "auto:[1-9]" resize to accommodate multiple signs up to the given number (maximum 9), e.g. "auto:4" "auto:[1-8]-[2-9]" @@ -5716,20 +5620,13 @@ A jump table for the options with a short description can be found at |Q_op|. at least the given minimum (maximum 8) fixed space. The minimum number should always be less than the maximum number, e.g. "auto:2-5" - "no" never - "yes" always + "no" never + "yes" always "yes:[1-9]" always, with fixed space for signs up to the given number (maximum 9), e.g. "yes:3" "number" display signs in the 'number' column. If the number column is not present, then behaves like "auto". - Note regarding "orphaned signs": with signcolumn numbers higher than - 1, deleting lines will also remove the associated signs automatically, - in contrast to the default Vim behavior of keeping and grouping them. - This is done in order for the signcolumn appearance not appear weird - during line deletion. - - *'smartcase'* *'scs'* *'nosmartcase'* *'noscs'* 'smartcase' 'scs' boolean (default off) global @@ -5740,7 +5637,7 @@ A jump table for the options with a short description can be found at |Q_op|. "*" and "#" you can make 'smartcase' used by doing a "/" command, recalling the search pattern from history and hitting <Enter>. - *'smartindent'* *'si'* *'nosmartindent'* *'nosi'* + *'smartindent'* *'si'* *'nosmartindent'* *'nosi'* 'smartindent' 'si' boolean (default off) local to buffer Do smart autoindenting when starting a new line. Works for C-like @@ -5762,10 +5659,8 @@ A jump table for the options with a short description can be found at |Q_op|. mapping: ":inoremap # X^H#", where ^H is entered with CTRL-V CTRL-H. When using the ">>" command, lines starting with '#' are not shifted right. - This option is reset when 'paste' is set and restored when 'paste' is - reset. - *'smarttab'* *'sta'* *'nosmarttab'* *'nosta'* + *'smarttab'* *'sta'* *'nosmarttab'* *'nosta'* 'smarttab' 'sta' boolean (default on) global When on, a <Tab> in front of a line inserts blanks according to @@ -5778,10 +5673,20 @@ A jump table for the options with a short description can be found at |Q_op|. What gets inserted (a <Tab> or spaces) depends on the 'expandtab' option. Also see |ins-expandtab|. When 'expandtab' is not set, the number of spaces is minimized by using <Tab>s. - This option is reset when 'paste' is set and restored when 'paste' is - reset. - *'softtabstop'* *'sts'* + *'smoothscroll'* *'sms'* *'nosmoothscroll'* *'nosms'* +'smoothscroll' 'sms' boolean (default off) + local to window + Scrolling works with screen lines. When 'wrap' is set and the first + line in the window wraps part of it may not be visible, as if it is + above the window. "<<<" is displayed at the start of the first line, + highlighted with |hl-NonText|. + You may also want to add "lastline" to the 'display' option to show as + much of the last line as possible. + NOTE: only partly implemented, currently works with CTRL-E, CTRL-Y + and scrolling with the mouse. + + *'softtabstop'* *'sts'* 'softtabstop' 'sts' number (default 0) local to buffer Number of spaces that a <Tab> counts for while performing editing @@ -5792,8 +5697,6 @@ A jump table for the options with a short description can be found at |Q_op|. commands like "x" still work on the actual characters. When 'sts' is zero, this feature is off. When 'sts' is negative, the value of 'shiftwidth' is used. - 'softtabstop' is set to 0 when the 'paste' option is set and restored - when 'paste' is reset. See also |ins-expandtab|. When 'expandtab' is not set, the number of spaces is minimized by using <Tab>s. The 'L' flag in 'cpoptions' changes how tabs are used when 'list' is @@ -5809,7 +5712,7 @@ A jump table for the options with a short description can be found at |Q_op|. The languages are specified with 'spelllang'. *'spellcapcheck'* *'spc'* -'spellcapcheck' 'spc' string (default "[.?!]\_[\])'" \t]\+") +'spellcapcheck' 'spc' string (default "[.?!]\_[\])'"\t ]\+") local to buffer Pattern to locate the end of a sentence. The following word will be checked to start with a capital letter. If not then it is highlighted @@ -5822,11 +5725,12 @@ A jump table for the options with a short description can be found at |Q_op|. |set-spc-auto|. *'spellfile'* *'spf'* -'spellfile' 'spf' string (default empty) +'spellfile' 'spf' string (default "") local to buffer Name of the word list file where words are added for the |zg| and |zw| commands. It must end in ".{encoding}.add". You need to include the path, otherwise the file is placed in the current directory. + The path may include characters from 'isfname', space, comma and '@'. *E765* It may also be a comma-separated list of names. A count before the |zg| and |zw| commands can be used to access each. This allows using @@ -5965,14 +5869,13 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'splitbelow'* *'sb'* *'nosplitbelow'* *'nosb'* 'splitbelow' 'sb' boolean (default off) global When on, splitting a window will put the new window below the current one. |:split| - *'splitkeep'* *'spk'* + *'splitkeep'* *'spk'* 'splitkeep' 'spk' string (default "cursor") global The value of this option determines the scroll behavior when opening, @@ -5994,21 +5897,22 @@ A jump table for the options with a short description can be found at |Q_op|. When on, splitting a window will put the new window right of the current one. |:vsplit| - *'startofline'* *'sol'* *'nostartofline'* *'nosol'* + *'startofline'* *'sol'* *'nostartofline'* *'nosol'* 'startofline' 'sol' boolean (default off) global When "on" the commands listed below move the cursor to the first non-blank of the line. When off the cursor is kept in the same column - (if possible). This applies to the commands: CTRL-D, CTRL-U, CTRL-B, - CTRL-F, "G", "H", "M", "L", gg, and to the commands "d", "<<" and ">>" - with a linewise operator, with "%" with a count and to buffer changing - commands (CTRL-^, :bnext, :bNext, etc.). Also for an Ex command that - only has a line number, e.g., ":25" or ":+". + (if possible). This applies to the commands: + - CTRL-D, CTRL-U, CTRL-B, CTRL-F, "G", "H", "M", "L", "gg" + - "d", "<<" and ">>" with a linewise operator + - "%" with a count + - buffer changing commands (CTRL-^, :bnext, :bNext, etc.) + - Ex commands that only have a line number, e.g., ":25" or ":+". In case of buffer changing commands the cursor is placed at the column where it was the last time the buffer was edited. - *'statuscolumn'* *'stc'* -'statuscolumn' 'stc' string (default: empty) + *'statuscolumn'* *'stc'* +'statuscolumn' 'stc' string (default "") local to window EXPERIMENTAL When non-empty, this option determines the content of the area to the @@ -6061,8 +5965,8 @@ A jump table for the options with a short description can be found at |Q_op|. < WARNING: this expression is evaluated for each screen line so defining an expensive expression can negatively affect render performance. - *'statusline'* *'stl'* *E540* *E542* -'statusline' 'stl' string (default empty) + *'statusline'* *'stl'* *E540* *E542* +'statusline' 'stl' string (default "") global or local to window |global-local| When non-empty, this option determines the content of the status line. Also see |status-line|. @@ -6166,41 +6070,45 @@ A jump table for the options with a short description can be found at |Q_op|. ( - 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. - T N For 'tabline': start of tab page N label. Use %T or %X to end - the label. Clicking this label with left mouse button switches + T N For 'tabline': start of tab page N label. Use %T or %X to end + the label. Clicking this label with left mouse button switches to the specified tab page. - X N For 'tabline': start of close tab N label. Use %X or %T to end - the label, e.g.: %3Xclose%X. Use %999X for a "close current - tab" label. Clicking this label with left mouse button closes + X N For 'tabline': start of close tab N label. Use %X or %T to end + the label, e.g.: %3Xclose%X. Use %999X for a "close current + tab" label. Clicking this label with left mouse button closes specified tab page. - @ N Start of execute function label. Use %X or %T to - end the label, e.g.: %10@SwitchBuffer@foo.c%X. Clicking this - label runs specified function: in the example when clicking once - using left mouse button on "foo.c" "SwitchBuffer(10, 1, 'l', - ' ')" expression will be run. Function receives the + @ N Start of execute function label. Use %X or %T to + end the label, e.g.: %10@SwitchBuffer@foo.c%X. Clicking this + label runs specified function: in the example when clicking once + using left mouse button on "foo.c" "SwitchBuffer(10, 1, 'l', + ' ')" expression will be run. Function receives the following arguments in order: 1. minwid field value or zero if no N was specified 2. number of mouse clicks to detect multiple clicks - 3. mouse button used: "l", "r" or "m" for left, right or middle - button respectively; one should not rely on third argument - being only "l", "r" or "m": any other non-empty string value - that contains only ASCII lower case letters may be expected + 3. mouse button used: "l", "r" or "m" for left, right or middle + button respectively; one should not rely on third argument + being only "l", "r" or "m": any other non-empty string value + that contains only ASCII lower case letters may be expected for other mouse buttons - 4. modifiers pressed: string which contains "s" if shift - modifier was pressed, "c" for control, "a" for alt and "m" - for meta; currently if modifier is not pressed string - contains space instead, but one should not rely on presence - of spaces or specific order of modifiers: use |stridx()| to - test whether some modifier is present; string is guaranteed - to contain only ASCII letters and spaces, one letter per - modifier; "?" modifier may also be present, but its presence - is a bug that denotes that new mouse button recognition was - added without modifying code that reacts on mouse clicks on + 4. modifiers pressed: string which contains "s" if shift + modifier was pressed, "c" for control, "a" for alt and "m" + for meta; currently if modifier is not pressed string + contains space instead, but one should not rely on presence + of spaces or specific order of modifiers: use |stridx()| to + test whether some modifier is present; string is guaranteed + to contain only ASCII letters and spaces, one letter per + modifier; "?" modifier may also be present, but its presence + is a bug that denotes that new mouse button recognition was + added without modifying code that reacts on mouse clicks on this label. + Use |getmousepos()|.winid in the specified function to get the + corresponding window id of the clicked item. < - Where to truncate line if too long. Default is at the start. No width fields allowed. - = - Separation point between alignment sections. Each section will - be separated by an equal number of spaces. + = - Separation point between alignment sections. Each section will + be separated by an equal number of spaces. With one %= what + comes after it will be right-aligned. With two %= there is a + middle part, with white space left and right of it. No width fields allowed. # - Set highlight group. The name must follow and then a # again. Thus use %#HLname# for highlight group HLname. The same @@ -6208,8 +6116,8 @@ A jump table for the options with a short description can be found at |Q_op|. windows. * - Set highlight group to User{N}, where {N} is taken from the minwid field, e.g. %1*. Restore normal highlight with %* or %0*. - The difference between User{N} and StatusLine will be applied - to StatusLineNC for the statusline of non-current windows. + The difference between User{N} and StatusLine will be applied to + StatusLineNC for the statusline of non-current windows. The number N must be between 1 and 9. See |hl-User1..9| When displaying a flag, Vim removes the leading comma, if any, when @@ -6269,6 +6177,7 @@ A jump table for the options with a short description can be found at |Q_op|. : if exists(a:var) | return a:val | else | return '' | endif :endfunction < + *'suffixes'* *'su'* 'suffixes' 'su' string (default ".bak,~,.o,.h,.info,.swp,.obj") global @@ -6290,8 +6199,9 @@ A jump table for the options with a short description can be found at |Q_op|. file for the "gf", "[I", etc. commands. Example: > :set suffixesadd=.java < + *'swapfile'* *'swf'* *'noswapfile'* *'noswf'* -'swapfile' 'swf' boolean (default on) +'swapfile' 'swf' boolean (default on) local to buffer Use a swapfile for the buffer. This option can be reset when a swapfile is not wanted for a specific buffer. For example, with @@ -6316,16 +6226,18 @@ A jump table for the options with a short description can be found at |Q_op|. 'switchbuf' 'swb' string (default "uselast") global This option controls the behavior when switching between buffers. - Mostly for |quickfix| commands some values are also used for other - commands, as mentioned below. + This option is checked, when + - jumping to errors with the |quickfix| commands (|:cc|, |:cn|, |:cp|, + etc.). + - jumping to a tag using the |:stag| command. + - opening a file using the |CTRL-W_f| or |CTRL-W_F| command. + - jumping to a buffer using a buffer split command (e.g. |:sbuffer|, + |:sbnext|, or |:sbrewind|). Possible values (comma-separated list): - useopen If included, jump to the first open window that - contains the specified buffer (if there is one). - Otherwise: Do not examine other windows. - This setting is checked with |quickfix| commands, when - jumping to errors (":cc", ":cn", "cp", etc.). It is - also used in all buffer related split commands, for - example ":sbuffer", ":sbnext", or ":sbrewind". + useopen If included, jump to the first open window in the + current tab page that contains the specified buffer + (if there is one). Otherwise: Do not examine other + windows. usetab Like "useopen", but also consider windows in other tab pages. split If included, split the current window before loading @@ -6350,8 +6262,8 @@ A jump table for the options with a short description can be found at |Q_op|. Set to zero to remove the limit. *'syntax'* *'syn'* -'syntax' 'syn' string (default empty) - local to buffer +'syntax' 'syn' string (default "") + local to buffer |local-noglobal| When this option is set, the syntax with this name is loaded, unless syntax highlighting has been switched off with ":syntax off". Otherwise this option does not always reflect the current syntax (the @@ -6374,10 +6286,10 @@ A jump table for the options with a short description can be found at |Q_op|. Syntax autocommand event is triggered with the value as argument. This option is not copied to another buffer, independent of the 's' or 'S' flag in 'cpoptions'. - Only normal file name characters can be used, "/\*?[|<>" are illegal. + Only normal file name characters can be used, `/\*?[|<>` are illegal. *'tabline'* *'tal'* -'tabline' 'tal' string (default empty) +'tabline' 'tal' string (default "") global When non-empty, this option determines the content of the tab pages line at the top of the Vim window. When empty Vim will use a default @@ -6400,14 +6312,12 @@ A jump table for the options with a short description can be found at |Q_op|. Keep in mind that only one of the tab pages is the current one, others are invisible and you can't jump to their windows. - *'tabpagemax'* *'tpm'* 'tabpagemax' 'tpm' number (default 50) global Maximum number of tab pages to be opened by the |-p| command line argument or the ":tab all" command. |tabpage| - *'tabstop'* *'ts'* 'tabstop' 'ts' number (default 8) local to buffer @@ -6423,13 +6333,25 @@ A jump table for the options with a short description can be found at |Q_op|. (or 3 or whatever you prefer) and use 'noexpandtab'. Then Vim will use a mix of tabs and spaces, but typing <Tab> and <BS> will behave like a tab appears every 4 (or 3) characters. - 2. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use + This is the recommended way, the file will look the same with other + tools and when listing it in a terminal. + 2. Set 'softtabstop' and 'shiftwidth' to whatever you prefer and use + 'expandtab'. This way you will always insert spaces. The + formatting will never be messed up when 'tabstop' is changed (leave + it at 8 just in case). The file will be a bit larger. + You do need to check if no Tabs exist in the file. You can get rid + of them by first setting 'expandtab' and using `%retab!`, making + sure the value of 'tabstop' is set correctly. + 3. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use 'expandtab'. This way you will always insert spaces. The formatting will never be messed up when 'tabstop' is changed. - 3. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use a + You do need to check if no Tabs exist in the file, just like in the + item just above. + 4. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use a |modeline| to set these values when editing the file again. Only - works when using Vim to edit the file. - 4. Always set 'tabstop' and 'shiftwidth' to the same value, and + works when using Vim to edit the file, other tools assume a tabstop + is worth 8 spaces. + 5. Always set 'tabstop' and 'shiftwidth' to the same value, and 'noexpandtab'. This should then work (for initial indents only) for any tabstop setting that people use. It might be nice to have tabs after the first non-blank inserted as spaces if you do this @@ -6457,7 +6379,7 @@ A jump table for the options with a short description can be found at |Q_op|. Linear searching is done anyway, for one file, when Vim finds a line at the start of the file indicating that it's not sorted: > - !_TAG_FILE_SORTED 0 /some comment/ + !_TAG_FILE_SORTED 0 /some comment/ < [The whitespace before and after the '0' must be a single <Tab>] When a binary search was done and no match was found in any of the @@ -6491,7 +6413,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option doesn't affect commands that find all matching tags (e.g., command-line completion and ":help"). - *'tagcase'* *'tc'* + *'tagcase'* *'tc'* 'tagcase' 'tc' string (default "followic") global or local to buffer |global-local| This option specifies how case is handled when searching the tags @@ -6502,8 +6424,8 @@ A jump table for the options with a short description can be found at |Q_op|. match Match case smart Ignore case unless an upper case letter is used - *'tagfunc'* *'tfu'* -'tagfunc' 'tfu' string (default: empty) + *'tagfunc'* *'tfu'* +'tagfunc' 'tfu' string (default "") local to buffer This option specifies a function to be used to perform tag searches. The function gets the tag pattern and should return a List of matching @@ -6511,6 +6433,8 @@ A jump table for the options with a short description can be found at |Q_op|. function and an example. The value can be the name of a function, a |lambda| or a |Funcref|. See |option-value-function| for more information. + This option cannot be set from a |modeline| or in the |sandbox|, for + security reasons. *'taglength'* *'tl'* 'taglength' 'tl' number (default 0) @@ -6518,7 +6442,7 @@ A jump table for the options with a short description can be found at |Q_op|. If non-zero, tags are significant up to this number of characters. *'tagrelative'* *'tr'* *'notagrelative'* *'notr'* -'tagrelative' 'tr' boolean (default: on) +'tagrelative' 'tr' boolean (default on) global If on and using a tags file in another directory, file names in that tags file are relative to the directory where the tags file is. @@ -6527,8 +6451,8 @@ A jump table for the options with a short description can be found at |Q_op|. 'tags' 'tag' string (default "./tags;,tags") global or local to buffer |global-local| Filenames for the tag command, separated by spaces or commas. To - include a space or comma in a file name, precede it with a backslash - (see |option-backslash| about including spaces and backslashes). + include a space or comma in a file name, precede it with backslashes + (see |option-backslash| about including spaces/commas and backslashes). When a file name starts with "./", the '.' is replaced with the path of the current file. But only when the 'd' flag is not included in 'cpoptions'. Environment variables are expanded |:set_env|. Also see @@ -6544,7 +6468,7 @@ A jump table for the options with a short description can be found at |Q_op|. file names from the list. This avoids problems when a future version uses another default. - *'tagstack'* *'tgst'* *'notagstack'* *'notgst'* + *'tagstack'* *'tgst'* *'notagstack'* *'notgst'* 'tagstack' 'tgst' boolean (default on) global When on, the |tagstack| is used normally. When off, a ":tag" or @@ -6555,9 +6479,8 @@ A jump table for the options with a short description can be found at |Q_op|. Resetting this option is useful when using a ":tag" command in a mapping which should not change the tagstack. - *'termbidi'* *'tbidi'* - *'notermbidi'* *'notbidi'* -'termbidi' 'tbidi' boolean (default off) + *'termbidi'* *'tbidi'* *'notermbidi'* *'notbidi'* +'termbidi' 'tbidi' boolean (default off) global The terminal is in charge of Bi-directionality of text (as specified by Unicode). The terminal is also expected to do the required shaping @@ -6568,15 +6491,15 @@ A jump table for the options with a short description can be found at |Q_op|. 'arabicshape' is ignored, but 'rightleft' isn't changed automatically. For further details see |arabic.txt|. - *'termguicolors'* *'tgc'* *'notermguicolors'* *'notgc'* -'termguicolors' 'tgc' boolean (default off) + *'termguicolors'* *'tgc'* *'notermguicolors'* *'notgc'* +'termguicolors' 'tgc' boolean (default off) global Enables 24-bit RGB color in the |TUI|. Uses "gui" |:highlight| attributes instead of "cterm" attributes. |guifg| Requires an ISO-8613-3 compatible terminal. - *'termpastefilter'* *'tpf'* -'termpastefilter' 'tpf' string (default: "BS,HT,ESC,DEL") + *'termpastefilter'* *'tpf'* +'termpastefilter' 'tpf' string (default "BS,HT,ESC,DEL") global A comma-separated list of options for specifying control characters to be removed from the text pasted into the terminal window. The @@ -6597,6 +6520,13 @@ A jump table for the options with a short description can be found at |Q_op|. C1 Control characters 0x80...0x9F + *'termsync'* *'notermsync'* +'termsync' boolean (default on) + global + If the host terminal supports it, buffer all screen updates + made during a redraw cycle so that each screen is displayed in + the terminal all at once. This can prevent tearing or flickering + when the terminal updates faster than Nvim can redraw. *'textwidth'* *'tw'* 'textwidth' 'tw' number (default 0) @@ -6604,8 +6534,6 @@ A jump table for the options with a short description can be found at |Q_op|. Maximum width of text that is being inserted. A longer line will be broken after white space to get this width. A zero value disables this. - 'textwidth' is set to 0 when the 'paste' option is set and restored - when 'paste' is reset. When 'textwidth' is zero, 'wrapmargin' may be used. See also 'formatoptions' and |ins-textwidth|. When 'formatexpr' is set it will be used to break the line. @@ -6628,8 +6556,8 @@ A jump table for the options with a short description can be found at |Q_op|. another default. Backticks cannot be used in this option for security reasons. - *'thesaurusfunc'* *'tsrfu'* -'thesaurusfunc' 'tsrfu' string (default: empty) + *'thesaurusfunc'* *'tsrfu'* +'thesaurusfunc' 'tsrfu' string (default "") global or local to buffer |global-local| This option specifies a function to be used for thesaurus completion with CTRL-X CTRL-T. |i_CTRL-X_CTRL-T| See |compl-thesaurusfunc|. @@ -6639,46 +6567,24 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'tildeop'* *'top'* *'notildeop'* *'notop'* + *'tildeop'* *'top'* *'notildeop'* *'notop'* 'tildeop' 'top' boolean (default off) global When on: The tilde command "~" behaves like an operator. *'timeout'* *'to'* *'notimeout'* *'noto'* -'timeout' 'to' boolean (default on) +'timeout' 'to' boolean (default on) global This option and 'timeoutlen' determine the behavior when part of a mapped key sequence has been received. For example, if <c-f> is pressed and 'timeout' is set, Nvim will wait 'timeoutlen' milliseconds for any key that can follow <c-f> in a mapping. - *'ttimeout'* *'nottimeout'* -'ttimeout' boolean (default on) - global - This option and 'ttimeoutlen' determine the behavior when part of a - key code sequence has been received by the |TUI|. - - For example if <Esc> (the \x1b byte) is received and 'ttimeout' is - set, Nvim waits 'ttimeoutlen' milliseconds for the terminal to - complete a key code sequence. If no input arrives before the timeout, - a single <Esc> is assumed. Many TUI cursor key codes start with <Esc>. - - On very slow systems this may fail, causing cursor keys not to work - sometimes. If you discover this problem you can ":set ttimeoutlen=9999". - Nvim will wait for the next character to arrive after an <Esc>. - *'timeoutlen'* *'tm'* 'timeoutlen' 'tm' number (default 1000) global Time in milliseconds to wait for a mapped sequence to complete. - *'ttimeoutlen'* *'ttm'* -'ttimeoutlen' 'ttm' number (default 50) - global - Time in milliseconds to wait for a key code sequence to complete. Also - used for CTRL-\ CTRL-N and CTRL-\ CTRL-G when part of a command has - been typed. - *'title'* *'notitle'* 'title' boolean (default off) global @@ -6694,7 +6600,7 @@ A jump table for the options with a short description can be found at |Q_op|. (path) is the path of the file being edited - NVIM the server name |v:servername| or "NVIM" - *'titlelen'* + *'titlelen'* 'titlelen' number (default 85) global Gives the percentage of 'columns' to use for the length of the window @@ -6707,14 +6613,15 @@ A jump table for the options with a short description can be found at |Q_op|. values from 1 to 30000 percent can be used. 'titlelen' is also used for the 'titlestring' option. - *'titleold'* + *'titleold'* 'titleold' string (default "") global If not empty, this option will be used to set the window title when exiting. Only if 'title' is enabled. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. - *'titlestring'* + + *'titlestring'* 'titlestring' string (default "") global When this option is not empty, it will be used for the title of the @@ -6737,7 +6644,29 @@ A jump table for the options with a short description can be found at |Q_op|. NOTE: Use of special characters in 'titlestring' may cause the display to be garbled (e.g., when it contains a CR or NL character). - *'undodir'* *'udir'* *E5003* + *'ttimeout'* *'nottimeout'* +'ttimeout' boolean (default on) + global + This option and 'ttimeoutlen' determine the behavior when part of a + key code sequence has been received by the |TUI|. + + For example if <Esc> (the \x1b byte) is received and 'ttimeout' is + set, Nvim waits 'ttimeoutlen' milliseconds for the terminal to + complete a key code sequence. If no input arrives before the timeout, + a single <Esc> is assumed. Many TUI cursor key codes start with <Esc>. + + On very slow systems this may fail, causing cursor keys not to work + sometimes. If you discover this problem you can ":set ttimeoutlen=9999". + Nvim will wait for the next character to arrive after an <Esc>. + + *'ttimeoutlen'* *'ttm'* +'ttimeoutlen' 'ttm' number (default 50) + global + Time in milliseconds to wait for a key code sequence to complete. Also + used for CTRL-\ CTRL-N and CTRL-\ CTRL-G when part of a command has + been typed. + + *'undodir'* *'udir'* *E5003* 'undodir' 'udir' string (default "$XDG_STATE_HOME/nvim/undo//") global List of directory names for undo files, separated with commas. @@ -6761,7 +6690,7 @@ A jump table for the options with a short description can be found at |Q_op|. though the trailing slashes are present (see 'backupdir' for what this means). - *'undofile'* *'noundofile'* *'udf'* *'noudf'* + *'undofile'* *'udf'* *'noundofile'* *'noudf'* 'undofile' 'udf' boolean (default off) local to buffer When on, Vim automatically saves undo history to an undo file when @@ -6810,7 +6739,7 @@ A jump table for the options with a short description can be found at |Q_op|. this option to a lower value if you run out of memory. *'updatecount'* *'uc'* -'updatecount' 'uc' number (default: 200) +'updatecount' 'uc' number (default 200) global After typing this many characters the swap file will be written to disk. When zero, no swap file will be created at all (see chapter on @@ -6893,7 +6822,7 @@ A jump table for the options with a short description can be found at |Q_op|. If 'verbosefile' is set then the verbose messages are not displayed. *'verbosefile'* *'vfile'* -'verbosefile' 'vfile' string (default empty) +'verbosefile' 'vfile' string (default "") global When not empty all messages are written in a file with this name. When the file exists messages are appended. @@ -6902,16 +6831,18 @@ A jump table for the options with a short description can be found at |Q_op|. Setting 'verbosefile' to a new value is like making it empty first. The difference with |:redir| is that verbose messages are not displayed when 'verbosefile' is set. + This option cannot be set from a |modeline| or in the |sandbox|, for + security reasons. *'viewdir'* *'vdir'* -'viewdir' 'vdir' string (default: "$XDG_STATE_HOME/nvim/view//") +'viewdir' 'vdir' string (default "$XDG_STATE_HOME/nvim/view//") global Name of the directory where to store files for |:mkview|. This option cannot be set from a |modeline| or in the |sandbox|, for security reasons. *'viewoptions'* *'vop'* -'viewoptions' 'vop' string (default: "folds,cursor,curdir") +'viewoptions' 'vop' string (default "folds,cursor,curdir") global Changes the effect of the |:mkview| command. It is a comma-separated list of words. Each word enables saving and restoring something: @@ -6926,7 +6857,7 @@ A jump table for the options with a short description can be found at |Q_op|. slash |deprecated| Always enabled. Uses "/" in filenames. unix |deprecated| Always enabled. Uses "\n" line endings. - *'virtualedit'* *'ve'* + *'virtualedit'* *'ve'* 'virtualedit' 've' string (default "") global or local to window |global-local| A comma-separated list of these words: @@ -6956,7 +6887,7 @@ A jump table for the options with a short description can be found at |Q_op|. not get a warning for it. When combined with other words, "none" is ignored. - *'visualbell'* *'vb'* *'novisualbell'* *'novb'* *beep* + *'visualbell'* *'vb'* *'novisualbell'* *'novb'* 'visualbell' 'vb' boolean (default off) global Use visual bell instead of beeping. Also see 'errorbells'. @@ -6968,7 +6899,7 @@ A jump table for the options with a short description can be found at |Q_op|. has been changed. *'whichwrap'* *'ww'* -'whichwrap' 'ww' string (default: "b,s") +'whichwrap' 'ww' string (default "b,s") global Allow specified keys that move the cursor left/right to move to the previous/next line when the cursor is on the first/last character in @@ -6998,7 +6929,7 @@ A jump table for the options with a short description can be found at |Q_op|. makes "dl", "cl", "yl" etc. work normally. *'wildchar'* *'wc'* -'wildchar' 'wc' number (default: <Tab>) +'wildchar' 'wc' number (default <Tab>) global Character you have to type to start wildcard expansion in the command-line, as specified with 'wildmode'. @@ -7006,12 +6937,14 @@ A jump table for the options with a short description can be found at |Q_op|. 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. + <Esc> can be used, but hitting it twice in a row will still exit + command-line as a failsafe measure. Although 'wc' is a number option, you can set it to a special key: > :set wc=<Tab> < *'wildcharm'* *'wcm'* -'wildcharm' 'wcm' number (default: none (0)) +'wildcharm' 'wcm' number (default 0) global 'wildcharm' works exactly like 'wildchar', except that it is recognized when used inside a macro. You can find "spare" command-line @@ -7037,8 +6970,7 @@ A jump table for the options with a short description can be found at |Q_op|. a pattern from the list. This avoids problems when a future version uses another default. - - *'wildignorecase'* *'wic'* *'nowildignorecase'* *'nowic'* + *'wildignorecase'* *'wic'* *'nowildignorecase'* *'nowic'* 'wildignorecase' 'wic' boolean (default off) global When set case is ignored when completing file names and directories. @@ -7046,8 +6978,7 @@ A jump table for the options with a short description can be found at |Q_op|. Does not apply when the shell is used to expand wildcards, which happens when there are special characters. - - *'wildmenu'* *'wmnu'* *'nowildmenu'* *'nowmnu'* + *'wildmenu'* *'wmnu'* *'nowildmenu'* *'nowmnu'* 'wildmenu' 'wmnu' boolean (default on) global When 'wildmenu' is on, command-line completion operates in an enhanced @@ -7065,18 +6996,21 @@ A jump table for the options with a short description can be found at |Q_op|. a completion. While the menu is active these keys have special meanings: - - CTRL-Y - accept the currently selected match and stop - completion. - CTRL-E - end completion, go back to what was there before - selecting a match. + CTRL-P - go to the previous entry + CTRL-N - go to the next entry <Left> <Right> - select previous/next match (like CTRL-P/CTRL-N) + <PageUp> - select a match several entries back + <PageDown> - select a match several entries further + <Up> - in filename/menu name completion: move up into + parent directory or parent menu. <Down> - in filename/menu name completion: move into a subdirectory or submenu. <CR> - in menu completion, when the cursor is just after a dot: move into a submenu. - <Up> - in filename/menu name completion: move up into - parent directory or parent menu. + CTRL-E - end completion, go back to what was there before + selecting a match. + CTRL-Y - accept the currently selected match and stop + completion. If you want <Left> and <Right> to move the cursor instead of selecting a different match, use this: > @@ -7086,7 +7020,7 @@ A jump table for the options with a short description can be found at |Q_op|. |hl-WildMenu| highlights the current match. *'wildmode'* *'wim'* -'wildmode' 'wim' string (default: "full") +'wildmode' 'wim' string (default "full") global Completion mode that is used for the character specified with 'wildchar'. It is a comma-separated list of up to four parts. Each @@ -7156,7 +7090,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'winaltkeys'* *'wak'* 'winaltkeys' 'wak' string (default "menu") global - {only used in Win32} + only used in Win32 Some GUI versions allow the access to menu entries by using the ALT key in combination with a character that appears underlined in the menu. This conflicts with the use of the ALT key for mappings and @@ -7173,7 +7107,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option is not used for <F10>; on Win32. *'winbar'* *'wbr'* -'winbar' 'wbr' string (default empty) +'winbar' 'wbr' string (default "") global or local to window |global-local| When non-empty, this option enables the window bar and determines its contents. The window bar is a bar that's shown at the top of every @@ -7190,7 +7124,7 @@ A jump table for the options with a short description can be found at |Q_op|. This option cannot be set in a modeline when 'modelineexpr' is off. *'winblend'* *'winbl'* -'winblend' 'winbl' number (default 0) +'winblend' 'winbl' number (default 0) local to window Enables pseudo-transparency for a floating window. Valid values are in the range of 0 for fully opaque window (disabled) to 100 for fully @@ -7198,8 +7132,8 @@ A jump table for the options with a short description can be found at |Q_op|. UI-dependent. Works best with RGB colors. 'termguicolors' - *'window'* *'wi'* -'window' 'wi' number (default screen height - 1) + *'window'* *'wi'* +'window' 'wi' number (default screen height - 1) global Window height used for |CTRL-F| and |CTRL-B| when there is only one window and the value is smaller than 'lines' minus one. The screen @@ -7211,6 +7145,21 @@ A jump table for the options with a short description can be found at |Q_op|. Note: Do not confuse this with the height of the Vim window, use 'lines' for that. + *'winfixheight'* *'wfh'* *'nowinfixheight'* *'nowfh'* +'winfixheight' 'wfh' boolean (default off) + local to window |local-noglobal| + Keep the window height when windows are opened or closed and + 'equalalways' is set. Also for |CTRL-W_=|. Set by default for the + |preview-window| and |quickfix-window|. + The height may be changed anyway when running out of room. + + *'winfixwidth'* *'wfw'* *'nowinfixwidth'* *'nowfw'* +'winfixwidth' 'wfw' boolean (default off) + local to window |local-noglobal| + Keep the window width when windows are opened or closed and + 'equalalways' is set. Also for |CTRL-W_=|. + The width may be changed anyway when running out of room. + *'winheight'* *'wh'* *E591* 'winheight' 'wh' number (default 1) global @@ -7231,8 +7180,8 @@ A jump table for the options with a short description can be found at |Q_op|. 'winheight' applies to the current window. Use 'winminheight' to set the minimal height for other windows. - *'winhighlight'* *'winhl'* -'winhighlight' 'winhl' string (default empty) + *'winhighlight'* *'winhl'* +'winhighlight' 'winhl' string (default "") local to window Window-local highlights. Comma-delimited list of highlight |group-name| pairs "{hl-from}:{hl-to},..." where each {hl-from} is @@ -7251,20 +7200,6 @@ A jump table for the options with a short description can be found at |Q_op|. Example: show a different color for non-current windows: > set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC < - *'winfixheight'* *'wfh'* *'nowinfixheight'* *'nowfh'* -'winfixheight' 'wfh' boolean (default off) - local to window - Keep the window height when windows are opened or closed and - 'equalalways' is set. Also for |CTRL-W_=|. Set by default for the - |preview-window| and |quickfix-window|. - The height may be changed anyway when running out of room. - - *'winfixwidth'* *'wfw'* *'nowinfixwidth'* *'nowfw'* -'winfixwidth' 'wfw' boolean (default off) - local to window - Keep the window width when windows are opened or closed and - 'equalalways' is set. Also for |CTRL-W_=|. - The width may be changed anyway when running out of room. *'winminheight'* *'wmh'* 'winminheight' 'wmh' number (default 1) @@ -7336,13 +7271,13 @@ A jump table for the options with a short description can be found at |Q_op|. When 'textwidth' is non-zero, this option is not used. See also 'formatoptions' and |ins-textwidth|. - *'wrapscan'* *'ws'* *'nowrapscan'* *'nows'* -'wrapscan' 'ws' boolean (default on) *E384* *E385* + *'wrapscan'* *'ws'* *'nowrapscan'* *'nows'* *E384* *E385* +'wrapscan' 'ws' boolean (default on) global Searches wrap around the end of the file. Also applies to |]s| and |[s|, searching for spelling mistakes. - *'write'* *'nowrite'* + *'write'* *'nowrite'* 'write' boolean (default on) global Allows writing files. When not set, writing a file is not allowed. @@ -7351,12 +7286,12 @@ A jump table for the options with a short description can be found at |Q_op|. argument. Filtering text is still possible, even though this requires writing a temporary file. - *'writeany'* *'wa'* *'nowriteany'* *'nowa'* + *'writeany'* *'wa'* *'nowriteany'* *'nowa'* 'writeany' 'wa' boolean (default off) global Allows writing to any file with no need for "!" override. - *'writebackup'* *'wb'* *'nowritebackup'* *'nowb'* + *'writebackup'* *'wb'* *'nowritebackup'* *'nowb'* 'writebackup' 'wb' boolean (default on) global Make a backup before overwriting a file. The backup is removed after @@ -7375,8 +7310,7 @@ A jump table for the options with a short description can be found at |Q_op|. *'writedelay'* *'wd'* 'writedelay' 'wd' number (default 0) global - The number of milliseconds to wait for each character sent to the - screen. When positive, characters are sent to the UI one by one. - See 'redrawdebug' for more options. For debugging purposes. + Only takes effect together with 'redrawdebug'. + The number of milliseconds to wait after each line or each flush vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/pattern.txt b/runtime/doc/pattern.txt index 5357aaa3f1..17136ee650 100644 --- a/runtime/doc/pattern.txt +++ b/runtime/doc/pattern.txt @@ -72,7 +72,7 @@ N Repeat the latest "/" or "?" [count] times in command "/\<keyword\>". |exclusive| 'ignorecase' is used, 'smartcase' is not. *v_star-default* - In Visual mode, search forward for the current selection. +{Visual}* In Visual mode, search forward for the current selection. |default-mappings| *#* @@ -81,7 +81,7 @@ N Repeat the latest "/" or "?" [count] times in backspace, try using "stty erase <BS>" before starting Vim (<BS> is CTRL-H or a real backspace). *v_#-default* - In Visual mode, search backward for the current selection. +{Visual}# In Visual mode, search backward for the current selection. |default-mappings| *gstar* @@ -97,6 +97,8 @@ g# Like "#", but don't put "\<" and "\>" around the word. *gd* gd Goto local Declaration. When the cursor is on a local variable, this command will jump to its declaration. + This was made to work for C code, in other languages + it may not work well. First Vim searches for the start of the current function, just like "[[". If it is not found the search stops in line 1. If it is found, Vim goes back @@ -430,8 +432,6 @@ after: \v \m \M \V matches ~ \\ \\ \\ \\ literal backslash \{ { { { literal curly brace -{only Vim supports \m, \M, \v and \V} - If you want to you can make a pattern immune to the 'magic' option being set or not by putting "\m" or "\M" at the start of the pattern. @@ -453,7 +453,7 @@ More explanation and examples below, follow the links. *E64* *E871* \{n} \{n} n exactly \{n,} \{n,} at least n as many as possible \{,m} \{,m} 0 to m as many as possible - \{} \{} 0 or more as many as possible (same as *) + \{} \{} 0 or more as many as possible (same as "*") |/\{-| \{-n,m} \{-n,m} n to m as few as possible \{-n} \{-n} n exactly @@ -631,7 +631,7 @@ overview. \{n} Matches n of the preceding atom \{n,} Matches at least n of the preceding atom, as many as possible \{,m} Matches 0 to m of the preceding atom, as many as possible -\{} Matches 0 or more of the preceding atom, as many as possible (like *) +\{} Matches 0 or more of the preceding atom, as many as possible (like "*") */\{-* \{-n,m} matches n to m of the preceding atom, as few as possible \{-n} matches n of the preceding atom @@ -1065,7 +1065,7 @@ match ASCII characters, as indicated by the range. \(\) A pattern enclosed by escaped parentheses. */\(* */\(\)* */\)* E.g., "\(^a\)" matches 'a' at the start of a line. - There can only be ten of these. You can use "\%(" to add more, but + There can only be nine of these. You can use "\%(" to add more, but not counting it as a sub-expression. *E51* *E54* *E55* *E872* *E873* @@ -1129,21 +1129,21 @@ x A single character, with no special meaning, matches itself are supported: Name Func Contents ~ *[:alnum:]* [:alnum:] isalnum ASCII letters and digits -*[:alpha:]* [:alpha:] isalpha ASCII letters -*[:blank:]* [:blank:] space and tab -*[:cntrl:]* [:cntrl:] iscntrl ASCII control characters -*[:digit:]* [:digit:] decimal digits '0' to '9' +*[:alpha:]* [:alpha:] isalpha ASCII letters +*[:blank:]* [:blank:] space and tab +*[:cntrl:]* [:cntrl:] iscntrl ASCII control characters +*[:digit:]* [:digit:] decimal digits '0' to '9' *[:graph:]* [:graph:] isgraph ASCII printable characters excluding space *[:lower:]* [:lower:] (1) lowercase letters (all letters when 'ignorecase' is used) -*[:print:]* [:print:] (2) printable characters including space +*[:print:]* [:print:] (2) printable characters including space *[:punct:]* [:punct:] ispunct ASCII punctuation characters -*[:space:]* [:space:] whitespace characters: space, tab, CR, +*[:space:]* [:space:] whitespace characters: space, tab, CR, NL, vertical tab, form feed *[:upper:]* [:upper:] (3) uppercase letters (all letters when 'ignorecase' is used) -*[:xdigit:]* [:xdigit:] hexadecimal digits: 0-9, a-f, A-F +*[:xdigit:]* [:xdigit:] hexadecimal digits: 0-9, a-f, A-F *[:return:]* [:return:] the <CR> character *[:tab:]* [:tab:] the <Tab> character *[:escape:]* [:escape:] the <Esc> character @@ -1254,7 +1254,6 @@ letters only. When "\c" appears anywhere in the pattern, the whole pattern is handled like 'ignorecase' is on. The actual value of 'ignorecase' and 'smartcase' is ignored. "\C" does the opposite: Force matching case for the whole pattern. -{only Vim supports \c and \C} Note that 'ignorecase', "\c" and "\C" are not used for the character classes. Examples: @@ -1296,7 +1295,6 @@ will probably never match. When "\Z" appears anywhere in the pattern, all composing characters are ignored. Thus only the base characters need to match, the composing characters may be different and the number of composing characters may differ. -Only relevant when 'encoding' is "utf-8". Exception: If the pattern starts with one or more composing characters, these must match. */\%C* @@ -1337,11 +1335,10 @@ difference between them is mostly just notation; here's a summary of where they differ: Capability in Vimspeak in Perlspeak ~ ----------------------------------------------------------------- force case insensitivity \c (?i) force case sensitivity \C (?-i) backref-less grouping \%(atom\) (?:atom) -conservative quantifiers \{-n,m} *?, +?, ??, {}? +conservative quantifiers \{-n,m} `*?,` +?, ??, {}? 0-width match atom\@= (?=atom) 0-width non-match atom\@! (?!atom) 0-width preceding match atom\@<= (?<=atom) @@ -1445,10 +1442,11 @@ Finally, these constructs are unique to Perl: Just like |:match| above, but set a separate match. Thus there can be three matches active at the same time. The match with the lowest number has priority if several match at the - same position. - The ":3match" command is used by the |matchparen| plugin. You - are suggested to use ":match" for manual matching and - ":2match" for another plugin. + same position. It uses the match id 3. + The ":3match" command is used by (older Vims) |matchparen| + plugin. You are suggested to use ":match" for manual matching + and ":2match" for another plugin or even better make use of + the more flexible |matchadd()| (and similar) functions instead. ============================================================================== 11. Fuzzy matching *fuzzy-matching* diff --git a/runtime/doc/pi_gzip.txt b/runtime/doc/pi_gzip.txt index 0363a8e34a..93a2388c26 100644 --- a/runtime/doc/pi_gzip.txt +++ b/runtime/doc/pi_gzip.txt @@ -12,6 +12,14 @@ The functionality mentioned here is a |standard-plugin|. This plugin is only available if 'compatible' is not set. You can avoid loading this plugin by setting the "loaded_gzip" variable: > :let loaded_gzip = 1 +< + *g:gzip_exec* + +For security reasons, one may prevent that Vim runs executables automatically +when opening a buffer. This option (default: "1") can be used to prevent +executing the executables command when set to "0": > + :let g:gzip_exec = 0 +< ============================================================================== 1. Autocommands *gzip-autocmd* @@ -19,7 +27,7 @@ You can avoid loading this plugin by setting the "loaded_gzip" variable: > The plugin installs autocommands to intercept reading and writing of files with these extensions: - extension compression ~ + extension compression > *.Z compress (Lempel-Ziv) *.gz gzip *.bz2 bzip2 diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt index 5ba5d1beef..bcc933d8b2 100644 --- a/runtime/doc/pi_health.txt +++ b/runtime/doc/pi_health.txt @@ -12,7 +12,7 @@ any other environment conditions that a plugin might care about. Nvim ships with healthchecks for configuration, performance, python support, ruby support, clipboard support, and more. -To run all healthchecks, use: > +To run all healthchecks, use: >vim :checkhealth < @@ -21,7 +21,7 @@ Plugin authors are encouraged to write new healthchecks. |health-dev| ============================================================================== Commands *health-commands* - *:che* *:checkhealth* *:CheckHealth* + *:che* *:checkhealth* :che[ckhealth] Run all healthchecks. *E5009* Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to @@ -32,17 +32,17 @@ Commands *health-commands* :che[ckhealth] {plugins} Run healthcheck(s) for one or more plugins. E.g. to run only - the standard Nvim healthcheck: > + the standard Nvim healthcheck: >vim :checkhealth nvim < To run the healthchecks for the "foo" and "bar" plugins (assuming they are on 'runtimepath' and they have implemented - the Lua `require("foo.health").check()` interface): > + the Lua `require("foo.health").check()` interface): >vim :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`: > + `vim.lsp` and `vim.treesitter`: >vim :checkhealth vim.lsp vim.treesitter :checkhealth vim* < @@ -52,22 +52,22 @@ Functions *health-functions* *vim.health* The Lua "health" module can be used to create new healthchecks. To get started see |health-dev|. -vim.health.report_start({name}) *vim.health.report_start()* +vim.health.start({name}) *vim.health.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. -vim.health.report_info({msg}) *vim.health.report_info()* +vim.health.info({msg}) *vim.health.info()* Reports an informational message. -vim.health.report_ok({msg}) *vim.health.report_ok()* +vim.health.ok({msg}) *vim.health.ok()* Reports a "success" message. -vim.health.report_warn({msg} [, {advice}]) *vim.health.report_warn()* +vim.health.warn({msg} [, {advice}]) *vim.health.warn()* Reports a warning. {advice} is an optional list of suggestions to present to the user. -vim.health.report_error({msg} [, {advice}]) *vim.health.report_error()* +vim.health.error({msg} [, {advice}]) *vim.health.error()* Reports an error. {advice} is an optional list of suggestions to present to the user. @@ -100,17 +100,17 @@ All such health modules must return a Lua table containing a `check()` function. Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path -with your plugin name: > +with your plugin name: >lua local M = {} M.check = function() - vim.health.report_start("my_plugin report") + vim.health.start("foo report") -- make sure setup function parameters are ok if check_setup() then - vim.health.report_ok("Setup is correct") + vim.health.ok("Setup is correct") else - vim.health.report_error("Setup is incorrect") + vim.health.error("Setup is incorrect") end -- do some more checking -- ... diff --git a/runtime/doc/pi_msgpack.txt b/runtime/doc/pi_msgpack.txt index 24a31f1de7..e900af97a8 100644 --- a/runtime/doc/pi_msgpack.txt +++ b/runtime/doc/pi_msgpack.txt @@ -3,13 +3,13 @@ Author: Nikolay Pavlov <kp-pav@yandex.ru> Copyright: (c) 2015 by Nikolay Pavlov -The Apache license applies to the files in this package, including -runtime/autoload/msgpack.vim, runtime/doc/pi_msgpack.txt and -test/functional/plugin/msgpack_spec.lua. Like anything else that's free, -msgpack.vim and its associated files are provided *as is* and comes with no -warranty of any kind, either expressed or implied. No guarantees of -merchantability. No guarantees of suitability for any purpose. By using this -plugin, you agree that in no event will the copyright holder be liable for any +The Apache license applies to the files in this package, including +runtime/autoload/msgpack.vim, runtime/doc/pi_msgpack.txt and +test/functional/plugin/msgpack_spec.lua. Like anything else that's free, +msgpack.vim and its associated files are provided as is and comes with no +warranty of any kind, either expressed or implied. No guarantees of +merchantability. No guarantees of suitability for any purpose. By using this +plugin, you agree that in no event will the copyright holder be liable for any damages resulting from the use of this software. Use at your own risk! ============================================================================== @@ -35,7 +35,7 @@ damages resulting from the use of this software. Use at your own risk! ============================================================================== 2. Msgpack.vim introduction *msgpack.vim-intro* -This plugin contains utility functions to be used in conjunction with +This plugin contains utility functions to be used in conjunction with |msgpackdump()| and |msgpackparse()| functions. ============================================================================== @@ -43,13 +43,13 @@ This plugin contains utility functions to be used in conjunction with FUNCTION ARGUMENTS *msgpack.vim-arguments* -Disambiguation of arguments described below. Note: if e.g. function is listed -as accepting |{msgpack-integer}| (or anything else) it means that function +Disambiguation of arguments described below. Note: if e.g. function is listed +as accepting |{msgpack-integer}| (or anything else) it means that function does not check whether argument matches its description. -*{msgpack-value}* Either |msgpack-special-dict| or a regular value, but +*{msgpack-value}* Either |msgpack-special-dict| or a regular value, but not function reference. -*{msgpack-integer}* Any value for which |msgpack#type()| will return +*{msgpack-integer}* Any value for which |msgpack#type()| will return "integer". *{msgpack-special-int}* |msgpack-special-dict| representing integer. @@ -57,87 +57,87 @@ msgpack#is_int({msgpack-value}) *msgpack#is_int()* Returns 1 if given {msgpack-value} is integer value, 0 otherwise. msgpack#is_uint({msgpack-value}) *msgpack#is_uint()* - Returns 1 if given {msgpack-value} is integer value greater or equal + Returns 1 if given {msgpack-value} is integer value greater or equal to zero, 0 otherwise. *msgpack#strftime* msgpack#strftime({format}, {msgpack-integer}) *msgpack#strftime()* - Same as |strftime()|, but second argument may be + Same as |strftime()|, but second argument may be |msgpack-special-dict|. Requires |Python| to really work with |msgpack-special-dict|s. *msgpack#strptime* msgpack#strptime({format}, {time}) *msgpack#strptime()* - Reverse of |msgpack#strftime()|: for any time and format - |msgpack#equal|( |msgpack#strptime|(format, |msgpack#strftime|(format, + Reverse of |msgpack#strftime()|: for any time and format + |msgpack#equal|( |msgpack#strptime|(format, |msgpack#strftime|(format, time)), time) be true. Requires ||Python|, without it only supports non-|msgpack-special-dict| nonnegative times and format equal to `%Y-%m-%dT%H:%M:%S`. msgpack#int_dict_to_str({msgpack-special-int}) *msgpack#int_dict_to_str()* - Function which converts |msgpack-special-dict| integer value to - a hexadecimal value like 0x1234567890ABCDEF (always returns exactly 16 + Function which converts |msgpack-special-dict| integer value to + a hexadecimal value like 0x1234567890ABCDEF (always returns exactly 16 hexadecimal digits). msgpack#special_type({msgpack-value}) *msgpack#special_type()* - Returns zero if {msgpack-value} is not |msgpack-special-dict|. If it - is it returns name of the key in |v:msgpack_types| which represents + Returns zero if {msgpack-value} is not |msgpack-special-dict|. If it + is it returns name of the key in |v:msgpack_types| which represents {msgpack-value} type. msgpack#type({msgpack-value}) *msgpack#type()* - Returns name of the key in |v:msgpack_types| that represents - {msgpack-value} type. Never returns zero: this function returns - msgpack type which will be dumped by |msgpackdump()| should it receive + Returns name of the key in |v:msgpack_types| that represents + {msgpack-value} type. Never returns zero: this function returns + msgpack type which will be dumped by |msgpackdump()| should it receive a list with single {msgpack-value} as input. msgpack#deepcopy({msgpack-value}) *msgpack#deepcopy()* - Like |deepcopy()|, but works correctly with |msgpack-special-dict| - values. Plain |deepcopy()| will destroy all types in - |msgpack-special-dict| values because it will copy _TYPE key values, + Like |deepcopy()|, but works correctly with |msgpack-special-dict| + values. Plain |deepcopy()| will destroy all types in + |msgpack-special-dict| values because it will copy _TYPE key values, while they should be preserved. msgpack#string({msgpack-value}) *msgpack#string()* - Like |string()|, but saves information about msgpack types. Values - dumped by msgpack#string may be read back by |msgpack#eval()|. + Like |string()|, but saves information about msgpack types. Values + dumped by msgpack#string may be read back by |msgpack#eval()|. Returns is the following: - - Dictionaries are dumped as "{key1: value1, key2: value2}". Note: - msgpack allows any values in keys, so with some - |msgpack-special-dict| values |msgpack#string()| may produce even + - Dictionaries are dumped as "{key1: value1, key2: value2}". Note: + msgpack allows any values in keys, so with some + |msgpack-special-dict| values |msgpack#string()| may produce even "{{1: 2}: 3, [4]: 5}". - Lists are dumped as "[value1, value2]". - Strings are dumped as 1. `"abc"`: binary string. 2. `="abc"`: string. - 3. `+(10)"ext"`: extension strings (10 may be replaced with any + 3. `+(10)"ext"`: extension strings (10 may be replaced with any 8-bit signed integer). - Inside strings the following escape sequences may be present: "\0" - (represents NUL byte), "\n" (represents line feed) and "\"" + Inside strings the following escape sequences may be present: "\0" + (represents NUL byte), "\n" (represents line feed) and "\"" (represents double quote). - - Floating-point and integer values are dumped using |string()| or + - Floating-point and integer values are dumped using |string()| or |msgpack#int_dict_to_str()|. - Booleans are dumped as "TRUE" or "FALSE". - Nil values are dumped as "NIL". msgpack#eval({string}, {dict}) *msgpack#eval()* - Transforms string created by |msgpack#string()| into a value suitable - for |msgpackdump()|. Second argument allows adding special values - that start with head characters (|/\h|) and contain only word - characters (|/\w|). Built-in special values are "TRUE", "FALSE", - "NIL", "nan" and "inf" and they cannot be overridden. Map values are - always evaluated to |msgpack-special-dict| values, as well as + Transforms string created by |msgpack#string()| into a value suitable + for |msgpackdump()|. Second argument allows adding special values + that start with head characters (|/\h|) and contain only word + characters (|/\w|). Built-in special values are "TRUE", "FALSE", + "NIL", "nan" and "inf" and they cannot be overridden. Map values are + always evaluated to |msgpack-special-dict| values, as well as hexadecimal digits. When evaluating maps order of keys is preserved. - Note that in addition to regular integer representations that may be - obtained using |msgpack#string()| msgpack#eval() also supports C-style - “character” integer constants like `'/'` (equivalent to + Note that in addition to regular integer representations that may be + obtained using |msgpack#string()| msgpack#eval() also supports C-style + “character” integer constants like `'/'` (equivalent to `char2nr('/')`: `47`). This also allows `'\0'` (number is decimal). *msgpack#equal* msgpack#equal({msgpack-value}, {msgpack-value}) *msgpack#equal()* - Returns 1 if given values are equal, 0 otherwise. When comparing - msgpack map values order of keys is ignored. Comparing - |msgpack-special-dict| with equivalent non-special-dict value + Returns 1 if given values are equal, 0 otherwise. When comparing + msgpack map values order of keys is ignored. Comparing + |msgpack-special-dict| with equivalent non-special-dict value evaluates to 1. ============================================================================== diff --git a/runtime/doc/pi_netrw.txt b/runtime/doc/pi_netrw.txt index 5167b4baf7..85ac290361 100644 --- a/runtime/doc/pi_netrw.txt +++ b/runtime/doc/pi_netrw.txt @@ -91,7 +91,6 @@ Copyright: Copyright (C) 2017 Charles E Campbell *netrw-copyright* Marked Files: Grep..................................|netrw-mg| Marked Files: Hiding and Unhiding by Suffix.........|netrw-mh| Marked Files: Moving................................|netrw-mm| - Marked Files: Printing..............................|netrw-mp| Marked Files: Sourcing..............................|netrw-ms| Marked Files: Setting the Target Directory..........|netrw-mt| Marked Files: Tagging...............................|netrw-mT| @@ -208,7 +207,7 @@ EXTERNAL APPLICATIONS AND PROTOCOLS *netrw-externapp* {{{2 http: g:netrw_http_cmd = "links" elseif links is available http: g:netrw_http_cmd = "curl" elseif curl is available http: g:netrw_http_cmd = "wget" elseif wget is available - http: g:netrw_http_cmd = "fetch" elseif fetch is available + http: g:netrw_http_cmd = "fetch" elseif fetch is available http: *g:netrw_http_put_cmd* = "curl -T" rcp: *g:netrw_rcp_cmd* = "rcp" rsync: *g:netrw_rsync_cmd* = "rsync" (see |g:netrw_rsync_sep|) @@ -440,12 +439,10 @@ settings are described below, in |netrw-browser-options|, and in *g:netrw_use_errorwindow* =2: messages from netrw will use a popup window Move the mouse and pause to remove the popup window. - (default value if popup windows are available) =1 : messages from netrw will use a separate one line window. This window provides reliable delivery of messages. - (default value if popup windows are not available) - =0 : messages from netrw will use echoerr ; + =0 : (default) messages from netrw will use echoerr ; messages don't always seem to show up this way, but one doesn't have to quit the window. @@ -1085,8 +1082,8 @@ QUICK REFERENCE: MAPS *netrw-browse-maps* {{{2 <c-tab> Shrink/expand a netrw/explore window |netrw-c-tab| - Makes Netrw go up one directory |netrw--| a Cycles between normal display, |netrw-a| - hiding (suppress display of files matching g:netrw_list_hide) - and showing (display only files which match g:netrw_list_hide) + hiding (suppress display of files matching g:netrw_list_hide) + and showing (display only files which match g:netrw_list_hide) cd Make browsing directory the current directory |netrw-cd| C Setting the editing window |netrw-C| d Make a directory |netrw-d| @@ -1108,7 +1105,6 @@ QUICK REFERENCE: MAPS *netrw-browse-maps* {{{2 mg Apply vimgrep to marked files |netrw-mg| mh Toggle marked file suffices' presence on hiding list |netrw-mh| mm Move marked files to marked-file target directory |netrw-mm| - mp Print marked files |netrw-mp| mr Mark files using a shell-style |regexp| |netrw-mr| mt Current browsing directory becomes markfile target |netrw-mt| mT Apply ctags to marked files |netrw-mT| @@ -1118,7 +1114,7 @@ QUICK REFERENCE: MAPS *netrw-browse-maps* {{{2 mX Apply arbitrary shell command to marked files en bloc|netrw-mX| mz Compress/decompress marked files |netrw-mz| o Enter the file/directory under the cursor in a new |netrw-o| - browser window. A horizontal split is used. + browser window. A horizontal split is used. O Obtain a file specified by cursor |netrw-O| p Preview the file |netrw-p| P Browse in the previously used window |netrw-P| @@ -1134,7 +1130,7 @@ QUICK REFERENCE: MAPS *netrw-browse-maps* {{{2 u Change to recently-visited directory |netrw-u| U Change to subsequently-visited directory |netrw-U| v Enter the file/directory under the cursor in a new |netrw-v| - browser window. A vertical split is used. + browser window. A vertical split is used. x View file with an associated program |netrw-x| X Execute filename under cursor via |system()| |netrw-X| @@ -2154,7 +2150,6 @@ The following netrw maps make use of marked files: |netrw-mF| Unmark marked files |netrw-mg| Apply vimgrep to marked files |netrw-mm| Move marked files to target - |netrw-mp| Print marked files |netrw-ms| Netrw will source marked files |netrw-mt| Set target for |netrw-mm| and |netrw-mc| |netrw-mT| Generate tags using marked files @@ -2271,7 +2266,7 @@ Example: ... -MARKED FILES, ARBITRARY SHELL COMMAND, EN BLOC *netrw-mX* {{{2 +MARKED FILES, ARBITRARY SHELL COMMAND, EN BLOC *netrw-mX* {{{2 (See |netrw-mf| and |netrw-mr| for how to mark files) (uses the global marked-file list) @@ -2611,7 +2606,7 @@ your browsing preferences. (see also: |netrw-settings|) Used to change access permission for a file. *g:netrw_clipboard* =1 - By default, netrw will attempt to insure that + By default, netrw will attempt to insure that the clipboard's values will remain unchanged. However, some users report that they have speed problems with this; consequently, this @@ -2759,7 +2754,7 @@ your browsing preferences. (see also: |netrw-settings|) escaped before applying glob() *g:netrw_gx* ="<cfile>" - This option controls how gx (|netrw-gx|) picks + This option controls how gx (|netrw-gx|) picks up the text under the cursor. See |expand()| for possibilities. @@ -2824,11 +2819,11 @@ your browsing preferences. (see also: |netrw-settings|) directory (|netrw-mt|, |netrw-mc|) *g:netrw_localcopycmdopt* ='' Linux/Unix/MacOS/Cygwin - =' \c copy' Windows + =' \c copy' Windows Options for the |g:netrw_localcopycmd| *g:netrw_localcopydircmd* ="cp" Linux/Unix/MacOS/Cygwin - =expand("$COMSPEC") Windows + =expand("$COMSPEC") Windows Copies directories to target directory. (|netrw-mc|, |netrw-mt|) @@ -2854,17 +2849,13 @@ your browsing preferences. (see also: |netrw-settings|) Options for |g:netrw_localmovecmd| *g:netrw_localrmdir* ="rmdir" Linux/Unix/MacOS/Cygwin - =expand("$COMSPEC") Windows + =expand("$COMSPEC") Windows Remove directory command (rmdir) This variable is only used if your vim is earlier than 7.4 or if your vim doesn't have patch#1107. Otherwise, |delete()| is used with the "d" option. - *g:netrw_localrmdiropt* ="" Linux/Unix/MacOS/Cygwin - =" /c rmdir" Windows - Options for |g:netrw_localrmdir| - *g:netrw_maxfilenamelen* =32 by default, selected so as to make long listings fit on 80 column displays. If your screen is wider, and you have file @@ -2890,10 +2881,10 @@ your browsing preferences. (see also: |netrw-settings|) (see |'ballooneval'|) *g:netrw_sizestyle* not defined: actual bytes (default) - ="b" : actual bytes (default) - ="h" : human-readable (ex. 5k, 4m, 3g) + ="b" : actual bytes (default) + ="h" : human-readable (ex. 5k, 4m, 3g) uses 1000 base - ="H" : human-readable (ex. 5K, 4M, 3G) + ="H" : human-readable (ex. 5K, 4M, 3G) uses 1024 base The long listing (|netrw-i|) and query-file maps (|netrw-qf|) will display file size @@ -2941,7 +2932,7 @@ your browsing preferences. (see also: |netrw-settings|) default: "NETRWSERVER" *g:netrw_sort_by* sort by "name", "time", "size", or - "exten". + "exten". default: "name" *g:netrw_sort_direction* sorting direction: "normal" or "reverse" @@ -2998,7 +2989,7 @@ your browsing preferences. (see also: |netrw-settings|) .vim/after/syntax/netrw.vim. < The netrwGray highlighting is set up by netrw when > - * netrwGray has not been previously + * netrwGray has not been previously defined * the gui is running < As an example, I myself use a dark-background @@ -3256,7 +3247,7 @@ If there are marked files: (see |netrw-mf|) name, applying that substitute, and renaming each file to the result. As an example : > - mr [query: reply with *.c] + mr [query: reply with *.c] R [query: reply with s/^\(.*\)\.c$/\1.cpp/] < This example will mark all "*.c" files and then rename them to "*.cpp" @@ -3265,7 +3256,7 @@ If there are marked files: (see |netrw-mf|) The ctrl-X character has special meaning for renaming files: > - <c-x> : a single ctrl-x tells netrw to ignore the portion of the response + <c-x> : a single ctrl-x tells netrw to ignore the portion of the response lying between the last '/' and the ctrl-x. <c-x><c-x> : a pair of contiguous ctrl-x's tells netrw to ignore any @@ -3833,7 +3824,7 @@ netrw: Decho.vim is provided as a "vimball". You should edit the Decho.vba.gz file and source it in: > - vim Decho.vba.gz + vim Decho.vba.gz :so % :q < @@ -3875,7 +3866,7 @@ netrw: To save the file: under linux, the output will be in a separate remote server window; in it, just save the file with > - :w! DBG + :w! DBG < Under a vim that doesn't support clientserver, your debugging output will appear in another tab: > @@ -3901,6 +3892,8 @@ netrw: ============================================================================== 12. History *netrw-history* {{{1 + v172: Apr 22, 2023 * removed g:netrw_localrmdiropt + removed g:netrw_localrmdir v171: Oct 09, 2020 * included code in s:NetrwOptionsSafe() to allow |'bh'| to be set to delete when rather than hide when g:netrw_fastbrowse @@ -3985,8 +3978,10 @@ netrw: Nov 09, 2016 * Broke apart the command from the options, mostly for Windows. Introduced new netrw settings: |g:netrw_localcopycmdopt| - |g:netrw_localcopydircmdopt| |g:netrw_localmkdiropt| - |g:netrw_localmovecmdopt| |g:netrw_localrmdiropt| + |g:netrw_localcopydircmdopt| + |g:netrw_localmkdiropt| + |g:netrw_localmovecmdopt| + g:netrw_localrmdiropt Nov 21, 2016 * (mattn) provided a patch for preview; swapped winwidth() with winheight() Nov 22, 2016 * (glacambre) reported that files containing @@ -4129,7 +4124,7 @@ netrw: The "<nowait>" modifier has been included with most of netrw's mappings to avoid that delay. - Jun 26, 2015 * |netrw-gn| mapping implemted + Jun 26, 2015 * |netrw-gn| mapping implemented * :Ntree NotADir resulted in having the tree listing expand in the error messages window. Fixed. @@ -4336,8 +4331,8 @@ netrw: Dec 24, 2013 * (esquifit) asked that netrw allow the /cygdrive prefix be a user-alterable parameter. - Jan 02, 2014 * Fixed a problem with netrw-based ballon - evaluation (ie. netrw#NetrwBaloonHelp() + Jan 02, 2014 * Fixed a problem with netrw-based balloon + evaluation (ie. netrw#NetrwBalloonHelp() not having been loaded error messages) Jan 03, 2014 * Fixed a problem with tree listings * New command installed: |:Ntree| diff --git a/runtime/doc/pi_tar.txt b/runtime/doc/pi_tar.txt index 2230b82dec..dd1edb5707 100644 --- a/runtime/doc/pi_tar.txt +++ b/runtime/doc/pi_tar.txt @@ -11,7 +11,7 @@ Copyright 2005-2017: *tar-copyright* package, including tarPlugin.vim, tar.vim, and pi_tar.txt. Like anything else that's except use "tar.vim" instead of "VIM". Like anything else that's free, tar.vim and its associated files are - provided *as is* and comes with no warranty of any kind, either + provided as is and comes with no warranty of any kind, either expressed or implied. No guarantees of merchantability. No guarantees of suitability for any purpose. By using this plugin, you agree that in no event will the copyright holder be liable for any @@ -27,29 +27,12 @@ Copyright 2005-2017: *tar-copyright* ============================================================================== 2. Usage *tar-usage* *tar-manual* - When one edits a *.tar file, this plugin will handle displaying a + When one edits a `*.tar` file, this plugin will handle displaying a contents page. Select a file to edit by moving the cursor atop the desired file, then hit the <return> key. After editing, one may also write to the file. Currently, one may not make a new file in tar archives via the plugin. - *:Vimuntar* - VIMUNTAR~ - - :Vimuntar [vimhome] - - This command copies, if necessary, the tarball to the .vim or vimfiles - directory using the first writable directory in the |'runtimepath'| - when no [vimhome] is specified. Otherwise, the [vimhome] argument - allows the user to specify that directory, instead. - - The copy is done using the command in *g:tar_copycmd* , which is > - cp for cygwin, unix, macunix - copy for windows (32, 95, 64, 16) -< The extraction is done with the command specified with - *g:tar_extractcmd* , which by default is > - "tar -xf" -< *:TarDiff* DIFFERENCING SUPPORT~ @@ -61,8 +44,8 @@ Copyright 2005-2017: *tar-copyright* the file mentioned in the tarball. If the current directory is not correct for that path, :TarDiff will fail to find the associated file. - If the [filename] is given, that that filename (and path) will be used - to specify the associated file. + If the [filename] is given, that filename (and path) will be used to + specify the associated file. PREVENTING LOADING~ @@ -138,8 +121,8 @@ Copyright 2005-2017: *tar-copyright* May 28, 2008 * various security improvements. Now requires patch 299 which provides the fnameescape() function - May 30, 2008 * allows one to view *.gz and *.bz2 files that - are in *.tar files. + May 30, 2008 * allows one to view `*.gz` and `*.bz2` files that + are in `*.tar` files. v12 Sep 07, 2007 * &shq now used if not the empty string for g:tar_shq v10 May 02, 2006 * now using "redraw then echo" to show messages, diff --git a/runtime/doc/pi_zip.txt b/runtime/doc/pi_zip.txt index 9b531d78b4..a8e1b8df10 100644 --- a/runtime/doc/pi_zip.txt +++ b/runtime/doc/pi_zip.txt @@ -10,7 +10,7 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* The VIM LICENSE (see |copyright|) applies to the files in this package, including zipPlugin.vim, zip.vim, and pi_zip.vim. except use "zip.vim" instead of "VIM". Like anything else that's free, zip.vim - and its associated files are provided *as is* and comes with no + and its associated files are provided as is and comes with no warranty of any kind, either expressed or implied. No guarantees of merchantability. No guarantees of suitability for any purpose. By using this plugin, you agree that in no event will the copyright @@ -27,7 +27,7 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* ============================================================================== 2. Usage *zip-usage* *zip-manual* - When one edits a *.zip file, this plugin will handle displaying a + When one edits a `*.zip` file, this plugin will handle displaying a contents page. Select a file to edit by moving the cursor atop the desired file, then hit the <return> key. After editing, one may also write to the file. Currently, one may not make a new file in @@ -70,6 +70,13 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* extract a file from a zip archive. By default, > let g:zip_extractcmd= g:zip_unzipcmd < + *g:zip_exec* + For security reasons, one may prevent that Vim runs executables + automatically when opening a buffer. This option (default: "1") + can be used to prevent executing the "unzip" command when set to + "0": > + let g:zip_exec=0 +< PREVENTING LOADING~ If for some reason you do not wish to use vim to examine zipped files, @@ -102,6 +109,7 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* ============================================================================== 4. History *zip-history* {{{1 + v33 Dec 07, 2021 * `*.xlam` mentioned twice in zipPlugin v32 Oct 22, 2021 * to avoid an issue with a vim 8.2 patch, zipfile: has been changed to zipfile:// . This often shows up as zipfile:/// with zipped files that are root-based. @@ -113,8 +121,8 @@ Copyright: Copyright (C) 2005-2015 Charles E Campbell *zip-copyright* the command actually to be attempted in zip#Read() and zip#Write() * added the extraction of a file capability - Nov 30, 2015 * added *.epub to the |g:zipPlugin_ext| list - Sep 13, 2016 * added *.apk to the |g:zipPlugin_ext| list and + Nov 30, 2015 * added `*.epub` to the |g:zipPlugin_ext| list + Sep 13, 2016 * added `*.apk` to the |g:zipPlugin_ext| list and sorted the suffices. v27 Jul 02, 2013 * sanity check: zipfile must have "PK" as its first two bytes. diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index 5375d971f0..b8182347f8 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -4,7 +4,7 @@ NVIM REFERENCE MANUAL by Thiago de Arruda -Providers *provider* +Providers *provider* Nvim delegates some features to dynamic "providers". This document describes the providers and how to install them. @@ -66,7 +66,7 @@ To disable Python 3 support: >vim PYTHON VIRTUALENVS ~ *python-virtualenv* If you plan to use per-project virtualenvs often, you should assign one -virtualenv for Neovim and hard-code the interpreter path via +virtualenv for Nvim and hard-code the interpreter path via |g:python3_host_prog| so that the "pynvim" package is not required for each virtualenv. @@ -82,7 +82,7 @@ The last command reports the interpreter path, add it to your init.vim: >vim See also: https://github.com/zchee/deoplete-jedi/wiki/Setting-up-Python-for-Neovim ============================================================================== -Ruby integration *provider-ruby* +Ruby integration *provider-ruby* Nvim supports Ruby |remote-plugin|s and the Vim legacy |ruby-vim| interface (which is itself implemented as a Nvim remote-plugin). @@ -169,7 +169,7 @@ can be slow. To avoid this, set g:node_host_prog to the host path: >vim let g:node_host_prog = '/usr/local/bin/neovim-node-host' < ============================================================================== -Clipboard integration *provider-clipboard* *clipboard* +Clipboard integration *provider-clipboard* *clipboard* Nvim has no direct connection to the system clipboard. Instead it depends on a |provider| which transparently uses shell commands to communicate with the @@ -182,15 +182,15 @@ the "+" and/or "*" registers explicitly): >vim See 'clipboard' for details and options. *clipboard-tool* -The presence of a working clipboard tool implicitly enables the '+' and '*' +The presence of a working clipboard tool implicitly enables the '+' and "*" registers. Nvim looks for these clipboard tools, in order of priority: - |g:clipboard| - pbcopy, pbpaste (macOS) - wl-copy, wl-paste (if $WAYLAND_DISPLAY is set) - waycopy, waypaste (if $WAYLAND_DISPLAY is set) - - xclip (if $DISPLAY is set) - xsel (if $DISPLAY is set) + - xclip (if $DISPLAY is set) - lemonade (for SSH) https://github.com/pocke/lemonade - doitclient (for SSH) https://www.chiark.greenend.org.uk/~sgtatham/doit/ - win32yank (Windows) @@ -253,9 +253,50 @@ For Windows WSL, try this g:clipboard definition: \ }, \ 'cache_enabled': 0, \ } - +< + *clipboard-osc52* +Nvim bundles a clipboard provider that allows copying to the system clipboard +using OSC 52. OSC 52 is an Operating System Command control sequence that +writes the copied text to the terminal emulator. If the terminal emulator +supports OSC 52 then it will write the copied text into the system clipboard. + +Nvim will attempt to automatically determine if the host terminal emulator +supports the OSC 52 sequence and enable the OSC 52 clipboard provider if it +does as long as all of the following are true: + + • Nvim is running in the |TUI| + • |g:clipboard| is unset + • 'clipboard' is not set to "unnamed" or "unnamedplus" + • $SSH_TTY is set + +If any of the above conditions are not met then the OSC 52 clipboard provider +will not be used by default and Nvim will fall back to discovering a +|clipboard-tool| through the usual process. + +To force Nvim to use the OSC 52 provider you can use the following +|g:clipboard| definition: >lua + + vim.g.clipboard = { + name = 'OSC 52', + copy = { + ['+'] = require('vim.ui.clipboard.osc52').copy('+'), + ['*'] = require('vim.ui.clipboard.osc52').copy('*'), + }, + paste = { + ['+'] = require('vim.ui.clipboard.osc52').paste('+'), + ['*'] = require('vim.ui.clipboard.osc52').paste('*'), + }, + } +< +Note that not all terminal emulators support reading from the system clipboard +(and even for those that do, users should be aware of the security +implications), so using OSC 52 for pasting may not be possible (and not +necessary, because you can |paste| instead using your system paste function). +Users may need to configure their terminal emulator to allow reading from the +clipboard. +< ============================================================================== -Paste *provider-paste* *paste* +Paste *provider-paste* *paste* "Paste" is a separate concept from |clipboard|: paste means "dump a bunch of text to the editor", whereas clipboard provides features like |quote+| to get diff --git a/runtime/doc/quickfix.txt b/runtime/doc/quickfix.txt index b1f7c927cc..4428ff2f65 100644 --- a/runtime/doc/quickfix.txt +++ b/runtime/doc/quickfix.txt @@ -353,8 +353,6 @@ processing a quickfix or location list command, it will be aborted. If numbers [from] and/or [to] are given, the respective range of errors is listed. A negative number counts from the last error backwards, -1 being the last error. - The 'switchbuf' settings are respected when jumping - to a buffer. The |:filter| command can be used to display only the quickfix entries matching a supplied pattern. The pattern is matched against the filename, module name, @@ -869,11 +867,11 @@ lists. They set one of the existing error lists as the current one. *:chistory* *:chi* :[count]chi[story] Show the list of error lists. The current list is - marked with ">". The output looks like: - error list 1 of 3; 43 errors :make ~ - > error list 2 of 3; 0 errors :helpgrep tag ~ - error list 3 of 3; 15 errors :grep ex_help *.c ~ - + marked with ">". The output looks like: > + error list 1 of 3; 43 errors :make + > error list 2 of 3; 0 errors :helpgrep tag + error list 3 of 3; 15 errors :grep ex_help *.c +< When [count] is given, then the count'th quickfix list is made the current list. Example: > " Make the 4th quickfix list current @@ -958,7 +956,7 @@ or simpler > "$*" can be given multiple times, for example: > :set makeprg=gcc\ -o\ $*\ $* -The 'shellpipe' option defaults to ">%s 2>&1" for Win32. +The 'shellpipe' option defaults to "2>&1| tee" for Win32. This means that the output of the compiler is saved in a file and not shown on the screen directly. For Unix "| tee" is used. The compiler output is shown on the screen and saved in a file the same time. Depending on the shell used @@ -1248,7 +1246,7 @@ not "b:current_compiler". What the command actually does is the following: - Delete the "current_compiler" and "b:current_compiler" variables. - Define the "CompilerSet" user command. With "!" it does ":set", without "!" it does ":setlocal". -- Execute ":runtime! compiler/{name}.(vim|lua)". The plugins are expected to +- Execute ":runtime! compiler/{name}.{vim,lua}". The plugins are expected to set options with "CompilerSet" and set the "current_compiler" variable to the name of the compiler. - Delete the "CompilerSet" user command. @@ -1319,8 +1317,8 @@ TEX COMPILER *compiler-tex* Included in the distribution compiler for TeX ($VIMRUNTIME/compiler/tex.vim) uses make command if possible. If the compiler finds a file named "Makefile" or "makefile" in the current directory, it supposes that you want to process -your *TeX files with make, and the makefile does the right work. In this case -compiler sets 'errorformat' for *TeX output and leaves 'makeprg' untouched. If +your `*TeX` files with make, and the makefile does the right work. In this case +compiler sets 'errorformat' for `*TeX` output and leaves 'makeprg' untouched. If neither "Makefile" nor "makefile" is found, the compiler will not use make. You can force the compiler to ignore makefiles by defining b:tex_ignore_makefile or g:tex_ignore_makefile variable (they are checked for @@ -1383,6 +1381,7 @@ rest is ignored. Items can only be 1023 bytes long. Basic items %f file name (finds a string) + %b buffer number (finds a number) %o module name (finds a string) %l line number (finds a number) %e end line number (finds a number) @@ -1422,6 +1421,11 @@ On Windows a leading "C:" will be included in "%f", even when using "%f:". This means that a file name which is a single alphabetical letter will not be detected. +The "%b" conversion is used to parse a buffer number. This is useful for +referring to lines in a scratch buffer or a buffer with no name. If a buffer +with the matching number doesn't exist, then that line is used as a non-error +line. + The "%p" conversion is normally followed by a "^". It's used for compilers that output a line like: > ^ @@ -1617,7 +1621,7 @@ be escaped), meta symbols have to be written with leading '%': %\ The single '\' character. Note that this has to be escaped ("%\\") in ":set errorformat=" definitions. %. The single '.' character. - %# The single '*'(!) character. + %# The single "*"(!) character. %^ The single '^' character. Note that this is not useful, the pattern already matches start of line. %$ The single '$' character. Note that this is not @@ -1935,7 +1939,7 @@ You can customize the given setting to suit your own purposes, for example, all the annoying "Overfull ..." warnings could be excluded from being recognized as an error. Alternatively to filtering the LaTeX compiler output, it is also possible -to directly read the *.log file that is produced by the [La]TeX compiler. +to directly read the `*.log` file that is produced by the [La]TeX compiler. This contains even more useful information about possible error causes. However, to properly parse such a complex file, an external filter should be used. See the description further above how to make such a filter known diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt index d17df3cd61..f976eb7464 100644 --- a/runtime/doc/quickref.txt +++ b/runtime/doc/quickref.txt @@ -489,8 +489,8 @@ In Insert or Command-line mode: |v_ip| N ip Select "inner paragraph" |v_ab| N ab Select "a block" (from "[(" to "])") |v_ib| N ib Select "inner block" (from "[(" to "])") -|v_aB| N aB Select "a Block" (from "[{" to "]}") -|v_iB| N iB Select "inner Block" (from "[{" to "]}") +|v_aB| N aB Select "a Block" (from `[{` to `]}`) +|v_iB| N iB Select "inner Block" (from `[{` to `]}`) |v_a>| N a> Select "a <> block" |v_i>| N i> Select "inner <> block" |v_at| N at Select "a tag block" (from <aaa> to </aaa>) @@ -812,14 +812,11 @@ Short explanation of each option: *option-list* 'operatorfunc' 'opfunc' function to be called for |g@| operator 'packpath' 'pp' list of directories used for packages 'paragraphs' 'para' nroff macros that separate paragraphs -'paste' allow pasting text -'pastetoggle' 'pt' key code that causes 'paste' to toggle 'patchexpr' 'pex' expression used to patch a file 'patchmode' 'pm' keep the oldest version of a file 'path' 'pa' list of directories searched with "gf" et.al. 'preserveindent' 'pi' preserve the indent structure when reindenting 'previewheight' 'pvh' height of the preview window -'previewpopup' 'pvp' use popup window for preview 'previewwindow' 'pvw' identifies the preview window 'pumheight' 'ph' maximum number of items to show in the popup menu 'pumwidth' 'pw' minimum width of the popup menu @@ -872,6 +869,7 @@ Short explanation of each option: *option-list* 'smartcase' 'scs' no ignore case when pattern has uppercase 'smartindent' 'si' smart autoindenting for C programs 'smarttab' 'sta' use 'shiftwidth' when inserting <Tab> +'smoothscroll' 'sms' scroll by screen lines when 'wrap' is set 'softtabstop' 'sts' number of spaces that <Tab> uses while editing 'spell' enable spell checking 'spellcapcheck' 'spc' pattern to locate end of a sentence diff --git a/runtime/doc/recover.txt b/runtime/doc/recover.txt index d9aaa757ad..e6b5b06744 100644 --- a/runtime/doc/recover.txt +++ b/runtime/doc/recover.txt @@ -83,6 +83,15 @@ Detecting an existing swap file ~ You can find this in the user manual, section |11.3|. + *W325* +The default |SwapExists| handler (|default-autocmds|) skips the |E325| prompt +(selects "(E)dit") if the swapfile owner process (1) is still running and (2) +was started by the current user. This presumes that you normally don't want +to be bothered with the |ATTENTION| message just because you happen to edit +the same file from multiple Nvim instances. In the worst case (a system +crash) there will be more than one swapfile for the file; use |:recover| to +inspect all of its swapfiles. + Updating the swapfile ~ @@ -154,7 +163,7 @@ the recover command: :rec[over]! [file] Like ":recover", but any changes in the current buffer are lost. - *E312* *E309* *E310* + *E312* *E309* *E310* *E1364* Vim has some intelligence about what to do if the swap file is corrupt in some way. If Vim has doubt about what it found, it will give an error message and insert lines with "???" in the text. If you see an error message diff --git a/runtime/doc/remote.txt b/runtime/doc/remote.txt index 4610088ab0..804645f774 100644 --- a/runtime/doc/remote.txt +++ b/runtime/doc/remote.txt @@ -46,7 +46,7 @@ The following command line arguments are available: new tabpage. *--remote-send* --remote-send {keys} Send {keys} to server and exit. The {keys} - are not mapped. Special key names are + are not mapped. Special key names are recognized, e.g., "<CR>" results in a CR character. *--remote-expr* diff --git a/runtime/doc/remote_plugin.txt b/runtime/doc/remote_plugin.txt index 4cdcbed250..cfe4b08000 100644 --- a/runtime/doc/remote_plugin.txt +++ b/runtime/doc/remote_plugin.txt @@ -4,7 +4,7 @@ NVIM REFERENCE MANUAL by Thiago de Arruda -Nvim support for remote plugins *remote-plugin* +Nvim support for remote plugins *remote-plugin* Type |gO| to see the table of contents. @@ -40,8 +40,8 @@ fast as possible, even if many plugins/hosts are installed. The best way to learn about remote plugins is with an example, so let's see what a Python plugin looks like. This plugin exports a command, a function, and an autocmd. The plugin is called 'Limit', and all it does is limit the number -of requests made to it. Here's the plugin source code: -> +of requests made to it. Here's the plugin source code: >python + import pynvim @pynvim.plugin @@ -119,7 +119,7 @@ would also be spawned, which could take seconds! With the manifest, each host will only be loaded when required. Continuing with the example, say the Java plugin is a semantic completion engine for Java code. -If it defines the autocommand "BufEnter *.java", then the Java host is spawned +If it defines the autocommand `BufEnter *.java`, then the Java host is spawned only when Nvim loads a buffer matching "*.java". If the explicit call to |:UpdateRemotePlugins| seems inconvenient, try to see diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index 1bbd20702b..53f6904170 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -56,7 +56,7 @@ Using the underscore after `:d` avoids clobbering registers or the clipboard. This also makes it faster. Instead of the '/' which surrounds the {pattern}, you can use any other -single byte character, but not an alphabetic character, '\', '"' or '|'. +single byte character, but not an alphabetic character, '\', '"', '|' or '!'. This is useful if you want to include a '/' in the search pattern or replacement string. @@ -183,7 +183,10 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. *:so* *:source* *load-vim-script* :[range]so[urce] [file] Runs |Ex| commands or Lua code (".lua" files) from - [file], or current buffer if no [file]. + [file]. + If no [file], the current buffer is used, and it is + treated as Lua code if its 'filetype' is "lua" or its + file name ends with ".lua". Triggers the |SourcePre| autocommand. *:source!* :[range]so[urce]! {file} @@ -211,12 +214,10 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. When [!] is included, all found files are sourced. Else only the first found file is sourced. - When [where] is omitted, first 'runtimepath' is - searched, then directories under "start" in 'packpath' - are searched. + When [where] is omitted only 'runtimepath' is used. Other values: START search only under "start" in 'packpath' - OPT search only under "opt" in 'packpath' + OPT search only under "opt" in 'packpath' PACK search under "start" and "opt" in 'packpath' ALL first use 'runtimepath', then search @@ -224,12 +225,16 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. When {file} contains wildcards it is expanded to all matching files. Example: > - :runtime! plugin/**/*.vim -< This is what Vim uses to load the plugin files when + :runtime! plugin/**/*.{vim,lua} +< This is what Nvim uses to load the plugin files when starting up. This similar command: > - :runtime plugin/**/*.vim + :runtime plugin/**/*.{vim,lua} < would source the first file only. + For each {file} pattern, if two `.vim` and `.lua` file + names match and differ only in extension, the `.vim` + file is sourced first. + When 'verbose' is one or higher, there is a message when no file could be found. When 'verbose' is two or higher, there is a message @@ -259,8 +264,8 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. 'runtimepath'. If the filetype detection was already enabled (this - is usually done with a "syntax enable" or "filetype - on" command in your |init.vim|, or automatically during + is usually done with a `syntax enable` or `filetype on` + command in your |vimrc|, or automatically during |initialization|), and the package was found in "pack/*/opt/{name}", this command will also look for "{name}/ftdetect/*.vim" files. @@ -338,6 +343,7 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|. :scr[iptnames] List all sourced script names, in the order they were first sourced. The number is used for the script ID |<SID>|. + Also see `getscriptinfo()`. :scr[iptnames][!] {scriptId} *:script* Edit script {scriptId}. Although ":scriptnames name" @@ -643,15 +649,15 @@ up-to-date easily, but it requires a program like "git" to be available. You can do both, github can automatically create an archive for a release. Your directory layout would be like this: - start/foobar/plugin/foo.vim " always loaded, defines commands - start/foobar/plugin/bar.vim " always loaded, defines commands - start/foobar/autoload/foo.vim " loaded when foo command used - start/foobar/doc/foo.txt " help for foo.vim - start/foobar/doc/tags " help tags - opt/fooextra/plugin/extra.vim " optional plugin, defines commands - opt/fooextra/autoload/extra.vim " loaded when extra command used - opt/fooextra/doc/extra.txt " help for extra.vim - opt/fooextra/doc/tags " help tags + start/foobar/plugin/foo.vim " always loaded, defines commands + start/foobar/plugin/bar.vim " always loaded, defines commands + start/foobar/autoload/foo.vim " loaded when foo command used + start/foobar/doc/foo.txt " help for foo.vim + start/foobar/doc/tags " help tags + opt/fooextra/plugin/extra.vim " optional plugin, defines commands + opt/fooextra/autoload/extra.vim " loaded when extra command used + opt/fooextra/doc/extra.txt " help for extra.vim + opt/fooextra/doc/tags " help tags This allows for the user to do: > mkdir ~/.local/share/nvim/site/pack diff --git a/runtime/doc/russian.txt b/runtime/doc/russian.txt index 8d3ed360c8..89be1a3c5a 100644 --- a/runtime/doc/russian.txt +++ b/runtime/doc/russian.txt @@ -34,7 +34,6 @@ enter Normal mode command, you can also set 'langmap' option: :set langmap=ФИСВУАПРШОЛДЬТЩЗЙКЫЕГМЦЧНЯ;ABCDEFGHIJKLMNOPQRSTUVWXYZ, фисвуапршолдьтщзйкыегмцчня;abcdefghijklmnopqrstuvwxyz -This is in utf-8, you cannot read this if your 'encoding' is not utf-8. You have to type this command in one line, it is wrapped for the sake of readability. diff --git a/runtime/doc/scroll.txt b/runtime/doc/scroll.txt index 170c87a1a4..29d6177213 100644 --- a/runtime/doc/scroll.txt +++ b/runtime/doc/scroll.txt @@ -40,9 +40,6 @@ CTRL-D Scroll window Downwards in the buffer. The number of difference). When the cursor is on the last line of the buffer nothing happens and a beep is produced. See also 'startofline' option. - {difference from vi: Vim scrolls 'scroll' screen - lines, instead of file lines; makes a difference when - lines wrap} <S-Down> or *<S-Down>* *<kPageDown>* <PageDown> or *<PageDown>* *CTRL-F* @@ -189,16 +186,16 @@ windows can be given this behavior by setting the (window-specific) other 'scrollbind' windows are scrolled the same amount, if possible. The behavior of 'scrollbind' can be modified by the 'scrollopt' option. -When using the scrollbars, the binding only happens when scrolling the window -with focus (where the cursor is). You can use this to avoid scroll-binding -for a moment without resetting options. +When using the scrollbars or the mouse wheel, the binding only happens when +scrolling the window with focus (where the cursor is). You can use this to +avoid scroll-binding for a moment without resetting options. When a window also has the 'diff' option set, the scroll-binding uses the differences between the two buffers to synchronize the position precisely. Otherwise the following method is used. *scrollbind-relative* -Each 'scrollbind' window keeps track of its "relative offset," which can be +Each 'scrollbind' window keeps track of its "relative offset", which can be thought of as the difference between the current window's vertical scroll position and the other window's vertical scroll position. When one of the 'scrollbind' windows is asked to vertically scroll past the beginning or end @@ -222,9 +219,10 @@ option. *scrollbind-quickadj* The 'scrollbind' flag is meaningful when using keyboard commands to vertically -scroll a window, and also meaningful when using the vertical scrollbar of the -window which has the cursor focus. However, when using the vertical scrollbar -of a window which doesn't have the cursor focus, 'scrollbind' is ignored. +scroll a window, and is also meaningful when using the vertical scrollbar or +the mouse wheel in the window which has the cursor focus. However, when using +the vertical scrollbar or the mouse wheel in a window which doesn't have the +cursor focus, 'scrollbind' is ignored. This allows quick adjustment of the relative offset of 'scrollbind' windows. ============================================================================== diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt index d09d0f226f..0360ce67f6 100644 --- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -53,11 +53,10 @@ If 'cursorline' is enabled, then the CursorLineSign highlight group is used Each placed sign is identified by a number called the sign identifier. This identifier is used to jump to the sign or to remove the sign. The identifier is assigned when placing the sign using the |:sign-place| command or the -|sign_place()| function. Each sign identifier should be a unique number. If -multiple placed signs use the same identifier, then jumping to or removing a -sign becomes unpredictable. To avoid overlapping identifiers, sign groups can -be used. The |sign_place()| function can be called with a zero sign identifier -to allocate the next available identifier. +|sign_place()| function. Each sign identifier should be a unique number (per +buffer). Placing the same identifier twice will move the previously placed +sign. The |sign_place()| function can be called with a zero sign identifier to +allocate the next available identifier. *sign-group* Each placed sign can be assigned to either the global group or a named group. @@ -77,9 +76,8 @@ When two signs with the same priority are present, and one has an icon or text in the signcolumn while the other has line highlighting, then both are displayed. -When the line on which the sign is placed is deleted, the sign is moved to the -next line (or the last line of the buffer, if there is no next line). When -the delete is undone the sign does not move back. +When the line on which the sign is placed is deleted, the sign is removed along +with it. ============================================================================== 2. Commands *sign-commands* *:sig* *:sign* @@ -177,11 +175,8 @@ See |sign_place()| for the equivalent Vim script function. space is ignored. The sign is remembered under {id}, this can be used for - further manipulation. {id} must be a number. - It's up to the user to make sure the {id} is used only once in - each file (if it's used several times unplacing will also have - to be done several times and making changes may not work as - expected). + further manipulation. {id} must be a number. Placing the + same {id} multiple times will move the sign. The following optional sign attributes can be specified before "file=": @@ -369,389 +364,15 @@ See |sign_jump()| for the equivalent Vim script function. ============================================================================== 3. Functions *sign-functions-details* -sign_define({name} [, {dict}]) *sign_define()* -sign_define({list}) - Define a new sign named {name} or modify the attributes of an - existing sign. This is similar to the |:sign-define| command. - - Prefix {name} with a unique text to avoid name collisions. - There is no {group} like with placing signs. - - The {name} can be a String or a Number. The optional {dict} - argument specifies the sign attributes. The following values - are supported: - icon full path to the bitmap file for the sign. - linehl highlight group used for the whole line the - sign is placed in. - numhl highlight group used for the line number where - the sign is placed. - text text that is displayed when there is no icon - or the GUI is not being used. - texthl highlight group used for the text item - culhl highlight group used for the text item when - the cursor is on the same line as the sign and - 'cursorline' is enabled. - - If the sign named {name} already exists, then the attributes - of the sign are updated. - - The one argument {list} can be used to define a list of signs. - Each list item is a dictionary with the above items in {dict} - and a "name" item for the sign name. - - Returns 0 on success and -1 on failure. When the one argument - {list} is used, then returns a List of values one for each - defined sign. - - Examples: > - call sign_define("mySign", { - \ "text" : "=>", - \ "texthl" : "Error", - \ "linehl" : "Search"}) - call sign_define([ - \ {'name' : 'sign1', - \ 'text' : '=>'}, - \ {'name' : 'sign2', - \ 'text' : '!!'} - \ ]) -< - Can also be used as a |method|: > - GetSignList()->sign_define() - -sign_getdefined([{name}]) *sign_getdefined()* - Get a list of defined signs and their attributes. - This is similar to the |:sign-list| command. - - If the {name} is not supplied, then a list of all the defined - signs is returned. Otherwise the attribute of the specified - sign is returned. - - Each list item in the returned value is a dictionary with the - following entries: - icon full path to the bitmap file of the sign - linehl highlight group used for the whole line the - sign is placed in; not present if not set. - name name of the sign - numhl highlight group used for the line number where - the sign is placed; not present if not set. - text text that is displayed when there is no icon - or the GUI is not being used. - texthl highlight group used for the text item; not - present if not set. - culhl highlight group used for the text item when - the cursor is on the same line as the sign and - 'cursorline' is enabled; not present if not - set. - - Returns an empty List if there are no signs and when {name} is - not found. - - Examples: > - " Get a list of all the defined signs - echo sign_getdefined() - - " Get the attribute of the sign named mySign - echo sign_getdefined("mySign") -< - Can also be used as a |method|: > - GetSignList()->sign_getdefined() - -sign_getplaced([{buf} [, {dict}]]) *sign_getplaced()* - Return a list of signs placed in a buffer or all the buffers. - This is similar to the |:sign-place-list| command. - - If the optional buffer name {buf} is specified, then only the - list of signs placed in that buffer is returned. For the use - of {buf}, see |bufname()|. The optional {dict} can contain - the following entries: - group select only signs in this group - id select sign with this identifier - lnum select signs placed in this line. For the use - of {lnum}, see |line()|. - If {group} is '*', then signs in all the groups including the - global group are returned. If {group} is not supplied or is an - empty string, then only signs in the global group are - returned. If no arguments are supplied, then signs in the - global group placed in all the buffers are returned. - See |sign-group|. - - Each list item in the returned value is a dictionary with the - following entries: - bufnr number of the buffer with the sign - signs list of signs placed in {bufnr}. Each list - item is a dictionary with the below listed - entries - - The dictionary for each sign contains the following entries: - group sign group. Set to '' for the global group. - id identifier of the sign - lnum line number where the sign is placed - name name of the defined sign - priority sign priority - - The returned signs in a buffer are ordered by their line - number and priority. - - Returns an empty list on failure or if there are no placed - signs. - - Examples: > - " Get a List of signs placed in eval.c in the - " global group - echo sign_getplaced("eval.c") - - " Get a List of signs in group 'g1' placed in eval.c - echo sign_getplaced("eval.c", {'group' : 'g1'}) - - " Get a List of signs placed at line 10 in eval.c - echo sign_getplaced("eval.c", {'lnum' : 10}) - - " Get sign with identifier 10 placed in a.py - echo sign_getplaced("a.py", {'id' : 10}) - - " Get sign with id 20 in group 'g1' placed in a.py - echo sign_getplaced("a.py", {'group' : 'g1', - \ 'id' : 20}) - - " Get a List of all the placed signs - echo sign_getplaced() -< - Can also be used as a |method|: > - GetBufname()->sign_getplaced() -< - *sign_jump()* -sign_jump({id}, {group}, {buf}) - Open the buffer {buf} or jump to the window that contains - {buf} and position the cursor at sign {id} in group {group}. - This is similar to the |:sign-jump| command. - - For the use of {buf}, see |bufname()|. - - Returns the line number of the sign. Returns -1 if the - arguments are invalid. - - Example: > - " Jump to sign 10 in the current buffer - call sign_jump(10, '', '') -< - Can also be used as a |method|: > - GetSignid()->sign_jump() -< - *sign_place()* -sign_place({id}, {group}, {name}, {buf} [, {dict}]) - Place the sign defined as {name} at line {lnum} in file or - buffer {buf} and assign {id} and {group} to sign. This is - similar to the |:sign-place| command. - - If the sign identifier {id} is zero, then a new identifier is - allocated. Otherwise the specified number is used. {group} is - the sign group name. To use the global sign group, use an - empty string. {group} functions as a namespace for {id}, thus - two groups can use the same IDs. Refer to |sign-identifier| - and |sign-group| for more information. - - {name} refers to a defined sign. - {buf} refers to a buffer name or number. For the accepted - values, see |bufname()|. - - The optional {dict} argument supports the following entries: - lnum line number in the file or buffer - {buf} where the sign is to be placed. - For the accepted values, see |line()|. - priority priority of the sign. See - |sign-priority| for more information. - - If the optional {dict} is not specified, then it modifies the - placed sign {id} in group {group} to use the defined sign - {name}. - - Returns the sign identifier on success and -1 on failure. - - Examples: > - " Place a sign named sign1 with id 5 at line 20 in - " buffer json.c - call sign_place(5, '', 'sign1', 'json.c', - \ {'lnum' : 20}) - - " Updates sign 5 in buffer json.c to use sign2 - call sign_place(5, '', 'sign2', 'json.c') - - " Place a sign named sign3 at line 30 in - " buffer json.c with a new identifier - let id = sign_place(0, '', 'sign3', 'json.c', - \ {'lnum' : 30}) - - " Place a sign named sign4 with id 10 in group 'g3' - " at line 40 in buffer json.c with priority 90 - call sign_place(10, 'g3', 'sign4', 'json.c', - \ {'lnum' : 40, 'priority' : 90}) -< - Can also be used as a |method|: > - GetSignid()->sign_place(group, name, expr) -< - *sign_placelist()* -sign_placelist({list}) - Place one or more signs. This is similar to the - |sign_place()| function. The {list} argument specifies the - List of signs to place. Each list item is a dict with the - following sign attributes: - buffer buffer name or number. For the accepted - values, see |bufname()|. - group sign group. {group} functions as a namespace - for {id}, thus two groups can use the same - IDs. If not specified or set to an empty - string, then the global group is used. See - |sign-group| for more information. - id sign identifier. If not specified or zero, - then a new unique identifier is allocated. - Otherwise the specified number is used. See - |sign-identifier| for more information. - lnum line number in the buffer where the sign is to - be placed. For the accepted values, see - |line()|. - name name of the sign to place. See |sign_define()| - for more information. - priority priority of the sign. When multiple signs are - placed on a line, the sign with the highest - priority is used. If not specified, the - default value of 10 is used. See - |sign-priority| for more information. - - If {id} refers to an existing sign, then the existing sign is - modified to use the specified {name} and/or {priority}. - - Returns a List of sign identifiers. If failed to place a - sign, the corresponding list item is set to -1. - - Examples: > - " Place sign s1 with id 5 at line 20 and id 10 at line - " 30 in buffer a.c - let [n1, n2] = sign_placelist([ - \ {'id' : 5, - \ 'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 20}, - \ {'id' : 10, - \ 'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 30} - \ ]) - - " Place sign s1 in buffer a.c at line 40 and 50 - " with auto-generated identifiers - let [n1, n2] = sign_placelist([ - \ {'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 40}, - \ {'name' : 's1', - \ 'buffer' : 'a.c', - \ 'lnum' : 50} - \ ]) -< - Can also be used as a |method|: > - GetSignlist()->sign_placelist() - -sign_undefine([{name}]) *sign_undefine()* -sign_undefine({list}) - Deletes a previously defined sign {name}. This is similar to - the |:sign-undefine| command. If {name} is not supplied, then - deletes all the defined signs. - - The one argument {list} can be used to undefine a list of - signs. Each list item is the name of a sign. - - Returns 0 on success and -1 on failure. For the one argument - {list} call, returns a list of values one for each undefined - sign. - - Examples: > - " Delete a sign named mySign - call sign_undefine("mySign") - - " Delete signs 'sign1' and 'sign2' - call sign_undefine(["sign1", "sign2"]) - - " Delete all the signs - call sign_undefine() -< - Can also be used as a |method|: > - GetSignlist()->sign_undefine() - -sign_unplace({group} [, {dict}]) *sign_unplace()* - Remove a previously placed sign in one or more buffers. This - is similar to the |:sign-unplace| command. - - {group} is the sign group name. To use the global sign group, - use an empty string. If {group} is set to '*', then all the - groups including the global group are used. - The signs in {group} are selected based on the entries in - {dict}. The following optional entries in {dict} are - supported: - buffer buffer name or number. See |bufname()|. - id sign identifier - If {dict} is not supplied, then all the signs in {group} are - removed. - - Returns 0 on success and -1 on failure. - - Examples: > - " Remove sign 10 from buffer a.vim - call sign_unplace('', {'buffer' : "a.vim", 'id' : 10}) - - " Remove sign 20 in group 'g1' from buffer 3 - call sign_unplace('g1', {'buffer' : 3, 'id' : 20}) - - " Remove all the signs in group 'g2' from buffer 10 - call sign_unplace('g2', {'buffer' : 10}) - - " Remove sign 30 in group 'g3' from all the buffers - call sign_unplace('g3', {'id' : 30}) - - " Remove all the signs placed in buffer 5 - call sign_unplace('*', {'buffer' : 5}) - - " Remove the signs in group 'g4' from all the buffers - call sign_unplace('g4') - - " Remove sign 40 from all the buffers - call sign_unplace('*', {'id' : 40}) - - " Remove all the placed signs from all the buffers - call sign_unplace('*') - -< Can also be used as a |method|: > - GetSigngroup()->sign_unplace() -< -sign_unplacelist({list}) *sign_unplacelist()* - Remove previously placed signs from one or more buffers. This - is similar to the |sign_unplace()| function. - - The {list} argument specifies the List of signs to remove. - Each list item is a dict with the following sign attributes: - buffer buffer name or number. For the accepted - values, see |bufname()|. If not specified, - then the specified sign is removed from all - the buffers. - group sign group name. If not specified or set to an - empty string, then the global sign group is - used. If set to '*', then all the groups - including the global group are used. - id sign identifier. If not specified, then all - the signs in the specified group are removed. - - Returns a List where an entry is set to 0 if the corresponding - sign was successfully removed or -1 on failure. - - Example: > - " Remove sign with id 10 from buffer a.vim and sign - " with id 20 from buffer b.vim - call sign_unplacelist([ - \ {'id' : 10, 'buffer' : "a.vim"}, - \ {'id' : 20, 'buffer' : 'b.vim'}, - \ ]) -< - Can also be used as a |method|: > - GetSignlist()->sign_unplacelist() -< +See: + - |sign_define()| + - |sign_getdefined()| + - |sign_getplaced()| + - |sign_jump()| + - |sign_place()| + - |sign_placelist()| + - |sign_undefine()| + - |sign_unplace()| + - |sign_unplacelist()| vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/spell.txt b/runtime/doc/spell.txt index 98a6af1b8b..29e4a7b0aa 100644 --- a/runtime/doc/spell.txt +++ b/runtime/doc/spell.txt @@ -111,7 +111,7 @@ zuG Undo |zW| and |zG|, remove the word from the internal list, like with |zW|. *:spellra* *:spellrare* -:[count]spellr[are] {word} +:[count]spellra[re] {word} Add {word} as a rare word to 'spellfile', similar to |zw|. Without count the first name is used, with a count of two the second entry, etc. @@ -124,7 +124,7 @@ zuG Undo |zW| and |zG|, remove the word from the internal nnoremap z/ :exe ':spellrare! ' .. expand('<cWORD>')<CR> < |:spellundo|, |zuw|, or |zuW| can be used to undo this. -:spellr[rare]! {word} Add {word} as a rare word to the internal word +:spellra[re]! {word} Add {word} as a rare word to the internal word list, similar to |zW|. :[count]spellu[ndo] {word} *:spellu* *:spellundo* @@ -205,7 +205,8 @@ line may be postponed. Use |CTRL-L| when needed. Also see |set-spc-auto| for how it can be set automatically when 'spelllang' is set. The 'spelloptions' option has a few more flags that influence the way spell -checking works. +checking works. For example, "camel" splits CamelCased words so that each +part of the word is spell-checked separately. Vim counts the number of times a good word is encountered. This is used to sort the suggestions: words that have been seen before get a small bonus, @@ -408,7 +409,7 @@ of the previous line "al." will be flagged as an error. And when you type Use |CTRL-L| to redraw right away. "[s" will also stop at a word combination with a line break. -When encountering a line break Vim skips characters such as '*', '>' and '"', +When encountering a line break Vim skips characters such as "*", '>' and '"', so that comments in C, shell and Vim code can be spell checked. @@ -440,9 +441,9 @@ find these functions useful: SETTING 'spellcapcheck' AUTOMATICALLY *set-spc-auto* After the 'spelllang' option has been set successfully, Vim will source the -files "spell/LANG.vim" in 'runtimepath'. "LANG" is the value of 'spelllang' -up to the first comma, dot or underscore. This can be used to set options -specifically for the language, especially 'spellcapcheck'. +files "spell/LANG.vim" and "spell/LANG.lua" in 'runtimepath'. "LANG" is the +value of 'spelllang' up to the first comma, dot or underscore. This can be +used to set options specifically for the language, especially 'spellcapcheck'. The distribution includes a few of these files. Use this command to see what they do: > diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt index 179bacdb24..a6619bc381 100644 --- a/runtime/doc/starting.txt +++ b/runtime/doc/starting.txt @@ -224,9 +224,11 @@ argument. All [args] are treated as {script} arguments and stored in the Lua `_G.arg` global table, thus "-l" ends processing of Nvim arguments. The {script} name is stored at `_G.arg[0]`. - + Sets 'verbose' to 1 (like "-V1"), so Lua `print()` writes to output. + If {script} prints messages and doesn't cause Nvim to exit, + Nvim ensures output ends with a newline. Arguments before "-l" are processed before executing {script}. This example quits before executing "foo.lua": > @@ -239,6 +241,14 @@ argument. Disables |shada| unless |-i| was given. Disables swapfile (like |-n|). + *-ll* +-ll {script} [args] + Execute a Lua script, similarly to |-l|, but the editor is not + initialized. This gives a Lua environment similar to a worker + thread. See |lua-loop-threading|. + + Unlike `-l` no prior arguments are allowed. + *-b* -b Binary mode. File I/O will only recognize <NL> to separate lines. The 'expandtab' option will be reset. The 'textwidth' @@ -250,7 +260,7 @@ argument. -A Arabic mode. Sets the 'arabic' option on. *-H* --H Hebrew mode. Sets the 'hkmap' and 'rightleft' options on. +-H Hebrew mode. Sets the 'rightleft' option on and 'keymap' to "hebrew" *-V* *verbose* -V[N] Verbose. Sets the 'verbose' option to [N] (default: 10). @@ -360,7 +370,7 @@ argument. -W {scriptout} Like -w, but do not append, overwrite an existing file. *--api-info* ---api-info Print msgpack-encoded |api-metadata| and exit. +--api-info Print msgpack-encoded |api-metadata| and exit. *--embed* --embed Use stdin/stdout as a msgpack-RPC channel, so applications can @@ -380,11 +390,15 @@ argument. < Then startup will continue without waiting for `nvim_ui_attach`. This is equivalent to: > nvim --headless --cmd "call stdioopen({'rpc': v:true})" +< + Embedders that use the UI protocol on a socket connection must + pass |--listen| as well as |--embed|: > + nvim --embed --listen addr < See also: |ui-startup| |channel-stdio| *--headless* ---headless Start without UI, and do not wait for `nvim_ui_attach`. The +--headless Start without UI, and do not wait for `nvim_ui_attach`. The builtin TUI is not used, so stdio works as an arbitrary communication channel. |channel-stdio| @@ -418,9 +432,11 @@ accordingly, proceeding as follows: 2. Process the arguments The options and file names from the command that start Vim are - inspected. Buffers are created for all files (but not loaded yet). + inspected. The |-V| argument can be used to display or log what happens next, useful for debugging the initializations. + The |--cmd| arguments are executed. + Buffers are created for all files (but not loaded yet). 3. Start a server (unless |--listen| was given) and set |v:servername|. @@ -450,13 +466,13 @@ accordingly, proceeding as follows: |$XDG_CONFIG_HOME| $XDG_CONFIG_HOME/nvim/init.vim (or init.lua) If Nvim was started with "-u {file}" then {file} is used as the config - and all initializations until 5. are skipped. $MYVIMRC is not set. + and all initializations until 8. are skipped. $MYVIMRC is not set. "nvim -u NORC" can be used to skip these initializations without reading a file. "nvim -u NONE" also skips plugins and syntax highlighting. |-u| - If Nvim was started with |-es| all initializations until 5. are - skipped. + If Nvim was started with |-es| or |-Es| or |-l| all initializations until 8. + are skipped. *system-vimrc* *sysinit.vim* a. The system vimrc file is read for initializations. If nvim/sysinit.vim file exists in one of $XDG_CONFIG_DIRS, it will be @@ -494,12 +510,12 @@ accordingly, proceeding as follows: 10. Load the plugin scripts. *load-plugins* This does the same as the command: > - :runtime! plugin/**/*.vim - :runtime! plugin/**/*.lua + :runtime! plugin/**/*.{vim,lua} < The result is that all directories in 'runtimepath' will be searched for the "plugin" sub-directory and all files ending in ".vim" or ".lua" will be sourced (in alphabetical order per directory), - also in subdirectories. First "*.vim" are sourced, then "*.lua" files. + also in subdirectories. First "*.vim" are sourced, then "*.lua" files, + per directory. However, directories in 'runtimepath' ending in "after" are skipped here and only loaded after packages, see below. @@ -814,7 +830,7 @@ resulting file, when executed with a ":source" command: 9. Restores the Views for all the windows, as with |:mkview|. But 'sessionoptions' is used instead of 'viewoptions'. 10. If a file exists with the same name as the Session file, but ending in - "x.vim" (for eXtra), executes that as well. You can use *x.vim files to + "x.vim" (for eXtra), executes that as well. You can use `*x.vim` files to specify additional settings and actions associated with a given Session, such as creating menu items in the GUI version. @@ -898,7 +914,7 @@ found. You might want to clean up your 'viewdir' directory now and then. -To automatically save and restore views for *.c files: > +To automatically save and restore views for `*.c` files: > au BufWinLeave *.c mkview au BufWinEnter *.c silent! loadview @@ -908,7 +924,7 @@ Shada ("shared data") file *shada* *shada-file* If you exit Vim and later start it again, you would normally lose a lot of information. The ShaDa file can be used to remember that information, which enables you to continue where you left off. Its name is the abbreviation of -SHAred DAta because it is used for sharing data between Neovim sessions. +SHAred DAta because it is used for sharing data between Nvim sessions. This is introduced in section |21.3| of the user manual. @@ -1000,16 +1016,16 @@ MERGING *shada-merging* When writing ShaDa files with |:wshada| without bang or at regular exit information in the existing ShaDa file is merged with information from current -Neovim instance. For this purpose ShaDa files store timestamps associated +Nvim instance. For this purpose ShaDa files store timestamps associated with ShaDa entries. Specifically the following is being done: 1. History lines are merged, ordered by timestamp. Maximum amount of items in ShaDa file is defined by 'shada' option (|shada-/|, |shada-:|, |shada-@|, etc: one suboption for each character that represents history name (|:history|)). -2. Local marks and changes for files that were not opened by Neovim are copied - to new ShaDa file. Marks for files that were opened by Neovim are merged, - changes to files opened by Neovim are ignored. |shada-'| +2. Local marks and changes for files that were not opened by Nvim are copied + to new ShaDa file. Marks for files that were opened by Nvim are merged, + changes to files opened by Nvim are ignored. |shada-'| 3. Jump list is merged: jumps are ordered by timestamp, identical jumps (identical position AND timestamp) are squashed. 4. Search patterns and substitute strings are not merged: search pattern or @@ -1017,14 +1033,14 @@ with ShaDa entries. Specifically the following is being done: to ShaDa file. 5. For each register entity with greatest timestamp is the only saved. |shada-<| -6. All saved variables are saved from current Neovim instance. Additionally +6. All saved variables are saved from current Nvim instance. Additionally existing variable values are copied, meaning that the only way to remove variable from a ShaDa file is either removing it by hand or disabling writing variables completely. |shada-!| 7. For each global mark entity with greatest timestamp is the only saved. 8. Buffer list and header are the only entries which are not merged in any fashion: the only header and buffer list present are the ones from the - Neovim instance which was last writing the file. |shada-%| + Nvim instance which was last writing the file. |shada-%| COMPATIBILITY *shada-compatibility* @@ -1049,13 +1065,13 @@ ShaDa files are forward and backward compatible. This means that history types. |history| 6. Unknown keys found in register, local mark, global mark, change, jump and search pattern entries are saved internally and dumped when writing. - Entries created during Neovim session never have such additions. + Entries created during Nvim session never have such additions. 7. Additional elements found in replacement string and history entries are - saved internally and dumped. Entries created during Neovim session never + saved internally and dumped. Entries created during Nvim session never have such additions. 8. Additional elements found in variable entries are simply ignored when reading. When writing new variables they will be preserved during merging, - but that's all. Variable values dumped from current Neovim session never + but that's all. Variable values dumped from current Nvim session never have additional elements, even if variables themselves were obtained by reading ShaDa files. @@ -1092,7 +1108,7 @@ start with an existing one to get the format right. You need to understand MessagePack (or, more likely, find software that is able to use it) format to do this. This can be useful in order to create a second file, say "~/.my.shada" which could contain certain settings that you always want when -you first start Neovim. For example, you can preload registers with +you first start Nvim. For example, you can preload registers with particular data, or put certain commands in the command line history. A line in your |config| file like > :rshada! ~/.my.shada @@ -1102,12 +1118,13 @@ file name, using the ":autocmd" command (see |:autocmd|). More information on ShaDa file format is contained in |shada-format| section. *E136* *E929* *shada-error-handling* -Some errors make Neovim leave temporary file named `{basename}.tmp.X` (X is +Some errors make Nvim leave temporary file named `{basename}.tmp.X` (X is any free letter from `a` to `z`) while normally it will create this file, write to it and then rename `{basename}.tmp.X` to `{basename}`. Such errors include: -- Errors which make Neovim think that read file is not a ShaDa file at all: +- Errors which make Nvim think that the file being read is not a ShaDa + file at all: non-ShaDa files are not overwritten for safety reasons to avoid accidentally destroying an unrelated file. This could happen e.g. when typing "nvim -i file" in place of "nvim -R file" (yes, somebody did that at least with Vim). @@ -1115,26 +1132,26 @@ include: - If writing to the temporary file failed: e.g. because of the insufficient space left. - If renaming file failed: e.g. because of insufficient permissions. -- If target ShaDa file has different from the Neovim instance's owners (user +- If target ShaDa file has different from the Nvim instance's owners (user and group) and changing them failed. Unix-specific, applies only when - Neovim was launched from root. + Nvim was launched from root. Do not forget to remove the temporary file or replace the target file with temporary one after getting one of the above errors or all attempts to create a ShaDa file may fail with |E929|. If you got one of them when using -|:wshada| (and not when exiting Neovim: i.e. when you have Neovim session +|:wshada| (and not when exiting Nvim: i.e. when you have Nvim session running) you have additional options: - First thing which you should consider if you got any error, except failure to write to the temporary file: remove existing file and replace it with the - temporary file. Do it even if you have running Neovim instance. + temporary file. Do it even if you have running Nvim instance. - Fix the permissions and/or file ownership, free some space and attempt to write again. Do not remove the existing file. - Use |:wshada| with bang. Does not help in case of permission error. If target file was actually the ShaDa file some information may be lost in this case. To make the matters slightly better use |:rshada| prior to writing, but this still will loose buffer-local marks and change list entries for any - file which is not opened in the current Neovim instance. + file which is not opened in the current Nvim instance. - Remove the target file from shell and use |:wshada|. Consequences are not different from using |:wshada| with bang, but "rm -f" works in some cases when you don't have write permissions. @@ -1201,7 +1218,7 @@ exactly four MessagePack objects: Key Data ~ generator Binary, software used to generate ShaDa file. Is equal to "nvim" when ShaDa file was - written by Neovim. + written by Nvim. version Binary, generator version. encoding Binary, effective 'encoding' value. max_kbyte Integer, effective |shada-s| limit value. @@ -1294,7 +1311,7 @@ exactly four MessagePack objects: 10 (LocalMark) 11 (Change) Map containing some position description: Entry Position ~ - GlobaMark Global mark position. |'A| + GlobalMark Global mark position. |'A| LocalMark Local mark position. |'a| Jump One position from the |jumplist|. Change One position from the |changelist|. @@ -1325,10 +1342,13 @@ exactly four MessagePack objects: reasons, see |shada-compatibility|. *E575* *E576* -Errors in ShaDa file may have two types: E575 used for all “logical” errors -and E576 used for all “critical” errors. Critical errors trigger behaviour -described in |shada-error-handling| when writing and skipping the rest of the -file when reading and include: +Errors in ShaDa file may have two types: +1. E575 for “logical” errors. +2. E576 for “critical” errors. +When writing, critical errors trigger behaviour described in +|shada-error-handling|. +When reading, critical errors cause the rest of the file to be skipped. +Critical errors include: *shada-critical-contents-errors* - Any of first three MessagePack objects being not an unsigned integer. - Third object requesting amount of bytes greater then bytes left in the ShaDa @@ -1350,9 +1370,12 @@ paths. *base-directories* *xdg* The "base" (root) directories conform to the XDG Base Directory Specification. https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html -The $XDG_CONFIG_HOME, $XDG_DATA_HOME, $XDG_RUNTIME_DIR, and $XDG_STATE_HOME -environment variables are used if defined, else default values (listed below) -are used. +The $XDG_CONFIG_HOME, $XDG_DATA_HOME, $XDG_RUNTIME_DIR, $XDG_STATE_HOME, +$XDG_CACHE_HOME, $XDG_CONFIG_DIRS and $XDG_DATA_DIRS environment variables +are used if defined, else default values (listed below) are used. + +Throughout the help pages these defaults are used as placeholders, e.g. +"~/.config" is understood to mean "$XDG_CONFIG_HOME or ~/.config". CONFIG DIRECTORY (DEFAULT) ~ *$XDG_CONFIG_HOME* Nvim: stdpath("config") @@ -1374,15 +1397,51 @@ STATE DIRECTORY (DEFAULT) ~ Unix: ~/.local/state ~/.local/state/nvim Windows: ~/AppData/Local ~/AppData/Local/nvim-data -Note: Throughout the user manual these defaults are used as placeholders, e.g. -"~/.config" is understood to mean "$XDG_CONFIG_HOME or ~/.config". - -LOG FILE *$NVIM_LOG_FILE* *E5430* +CACHE DIRECTORY (DEFAULT) ~ + *$XDG_CACHE_HOME* Nvim: stdpath("cache") + Unix: ~/.cache ~/.cache/nvim + Windows: ~/AppData/Local/Temp ~/AppData/Local/Temp/nvim-data + +LOG FILE (DEFAULT) ~ + `$NVIM_LOG_FILE` Nvim: stdpath("log")/log + Unix: ~/.local/state/nvim ~/.local/state/nvim/log + Windows: ~/AppData/Local/nvim-data ~/AppData/Local/nvim-data/log + +Note that stdpath("log") is currently an alias for stdpath("state"). + +ADDITIONAL CONFIGS DIRECTORY (DEFAULT) ~ + *$XDG_CONFIG_DIRS* Nvim: stdpath("config_dirs") + Unix: /etc/xdg/ /etc/xdg/nvim + Windows: Not applicable Not applicable + +ADDITIONAL DATA DIRECTORY (DEFAULT) ~ + *$XDG_DATA_DIRS* Nvim: stdpath("data_dirs") + Unix: /usr/local/share /usr/local/share/nvim + /usr/share /usr/share/nvim + Windows: Not applicable Not applicable + +NVIM_APPNAME *$NVIM_APPNAME* +The standard directories can be further configured by the `$NVIM_APPNAME` +environment variable. This variable controls the sub-directory that Nvim will +read from (and auto-create) in each of the base directories. For example, +setting `$NVIM_APPNAME` to "foo" before starting will cause Nvim to look for +configuration files in `$XDG_CONFIG_HOME/foo` instead of +`$XDG_CONFIG_HOME/nvim`. `$NVIM_APPNAME` must be a name, such as "foo", or a +relative path, such as "foo/bar". + +One use-case for $NVIM_APPNAME is to "isolate" Nvim applications. +Alternatively, for true isolation, on Linux you can use cgroups namespaces: > + systemd-run --user -qt -p PrivateUsers=yes -p BindPaths=/home/user/profile_xy:/home/user/.config/nvim nvim + +Note: Throughout the help pages, wherever `$XDG_CONFIG_…/nvim` is mentioned it +is understood to mean `$XDG_CONFIG_…/$NVIM_APPNAME`. + +LOG FILE *log* *$NVIM_LOG_FILE* *E5430* Besides 'debug' and 'verbose', Nvim keeps a general log file for internal debugging, plugins and RPC clients. > :echo $NVIM_LOG_FILE -By default, the file is located at stdpath("log")/log unless that path -is inaccessible or if $NVIM_LOG_FILE was set before |startup|. +By default, the file is located at stdpath("log")/log ($XDG_STATE_HOME/nvim/log) +unless that path is inaccessible or if $NVIM_LOG_FILE was set before |startup|. vim:noet:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/support.txt b/runtime/doc/support.txt index 481959d8f1..80a035068a 100644 --- a/runtime/doc/support.txt +++ b/runtime/doc/support.txt @@ -14,12 +14,16 @@ Supported platforms *supported-platforms* `System` `Tier` `Versions` `Tested versions` Linux 1 >= 2.6.32, glibc >= 2.12 Ubuntu 22.04 macOS (Intel) 1 >= 10.15 macOS 12 -Windows 64-bit 1 >= 8 Windows Server 2019 +Windows 64-bit 1 >= 8 (see note below) Windows Server 2022 FreeBSD 1 >= 10 FreeBSD 13 macOS (M1) 2 >= 10.15 OpenBSD 2 >= 7 MinGW 2 MinGW-w64 +Note: Windows 10 "Version 1809" or later is required for |:terminal|. To check +your Windows version, run the "winver" command and look for "Version xxxx" +(NOT "OS Build"). + Support types ~ * Tier 1: Officially supported and tested with CI. Any contributed patch diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index bd5a4f1926..e1053b54f1 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -188,28 +188,27 @@ thing. These are then linked to a highlight group that specifies the color. A syntax group name doesn't specify any color or attributes itself. The name for a highlight or syntax group must consist of ASCII letters, -digits, underscores, periods and `@` characters. As a regexp it is -`[a-zA-Z0-9_.@]*`. The maximum length of a group name is about 200 bytes. -*E1249* +digits, underscores, dots, hyphens, or `@`. As a regexp: `[a-zA-Z0-9_.@-]*`. +The maximum length of a group name is about 200 bytes. *E1249* To be able to allow each user to pick their favorite set of colors, there must be preferred names for highlight groups that are common for many languages. These are the suggested group names (if syntax highlighting works properly you can see the actual color, except for "Ignore"): - *Comment any comment + Comment any comment - *Constant any constant + Constant any constant String a string constant: "this is a string" Character a character constant: 'c', '\n' Number a number constant: 234, 0xff Boolean a boolean constant: TRUE, false Float a floating point constant: 2.3e10 - *Identifier any variable name + Identifier any variable name Function function name (also: methods for classes) - *Statement any statement + Statement any statement Conditional if, then, else, endif, switch, etc. Repeat for, do, while, etc. Label case, default, etc. @@ -217,31 +216,31 @@ you can see the actual color, except for "Ignore"): Keyword any other keyword Exception try, catch, throw - *PreProc generic Preprocessor + PreProc generic Preprocessor Include preprocessor #include Define preprocessor #define Macro same as Define PreCondit preprocessor #if, #else, #endif, etc. - *Type int, long, char, etc. + Type int, long, char, etc. StorageClass static, register, volatile, etc. Structure struct, union, enum, etc. Typedef A typedef - *Special any special symbol + Special any special symbol SpecialChar special character in a constant Tag you can use CTRL-] on this Delimiter character that needs attention SpecialComment special things inside a comment Debug debugging statements - *Underlined text that stands out, HTML links + Underlined text that stands out, HTML links - *Ignore left blank, hidden |hl-Ignore| + Ignore left blank, hidden |hl-Ignore| - *Error any erroneous construct + Error any erroneous construct - *Todo anything that needs extra attention; mostly the + Todo anything that needs extra attention; mostly the keywords TODO FIXME and XXX The names marked with * are the preferred groups; the others are minor groups. @@ -560,7 +559,7 @@ The method used to prevent copying in the generated page depends on the value of |g:html_use_input_for_pc|. *g:html_use_input_for_pc* -Default: "fallback" +Default: "none" If |g:html_prevent_copy| is non-empty, then: When "all", read-only <input> elements are used in place of normal text for @@ -893,7 +892,7 @@ nasm_no_warn potentially risky syntax not as ToDo ASPPERL and ASPVBS *ft-aspperl-syntax* *ft-aspvbs-syntax* -*.asp and *.asa files could be either Perl or Visual Basic script. Since it's +`*.asp` and `*.asa` files could be either Perl or Visual Basic script. Since it's hard to detect this you can set two global variables to tell Vim what you are using. For Perl script use: > :let g:filetype_asa = "aspperl" @@ -979,7 +978,7 @@ Variable Highlight ~ *c_ansi_typedefs* ... but do standard ANSI types *c_ansi_constants* ... but do standard ANSI constants *c_no_utf* don't highlight \u and \U in strings -*c_syntax_for_h* for *.h files use C syntax instead of C++ and use objc +*c_syntax_for_h* for `*.h` files use C syntax instead of C++ and use objc syntax instead of objcpp *c_no_if0* don't highlight "#if 0" blocks as comments *c_no_cformat* don't highlight %-formats in strings @@ -987,7 +986,7 @@ Variable Highlight ~ *c_no_c11* don't highlight C11 standard items *c_no_bsd* don't highlight BSD specific types -When 'foldmethod' is set to "syntax" then /* */ comments and { } blocks will +When 'foldmethod' is set to "syntax" then `/* */` comments and { } blocks will become a fold. If you don't want comments to become a fold use: > :let c_no_comment_fold = 1 "#if 0" blocks are also folded, unless: > @@ -1034,7 +1033,7 @@ CH *ch.vim* *ft-ch-syntax* C/C++ interpreter. Ch has similar syntax highlighting to C and builds upon the C syntax file. See |c.vim| for all the settings that are available for C. -By setting a variable you can tell Vim to use Ch syntax for *.h files, instead +By setting a variable you can tell Vim to use Ch syntax for `*.h` files, instead of C or C++: > :let ch_syntax_for_h = 1 @@ -1271,18 +1270,32 @@ When not set 4 is used. DOSBATCH *dosbatch.vim* *ft-dosbatch-syntax* -There is one option with highlighting DOS batch files. This covers new -extensions to the Command Interpreter introduced with Windows 2000 and -is controlled by the variable dosbatch_cmdextversion. For Windows NT -this should have the value 1, and for Windows 2000 it should be 2. +Select the set of Windows Command interpreter extensions that should be +supported with the variable dosbatch_cmdextversion. For versions of Windows +NT (before Windows 2000) this should have the value of 1. For Windows 2000 +and later it should be 2. Select the version you want with the following line: > :let dosbatch_cmdextversion = 1 If this variable is not defined it defaults to a value of 2 to support -Windows 2000. +Windows 2000 and later. -A second option covers whether *.btm files should be detected as type +The original MS-DOS supports an idiom of using a double colon (::) as an +alternative way to enter a comment line. This idiom can be used with the +current Windows Command Interpreter, but it can lead to problems when used +inside ( ... ) command blocks. You can find a discussion about this on +Stack Overflow - + +https://stackoverflow.com/questions/12407800/which-comment-style-should-i-use-in-batch-files + +To allow the use of the :: idiom for comments in the Windows Command +Interpreter or working with MS-DOS bat files, set the +dosbatch_colons_comment variable to anything: > + + :let dosbatch_colons_comment = 1 + +There is an option that covers whether `*.btm` files should be detected as type "dosbatch" (MS-DOS batch files) or type "btm" (4DOS batch files). The latter is used by default. You may select the former with the following line: > @@ -1413,13 +1426,13 @@ Euphoria version 3.1.1 (https://www.rapideuphoria.com/) is still necessary for developing applications for the DOS platform, which Euphoria version 4 (https://www.openeuphoria.org/) does not support. -The following file extensions are auto-detected as Euphoria file type: +The following file extensions are auto-detected as Euphoria file type: > *.e, *.eu, *.ew, *.ex, *.exu, *.exw *.E, *.EU, *.EW, *.EX, *.EXU, *.EXW To select syntax highlighting file for Euphoria, as well as for -auto-detecting the *.e and *.E file extensions as Euphoria file type, +auto-detecting the `*.e` and `*.E` file extensions as Euphoria file type, add the following line to your startup file: > :let g:filetype_euphoria = "euphoria3" @@ -1428,7 +1441,7 @@ add the following line to your startup file: > :let g:filetype_euphoria = "euphoria4" -Elixir and Euphoria share the *.ex file extension. If the filetype is +Elixir and Euphoria share the `*.ex` file extension. If the filetype is specifically set as Euphoria with the g:filetype_euphoria variable, or the file is determined to be Euphoria based on keywords in the file, then the filetype will be set as Euphoria. Otherwise, the filetype will default to @@ -1455,11 +1468,11 @@ ELIXIR *elixir.vim* *ft-elixir-syntax* Elixir is a dynamic, functional language for building scalable and maintainable applications. -The following file extensions are auto-detected as Elixir file types: +The following file extensions are auto-detected as Elixir file types: > *.ex, *.exs, *.eex, *.leex, *.lock -Elixir and Euphoria share the *.ex file extension. If the filetype is +Elixir and Euphoria share the `*.ex` file extension. If the filetype is specifically set as Euphoria with the g:filetype_euphoria variable, or the file is determined to be Euphoria based on keywords in the file, then the filetype will be set as Euphoria. Otherwise, the filetype will default to @@ -1529,9 +1542,10 @@ example, FORM files, use this in your startup vimrc: > FORTH *forth.vim* *ft-forth-syntax* -Files matching "*.fs" could be F# or Forth. If the automatic detection -doesn't work for you, or you don't edit F# at all, use this in your -startup vimrc: > +Files matching "*.f" could be Fortran or Forth and those matching "*.fs" could +be F# or Forth. If the automatic detection doesn't work for you, or you don't +edit F# or Fortran at all, use this in your startup vimrc: > + :let filetype_f = "forth" :let filetype_fs = "forth" @@ -1891,7 +1905,7 @@ IA64 *ia64.vim* *intel-itanium* *ft-ia64-syntax* Highlighting for the Intel Itanium 64 assembly language. See |asm.vim| for how to recognize this filetype. -To have *.inc files be recognized as IA64, add this to your vimrc file: > +To have `*.inc` files be recognized as IA64, add this to your vimrc file: > :let g:filetype_inc = "ia64" @@ -2104,18 +2118,18 @@ set "lite_minlines" to the value you desire. Example: > LPC *lpc.vim* *ft-lpc-syntax* LPC stands for a simple, memory-efficient language: Lars Pensjö C. The -file name of LPC is usually *.c. Recognizing these files as LPC would bother +file name of LPC is usually `*.c`. Recognizing these files as LPC would bother users writing only C programs. If you want to use LPC syntax in Vim, you should set a variable in your vimrc file: > :let lpc_syntax_for_c = 1 If it doesn't work properly for some particular C or LPC files, use a -modeline. For a LPC file: +modeline. For a LPC file: > // vim:set ft=lpc: -For a C file that is recognized as LPC: +For a C file that is recognized as LPC: > // vim:set ft=c: @@ -2139,7 +2153,7 @@ For LPC4 series of LPC: > For uLPC series of LPC: uLPC has been developed to Pike, so you should use Pike syntax -instead, and the name of your source file should be *.pike +instead, and the name of your source file should be `*.pike` LUA *lua.vim* *ft-lua-syntax* @@ -2147,7 +2161,7 @@ LUA *lua.vim* *ft-lua-syntax* The Lua syntax file can be used for versions 4.0, 5.0, 5.1 and 5.2 (5.2 is the default). You can select one of these versions using the global variables lua_version and lua_subversion. For example, to activate Lua -5.1 syntax highlighting, set the variables like this: +5.1 syntax highlighting, set the variables like this: > :let lua_version = 5 :let lua_subversion = 1 @@ -2216,7 +2230,7 @@ the start of a region, for example 500 lines: > MATHEMATICA *mma.vim* *ft-mma-syntax* *ft-mathematica-syntax* -Empty *.m files will automatically be presumed to be Matlab files unless you +Empty `*.m` files will automatically be presumed to be Matlab files unless you have the following in your vimrc: > let filetype_m = "mma" @@ -2423,7 +2437,7 @@ keywords, etc): > The option pascal_symbol_operator controls whether symbol operators such as +, -*, .., etc. are displayed using the Operator color or not. To colorize symbol +`*`, .., etc. are displayed using the Operator color or not. To colorize symbol operators, add the following line to your startup file: > :let pascal_symbol_operator=1 @@ -2586,7 +2600,7 @@ x = 0 to sync from start. PLAINTEX *plaintex.vim* *ft-plaintex-syntax* TeX is a typesetting language, and plaintex is the file type for the "plain" -variant of TeX. If you never want your *.tex files recognized as plain TeX, +variant of TeX. If you never want your `*.tex` files recognized as plain TeX, see |ft-tex-plugin|. This syntax file has the option > @@ -2742,17 +2756,25 @@ For highlighted doctests and code inside: > :let python_no_doctest_highlight = 1 or > :let python_no_doctest_code_highlight = 1 -(first option implies second one). +The first option implies the second one. For highlighted trailing whitespace and mix of spaces and tabs: > :let python_space_error_highlight = 1 -If you want all possible Python highlighting (the same as setting the -preceding last option and unsetting all other ones): > +If you want all possible Python highlighting: > :let python_highlight_all = 1 +This has the same effect as setting python_space_error_highlight and +unsetting all the other ones. + +If you use Python 2 or straddling code (Python 2 and 3 compatible), +you can enforce the use of an older syntax file with support for +Python 2 and up to Python 3.5. > + :let python_use_python2_syntax = 1 +This option will exclude all modern Python 3.6 or higher features. + +Note: Only existence of these options matters, not their value. + You can replace 1 above with anything. -Note: Only existence of these options matter, not their value. You can replace - 1 above with anything. QUAKE *quake.vim* *ft-quake-syntax* @@ -3127,7 +3149,7 @@ The syntax/sh.vim file provides several levels of syntax-based folding: > let g:sh_fold_enabled= 1 (enable function folding) let g:sh_fold_enabled= 2 (enable heredoc folding) let g:sh_fold_enabled= 4 (enable if/do/for folding) -> + then various syntax items (ie. HereDocuments and function bodies) become syntax-foldable (see |:syn-fold|). You also may add these together to get multiple types of folding: > @@ -3248,7 +3270,7 @@ This covers the shell named "tcsh". It is a superset of csh. See |csh.vim| for how the filetype is detected. Tcsh does not allow \" in strings unless the "backslash_quote" shell variable -is set. If you want VIM to assume that no backslash quote constructs exist +is set. If you want VIM to assume that no backslash quote constructs exist add this line to your vimrc: > :let tcsh_backslash_quote = 0 @@ -3424,8 +3446,8 @@ has a starred form (ie. eqnarray*). *tex-style* *b:tex_stylish* Tex: Starting a New Style? ~ -One may use "\makeatletter" in *.tex files, thereby making the use of "@" in -commands available. However, since the *.tex file doesn't have one of the +One may use "\makeatletter" in `*.tex` files, thereby making the use of "@" in +commands available. However, since the `*.tex` file doesn't have one of the following suffices: sty cls clo dtx ltx, the syntax highlighting will flag such use of @ as an error. To solve this: > @@ -3469,7 +3491,7 @@ substitution will not be made. Tex: Controlling iskeyword~ Normally, LaTeX keywords support 0-9, a-z, A-z, and 192-255 only. Latex -keywords don't support the underscore - except when in *.sty files. The +keywords don't support the underscore - except when in `*.sty` files. The syntax highlighting script handles this with the following logic: * If g:tex_stylish exists and is 1 @@ -3676,11 +3698,12 @@ The syntax script for zsh allows for syntax-based folding: > Vim understands three types of syntax items: 1. Keyword - It can only contain keyword characters, according to the 'iskeyword' - option. It cannot contain other syntax items. It will only match with a - complete word (there are no keyword characters before or after the match). - The keyword "if" would match in "if(a=b)", but not in "ifdef x", because - "(" is not a keyword character and "d" is. + It can only contain keyword characters, according to the characters + specified with |:syn-iskeyword| or the 'iskeyword' option. It cannot + contain other syntax items. It will only match with a complete word (there + are no keyword characters before or after the match). The keyword "if" + would match in "if(a=b)", but not in "ifdef x", because "(" is not a + keyword character and "d" is. 2. Match This is a match with a single regexp pattern. @@ -3692,7 +3715,7 @@ Vim understands three types of syntax items: Several syntax ITEMs can be put into one syntax GROUP. For a syntax group you can give highlighting attributes. For example, you could have an item -to define a "/* .. */" comment and another one that defines a "// .." comment, +to define a `/* .. */` comment and another one that defines a "// .." comment, and put them both in the "Comment" group. You can then specify that a "Comment" will be in bold font and have a blue color. You are free to make one highlight group for one syntax item, or put all items into one group. @@ -3784,7 +3807,7 @@ SYNTAX ISKEYWORD SETTING *:syn-iskeyword* clear: Syntax specific iskeyword setting is disabled and the buffer-local 'iskeyword' setting is used. - {option} Set the syntax 'iskeyword' option to a new value. + {option} Set the syntax 'iskeyword' option to a new value. Example: > :syntax iskeyword @,48-57,192-255,$,_ @@ -4450,19 +4473,19 @@ Notes: matched. This doesn't work: "a\nb"ms=e. You can make the highlighting start in another line, this does work: "a\nb"hs=e. -Example (match a comment but don't highlight the /* and */): > +Example (match a comment but don't highlight the `/* and */`): >vim :syntax region Comment start="/\*"hs=e+1 end="\*/"he=s-1 -< +< > /* this is a comment */ ^^^^^^^^^^^^^^^^^^^ highlighted - -A more complicated Example: > - :syn region Exa matchgroup=Foo start="foo"hs=s+2,rs=e+2 matchgroup=Bar end="bar"me=e-1,he=e-1,re=s-1 < +A more complicated Example: >vim + :syn region Exa matchgroup=Foo start="foo"hs=s+2,rs=e+2 matchgroup=Bar end="bar"me=e-1,he=e-1,re=s-1 +< > abcfoostringbarabc mmmmmmmmmmm match sssrrreee highlight start/region/end ("Foo", "Exa" and "Bar") - +< Leading context *:syn-lc* *:syn-leading* *:syn-context* Note: This is an obsolete feature, only included for backwards compatibility @@ -4762,7 +4785,7 @@ matches, nextgroup, etc. But there are a few differences: - When a match with a sync pattern is found, the rest of the line (or group of continued lines) is searched for another match. The last match is used. This is used when a line can contain both the start end the end of a region - (e.g., in a C-comment like /* this */, the last "*/" is used). + (e.g., in a C-comment like `/* this */`, the last "*/" is used). There are two ways how a match with a sync pattern can be used: 1. Parsing for highlighting starts where redrawing starts (and where the @@ -4872,8 +4895,8 @@ in their own color. output "default". :colo[rscheme] {name} Load color scheme {name}. This searches 'runtimepath' - for the file "colors/{name}.(vim|lua)". The first one that - is found is loaded. + for the file "colors/{name}.{vim,lua}". The first one + that is found is loaded. Note: "colors/{name}.vim" is tried first. Also searches all plugins in 'packpath', first below "start" and then under "opt". @@ -4997,7 +5020,7 @@ stop={term-list} *term-list* *highlight-stop* highlighted area. This should undo the "start" argument. Otherwise the screen will look messed up. - {term-list} is a a string with escape sequences. This is any string of + {term-list} is a string with escape sequences. This is any string of characters, except that it can't start with "t_" and blanks are not allowed. The <> notation is recognized here, so you can use things like "<Esc>" and "<Space>". Example: @@ -5035,16 +5058,16 @@ ctermbg={color-nr} *ctermbg* The number under "NR-16" is used for 16-color terminals ('t_Co' greater than or equal to 16). The number under "NR-8" is used for - 8-color terminals ('t_Co' less than 16). The '*' indicates that the + 8-color terminals ('t_Co' less than 16). The "*" indicates that the bold attribute is set for ctermfg. In many 8-color terminals (e.g., "linux"), this causes the bright colors to appear. This doesn't work - for background colors! Without the '*' the bold attribute is removed. + for background colors! Without the "*" the bold attribute is removed. If you want to set the bold attribute in a different way, put a "cterm=" argument AFTER the "ctermfg=" or "ctermbg=" argument. Or use a number instead of a color name. Note that for 16 color ansi style terminals (including xterms), the - numbers in the NR-8 column is used. Here "*" means "add 8" so that + numbers in the NR-8 column is used. Here "*" means "add 8" so that Blue is 12, DarkGray is 8 etc. Note that for some color terminals these names may result in the wrong @@ -5165,7 +5188,7 @@ Conceal Placeholder characters substituted for concealed *hl-CurSearch* CurSearch Used for highlighting a search pattern under the cursor (see 'hlsearch'). - *hl-Cursor* + *hl-Cursor* *hl-lCursor* Cursor Character under the cursor. lCursor Character under the cursor when |language-mapping| is used (see 'guicursor'). @@ -5246,12 +5269,26 @@ NonText '@' at the end of the window, characters from 'showbreak' Normal Normal text. *hl-NormalFloat* NormalFloat Normal text in floating windows. + *hl-FloatBorder* +FloatBorder Border of floating windows. + *hl-FloatTitle* +FloatTitle Title of floating windows. + *hl-FloatFooter* +FloatFooter Footer of floating windows. *hl-NormalNC* NormalNC Normal text in non-current windows. *hl-Pmenu* Pmenu Popup menu: Normal item. *hl-PmenuSel* PmenuSel Popup menu: Selected item. + *hl-PmenuKind* +PmenuKind Popup menu: Normal item "kind". + *hl-PmenuKindSel* +PmenuKindSel Popup menu: Selected item "kind". + *hl-PmenuExtra* +PmenuExtra Popup menu: Normal item "extra text". + *hl-PmenuExtraSel* +PmenuExtraSel Popup menu: Selected item "extra text". *hl-PmenuSbar* PmenuSbar Popup menu: Scrollbar. *hl-PmenuThumb* @@ -5285,8 +5322,6 @@ SpellRare Word that is recognized by the spellchecker as one that is StatusLine Status line of current window. *hl-StatusLineNC* StatusLineNC Status lines of not-current windows. - Note: If this is equal to "StatusLine", Vim will use "^^^" in - the status line of the current window. *hl-TabLine* TabLine Tab pages line, not active tab page label. *hl-TabLineFill* @@ -5446,14 +5481,14 @@ memory Vim will consume. Only highlighting typedefs, unions and structs can be done too. For this you must use Universal Ctags (https://ctags.io) or Exuberant ctags. -Put these lines in your Makefile: +Put these lines in your Makefile: > -# Make a highlight file for types. Requires Universal/Exuberant ctags and awk -types: types.vim -types.vim: *.[ch] - ctags --c-kinds=gstu -o- *.[ch] |\ - awk 'BEGIN{printf("syntax keyword Type\t")}\ - {printf("%s ", $$1)}END{print ""}' > $@ + # Make a highlight file for types. Requires Universal/Exuberant ctags and awk + types: types.vim + types.vim: *.[ch] + ctags --c-kinds=gstu -o- *.[ch] |\ + awk 'BEGIN{printf("syntax keyword Type\t")}\ + {printf("%s ", $$1)}END{print ""}' > $@ And put these lines in your vimrc: > diff --git a/runtime/doc/tagsrch.txt b/runtime/doc/tagsrch.txt index 0f785dd1eb..2b5b253a09 100644 --- a/runtime/doc/tagsrch.txt +++ b/runtime/doc/tagsrch.txt @@ -92,7 +92,7 @@ The ignore-case matches are found when: - when 'tagcase' is "followscs" and 'ignorecase' is on or the 'smartcase' option is on and the pattern does not contain an upper case character - when 'tagcase' is "ignore" -- when 'tagcase' is "smart" and the patter does not contain an upper case +- when 'tagcase' is "smart" and the pattern does not contain an upper case character Note that using ignore-case tag searching disables binary searching in the @@ -695,7 +695,7 @@ do not have an absolute path. The 'comments' option is used for the commands that display a single line or jump to a line. It defines patterns that may start a comment. Those lines are ignored for the search, unless [!] is used. One exception: When the line -matches the pattern "^# *define" it is not considered to be a comment. +matches the pattern `"^# *define"` it is not considered to be a comment. If you want to list matches, and then select one to jump to, you could use a mapping to do that for you. Here is an example: > @@ -838,7 +838,7 @@ Common arguments for the commands above: [!] When included, find matches in lines that are recognized as comments. When excluded, a match is ignored when the line is recognized as a comment (according to 'comments'), or the match is in a C comment - (after "//" or inside /* */). Note that a match may be missed if a + (after "//" or inside `/* */`). Note that a match may be missed if a line is recognized as a comment, but the comment ends halfway the line. And if the line is a comment, but it is not recognized (according to 'comments') a match may be found in it anyway. Example: > @@ -907,7 +907,7 @@ The following fields are optional: If the function returns |v:null| instead of a List, a standard tag lookup will be performed instead. -It is not allowed to change the tagstack from inside 'tagfunc'. *E986* +It is not allowed to change the tagstack from inside 'tagfunc'. *E986* It is not allowed to close a window or change window from inside 'tagfunc'. *E1299* diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt index 847b4b6112..8ef8675d13 100644 --- a/runtime/doc/term.txt +++ b/runtime/doc/term.txt @@ -31,7 +31,7 @@ a non-superuser: > curl -LO https://invisible-island.net/datafiles/current/terminfo.src.gz gunzip terminfo.src.gz - tic terminfo.src + tic -x terminfo.src < *$TERM* The $TERM environment variable must match the terminal you are using! @@ -108,10 +108,22 @@ and right scroll margins as well. If Nvim detects that the terminal is Xterm, it will make use of this ability to speed up scrolling that is not the full width of the terminal. - *tui-input* + *tui-input* +Historically, terminal emulators could not distinguish between certain control +key modifiers and other keys. For example, <C-I> and <Tab> are represented in +the same way, as are <Esc> and <C-[>, <CR> and <C-M>, and <NL> and <C-J>. + +Modern terminal emulators are able to distinguish between these pairs of keys +by encoding control modifiers differently. There are two common but distinct +ways of doing this, known as "modifyOtherKeys" and "CSI u". Nvim supports both +encoding methods and at startup will tell the terminal emulator that it +understands these key encodings. If your terminal emulator supports it then +this will allow you to map the key pairs listed above separately. |<Tab>| + Nvim uses libtermkey to convert terminal escape sequences to key codes. |terminfo| is used first, and CSI sequences not in |terminfo| (including -extended keys a.k.a. modifyOtherKeys or "CSI u") can also be parsed. +extended keys a.k.a. "modifyOtherKeys" or "CSI u") can also be parsed. + For example, when running Nvim in tmux, this makes Nvim leave Insert mode and go to the window below: > tmux send-keys 'Escape' [ 2 7 u 'C-W' j @@ -124,42 +136,22 @@ For example, this sequence is recognized by Nvim as <C-kEnter>: > and can be used differently from <C-CR> in mappings. *tui-modifyOtherKeys* *tui-csiu* -Historically, terminal emulators could not distinguish between certain control -key modifiers and other keys. For example, <C-I> and <Tab> are represented the -same way, as are <Esc> and <C-[>, <CR> and <C-M>, and <NL> and <C-J>. This -meant that Nvim also could not map these keys separately. - -Modern terminal emulators are able to distinguish between these pairs of keys -by encoding control modifiers differently. There are two common but distinct -ways of doing this, known as "modifyOtherKeys" and "CSI u". Nvim supports both -encoding methods and at startup will tell the terminal emulator that it -understands these key encodings. If your terminal emulator supports it then -this will allow you to map the key pairs listed above separately. - -At startup Nvim will query your terminal to see if it supports the CSI u +At startup Nvim will query your terminal to see if it supports the "CSI u" encoding by writing the sequence > - CSI ? u CSI c - If your terminal emulator responds with > - CSI ? <flags> u - -this means your terminal supports the CSI u encoding and Nvim will tell your +this means your terminal supports the "CSI u" encoding and Nvim will tell your terminal to enable it by writing the sequence > - CSI > 1 u - -If your terminal does not support CSI u then Nvim will instead enable the +If your terminal does not support "CSI u" then Nvim will instead enable the "modifyOtherKeys" encoding by writing the sequence > - CSI > 4 ; 2 m When Nvim exits cleanly it will send the corresponding sequence to disable the special key encoding. If Nvim does not exit cleanly then your terminal emulator could be in a bad state. If this happens, simply run "reset". - *tui-colors* Nvim uses 256 colours by default, ignoring |terminfo| for most terminal types, including "linux" (whose virtual terminals have had 256-colour support since diff --git a/runtime/doc/testing.txt b/runtime/doc/testing.txt index ef5e179c86..941c440b6c 100644 --- a/runtime/doc/testing.txt +++ b/runtime/doc/testing.txt @@ -31,195 +31,24 @@ Find more information in the file src/testdir/README.txt. ============================================================================== 2. Test functions *test-functions-details* -test_garbagecollect_now() *test_garbagecollect_now()* - Like garbagecollect(), but executed right away. This must - only be called directly to avoid any structure to exist - internally, and |v:testing| must have been set before calling - any function. +See |test_garbagecollect_now()|. ============================================================================== 3. Assert functions *assert-functions-details* - -assert_beeps({cmd}) *assert_beeps()* - Run {cmd} and add an error message to |v:errors| if it does - NOT produce a beep or visual bell. - Also see |assert_fails()|, |assert_nobeep()| and - |assert-return|. - - Can also be used as a |method|: > - GetCmd()->assert_beeps() -< - *assert_equal()* -assert_equal({expected}, {actual} [, {msg}]) - When {expected} and {actual} are not equal an error message is - added to |v:errors| and 1 is returned. Otherwise zero is - returned |assert-return|. - There is no automatic conversion, the String "4" is different - from the Number 4. And the number 4 is different from the - Float 4.0. The value of 'ignorecase' is not used here, case - always matters. - When {msg} is omitted an error in the form "Expected - {expected} but got {actual}" is produced. - Example: > - assert_equal('foo', 'bar') -< Will result in a string to be added to |v:errors|: - test.vim line 12: Expected 'foo' but got 'bar' ~ - - Can also be used as a |method|: > - mylist->assert_equal([1, 2, 3]) - -< *assert_equalfile()* -assert_equalfile({fname-one}, {fname-two}) - When the files {fname-one} and {fname-two} do not contain - exactly the same text an error message is added to |v:errors|. - Also see |assert-return|. - When {fname-one} or {fname-two} does not exist the error will - mention that. - - Can also be used as a |method|: > - GetLog()->assert_equalfile('expected.log') - -assert_exception({error} [, {msg}]) *assert_exception()* - When v:exception does not contain the string {error} an error - message is added to |v:errors|. Also see |assert-return|. - This can be used to assert that a command throws an exception. - Using the error number, followed by a colon, avoids problems - with translations: > - try - commandthatfails - call assert_false(1, 'command should have failed') - catch - call assert_exception('E492:') - endtry -< - *assert_fails()* -assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) - Run {cmd} and add an error message to |v:errors| if it does - NOT produce an error or when {error} is not found in the - error message. Also see |assert-return|. - - When {error} is a string it must be found literally in the - first reported error. Most often this will be the error code, - including the colon, e.g. "E123:". > - assert_fails('bad cmd', 'E987:') -< - When {error} is a |List| with one or two strings, these are - used as patterns. The first pattern is matched against the - first reported error: > - assert_fails('cmd', ['E987:.*expected bool']) -< The second pattern, if present, is matched against the last - reported error. To only match the last error use an empty - string for the first error: > - assert_fails('cmd', ['', 'E987:']) -< - If {msg} is empty then it is not used. Do this to get the - default message when passing the {lnum} argument. - - When {lnum} is present and not negative, and the {error} - argument is present and matches, then this is compared with - the line number at which the error was reported. That can be - the line number in a function or in a script. - - When {context} is present it is used as a pattern and matched - against the context (script name or function name) where - {lnum} is located in. - - Note that beeping is not considered an error, and some failing - commands only beep. Use |assert_beeps()| for those. - - Can also be used as a |method|: > - GetCmd()->assert_fails('E99:') - -assert_false({actual} [, {msg}]) *assert_false()* - When {actual} is not false an error message is added to - |v:errors|, like with |assert_equal()|. - Also see |assert-return|. - A value is false when it is zero. When {actual} is not a - number the assert fails. - When {msg} is omitted an error in the form - "Expected False but got {actual}" is produced. - - Can also be used as a |method|: > - GetResult()->assert_false() - -assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()* - This asserts number and |Float| values. When {actual} is lower - than {lower} or higher than {upper} an error message is added - to |v:errors|. Also see |assert-return|. - When {msg} is omitted an error in the form - "Expected range {lower} - {upper}, but got {actual}" is - produced. - - *assert_match()* -assert_match({pattern}, {actual} [, {msg}]) - When {pattern} does not match {actual} an error message is - added to |v:errors|. Also see |assert-return|. - - {pattern} is used as with |expr-=~|: The matching is always done - like 'magic' was set and 'cpoptions' is empty, no matter what - the actual value of 'magic' or 'cpoptions' is. - - {actual} is used as a string, automatic conversion applies. - Use "^" and "$" to match with the start and end of the text. - Use both to match the whole text. - - When {msg} is omitted an error in the form - "Pattern {pattern} does not match {actual}" is produced. - Example: > - assert_match('^f.*o$', 'foobar') -< Will result in a string to be added to |v:errors|: - test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~ - - Can also be used as a |method|: > - getFile()->assert_match('foo.*') -< -assert_nobeep({cmd}) *assert_nobeep()* - Run {cmd} and add an error message to |v:errors| if it - produces a beep or visual bell. - Also see |assert_beeps()|. - - Can also be used as a |method|: > - GetCmd()->assert_nobeep() -< - *assert_notequal()* -assert_notequal({expected}, {actual} [, {msg}]) - The opposite of `assert_equal()`: add an error message to - |v:errors| when {expected} and {actual} are equal. - Also see |assert-return|. - - Can also be used as a |method|: > - mylist->assert_notequal([1, 2, 3]) - -< *assert_notmatch()* -assert_notmatch({pattern}, {actual} [, {msg}]) - The opposite of `assert_match()`: add an error message to - |v:errors| when {pattern} matches {actual}. - Also see |assert-return|. - - Can also be used as a |method|: > - getFile()->assert_notmatch('bar.*') - - -assert_report({msg}) *assert_report()* - Report a test failure directly, using String {msg}. - Always returns one. - - Can also be used as a |method|: > - GetMessage()->assert_report() - - -assert_true({actual} [, {msg}]) *assert_true()* - When {actual} is not true an error message is added to - |v:errors|, like with |assert_equal()|. - Also see |assert-return|. - A value is |TRUE| when it is a non-zero number or |v:true|. - When {actual} is not a number or |v:true| the assert fails. - When {msg} is omitted an error in the form "Expected True but - got {actual}" is produced. - - Can also be used as a |method|: > - GetResult()->assert_true() -< +See: + - |assert_beeps()| + - |assert_equal()| + - |assert_equalfile()| + - |assert_exception()| + - |assert_fails()| + - |assert_false()| + - |assert_inrange()| + - |assert_match()| + - |assert_nobeep()| + - |assert_notequal()| + - |assert_notmatch()| + - |assert_report()| + - |assert_true()| vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/tips.txt b/runtime/doc/tips.txt index 5d5e89da77..88528b0e4e 100644 --- a/runtime/doc/tips.txt +++ b/runtime/doc/tips.txt @@ -47,7 +47,7 @@ is an overview with tags to jump to: |gf| Go to file name under the cursor. -|%| Go to matching (), {}, [], /* */, #if, #else, #endif. +|%| Go to matching (), {}, [], `/* */`, #if, #else, #endif. |[/| Go to previous start of comment. |]/| Go to next end of comment. |[#| Go back to unclosed #if, #ifdef, or #else. @@ -59,8 +59,8 @@ is an overview with tags to jump to: |v_ab| Select "a block" from "[(" to "])", including braces |v_ib| Select "inner block" from "[(" to "])" -|v_aB| Select "a block" from "[{" to "]}", including brackets -|v_iB| Select "inner block" from "[{" to "]}" +|v_aB| Select "a block" from `[{` to `]}`, including brackets +|v_iB| Select "inner block" from `[{` to `]}` ============================================================================== Finding where identifiers are used *ident-search* @@ -196,7 +196,7 @@ charset.c digraph.c ... -and I want to rename *.c *.bla. I'd do it like this: > +and I want to rename `*.c` `*.bla`. I'd do it like this: > $ vim :r !ls *.c @@ -346,14 +346,26 @@ comma-separated list of extension(s) you find yourself wanting to edit: > " vim -b : edit binary using xxd-format! augroup Binary - au! - au BufReadPre *.bin let &bin=1 - au BufReadPost *.bin if &bin | %!xxd - au BufReadPost *.bin set ft=xxd | endif - au BufWritePre *.bin if &bin | %!xxd -r - au BufWritePre *.bin endif - au BufWritePost *.bin if &bin | %!xxd - au BufWritePost *.bin set nomod | endif + autocmd! + autocmd BufReadPre *.bin set binary + autocmd BufReadPost *.bin + \ if &binary + \ | execute "silent %!xxd -c 32" + \ | set filetype=xxd + \ | redraw + \ | endif + autocmd BufWritePre *.bin + \ if &binary + \ | let s:view = winsaveview() + \ | execute "silent %!xxd -r -c 32" + \ | endif + autocmd BufWritePost *.bin + \ if &binary + \ | execute "silent %!xxd -c 32" + \ | set nomodified + \ | call winrestview(s:view) + \ | redraw + \ | endif augroup END ============================================================================== diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index 917863eef8..9bdc6b8d24 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -18,150 +18,129 @@ changes. This documentation may also not fully reflect the latest changes. PARSER FILES *treesitter-parsers* Parsers are the heart of tree-sitter. They are libraries that tree-sitter will -search for in the `parser` runtime directory. By default, Nvim bundles only -parsers for C, Lua, and Vimscript, but parsers can be installed manually or -via a plugin like https://github.com/nvim-treesitter/nvim-treesitter. -Parsers are searched for as `parser/{lang}.*` in any 'runtimepath' directory. -If multiple parsers for the same language are found, the first one is used. -(This typically implies the priority "user config > plugins > bundled". +search for in the `parser` runtime directory. By default, Nvim bundles parsers +for C, Lua, Vimscript, Vimdoc and Treesitter query files, but parsers can be +installed manually or via a plugin like +https://github.com/nvim-treesitter/nvim-treesitter. Parsers are searched for +as `parser/{lang}.*` in any 'runtimepath' directory. If multiple parsers for +the same language are found, the first one is used. (This typically implies +the priority "user config > plugins > bundled". A parser can also be loaded manually using a full path: >lua - vim.treesitter.require_language("python", "/path/to/python.so") + vim.treesitter.language.add('python', { path = "/path/to/python.so" }) < ============================================================================== -LANGUAGE TREES *treesitter-languagetree* - *LanguageTree* - -As buffers can contain multiple languages (e.g., Vimscript commands in a Lua -file), multiple parsers may be needed to parse the full buffer. These are -combined in a |LanguageTree| object. - -To create a LanguageTree (parser object) for a buffer and a given language, -use >lua - - tsparser = vim.treesitter.get_parser(bufnr, lang) -< -`bufnr=0` can be used for current buffer. `lang` will default to 'filetype'. -Currently, the parser will be retained for the lifetime of a buffer but this -is subject to change. A plugin should keep a reference to the parser object as -long as it wants incremental updates. - -Whenever you need to access the current syntax tree, parse the buffer: >lua - - tstree = tsparser:parse() -< -This will return a table of immutable |treesitter-tree|s that represent the -current state of the buffer. When the plugin wants to access the state after a -(possible) edit it should call `parse()` again. If the buffer wasn't edited, -the same tree will be returned again without extra work. If the buffer was -parsed before, incremental parsing will be done of the changed parts. - -Note: To use the parser directly inside a |nvim_buf_attach()| Lua callback, -you must call |vim.treesitter.get_parser()| before you register your callback. -But preferably parsing shouldn't be done directly in the change callback -anyway as they will be very frequent. Rather a plugin that does any kind of -analysis on a tree should use a timer to throttle too frequent updates. - -See |lua-treesitter-languagetree| for the list of available methods. - -============================================================================== TREESITTER TREES *treesitter-tree* - *tstree* + *TSTree* A "treesitter tree" represents the parsed contents of a buffer, which can be -used to perform further analysis. It is a |luaref-userdata| reference to an -object held by the tree-sitter library. +used to perform further analysis. It is a |userdata| reference to an object +held by the tree-sitter library. -An instance `tstree` of a treesitter tree supports the following methods. +An instance `TSTree` of a treesitter tree supports the following methods. -tstree:root() *tstree:root()* +TSTree:root() *TSTree:root()* Return the root node of this tree. -tstree:copy() *tstree:copy()* - Returns a copy of the `tstree`. +TSTree:copy() *TSTree:copy()* + Returns a copy of the `TSTree`. ============================================================================== TREESITTER NODES *treesitter-node* - *tsnode* + *TSNode* A "treesitter node" represents one specific element of the parsed contents of -a buffer, which can be captured by a |Query| for, e.g., highlighting. It is a -|luaref-userdata| reference to an object held by the tree-sitter library. +a buffer, which can be captured by a |Query| for, e.g., highlighting. It is +a |userdata| reference to an object held by the tree-sitter library. -An instance `tsnode` of a treesitter node supports the following methods. +An instance `TSNode` of a treesitter node supports the following methods. -tsnode:parent() *tsnode:parent()* +TSNode:parent() *TSNode:parent()* Get the node's immediate parent. -tsnode:next_sibling() *tsnode:next_sibling()* +TSNode:next_sibling() *TSNode:next_sibling()* Get the node's next sibling. -tsnode:prev_sibling() *tsnode:prev_sibling()* +TSNode:prev_sibling() *TSNode:prev_sibling()* Get the node's previous sibling. -tsnode:next_named_sibling() *tsnode:next_named_sibling()* +TSNode:next_named_sibling() *TSNode:next_named_sibling()* Get the node's next named sibling. -tsnode:prev_named_sibling() *tsnode:prev_named_sibling()* +TSNode:prev_named_sibling() *TSNode:prev_named_sibling()* Get the node's previous named sibling. -tsnode:iter_children() *tsnode:iter_children()* - Iterates over all the direct children of {tsnode}, regardless of whether +TSNode:iter_children() *TSNode:iter_children()* + Iterates over all the direct children of {TSNode}, regardless of whether they are named or not. Returns the child node plus the eventual field name corresponding to this child node. -tsnode:field({name}) *tsnode:field()* +TSNode:field({name}) *TSNode:field()* Returns a table of the nodes corresponding to the {name} field. -tsnode:child_count() *tsnode:child_count()* +TSNode:child_count() *TSNode:child_count()* Get the node's number of children. -tsnode:child({index}) *tsnode:child()* +TSNode:child({index}) *TSNode:child()* Get the node's child at the given {index}, where zero represents the first child. -tsnode:named_child_count() *tsnode:named_child_count()* +TSNode:named_child_count() *TSNode:named_child_count()* Get the node's number of named children. -tsnode:named_child({index}) *tsnode:named_child()* +TSNode:named_child({index}) *TSNode:named_child()* Get the node's named child at the given {index}, where zero represents the first named child. -tsnode:start() *tsnode:start()* +TSNode:start() *TSNode:start()* Get the node's start position. Return three values: the row, column and total byte count (all zero-based). -tsnode:end_() *tsnode:end_()* +TSNode:end_() *TSNode:end_()* Get the node's end position. Return three values: the row, column and total byte count (all zero-based). -tsnode:range() *tsnode:range()* - Get the range of the node. Return four values: the row, column of the - start position, then the row, column of the end position. +TSNode:range({include_bytes}) *TSNode:range()* + Get the range of the node. + + Return four or six values: + - start row + - start column + - start byte (if {include_bytes} is `true`) + - end row + - end column + - end byte (if {include_bytes} is `true`) -tsnode:type() *tsnode:type()* +TSNode:type() *TSNode:type()* Get the node's type as a string. -tsnode:symbol() *tsnode:symbol()* +TSNode:symbol() *TSNode:symbol()* Get the node's type as a numerical id. -tsnode:named() *tsnode:named()* +TSNode:named() *TSNode:named()* Check if the node is named. Named nodes correspond to named rules in the grammar, whereas anonymous nodes correspond to string literals in the grammar. -tsnode:missing() *tsnode:missing()* +TSNode:missing() *TSNode:missing()* Check if the node is missing. Missing nodes are inserted by the parser in order to recover from certain kinds of syntax errors. -tsnode:has_error() *tsnode:has_error()* +TSNode:extra() *TSNode:extra()* + Check if the node is extra. Extra nodes represent things like comments, + which are not required by the grammar but can appear anywhere. + +TSNode:has_changes() *TSNode:has_changes()* + Check if a syntax node has been edited. + +TSNode:has_error() *TSNode:has_error()* Check if the node is a syntax error or contains any syntax errors. -tsnode:sexpr() *tsnode:sexpr()* +TSNode:sexpr() *TSNode:sexpr()* Get an S-expression representing the node as a string. -tsnode:id() *tsnode:id()* +TSNode:id() *TSNode:id()* Get an unique identifier for the node inside its own tree. No guarantees are made about this identifier's internal representation, @@ -171,20 +150,29 @@ tsnode:id() *tsnode:id()* Note: The `id` is not guaranteed to be unique for nodes from different trees. - *tsnode:descendant_for_range()* -tsnode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) +TSNode:tree() *TSNode:tree()* + Get the |TSTree| of the node. + *TSNode:descendant_for_range()* +TSNode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) Get the smallest node within this node that spans the given range of (row, column) positions - *tsnode:named_descendant_for_range()* -tsnode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) + *TSNode:named_descendant_for_range()* +TSNode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) Get the smallest named node within this node that spans the given range of (row, column) positions + *TSNode:equal()* +TSNode:equal({node}) + Check if {node} refers to the same node within the same tree. + + *TSNode:byte_length()* +TSNode:byte_length() + Return the number of bytes spanned by this node. ============================================================================== TREESITTER QUERIES *treesitter-query* -Treesitter queries are a way to extract information about a parsed |tstree|, +Treesitter queries are a way to extract information about a parsed |TSTree|, e.g., for the purpose of highlighting. Briefly, a `query` consists of one or more patterns. A `pattern` is defined over node types in the syntax tree. A `match` corresponds to specific elements of the syntax tree which match a @@ -202,7 +190,7 @@ Nvim looks for queries as `*.scm` files in a `queries` directory under purpose, e.g., `queries/lua/highlights.scm` for highlighting Lua files. By default, the first query on `runtimepath` is used (which usually implies that user config takes precedence over plugins, which take precedence over -queries bundled with Neovim). If a query should extend other queries instead +queries bundled with Nvim). If a query should extend other queries instead of replacing them, use |treesitter-query-modeline-extends|. See |lua-treesitter-query| for the list of available methods for working with @@ -212,7 +200,7 @@ treesitter queries from Lua. TREESITTER QUERY PREDICATES *treesitter-predicates* Predicates are special scheme nodes that are evaluated to conditionally capture -nodes. For example, the `eq?` predicate can be used as follows: > +nodes. For example, the `eq?` predicate can be used as follows: >query ((identifier) @foo (#eq? @foo "foo")) < @@ -221,13 +209,13 @@ to only match identifier corresponding to the `"foo"` text. The following predicates are built in: `eq?` *treesitter-predicate-eq?* - Match a string against the text corresponding to a node: > + Match a string against the text corresponding to a node: >query ((identifier) @foo (#eq? @foo "foo")) ((node1) @left (node2) @right (#eq? @left @right)) < `match?` *treesitter-predicate-match?* `vim-match?` *treesitter-predicate-vim-match?* - Match a |regexp| against the text corresponding to a node: > + Match a |regexp| against the text corresponding to a node: >query ((identifier) @constant (#match? @constant "^[A-Z_]+$")) < Note: The `^` and `$` anchors will match the start and end of the node's text. @@ -237,31 +225,43 @@ The following predicates are built in: similar to `match?` `contains?` *treesitter-predicate-contains?* - Match a string against parts of the text corresponding to a node: > + Match a string against parts of the text corresponding to a node: >query ((identifier) @foo (#contains? @foo "foo")) ((identifier) @foo-bar (#contains? @foo-bar "foo" "bar")) < `any-of?` *treesitter-predicate-any-of?* Match any of the given strings against the text corresponding to - a node: > + a node: >query ((identifier) @foo (#any-of? @foo "foo" "bar")) < This is the recommended way to check if the node matches one of many keywords, as it has been optimized for this. + `has-ancestor?` *treesitter-predicate-has-ancestor?* + Match any of the given node types against all ancestors of a node: >query + ((identifier) @variable.builtin + (#any-of? @variable.builtin "begin" "end") + (#has-ancestor? @variable.builtin range_expression)) +< + `has-parent?` *treesitter-predicate-has-parent?* + Match any of the given node types against the direct ancestor of a + node: >query + (((field_expression + (field_identifier) @method)) @_parent + (#has-parent? @_parent template_method function_declarator)) +< *lua-treesitter-not-predicate* Each predicate has a `not-` prefixed predicate that is just the negation of the predicate. Further predicates can be added via |vim.treesitter.query.add_predicate()|. -Use |vim.treesitter.query.list_predicates()| to list all available -predicates. +Use |vim.treesitter.query.list_predicates()| to list all available predicates. TREESITTER QUERY DIRECTIVES *treesitter-directives* Treesitter directives store metadata for a node or match and perform side -effects. For example, the `set!` directive sets metadata on the match or node: > +effects. For example, the `set!` directive sets metadata on the match or node: >query ((identifier) @foo (#set! "type" "parameter")) < @@ -277,7 +277,7 @@ The following directives are built in: {key} {value} - Examples: > + Examples: >query ((identifier) @foo (#set! @foo "kind" "parameter")) ((node1) @left (node2) @right (#set! "type" "pair")) < @@ -293,18 +293,37 @@ The following directives are built in: {end_row} {end_col} - Example: > + Example: >query ((identifier) @constant (#offset! @constant 0 1 0 -1)) < + `gsub!` *treesitter-directive-gsub!* + Transforms the content of the node using a Lua pattern. This will set + a new `metadata[capture_id].text`. + + Parameters: ~ + {capture_id} + {pattern} + + Example: >query + (#gsub! @_node ".*%.(.*)" "%1") +< + `trim!` *treesitter-directive-trim!* + Trim blank lines from the end of the node. This will set a new + `metadata[capture_id].range`. + + Parameters: ~ + {capture_id} + Example: >query + (#trim! @fold) +< Further directives can be added via |vim.treesitter.query.add_directive()|. -Use |vim.treesitter.query.list_directives()| to list all available -directives. +Use |vim.treesitter.query.list_directives()| to list all available directives. TREESITTER QUERY MODELINES *treesitter-query-modeline* -Neovim supports to customize the behavior of the queries using a set of +Nvim supports to customize the behavior of the queries using a set of "modelines", that is comments in the queries starting with `;`. Here are the currently supported modeline alternatives: @@ -323,11 +342,12 @@ currently supported modeline alternatives: a base depends on your 'runtimepath' value. Note: These modeline comments must be at the top of the query, but can be -repeated, for example, the following two modeline blocks are both valid: > - +repeated, for example, the following two modeline blocks are both valid: +>query ;; inherits: foo,bar ;; extends - +< +>query ;; extends ;; ;; inherits: baz @@ -336,14 +356,14 @@ repeated, for example, the following two modeline blocks are both valid: > TREESITTER SYNTAX HIGHLIGHTING *treesitter-highlight* Syntax highlighting is specified through queries named `highlights.scm`, -which match a |tsnode| in the parsed |tstree| to a `capture` that can be -assigned a highlight group. For example, the query > +which match a |TSNode| in the parsed |TSTree| to a `capture` that can be +assigned a highlight group. For example, the query >query (parameters (identifier) @parameter) < matches any `identifier` node inside a function `parameter` node (e.g., the `bar` in `foo(bar)`) to the capture named `@parameter`. It is also possible to -match literal expressions (provided the parser returns them): > +match literal expressions (provided the parser returns them): >query "return" @keyword.return < @@ -428,7 +448,7 @@ The following captures are linked by default to standard |group-name|s: *treesitter-highlight-spell* The special `@spell` capture can be used to indicate that a node should be spell checked by Nvim's builtin |spell| checker. For example, the following -capture marks comments as to be checked: > +capture marks comments as to be checked: >query (comment) @spell < @@ -439,14 +459,14 @@ There is also `@nospell` which disables spellchecking regions with `@spell`. Treesitter highlighting supports |conceal| via the `conceal` metadata. By convention, nodes to be concealed are captured as `@conceal`, but any capture can be used. For example, the following query can be used to hide code block -delimiters in Markdown: > +delimiters in Markdown: >query - (fenced_code_block_delimiter) @conceal (#set! conceal "") + (fenced_code_block_delimiter @conceal (#set! conceal "")) < It is also possible to replace a node with a single character, which (unlike legacy syntax) can be given a custom highlight. For example, the following (ill-advised) query replaces the `!=` operator by a Unicode glyph, which is -still highlighted the same as other operators: > +still highlighted the same as other operators: >query "!=" @operator (#set! conceal "≠") < @@ -457,10 +477,61 @@ Treesitter uses |nvim_buf_set_extmark()| to set highlights with a default priority of 100. This enables plugins to set a highlighting priority lower or higher than tree-sitter. It is also possible to change the priority of an individual query pattern manually by setting its `"priority"` metadata -attribute: > +attribute: >query + + ((super_important_node) @superimportant (#set! "priority" 105)) +< - (super_important_node) @ImportantHighlight (#set! "priority" 105) +============================================================================== +TREESITTER LANGUAGE INJECTIONS *treesitter-language-injections* < + +Note the following information is adapted from: + https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection + +Some source files contain code written in multiple different languages. +Examples include: + + • HTML files, which can contain JavaScript inside of `<script>` tags and + CSS inside of `<style>` tags + • ERB files, which contain Ruby inside of `<%` `%>` tags, and HTML outside of + those tags + • PHP files, which can contain HTML between the `<php` tags + • JavaScript files, which contain regular expression syntax within regex + literals + • Ruby, which can contain snippets of code inside of heredoc literals, + where the heredoc delimiter often indicates the language + • Lua, which can contain snippets of Vimscript inside |vim.cmd()| calls. + • Vimscript, which can contain snippets of Lua inside |:lua-heredoc| + blocks. + +All of these examples can be modeled in terms of a parent syntax tree and one +or more injected syntax trees, which reside inside of certain nodes in the +parent tree. The language injection query allows you to specify these +“injections” using the following captures: + + • `@injection.content` - indicates that the captured node should have its + contents re-parsed using another language. + • `@injection.language` - indicates that the captured node’s text may + contain the name of a language that should be used to re-parse the + `@injection.content`. + +The language injection behavior can also be configured by some properties +associated with patterns: + + • `injection.language` - can be used to hard-code the name of a specific + language. + • `injection.combined` - indicates that all of the matching nodes in the + tree should have their content parsed as one nested document. + • `injection.include-children` - indicates that the `@injection.content` + node's entire text should be re-parsed, including the text of its child + nodes. By default, child nodes' text will be excluded from the injected + document. + • `injection.self` - indicates that the node's text should be parsed with + the same language as the node's LanguageTree. + • `injection.parent` - indicates that the captured node’s text should + be parsed with the same language as the node's parent LanguageTree. + ============================================================================== VIM.TREESITTER *lua-treesitter* @@ -481,12 +552,34 @@ library. ============================================================================== Lua module: vim.treesitter *lua-treesitter-core* +foldexpr({lnum}) *vim.treesitter.foldexpr()* + Returns the fold level for {lnum} in the current buffer. Can be set + directly to 'foldexpr': >lua + vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()' +< + + Parameters: ~ + • {lnum} (integer|nil) Line number to calculate fold level for + + Return: ~ + (string) + +foldtext() *vim.treesitter.foldtext()* + Returns the highlighted content of the first line of the fold or falls + back to |foldtext()| if no treesitter parser is found. Can be set directly + to 'foldtext': >lua + vim.wo.foldtext = 'v:lua.vim.treesitter.foldtext()' +< + + Return: ~ + `{ [1]: string, [2]: string[] }[]` | string + *vim.treesitter.get_captures_at_cursor()* get_captures_at_cursor({winnr}) Returns a list of highlight capture names under the cursor Parameters: ~ - • {winnr} (number|nil) Window handle or 0 for current window (default) + • {winnr} (integer|nil) Window handle or 0 for current window (default) Return: ~ string[] List of capture names @@ -500,63 +593,90 @@ get_captures_at_pos({bufnr}, {row}, {col}) if none are defined). Parameters: ~ - • {bufnr} (number) Buffer number (0 for current buffer) - • {row} (number) Position row - • {col} (number) Position column + • {bufnr} (integer) Buffer number (0 for current buffer) + • {row} (integer) Position row + • {col} (integer) Position column Return: ~ - table[] List of captures `{ capture = "capture name", metadata = { ... - } }` + table[] List of captures `{ capture = "name", metadata = { ... } }` + +get_node({opts}) *vim.treesitter.get_node()* + Returns the smallest named node at the given position -get_node_at_cursor({winnr}) *vim.treesitter.get_node_at_cursor()* - Returns the smallest named node under the cursor + NOTE: Calling this on an unparsed tree can yield an invalid node. If the + tree is not known to be parsed by, e.g., an active highlighter, parse the + tree first via >lua + vim.treesitter.get_parser(bufnr):parse(range) +< Parameters: ~ - • {winnr} (number|nil) Window handle or 0 for current window (default) + • {opts} (table|nil) Optional keyword arguments: + • bufnr integer|nil Buffer number (nil or 0 for current + buffer) + • pos table|nil 0-indexed (row, col) tuple. Defaults to cursor + position in the current window. Required if {bufnr} is not + the current buffer + • ignore_injections boolean Ignore injected languages (default + true) Return: ~ - (string) Name of node under the cursor + |TSNode| | nil Node at the given position - *vim.treesitter.get_node_at_pos()* -get_node_at_pos({bufnr}, {row}, {col}, {opts}) - Returns the smallest named node at the given position +get_node_range({node_or_range}) *vim.treesitter.get_node_range()* + Returns the node's range or an unpacked range table Parameters: ~ - • {bufnr} (number) Buffer number (0 for current buffer) - • {row} (number) Position row - • {col} (number) Position column - • {opts} (table) Optional keyword arguments: - • lang string|nil Parser language - • ignore_injections boolean Ignore injected languages - (default true) + • {node_or_range} (|TSNode| | table) Node or table of positions - Return: ~ - userdata|nil |tsnode| under the cursor + Return (multiple): ~ + (integer) start_row + (integer) start_col + (integer) end_row + (integer) end_col -get_node_range({node_or_range}) *vim.treesitter.get_node_range()* - Returns the node's range or an unpacked range table + *vim.treesitter.get_node_text()* +get_node_text({node}, {source}, {opts}) + Gets the text corresponding to a given node Parameters: ~ - • {node_or_range} (userdata|table) |tsnode| or table of positions + • {node} |TSNode| + • {source} (integer|string) Buffer or string from which the {node} is + extracted + • {opts} (table|nil) Optional parameters. + • metadata (table) Metadata of a specific capture. This + would be set to `metadata[capture_id]` when using + |vim.treesitter.query.add_directive()|. Return: ~ - (table) `{ start_row, start_col, end_row, end_col }` + (string) get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()* - Returns the parser for a specific buffer and filetype and attaches it to - the buffer + Returns the parser for a specific buffer and attaches it to the buffer If needed, this will create the parser. Parameters: ~ - • {bufnr} (number|nil) Buffer the parser should be tied to (default: + • {bufnr} (integer|nil) Buffer the parser should be tied to (default: current buffer) • {lang} (string|nil) Filetype of this parser (default: buffer filetype) • {opts} (table|nil) Options to pass to the created language tree Return: ~ - LanguageTree |LanguageTree| object to use for parsing + |LanguageTree| object to use for parsing + +get_range({node}, {source}, {metadata}) *vim.treesitter.get_range()* + Get the range of a |TSNode|. Can also supply {source} and {metadata} to + get the range with directives applied. + + Parameters: ~ + • {node} |TSNode| + • {source} integer|string|nil Buffer or string from which the {node} + is extracted + • {metadata} TSMetadata|nil + + Return: ~ + (table) *vim.treesitter.get_string_parser()* get_string_parser({str}, {lang}, {opts}) @@ -568,14 +688,42 @@ get_string_parser({str}, {lang}, {opts}) • {opts} (table|nil) Options to pass to the created language tree Return: ~ - LanguageTree |LanguageTree| object to use for parsing + |LanguageTree| object to use for parsing + +inspect_tree({opts}) *vim.treesitter.inspect_tree()* + Open a window that displays a textual representation of the nodes in the + language tree. + + While in the window, press "a" to toggle display of anonymous nodes, "I" + to toggle the display of the source language of each node, "o" to toggle + the query editor, and press <Enter> to jump to the node under the cursor + in the source buffer. + + Can also be shown with `:InspectTree`. *:InspectTree* + + Parameters: ~ + • {opts} (table|nil) Optional options table with the following possible + keys: + • lang (string|nil): The language of the source buffer. If + omitted, the filetype of the source buffer is used. + • bufnr (integer|nil): Buffer to draw the tree into. If + omitted, a new buffer is created. + • winid (integer|nil): Window id to display the tree buffer + in. If omitted, a new window is created with {command}. + • command (string|nil): Vimscript command to create the + window. Default value is "60vnew". Only used when {winid} is + nil. + • title (string|fun(bufnr:integer):string|nil): Title of the + window. If a function, it accepts the buffer number of the + source buffer as its only argument and should return a + string. is_ancestor({dest}, {source}) *vim.treesitter.is_ancestor()* Determines whether a node is the ancestor of another Parameters: ~ - • {dest} userdata Possible ancestor |tsnode| - • {source} userdata Possible descendant |tsnode| + • {dest} |TSNode| Possible ancestor + • {source} |TSNode| Possible descendant Return: ~ (boolean) True if {dest} is an ancestor of {source} @@ -585,9 +733,9 @@ is_in_node_range({node}, {line}, {col}) Determines whether (line, col) position is in node range Parameters: ~ - • {node} userdata |tsnode| defining the range - • {line} (number) Line (0-based) - • {col} (number) Column (0-based) + • {node} |TSNode| defining the range + • {line} (integer) Line (0-based) + • {col} (integer) Column (0-based) Return: ~ (boolean) True if the position is in node range @@ -596,37 +744,12 @@ node_contains({node}, {range}) *vim.treesitter.node_contains()* Determines if a node contains a range Parameters: ~ - • {node} userdata |tsnode| + • {node} |TSNode| • {range} (table) Return: ~ (boolean) True if the {node} contains the {range} -show_tree({opts}) *vim.treesitter.show_tree()* - Open a window that displays a textual representation of the nodes in the - language tree. - - While in the window, press "a" to toggle display of anonymous nodes, "I" - to toggle the display of the source language of each node, and press - <Enter> to jump to the node under the cursor in the source buffer. - - Parameters: ~ - • {opts} (table|nil) Optional options table with the following possible - keys: - • lang (string|nil): The language of the source buffer. If - omitted, the filetype of the source buffer is used. - • bufnr (number|nil): Buffer to draw the tree into. If - omitted, a new buffer is created. - • winid (number|nil): Window id to display the tree buffer in. - If omitted, a new window is created with {command}. - • command (string|nil): Vimscript command to create the - window. Default value is "topleft 60vnew". Only used when - {winid} is nil. - • title (string|fun(bufnr:number):string|nil): Title of the - window. If a function, it accepts the buffer number of the - source buffer as its only argument and should return a - string. - start({bufnr}, {lang}) *vim.treesitter.start()* Starts treesitter highlighting for a buffer @@ -637,17 +760,16 @@ start({bufnr}, {lang}) *vim.treesitter.start()* the call to `start`. Example: >lua - - vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', - callback = function(args) - vim.treesitter.start(args.buf, 'latex') - vim.bo[args.buf].syntax = 'on' -- only if additional legacy syntax is needed - end - }) + vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex', + callback = function(args) + vim.treesitter.start(args.buf, 'latex') + vim.bo[args.buf].syntax = 'on' -- only if additional legacy syntax is needed + end + }) < Parameters: ~ - • {bufnr} (number|nil) Buffer to be highlighted (default: current + • {bufnr} (integer|nil) Buffer to be highlighted (default: current buffer) • {lang} (string|nil) Language of the parser (default: buffer filetype) @@ -656,14 +778,45 @@ stop({bufnr}) *vim.treesitter.stop()* Stops treesitter highlighting for a buffer Parameters: ~ - • {bufnr} (number|nil) Buffer to stop highlighting (default: current + • {bufnr} (integer|nil) Buffer to stop highlighting (default: current buffer) ============================================================================== Lua module: vim.treesitter.language *lua-treesitter-language* -inspect_language({lang}) *vim.treesitter.language.inspect_language()* +add({lang}, {opts}) *vim.treesitter.language.add()* + Load parser with name {lang} + + Parsers are searched in the `parser` runtime directory, or the provided + {path} + + Parameters: ~ + • {lang} (string) Name of the parser (alphanumerical and `_` only) + • {opts} (table|nil) Options: + • filetype (string|string[]) Default filetype the parser + should be associated with. Defaults to {lang}. + • path (string|nil) Optional path the parser is located at + • symbol_name (string|nil) Internal symbol name for the + language to load + +get_filetypes({lang}) *vim.treesitter.language.get_filetypes()* + Get the filetypes associated with the parser named {lang}. + + Parameters: ~ + • {lang} (string) Name of parser + + Return: ~ + string[] filetypes + +get_lang({filetype}) *vim.treesitter.language.get_lang()* + Parameters: ~ + • {filetype} (string) + + Return: ~ + (string|nil) + +inspect({lang}) *vim.treesitter.language.inspect()* Inspects the provided language. Inspecting provides some useful information on the language like node @@ -675,23 +828,12 @@ inspect_language({lang}) *vim.treesitter.language.inspect_language()* Return: ~ (table) - *vim.treesitter.language.require_language()* -require_language({lang}, {path}, {silent}, {symbol_name}) - Asserts that a parser for the language {lang} is installed. - - Parsers are searched in the `parser` runtime directory, or the provided - {path} +register({lang}, {filetype}) *vim.treesitter.language.register()* + Register a parser named {lang} to be used for {filetype}(s). Parameters: ~ - • {lang} (string) Language the parser should parse - • {path} (string|nil) Optional path the parser is located at - • {silent} (boolean|nil) Don't throw an error if language not - found - • {symbol_name} (string|nil) Internal symbol name for the language to - load - - Return: ~ - (boolean) If the specified language is installed + • {lang} (string) Name of parser + • {filetype} string|string[] Filetype(s) to associate with lang ============================================================================== @@ -708,8 +850,8 @@ add_directive({name}, {handler}, {force}) Parameters: ~ • {name} (string) Name of the directive, without leading # - • {handler} function(match:table, pattern:string, bufnr:number, - predicate:string[], metadata:table) + • {handler} function(match:table<string,|TSNode|>, pattern:string, + bufnr:integer, predicate:string[], metadata:table) • match: see |treesitter-query| • node-level data are accessible via `match[capture_id]` @@ -717,6 +859,7 @@ add_directive({name}, {handler}, {force}) • predicate: list of strings containing the full directive being called, e.g. `(node (#set! conceal "-"))` would get the predicate `{ "#set!", "conceal", "-" }` + • {force} (boolean|nil) *vim.treesitter.query.add_predicate()* add_predicate({name}, {handler}, {force}) @@ -724,27 +867,27 @@ add_predicate({name}, {handler}, {force}) Parameters: ~ • {name} (string) Name of the predicate, without leading # - • {handler} function(match:table, pattern:string, bufnr:number, - predicate:string[]) + • {handler} function(match:table<string,|TSNode|>, pattern:string, + bufnr:integer, predicate:string[]) • see |vim.treesitter.query.add_directive()| for argument meanings + • {force} (boolean|nil) - *vim.treesitter.query.get_node_text()* -get_node_text({node}, {source}, {opts}) - Gets the text corresponding to a given node +edit({lang}) *vim.treesitter.query.edit()* + Opens a live editor to query the buffer you started from. - Parameters: ~ - • {node} userdata |tsnode| - • {source} (number|string) Buffer or string from which the {node} is - extracted - • {opts} (table|nil) Optional parameters. - • concat: (boolean) Concatenate result in a string (default - true) + Can also be shown with *:EditQuery*. - Return: ~ - (string[]|string) + If you move the cursor to a capture name ("@foo"), text matching the + capture is highlighted in the source buffer. The query editor is a scratch + buffer, use `:write` to save it. You can find example queries at + `$VIMRUNTIME/queries/`. + + Parameters: ~ + • {lang} (string|nil) language to open the query editor for. If + omitted, inferred from the current buffer's filetype. -get_query({lang}, {query_name}) *vim.treesitter.query.get_query()* +get({lang}, {query_name}) *vim.treesitter.query.get()* Returns the runtime query {query_name} for {lang}. Parameters: ~ @@ -752,10 +895,10 @@ get_query({lang}, {query_name}) *vim.treesitter.query.get_query()* • {query_name} (string) Name of the query (e.g. "highlights") Return: ~ - Query Parsed query + Query|nil Parsed query - *vim.treesitter.query.get_query_files()* -get_query_files({lang}, {query_name}, {is_included}) + *vim.treesitter.query.get_files()* +get_files({lang}, {query_name}, {is_included}) Gets the list of files used to make up a query Parameters: ~ @@ -768,6 +911,28 @@ get_query_files({lang}, {query_name}, {is_included}) string[] query_files List of files to load for given query and language +lint({buf}, {opts}) *vim.treesitter.query.lint()* + Lint treesitter queries using installed parser, or clear lint errors. + + Use |treesitter-parsers| in runtimepath to check the query file in {buf} + for errors: + + • verify that used nodes are valid identifiers in the grammar. + • verify that predicates and directives are valid. + • verify that top-level s-expressions are valid. + + The found diagnostics are reported using |diagnostic-api|. By default, the + parser used for verification is determined by the containing folder of the + query file, e.g., if the path ends in `/lua/highlights.scm` , the parser for the `lua` language will be used. + + Parameters: ~ + • {buf} (integer) Buffer handle + • {opts} (QueryLinterOpts|nil) Optional keyword arguments: + • langs (string|string[]|nil) Language(s) to use for checking + the query. If multiple languages are specified, queries are + validated for all of them + • clear (boolean) if `true`, just clear current lint errors + list_directives() *vim.treesitter.query.list_directives()* Lists the currently available directives to use in queries. @@ -780,7 +945,14 @@ list_predicates() *vim.treesitter.query.list_predicates()* Return: ~ string[] List of supported predicates. -parse_query({lang}, {query}) *vim.treesitter.query.parse_query()* +omnifunc({findstart}, {base}) *vim.treesitter.query.omnifunc()* + Omnifunc for completing node names and predicates in treesitter queries. + + Use via >lua + vim.bo.omnifunc = 'v:lua.vim.treesitter.query.omnifunc' +< + +parse({lang}, {query}) *vim.treesitter.query.parse()* Parse {query} as a string. (If the query is in a file, the caller should read the contents into a string before calling). @@ -800,44 +972,41 @@ parse_query({lang}, {query}) *vim.treesitter.query.parse_query()* Query Parsed query *Query:iter_captures()* -Query:iter_captures({self}, {node}, {source}, {start}, {stop}) +Query:iter_captures({node}, {source}, {start}, {stop}) Iterate over all captures from all matches inside {node} {source} is needed if the query contains predicates; then the caller must ensure to use a freshly parsed tree consistent with the current text of - the buffer (if relevant). {start_row} and {end_row} can be used to limit - matches inside a row range (this is typically used with root node as the - {node}, i.e., to get syntax highlight matches in the current viewport). - When omitted, the {start} and {end} row values are used from the given - node. + the buffer (if relevant). {start} and {stop} can be used to limit matches + inside a row range (this is typically used with root node as the {node}, + i.e., to get syntax highlight matches in the current viewport). When + omitted, the {start} and {stop} row values are used from the given node. The iterator returns three values: a numeric id identifying the capture, the captured node, and metadata from any directives processing the match. The following example shows how to get captures by name: >lua - - for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do - local name = query.captures[id] -- name of the capture in the query - -- typically useful info about the node: - local type = node:type() -- type of the captured node - local row1, col1, row2, col2 = node:range() -- range of the capture - ... use the info here ... - end + for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do + local name = query.captures[id] -- name of the capture in the query + -- typically useful info about the node: + local type = node:type() -- type of the captured node + local row1, col1, row2, col2 = node:range() -- range of the capture + -- ... use the info here ... + end < Parameters: ~ - • {node} userdata |tsnode| under which the search will occur - • {source} (number|string) Source buffer or string to extract text from - • {start} (number) Starting line for the search - • {stop} (number) Stopping line for the search (end-exclusive) - • {self} + • {node} |TSNode| under which the search will occur + • {source} (integer|string) Source buffer or string to extract text + from + • {start} (integer) Starting line for the search + • {stop} (integer) Stopping line for the search (end-exclusive) Return: ~ - (number) capture Matching capture id - (table) capture_node Capture for {node} - (table) metadata for the {capture} + (fun(end_line: integer|nil): integer, TSNode, TSMetadata): capture id, + capture node, metadata *Query:iter_matches()* -Query:iter_matches({self}, {node}, {source}, {start}, {stop}) +Query:iter_matches({node}, {source}, {start}, {stop}, {opts}) Iterates the matches of self on a given range. Iterate over all matches within a {node}. The arguments are the same as @@ -845,34 +1014,36 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop}) (1-based) index of the pattern in the query, a table mapping capture indices to nodes, and metadata from any directives processing the match. If the query has more than one pattern, the capture table might be sparse - and e.g. `pairs()` method should be used over `ipairs` . Here is an example iterating over all captures in every match: >lua - - for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do - 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 - - ... use the info here ... - end - end + and e.g. `pairs()` method should be used over `ipairs`. Here is an example + iterating over all captures in every match: >lua + for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do + 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 + + -- ... use the info here ... + end + end < Parameters: ~ - • {node} userdata |tsnode| under which the search will occur - • {source} (number|string) Source buffer or string to search - • {start} (number) Starting line for the search - • {stop} (number) Stopping line for the search (end-exclusive) - • {self} + • {node} |TSNode| under which the search will occur + • {source} (integer|string) Source buffer or string to search + • {start} (integer) Starting line for the search + • {stop} (integer) Stopping line for the search (end-exclusive) + • {opts} (table|nil) Options: + • max_start_depth (integer) if non-zero, sets the maximum + start depth for each match. This is used to prevent + traversing too deep into a tree. Requires treesitter >= + 0.20.9. Return: ~ - (number) pattern id - (table) match - (table) metadata + (fun(): integer, table<integer,TSNode>, table): pattern id, match, + metadata - *vim.treesitter.query.set_query()* -set_query({lang}, {query_name}, {text}) +set({lang}, {query_name}, {text}) *vim.treesitter.query.set()* Sets the runtime query named {query_name} for {lang} This allows users to override any runtime files and/or configuration set @@ -885,111 +1056,112 @@ set_query({lang}, {query_name}, {text}) ============================================================================== -Lua module: vim.treesitter.highlighter *lua-treesitter-highlighter* +Lua module: vim.treesitter.languagetree *lua-treesitter-languagetree* -new({tree}, {opts}) *vim.treesitter.highlighter.new()* - Creates a new highlighter using - Parameters: ~ - • {tree} LanguageTree |LanguageTree| parser object to use for highlighting - • {opts} (table|nil) Configuration of the highlighter: - • queries table overwrite queries used by the highlighter +A *LanguageTree* contains a tree of parsers: the root treesitter parser +for {lang} and any "injected" language parsers, which themselves may +inject other languages, recursively. For example a Lua buffer containing +some Vimscript commands needs multiple parsers to fully understand its +contents. - Return: ~ - TSHighlighter Created highlighter object +To create a LanguageTree (parser object) for a given buffer and language, use: >lua + local parser = vim.treesitter.get_parser(bufnr, lang) -TSHighlighter:destroy({self}) *TSHighlighter:destroy()* - Removes all internal references to the highlighter +< - Parameters: ~ - • {self} +(where `bufnr=0` means current buffer). `lang` defaults to 'filetype'. +Note: currently the parser is retained for the lifetime of a buffer but +this may change; a plugin should keep a reference to the parser object if +it wants incremental updates. +Whenever you need to access the current syntax tree, parse the buffer: >lua + local tree = parser:parse({ start_row, end_row }) -============================================================================== -Lua module: vim.treesitter.languagetree *lua-treesitter-languagetree* +< -LanguageTree:children({self}) *LanguageTree:children()* +This returns a table of immutable |treesitter-tree| objects representing +the current state of the buffer. When the plugin wants to access the state +after a (possible) edit it must call `parse()` again. If the buffer wasn't +edited, the same tree will be returned again without extra work. If the +buffer was parsed before, incremental parsing will be done of the changed +parts. + +Note: To use the parser directly inside a |nvim_buf_attach()| Lua +callback, you must call |vim.treesitter.get_parser()| before you register +your callback. But preferably parsing shouldn't be done directly in the +change callback anyway as they will be very frequent. Rather a plugin that +does any kind of analysis on a tree should use a timer to throttle too +frequent updates. + +LanguageTree:children() *LanguageTree:children()* Returns a map of language to child tree. - Parameters: ~ - • {self} - -LanguageTree:contains({self}, {range}) *LanguageTree:contains()* +LanguageTree:contains({range}) *LanguageTree:contains()* Determines whether {range} is contained in the |LanguageTree|. Parameters: ~ • {range} (table) `{ start_line, start_col, end_line, end_col }` - • {self} Return: ~ (boolean) -LanguageTree:destroy({self}) *LanguageTree:destroy()* +LanguageTree:destroy() *LanguageTree:destroy()* Destroys this |LanguageTree| and all its children. Any cleanup logic should be performed here. - Note: This DOES NOT remove this tree from a parent. Instead, `remove_child` must be called on the parent to remove it. - - Parameters: ~ - • {self} - - *LanguageTree:for_each_child()* -LanguageTree:for_each_child({self}, {fn}, {include_self}) - Invokes the callback for each |LanguageTree| and its children recursively - - Parameters: ~ - • {fn} function(tree: LanguageTree, lang: string) - • {include_self} (boolean) Whether to include the invoking tree in the - results - • {self} + Note: This DOES NOT remove this tree from a parent. Instead, + `remove_child` must be called on the parent to remove it. -LanguageTree:for_each_tree({self}, {fn}) *LanguageTree:for_each_tree()* +LanguageTree:for_each_tree({fn}) *LanguageTree:for_each_tree()* Invokes the callback for each |LanguageTree| recursively. Note: This includes the invoking tree's child trees as well. Parameters: ~ - • {fn} function(tree: TSTree, languageTree: LanguageTree) - • {self} + • {fn} fun(tree: TSTree, ltree: LanguageTree) -LanguageTree:included_regions({self}) *LanguageTree:included_regions()* - Gets the set of included regions +LanguageTree:included_regions() *LanguageTree:included_regions()* + Gets the set of included regions managed by this LanguageTree . This can be different from the regions set by injection query, because a + partial |LanguageTree:parse()| drops the regions outside the requested + range. - Parameters: ~ - • {self} + Return: ~ + table<integer, Range6[]> -LanguageTree:invalidate({self}, {reload}) *LanguageTree:invalidate()* +LanguageTree:invalidate({reload}) *LanguageTree:invalidate()* Invalidates this parser and all its children Parameters: ~ - • {self} + • {reload} (boolean|nil) -LanguageTree:is_valid({self}) *LanguageTree:is_valid()* - Determines whether this tree is valid. If the tree is invalid, call `parse()` . This will return the updated tree. +LanguageTree:is_valid({exclude_children}) *LanguageTree:is_valid()* + Returns whether this LanguageTree is valid, i.e., |LanguageTree:trees()| reflects the latest state of the + source. If invalid, user should call |LanguageTree:parse()|. Parameters: ~ - • {self} + • {exclude_children} (boolean|nil) whether to ignore the validity of + children (default `false`) -LanguageTree:lang({self}) *LanguageTree:lang()* - Gets the language of this tree node. + Return: ~ + (boolean) - Parameters: ~ - • {self} +LanguageTree:lang() *LanguageTree:lang()* + Gets the language of this tree node. *LanguageTree:language_for_range()* -LanguageTree:language_for_range({self}, {range}) +LanguageTree:language_for_range({range}) Gets the appropriate language that contains {range}. Parameters: ~ • {range} (table) `{ start_line, start_col, end_line, end_col }` - • {self} Return: ~ - LanguageTree Managing {range} + |LanguageTree| Managing {range} *LanguageTree:named_node_for_range()* -LanguageTree:named_node_for_range({self}, {range}, {opts}) +LanguageTree:named_node_for_range({range}, {opts}) Gets the smallest named node that contains {range}. Parameters: ~ @@ -997,48 +1169,58 @@ LanguageTree:named_node_for_range({self}, {range}, {opts}) • {opts} (table|nil) Optional keyword arguments: • ignore_injections boolean Ignore injected languages (default true) - • {self} Return: ~ - userdata|nil Found |tsnode| + |TSNode| | nil Found node + +LanguageTree:parse({range}) *LanguageTree:parse()* + Recursively parse all regions in the language tree using + |treesitter-parsers| for the corresponding languages and run injection + queries on the parsed trees to determine whether child trees should be + created and parsed. -LanguageTree:parse({self}) *LanguageTree:parse()* - Parses all defined regions using a treesitter parser for the language this - tree represents. This will run the injection query for this language to - determine if any child languages should be created. + Any region with empty range (`{}`, typically only the root tree) is always + parsed; otherwise (typically injections) only if it intersects {range} (or + if {range} is `true`). Parameters: ~ - • {self} + • {range} boolean|Range|nil: Parse this range in the parser's source. + Set to `true` to run a complete parse of the source (Note: + Can be slow!) Set to `false|nil` to only parse regions with + empty ranges (typically only the root tree without + injections). Return: ~ - userdata[] Table of parsed |tstree| - (table) Change list + table<integer, TSTree> -LanguageTree:register_cbs({self}, {cbs}) *LanguageTree:register_cbs()* + *LanguageTree:register_cbs()* +LanguageTree:register_cbs({cbs}, {recursive}) Registers callbacks for the |LanguageTree|. Parameters: ~ - • {cbs} (table) An |nvim_buf_attach()|-like table argument with the - following handlers: - • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback. - • `on_changedtree` : a callback that will be called every time - the tree has syntactical changes. It will only be passed one - argument, which is a table of the ranges (as node ranges) - that changed. - • `on_child_added` : emitted when a child is added to the - tree. - • `on_child_removed` : emitted when a child is removed from - the tree. - • {self} - -LanguageTree:source({self}) *LanguageTree:source()* + • {cbs} (table) An |nvim_buf_attach()|-like table argument with + the following handlers: + • `on_bytes` : see |nvim_buf_attach()|, but this will be called after the parsers callback. + • `on_changedtree` : a callback that will be called every + time the tree has syntactical changes. It will be + passed two arguments: a table of the ranges (as node + ranges) that changed and the changed tree. + • `on_child_added` : emitted when a child is added to the + tree. + • `on_child_removed` : emitted when a child is removed + from the tree. + • `on_detach` : emitted when the buffer is detached, see + |nvim_buf_detach_event|. Takes one argument, the number + of the buffer. + • {recursive} (boolean|nil) Apply callbacks recursively for all + children. Any new children will also inherit the + callbacks. + +LanguageTree:source() *LanguageTree:source()* Returns the source content of the language tree (bufnr or string). - Parameters: ~ - • {self} - *LanguageTree:tree_for_range()* -LanguageTree:tree_for_range({self}, {range}, {opts}) +LanguageTree:tree_for_range({range}, {opts}) Gets the tree that contains {range}. Parameters: ~ @@ -1046,33 +1228,17 @@ LanguageTree:tree_for_range({self}, {range}, {opts}) • {opts} (table|nil) Optional keyword arguments: • ignore_injections boolean Ignore injected languages (default true) - • {self} Return: ~ - userdata|nil Contained |tstree| + TSTree|nil -LanguageTree:trees({self}) *LanguageTree:trees()* - Returns all trees this language tree contains. Does not include child - languages. - - Parameters: ~ - • {self} - -new({source}, {lang}, {opts}) *vim.treesitter.languagetree.new()* - A |LanguageTree| holds the treesitter parser for a given language {lang} - used to parse a buffer. As the buffer may contain injected languages, the LanguageTree needs to store parsers for these child languages as well (which in turn - may contain child languages themselves, hence the name). - - Parameters: ~ - • {source} (number|string) Buffer or a string of text to parse - • {lang} (string) Root language this tree represents - • {opts} (table|nil) Optional keyword arguments: - • injections table Mapping language to injection query - strings. This is useful for overriding the built-in - runtime file searching for the injection language query - per language. +LanguageTree:trees() *LanguageTree:trees()* + Returns all trees of the regions parsed by this parser. Does not include + child languages. The result is list-like if + • this LanguageTree is the root, in which case the result is empty or a singleton list; or + • the root LanguageTree is fully parsed. Return: ~ - LanguageTree |LanguageTree| parser object + table<integer, TSTree> vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: diff --git a/runtime/doc/uganda.txt b/runtime/doc/uganda.txt index d8fc26ad17..42e275c230 100644 --- a/runtime/doc/uganda.txt +++ b/runtime/doc/uganda.txt @@ -46,8 +46,8 @@ II) It is allowed to distribute a modified (or extended) version of Vim, maintainer will do with your changes and under what license they will be distributed is negotiable. If there has been no negotiation then this license, or a later version, also applies to your changes. - The current maintainer is Bram Moolenaar <Bram@vim.org>. If this - changes it will be announced in appropriate places (most likely + The current maintainers are listed here: https://github.com/orgs/vim/people. + If this changes it will be announced in appropriate places (most likely vim.sf.net, www.vim.org and/or comp.editors). When it is completely impossible to contact the maintainer, the obligation to send him your changes ceases. Once the maintainer has confirmed that he has @@ -246,7 +246,7 @@ Credit Card: You can use PayPal to send money with a Credit card. This is Bram@iccf-holland.org Others: Transfer to this account if possible: - ING bank: IBAN: NL95 INGB 0004 5487 74 + ING bank: IBAN: NL95 INGB 0004 5487 74 Swift code: INGBNL2A under the name "stichting ICCF Holland", Amersfoort Checks are not accepted. diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt index 3110d0817c..ab99b0446f 100644 --- a/runtime/doc/ui.txt +++ b/runtime/doc/ui.txt @@ -52,12 +52,10 @@ with these (optional) keys: - `ext_termcolors` Use external default colors. - `term_name` Sets the name of the terminal 'term'. - `term_colors` Sets the number of supported colors 't_Co'. -- `term_background` Sets the default value of 'background'. -- `stdin_fd` Read buffer from `fd` as if it was a stdin pipe - This option can only used by |--embed| ui, - see |ui-startup-stdin|. - `stdin_tty` Tells if `stdin` is a `tty` or not. - `stdout_tty` Tells if `stdout` is a `tty` or not. +- `stdin_fd` Read buffer 1 from this fd as if it were stdin |--|. + Only from |--embed| UI on startup. |ui-startup-stdin| +- `stdin_tty` Tells if `stdin` is a `tty` or not. +- `stdout_tty` Tells if `stdout` is a `tty` or not. Specifying an unknown option is an error; UIs can check the |api-metadata| `ui_options` key for supported options. @@ -79,14 +77,14 @@ Example of a typical "redraw" batch in a single RPC notification: > [ ['grid_resize', [2, 77, 36]], ['grid_line', - [2, 0, 0, [[' ' , 0, 77]]], - [2, 1, 0, [['~', 7], [' ', 7, 76]]], - [2, 9, 0, [['~', 7], [' ', 7, 76]]], + [2, 0, 0, [[' ' , 0, 77]], false], + [2, 1, 0, [['~', 7], [' ', 7, 76]], false], + [2, 9, 0, [['~', 7], [' ', 7, 76]], false], ... - [2, 35, 0, [['~', 7], [' ', 7, 76]]], - [1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']]], - [1, 36, 9, [[' ', 9, 50]]], - [1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]]] + [2, 35, 0, [['~', 7], [' ', 7, 76]], false], + [1, 36, 0, [['[', 9], ['N'], ['o'], [' '], ['N'], ['a'], ['m'], ['e'], [']']], false], + [1, 36, 9, [[' ', 9, 50]], false], + [1, 36, 59, [['0', 9], [','], ['0'], ['-' ], ['1'], [' ', 9, 10], ['A'], ['l', 9, 2]], false] ], ['msg_showmode', [[]]], ['win_pos', [2, 1000, 0, 0, 77, 36]], @@ -154,11 +152,11 @@ procedure: An UI can support the native read from stdin feature as invoked with `command | nvim -` for the builtin TUI. |--| The embedding process can detect that its stdin is open to a file which -not is a terminal, just like nvim does. It then needs to forward this fd +not is a terminal, just like Nvim does. It then needs to forward this fd to Nvim. As fd=0 is already is used to send rpc data from the embedder to Nvim, it needs to use some other file descriptor, like fd=3 or higher. -Then, `stdin_fd` option should be passed to `nvim_ui_attach` and nvim will +Then, `stdin_fd` option should be passed to `nvim_ui_attach` and Nvim will implicitly read it as a buffer. This option can only be used when Nvim is launched with `--embed` option, as described above. @@ -200,7 +198,7 @@ the editor. The following keys are deprecated: `hl_id`: Use `attr_id` instead. - `hl_lm`: Use `attr_id_lm` instead. + `id_lm`: Use `attr_id_lm` instead. ["option_set", name, value] ~ UI-related option changed, where `name` is one of: @@ -212,6 +210,7 @@ the editor. - 'guifontwide' - 'linespace' - 'mousefocus' + - 'mousehide' - 'mousemoveevent' - 'pumblend' - 'showtabline' @@ -337,7 +336,7 @@ numerical highlight ids to the actual attributes. Highlights are always transmitted both for both the RGB format and as terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters - respectively. The |ui-rgb| option has no effect effect anymore. + respectively. The |ui-rgb| option has no effect anymore. Most external UIs will only need to store and use the `rgb_attr` attributes. @@ -353,15 +352,15 @@ numerical highlight ids to the actual attributes. |ui-hlstate| extension explained below. ["hl_group_set", name, hl_id] ~ - The bulitin highlight group `name` was set to use the attributes `hl_id` + The built-in highlight group `name` was set to use the attributes `hl_id` defined by a previous `hl_attr_define` call. This event is not needed to render the grids which use attribute ids directly, but is useful - for an UI who want to render its own elements with consistent - highlighting. For instance an UI using |ui-popupmenu| events, might + for a UI who want to render its own elements with consistent + highlighting. For instance a UI using |ui-popupmenu| events, might use the |hl-Pmenu| family of builtin highlights. *ui-event-grid_line* -["grid_line", grid, row, col_start, cells] ~ +["grid_line", grid, row, col_start, cells, wrap] ~ Redraw a continuous part of a `row` on a `grid`, starting at the column `col_start`. `cells` is an array of arrays each with 1 to 3 items: `[text(, hl_id, repeat)]` . `text` is the UTF-8 text that should be put in @@ -380,6 +379,12 @@ numerical highlight ids to the actual attributes. enough to cover the remaining line, will be sent when the rest of the line should be cleared. + `wrap` is a boolean indicating that this line wraps to the next row. + When redrawing a line which wraps to the next row, Nvim will emit a + `grid_line` event covering the last column of the line with `wrap` set + to true, followed immediately by a `grid_line` event starting at the + first column of the next row. + ["grid_clear", grid] ~ Clear a `grid`. @@ -429,7 +434,7 @@ numerical highlight ids to the actual attributes. +-------------------------+ < `cols` is always zero in this version of Nvim, and reserved for future - use. + use. Note when updating code from |ui-grid-old| events: ranges are end-exclusive, which is consistent with API conventions, but different @@ -532,7 +537,7 @@ is not active. New UIs should implement |ui-linegrid| instead. +-------------------------+ < ============================================================================== -Detailed highlight state Extension *ui-hlstate* +Detailed highlight state Extension *ui-hlstate* Activated by the `ext_hlstate` |ui-option|. Activates |ui-linegrid| implicitly. @@ -566,7 +571,7 @@ highlight group is cleared, so `ui_name` can always be used to reliably identify screen elements, even if no attributes have been applied. ============================================================================== -Multigrid Events *ui-multigrid* +Multigrid Events *ui-multigrid* Activated by the `ext_multigrid` |ui-option|. Activates |ui-linegrid| implicitly. @@ -627,15 +632,27 @@ tabs. When |ui-messages| is active, no message grid is used, and this event will not be sent. -["win_viewport", grid, win, topline, botline, curline, curcol] ~ +["win_viewport", grid, win, topline, botline, curline, curcol, line_count, scroll_delta] ~ Indicates the range of buffer text displayed in the window, as well as the cursor position in the buffer. All positions are zero-based. `botline` is set to one more than the line count of the buffer, if - there are filler lines past the end. + there are filler lines past the end. `scroll_delta` contains how much + the top line of a window moved since `win_viewport` was last emitted. + It is intended to be used to implement smooth scrolling. For this + purpose it only counts "virtual" or "displayed" lines, so folds + only count as one line. When scrolling more than a full screen it is + an approximate value. + + All updates, such as `grid_line`, in a batch affects the new viewport, + despite the fact that `win_viewport` is received after the updates. + Applications implementing, for example, smooth scrolling should take + this into account and keep the grid separated from what's displayed on + the screen and copy it to the viewport destination once `win_viewport` + is received. ["win_extmark", grid, win, ns_id, mark_id, row, col] ~ Updates the position of an extmark which is currently visible in a - window. Only emitted if the mark has the `ui_watched` attribute. + window. Only emitted if the mark has the `ui_watched` attribute. ============================================================================== Popupmenu Events *ui-popupmenu* @@ -707,7 +724,7 @@ For command-line 'wildmenu' UI events, activate |ui-popupmenu|. to distinguish different command lines active at the same time. The first invoked command line has level 1, the next recursively-invoked prompt has level 2. A command line invoked from the |cmdline-window| - has a higher level than than the edited command line. + has a higher level than the edited command line. ["cmdline_pos", pos, level] ~ Change the cursor position in the cmdline. @@ -809,5 +826,8 @@ events, which the UI must handle. Sent when |:messages| command is invoked. History is sent as a list of entries, where each entry is a `[kind, content]` tuple. +["msg_history_clear"] ~ + Clear the |:messages| history. + ============================================================================== vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/undo.txt b/runtime/doc/undo.txt index 98ab60c7e7..3fcc196250 100644 --- a/runtime/doc/undo.txt +++ b/runtime/doc/undo.txt @@ -114,7 +114,17 @@ use CTRL-G u. This is useful if you want an insert command to be undoable in parts. E.g., for each sentence. |i_CTRL-G_u| Setting the value of 'undolevels' also closes the undo block. Even when the -new value is equal to the old value: > +new value is equal to the old value. Use `g:undolevels` to explicitly read +and write only the global value of 'undolevels'. > + let &g:undolevels = &g:undolevels + +Note that the similar-looking assignment `let &undolevels=&undolevels` does not +preserve the global option value of 'undolevels' in the event that the local +option has been set to a different value. For example: > + " Start with different global and local values for 'undolevels'. + let &g:undolevels = 1000 + let &l:undolevels = 2000 + " This assignment changes the global option to 2000: let &undolevels = &undolevels ============================================================================== @@ -255,7 +265,7 @@ ignored if its owner differs from the owner of the edited file, except when the owner of the undo file is the current user. Set 'verbose' to get a message about that when opening a file. -Location of the undo files is controlled by the 'undodir' option, by default +Location of the undo files is controlled by the 'undodir' option, by default they are saved to the dedicated directory in the application data folder. You can also save and restore undo histories by using ":wundo" and ":rundo" @@ -351,12 +361,20 @@ undo is possible. Use this if you are running out of memory. When you set 'undolevels' to -1 the undo information is not immediately cleared, this happens at the next change. To force clearing the undo information you can use these commands: > - :let old_undolevels = &undolevels - :set undolevels=-1 + :let old_undolevels = &l:undolevels + :setlocal undolevels=-1 :exe "normal a \<BS>\<Esc>" - :let &undolevels = old_undolevels + :let &l:undolevels = old_undolevels :unlet old_undolevels +Note use of `&l:undolevels` to explicitly read the local value of 'undolevels' +and the use of `:setlocal` to change only the local option (which takes +precedence over the corresponding global option value). Saving the option value +via the use of `&undolevels` is unpredictable; it reads either the local value +(if one has been set) or the global value (otherwise). Also, if a local value +has been set, changing the option via `:set undolevels` will change both the +global and local values, requiring extra work to save and restore both values. + Marks for the buffer ('a to 'z) are also saved and restored, together with the text. diff --git a/runtime/doc/userfunc.txt b/runtime/doc/userfunc.txt index 9c428175bb..b0384df454 100644 --- a/runtime/doc/userfunc.txt +++ b/runtime/doc/userfunc.txt @@ -44,6 +44,13 @@ functions. unless "!" is given. {name} may be a |Dictionary| |Funcref| entry: > :function dict.init +< Note that {name} is not an expression, you cannot use + a variable that is a function reference. You can use + this dirty trick to list the function referred to with + variable "Funcref": > + let g:MyFuncref = Funcref + func g:MyFuncref + unlet g:MyFuncref :fu[nction] /{pattern} List functions with a name matching {pattern}. Example that lists all functions ending with "File": > @@ -72,8 +79,7 @@ See |:verbose-cmd| for more information. name has a colon in the name, e.g. for "foo:bar()". Before that patch no error was given). - {name} can also be a |Dictionary| entry that is a - |Funcref|: > + {name} may be a |Dictionary| |Funcref| entry: > :function dict.init(arg) < "dict" must be an existing dictionary. The entry "init" is added if it didn't exist yet. Otherwise [!] @@ -234,9 +240,10 @@ Example: > call Something('key', 20) "key: 20" The argument default expressions are evaluated at the time of the function -call, not definition. Thus it is possible to use an expression which is -invalid the moment the function is defined. The expressions are also only -evaluated when arguments are not specified during a call. +call, not when the function is defined. Thus it is possible to use an +expression which is invalid the moment the function is defined. The +expressions are also only evaluated when arguments are not specified during a +call. *E989* Optional arguments with default expressions must occur after any mandatory @@ -349,10 +356,69 @@ A function can also be called as part of evaluating an expression or when it is used as a method: > let x = GetList() let y = GetList()->Filter() +< +============================================================================== +3. Cleaning up in a function ~ + *:defer* +:defer {func}({args}) Call {func} when the current function is done. + {args} are evaluated here. + +Quite often a command in a function has a global effect, which must be undone +when the function finishes. Handling this in all kinds of situations can be a +hassle. Especially when an unexpected error is encountered. This can be done +with `try` / `finally` blocks, but this gets complicated when there is more +than one. + +A much simpler solution is using `defer`. It schedules a function call when +the function is returning, no matter if there is an error. Example: > + func Filter(text) abort + call writefile(a:text, 'Tempfile') + call system('filter < Tempfile > Outfile') + call Handle('Outfile') + call delete('Tempfile') + call delete('Outfile') + endfunc + +Here 'Tempfile' and 'Outfile' will not be deleted if something causes the +function to abort. `:defer` can be used to avoid that: > + func Filter(text) abort + call writefile(a:text, 'Tempfile') + defer delete('Tempfile') + defer delete('Outfile') + call system('filter < Tempfile > Outfile') + call Handle('Outfile') + endfunc + +Note that deleting "Outfile" is scheduled before calling `system()`, since it +can be created even when `system()` fails. + +The deferred functions are called in reverse order, the last one added is +executed first. A useless example: > + func Useless() abort + for s in range(3) + defer execute('echomsg "number ' .. s .. '"') + endfor + endfunc + +Now `:messages` shows: + number 2 + number 1 + number 0 + +Any return value of the deferred function is discarded. The function cannot +be followed by anything, such as "->func" or ".member". Currently `:defer +GetArg()->TheFunc()` does not work, it may work in a later version. + +Errors are reported but do not cause aborting execution of deferred functions +or altering execution outside of deferred functions. + +No range is accepted. The function can be a partial with extra arguments, but +not with a dictionary. *E1300* ============================================================================== -3. Automatically loading functions ~ + +4. Automatically loading functions ~ *autoload-functions* When using many or large functions, it's possible to automatically define them only when they are used. There are two methods: with an autocommand and with diff --git a/runtime/doc/usr_01.txt b/runtime/doc/usr_01.txt index f0e2462fae..6b94806941 100644 --- a/runtime/doc/usr_01.txt +++ b/runtime/doc/usr_01.txt @@ -81,7 +81,7 @@ from within nvim. The tutorial will lead you from that point. Have fun! ============================================================================== *01.4* Copyright *manual-copyright* -The Vim user manual and reference manual are Copyright (c) 1988-2003 by Bram +The Vim user manual and reference manual are Copyright (c) 1988 by Bram Moolenaar. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later. The latest version is presently available at: diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt index 11afe39742..1fc612de26 100644 --- a/runtime/doc/usr_02.txt +++ b/runtime/doc/usr_02.txt @@ -40,7 +40,7 @@ blank window. This is what your screen will look like: |~ | |~ | |~ | - |"file.txt" [New file] | + |"file.txt" [New] | +---------------------------------------+ ('#' is the cursor position.) < @@ -495,7 +495,7 @@ You can use the error ID at the start to find help about it: > :help E37 -Summary: *help-summary* > +Summary: *help-summary* > 1) Use Ctrl-D after typing a topic and let Vim show all available topics. Or press Tab to complete: > diff --git a/runtime/doc/usr_03.txt b/runtime/doc/usr_03.txt index 2b0d40ba32..b76ca18d20 100644 --- a/runtime/doc/usr_03.txt +++ b/runtime/doc/usr_03.txt @@ -173,6 +173,8 @@ one. Thus if the cursor is at the start of the line of the previous example, ---+----------------> % +Other ways to move around code can be found in |usr_29.txt|. + ============================================================================== *03.5* Moving to a specific line diff --git a/runtime/doc/usr_05.txt b/runtime/doc/usr_05.txt index 24d6185eae..076a50c582 100644 --- a/runtime/doc/usr_05.txt +++ b/runtime/doc/usr_05.txt @@ -10,7 +10,7 @@ make Vim start with options set to different values. Add plugins to extend Vim's capabilities. Or define your own macros. |05.1| The vimrc file -|05.2| The example vimrc file explained +|05.2| Example vimrc contents |05.3| Simple mappings |05.4| Adding a package |05.5| Adding a plugin @@ -27,10 +27,10 @@ Table of contents: |usr_toc.txt| You probably got tired of typing commands that you use very often. To start Vim with all your favorite option settings and mappings, you write them in -what is called the init.vim file. Vim executes the commands in this file when +what is called the init.vim file. Vim executes the commands in this file when it starts up. -If you already have a init.vim file (e.g., when your sysadmin has one setup +If you already have a init.vim file (e.g., when your sysadmin has one setup for you), you can edit it this way: > :edit $MYVIMRC @@ -56,80 +56,32 @@ This chapter only explains the most basic items. For more information on how to write a Vim script file: |usr_41.txt|. ============================================================================== -*05.2* The example vimrc file explained *vimrc_example.vim* +*05.2* Example vimrc contents *vimrc_example.vim* In the first chapter was explained how to create a vimrc file. > :exe 'edit' stdpath('config').'/init.vim' -In this section we will explain the various commands used in this file. This -will give you hints about how to set up your own preferences. Not everything -will be explained though. Use the ":help" command to find out more. - -> - set backspace=indent,eol,start - -This specifies where in Insert mode the <BS> is allowed to delete the -character in front of the cursor. The three items, separated by commas, tell -Vim to delete the white space at the start of the line, a line break and the -character before where Insert mode started. -> - - set autoindent - -This makes Vim use the indent of the previous line for a newly created line. -Thus there is the same amount of white space before the new line. For example -when pressing <Enter> in Insert mode, and when using the "o" command to open a -new line. +In this section we will explain the various commands that can be specified in +this file. This will give you hints about how to set up your own preferences. +Not everything will be explained though. Use the ":help" command to find out +more. > - set backup This tells Vim to keep a backup copy of a file when overwriting it. The backup file will have the same name as the original file with "~" added. See |07.4| > - set history=50 - +< Keep 50 commands and 50 search patterns in the history. Use another number if you want to remember fewer or more lines. > - - set ruler - -Always display the current cursor position in the lower right corner of the -Vim window. - -> - set showcmd - -Display an incomplete command in the lower right corner of the Vim window, -left of the ruler. For example, when you type "2f", Vim is waiting for you to -type the character to find and "2f" is displayed. When you press "w" next, -the "2fw" command is executed and the displayed "2f" is removed. -> - +-------------------------------------------------+ - |text in the Vim window | - |~ | - |~ | - |-- VISUAL -- 2f 43,8 17% | - +-------------------------------------------------+ - ^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^ - 'showmode' 'showcmd' 'ruler' - -> - set incsearch -< -Display matches for a search pattern while you type. - -> map Q gq This defines a key mapping. More about that in the next section. This -defines the "Q" command to do formatting with the "gq" operator. This is how -it worked before Vim 5.0. Otherwise the "Q" command repeats the last recorded -register. - +defines the "Q" command to do formatting with the "gq" operator. Otherwise the +"Q" command repeats the last recorded register. > vnoremap _g y:exe "grep /" .. escape(@", '\\/') .. "/ *.c *.h"<CR> @@ -138,14 +90,8 @@ This is a complicated mapping. You can see that mappings can be used to do quite complicated things. Still, it is just a sequence of commands that are executed like you typed them. + *vimrc-filetype* > - set hlsearch - -This option tells Vim to highlight matches with the last used search pattern. -The "if" command is very useful to set options only when some condition is -met. More about that in |usr_41.txt|. - - *vimrc-filetype* > filetype plugin indent on This switches on three very clever mechanisms: @@ -172,15 +118,27 @@ This switches on three very clever mechanisms: *restore-cursor* *last-position-jump* > - autocmd BufRead * autocmd FileType <buffer> ++once - \ if &ft !~# 'commit\|rebase' && line("'\"") > 1 && line("'\"") <= line("$") | exe 'normal! g`"' | endif + augroup RestoreCursor + autocmd! + autocmd BufRead * autocmd FileType <buffer> ++once + \ let s:line = line("'\"") + \ | if s:line >= 1 && s:line <= line("$") && &filetype !~# 'commit' + \ && index(['xxd', 'gitrebase'], &filetype) == -1 + \ | execute "normal! g`\"" + \ | endif + augroup END Another autocommand. This time it is used after reading any file. The complicated stuff after it checks if the '" mark is defined, and jumps to it -if so. The backslash at the start of a line is used to continue the command -from the previous line. That avoids a line getting very long. -See |line-continuation|. This only works in a Vim script file, not when -typing commands at the command-line. +if so. It doesn't do that for a commit or rebase message, which are likely +a different one than last time, and when using xxd(1) to filter and edit +binary files, which transforms input files back and forth, causing them to +have dual nature, so to speak. See also |using-xxd|. + +The backslash at the start of a line is used to continue the command from the +previous line. That avoids a line getting very long. See |line-continuation|. +This only works in a Vim script file, not when typing commands at the +command line. > command DiffOrig vert new | set bt=nofile | r ++edit # | 0d_ | diffthis @@ -244,26 +202,21 @@ The ":map" command (with no arguments) lists your current mappings. At least the ones for Normal mode. More about mappings in section |40.1|. ============================================================================== -*05.4* Adding a package *add-package* *vimball-install* - -A package is a set of files that you can add to Vim. There are two kinds of -packages: optional and automatically loaded on startup. +*05.4* Adding a package *add-package* -The Vim distribution comes with a few packages that you can optionally use. -For example, the vimball plugin. This plugin supports creating and using -vimballs (self-installing Vim plugin archives). +You may use |:packadd| to enable packages on demand. This is useful for plugins +you want to enable only sometimes. To enable `example_package`, use the +following command: > + packadd example_package -To start using the vimball plugin, add one line to your vimrc file: > - packadd vimball - -That's all! You can also type the command to try it out. Now you can find -help about this plugin: > - :help vimball +That's all! Now you can find help about this plugin: > + :help example_package This works, because when `:packadd` loaded the plugin it also added the -package directory in 'runtimepath', so that the help file can be found. The -tags for vimball's help are already created. If you need to generate the help -tags for a package, see the `:helptags` command. +package directory in 'runtimepath', so that the help file can be found. + +A package is a set of files that you can add to Vim. There are two kinds of +packages: optional and automatically loaded on startup. You can find packages on the Internet in various places. It usually comes as an archive or as a repository. For an archive you can follow these steps: @@ -273,7 +226,7 @@ an archive or as a repository. For an archive you can follow these steps: package. 2. unpack the archive in that directory. This assumes the top directory in the archive is "start": > - cd ~/.local/share/nvim/site/pack/fancy + cd ~/.local/share/nvim/site/pack/fancy unzip /tmp/fancy.zip < If the archive layout is different make sure that you end up with a path like this: @@ -342,7 +295,7 @@ That's all! Now you can use the commands defined in this plugin. Instead of putting plugins directly into the plugin/ directory, you may better organize them by putting them into subdirectories under plugin/. -As an example, consider using "~/.local/share/nvim/site/plugin/perl/*.vim" for +As an example, consider using "~/.local/share/nvim/site/plugin/perl/*.vim" for all your Perl plugins. diff --git a/runtime/doc/usr_09.txt b/runtime/doc/usr_09.txt index 8084d13b5d..da9a404420 100644 --- a/runtime/doc/usr_09.txt +++ b/runtime/doc/usr_09.txt @@ -63,10 +63,10 @@ Vim will set the title to show the name of the current file. First comes the name of the file. Then some special characters and the directory of the file in parens. These special characters can be present: - - The file cannot be modified (e.g., a help file) - + The file contains changes - = The file is read-only - =+ The file is read-only, contains changes anyway + • - The file cannot be modified (e.g., a help file) + • + The file contains changes + • = The file is read-only + • =+ The file is read-only, contains changes anyway If nothing is shown you have an ordinary, unchanged file. @@ -124,41 +124,13 @@ This adds the 'l' flag to 'guioptions'. Standards are wonderful. In Microsoft Windows, you can use the mouse to select text in a standard manner. The X Window system also has a standard system for using the mouse. Unfortunately, these two standards are not the -same. - Fortunately, you can customize Vim. You can make the behavior of the mouse -work like an X Window system mouse or a Microsoft Windows mouse. The following -command makes the mouse behave like an X Window mouse: > +same. Fortunately, you can customize Vim. - :behave xterm - -The following command makes the mouse work like a Microsoft Windows mouse: > - - :behave mswin - -The default behavior of the mouse on Unix systems is xterm. The default -behavior on Windows systems is selected during the installation process. For -details about what the two behaviors are, see |:behave|. Here follows a -summary. - - -XTERM MOUSE BEHAVIOR - -Left mouse click position the cursor -Left mouse drag select text in Visual mode -Middle mouse click paste text from the clipboard -Right mouse click extend the selected text until the mouse - pointer - - -MSWIN MOUSE BEHAVIOR - -Left mouse click position the cursor -Left mouse drag select text in Select mode (see |09.4|) -Left mouse click, with Shift extend the selected text until the mouse - pointer -Middle mouse click paste text from the clipboard -Right mouse click display a pop-up menu +The following commands makes the mouse work more like a Microsoft Windows mouse: > + set selection=exclusive + set selectmode=mouse,key + set keymodel=startsel,stopsel The mouse can be further tuned. Check out these options if you want to change the way how the mouse works: @@ -251,7 +223,7 @@ Remember, "y" is yank, which is Vim's copy command. "+P It's the same as for the current selection, but uses the plus (+) register -instead of the star (*) register. +instead of the star "*" register. ============================================================================== *09.4* Select mode diff --git a/runtime/doc/usr_11.txt b/runtime/doc/usr_11.txt index 361fe51caa..1fa7fb6f77 100644 --- a/runtime/doc/usr_11.txt +++ b/runtime/doc/usr_11.txt @@ -82,9 +82,8 @@ You must be in the right directory, otherwise Vim can't find the swap file. ============================================================================== *11.2* Where is the swap file? -Vim can store the swap file in several places. Normally it is in the same -directory as the original file. To find it, change to the directory of the -file, and use: > +Vim can store the swap file in several places. To find it, change to the +directory of the file, and use: > vim -r diff --git a/runtime/doc/usr_12.txt b/runtime/doc/usr_12.txt index 51a25b1593..dd1d62bb52 100644 --- a/runtime/doc/usr_12.txt +++ b/runtime/doc/usr_12.txt @@ -59,7 +59,7 @@ playback. Let's assume you have a directory with C++ files, all ending in ".cpp". There is a function called "GetResp" that you want to rename to "GetAnswer". - vim *.cpp Start Vim, defining the argument list to + vim `*.cpp` Start Vim, defining the argument list to contain all the C++ files. You are now in the first file. qq Start recording into the q register @@ -331,7 +331,7 @@ program files, for example, enter the following command: > :grep error_string *.c This causes Vim to search for the string "error_string" in all the specified -files (*.c). The editor will now open the first file where a match is found +files (`*.c`). The editor will now open the first file where a match is found and position the cursor on the first matching line. To go to the next matching line (no matter in what file it is), use the ":cnext" command. To go to the previous match, use the ":cprev" command. Use ":clist" to see all the diff --git a/runtime/doc/usr_21.txt b/runtime/doc/usr_21.txt index 191d333f3d..4ae72bbe84 100644 --- a/runtime/doc/usr_21.txt +++ b/runtime/doc/usr_21.txt @@ -82,7 +82,7 @@ After editing for a while you will have text in registers, marks in various files, a command line history filled with carefully crafted commands. When you exit Vim all of this is lost. But you can get it back! -The ShaDa (abbreviation of SHAred DAta) file is designed to store status +The ShaDa (abbreviation of SHAred DAta) file is designed to store status information: Command-line and Search pattern history @@ -218,8 +218,8 @@ Obviously, the "w" stands for "write" and the "r" for "read". The ! character is used by ":wshada" to forcefully overwrite an existing file. When it is omitted, and the file exists, the information is merged into the file. - The ! character used for ":rshada" means that all the information in ShaDa -file has priority over existing information, this may overwrite it. Without + The ! character used for ":rshada" means that all the information in ShaDa +file has priority over existing information, this may overwrite it. Without the ! only information that wasn't set is used. These commands can also be used to store info and use it again later. You could make a directory full of ShaDa files, each containing info for a @@ -277,8 +277,8 @@ example, use: > SESSION HERE, SESSION THERE The obvious way to use sessions is when working on different projects. -Suppose you store your session files in the directory "~/.config/nvim". You -are currently working on the "secret" project and have to switch to the +Suppose you store your session files in the directory "~/.config/nvim". You +are currently working on the "secret" project and have to switch to the "boring" project: > :wall @@ -426,7 +426,7 @@ a line of text that tells Vim the values of options, to be used in this file only. A typical example is a C program where you make indents by a multiple of 4 spaces. This requires setting the 'shiftwidth' option to 4. This modeline -will do that: +will do that: > /* vim:set shiftwidth=4: */ ~ diff --git a/runtime/doc/usr_22.txt b/runtime/doc/usr_22.txt index 539bda3980..ae569dc6a0 100644 --- a/runtime/doc/usr_22.txt +++ b/runtime/doc/usr_22.txt @@ -50,8 +50,8 @@ You can see these items: 1. The name of the browsing tool and its version number 2. The name of the browsing directory 3. The method of sorting (may be by name, time, or size) -4. How names are to be sorted (directories first, then *.h files, - *.c files, etc) +4. How names are to be sorted (directories first, then `*.h` files, + `*.c` files, etc) 5. How to get help (use the <F1> key), and an abbreviated listing of available commands 6. A listing of files, including "../", which allows one to list @@ -77,25 +77,25 @@ browser. This is what you get: > 9. Directory Browsing netrw-browse netrw-dir netrw-list netrw-help MAPS netrw-maps - <F1>.............Help.......................................|netrw-help| - <cr>.............Browsing...................................|netrw-cr| - <del>............Deleting Files or Directories..............|netrw-delete| - -................Going Up...................................|netrw--| - a................Hiding Files or Directories................|netrw-a| - mb...............Bookmarking a Directory....................|netrw-mb| - gb...............Changing to a Bookmarked Directory.........|netrw-gb| - cd...............Make Browsing Directory The Current Dir....|netrw-c| - d................Make A New Directory.......................|netrw-d| - D................Deleting Files or Directories..............|netrw-D| - <c-h>............Edit File/Directory Hiding List............|netrw-ctrl-h| - i................Change Listing Style.......................|netrw-i| - <c-l>............Refreshing the Listing.....................|netrw-ctrl-l| - o................Browsing with a Horizontal Split...........|netrw-o| - p................Use Preview Window.........................|netrw-p| - P................Edit in Previous Window....................|netrw-p| - q................Listing Bookmarks and History..............|netrw-qb| - r................Reversing Sorting Order....................|netrw-r| -< (etc) + <F1>.............Help.......................................|netrw-help| + <cr>.............Browsing...................................|netrw-cr| + <del>............Deleting Files or Directories..............|netrw-delete| + -................Going Up...................................|netrw--| + a................Hiding Files or Directories................|netrw-a| + mb...............Bookmarking a Directory....................|netrw-mb| + gb...............Changing to a Bookmarked Directory.........|netrw-gb| + cd...............Make Browsing Directory The Current Dir....|netrw-c| + d................Make A New Directory.......................|netrw-d| + D................Deleting Files or Directories..............|netrw-D| + <c-h>............Edit File/Directory Hiding List............|netrw-ctrl-h| + i................Change Listing Style.......................|netrw-i| + <c-l>............Refreshing the Listing.....................|netrw-ctrl-l| + o................Browsing with a Horizontal Split...........|netrw-o| + p................Use Preview Window.........................|netrw-p| + P................Edit in Previous Window....................|netrw-p| + q................Listing Bookmarks and History..............|netrw-qb| + r................Reversing Sorting Order....................|netrw-r| +< (etc) The <F1> key thus brings you to a netrw directory browsing contents help page. It's a regular help page; use the usual |CTRL-]| to jump to tagged help items @@ -106,7 +106,7 @@ To select files for display and editing: (with the cursor is atop a filename) <enter> Open the file in the current window. |netrw-cr| o Horizontally split window and display file |netrw-o| v Vertically split window and display file |netrw-v| - p Use the |preview-window| |netrw-p| + p Use the |preview-window| |netrw-p| P Edit in the previous window |netrw-P| t Open file in a new tab |netrw-t| diff --git a/runtime/doc/usr_24.txt b/runtime/doc/usr_24.txt index efda2bc33d..db6c8e45d0 100644 --- a/runtime/doc/usr_24.txt +++ b/runtime/doc/usr_24.txt @@ -241,11 +241,11 @@ some other editors it's called intellisense, but that is a trademark. The key to Omni completion is CTRL-X CTRL-O. Obviously the O stands for Omni here, so that you can remember it easier. Let's use an example for editing C -source: +source: > - { ~ - struct foo *p; ~ - p-> ~ + { + struct foo *p; + p-> The cursor is after "p->". Now type CTRL-X CTRL-O. Vim will offer you a list of alternatives, which are the items that "struct foo" contains. That is @@ -270,13 +270,13 @@ work. If you press CTRL-A, the editor inserts the text you typed the last time you were in Insert mode. - Assume, for example, that you have a file that begins with the following: + Assume, for example, that you have a file that begins with the following: > "file.h" ~ /* Main program begins */ ~ You edit this file by inserting "#include " at the beginning of the first -line: +line: > #include "file.h" ~ /* Main program begins */ ~ @@ -286,13 +286,13 @@ now start to insert a new "#include" line. So you type: > i CTRL-A -The result is as follows: +The result is as follows: > #include "file.h" ~ #include /* Main program begins */ ~ The "#include " was inserted because CTRL-A inserts the text of the previous -insert. Now you type "main.h"<Enter> to finish the line: +insert. Now you type "main.h"<Enter> to finish the line: > #include "file.h" ~ @@ -429,7 +429,7 @@ mistake. LISTING ABBREVIATIONS -The ":abbreviate" command lists the abbreviations: +The ":abbreviate" command lists the abbreviations: > :abbreviate i #e ****************************************/ diff --git a/runtime/doc/usr_28.txt b/runtime/doc/usr_28.txt index 86aa20597e..96f635a307 100644 --- a/runtime/doc/usr_28.txt +++ b/runtime/doc/usr_28.txt @@ -277,7 +277,7 @@ Try it: > :set foldmethod=marker -Example text, as it could appear in a C program: +Example text, as it could appear in a C program: > /* foobar () {{{ */ int foobar() @@ -292,7 +292,7 @@ Notice that the folded line will display the text before the marker. This is very useful to tell what the fold contains. It's quite annoying when the markers don't pair up correctly after moving some -lines around. This can be avoided by using numbered markers. Example: +lines around. This can be avoided by using numbered markers. Example: > /* global variables {{{1 */ int varA, varB; diff --git a/runtime/doc/usr_29.txt b/runtime/doc/usr_29.txt index 751cb9a902..dd8598a3a0 100644 --- a/runtime/doc/usr_29.txt +++ b/runtime/doc/usr_29.txt @@ -307,9 +307,9 @@ tags file. Example: > :psearch popen This will show the "stdio.h" file in the preview window, with the function -prototype for popen(): +prototype for popen(): >c - FILE *popen __P((const char *, const char *)); ~ + FILE *popen __P((const char *, const char *)); You can specify the height of the preview window, when it is opened, with the 'previewheight' option. @@ -319,13 +319,13 @@ You can specify the height of the preview window, when it is opened, with the Since a program is structured, Vim can recognize items in it. Specific commands can be used to move around. - C programs often contain constructs like this: + C programs often contain constructs like this: >c - #ifdef USE_POPEN ~ - fd = popen("ls", "r") ~ - #else ~ - fd = fopen("tmp", "w") ~ - #endif ~ + #ifdef USE_POPEN + fd = popen("ls", "r") + #else + fd = fopen("tmp", "w") + #endif But then much longer, and possibly nested. Position the cursor on the "#ifdef" and press %. Vim will jump to the "#else". Pressing % again takes @@ -361,7 +361,7 @@ MOVING IN CODE BLOCKS In C code blocks are enclosed in {}. These can get pretty long. To move to the start of the outer block use the "[[" command. Use "][" to find the end. This assumes that the "{" and "}" are in the first column. - The "[{" command moves to the start of the current block. It skips over + The [{ command moves to the start of the current block. It skips over pairs of {} at the same level. "]}" jumps to the end. An overview: @@ -410,7 +410,7 @@ That also works when they are many lines apart. MOVING IN BRACES -The "[(" and "])" commands work similar to "[{" and "]}", except that they +The [( and ]) commands work similar to [{ and ]}, except that they work on () pairs instead of {} pairs. > [( @@ -424,7 +424,7 @@ work on () pairs instead of {} pairs. MOVING IN COMMENTS To move back to the start of a comment use "[/". Move forward to the end of a -comment with "]/". This only works for /* - */ comments. +comment with "]/". This only works for `/* - */` comments. > +-> +-> /* | [/ | * A comment about --+ @@ -446,10 +446,10 @@ You are editing a C program and wonder if a variable is declared as "int" or Vim will list the matching lines it can find. Not only in the current file, but also in all included files (and files included in them, etc.). The result -looks like this: +looks like this: > - structs.h ~ - 1: 29 unsigned column; /* column number */ ~ + structs.h + 1: 29 unsigned column; /* column number */ The advantage over using tags or the preview window is that included files are searched. In most cases this results in the right declaration to be found. diff --git a/runtime/doc/usr_30.txt b/runtime/doc/usr_30.txt index 7e7b3b21f4..a0d22482c3 100644 --- a/runtime/doc/usr_30.txt +++ b/runtime/doc/usr_30.txt @@ -517,12 +517,12 @@ The other way around works just as well: > One of the great things about Vim is that it understands comments. You can ask Vim to format a comment and it will do the right thing. - Suppose, for example, that you have the following comment: + Suppose, for example, that you have the following comment: >c - /* ~ - * This is a test ~ - * of the text formatting. ~ - */ ~ + /* + * This is a test + * of the text formatting. + */ You then ask Vim to format it by positioning the cursor at the start of the comment and type: > @@ -530,33 +530,33 @@ comment and type: > gq]/ "gq" is the operator to format text. "]/" is the motion that takes you to the -end of a comment. The result is: +end of a comment. The result is: >c - /* ~ - * This is a test of the text formatting. ~ - */ ~ + /* + * This is a test of the text formatting. + */ Notice that Vim properly handled the beginning of each line. An alternative is to select the text that is to be formatted in Visual mode and type "gq". To add a new line to the comment, position the cursor on the middle line and -press "o". The result looks like this: +press "o". The result looks like this: >c - /* ~ - * This is a test of the text formatting. ~ - * ~ - */ ~ + /* + * This is a test of the text formatting. + * + */ Vim has automatically inserted a star and a space for you. Now you can type the comment text. When it gets longer than 'textwidth', Vim will break the -line. Again, the star is inserted automatically: +line. Again, the star is inserted automatically: >c - /* ~ - * This is a test of the text formatting. ~ - * Typing a lot of text here will make Vim ~ - * break ~ - */ ~ + /* + * This is a test of the text formatting. + * Typing a lot of text here will make Vim + * break + */ For this to work some flags must be present in 'formatoptions': diff --git a/runtime/doc/usr_40.txt b/runtime/doc/usr_40.txt index 8befb15528..b0d53e0d8c 100644 --- a/runtime/doc/usr_40.txt +++ b/runtime/doc/usr_40.txt @@ -159,7 +159,7 @@ RECURSIVE MAPPING When a mapping triggers itself, it will run forever. This can be used to repeat an action an unlimited number of times. For example, you have a list of files that contain a version number in the -first line. You edit these files with "vim *.txt". You are now editing the +first line. You edit these files with `vim *.txt`. You are now editing the first file. Define this mapping: > :map ,, :s/5.1/5.2/<CR>:wnext<CR>,, @@ -501,7 +501,7 @@ See |autocmd-events| for a complete list of events. PATTERNS The {file-pattern} argument can actually be a comma-separated list of file -patterns. For example: "*.c,*.h" matches files ending in ".c" and ".h". +patterns. For example: `*.c,*.h` matches files ending in ".c" and ".h". The usual file wildcards can be used. Here is a summary of the most often used ones: @@ -622,7 +622,7 @@ Example: > :autocmd BufReadPost *.log normal G -This will make the cursor jump to the last line of *.log files when you start +This will make the cursor jump to the last line of `*.log` files when you start to edit it. Using the ":normal" command is a bit tricky. First of all, make sure its argument is a complete command, including all the arguments. When you use "i" diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 910aebae70..e206a804f4 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -588,7 +588,7 @@ after the substitute() call. FUNCTIONS *function-list* There are many functions. We will mention them here, grouped by what they are -used for. You can find an alphabetical list here: |builtin-function-list|. +used for. You can find an alphabetical list here: |builtin-function-details|. Use CTRL-] on the function name to jump to detailed help on it. String manipulation: *string-functions* @@ -621,14 +621,18 @@ String manipulation: *string-functions* strlen() length of a string in bytes strcharlen() length of a string in characters strchars() number of characters in a string + strutf16len() number of UTF-16 code units in a string strwidth() size of string when displayed strdisplaywidth() size of string when displayed, deals with tabs setcellwidths() set character cell width overrides getcellwidths() get character cell width overrides + reverse() reverse the order of characters in a string substitute() substitute a pattern match with a string submatch() get a specific match in ":s" and substitute() strpart() get part of a string using byte index strcharpart() get part of a string using char index + slice() take a slice of a string, using char index in + Vim9 script strgetchar() get character from a string using char index expand() expand special keywords expandcmd() expand a command like done for `:edit` @@ -636,6 +640,7 @@ String manipulation: *string-functions* byteidx() byte index of a character in a string byteidxcomp() like byteidx() but count composing characters charidx() character index of a byte in a string + utf16idx() UTF-16 index of a byte in a string repeat() repeat a string multiple times eval() evaluate a string expression execute() execute an Ex command and get the output @@ -650,26 +655,32 @@ List manipulation: *list-functions* insert() insert an item somewhere in a List add() append an item to a List extend() append a List to a List + extendnew() make a new List and append items remove() remove one or more items from a List copy() make a shallow copy of a List deepcopy() make a full copy of a List filter() remove selected items from a List map() change each List item + mapnew() make a new List with changed items reduce() reduce a List to a value + slice() take a slice of a List sort() sort a List - reverse() reverse the order of a List + reverse() reverse the order of items in a List uniq() remove copies of repeated adjacent items split() split a String into a List join() join List items into a String range() return a List with a sequence of numbers string() String representation of a List call() call a function with List as arguments - index() index of a value in a List + index() index of a value in a List or Blob + indexof() index in a List or Blob where an expression + evaluates to true max() maximum value in a List min() minimum value in a List count() count number of times a value appears in a List repeat() repeat a List multiple times flatten() flatten a List + flattennew() flatten a copy of a List Dictionary manipulation: *dict-functions* get() get an entry without an error for a wrong key @@ -678,8 +689,10 @@ Dictionary manipulation: *dict-functions* empty() check if Dictionary is empty remove() remove an entry from a Dictionary extend() add entries from one Dictionary to another + extendnew() make a new Dictionary and append items filter() remove selected entries from a Dictionary map() change each Dictionary entry + mapnew() make a new Dictionary with changed items keys() get List of Dictionary keys values() get List of Dictionary values items() get List of Dictionary key-value pairs @@ -716,6 +729,11 @@ Floating point computation: *float-functions* isinf() check for infinity isnan() check for not a number +Blob manipulation: *blob-functions* + blob2list() get a list of numbers from a blob + list2blob() get a blob from a list of numbers + reverse() reverse the order of numbers in a blob + Other computation: *bitwise-function* and() bitwise AND invert() bitwise invert @@ -874,6 +892,7 @@ Buffers, windows and the argument list: getwininfo() get a list with window information getchangelist() get a list of change list entries getjumplist() get a list of jump list entries + swapfilelist() list of existing swap files in 'directory' swapinfo() information about a swap file swapname() get the swap file path of a buffer @@ -996,6 +1015,7 @@ Mappings and Menus: *mapping-functions* hasmapto() check if a mapping exists mapcheck() check if a matching mapping exists maparg() get rhs of a mapping + maplist() get list of all mappings mapset() restore a mapping menu_info() get information about a menu item wildmenumode() check if the wildmode is active @@ -1047,6 +1067,14 @@ Prompt Buffer: *promptbuffer-functions* prompt_setinterrupt() set interrupt callback for a buffer prompt_setprompt() set the prompt text for a buffer +Registers: *register-functions* + 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 + reg_recording() return the name of the register being recorded + Context Stack: *ctx-functions* ctxget() return context at given index from top ctxpop() pop and restore top context @@ -1063,19 +1091,13 @@ Various: *various-functions* did_filetype() check if a FileType autocommand was used eventhandler() check if invoked by an event handler getpid() get process ID of Vim + getscriptinfo() get list of sourced vim scripts libcall() call a function in an external library libcallnr() idem, returning a number undofile() get the name of the undo file - 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 - reg_recording() return the name of the register being recorded + undotree() return the state of the undo tree for a buffer shiftwidth() effective value of 'shiftwidth' @@ -1316,6 +1338,8 @@ is a List with arguments. Function references are most useful in combination with a Dictionary, as is explained in the next section. +More information about defining your own functions here: |user-function|. + ============================================================================== *41.8* Lists and Dictionaries @@ -1763,7 +1787,7 @@ PITFALLS Even bigger problem arises in the following example: > :map ,ab o#include - :unmap ,ab + :unmap ,ab Here the unmap command will not work, because it tries to unmap ",ab ". This does not exist as a mapped sequence. An error will be issued, which is very @@ -2225,7 +2249,7 @@ Example: > Write this single-line file as "ftdetect/foofoo.vim" in the first directory that appears in 'runtimepath'. For Unix that would be -"~/.config/nvim/ftdetect/foofoo.vim". The convention is to use the name of +"~/.config/nvim/ftdetect/foofoo.vim". The convention is to use the name of the filetype for the script name. You can make more complicated checks if you like, for example to inspect the @@ -2296,7 +2320,7 @@ you can write the different setting in a script: > Now write this in the "after" directory, so that it gets sourced after the distributed "vim.vim" ftplugin |after-directory|. For Unix this would be -"~/.config/nvim/after/ftplugin/vim.vim". Note that the default plugin will +"~/.config/nvim/after/ftplugin/vim.vim". Note that the default plugin will have set "b:did_ftplugin", but it is ignored here. @@ -2466,7 +2490,7 @@ a user to overrule or add to the default file. The default files start with: > :let current_compiler = "mine" When you write a compiler file and put it in your personal runtime directory -(e.g., ~/.config/nvim/compiler for Unix), you set the "current_compiler" +(e.g., ~/.config/nvim/compiler for Unix), you set the "current_compiler" variable to make the default file skip the settings. *:CompilerSet* The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for diff --git a/runtime/doc/usr_43.txt b/runtime/doc/usr_43.txt index 15c94cd15e..0de972b8cc 100644 --- a/runtime/doc/usr_43.txt +++ b/runtime/doc/usr_43.txt @@ -27,7 +27,7 @@ want to set the 'softtabstop' option to 4 and define a mapping to insert a three-line comment. You do this with only two steps: *your-runtime-dir* -1. Create your own runtime directory. On Unix this usually is +1. Create your own runtime directory. On Unix this usually is "~/.config/nvim". In this directory create the "ftplugin" directory: > mkdir -p ~/.config/nvim/ftplugin @@ -123,12 +123,12 @@ That file is found in 'runtimepath' first. Then use this in What will happen now is that Vim searches for "filetype.vim" files in each directory in 'runtimepath'. First ~/.config/nvim/filetype.vim is found. The -autocommand to catch *.txt files is defined there. Then Vim finds the +autocommand to catch `*.txt` files is defined there. Then Vim finds the filetype.vim file in $VIMRUNTIME, which is halfway 'runtimepath'. Finally -~/.config/nvim/after/filetype.vim is found and the autocommand for detecting +~/.config/nvim/after/filetype.vim is found and the autocommand for detecting ruby files in /usr/share/scripts is added. When you now edit /usr/share/scripts/README.txt, the autocommands are -checked in the order in which they were defined. The *.txt pattern matches, +checked in the order in which they were defined. The `*.txt` pattern matches, thus "setf text" is executed to set the filetype to "text". The pattern for ruby matches too, and the "setf ruby" is executed. But since 'filetype' was already set to "text", nothing happens here. diff --git a/runtime/doc/usr_45.txt b/runtime/doc/usr_45.txt index 95a2bc8f79..85710b15d5 100644 --- a/runtime/doc/usr_45.txt +++ b/runtime/doc/usr_45.txt @@ -190,8 +190,7 @@ font. Example: > xterm -u8 -fn -misc-fixed-medium-r-normal--18-120-100-100-c-90-iso10646-1 -Now you can run Vim inside this terminal. Set 'encoding' to "utf-8" as -before. That's all. +Now you can run Vim inside this terminal. USING UNICODE IN AN ORDINARY TERMINAL diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt index e13d892fd6..33f57580c7 100644 --- a/runtime/doc/various.txt +++ b/runtime/doc/various.txt @@ -32,7 +32,8 @@ CTRL-L Clears and redraws the screen. The redraw may happen *:redraws* *:redrawstatus* :redraws[tatus][!] Redraws the status line and window bar of the current window, or all status lines and window bars if "!" is - included. Useful if 'statusline' or 'winbar' includes + included. Redraws the commandline instead if it contains + the 'ruler'. Useful if 'statusline' or 'winbar' includes an item that doesn't cause automatic updating. *:redrawt* *:redrawtabline* @@ -87,18 +88,24 @@ g8 Print the hex values of the bytes used in the *8g8* 8g8 Find an illegal UTF-8 byte sequence at or after the - cursor. This works in two situations: - 1. when 'encoding' is any 8-bit encoding - 2. when 'encoding' is "utf-8" and 'fileencoding' is - any 8-bit encoding - Thus it can be used when editing a file that was - supposed to be UTF-8 but was read as if it is an 8-bit - encoding because it contains illegal bytes. + cursor. + Can be used when editing a file that was supposed to + be UTF-8 but was read as if it is an 8-bit encoding + because it contains illegal bytes. Does not wrap around the end of the file. Note that when the cursor is on an illegal byte or the cursor is halfway through a multibyte character the command won't move the cursor. + *gx* +gx Opens the current filepath or URL (decided by + |<cfile>|, 'isfname') at cursor using the system + default handler, by calling |vim.ui.open()|. + + *v_gx* +{Visual}gx Opens the selected text using the system default + handler, by calling |vim.ui.open()|. + *:p* *:pr* *:print* *E749* :[range]p[rint] [flags] Print [range] lines (default current line). @@ -173,13 +180,12 @@ g8 Print the hex values of the bytes used in the Like ":z" or ":z!", but number the lines. *:=* -:= [flags] Print the last line number. - See |ex-flags| for [flags]. +:= [args] Without [args]: prints the last line number. + With [args]: equivalent to `:lua ={expr}`. see |:lua| -:{range}= [flags] Prints the last line number in {range}. For example, +:{range}= Prints the last line number in {range}. For example, this prints the current line number: > :.= -< See |ex-flags| for [flags]. :norm[al][!] {commands} *:norm* *:normal* Execute Normal mode commands {commands}. This makes @@ -243,6 +249,10 @@ g8 Print the hex values of the bytes used in the Fails if changes have been made to the current buffer, unless 'hidden' is set. + If {cmd} is omitted, and the 'shell' job exits with no + error, the buffer is closed automatically + |default-autocmds|. + To enter |Terminal-mode| automatically: > autocmd TermOpen * startinsert < @@ -473,7 +483,7 @@ will be no "Last set" message. When it was defined while executing a function, user command or autocommand, the script in which it was defined is reported. *K* -[count]K Runs the program given by 'keywordprg' to lookup the +[count]K Runs the program given by 'keywordprg' to lookup the |word| (defined by 'iskeyword') under or right of the cursor. Default is "man". Works like this: > :tabnew | terminal {program} {keyword} @@ -489,6 +499,9 @@ user command or autocommand, the script in which it was defined is reported. < - When 'keywordprg' is equal to "man -s", a [count] before "K" is inserted after the "-s". If there is no count, the "-s" is removed. + *K-lsp-default* + - The Nvim |LSP| client sets K to show LSP "hover" + feature. |lsp-defaults| *v_K* {Visual}K Like "K", but use the visually highlighted text for diff --git a/runtime/doc/vi_diff.txt b/runtime/doc/vi_diff.txt index afabddb7f9..0a0cbc8ec6 100644 --- a/runtime/doc/vi_diff.txt +++ b/runtime/doc/vi_diff.txt @@ -11,9 +11,9 @@ Differences between Vim and Vi *vi-differences* ============================================================================== 1. Limits *limits* -Vim has only a few limits for the files that can be edited {Vi: can not handle +Vim has only a few limits for the files that can be edited. Vi cannot handle <Nul> characters and characters above 128, has limited line length, many other -limits}. +limits. Maximum line length 2147483647 characters Maximum number of lines 2147483647 lines @@ -44,7 +44,7 @@ kept in memory: Command-line history, error messages for Quickfix mode, etc. Support for different systems. Vim can be used on: - - Modern Unix systems (*BSD, Linux, etc.) + - Modern Unix systems (BSD, Linux, etc.) - Windows (XP SP 2 or greater) - OS X @@ -180,12 +180,12 @@ Command-line editing and history. |cmdline-editing| forward/backward one character. The shifted right/left cursor keys can be used to move forward/backward one word. CTRL-B/CTRL-E can be used to go to the begin/end of the command-line. - {Vi: can only alter the last character in the line} - {Vi: when hitting <Esc> the command-line is executed. This is + (Vi: can only alter the last character in the line) + (Vi: when hitting <Esc> the command-line is executed. This is unexpected for most people; therefore it was changed in Vim. But when the <Esc> is part of a mapping, the command-line is executed. If you want the Vi behaviour also when typing <Esc>, use ":cmap ^V<Esc> - ^V^M"} + ^V^M") |cmdline-history| The command-lines are remembered. The up/down cursor keys can be used to recall previous command-lines. The 'history' option can be set to diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index bb3b670b24..cf9b3cf0e5 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -13,7 +13,10 @@ centralized reference of the differences. Type |gO| to see the table of contents. ============================================================================== -1. Configuration *nvim-config* +Configuration *nvim-config* + +User configuration and data files are found in standard |base-directories| +(see also |$NVIM_APPNAME|). Note in particular: - Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for your |config|. - Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files. @@ -21,7 +24,7 @@ centralized reference of the differences. session information. |shada| ============================================================================== -2. Defaults *nvim-defaults* +Defaults *nvim-defaults* - Filetype detection is enabled by default. This can be disabled by adding ":filetype off" to |init.vim|. @@ -29,23 +32,28 @@ centralized reference of the differences. ":syntax off" to |init.vim|. - 'autoindent' is enabled -- 'autoread' is enabled +- 'autoread' is enabled (works in all UIs, including terminal) - 'background' defaults to "dark" (unless set automatically by the terminal/UI) - 'backspace' defaults to "indent,eol,start" - 'backupdir' defaults to .,~/.local/state/nvim/backup// (|xdg|), auto-created - 'belloff' defaults to "all" +- 'comments' includes "fb:•" +- 'commentstring' defaults to "" - 'compatible' is always disabled - 'complete' excludes "i" +- 'define' defaults to "". The C ftplugin sets it to "^\\s*#\\s*define" - 'directory' defaults to ~/.local/state/nvim/swap// (|xdg|), auto-created - 'display' defaults to "lastline" - 'encoding' is UTF-8 (cf. 'fileencoding' for file-content encoding) -- 'fillchars' defaults (in effect) to "vert:│,fold:·,sep:│" +- 'fillchars' defaults (in effect) to "vert:│,fold:·,foldsep:│" - 'formatoptions' defaults to "tcqj" -- 'fsync' is disabled - 'hidden' is enabled - 'history' defaults to 10000 (the maximum) - 'hlsearch' is enabled +- 'include' defaults to "". The C ftplugin sets it to "^\\s*#\\s*include" - 'incsearch' is enabled +- 'isfname' does not include ":" (on Windows). Drive letters are handled + correctly without it. (Use |gF| for filepaths suffixed with ":line:col"). - 'joinspaces' is disabled - 'langnoremap' is enabled - 'langremap' is disabled @@ -54,9 +62,10 @@ centralized reference of the differences. - 'mouse' defaults to "nvi" - 'mousemodel' defaults to "popup_setpos" - 'nrformats' defaults to "bin,hex" +- 'path' defaults to ".,,". The C ftplugin adds "/usr/include" if it exists. - 'ruler' is enabled - 'sessionoptions' includes "unix,slash", excludes "options" -- 'shortmess' includes "F", excludes "S" +- 'shortmess' includes "CF", excludes "S" - 'showcmd' is enabled - 'sidescroll' defaults to 1 - 'smarttab' is enabled @@ -72,13 +81,14 @@ centralized reference of the differences. - 'wildmenu' is enabled - 'wildoptions' defaults to "pum,tagfile" +- |editorconfig| plugin is enabled, .editorconfig settings are applied. - |man.lua| plugin is enabled, so |:Man| is available by default. - |matchit| plugin is enabled. To disable it in your config: >vim :let loaded_matchit = 1 - |g:vimsyn_embed| defaults to "l" to enable Lua highlighting -Default Mouse ~ +DEFAULT MOUSE *default-mouse* *disable-mouse* By default the mouse is enabled, and <RightMouse> opens a |popup-menu| with standard actions ("Cut", "Copy", "Paste", …). Mouse is NOT enabled in @@ -102,60 +112,70 @@ To remove the "How-to disable mouse" menu item and the separator above it: >vim aunmenu PopUp.How-to\ disable\ mouse aunmenu PopUp.-1- < -Default Mappings ~ +DEFAULT MAPPINGS *default-mappings* Nvim creates the following default mappings at |startup|. You can disable any of these in your config by simply removing the mapping, e.g. ":unmap Y". ->vim - nnoremap Y y$ - nnoremap <C-L> <Cmd>nohlsearch<Bar>diffupdate<Bar>normal! <C-L><CR> - inoremap <C-U> <C-G>u<C-U> - inoremap <C-W> <C-G>u<C-W> - xnoremap * y/\V<C-R>"<CR> - xnoremap # y?\V<C-R>"<CR> - nnoremap & :&&<CR> -< -Default Autocommands ~ + +- Y |Y-default| +- <C-U> |i_CTRL-U-default| +- <C-W> |i_CTRL-W-default| +- <C-L> |CTRL-L-default| +- & |&-default| +- # |v_#-default| +- * |v_star-default| +- Nvim LSP client defaults |lsp-defaults| + - K |K-lsp-default| + +DEFAULT AUTOCOMMANDS *default-autocmds* Default autocommands exist in the following groups. Use ":autocmd! {group}" to remove them and ":autocmd {group}" to see how they're defined. nvim_terminal: - BufReadCmd: Treats "term://" buffers as |terminal| buffers. |terminal-start| +- TermClose: A |terminal| buffer started with no arguments (which thus uses + 'shell') and which exits with no error is closed automatically. nvim_cmdwin: - CmdwinEnter: Limits syntax sync to maxlines=1 in the |cmdwin|. +nvim_swapfile: +- SwapExists: Skips the swapfile prompt (sets |v:swapchoice| to "e") when the + swapfile is owned by a running Nvim process. Shows |W325| "Ignoring + swapfile…" message. + ============================================================================== -3. New Features *nvim-features* +New Features *nvim-features* MAJOR COMPONENTS -API |API| -Job control |job-control| -LSP framework |lsp| -Lua scripting |lua| -Parsing engine |treesitter| -Providers - Clipboard |provider-clipboard| - Node.js plugins |provider-nodejs| - Python plugins |provider-python| - Ruby plugins |provider-ruby| -Remote plugins |remote-plugin| -Shared data |shada| -Terminal emulator |terminal| -Vimscript parser |nvim_parse_expression()| -XDG base directories |xdg| +- API |API| +- Job control |job-control| +- LSP framework |lsp| +- Lua scripting |lua| +- Parsing engine |treesitter| +- Providers + - Clipboard |provider-clipboard| + - Node.js plugins |provider-nodejs| + - Python plugins |provider-python| + - Ruby plugins |provider-ruby| +- Remote plugins |remote-plugin| +- Shared data |shada| +- Terminal emulator |terminal| +- UI |ui| |--listen| |--server| +- Vimscript parser |nvim_parse_expression()| +- XDG base directories |xdg| USER EXPERIENCE Working intuitively and consistently is a major goal of Nvim. *feature-compile* -- Nvim always includes ALL features, in contrast to Vim (which ships with - various combinations of 100+ optional features). Think of it as a leaner - version of Vim's "HUGE" build. This reduces surface area for bugs, and - removes a common source of confusion and friction for users. +- Nvim always includes ALL features, in contrast to Vim (which ships various + combinations of 100+ optional features). |feature-compile| Think of it as + a leaner version of Vim's "HUGE" build. This reduces surface area for bugs, + and removes a common source of confusion and friction for users. - Nvim avoids features that cannot be provided on all platforms; instead that is delegated to external plugins/extensions. E.g. the `-X` platform-specific @@ -173,17 +193,23 @@ backwards-compatibility cost. Some examples: - Directories for 'directory' and 'undodir' are auto-created. - Terminal features such as 'guicursor' are enabled where possible. +- Various "nvim" |cli-arguments| were redesigned. Some features are built in that otherwise required external plugins: -- Highlighting the yanked region, see |lua-highlight|. +- Highlighting the yanked region, see |vim.highlight|. ARCHITECTURE +The Nvim UI is "decoupled" from the core editor: all UIs, including the +builtin |TUI| are just plugins that connect to a Nvim server (via |--server| +or |--embed|). Multiple Nvim UI clients can connect to the same Nvim editor +server. + External plugins run in separate processes. |remote-plugin| This improves stability and allows those plugins to work without blocking the editor. Even "legacy" Python and Ruby plugins which use the old Vim interfaces (|if_pyth|, -|if_ruby|) run out-of-process. +|if_ruby|) run out-of-process, so they cannot crash Nvim. Platform and I/O facilities are built upon libuv. Nvim benefits from libuv features and bug fixes, and other projects benefit from improvements to libuv @@ -191,7 +217,7 @@ by Nvim developers. FEATURES -Command-line highlighting: +Command-line: The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted using a built-in Vimscript expression parser. |expr-highlight| *E5408* *E5409* @@ -229,12 +255,16 @@ Functions: |stdpath()| |system()|, |systemlist()| can run {cmd} directly (without 'shell') |matchadd()| can be called before highlight group is defined + |tempname()| tries to recover if the Nvim |tempdir| disappears. |writefile()| with "p" flag creates parent directories. Highlight groups: |highlight-blend| controls blend level for a highlight group |expr-highlight| highlight groups (prefixed with "Nvim") |hl-NormalFloat| highlights floating window + |hl-FloatBorder| highlights border of a floating window + |hl-FloatTitle| highlights title of a floating window + |hl-FloatFooter| highlights footer of a floating window |hl-NormalNC| highlights non-current windows |hl-MsgArea| highlights messages/cmdline area |hl-MsgSeparator| highlights separator for scrolled messages @@ -243,6 +273,8 @@ Highlight groups: |hl-TermCursorNC| |hl-WinSeparator| highlights window separators |hl-Whitespace| highlights 'listchars' whitespace + |hl-WinBar| highlights 'winbar' + |hl-WinBarNC| highlights non-current window 'winbar' Input/Mappings: ALT (|META|) chords always work (even in the |TUI|). Map |<M-| with any key: @@ -253,62 +285,135 @@ Input/Mappings: Normal commands: |gO| shows a filetype-defined "outline" of the current buffer. + |Q| replays the last recorded macro instead of switching to Ex mode (|gQ|). Options: + Local values for global-local number/boolean options are unset when the + option is set without a scope (e.g. by using |:set|), similarly to how + global-local string options work. + + 'autoread' works in the terminal (if it supports "focus" events) 'cpoptions' flags: |cpo-_| - 'guicursor' works in the terminal - 'fillchars' flags: "msgsep", "horiz", "horizup", - "horizdown", "vertleft", "vertright", "verthoriz" + 'diffopt' "linematch" feature + 'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The + user is prompted whether to trust the file. + 'fillchars' flags: "msgsep", "horiz", "horizup", "horizdown", + "vertleft", "vertright", "verthoriz" 'foldcolumn' supports up to 9 dynamic/fixed columns + 'guicursor' works in the terminal (TUI) 'inccommand' shows interactive results for |:substitute|-like commands and |:command-preview| commands + 'jumpoptions' "view" tries to restore the |mark-view| when moving through + the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|. 'laststatus' global statusline support 'mousescroll' amount to scroll by when scrolling with a mouse 'pumblend' pseudo-transparent popupmenu 'scrollback' + 'shortmess' "F" flag does not affect output from autocommands 'signcolumn' supports up to 9 dynamic/fixed columns - 'statusline' supports unlimited alignment sections + 'statuscolumn' full control of columns using 'statusline' format 'tabline' %@Func@foo%X can call any function on mouse-click + 'termpastefilter' + 'ttimeout', 'ttimeoutlen' behavior was simplified 'winblend' pseudo-transparency in floating windows |api-floatwin| 'winhighlight' window-local highlights - 'diffopt' has the option `linematch`. + +Providers: + If a Python interpreter is available on your `$PATH`, |:python| and + |:python3| are always available. See |provider-python|. + +Shell: + Shell output (|:!|, |:make|, …) is always routed through the UI, so it + cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if + you want to mess up the screen :) + + Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|) + if there is too much output. No data is lost, this only affects display and + improves performance. |:terminal| output is never throttled. + + |:!| does not support "interactive" commands. Use |:terminal| instead. + (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.) + + :!start is not special-cased on Windows. + + |system()| does not support writing/reading "backgrounded" commands. |E5677| Signs: Signs are removed if the associated line is deleted. + Signs placed twice with the same identifier in the same group are moved. + +Startup: + |-e| and |-es| invoke the same "improved Ex mode" as -E and -Es. + |-E| and |-Es| read stdin as text (into buffer 1). + |-es| and |-Es| have improved behavior: + - Quits automatically, don't need "-c qa!". + - Skips swap-file dialog. + |-s| reads Normal commands from stdin if the script name is "-". + Reading text (instead of commands) from stdin |--|: + - works by default: "-" file is optional + - works in more cases: |-Es|, file args + +TUI: + *:set-termcap* + Start Nvim with 'verbose' level 3 to show terminal capabilities: > + nvim -V3 +< + *'term'* *E529* *E530* *E531* + 'term' reflects the terminal type derived from |$TERM| and other environment + checks. For debugging only; not reliable during startup. >vim + :echo &term +< "builtin_x" means one of the |builtin-terms| was chosen, because the expected + terminfo file was not found on the system. + + Nvim will use 256-colour capability on Linux virtual terminals. Vim uses + only 8 colours plus bright foreground on Linux VTs. + + Vim combines what is in its |builtin-terms| with what it reads from terminfo, + and has a 'ttybuiltin' setting to control how that combination works. Nvim + uses one or the other, it does not attempt to merge the two. + +UI/Display: + |Visual| selection highlights the character at cursor. |visual-use| + + messages: When showing messages longer than 'cmdheight', only + scroll the message lines, not the entire screen. The + separator line is decorated by |hl-MsgSeparator| and + the "msgsep" flag of 'fillchars'. *msgsep* Variables: |v:progpath| is always absolute ("full") |v:windowid| is always available (for use by external UIs) + |OptionSet| autocommand args |v:option_new|, |v:option_old|, + |v:option_oldlocal|, |v:option_oldglobal| have the type of the option + instead of always being strings. |v:option_old| is now the old global value + for all global-local options, instead of just string global-local options. + +Vimscript: + |:redir| nested in |execute()| works. ============================================================================== -4. Upstreamed features *nvim-upstreamed* +Upstreamed features *nvim-upstreamed* These Nvim features were later integrated into Vim. - 'fillchars' flags: "eob" +- 'jumpoptions' "stack" behavior - 'wildoptions' flags: "pum" enables popupmenu for wildmode completion - |<Cmd>| - |WinClosed| - |WinScrolled| - |:sign-define| "numhl" argument - |:source| works with anonymous (no file) scripts +- 'statusline' supports unlimited alignment sections ============================================================================== -5. Changed features *nvim-features-changed* - -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. +Other changes *nvim-changed* -If a Python interpreter is available on your `$PATH`, |:python| and |:python3| -are always available and may be used simultaneously. See |provider-python|. - -|:redir| nested in |execute()| works. +This section documents various low-level behavior changes. |mkdir()| behaviour changed: 1. Assuming /tmp/foo does not exist and /tmp can be written to - mkdir('/tmp/foo/bar', 'p', 0700) will create both /tmp/foo and /tmp/foo/bar + mkdir('/tmp/foo/bar', 'p', 0700) will create both /tmp/foo and /tmp/foo/bar with 0700 permissions. Vim mkdir will create /tmp/foo with 0755. 2. If you try to create an existing directory with `'p'` (e.g. mkdir('/', 'p')) mkdir() will silently exit. In Vim this was an error. @@ -319,33 +424,33 @@ are always available and may be used simultaneously. See |provider-python|. structures. 2. |string()| fails immediately on nested containers, not when recursion limit was exceeded. -2. When |:echo| encounters duplicate containers like >vim +3. When |:echo| encounters duplicate containers like >vim let l = [] echo [l, l] < it does not use "[...]" (was: "[[], [...]]", now: "[[], []]"). "..." is only used for recursive containers. -3. |:echo| printing nested containers adds "@level" after "..." designating +4. |:echo| printing nested containers adds "@level" after "..." designating the level at which recursive container was printed: |:echo-self-refer|. Same thing applies to |string()| (though it uses construct like "{E724@level}"), but this is not reliable because |string()| continues to error out. -4. Stringifyed infinite and NaN values now use |str2float()| and can be evaled +5. Stringifyed infinite and NaN values now use |str2float()| and can be evaled back. -5. (internal) Trying to print or stringify VAR_UNKNOWN in Vim results in +6. (internal) Trying to print or stringify VAR_UNKNOWN in Vim results in nothing, E908, in Nvim it is internal error. |json_decode()| behaviour changed: 1. It may output |msgpack-special-dict|. -2. |msgpack-special-dict| is emitted also in case of duplicate keys, while in +2. |msgpack-special-dict| is emitted also in case of duplicate keys, while in Vim it errors out. 3. It accepts only valid JSON. Trailing commas are not accepted. -|json_encode()| behaviour slightly changed: now |msgpack-special-dict| values +|json_encode()| behaviour slightly changed: now |msgpack-special-dict| values are accepted, but |v:none| is not. -Viminfo text files were replaced with binary (messagepack) ShaDa files. +Viminfo text files were replaced with binary (messagepack) |shada| files. Additional differences: - |shada-c| has no effect. @@ -361,33 +466,35 @@ Additional differences: |shada-error-handling| - ShaDa file keeps search direction (|v:searchforward|), viminfo does not. -|printf()| returns something meaningful when used with `%p` argument: in Vim -it used to return useless address of the string (strings are copied to the -newly allocated memory all over the place) and fail on types which cannot be -coerced to strings. See |id()| for more details, currently it uses +|printf()| returns something meaningful when used with `%p` argument: in Vim +it used to return useless address of the string (strings are copied to the +newly allocated memory all over the place) and fail on types which cannot be +coerced to strings. See |id()| for more details, currently it uses `printf("%p", {expr})` internally. |c_CTRL-R| pasting a non-special register into |cmdline| omits the last <CR>. -|CursorMoved| always triggers when moving between windows. +|CursorMoved| triggers when moving between windows. Lua interface (|lua.txt|): - `:lua print("a\0b")` will print `a^@b`, like with `:echomsg "a\nb"` . In Vim that prints `a` and `b` on separate lines, exactly like `:lua print("a\nb")` . -- `:lua error('TEST')` emits the error “E5105: Error while calling lua chunk: - [string "<VimL compiled string>"]:1: TEST”, whereas Vim emits only “TEST”. +- `:lua error('TEST')` emits the error: > + E5108: Error executing lua: [string "<Vimscript compiled string>"]:1: TEST +< whereas Vim emits only "TEST". - Lua has direct access to Nvim |API| via `vim.api`. - Lua package.path and package.cpath are automatically updated according to - 'runtimepath': |lua-require|. + 'runtimepath'. |lua-module-load| Commands: |:doautocmd| does not warn about "No matching autocommands". |:wincmd| accepts a count. `:write!` does not show a prompt if the file was updated externally. + |:=| does not accept |ex-flags|. With an arg it is equivalent to |:lua=| -Command line completion: +Command-line: The meanings of arrow keys do not change depending on 'wildoptions'. Functions: @@ -404,9 +511,9 @@ Highlight groups: using |n| or |N| |hl-CursorLine| is low-priority unless foreground color is set |hl-VertSplit| superseded by |hl-WinSeparator| - Highlight groups names are allowed to contain the characters `.` and `@`. + Highlight groups names are allowed to contain `@` characters. It is an error to define a highlight group with a name that doesn't match - the regexp `[a-zA-Z0-9_.@]*` (see |group-name|). + the regexp `[a-zA-Z0-9_.@-]*` (see |group-name|). Macro/|recording| behavior Replay of a macro recorded during :lmap produces the same actions as when it @@ -418,51 +525,16 @@ Macro/|recording| behavior the results of keys from 'keymap'. Mappings: - Creating a mapping for a simplifiable key (e.g. <C-I>) doesn't replace an +- Creating a mapping for a simplifiable key (e.g. <C-I>) doesn't replace an existing mapping for its simplified form (e.g. <Tab>). +- "#" followed by a digit doesn't stand for a function key at the start of the + lhs of a mapping. Motion: The |jumplist| avoids useless/phantom jumps. -Normal commands: - |Q| replays the last recorded macro instead of switching to Ex mode. - Instead |gQ| can be used to enter Ex mode. - -Options: - 'ttimeout', 'ttimeoutlen' behavior was simplified - 'jumpoptions' "stack" behavior - 'jumpoptions' "view" tries to restore the |mark-view| when moving through - the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|. - 'shortmess' the "F" flag does not affect output from autocommands - 'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The user is - prompted whether to trust the file. - -Shell: - Shell output (|:!|, |:make|, …) is always routed through the UI, so it - cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if - you want to mess up the screen :) - - Nvim throttles (skips) messages from shell commands (|:!|, |:grep|, |:make|) - if there is too much output. No data is lost, this only affects display and - improves performance. |:terminal| output is never throttled. - - |:!| does not support "interactive" commands. Use |:terminal| instead. - (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.) - - :!start is not special-cased on Windows. - - |system()| does not support writing/reading "backgrounded" commands. |E5677| - -Startup: - |-e| and |-es| invoke the same "improved Ex mode" as -E and -Es. - |-E| and |-Es| read stdin as text (into buffer 1). - |-es| and |-Es| have improved behavior: - - Quits automatically, don't need "-c qa!". - - Skips swap-file dialog. - |-s| reads Normal commands from stdin if the script name is "-". - Reading text (instead of commands) from stdin |--|: - - works by default: "-" file is optional - - works in more cases: |-Es|, file args +Performance: + Folds are not updated during insert-mode. Syntax highlighting: syncolor.vim has been removed. Nvim now sets up default highlighting groups @@ -472,40 +544,13 @@ Syntax highlighting: after/syntax/syncolor.vim file should transition that file into a colorscheme. |:colorscheme| -TUI: - *:set-termcap* - Start Nvim with 'verbose' level 3 to show terminal capabilities: > - nvim -V3 -< - *'term'* *E529* *E530* *E531* - 'term' reflects the terminal type derived from |$TERM| and other environment - checks. For debugging only; not reliable during startup. >vim - :echo &term -< "builtin_x" means one of the |builtin-terms| was chosen, because the expected - terminfo file was not found on the system. - - Nvim will use 256-colour capability on Linux virtual terminals. Vim uses - only 8 colours plus bright foreground on Linux VTs. - - Vim combines what is in its |builtin-terms| with what it reads from terminfo, - and has a 'ttybuiltin' setting to control how that combination works. Nvim - uses one or the other, it does not attempt to merge the two. - -UI/Display: - |Visual| selection highlights the character at cursor. |visual-use| - - messages: When showing messages longer than 'cmdheight', only - scroll the message lines, not the entire screen. The - separator line is decorated by |hl-MsgSeparator| and - the "msgsep" flag of 'fillchars'. *msgsep* - Vimscript compatibility: `count` does not alias to |v:count| `errmsg` does not alias to |v:errmsg| `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): +Working directory (Vim implemented some of these after Nvim): - |DirChanged| and |DirChangedPre| can be triggered when switching to another window or tab. - |getcwd()| and |haslocaldir()| may throw errors if the tab page or window @@ -515,21 +560,24 @@ Working directory (Vim implemented some of these later than Nvim): - `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. -============================================================================== -6. Missing legacy features *nvim-features-missing* +Autocommands: +- Fixed inconsistent behavior in execution of nested autocommands: + https://github.com/neovim/neovim/issues/23368 +- |TermResponse| is fired for any OSC sequence received from the terminal, + instead of the Primary Device Attributes response. |v:termresponse| -Some legacy Vim features are not yet implemented: +============================================================================== +Missing features *nvim-missing* -- *if_lua* : Nvim |Lua| API is not compatible with Vim's "if_lua" -- *if_mzscheme* -- |if_pyth|: *python-bindeval* *python-Function* are not supported -- *if_tcl* +These legacy Vim features are not yet implemented: -*:gui* -*:gvim* +- *:gui* +- *:gvim* +- *'completepopup'* +- *'previewpopup'* ============================================================================== -7. Removed features *nvim-features-removed* +Removed legacy features *nvim-removed* These Vim features were intentionally removed from Nvim. @@ -548,8 +596,10 @@ Aliases: vimdiff (alias for "nvim -d" |diff-mode|) Commands: + :behave :fixdel - :hardcopy + *hardcopy* `:hardcopy` was removed. Instead, use `:TOhtml` and print the + resulting HTML using a web browser or other HTML viewer. :helpfind :mode (no longer accepts an argument) :open @@ -565,14 +615,21 @@ Commands: :cscope :lcscope :scscope + :Vimuntar Compile-time features: Emacs tags support X11 integration (see |x11-selection|) +Cscope: + *cscope* + Cscope support was removed in favour of plugin-based solutions such as: + https://github.com/dhananjaylatkar/cscope_maps.nvim + Eval: Vim9script *cscope_connection()* + *err_teapot()* *js_encode()* *js_decode()* *v:none* (used by Vim to represent JavaScript "undefined"); use |v:null| instead. @@ -581,6 +638,7 @@ Eval: *v:sizeofpointer* Events: + *SafeStateAgain* *SigUSR1* Use |Signal| to detect `SIGUSR1` signal instead. Highlight groups: @@ -595,7 +653,13 @@ Highlight groups: < Options: + *'aleph'* *'al'* antialias + 'backspace' no longer supports number values. Instead: + - for `backspace=0` set `backspace=` (empty) + - for `backspace=1` set `backspace=indent,eol` + - for `backspace=2` set `backspace=indent,eol,start` (default behavior in Nvim) + - for `backspace=3` set `backspace=indent,eol,nostop` *'balloondelay'* *'bdlay'* *'ballooneval'* *'beval'* *'noballooneval'* *'nobeval'* *'balloonexpr'* *'bexpr'* @@ -618,6 +682,14 @@ Options: *'guifontset'* *'gfs'* (Use 'guifont' instead.) *'guipty'* (Nvim uses pipes and PTYs consistently on all platforms.) 'highlight' (Names of builtin |highlight-groups| cannot be changed.) + *'hkmap'* *'hk'* use `set keymap=hebrew` instead. + *'hkmapp'* *'hkp'* use `set keymap=hebrewp` instead. + keyprotocol + + *'pastetoggle'* *'pt'* Just Paste It.™ |paste| is handled automatically when + you paste text using your terminal's or GUI's paste feature (CTRL-SHIFT-v, + CMD-v (macOS), middle-click, …). + *'imactivatefunc'* *'imaf'* *'imactivatekey'* *'imak'* *'imstatusfunc'* *'imsf'* @@ -651,11 +723,19 @@ Options: < *'macatsui'* *'maxcombine'* *'mco'* - Nvim always displays up to 6 combining characters. You can still edit - text with more than 6 combining characters, you just can't see them. - Use |g8| or |ga|. See |mbyte-combining|. + Nvim counts maximum character sizes in bytes, not codepoints. This is + guaranteed to be big enough to always fit all chars properly displayed + in vim with 'maxcombine' set to 6. + + You can still edit text with larger characters than fits in the screen buffer, + you just can't see them. Use |g8| or |ga|. See |mbyte-combining|. + + NOTE: the rexexp engine still has a hard-coded limit of considering + 6 composing chars only. + *'maxmem'* Nvim delegates memory-management to the OS. *'maxmemtot'* Nvim delegates memory-management to the OS. + printoptions *'printdevice'* *'printencoding'* *'printexpr'* @@ -669,6 +749,7 @@ Options: Everything is allowed in 'exrc' files since they must be explicitly marked trusted. *'shelltype'* + 'shortmess' flags: *shm-f* *shm-n* *shm-x* *shm-i* (behave like always on) *'shortname'* *'sn'* *'noshortname'* *'nosn'* *'swapsync'* *'sws'* *'termencoding'* *'tenc'* (Vim 7.4.852 also removed this for Windows) @@ -684,8 +765,18 @@ Options: *'ttytype'* *'tty'* weirdinvert -Performance: - Folds are not updated during insert-mode. +Plugins: + +- logiPat +- rrhelper +- *vimball* + +Providers: + +- *if_lua* : Nvim |Lua| API is not compatible with Vim's "if_lua". +- *if_mzscheme* +- |if_pyth|: *python-bindeval* *python-Function* are not supported. +- *if_tcl* Startup: --literal (file args are always literal; to expand wildcards on Windows, use @@ -735,14 +826,5 @@ TUI: at how the terminal is sending CSI. Nvim does not issue such a sequence and always uses 7-bit control sequences. -Cscope: - *cscope* - Cscope support has been removed in favour of LSP based solutions. - -Hardcopy: - *hardcopy* - `:hardcopy` was removed. Instead, use `:TOhtml` and print the resulting HTML - using a web browser or some other HTML viewer. - ============================================================================== vim:tw=78:ts=8:sw=2:et:ft=help:norl: diff --git a/runtime/doc/visual.txt b/runtime/doc/visual.txt index 0c6bd4f3a1..0d1ea937c0 100644 --- a/runtime/doc/visual.txt +++ b/runtime/doc/visual.txt @@ -169,6 +169,7 @@ If you want to highlight exactly the same area as the last time, you can use CTRL-C In Visual mode: Stop Visual mode. When insert mode is pending (the mode message shows "-- (insert) VISUAL --"), it is also stopped. + On MS-Windows, you may need to press CTRL-Break. ============================================================================== 3. Changing the Visual area *visual-change* @@ -398,7 +399,7 @@ selected text: > (In the <> notation |<>|, when typing it you should type it literally; you need to remove the 'B' flag from 'cpoptions') -Note that special characters (like '.' and '*') will cause problems. +Note that special characters (like '.' and "*") will cause problems. Visual-block Examples *blockwise-examples* With the following text, I will indicate the commands to produce the block and diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 61f5013f47..d6fce89f23 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -169,7 +169,7 @@ CTRL-W v *CTRL-W_v* it doesn't! CTRL-W n *CTRL-W_n* -CTRL-W CTRL_N *CTRL-W_CTRL-N* +CTRL-W CTRL-N *CTRL-W_CTRL-N* :[N]new [++opt] [+cmd] *:new* Create a new window and start editing an empty file in it. Make new window N high (default is to use half the existing @@ -223,7 +223,7 @@ CTRL-W ^ Split the current window in two and edit the alternate file. CTRL-W ge *CTRL-W_ge* Detach the current window as an external window. - Only available when using an UI with |ui-multigrid| support. + Only available when using a UI with |ui-multigrid| support. Note that the 'splitbelow' and 'splitright' options influence where a new window will appear. @@ -243,7 +243,8 @@ and 'winminwidth' are relevant. :hor[izontal] {cmd} Execute {cmd}. Currently only makes a difference for `horizontal wincmd =`, which will equalize windows only - horizontally. + horizontally, and |:terminal|, which will open a |terminal| + buffer in a split window. :lefta[bove] {cmd} *:lefta* *:leftabove* :abo[veleft] {cmd} *:abo* *:aboveleft* @@ -391,6 +392,11 @@ CTRL-W CTRL-O *CTRL-W_CTRL-O* *:on* *:only* given, then they become hidden. But modified buffers are never abandoned, so changes cannot get lost. + *:fc* *:fclose* +:[count]fc[lose][!] + Close [count] floating windows with the highest zindex values. + '!' to close all floating windows. + ============================================================================== 4. Moving cursor to other windows *window-move-cursor* @@ -631,7 +637,7 @@ times than |WinResized|, it may slow down editing a bit. The information provided by |WinScrolled| is a dictionary for each window that has changes, using the window ID as the key, and a total count of the changes -with the key "all". Example value for |v:event|: +with the key "all". Example value for |v:event|: > { all: {width: 0, height: 2, leftcol: 0, skipcol: 0, topline: 1, topfill: 0}, 1003: {width: 0, height: -1, leftcol: 0, skipcol: 0, topline: 0, topfill: 0}, @@ -1090,7 +1096,7 @@ list of buffers. |unlisted-buffer| a an active buffer: it is loaded and visible h a hidden buffer: It is loaded, but currently not displayed in a window |hidden-buffer| - - a buffer with 'modifiable' off + `-` a buffer with 'modifiable' off = a readonly buffer R a terminal buffer with a running job F a terminal buffer with a finished job @@ -1101,7 +1107,7 @@ list of buffers. |unlisted-buffer| [flags] can be a combination of the following characters, which restrict the buffers to be listed: + modified buffers - - buffers with 'modifiable' off + `-` buffers with 'modifiable' off = readonly buffers a active buffers u unlisted buffers (overrides the "!") |