To: vim_dev@googlegroups.com Subject: Patch 8.2.3913 Fcc: outbox From: Bram Moolenaar Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ------------ Patch 8.2.3913 Problem: Help for expressions does not mention Vim9 syntax. Solution: Add the rules for Vim9 to the expression help. Rename functions to match the help. Files: runtime/doc/vim9.txt, runtime/doc/eval.txt, src/vim9expr.c *** ../vim-8.2.3912/runtime/doc/vim9.txt 2021-12-26 18:08:33.729729382 +0000 --- runtime/doc/vim9.txt 2021-12-27 15:37:15.811001697 +0000 *************** *** 81,87 **** echo "hello " .. yourName .. ", how are you?" ! - White space is required in many places. - Assign values without `:let`, declare variables with `:var`: > var count = 0 count += 3 --- 81,87 ---- echo "hello " .. yourName .. ", how are you?" ! - White space is required in many places to improve readability. - Assign values without `:let`, declare variables with `:var`: > var count = 0 count += 3 *************** *** 94,101 **** def CallMe(count: number, message: string): bool - Call functions without `:call`: > writefile(['done'], 'file.txt') ! - You cannot use `:xit`, `:t`, `:k`, `:append`, `:change`, `:insert`, `:open`, ! and `:s` or `:d` with only flags. - You cannot use curly-braces names. - A range before a command must be prefixed with a colon: > :%s/this/that --- 94,101 ---- def CallMe(count: number, message: string): bool - Call functions without `:call`: > writefile(['done'], 'file.txt') ! - You cannot use old Ex commands `:xit`, `:t`, `:k`, `:append`, `:change`, ! `:insert`, `:open`, and `:s` or `:d` with only flags. - You cannot use curly-braces names. - A range before a command must be prefixed with a colon: > :%s/this/that *************** *** 353,359 **** In Vim9 script `:let` cannot be used. An existing variable is assigned to without any command. The same for global, window, tab, buffer and Vim ! variables, because they are not really declared. They can also be deleted with `:unlet`. `:lockvar` does not work on local variables. Use `:const` and `:final` --- 353,359 ---- In Vim9 script `:let` cannot be used. An existing variable is assigned to without any command. The same for global, window, tab, buffer and Vim ! variables, because they are not really declared. Those can also be deleted with `:unlet`. `:lockvar` does not work on local variables. Use `:const` and `:final` *************** *** 597,603 **** Automatic line continuation ~ ! In many cases it is obvious that an expression continues on the next line. In those cases there is no need to prefix the line with a backslash (see |line-continuation|). For example, when a list spans multiple lines: > --- 597,603 ---- Automatic line continuation ~ ! *vim9-line-continuation* In many cases it is obvious that an expression continues on the next line. In those cases there is no need to prefix the line with a backslash (see |line-continuation|). For example, when a list spans multiple lines: > *************** *** 775,781 **** Dictionary literals ~ ! Traditionally Vim has supported dictionary literals with a {} syntax: > let dict = {'key': value} --- 775,781 ---- Dictionary literals ~ ! *vim9-literal-dict* Traditionally Vim has supported dictionary literals with a {} syntax: > let dict = {'key': value} *************** *** 865,871 **** Conditions and expressions ~ ! Conditions and expressions are mostly working like they do in other languages. Some values are different from legacy Vim script: value legacy Vim script Vim9 script ~ --- 865,871 ---- Conditions and expressions ~ ! *vim9-boolean* Conditions and expressions are mostly working like they do in other languages. Some values are different from legacy Vim script: value legacy Vim script Vim9 script ~ *************** *** 917,924 **** 'hello ' .. 123 == 'hello 123' 'hello ' .. v:true == 'hello true' ! Simple types are string, float, special and bool. For other types |string()| ! can be used. *false* *true* *null* In Vim9 script one can use "true" for v:true, "false" for v:false and "null" for v:null. When converting a boolean to a string "false" and "true" are --- 917,924 ---- 'hello ' .. 123 == 'hello 123' 'hello ' .. v:true == 'hello true' ! Simple types are Number, Float, Special and Bool. For other types |string()| ! should be used. *false* *true* *null* In Vim9 script one can use "true" for v:true, "false" for v:false and "null" for v:null. When converting a boolean to a string "false" and "true" are *** ../vim-8.2.3912/runtime/doc/eval.txt 2021-12-19 10:35:10.700109727 +0000 --- runtime/doc/eval.txt 2021-12-27 15:37:14.363004384 +0000 *************** *** 55,61 **** {only when compiled with the |+float| feature} Examples: 123.456 1.15e-6 -1.1e3 - *E928* String A NUL terminated string of 8-bit unsigned characters (bytes). |expr-string| Examples: "ab\txx\"--" 'x-z''a,c' --- 55,60 ---- *************** *** 98,105 **** Vim9 script. It is done by converting the first digits to a number. Hexadecimal "0xf9", Octal "017" or "0o17", and Binary "0b10" numbers are recognized ! NOTE: when using |scriptversion-4| octal with a leading "0" is not recognized. ! The 0o notation requires patch 8.2.0886. If the String doesn't start with digits, the result is zero. Examples: String "456" --> Number 456 ~ --- 97,104 ---- Vim9 script. It is done by converting the first digits to a number. Hexadecimal "0xf9", Octal "017" or "0o17", and Binary "0b10" numbers are recognized ! NOTE: when using |Vim9| script or |scriptversion-4| octal with a leading "0" ! is not recognized. The 0o notation requires patch 8.2.0886. If the String doesn't start with digits, the result is zero. Examples: String "456" --> Number 456 ~ *************** *** 121,127 **** *TRUE* *FALSE* *Boolean* For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE. ! You can also use |v:false| and |v:true|. In Vim9 script |false| and |true|. When TRUE is returned from a function it is the Number one, FALSE is the number zero. --- 120,126 ---- *TRUE* *FALSE* *Boolean* For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE. ! You can also use |v:false| and |v:true|, in Vim9 script |false| and |true|. When TRUE is returned from a function it is the Number one, FALSE is the number zero. *************** *** 524,535 **** entry. Note that the String '04' and the Number 04 are different, since the Number will be converted to the String '4'. The empty string can also be used as a key. *literal-Dict* *#{}* ! To avoid having to put quotes around every key the #{} form can be used. This ! does require the key to consist only of ASCII letters, digits, '-' and '_'. ! Example: > :let mydict = #{zero: 0, one_key: 1, two-key: 2, 333: 3} Note that 333 here is the string "333". Empty keys are not possible with #{}. A value can be any expression. Using a Dictionary for a value creates a nested Dictionary: > --- 523,538 ---- entry. Note that the String '04' and the Number 04 are different, since the Number will be converted to the String '4'. The empty string can also be used as a key. + + In |Vim9| script literaly keys can be used if the key consists of alphanumeric + characters, underscore and dash, see |vim9-literal-dict|. *literal-Dict* *#{}* ! To avoid having to put quotes around every key the #{} form can be used in ! legacy script. This does require the key to consist only of ASCII letters, ! digits, '-' and '_'. Example: > :let mydict = #{zero: 0, one_key: 1, two-key: 2, 333: 3} Note that 333 here is the string "333". Empty keys are not possible with #{}. + In |Vim9| script the #{} form cannot be used. A value can be any expression. Using a Dictionary for a value creates a nested Dictionary: > *************** *** 659,665 **** If you get an error for a numbered function, you can find out what it is with a trick. Assuming the function is 42, the command is: > ! :function {42} Functions for Dictionaries ~ --- 662,668 ---- If you get an error for a numbered function, you can find out what it is with a trick. Assuming the function is 42, the command is: > ! :function g:42 Functions for Dictionaries ~ *************** *** 826,832 **** MY_VAR_6 viminfo file ! It's possible to form a variable name with curly braces, see |curly-braces-names|. ============================================================================== --- 829,835 ---- MY_VAR_6 viminfo file ! In legacy script it is possible to form a variable name with curly braces, see |curly-braces-names|. ============================================================================== *************** *** 874,896 **** expr7 % expr7 ... number modulo |expr7| expr8 ! ! expr7 logical NOT ! - expr7 unary minus ! + expr7 unary plus |expr8| expr9 ! expr8[expr1] byte of a String or item of a |List| ! expr8[expr1 : expr1] substring of a String or sublist of a |List| ! expr8.name entry in a |Dictionary| ! expr8(expr1, ...) function call with |Funcref| variable ! expr8->name(expr1, ...) |method| call ! |expr9| number number constant "string" string constant, backslash is special 'string' string constant, ' is doubled [expr1, ...] |List| {expr1: expr1, ...} |Dictionary| ! #{key: expr1, ...} |Dictionary| &option option value (expr1) nested expression variable internal variable --- 877,902 ---- expr7 % expr7 ... number modulo |expr7| expr8 ! expr8 type check and conversion (|Vim9| only) |expr8| expr9 ! ! expr8 logical NOT ! - expr8 unary minus ! + expr8 unary plus ! ! |expr9| expr10 ! expr9[expr1] byte of a String or item of a |List| ! expr9[expr1 : expr1] substring of a String or sublist of a |List| ! expr9.name entry in a |Dictionary| ! expr9(expr1, ...) function call with |Funcref| variable ! expr9->name(expr1, ...) |method| call ! |expr10| number number constant "string" string constant, backslash is special 'string' string constant, ' is doubled [expr1, ...] |List| {expr1: expr1, ...} |Dictionary| ! #{key: expr1, ...} legacy |Dictionary| &option option value (expr1) nested expression variable internal variable *************** *** 899,905 **** @r contents of register 'r' function(expr1, ...) function call func{ti}on(expr1, ...) function call with curly braces ! {args -> expr1} lambda expression "..." indicates that the operations in this level can be concatenated. --- 905,912 ---- @r contents of register 'r' function(expr1, ...) function call func{ti}on(expr1, ...) function call with curly braces ! {args -> expr1} legacy lambda expression ! (args) => expr1 Vim9 lambda expression "..." indicates that the operations in this level can be concatenated. *************** *** 917,925 **** Trinary 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 ':', ! otherwise the result is the value of the expression after the ':'. Example: > :echo lnum == 1 ? "top" : lnum --- 924,937 ---- Trinary operator ~ ! In legacy script 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 ':', otherwise the result is the value of the expression after the ! ':'. ! ! In |Vim9| script the first expression must evaluate to a boolean, see ! |vim9-boolean|. ! Example: > :echo lnum == 1 ? "top" : lnum *************** *** 953,959 **** These are similar, but not equal: > expr2 ?? expr1 expr2 ? expr2 : expr1 ! In the second line "expr2" is evaluated twice. expr2 and expr3 *expr2* *expr3* --- 965,972 ---- These are similar, but not equal: > expr2 ?? expr1 expr2 ? expr2 : expr1 ! In the second line "expr2" is evaluated twice. And in |Vim9| script the type ! of expr2 before "?" must be a boolean. expr2 and expr3 *expr2* *expr3* *************** *** 962,970 **** expr3 || expr3 .. logical OR *expr-barbar* expr4 && expr4 .. logical AND *expr-&&* ! The "||" and "&&" operators take one argument on each side. The arguments ! are (converted to) Numbers. The result is: input output ~ n1 n2 n1 || n2 n1 && n2 ~ |FALSE| |FALSE| |FALSE| |FALSE| --- 975,988 ---- expr3 || expr3 .. logical OR *expr-barbar* expr4 && expr4 .. logical AND *expr-&&* ! The "||" and "&&" operators take one argument on each side. + In legacy script the arguments are (converted to) Numbers. + + In |Vim9| script the values must be boolean, see |vim9-boolean|. Use "!!" to + convert any type to a boolean. + + The result is: input output ~ n1 n2 n1 || n2 n1 && n2 ~ |FALSE| |FALSE| |FALSE| |FALSE| *************** *** 1000,1007 **** expr5 {cmp} expr5 ! Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1 ! if it evaluates to true. *expr-==* *expr-!=* *expr->* *expr->=* *expr-<* *expr-<=* *expr-=~* *expr-!~* --- 1018,1026 ---- expr5 {cmp} expr5 ! Compare two expr5 expressions. In legacy script the result is a 0 if it ! evaluates to false, or 1 if it evaluates to true. In |Vim9| script the result ! is |true| or |false|. *expr-==* *expr-!=* *expr->* *expr->=* *expr-<* *expr-<=* *expr-=~* *expr-!~* *************** *** 1027,1032 **** --- 1046,1052 ---- "abc" ==# "Abc" evaluates to 0 "abc" ==? "Abc" evaluates to 1 "abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise + NOTE: In |Vim9| script 'ignorecase' is not used. *E691* *E692* A |List| can only be compared with a |List| and only "equal", "not equal", *************** *** 1065,1072 **** 0 "is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case. ! When comparing a String with a Number, the String is converted to a Number, ! and the comparison is done on Numbers. This means that: > echo 0 == 'x' 1 because 'x' converted to a Number is zero. However: > --- 1085,1093 ---- 0 "is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case. ! In legacy script, when comparing a String with a Number, the String is ! converted to a Number, and the comparison is done on Numbers. This means ! that: > echo 0 == 'x' 1 because 'x' converted to a Number is zero. However: > *************** *** 1074,1079 **** --- 1095,1102 ---- 0 Inside a List or Dictionary this conversion is not used. + In |Vim9| script the types must match. + When comparing two Strings, this is done with strcmp() or stricmp(). This results in the mathematical difference (comparing byte values), not necessarily the alphabetical difference in the local language. *************** *** 1111,1139 **** For String concatenation ".." is preferred, since "." is ambiguous, it is also used for |Dict| member access and floating point numbers. ! When |vimscript-version| is 2 or higher, using "." is not allowed. expr7 * expr7 Number multiplication *expr-star* expr7 / expr7 Number division *expr-/* expr7 % expr7 Number modulo *expr-%* ! For all, except "." and "..", Strings are converted to Numbers. For bitwise operators see |and()|, |or()| and |xor()|. ! Note the difference between "+" and ".": "123" + "456" = 579 ! "123" . "456" = "123456" ! Since '.' has the same precedence as '+' and '-', you need to read: > ! 1 . 90 + 90.0 As: > ! (1 . 90) + 90.0 ! That works, since the String "190" is automatically converted to the Number ! 190, which can be added to the Float 90.0. However: > ! 1 . 90 * 90.0 Should be read as: > ! 1 . (90 * 90.0) ! 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: --- 1134,1169 ---- For String concatenation ".." is preferred, since "." is ambiguous, it is also used for |Dict| member access and floating point numbers. ! In |Vim9| script and when |vimscript-version| is 2 or higher, using "." is not ! allowed. ! ! In |Vim9| script the arguments of ".." are converted to String for simple ! types: Number, Float, Special and Bool. For other types |string()| should be ! used. expr7 * expr7 Number multiplication *expr-star* expr7 / expr7 Number division *expr-/* expr7 % expr7 Number modulo *expr-%* ! In legacy script, for all operators except "." and "..", Strings are converted ! to Numbers. ! For bitwise operators see |and()|, |or()| and |xor()|. ! Note the difference between "+" and ".." in legacy script: "123" + "456" = 579 ! "123" .. "456" = "123456" ! Since '..' has the same precedence as '+' and '-', you need to read: > ! 1 .. 90 + 90.0 As: > ! (1 .. 90) + 90.0 ! That works in legacy script, since the String "190" is automatically converted ! to the Number 190, which can be added to the Float 90.0. However: > ! 1 .. 90 * 90.0 Should be read as: > ! 1 .. (90 * 90.0) ! 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: *************** *** 1151,1170 **** None of these work for |Funcref|s. ! . and % do not work for Float. *E804* expr7 *expr7* ----- ! ! expr7 logical NOT *expr-!* ! - expr7 unary minus *expr-unary--* ! + expr7 unary plus *expr-unary-+* For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one). For '-' the sign of the number is changed. For '+' the number is unchanged. Note: "++" has no effect. ! A String will be converted to a Number first. These three can be repeated and mixed. Examples: !-1 == 0 --- 1181,1215 ---- None of these work for |Funcref|s. ! ".", ".." and "%" do not work for Float. *E804* expr7 *expr7* ----- ! expr8 ! ! This is only available in |Vim9| script, see |type-casting|. ! ! ! expr8 *expr8* ! ----- ! ! expr8 logical NOT *expr-!* ! - expr8 unary minus *expr-unary--* ! + expr8 unary plus *expr-unary-+* For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one). For '-' the sign of the number is changed. For '+' the number is unchanged. Note: "++" has no effect. ! In legacy script a String will be converted to a Number first. Note that if ! the string does not start with a digit you likely don't get what you expect. ! ! In |Vim9| script an error is given when "-" or "+" is used and the type is not ! a number. ! ! In |Vim9| script "!" can be used for any type and the result is always a ! boolean. Use "!!" to convert any type to a boolean, according to whether the ! value is |falsy|. These three can be repeated and mixed. Examples: !-1 == 0 *************** *** 1172,1201 **** --9 == 9 ! expr8 *expr8* ----- ! This expression is either |expr9| or a sequence of the alternatives below, in any order. E.g., these are all possible: ! expr8[expr1].name ! expr8.name[expr1] ! expr8(expr1, ...)[expr1].name ! expr8->(expr1, ...)[expr1] Evaluation is always from left to right. ! expr8[expr1] item of String or |List| *expr-[]* *E111* *E909* *subscript* In legacy Vim script: ! If expr8 is a Number or String this results in a String that contains the ! expr1'th single byte from expr8. expr8 is used as a String (a number is automatically converted to a String), expr1 as a Number. This doesn't recognize multibyte encodings, see `byteidx()` for an alternative, or use `split()` to turn the string into a list of characters. Example, to get the byte under the cursor: > :let c = getline(".")[col(".") - 1] ! In Vim9 script: ! If expr8 is a String this results in a String that contains the expr1'th ! single character (including any composing characters) from expr8. To use byte indexes use |strpart()|. Index zero gives the first byte or character. Careful: text column numbers --- 1217,1246 ---- --9 == 9 ! expr9 *expr9* ----- ! This expression is either |expr10| or a sequence of the alternatives below, in any order. E.g., these are all possible: ! expr9[expr1].name ! expr9.name[expr1] ! expr9(expr1, ...)[expr1].name ! expr9->(expr1, ...)[expr1] Evaluation is always from left to right. ! expr9[expr1] item of String or |List| *expr-[]* *E111* *E909* *subscript* In legacy Vim script: ! If expr9 is a Number or String this results in a String that contains the ! expr1'th single byte from expr9. expr9 is used as a String (a number is automatically converted to a String), expr1 as a Number. This doesn't recognize multibyte encodings, see `byteidx()` for an alternative, or use `split()` to turn the string into a list of characters. Example, to get the byte under the cursor: > :let c = getline(".")[col(".") - 1] ! In |Vim9| script: ! If expr9 is a String this results in a String that contains the expr1'th ! single character (including any composing characters) from expr9. To use byte indexes use |strpart()|. Index zero gives the first byte or character. Careful: text column numbers *************** *** 1206,1212 **** compatibility). Use [-1:] to get the last byte or character. In Vim9 script a negative index is used like with a list: count from the end. ! If expr8 is a |List| then it results the item at index expr1. See |list-index| for possible index values. If the index is out of range this results in an error. Example: > :let item = mylist[-1] " get last item --- 1251,1257 ---- compatibility). Use [-1:] to get the last byte or character. In Vim9 script a negative index is used like with a list: count from the end. ! If expr9 is a |List| then it results the item at index expr1. See |list-index| for possible index values. If the index is out of range this results in an error. Example: > :let item = mylist[-1] " get last item *************** *** 1216,1229 **** error. ! expr8[expr1a : expr1b] substring or sublist *expr-[:]* ! If expr8 is a String this results in the substring with the bytes or ! characters from expr1a to and including expr1b. expr8 is used as a String, expr1a and expr1b are used as a Number. 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. In Vim9 script the indexes are character indexes and include composing --- 1261,1274 ---- error. ! expr9[expr1a : expr1b] substring or sublist *expr-[:]* ! If expr9 is a String this results in the substring with the bytes or ! characters from expr1a to and including expr1b. expr9 is used as a String, expr1a and expr1b are used as a Number. In legacy Vim script the indexes are byte indexes. This doesn't recognize ! multibyte encodings, see |byteidx()| for computing the indexes. If expr9 is a Number it is first converted to a String. In Vim9 script the indexes are character indexes and include composing *************** *** 1250,1269 **** :let s = s[:-3] " remove last two bytes < *slice* ! If expr8 is a |List| this results in a new |List| with the items indicated by the indexes expr1a and expr1b. This works like with a String, as explained just above. Also see |sublist| below. Examples: > :let l = mylist[:3] " first four items :let l = mylist[4:4] " List with one item :let l = mylist[:] " shallow copy of a List ! If expr8 is a |Blob| this results in a new |Blob| with the bytes in the indexes expr1a and expr1b, inclusive. Examples: > :let b = 0zDEADBEEF :let bs = b[1:2] " 0zADBE :let bs = b[:] " copy of 0zDEADBEEF ! Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an error. Watch out for confusion between a namespace and a variable followed by a colon --- 1295,1314 ---- :let s = s[:-3] " remove last two bytes < *slice* ! If expr9 is a |List| this results in a new |List| with the items indicated by the indexes expr1a and expr1b. This works like with a String, as explained just above. Also see |sublist| below. Examples: > :let l = mylist[:3] " first four items :let l = mylist[4:4] " List with one item :let l = mylist[:] " shallow copy of a List ! If expr9 is a |Blob| this results in a new |Blob| with the bytes in the indexes expr1a and expr1b, inclusive. Examples: > :let b = 0zDEADBEEF :let bs = b[1:2] " 0zADBE :let bs = b[:] " copy of 0zDEADBEEF ! Using expr9[expr1] or expr9[expr1a : expr1b] on a |Funcref| results in an error. Watch out for confusion between a namespace and a variable followed by a colon *************** *** 1272,1282 **** mylist[s:] " uses namespace s:, error! ! expr8.name entry in a |Dictionary| *expr-entry* ! If expr8 is a |Dictionary| and it is followed by a dot, then the following name will be used as a key in the |Dictionary|. This is just like: ! expr8[name]. The name must consist of alphanumeric characters, just like a variable name, but it may start with a number. Curly braces cannot be used. --- 1317,1327 ---- mylist[s:] " uses namespace s:, error! ! expr9.name entry in a |Dictionary| *expr-entry* ! If expr9 is a |Dictionary| and it is followed by a dot, then the following name will be used as a key in the |Dictionary|. This is just like: ! expr9[name]. The name must consist of alphanumeric characters, just like a variable name, but it may start with a number. Curly braces cannot be used. *************** *** 1293,1309 **** always put spaces around the dot for String concatenation. ! expr8(expr1, ...) |Funcref| function call ! When expr8 is a |Funcref| type variable, invoke the function it refers to. ! expr8->name([args]) method call *method* *->* ! expr8->{lambda}([args]) *E276* For methods that are also available as global functions this is the same as: > ! name(expr8 [, args]) ! There can also be methods specifically for the type of "expr8". This allows for chaining, passing the value that one method returns to the next method: > --- 1338,1354 ---- always put spaces around the dot for String concatenation. ! expr9(expr1, ...) |Funcref| function call ! When expr9 is a |Funcref| type variable, invoke the function it refers to. ! expr9->name([args]) method call *method* *->* ! expr9->{lambda}([args]) *E276* For methods that are also available as global functions this is the same as: > ! name(expr9 [, args]) ! There can also be methods specifically for the type of "expr9". This allows for chaining, passing the value that one method returns to the next method: > *************** *** 1312,1318 **** Example of using a lambda: > GetPercentage()->{x -> x * 100}()->printf('%d%%') < ! When using -> the |expr7| operators will be applied first, thus: > -1.234->string() Is equivalent to: > (-1.234)->string() --- 1357,1363 ---- Example of using a lambda: > GetPercentage()->{x -> x * 100}()->printf('%d%%') < ! When using -> the |expr8| operators will be applied first, thus: > -1.234->string() Is equivalent to: > (-1.234)->string() *************** *** 1332,1338 **** (. ! *expr9* number ------ number number constant *expr-number* --- 1377,1383 ---- (. ! *expr10* number ------ number number constant *expr-number* *************** *** 1348,1354 **** [-+]{N}.{M}[eE][-+]{exp} {N} and {M} are numbers. Both {N} and {M} must be present and can only ! contain digits. [-+] means there is an optional plus or minus sign. {exp} is the exponent, power of 10. Only a decimal point is accepted, not a comma. No matter what the current --- 1393,1400 ---- [-+]{N}.{M}[eE][-+]{exp} {N} and {M} are numbers. Both {N} and {M} must be present and can only ! contain digits, except that in |Vim9| script in {N} single quotes between ! digits are ignored. [-+] means there is an optional plus or minus sign. {exp} is the exponent, power of 10. Only a decimal point is accepted, not a comma. No matter what the current *************** *** 1417,1423 **** \U.... same as \u but allows up to 8 hex numbers. \b backspace \e escape ! \f formfeed \n newline \r return \t tab --- 1463,1469 ---- \U.... same as \u but allows up to 8 hex numbers. \b backspace \e escape ! \f formfeed 0x0C \n newline \r return \t tab *************** *** 1426,1432 **** \ Special key named "xxx". e.g. "\" for CTRL-W. This is for use in mappings, the 0x80 byte is escaped. To use the double quote character it must be escaped: "". ! Don't use to get a utf-8 character, use \uxxxx as mentioned above. \<*xxx> Like \ but prepends a modifier instead of including it in the character. E.g. "\" is one character 0x17 while "\<*C-w>" is four --- 1472,1478 ---- \ Special key named "xxx". e.g. "\" for CTRL-W. This is for use in mappings, the 0x80 byte is escaped. To use the double quote character it must be escaped: "". ! Don't use to get a UTF-8 character, use \uxxxx as mentioned above. \<*xxx> Like \ but prepends a modifier instead of including it in the character. E.g. "\" is one character 0x17 while "\<*C-w>" is four *************** *** 1535,1541 **** lambda expression *expr-lambda* *lambda* ----------------- ! {args -> expr1} lambda expression A lambda expression creates a new unnamed function which returns the result of evaluating |expr1|. Lambda expressions differ from |user-functions| in --- 1581,1588 ---- lambda expression *expr-lambda* *lambda* ----------------- ! {args -> expr1} legacy lambda expression ! (args) => expr1 |Vim9| lambda expression A lambda expression creates a new unnamed function which returns the result of evaluating |expr1|. Lambda expressions differ from |user-functions| in *************** *** 1550,1557 **** The arguments are optional. Example: > :let F = {-> 'error function'} ! :echo F() < error function *closure* Lambda expressions can access outer scope variables and arguments. This is often called a closure. Example where "i" and "a:arg" are used in a lambda --- 1597,1608 ---- The arguments are optional. Example: > :let F = {-> 'error function'} ! :echo F('ignored') < error function + + The |Vim9| lambda does not only use a different syntax, it also adds type + checking and can be split over multiple lines, see |vim9-lambda|. + *closure* Lambda expressions can access outer scope variables and arguments. This is often called a closure. Example where "i" and "a:arg" are used in a lambda *************** *** 1585,1592 **** Handler called Handler called ! Note how execute() is used to execute an Ex command. That's ugly though. Lambda expressions have internal names like '42'. If you get an error for a lambda expression, you can find what it is with the following command: > --- 1636,1653 ---- Handler called Handler called ! Note that it is possible to cause memory to be used and not freed if the ! closure is referenced by the context it depends on: > ! function Function() ! let x = 0 ! let F = {-> x} ! endfunction ! The closure uses "x" from the function scope, and "F" in that same scope ! refers to the closure. This cycle results in the memory not being freed. ! Recommendation: don't do this. + Notice how execute() is used to execute an Ex command. That's ugly though. + In Vim9 script you can use a command block, see |inline-function|. Lambda expressions have internal names like '42'. If you get an error for a lambda expression, you can find what it is with the following command: > *************** *** 1597,1623 **** 3. Internal variable *internal-variables* *E461* An internal variable name can be made up of letters, digits and '_'. But it ! cannot start with a digit. It's also possible to use curly braces, see ! |curly-braces-names|. ! An internal variable is created with the ":let" command |:let|. ! An internal variable is explicitly destroyed with the ":unlet" command ! |:unlet|. Using a name that is not an internal variable or refers to a variable that has been destroyed results in an error. *variable-scope* There are several name spaces for variables. Which one is to be used is specified by what is prepended: ! (nothing) In a function: local to a function; otherwise: global |buffer-variable| b: Local to the current buffer. |window-variable| w: Local to the current window. |tabpage-variable| t: Local to the current tab page. |global-variable| g: Global. ! |local-variable| l: Local to a function. |script-variable| s: Local to a |:source|'ed Vim script. ! |function-argument| a: Function argument (only inside a function). |vim-variable| v: Global, predefined by Vim. The scope name by itself can be used as a |Dictionary|. For example, to --- 1658,1688 ---- 3. Internal variable *internal-variables* *E461* An internal variable name can be made up of letters, digits and '_'. But it ! cannot start with a digit. In legacy script it also possible to use curly ! braces, see |curly-braces-names|. ! In legacy script ann internal variable is created with the ":let" command ! |:let|. An internal variable is explicitly destroyed with the ":unlet" ! command |:unlet|. Using a name that is not an internal variable or refers to a variable that has been destroyed results in an error. + In |Vim9| script `:let` is not used and variables work differently, see |:var|. + *variable-scope* There are several name spaces for variables. Which one is to be used is specified by what is prepended: ! (nothing) In a function: local to the function; ! in a legacy script: global; ! in a |Vim9| script: local to the script |buffer-variable| b: Local to the current buffer. |window-variable| w: Local to the current window. |tabpage-variable| t: Local to the current tab page. |global-variable| g: Global. ! |local-variable| l: Local to a function (only in a legacy function) |script-variable| s: Local to a |:source|'ed Vim script. ! |function-argument| a: Function argument (only in a legacy function). |vim-variable| v: Global, predefined by Vim. The scope name by itself can be used as a |Dictionary|. For example, to *************** *** 1626,1633 **** : unlet s:[k] :endfor ! Note: in Vim9 script this is different, see |vim9-scopes|. ! *buffer-variable* *b:var* *b:* A variable name that is preceded with "b:" is local to the current buffer. Thus you can have several "b:foo" variables, one for each buffer. --- 1691,1698 ---- : unlet s:[k] :endfor ! Note: in Vim9 script variables can also be local to a block of commands, see ! |vim9-scopes|. *buffer-variable* *b:var* *b:* A variable name that is preceded with "b:" is local to the current buffer. Thus you can have several "b:foo" variables, one for each buffer. *************** *** 1969,1974 **** --- 2034,2040 ---- < v:false ~ That is so that eval() can parse the string back to the same value. Read-only. + In |Vim9| script "false" can be used which has a boolean type. *v:fcs_reason* *fcs_reason-variable* v:fcs_reason The reason why the |FileChangedShell| event was triggered. *************** *** 1996,2001 **** --- 2062,2071 ---- The default is empty. If another (invalid) value is used then Vim behaves like it is empty, there is no warning message. + *v:fname* *fname-variable* + v:fname When evaluating 'includeexpr': the file name that was + detected. Empty otherwise. + *v:fname_in* *fname_in-variable* v:fname_in The name of the input file. Valid while evaluating: option used for ~ *************** *** 2128,2133 **** --- 2198,2204 ---- < v:null ~ That is so that eval() can parse the string back to the same value. Read-only. + In |Vim9| script "null" can be used without "v:". *v:numbermax* *numbermax-variable* v:numbermax Maximum value of a number. *************** *** 2350,2356 **** The response from a new xterm is: "[> 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. {only when compiled with |+termresponse| feature} *v:termblinkresp* --- 2421,2429 ---- The response from a new xterm is: "[> 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 higher). Pc is always zero. ! If Pv is 141 or higher then Vim will try to request terminal ! codes. This only works with xterm |xterm-codes|. {only when compiled with |+termresponse| feature} *v:termblinkresp* *************** *** 2410,2415 **** --- 2483,2489 ---- < v:true ~ That is so that eval() can parse the string back to the same value. Read-only. + In |Vim9| script "true" can be used which has a boolean type. *v:val* *val-variable* v:val Value of the current item of a |List| or |Dictionary|. Only valid while evaluating the expression used with |map()| and *************** *** 2551,2561 **** ch_status({handle} [, {options}]) String status of channel {handle} changenr() Number current change number ! char2nr({expr} [, {utf8}]) Number ASCII/UTF8 value of first char in {expr} charclass({string}) Number character class of {string} charcol({expr}) 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 --- 2625,2635 ---- ch_status({handle} [, {options}]) String status of channel {handle} changenr() Number current change number ! char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr} charclass({string}) Number character class of {string} charcol({expr}) 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 *************** *** 2576,2590 **** 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({expr}, {first} [, {last}]) ! Number delete lines from buffer {expr} did_filetype() Number |TRUE| if FileType autocmd 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 --- 2650,2664 ---- 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} did_filetype() Number |TRUE| if FileType autocmd 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 *************** *** 2641,2652 **** 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([{expr}]) List information about buffers ! getbufline({expr}, {lnum} [, {end}]) ! List lines {lnum} to {end} of buffer {expr} ! getbufvar({expr}, {varname} [, {def}]) ! any variable {varname} in buffer {expr} ! getchangelist([{expr}]) 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 --- 2715,2726 ---- 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} ! getbufvar({buf}, {varname} [, {def}]) ! any variable {varname} in buffer {buf} ! 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 *************** *** 2675,2681 **** 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([{expr}]) 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 --- 2749,2755 ---- 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 *************** *** 2809,2815 **** mode([expr]) String current editing mode mzeval({expr}) any evaluate |MzScheme| expression nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} ! nr2char({expr} [, {utf8}]) String single char with ASCII/UTF8 value {expr} or({expr}, {expr}) Number bitwise OR pathshorten({expr} [, {len}]) String shorten directory names in a path perleval({expr}) any evaluate |Perl| expression --- 2883,2889 ---- mode([expr]) String current editing mode mzeval({expr}) any evaluate |MzScheme| expression nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} ! nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr} or({expr}, {expr}) Number bitwise OR pathshorten({expr} [, {len}]) String shorten directory names in a path perleval({expr}) any evaluate |Perl| expression *************** *** 2827,2833 **** popup_getpos({id}) Dict get position of popup window {id} popup_hide({id}) none hide popup menu {id} popup_list() List get a list of window IDs of all popups ! popup_locate({row}, {col}) Number get window ID of popup at position popup_menu({what}, {options}) Number create a popup window used as a menu popup_move({id}, {options}) none set position of popup window {id} popup_notification({what}, {options}) --- 2901,2907 ---- popup_getpos({id}) Dict get position of popup window {id} popup_hide({id}) none hide popup menu {id} popup_list() List get a list of window IDs of all popups ! popup_locate({row}, {col}) Number get window ID of popup at position popup_menu({what}, {options}) Number create a popup window used as a menu popup_move({id}, {options}) none set position of popup window {id} popup_notification({what}, {options}) *************** *** 2928,2935 **** setbufline({expr}, {lnum}, {text}) Number set line {lnum} to {text} in buffer {expr} ! setbufvar({expr}, {varname}, {val}) ! none set {varname} in buffer {expr} 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} --- 3002,3009 ---- setbufline({expr}, {lnum}, {text}) Number set line {lnum} to {text} in buffer {expr} ! setbufvar({buf}, {varname}, {val}) ! none 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} *************** *** 2939,2945 **** 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 --- 3013,3019 ---- 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 *************** *** 2963,2973 **** 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([{expr} [, {dict}]]) List get a list of placed signs ! sign_jump({id}, {group}, {expr}) Number jump to a sign ! sign_place({id}, {group}, {name}, {expr} [, {dict}]) Number place a sign sign_placelist({list}) List place a list of signs sign_undefine([{name}]) Number undefine a sign --- 3037,3047 ---- 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 *************** *** 2997,3005 **** sqrt({expr}) Float square root of {expr} srand([{expr}]) List get seed for |rand()| state([{what}]) String current state of Vim ! str2float({expr}) Float convert String to Float str2list({expr} [, {utf8}]) List convert each character of {expr} to ! ASCII/UTF8 value str2nr({expr} [, {base} [, {quoted}]]) Number convert String to Number strcharlen({expr}) Number character length of the String {expr} --- 3071,3079 ---- sqrt({expr}) Float square root of {expr} srand([{expr}]) List get seed for |rand()| state([{what}]) String current state of Vim ! 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} *************** *** 3028,3034 **** substitute({expr}, {pat}, {sub}, {flags}) String all {pat} in {expr} replaced with {sub} swapinfo({fname}) Dict information about swap file {fname} ! swapname({expr}) String swap file of buffer {expr} synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col} synIDattr({synID}, {what} [, {mode}]) String attribute {what} of syntax ID {synID} --- 3102,3108 ---- 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} *************** *** 3222,3227 **** --- 3296,3302 ---- the current buffer. Any type of item is accepted and converted to a String. {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") *************** *** 3232,3244 **** mylist->append(lnum) ! appendbufline({expr}, {lnum}, {text}) *appendbufline()* ! Like |append()| but append the text in buffer {expr}. This function works only for loaded buffers. First call |bufload()| if needed. ! For the use of {expr}, see |bufname()|. {lnum} is used like with |append()|. Note that using |line()| would use the current buffer, not the one appending to. --- 3307,3319 ---- mylist->append(lnum) ! appendbufline({buf}, {lnum}, {text}) *appendbufline()* ! Like |append()| but append the text in buffer {buf}. This function works only for loaded buffers. First call |bufload()| if needed. ! For the use of {buf}, see |bufname()|. {lnum} is used like with |append()|. Note that using |line()| would use the current buffer, not the one appending to. *************** *** 3246,3252 **** On success 0 is returned, on failure 1 is returned. ! If {expr} is not a valid buffer or {lnum} is not valid, an error message is given. Example: > :let failed = appendbufline(13, 0, "# THE START") < --- 3321,3327 ---- 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") < *************** *** 3386,3394 **** |+balloon_eval_term| feature} balloon_split({msg}) *balloon_split()* ! Split {msg} into lines to be displayed in a balloon. The ! splits are made for the current window size and optimize to ! show debugger output. Returns a |List| with the split lines. Can also be used as a |method|: > GetText()->balloon_split()->balloon_show() --- 3461,3469 ---- |+balloon_eval_term| feature} balloon_split({msg}) *balloon_split()* ! Split String {msg} into lines to be displayed in a balloon. ! The splits are made for the current window size and optimize ! to show debugger output. Returns a |List| with the split lines. Can also be used as a |method|: > GetText()->balloon_split()->balloon_show() *************** *** 3433,3439 **** browsing is not possible, an empty string is returned. bufadd({name}) *bufadd()* ! Add a buffer to the buffer list with {name}. If a buffer for file {name} already exists, return that buffer number. Otherwise return the buffer number of the newly created buffer. When {name} is an empty string then a new --- 3508,3514 ---- browsing is not possible, an empty string is returned. bufadd({name}) *bufadd()* ! Add a buffer to the buffer list with String {name}. If a buffer for file {name} already exists, return that buffer number. Otherwise return the buffer number of the newly created buffer. When {name} is an empty string then a new *************** *** 3446,3458 **** < Can also be used as a |method|: > let bufnr = 'somename'->bufadd() ! bufexists({expr}) *bufexists()* The result is a Number, which is |TRUE| if a buffer called ! {expr} exists. ! If the {expr} argument is a number, buffer numbers are used. Number zero is the alternate buffer for the current window. ! If the {expr} argument is a string it must match a buffer name exactly. The name can be: - Relative to the current directory. - A full path. --- 3521,3533 ---- < Can also be used as a |method|: > let bufnr = 'somename'->bufadd() ! 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. Number zero is the alternate buffer for the current window. ! If the {buf} argument is a string it must match a buffer name exactly. The name can be: - Relative to the current directory. - A full path. *************** *** 3473,3513 **** < Obsolete name: buffer_exists(). *buffer_exists()* ! buflisted({expr}) *buflisted()* The result is a Number, which is |TRUE| if a buffer called ! {expr} exists and is listed (has the 'buflisted' option set). ! The {expr} argument is used like with |bufexists()|. Can also be used as a |method|: > let listed = 'somename'->buflisted() ! bufload({expr}) *bufload()* ! Ensure the buffer {expr} 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 there is an existing swap file for the file of the buffer, there will be no dialog, the buffer will be loaded anyway. ! The {expr} argument is used like with |bufexists()|. Can also be used as a |method|: > eval 'somename'->bufload() ! bufloaded({expr}) *bufloaded()* The result is a Number, which is |TRUE| if a buffer called ! {expr} exists and is loaded (shown in a window or hidden). ! The {expr} argument is used like with |bufexists()|. Can also be used as a |method|: > let loaded = 'somename'->bufloaded() ! bufname([{expr}]) *bufname()* ! The result is the name of a buffer, as it is displayed by the ! ":ls" command. ! If {expr} is omitted the current buffer is used. ! If {expr} is a Number, that buffer number's name is given. Number zero is the alternate buffer for the current window. ! If {expr} is a String, it is used as a |file-pattern| to match with the buffer names. This is always done like 'magic' is set and 'cpoptions' is empty. When there is more than one match an empty string is returned. --- 3548,3589 ---- < Obsolete name: buffer_exists(). *buffer_exists()* ! 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()* ! 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 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()* 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()* ! 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]". ! If {buf} is omitted the current buffer is used. ! If {buf} is a Number, that buffer number's name is given. Number zero is the alternate buffer for the current window. ! If {buf} is a String, it is used as a |file-pattern| to match with the buffer names. This is always done like 'magic' is set and 'cpoptions' is empty. When there is more than one match an empty string is returned. *************** *** 3520,3526 **** Listed buffers are found first. If there is a single match with a listed buffer, that one is returned. Next unlisted buffers are searched for. ! If the {expr} 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|: > --- 3596,3602 ---- Listed buffers are found first. If there is a single match 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|: > *************** *** 3536,3544 **** Obsolete name: buffer_name(). *bufnr()* ! bufnr([{expr} [, {create}]]) The result is the number of a buffer, as it is displayed by ! the ":ls" command. For the use of {expr}, see |bufname()| above. If the buffer doesn't exist, -1 is returned. Or, if the --- 3612,3620 ---- Obsolete name: buffer_name(). *bufnr()* ! bufnr([{buf} [, {create}]]) 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 *************** *** 3562,3571 **** *last_buffer_nr()* Obsolete name for bufnr("$"): last_buffer_nr(). ! bufwinid({expr}) *bufwinid()* The result is a Number, which is the |window-ID| of the first ! window associated with buffer {expr}. For the use of {expr}, ! see |bufname()| above. If buffer {expr} doesn't exist or there is no such window, -1 is returned. Example: > echo "A window containing buffer 1 is " . (bufwinid(1)) --- 3638,3647 ---- *last_buffer_nr()* Obsolete name for bufnr("$"): last_buffer_nr(). ! 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: > echo "A window containing buffer 1 is " . (bufwinid(1)) *************** *** 3575,3584 **** Can also be used as a |method|: > FindBuffer()->bufwinid() ! bufwinnr({expr}) *bufwinnr()* Like |bufwinid()| but return the window number instead of the |window-ID|. ! If buffer {expr} doesn't exist or there is no such window, -1 is returned. Example: > echo "A window containing buffer 1 is " . (bufwinnr(1)) --- 3651,3660 ---- Can also be used as a |method|: > FindBuffer()->bufwinid() ! 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: > echo "A window containing buffer 1 is " . (bufwinnr(1)) *************** *** 3604,3610 **** feature} byteidx({expr}, {nr}) *byteidx()* ! Return byte index of the {nr}'th character in the string {expr}. Use zero for the first character, it then returns zero. If there are no multibyte characters the returned value is --- 3680,3686 ---- feature} byteidx({expr}, {nr}) *byteidx()* ! Return byte index of the {nr}'th character in the String {expr}. Use zero for the first character, it then returns zero. If there are no multibyte characters the returned value is *************** *** 3685,3699 **** redo it is the number of the redone change. After undo it is one less than the number of the undone change. ! char2nr({expr} [, {utf8}]) *char2nr()* ! Return number value of the first char in {expr}. Examples: > char2nr(" ") returns 32 char2nr("ABC") returns 65 < When {utf8} is omitted or zero, the current 'encoding' is used. Example for "utf-8": > char2nr("á") returns 225 char2nr("á"[0]) returns 195 ! < With {utf8} set to TRUE, always treat as utf-8 characters. A combining character is a separate character. |nr2char()| does the opposite. To turn a string into a list of character numbers: > --- 3761,3776 ---- redo it is the number of the redone change. After undo it is one less than the number of the undone change. ! char2nr({string} [, {utf8}]) *char2nr()* ! Return number value of the first char in {string}. ! Examples: > char2nr(" ") returns 32 char2nr("ABC") returns 65 < When {utf8} is omitted or zero, the current 'encoding' is used. Example for "utf-8": > char2nr("á") returns 225 char2nr("á"[0]) returns 195 ! < When {utf8} is TRUE, always treat as UTF-8 characters. A combining character is a separate character. |nr2char()| does the opposite. To turn a string into a list of character numbers: > *************** *** 3715,3722 **** other specific Unicode class The class is used in patterns and word motions. ! *charcol()* ! charcol({expr}) Same as |col()| but returns the character index of the column position given with {expr} instead of the byte position. Example: --- 3792,3800 ---- other specific Unicode class The class is used in patterns and word motions. ! ! charcol({expr}) *charcol()* ! Same as |col()| but returns the character index of the column position given with {expr} instead of the byte position. Example: *************** *** 3733,3742 **** 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 zero, then composing characters ! are not counted separately, their byte length is added to the ! preceding base character. ! When {countcc} is set to 1, 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 --- 3811,3820 ---- 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. ! 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 *************** *** 3852,3857 **** --- 3930,3936 ---- match. {matches} must be a |List|. Each |List| item is one match. See |complete-items| for the kind of items that are possible. + "longest" in 'completeopt' is ignored. Note that the after calling this function you need to avoid inserting anything that would cause completion to stop. The match can be selected with CTRL-N and CTRL-P as usual with *************** *** 3893,3900 **** Only to be used by the function specified with the 'completefunc' option. ! *complete_info()* ! complete_info([{what}]) Returns a |Dictionary| with information about Insert mode completion. See |ins-completion|. The items are: --- 3972,3979 ---- Only to be used by the function specified with the 'completefunc' option. ! ! complete_info([{what}]) *complete_info()* Returns a |Dictionary| with information about Insert mode completion. See |ins-completion|. The items are: *************** *** 3908,3914 **** See |complete-items|. selected Selected item index. First index is zero. Index is -1 if no item is selected (showing ! typed text only) inserted Inserted string. [NOT IMPLEMENT YET] *complete_info_mode* --- 3987,3995 ---- See |complete-items|. selected Selected item index. First index is zero. Index is -1 if no item is selected (showing ! typed text only, or the last completion after ! no item is selected when using the or ! keys) inserted Inserted string. [NOT IMPLEMENT YET] *complete_info_mode* *************** *** 3980,3990 **** choice the default one. Use 0 to not set a default. If {default} is omitted, 1 is used. ! The optional {type} argument gives the type of dialog. This ! is only used for the icon of the GTK, Mac, Motif and Win32 ! GUI. It can be one of these values: "Error", "Question", ! "Info", "Warning" or "Generic". Only the first character is ! relevant. When {type} is omitted, "Generic" is used. If the user aborts the dialog by pressing , CTRL-C, or another valid interrupt key, confirm() returns 0. --- 4061,4072 ---- choice the default one. Use 0 to not set a default. If {default} is omitted, 1 is used. ! The optional {type} String argument gives the type of dialog. ! This is only used for the icon of the GTK, Mac, Motif and ! Win32 GUI. It can be one of these values: "Error", ! "Question", "Info", "Warning" or "Generic". Only the first ! character is relevant. When {type} is omitted, "Generic" is ! used. If the user aborts the dialog by pressing , CTRL-C, or another valid interrupt key, confirm() returns 0. *************** *** 4125,4130 **** --- 4207,4213 ---- |setcursorcharpos()|. Does not change the jumplist. + {lnum} is used like with |getline()|. If {lnum} is greater than the number of lines in the buffer, the cursor will be positioned at the last line in the buffer. If {lnum} is zero, the cursor will stay in the current line. *************** *** 4177,4183 **** Can also be used as a |method|: > GetObject()->deepcopy() ! delete({fname} [, {flags}]) *delete()* Without {flags} or with {flags} empty: Deletes the file by the name {fname}. This also works when {fname} is a symbolic link. --- 4260,4266 ---- Can also be used as a |method|: > GetObject()->deepcopy() ! delete({fname} [, {flags}]) *delete()* Without {flags} or with {flags} empty: Deletes the file by the name {fname}. This also works when {fname} is a symbolic link. *************** *** 4202,4220 **** Can also be used as a |method|: > GetName()->delete() ! deletebufline({expr}, {first} [, {last}]) *deletebufline()* ! Delete lines {first} to {last} (inclusive) from buffer {expr}. If {last} is omitted then delete line {first} only. On success 0 is returned, on failure 1 is returned. This function works only for loaded buffers. First call |bufload()| if needed. ! For the use of {expr}, see |bufname()| above. {first} and {last} are used like with |getline()|. Note that when using |line()| this refers to the current buffer. Use "$" ! to refer to the last line in buffer {expr}. Can also be used as a |method|: > GetBuffer()->deletebufline(1) --- 4285,4303 ---- Can also be used as a |method|: > GetName()->delete() ! 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. This function works only for loaded buffers. First call |bufload()| if needed. ! For the use of {buf}, see |bufname()| above. {first} and {last} are used like with |getline()|. Note that 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) *************** *** 4314,4320 **** digraph_set({chars}, {digraph}) *digraph_set()* *E1205* Add digraph {chars} to the list. {chars} must be a string ! with two characters. {digraph} is a string with one utf-8 encoded character. Be careful, composing characters are NOT ignored. This function is similar to |:digraphs| command, but useful to add digraphs start with a white space. --- 4397,4403 ---- digraph_set({chars}, {digraph}) *digraph_set()* *E1205* Add digraph {chars} to the list. {chars} must be a string ! with two characters. {digraph} is a string with one UTF-8 encoded character. Be careful, composing characters are NOT ignored. This function is similar to |:digraphs| command, but useful to add digraphs start with a white space. *************** *** 4359,4368 **** display an error message. ! echoraw({expr}) *echoraw()* ! Output {expr} as-is, including unprintable characters. This ! can be used to output a terminal code. For example, to disable ! modifyOtherKeys: > call echoraw(&t_TE) < and to enable it again: > call echoraw(&t_TI) --- 4442,4451 ---- display an error message. ! echoraw({string}) *echoraw()* ! Output {string} as-is, including unprintable characters. ! This can be used to output a terminal code. For example, to ! disable modifyOtherKeys: > call echoraw(&t_TE) < and to enable it again: > call echoraw(&t_TI) *************** *** 4521,4529 **** varname internal variable (see |internal-variables|). Also works for |curly-braces-names|, |Dictionary| ! 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]") --- 4604,4614 ---- varname internal variable (see |internal-variables|). Also works for |curly-braces-names|, |Dictionary| ! entries, |List| items, etc. ! Does not work for local variables in a ! compiled `:def` function. ! 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]") *************** *** 4601,4606 **** --- 4686,4692 ---- {expr} must be a literal string. *E1232* Can only be used in a |:def| function. *E1233* + This does not work to check for arguments or local variables. exp({expr}) *exp()* *************** *** 4619,4627 **** {only available when compiled with the |+float| feature} ! expand({expr} [, {nosuf} [, {list}]]) *expand()* ! Expand wildcards and the following special keywords in {expr}. ! 'wildignorecase' applies. If {list} is given and it is |TRUE|, a List will be returned. Otherwise the result is a String and when there are several --- 4705,4713 ---- {only available when compiled with the |+float| feature} ! 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. Otherwise the result is a String and when there are several *************** *** 4630,4641 **** file name contains a space] If the expansion fails, the result is an empty string. A name ! for a non-existing file is not included, unless {expr} does not start with '%', '#' or '<', see below. ! When {expr} starts with '%', '#' or '<', the expansion is done ! like for the |cmdline-special| variables with their associated ! modifiers. Here is a short overview: % current file name # alternate file name --- 4716,4727 ---- file name contains a space] If the expansion fails, the result is an empty string. A name ! for a non-existing file is not included, unless {string} does not start with '%', '#' or '<', see below. ! When {string} starts with '%', '#' or '<', the expansion is ! done like for the |cmdline-special| variables with their ! associated modifiers. Here is a short overview: % current file name # alternate file name *************** *** 4686,4692 **** buffer with no name, results in the current directory, with a '/' added. ! When {expr} does not start with '%', '#' or '<', it is expanded like a file name is expanded on the command line. 'suffixes' and 'wildignore' are used, unless the optional {nosuf} argument is given and it is |TRUE|. --- 4772,4778 ---- buffer with no name, results in the current directory, with a '/' added. ! When {string} does not start with '%', '#' or '<', it is expanded like a file name is expanded on the command line. 'suffixes' and 'wildignore' are used, unless the optional {nosuf} argument is given and it is |TRUE|. *************** *** 4710,4720 **** Can also be used as a |method|: > Getpattern()->expand() ! expandcmd({expr}) *expandcmd()* ! Expand special items in {expr} like what is done for an Ex ! command such as `:edit`. This expands special keywords, like ! with |expand()|, and environment variables, anywhere in ! {expr}. "~user" and "~/path" are only expanded at the start. Returns the expanded string. Example: > :echo expandcmd('make %<.o') --- 4796,4807 ---- Can also be used as a |method|: > Getpattern()->expand() ! expandcmd({string}) *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 ! {string}. "~user" and "~/path" are only expanded at the ! start. Returns the expanded string. Example: > :echo expandcmd('make %<.o') *************** *** 4891,4896 **** --- 4978,4986 ---- < If you do not use "val" you can leave it out: > call filter(myList, {idx -> idx % 2 == 1}) < + In |Vim9| script the result must be true, false, zero or one. + Other values will result in a type error. + For a |List| and a |Dictionary| the operation is done in-place. If you want it to remain unmodified make a copy first: > *************** *** 4910,4923 **** Find directory {name} in {path}. Supports both downwards and upwards recursive directory searches. See |file-searching| for the syntax of {path}. Returns the path of the first found match. When the found directory is below the current directory a relative path is returned. Otherwise a full path is returned. If {path} is omitted or empty then 'path' is used. If the optional {count} is given, find {count}'s occurrence of {name} in {path} instead of the first one. When {count} is negative return all the matches in a |List|. ! This is quite similar to the ex-command |:find|. {only available when compiled with the |+file_in_path| feature} --- 5000,5016 ---- Find directory {name} in {path}. Supports both downwards and upwards recursive directory searches. See |file-searching| for the syntax of {path}. + Returns the path of the first found match. When the found directory is below the current directory a relative path is returned. Otherwise a full path is returned. If {path} is omitted or empty then 'path' is used. + If the optional {count} is given, find {count}'s occurrence of {name} in {path} instead of the first one. When {count} is negative return all the matches in a |List|. ! ! This is quite similar to the ex-command `:find`. {only available when compiled with the |+file_in_path| feature} *************** *** 5065,5070 **** --- 5158,5165 ---- 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() *************** *** 5073,5078 **** --- 5168,5175 ---- 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() *************** *** 5086,5091 **** --- 5183,5190 ---- returned for lines where folds are still to be updated and the foldlevel is unknown. As a special case the level of the previous line is usually available. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. Can also be used as a |method|: > GetLnum()->foldlevel() *************** *** 5134,5143 **** Get the full command name from a short abbreviated command name; see |20.2| for details on command abbreviations. ! {name} may start with a `:` and can include a [range], these ! are skipped and not returned. Returns an empty string if a command doesn't exist or if it's ! ambiguous (for user-defined functions). For example `fullcommand('s')`, `fullcommand('sub')`, `fullcommand(':%substitute')` all return "substitute". --- 5233,5242 ---- Get the full command name from a short abbreviated command name; see |20.2| for details on command abbreviations. ! The string argument {name} may start with a `:` and can ! include a [range], these are skipped and not returned. Returns an empty string if a command doesn't exist or if it's ! ambiguous (for user-defined commands). For example `fullcommand('s')`, `fullcommand('sub')`, `fullcommand(':%substitute')` all return "substitute". *************** *** 5158,5164 **** Can also be used as a |method|: > GetFuncname()->funcref([arg]) < ! *function()* *E700* *E922* *E923* function({name} [, {arglist}] [, {dict}]) Return a |Funcref| variable that refers to function {name}. {name} can be the name of a user defined function or an --- 5257,5263 ---- Can also be used as a |method|: > GetFuncname()->funcref([arg]) < ! *function()* *partial* *E700* *E922* *E923* function({name} [, {arglist}] [, {dict}]) Return a |Funcref| variable that refers to function {name}. {name} can be the name of a user defined function or an *************** *** 5291,5297 **** myfunc->get(what) < *getbufinfo()* ! getbufinfo([{expr}]) getbufinfo([{dict}]) Get information about buffers as a List of Dictionaries. --- 5390,5396 ---- myfunc->get(what) < *getbufinfo()* ! getbufinfo([{buf}]) getbufinfo([{dict}]) Get information about buffers as a List of Dictionaries. *************** *** 5305,5312 **** bufloaded include only loaded buffers. bufmodified include only modified buffers. ! Otherwise, {expr} specifies a particular buffer to return ! information for. For the use of {expr}, see |bufname()| above. If the buffer is found the returned List has one item. Otherwise the result is an empty list. --- 5404,5411 ---- bufloaded include only loaded buffers. bufmodified include only modified buffers. ! Otherwise, {buf} specifies a particular buffer to return ! information for. For the use of {buf}, see |bufname()| above. If the buffer is found the returned List has one item. Otherwise the result is an empty list. *************** *** 5323,5328 **** --- 5422,5434 ---- listed TRUE if the buffer is listed. lnum Line number used for the buffer when opened in the current window. + Only valid if the buffer has been + 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}) + < linecount Number of lines in the buffer (only valid when loaded) loaded TRUE if the buffer is loaded. *************** *** 5358,5369 **** < *getbufline()* ! getbufline({expr}, {lnum} [, {end}]) Return a |List| with the lines starting from {lnum} to {end} ! (inclusive) in the buffer {expr}. If {end} is omitted, a |List| with only the line {lnum} is returned. ! For the use of {expr}, see |bufname()| above. For {lnum} and {end} "$" can be used for the last line of the buffer. Otherwise a number must be used. --- 5464,5475 ---- < *getbufline()* ! getbufline({buf}, {lnum} [, {end}]) 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. ! For the use of {buf}, see |bufname()| above. For {lnum} and {end} "$" can be used for the last line of the buffer. Otherwise a number must be used. *************** *** 5385,5394 **** < Can also be used as a |method|: > GetBufnr()->getbufline(lnum) ! getbufvar({expr}, {varname} [, {def}]) *getbufvar()* The result is the value of option or local buffer variable ! {varname} in buffer {expr}. Note that the name without "b:" must be used. When {varname} is empty returns a |Dictionary| with all the buffer-local variables. When {varname} is equal to "&" returns a |Dictionary| with all --- 5491,5501 ---- < Can also be used as a |method|: > GetBufnr()->getbufline(lnum) ! getbufvar({buf}, {varname} [, {def}]) *getbufvar()* The result is the value of option or local buffer variable ! {varname} in buffer {buf}. Note that the name without "b:" must be used. + The {varname} argument is a string. When {varname} is empty returns a |Dictionary| with all the buffer-local variables. When {varname} is equal to "&" returns a |Dictionary| with all *************** *** 5398,5404 **** This also works for a global or buffer-local option, but it doesn't work for a global variable, window-local variable or window-local option. ! For the use of {expr}, see |bufname()| above. When the buffer or variable doesn't exist {def} or an empty string is returned, there is no error message. Examples: > --- 5505,5511 ---- This also works for a global or buffer-local option, but it doesn't work for a global variable, window-local variable or window-local option. ! 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: > *************** *** 5408,5416 **** < Can also be used as a |method|: > GetBufnr()->getbufvar(varname) < ! getchangelist([{expr}]) *getchangelist()* ! Returns the |changelist| for the buffer {expr}. For the use ! of {expr}, see |bufname()| above. If buffer {expr} doesn't exist, an empty list is returned. The returned list contains two entries: a list with the change --- 5515,5523 ---- < Can also be used as a |method|: > GetBufnr()->getbufvar(varname) < ! 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. The returned list contains two entries: a list with the change *************** *** 5420,5426 **** col column number coladd column offset for 'virtualedit' lnum line number ! If buffer {expr} is the current buffer, then the current position refers to the position in the list. For other buffers, it is set to the length of the list. --- 5527,5533 ---- col column number coladd column offset for 'virtualedit' lnum line number ! If buffer {buf} is the current buffer, then the current position refers to the position in the list. For other buffers, it is set to the length of the list. *************** *** 5525,5533 **** *getcharpos()* getcharpos({expr}) ! Get the position for {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, such as 2147483647, then getcharpos() will return the character index of the last character. --- 5632,5640 ---- *getcharpos()* getcharpos({expr}) ! 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, such as 2147483647, then getcharpos() will return the character index of the last character. *************** *** 5613,5628 **** when not in the command-line window. getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* ! Return a list of command-line completion matches. {type} ! specifies what for. The following completion types are ! supported: arglist file names in argument list augroup autocmd groups buffer buffer names behave :behave suboptions color color schemes ! command Ex command (and arguments) cmdline |cmdline-completion| result compiler compilers cscope |:cscope| suboptions --- 5720,5735 ---- when not in the command-line window. 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: arglist file names in argument list augroup autocmd groups buffer buffer names behave :behave suboptions color color schemes ! command Ex command cmdline |cmdline-completion| result compiler compilers cscope |:cscope| suboptions *************** *** 5700,5707 **** Can also be used as a |method|: > GetWinid()->getcurpos() ! ! < *getcursorcharpos()* getcursorcharpos([{winid}]) Same as |getcurpos()| but the column number in the returned List is a character index instead of a byte index. --- 5807,5814 ---- Can also be used as a |method|: > GetWinid()->getcurpos() ! < ! *getcursorcharpos()* getcursorcharpos([{winid}]) Same as |getcurpos()| but the column number in the returned List is a character index instead of a byte index. *************** *** 5752,5759 **** GetWinnr()->getcwd() getenv({name}) *getenv()* ! Return the value of environment variable {name}. ! When the variable does not exist |v:null| is returned. That is different from a variable set to an empty string, although some systems interpret the empty value as the variable being deleted. See also |expr-env|. --- 5859,5869 ---- GetWinnr()->getcwd() getenv({name}) *getenv()* ! Return the value of environment variable {name}. The {name} ! argument is a string, without a leading '$'. Example: > ! myHome = getenv('HOME') ! ! < When the variable does not exist |v:null| is returned. That is different from a variable set to an empty string, although some systems interpret the empty value as the variable being deleted. See also |expr-env|. *************** *** 5765,5772 **** Without an argument returns the name of the normal font being used. Like what is used for the Normal highlight group |hl-Normal|. ! With an argument a check is done whether {name} is a valid ! font name. If not then an empty string is returned. Otherwise the actual font name is returned, or {name} if the GUI does not support obtaining the real name. Only works when the GUI is running, thus not in your vimrc or --- 5875,5882 ---- Without an argument returns the name of the normal font being used. Like what is used for the Normal highlight group |hl-Normal|. ! With an argument a check is done whether String {name} is a ! valid font name. If not then an empty string is returned. Otherwise the actual font name is returned, or {name} if the GUI does not support obtaining the real name. Only works when the GUI is running, thus not in your vimrc or *************** *** 5876,5883 **** digit, |line()| is called to translate the String into a Number. To get the line under the cursor: > getline(".") ! < When {lnum} is smaller than 1 or bigger than the number of ! lines in the buffer, an empty string is returned. When {end} is given the result is a |List| where each item is a line from the current buffer in the range {lnum} to {end}, --- 5986,5993 ---- digit, |line()| is called to translate the String into a Number. To get the line under the cursor: > getline(".") ! < When {lnum} is a number smaller than 1 or bigger than the ! number of lines in the buffer, an empty string is returned. When {end} is given the result is a |List| where each item is a line from the current buffer in the range {lnum} to {end}, *************** *** 5927,5946 **** :echo getloclist(5, {'filewinid': 0}) ! getmarklist([{expr}]) *getmarklist()* ! Without the {expr} argument returns a |List| with information about all the global marks. |mark| ! If the optional {expr} argument is specified, returns the ! local marks defined in buffer {expr}. For the use of {expr}, see |bufname()|. Each item in the returned List is a |Dict| with the following: ! name - name of the mark prefixed by "'" ! pos - a |List| with the position of the mark: [bufnum, lnum, col, off] ! Refer to |getpos()| for more information. ! file - file name Refer to |getpos()| for getting information about a specific mark. --- 6037,6056 ---- :echo getloclist(5, {'filewinid': 0}) ! getmarklist([{buf}]) *getmarklist()* ! Without the {buf} argument returns a |List| with information about all the global marks. |mark| ! If the optional {buf} argument is specified, returns the ! local marks defined in buffer {buf}. For the use of {buf}, see |bufname()|. Each item in the returned List is a |Dict| with the following: ! mark name of the mark prefixed by "'" ! pos a |List| with the position of the mark: [bufnum, lnum, col, off] ! Refer to |getpos()| for more information. ! file file name Refer to |getpos()| for getting information about a specific mark. *************** *** 5954,5959 **** --- 6064,6071 ---- |getmatches()| is useful in combination with |setmatches()|, as |setmatches()| can restore a list of matches saved by |getmatches()|. + If {win} is specified, use the window with this number or + window ID instead of the current window. Example: > :echo getmatches() < [{'group': 'MyGroup1', 'pattern': 'TODO', *************** *** 5991,6001 **** are zero. When the position is after the text then "column" is the ! length of the text in bytes. If the mouse is over a popup window then that window is used. - When using |getchar()| the Vim variables |v:mouse_lnum|, |v:mouse_col| and |v:mouse_winid| also provide these values. --- 6103,6112 ---- are zero. When the position is after the text then "column" is the ! length of the text in bytes plus one. If the mouse is over a popup window then that window is used. When using |getchar()| the Vim variables |v:mouse_lnum|, |v:mouse_col| and |v:mouse_winid| also provide these values. *************** *** 6005,6012 **** exits. *getpos()* ! getpos({expr}) Get the position for {expr}. For possible values of {expr} ! see |line()|. For getting the cursor position see |getcurpos()|. The result is a |List| with four numbers: [bufnum, lnum, col, off] --- 6116,6123 ---- exits. *getpos()* ! getpos({expr}) 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: [bufnum, lnum, col, off] *************** *** 6023,6029 **** '> is a large number. The column number in the returned List is the byte position within the line. To get the character position in the line, ! use |getcharpos()| This can be used to save and restore the position of a mark: > let save_a_mark = getpos("'a") ... --- 6134,6142 ---- '> is a large number. 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". This can be used to save and restore the position of a mark: > let save_a_mark = getpos("'a") ... *************** *** 6053,6060 **** valid |TRUE|: recognized error message When there is no error list or it's empty, an empty list is ! returned. Quickfix list entries with non-existing buffer ! number are returned with "bufnr" set to zero. Useful application: Find pattern matches in multiple files and do something with them: > --- 6166,6175 ---- valid |TRUE|: recognized error message When there is no error list or it's empty, an empty list is ! returned. Quickfix list entries with a non-existing buffer ! number are returned with "bufnr" set to zero (Note: some ! functions accept buffer number zero for the alternate buffer, ! you may need to explicitly check for zero). Useful application: Find pattern matches in multiple files and do something with them: > *************** *** 6135,6141 **** The result is a String, which is the contents of register {regname}. Example: > :let cliptext = getreg('*') ! < When {regname} was not set the result is an empty string. getreg('=') returns the last evaluated value of the expression register. (For use in maps.) --- 6250,6258 ---- The result is a String, which is the contents of register {regname}. Example: > :let cliptext = getreg('*') ! < When register {regname} was not set the result is an empty ! string. ! The {regname} argument must be a string. getreg('=') returns the last evaluated value of the expression register. (For use in maps.) *************** *** 6150,6155 **** --- 6267,6273 ---- (see |NL-used-for-Nul|). When the register was not set an empty list is returned. + If {regname} is "", the unnamed register '"' is used. If {regname} is not specified, |v:register| is used. In |Vim9-script| {regname} must be one character. *************** *** 6175,6182 **** which is the register that got the deleted text. ! If {regname} is invalid or not set, an empty Dictionary ! will be returned. If {regname} is not specified, |v:register| is used. The returned Dictionary can be passed to |setreg()|. In |Vim9-script| {regname} must be one character. --- 6293,6301 ---- which is the register that got the deleted text. ! The {regname} argument is a string. If {regname} is invalid ! or not set, an empty Dictionary will be returned. ! If {regname} is "" or "@", the unnamed register '"' is used. If {regname} is not specified, |v:register| is used. The returned Dictionary can be passed to |setreg()|. In |Vim9-script| {regname} must be one character. *************** *** 6192,6209 **** "{width}" for |blockwise-visual| text "" for an empty or unknown register is one character with value 0x16. ! If {regname} is not specified, |v:register| is used. In |Vim9-script| {regname} must be one character. Can also be used as a |method|: > GetRegname()->getregtype() ! gettabinfo([{arg}]) *gettabinfo()* ! If {arg} is not specified, then information about all the tab ! pages is returned as a |List|. Each List item is a |Dictionary|. ! Otherwise, {arg} specifies the tab page number and information ! about that one is returned. If the tab page does not exist an ! empty List is returned. Each List item is a |Dictionary| with the following entries: tabnr tab page number. --- 6311,6330 ---- "{width}" for |blockwise-visual| text "" for an empty or unknown register is one character with value 0x16. ! The {regname} argument is a string. If {regname} is "", the ! unnamed register '"' is used. If {regname} is not specified, ! |v:register| is used. In |Vim9-script| {regname} must be one character. Can also be used as a |method|: > GetRegname()->getregtype() ! gettabinfo([{tabnr}]) *gettabinfo()* ! If {tabnr} is not specified, then information about all the ! tab pages is returned as a |List|. Each List item is a ! |Dictionary|. Otherwise, {tabnr} specifies the tab page ! number and information about that one is returned. If the tab ! page does not exist an empty List is returned. Each List item is a |Dictionary| with the following entries: tabnr tab page number. *************** *** 6218,6225 **** Get the value of a tab-local variable {varname} in tab page {tabnr}. |t:var| Tabs are numbered starting with one. ! When {varname} is empty a dictionary with all tab-local ! variables is returned. Note that the name without "t:" must be used. When the tab or variable doesn't exist {def} or an empty string is returned, there is no error message. --- 6339,6346 ---- Get the value of a tab-local variable {varname} in tab page {tabnr}. |t:var| Tabs are numbered starting with one. ! The {varname} argument is a string. When {varname} is empty a ! dictionary with all tab-local variables is returned. Note that the name without "t:" must be used. When the tab or variable doesn't exist {def} or an empty string is returned, there is no error message. *************** *** 6230,6237 **** gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* Get the value of window-local variable {varname} in window {winnr} in tab page {tabnr}. ! When {varname} is empty a dictionary with all window-local ! variables is returned. When {varname} is equal to "&" get the values of all window-local options in a |Dictionary|. Otherwise, when {varname} starts with "&" get the value of a --- 6351,6358 ---- 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 ! dictionary with all window-local variables is returned. When {varname} is equal to "&" get the values of all window-local options in a |Dictionary|. Otherwise, when {varname} starts with "&" get the value of a *************** *** 6256,6266 **** < Can also be used as a |method|: > GetTabnr()->gettabwinvar(winnr, varname) ! gettagstack([{nr}]) *gettagstack()* ! The result is a Dict, which is the tag stack of window {nr}. ! {nr} can be the window number or the |window-ID|. ! When {nr} is not specified, the current window is used. ! When window {nr} doesn't exist, an empty Dict is returned. The returned dictionary contains the following entries: curidx Current index in the stack. When at --- 6377,6387 ---- < Can also be used as a |method|: > GetTabnr()->gettabwinvar(winnr, varname) ! gettagstack([{winnr}]) *gettagstack()* ! The result is a Dict, which is the tag stack of window {winnr}. ! {winnr} can be the window number or the |window-ID|. ! When {winnr} is not specified, the current window is used. ! When window {winnr} doesn't exist, an empty Dict is returned. The returned dictionary contains the following entries: curidx Current index in the stack. When at *************** *** 6289,6295 **** gettext({text}) *gettext()* ! Translate {text} if possible. This is mainly for use in the distributed Vim scripts. When generating message translations the {text} is extracted by xgettext, the translator can add the translated message in the --- 6410,6416 ---- 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 xgettext, the translator can add the translated message in the *************** *** 6311,6317 **** tab pages is returned. Each List item is a |Dictionary| with the following entries: ! botline last displayed buffer line bufnr number of buffer in the window height window height (excluding winbar) loclist 1 if showing a location list --- 6432,6438 ---- tab pages is returned. Each List item is a |Dictionary| with the following entries: ! botline last complete displayed buffer line bufnr number of buffer in the window height window height (excluding winbar) loclist 1 if showing a location list *************** *** 6425,6438 **** Can also be used as a |method|: > GetExpr()->glob() ! glob2regpat({expr}) *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. > if filename =~ glob2regpat('Make*.mak') < This is equivalent to: > if filename =~ '^Make.*\.mak$' ! < When {expr} 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. --- 6546,6559 ---- Can also be used as a |method|: > GetExpr()->glob() ! glob2regpat({string}) *glob2regpat()* Convert a file pattern, as used by glob(), into a search pattern. The result can be used to match with a string that is a file name. E.g. > if filename =~ glob2regpat('Make*.mak') < This is equivalent to: > if filename =~ '^Make.*\.mak$' ! < 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. *************** *** 6441,6448 **** GetExpr()->glob2regpat() < *globpath()* globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) ! Perform glob() for {expr} on all directories in {path} and ! concatenate the results. Example: > :echo globpath(&rtp, "syntax/c.vim") < {path} is a comma-separated list of directory names. Each --- 6562,6569 ---- GetExpr()->glob2regpat() < *globpath()* globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) ! Perform glob() for String {expr} on all directories in {path} ! and concatenate the results. Example: > :echo globpath(&rtp, "syntax/c.vim") < {path} is a comma-separated list of directory names. Each *************** *** 6494,6500 **** features that have been abandoned will not be known by the current Vim version. ! Also see |exists()|. Note that to skip code that has a syntax error when the feature is not available, Vim may skip the rest of the line --- 6615,6621 ---- features that have been abandoned will not be known by the current Vim version. ! Also see |exists()| and |exists_compiled()|. Note that to skip code that has a syntax error when the feature is not available, Vim may skip the rest of the line *************** *** 6509,6515 **** 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. Can also be used as a |method|: > mydict->has_key(key) --- 6630,6637 ---- 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) *************** *** 6556,6561 **** --- 6678,6684 ---- that contains {what} in somewhere in the rhs (what it is mapped to) and this mapping exists in one of the modes indicated by {mode}. + The arguments {what} and {mode} are strings. When {abbr} is there and it is |TRUE| use abbreviations instead of mappings. Don't forget to specify Insert and/or Command-line mode. *************** *** 6806,6813 **** which Vim is currently running. Machine names greater than 256 characters long are truncated. ! iconv({expr}, {from}, {to}) *iconv()* ! The result is a String, which is the text {expr} converted from encoding {from} to encoding {to}. When the conversion completely fails an empty string is returned. When some characters could not be converted they --- 6929,6936 ---- which Vim is currently running. Machine names greater than 256 characters long are truncated. ! 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 returned. When some characters could not be converted they *************** *** 7038,7045 **** islocked({expr}) *islocked()* *E786* The result is a Number, which is |TRUE| when {expr} is the name of a locked variable. ! {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 --- 7161,7169 ---- 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 *************** *** 7047,7052 **** --- 7171,7177 ---- < When {expr} is a variable that does not exist you get an error message. Use |exists()| to check for existence. + In Vim9 script it does not work for local variables. Can also be used as a |method|: > GetName()->islocked() *************** *** 7271,7277 **** line({expr} [, {winid}]) *line()* The result is a Number, which is the line number of the file ! position given with {expr}. The accepted positions are: . the cursor position $ the last line in the current buffer 'x position of mark x (if the mark is not set, 0 is --- 7396,7403 ---- line({expr} [, {winid}]) *line()* The result is a Number, which is the line number of the file ! position given with {expr}. The {expr} argument is a string. ! The accepted positions are: . the cursor position $ the last line in the current buffer 'x position of mark x (if the mark is not set, 0 is *************** *** 7311,7319 **** below the last line: > line2byte(line("$") + 1) < This is the buffer size plus one. If 'fileencoding' is empty ! it is the file size plus one. ! When {lnum} is invalid, or the |+byte_offset| feature has been ! disabled at compile time, -1 is returned. Also see |byte2line()|, |go| and |:goto|. Can also be used as a |method|: > --- 7437,7445 ---- below the last line: > 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, or the |+byte_offset| ! feature has been disabled at compile time, -1 is returned. Also see |byte2line()|, |go| and |:goto|. Can also be used as a |method|: > *************** *** 7353,7360 **** < |str2list()| does the opposite. When {utf8} is omitted or zero, the current 'encoding' is used. ! With {utf8} is 1, always return utf-8 characters. ! With utf-8 composing characters work as expected: > list2str([97, 769]) returns "á" < Can also be used as a |method|: > --- 7479,7486 ---- < |str2list()| does the opposite. When {utf8} is omitted or zero, the current 'encoding' is used. ! When {utf8} is TRUE, always return UTF-8 characters. ! With UTF-8 composing characters work as expected: > list2str([97, 769]) returns "á" < Can also be used as a |method|: > *************** *** 7499,7504 **** --- 7625,7632 ---- as-is. Other objects are returned as zero without any errors. See |lua-luaeval| for more details. + Note that in a `:def` function local variables are not visible + to {expr}. Can also be used as a |method|: > GetExpr()->luaeval() *************** *** 7599,7605 **** "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" "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. --- 7727,7733 ---- "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" "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. *************** *** 7753,7758 **** --- 7881,7887 ---- further down in the text. Can also be used as a |method|: > + GetText()->match('word') GetList()->match('word') < *matchadd()* *E798* *E799* *E801* *E957* *************** *** 7822,7828 **** to be used when fast match additions and deletions are required, for example to highlight matching parentheses. ! The list {pos} can contain one of these items: - A number. This whole line will be highlighted. The first line has number 1. - A list with one number, e.g., [23]. The whole line with this --- 7951,7958 ---- to be used when fast match additions and deletions are required, for example to highlight matching parentheses. ! {pos} is a list of positions. Each position can be one of ! these: - A number. This whole line will be highlighted. The first line has number 1. - A list with one number, e.g., [23]. The whole line with this *************** *** 7835,7841 **** - A list with three numbers, e.g., [23, 11, 3]. As above, but the third number gives the length of the highlight in bytes. ! The maximum number of positions is 8. Example: > :highlight MyGroup ctermbg=green guibg=green --- 7965,7971 ---- - A list with three numbers, e.g., [23, 11, 3]. As above, but the third number gives the length of the highlight in bytes. ! The maximum number of positions in {pos} is 8. Example: > :highlight MyGroup ctermbg=green guibg=green *************** *** 7844,7851 **** :call matchdelete(m) < Matches added by |matchaddpos()| are returned by ! |getmatches()| with an entry "pos1", "pos2", etc., with the ! value a list like the {pos} item. Can also be used as a |method|: > GetGroup()->matchaddpos([23, 11]) --- 7974,7980 ---- :call matchdelete(m) < Matches added by |matchaddpos()| are returned by ! |getmatches()|. Can also be used as a |method|: > GetGroup()->matchaddpos([23, 11]) *************** *** 7933,7938 **** --- 8062,8070 ---- empty list is returned. If length of {str} is greater than 256, then returns an empty list. + Refer to |fuzzy-match| for more information about fuzzy + matching strings. + Example: > :echo matchfuzzy(["clay", "crow"], "cay") < results in ["clay"]. > *************** *** 7959,7965 **** 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 ! use |byteidx()|to convert a character position to a byte position. If {str} matches multiple times in a string, then only the --- 8091,8097 ---- 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 ! use |byteidx()| to convert a character position to a byte position. If {str} matches multiple times in a string, then only the *************** *** 7986,7993 **** < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] When there is no match an empty list is returned. Can also be used as a |method|: > ! GetList()->matchlist('word') matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* Same as |match()|, but return the matched string. Example: > --- 8118,8127 ---- < 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: > *************** *** 8230,8235 **** --- 8364,8372 ---- :echo mzeval("l") :echo mzeval("h") < + Note that in a `:def` function local variables are not visible + to {expr}. + Can also be used as a |method|: > GetExpr()->mzeval() < *************** *** 8241,8246 **** --- 8378,8384 ---- if getline(nextnonblank(1)) =~ "Java" < 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|: > *************** *** 8254,8260 **** < When {utf8} is omitted or zero, the current 'encoding' is used. Example for "utf-8": > nr2char(300) returns I with bow character ! < With {utf8} set to 1, always return utf-8 characters. 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 --- 8392,8398 ---- < When {utf8} is omitted or zero, the current 'encoding' is used. Example for "utf-8": > nr2char(300) returns I with bow character ! < When {utf8} is TRUE, always return UTF-8 characters. 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 *************** *** 8276,8283 **** :let bits = bits->or(0x80) ! pathshorten({expr} [, {len}]) *pathshorten()* ! Shorten directory names in the path {expr} 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 --- 8414,8421 ---- :let bits = bits->or(0x80) ! 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 *************** *** 8302,8307 **** --- 8440,8448 ---- :echo perleval('[1 .. 4]') < [1, 2, 3, 4] + Note that in a `:def` function local variables are not visible + to {expr}. + Can also be used as a |method|: > GetExpr()->perleval() *************** *** 8333,8338 **** --- 8474,8480 ---- 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|: > *************** *** 8420,8434 **** field width. If the converted value has fewer bytes than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has ! been given) to fill out the field width. .precision An optional precision, in the form of a period '.' followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for ! d, o, x, and X conversions, or the maximum number of ! bytes to be printed from a string for s conversions. For floating point it is the number of digits after the decimal point. --- 8562,8579 ---- field width. If the converted value has fewer bytes than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has ! been given) to fill out the field width. For the S ! conversion the count is in cells. .precision An optional precision, in the form of a period '.' followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for ! d, o, x, and X conversions, the maximum number of ! bytes to be printed from a string for s conversions, ! or the maximum number of cells to be printed from a ! string for S conversions. For floating point it is the number of digits after the decimal point. *************** *** 8677,8682 **** --- 8822,8842 ---- < {only available when compiled with the |+python| or the |+python3| feature} + rand([{expr}]) *rand()* *random* + 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. + + Examples: > + :echo rand() + :let seed = srand() + :echo rand(seed) + :echo rand(seed) % 16 " random number 0 - 15 + < + *E726* *E727* range({expr} [, {max} [, {stride}]]) *range()* Returns a |List| with Numbers: *************** *** 8700,8720 **** GetExpr()->range() < - rand([{expr}]) *rand()* *random* - 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. - - Examples: > - :echo rand() - :let seed = srand() - :echo rand(seed) - :echo rand(seed) % 16 " random number 0 - 15 - < - readblob({fname}) *readblob()* Read file {fname} in binary mode and return a |Blob|. When the file can't be opened an error message is given and --- 8860,8865 ---- *************** *** 8919,8925 **** and {end}. The {start} and {end} arguments must be values returned by ! reltime(). Can also be used as a |method|: > GetStart()->reltime() --- 9064,9071 ---- and {end}. The {start} and {end} arguments must be values returned by ! reltime(). If there is an error zero is returned in legacy ! script, in Vim9 script an error is given. Can also be used as a |method|: > GetStart()->reltime() *************** *** 8934,8939 **** --- 9080,9087 ---- let seconds = reltimefloat(reltime(start)) < See the note of reltimestr() about overhead. Also see |profiling|. + If there is an error 0.0 is returned in legacy script, in Vim9 + script an error is given. Can also be used as a |method|: > reltime(start)->reltimefloat() *************** *** 8953,8958 **** --- 9101,9108 ---- can use split() to remove it. > echo split(reltimestr(reltime(start)))[0] < Also see |profiling|. + If there is an error an empty string is returned in legacy + script, in Vim9 script an error is given. Can also be used as a |method|: > reltime(start)->reltimestr() *************** *** 8991,8996 **** --- 9141,9147 ---- remote_foreground({server}) *remote_foreground()* Move the Vim server with the name {server} to the foreground. + The {server} argument is a string. This works like: > remote_expr({server}, "foreground()") < Except that on Win32 systems the client does the work, to work *************** *** 9186,9191 **** --- 9337,9344 ---- Hashes are represented as Vim |Dictionary| type. Other objects are represented as strings resulted from their "Object#to_s" method. + Note that in a `:def` function local variables are not visible + to {expr}. Can also be used as a |method|: > GetRubyExpr()->rubyeval() *************** *** 9253,9258 **** --- 9406,9415 ---- The "curscol" value is where the cursor would be placed. For a Tab it would be the same as "endcol", while for a double width character it would be the same as "col". + The |conceal| feature is ignored here, the column numbers are + 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. Can also be used as a |method|: > GetWinid()->screenpos(lnum, col) *************** *** 9566,9571 **** --- 9723,9730 ---- and -1 returned. {skip} can be a string, a lambda, a funcref or a partial. Anything else makes the function fail. + In a `:def` function when the {skip} argument is a string + constant it is compiled into instructions. For {stopline} and {timeout} see |search()|. *************** *** 9668,9675 **** Example: > :echo serverlist() < ! setbufline({expr}, {lnum}, {text}) *setbufline()* ! Set line {lnum} to {text} in buffer {expr}. This works like |setline()| for the specified buffer. This function works only for loaded buffers. First call --- 9827,9834 ---- Example: > :echo serverlist() < ! setbufline({buf}, {lnum}, {text}) *setbufline()* ! Set line {lnum} to {text} in buffer {buf}. This works like |setline()| for the specified buffer. This function works only for loaded buffers. First call *************** *** 9682,9694 **** to set multiple lines. If the list extends below the last line then those lines are added. ! For the use of {expr}, see |bufname()| above. {lnum} is used like with |setline()|. When {lnum} is just below the last line the {text} will be added below the last line. ! When {expr} is not a valid buffer, the buffer is not loaded or {lnum} is not valid then 1 is returned. On success 0 is returned. --- 9841,9854 ---- to set multiple lines. If the list extends below the last line then those lines are added. ! For the use of {buf}, see |bufname()| above. {lnum} is used like with |setline()|. + Use "$" to refer to the last line in buffer {buf}. When {lnum} is just below the last line the {text} will be added below the last line. ! When {buf} is not a valid buffer, the buffer is not loaded or {lnum} is not valid then 1 is returned. On success 0 is returned. *************** *** 9696,9708 **** third argument: > GetText()->setbufline(buf, lnum) ! setbufvar({expr}, {varname}, {val}) *setbufvar()* ! Set option or local variable {varname} in buffer {expr} to {val}. This also works for a global or local window option, but it doesn't work for a global or local window variable. For a local window option the global value is unchanged. ! For the use of {expr}, see |bufname()| above. Note that the variable name without "b:" must be used. Examples: > :call setbufvar(1, "&mod", 1) --- 9856,9869 ---- third argument: > GetText()->setbufline(buf, lnum) ! 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 doesn't work for a global or local window variable. For a local window option the global value is unchanged. ! 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) *************** *** 9719,9725 **** tells Vim how wide characters are, counted in screen cells. This overrides 'ambiwidth'. Example: > setcellwidths([[0xad, 0xad, 1], ! \ [0x2194, 0x2199, 2]]) < *E1109* *E1110* *E1111* *E1112* *E1113* The {list} argument is a list of lists with each three --- 9880,9886 ---- tells Vim how wide characters are, counted in screen cells. This overrides 'ambiwidth'. Example: > setcellwidths([[0xad, 0xad, 1], ! \ [0x2194, 0x2199, 2]]) < *E1109* *E1110* *E1111* *E1112* *E1113* The {list} argument is a list of lists with each three *************** *** 9812,9819 **** setenv({name}, {val}) *setenv()* ! Set environment variable {name} to {val}. ! 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 --- 9973,9982 ---- setenv({name}, {val}) *setenv()* ! Set environment variable {name} to {val}. Example: > ! 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 *************** *** 9905,9911 **** < *setpos()* setpos({expr}, {list}) ! Set the position for {expr}. Possible values: . the cursor 'x mark x --- 10068,10074 ---- < *setpos()* setpos({expr}, {list}) ! Set the position for String {expr}. Possible values: . the cursor 'x mark x *************** *** 10073,10079 **** setreg({regname}, {value} [, {options}]) Set the register {regname} to {value}. If {regname} is "" or "@", the unnamed register '"' is used. ! In |Vim9-script| {regname} must be one character. {value} may be any value returned by |getreg()| or |getreginfo()|, including a |List| or |Dict|. --- 10236,10243 ---- setreg({regname}, {value} [, {options}]) Set the register {regname} to {value}. If {regname} is "" or "@", the unnamed register '"' is used. ! The {regname} argument is a string. In |Vim9-script| ! {regname} must be one character. {value} may be any value returned by |getreg()| or |getreginfo()|, including a |List| or |Dict|. *************** *** 10131,10136 **** --- 10295,10301 ---- settabvar({tabnr}, {varname}, {val}) *settabvar()* Set tab-local variable {varname} to {val} in tab page {tabnr}. |t:var| + The {varname} argument is a string. Note that autocommands are blocked, side effects may not be triggered, e.g. when setting 'filetype'. Note that the variable name without "t:" must be used. *************** *** 10329,10335 **** {only available when compiled with the |+float| feature} ! 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, like in --- 10494,10500 ---- {only available when compiled with the |+float| feature} ! 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, like in *************** *** 10407,10421 **** func MyCompare(i1, i2) return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 endfunc ! let sortedlist = sort(mylist, "MyCompare") < A shorter compare version for this specific simple case, which ignores overflow: > func MyCompare(i1, i2) return a:i1 - a:i2 endfunc < sound_clear() *sound_clear()* Stop playing all sounds. {only available when compiled with the |+sound| feature} *sound_playevent()* --- 10572,10592 ---- 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: > func MyCompare(i1, i2) return a:i1 - a:i2 endfunc + < For a simple expression you can use a lambda: > + eval mylist->sort({i1, i2 -> i1 - i2}) < sound_clear() *sound_clear()* Stop playing all sounds. + + On some Linux systems you may need the libcanberra-pulse + package, otherwise sound may not stop. + {only available when compiled with the |+sound| feature} *sound_playevent()* *************** *** 10468,10473 **** --- 10639,10647 ---- Stop playing sound {id}. {id} must be previously returned by `sound_playevent()` or `sound_playfile()`. + On some Linux systems you may need the libcanberra-pulse + package, otherwise sound may not stop. + On MS-Windows, this does not work for event sound started by `sound_playevent()`. To stop event sounds, use `sound_clear()`. *************** *** 10541,10548 **** Can also be used as a |method|: > GetWord()->spellsuggest() ! split({expr} [, {pattern} [, {keepempty}]]) *split()* ! Make a |List| out of {expr}. When {pattern} is omitted or empty each white-separated sequence of characters becomes an item. Otherwise the string is split where {pattern} matches, --- 10715,10722 ---- Can also be used as a |method|: > GetWord()->spellsuggest() ! 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. Otherwise the string is split where {pattern} matches, *************** *** 10630,10647 **** w blocked on waiting, e.g. ch_evalexpr(), ch_read() and ch_readraw() when reading json S not triggering SafeState or SafeStateAgain, e.g. after ! |f| or a count c callback invoked, including timer (repeats for recursiveness up to "ccc") s screen has scrolled for messages ! str2float({expr}) *str2float()* ! Convert String {expr} 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. E.g., "1e40" is accepted, while in an expression you need to write "1.0e40". The hexadecimal form "0x123" is also accepted, but not others, like binary or octal. Text after the number is silently ignored. The decimal point is always '.', no matter what the locale is set to. A comma ends the number: "12,345.67" is converted to --- 10804,10824 ---- w blocked on waiting, e.g. ch_evalexpr(), ch_read() and ch_readraw() when reading json S not triggering SafeState or SafeStateAgain, e.g. after ! |f| or a count c callback invoked, including timer (repeats for recursiveness up to "ccc") s screen has scrolled for messages ! 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. E.g., "1e40" is accepted, while in an expression you need to write "1.0e40". The hexadecimal form "0x123" is also accepted, but not others, like binary or octal. + When {quoted} is present and non-zero then embedded single + quotes before the dot are ignored, thus "1'000.0" is a + thousand. Text after the number is silently ignored. The decimal point is always '.', no matter what the locale is set to. A comma ends the number: "12,345.67" is converted to *************** *** 10654,10669 **** < {only available when compiled with the |+float| feature} ! str2list({expr} [, {utf8}]) *str2list()* Return a list containing the number values which represent ! each character in String {expr}. Examples: > str2list(" ") returns [32] str2list("ABC") returns [65, 66, 67] < |list2str()| does the opposite. When {utf8} is omitted or zero, the current 'encoding' is used. ! With {utf8} set to 1, always treat the String as utf-8 ! characters. With utf-8 composing characters are handled properly: > str2list("á") returns [97, 769] --- 10831,10846 ---- < {only available when compiled with the |+float| feature} ! 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] < |list2str()| does the opposite. When {utf8} is omitted or zero, the current 'encoding' is used. ! When {utf8} is TRUE, always treat the String as UTF-8 ! characters. With UTF-8 composing characters are handled properly: > str2list("á") returns [97, 769] *************** *** 10671,10678 **** GetString()->str2list() ! str2nr({expr} [, {base} [, {quoted}]]) *str2nr()* ! Convert string {expr} 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 quotes are ignored, thus "1'000'000" is a million. --- 10848,10855 ---- GetString()->str2list() ! str2nr({string} [, {base} [, {quoted}]]) *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 quotes are ignored, thus "1'000'000" is a million. *************** *** 10692,10700 **** GetText()->str2nr() ! strcharlen({expr}) *strcharlen()* The result is a Number, which is the number of characters ! in String {expr}. Composing characters are ignored. |strchars()| can count the number of characters, counting composing characters separately. --- 10869,10877 ---- GetText()->str2nr() ! 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 composing characters separately. *************** *** 10721,10729 **** GetText()->strcharpart(5) ! strchars({expr} [, {skipcc}]) *strchars()* The result is a Number, which is the number of characters ! in String {expr}. When {skipcc} is omitted or zero, composing characters are counted separately. When {skipcc} set to 1, Composing characters are ignored. --- 10898,10906 ---- GetText()->strcharpart(5) ! 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 counted separately. When {skipcc} set to 1, Composing characters are ignored. *************** *** 10750,10765 **** Can also be used as a |method|: > GetText()->strchars() ! strdisplaywidth({expr} [, {col}]) *strdisplaywidth()* The result is a Number, which is the number of display cells ! String {expr} occupies on the screen when it starts at {col} (first column is zero). When {col} is omitted zero is used. Otherwise it is the screen column where to start. This matters for Tab characters. The option settings of the current window are used. This matters for anything that's displayed differently, such as 'tabstop' and 'display'. ! When {expr} contains characters with East Asian Width Class Ambiguous, this function's return value depends on 'ambiwidth'. Also see |strlen()|, |strwidth()| and |strchars()|. --- 10927,10942 ---- Can also be used as a |method|: > GetText()->strchars() ! 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. Otherwise it is the screen column where to start. This matters for Tab characters. The option settings of the current window are used. This matters for anything that's displayed differently, such as 'tabstop' and 'display'. ! When {string} contains characters with East Asian Width Class Ambiguous, this function's return value depends on 'ambiwidth'. Also see |strlen()|, |strwidth()| and |strchars()|. *************** *** 10841,10849 **** < Also see |strtrans()|. ! *strlen()* ! strlen({expr}) The result is a Number, which is the length of the String ! {expr} in bytes. If the argument is a Number it is first converted to a String. For other types an error is given. If you want to count the number of multibyte characters use --- 11018,11027 ---- < Also see |strtrans()|. ! ! 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. For other types an error is given. If you want to count the number of multibyte characters use *************** *** 10930,10937 **** Can also be used as a |method|: > GetHaystack()->strridx(needle) ! strtrans({expr}) *strtrans()* ! The result is a String, which is {expr} with all unprintable characters translated into printable characters |'isprint'|. Like they are shown in a window. Example: > echo strtrans(@a) --- 11108,11115 ---- Can also be used as a |method|: > GetHaystack()->strridx(needle) ! 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: > echo strtrans(@a) *************** *** 10941,10951 **** Can also be used as a |method|: > GetString()->strtrans() ! strwidth({expr}) *strwidth()* The result is a Number, which is the number of display cells ! String {expr} occupies. A Tab character is counted as one cell, alternatively use |strdisplaywidth()|. ! When {expr} contains characters with East Asian Width Class Ambiguous, this function's return value depends on 'ambiwidth'. Also see |strlen()|, |strdisplaywidth()| and |strchars()|. --- 11119,11129 ---- Can also be used as a |method|: > GetString()->strtrans() ! 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()|. ! When {string} contains characters with East Asian Width Class Ambiguous, this function's return value depends on 'ambiwidth'. Also see |strlen()|, |strdisplaywidth()| and |strchars()|. *************** *** 10981,10990 **** Can also be used as a |method|: > GetNr()->submatch() ! substitute({expr}, {pat}, {sub}, {flags}) *substitute()* ! The result is a String, which is a copy of {expr}, in which the first match of {pat} is replaced with {sub}. ! When {flags} is "g", all matches of {pat} in {expr} are replaced. Otherwise {flags} should be "". This works like the ":substitute" command (without any flags). --- 11159,11168 ---- Can also be used as a |method|: > GetNr()->submatch() ! 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 replaced. Otherwise {flags} should be "". This works like the ":substitute" command (without any flags). *************** *** 11000,11006 **** |sub-replace-special|. For example, to replace something with "\n" (two characters), use "\\\\n" or '\\n'. ! When {pat} does not match in {expr}, {expr} is returned unmodified. Example: > --- 11178,11184 ---- |sub-replace-special|. For example, to replace something with "\n" (two characters), use "\\\\n" or '\\n'. ! When {pat} does not match in {string}, {string} is returned unmodified. Example: > *************** *** 11047,11058 **** Can also be used as a |method|: > GetFilename()->swapinfo() ! swapname({expr}) *swapname()* The result is the swap file path of the buffer {expr}. ! For the use of {expr}, see |bufname()| above. ! If buffer {expr} is the current buffer, the result is equal to |:swapname| (unless there is no swap file). ! If buffer {expr} has no swap file, returns an empty string. Can also be used as a |method|: > GetBufname()->swapname() --- 11225,11236 ---- Can also be used as a |method|: > GetFilename()->swapinfo() ! swapname({buf}) *swapname()* The result is the swap file path of the buffer {expr}. ! 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() *************** *** 11067,11073 **** line. 'synmaxcol' applies, in a longer line zero is returned. Note that when the position is after the last character, that's where the cursor can be in Insert mode, synID() returns ! zero. When {trans} is |TRUE|, transparent items are reduced to the item that they reveal. This is useful when wanting to know --- 11245,11251 ---- line. 'synmaxcol' applies, in a longer line zero is returned. Note that when the position is after the last character, that's where the cursor can be in Insert mode, synID() returns ! zero. {lnum} is used like with |getline()|. When {trans} is |TRUE|, transparent items are reduced to the item that they reveal. This is useful when wanting to know *************** *** 11135,11141 **** 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 --- 11313,11319 ---- 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. {lnum} is used like with |getline()|. 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 *************** *** 11159,11166 **** synstack({lnum}, {col}) *synstack()* Return a |List|, which is the stack of syntax items at the ! position {lnum} and {col} in the current window. Each item in ! the List is an ID like what |synID()| returns. The first item in the List is the outer region, following are items contained in that one. The last one is what |synID()| returns, unless not the whole item is highlighted or it is a --- 11337,11345 ---- 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 ! like what |synID()| returns. The first item in the List is the outer region, following are items contained in that one. The last one is what |synID()| returns, unless not the whole item is highlighted or it is a *************** *** 11176,11185 **** valid positions. system({expr} [, {input}]) *system()* *E677* ! Get the output of the shell command {expr} as a string. See |systemlist()| to get the output as a |List|. ! When {input} is given and is a string this string is written to a file and passed as stdin to the command. The string is written as-is, you need to take care of using the correct line separators yourself. --- 11355,11364 ---- valid positions. system({expr} [, {input}]) *system()* *E677* ! Get the output of the shell command {expr} as a |String|. See |systemlist()| to get the output as a |List|. ! When {input} is given and is a |String| this string is written to a file and passed as stdin to the command. The string is written as-is, you need to take care of using the correct line separators yourself. *************** *** 11802,11810 **** 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. When executing {command} ! autocommands will be triggered, this may have unexpected side ! effects. Use |:noautocmd| if needed. Example: > call win_execute(winid, 'set syntax=python') < Doing the same with `setwinvar()` would not trigger --- 11981,11989 ---- 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: > call win_execute(winid, 'set syntax=python') < Doing the same with `setwinvar()` would not trigger *************** *** 11891,11897 **** [1, 1], unless there is a tabline, then it is [2, 1]. {nr} can be the window number or the |window-ID|. Use zero for the current window. ! Return [0, 0] if the window cannot be found in the current tabpage. Can also be used as a |method|: > --- 12070,12076 ---- [1, 1], unless there is a tabline, then it is [2, 1]. {nr} can be the window number or the |window-ID|. Use zero for the current window. ! Returns [0, 0] if the window cannot be found in the current tabpage. Can also be used as a |method|: > *************** *** 12181,12186 **** --- 12360,12366 ---- 1. Features that are only supported when they have been enabled when Vim was compiled |+feature-list|. Example: > :if has("cindent") + < *gui_running* 2. Features that are only supported when certain conditions have been met. Example: > :if has("gui_running") *************** *** 12238,12243 **** --- 12418,12424 ---- digraphs Compiled with support for digraphs. directx Compiled with support for DirectX and 'renderoptions'. dnd Compiled with support for the "~ register |quote_~|. + drop_file Compiled with |drop_file| support. ebcdic Compiled on a machine with ebcdic character set. emacs_tags Compiled with support for Emacs tags. eval Compiled with expression evaluation support. Always *************** *** 12456,12473 **** avoid obvious, short names. A good habit is to start the function name with the name of the script, e.g., "HTMLcolor()". ! It's also possible to use curly braces, see |curly-braces-names|. And the ! |autoload| facility is useful to define a function only when it's called. *local-function* ! A function local to a script must start with "s:". A local script function ! can only be called from within the script and from functions, user commands ! and autocommands defined in the script. It is also possible to call the ! function from a mapping defined in the script, but then || must be used ! instead of "s:" when the mapping is expanded outside of the script. There are only script-local functions, no buffer-local or window-local functions. *:fu* *:function* *E128* *E129* *E123* :fu[nction] List all functions and their arguments. --- 12637,12658 ---- avoid obvious, short names. A good habit is to start the function name with the name of the script, e.g., "HTMLcolor()". ! In legacy script it is also possible to use curly braces, see ! |curly-braces-names|. ! The |autoload| facility is useful to define a function only when it's called. *local-function* ! A function local to a legacy script must start with "s:". A local script ! function can only be called from within the script and from functions, user ! commands and autocommands defined in the script. It is also possible to call ! the function from a mapping defined in the script, but then || must be ! used instead of "s:" when the mapping is expanded outside of the script. There are only script-local functions, no buffer-local or window-local functions. + In |Vim9| script functions are local to the script by default, prefix "g:" to + define a global function. + *:fu* *:function* *E128* *E129* *E123* :fu[nction] List all functions and their arguments. *************** *** 12729,12735 **** Call a function. The name of the function and its arguments are as specified with `:function`. Up to 20 arguments can be used. The returned value is discarded. ! Without a range and for functions that accept a range, the function is called once. When a range is given the cursor is positioned at the start of the first line before executing the function. --- 12914,12924 ---- Call a function. The name of the function and its arguments are as specified with `:function`. Up to 20 arguments can be used. The returned value is discarded. ! In |Vim9| script using `:call` is optional, these two lines do ! the same thing: > ! call SomeFunc(arg) ! SomeFunc(arg) ! < Without a range and for functions that accept a range, the function is called once. When a range is given the cursor is positioned at the start of the first line before executing the function. *************** *** 12874,12879 **** --- 13063,13070 ---- wrapped in braces {} like this: > my_{adjective}_variable + This only works in legacy Vim script, not in |Vim9| script. + When Vim encounters this, it evaluates the expression inside the braces, puts that in place of the expression, and re-interprets the whole as a variable name. So in the above example, if the variable "adjective" was set to *************** *** 12915,12922 **** ============================================================================== 7. Commands *expression-commands* ! Note: in Vim9 script `:let` is used for variable declaration, not assignment. ! An assignment leaves out the `:let` command. |vim9-declaration| :let {var-name} = {expr1} *:let* *E18* Set internal variable {var-name} to the result of the --- 13106,13113 ---- ============================================================================== 7. Commands *expression-commands* ! Note: in |Vim9| script `:let` is not used. `:var` is used for variable ! declarations and assignments do not use a command. |vim9-declaration| :let {var-name} = {expr1} *:let* *E18* Set internal variable {var-name} to the result of the *************** *** 13199,13205 **** literal then the items also cannot be changed: > const ll = [1, 2, 3] let ll[1] = 5 " Error! ! < Nested references are not locked: > let lvar = ['a'] const lconst = [0, lvar] let lconst[0] = 2 " Error! --- 13390,13396 ---- literal then the items also cannot be changed: > const ll = [1, 2, 3] let ll[1] = 5 " Error! ! < Nested references are not locked: > let lvar = ['a'] const lconst = [0, lvar] let lconst[0] = 2 " Error! *************** *** 13223,13230 **** it can no longer be changed (until it is unlocked). A locked variable can be deleted: > :lockvar v ! :let v = 'asdf' " fails! ! :unlet v < *E741* *E940* If you try to change a locked variable you get an error message: "E741: Value is locked: {name}". --- 13414,13421 ---- it can no longer be changed (until it is unlocked). A locked variable can be deleted: > :lockvar v ! :let v = 'asdf' " fails! ! :unlet v " works < *E741* *E940* If you try to change a locked variable you get an error message: "E741: Value is locked: {name}". *************** *** 13253,13260 **** Example with [depth] 0: > let mylist = [1, 2, 3] lockvar 0 mylist ! let mylist[0] = 77 " OK ! call add(mylist, 4] " OK let mylist = [7, 8, 9] " Error! < *E743* For unlimited depth use [!] and omit [depth]. --- 13444,13451 ---- Example with [depth] 0: > let mylist = [1, 2, 3] lockvar 0 mylist ! let mylist[0] = 77 " OK ! call add(mylist, 4] " OK let mylist = [7, 8, 9] " Error! < *E743* For unlimited depth use [!] and omit [depth]. *************** *** 13334,13358 **** :endfo[r] *:endfo* *:endfor* Repeat the commands between ":for" and ":endfor" for each item in {object}. {object} can be a |List| or ! a |Blob|. Variable {var} is set to the value of each ! item. When an error is detected for a command inside ! the loop, execution continues after the "endfor". Changing {object} inside the loop affects what items are used. Make a copy if this is unwanted: > :for item in copy(mylist) < ! When {object} is a |List| and not making a copy, Vim ! stores a reference to the next item in the |List| ! before executing the commands with the current item. ! Thus the current item can be removed without effect. ! Removing any later item means it will not be found. ! Thus the following example works (an inefficient way ! to make a |List| empty): > for item in mylist call remove(mylist, 0) endfor < Note that reordering the |List| (e.g., with sort() or reverse()) may have unexpected effects. When {object} is a |Blob|, Vim always makes a copy to iterate over. Unlike with |List|, modifying the --- 13525,13558 ---- :endfo[r] *:endfo* *:endfor* Repeat the commands between ":for" and ":endfor" for each item in {object}. {object} can be a |List| or ! a |Blob|. ! ! Variable {var} is set to the value of each item. ! In |Vim9| script the loop variable must not have been ! declared yet, unless when it is a ! global/window/tab/buffer variable. ! ! When an error is detected for a command inside the ! loop, execution continues after the "endfor". Changing {object} inside the loop affects what items are used. Make a copy if this is unwanted: > :for item in copy(mylist) < ! When {object} is a |List| and not making a copy, in ! legacy script Vim stores a reference to the next item ! in the |List| before executing the commands with the ! current item. Thus the current item can be removed ! without effect. Removing any later item means it will ! not be found. Thus the following example works (an ! inefficient way to make a |List| empty): > for item in mylist call remove(mylist, 0) endfor < Note that reordering the |List| (e.g., with sort() or reverse()) may have unexpected effects. + In |Vim9| script the index is used. If an item before + the current one is deleted the next item will be + skipped. When {object} is a |Blob|, Vim always makes a copy to iterate over. Unlike with |List|, modifying the *************** *** 13597,13603 **** Cannot be followed by a comment. Examples: > :execute "buffer" nextbuf ! :execute "normal" count . "w" < ":execute" can be used to append a command to commands that don't accept a '|'. Example: > --- 13797,13803 ---- Cannot be followed by a comment. Examples: > :execute "buffer" nextbuf ! :execute "normal" count .. "w" < ":execute" can be used to append a command to commands that don't accept a '|'. Example: > *************** *** 14609,14615 **** *except-several-errors* When several errors appear in a single command, the first error message is ! usually the most specific one and therefor converted to the error exception. Example: > echo novar causes > --- 14809,14815 ---- *except-several-errors* When several errors appear in a single command, the first error message is ! usually the most specific one and therefore converted to the error exception. Example: > echo novar causes > *** ../vim-8.2.3912/src/vim9expr.c 2021-12-22 13:18:36.145009230 +0000 --- src/vim9expr.c 2021-12-27 14:05:01.381921893 +0000 *************** *** 1883,1889 **** * trailing ->name() method call */ static int ! compile_expr7( char_u **arg, cctx_T *cctx, ppconst_T *ppconst) --- 1883,1889 ---- * trailing ->name() method call */ static int ! compile_expr8( char_u **arg, cctx_T *cctx, ppconst_T *ppconst) *************** *** 2119,2128 **** } /* ! * expr7: runtime type check / conversion */ static int ! compile_expr7t(char_u **arg, cctx_T *cctx, ppconst_T *ppconst) { type_T *want_type = NULL; --- 2119,2128 ---- } /* ! * expr8: runtime type check / conversion */ static int ! compile_expr7(char_u **arg, cctx_T *cctx, ppconst_T *ppconst) { type_T *want_type = NULL; *************** *** 2147,2153 **** return FAIL; } ! if (compile_expr7(arg, cctx, ppconst) == FAIL) return FAIL; if (want_type != NULL) --- 2147,2153 ---- return FAIL; } ! if (compile_expr8(arg, cctx, ppconst) == FAIL) return FAIL; if (want_type != NULL) *************** *** 2182,2188 **** int ppconst_used = ppconst->pp_used; // get the first expression ! if (compile_expr7t(arg, cctx, ppconst) == FAIL) return FAIL; /* --- 2182,2188 ---- int ppconst_used = ppconst->pp_used; // get the first expression ! if (compile_expr7(arg, cctx, ppconst) == FAIL) return FAIL; /* *************** *** 2208,2214 **** return FAIL; // get the second expression ! if (compile_expr7t(arg, cctx, ppconst) == FAIL) return FAIL; if (ppconst->pp_used == ppconst_used + 2 --- 2208,2214 ---- return FAIL; // get the second expression ! if (compile_expr7(arg, cctx, ppconst) == FAIL) return FAIL; if (ppconst->pp_used == ppconst_used + 2 *** ../vim-8.2.3912/src/version.c 2021-12-27 12:52:03.460567722 +0000 --- src/version.c 2021-12-27 14:11:06.420892124 +0000 *************** *** 751,752 **** --- 751,754 ---- { /* Add new patch number below this line */ + /**/ + 3913, /**/ -- hundred-and-one symptoms of being an internet addict: 121. You ask for e-mail adresses instead of telephone numbers. /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net \\\ /// \\\ \\\ sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ /// \\\ help me help AIDS victims -- http://ICCF-Holland.org ///