Mercurial > vim
comparison runtime/doc/vim9.txt @ 27459:5825405e4e2c
Update runtime files
Commit: https://github.com/vim/vim/commit/f10911e5db16f1fe6ab519c5d091ad0c1df0d063
Author: Bram Moolenaar <Bram@vim.org>
Date: Sat Jan 29 22:20:48 2022 +0000
Update runtime files
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Sat, 29 Jan 2022 23:30:04 +0100 |
parents | 3649b5a6b1b6 |
children | 4789f29c9595 |
comparison
equal
deleted
inserted
replaced
27458:2a7fc102cb91 | 27459:5825405e4e2c |
---|---|
1 *vim9.txt* For Vim version 8.2. Last change: 2022 Jan 23 | 1 *vim9.txt* For Vim version 8.2. Last change: 2022 Jan 29 |
2 | 2 |
3 | 3 |
4 VIM REFERENCE MANUAL by Bram Moolenaar | 4 VIM REFERENCE MANUAL by Bram Moolenaar |
5 | 5 |
6 | 6 |
80 - Using a backslash for line continuation is hardly ever needed: > | 80 - Using a backslash for line continuation is hardly ever needed: > |
81 echo "hello " | 81 echo "hello " |
82 .. yourName | 82 .. yourName |
83 .. ", how are you?" | 83 .. ", how are you?" |
84 - White space is required in many places to improve readability. | 84 - White space is required in many places to improve readability. |
85 - Assign values without `:let`, declare variables with `:var`: > | 85 - Assign values without `:let` *E1126* , declare variables with `:var`: > |
86 var count = 0 | 86 var count = 0 |
87 count += 3 | 87 count += 3 |
88 - Constants can be declared with `:final` and `:const`: > | 88 - Constants can be declared with `:final` and `:const`: > |
89 final matches = [] # add matches | 89 final matches = [] # add matches |
90 const names = ['Betty', 'Peter'] # cannot be changed | 90 const names = ['Betty', 'Peter'] # cannot be changed |
137 script you need to use %% instead. Instead of ## use %%% (stands for all | 137 script you need to use %% instead. Instead of ## use %%% (stands for all |
138 arguments). | 138 arguments). |
139 | 139 |
140 | 140 |
141 Vim9 functions ~ | 141 Vim9 functions ~ |
142 | 142 *E1099* |
143 A function defined with `:def` is compiled. Execution is many times faster, | 143 A function defined with `:def` is compiled. Execution is many times faster, |
144 often 10 to 100 times. | 144 often 10 to 100 times. |
145 | 145 |
146 Many errors are already found when compiling, before the function is executed. | 146 Many errors are already found when compiling, before the function is executed. |
147 The syntax is strict, to enforce code that is easy to read and understand. | 147 The syntax is strict, to enforce code that is easy to read and understand. |
181 endfunc | 181 endfunc |
182 def CallLegacy() | 182 def CallLegacy() |
183 var d = {func: Legacy, value: 'text'} | 183 var d = {func: Legacy, value: 'text'} |
184 d.func() | 184 d.func() |
185 enddef | 185 enddef |
186 | 186 < *E1096* |
187 The argument types and return type need to be specified. The "any" type can | 187 The argument types and return type need to be specified. The "any" type can |
188 be used, type checking will then be done at runtime, like with legacy | 188 be used, type checking will then be done at runtime, like with legacy |
189 functions. | 189 functions. |
190 | 190 *E1106* |
191 Arguments are accessed by name, without "a:", just like any other language. | 191 Arguments are accessed by name, without "a:", just like any other language. |
192 There is no "a:" dictionary or "a:000" list. | 192 There is no "a:" dictionary or "a:000" list. |
193 *vim9-variable-arguments* *E1055* | 193 *vim9-variable-arguments* *E1055* |
194 Variable arguments are defined as the last argument, with a name and have a | 194 Variable arguments are defined as the last argument, with a name and have a |
195 list type, similar to TypeScript. For example, a list of numbers: > | 195 list type, similar to TypeScript. For example, a list of numbers: > |
236 | 236 |
237 When referring to a function and no "s:" or "g:" prefix is used, Vim will | 237 When referring to a function and no "s:" or "g:" prefix is used, Vim will |
238 search for the function: | 238 search for the function: |
239 - in the function scope, in block scopes | 239 - in the function scope, in block scopes |
240 - in the script scope, possibly imported | 240 - in the script scope, possibly imported |
241 - in the list of global functions | |
242 However, it is recommended to always use "g:" to refer to a global function | |
243 for clarity. | |
244 | 241 |
245 Since a script-local function reference can be used without "s:" the name must | 242 Since a script-local function reference can be used without "s:" the name must |
246 start with an upper case letter even when using the "s:" prefix. In legacy | 243 start with an upper case letter even when using the "s:" prefix. In legacy |
247 script "s:funcref" could be used, because it could not be referred to with | 244 script "s:funcref" could be used, because it could not be referred to with |
248 "funcref". In Vim9 script it can, therefore "s:Funcref" must be used to avoid | 245 "funcref". In Vim9 script it can, therefore "s:Funcref" must be used to avoid |
253 it is being compiled (to figure out the return type). | 250 it is being compiled (to figure out the return type). |
254 | 251 |
255 The result is that functions and variables without a namespace can usually be | 252 The result is that functions and variables without a namespace can usually be |
256 found in the script, either defined there or imported. Global functions and | 253 found in the script, either defined there or imported. Global functions and |
257 variables could be defined anywhere (good luck finding out where!). | 254 variables could be defined anywhere (good luck finding out where!). |
258 | 255 *E1102* |
259 Global functions can still be defined and deleted at nearly any time. In | 256 Global functions can still be defined and deleted at nearly any time. In |
260 Vim9 script script-local functions are defined once when the script is sourced | 257 Vim9 script script-local functions are defined once when the script is sourced |
261 and cannot be deleted or replaced. | 258 and cannot be deleted or replaced. |
262 | 259 |
263 When compiling a function and a function call is encountered for a function | 260 When compiling a function and a function call is encountered for a function |
287 def g:SomeFunc() | 284 def g:SomeFunc() |
288 .... | 285 .... |
289 | 286 |
290 | 287 |
291 Variable declarations with :var, :final and :const ~ | 288 Variable declarations with :var, :final and :const ~ |
292 *vim9-declaration* *:var* | 289 *vim9-declaration* *:var* |
293 *E1017* *E1020* *E1054* | 290 *E1017* *E1020* *E1054* *E1087* *E1108* *E1124* |
294 Local variables need to be declared with `:var`. Local constants need to be | 291 Local variables need to be declared with `:var`. Local constants need to be |
295 declared with `:final` or `:const`. We refer to both as "variables" in this | 292 declared with `:final` or `:const`. We refer to both as "variables" in this |
296 section. | 293 section. |
297 | 294 |
298 Variables can be local to a script, function or code block: > | 295 Variables can be local to a script, function or code block: > |
319 inner = 5 | 316 inner = 5 |
320 else | 317 else |
321 inner = 0 | 318 inner = 0 |
322 endif | 319 endif |
323 echo inner | 320 echo inner |
324 < *E1025* | 321 < *E1025* *E1128* |
325 To intentionally hide a variable from code that follows, a block can be | 322 To intentionally hide a variable from code that follows, a block can be |
326 used: > | 323 used: > |
327 { | 324 { |
328 var temp = 'temp' | 325 var temp = 'temp' |
329 ... | 326 ... |
346 silent! exe ':%! some formatting command' | 343 silent! exe ':%! some formatting command' |
347 winrestview(save) | 344 winrestview(save) |
348 } | 345 } |
349 | 346 |
350 Although using a :def function probably works better. | 347 Although using a :def function probably works better. |
351 *E1022* | 348 *E1022* *E1103* *E1130* *E1131* *E1133* *E1134* |
352 Declaring a variable with a type but without an initializer will initialize to | 349 Declaring a variable with a type but without an initializer will initialize to |
353 false (for bool), empty (for string, list, dict, etc.) or zero (for number, | 350 false (for bool), empty (for string, list, dict, etc.) or zero (for number, |
354 any, etc.). This matters especially when using the "any" type, the value will | 351 any, etc.). This matters especially when using the "any" type, the value will |
355 default to the number zero. | 352 default to the number zero. |
356 *E1016* *E1052* *E1066* | 353 *E1016* *E1052* *E1066* |
438 Example: > | 435 Example: > |
439 const myList = [1, 2] | 436 const myList = [1, 2] |
440 myList = [3, 4] # Error! | 437 myList = [3, 4] # Error! |
441 myList[0] = 9 # Error! | 438 myList[0] = 9 # Error! |
442 myList->add(3) # Error! | 439 myList->add(3) # Error! |
443 < *:final* | 440 < *:final* *E1125* |
444 `:final` is used for making only the variable a constant, the value can be | 441 `:final` is used for making only the variable a constant, the value can be |
445 changed. This is well known from Java. Example: > | 442 changed. This is well known from Java. Example: > |
446 final myList = [1, 2] | 443 final myList = [1, 2] |
447 myList = [3, 4] # Error! | 444 myList = [3, 4] # Error! |
448 myList[0] = 9 # OK | 445 myList[0] = 9 # OK |
598 key: value | 595 key: value |
599 })->method() | 596 })->method() |
600 | 597 |
601 | 598 |
602 Automatic line continuation ~ | 599 Automatic line continuation ~ |
603 *vim9-line-continuation* | 600 *vim9-line-continuation* *E1097* |
604 In many cases it is obvious that an expression continues on the next line. In | 601 In many cases it is obvious that an expression continues on the next line. In |
605 those cases there is no need to prefix the line with a backslash (see | 602 those cases there is no need to prefix the line with a backslash (see |
606 |line-continuation|). For example, when a list spans multiple lines: > | 603 |line-continuation|). For example, when a list spans multiple lines: > |
607 var mylist = [ | 604 var mylist = [ |
608 'one', | 605 'one', |
706 popup_create(some invalid expression, { | 703 popup_create(some invalid expression, { |
707 exit_cb: Func}) | 704 exit_cb: Func}) |
708 Now "exit_cb: Func})" is actually a valid command: save any changes to the | 705 Now "exit_cb: Func})" is actually a valid command: save any changes to the |
709 file "_cb: Func})" and exit. To avoid this kind of mistake in Vim9 script | 706 file "_cb: Func})" and exit. To avoid this kind of mistake in Vim9 script |
710 there must be white space between most command names and the argument. | 707 there must be white space between most command names and the argument. |
708 *E1144* | |
711 | 709 |
712 However, the argument of a command that is a command won't be recognized. For | 710 However, the argument of a command that is a command won't be recognized. For |
713 example, after "windo echo expr" a line break inside "expr" will not be seen. | 711 example, after "windo echo expr" a line break inside "expr" will not be seen. |
714 | 712 |
715 | 713 |
736 commands are used as an argument to another command, such as `windo`. In | 734 commands are used as an argument to another command, such as `windo`. In |
737 those cases the line continuation with a backslash has to be used. | 735 those cases the line continuation with a backslash has to be used. |
738 | 736 |
739 | 737 |
740 White space ~ | 738 White space ~ |
741 *E1004* *E1068* *E1069* *E1074* | 739 *E1004* *E1068* *E1069* *E1074* *E1127* |
742 Vim9 script enforces proper use of white space. This is no longer allowed: > | 740 Vim9 script enforces proper use of white space. This is no longer allowed: > |
743 var name=234 # Error! | 741 var name=234 # Error! |
744 var name= 234 # Error! | 742 var name= 234 # Error! |
745 var name =234 # Error! | 743 var name =234 # Error! |
746 There must be white space before and after the "=": > | 744 There must be white space before and after the "=": > |
801 This works for alphanumeric characters, underscore and dash. If you want to | 799 This works for alphanumeric characters, underscore and dash. If you want to |
802 use another character, use a single or double quoted string: > | 800 use another character, use a single or double quoted string: > |
803 var dict = {'key with space': value} | 801 var dict = {'key with space': value} |
804 var dict = {"key\twith\ttabs": value} | 802 var dict = {"key\twith\ttabs": value} |
805 var dict = {'': value} # empty key | 803 var dict = {'': value} # empty key |
806 | 804 < *E1139* |
807 In case the key needs to be an expression, square brackets can be used, just | 805 In case the key needs to be an expression, square brackets can be used, just |
808 like in JavaScript: > | 806 like in JavaScript: > |
809 var dict = {["key" .. nr]: value} | 807 var dict = {["key" .. nr]: value} |
810 | 808 |
811 The key type can be string, number, bool or float. Other types result in an | 809 The key type can be string, number, bool or float. Other types result in an |
814 echo dict | 812 echo dict |
815 {'456': 'with', '123': 'without'} | 813 {'456': 'with', '123': 'without'} |
816 | 814 |
817 | 815 |
818 No :xit, :t, :k, :append, :change or :insert ~ | 816 No :xit, :t, :k, :append, :change or :insert ~ |
819 | 817 *E1100* |
820 These commands are too easily confused with local variable names. | 818 These commands are too easily confused with local variable names. |
821 Instead of `:x` or `:xit` you can use `:exit`. | 819 Instead of `:x` or `:xit` you can use `:exit`. |
822 Instead of `:t` you can use `:copy`. | 820 Instead of `:t` you can use `:copy`. |
823 Instead of `:k` you can use `:mark`. | 821 Instead of `:k` you can use `:mark`. |
824 | 822 |
1080 *E1003* *E1027* *E1056* *E1059* | 1078 *E1003* *E1027* *E1056* *E1059* |
1081 The type of value used with `:return` must match | 1079 The type of value used with `:return` must match |
1082 {return-type}. When {return-type} is omitted or is | 1080 {return-type}. When {return-type} is omitted or is |
1083 "void" the function is not expected to return | 1081 "void" the function is not expected to return |
1084 anything. | 1082 anything. |
1085 *E1077* | 1083 *E1077* *E1123* |
1086 {arguments} is a sequence of zero or more argument | 1084 {arguments} is a sequence of zero or more argument |
1087 declarations. There are three forms: | 1085 declarations. There are three forms: |
1088 {name}: {type} | 1086 {name}: {type} |
1089 {name} = {value} | 1087 {name} = {value} |
1090 {name}: {type} = {value} | 1088 {name}: {type} = {value} |
1098 used. Syntax and type errors will be produced at that | 1096 used. Syntax and type errors will be produced at that |
1099 time. | 1097 time. |
1100 | 1098 |
1101 It is possible to nest `:def` inside another `:def` or | 1099 It is possible to nest `:def` inside another `:def` or |
1102 `:function` up to about 50 levels deep. | 1100 `:function` up to about 50 levels deep. |
1103 | 1101 *E1117* |
1104 [!] is used as with `:function`. Note that | 1102 [!] is used as with `:function`. Note that |
1105 script-local functions cannot be deleted or redefined | 1103 script-local functions cannot be deleted or redefined |
1106 later in Vim9 script. They can only be removed by | 1104 later in Vim9 script. They can only be removed by |
1107 reloading the same script. | 1105 reloading the same script. |
1108 | 1106 |
1286 expected to always be the same. For example, when declaring a list: > | 1284 expected to always be the same. For example, when declaring a list: > |
1287 var l: list<number> = [1, g:two] | 1285 var l: list<number> = [1, g:two] |
1288 At compile time Vim doesn't know the type of "g:two" and the expression type | 1286 At compile time Vim doesn't know the type of "g:two" and the expression type |
1289 becomes list<any>. An instruction is generated to check the list type before | 1287 becomes list<any>. An instruction is generated to check the list type before |
1290 doing the assignment, which is a bit inefficient. | 1288 doing the assignment, which is a bit inefficient. |
1291 *type-casting* | 1289 *type-casting* *E1104* |
1292 To avoid this, use a type cast: > | 1290 To avoid this, use a type cast: > |
1293 var l: list<number> = [1, <number>g:two] | 1291 var l: list<number> = [1, <number>g:two] |
1294 The compiled code will then only check that "g:two" is a number and give an | 1292 The compiled code will then only check that "g:two" is a number and give an |
1295 error if it isn't. This is called type casting. | 1293 error if it isn't. This is called type casting. |
1296 | 1294 |
1331 list<func(...)> | 1329 list<func(...)> |
1332 | 1330 |
1333 For script-local variables in Vim9 script the type is checked, also when the | 1331 For script-local variables in Vim9 script the type is checked, also when the |
1334 variable was declared in a legacy function. | 1332 variable was declared in a legacy function. |
1335 | 1333 |
1334 When a type has been declared this is attached to a list or string. When | |
1335 later some expression attempts to change the type an error will be given: > | |
1336 var ll: list<number> = [1, 2, 3] | |
1337 ll->extend('x') # Error, 'x' is not a number | |
1338 | |
1339 If the type is inferred then the type is allowed to change: > | |
1340 [1, 2, 3]->extend('x') # result: [1, 2, 3, 'x'] | |
1341 | |
1336 | 1342 |
1337 Stricter type checking ~ | 1343 Stricter type checking ~ |
1338 *type-checking* | 1344 *type-checking* |
1339 In legacy Vim script, where a number was expected, a string would be | 1345 In legacy Vim script, where a number was expected, a string would be |
1340 automatically converted to a number. This was convenient for an actual number | 1346 automatically converted to a number. This was convenient for an actual number |
1345 In Vim9 script this has been made stricter. In most places it works just as | 1351 In Vim9 script this has been made stricter. In most places it works just as |
1346 before, if the value used matches the expected type. There will sometimes be | 1352 before, if the value used matches the expected type. There will sometimes be |
1347 an error, thus breaking backwards compatibility. For example: | 1353 an error, thus breaking backwards compatibility. For example: |
1348 - Using a number other than 0 or 1 where a boolean is expected. *E1023* | 1354 - Using a number other than 0 or 1 where a boolean is expected. *E1023* |
1349 - Using a string value when setting a number option. | 1355 - Using a string value when setting a number option. |
1350 - Using a number where a string is expected. *E1024* | 1356 - Using a number where a string is expected. *E1024* *E1105* |
1351 | 1357 |
1352 One consequence is that the item type of a list or dict given to |map()| must | 1358 One consequence is that the item type of a list or dict given to |map()| must |
1353 not change. This will give an error in Vim9 script: > | 1359 not change. This will give an error in Vim9 script: > |
1354 echo map([1, 2, 3], (i, v) => 'item ' .. i) | 1360 echo map([1, 2, 3], (i, v) => 'item ' .. i) |
1355 E1012: Type mismatch; expected number but got string | 1361 E1012: Type mismatch; expected number but got string |
1396 global namespace. If a file starts with: > | 1402 global namespace. If a file starts with: > |
1397 vim9script | 1403 vim9script |
1398 var myvar = 'yes' | 1404 var myvar = 'yes' |
1399 Then "myvar" will only exist in this file. While without `vim9script` it would | 1405 Then "myvar" will only exist in this file. While without `vim9script` it would |
1400 be available as `g:myvar` from any other script and function. | 1406 be available as `g:myvar` from any other script and function. |
1401 | 1407 *E1101* |
1402 The variables at the file level are very much like the script-local "s:" | 1408 The variables at the file level are very much like the script-local "s:" |
1403 variables in legacy Vim script, but the "s:" is omitted. And they cannot be | 1409 variables in legacy Vim script, but the "s:" is omitted. And they cannot be |
1404 deleted. | 1410 deleted. |
1405 | 1411 |
1406 In Vim9 script the global "g:" namespace can still be used as before. And the | 1412 In Vim9 script the global "g:" namespace can still be used as before. And the |
1464 In case the name is long or ambiguous, another name can be specified: > | 1470 In case the name is long or ambiguous, another name can be specified: > |
1465 import "thatscript.vim" as that | 1471 import "thatscript.vim" as that |
1466 < *E1060* | 1472 < *E1060* |
1467 Then you can use "that.EXPORTED_CONST", "that.someValue", etc. You are free | 1473 Then you can use "that.EXPORTED_CONST", "that.someValue", etc. You are free |
1468 to choose the name "that". Use something that will be recognized as referring | 1474 to choose the name "that". Use something that will be recognized as referring |
1469 to the imported script. Avoid command names and builtin function names, | 1475 to the imported script. Avoid command names, command modifiers and builtin |
1470 because the name will shadow them. If the name starts with a capital letter | 1476 function names, because the name will shadow them. |
1471 it can also shadow global user commands and functions. Also, you cannot use | 1477 If the name starts with a capital letter it can also shadow global user |
1472 the name for something else in the script, such as a function or variable | 1478 commands and functions. Also, you cannot use the name for something else in |
1473 name. | 1479 the script, such as a function or variable name. |
1474 | 1480 |
1475 In case the dot in the name is undesired, a local reference can be made for a | 1481 In case the dot in the name is undesired, a local reference can be made for a |
1476 function: > | 1482 function: > |
1477 var LongFunc = that.LongFuncName | 1483 var LongFunc = that.LongFuncName |
1478 | 1484 |
1745 Truthy. That is inconsistent. In Vim an empty list and dict are also | 1751 Truthy. That is inconsistent. In Vim an empty list and dict are also |
1746 Falsy. | 1752 Falsy. |
1747 - TypeScript has various "Readonly" types, which have limited usefulness, | 1753 - TypeScript has various "Readonly" types, which have limited usefulness, |
1748 since a type cast can remove the immutable nature. Vim locks the value, | 1754 since a type cast can remove the immutable nature. Vim locks the value, |
1749 which is more flexible, but is only checked at runtime. | 1755 which is more flexible, but is only checked at runtime. |
1756 - TypeScript has a complicated "import" statement that does not match how the | |
1757 Vim import mechanism works. A much simpler mechanism is used instead, which | |
1758 matches that the imported script is only sourced once. | |
1750 | 1759 |
1751 | 1760 |
1752 Declarations ~ | 1761 Declarations ~ |
1753 | 1762 |
1754 Legacy Vim script uses `:let` for every assignment, while in Vim9 declarations | 1763 Legacy Vim script uses `:let` for every assignment, while in Vim9 declarations |