Mercurial > vim
diff 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 |
line wrap: on
line diff
--- a/runtime/doc/vim9.txt +++ b/runtime/doc/vim9.txt @@ -1,4 +1,4 @@ -*vim9.txt* For Vim version 8.2. Last change: 2022 Jan 23 +*vim9.txt* For Vim version 8.2. Last change: 2022 Jan 29 VIM REFERENCE MANUAL by Bram Moolenaar @@ -82,7 +82,7 @@ script and `:def` functions; details are .. yourName .. ", how are you?" - White space is required in many places to improve readability. -- Assign values without `:let`, declare variables with `:var`: > +- Assign values without `:let` *E1126* , declare variables with `:var`: > var count = 0 count += 3 - Constants can be declared with `:final` and `:const`: > @@ -139,7 +139,7 @@ arguments). Vim9 functions ~ - + *E1099* A function defined with `:def` is compiled. Execution is many times faster, often 10 to 100 times. @@ -183,11 +183,11 @@ You can call a legacy dict function thou var d = {func: Legacy, value: 'text'} d.func() enddef - +< *E1096* The argument types and return type need to be specified. The "any" type can be used, type checking will then be done at runtime, like with legacy functions. - + *E1106* Arguments are accessed by name, without "a:", just like any other language. There is no "a:" dictionary or "a:000" list. *vim9-variable-arguments* *E1055* @@ -238,9 +238,6 @@ When referring to a function and no "s:" search for the function: - in the function scope, in block scopes - in the script scope, possibly imported -- in the list of global functions -However, it is recommended to always use "g:" to refer to a global function -for clarity. Since a script-local function reference can be used without "s:" the name must start with an upper case letter even when using the "s:" prefix. In legacy @@ -255,7 +252,7 @@ it is being compiled (to figure out the The result is that functions and variables without a namespace can usually be found in the script, either defined there or imported. Global functions and variables could be defined anywhere (good luck finding out where!). - + *E1102* Global functions can still be defined and deleted at nearly any time. In Vim9 script script-local functions are defined once when the script is sourced and cannot be deleted or replaced. @@ -289,8 +286,8 @@ some point when loaded again. E.g. when Variable declarations with :var, :final and :const ~ - *vim9-declaration* *:var* - *E1017* *E1020* *E1054* + *vim9-declaration* *:var* + *E1017* *E1020* *E1054* *E1087* *E1108* *E1124* Local variables need to be declared with `:var`. Local constants need to be declared with `:final` or `:const`. We refer to both as "variables" in this section. @@ -321,7 +318,7 @@ The declaration must be done earlier: > inner = 0 endif echo inner -< *E1025* +< *E1025* *E1128* To intentionally hide a variable from code that follows, a block can be used: > { @@ -348,7 +345,7 @@ And with autocommands: > } Although using a :def function probably works better. - *E1022* + *E1022* *E1103* *E1130* *E1131* *E1133* *E1134* Declaring a variable with a type but without an initializer will initialize to false (for bool), empty (for string, list, dict, etc.) or zero (for number, any, etc.). This matters especially when using the "any" type, the value will @@ -440,7 +437,7 @@ Example: > myList = [3, 4] # Error! myList[0] = 9 # Error! myList->add(3) # Error! -< *:final* +< *:final* *E1125* `:final` is used for making only the variable a constant, the value can be changed. This is well known from Java. Example: > final myList = [1, 2] @@ -600,7 +597,7 @@ Also when confused with the start of a c Automatic line continuation ~ - *vim9-line-continuation* + *vim9-line-continuation* *E1097* 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: > @@ -708,6 +705,7 @@ second line is seen as a separate comman Now "exit_cb: Func})" is actually a valid command: save any changes to the file "_cb: Func})" and exit. To avoid this kind of mistake in Vim9 script there must be white space between most command names and the argument. +*E1144* However, the argument of a command that is a command won't be recognized. For example, after "windo echo expr" a line break inside "expr" will not be seen. @@ -738,7 +736,7 @@ Notes: White space ~ - *E1004* *E1068* *E1069* *E1074* + *E1004* *E1068* *E1069* *E1074* *E1127* Vim9 script enforces proper use of white space. This is no longer allowed: > var name=234 # Error! var name= 234 # Error! @@ -803,7 +801,7 @@ use another character, use a single or d var dict = {'key with space': value} var dict = {"key\twith\ttabs": value} var dict = {'': value} # empty key - +< *E1139* In case the key needs to be an expression, square brackets can be used, just like in JavaScript: > var dict = {["key" .. nr]: value} @@ -816,7 +814,7 @@ error. A number can be given with and w No :xit, :t, :k, :append, :change or :insert ~ - + *E1100* These commands are too easily confused with local variable names. Instead of `:x` or `:xit` you can use `:exit`. Instead of `:t` you can use `:copy`. @@ -1082,7 +1080,7 @@ 3. New style functions *fast-functio {return-type}. When {return-type} is omitted or is "void" the function is not expected to return anything. - *E1077* + *E1077* *E1123* {arguments} is a sequence of zero or more argument declarations. There are three forms: {name}: {type} @@ -1100,7 +1098,7 @@ 3. New style functions *fast-functio It is possible to nest `:def` inside another `:def` or `:function` up to about 50 levels deep. - + *E1117* [!] is used as with `:function`. Note that script-local functions cannot be deleted or redefined later in Vim9 script. They can only be removed by @@ -1288,7 +1286,7 @@ expected to always be the same. For exa At compile time Vim doesn't know the type of "g:two" and the expression type becomes list<any>. An instruction is generated to check the list type before doing the assignment, which is a bit inefficient. - *type-casting* + *type-casting* *E1104* To avoid this, use a type cast: > var l: list<number> = [1, <number>g:two] The compiled code will then only check that "g:two" is a number and give an @@ -1333,6 +1331,14 @@ Results in: For script-local variables in Vim9 script the type is checked, also when the variable was declared in a legacy function. +When a type has been declared this is attached to a list or string. When +later some expression attempts to change the type an error will be given: > + var ll: list<number> = [1, 2, 3] + ll->extend('x') # Error, 'x' is not a number + +If the type is inferred then the type is allowed to change: > + [1, 2, 3]->extend('x') # result: [1, 2, 3, 'x'] + Stricter type checking ~ *type-checking* @@ -1347,7 +1353,7 @@ before, if the value used matches the ex an error, thus breaking backwards compatibility. For example: - Using a number other than 0 or 1 where a boolean is expected. *E1023* - Using a string value when setting a number option. -- Using a number where a string is expected. *E1024* +- Using a number where a string is expected. *E1024* *E1105* One consequence is that the item type of a list or dict given to |map()| must not change. This will give an error in Vim9 script: > @@ -1398,7 +1404,7 @@ global namespace. If a file starts with var myvar = 'yes' Then "myvar" will only exist in this file. While without `vim9script` it would be available as `g:myvar` from any other script and function. - + *E1101* The variables at the file level are very much like the script-local "s:" variables in legacy Vim script, but the "s:" is omitted. And they cannot be deleted. @@ -1466,11 +1472,11 @@ In case the name is long or ambiguous, a < *E1060* Then you can use "that.EXPORTED_CONST", "that.someValue", etc. You are free to choose the name "that". Use something that will be recognized as referring -to the imported script. Avoid command names and builtin function names, -because the name will shadow them. If the name starts with a capital letter -it can also shadow global user commands and functions. Also, you cannot use -the name for something else in the script, such as a function or variable -name. +to the imported script. Avoid command names, command modifiers and builtin +function names, because the name will shadow them. +If the name starts with a capital letter it can also shadow global user +commands and functions. Also, you cannot use the name for something else in +the script, such as a function or variable name. In case the dot in the name is undesired, a local reference can be made for a function: > @@ -1747,6 +1753,9 @@ Specific items from TypeScript we avoid: - TypeScript has various "Readonly" types, which have limited usefulness, since a type cast can remove the immutable nature. Vim locks the value, which is more flexible, but is only checked at runtime. +- TypeScript has a complicated "import" statement that does not match how the + Vim import mechanism works. A much simpler mechanism is used instead, which + matches that the imported script is only sourced once. Declarations ~