diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 495 |
1 files changed, 321 insertions, 174 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index d2a3a962e6..11c4b62403 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1559,10 +1559,10 @@ v:exception The value of the exception most recently caught and not < Output: "caught oops". *v:false* *false-variable* -v:false Special value used to put "false" in JSON and msgpack. See - |json_encode()|. This value is converted to "v:false" when used - as a String (e.g. in |expr5| with string concatenation - operator) and to zero when used as a Number (e.g. in |expr5| +v:false Special value used to put "false" in JSON and msgpack. See + |json_encode()|. This value is converted to "v:false" when used + as a String (e.g. in |expr5| with string concatenation + operator) and to zero when used as a Number (e.g. in |expr5| or |expr7| when used with numeric operators). Read-only. *v:fcs_reason* *fcs_reason-variable* @@ -1703,16 +1703,16 @@ v:mouse_col Column number for a mouse click obtained with |getchar()|. value is zero when there was no mouse button click. *v:msgpack_types* *msgpack_types-variable* -v:msgpack_types Dictionary containing msgpack types used by |msgpackparse()| - and |msgpackdump()|. All types inside dictionary are fixed - (not editable) empty lists. To check whether some list is one +v:msgpack_types Dictionary containing msgpack types used by |msgpackparse()| + and |msgpackdump()|. All types inside dictionary are fixed + (not editable) empty lists. To check whether some list is one of msgpack types, use |is| operator. *v:null* *null-variable* -v:null Special value used to put "null" in JSON and NIL in msgpack. - See |json_encode()|. This value is converted to "v:null" when - used as a String (e.g. in |expr5| with string concatenation - operator) and to zero when used as a Number (e.g. in |expr5| +v:null Special value used to put "null" in JSON and NIL in msgpack. + See |json_encode()|. This value is converted to "v:null" when + used as a String (e.g. in |expr5| with string concatenation + operator) and to zero when used as a Number (e.g. in |expr5| or |expr7| when used with numeric operators). Read-only. *v:oldfiles* *oldfiles-variable* @@ -1788,9 +1788,9 @@ v:scrollstart String describing the script or function that caused the hit-enter prompt. *v:servername* *servername-variable* - *$NVIM_LISTEN_ADDRESS* -v:servername Default Nvim server address. Equivalent to - |$NVIM_LISTEN_ADDRESS| on startup. |serverstop()| +v:servername Primary listen-address of the current Nvim instance, the first + item returned by |serverlist()|. Can be set by |--listen| or + |$NVIM_LISTEN_ADDRESS| at startup. |serverstart()| |serverstop()| Read-only. @@ -1903,10 +1903,10 @@ v:throwpoint The point where the exception most recently caught and not < Output: "Exception from test.vim, line 2" *v:true* *true-variable* -v:true Special value used to put "true" in JSON and msgpack. See - |json_encode()|. This value is converted to "v:true" when used - as a String (e.g. in |expr5| with string concatenation - operator) and to one when used as a Number (e.g. in |expr5| or +v:true Special value used to put "true" in JSON and msgpack. See + |json_encode()|. This value is converted to "v:true" when used + as a String (e.g. in |expr5| with string concatenation + operator) and to one when used as a Number (e.g. in |expr5| or |expr7| when used with numeric operators). Read-only. *v:val* *val-variable* @@ -2492,7 +2492,7 @@ assert_fails({cmd} [, {error}]) *assert_fails()* assert_false({actual} [, {msg}]) *assert_false()* When {actual} is not false an error message is added to |v:errors|, like with |assert_equal()|. - A value is false when it is zero or |v:false|. When "{actual}" + A value is false when it is zero or |v:false|. When "{actual}" is not a number or |v:false| the assert fails. When {msg} is omitted an error in the form "Expected False but got {actual}" is produced. @@ -3182,7 +3182,7 @@ diff_hlID({lnum}, {col}) *diff_hlID()* 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. A Number is empty when its value is zero. Special + items. A Number is empty when its value is zero. Special variable is empty when it is |v:false| or |v:null|. escape({string}, {chars}) *escape()* @@ -4327,17 +4327,25 @@ getqflist([{what}]) *getqflist()* If the optional {what} dictionary argument is supplied, then returns only the items listed in {what} as a dictionary. The following string items are supported in {what}: + context get the context stored with |setqflist()| + items quickfix list entries nr get information for this quickfix list; zero - means the current quickfix list + means the current quickfix list and '$' means + the last quickfix list title get the list title winid get the |window-ID| (if opened) all all of the above quickfix properties Non-string items in {what} are ignored. If "nr" is not present then the current quickfix list is used. + To get the number of lists in the quickfix stack, set 'nr' to + '$' in {what}. The 'nr' value in the returned dictionary + contains the quickfix stack size. In case of error processing {what}, an empty dictionary is returned. The returned dictionary contains the following entries: + context context information stored with |setqflist()| + items quickfix list entries nr quickfix list number title quickfix list title text winid quickfix |window-ID| (if opened) @@ -4749,7 +4757,7 @@ input({opts}) string, or a blank string (for no prompt). A '\n' can be used in the prompt to start a new line. - In the second form it accepts a single dictionary with the + In the second form it accepts a single dictionary with the following keys, any of which may be omitted: Key Default Description ~ @@ -4757,7 +4765,7 @@ input({opts}) default "" Same as {text} in the first form. completion nothing Same as {completion} in the first form. cancelreturn "" Same as {cancelreturn} from - |inputdialog()|. Also works with + |inputdialog()|. Also works with input(). highlight nothing Highlight handler: |Funcref|. @@ -4833,8 +4841,8 @@ input({opts}) modifier. If the function causes any errors, it will be skipped for the duration of the current input() call. - Currently coloring is disabled when command-line contains - arabic characters. + Highlighting is disabled if command-line contains arabic + characters. NOTE: This function must not be used in a startup file, for the versions that only run in GUI mode (e.g., the Win32 GUI). @@ -4948,19 +4956,19 @@ islocked({expr}) *islocked()* *E786* message. Use |exists()| to check for existence. id({expr}) *id()* - Returns a |String| which is a unique identifier of the - container type (|List|, |Dict| 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: - |v:_null_list| and |v:_null_dict| have the same `id()` with - different types because they are internally represented as - a NULL pointers). Currently `id()` returns a hexadecimal - representanion of the pointers to the containers (i.e. like - `0x994a40`), same as `printf("%p", {expr})`, but it is advised + Returns a |String| which is a unique identifier of the + container type (|List|, |Dict| 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: + |v:_null_list| and |v:_null_dict| have the same `id()` with + different types because they are internally represented as + a NULL pointers). Currently `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 exact format of return value. - It is not guaranteed that `id(no_longer_existing_container)` - will not be equal to some other `id()`: new containers may + 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. items({dict}) *items()* @@ -5071,14 +5079,14 @@ join({list} [, {sep}]) *join()* The opposite function is |split()|. 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 + 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 |msgpack-special-dict|: 1. Dictionary contains duplicate key. 2. Dictionary contains empty key. - 3. String contains NUL byte. Two special dictionaries: for - dictionary and for string will be emitted in case string + 3. String contains NUL byte. Two special dictionaries: for + dictionary and for string will be emitted in case string with NUL byte was a dictionary key. Note: function treats its input as UTF-8 always. The JSON @@ -5087,14 +5095,14 @@ json_decode({expr}) *json_decode()* Non-UTF-8 characters are an error. 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 - |msgpack-special-dict|), values with self-referencing - containers, strings which contain non-UTF-8 characters, - pseudo-UTF-8 strings which contain codepoints reserved for - surrogate pairs (such strings are not valid UTF-8 strings). - Non-printable characters are converted into "\u1234" escapes + 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 + |msgpack-special-dict|), values with self-referencing + containers, strings which contain non-UTF-8 characters, + pseudo-UTF-8 strings which contain codepoints reserved for + surrogate pairs (such strings are not valid UTF-8 strings). + Non-printable characters are converted into "\u1234" escapes or special escapes like "\t", other are dumped as-is. keys({dict}) *keys()* @@ -5193,7 +5201,7 @@ line({expr}) The result is a Number, which is the line number of the file This autocommand jumps to the last known position in a file just after opening it, if the '" mark is set: > :au BufReadPost * - \ if line("'\"") > 1 && line("'\"") <= line("$") && &ft !~# 'commit' + \ if line("'\"") > 1 && line("'\"") <= line("$") && &ft !~# 'commit' \ | exe "normal! g`\"" \ | endif @@ -5244,7 +5252,7 @@ log10({expr}) *log10()* < -2.0 luaeval({expr}[, {expr}]) - Evaluate Lua expression {expr} and return its result converted + Evaluate Lua expression {expr} and return its result converted to Vim data structures. See |lua-luaeval| for more details. map({expr1}, {expr2}) *map()* @@ -5493,7 +5501,7 @@ matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) sets buffer line boundaries to redraw screen. It is supposed to be used when fast match additions and deletions are required, for example to highlight matching parentheses. - + *E5030* *E5031* The list {pos} can contain one of these items: - A number. This whole line will be highlighted. The first line has number 1. @@ -5507,6 +5515,10 @@ matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) - A list with three numbers, e.g., [23, 11, 3]. As above, but the third number gives the length of the highlight in bytes. + Entries with zero and negative line numbers are silently + ignored, as well as entries with negative column numbers and + lengths. + The maximum number of positions is 8. Example: > @@ -5675,7 +5687,7 @@ mkdir({name} [, {path} [, {prot}]]) :call mkdir($HOME . "/tmp/foo/bar", "p", 0700) < 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 {path} set to "p" mkdir() will silently exit. *mode()* @@ -5728,78 +5740,76 @@ msgpackdump({list}) {Nvim} *msgpackdump()* 5. Points 3. and 4. do not apply to |msgpack-special-dict|s. msgpackparse({list}) {Nvim} *msgpackparse()* - Convert a |readfile()|-style list to a list of VimL objects. + Convert a |readfile()|-style list to a list of VimL objects. Example: > let fname = expand('~/.config/nvim/shada/main.shada') let mpack = readfile(fname, 'b') let shada_objects = msgpackparse(mpack) -< This will read ~/.config/nvim/shada/main.shada file to +< This will read ~/.config/nvim/shada/main.shada file to `shada_objects` list. Limitations: - 1. Mapping ordering is not preserved unless messagepack - mapping is dumped using generic mapping + 1. Mapping ordering is not preserved unless messagepack + mapping is dumped using generic mapping (|msgpack-special-map|). - 2. Since the parser aims to preserve all data untouched - (except for 1.) some strings are parsed to - |msgpack-special-dict| format which is not convenient to + 2. Since the parser aims to preserve all data untouched + (except for 1.) some strings are parsed to + |msgpack-special-dict| format which is not convenient to use. *msgpack-special-dict* - Some messagepack strings may be parsed to special + Some messagepack strings may be parsed to special dictionaries. Special dictionaries are dictionaries which 1. Contain exactly two keys: `_TYPE` and `_VAL`. - 2. `_TYPE` key is one of the types found in |v:msgpack_types| + 2. `_TYPE` key is one of the types found in |v:msgpack_types| variable. - 3. Value for `_VAL` has the following format (Key column + 3. Value for `_VAL` has the following format (Key column contains name of the key from |v:msgpack_types|): Key Value ~ - nil Zero, ignored when dumping. This value cannot - possibly appear in |msgpackparse()| output in Neovim - versions which have |v:null|. - boolean One or zero. When dumping it is only checked that - value is a |Number|. This value cannot possibly - appear in |msgpackparse()| output in Neovim versions - which have |v:true| and |v:false|. - integer |List| with four numbers: sign (-1 or 1), highest two - bits, number with bits from 62nd to 31st, lowest 31 - bits. I.e. to get actual number one will need to use + nil Zero, ignored when dumping. Not returned by + |msgpackparse()| since |v:null| was introduced. + boolean One or zero. When dumping it is only checked that + value is a |Number|. Not returned by |msgpackparse()| + since |v:true| and |v:false| were introduced. + integer |List| with four numbers: sign (-1 or 1), highest two + bits, number with bits from 62nd to 31st, lowest 31 + bits. I.e. to get actual number one will need to use code like > _VAL[0] * ((_VAL[1] << 62) & (_VAL[2] << 31) & _VAL[3]) -< Special dictionary with this type will appear in - |msgpackparse()| output under one of the following +< Special dictionary with this type will appear in + |msgpackparse()| output under one of the following circumstances: - 1. |Number| is 32-bit and value is either above + 1. |Number| is 32-bit and value is either above INT32_MAX or below INT32_MIN. - 2. |Number| is 64-bit and value is above INT64_MAX. It - cannot possibly be below INT64_MIN because msgpack + 2. |Number| is 64-bit and value is above INT64_MAX. It + cannot possibly be below INT64_MIN because msgpack C parser does not support such values. - float |Float|. This value cannot possibly appear in + float |Float|. This value cannot possibly appear in |msgpackparse()| output. - string |readfile()|-style list of strings. This value will - appear in |msgpackparse()| output if string contains - zero byte or if string is a mapping key and mapping is - being represented as special dictionary for other + string |readfile()|-style list of strings. This value will + appear in |msgpackparse()| output if string contains + zero byte or if string is a mapping key and mapping is + being represented as special dictionary for other reasons. - binary |readfile()|-style list of strings. This value will - appear in |msgpackparse()| output if binary string + binary |readfile()|-style list of strings. This value will + appear in |msgpackparse()| output if binary string contains zero byte. - array |List|. This value cannot appear in |msgpackparse()| + array |List|. This value cannot appear in |msgpackparse()| output. *msgpack-special-map* - map |List| of |List|s with two items (key and value) each. - This value will appear in |msgpackparse()| output if + map |List| of |List|s with two items (key and value) each. + This value will appear in |msgpackparse()| output if parsed mapping contains one of the following keys: - 1. Any key that is not a string (including keys which + 1. Any key that is not a string (including keys which are binary strings). 2. String with NUL byte inside. 3. Duplicate key. 4. Empty key. - ext |List| with two values: first is a signed integer - representing extension type. Second is + ext |List| with two values: first is a signed integer + representing extension type. Second is |readfile()|-style list of strings. nextnonblank({lnum}) *nextnonblank()* @@ -6073,11 +6083,11 @@ pumvisible() *pumvisible()* 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 - copied though, Unicode strings are additionally converted to + Numbers and strings are returned as they are (strings are + copied though, Unicode strings are additionally converted to UTF-8). Lists are represented as Vim |List| type. - Dictionaries are represented as Vim |Dictionary| type with + Dictionaries are represented as Vim |Dictionary| type with keys converted to strings. {only available when compiled with the |+python3| feature} @@ -6145,7 +6155,7 @@ readfile({fname} [, {binary} [, {max}]]) reltime([{start} [, {end}]]) *reltime()* Return an item that represents a time value. The format of the item depends on the system. It can be passed to - |reltimestr()| to convert it to a string or |reltimefloat()| + |reltimestr()| to convert it to a string or |reltimefloat()| to convert to a float. Without an argument it returns the current "relative time", an @@ -6628,15 +6638,11 @@ server2client({clientid}, {string}) *server2client()* :echo server2client(expand("<client>"), "HELLO") < serverlist() *serverlist()* - Returns a list of available server names in a list. - When there are no servers an empty string is returned. + Returns a list of server addresses, or empty if all servers + were stopped. |serverstart()| |serverstop()| Example: > :echo serverlist() -< {Nvim} *--serverlist* - The Vim command-line option `--serverlist` was removed from - Nvim, but it can be imitated: > - nvim --cmd "echo serverlist()" --cmd "q" -< + serverstart([{address}]) *serverstart()* Opens a socket or named pipe at {address} and listens for |RPC| messages. Clients can send |API| commands to the address @@ -6664,13 +6670,9 @@ serverstart([{address}]) *serverstart()* < |$NVIM_LISTEN_ADDRESS| is set to {address} if not already set. - *--servername* - The Vim command-line option `--servername` can be imitated: > - nvim --cmd "let g:server_addr = serverstart('foo')" -< serverstop({address}) *serverstop()* - Closes the pipe or socket at {address}. Does nothing if - {address} is empty or invalid. + Closes the pipe or socket at {address}. + Returns TRUE if {address} is valid, else FALSE. If |$NVIM_LISTEN_ADDRESS| is stopped it is unset. If |v:servername| is stopped it is set to the next available address returned by |serverlist()|. @@ -6843,6 +6845,7 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* nr error number text description of the error type single-character error type, 'E', 'W', etc. + valid recognized error message The "col", "vcol", "nr", "type" and "text" entries are optional. Either "lnum" or "pattern" entry can be used to @@ -6852,21 +6855,26 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* item will not be handled as an error line. If both "pattern" and "lnum" are present then "pattern" will be used. + If the "valid" entry is not supplied, then the valid flag is + set when "bufnr" is a valid buffer or "filename" exists. If you supply an empty {list}, the quickfix list will be cleared. Note that the list is not exactly the same as what |getqflist()| returns. - *E927* - If {action} is set to 'a', then the items from {list} are - added to the existing quickfix list. If there is no existing - list, then a new list is created. + {action} values: *E927* + 'a' The items from {list} are added to the existing + quickfix list. If there is no existing list, then a + new list is created. - If {action} is set to 'r', then 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') + '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') < + 'f' All the quickfix lists in the quickfix stack are + freed. + If {action} is not present or is set to ' ', then a new list is created. @@ -6877,7 +6885,12 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* only the items listed in {what} are set. The first {list} argument is ignored. The following items can be specified in {what}: - nr list number in the quickfix stack + context any Vim type can be stored as a context + items list of quickfix entries. Same as the {list} + argument. + nr list number in the quickfix stack; zero + means the current quickfix list and '$' means + the last quickfix list title quickfix list title text Unsupported keys in {what} are ignored. If the "nr" item is not present, then the current quickfix list @@ -6929,9 +6942,9 @@ setreg({regname}, {value} [, {options}]) :call setreg('a', "1\n2\n3", 'b5') < This example shows using the functions to save and restore a - register (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 + register (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|). > :let var_a = getreg('a', 1, 1) :let var_amode = getregtype('a') @@ -6982,18 +6995,22 @@ shellescape({string} [, {special}]) *shellescape()* quotes within {string}. Otherwise, it will enclose {string} in single quotes and replace all "'" with "'\''". + When the {special} argument is present and it's a non-zero Number or a non-empty String (|non-zero-arg|), then special items such as "!", "%", "#" and "<cword>" will be preceded by a backslash. This backslash will be removed again by the |:!| command. + The "!" character will be escaped (again with a |non-zero-arg| {special}) when 'shell' contains "csh" in the tail. That is because for csh and tcsh "!" is used for history replacement even when inside single quotes. - The <NL> character is also escaped. With a |non-zero-arg| - {special} and 'shell' containing "csh" in the tail it's + + With a |non-zero-arg| {special} the <NL> character is also + escaped. When 'shell' containing "csh" in the tail it's escaped a second time. + Example of use with a |:!| command: > :exe '!dir ' . shellescape(expand('<cfile>'), 1) < This results in a directory listing for the file under the @@ -7369,20 +7386,20 @@ string({expr}) Return {expr} converted to a String. If {expr} is a Number, {expr} type result ~ String 'string' Number 123 - Float 123.123456 or 1.123456e8 or + Float 123.123456 or 1.123456e8 or `str2float('inf')` Funcref `function('name')` List [item, item] 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 - for infinite and NaN floating-point values representations - which use |str2float()|. Strings are also dumped literally, - only single quote is escaped, which does not allow using YAML - for parsing back binary strings. |eval()| should always work for - strings and floats though and this is the only official - method, use |msgpackdump()| or |json_encode()| if you need to + Note 2: Output format is mostly compatible with YAML, except + for infinite and NaN floating-point values representations + which use |str2float()|. Strings are also dumped literally, + only single quote is escaped, which does not allow using YAML + for parsing back binary strings. |eval()| should always work for + strings and floats though and this is the only official + method, use |msgpackdump()| or |json_encode()| if you need to share data with other application. *strlen()* @@ -7577,17 +7594,29 @@ synIDtrans({synID}) *synIDtrans()* ":highlight link" are followed. synconcealed({lnum}, {col}) *synconcealed()* - The result is a List. The first item in the list is 0 if the - character at the position {lnum} and {col} is not part of a - concealable region, 1 if it is. The second item in the list is - a string. If the first item is 1, the second item contains the - text which will be displayed in place of the concealed text, - depending on the current setting of 'conceallevel'. The third - and final item in the list is a unique number representing the - specific syntax region matched. This allows detection of the - beginning of a new concealable region if there are two - consecutive regions with the same replacement character. - For an example use see $VIMRUNTIME/syntax/2html.vim . + 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 + region, 1 if it is. + 2. The second item in the list is a string. If the first item + is 1, the second item contains the text which will be + displayed in place of the concealed text, depending on the + current setting of 'conceallevel' and 'listchars'. + 3. The third and final item in the list is a number + representing the specific syntax region matched in the + line. When the character is not concealed the value is + zero. This allows detection of the beginning of a new + concealable region if there are two consecutive regions + with the same replacement character. For an example, if + the text is "123456" and both "23" and "45" are concealed + and replace by the character "X", then: + call returns ~ + synconcealed(lnum, 1) [0, '', 0] + synconcealed(lnum, 2) [1, 'X', 1] + synconcealed(lnum, 3) [1, 'X', 1] + synconcealed(lnum, 4) [1, 'X', 2] + synconcealed(lnum, 5) [1, 'X', 2] + synconcealed(lnum, 6) [0, '', 0] synstack({lnum}, {col}) *synstack()* @@ -7620,6 +7649,9 @@ system({cmd} [, {input}]) *system()* *E677* |writefile()| does with {binary} set to "b" (i.e. with a newline between each list item, and newlines inside list items converted to NULs). + When {input} is given and is a valid buffer id, the content of + the buffer is written to the file line by line, each line + terminated by a NL (and NUL where the text has NL). *E5677* Note: system() cannot write to or read from backgrounded ("&") shell commands, e.g.: > @@ -7630,10 +7662,10 @@ system({cmd} [, {input}]) *system()* *E677* redirection syntax) before input can reach it. Use |jobstart()| instead. - Note: Use |shellescape()| or |::S| with |expand()| or - |fnamemodify()| to escape special characters in a command - argument. Newlines in {cmd} may cause the command to fail. - The characters in 'shellquote' and 'shellxquote' may also + Note: Use |shellescape()| or |::S| with |expand()| or + |fnamemodify()| to escape special characters in a command + argument. Newlines in {cmd} may cause the command to fail. + The characters in 'shellquote' and 'shellxquote' may also cause trouble. The result is a String. Example: > @@ -7660,9 +7692,9 @@ system({cmd} [, {input}]) *system()* *E677* 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 + 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 set to "b", except that a final newline is not preserved, unless {keepempty} is non-zero. Note that on MS-Windows you may get trailing CR characters. @@ -7926,7 +7958,7 @@ type({expr}) *type()* :if type(myvar) == type({}) :if type(myvar) == type(0.0) :if type(myvar) == type(v:true) -< In place of checking for |v:null| type it is better to check +< 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: > @@ -8243,10 +8275,10 @@ writefile({list}, {fname} [, {flags}]) :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 + 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. All NL characters are replaced with a NUL character. @@ -8414,6 +8446,7 @@ win32 Windows version of Vim (32 or 64 bit). winaltkeys Compiled with 'winaltkeys' option. windows Compiled with support for more than one window. writebackup Compiled with 'writebackup' default on. +wsl WSL (Windows Subsystem for Linux) version of Vim. *string-match* Matching a pattern in a String @@ -8728,7 +8761,7 @@ like this: > When such a function is called, and it is not defined yet, Vim will search the "autoload" directories in 'runtimepath' for a script file called -"filename.vim". For example "~/.config/nvim/autoload/filename.vim". That +"filename.vim". For example "~/.config/nvim/autoload/filename.vim". That file should then define the function like this: > function filename#funcname() @@ -8889,11 +8922,6 @@ This does NOT work: > value and the global value are changed. Example: > :let &path = &path . ',/usr/local/include' -< This also works for terminal codes in the form t_xx. - But only for alphanumerical names. Example: > - :let &t_k1 = "\<Esc>[234;" -< When the code does not exist yet it will be created as - a terminal key code, there is no error. :let &{option-name} .= {expr1} For a string option: Append {expr1} to the value. @@ -9004,8 +9032,8 @@ This does NOT work: > < *E741* *E940* If you try to change a locked variable you get an error message: "E741: Value is locked: {name}". - If you try to lock or unlock a built-in variable you - will get an error message "E940: Cannot lock or unlock + If you try to lock or unlock a built-in variable you + will get an error message "E940: Cannot lock or unlock variable {name}". [depth] is relevant when locking a |List| or @@ -9264,17 +9292,17 @@ This does NOT work: > with the |:redraw| command. Example: > :new | redraw | echo "there is a new window" < *:echo-self-refer* - When printing nested containers echo prints second - occurrence of the self-referencing container using - "[...@level]" (self-referencing |List|) or + When printing nested containers echo prints second + occurrence of the self-referencing container using + "[...@level]" (self-referencing |List|) or "{...@level}" (self-referencing |Dict|): > :let l = [] :call add(l, l) :let l2 = [] :call add(l2, [l2]) :echo l l2 -< echoes "[[...@0]] [[[...@0]]]". Echoing "[l]" will - echo "[[[...@1]]]" because l first occurs at second +< echoes "[[...@0]] [[[...@0]]]". Echoing "[l]" will + echo "[[[...@1]]]" because l first occurs at second level. *:echon* @@ -10505,18 +10533,19 @@ missing: > To execute a command only when the |+eval| feature is disabled requires a trick, as this example shows: > - if 1 - nnoremap : :" - endif - normal :set history=111<CR> - if 1 - nunmap : - endif + + silent! while 0 + set history=111 + silent! endwhile + +When the |+eval| feature is available the command is skipped because of the +"while 0". Without the |+eval| feature the "while 0" is an error, which is +silently ignored, and the command is executed. The "<CR>" here is a real CR character, type CTRL-V Enter to get it. When the |+eval| feature is available the ":" is remapped to add a double -quote, which has the effect of commenting-out the command. without the +quote, which has the effect of commenting-out the command. Without the |+eval| feature the nnoremap command is skipped and the command is executed. ============================================================================== @@ -10563,7 +10592,7 @@ option will still be marked as it was set in the sandbox. 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 +actually doing something else. For example, evaluating the 'balloonexpr' may happen any moment the mouse cursor is resting at some position. This is not allowed when the textlock is active: @@ -10573,5 +10602,123 @@ This is not allowed when the textlock is active: - closing a window or quitting Vim - etc. +============================================================================== +13. Command-line expressions highlighting *expr-highlight* + +Expressions entered by the user in |i_CTRL-R_=|, |c_CTRL-\_e|, |quote=| are +highlighted by the built-in expressions parser. It uses highlight groups +described in the table below, which may be overriden by colorschemes. + *hl-NvimInvalid* +Besides the "Nvim"-prefixed highlight groups described below, there are +"NvimInvalid"-prefixed highlight groups which have the same meaning but +indicate that the token contains an error or that an error occurred just +before it. They have mostly the same hierarchy, except that (by default) in +place of any non-Nvim-prefixed group NvimInvalid linking to `Error` is used +and some other intermediate groups are present. + +Group Default link Colored expression ~ +*hl-NvimInternalError* None, red/red Parser bug + +*hl-NvimAssignment* Operator Generic assignment +*hl-NvimPlainAssignment* NvimAssignment `=` in |:let| +*hl-NvimAugmentedAssignment* NvimAssignment Generic, `+=`/`-=`/`.=` +*hl-NvimAssignmentWithAddition* NvimAugmentedAssignment `+=` in |:let+=| +*hl-NvimAssignmentWithSubtraction* NvimAugmentedAssignment `-=` in |:let-=| +*hl-NvimAssignmentWithConcatenation* NvimAugmentedAssignment `.=` in |:let.=| + +*hl-NvimOperator* Operator Generic operator + +*hl-NvimUnaryOperator* NvimOperator Generic unary op +*hl-NvimUnaryPlus* NvimUnaryOperator |expr-unary-+| +*hl-NvimUnaryMinus* NvimUnaryOperator |expr-unary--| +*hl-NvimNot* NvimUnaryOperator |expr-!| + +*hl-NvimBinaryOperator* NvimOperator Generic binary op +*hl-NvimComparison* NvimBinaryOperator Any |expr4| operator +*hl-NvimComparisonModifier* NvimComparison `#`/`?` near |expr4| op +*hl-NvimBinaryPlus* NvimBinaryOperator |expr-+| +*hl-NvimBinaryMinus* NvimBinaryOperator |expr--| +*hl-NvimConcat* NvimBinaryOperator |expr-.| +*hl-NvimConcatOrSubscript* NvimConcat |expr-.| or |expr-entry| +*hl-NvimOr* NvimBinaryOperator |expr-barbar| +*hl-NvimAnd* NvimBinaryOperator |expr-&&| +*hl-NvimMultiplication* NvimBinaryOperator |expr-star| +*hl-NvimDivision* NvimBinaryOperator |expr-/| +*hl-NvimMod* NvimBinaryOperator |expr-%| + +*hl-NvimTernary* NvimOperator `?` in |expr1| +*hl-NvimTernaryColon* NvimTernary `:` in |expr1| + +*hl-NvimParenthesis* Delimiter Generic bracket +*hl-NvimLambda* NvimParenthesis `{`/`}` in |lambda| +*hl-NvimNestingParenthesis* NvimParenthesis `(`/`)` in |expr-nesting| +*hl-NvimCallingParenthesis* NvimParenthesis `(`/`)` in |expr-function| + +*hl-NvimSubscript* NvimParenthesis Generic subscript +*hl-NvimSubscriptBracket* NvimSubscript `[`/`]` in |expr-[]| +*hl-NvimSubscriptColon* NvimSubscript `:` in |expr-[:]| +*hl-NvimCurly* NvimSubscript `{`/`}` in + |curly-braces-names| + +*hl-NvimContainer* NvimParenthesis Generic container +*hl-NvimDict* NvimContainer `{`/`}` in |dict| literal +*hl-NvimList* NvimContainer `[`/`]` in |list| literal + +*hl-NvimIdentifier* Identifier Generic identifier +*hl-NvimIdentifierScope* NvimIdentifier Namespace: letter + before `:` in + |internal-variables| +*hl-NvimIdentifierScopeDelimiter* NvimIdentifier `:` after namespace + letter +*hl-NvimIdentifierName* NvimIdentifier Rest of the ident +*hl-NvimIdentifierKey* NvimIdentifier Identifier after + |expr-entry| + +*hl-NvimColon* Delimiter `:` in |dict| literal +*hl-NvimComma* Delimiter `,` in |dict|/|list| + literal or + |expr-function| +*hl-NvimArrow* Delimiter `->` in |lambda| + +*hl-NvimRegister* SpecialChar |expr-register| +*hl-NvimNumber* Number Non-prefix digits + in integer + |expr-number| +*hl-NvimNumberPrefix* Type `0` for |octal-number| + `0x` for |hex-number| + `0b` for |binary-number| +*hl-NvimFloat* NvimNumber Floating-point + number + +*hl-NvimOptionSigil* Type `&` in |expr-option| +*hl-NvimOptionScope* NvimIdentifierScope Option scope if any +*hl-NvimOptionScopeDelimiter* NvimIdentifierScopeDelimiter + `:` after option scope +*hl-NvimOptionName* NvimIdentifier Option name + +*hl-NvimEnvironmentSigil* NvimOptionSigil `$` in |expr-env| +*hl-NvimEnvironmentName* NvimIdentifier Env variable name + +*hl-NvimString* String Generic string +*hl-NvimStringBody* NvimString Generic string + literal body +*hl-NvimStringQuote* NvimString Generic string quote +*hl-NvimStringSpecial* SpecialChar Generic string + non-literal body + +*hl-NvimSingleQuote* NvimStringQuote `'` in |expr-'| +*hl-NvimSingleQuotedBody* NvimStringBody Literal part of + |expr-'| string body +*hl-NvimSingleQuotedQuote* NvimStringSpecial `''` inside |expr-'| + string body + +*hl-NvimDoubleQuote* NvimStringQuote `"` in |expr-quote| +*hl-NvimDoubleQuotedBody* NvimStringBody Literal part of + |expr-quote| body +*hl-NvimDoubleQuotedEscape* NvimStringSpecial Valid |expr-quote| + escape sequence +*hl-NvimDoubleQuotedUnknownEscape* NvimInvalidValue Unrecognized + |expr-quote| escape + sequence vim:tw=78:ts=8:noet:ft=help:norl: |