Mercurial > vim

comparison runtime/doc/vim9.txt @ 20552:74e3316c1d5a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update runtime files Commit: https://github.com/vim/vim/commit/388a5d4f20b4b64341d1604aa238cab85827b892 Author: Bram Moolenaar <Bram@vim.org> Date: Tue May 26 21:20:45 2020 +0200 Update runtime files
author Bram Moolenaar <Bram@vim.org>
date Tue, 26 May 2020 21:30:04 +0200
parents 7f88f6a3ed4c
children 83cfa1ef1bf2
comparison
equal deleted inserted replaced
20551:f1b23a9643fe 20552:74e3316c1d5a
1 *vim9.txt* For Vim version 8.2. Last change: 2020 May 09 1 *vim9.txt* For Vim version 8.2. Last change: 2020 May 25
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
39 39
40 A secondary goal is to avoid Vim-specific constructs and get closer to 40 A secondary goal is to avoid Vim-specific constructs and get closer to
41 commonly used programming languages, such as JavaScript, TypeScript and Java. 41 commonly used programming languages, such as JavaScript, TypeScript and Java.
42 42
43 The performance improvements can only be achieved by not being 100% backwards 43 The performance improvements can only be achieved by not being 100% backwards
44 compatible. For example, in a function the arguments are not available in the 44 compatible. For example, making function arguments available in the
45 "a:" dictionary, because creating that dictionary adds quite a lot of 45 "a:" dictionary adds quite a lot of overhead. In a Vim9 function this
46 overhead. Other differences are more subtle, such as how errors are handled. 46 dictionary is not available. Other differences are more subtle, such as how
47 errors are handled.
47 48
48 The Vim9 script syntax and semantics are used in: 49 The Vim9 script syntax and semantics are used in:
49 - a function defined with the `:def` command 50 - a function defined with the `:def` command
50 - a script file where the first command is `vim9script` 51 - a script file where the first command is `vim9script`
51 52
77 Vim9 functions ~ 78 Vim9 functions ~
78 79
79 A function defined with `:def` is compiled. Execution is many times faster, 80 A function defined with `:def` is compiled. Execution is many times faster,
80 often 10x to 100x times. 81 often 10x to 100x times.
81 82
82 Many errors are already found when compiling, before the function is called. 83 Many errors are already found when compiling, before the function is executed.
83 The syntax is strict, to enforce code that is easy to read and understand. 84 The syntax is strict, to enforce code that is easy to read and understand.
84 85
85 `:def` has no extra arguments like `:function` does: "range", "abort", "dict" 86 Compilation is done when the function is first called, or when the
86 or "closure". A `:def` function always aborts on an error, does not get a 87 `:defcompile` command is encountered in the script where the function was
87 range passed and cannot be a "dict" function. 88 defined.
89
90 `:def` has no options like `:function` does: "range", "abort", "dict" or
91 "closure". A `:def` function always aborts on an error, does not get a range
92 passed and cannot be a "dict" function.
88 93
89 The argument types and return type need to be specified. The "any" type can 94 The argument types and return type need to be specified. The "any" type can
90 be used, type checking will then be done at runtime, like with legacy 95 be used, type checking will then be done at runtime, like with legacy
91 functions. 96 functions.
92 97
116 When referring to a function and no "s:" or "g:" prefix is used, Vim will 121 When referring to a function and no "s:" or "g:" prefix is used, Vim will
117 search for the function in this order: 122 search for the function in this order:
118 - Local to the current scope and outer scopes up to the function scope. 123 - Local to the current scope and outer scopes up to the function scope.
119 - Local to the current script file. 124 - Local to the current script file.
120 - Imported functions, see `:import`. 125 - Imported functions, see `:import`.
121 In all cases the function must be defined before used. To make a call cycle a 126 In all cases the function must be defined before used. That is when it is
122 global function needs to be used. (TODO: can we fix this?) 127 first called or when `:defcompile` causes the call to be compiled.
123 128
124 The result is that functions and variables without a namespace can always be 129 The result is that functions and variables without a namespace can always be
125 found in the script, either defined there or imported. Global functions and 130 found in the script, either defined there or imported. Global functions and
126 variables could be defined anywhere (good luck finding where!). 131 variables could be defined anywhere (good luck finding where!).
127 132
128 Global functions can be still be defined and deleted at nearly any time. In 133 Global functions can be still be defined and deleted at nearly any time. In
129 Vim9 script script-local functions are defined once when the script is sourced 134 Vim9 script script-local functions are defined once when the script is sourced
130 and cannot be deleted. 135 and cannot be deleted or replaced.
131
132
133 Four phases when loading a Vim9 script ~
134
135 In legacy script the functions are created when encountered, but parsed only
136 when used. This allows for defining functions in any order and having them
137 call each other, so long as the function is defined when it is called: >
138 func One()
139 call Two()
140 endfunc
141 func Two()
142 if cond
143 call One() " recursive call
144 endif
145 endfunc
146 call One()
147
148 In Vim9 script the functions are compiled. When using the same functions as
149 the above example it is not possible to compile function One without knowing
150 that function Two exists. Or this would require a runtime check, which is slow
151 and does not allow for compile time type checking.
152
153 When sourcing a Vim9 script this happens in four phases:
154 1. Cleanup: If the script was sourced before all script-local variables,
155 imports and functions are deleted.
156 2. Discovery: The script is read and declarations of functions, imports and
157 variables are recognized and the type is parsed. Variable initializers
158 that are a constant are evaluated, this can also give the type of the
159 variable.
160 3. Compilation: Functions are compiled. The script-local functions, imports
161 and variables from the discovery phase are found and types are checked.
162 4. Execution: the commands in the script are executed, top to bottom.
163 Functions are skipped over, they do do not need to be processed again.
164 Variable initializers are evaluated when encountered. Note that if a
165 function called earlier has set the value this will be over-written. It is
166 best to declare variables before where they are used to avoid confusion.
167
168 The result is that items defined at the script level can be used anywhere in
169 the script. This allows for putting the main function at the top: >
170 def Main()
171 SubOne()
172 SubTwo()
173 enddef
174 def SubOne()
175 ...
176 def SubTwo()
177 ...
178
179 Note that script-local variables should either have a type defined or have a
180 constant initializer. Otherwise an error is given for the type being unknown.
181 136
182 137
183 Variable declarations with :let and :const ~ 138 Variable declarations with :let and :const ~
184 139
185 Local variables need to be declared with `:let`. Local constants need to be 140 Local variables need to be declared with `:let`. Local constants need to be
210 else 165 else
211 inner = 0 166 inner = 0
212 endif 167 endif
213 echo inner 168 echo inner
214 169
215 To intentionally use a variable that won't be available later, a block can be 170 To intentionally avoid a variable being available later, a block can be used:
216 used: > 171 >
217 { 172 {
218 let temp = 'temp' 173 let temp = 'temp'
219 ... 174 ...
220 } 175 }
221 echo temp " Error! 176 echo temp " Error!
435 390
436 NOTE: It is possible to nest `:def` inside another 391 NOTE: It is possible to nest `:def` inside another
437 `:def`, but it is not possible to nest `:def` inside 392 `:def`, but it is not possible to nest `:def` inside
438 `:function`, for backwards compatibility. 393 `:function`, for backwards compatibility.
439 394
440 [!] is used as with `:function`. 395 [!] is used as with `:function`. Note that in Vim9
396 script script-local functions cannot be deleted or
397 redefined.
441 398
442 *:enddef* 399 *:enddef*
443 :enddef End of a function defined with `:def`. 400 :enddef End of a function defined with `:def`.
444 401
445 402
446 If the script the function is defined in is Vim9 script, then script-local 403 If the script the function is defined in is Vim9 script, then script-local
447 variables can be accessed without the "s:" prefix. They must be defined 404 variables can be accessed without the "s:" prefix. They must be defined
448 before the function. If the script the function is defined in is legacy 405 before the function. If the script the function is defined in is legacy
449 script, then script-local variables must be accessed with the "s:" prefix. 406 script, then script-local variables must be accessed with the "s:" prefix.
450 407
408 *:defc* *:defcompile*
409 :defc[ompile] Compile functions defined in the current script that
410 were not compiled yet.
411 This will report errors found during the compilation.
451 412
452 *:disa* *:disassemble* 413 *:disa* *:disassemble*
453 :disa[ssemble] {func} Show the instructions generated for {func}. 414 :disa[ssemble] {func} Show the instructions generated for {func}.
454 This is for debugging and testing. 415 This is for debugging and testing.
455 Note that for command line completion of {func} you 416 Note that for command line completion of {func} you