/
vim9.txt
2241 lines (1882 loc) · 82.2 KB
/
vim9.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*vim9.txt* For Vim version 9.0. Last change: 2022 Nov 14
VIM REFERENCE MANUAL by Bram Moolenaar
Vim9 script commands and expressions. *Vim9* *vim9*
Most expression help is in |eval.txt|. This file is about the new syntax and
features in Vim9 script.
1. What is Vim9 script? |Vim9-script|
2. Differences |vim9-differences|
3. New style functions |fast-functions|
4. Types |vim9-types|
5. Namespace, Import and Export |vim9script|
6. Classes and interfaces |vim9-classes|
9. Rationale |vim9-rationale|
==============================================================================
1. What is Vim9 script? *Vim9-script*
Vim script has been growing over time, while preserving backwards
compatibility. That means bad choices from the past often can't be changed
and compatibility with Vi restricts possible solutions. Execution is quite
slow, each line is parsed every time it is executed.
The main goal of Vim9 script is to drastically improve performance. This is
accomplished by compiling commands into instructions that can be efficiently
executed. An increase in execution speed of 10 to 100 times can be expected.
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, 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
- a script file where the first command is `vim9script`
- an autocommand defined in the context of the above
- a command prefixed with the `vim9cmd` command modifier
When using `:function` in a Vim9 script file the legacy syntax is used, with
the highest |scriptversion|. However, this can be confusing and is therefore
discouraged.
Vim9 script and legacy Vim script can be mixed. There is no requirement to
rewrite old scripts, they keep working as before. You may want to use a few
`:def` functions for code that needs to be fast.
:vim9[cmd] {cmd} *:vim9* *:vim9cmd* *E1164*
Evaluate and execute {cmd} using Vim9 script syntax and
semantics. Useful when typing a command and in a legacy
script or function.
:leg[acy] {cmd} *:leg* *:legacy* *E1189* *E1234*
Evaluate and execute {cmd} using legacy script syntax and
semantics. Only useful in a Vim9 script or a :def function.
Note that {cmd} cannot use local variables, since it is parsed
with legacy expression syntax.
==============================================================================
2. Differences from legacy Vim script *vim9-differences*
Overview ~
*E1146*
Brief summary of the differences you will most often encounter when using Vim9
script and `:def` functions; details are below:
- Comments start with #, not ": >
echo "hello" # comment
- Using a backslash for line continuation is hardly ever needed: >
echo "hello "
.. yourName
.. ", how are you?"
- White space is required in many places to improve readability.
- Assign values without `:let` *E1126* , declare variables with `:var`: >
var count = 0
count += 3
- Constants can be declared with `:final` and `:const`: >
final matches = [] # add to the list later
const names = ['Betty', 'Peter'] # cannot be changed
- `:final` cannot be used as an abbreviation of `:finally`.
- Variables and functions are script-local by default.
- Functions are declared with argument types and return type: >
def CallMe(count: number, message: string): bool
- Call functions without `:call`: >
writefile(['done'], 'file.txt')
- You cannot use old Ex commands:
`:Print`
`:append`
`:change`
`:d` directly followed by 'd' or 'p'.
`:insert`
`:k`
`:mode`
`:open`
`:s` with only flags
`:t`
`:xit`
- Some commands, especially those used for flow control, cannot be shortened.
E.g., `:throw` cannot be written as `:th`. *vim9-no-shorten*
- You cannot use curly-braces names.
- A range before a command must be prefixed with a colon: >
:%s/this/that
- Executing a register with "@r" does not work, you can prepend a colon or use
`:exe`: >
:exe @a
- Unless mentioned specifically, the highest |scriptversion| is used.
- When defining an expression mapping, the expression will be evaluated in the
context of the script where it was defined.
Comments starting with # ~
In legacy Vim script comments start with double quote. In Vim9 script
comments start with #. >
# declarations
var count = 0 # number of occurrences
The reason is that a double quote can also be the start of a string. In many
places, especially halfway through an expression with a line break, it's hard
to tell what the meaning is, since both a string and a comment can be followed
by arbitrary text. To avoid confusion only # comments are recognized. This
is the same as in shell scripts and Python programs.
In Vi # is a command to list text with numbers. In Vim9 script you can use
`:number` for that. >
:101 number
To improve readability there must be a space between a command and the #
that starts a comment: >
var name = value # comment
var name = value# error!
< *E1170*
Do not start a comment with #{, it looks like the legacy dictionary literal
and produces an error where this might be confusing. #{{ or #{{{ are OK,
these can be used to start a fold.
When starting to read a script file Vim doesn't know it is |Vim9| script until
the `vim9script` command is found. Until that point you would need to use
legacy comments: >
" legacy comment
vim9script
# Vim9 comment
That looks ugly, better put `vim9script` in the very first line: >
vim9script
# Vim9 comment
In legacy Vim script # is also used for the alternate file name. In Vim9
script you need to use %% instead. Instead of ## use %%% (stands for all
arguments).
Vim9 functions ~
*E1099*
A function defined with `:def` is compiled. Execution is many times faster,
often 10 to 100 times.
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.
Compilation is done when any of these is encountered:
- the first time the function is called
- when the `:defcompile` command is encountered in the script after the
function was defined
- `:disassemble` is used for the function.
- a function that is compiled calls the function or uses it as a function
reference (so that the argument and return types can be checked)
*E1091* *E1191*
If compilation fails it is not tried again on the next call, instead this
error is given: "E1091: Function is not compiled: {name}".
Compilation will fail when encountering a user command that has not been
created yet. In this case you can call `execute()` to invoke it at runtime. >
def MyFunc()
execute('DefinedLater')
enddef
`:def` has no options like `:function` does: "range", "abort", "dict" or
"closure". A `:def` function always aborts on an error (unless `:silent!` was
used for the command or the error was caught a `:try` block), does not get a
range passed, cannot be a "dict" function, and can always be a closure.
*vim9-no-dict-function*
Later classes will be added, which replaces the "dict function" mechanism.
For now you will need to pass the dictionary explicitly: >
def DictFunc(self: dict<any>, arg: string)
echo self[arg]
enddef
var ad = {item: 'value', func: DictFunc}
ad.func(ad, 'item')
You can call a legacy dict function though: >
func Legacy() dict
echo self.value
endfunc
def CallLegacy()
var d = {func: Legacy, value: 'text'}
d.func()
enddef
< *E1096* *E1174* *E1175*
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* *E1160* *E1180*
Variable arguments are defined as the last argument, with a name and have a
list type, similar to TypeScript. For example, a list of numbers: >
def MyFunc(...itemlist: list<number>)
for item in itemlist
...
When a function argument is optional (it has a default value) passing `v:none`
as the argument results in using the default value. This is useful when you
want to specify a value for an argument that comes after an argument that
should use its default value. Example: >
def MyFunc(one = 'one', last = 'last')
...
enddef
MyFunc(v:none, 'LAST') # first argument uses default value 'one'
<
*vim9-ignored-argument* *E1181*
The argument "_" (an underscore) can be used to ignore the argument. This is
most useful in callbacks where you don't need it, but do need to give an
argument to match the call. E.g. when using map() two arguments are passed,
the key and the value, to ignore the key: >
map(numberList, (_, v) => v * 2)
There is no error for using the "_" argument multiple times. No type needs to
be given.
Functions and variables are script-local by default ~
*vim9-scopes*
When using `:function` or `:def` to specify a new function at the script level
in a Vim9 script, the function is local to the script. Like prefixing "s:" in
legacy script. To define a global function or variable the "g:" prefix must
be used. For functions in a script that is to be imported and in an autoload
script "export" needs to be used for those to be used elsewhere. >
def ThisFunction() # script-local
def g:ThatFunction() # global
export def Function() # for import and import autoload
< *E1058* *E1075*
When using `:function` or `:def` to specify a nested function inside a `:def`
function and no namespace was given, this nested function is local to the code
block it is defined in. It cannot be used in `function()` with a string
argument, pass the function reference itself: >
def Outer()
def Inner()
echo 'inner'
enddef
var Fok = function(Inner) # OK
var Fbad = function('Inner') # does not work
Detail: this is because "Inner" will actually become a function reference to a
function with a generated name.
It is not possible to define a script-local function in a function. You can
define a local function and assign it to a script-local funcref (it must have
been declared at the script level). It is possible to define a global
function by using the "g:" prefix.
When referring to a function and no "s:" or "g:" prefix is used, Vim will
search for the function:
- in the function scope, in block scopes
- in the script scope
Imported functions are found with the prefix from the `:import` command.
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
script "s:funcref" could be used, because it could not be referred to with
"funcref". In Vim9 script it can, therefore "s:Funcref" must be used to avoid
that the name interferes with builtin functions.
*vim9-s-namespace* *E1268*
The use of the "s:" prefix is not supported at the Vim9 script level. All
functions and variables without a prefix are script-local.
In :def functions the use of "s:" depends on the script: Script-local
variables and functions in a legacy script do use "s:", while in a Vim9 script
they do not use "s:". This matches what you see in the rest of the file.
In legacy functions the use of "s:" for script items is required, as before.
No matter if the script is Vim9 or legacy.
In all cases the function must be defined before used. That is when it is
called, when `:defcompile` causes it to be compiled, or when code that calls
it is being compiled (to figure out the return type).
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! You can
often see where it was last set using |:verbose|).
*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 by itself (it can be by reloading the
script).
When compiling a function and a function call is encountered for a function
that is not (yet) defined, the |FuncUndefined| autocommand is not triggered.
You can use an autoload function if needed, or call a legacy function and have
|FuncUndefined| triggered there.
Reloading a Vim9 script clears functions and variables by default ~
*vim9-reload* *E1149* *E1150*
When loading a legacy Vim script a second time nothing is removed, the
commands will replace existing variables and functions, create new ones, and
leave removed things hanging around.
When loading a Vim9 script a second time all existing script-local functions
and variables are deleted, thus you start with a clean slate. This is useful
if you are developing a plugin and want to try a new version. If you renamed
something you don't have to worry about the old name still hanging around.
If you do want to keep items, use: >
vim9script noclear
You want to use this in scripts that use a `finish` command to bail out at
some point when loaded again. E.g. when a buffer local option is set to a
function, the function does not need to be defined more than once: >
vim9script noclear
setlocal completefunc=SomeFunc
if exists('*SomeFunc')
finish
endif
def SomeFunc()
....
Variable declarations with :var, :final and :const ~
*vim9-declaration* *:var* *E1079*
*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.
Variables can be local to a script, function or code block: >
vim9script
var script_var = 123
def SomeFunc()
var func_var = script_var
if cond
var block_var = func_var
...
The variables are only visible in the block where they are defined and nested
blocks. Once the block ends the variable is no longer accessible: >
if cond
var inner = 5
else
var inner = 0
endif
echo inner # Error!
The declaration must be done earlier: >
var inner: number
if cond
inner = 5
else
inner = 0
endif
echo inner
Although this is shorter and faster for simple values: >
var inner = 0
if cond
inner = 5
endif
echo inner
< *E1025* *E1128*
To intentionally hide a variable from code that follows, a block can be
used: >
{
var temp = 'temp'
...
}
echo temp # Error!
This is especially useful in a user command: >
command -range Rename {
var save = @a
@a = 'some expression'
echo 'do something with ' .. @a
@a = save
}
And with autocommands: >
au BufWritePre *.go {
var save = winsaveview()
silent! exe ':%! some formatting command'
winrestview(save)
}
Although using a :def function probably works better.
*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
default to the number zero. For example, when declaring a list, items can be
added: >
var myList: list<number>
myList->add(7)
Initializing a variable to a null value, e.g. `null_list`, differs from not
initializing the variable. This throws an error: >
var myList = null_list
myList->add(7) # E1130: Cannot add to null list
< *E1016* *E1052* *E1066*
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`.
*E1065*
You cannot use `:va` to declare a variable, it must be written with the full
name `:var`. Just to make sure it is easy to read.
*E1178*
`:lockvar` does not work on local variables. Use `:const` and `:final`
instead.
The `exists()` and `exists_compiled()` functions do not work on local variables
or arguments.
*E1006* *E1041* *E1167* *E1168* *E1213*
Variables, functions and function arguments cannot shadow previously defined
or imported variables and functions in the same script file.
Variables may shadow Ex commands, rename the variable if needed.
Global variables must be prefixed with "g:", also at the script level. >
vim9script
var script_local = 'text'
g:global = 'value'
var Funcref = g:ThatFunction
Global functions must be prefixed with "g:": >
vim9script
def g:GlobalFunc(): string
return 'text'
enddef
echo g:GlobalFunc()
The "g:" prefix is not needed for auto-load functions.
*vim9-function-defined-later*
Although global functions can be called without the "g:" prefix, they must
exist when compiled. By adding the "g:" prefix the function can be defined
later. Example: >
def CallPluginFunc()
if exists('g:loaded_plugin')
g:PluginFunc()
endif
enddef
If you do it like this, you get an error at compile time that "PluginFunc"
does not exist, even when "g:loaded_plugin" does not exist: >
def CallPluginFunc()
if exists('g:loaded_plugin')
PluginFunc() # Error - function not found
endif
enddef
You can use exists_compiled() to avoid the error, but then the function would
not be called, even when "g:loaded_plugin" is defined later: >
def CallPluginFunc()
if exists_compiled('g:loaded_plugin')
PluginFunc() # Function may never be called
endif
enddef
Since `&opt = value` is now assigning a value to option "opt", ":&" cannot be
used to repeat a `:substitute` command.
*vim9-unpack-ignore*
For an unpack assignment the underscore can be used to ignore a list item,
similar to how a function argument can be ignored: >
[a, _, c] = theList
To ignore any remaining items: >
[a, b; _] = longList
< *E1163* *E1080*
Declaring more than one variable at a time, using the unpack notation, is
possible. Each variable can have a type or infer it from the value: >
var [v1: number, v2] = GetValues()
Use this only when there is a list with values, declaring one variable per
line is much easier to read and change later.
Constants ~
*vim9-const* *vim9-final*
How constants work varies between languages. Some consider a variable that
can't be assigned another value a constant. JavaScript is an example. Others
also make the value immutable, thus when a constant uses a list, the list
cannot be changed. In Vim9 we can use both.
*E1021* *E1307*
`:const` is used for making both the variable and the value a constant. Use
this for composite structures that you want to make sure will not be modified.
Example: >
const myList = [1, 2]
myList = [3, 4] # Error!
myList[0] = 9 # Error!
myList->add(3) # Error!
< *: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]
myList = [3, 4] # Error!
myList[0] = 9 # OK
myList->add(3) # OK
It is common to write constants as ALL_CAPS, but you don't have to.
The constant only applies to the value itself, not what it refers to. >
final females = ["Mary"]
const NAMES = [["John", "Peter"], females]
NAMES[0] = ["Jack"] # Error!
NAMES[0][0] = "Jack" # Error!
NAMES[1] = ["Emma"] # Error!
NAMES[1][0] = "Emma" # OK, now females[0] == "Emma"
Omitting :call and :eval ~
*E1190*
Functions can be called without `:call`: >
writefile(lines, 'file')
Using `:call` is still possible, but this is discouraged.
A method call without `eval` is possible, so long as the start is an
identifier or can't be an Ex command. For a function either "(" or "->" must
be following, without a line break. Examples: >
myList->add(123)
g:myList->add(123)
[1, 2, 3]->Process()
{a: 1, b: 2}->Process()
"foobar"->Process()
("foobar")->Process()
'foobar'->Process()
('foobar')->Process()
In the rare case there is ambiguity between a function name and an Ex command,
prepend ":" to make clear you want to use the Ex command. For example, there
is both the `:substitute` command and the `substitute()` function. When the
line starts with `substitute(` this will use the function. Prepend a colon to
use the command instead: >
:substitute(pattern (replacement (
If the expression starts with "!" this is interpreted as a shell command, not
negation of a condition. Thus this is a shell command: >
!shellCommand->something
Put the expression in parentheses to use the "!" for negation: >
(!expression)->Method()
Note that while variables need to be defined before they can be used,
functions can be called before being defined. This is required to allow
for cyclic dependencies between functions. It is slightly less efficient,
since the function has to be looked up by name. And a typo in the function
name will only be found when the function is called.
Omitting function() ~
A user defined function can be used as a function reference in an expression
without `function()`. The argument types and return type will then be checked.
The function must already have been defined. >
var Funcref = MyFunction
When using `function()` the resulting type is "func", a function with any
number of arguments and any return type (including void). The function can be
defined later if the argument is in quotes.
Lambda using => instead of -> ~
*vim9-lambda*
In legacy script there can be confusion between using "->" for a method call
and for a lambda. Also, when a "{" is found the parser needs to figure out if
it is the start of a lambda or a dictionary, which is now more complicated
because of the use of argument types.
To avoid these problems Vim9 script uses a different syntax for a lambda,
which is similar to JavaScript: >
var Lambda = (arg) => expression
var Lambda = (arg): type => expression
< *E1157*
No line break is allowed in the arguments of a lambda up to and including the
"=>" (so that Vim can tell the difference between an expression in parentheses
and lambda arguments). This is OK: >
filter(list, (k, v) =>
v > 0)
This does not work: >
filter(list, (k, v)
=> v > 0)
This also does not work: >
filter(list, (k,
v) => v > 0)
But you can use a backslash to concatenate the lines before parsing: >
filter(list, (k,
\ v)
\ => v > 0)
< *vim9-lambda-arguments* *E1172*
In legacy script a lambda could be called with any number of extra arguments,
there was no way to warn for not using them. In Vim9 script the number of
arguments must match. If you do want to accept any arguments, or any further
arguments, use "..._", which makes the function accept
|vim9-variable-arguments|. Example: >
var Callback = (..._) => 'anything'
echo Callback(1, 2, 3) # displays "anything"
< *inline-function* *E1171*
Additionally, a lambda can contain statements in {}: >
var Lambda = (arg) => {
g:was_called = 'yes'
return expression
}
This can be useful for a timer, for example: >
var count = 0
var timer = timer_start(500, (_) => {
count += 1
echom 'Handler called ' .. count
}, {repeat: 3})
The ending "}" must be at the start of a line. It can be followed by other
characters, e.g.: >
var d = mapnew(dict, (k, v): string => {
return 'value'
})
No command can follow the "{", only a comment can be used there.
*command-block* *E1026*
The block can also be used for defining a user command. Inside the block Vim9
syntax will be used.
If the statements include a dictionary, its closing bracket must not be
written at the start of a line. Otherwise, it would be parsed as the end of
the block. This does not work: >
command NewCommand {
g:mydict = {
'key': 'value',
} # ERROR: will be recognized as the end of the block
}
Put the '}' after the last item to avoid this: >
command NewCommand {
g:mydict = {
'key': 'value' }
}
Rationale: The "}" cannot be after a command because it would require parsing
the commands to find it. For consistency with that no command can follow the
"{". Unfortunately this means using "() => { command }" does not work, line
breaks are always required.
*vim9-curly*
To avoid the "{" of a dictionary literal to be recognized as a statement block
wrap it in parentheses: >
var Lambda = (arg) => ({key: 42})
Also when confused with the start of a command block: >
({
key: value
})->method()
Automatic 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: >
var mylist = [
'one',
'two',
]
And when a dict spans multiple lines: >
var mydict = {
one: 1,
two: 2,
}
With a function call: >
var result = Func(
arg1,
arg2
)
For binary operators in expressions not in [], {} or () a line break is
possible just before or after the operator. For example: >
var text = lead
.. middle
.. end
var total = start +
end -
correction
var result = positive
? PosFunc(arg)
: NegFunc(arg)
For a method call using "->" and a member using a dot, a line break is allowed
before it: >
var result = GetBuilder()
->BuilderSetWidth(333)
->BuilderSetHeight(777)
->BuilderBuild()
var result = MyDict
.member
For commands that have an argument that is a list of commands, the | character
at the start of the line indicates line continuation: >
autocmd BufNewFile *.match if condition
| echo 'match'
| endif
Note that this means that in heredoc the first line cannot start with a bar: >
var lines =<< trim END
| this doesn't work
END
Either use an empty line at the start or do not use heredoc. Or temporarily
add the "C" flag to 'cpoptions': >
set cpo+=C
var lines =<< trim END
| this works
END
set cpo-=C
If the heredoc is inside a function 'cpoptions' must be set before :def and
restored after the :enddef.
In places where line continuation with a backslash is still needed, such as
splitting up a long Ex command, comments can start with '#\ ': >
syn region Text
\ start='foo'
#\ comment
\ end='bar'
Like with legacy script '"\ ' is used. This is also needed when line
continuation is used without a backslash and a line starts with a bar: >
au CursorHold * echom 'BEFORE bar'
#\ some comment
| echom 'AFTER bar'
<
*E1050*
To make it possible for the operator at the start of the line to be
recognized, it is required to put a colon before a range. This example will
add "start" and print: >
var result = start
+ print
Like this: >
var result = start + print
This will assign "start" and print a line: >
var result = start
:+ print
After the range an Ex command must follow. Without the colon you can call a
function without `:call`, but after a range you do need it: >
MyFunc()
:% call MyFunc()
Note that the colon is not required for the |+cmd| argument: >
edit +6 fname
It is also possible to split a function header over multiple lines, in between
arguments: >
def MyFunc(
text: string,
separator = '-'
): string
Since a continuation line cannot be easily recognized the parsing of commands
has been made stricter. E.g., because of the error in the first line, the
second line is seen as a separate command: >
popup_create(some invalid expression, {
exit_cb: Func})
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.
Notes:
- "enddef" cannot be used at the start of a continuation line, it ends the
current function.
- No line break is allowed in the LHS of an assignment. Specifically when
unpacking a list |:let-unpack|. This is OK: >
[var1, var2] =
Func()
< This does not work: >
[var1,
var2] =
Func()
- No line break is allowed in between arguments of an `:echo`, `:execute` and
similar commands. This is OK: >
echo [1,
2] [3,
4]
< This does not work: >
echo [1, 2]
[3, 4]
- In some cases it is difficult for Vim to parse a command, especially when
commands are used as an argument to another command, such as `windo`. In
those cases the line continuation with a backslash has to be used.
White space ~
*E1004* *E1068* *E1069* *E1074* *E1127* *E1202*
Vim9 script enforces proper use of white space. This is no longer allowed: >
var name=234 # Error!
var name= 234 # Error!
var name =234 # Error!
There must be white space before and after the "=": >
var name = 234 # OK
White space must also be put before the # that starts a comment after a
command: >
var name = 234# Error!
var name = 234 # OK
White space is required around most operators.
White space is required in a sublist (list slice) around the ":", except at
the start and end: >
otherlist = mylist[v : count] # v:count has a different meaning
otherlist = mylist[:] # make a copy of the List
otherlist = mylist[v :]
otherlist = mylist[: v]
White space is not allowed:
- Between a function name and the "(": >
Func (arg) # Error!
Func
\ (arg) # Error!
Func
(arg) # Error!
Func(arg) # OK
Func(
arg) # OK
Func(
arg # OK
)
< *E1205*
White space is not allowed in a `:set` command between the option name and a
following "&", "!", "<", "=", "+=", "-=" or "^=".
No curly braces expansion ~
|curly-braces-names| cannot be used.
Command modifiers are not ignored ~
*E1176*
Using a command modifier for a command that does not use it gives an error.
*E1082*
Also, using a command modifier without a following command is now an error.
Dictionary literals ~
*vim9-literal-dict* *E1014*
Traditionally Vim has supported dictionary literals with a {} syntax: >
let dict = {'key': value}
Later it became clear that using a simple text key is very common, thus
literal dictionaries were introduced in a backwards compatible way: >
let dict = #{key: value}
However, this #{} syntax is unlike any existing language. As it turns out
that using a literal key is much more common than using an expression, and
considering that JavaScript uses this syntax, using the {} form for dictionary
literals is considered a much more useful syntax. In Vim9 script the {} form
uses literal keys: >
var dict = {key: value}
This works for alphanumeric characters, underscore and dash. If you want to
use another character, use a single or double quoted string: >
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}
The key type can be string, number, bool or float. Other types result in an
error. Without using [] the value is used as a string, keeping leading zeros.
An expression given with [] is evaluated and then converted to a string.
Leading zeros will then be dropped: >
var dict = {000123: 'without', [000456]: 'with'}
echo dict
{'456': 'with', '000123': 'without'}
A float only works inside [] because the dot is not accepted otherwise: >
var dict = {[00.013]: 'float'}
echo dict
{'0.013': 'float'}
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`.
Instead of `:k` you can use `:mark`.
Comparators ~
The 'ignorecase' option is not used for comparators that use strings.
Thus "=~" works like "=~#".
"is" and "isnot" (|expr-is| and |expr-isnot|) when used on strings now return
false. In legacy script they just compare the strings, in |Vim9| script they
check identity, and strings are copied when used, thus two strings are never
the same (this might change some day if strings are not copied but reference
counted).
Abort after error ~
In legacy script, when an error is encountered, Vim continues to execute
following lines. This can lead to a long sequence of errors and need to type
CTRL-C to stop it. In Vim9 script execution of commands stops at the first
error. Example: >
vim9script
var x = does-not-exist
echo 'not executed'
For loop ~
*E1254*
The loop variable must not be declared yet: >
var i = 1
for i in [1, 2, 3] # Error!
It is possible to use a global variable though: >
g:i = 1
for g:i in [1, 2, 3]
echo g:i
endfor
Legacy Vim script has some tricks to make a for loop over a list handle
deleting items at the current or previous item. In Vim9 script it just uses
the index, if items are deleted then items in the list will be skipped.
Example legacy script: >
let l = [1, 2, 3, 4]
for i in l
echo i
call remove(l, index(l, i))
endfor
Would echo:
1
2
3
4
In compiled Vim9 script you get:
1
3
Generally, you should not change the list that is iterated over. Make a copy
first if needed.
When looping over a list of lists, the nested lists can be changed. The loop
variable is "final", it cannot be changed but what its value can be changed.
*E1306*
The depth of loops, :for and :while loops added together, cannot exceed 10.
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 ~
0 falsy falsy
1 truthy truthy
99 truthy Error!
"0" falsy Error!
"99" truthy Error!
"text" falsy Error!
For the "??" operator and when using "!" then there is no error, every value
is either falsy or truthy. This is mostly like JavaScript, except that an
empty list and dict is falsy:
type truthy when ~
bool true, v:true or 1
number non-zero
float non-zero
string non-empty
blob non-empty
list non-empty (different from JavaScript)
dictionary non-empty (different from JavaScript)
func when there is a function name
special true or v:true
job when not NULL
channel when not NULL
class when not NULL
object when not NULL (TODO: when isTrue() returns true)