summaryrefslogtreecommitdiffstats
path: root/runtime/doc/vim9.txt
blob: b12b1cc998a312809ebf56ff45d1d841f1ab482d (plain)
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
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
*vim9.txt*	For Vim version 9.1.  Last change: 2023 Dec 24


		  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.
- When indexing a string the index is counted in characters, not bytes:
  |vim9-string-index|
- Some possibly unexpected differences: |vim9-gotchas|.


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*
You can use a Vim9 Class (|Vim9-class|) instead of a "dict function".
You can also 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* *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 someday 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)

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 true'

Simple types are Number, Float, Special and Bool.  For other types |string()|
should be used.
			*false* *true* *null* *null_blob* *null_channel*
			*null_class* *null_dict* *null_function* *null_job*
			*null_list* *null_object* *null_partial* *null_string*
			*E1034*
In Vim9 script one can use the following predefined values: >
	true
	false
	null
	null_blob
	null_channel
	null_class
	null_dict
	null_function
	null_job
	null_list
	null_object
	null_partial
	null_string
`true` is the same as `v:true`, `false` the same as `v:false`, `null` the same
as `v:null`.

While `null` has the type "special", the other "null_" values have the type
indicated by their name.  Quite often a null value is handled the same as an
empty value, but not always.  The values can be useful to clear a script-local
variable, since they cannot be deleted with `:unlet`.  E.g.: >
	var theJob = job_start(...)
	# let the job do its work
	theJob = null_job

The values can also be useful as the default value for an argument: >
	def MyFunc(b: blob = null_blob)
	    # Note: compare against null, not null_blob,
	    #       to distinguish the default value from an empty blob.
	    if b == null
	        # b argument was not given
See |null-compare| for more information about testing against null.

It is possible to compare `null`  with any value, this will not give a type
error.  However, comparing `null` with a number, float or bool will always
result in `false`.  This is different from legacy script, where comparing
`null` with zero or `false` would return `true`.
							*vim9-false-true*
When converting a boolean to a string `false` and `true` are used, not
`v:false` and `v:true` like in legacy script.  `v:none` has no `none`
replacement, it has no equivalent in other languages.
							*vim9-string-index*
Indexing a string with [idx] or taking a slice with [idx : idx] uses character
indexes instead of byte indexes.  Composing characters are included.
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 'á'.
A negative index is counting from the end, "[-1]" is the last character.
To exclude the last character use |slice()|.
To count composing characters separately use |strcharpart()|.
If the index is out of range then an empty string results.

In legacy script "++var" and "--var" would be silently accepted and have no
effect.  This is an error in Vim9 script.

Numbers starting with zero are not considered to be octal, only numbers
starting with "0o" are octal: "0o744". |scriptversion-4|


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 a continuation line
	:->		  Vim9: shifts the previous line to the right

	%s/a/b		  legacy Vim: substitute on all lines
	x = alongname
	     % another	  Vim9: modulo operator in a continuation line
	:%s/a/b		  Vim9: substitute on all lines
	't		  legacy Vim: jump to mark t
	'text'->func()	  Vim9: method call
	:'t		  Vim9: jump to mark t

Some Ex commands can be confused with assignments in Vim9 script: >
	g:name = value    # assignment
	:g:pattern:cmd	  # :global command

To avoid confusion between a `:global` or `:substitute` command and an
expression or assignment, a few separators cannot be used when these commands
are abbreviated to a single character: ':', '-' and '.'. >
	g:pattern:cmd	  # invalid command - ERROR
	s:pattern:repl	  # invalid command - ERROR
	g-pattern-cmd	  # invalid command - ERROR
	s-pattern-repl	  # invalid command - ERROR
	g.pattern.cmd	  # invalid command - ERROR
	s.pattern.repl	  # invalid command - ERROR

Also, there cannot be a space between the command and the separator: >
	g /pattern/cmd	  # invalid command - ERROR
	s /pattern/repl	  # invalid command - ERROR

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 a compilation error
	enddef
For a workaround, split it in two functions: >
	func Maybe()
	  if has('feature')
	    call MaybeInner()
	  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
The `exists_compiled()` function can also be used for this.
							*vim9-user-command*
Another side effect of compiling a function is that the presence of a user
command is checked at compile time.  If the user command is defined later an
error will result.  This works: >
	command -nargs=1 MyCommand echom <q-args>
	def Works()
	  MyCommand 123
	enddef
This will give an error for "MyCommand" not being defined: >
	def Works()
	  command -nargs=1 MyCommand echom <q-args>
	  MyCommand 123
	enddef
A workaround is to invoke the command indirectly with `:execute`: >
	def Works()
	  command -nargs=1 MyCommand echom <q-args>
	  execute 'MyCommand 123'
	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

Other differences ~

Patterns are used like 'magic' is set, unless explicitly overruled.
The 'edcompatible' option value is not used.
The 'gdefault' option value is not used.

You may also find this wiki useful.  It was written by an early adopter of
Vim9 script: https://github.com/lacygoill/wiki/blob/master/vim/vim9.md

							*:++* *:--*
The ++ and -- commands have been added.  They are very similar to adding or
subtracting one: >
		++var
		var += 1
		--var
		var -= 1

Using ++var or --var in an expression is not supported yet.

==============================================================================

3. New style functions					*fast-functions*

							*:def* *E1028*
: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`. *E1073*
							*E1011*
			The {name} must be less than 100 bytes long.
					*E1003* *E1027* *E1056* *E1059*
			The type of value used with `:return` must match
			{return-type}.  When {return-type} is omitted or is
			"void" the function is not expected to return
			anything.
							*E1077* *E1123*
			{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.
							*E1117*
			[!] is used as with `:function`.  Note that
			script-local functions cannot be deleted or redefined
			later in Vim9 script.  They can only be removed by
			reloading the same script.

					*:enddef* *E1057* *E1152* *E1173*
:enddef			End of a function defined with `:def`. It should be on
			a line by its own.

You may also find this wiki useful.  It was written by an early adopter of
Vim9 script: https://github.com/lacygoill/wiki/blob/master/vim/vim9.md

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 if they do not exist at the time of compiling.
							*E1269*
Script-local variables in a |Vim9| script must be declared at the script
level.  They cannot be created in a function, also not in a legacy function.

						*:defc* *:defcompile*
:defc[ompile]		Compile functions defined in the current script that
			were not compiled yet.
			This will report any errors found during compilation.
			This excludes functions defined inside a class.

:defc[ompile] {func}
:defc[ompile] debug {func}
:defc[ompile] profile {func}
			Compile function {func}, if needed.  Use "debug" and
			"profile" to specify the compilation mode.
			This will report any errors found during compilation.
			{func} call also be "ClassName.functionName" to
			compile a function or method in a class.
			{func} call also be "ClassName" to compile all
			functions and methods in a class.

						*:disa* *:disassemble*
:disa[ssemble] {func}	Show the instructions generated for {func}.
			This is for debugging and testing. *E1061*
			Note that for command line completion of {func} you
			can prepend "s:" to find script-local functions.

:disa[ssemble] profile {func}
			Like `:disassemble` but with the instructions used for
			profiling.

:disa[ssemble] debug {func}
			Like `:disassemble` but with the instructions used for
			debugging.

Limitations ~

Local variables will not be visible to string evaluation.  For example: >
	def MapList(): 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 MapList(): list<string>
	  var list = ['aa', 'bb', 'cc', 'dd']
	  return range(1, 2)->map((_, v) => list[v])
	enddef

For commands that are not compiled, such as `:edit`, backtick expansion can be
used and it can use the local scope.  Example: >
	def Replace()
	  var fname = 'blah.txt'
	  edit `=fname`
	enddef

Closures defined in a loop will share the same context.  For example: >
	var flist: list<func>
	for i in range(5)
	  var inloop = i
	  flist[i] = () => inloop
	endfor
	echo range(5)->map((i, _) => flist[i]())
	# Result: [4, 4, 4, 4, 4]
<							*E1271*
A closure must be compiled in the context that it is defined in, so that
variables in that context can be found.  This mostly happens correctly, except
when a function is marked for debugging with `:breakadd` after it was compiled.
Make sure to define the breakpoint before compiling the outer function.

The "inloop" variable will exist only once, all closures put in the list refer
to the same instance, which in the end will have the value 4.  This is
efficient, also when looping many times.  If you do want a separate context
for each closure, call a function to define it: >
	def GetClosure(i: number): func
	  var infunc = i
	  return () => infunc
	enddef

	var flist: list<func>
	for i in range(5)
	  flist[i] = GetClosure(i)
	endfor
	echo range(5)->map((i, _) => flist[i]())
	# Result: [0, 1, 2, 3, 4]

In some situations, especially when calling a Vim9 closure from legacy
context, the evaluation will fail.  *E1248*

Note that at the script level the loop variable will be invalid after the
loop, also when used in a closure that is called later, e.g. with a timer.
This will generate error |E1302|: >
	for n in range(4)
	    timer_start(500 * n, (_) => {
	          echowin n
	       })
	endfor

You need to use a block and define a variable there, and use that one in the
closure: >
	for n in range(4)
	{
	   var nr = n
	   timer_start(500 * n, (_) => {
	          echowin nr
	      })
	}
	endfor

Using `:echowindow` is useful in a timer, the messages go into a popup and will
not interfere with what the user is doing when it triggers.


Converting a function from legacy to Vim9 ~
					*convert_legacy_function_to_vim9*
These are the most changes that need to be made to convert a legacy function
to a Vim9 function:

- Change `func` or `function` to `def`.
- Change `endfunc` or `endfunction` to `enddef`.
- Add types to the function arguments.
- If the function returns something, add the return type.
- Change comments to start with # instead of ".

  For example, a legacy function: >
	func MyFunc(text)
	  " function body
	endfunc
<  Becomes: >
	def MyFunc(text: string): number
	  # function body
	enddef

- Remove "a:" used for arguments. E.g.: >
	return len(a:text)
<  Becomes: >
	return len(text)

- Change `let` used to declare a variable to `var`.
- Remove `let` used to assign a value to a variable.  This is for local
  variables already declared and b: w: g: and t: variables.

  For example, legacy function: >
	  let lnum = 1
	  let lnum += 3
	  let b:result = 42
<  Becomes: >
	  var lnum = 1
	  lnum += 3
	  b:result = 42

- Insert white space in expressions where needed.
- Change "." used for concatenation to "..".

  For example, legacy function: >
	  echo line(1).line(2)
<  Becomes: >
	  echo line(1) .. line(2)

- line continuation does not always require a backslash: >
	echo ['one',
		\ 'two',
		\ 'three'
		\ ]
<  Becomes: >
	echo ['one',
		'two',
		'three'
		]


Calling a function in an expr option ~
							*expr-option-function*
The value of a few options, such as 'foldexpr', is an expression that is
evaluated to get a value.  The evaluation can have quite a bit of overhead.
One way to minimize the overhead, and also to keep the option value very
simple, is to define a compiled function and set the option to call it
without arguments.  Example: >
	vim9script
	def MyFoldFunc(): any
	   ... compute fold level for line v:lnum
	   return level
	enddef
	set foldexpr=s:MyFoldFunc()

==============================================================================

4. Types					*vim9-types*
					*E1008* *E1009* *E1010* *E1012*
					*E1013* *E1029* *E1030*
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}
	void

Not supported yet:
	tuple<a: {type}, b: {type}, ...>

These types can be used in declarations, but no simple value will actually
have the "void" type.  Trying to use a void (e.g. a function without a
return value) results in error *E1031*  *E1186* .

There is no array type, use list<{type}> instead.  For a list constant an
efficient implementation is used that avoids allocating a lot of small pieces
of memory.
				    *vim9-func-declaration* *E1005* *E1007*
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: void			any number and type of arguments, no return
				value
func: {type}			any number and type of arguments with specific
				return type

func()				function with no argument, does not return a
				value
func(): void			same
func(): {type}			function with no argument and 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(...list<{type}>)		function with type of list for variable number
				of arguments, does not return a value
func({type}, ?{type}, ...list<{type}>): {type}
				function with:
				- type of mandatory argument
				- type of optional argument
				- type of list for 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]
At compile time Vim doesn't know the type of "g:two" and the expression type
becomes list<any>.  An instruction is generated to check the list type before
doing the assignment, which is a bit inefficient.
						*type-casting* *E1104*
To avoid this, use a type cast: >
	var l: list<number> = [1, <number>g:two]
The compiled code will then only check that "g:two" is a number and give an
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.

If a type is given where it is not expected you can get *E1272* .

If a type is incomplete you get *E1363* , e.g. when you have an object for
which the class is not known (usually that is a null object).

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>

The common type of function references, if they do not all have the same
number of arguments, uses "(...)" to indicate the number of arguments is not
specified.  For example: >
	def Foo(x: bool)
	enddef
	def Bar(x: bool, y: bool)
	enddef
	var funclist = [Foo, Bar]
	echo funclist->typename()
Results in:
	list<func(...)>

For script-local variables in Vim9 script the type is checked, also when the
variable was declared in a legacy function.

When a type has been declared this is attached to a List or Dictionary.  When
later some expression attempts to change the type an error will be given: >
	var ll: list<number> = [1, 2, 3]
	ll->extend(['x'])  # Error, 'x' is not a number

If the type is not declared then it is allowed to change: >
	[1, 2, 3]->extend(['x'])  # result: [1, 2, 3, 'x']

For a variable declaration an inferred type matters: >
	var ll = [1, 2, 3]
	ll->extend(['x'])  # Error, 'x' is not a number
That is because the declaration looks like a list of numbers, thus is
equivalent to: >
	var ll: list<number> = [1, 2, 3]
If you do want a more permissive list you need to declare the type: >
	var ll: list<any> = [1, 2, 3]
	ll->extend(['x'])  # OK


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 (and no error message) if the
string doesn't start with a number.  Quite often this leads to hard-to-find
bugs. e.g.: >
	echo 123 == '123'
<	1 ~
With an accidental space: >
	echo 123 == ' 123'
<	0 ~
							*E1206* *E1210* *E1212*
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 option.
- Using a number where a string is expected.   *E1024* *E1105*

One consequence is that the item type of a list or dict given to |map()| must
not change, if the type was declared.  This will give an error in Vim9
script: >
	var mylist: list<number> = [1, 2, 3]
	echo map(mylist, (i, v) => 'item ' .. i)
<	E1012: Type mismatch; expected number but got string in map() ~

Instead use |mapnew()|, it creates a new list: >
	var mylist: list<number> = [1, 2, 3]
	echo mapnew(mylist, (i, v) => 'item ' .. i)
<	['item 0', 'item 1', 'item 2'] ~

If the item type was not declared or determined to be "any" it can change to a
more specific type.  E.g. when a list of mixed types gets changed to a list of
strings: >
	var mylist = [1, 2.0, '3']
	# typename(mylist) == "list<any>"
	map(mylist, (i, v) => 'item ' .. i)
	# typename(mylist) == "list<string>", no error

There is a subtle difference between using a list constant directly and
through a variable declaration.  Because of type inference, when using a list
constant to initialize a variable, this also sets the declared type: >
	var mylist = [1, 2, 3]
	# typename(mylist) == "list<number>"
	echo map(mylist, (i, v) => 'item ' .. i)  # Error!

When using the list constant directly, the type is not declared and is allowed
to change: >
	echo map([1, 2, 3], (i, v) => 'item ' .. i)  # OK

The reasoning behind this is that when a type is declared and the list is
passed around and changed, the declaration must always hold.  So that you can
rely on the type to match the declared type.  For a constant this is not
needed.

								*E1158*
Same for |extend()|, use |extendnew()| instead, and for |flatten()|, use
|flattennew()| instead.  Since |flatten()| is intended to always change the
type, it can not be used in Vim9 script.

Assigning to a funcref with specified arguments (see |vim9-func-declaration|)
does strict type checking of the arguments. For variable number of arguments
the type must match: >
	var FuncRef: func(string, number, bool): number
	FuncRef = (v1: string, v2: number, v3: bool) => 777	# OK
	FuncRef = (v1: string, v2: number, v3: number) => 777	# Error!
	# variable number of arguments must have same type
	var FuncVA: func(...list<string>): number
	FuncVA = (...v: list<number>): number => v  # Error!
	FuncVA = (...v: list<any>): number => v	    # OK, `any` runtime check
	FuncVA = (v1: string, v: string2): number => 333     # Error!
	FuncVA = (v: list<string>): number => 3	    # Error!

If the destination funcref has no specified arguments, then there is no
argument type checking: >
	var FuncUnknownArgs: func: number
	FuncUnknownArgs = (v): number => v			# OK
	FuncUnknownArgs = (v1: string, v2: string): number => 3	# OK
	FuncUnknownArgs = (...v1: list<string>): number => 333	# OK
<
			 *E1211* *E1217* *E1218* *E1219* *E1220* *E1221*
			 *E1222* *E1223* *E1224* *E1225* *E1226* *E1227*
			 *E1228* *E1238* *E1250* *E1251* *E1252* *E1256*
			 *E1297* *E1298* *E1301*
Types are checked for most builtin functions to make it easier to spot
mistakes.

Categories of variables, defaults and null handling ~
				*variable-categories* *null-variables*
There are categories of variables:
	primitive	number, float, boolean
	container	string, blob, list, dict
	specialized	function, job, channel, user-defined-object

When declaring a variable without an initializer, an explicit type must be
provided. Each category has different default initialization semantics. Here's
an example for each category: >
	var num: number		# primitives default to a 0 equivalent
	var cont: list<string>	# containers default to an empty container
	var spec: job		# specialized variables default to null
<
Vim does not have a familiar null value; it has various null_<type> predefined
values, for example |null_string|, |null_list|, |null_job|. Primitives do not
have a null_<type>. The typical use cases for null_<type> are:
- to `clear a variable` and release its resources;
- as a `default for a parameter` in a function definition, see |null-compare|.

For a specialized variable, like `job`, null_<type> is used to clear the
resources. For a container variable, resources can also be cleared by
assigning an empty container to the variable. For example: >
	var j: job = job_start(...)
	# ... job does its work
	j = null_job	# clear the variable and release the job's resources

	var l: list<any>
	# ... add lots of stuff to list
	l = []  # clear the variable and release container resources
Using the empty container, rather than null_<type>, to clear a container
variable may avoid null complications as described in |null-anomalies|.

The initialization semantics of container variables and specialized variables
differ. An uninitialized container defaults to an empty container: >
	var l1: list<string>		    # empty container
	var l2: list<string> = []	    # empty container
	var l3: list<string> = null_list    # null container
"l1" and "l2" are equivalent and indistinguishable initializations; but "l3"
is a null container. A null container is similar to, but different from, an
empty container, see |null-anomalies|.

Specialized variables default to null. These job initializations are
equivalent and indistinguishable: >
	var j1: job
	var j2: job = null_job
	var j3 = null_job

When a list or dict is declared, if the item type is not specified and can not
be inferred, then the type is "any": >
	var d1 = {}		# type is "dict<any>"
	var d2 = null_dict	# type is "dict<any>"

Declaring a function, see |vim9-func-declaration|, is particularly unique.

						*null-compare*
For familiar null compare semantics, where a null container is not equal to
an empty container, do not use null_<type> in a comparison: >
	vim9script
	def F(arg: list<string> = null_list)
	    if arg == null
	       echo "null"
	    else
		echo printf("not null, %sempty", empty(arg) ? '' : 'not ')
	    endif
	enddef
	F()		# output: "null"
	F(null_list)	# output: "null"
	F([])		# output: "not null, empty"
	F([''])		# output: "not null, not empty"
The above function takes a `list of strings` and reports on it.
Change the above function signature to accept different types of arguments: >
	def F(arg: list<any> = null_list)   # any type of list
	def F(arg: any = null)		    # any type
<
In the above example, where the goal is to distinguish a null list from an
empty list, comparing against `null` instead of `null_list` is the correct
choice. The basic reason is because "null_list == null" and "[] != null".
Comparing to `null_list` fails since "[] == null_list". In the following section
there are details about comparison results.

					*null-details* *null-anomalies*
This section describes issues about using null and null_<type>; included below
are the enumerated results of null comparisons. In some cases, if familiar
with vim9 null semantics, the programmer may chose to use null_<type> in
comparisons and/or other situations.

Elsewhere in the documentation it says:
	Quite often a null value is handled the same as an
	empty value, but not always
Here's an example: >
	vim9script
	var s1: list<string>
	var s2: list<string> = null_list
	echo s1		    # output: "[]"
	echo s2		    # output: "[]"
	
	echo s1 + ['a']     # output: "['a']"
	echo s2 + ['a']     # output: "['a']"
	
	echo s1->add('a')   # output: "['a']"
	echo s2->add('a')   # E1130: Can not add to null list
<
Two values equal to a null_<type> are not necessarily equal to each other: >
	vim9script
	echo {} == null_dict      # true
	echo null_dict == null    # true
	echo {} == null           # false
<
Unlike the other containers, an uninitialized string is equal to null. The
'is' operator can be used to determine if it is a null_string: >
	vim9script
	var s1: string
	var s2 = null_string
	echo s1 == null		# true - this is unexpected
	echo s2 == null		# true
	echo s2 is null_string	# true

	var b1: blob
	var b2 = null_blob
	echo b1 == null		# false
	echo b2 == null		# true
<
Any variable initialized to the null_<type> is equal to the null_<type> and is
also equal to null. For example: >
	vim9script
	var x = null_blob
	echo x == null_blob	# true
	echo x == null		# true
<
An uninitialized variable is usually equal to null; it depends on its type:
	var s: string		s == null
	var b: blob		b != null   ***
	var l: list<any>	l != null   ***
	var d: dict<any>	d != null   ***
	var f: func		f == null
	var j: job		j == null
	var c: channel		c == null
	var o: Class		o == null

A variable initialized to empty equals null_<type>; but not null:
	var s2: string = ""	  == null_string	!= null
	var b2: blob = 0z	  == null_blob		!= null
	var l2: list<any> = []	  == null_list		!= null
	var d2: dict<any> = {}	  == null_dict		!= null

NOTE: the specialized variables, like job, default to null value and have no
corresponding empty value.

==============================================================================

5. Namespace, Import and Export
					*vim9script* *vim9-export* *vim9-import*

A Vim9 script can be written to be imported.  This means that some items are
intentionally exported, made available to other scripts.  When the exporting
script is imported in another script, these exported items can then be used in
that script.  All the other items remain script-local in the exporting script
and cannot be accessed by the importing script.

This mechanism exists for writing a script that can be sourced (imported) by
other scripts, while making sure these other scripts only have access to what
you want them to.  This also avoids using the global namespace, which has a
risk of name collisions.  For example when you have two plugins with similar
functionality.

You can cheat by using the global namespace explicitly.  That should be done
only for things that really are global.


Namespace ~
							*vim9-namespace*
To recognize a file that can be imported the `vim9script` statement must
appear as the first statement in the file (see |vim9-mix| for an exception).
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.
							*E1101*
The variables at the file level are very much like the script-local "s:"
variables in legacy Vim script, but the "s:" is omitted.  And they cannot be
deleted.

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, have no specific type and they can be deleted.  *E1304*

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, while
flags added or removed in the script are also added to or removed from the
original value to get the same effect.  The order of flags may change.
In the |vimrc| file sourced on startup this does not happen.

							*vim9-mix*
There is one way to use both legacy and Vim9 syntax in one script file: >
	" comments may go here
	if !has('vim9script')
	   " legacy script commands go here
	   finish
	endif
	vim9script
	# Vim9 script commands go here
This allows for writing a script that takes advantage of the Vim9 script
syntax if possible, but will also work on a Vim version without it.

This can only work in two ways:
1. The "if" statement evaluates to false, the commands up to `endif` are
   skipped and `vim9script` is then the first command actually executed.
2. The "if" statement evaluates to true, the commands up to `endif` are
   executed and `finish` bails out before reaching `vim9script`.


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 ...
	export interface MyClass ...
<							*E1043* *E1044*
As this suggests, only constants, variables, `:def` functions and classes can
be exported.

							*E1042*
`:export` can only be used in Vim9 script, at the script level.


Import ~
				*:import* *:imp* *E1094* *E1047* *E1262*
				*E1048* *E1049* *E1053* *E1071* *E1088* *E1236*
The exported items can be imported in another script. The import syntax has
two forms. The simple form: >
	import {filename}
<
Where {filename} is an expression that must evaluate to a string.  In this
form the filename should end in ".vim" and the portion before ".vim" will
become the script local name of the namespace. For example: >
	import "myscript.vim"
<
This makes each exported item in "myscript.vim" available as "myscript.item".
						*:import-as* *E1257* *E1261*
In case the name is long or ambiguous, this form can be used to specify
another name: >
	import {longfilename} as {name}
<
In this form {name} becomes a specific script local name for the imported
namespace.  Therefore {name} must consist of letters, digits and '_', like
|internal-variables|.  The {longfilename} expression must evaluate to any
filename.  For example: >
	import "thatscript.vim.v2" as that
<						*E1060* *E1258* *E1259* *E1260*
Then you can use "that.item", etc.  You are free to choose the name "that".
Use something that will be recognized as referring to the imported script.
Avoid command names, command modifiers and builtin function names, because the
name will shadow them.  It's better not to start the name with a capital
letter, since it can then also shadow global user commands and functions.
Also, you cannot use the name for something else in the script, such as a
function or variable name.

In case the dot in the name is undesired, a local reference can be made for a
function: >
	var LongFunc = that.LongFuncName

This also works for constants: >
	const MAXLEN = that.MAX_LEN_OF_NAME

This does not work for variables, since the value would be copied once and
when changing the variable the copy will change, not the original variable.
You will need to use the full name, with the dot.

`:import` can not be used in a function.  Imported items are intended to exist
at the script level and only imported once.

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 rarely be 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.
  Note that "after/import" is not used.

If the name does not end in ".vim" then the use of "as name" is required.

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.

It is not allowed to import the same script twice, also when using two
different "as" names.

When using the imported name the dot and the item name must be in the same
line, there can be no line break: >
	echo that.
		name   # Error!
	echo that
		.name  # Error!
<						*import-map*
When you've imported a function from one script into a vim9 script you can
refer to the imported function in a mapping by prefixing it with |<SID>|: >
	noremap <silent> ,a :call <SID>name.Function()<CR>

When the mapping is defined "<SID>name." will be replaced with <SNR> and the
script ID of the imported script.
An even simpler solution is using |<ScriptCmd>|: >
	noremap ,a <ScriptCmd>name.Function()<CR>

Note that this does not work for variables, only for functions.

					    *import-legacy* *legacy-import*
`:import` can also be used in legacy Vim script.  The imported namespace still
becomes script-local, even when the "s:" prefix is not given. For example: >
        import "myfile.vim"
	call s:myfile.MyFunc()

And using the "as name" form: >
	import "otherfile.vim9script" as that
	call s:that.OtherFunc()

However, the namespace cannot be resolved on its own: >
	import "that.vim"
	echo s:that
	" ERROR: E1060: Expected dot after name: s:that
<
This also affects the use of |<SID>| in the legacy mapping context.  Since
|<SID>| is only a valid prefix for a function and NOT for a namespace, you
cannot use it to scope a function in a script local namespace. Instead of
prefixing the function with |<SID>| you should use|<ScriptCmd>|. For example:
>
	noremap ,a <ScriptCmd>:call s:that.OtherFunc()<CR>
<
							*:import-cycle*
The `import` commands are executed when encountered.  If script A imports
script B, and B (directly or indirectly) imports A, this will be skipped over.
At this point items in A after "import B" will not have been processed and
defined yet.  Therefore cyclic imports can exist and not result in an error
directly, but may result in an error for items in A after "import B" not being
defined.  This does not apply to autoload imports, see the next section.


Importing an autoload script ~
					*vim9-autoload* *import-autoload*
For optimal startup speed, loading scripts should be postponed until they are
actually needed.  Using the autoload mechanism is recommended:
							*E1264*
1. In the plugin define user commands, functions and/or mappings that refer to
   items imported from an autoload script. >
	import autoload 'for/search.vim'
	command -nargs=1 SearchForStuff search.Stuff(<f-args>)

<   This goes in .../plugin/anyname.vim.  "anyname.vim" can be freely chosen.
   The "SearchForStuff" command is now available to the user.

   The "autoload" argument to `:import` means that the script is not loaded
   until one of the items is actually used.  The script will be found under
   the "autoload" directory in 'runtimepath' instead of the "import"
   directory.  Alternatively a relative or absolute name can be used, see
   below.

2. In the autoload script put the bulk of the code. >
	vim9script
	export def Stuff(arg: string)
	  ...

<   This goes in .../autoload/for/search.vim.

   Putting the "search.vim" script under the "/autoload/for/" directory has
   the effect that "for#search#" will be prefixed to every exported item.  The
   prefix is obtained from the file name, as you would to manually in a
   legacy autoload script.  Thus the exported function can be found with
   "for#search#Stuff", but you would normally use `import autoload` and not
   use the prefix (which has the side effect of loading the autoload script
   when compiling a function that encounters this name).

   You can split up the functionality and import other scripts from the
   autoload script as you like.  This way you can share code between plugins.

Searching for the autoload script in all entries in 'runtimepath' can be a bit
slow.  If the plugin knows where the script is located, quite often a relative
path can be used.  This avoids the search and should be quite a bit faster.
Another advantage is that the script name does not need to be unique.  An
absolute path is also possible.  Examples: >
	import autoload '../lib/implement.vim'
	import autoload MyScriptsDir .. '/lib/implement.vim'

For defining a mapping that uses the imported autoload script the special key
|<ScriptCmd>| is useful.  It allows for a command in a mapping to use the
script context of where the mapping was defined.

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.
This also means you get any errors only at runtime, since the argument and
return types are not known yet.  If you would use the name with '#' characters
then the autoload script IS loaded.

Be careful to not refer to an item in an autoload script that does trigger
loading it unintentionally.  For example, when setting an option that takes a
function name, make sure to use a string, not a function reference: >
	import autoload 'qftf.vim'
	&quickfixtextfunc = 'qftf.Func'  # autoload script NOT loaded
	&quickfixtextfunc = qftf.Func    # autoload script IS loaded
On the other hand, it can be useful to load the script early, at a time when
any errors should be given.

For testing the |test_override()| function can be used to have the
`import autoload` load the script right away, so that the items and types can
be checked without waiting for them to be actually used: >
	test_override('autoload', 1)
Reset it later with: >
	test_override('autoload', 0)
Or: >
	test_override('ALL', 0)


==============================================================================

6. Classes and interfaces				*vim9-classes*

In legacy script a Dictionary could be used as a kind-of object, by adding
members that are functions.  However, this is quite inefficient and requires
the writer to do the work of making sure all the objects have the right
members.  See |Dictionary-function|.

In |Vim9| script you can have classes, objects and interfaces like in most
popular object-oriented programming languages.  Since this is a lot of
functionality it is located in a separate help file: |vim9class.txt|.


==============================================================================

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 runtime 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 evaluating an
  expression.
- 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 also used by 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.  The |falsy-operator| was added for the mechanism to use a
  default value.
- 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.
- TypeScript has a complicated "import" statement that does not match how the
  Vim import mechanism works.  A much simpler mechanism is used instead, which
  matches that the imported script is only sourced once.


Declarations ~

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 varies.  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 have 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 other languages are doing.
Some details are unexpected and can be improved.  For example a boolean
condition would accept a string, convert it to a number and check if the
number is non-zero.  This is unexpected and often leads to mistakes, since
text not starting with a number would be converted to zero, which is
considered false.  Thus using a string for a condition would often not give an
error and be considered false.  That is confusing.

In Vim9 type checking is stricter to avoid mistakes.  Where a condition is
used, e.g. with the `:if` command and the `||` operator, only boolean-like
values are accepted:
	true:  `true`, `v:true`, `1`, `0 < 9`
	false: `false`, `v:false`, `0`, `0 > 9`
Note that the number zero is false and the number one is true.  This is more
permissive than most other languages.  It was done because many builtin
functions return these values, and changing that causes more problems than it
solves.  After using this for a while it turned out to work well.

If you have any type of value and want to use it as a boolean, use the `!!`
operator:
	true: `!!'text'`   `!![99]`   `!!{'x': 1}`   `!!99`
	false: `!!''`   `!![]`   `!!{}`

From a language like JavaScript we have this handy construct: >
	GetName() || 'unknown'
However, this conflicts with only allowing a boolean for a condition.
Therefore the "??" operator was added: >
	GetName() ?? 'unknown'
Here you can explicitly express your intention to use the value as-is and not
result in a boolean. This is called the |falsy-operator|.


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,
  some of these are 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 functions, variables and classes.
- 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, its items are cached and loading it again is
  not needed.
- The Vim-specific use of "s:" to make things script-local can be dropped.

When sourcing a Vim9 script (from a Vim9 or 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 well.

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, a `:defcompile` command at the end of the script will help out.


Why not use an existing 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 process, 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.



 vim:tw=78:ts=8:noet:ft=help:norl: