blob: 1782f179a3baa065994672890119e6291e9ab256 [file] [log] [blame]
Bram Moolenaar6304be62021-11-27 10:57:26 +00001*vim9.txt* For Vim version 8.2. Last change: 2021 Nov 22
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
8
Bram Moolenaardcc58e02020-12-28 20:53:21 +01009Vim9 script commands and expressions. *Vim9* *vim9*
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010010
11Most expression help is in |eval.txt|. This file is about the new syntax and
12features in Vim9 script.
13
14THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
15
16
Bram Moolenaar7e6a5152021-01-02 16:39:53 +0100171. What is Vim9 script? |Vim9-script|
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100182. Differences |vim9-differences|
193. New style functions |fast-functions|
204. Types |vim9-types|
215. Namespace, Import and Export |vim9script|
Bram Moolenaar1d59aa12020-09-19 18:50:13 +0200226. Future work: classes |vim9-classes|
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010023
249. Rationale |vim9-rationale|
25
26==============================================================================
27
Bram Moolenaar2b327002020-12-26 15:39:31 +0100281. What is Vim9 script? *Vim9-script*
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010029
30THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
31
Bram Moolenaar7ceefb32020-05-01 16:07:38 +020032Vim script has been growing over time, while preserving backwards
33compatibility. That means bad choices from the past often can't be changed
Bram Moolenaar73fef332020-06-21 22:12:03 +020034and compatibility with Vi restricts possible solutions. Execution is quite
Bram Moolenaar7ceefb32020-05-01 16:07:38 +020035slow, each line is parsed every time it is executed.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010036
Bram Moolenaar7ceefb32020-05-01 16:07:38 +020037The main goal of Vim9 script is to drastically improve performance. This is
38accomplished by compiling commands into instructions that can be efficiently
39executed. An increase in execution speed of 10 to 100 times can be expected.
40
41A secondary goal is to avoid Vim-specific constructs and get closer to
42commonly used programming languages, such as JavaScript, TypeScript and Java.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010043
44The performance improvements can only be achieved by not being 100% backwards
Bram Moolenaar388a5d42020-05-26 21:20:45 +020045compatible. For example, making function arguments available in the
46"a:" dictionary adds quite a lot of overhead. In a Vim9 function this
47dictionary is not available. Other differences are more subtle, such as how
48errors are handled.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010049
50The Vim9 script syntax and semantics are used in:
51- a function defined with the `:def` command
52- a script file where the first command is `vim9script`
Bram Moolenaar1d59aa12020-09-19 18:50:13 +020053- an autocommand defined in the context of the above
Bram Moolenaar39f3b142021-02-14 12:57:36 +010054- a command prefixed with the `vim9cmd` command modifier
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010055
Bram Moolenaar82be4842021-01-11 19:40:15 +010056When using `:function` in a Vim9 script file the legacy syntax is used, with
57the highest |scriptversion|. However, this can be confusing and is therefore
58discouraged.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010059
Bram Moolenaar7ceefb32020-05-01 16:07:38 +020060Vim9 script and legacy Vim script can be mixed. There is no requirement to
Bram Moolenaar1d59aa12020-09-19 18:50:13 +020061rewrite old scripts, they keep working as before. You may want to use a few
62`:def` functions for code that needs to be fast.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010063
Bram Moolenaar96cf4ba2021-04-24 14:15:41 +020064:vim9[cmd] {cmd} *:vim9* *:vim9cmd*
Bram Moolenaar39f3b142021-02-14 12:57:36 +010065 Execute {cmd} using Vim9 script syntax and semantics.
66 Useful when typing a command and in a legacy script or
67 function.
68
Bram Moolenaar96cf4ba2021-04-24 14:15:41 +020069:leg[acy] {cmd} *:leg* *:legacy*
70 Execute {cmd} using legacy script syntax and semantics. Only
71 useful in a Vim9 script or a :def function.
72 Note that {cmd} cannot use local variables, since it is parsed
73 with legacy expression syntax.
74
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010075==============================================================================
76
772. Differences from legacy Vim script *vim9-differences*
78
79THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
80
Bram Moolenaard58a3bf2020-09-28 21:48:16 +020081Overview ~
82
83Brief summary of the differences you will most often encounter when using Vim9
84script and `:def` functions; details are below:
85- Comments start with #, not ": >
Bram Moolenaar82be4842021-01-11 19:40:15 +010086 echo "hello" # comment
Bram Moolenaard58a3bf2020-09-28 21:48:16 +020087- Using a backslash for line continuation is hardly ever needed: >
Bram Moolenaar82be4842021-01-11 19:40:15 +010088 echo "hello "
Bram Moolenaard58a3bf2020-09-28 21:48:16 +020089 .. yourName
90 .. ", how are you?"
91- White space is required in many places.
92- Assign values without `:let`, declare variables with `:var`: >
Bram Moolenaar82be4842021-01-11 19:40:15 +010093 var count = 0
Bram Moolenaard58a3bf2020-09-28 21:48:16 +020094 count += 3
95- Constants can be declared with `:final` and `:const`: >
Bram Moolenaar82be4842021-01-11 19:40:15 +010096 final matches = [] # add matches
Bram Moolenaard58a3bf2020-09-28 21:48:16 +020097 const names = ['Betty', 'Peter'] # cannot be changed
98- `:final` cannot be used as an abbreviation of `:finally`.
99- Variables and functions are script-local by default.
100- Functions are declared with argument types and return type: >
101 def CallMe(count: number, message: string): bool
102- Call functions without `:call`: >
Bram Moolenaar82be4842021-01-11 19:40:15 +0100103 writefile(['done'], 'file.txt')
Bram Moolenaard2ea7cf2021-05-30 20:54:13 +0200104- You cannot use `:xit`, `:t`, `:k`, `:append`, `:change`, `:insert`, `:open`,
105 and `:s` or `:d` with only flags.
Bram Moolenaar22863042021-10-16 15:23:36 +0100106- You cannot use curly-braces names.
Bram Moolenaard58a3bf2020-09-28 21:48:16 +0200107- A range before a command must be prefixed with a colon: >
Bram Moolenaar82be4842021-01-11 19:40:15 +0100108 :%s/this/that
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200109- Executing a register with "@r" does not work, you can prepend a colon or use
110 `:exe`: >
111 :exe @a
Bram Moolenaar82be4842021-01-11 19:40:15 +0100112- Unless mentioned specifically, the highest |scriptversion| is used.
Bram Moolenaard58a3bf2020-09-28 21:48:16 +0200113
114
Bram Moolenaar2c330432020-04-13 14:41:35 +0200115Comments starting with # ~
116
Bram Moolenaarf5be8cd2020-07-17 20:36:00 +0200117In legacy Vim script comments start with double quote. In Vim9 script
118comments start with #. >
119 # declarations
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200120 var count = 0 # number of occurrences
Bram Moolenaar2c330432020-04-13 14:41:35 +0200121
Bram Moolenaarf5be8cd2020-07-17 20:36:00 +0200122The reason is that a double quote can also be the start of a string. In many
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200123places, especially halfway through an expression with a line break, it's hard
124to tell what the meaning is, since both a string and a comment can be followed
125by arbitrary text. To avoid confusion only # comments are recognized. This
126is the same as in shell scripts and Python programs.
Bram Moolenaarf5be8cd2020-07-17 20:36:00 +0200127
128In Vi # is a command to list text with numbers. In Vim9 script you can use
129`:number` for that. >
Bram Moolenaarae616492020-07-28 20:07:27 +0200130 101 number
Bram Moolenaarf5be8cd2020-07-17 20:36:00 +0200131
132To improve readability there must be a space between a command and the #
Bram Moolenaar2b327002020-12-26 15:39:31 +0100133that starts a comment: >
Bram Moolenaardcc58e02020-12-28 20:53:21 +0100134 var name = value # comment
135 var name = value# error!
Bram Moolenaar2b327002020-12-26 15:39:31 +0100136
Bram Moolenaar38a3bfa2021-03-29 22:14:55 +0200137Do not start a comment with #{, it looks like the legacy dictionary literal
138and produces an error where this might be confusing. #{{ or #{{{ are OK,
139these can be used to start a fold.
140
Bram Moolenaardcc58e02020-12-28 20:53:21 +0100141In legacy Vim script # is also used for the alternate file name. In Vim9
142script you need to use %% instead. Instead of ## use %%% (stands for all
143arguments).
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200144
Bram Moolenaar2c330432020-04-13 14:41:35 +0200145
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100146Vim9 functions ~
147
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200148A function defined with `:def` is compiled. Execution is many times faster,
Bram Moolenaar962c43b2021-04-10 17:18:09 +0200149often 10 to 100 times.
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200150
Bram Moolenaar388a5d42020-05-26 21:20:45 +0200151Many errors are already found when compiling, before the function is executed.
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200152The syntax is strict, to enforce code that is easy to read and understand.
153
Bram Moolenaar962c43b2021-04-10 17:18:09 +0200154Compilation is done when any of these is encountered:
Bram Moolenaar1b884a02020-12-10 21:11:27 +0100155- the first time the function is called
Bram Moolenaar962c43b2021-04-10 17:18:09 +0200156- when the `:defcompile` command is encountered in the script after the
Bram Moolenaar207f0092020-08-30 17:20:20 +0200157 function was defined
158- `:disassemble` is used for the function.
159- a function that is compiled calls the function or uses it as a function
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200160 reference (so that the argument and return types can be checked)
Bram Moolenaar962c43b2021-04-10 17:18:09 +0200161 *E1091*
162If compilation fails it is not tried again on the next call, instead this
163error is given: "E1091: Function is not compiled: {name}".
Bram Moolenaar4c295022021-05-02 17:19:11 +0200164Compilation will fail when encountering a user command that has not been
165created yet. In this case you can call `execute()` to invoke it at runtime. >
166 def MyFunc()
167 execute('DefinedLater')
168 enddef
Bram Moolenaar388a5d42020-05-26 21:20:45 +0200169
170`:def` has no options like `:function` does: "range", "abort", "dict" or
Bram Moolenaar1b884a02020-12-10 21:11:27 +0100171"closure". A `:def` function always aborts on an error (unless `:silent!` was
172used for the command or inside a `:try` block), does not get a range passed
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100173cannot be a "dict" function, and can always be a closure.
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200174 *vim9-no-dict-function*
Bram Moolenaar74235772021-06-12 14:53:05 +0200175Later classes will be added, which replaces the "dict function" mechanism.
176For now you will need to pass the dictionary explicitly: >
177 def DictFunc(d: dict<any>, arg: string)
178 echo d[arg]
179 enddef
180 var d = {item: 'value', func: DictFunc}
181 d.func(d, 'item')
182
Bram Moolenaar34cc7d82021-09-21 20:09:51 +0200183You can call a legacy dict function though: >
184 func Legacy() dict
185 echo self.value
186 endfunc
187 def CallLegacy()
188 var d = {func: Legacy, value: 'text'}
189 d.func()
190 enddef
191
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200192The argument types and return type need to be specified. The "any" type can
193be used, type checking will then be done at runtime, like with legacy
194functions.
195
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200196Arguments are accessed by name, without "a:", just like any other language.
197There is no "a:" dictionary or "a:000" list.
Bram Moolenaar962c43b2021-04-10 17:18:09 +0200198 *vim9-variable-arguments*
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200199Variable arguments are defined as the last argument, with a name and have a
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200200list type, similar to TypeScript. For example, a list of numbers: >
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200201 def MyFunc(...itemlist: list<number>)
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100202 for item in itemlist
203 ...
204
Bram Moolenaar38a3bfa2021-03-29 22:14:55 +0200205When a function argument is optional (it has a default value) passing `v:none`
206as the argument results in using the default value. This is useful when you
207want to specify a value for an argument that comes after an argument that
208should use its default value. Example: >
Bram Moolenaar22863042021-10-16 15:23:36 +0100209 def MyFunc(one = 'one', last = 'last')
Bram Moolenaar38a3bfa2021-03-29 22:14:55 +0200210 ...
211 enddef
212 MyFunc(v:none, 'LAST') # first argument uses default value 'one'
Bram Moolenaar962c43b2021-04-10 17:18:09 +0200213<
214 *vim9-ignored-argument*
215The argument "_" (an underscore) can be used to ignore the argument. This is
216most useful in callbacks where you don't need it, but do need to give an
217argument to match the call. E.g. when using map() two arguments are passed,
218the key and the value, to ignore the key: >
219 map(myList, (_, v) => v * 2)
220There is no error for using the "_" argument multiple times. No type needs to
221be given.
Bram Moolenaar38a3bfa2021-03-29 22:14:55 +0200222
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100223
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200224Functions and variables are script-local by default ~
Bram Moolenaar65e0d772020-06-14 17:29:55 +0200225 *vim9-scopes*
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200226When using `:function` or `:def` to specify a new function at the script level
227in a Vim9 script, the function is local to the script, as if "s:" was
Bram Moolenaar2bb26582020-10-03 22:52:39 +0200228prefixed. Using the "s:" prefix is optional. To define a global function or
229variable the "g:" prefix must be used. For functions in an autoload script
230the "name#" prefix is sufficient. >
Bram Moolenaarea2d8d22020-07-29 22:11:05 +0200231 def ThisFunction() # script-local
232 def s:ThisFunction() # script-local
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200233 def g:ThatFunction() # global
Bram Moolenaarea2d8d22020-07-29 22:11:05 +0200234 def scriptname#function() # autoload
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200235
Bram Moolenaar2bb26582020-10-03 22:52:39 +0200236When using `:function` or `:def` to specify a nested function inside a `:def`
237function, this nested function is local to the code block it is defined in.
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200238In a `:def` function it is not possible to define a script-local function. It
Bram Moolenaar2bb26582020-10-03 22:52:39 +0200239is possible to define a global function by using the "g:" prefix.
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200240
241When referring to a function and no "s:" or "g:" prefix is used, Vim will
Bram Moolenaar13106602020-10-04 16:06:05 +0200242search for the function:
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200243- in the function scope, in block scopes
Bram Moolenaar13106602020-10-04 16:06:05 +0200244- in the script scope, possibly imported
245- in the list of global functions
246However, it is recommended to always use "g:" to refer to a global function
247for clarity.
248
Bram Moolenaar38a3bfa2021-03-29 22:14:55 +0200249Since a script-local function reference can be used without "s:" the name must
Bram Moolenaardad44732021-03-31 20:07:33 +0200250start with an upper case letter even when using the "s:" prefix. In legacy
Bram Moolenaar38a3bfa2021-03-29 22:14:55 +0200251script "s:funcref" could be used, because it could not be referred to with
252"funcref". In Vim9 script it can, therefore "s:Funcref" must be used to avoid
253that the name interferes with builtin functions.
254
Bram Moolenaar13106602020-10-04 16:06:05 +0200255In all cases the function must be defined before used. That is when it is
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100256called, when `:defcompile` causes it to be compiled, or when code that calls
257it is being compiled (to figure out the return type).
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200258
Bram Moolenaare7b1ea02020-08-07 19:54:59 +0200259The result is that functions and variables without a namespace can usually be
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200260found in the script, either defined there or imported. Global functions and
Bram Moolenaare7b1ea02020-08-07 19:54:59 +0200261variables could be defined anywhere (good luck finding out where!).
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200262
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200263Global functions can still be defined and deleted at nearly any time. In
Bram Moolenaar2cfb4a22020-05-07 18:56:00 +0200264Vim9 script script-local functions are defined once when the script is sourced
Bram Moolenaar388a5d42020-05-26 21:20:45 +0200265and cannot be deleted or replaced.
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200266
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100267When compiling a function and a function call is encountered for a function
268that is not (yet) defined, the |FuncUndefined| autocommand is not triggered.
269You can use an autoload function if needed, or call a legacy function and have
270|FuncUndefined| triggered there.
271
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +0200272
Bram Moolenaar2b327002020-12-26 15:39:31 +0100273Reloading a Vim9 script clears functions and variables by default ~
274 *vim9-reload*
275When loading a legacy Vim script a second time nothing is removed, the
276commands will replace existing variables and functions and create new ones.
277
278When loading a Vim9 script a second time all existing script-local functions
279and variables are deleted, thus you start with a clean slate. This is useful
280if you are developing a plugin and want to try a new version. If you renamed
281something you don't have to worry about the old name still hanging around.
282
283If you do want to keep items, use: >
Bram Moolenaardcc58e02020-12-28 20:53:21 +0100284 vim9script noclear
Bram Moolenaar2b327002020-12-26 15:39:31 +0100285
286You want to use this in scripts that use a `finish` command to bail out at
287some point when loaded again. E.g. when a buffer local option is set: >
Bram Moolenaardcc58e02020-12-28 20:53:21 +0100288 vim9script noclear
Bram Moolenaar2b327002020-12-26 15:39:31 +0100289 setlocal completefunc=SomeFunc
Bram Moolenaardcc58e02020-12-28 20:53:21 +0100290 if exists('*g:SomeFunc') | finish | endif
Bram Moolenaar2b327002020-12-26 15:39:31 +0100291 def g:SomeFunc()
292 ....
293
Bram Moolenaar2b327002020-12-26 15:39:31 +0100294
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200295Variable declarations with :var, :final and :const ~
Bram Moolenaar2bb26582020-10-03 22:52:39 +0200296 *vim9-declaration* *:var*
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200297Local variables need to be declared with `:var`. Local constants need to be
298declared with `:final` or `:const`. We refer to both as "variables" in this
299section.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100300
301Variables can be local to a script, function or code block: >
302 vim9script
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200303 var script_var = 123
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100304 def SomeFunc()
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200305 var func_var = script_var
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100306 if cond
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200307 var block_var = func_var
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100308 ...
309
310The variables are only visible in the block where they are defined and nested
311blocks. Once the block ends the variable is no longer accessible: >
312 if cond
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200313 var inner = 5
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100314 else
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200315 var inner = 0
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100316 endif
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200317 echo inner # Error!
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100318
319The declaration must be done earlier: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200320 var inner: number
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100321 if cond
322 inner = 5
323 else
324 inner = 0
325 endif
326 echo inner
327
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200328To intentionally hide a variable from code that follows, a block can be
329used: >
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100330 {
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200331 var temp = 'temp'
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100332 ...
333 }
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200334 echo temp # Error!
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100335
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +0200336This is especially useful in a user command: >
337
338 command -range Rename {
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200339 var save = @a
340 @a = 'some expression'
341 echo 'do something with ' .. @a
342 @a = save
343 }
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +0200344
345And with autocommands: >
346
347 au BufWritePre *.go {
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200348 var save = winsaveview()
349 silent! exe ':%! some formatting command'
350 winrestview(save)
351 }
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +0200352
353Although using a :def function probably works better.
354
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +0200355Declaring a variable with a type but without an initializer will initialize to
356zero, false or empty.
357
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200358In Vim9 script `:let` cannot be used. An existing variable is assigned to
359without any command. The same for global, window, tab, buffer and Vim
360variables, because they are not really declared. They can also be deleted
Bram Moolenaarf5a48012020-08-01 17:00:03 +0200361with `:unlet`.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100362
Bram Moolenaar38a3bfa2021-03-29 22:14:55 +0200363`:lockvar` does not work on local variables. Use `:const` and `:final`
364instead.
365
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200366The `exists()` and `exists_compiled()` functions do not work on local variables
367or arguments.
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +0200368
Bram Moolenaar9faec4e2021-02-27 16:38:07 +0100369Variables, functions and function arguments cannot shadow previously defined
370or imported variables and functions in the same script file.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100371Variables may shadow Ex commands, rename the variable if needed.
372
Bram Moolenaar130cbfc2021-04-07 21:07:20 +0200373Global variables must be prefixed with "g:", also at the script level. >
Bram Moolenaard1caa942020-04-10 22:10:56 +0200374 vim9script
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200375 var script_local = 'text'
Bram Moolenaar2547aa92020-07-26 17:00:44 +0200376 g:global = 'value'
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200377 var Funcref = g:ThatFunction
Bram Moolenaard1caa942020-04-10 22:10:56 +0200378
Bram Moolenaar130cbfc2021-04-07 21:07:20 +0200379Global functions must be prefixed with "g:" when defining them, but can be
380called without "g:". >
381 vim9script
382 def g:GlobalFunc(): string
383 return 'text'
384 enddef
385 echo GlobalFunc()
386The "g:" prefix is not needed for auto-load functions.
387
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200388 *vim9-function-defined-later*
389Although global functions can be called without the "g:" prefix, they must
390exist when compiled. By adding the "g:" prefix the function can be defined
391later. Example: >
392 def CallPluginFunc()
393 if exists('g:loaded_plugin')
394 g:PluginFunc()
395 endif
396 enddef
397
398If you would do it like this you get an error at compile time that
399"PluginFunc" does not exist, even when "g:loaded_plugin" does not exist: >
400 def CallPluginFunc()
401 if exists('g:loaded_plugin')
402 PluginFunc() # Error - function not found
403 endif
404 enddef
405
406You can use exists_compiled() to avoid the error, but then the function would
407not be called, even when "g:loaded_plugin" is defined later: >
408 def CallPluginFunc()
409 if exists_compiled('g:loaded_plugin')
410 PluginFunc() # Function may never be called
411 endif
412 enddef
413
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200414Since `&opt = value` is now assigning a value to option "opt", ":&" cannot be
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100415used to repeat a `:substitute` command.
Bram Moolenaar56994d22021-04-17 16:31:09 +0200416 *vim9-unpack-ignore*
Bram Moolenaarf93bbd02021-04-10 22:35:43 +0200417For an unpack assignment the underscore can be used to ignore a list item,
418similar to how a function argument can be ignored: >
419 [a, _, c] = theList
Bram Moolenaar56994d22021-04-17 16:31:09 +0200420To ignore any remaining items: >
Bram Moolenaarf93bbd02021-04-10 22:35:43 +0200421 [a, b; _] = longList
422
423< *E1092*
424Declaring more than one variable at a time, using the unpack notation, is
425currently not supported: >
426 var [v1, v2] = GetValues() # Error!
427That is because the type needs to be inferred from the list item type, which
428isn't that easy.
429
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200430
431Constants ~
432 *vim9-const* *vim9-final*
433How constants work varies between languages. Some consider a variable that
434can't be assigned another value a constant. JavaScript is an example. Others
435also make the value immutable, thus when a constant uses a list, the list
436cannot be changed. In Vim9 we can use both.
437
438`:const` is used for making both the variable and the value a constant. Use
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +0200439this for composite structures that you want to make sure will not be modified.
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200440Example: >
441 const myList = [1, 2]
442 myList = [3, 4] # Error!
443 myList[0] = 9 # Error!
Bram Moolenaar9faec4e2021-02-27 16:38:07 +0100444 myList->add(3) # Error!
Bram Moolenaar2bb26582020-10-03 22:52:39 +0200445< *:final*
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200446`:final` is used for making only the variable a constant, the value can be
447changed. This is well known from Java. Example: >
448 final myList = [1, 2]
449 myList = [3, 4] # Error!
450 myList[0] = 9 # OK
Bram Moolenaar9faec4e2021-02-27 16:38:07 +0100451 myList->add(3) # OK
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +0200452
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +0200453It is common to write constants as ALL_CAPS, but you don't have to.
454
455The constant only applies to the value itself, not what it refers to. >
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200456 final females = ["Mary"]
457 const NAMES = [["John", "Peter"], females]
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +0200458 NAMES[0] = ["Jack"] # Error!
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200459 NAMES[0][0] = "Jack" # Error!
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +0200460 NAMES[1] = ["Emma"] # Error!
Bram Moolenaar82be4842021-01-11 19:40:15 +0100461 NAMES[1][0] = "Emma" # OK, now females[0] == "Emma"
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +0200462
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100463
464Omitting :call and :eval ~
465
466Functions can be called without `:call`: >
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200467 writefile(lines, 'file')
Bram Moolenaar560979e2020-02-04 22:53:05 +0100468Using `:call` is still possible, but this is discouraged.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100469
470A method call without `eval` is possible, so long as the start is an
Bram Moolenaar0289a092021-03-14 18:40:19 +0100471identifier or can't be an Ex command. For a function either "(" or "->" must
472be following, without a line break. Examples: >
Bram Moolenaarae616492020-07-28 20:07:27 +0200473 myList->add(123)
474 g:myList->add(123)
475 [1, 2, 3]->Process()
Bram Moolenaar2bede172020-11-19 18:53:18 +0100476 {a: 1, b: 2}->Process()
Bram Moolenaarae616492020-07-28 20:07:27 +0200477 "foobar"->Process()
478 ("foobar")->Process()
479 'foobar'->Process()
480 ('foobar')->Process()
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100481
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200482In the rare case there is ambiguity between a function name and an Ex command,
Bram Moolenaare7b1ea02020-08-07 19:54:59 +0200483prepend ":" to make clear you want to use the Ex command. For example, there
484is both the `:substitute` command and the `substitute()` function. When the
485line starts with `substitute(` this will use the function. Prepend a colon to
486use the command instead: >
Bram Moolenaar0c6ceaf2020-02-22 18:36:32 +0100487 :substitute(pattern (replacement (
Bram Moolenaar5b1c8fe2020-02-21 18:42:43 +0100488
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +0200489If the expression starts with "!" this is interpreted as a shell command, not
490negation of a condition. Thus this is a shell command: >
491 !shellCommand->something
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200492Put the expression in parentheses to use the "!" for negation: >
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +0200493 (!expression)->Method()
494
Bram Moolenaarcc390ff2020-02-29 22:06:30 +0100495Note that while variables need to be defined before they can be used,
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200496functions can be called before being defined. This is required to allow
497for cyclic dependencies between functions. It is slightly less efficient,
Bram Moolenaarcc390ff2020-02-29 22:06:30 +0100498since the function has to be looked up by name. And a typo in the function
Bram Moolenaarae616492020-07-28 20:07:27 +0200499name will only be found when the function is called.
Bram Moolenaarcc390ff2020-02-29 22:06:30 +0100500
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100501
Bram Moolenaard1caa942020-04-10 22:10:56 +0200502Omitting function() ~
503
504A user defined function can be used as a function reference in an expression
505without `function()`. The argument types and return type will then be checked.
506The function must already have been defined. >
507
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200508 var Funcref = MyFunction
Bram Moolenaard1caa942020-04-10 22:10:56 +0200509
510When using `function()` the resulting type is "func", a function with any
Bram Moolenaar90df4b92021-07-07 20:26:08 +0200511number of arguments and any return type (including void). The function can be
512defined later.
Bram Moolenaard1caa942020-04-10 22:10:56 +0200513
514
Bram Moolenaar2b327002020-12-26 15:39:31 +0100515Lambda using => instead of -> ~
Bram Moolenaar130cbfc2021-04-07 21:07:20 +0200516 *vim9-lambda*
Bram Moolenaar65c44152020-12-24 15:14:01 +0100517In legacy script there can be confusion between using "->" for a method call
518and for a lambda. Also, when a "{" is found the parser needs to figure out if
519it is the start of a lambda or a dictionary, which is now more complicated
520because of the use of argument types.
521
522To avoid these problems Vim9 script uses a different syntax for a lambda,
Bram Moolenaar74235772021-06-12 14:53:05 +0200523which is similar to JavaScript: >
Bram Moolenaar65c44152020-12-24 15:14:01 +0100524 var Lambda = (arg) => expression
525
Bram Moolenaar2b327002020-12-26 15:39:31 +0100526No line break is allowed in the arguments of a lambda up to and including the
Bram Moolenaar4d8f4762021-06-27 15:18:56 +0200527"=>" (so that Vim can tell the difference between an expression in parentheses
Bram Moolenaar2346a632021-06-13 19:02:49 +0200528and lambda arguments). This is OK: >
Bram Moolenaar65c44152020-12-24 15:14:01 +0100529 filter(list, (k, v) =>
530 v > 0)
531This does not work: >
532 filter(list, (k, v)
533 => v > 0)
Bram Moolenaardcc58e02020-12-28 20:53:21 +0100534This also does not work: >
Bram Moolenaar65c44152020-12-24 15:14:01 +0100535 filter(list, (k,
536 v) => v > 0)
Bram Moolenaardcc58e02020-12-28 20:53:21 +0100537But you can use a backslash to concatenate the lines before parsing: >
538 filter(list, (k,
539 \ v)
540 \ => v > 0)
Bram Moolenaar962c43b2021-04-10 17:18:09 +0200541< *vim9-lambda-arguments*
542In legacy script a lambda could be called with any number of extra arguments,
543there was no way to warn for not using them. In Vim9 script the number of
544arguments must match. If you do want to accept any arguments, or any further
545arguments, use "..._", which makes the function accept
546|vim9-variable-arguments|. Example: >
547 var Callback = (..._) => 'anything'
548 echo Callback(1, 2, 3) # displays "anything"
549
Bram Moolenaar130cbfc2021-04-07 21:07:20 +0200550< *inline-function*
Bram Moolenaar65c44152020-12-24 15:14:01 +0100551Additionally, a lambda can contain statements in {}: >
552 var Lambda = (arg) => {
553 g:was_called = 'yes'
554 return expression
555 }
Bram Moolenaar130cbfc2021-04-07 21:07:20 +0200556This can be useful for a timer, for example: >
557 var count = 0
558 var timer = timer_start(500, (_) => {
559 count += 1
560 echom 'Handler called ' .. count
561 }, {repeat: 3})
562
Bram Moolenaar38a3bfa2021-03-29 22:14:55 +0200563
564The ending "}" must be at the start of a line. It can be followed by other
565characters, e.g.: >
566 var d = mapnew(dict, (k, v): string => {
567 return 'value'
568 })
569No command can follow the "{", only a comment can be used there.
570
571Rationale: The "}" cannot be after a command because it would require parsing
572the commands to find it. For consistency with that no command can follow the
573"{". Unfortunately this means using "() => { command }" does not work, line
574breaks are always required.
Bram Moolenaar65c44152020-12-24 15:14:01 +0100575
Bram Moolenaare0e39172021-01-25 21:14:57 +0100576 *vim9-curly*
Bram Moolenaar2b327002020-12-26 15:39:31 +0100577To avoid the "{" of a dictionary literal to be recognized as a statement block
Bram Moolenaar9faec4e2021-02-27 16:38:07 +0100578wrap it in parentheses: >
Bram Moolenaar2b327002020-12-26 15:39:31 +0100579 var Lambda = (arg) => ({key: 42})
Bram Moolenaar65c44152020-12-24 15:14:01 +0100580
Bram Moolenaare0e39172021-01-25 21:14:57 +0100581Also when confused with the start of a command block: >
582 ({
583 key: value
584 })->method()
585
Bram Moolenaar65c44152020-12-24 15:14:01 +0100586
Bram Moolenaar4fdae992020-04-12 16:38:57 +0200587Automatic line continuation ~
588
589In many cases it is obvious that an expression continues on the next line. In
Bram Moolenaardcc58e02020-12-28 20:53:21 +0100590those cases there is no need to prefix the line with a backslash (see
591|line-continuation|). For example, when a list spans multiple lines: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200592 var mylist = [
Bram Moolenaar4fdae992020-04-12 16:38:57 +0200593 'one',
594 'two',
595 ]
Bram Moolenaare6085c52020-04-12 20:19:16 +0200596And when a dict spans multiple lines: >
Bram Moolenaar2bede172020-11-19 18:53:18 +0100597 var mydict = {
Bram Moolenaare6085c52020-04-12 20:19:16 +0200598 one: 1,
599 two: 2,
600 }
Bram Moolenaar74235772021-06-12 14:53:05 +0200601With a function call: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200602 var result = Func(
Bram Moolenaare6085c52020-04-12 20:19:16 +0200603 arg1,
604 arg2
605 )
606
Bram Moolenaardf069ee2020-06-22 23:02:51 +0200607For binary operators in expressions not in [], {} or () a line break is
608possible just before or after the operator. For example: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200609 var text = lead
Bram Moolenaardf069ee2020-06-22 23:02:51 +0200610 .. middle
611 .. end
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200612 var total = start +
Bram Moolenaar82be4842021-01-11 19:40:15 +0100613 end -
Bram Moolenaar9c7e6dd2020-04-12 20:55:20 +0200614 correction
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200615 var result = positive
Bram Moolenaardf069ee2020-06-22 23:02:51 +0200616 ? PosFunc(arg)
617 : NegFunc(arg)
Bram Moolenaar9c7e6dd2020-04-12 20:55:20 +0200618
Bram Moolenaar2547aa92020-07-26 17:00:44 +0200619For a method call using "->" and a member using a dot, a line break is allowed
620before it: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200621 var result = GetBuilder()
Bram Moolenaar73fef332020-06-21 22:12:03 +0200622 ->BuilderSetWidth(333)
623 ->BuilderSetHeight(777)
624 ->BuilderBuild()
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200625 var result = MyDict
Bram Moolenaar2547aa92020-07-26 17:00:44 +0200626 .member
Bram Moolenaar73fef332020-06-21 22:12:03 +0200627
Bram Moolenaardcc58e02020-12-28 20:53:21 +0100628For commands that have an argument that is a list of commands, the | character
629at the start of the line indicates line continuation: >
630 autocmd BufNewFile *.match if condition
631 | echo 'match'
632 | endif
633
Bram Moolenaar22863042021-10-16 15:23:36 +0100634Note that this means that in heredoc the first line cannot start with a bar: >
Bram Moolenaar74235772021-06-12 14:53:05 +0200635 var lines =<< trim END
636 | this doesn't work
637 END
638Either use an empty line at the start or do not use heredoc. Or temporarily
639add the "C" flag to 'cpoptions': >
640 set cpo+=C
641 var lines =<< trim END
Bram Moolenaar22863042021-10-16 15:23:36 +0100642 | this works
Bram Moolenaar74235772021-06-12 14:53:05 +0200643 END
644 set cpo-=C
645If the heredoc is inside a function 'cpoptions' must be set before :def and
646restored after the :enddef.
647
648In places where line continuation with a backslash is still needed, such as
Bram Moolenaar90df4b92021-07-07 20:26:08 +0200649splitting up a long Ex command, comments can start with '#\ ': >
650 syn region Text
Bram Moolenaar74235772021-06-12 14:53:05 +0200651 \ start='foo'
652 #\ comment
653 \ end='bar'
Bram Moolenaar90df4b92021-07-07 20:26:08 +0200654Like with legacy script '"\ ' is used. This is also needed when line
655continuation is used without a backslash and a line starts with a bar: >
656 au CursorHold * echom 'BEFORE bar'
657 #\ some comment
658 | echom 'AFTER bar'
659<
660 *E1050*
Bram Moolenaardf069ee2020-06-22 23:02:51 +0200661To make it possible for the operator at the start of the line to be
Bram Moolenaar74235772021-06-12 14:53:05 +0200662recognized, it is required to put a colon before a range. This example will
663add "start" and print: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200664 var result = start
Bram Moolenaardf069ee2020-06-22 23:02:51 +0200665 + print
Bram Moolenaar7ff78462020-07-10 22:00:53 +0200666Like this: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200667 var result = start + print
Bram Moolenaar7ff78462020-07-10 22:00:53 +0200668
Bram Moolenaardf069ee2020-06-22 23:02:51 +0200669This will assign "start" and print a line: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +0200670 var result = start
Bram Moolenaardf069ee2020-06-22 23:02:51 +0200671 :+ print
Bram Moolenaar4fdae992020-04-12 16:38:57 +0200672
Bram Moolenaar23515b42020-11-29 14:36:24 +0100673Note that the colon is not required for the |+cmd| argument: >
674 edit +6 fname
675
Bram Moolenaar5e774c72020-04-12 21:53:00 +0200676It is also possible to split a function header over multiple lines, in between
677arguments: >
678 def MyFunc(
679 text: string,
680 separator = '-'
681 ): string
682
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100683Since a continuation line cannot be easily recognized the parsing of commands
Bram Moolenaar65c44152020-12-24 15:14:01 +0100684has been made stricter. E.g., because of the error in the first line, the
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100685second line is seen as a separate command: >
686 popup_create(some invalid expression, {
687 exit_cb: Func})
688Now "exit_cb: Func})" is actually a valid command: save any changes to the
689file "_cb: Func})" and exit. To avoid this kind of mistake in Vim9 script
690there must be white space between most command names and the argument.
691
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100692However, the argument of a command that is a command won't be recognized. For
693example, after "windo echo expr" a line break inside "expr" will not be seen.
694
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100695
Bram Moolenaar7ff78462020-07-10 22:00:53 +0200696Notes:
697- "enddef" cannot be used at the start of a continuation line, it ends the
698 current function.
699- No line break is allowed in the LHS of an assignment. Specifically when
700 unpacking a list |:let-unpack|. This is OK: >
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200701 [var1, var2] =
Bram Moolenaar7ff78462020-07-10 22:00:53 +0200702 Func()
703< This does not work: >
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200704 [var1,
Bram Moolenaar7ff78462020-07-10 22:00:53 +0200705 var2] =
706 Func()
707- No line break is allowed in between arguments of an `:echo`, `:execute` and
708 similar commands. This is OK: >
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200709 echo [1,
Bram Moolenaar7ff78462020-07-10 22:00:53 +0200710 2] [3,
711 4]
712< This does not work: >
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200713 echo [1, 2]
Bram Moolenaar7ff78462020-07-10 22:00:53 +0200714 [3, 4]
Bram Moolenaar74235772021-06-12 14:53:05 +0200715- In some cases it is difficult for Vim to parse a command, especially when
716 commands are used as an argument to another command, such as `windo`. In
717 those cases the line continuation with a backslash has to be used.
Bram Moolenaar4fdae992020-04-12 16:38:57 +0200718
Bram Moolenaar4c295022021-05-02 17:19:11 +0200719
720White space ~
721
722Vim9 script enforces proper use of white space. This is no longer allowed: >
723 var name=234 # Error!
724 var name= 234 # Error!
725 var name =234 # Error!
726There must be white space before and after the "=": >
727 var name = 234 # OK
728White space must also be put before the # that starts a comment after a
729command: >
730 var name = 234# Error!
731 var name = 234 # OK
732
733White space is required around most operators.
734
735White space is required in a sublist (list slice) around the ":", except at
736the start and end: >
737 otherlist = mylist[v : count] # v:count has a different meaning
738 otherlist = mylist[:] # make a copy of the List
739 otherlist = mylist[v :]
740 otherlist = mylist[: v]
741
742White space is not allowed:
743- Between a function name and the "(": >
744 Func (arg) # Error!
745 Func
746 \ (arg) # Error!
747 Func
748 (arg) # Error!
749 Func(arg) # OK
750 Func(
751 arg) # OK
752 Func(
753 arg # OK
754 )
755
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200756White space is not allowed in a `:set` command between the option name and a
757following "&", "!", "<", "=", "+=", "-=" or "^=".
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +0200758
Bram Moolenaar4c295022021-05-02 17:19:11 +0200759
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100760No curly braces expansion ~
761
762|curly-braces-names| cannot be used.
763
764
Bram Moolenaar2bede172020-11-19 18:53:18 +0100765Dictionary literals ~
766
767Traditionally Vim has supported dictionary literals with a {} syntax: >
768 let dict = {'key': value}
769
Bram Moolenaarc5e6a712020-12-04 19:12:14 +0100770Later it became clear that using a simple text key is very common, thus
771literal dictionaries were introduced in a backwards compatible way: >
Bram Moolenaar2bede172020-11-19 18:53:18 +0100772 let dict = #{key: value}
773
Bram Moolenaarc5e6a712020-12-04 19:12:14 +0100774However, this #{} syntax is unlike any existing language. As it turns out
775that using a literal key is much more common than using an expression, and
Bram Moolenaar2bede172020-11-19 18:53:18 +0100776considering that JavaScript uses this syntax, using the {} form for dictionary
Bram Moolenaarc5e6a712020-12-04 19:12:14 +0100777literals is considered a much more useful syntax. In Vim9 script the {} form
Bram Moolenaar2bede172020-11-19 18:53:18 +0100778uses literal keys: >
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100779 var dict = {key: value}
Bram Moolenaar2bede172020-11-19 18:53:18 +0100780
Bram Moolenaarc5e6a712020-12-04 19:12:14 +0100781This works for alphanumeric characters, underscore and dash. If you want to
782use another character, use a single or double quoted string: >
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100783 var dict = {'key with space': value}
784 var dict = {"key\twith\ttabs": value}
785 var dict = {'': value} # empty key
Bram Moolenaarc5e6a712020-12-04 19:12:14 +0100786
787In case the key needs to be an expression, square brackets can be used, just
788like in JavaScript: >
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100789 var dict = {["key" .. nr]: value}
Bram Moolenaar2bede172020-11-19 18:53:18 +0100790
Bram Moolenaar2e5910b2021-02-03 17:41:24 +0100791The key type can be string, number, bool or float. Other types result in an
792error. A number can be given with and without the []: >
793 var dict = {123: 'without', [456]: 'with'}
794 echo dict
795 {'456': 'with', '123': 'without'}
796
Bram Moolenaar2bede172020-11-19 18:53:18 +0100797
Bram Moolenaar10b94212021-02-19 21:42:57 +0100798No :xit, :t, :k, :append, :change or :insert ~
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100799
Bram Moolenaarf5a48012020-08-01 17:00:03 +0200800These commands are too easily confused with local variable names.
801Instead of `:x` or `:xit` you can use `:exit`.
802Instead of `:t` you can use `:copy`.
Bram Moolenaar10b94212021-02-19 21:42:57 +0100803Instead of `:k` you can use `:mark`.
Bram Moolenaar560979e2020-02-04 22:53:05 +0100804
805
806Comparators ~
807
808The 'ignorecase' option is not used for comparators that use strings.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100809
810
Bram Moolenaar4c295022021-05-02 17:19:11 +0200811Abort after error ~
812
813In legacy script, when an error is encountered, Vim continues to execute
814following lines. This can lead to a long sequence of errors and need to type
815CTRL-C to stop it. In Vim9 script execution of commands stops at the first
816error. Example: >
817 vim9script
818 var x = does-not-exist
819 echo 'not executed'
820
821
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100822For loop ~
823
Bram Moolenaar6304be62021-11-27 10:57:26 +0000824The loop variable must not exist yet: >
825 var i = 1
826 for i in [1, 2, 3] # Error!
827
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100828Legacy Vim script has some tricks to make a for loop over a list handle
829deleting items at the current or previous item. In Vim9 script it just uses
830the index, if items are deleted then items in the list will be skipped.
831Example legacy script: >
832 let l = [1, 2, 3, 4]
833 for i in l
834 echo i
835 call remove(l, index(l, i))
836 endfor
837Would echo:
838 1
839 2
840 3
841 4
842In compiled Vim9 script you get:
843 1
844 3
845Generally, you should not change the list that is iterated over. Make a copy
846first if needed.
847
848
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100849Conditions and expressions ~
850
Bram Moolenaar13106602020-10-04 16:06:05 +0200851Conditions and expressions are mostly working like they do in other languages.
852Some values are different from legacy Vim script:
853 value legacy Vim script Vim9 script ~
854 0 falsy falsy
855 1 truthy truthy
856 99 truthy Error!
857 "0" falsy Error!
858 "99" truthy Error!
859 "text" falsy Error!
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100860
Bram Moolenaar13106602020-10-04 16:06:05 +0200861For the "??" operator and when using "!" then there is no error, every value
862is either falsy or truthy. This is mostly like JavaScript, except that an
863empty list and dict is falsy:
864
865 type truthy when ~
Bram Moolenaar7e6a5152021-01-02 16:39:53 +0100866 bool true, v:true or 1
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100867 number non-zero
868 float non-zero
869 string non-empty
870 blob non-empty
871 list non-empty (different from JavaScript)
872 dictionary non-empty (different from JavaScript)
Bram Moolenaard1caa942020-04-10 22:10:56 +0200873 func when there is a function name
Bram Moolenaar7e6a5152021-01-02 16:39:53 +0100874 special true or v:true
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100875 job when not NULL
876 channel when not NULL
877 class when not NULL
Bram Moolenaar7e6a5152021-01-02 16:39:53 +0100878 object when not NULL (TODO: when isTrue() returns true)
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100879
Bram Moolenaar2bb26582020-10-03 22:52:39 +0200880The boolean operators "||" and "&&" expect the values to be boolean, zero or
881one: >
882 1 || false == true
883 0 || 1 == true
884 0 || false == false
885 1 && true == true
886 0 && 1 == false
887 8 || 0 Error!
888 'yes' && 0 Error!
889 [] || 99 Error!
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100890
Bram Moolenaar2bb26582020-10-03 22:52:39 +0200891When using "!" for inverting, there is no error for using any type and the
Bram Moolenaar13106602020-10-04 16:06:05 +0200892result is a boolean. "!!" can be used to turn any value into boolean: >
Bram Moolenaar82be4842021-01-11 19:40:15 +0100893 !'yes' == false
Bram Moolenaar13106602020-10-04 16:06:05 +0200894 !![] == false
Bram Moolenaar82be4842021-01-11 19:40:15 +0100895 !![1, 2, 3] == true
Bram Moolenaar2bb26582020-10-03 22:52:39 +0200896
897When using "`.."` for string concatenation arguments of simple types are
Bram Moolenaar13106602020-10-04 16:06:05 +0200898always converted to string: >
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100899 'hello ' .. 123 == 'hello 123'
Bram Moolenaar7e6a5152021-01-02 16:39:53 +0100900 'hello ' .. v:true == 'hello true'
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100901
Bram Moolenaar418f1df2020-08-12 21:34:49 +0200902Simple types are string, float, special and bool. For other types |string()|
903can be used.
Bram Moolenaar67977822021-01-03 21:53:53 +0100904 *false* *true* *null*
905In Vim9 script one can use "true" for v:true, "false" for v:false and "null"
906for v:null. When converting a boolean to a string "false" and "true" are
907used, not "v:false" and "v:true" like in legacy script. "v:none" is not
908changed, it is only used in JSON and has no equivalent in other languages.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100909
Bram Moolenaar0289a092021-03-14 18:40:19 +0100910Indexing a string with [idx] or taking a slice with [idx : idx] uses character
911indexes instead of byte indexes. Composing characters are included.
912Example: >
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200913 echo 'bár'[1]
914In legacy script this results in the character 0xc3 (an illegal byte), in Vim9
915script this results in the string 'á'.
Bram Moolenaar82be4842021-01-11 19:40:15 +0100916A negative index is counting from the end, "[-1]" is the last character.
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100917To exclude the last character use |slice()|.
Bram Moolenaar38a3bfa2021-03-29 22:14:55 +0200918To count composing characters separately use |strcharpart()|.
Bram Moolenaar82be4842021-01-11 19:40:15 +0100919If the index is out of range then an empty string results.
920
921In legacy script "++var" and "--var" would be silently accepted and have no
922effect. This is an error in Vim9 script.
923
924Numbers starting with zero are not considered to be octal, only numbers
925starting with "0o" are octal: "0o744". |scriptversion-4|
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200926
Bram Moolenaar8a7d6542020-01-26 15:56:19 +0100927
Bram Moolenaare46a4402020-06-30 20:38:27 +0200928What to watch out for ~
929 *vim9-gotchas*
930Vim9 was designed to be closer to often used programming languages, but at the
931same time tries to support the legacy Vim commands. Some compromises had to
932be made. Here is a summary of what might be unexpected.
933
934Ex command ranges need to be prefixed with a colon. >
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100935 -> legacy Vim: shifts the previous line to the right
936 ->func() Vim9: method call in a continuation line
937 :-> Vim9: shifts the previous line to the right
Bram Moolenaare46a4402020-06-30 20:38:27 +0200938
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100939 %s/a/b legacy Vim: substitute on all lines
Bram Moolenaare46a4402020-06-30 20:38:27 +0200940 x = alongname
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100941 % another Vim9: modulo operator in a continuation line
942 :%s/a/b Vim9: substitute on all lines
943 't legacy Vim: jump to mark t
944 'text'->func() Vim9: method call
945 :'t Vim9: jump to mark t
Bram Moolenaare46a4402020-06-30 20:38:27 +0200946
Bram Moolenaare7b1ea02020-08-07 19:54:59 +0200947Some Ex commands can be confused with assignments in Vim9 script: >
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100948 g:name = value # assignment
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100949 :g:pattern:cmd # :global command
Bram Moolenaare7b1ea02020-08-07 19:54:59 +0200950
Bram Moolenaar7b829262021-10-13 15:04:34 +0100951To avoid confusion between a `:global` or `:substitute` command and an
952expression or assignment, a few separators cannot be used when these commands
953are abbreviated to a single character: ':', '-' and '.'. >
954 g:pattern:cmd # invalid command - ERROR
955 s:pattern:repl # invalid command - ERROR
956 g-pattern-cmd # invalid command - ERROR
957 s-pattern-repl # invalid command - ERROR
958 g.pattern.cmd # invalid command - ERROR
959 s.pattern.repl # invalid command - ERROR
960
961Also, there cannot be a space between the command and the separator: >
962 g /pattern/cmd # invalid command - ERROR
963 s /pattern/repl # invalid command - ERROR
964
Bram Moolenaare46a4402020-06-30 20:38:27 +0200965Functions defined with `:def` compile the whole function. Legacy functions
966can bail out, and the following lines are not parsed: >
967 func Maybe()
968 if !has('feature')
969 return
970 endif
971 use-feature
972 endfunc
973Vim9 functions are compiled as a whole: >
974 def Maybe()
975 if !has('feature')
976 return
977 endif
Bram Moolenaar82be4842021-01-11 19:40:15 +0100978 use-feature # May give a compilation error
Bram Moolenaare46a4402020-06-30 20:38:27 +0200979 enddef
980For a workaround, split it in two functions: >
981 func Maybe()
982 if has('feature')
Bram Moolenaar98a29d02021-01-18 19:55:44 +0100983 call MaybeInner()
Bram Moolenaare46a4402020-06-30 20:38:27 +0200984 endif
985 endfunc
986 if has('feature')
987 def MaybeInner()
988 use-feature
989 enddef
990 endif
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200991Or put the unsupported code inside an `if` with a constant expression that
Bram Moolenaar207f0092020-08-30 17:20:20 +0200992evaluates to false: >
993 def Maybe()
994 if has('feature')
995 use-feature
996 endif
997 enddef
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200998The `exists_compiled()` function can also be used for this.
999 *vim9-user-command*
Bram Moolenaar98a29d02021-01-18 19:55:44 +01001000Another side effect of compiling a function is that the presence of a user
Bram Moolenaar82be4842021-01-11 19:40:15 +01001001command is checked at compile time. If the user command is defined later an
1002error will result. This works: >
1003 command -nargs=1 MyCommand echom <q-args>
1004 def Works()
1005 MyCommand 123
1006 enddef
1007This will give an error for "MyCommand" not being defined: >
1008 def Works()
1009 command -nargs=1 MyCommand echom <q-args>
1010 MyCommand 123
1011 enddef
1012A workaround is to invoke the command indirectly with `:execute`: >
1013 def Works()
1014 command -nargs=1 MyCommand echom <q-args>
1015 execute 'MyCommand 123'
1016 enddef
1017
Bram Moolenaar207f0092020-08-30 17:20:20 +02001018Note that for unrecognized commands there is no check for "|" and a following
1019command. This will give an error for missing `endif`: >
1020 def Maybe()
1021 if has('feature') | use-feature | endif
1022 enddef
Bram Moolenaare46a4402020-06-30 20:38:27 +02001023
Bram Moolenaar4072ba52020-12-23 13:56:35 +01001024Other differences ~
1025
1026Patterns are used like 'magic' is set, unless explicitly overruled.
1027The 'edcompatible' option value is not used.
1028The 'gdefault' option value is not used.
1029
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001030You may also find this wiki useful. It was written by an early adopter of
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01001031Vim9 script: https://github.com/lacygoill/wiki/blob/master/vim/vim9.md
Bram Moolenaar4072ba52020-12-23 13:56:35 +01001032
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02001033 *:++* *:--*
1034The ++ and -- commands have been added. They are very similar to adding or
1035subtracting one: >
1036 ++var
1037 var += 1
1038 --var
1039 var -= 1
1040
1041Using ++var or --var in an expression is not supported yet.
1042
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001043==============================================================================
1044
10453. New style functions *fast-functions*
1046
1047THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
1048
1049 *:def*
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02001050:def[!] {name}([arguments])[: {return-type}]
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001051 Define a new function by the name {name}. The body of
1052 the function follows in the next lines, until the
1053 matching `:enddef`.
1054
Bram Moolenaard77a8522020-04-03 21:59:57 +02001055 When {return-type} is omitted or is "void" the
1056 function is not expected to return anything.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001057
1058 {arguments} is a sequence of zero or more argument
1059 declarations. There are three forms:
1060 {name}: {type}
1061 {name} = {value}
1062 {name}: {type} = {value}
1063 The first form is a mandatory argument, the caller
1064 must always provide them.
1065 The second and third form are optional arguments.
1066 When the caller omits an argument the {value} is used.
1067
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001068 The function will be compiled into instructions when
Bram Moolenaar2547aa92020-07-26 17:00:44 +02001069 called, or when `:disassemble` or `:defcompile` is
1070 used. Syntax and type errors will be produced at that
1071 time.
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001072
Bram Moolenaar2547aa92020-07-26 17:00:44 +02001073 It is possible to nest `:def` inside another `:def` or
1074 `:function` up to about 50 levels deep.
Bram Moolenaar560979e2020-02-04 22:53:05 +01001075
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001076 [!] is used as with `:function`. Note that
1077 script-local functions cannot be deleted or redefined
1078 later in Vim9 script. They can only be removed by
1079 reloading the same script.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001080
1081 *:enddef*
Bram Moolenaar2547aa92020-07-26 17:00:44 +02001082:enddef End of a function defined with `:def`. It should be on
1083 a line by its own.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001084
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001085You may also find this wiki useful. It was written by an early adopter of
Bram Moolenaar0289a092021-03-14 18:40:19 +01001086Vim9 script: https://github.com/lacygoill/wiki/blob/master/vim/vim9.md
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001087
Bram Moolenaar5b1c8fe2020-02-21 18:42:43 +01001088If the script the function is defined in is Vim9 script, then script-local
1089variables can be accessed without the "s:" prefix. They must be defined
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001090before the function is compiled. If the script the function is defined in is
1091legacy script, then script-local variables must be accessed with the "s:"
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001092prefix if they do not exist at the time of compiling.
Bram Moolenaar5b1c8fe2020-02-21 18:42:43 +01001093
Bram Moolenaar388a5d42020-05-26 21:20:45 +02001094 *:defc* *:defcompile*
1095:defc[ompile] Compile functions defined in the current script that
1096 were not compiled yet.
1097 This will report errors found during the compilation.
Bram Moolenaar5b1c8fe2020-02-21 18:42:43 +01001098
Bram Moolenaarebdf3c92020-02-15 21:41:42 +01001099 *:disa* *:disassemble*
1100:disa[ssemble] {func} Show the instructions generated for {func}.
1101 This is for debugging and testing.
Bram Moolenaarcc390ff2020-02-29 22:06:30 +01001102 Note that for command line completion of {func} you
1103 can prepend "s:" to find script-local functions.
Bram Moolenaarebdf3c92020-02-15 21:41:42 +01001104
Bram Moolenaar2346a632021-06-13 19:02:49 +02001105:disa[ssemble] profile {func}
1106 Like `:disassemble` but with the instructions used for
Bram Moolenaare0e39172021-01-25 21:14:57 +01001107 profiling.
1108
Bram Moolenaar2346a632021-06-13 19:02:49 +02001109:disa[ssemble] debug {func}
1110 Like `:disassemble` but with the instructions used for
1111 debugging.
1112
Bram Moolenaar7ff78462020-07-10 22:00:53 +02001113Limitations ~
1114
1115Local variables will not be visible to string evaluation. For example: >
Bram Moolenaar2b327002020-12-26 15:39:31 +01001116 def MapList(): list<string>
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001117 var list = ['aa', 'bb', 'cc', 'dd']
Bram Moolenaar7ff78462020-07-10 22:00:53 +02001118 return range(1, 2)->map('list[v:val]')
1119 enddef
1120
1121The map argument is a string expression, which is evaluated without the
1122function scope. Instead, use a lambda: >
Bram Moolenaar2b327002020-12-26 15:39:31 +01001123 def MapList(): list<string>
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001124 var list = ['aa', 'bb', 'cc', 'dd']
Bram Moolenaar22863042021-10-16 15:23:36 +01001125 return range(1, 2)->map((_, v) => list[v])
Bram Moolenaar7ff78462020-07-10 22:00:53 +02001126 enddef
1127
Bram Moolenaar2b327002020-12-26 15:39:31 +01001128The same is true for commands that are not compiled, such as `:global`.
1129For these the backtick expansion can be used. Example: >
1130 def Replace()
1131 var newText = 'blah'
1132 g/pattern/s/^/`=newText`/
1133 enddef
Bram Moolenaar7ff78462020-07-10 22:00:53 +02001134
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02001135Or a script variable can be used: >
1136 var newText = 'blah'
1137 def Replace()
1138 g/pattern/s/^/\=newText/
1139 enddef
1140
Bram Moolenaardad44732021-03-31 20:07:33 +02001141Closures defined in a loop will share the same context. For example: >
1142 var flist: list<func>
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02001143 for i in range(5)
Bram Moolenaardad44732021-03-31 20:07:33 +02001144 var inloop = i
1145 flist[i] = () => inloop
1146 endfor
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02001147 echo range(5)->map((i, _) => flist[i]())
1148 # Result: [4, 4, 4, 4, 4]
Bram Moolenaardad44732021-03-31 20:07:33 +02001149
1150The "inloop" variable will exist only once, all closures put in the list refer
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02001151to the same instance, which in the end will have the value 4. This is
1152efficient, also when looping many times. If you do want a separate context
1153for each closure call a function to define it: >
1154 def GetClosure(i: number): func
1155 var infunc = i
1156 return () => infunc
Bram Moolenaardad44732021-03-31 20:07:33 +02001157 enddef
1158
1159 var flist: list<func>
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02001160 for i in range(5)
1161 flist[i] = GetClosure(i)
Bram Moolenaardad44732021-03-31 20:07:33 +02001162 endfor
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02001163 echo range(5)->map((i, _) => flist[i]())
1164 # Result: [0, 1, 2, 3, 4]
Bram Moolenaardad44732021-03-31 20:07:33 +02001165
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001166==============================================================================
1167
11684. Types *vim9-types*
1169
1170THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
1171
1172The following builtin types are supported:
1173 bool
1174 number
1175 float
1176 string
1177 blob
Bram Moolenaard77a8522020-04-03 21:59:57 +02001178 list<{type}>
1179 dict<{type}>
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001180 job
1181 channel
Bram Moolenaarb17893a2020-03-14 08:19:51 +01001182 func
Bram Moolenaard1caa942020-04-10 22:10:56 +02001183 func: {type}
Bram Moolenaard77a8522020-04-03 21:59:57 +02001184 func({type}, ...)
1185 func({type}, ...): {type}
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001186
1187Not supported yet:
Bram Moolenaard77a8522020-04-03 21:59:57 +02001188 tuple<a: {type}, b: {type}, ...>
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001189
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001190These types can be used in declarations, but no simple value will actually
1191have the "void" type.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001192
Bram Moolenaard77a8522020-04-03 21:59:57 +02001193There is no array type, use list<{type}> instead. For a list constant an
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001194efficient implementation is used that avoids allocating lot of small pieces of
1195memory.
1196
Bram Moolenaard77a8522020-04-03 21:59:57 +02001197A partial and function can be declared in more or less specific ways:
1198func any kind of function reference, no type
Bram Moolenaard1caa942020-04-10 22:10:56 +02001199 checking for arguments or return value
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001200func: void any number and type of arguments, no return
1201 value
Bram Moolenaard77a8522020-04-03 21:59:57 +02001202func: {type} any number and type of arguments with specific
1203 return type
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001204
1205func() function with no argument, does not return a
1206 value
1207func(): void same
1208func(): {type} function with no argument and return type
1209
Bram Moolenaard1caa942020-04-10 22:10:56 +02001210func({type}) function with argument type, does not return
Bram Moolenaard77a8522020-04-03 21:59:57 +02001211 a value
Bram Moolenaard1caa942020-04-10 22:10:56 +02001212func({type}): {type} function with argument type and return type
1213func(?{type}) function with type of optional argument, does
1214 not return a value
1215func(...{type}) function with type of variable number of
1216 arguments, does not return a value
1217func({type}, ?{type}, ...{type}): {type}
1218 function with:
1219 - type of mandatory argument
1220 - type of optional argument
1221 - type of variable number of arguments
1222 - return type
Bram Moolenaard77a8522020-04-03 21:59:57 +02001223
1224If the return type is "void" the function does not return a value.
1225
1226The reference can also be a |Partial|, in which case it stores extra arguments
1227and/or a dictionary, which are not visible to the caller. Since they are
1228called in the same way the declaration is the same.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001229
1230Custom types can be defined with `:type`: >
1231 :type MyList list<string>
Bram Moolenaar127542b2020-08-09 17:22:04 +02001232Custom types must start with a capital letter, to avoid name clashes with
1233builtin types added later, similarly to user functions.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001234{not implemented yet}
1235
1236And classes and interfaces can be used as types: >
1237 :class MyClass
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001238 :var mine: MyClass
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001239
1240 :interface MyInterface
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001241 :var mine: MyInterface
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001242
1243 :class MyTemplate<Targ>
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001244 :var mine: MyTemplate<number>
1245 :var mine: MyTemplate<string>
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001246
1247 :class MyInterface<Targ>
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001248 :var mine: MyInterface<number>
1249 :var mine: MyInterface<string>
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001250{not implemented yet}
1251
1252
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001253Variable types and type casting ~
1254 *variable-types*
Bram Moolenaar64d662d2020-08-09 19:02:50 +02001255Variables declared in Vim9 script or in a `:def` function have a type, either
1256specified explicitly or inferred from the initialization.
1257
1258Global, buffer, window and tab page variables do not have a specific type, the
1259value can be changed at any time, possibly changing the type. Therefore, in
1260compiled code the "any" type is assumed.
1261
1262This can be a problem when the "any" type is undesired and the actual type is
1263expected to always be the same. For example, when declaring a list: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001264 var l: list<number> = [1, g:two]
Bram Moolenaar4072ba52020-12-23 13:56:35 +01001265At compile time Vim doesn't know the type of "g:two" and the expression type
1266becomes list<any>. An instruction is generated to check the list type before
1267doing the assignment, which is a bit inefficient.
1268 *type-casting*
1269To avoid this, use a type cast: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001270 var l: list<number> = [1, <number>g:two]
Bram Moolenaar4072ba52020-12-23 13:56:35 +01001271The compiled code will then only check that "g:two" is a number and give an
1272error if it isn't. This is called type casting.
Bram Moolenaar64d662d2020-08-09 19:02:50 +02001273
1274The syntax of a type cast is: "<" {type} ">". There cannot be white space
1275after the "<" or before the ">" (to avoid them being confused with
1276smaller-than and bigger-than operators).
1277
1278The semantics is that, if needed, a runtime type check is performed. The
1279value is not actually changed. If you need to change the type, e.g. to change
1280it to a string, use the |string()| function. Or use |str2nr()| to convert a
1281string to a number.
1282
1283
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001284Type inference ~
1285 *type-inference*
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001286In general: Whenever the type is clear it can be omitted. For example, when
1287declaring a variable and giving it a value: >
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001288 var name = 0 # infers number type
1289 var name = 'hello' # infers string type
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001290
Bram Moolenaar127542b2020-08-09 17:22:04 +02001291The type of a list and dictionary comes from the common type of the values.
1292If the values all have the same type, that type is used for the list or
1293dictionary. If there is a mix of types, the "any" type is used. >
1294 [1, 2, 3] list<number>
1295 ['a', 'b', 'c'] list<string>
1296 [1, 'x', 3] list<any>
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001297
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001298The common type of function references, if they do not all have the same
1299number of arguments, uses "(...)" to indicate the number of arguments is not
1300specified. For example: >
1301 def Foo(x: bool)
1302 enddef
1303 def Bar(x: bool, y: bool)
1304 enddef
1305 var funclist = [Foo, Bar]
1306 echo funclist->typename()
1307Results in:
1308 list<func(...)>
1309
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001310For script-local variables in Vim9 script the type is checked, also when the
1311variable was declared in a legacy function.
1312
Bram Moolenaar207f0092020-08-30 17:20:20 +02001313
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001314Stricter type checking ~
1315 *type-checking*
Bram Moolenaar207f0092020-08-30 17:20:20 +02001316In legacy Vim script, where a number was expected, a string would be
1317automatically converted to a number. This was convenient for an actual number
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001318such as "123", but leads to unexpected problems (and no error message) if the
Bram Moolenaar207f0092020-08-30 17:20:20 +02001319string doesn't start with a number. Quite often this leads to hard-to-find
1320bugs.
1321
1322In Vim9 script this has been made stricter. In most places it works just as
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001323before, if the value used matches the expected type. There will sometimes be
1324an error, thus breaking backwards compatibility. For example:
Bram Moolenaar207f0092020-08-30 17:20:20 +02001325- Using a number other than 0 or 1 where a boolean is expected. *E1023*
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001326- Using a string value when setting a number option.
Bram Moolenaar207f0092020-08-30 17:20:20 +02001327- Using a number where a string is expected. *E1024*
1328
Bram Moolenaar22863042021-10-16 15:23:36 +01001329One consequence is that the item type of a list or dict given to |map()| must
Bram Moolenaar9faec4e2021-02-27 16:38:07 +01001330not change. This will give an error in Vim9 script: >
Bram Moolenaar22863042021-10-16 15:23:36 +01001331 echo map([1, 2, 3], (i, v) => 'item ' .. i)
Bram Moolenaar9faec4e2021-02-27 16:38:07 +01001332 E1012: Type mismatch; expected number but got string
Bram Moolenaar22863042021-10-16 15:23:36 +01001333Instead use |mapnew()|: >
1334 echo mapnew([1, 2, 3], (i, v) => 'item ' .. i)
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001335 ['item 0', 'item 1', 'item 2']
1336
1337If the item type was determined to be "any" it can change to a more specific
Bram Moolenaar22863042021-10-16 15:23:36 +01001338type. E.g. when a list of mixed types gets changed to a list of strings: >
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001339 var mylist = [1, 2.0, '3']
1340 # typename(mylist) == "list<any>"
1341 map(mylist, (i, v) => 'item ' .. i)
1342 # typename(mylist) == "list<string>", no error
1343
Bram Moolenaar9faec4e2021-02-27 16:38:07 +01001344Same for |extend()|, use |extendnew()| instead, and for |flatten()|, use
1345|flattennew()| instead.
Bram Moolenaar82be4842021-01-11 19:40:15 +01001346
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001347==============================================================================
1348
Bram Moolenaar30fd8202020-09-26 15:09:30 +020013495. Namespace, Import and Export
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001350 *vim9script* *vim9-export* *vim9-import*
1351
1352THIS IS STILL UNDER DEVELOPMENT - ANYTHING CAN BREAK - ANYTHING CAN CHANGE
1353
1354A Vim9 script can be written to be imported. This means that everything in
1355the script is local, unless exported. Those exported items, and only those
1356items, can then be imported in another script.
1357
Bram Moolenaar207f0092020-08-30 17:20:20 +02001358You can cheat by using the global namespace explicitly. We will assume here
1359that you don't do that.
1360
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001361
1362Namespace ~
Bram Moolenaardcc58e02020-12-28 20:53:21 +01001363 *vim9-namespace*
Bram Moolenaar560979e2020-02-04 22:53:05 +01001364To recognize a file that can be imported the `vim9script` statement must
Bram Moolenaard3f8a9e2021-02-17 21:57:03 +01001365appear as the first statement in the file (see |vim9-mix| for an exception).
1366It tells Vim to interpret the script in its own namespace, instead of the
1367global namespace. If a file starts with: >
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001368 vim9script
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001369 var myvar = 'yes'
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001370Then "myvar" will only exist in this file. While without `vim9script` it would
1371be available as `g:myvar` from any other script and function.
1372
1373The variables at the file level are very much like the script-local "s:"
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +02001374variables in legacy Vim script, but the "s:" is omitted. And they cannot be
1375deleted.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001376
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +02001377In Vim9 script the global "g:" namespace can still be used as before. And the
1378"w:", "b:" and "t:" namespaces. These have in common that variables are not
1379declared and they can be deleted.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001380
1381A side effect of `:vim9script` is that the 'cpoptions' option is set to the
1382Vim default value, like with: >
1383 :set cpo&vim
1384One of the effects is that |line-continuation| is always enabled.
Bram Moolenaar3e191692021-03-17 17:46:00 +01001385The original value of 'cpoptions' is restored at the end of the script, while
1386flags added or removed in the script are also added to or removed from the
1387original value to get the same effect. The order of flags may change.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001388
Bram Moolenaard3f8a9e2021-02-17 21:57:03 +01001389 *vim9-mix*
1390There is one way to use both legacy and Vim9 syntax in one script file: >
1391 " comments may go here
1392 if !has('vim9script')
1393 " legacy script commands go here
1394 finish
1395 endif
1396 vim9script
1397 # Vim9 script commands go here
1398This allows for writing a script that takes advantage of the Vim9 script
Bram Moolenaar9faec4e2021-02-27 16:38:07 +01001399syntax if possible, but will also work on a Vim version without it.
Bram Moolenaard3f8a9e2021-02-17 21:57:03 +01001400
1401This can only work in two ways:
14021. The "if" statement evaluates to false, the commands up to `endif` are
1403 skipped and `vim9script` is then the first command actually executed.
14042. The "if" statement evaluates to true, the commands up to `endif` are
1405 executed and `finish` bails out before reaching `vim9script`.
1406
1407TODO: The "vim9script" feature does not exist yet, it will only be added once
1408the Vim9 script syntax has been fully implemented.
1409
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001410
1411Export ~
1412 *:export* *:exp*
Bram Moolenaar2547aa92020-07-26 17:00:44 +02001413Exporting an item can be written as: >
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001414 export const EXPORTED_CONST = 1234
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001415 export var someValue = ...
1416 export final someValue = ...
1417 export const someValue = ...
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001418 export def MyFunc() ...
1419 export class MyClass ...
Bram Moolenaar74235772021-06-12 14:53:05 +02001420 export interface MyClass ...
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001421
1422As this suggests, only constants, variables, `:def` functions and classes can
Bram Moolenaar74235772021-06-12 14:53:05 +02001423be exported. {not implemented yet: class, interface}
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001424
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001425 *E1042*
1426`:export` can only be used in Vim9 script, at the script level.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001427
1428
1429Import ~
Bram Moolenaar73fef332020-06-21 22:12:03 +02001430 *:import* *:imp* *E1094*
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001431The exported items can be imported individually in another Vim9 script: >
1432 import EXPORTED_CONST from "thatscript.vim"
1433 import MyClass from "myclass.vim"
1434
1435To import multiple items at the same time: >
1436 import {someValue, MyClass} from "thatscript.vim"
1437
Bram Moolenaar560979e2020-02-04 22:53:05 +01001438In case the name is ambiguous, another name can be specified: >
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001439 import MyClass as ThatClass from "myclass.vim"
1440 import {someValue, MyClass as ThatClass} from "myclass.vim"
1441
1442To import all exported items under a specific identifier: >
1443 import * as That from 'thatscript.vim'
1444
1445Then you can use "That.EXPORTED_CONST", "That.someValue", etc. You are free
1446to choose the name "That", but it is highly recommended to use the name of the
Bram Moolenaar6c391a72021-09-09 21:55:11 +02001447script file to avoid confusion. Also avoid command names, because the name
1448will shadow them.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001449
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001450`:import` can also be used in legacy Vim script. The imported items still
1451become script-local, even when the "s:" prefix is not given.
1452
Bram Moolenaar4db572e2021-07-18 18:21:38 +02001453`:import` can not be used in a function. Imported items are intended to exist
1454at the script level and only imported once.
1455
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001456The script name after `import` can be:
1457- A relative path, starting "." or "..". This finds a file relative to the
1458 location of the script file itself. This is useful to split up a large
1459 plugin into several files.
1460- An absolute path, starting with "/" on Unix or "D:/" on MS-Windows. This
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01001461 will rarely be used.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001462- A path not being relative or absolute. This will be found in the
1463 "import" subdirectories of 'runtimepath' entries. The name will usually be
1464 longer and unique, to avoid loading the wrong file.
Bram Moolenaar6aa57292021-08-14 21:25:52 +02001465 Note that "after/import" is not used.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001466
1467Once a vim9 script file has been imported, the result is cached and used the
1468next time the same script is imported. It will not be read again.
1469 *:import-cycle*
1470The `import` commands are executed when encountered. If that script (directly
1471or indirectly) imports the current script, then items defined after the
1472`import` won't be processed yet. Therefore cyclic imports can exist, but may
1473result in undefined items.
1474
1475
1476Import in an autoload script ~
1477
1478For optimal startup speed, loading scripts should be postponed until they are
Bram Moolenaar560979e2020-02-04 22:53:05 +01001479actually needed. A recommended mechanism:
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001480
14811. In the plugin define user commands, functions and/or mappings that refer to
1482 an autoload script. >
Bram Moolenaar98a29d02021-01-18 19:55:44 +01001483 command -nargs=1 SearchForStuff searchfor#Stuff(<f-args>)
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001484
1485< This goes in .../plugin/anyname.vim. "anyname.vim" can be freely chosen.
1486
Bram Moolenaar3d1cde82020-08-15 18:55:18 +020014872. In the autoload script do the actual work. You can import items from
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001488 other files to split up functionality in appropriate pieces. >
1489 vim9script
Bram Moolenaar82be4842021-01-11 19:40:15 +01001490 import FilterFunc from "../import/someother.vim"
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001491 def searchfor#Stuff(arg: string)
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001492 var filtered = FilterFunc(arg)
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001493 ...
1494< This goes in .../autoload/searchfor.vim. "searchfor" in the file name
1495 must be exactly the same as the prefix for the function name, that is how
1496 Vim finds the file.
1497
14983. Other functionality, possibly shared between plugins, contains the exported
1499 items and any private items. >
1500 vim9script
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001501 var localVar = 'local'
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001502 export def FilterFunc(arg: string): string
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001503 ...
1504< This goes in .../import/someother.vim.
1505
Bram Moolenaar418f1df2020-08-12 21:34:49 +02001506When compiling a `:def` function and a function in an autoload script is
1507encountered, the script is not loaded until the `:def` function is called.
1508
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001509
1510Import in legacy Vim script ~
1511
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001512If an `import` statement is used in legacy Vim script, the script-local "s:"
1513namespace will be used for the imported item, even when "s:" is not specified.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001514
1515
1516==============================================================================
1517
Bram Moolenaar1d59aa12020-09-19 18:50:13 +020015186. Future work: classes *vim9-classes*
1519
1520Above "class" was mentioned a few times, but it has not been implemented yet.
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001521Most of Vim9 script can be created without this functionality, and since
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001522implementing classes is going to be a lot of work, it is left for the future.
1523For now we'll just make sure classes can be added later.
1524
1525Thoughts:
Bram Moolenaar74235772021-06-12 14:53:05 +02001526- `class` / `endclass`, the whole class must be in one file
1527- Class names are always CamelCase (to avoid a name clash with builtin types)
1528- A single constructor called "constructor"
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001529- Single inheritance with `class ThisClass extends BaseClass`
Bram Moolenaar74235772021-06-12 14:53:05 +02001530- `abstract class` (class with incomplete implementation)
1531- `interface` / `endinterface` (abstract class without any implementation)
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001532- `class SomeClass implements SomeInterface`
1533- Generics for class: `class <Tkey, Tentry>`
1534- Generics for function: `def <Tkey> GetLast(key: Tkey)`
1535
Bram Moolenaar74235772021-06-12 14:53:05 +02001536Again, much of this is from TypeScript with a slightly different syntax.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001537
1538Some things that look like good additions:
1539- Use a class as an interface (like Dart)
1540- Extend a class with methods, using an import (like Dart)
Bram Moolenaar74235772021-06-12 14:53:05 +02001541- Mixins
1542- For testing: Mock mechanism
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001543
1544An important class that will be provided is "Promise". Since Vim is single
1545threaded, connecting asynchronous operations is a natural way of allowing
1546plugins to do their work without blocking the user. It's a uniform way to
1547invoke callbacks and handle timeouts and errors.
1548
Bram Moolenaar74235772021-06-12 14:53:05 +02001549Some examples: >
1550
1551 abstract class Person
1552 static const prefix = 'xxx'
1553 var name: string
1554
1555 def constructor(name: string)
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02001556 this.name = name
Bram Moolenaar74235772021-06-12 14:53:05 +02001557 enddef
1558
1559 def display(): void
1560 echo name
1561 enddef
1562
1563 abstract def find(string): Person
1564 endclass
1565
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001566==============================================================================
1567
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010015689. Rationale *vim9-rationale*
1569
1570The :def command ~
1571
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001572Plugin writers have asked for much faster Vim script. Investigations have
Bram Moolenaar560979e2020-02-04 22:53:05 +01001573shown that keeping the existing semantics of function calls make this close to
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001574impossible, because of the overhead involved with calling a function, setting
1575up the local function scope and executing lines. There are many details that
1576need to be handled, such as error messages and exceptions. The need to create
1577a dictionary for a: and l: scopes, the a:000 list and several others add too
1578much overhead that cannot be avoided.
1579
1580Therefore the `:def` method to define a new-style function had to be added,
1581which allows for a function with different semantics. Most things still work
1582as before, but some parts do not. A new way to define a function was
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001583considered the best way to separate the legacy style code from Vim9 style code.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001584
1585Using "def" to define a function comes from Python. Other languages use
1586"function" which clashes with legacy Vim script.
1587
1588
1589Type checking ~
1590
1591When compiling lines of Vim commands into instructions as much as possible
1592should be done at compile time. Postponing it to runtime makes the execution
1593slower and means mistakes are found only later. For example, when
1594encountering the "+" character and compiling this into a generic add
Bram Moolenaar98a29d02021-01-18 19:55:44 +01001595instruction, at runtime the instruction would have to inspect the type of the
1596arguments and decide what kind of addition to do. And when the type is
1597dictionary throw an error. If the types are known to be numbers then an "add
1598number" instruction can be used, which is faster. The error can be given at
1599compile time, no error handling is needed at runtime, since adding two numbers
1600cannot fail.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001601
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001602The syntax for types, using <type> for compound types, is similar to Java. It
1603is easy to understand and widely used. The type names are what were used in
1604Vim before, with some additions such as "void" and "bool".
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001605
1606
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001607Removing clutter and weirdness ~
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001608
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001609Once decided that `:def` functions have different syntax than legacy functions,
1610we are free to add improvements to make the code more familiar for users who
1611know popular programming languages. In other words: remove weird things that
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001612only Vim does.
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001613
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001614We can also remove clutter, mainly things that were done to make Vim script
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001615backwards compatible with the good old Vi commands.
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001616
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001617Examples:
1618- Drop `:call` for calling a function and `:eval` for manipulating data.
1619- Drop using a leading backslash for line continuation, automatically figure
1620 out where an expression ends.
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001621
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001622However, this does require that some things need to change:
1623- Comments start with # instead of ", to avoid confusing them with strings.
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001624 This is good anyway, it is known from several popular languages.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001625- Ex command ranges need to be prefixed with a colon, to avoid confusion with
1626 expressions (single quote can be a string or a mark, "/" can be divide or a
1627 search command, etc.).
1628
1629Goal is to limit the differences. A good criteria is that when the old syntax
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001630is accidentally used you are very likely to get an error message.
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001631
1632
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001633Syntax and semantics from popular languages ~
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001634
1635Script writers have complained that the Vim script syntax is unexpectedly
1636different from what they are used to. To reduce this complaint popular
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001637languages are used as an example. At the same time, we do not want to abandon
1638the well-known parts of legacy Vim script.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001639
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001640For many things TypeScript is followed. It's a recent language that is
1641gaining popularity and has similarities with Vim script. It also has a
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001642mix of static typing (a variable always has a known value type) and dynamic
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001643typing (a variable can have different types, this changes at runtime). Since
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001644legacy Vim script is dynamically typed and a lot of existing functionality
1645(esp. builtin functions) depends on that, while static typing allows for much
1646faster execution, we need to have this mix in Vim9 script.
1647
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001648There is no intention to completely match TypeScript syntax and semantics. We
1649just want to take those parts that we can use for Vim and we expect Vim users
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001650will be happy with. TypeScript is a complex language with its own history,
1651advantages and disadvantages. To get an idea of the disadvantages read the
1652book: "JavaScript: The Good Parts". Or find the article "TypeScript: the good
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +02001653parts" and read the "Things to avoid" section.
1654
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001655People familiar with other languages (Java, Python, etc.) will also find
1656things in TypeScript that they do not like or do not understand. We'll try to
1657avoid those things.
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +02001658
1659Specific items from TypeScript we avoid:
1660- Overloading "+", using it both for addition and string concatenation. This
1661 goes against legacy Vim script and often leads to mistakes. For that reason
1662 we will keep using ".." for string concatenation. Lua also uses ".." this
1663 way. And it allows for conversion to string for more values.
1664- TypeScript can use an expression like "99 || 'yes'" in a condition, but
1665 cannot assign the value to a boolean. That is inconsistent and can be
1666 annoying. Vim recognizes an expression with && or || and allows using the
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001667 result as a bool. TODO: to be reconsidered
Bram Moolenaar0b4c66c2020-09-14 21:39:44 +02001668- TypeScript considers an empty string as Falsy, but an empty list or dict as
1669 Truthy. That is inconsistent. In Vim an empty list and dict are also
1670 Falsy.
1671- TypeScript has various "Readonly" types, which have limited usefulness,
1672 since a type cast can remove the immutable nature. Vim locks the value,
1673 which is more flexible, but is only checked at runtime.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001674
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001675
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001676Declarations ~
1677
1678Legacy Vim script uses `:let` for every assignment, while in Vim9 declarations
1679are used. That is different, thus it's good to use a different command:
1680`:var`. This is used in many languages. The semantics might be slightly
1681different, but it's easily recognized as a declaration.
1682
Bram Moolenaar23515b42020-11-29 14:36:24 +01001683Using `:const` for constants is common, but the semantics varies. Some
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001684languages only make the variable immutable, others also make the value
1685immutable. Since "final" is well known from Java for only making the variable
1686immutable we decided to use that. And then `:const` can be used for making
1687both immutable. This was also used in legacy Vim script and the meaning is
1688almost the same.
1689
1690What we end up with is very similar to Dart: >
1691 :var name # mutable variable and value
1692 :final name # immutable variable, mutable value
1693 :const name # immutable variable and value
1694
1695Since legacy and Vim9 script will be mixed and global variables will be
1696shared, optional type checking is desirable. Also, type inference will avoid
1697the need for specifying the type in many cases. The TypeScript syntax fits
1698best for adding types to declarations: >
1699 var name: string # string type is specified
1700 ...
1701 name = 'John'
1702 const greeting = 'hello' # string type is inferred
1703
1704This is how we put types in a declaration: >
1705 var mylist: list<string>
1706 final mylist: list<string> = ['foo']
1707 def Func(arg1: number, arg2: string): bool
1708
1709Two alternatives were considered:
17101. Put the type before the name, like Dart: >
1711 var list<string> mylist
1712 final list<string> mylist = ['foo']
1713 def Func(number arg1, string arg2) bool
17142. Put the type after the variable name, but do not use a colon, like Go: >
1715 var mylist list<string>
1716 final mylist list<string> = ['foo']
1717 def Func(arg1 number, arg2 string) bool
1718
1719The first is more familiar for anyone used to C or Java. The second one
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02001720doesn't really have an advantage over the first, so let's discard the second.
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001721
1722Since we use type inference the type can be left out when it can be inferred
1723from the value. This means that after `var` we don't know if a type or a name
1724follows. That makes parsing harder, not only for Vim but also for humans.
1725Also, it will not be allowed to use a variable name that could be a type name,
1726using `var string string` is too confusing.
1727
1728The chosen syntax, using a colon to separate the name from the type, adds
1729punctuation, but it actually makes it easier to recognize the parts of a
1730declaration.
1731
1732
1733Expressions ~
1734
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02001735Expression evaluation was already close to what other languages are doing.
1736Some details are unexpected and can be improved. For example a boolean
1737condition would accept a string, convert it to a number and check if the
1738number is non-zero. This is unexpected and often leads to mistakes, since
1739text not starting with a number would be converted to zero, which is
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01001740considered false. Thus using a string for a condition would often not give an
1741error and be considered false. That is confusing.
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001742
Bram Moolenaar23515b42020-11-29 14:36:24 +01001743In Vim9 type checking is stricter to avoid mistakes. Where a condition is
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02001744used, e.g. with the `:if` command and the `||` operator, only boolean-like
1745values are accepted:
1746 true: `true`, `v:true`, `1`, `0 < 9`
1747 false: `false`, `v:false`, `0`, `0 > 9`
1748Note that the number zero is false and the number one is true. This is more
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01001749permissive than most other languages. It was done because many builtin
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02001750functions return these values.
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001751
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02001752If you have any type of value and want to use it as a boolean, use the `!!`
1753operator:
Bram Moolenaard2ea7cf2021-05-30 20:54:13 +02001754 true: `!!'text'`, `!![99]`, `!!{'x': 1}`, `!!99`
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02001755 false: `!!''`, `!![]`, `!!{}`
1756
1757From a language like JavaScript we have this handy construct: >
1758 GetName() || 'unknown'
1759However, this conflicts with only allowing a boolean for a condition.
1760Therefore the "??" operator was added: >
1761 GetName() ?? 'unknown'
1762Here you can explicitly express your intention to use the value as-is and not
1763result in a boolean. This is called the |falsy-operator|.
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001764
1765
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001766Import and Export ~
1767
1768A problem of legacy Vim script is that by default all functions and variables
1769are global. It is possible to make them script-local, but then they are not
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001770available in other scripts. This defies the concept of a package that only
1771exports selected items and keeps the rest local.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001772
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02001773In Vim9 script a mechanism very similar to the JavaScript import and export
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001774mechanism is supported. It is a variant to the existing `:source` command
1775that works like one would expect:
1776- Instead of making everything global by default, everything is script-local,
1777 unless exported.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001778- When importing a script the symbols that are imported are explicitly listed,
1779 avoiding name conflicts and failures if functionality is added later.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001780- The mechanism allows for writing a big, long script with a very clear API:
1781 the exported function(s) and class(es).
1782- By using relative paths loading can be much faster for an import inside of a
1783 package, no need to search many directories.
1784- Once an import has been used, it can be cached and loading it again can be
1785 avoided.
1786- The Vim-specific use of "s:" to make things script-local can be dropped.
1787
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001788When sourcing a Vim9 script from a legacy script, only the items defined
1789globally can be used, not the exported items. Alternatives considered:
1790- All the exported items become available as script-local items. This makes
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001791 it uncontrollable what items get defined and likely soon leads to trouble.
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001792- Use the exported items and make them global. Disadvantage is that it's then
1793 not possible to avoid name clashes in the global namespace.
1794- Completely disallow sourcing a Vim9 script, require using `:import`. That
1795 makes it difficult to use scripts for testing, or sourcing them from the
1796 command line to try them out.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001797Note that you can also use `:import` in legacy Vim script, see above.
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001798
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001799
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001800Compiling functions early ~
1801
1802Functions are compiled when called or when `:defcompile` is used. Why not
1803compile them early, so that syntax and type errors are reported early?
1804
1805The functions can't be compiled right away when encountered, because there may
1806be forward references to functions defined later. Consider defining functions
1807A, B and C, where A calls B, B calls C, and C calls A again. It's impossible
1808to reorder the functions to avoid forward references.
1809
1810An alternative would be to first scan through the file to locate items and
1811figure out their type, so that forward references are found, and only then
1812execute the script and compile the functions. This means the script has to be
1813parsed twice, which is slower, and some conditions at the script level, such
1814as checking if a feature is supported, are hard to use. An attempt was made
1815to see if it works, but it turned out to be impossible to make work nicely.
1816
1817It would be possible to compile all the functions at the end of the script.
1818The drawback is that if a function never gets called, the overhead of
1819compiling it counts anyway. Since startup speed is very important, in most
1820cases it's better to do it later and accept that syntax and type errors are
1821only reported then. In case these errors should be found early, e.g. when
1822testing, the `:defcompile` command will help out.
1823
1824
Bram Moolenaar30fd8202020-09-26 15:09:30 +02001825Why not use an embedded language? ~
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001826
1827Vim supports interfaces to Perl, Python, Lua, Tcl and a few others. But
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001828these interfaces have never become widely used, for various reasons. When
1829Vim9 was designed a decision was made to make these interfaces lower priority
1830and concentrate on Vim script.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001831
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001832Still, plugin writers may find other languages more familiar, want to use
1833existing libraries or see a performance benefit. We encourage plugin authors
1834to write code in any language and run it as an external tool, using jobs and
1835channels. We can try to make this easier somehow.
1836
1837Using an external tool also has disadvantages. An alternative is to convert
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001838the tool into Vim script. For that to be possible without too much
1839translation, and keeping the code fast at the same time, the constructs of the
1840tool need to be supported. Since most languages support classes the lack of
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001841support for classes in Vim is then a problem.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001842
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001843
1844Classes ~
1845
1846Vim supports a kind-of object oriented programming by adding methods to a
1847dictionary. With some care this can be made to work, but it does not look
1848like real classes. On top of that, it's quite slow, because of the use of
1849dictionaries.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001850
1851The support of classes in Vim9 script is a "minimal common functionality" of
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001852class support in most languages. It works much like Java, which is the most
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01001853popular programming language.
1854
1855
1856
1857 vim:tw=78:ts=8:noet:ft=help:norl: