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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
|
*vim9.txt* For Vim version 8.2. Last change: 2020 Sep 26
VIM REFERENCE MANUAL by Bram Moolenaar
THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
Vim9 script commands and expressions. *vim9*
Most expression help is in |eval.txt|. This file is about the new syntax and
features in Vim9 script.
THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
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. Future work: classes |vim9-classes|
9. Rationale |vim9-rationale|
==============================================================================
1. What is Vim9 script? *vim9-script*
THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
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
When using `:function` in a Vim9 script file the legacy syntax is used.
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.
==============================================================================
2. Differences from legacy Vim script *vim9-differences*
THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
Overview ~
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.
- Assign values without `:let`, declare variables with `:var`: >
var count = 0
count += 3
- Constants can be declared with `:final` and `:const`: >
final matches = [] # add matches
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 `:xit`, `:t`, `:append`, `:change`, `:insert` or curly-braces
names.
- A range before a command must be prefixed with a colon: >
:%s/this/that
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. Note that #{ is the start of a dictionary, therefore
it does not start a comment.
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 executed.
The syntax is strict, to enforce code that is easy to read and understand.
Compilation is done when:
- the function is first called
- when the `:defcompile` command is encountered in the script where 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
`: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
functions.
Arguments are accessed by name, without "a:", just like any other language.
There is no "a:" dictionary or "a:000" list.
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
...
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, as if "s:" was
prefixed. Using the "s:" prefix is optional. To define a global function or
variable the "g:" prefix must be used. For functions in an autoload script
the "name#" prefix is sufficient. >
def ThisFunction() # script-local
def s:ThisFunction() # script-local
def g:ThatFunction() # global
def scriptname#function() # autoload
When using `:function` or `:def` to specify a nested function inside a `:def`
function, this nested function is local to the code block it is defined in.
In a `:def` function it is not possible to define a script-local function. 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 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.
In all cases the function must be defined before used. That is when it is
called, when `:defcompile` causes the 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!).
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.
Variable declarations with :var, :final and :const ~
*vim9-declaration* *:var*
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
To intentionally hide a variable from code that follows, a block can be
used: >
{
var temp = 'temp'
...
}
echo temp # Error!
Declaring a variable with a type but without an initializer will initialize to
zero, false or empty.
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. They can also be deleted
with `:unlet`.
Variables and functions cannot shadow previously defined or imported variables
and functions.
Variables may shadow Ex commands, rename the variable if needed.
Global variables and user defined functions must be prefixed with "g:", also
at the script level. >
vim9script
var script_local = 'text'
g:global = 'value'
var Funcref = g:ThatFunction
Since `&opt = value` is now assigning a value to option "opt", ":&" cannot be
used to repeat a `:substitute` command.
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.
`: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!
muList->add(3) # Error!
< *:final*
`: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
muList->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"
< *E1092*
Declaring more than one variable at a time, using the unpack notation, is
currently not supported: >
var [v1, v2] = GetValues() # Error!
That is because the type needs to be inferred from the list item type, which
isn't that easy.
Omitting :call and :eval ~
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. Examples: >
myList->add(123)
g:myList->add(123)
[1, 2, 3]->Process()
#{a: 1, b: 2}->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 (
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. The function can be defined later.
Automatic line continuation ~
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
|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,
}
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
< *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 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
It is also possible to split a function header over multiple lines, in between
arguments: >
def MyFunc(
text: string,
separator = '-'
): string
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]
- No line break is allowed in the arguments of a lambda, between the "{" and
"->". This is OK: >
filter(list, {k, v ->
v > 0})
< This does not work: >
filter(list, {k,
v -> v > 0})
No curly braces expansion ~
|curly-braces-names| cannot be used.
No :xit, :t, :append, :change or :insert ~
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`.
Comparators ~
The 'ignorecase' option is not used for comparators that use strings.
White space ~
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 not allowed:
- Between a function name and the "(": >
call Func (arg) # Error!
call Func
\ (arg) # Error!
call Func(arg) # OK
call Func(
\ arg) # OK
call Func(
\ arg # OK
\ )
Conditions and expressions ~
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 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 v:true
job when not NULL
channel when not NULL
class when not NULL
object when not NULL (TODO: when isTrue() returns v:true)
The boolean operators "||" and "&&" expect the values to be boolean, zero or
one: >
1 || false == true
0 || 1 == true
0 || false == false
1 && true == true
0 && 1 == false
8 || 0 Error!
'yes' && 0 Error!
[] || 99 Error!
When using "!" for inverting, there is no error for using any type and the
result is a boolean. "!!" can be used to turn any value into boolean: >
!'yes' == false
!![] == false
!![1, 2, 3] == true
When using "`.."` for string concatenation arguments of simple types are
always converted to string: >
'hello ' .. 123 == 'hello 123'
'hello ' .. v:true == 'hello v:true'
Simple types are string, float, special and bool. For other types |string()|
can be used.
*false* *true*
In Vim9 script one can use "true" for v:true and "false" for v:false.
Indexing a string with [idx] or [idx, idx] uses character indexes instead of
byte indexes. Example: >
echo 'bár'[1]
In legacy script this results in the character 0xc3 (an illegal byte), in Vim9
script this results in the string 'á'.
What to watch out for ~
*vim9-gotchas*
Vim9 was designed to be closer to often used programming languages, but at the
same time tries to support the legacy Vim commands. Some compromises had to
be made. Here is a summary of what might be unexpected.
Ex command ranges need to be prefixed with a colon. >
-> # legacy Vim: shifts the previous line to the right
->func() # Vim9: method call in continuation line
:-> # Vim9: shifts the previous line to the right
%s/a/b # legacy Vim: substitute on all lines
x = alongname
% another # Vim9: line continuation without a backslash
:%s/a/b # Vim9: substitute on all lines
'text'->func() # Vim9: method call
:'t # legacy Vim: jump to mark m
Some Ex commands can be confused with assignments in Vim9 script: >
g:name = value # assignment
g:pattern:cmd # invalid command - ERROR
:g:pattern:cmd # :global command
Functions defined with `:def` compile the whole function. Legacy functions
can bail out, and the following lines are not parsed: >
func Maybe()
if !has('feature')
return
endif
use-feature
endfunc
Vim9 functions are compiled as a whole: >
def Maybe()
if !has('feature')
return
endif
use-feature # May give compilation error
enddef
For a workaround, split it in two functions: >
func Maybe()
if has('feature')
call MaybyInner()
endif
endfunc
if has('feature')
def MaybeInner()
use-feature
enddef
endif
Or put the unsupported code inside an `if` with a constant expression that
evaluates to false: >
def Maybe()
if has('feature')
use-feature
endif
enddef
Note that for unrecognized commands there is no check for "|" and a following
command. This will give an error for missing `endif`: >
def Maybe()
if has('feature') | use-feature | endif
enddef
==============================================================================
3. New style functions *fast-functions*
THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
*:def*
:def[!] {name}([arguments])[: {return-type}]
Define a new function by the name {name}. The body of
the function follows in the next lines, until the
matching `:enddef`.
When {return-type} is omitted or is "void" the
function is not expected to return anything.
{arguments} is a sequence of zero or more argument
declarations. There are three forms:
{name}: {type}
{name} = {value}
{name}: {type} = {value}
The first form is a mandatory argument, the caller
must always provide them.
The second and third form are optional arguments.
When the caller omits an argument the {value} is used.
The function will be compiled into instructions when
called, or when `:disassemble` or `:defcompile` is
used. Syntax and type errors will be produced at that
time.
It is possible to nest `:def` inside another `:def` or
`:function` up to about 50 levels deep.
[!] 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
reloading the same script.
*:enddef*
:enddef End of a function defined with `:def`. It should be on
a line by its own.
If the script the function is defined in is Vim9 script, then script-local
variables can be accessed without the "s:" prefix. They must be defined
before the function is compiled. If the script the function is defined in is
legacy script, then script-local variables must be accessed with the "s:"
prefix and they do not need to exist (they can be deleted any time).
*: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}.
This is for debugging and testing.
Note that for command line completion of {func} you
can prepend "s:" to find script-local functions.
Limitations ~
Local variables will not be visible to string evaluation. For example: >
def EvalString(): list<string>
var list = ['aa', 'bb', 'cc', 'dd']
return range(1, 2)->map('list[v:val]')
enddef
The map argument is a string expression, which is evaluated without the
function scope. Instead, use a lambda: >
def EvalString(): list<string>
var list = ['aa', 'bb', 'cc', 'dd']
return range(1, 2)->map({ _, v -> list[v] })
enddef
==============================================================================
4. Types *vim9-types*
THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
The following builtin types are supported:
bool
number
float
string
blob
list<{type}>
dict<{type}>
job
channel
func
func: {type}
func({type}, ...)
func({type}, ...): {type}
Not supported yet:
tuple<a: {type}, b: {type}, ...>
These types can be used in declarations, but no value will have this type:
{type}|{type} {not implemented yet}
void
any
There is no array type, use list<{type}> instead. For a list constant an
efficient implementation is used that avoids allocating lot of small pieces of
memory.
A partial and function can be declared in more or less specific ways:
func any kind of function reference, no type
checking for arguments or return value
func: {type} any number and type of arguments with specific
return type
func({type}) function with argument type, does not return
a value
func({type}): {type} function with argument type and return type
func(?{type}) function with type of optional argument, does
not return a value
func(...{type}) function with type of variable number of
arguments, does not return a value
func({type}, ?{type}, ...{type}): {type}
function with:
- type of mandatory argument
- type of optional argument
- type of variable number of arguments
- return type
If the return type is "void" the function does not return a value.
The reference can also be a |Partial|, in which case it stores extra arguments
and/or a dictionary, which are not visible to the caller. Since they are
called in the same way the declaration is the same.
Custom types can be defined with `:type`: >
:type MyList list<string>
Custom types must start with a capital letter, to avoid name clashes with
builtin types added later, similarly to user functions.
{not implemented yet}
And classes and interfaces can be used as types: >
:class MyClass
:var mine: MyClass
:interface MyInterface
:var mine: MyInterface
:class MyTemplate<Targ>
:var mine: MyTemplate<number>
:var mine: MyTemplate<string>
:class MyInterface<Targ>
:var mine: MyInterface<number>
:var mine: MyInterface<string>
{not implemented yet}
Variable types and type casting ~
*variable-types*
Variables declared in Vim9 script or in a `:def` function have a type, either
specified explicitly or inferred from the initialization.
Global, buffer, window and tab page variables do not have a specific type, the
value can be changed at any time, possibly changing the type. Therefore, in
compiled code the "any" type is assumed.
This can be a problem when the "any" type is undesired and the actual type is
expected to always be the same. For example, when declaring a list: >
var l: list<number> = [1, g:two]
This will give an error, because "g:two" has type "any". To avoid this, use a
type cast: >
var l: list<number> = [1, <number>g:two]
< *type-casting*
The compiled code will then check that "g:two" is a number at runtime and give
an error if it isn't. This is called type casting.
The syntax of a type cast is: "<" {type} ">". There cannot be white space
after the "<" or before the ">" (to avoid them being confused with
smaller-than and bigger-than operators).
The semantics is that, if needed, a runtime type check is performed. The
value is not actually changed. If you need to change the type, e.g. to change
it to a string, use the |string()| function. Or use |str2nr()| to convert a
string to a number.
Type inference ~
*type-inference*
In general: Whenever the type is clear it can be omitted. For example, when
declaring a variable and giving it a value: >
var name = 0 # infers number type
var name = 'hello' # infers string type
The type of a list and dictionary comes from the common type of the values.
If the values all have the same type, that type is used for the list or
dictionary. If there is a mix of types, the "any" type is used. >
[1, 2, 3] list<number>
['a', 'b', 'c'] list<string>
[1, 'x', 3] list<any>
Stricter type checking ~
*type-checking*
In legacy Vim script, where a number was expected, a string would be
automatically converted to a number. This was convenient for an actual number
such as "123", but leads to unexpected problems (but no error message) if the
string doesn't start with a number. Quite often this leads to hard-to-find
bugs.
In Vim9 script this has been made stricter. In most places it works just as
before, if the value used matches the expected type. There will sometimes be
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 options.
- Using a number where a string is expected. *E1024*
==============================================================================
5. Namespace, Import and Export
*vim9script* *vim9-export* *vim9-import*
THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
A Vim9 script can be written to be imported. This means that everything in
the script is local, unless exported. Those exported items, and only those
items, can then be imported in another script.
You can cheat by using the global namespace explicitly. We will assume here
that you don't do that.
Namespace ~
*:vim9script* *:vim9*
To recognize a file that can be imported the `vim9script` statement must
appear as the first statement in the file. It tells Vim to interpret the
script in its own namespace, instead of the global namespace. If a file
starts with: >
vim9script
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.
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.
In Vim9 script the global "g:" namespace can still be used as before. And the
"w:", "b:" and "t:" namespaces. These have in common that variables are not
declared and they can be deleted.
A side effect of `:vim9script` is that the 'cpoptions' option is set to the
Vim default value, like with: >
:set cpo&vim
One of the effects is that |line-continuation| is always enabled.
The original value of 'cpoptions' is restored at the end of the script.
Export ~
*:export* *:exp*
Exporting an item can be written as: >
export const EXPORTED_CONST = 1234
export var someValue = ...
export final someValue = ...
export const someValue = ...
export def MyFunc() ...
export class MyClass ...
As this suggests, only constants, variables, `:def` functions and classes can
be exported. {classes are not implemented yet}
*E1042*
`:export` can only be used in Vim9 script, at the script level.
Import ~
*:import* *:imp* *E1094*
The exported items can be imported individually in another Vim9 script: >
import EXPORTED_CONST from "thatscript.vim"
import MyClass from "myclass.vim"
To import multiple items at the same time: >
import {someValue, MyClass} from "thatscript.vim"
In case the name is ambiguous, another name can be specified: >
import MyClass as ThatClass from "myclass.vim"
import {someValue, MyClass as ThatClass} from "myclass.vim"
To import all exported items under a specific identifier: >
import * as That from 'thatscript.vim'
{not implemented yet: using "This as That"}
Then you can use "That.EXPORTED_CONST", "That.someValue", etc. You are free
to choose the name "That", but it is highly recommended to use the name of the
script file to avoid confusion.
`:import` can also be used in legacy Vim script. The imported items still
become script-local, even when the "s:" prefix is not given.
The script name after `import` can be:
- A relative path, starting "." or "..". This finds a file relative to the
location of the script file itself. This is useful to split up a large
plugin into several files.
- An absolute path, starting with "/" on Unix or "D:/" on MS-Windows. This
will be rarely used.
- A path not being relative or absolute. This will be found in the
"import" subdirectories of 'runtimepath' entries. The name will usually be
longer and unique, to avoid loading the wrong file.
Once a vim9 script file has been imported, the result is cached and used the
next time the same script is imported. It will not be read again.
*:import-cycle*
The `import` commands are executed when encountered. If that script (directly
or indirectly) imports the current script, then items defined after the
`import` won't be processed yet. Therefore cyclic imports can exist, but may
result in undefined items.
Import in an autoload script ~
For optimal startup speed, loading scripts should be postponed until they are
actually needed. A recommended mechanism:
1. In the plugin define user commands, functions and/or mappings that refer to
an autoload script. >
command -nargs=1 SearchForStuff call searchfor#Stuff(<f-args>)
< This goes in .../plugin/anyname.vim. "anyname.vim" can be freely chosen.
2. In the autoload script do the actual work. You can import items from
other files to split up functionality in appropriate pieces. >
vim9script
import FilterFunc from "../import/someother.vim"
def searchfor#Stuff(arg: string)
var filtered = FilterFunc(arg)
...
< This goes in .../autoload/searchfor.vim. "searchfor" in the file name
must be exactly the same as the prefix for the function name, that is how
Vim finds the file.
3. Other functionality, possibly shared between plugins, contains the exported
items and any private items. >
vim9script
var localVar = 'local'
export def FilterFunc(arg: string): string
...
< This goes in .../import/someother.vim.
When compiling a `:def` function and a function in an autoload script is
encountered, the script is not loaded until the `:def` function is called.
Import in legacy Vim script ~
If an `import` statement is used in legacy Vim script, the script-local "s:"
namespace will be used for the imported item, even when "s:" is not specified.
==============================================================================
6. Future work: classes *vim9-classes*
Above "class" was mentioned a few times, but it has not been implemented yet.
Most of Vim9 script can be created without this functionality, and since
implementing classes is going to be a lot of work, it is left for the future.
For now we'll just make sure classes can be added later.
Thoughts:
- `class` / `endclass`, everything in one file
- Class names are always CamelCase
- Single constructor
- Single inheritance with `class ThisClass extends BaseClass`
- `abstract class`
- `interface` (Abstract class without any implementation)
- `class SomeClass implements SomeInterface`
- Generics for class: `class <Tkey, Tentry>`
- Generics for function: `def <Tkey> GetLast(key: Tkey)`
Again, much of this is from TypeScript.
Some things that look like good additions:
- Use a class as an interface (like Dart)
- Extend a class with methods, using an import (like Dart)
An important class that will be provided is "Promise". Since Vim is single
threaded, connecting asynchronous operations is a natural way of allowing
plugins to do their work without blocking the user. It's a uniform way to
invoke callbacks and handle timeouts and errors.
==============================================================================
9. Rationale *vim9-rationale*
The :def command ~
Plugin writers have asked for much faster Vim script. Investigations have
shown that keeping the existing semantics of function calls make this close to
impossible, because of the overhead involved with calling a function, setting
up the local function scope and executing lines. There are many details that
need to be handled, such as error messages and exceptions. The need to create
a dictionary for a: and l: scopes, the a:000 list and several others add too
much overhead that cannot be avoided.
Therefore the `:def` method to define a new-style function had to be added,
which allows for a function with different semantics. Most things still work
as before, but some parts do not. A new way to define a function was
considered the best way to separate the legacy style code from Vim9 style code.
Using "def" to define a function comes from Python. Other languages use
"function" which clashes with legacy Vim script.
Type checking ~
When compiling lines of Vim commands into instructions as much as possible
should be done at compile time. Postponing it to runtime makes the execution
slower and means mistakes are found only later. For example, when
encountering the "+" character and compiling this into a generic add
instruction, at execution time the instruction would have to inspect the type
of the arguments and decide what kind of addition to do. And when the
type is dictionary throw an error. If the types are known to be numbers then
an "add number" instruction can be used, which is faster. The error can be
given at compile time, no error handling is needed at runtime, since adding
two numbers cannot fail.
The syntax for types, using <type> for compound types, is similar to Java. It
is easy to understand and widely used. The type names are what were used in
Vim before, with some additions such as "void" and "bool".
Removing clutter and weirdness ~
Once decided that `:def` functions have different syntax than legacy functions,
we are free to add improvements to make the code more familiar for users who
know popular programming languages. In other words: remove weird things that
only Vim does.
We can also remove clutter, mainly things that were done to make Vim script
backwards compatible with the good old Vi commands.
Examples:
- Drop `:call` for calling a function and `:eval` for manipulating data.
- Drop using a leading backslash for line continuation, automatically figure
out where an expression ends.
However, this does require that some things need to change:
- Comments start with # instead of ", to avoid confusing them with strings.
This is good anyway, it is known from several popular languages.
- Ex command ranges need to be prefixed with a colon, to avoid confusion with
expressions (single quote can be a string or a mark, "/" can be divide or a
search command, etc.).
Goal is to limit the differences. A good criteria is that when the old syntax
is accidentally used you are very likely to get an error message.
Syntax and semantics from popular languages ~
Script writers have complained that the Vim script syntax is unexpectedly
different from what they are used to. To reduce this complaint popular
languages are used as an example. At the same time, we do not want to abandon
the well-known parts of legacy Vim script.
For many things TypeScript is followed. It's a recent language that is
gaining popularity and has similarities with Vim script. It also has a
mix of static typing (a variable always has a known value type) and dynamic
typing (a variable can have different types, this changes at runtime). Since
legacy Vim script is dynamically typed and a lot of existing functionality
(esp. builtin functions) depends on that, while static typing allows for much
faster execution, we need to have this mix in Vim9 script.
There is no intention to completely match TypeScript syntax and semantics. We
just want to take those parts that we can use for Vim and we expect Vim users
will be happy with. TypeScript is a complex language with its own history,
advantages and disadvantages. To get an idea of the disadvantages read the
book: "JavaScript: The Good Parts". Or find the article "TypeScript: the good
parts" and read the "Things to avoid" section.
People familiar with other languages (Java, Python, etc.) will also find
things in TypeScript that they do not like or do not understand. We'll try to
avoid those things.
Specific items from TypeScript we avoid:
- Overloading "+", using it both for addition and string concatenation. This
goes against legacy Vim script and often leads to mistakes. For that reason
we will keep using ".." for string concatenation. Lua also uses ".." this
way. And it allows for conversion to string for more values.
- TypeScript can use an expression like "99 || 'yes'" in a condition, but
cannot assign the value to a boolean. That is inconsistent and can be
annoying. Vim recognizes an expression with && or || and allows using the
result as a bool. TODO: to be reconsidered
- TypeScript considers an empty string as Falsy, but an empty list or dict as
Truthy. That is inconsistent. In Vim an empty list and dict are also
Falsy.
- 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.
Declarations ~
Legacy Vim script uses `:let` for every assignment, while in Vim9 declarations
are used. That is different, thus it's good to use a different command:
`:var`. This is used in many languages. The semantics might be slightly
different, but it's easily recognized as a declaration.
Using `:const` for constants is common, but the semantics vary. Some
languages only make the variable immutable, others also make the value
immutable. Since "final" is well known from Java for only making the variable
immutable we decided to use that. And then `:const` can be used for making
both immutable. This was also used in legacy Vim script and the meaning is
almost the same.
What we end up with is very similar to Dart: >
:var name # mutable variable and value
:final name # immutable variable, mutable value
:const name # immutable variable and value
Since legacy and Vim9 script will be mixed and global variables will be
shared, optional type checking is desirable. Also, type inference will avoid
the need for specifying the type in many cases. The TypeScript syntax fits
best for adding types to declarations: >
var name: string # string type is specified
...
name = 'John'
const greeting = 'hello' # string type is inferred
This is how we put types in a declaration: >
var mylist: list<string>
final mylist: list<string> = ['foo']
def Func(arg1: number, arg2: string): bool
Two alternatives were considered:
1. Put the type before the name, like Dart: >
var list<string> mylist
final list<string> mylist = ['foo']
def Func(number arg1, string arg2) bool
2. Put the type after the variable name, but do not use a colon, like Go: >
var mylist list<string>
final mylist list<string> = ['foo']
def Func(arg1 number, arg2 string) bool
The first is more familiar for anyone used to C or Java. The second one
doesn't really has an advantage over the first, so let's discard the second.
Since we use type inference the type can be left out when it can be inferred
from the value. This means that after `var` we don't know if a type or a name
follows. That makes parsing harder, not only for Vim but also for humans.
Also, it will not be allowed to use a variable name that could be a type name,
using `var string string` is too confusing.
The chosen syntax, using a colon to separate the name from the type, adds
punctuation, but it actually makes it easier to recognize the parts of a
declaration.
Expressions ~
Expression evaluation was already close to what JavaScript and other languages
are doing. Some details are unexpected and can be fixed. For example how the
|| and && operators work. Legacy Vim script: >
var value = 44
...
var result = value || 0 # result == 1
Vim9 script works like JavaScript/TypeScript, keep the value: >
var value = 44
...
var result = value || 0 # result == 44
TODO: the semantics of || and && need to be reconsidered.
Import and Export ~
A problem of legacy Vim script is that by default all functions and variables
are global. It is possible to make them script-local, but then they are not
available in other scripts. This defies the concept of a package that only
exports selected items and keeps the rest local.
In Vim9 script a mechanism very similar to the JavaScript import and export
mechanism is supported. It is a variant to the existing `:source` command
that works like one would expect:
- Instead of making everything global by default, everything is script-local,
unless exported.
- When importing a script the symbols that are imported are explicitly listed,
avoiding name conflicts and failures if functionality is added later.
- The mechanism allows for writing a big, long script with a very clear API:
the exported function(s) and class(es).
- By using relative paths loading can be much faster for an import inside of a
package, no need to search many directories.
- Once an import has been used, it can be cached and loading it again can be
avoided.
- The Vim-specific use of "s:" to make things script-local can be dropped.
When sourcing a Vim9 script from a legacy script, only the items defined
globally can be used, not the exported items. Alternatives considered:
- All the exported items become available as script-local items. This makes
it uncontrollable what items get defined and likely soon leads to trouble.
- Use the exported items and make them global. Disadvantage is that it's then
not possible to avoid name clashes in the global namespace.
- Completely disallow sourcing a Vim9 script, require using `:import`. That
makes it difficult to use scripts for testing, or sourcing them from the
command line to try them out.
Note that you can also use `:import` in legacy Vim script, see above.
Compiling functions early ~
Functions are compiled when called or when `:defcompile` is used. Why not
compile them early, so that syntax and type errors are reported early?
The functions can't be compiled right away when encountered, because there may
be forward references to functions defined later. Consider defining functions
A, B and C, where A calls B, B calls C, and C calls A again. It's impossible
to reorder the functions to avoid forward references.
An alternative would be to first scan through the file to locate items and
figure out their type, so that forward references are found, and only then
execute the script and compile the functions. This means the script has to be
parsed twice, which is slower, and some conditions at the script level, such
as checking if a feature is supported, are hard to use. An attempt was made
to see if it works, but it turned out to be impossible to make work nicely.
It would be possible to compile all the functions at the end of the script.
The drawback is that if a function never gets called, the overhead of
compiling it counts anyway. Since startup speed is very important, in most
cases it's better to do it later and accept that syntax and type errors are
only reported then. In case these errors should be found early, e.g. when
testing, the `:defcompile` command will help out.
Why not use an embedded language? ~
Vim supports interfaces to Perl, Python, Lua, Tcl and a few others. But
these interfaces have never become widely used, for various reasons. When
Vim9 was designed a decision was made to make these interfaces lower priority
and concentrate on Vim script.
Still, plugin writers may find other languages more familiar, want to use
existing libraries or see a performance benefit. We encourage plugin authors
to write code in any language and run it as an external tool, using jobs and
channels. We can try to make this easier somehow.
Using an external tool also has disadvantages. An alternative is to convert
the tool into Vim script. For that to be possible without too much
translation, and keeping the code fast at the same time, the constructs of the
tool need to be supported. Since most languages support classes the lack of
support for classes in Vim is then a problem.
Classes ~
Vim supports a kind-of object oriented programming by adding methods to a
dictionary. With some care this can be made to work, but it does not look
like real classes. On top of that, it's quite slow, because of the use of
dictionaries.
The support of classes in Vim9 script is a "minimal common functionality" of
class support in most languages. It works much like Java, which is the most
popular programming language.
vim:tw=78:ts=8:noet:ft=help:norl:
|