Update runtime files
This commit is contained in:
Bram Moolenaar
@ -1,4 +1,4 @@
|
||||
*vim9.txt* For Vim version 8.2. Last change: 2020 May 09
|
||||
*vim9.txt* For Vim version 8.2. Last change: 2020 May 25
|
||||
|
||||
|
||||
VIM REFERENCE MANUAL by Bram Moolenaar
|
||||
@ -41,9 +41,10 @@ A secondary goal is to avoid Vim-specific constructs and get closer to
|
||||
commonly used programming languages, such as JavaScript, TypeScript and Java.
|
||||
|
||||
The performance improvements can only be achieved by not being 100% backwards
|
||||
compatible. For example, in a function the arguments are not available in the
|
||||
"a:" dictionary, because creating that dictionary adds quite a lot of
|
||||
overhead. Other differences are more subtle, such as how errors are handled.
|
||||
compatible. For example, making function arguments available in the
|
||||
"a:" dictionary adds quite a lot of overhead. In a Vim9 function this
|
||||
dictionary is not available. Other differences are more subtle, such as how
|
||||
errors are handled.
|
||||
|
||||
The Vim9 script syntax and semantics are used in:
|
||||
- a function defined with the `:def` command
|
||||
@ -79,12 +80,16 @@ Vim9 functions ~
|
||||
A function defined with `:def` is compiled. Execution is many times faster,
|
||||
often 10x to 100x times.
|
||||
|
||||
Many errors are already found when compiling, before the function is called.
|
||||
Many errors are already found when compiling, before the function is executed.
|
||||
The syntax is strict, to enforce code that is easy to read and understand.
|
||||
|
||||
`:def` has no extra arguments like `:function` does: "range", "abort", "dict"
|
||||
or "closure". A `:def` function always aborts on an error, does not get a
|
||||
range passed and cannot be a "dict" function.
|
||||
Compilation is done when the function is first called, or when the
|
||||
`:defcompile` command is encountered in the script where the function was
|
||||
defined.
|
||||
|
||||
`:def` has no options like `:function` does: "range", "abort", "dict" or
|
||||
"closure". A `:def` function always aborts on an error, does not get a range
|
||||
passed and cannot be a "dict" function.
|
||||
|
||||
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
|
||||
@ -118,8 +123,8 @@ search for the function in this order:
|
||||
- Local to the current scope and outer scopes up to the function scope.
|
||||
- Local to the current script file.
|
||||
- Imported functions, see `:import`.
|
||||
In all cases the function must be defined before used. To make a call cycle a
|
||||
global function needs to be used. (TODO: can we fix this?)
|
||||
In all cases the function must be defined before used. That is when it is
|
||||
first called or when `:defcompile` causes the call to be compiled.
|
||||
|
||||
The result is that functions and variables without a namespace can always be
|
||||
found in the script, either defined there or imported. Global functions and
|
||||
@ -127,57 +132,7 @@ variables could be defined anywhere (good luck finding where!).
|
||||
|
||||
Global functions can be 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.
|
||||
|
||||
|
||||
Four phases when loading a Vim9 script ~
|
||||
|
||||
In legacy script the functions are created when encountered, but parsed only
|
||||
when used. This allows for defining functions in any order and having them
|
||||
call each other, so long as the function is defined when it is called: >
|
||||
func One()
|
||||
call Two()
|
||||
endfunc
|
||||
func Two()
|
||||
if cond
|
||||
call One() " recursive call
|
||||
endif
|
||||
endfunc
|
||||
call One()
|
||||
|
||||
In Vim9 script the functions are compiled. When using the same functions as
|
||||
the above example it is not possible to compile function One without knowing
|
||||
that function Two exists. Or this would require a runtime check, which is slow
|
||||
and does not allow for compile time type checking.
|
||||
|
||||
When sourcing a Vim9 script this happens in four phases:
|
||||
1. Cleanup: If the script was sourced before all script-local variables,
|
||||
imports and functions are deleted.
|
||||
2. Discovery: The script is read and declarations of functions, imports and
|
||||
variables are recognized and the type is parsed. Variable initializers
|
||||
that are a constant are evaluated, this can also give the type of the
|
||||
variable.
|
||||
3. Compilation: Functions are compiled. The script-local functions, imports
|
||||
and variables from the discovery phase are found and types are checked.
|
||||
4. Execution: the commands in the script are executed, top to bottom.
|
||||
Functions are skipped over, they do do not need to be processed again.
|
||||
Variable initializers are evaluated when encountered. Note that if a
|
||||
function called earlier has set the value this will be over-written. It is
|
||||
best to declare variables before where they are used to avoid confusion.
|
||||
|
||||
The result is that items defined at the script level can be used anywhere in
|
||||
the script. This allows for putting the main function at the top: >
|
||||
def Main()
|
||||
SubOne()
|
||||
SubTwo()
|
||||
enddef
|
||||
def SubOne()
|
||||
...
|
||||
def SubTwo()
|
||||
...
|
||||
|
||||
Note that script-local variables should either have a type defined or have a
|
||||
constant initializer. Otherwise an error is given for the type being unknown.
|
||||
and cannot be deleted or replaced.
|
||||
|
||||
|
||||
Variable declarations with :let and :const ~
|
||||
@ -212,8 +167,8 @@ The declaration must be done earlier: >
|
||||
endif
|
||||
echo inner
|
||||
|
||||
To intentionally use a variable that won't be available later, a block can be
|
||||
used: >
|
||||
To intentionally avoid a variable being available later, a block can be used:
|
||||
>
|
||||
{
|
||||
let temp = 'temp'
|
||||
...
|
||||
@ -437,7 +392,9 @@ THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
|
||||
`:def`, but it is not possible to nest `:def` inside
|
||||
`:function`, for backwards compatibility.
|
||||
|
||||
[!] is used as with `:function`.
|
||||
[!] is used as with `:function`. Note that in Vim9
|
||||
script script-local functions cannot be deleted or
|
||||
redefined.
|
||||
|
||||
*:enddef*
|
||||
:enddef End of a function defined with `:def`.
|
||||
@ -448,6 +405,10 @@ variables can be accessed without the "s:" prefix. They must be defined
|
||||
before the function. If the script the function is defined in is legacy
|
||||
script, then script-local variables must be accessed with the "s:" prefix.
|
||||
|
||||
*:defc* *:defcompile*
|
||||
:defc[ompile] Compile functions defined in the current script that
|
||||
were not compiled yet.
|
||||
This will report errors found during the compilation.
|
||||
|
||||
*:disa* *:disassemble*
|
||||
:disa[ssemble] {func} Show the instructions generated for {func}.
|
||||
|
||||
Reference in New Issue
Block a user