*vim9.txt* For Vim version 9.2. Last change: 2026 Sep 28 VIM REFERENCE MANUAL by Bram Moolenaar Vim9 script commands and expressions. *Vim9* *vim9* Most expression help is in |eval.txt|. This file is about the new syntax and features in Vim9 script, including more than 200 sourceable scripts. For a short primer on Vim9 script, other resources may be helpful too, e.g., https://learnxinyminutes.com/vim9script/. 1. What is Vim9 script? |Vim9-script| 2. Differences |vim9-differences| 3. New style functions |fast-functions| 4. Types |vim9-types| 5. Generic functions |generic-functions| 6. Namespace, Import and Export |vim9script| 7. Classes and interfaces |vim9-classes| 8. Rationale |vim9-rationale| ------------------------------------------------------------------------------ NOTE: In this vim9.txt help file, the Vim9 script code blocks beginning with `vim9script` (and individual lines starting with `vim9cmd`) are Vim9 script syntax highlighted. Also, they are sourceable, meaning you can run them to see what they output. To source them, use `:'<,'>source` (see |:source-range|), which is done by visually selecting the line(s) with |V| and typing `:so`. For example, try it on the following Vim9 script: >vim9 vim9script echowindow "Welcome to Vim9 script!" < There are also code examples that should not be sourced - they explain concepts that don't require a sourceable example. Such code blocks appear in generic code syntax highlighting, like this: > def ThisFunction() # script-local def g:ThatFunction() # global export def Function() # for import and import autoload < ============================================================================== 1. What is Vim9 script? *Vim9-script* Vim script has been growing over time, while preserving backwards compatibility. That means bad choices from the past often can't be changed and compatibility with Vi restricts possible solutions. Execution is quite slow, each line is parsed every time it is executed. The main goal of Vim9 script is to drastically improve performance. This is accomplished by compiling commands into instructions that can be efficiently executed. An increase in execution speed of 10 to 100 times can be expected. A secondary goal is to avoid Vim-specific constructs and get closer to commonly used programming languages, such as JavaScript, TypeScript and Java. The performance improvements can only be achieved by not being 100% backwards compatible. For example, making function arguments available in the "a:" dictionary adds quite a lot of overhead. In a Vim9 function this dictionary is not available. Other differences are more subtle, such as how errors are handled. Vim9 script syntax, semantics, and behavior apply in: - a function defined with the `:def` command - a script file where the first command is `vim9script` - an autocommand defined in the context of the above - a command prefixed with the `vim9cmd` command modifier When using `:function` in a Vim9 script file the legacy syntax is used, with the highest |scriptversion|. However, this can be confusing and is therefore discouraged. Vim9 script and legacy Vim script can be mixed. There is no requirement to rewrite old scripts, they keep working as before. You may want to use a few `:def` functions for code that needs to be fast. :vim9[cmd] {cmd} *:vim9* *:vim9cmd* Evaluate and execute {cmd} using Vim9 script syntax, semantics, and behavior. Useful when typing a command, in a `:function`, or a legacy Vim script. The following short example shows how a legacy Vim script command and a :vim9cmd (so Vim9 script context) may appear similar, though may differ not just syntactically, but also semantically and behaviorally. >vim call popup_notification('entrée'[5:] \ ->str2list()->string(), #{time: 7000}) vim9cmd popup_notification('entrée'[5 :] ->str2list()->string(), {time: 7000}) < Notes: 1. The reason for the different output is Vim9 script uses character indexing whereas legacy Vim script uses byte indexing - see |vim9-string-index|. 2. Syntax is different too. In Vim9 script: - The space in "[5 :]" is mandatory (see |vim9-white-space|). - Line continuation with "\" is not required. - The "#" (to avoid putting quotes around dictionary keys) is neither required nor allowed - see |#{}|. *E1164* `:vim9cmd` cannot stand alone; it must be followed by a command. :leg[acy] {cmd} *:leg* *:legacy* Evaluate and execute {cmd} using legacy Vim script syntax, semantics, and behavior. It is only applicable in a Vim9 script or a `:def` function. Using an equivalent script to the one, above (see its notes for why the output differs): >vim9 vim9script # In legacy Vim script context the popup is [769, 101] legacy call popup_notification('entrée'[5:] \ ->str2list()->string(), #{time: 7000}) # In Vim9 script context the popup is [101] popup_notification('entrée'[5 :] ->str2list()->string(), {time: 7000}) < Vim9 script's script-local variables may be used by prefixing "s:", like in legacy Vim script. This example shows the difference in syntax: "k" for the script-local variable in Vim9 script, "s:k" in the legacy Vim script context. >vim9 vim9script var k: string = "Okay" echo k legacy echo s:k < *E1189* Using `:legacy` is not allowed in compiled Vim9 script control flow contexts. For example: >vim9 vim9script def F_1189() if v:version == 900 # E1189: Cannot use :legacy with this command: endif legacy endif enddef F_1189() < *E1234* `:legacy` cannot stand alone; it must be followed by a command. ============================================================================== 2. Differences from legacy Vim script *vim9-differences* Overview ~ *E1146* The following list is a brief summary of some key differences between legacy Vim script and Vim9 script, including `:def` functions: - Comments start with #, not ": >vim9 vim9script # Comments start with a number sign (#), not a quotation mark (") < - Using a backslash (i.e., \, a reverse solidus) for line continuation is rarely needed: >vim9 vim9script echo $"Your $HOME directory is {$HOME}\n" .. $"Your $VIMRUNTIME environment variable is {$VIMRUNTIME}" < - White space is required in many places, improving readability. See |vim9-white-space|. *E1126* - Declare variables with `:var` and assign values without `:let` (which is not allowed): >vim9 vim9script var count = 0 count += 3 # 3 echo count let E1126 = count # E1126: Cannot use :let in Vim9 script < - Constants can be declared with `:final` and `:const`: >vim9 vim9script final matches = ['Peter'] # adding to this list later is okay const NAMES = ['Paul', 'Mary'] # NAMES constant cannot be changed matches->extend(NAMES) echo matches # ['Peter', 'Paul', 'Mary'] < - Variables and functions are script-local by default (see |vim9-scopes|). - Functions are declared with argument types and return type: >vim9 vim9script def Cubed(n: float): string # float arg, string returned return $"\n{n} cubed is {n->pow(3)}" enddef echo Cubed(input("Enter a float to cube: ")->str2float()) < - Calling functions does not require `:call`. Although it is deprecated, using it does not give an error: >vim9 vim9script popup_notification("Builtin function called WITHOUT :call", {}) call popup_notification("Builtin function called WITH :call", {}) < *vim9-invalid-Ex-commands* - You cannot use these Ex commands: `:Print` (or shortened forms like `:Pr`) `:append` (or shortened forms like `:a`) `:change` (or shortened forms like `:c`) `:dp` `:insert` (or shortened forms like `:i`) `:k` `:mode` (or the shortened form `:mod`) `:open` (or shortened forms like `:o`) `:sce` `:scg` `:sci` `:scI` `:scl` `:scn` `:scp` `:sg` `:sgc` `:sge` `:sgi` `:sgI` `:sgl` `:sgn` `:sgp` `:sgr` `:sic` `:sie` `:siI` `:sin` `:sip` `:sir` `:sI` `:sIc` `:sIe` `:sIg` `:sIi` `:sIl` `:sIn` `:sIp` `:sIr` `:src` `:srg` `:sri` `:srI` `:srl` `:srn` `:srp` `:t` `:xit` (or shortened forms `:x` and `:xi`) Note: There are some commands that do not give errors but behave differently in Vim9 script. One is `:dl`, which is an abbreviation of `:dlist` (whereas it is `:delete` in legacy Vim script). Others are `:sc`, `:si`, and `:sr`, which in legacy Vim script are short substitute commands (like the 38 others listed above). However, in Vim9 script they are shortened forms of `:scriptnames`, `:simalt`, and `:srewind` respectively. *vim9-no-shorten* *E1065* - Many commands cannot be shortened. Trying to use a shortened command will give E1065. Specifically, these commands' full names must be used: - Flow control commands: `:break`, `:catch`, `:continue`, `:else`, `:elseif`, `:endfor`, `:endif`, `:endtry`, `:endwhile`, `:finally`, `:finish`, `:return`, `:throw`, `:while` - Declaration keywords: `:abstract`, `:class`, `:const`, `:def`, `:endclass`, `:enddef`, `:endenum`, `:endinterface`, `:enum`, `:export`, `:final`, `:import`, `:interface`, `:public`, `:static`, `:this`, `:type`, `:var` - `:final` cannot be used as a shortened form of `:finally`. That is because it means |:final| in Vim9 script. By itself, `:final` lists all variables, the same as a bare `:let` in legacy Vim script. - You cannot use |curly-braces-names| like `my_{&background}_message`. - A range before a command must be prefixed with a colon, for example: >vim9 vim9script # The following line displays lines containing the word 'colon' :-3,+2g/colon # The following line gives E1050: colon required before a range -3,+2g/colon < - Executing a register with "@" doesn't work; prepend either a colon or use `:execute`: >vim9 vim9script @a = 'echo "Works"' :@a # Works execute @a # Works @a # E1207: Expression without an effect @a < - Unless mentioned specifically, the highest |scriptversion| is used. - When defining an expression mapping, the expression will be evaluated in the context of the script where it was defined. - When indexing a string, the index is counted in characters, not bytes. For implications and examples, see |vim9-string-index|. - There are some possibly unexpected differences - see |vim9-gotchas|. Comments starting with # ~ *vim9-comments* In legacy Vim script, comments start with a quotation mark ("). In Vim9 script, comments start with a number sign (#). >vim9 vim9script # This is a comment 'Vim9 script uses #, not "'->popup_notification({}) # Another comment < The reason is that a quotation mark can also start a string. In many places, especially halfway through an expression with a line break, it is hard to tell what the meaning is because both a string and a comment can be followed by arbitrary text. To avoid confusion, only # comments are recognized. This is the same as in shell scripts and Python. In Vi, # is a command to list text with numbers. In Vim9 script, `:number` may be used. For example, the following one-line script prints this paragraph. >vim9 vim9cmd :-4,-2number < To improve readability, there must be at least one space or tab between a command and the # starting a comment. With 'syntax' set, syntax highlighting also helps to show where an invalid comment is used. For example: >vim9 vim9script const OKAY: bool = true # A valid comment (white space before the #) echo OKAY # true try const NO: bool = false# THIS IS AN INVALID COMMENT! catch echo v:exception # E121: Undefined variable: false# endtry < *E1170* You cannot not start a comment with `#{` - it looks like the legacy dictionary literal and produces an error where this might be confusing, for example: >vim9 vim9script #{ E1170: Cannot use #{ to start a comment: < A |fold-marker| (i.e., `#{{{`) used to start a fold, is still okay. When reading a script, Vim doesn't know whether it is |Vim9| script before finding the `vim9script` command. Before it, comments must use legacy syntax, so a quotation mark: >vim9 " legacy Vim script comment before vim9script vim9script # Vim9 script comment < That looks ugly (especially with the syntax highlighting not treating the initial Vim script comment in Comment highlight group as a command). It is better having the `vim9script` command as the first line: >vim9 vim9script # Vim9 script comment < In legacy Vim script, # is also used for the alternate file name. In Vim9 script you must use %% instead. Instead of ##, use %%%, which stands for all arguments. See |c_%%| and |c_%%%#|. Vim9 functions ~ *vim9-functions* A function defined with `:def` is compiled. Execution is many times faster, often 10 to 100 times. Many errors are already found when compiling, before the function is executed. The syntax is strict, to enforce code that is easy to read and understand. Compilation is done when any of these is encountered: - the first time the function is called - when the `:defcompile` command is encountered in the script after the function was defined - `:disassemble` is used for the function, or - a function that is compiled calls the function or uses it as a function reference (so that the argument and return types can be checked). *E1099* "Unknown error", E1099, may occur while executing. If reproducible, it may be reported at https://github.com/vim/vim/issues as it is now likely to be a rare, unhandled error worth reporting. *E1091* If compilation fails it is not tried again on the next call, instead this error is given: "E1091: Function is not compiled: {name}". For example: >vim9 vim9script def g:Broken(): string echo 'a' .. [] enddef g:Broken() # E1105: Cannot convert list to string < Compilation failed. Now, attempting to call "g:Broken" gives E1091: >vim9 vim9cmd g:Broken() # E1091: Function is not compiled: Broken < *E1191* Trying to call a function which failed to compile may also return: "E1191: Call to function that failed to compile". For example: >vim9 vim9script def Set_hlsearch() &hlsearch = 9 # NB: 'hlsearch' is bool, so would give E1012 enddef def D_Set_hlsearch() Set_hlsearch() enddef # With 'silent!', this call does not abort, despite the E1012 error silent! Set_hlsearch() # Trying to use the function that failed to compile gives E1191: D_Set_hlsearch() # E1191: Call to function that failed to compile < Compilation will fail when attempting to execute a user command that does not exist at either compile or execution time. So, this fails: >vim9 vim9cmd YeahNah() # E117: Unknown function: YeahNah < However, a user command contained in a function, which itself is not yet compiled, does not fail. For example, this script can be sourced without error even though neither command in either of the functions exists: >vim9 vim9script def g:Late1() DefinedLate1 enddef def g:Late2() execute('DefinedLate2') enddef < Further, if the functions, above, are subsequently called before the commands DefinedLate1 and DefinedLate2 exist, compilation fails. So, after sourcing the script, above, when the following script is sourced, either |E476| or |E492| are given: >vim9 vim9cmd g:Late1() # E476: Invalid command: DefinedLate1 vim9cmd g:Late2() # E492: Not an editor command: DefinedLate2 < Although those calls fail, and for different reasons, the point is that any commands must exist when they are executed. So, the following script works because the commands are defined prior to being executed (Note: The script defining the two global functions must be re-sourced before sourcing this script): >vim9 vim9script command DefinedLate1 @a = "One" command DefinedLate2 @b = "Two" g:Late1() g:Late2() echo (@a, @b) # ('One', 'Two') < A `:def` function has no options like `:function` (i.e., "abort", "range", "closure", or "dict"). A `:def` function: - always aborts on an error unless the error is caught by a `:try` block or `:silent!` is used calling the function (for an example, see the first script under |E1191|), - may not have a range passed, - automatically supports closures (for an example, see |vim9-closure|), and - cannot be a "dict" function (see |vim9-no-dict-function|, which follows). *vim9-no-dict-function* Neither the "dict" option nor "dict" functions are supported in a `:def` function. To illustrate, first consider this working legacy Vim script: >vim " legacy Vim script dict function let dic = {'ln': [0, 1, 2, 3]} function! dic.Len() dict return len(self.ln) endfunction echo dic.Len() | " 4 < *E1182* In Vim9 script, trying to do something similar gives E1182: >vim9 vim9script var dic: dict> = {'ln': [0, 1, 2, 3]} def dic.len(): number # E1182: Cannot define a dict function in Vim9… return len(self.ln) enddef < Instead of using a "dict" function, in Vim9 script, there are a few options: - Use a Vim9 Class (see |Vim9-class|): >vim9 vim9script class MyClass var ln: list def Len(): number return this.ln->len() enddef endclass var obj = MyClass.new([0, 1, 2, 3]) echo obj.Len() # 4 < - Pass the dictionary explicitly: >vim9 vim9script def DicLen(self: dict, arg: string): number return self[arg]->len() enddef var da: dict = {func: DicLen, item: [0, 1, 2, 3]} echo da.func(da, 'item') # 4 < - Call a legacy Vim script dict function (|Dictionary-function|): >vim9 vim9script function LegDicLen() dict return self.item->len() endfunc def CallLegDicLen(): number var da: dict = {func: LegDicLen, item: [0, 1, 2, 3]} return da.func() enddef echo CallLegDicLen() # 4 < The argument types and return type need to be specified and match - various errors may occur when they do not. See |fast-functions| and |type-checking|. *vim9-any-type* The "any" type can be used, type checking will then be done at runtime, like with legacy functions, and allows the type to change. For example: >vim9 vim9script var avar: any echo avar->typename() # number avar = 'A string' echo avar->typename() # string avar = [['A', 'list'], ['of', 'lists']] echo avar->typename() # list> < Warning: The "any" type defaults to the number type and 0. Operations demanding a specific type may produce unexpected results or errors if that is not factored. Further, unlike a variable explicitly declared as a number, direct assignment of any other type means the variable's type is re-inferred, which can occur multiple times at runtime. For example: >vim9 vim9script var n1: any echo n1->typename() # number n1 ..= 'zero' echo n1 # 0zero (that is, the default 0 and "zero") echo n1->typename() # string n1 = true echo n1->typename() # bool var n2: any n2->extend(['item']) # E712: Argument of extend() must be a List o… < Arguments are accessed by name, without "a:", just like any other language. There is no "a:" dictionary or "a:000" list. This example shows not only "a:" but also valid extreme white space minimization in a legacy Vim script: >vim function! MyFirst(s,d,n,...) return a:s.a:d[a:n].a:000[1] endfunction let MyDict={1:'one',2:'two'} echo MyFirst('The value of key 2 of MyDict is ', \ MyDict,2,v:null,'!',9999) < The equivalent, in Vim9 script: >vim9 vim9script def MyFirst(s: string, d: dict, n: number, ...l: list): string return s .. d[n] .. l[1] enddef var MyDict: dict = {1: 'one', 2: 'two'} echo MyFirst('The value of key 2 of MyDict is ', MyDict, 2, null, '!', 9999) < Note: In this Vim9 script, an error would occur if omitting spaces: - after any of the commas - after any of the colons in 'key: value' or 'variable: type' - before/after instances of '..', and - before/after '='. *vim9-variable-arguments* The previous example shows variable arguments ("...l: list") defined as the last argument. In Vim9 script, variable arguments require a name and list, similar to TypeScript. This example iterates a variadic list of numbers: >vim9 vim9script def MyProduct(...ln: list): number var prod: number = 1 for num in ln prod *= num endfor return prod enddef echo MyProduct(10, 10) # 100 echo MyProduct(5, 4, 5) # 100 < Errors may occur when variadic arguments are not declared or passed correctly: *E1055* - Failing to provide the name to a variable argument: >vim9 vim9script def F1055(n: number, ...): void # E1055: Missing name after ... enddef < *E1160* - Trying to use a default for a variable argument: >vim9 vim9script def F1160(...l = []): void # E1160: Cannot use a default for variabl… enddef < *E1180* - Failing to declare a variable argument as a list: >vim9 vim9script def F1180(...l: string): void # E1180: Variable arguments type must… enddef < When a function argument is optional (that is, it has a default value), passing `v:none` as the argument results in using the default value. This is useful when you want to specify a value for an argument that comes after an argument that should use its default value. For example: >vim9 vim9script def F(pi: float = 3.14, ra: float = 1.0): float return pi * ra->pow(2) enddef echo F(v:none, 2.0) # 12.56 (using default 'pi' value, 3.14) < *E1106* When too many arguments are passed, either an |E176| or E1106 error occurs. An E1106 example: >vim9 vim9script var ln: list = [1, 2, 4, 8] foreach(ln, (val) => { echo val }) # E1106: One argument too many (the Lambda has only one argument) < Note: `foreach()` passes two arguments to its callback: for a list, they are the list's index and value. Vim9 lambdas must have both (technically, "matching arity"), even when only one appears to be required. So, "(val)" should be "(_, val)", explained below. *vim9-ignored-argument* The argument "_" (an underscore) can be used to ignore the argument. This is most useful in callbacks where you don't need it, but do need to give an argument to match the call. For example, when using |map()| with a list, two arguments are passed, the index and the value. The following script first demonstrates ignoring the indexes, then ignoring the values: >vim9 vim9script final nl: list = [1, 2, 4, 8] map(nl, (_, val) => val * 2) # '_' ignores the indexes echo nl # [2, 4, 8, 16] map(nl, (idx, _) => idx * 2) # '_' ignores the values echo nl # [0, 2, 4, 6] < The "_" argument can be used multiple times, and no type is needed. >vim9 vim9script var count: number def In20s(_, _, year: number): void count += year >= 2020 ? 1 : 0 enddef var data = [['Bo', 'A', 2026], ['Mo', 'B', 2018], ['Jo', 'A', 2022]] for staff in data In20s->call(staff) endfor echo $"There are {count} staff members in the 2020s." < Note: This script uses |call()|, not to be confused with |:call|. *E1181* Using "_" in a disallowed context gives error E1181. For example: >vim9 vim9script def F1181(_): string return _ # E1181: Cannot use an underscore here enddef echo F1181("No") < Functions and variables are script-local by default ~ *vim9-scopes* When using `:function` or `:def` to specify a new function at the script level in a Vim9 script, the function is local to the script (like prefixing "s:" in legacy Vim script). To define a global function or variable, the "g:" prefix must be used. For functions in a script that is to be imported, and in an autoload script, `:export` needs to be used for those to be used elsewhere. > def ThisFunction() # script-local def g:ThatFunction() # global export def Function() # for import and import autoload < *E1075* Using "s:" (like in a legacy Vim script function), is not allowed. If used in a script level `:def` function, |E1268| is given, and, if used in a nested `:def` function, E1075. For example: >vim9 vim9script def F1075(): void def s:Inner() # E1075: Namespace not supported: s:Inner() enddef enddef F1075() < When using `:function` or `:def` to specify a nested function inside a `:def` function and no namespace was given, the nested function is local to the code block it is defined in. It cannot be used in a `function()` with a string argument. Instead, pass the function reference itself: >vim9 vim9script def Outer(): void def Inner(): string return 'Inner() successfully called' enddef var Okay = function(Inner) echo Okay() # Inner() successfully called try var Bad = function("Inner") catch echo v:exception # Vim:E700: Unknown function: Inner endtry enddef Outer() < Note: Passing the string argument fails because "Inner" becomes a function reference to a function with a generated internal name, which could be shown with "funcref(Inner)". It is not possible to define a script-local function in a function. You can define a local function and assign it to a script-local |Funcref|, though it must first have been declared at the script level. >vim9 vim9script var ScriptLocalFuncref: func def Outer(): void def Inner(): string return "Hi from ScriptLocalFuncref!" enddef ScriptLocalFuncref = Inner enddef Outer() echo ScriptLocalFuncref() < When referring to an unprefixed function (i.e., without either a "g:" or "s:" prefix), Vim will search for the function in the function scope, in block scopes, and in the script scope. Imported functions are found with the prefix from the `:import` command. Exporting and importing is explained at |vim9-import|. In Vim9 script, a script-local function reference must start with an uppercase letter. Consequently, even in scenarios where "s:" is required (within legacy Vim script scopes), "s:Funcref" must be used, avoiding potential ambiguity with builtin functions. Consider the following legacy Vim script and Vim9 script examples. - First, legacy Vim script, showing that "s:" may be used in a legacy Vim script to define a function, which would otherwise interfere with a builtin function (in this instance, the builtin, |cos()|): >vim function! s:cos() echo 's:cos() works' endfunction call s:cos() " s:cos() works < - Second, Vim9 scripts, showing that legacy functions: 1. Must start with an uppercase letter (otherwise |E1267| is given), 2. Cannot be defined with "s:" in a Vim9 script-local scope (|E1268|), and 3. Within the legacy scope of a function, "s:" is required but, for the reasons, above, must be "s:" and an uppercase letter (|E117|): >vim9 vim9script execute ('function cos()') # E1267: Function name must start with a … < >vim9 vim9script execute ('function s:cos()') # E1268: Cannot use s: in Vim9 script: … < >vim9 vim9script function Cos() echo 'This works: now we are in Cos().' endfunction function Call_Cos() call s:Cos() " Requires the 's:' call Cos() " E117: Unknown function: Cos endfunction Call_Cos() < *vim9-s-namespace* *E1268* Within a Vim9 script's `:def` function, "s:" cannot be used. Compare these two scripts: first, legacy Vim script where "s:" may be used in a `:def` then, second, Vim9 script where E1268 is given: >vim " Legacy Vim script - s: working in a :def, though it is optional let s:leg = 'okay' def Ok_def_s(): void # Note that either leg or s:leg are valid here echo leg .. ', ' .. s:leg # okay, okay enddef call Ok_def_s() < >vim9 vim9script var nine: string def F1268(): void echo s:nine # E1268: Cannot use s: in Vim9 script: s:nine enddef F1268() < The use of the "s:" prefix is not supported in the Vim9 script-local scope. Functions and variables without a prefix are always script-local. This includes calling legacy functions: >vim9 vim9script function ScriptLevel(str) echo a:str endfunction ScriptLevel('okay') # The following gives E1268: Cannot use s: in Vim9 script s:ScriptLevel('not okay') < Within legacy functions, using "s:" for script-local variables is always required: >vim9 vim9script var local: string = 'script-local :var' function Legacy_requires_s() echo s:local " Without 's:', 'local' gives E121: echo local endfunction Legacy_requires_s() < In all cases the function must be defined before it is used. That is, either when it is called explicitly (including if `:defcompile` causes it to be compiled), or when code that calls it is being compiled, inferring the return type. The result is that functions and variables without a namespace can usually be found in the script, either defined there or imported. Global functions and variables could be defined anywhere. (Good luck finding out where! You can often see where it was last set using |:verbose|). Deleting functions in a Vim9 script ~ *E1084* In Vim9 script, script-local functions (either `:function` or `:def`) are defined once when the script is sourced and cannot be deleted or replaced by the script itself: >vim9 vim9script def MyDef(): void enddef delfunction MyDef # E1084: Cannot delete Vim9 script function MyDef < Note: A script-local function may be replaced by reloading the script. See |vim9-reload|. Global functions ("g:" prefixed) can still be defined and deleted at nearly any time, though deleting a global function in Vim9 script has a distinction between |function()| and |funcref()|. When a global function is deleted and redefined, the replacement global function is updated dynamically in any variables calling it whereas the function reference is persistent (unless the variable itself is redeclared). This is an important distinction, differing from legacy Vim script behavior, where deleting a function deletes the funcref too. To illustrate: >vim9 vim9script def g:F(): string return 'one' enddef var Function = function(g:F) var Funcref = funcref(g:F) echo (Function(), Funcref()) # ('one', 'one') delfunction g:F def g:F(): string return 'two' enddef echo (Function(), Funcref()) # ('two', 'one') Funcref = funcref(g:F) # Redeclare Funcref echo (Function(), Funcref()) # ('two', 'two') < Note: This persistent behavior of |funcref()| may be regarded as a feature, or may be unexpected if not understood. When compiling a function, and a function call is encountered for a function that is not (yet) defined, the |FuncUndefined| autocommand is not triggered. You can use an autoload function if needed, or call a legacy function and have |FuncUndefined| triggered there. Reloading a Vim9 script clears functions and variables by default ~ *vim9-reload* *vim9-noclear* When loading a legacy Vim script a second or subsequent time, nothing is removed. Commands will replace existing variables and functions, create new ones, and leave removed things hanging around. When loading a Vim9 script a second or subsequent time, the default is that all existing script-local functions and variables are deleted. So, you start with a clean slate. This is useful if you are developing a plugin and want to try a new version. If you renamed something you don't have to worry about the old name persisting. The exported functions and variables of an autoload script live in the global namespace with the autoload prefix. When such a script is sourced again they are likewise given a clean slate, so an autoload script can be sourced more than once. A class or enum in an autoload script is an exception: it cannot be redefined this way and |E1041| is given, because objects created from the previous definition would keep referring to it. Restart Vim to load a changed class or enum in an autoload script. In other scripts a class or enum is cleared like everything else, so it can be redefined. If you do want to keep script-local functions and variables, use "noclear". To illustrate, source this script a few times; every time it is sourced, another 9 is added to MyList: >vim9 vim9script noclear var MyList: list = !exists('MyList') ? [9] : MyList->add(9) echo MyList < You want to use this in scripts that use a `finish` command to bail out at some point when loaded again. For example, when a buffer local option is set to a function, the function does not need to be defined more than once: >vim9 vim9script noclear # 'We are in SomeFunc()' is echoed only the first time this script is # sourced. Subsequent times, you are told, 'SomeFunc exists already'. setlocal completefunc=SomeFunc if exists('*SomeFunc') popup_notification('SomeFunc() exists already', {time: 4000}) finish endif def SomeFunc() popup_notification('We are in SomeFunc()', {time: 4000}) enddef SomeFunc() < *E1149* An important consequence of cleared script-local functions and variables is that idiomatic practices, such as finishing when "g:loaded_{plugin_name}" exists, means it's important to remember that variables and functions do not persist. To illustrate, source the following Vim9 script. Then source it again. The first time in it will echo "Okay...." The second/subsequent times it gives an E1149 error: >vim9 vim9script :+7,+15source echo g:GetName() # The second and subsequent times it is sourced, this error is given: # E1149: Script variable is invalid after reload in function GetName < > " DO NOT SOURCE THIS SCRIPT: TO FOLLOW THIS DEMO, SOURCE THE ONE ABOVE vim9script if exists('g:loaded_E1149') finish endif g:loaded_E1149 = true var name: string = 'Okay (declared only the first time sourced!)' def g:GetName(): string return name enddef < Note: If you want to re-run this, use `:unlet` g:loaded_E1149 to remove the global variable. *E1150* Variables' types are not cleared when using `noclear` (|vim9-noclear|). If you try to change a variable's type, E1150 may be given. For example, if you source the following script it echoes "string". If you then source the second script it gives E1150: >vim9 vim9script var my_var: string = "string" def g:Get_myvar(): void echo my_var enddef g:Get_myvar() < >vim9 vim9script noclear my_var = false # This changes my_var to a bool echo my_var # false echo my_var->typename() # bool g:Get_myvar() # E1150: Script variable type changed < *E1190* When reloading with `noclear`, compiled function calls are preserved. If a called function's signature changes, argument mismatches will occur. For example, when sourced for the first time, the following script echoes "9". However, when sourced subsequently, the changed function signature change means there is one argument too few and E1190 is given: >vim9 vim9script noclear if !exists('g:loaded_E1190') def Echo(n: number): void echo n enddef def CallEcho(n: number): void Echo(n) enddef else # Redefine Echo() with a second argument def Echo(n: number, x: number) echo n * x enddef endif CallEcho(9) # First time, 9. Second, E1190: One argument too few. g:loaded_E1190 = true < Variable declarations with :var, :final, and :const ~ *vim9-declaration* *:var* Local variables need to be declared with `:var`. Local constants need to be declared with either `:final` or `:const`. Collectively they are referred to as "variables" in this section. Shortening `:var`, `:final`, or `:const` is not allowed - see |vim9-no-shorten|. Variables can be local to a script, function, or code block. The following example demonstrates all three: >vim9 vim9script var s: string = 'script' def Func(): void var f: string = 'function' { var b: string = 'block' echo $"Visible: {s}, {f}, and {b}" } echo $"Visible: {s} and {f}" # b: invisible outside the {...} block enddef Func() echo $"Visible: {s} only" # f and b: invisible outside the :def < Note: See |vim9-exists()| for limitations in determining whether a variable exists. *vim9-block* Variables are only visible in the block where they are defined, including any nested blocks. Once the block ends the variable is no longer accessible and, if you try to use it, gives E121. So, for example, to intentionally "hide" a variable from code which follows it, a block may be used to make the variable only accessible within the block's scope: >vim9 vim9script { var inblock: string = 'inblock is not visible outside the block!' } echo inblock # E121: Undefined variable: inblock < For the variable "inblock" to be visible, it needs to be declared earlier: >vim9 vim9script var inblock: string { inblock = 'when defined earlier, inblock is visible outside' } echo inblock < A block is especially useful in a user command (see also |command-block|). In the following example, the SAVE constant is assigned the value of the unnamed register and later it is used to revert the unnamed register. The SAVE constant is invisible outside the user command: >vim9 vim9script # Create the YankHelpGrep command (to :helpgrep a visual selection) command -register YankHelpGrep { const SAVE = @" normal! y execute $"helpgrep {getreg('')}" @" = SAVE copen } # Map YH in Visual mode to YankLhelpGrep xnoremap YH YankHelpGrep " < A block can also be useful with autocommands (see |:autocmd-block|). Although a block may be useful and terse, using a `:def` function works better in many instances, and often is more readable. *E1025* *E1128* A block with a missing left curly bracket may give E1025 or E1128. Examples: >vim9 vim9script def F1025() } enddef defcompile F1025 # E1025: Using } outside of a block scope vim9 vim9cmd } # E1128: } without { < Errors given when incorrectly declaring or initializing a variable include: *E1017* >vim9 vim9script var F1017: func = (): void => { var a: any var a = 'error' # E1017: Variable already declared: a } < *E1020* >vim9 vim9script var x += 4 # E1020: Cannot use an operator on a new variable: x += 4 < *E1022* >vim9 vim9script var x # E1022: Type or initialization required < *E1034* >vim9 vim9script var this = 'reserved' # E1034: Cannot use reserved name this < *E1054* >vim9 vim9script var x: bool var F1054: func = (): void => { var x = 'no' # E1054: Variable already declared in the script: x } < *E1087* >vim9 vim9script var F1087: func = (): void => { var x.y = 0 # E1087: Cannot use an index when declaring a variable } < *E1124* >vim9 vim9script function F1124() var x = 'E1124: ":var" cannot be used in legacy Vim script' endfunction F1124() < *E1079* A variable cannot be declared in Command-line mode or Ex mode. For example: >vim9 vim9script feedkeys(":vim9cmd var x = 0\") # E1079: Cannot declare a variable on the command line < Declaring a variable with a type, but without an initializer, defaults to: - `false` for bool - 0 for number and "any" - 0.0 for float, and - empty (for all other types that can be declared without an initializer). To illustrate: >vim9 vim9script var a: any | var b: bool | var n: number | var f: float echo [a, b, f, n] # [0, false, 0.0, 0] var s: string | var F: func | var l: list | var d: dict | \ var j: job | var c: channel | var z: blob | var t: tuple echo empty(s) && empty(F) && empty(l) && empty(d) && empty(j) && \ empty(c) && empty(z) && empty(t) # true < Note: Take care using the "any" type given its default is 0. For implications, see |vim9-any-type|. Uninitialized container types can be added to. For example: >vim9 vim9script var myDict: dict> var myList: list myList->add(9) myDict['version'] = myList echo myDict # {'version': [9]} < Initializing a variable to a null value differs from initializing a variable with "null_". Particularly, `null_dict`, `null_list`, and `null_blob` give errors when trying to add to/extend variables initialized to them: - `null_dict`: *E1103* >vim9 vim9script var nd = null_dict def F1103(): void nd['a'] = 'fail' # E1103: Dictionary not set enddef F1103() < *E1133* >vim9 vim9script var ed: dict # An empty dict can be extended ed->extend({'a': 'okay'}) echo ed # {'a': 'okay'} var nd: dict = null_dict nd->extend({'a': 'fail'}) # E1133: Cannot extend a null_dict < - `null_list`: *E1147* >vim9 vim9script var nl = null_list def F1147(): void nl[0] = 'fail' # E1147: List not set enddef F1147() < *E1130* >vim9 vim9script var el: list # An empty list can be added to el->add('okay') echo el # ['okay'] var nl: list = null_list nl->add('fail') # E1130: Cannot add to null_list < *E1134* >vim9 vim9script var el: list # An empty list can be extended el->extend(['okay']) echo el # ['okay'] var nl: list = null_list nl->extend(['fail']) # E1134: Cannot extend a null_list < - `null_blob`: *E1581* >vim9 vim9script var eb: blob # An empty blob can be extended eb->extend(0zF09F988A) echo eb->blob2str() # ['😊'] var nb: blob = null_blob nb->extend(0zF09F988A) # E1581: Cannot extend a null_blob < *E1131* >vim9 vim9script var eb: blob # An empty blob can be added to eb->add(0xF0)->add(0x9F)->add(0x98)->add(0x8A) echo eb->blob2str() # ['😊'] var nb: blob = null_blob nb->add(0xF0) # E1131: Cannot add to null_blob < Note: Similar errors should not be encountered with: - `null_tuple` (because |Tuples| are immutable, neither adding to nor extending them is permitted), and - `null_string` (which is one of the |null-anomalies|), for example: >vim9 vim9script var ns: string = null_string ns ..= 'Okay!' echo ns # Okay! < Using |:let| is not allowed in Vim9 script. Trying to do so gives |E1226|. An existing variable is assigned to without any command. The same applies to global, window, tab, buffer and Vim variables, because they are not really declared. They can also be deleted with |:unlet|, for example: >vim9 vim9script g:v = "global" b:v = "buffer local" t:v = "tab local" w:v = "window local" echo [g:v, b:v, w:v, t:v] unlet g:v | unlet b:v | unlet w:v | unlet t:v # Now none of the 'v' variables exist, so this echoes [0, 0, 0, 0] echo [exists('g:v'), exists('b:v'), exists('w:v'), exists('t:v')] < Declaring any of the following with `:var` gives an error: - a global, buffer, tab, or window variable - an option, or - a register. Examples: *E1016* >vim9 vim9script var t:err = 'err' # E1016: Cannot declare a tab variable: t:err < *E1052* >vim9 vim9script var &ts = 8 # E1052: Cannot declare an option: &ts = 8 < *E1066* >vim9 vim9script var @a = 'no' # E1066: Cannot declare a register: @a = 'no' < *E1178* Use `:const` or `:final` instead of `:lockvar`, which does not work on local variables. >vim9 vim9script def F1178(): void var x: any lockvar x enddef F1178() # E1178: Cannot lock or unlock a local variable < Even though `:lockvar` works with script-local variables, using `:const` or `:final` usually is better for those too, except where locked/unlocked toggling is wanted, which is shown in this example: >vim9 vim9script var n: number = 8 lockvar n try n = 9 catch echo v:exception # E741: Value is locked: n finally unlockvar n endtry n = 9 echo n # 9 < *vim9-exists()* The `exists()` (and `exists_compiled()`) function does not work on local arguments or variables declared in a compiled function. It always returns 0. However, `exists()` works in both non-compiled Vim9 script and on variables tested from within a compiled function where the variable is declared already in a non-compiled scope. To illustrate: >vim9 vim9script var script: any var MyCompiled: func = (arg: any): void => { var compiled: any echo exists('arg') # 0 (compiled, local argument) echo exists('compiled') # 0 (compiled, local variable) echo exists('script') # 1 (compiled, script-local variable) } MyCompiled(true) echo exists('script') # 1 (script-local scope and variable) < Also, `exists()` works in a Vim9 script for arguments and variables in a legacy function, including those declared with `:var`. For example: >vim9 vim9script function Legacy(arg = 'yes') let local = 'yes' vim9cmd var vlocal: string = 'yes' return [exists('a:arg'), exists('local'), exists('vlocal')] endfunction echo Legacy() # [1, 1, 1] < *vim9-no-shadowing* Variables, functions and function arguments cannot shadow previously defined or imported variables and functions in the same script file. However, variables can shadow Ex commands, so rename the variable if necessary. The following are examples of errors given when trying to shadow: *E1006* >vim9 vim9script def F1006(n: number): void var n: number = 10 # E1006: n is used as an argument enddef F1006(9) < *E1041* >vim9 vim9script def X(): void enddef var X: number # E1041: Redefining script item: "X" < *E1167* >vim9 vim9script var ll: list = [2, 3, 1] def F1167(): void var x: number = 1 echo ll->sort((x, y) => x - y) enddef F1167() # E1167: Argument name shadows existing variable: x < *E1168* >vim9 vim9script var ll: list = [2, 3, 1] var x: number echo ll->sort((x, y) => x - y) # E1168: Argument already declared in… < *E1213* Attempting to redefine an imported script's name will give E1213 (see also |:import|). For example, the following script will write a temporary file, which is then imported as "Imp" and its variable, "y", echoed. Subsequently, E1213 is given because "Imp" is the {name} of the imported script: >vim9 vim9script const TMP: string = tempname() var lines: list = ['vim9script', 'export var y = "Success!"'] lines->writefile(TMP) import TMP as Imp echo Imp.y # Success! var Imp: string # E1213: Redefining imported item "Imp" < Global variables and global functions must be prefixed with "g:", including at the script level. That is because a variable or function is script-local when it does not have a prefix in a Vim9 script-local scope. An example (noting this will appear to do nothing until you source the subsequent script): >vim9 vim9script var scriptvar: string = 'scriptvar is a script-local variable' def Sfunc(): string return 'Sfunc() is a script-local function' enddef g:globalvar = 'g:globalvar is a global variable' def g:Gfunc(): string return 'g:Gfunc() is a global function' enddef < Now source the following script. The first two will echo the "g:...is a global..." strings whereas the unprefixed variable and function will give |E121| (undefined variable) and |E117| (unknown function) respectively. >vim echo g:globalvar echo g:Gfunc() echo scriptvar echo Sfunc() < The "g:" prefix is not needed for |autoload| functions. *vim9-function-defined-later* In a Vim9 script, it is possible to call a global function before it exists provided it is called from within an `exists()` conditional. For example: >vim9 vim9script def Later(arg: number): void if exists('g:ExLater') g:ExLater(arg) endif enddef Later(1) def g:ExLater(arg: number): void popup_notification($'Called g:ExLater() - {arg}', {}) enddef Later(2) < When sourced initially, "Later(1)" does nothing because the `exists()` conditional skips calling "g:ExLater(arg)" (since it doesn't exist, yet). When sourced again, the "g:ExLater()" function exists, and both popups, "Called g:ExLater() - 1" and "Called g:ExLater() - 2", are generated. You could use `exists_compiled()` to avoid the error, however, then the function would not be called, even when it is defined later. To illustrate, in the following script neither of the "LaterCompiled()" calls generate the popup when sourced initially but, when sourced a second time, two popups are generated: >vim9 vim9script def LaterCompiled(arg: number): void if exists_compiled('g:ExCompLater') g:ExCompLater(arg) endif enddef LaterCompiled(1) def g:ExCompLater(arg: number): void popup_notification($'Called g:ExCompLater() with {arg}', {}) enddef LaterCompiled(2) < Since `&opt = value` is now assigning a value to option "opt", "&" by itself cannot be used to repeat a `:substitute` command. A ":" needs to precede the "&" to distinguish it as the repeat command. The following script demonstrates this. It creates a modifiable buffer in a new split, appends "princess", then replaces the "s" twice, resulting in "prince": >vim9 vim9script :sp | enew append(0, 'princess') :1substitute/s// :& < Note: If you did use "&" instead of ":&" in this script it would give |E112|. > < *vim9-unpack-ignore* For unpack assignment (destructuring), the underscore can be used to ignore a list item, similar to how a function argument can be ignored: >vim9 vim9script var theList: list = ['A', 'M', 'Z'] var [first, _, last] = theList # ignore the second item echo $"{first} to {last}" < To ignore any remaining items, use "; _": >vim9 vim9script def GetNameCountry(): list return ['Kamoga', 'Kibaale', 'Uganda', '9', 'M'] enddef # Unpack, ignoring second and all items after the third: var [name, _, country; _] = GetNameCountry() echo $"{name} lives in {country}" < Aside from declaring more than one variable at a time using unpack notation, each variable can either have a declared type or infer it from its value: >vim9 vim9script var one: tuple<...list> = (1, 'I', 'one', 'tahi', '١', '๑') var [d: number, _, _, m; _] = one echo $'Digit {d} is "{m}" in Māori.' < This approach should be used only where there is a list with values. Declaring one variable per line usually is easier to understand. The type of a variable that does not have a declared type is the type of the value it gets. The variable after the ";" gets the remaining items: for a list this is a list of the same member type, for a tuple this is a tuple of the types of the remaining items: >vim9 vim9script var [v1; v2] = [8, 9, 10] # v2 has type list var [v3; v4] = (null, 'a', true) # v4 has type tuple echo " Variable has type\n -------- --------" echo $"{v1->printf('%12S')} {v1->typename()}" echo $"{v2->printf('%12S')} {v2->typename()}" echo $"{v3->printf('%12S')} {v3->typename()}" echo $"{v4->printf('%12S')} {v4->typename()}" < When the value has type "any" the item types are not known and every variable gets type "any". *E1163* When unpacking, type mismatches give E1163. For example, the builtin function `getpos()` returns four numbers (bufnum, lnum, col, off) so "col" in this script is a type mismatch: >vim9 vim9script def F1163(): void var lin: number var col: bool [lin, col] = getpos('w0')[1 : 2] # E1163: Variable 2: type mismatc… enddef F1163() < *E1080* And E1080, which is the function-scope equivalent of |E452| at the script level, is given in a `:def` function if ";" is used more than once: >vim9 vim9script def F1080(): void var [b; l; c] = getpos('w0')[0 : 2] # E1080: Invalid assignment enddef F1080() < Constants ~ *vim9-const* *vim9-final* How constants work varies between languages. Some consider a variable that can't be assigned another value a constant. JavaScript is an example. Others also make the value immutable, thus when a constant uses a list, the list cannot be changed. Both can be used in Vim9 script. *E1021* *E1307* `:const` is used for making both the variable and the value a constant. Use this for composite structures that you want to make sure will not be modified. The following script shows: - That a constant must have a value, otherwise E1021 is given, and - Attempts to change a constant fail, with E1307. >vim9 vim9script try const MISSING_VAL: any catch echo v:exception # E1021: Const requires a value endtry def F1307(): void const L: list = [7, 8] L->add(9) # E1307: Argument 1: Trying to modify a const list enddef F1307() < Errors |E46| and |E741| may also be given if you try to modify a constant in the script-local scope. Note: It is common to write constants in ALL_CAPS, as has been done in the examples in this help file, though you do not have to. *:final* *E1125* `:final` is used for making only the variable a constant, but with the variable's values mutable. This is well known from Java. This example shows how a variable declared with final can have its values changed and concludes with another variable declared with final giving E1125 because it has no value: >vim9 vim9script final ln: list = [7] ln[1] = 9 # Adds an item to the list (okay with :final) ln->add(10) # Alternative way to add to the list ln->extend([11, 12]) # Extending the list with a list ln[0] = 8 # Changing the values is fine too echo ln # [8, 9, 10, 11, 12] final f1125: list # E1125: Final requires a value < The constant only applies to the value itself, not to what it refers to. An example, showing that all items are constant/locked except for those within the "females" list: >vim9 vim9script final females: list = ['Martha'] const NAMES: list> = [['Peter', 'Paul'], females] NAMES[1][0] = 'Mary' echo NAMES->flattennew() # ['Peter', 'Paul', 'Mary'] NAMES[1] = ["Mary"] # E741: Value is locked < Omitting :call and :eval ~ *vim9-omitting-:call* Functions can be called without `:call`. Using `:call`, as the following example shows, is allowed (though it's discouraged). >vim9 vim9script popup_create("Call functions without using :call", {time: 3000}) call popup_create(":call works, but isn't needed", {time: 6000}) < *vim9-omitting-:eval* Method calls can be made without `:eval` provided the evaluated expression is unequivocally an expression. Each `->` must be followed by a function name, and without a line break, otherwise |E260| is given. Likewise, the "(" of a function call cannot have a line break before it, otherwise |E107| is given. Consider the following script-local methods where in legacy script `:eval` would be mandatory. In Vim9 script, it is unnecessary: >vim9 vim9script def Pop(arg: any): void arg->popup_notification({time: 7000}) enddef b:list = [] b:list->add('1')->add('2')->Pop() # 1 and 2 (on separate lines) {a: 1, b: 2}->string()->Pop() # {'a': 1, 'b': 2} (8, 9)->typename()->Pop() # tuple 'single quoted ''string'''->Pop() # single quoted 'string' "double quoted \"string\""->Pop() # double quoted "string" (85 >> 1 == 42)->string()->Pop() # true # The following gives E260: Missing name after -> b:list->add('3')-> Pop() < In the rare case there is ambiguity between a function name and an Ex command, prepend ":" to ensure the Ex command is executed. For example, there is the `:substitute` command and `substitute()` function, the `:glob` shortened command and `glob()` function, and so on. Consequently, when the ":" is not present the "(" is inferred by Vim to be the left parenthesis before a function's arguments, not a |pattern-delimiter|. So, prepending a colon will ensure the command is executed with "(" as the delimiter. For example: >vim9 vim9script # Synonymous with ":glob/delimiter)" (and prints these lines) :glob(delimiter) # Literally calls the "glob()" function (and gives E121/E116) glob(delimiter) < If an expression starts with "!" it is interpreted as a shell command, not negation of a condition. So, this is interpreted as a shell command: >vim9 vim9cmd !(900 == v:version) < Put the expression in parentheses to use the "!" for negation: >vim9 vim9cmd (!(900 == v:version))->string()->popup_notification({}) < Note that while variables need to be defined before they can be used, functions may be called before being defined - |vim9-function-defined-later|. This is required to allow for cyclic dependencies between functions. It is slightly less efficient, since the function has to be looked up by name. Also, a typographical error in the function name will only be found when the function is called. Omitting function() ~ A user defined function can be used as a function reference in an expression without `function()`, though the function must already be defined. Argument types and the return type will then be checked. An example, demonstrating that `function()` is optional: >vim9 vim9script def IsASCII(c: string): string return $"{c} is{char2nr(c) > 127 ? ' not' : ''} an ASCII character" enddef const ASCII: func(string): string = IsASCII const F_ASCII: func(string): string = function(IsASCII) popup_notification(['K'->ASCII(), '§'->F_ASCII()], {time: 7000}) < In the script-local scope, as above, both direct assignment and using `function()` require a function to be defined already when used in a function reference. Inside a `:def` function, both direct assignment and `function()` are allowed as forward references because they are evaluated at runtime. For example: >vim9 vim9script # IsASCII forward reference def ASCII(arg: string): string var Forward_IsASCII: func(string): string = IsASCII return Forward_IsASCII(arg) enddef # function(IsASCII) forward reference def Func_ASCII(arg: string): string var Forward_funcIsASCII: func(string): string = function(IsASCII) return Forward_funcIsASCII(arg) enddef # The forward-referenced function from the two functions above def IsASCII(c: string): string return $"{c} is{char2nr(c) > 127 ? ' not' : ''} an ASCII character" enddef popup_notification(['K'->ASCII(), '§'->Func_ASCII()], {time: 7000}) < Lambda using => instead of -> ~ *vim9-lambda* In legacy Vim script there can be confusion between using "->" for method calling/chaining and for a |lambda|. Also, when a "{" is found the parser needs to figure out whether it is the start of a lambda or a dictionary, which is more complicated in Vim9 script because of the use of argument types. To avoid these problems, Vim9 script uses a different syntax for a lambda, similar to JavaScript, which in its simplest form is: > (args) => expr1 < This syntax produces a func type (|vim9-func-type|) with args of "any" type, and return type "any". Examples: >vim9 vim9script # Vim9 lambda as expr2 of filter() echo [8, -2, 9]->filter((_, val) => val > 0) # [8, 9] # Vim9 lambda as a func type var Increment = (n) => n + 1 echo Increment(8) # 9 echo Increment->typename() # func(any): any < A Vim9 script lambda can have its arguments and/or its return value strictly typed. For example, using the filtering example, these all echo [8, 9]: >vim9 vim9script echo [8, -2, 9]->filter((_, val: number) => val > 0) echo [8, -2, 9]->filter((_, val): bool => val > 0) echo [8, -2, 9]->filter((_, val: number): bool => val > 0) < When used as a func type in a |Funcref| variable, fourteen valid forms are possible. They are demonstrated in this example: >vim9 vim9script const I01 = (n) => n + 1 const I02 = (n): number => n + 1 const I03 = (n: number) => n + 1 const I04 = (n: number): number => n + 1 const I05: func = (n) => n + 1 const I06: func = (n: number) => n + 1 const I07: func = (n): number => n + 1 const I08: func = (n: number): number => n + 1 const I09: func: number = (n: number) => n + 1 const I10: func: number = (n): number => n + 1 const I11: func: number = (n: number): number => n + 1 const I12: func(number): number = (n): number => n + 1 const I13: func(number): number = (n: number) => n + 1 const I14: func(number): number = (n: number): number => n + 1 echo 0->I01()->I02()->I03()->I04()->I05()->I06()->I07()->I08() ->I09()->I10()->I11()->I12()->I13()->I14() # 14 < Notes: 1. Return types use the most specific type from either the variable's declaration or the lambda's return type (i.e., if ": {type}" appears in either, that will be the lambda's return type). Further, the variable's declaration cannot mismatch - it must be either the lambda's explicit or inferred return type, be "any", or be omitted. If the lambda's return type is not declared, it may be inferred from the lambda's expression (e.g., I03 inferred as "number"). 2. Arguments' types are determined from the lambda's parameter declaration (not from the variable's type declaration, if specified). So, the `typename()` of I02, I07, I10, and I12 is "func(any): number". Those forms should be avoided because, although they appear to accept "any" type arguments they don't (and consequently type mismatches can easily occur). 3. The following are examples of invalid lambdas giving |E1012|. They are invalid because either (a and b) the variable declaration is for a number return type, but the lambda's return type is "any", or (c) because the form "func({type}) =" is always invalid. >vim9 vim9cmd var a: func: number = (n) => n + 1 # E1012: ...; expected func(...): number but got func(any): any vim9cmd var b: func(number): number = (n) => n + 1 # E1012: ...; expected func(number): number but got func(any): any vim9cmd var c: func(number) = (n) => n + 1 # E1012: ...; expected func(number) but got func(any): any < The "Increment" lambda, shown in the first example, with `func` declared and the lambda's argument type and return type specified (like I08 in the example above), is: >vim9 vim9script var Increment: func = (n: number): number => n + 1 echo Increment(0) # 1 echo Increment->typename() # func(number): number < Note: Specifying the func type explicitly may appear redundant, though it does make it clearer up front that the variable is a func and, for reasons outlined above, specifying a lambda's return type and arguments' types is prudent. It is also more performant at runtime because "any" type checking is not required (which can be verified using |:disassemble|). Many of the examples in this help file use that form. *E1157* Although specifying a lambda's return type is not mandatory, including the colon means the return type must be specified: >vim9 vim9script var Minimal = (n) => n / 2 var Missing = (n): => n / 2 # E1157: Missing return type < No line break is allowed in the arguments of a lambda up to and including the "=>" (so that Vim can tell the difference between an expression in parentheses and lambda arguments). This is okay: >vim9 vim9script var list: list = [1, -2, 2, -3, -1, 3] filter(list, (_, val): bool => val > 0) echowindow list < This would not work (|E121| and |E116|): > filter(list, (ind, val): bool => val > 0) And this would not work (|E121| and |E116|): > filter(list, (ind, val): bool => val > 0) Nor would this (|E1157|): > filter(list, (ind, val): bool => val > 0) However, you can use a backslash to concatenate the lines before parsing. This script also shows the lambda's "val" parameter typed: >vim9 vim9script var list: list = [1, -2, 2, -3, -1, 3] filter(list, \ (_, \ val: number): \ bool \ => val > 0) echowindow list < *E1172* Default values are not allowed in a lambda: >vim9 vim9script var F_1172 = (n = 1) => n + 1 # E1172: Cannot use default values in… < *vim9-lambda-arguments* In legacy Vim script, a lambda could be called with any number of extra arguments and there was no way to warn for not using them. In Vim9 script the number of arguments must match. If you want to accept either any arguments or any additional arguments, use "..._", which enables |vim9-variable-arguments|. For example: >vim9 vim9script b:fruits = ['apple', 'apricot', 'avocado'] def Complete(..._): list const K: string = getcmdline()[: getcmdpos() - 2]->matchstr('\S*$') return b:fruits->filter((_, val) => val =~ K) enddef var fruit = input('> ', '', $"customlist,{Complete->string()}") # (e.g., entering p will present apple and apricot) echowindow $"Your choice was {fruit}" < Note: Without "..._", the function will fail. The {completion} argument of |input()| has three list items (ArgLead, CmdLine, and CursorPos). None are required to build the output list, so it is preferable to use "..._", though it works with "...l: list" too). See |:command-completion-custom|. *inline-function* A |lambda| can contain statements in a {} block. The following example reports on three "local to buffer" options: >vim9 vim9script var Get_bv: func = (...args: list): dict => { var opts: dict for arg in args opts[arg] = getbufvar(bufname(), $'&{arg}') endfor return opts } echowindow Get_bv('modifiable', 'tabstop', 'textwidth') < This is also useful for a |Channel|, |Job|, or |timer|. This is a timer example: >vim9 vim9script echowindow "Handler calling..." var count: number var timer: number = timer_start(700, (_): void => { count += 1 echowindow $'Handler called {count}' }, {repeat: 3}) < Note: In this example, |timer_start()| requires {callback}, the function to call, as its second parameter. When the timer triggers, Vim calls the callback function, passing the timer ID to it as a mandatory argument. The "(_)" syntax in the lambda enables passing that ID without needing explicitly either to name it or to reference it - see |vim9-ignored-argument|. The ending "}" of the block must be at the start of a line, excluding leading space or tab characters. It can be followed by other characters too. No command can follow the "{", though a comment can be used there. These points are shown in this example: >vim9 vim9script var numbers: list = [1, 2, 3, 4, 5] var Square: func = (ln: list): list => ln ->mapnew((_, val) => { # Comment is okay after the { of the block return val * val }) # The } of the block starting a new line (excl. white space) echowindow Square(numbers) < *E1171* Omitting the closing "}" of an inline-function's code block gives E1171: >vim9 vim9script var F_1171 = (): bool => { return false # E1171: missing } after inline function < *command-block* A block can also be used for defining a user command. Inside the block, Vim9 script syntax applies. This example uses a heredoc (see |:let-heredoc|): >vim9 vim9script command MyHeredoc { var someVar: list =<< trim eval END Life, the universe, and everything {6 * 7} END echowindow someVar } MyHeredoc < Note: "eval" is required after the "=<<" so that "{6 * 7}" is evaluated and not treated as a |literal-string|. This is different to |vim9-omitting-:eval|, even though the command block is Vim9 script. If the statements include a dictionary, the dictionary's closing bracket must not be written at the start of a line, otherwise it will be parsed as the end of the block. So, this does not work (the last line gives |E1128|), because the penultimate "}" is recognized as the end of the block: >vim9 command FailingNewCommand { g:mydict = { 'k1': 'v1', 'k2': 'v2' } } < To avoid this, place the dictionary's "}" after the last item: >vim9 vim9script command WorkingNewCommand { g:mydict = { 'k1': 'v1', 'k2': 'v2' } g:mydict->keys()->popup_notification({time: 4000}) } WorkingNewCommand < Rationale: The "}" cannot be after a command because it would require parsing the commands to find it. For consistency with that, no command can follow the "{". Consequently, this means using "() => { command }" does not work and, similarly, a line break (with optional leading spaces/tabs) is always required before the "}" ending the command block too. *E1026* Omitting the closing "}" of a code block gives E1026 ("Missing }"): >vim9 vim9script command C1026 { < *vim9-curly* To avoid the "{" of a dictionary being recognized as a statement block, wrap the dictionary in parentheses: >vim9 vim9script var AgeDict: func = (arg: number): dict => ({'age': arg}) echo 42->AgeDict() < Similarly, wrap a dictionary in parentheses to avoid confusion with the start of a command block. For example, if a dictionary's opening curly bracket is followed by a newline, wrap the dictionary in parentheses to avoid it being interpreted as a command block: >vim9 vim9script command -nargs=+ PopDict { var [key, val] = split() ({ [key]: val}) ->string()->popup_notification({time: 5000}) } PopDict one tahi < Note: The dictionary's "}" cannot be on a separate line, even when within parentheses. Also, the dictionary's key must be in square brackets to be evaluated as an expression - see |vim9-literal-dict|. Automatic line continuation ~ *vim9-line-continuation* In many cases it is obvious that an expression continues on the next line. In such cases, there is no need in Vim9 script to prefix the line with a backslash, which is required in legacy Vim script (see |line-continuation|) when a list, dictionary, tuple, or function call spans multiple lines. The following example illustrates all four: >vim9 vim9script var mylist: list = [ 1, 2, ] var mydict: dict = { 1: 1, 2: 2, } var mytuple: tuple = ( 1, 2, ) var MyDef: func = (...l: list): list => l echo MyDef(mylist, mydict, mytuple) # [[1, 2], {'1': 1, '2': 2}, (1, 2)] < For binary and ternary operators in expressions not within in a list, dictionary, or tuple, a line break is possible either before or after the operator. For example: >vim9 vim9script var text: string = 'V' .. 'i' .. 'm' var version: number = 9 * 100 + 2 var latest: string = v:version == 902 ? 'current' : 'out-of-date' echo (text, version, latest) # ('Vim', 902, 'current') < For a method call using "->", a line break is allowed before it. Likewise, for a member using a dot. Both are illustrated in this interactive example, which prompts for a min:sec pace and returns the total seconds and minutes and seconds for a 5km run/walk: >vim9 vim9script def Run5(ms: string): dict const M: number = ms ->split('[:.]')[0] ->str2nr() const S: number = ms ->split('[:.]')[1] ->str2nr() var secs: number = (M * 5 * 60) + S * 5 var m_s: string = (secs / 60) .. ':' .. printf('%02d', (secs % 60)) return {seconds: secs, minutes_seconds: m_s} enddef var result: dict = input('Pace of min:sec / km: ') ->Run5() echo ' is a 5km completed in (seconds, mins:secs):' echo (result .seconds, result .minutes_seconds) < For commands that have an argument that is a list of commands, a | character (see |:bar|) at the start of the line indicates line continuation: >vim9 vim9script command! ShowFileLine if !empty(bufname()) | echo $'File: {bufname()}' | echo $'Line: {line(".")}' | endif ShowFileLine < Note: Consequently, a heredoc's first line usually cannot start with a bar: >vim9 vim9script # E488: Trailing characters: | this doesn't work var lines =<< trim END | this doesn't work END < Either use an empty line at the start or do not use heredoc. Alternatively, ensure the "C" flag is temporarily in 'cpoptions': >vim9 vim9script const CPO: string = &cpoptions execute CPO->match('C') == -1 ? 'set cpoptions+=C' : '' var lines =<< trim END | this works END echo lines[0] &cpoptions = $'{CPO}' < If the heredoc is inside a function 'cpoptions' must be set before `:def` and restored after the `:enddef`. *E1097* A continued, incomplete line will give E1097: >vim9 vim9script def F1097(): void var x = enddef defcompile # E1097: Line incomplete < In places where line continuation with a backslash is still needed, such as splitting up a long Ex command, comments can start with '#\ ' (like '"\ ' in legacy Vim script): >vim9 vim9script syntax region IncSearch \ oneline #\ Sourcing this script applies the IncSearch highlight group #\ to the text "Ex command" in this buffer. \ start='Ex ' \ end='command' < This is also needed when line continuation is used without a backslash and a line starts with a bar. For example: >vim9 vim9script command! BufferWords echo $'Buffer name: {bufname()}' #\ Word count of the buffer | echo $'Word count: {wordcount().words}' BufferWords < *E1050* To make it possible for an operator at the start of a line to be recognized, a colon must come before a range. This example will add "start" and "print" (Note this involves shadowing the `:print` command): >vim9 vim9script var print: number = 1 # The following two lines are the same as declaring on one line # var start: number = 1 + print var start: number = 1 + print echo start < Whereas, this will assign "start" and print the second line of the script: >vim9 vim9script var start: number = 1 :+ print < And omitting a colon in this script gives E1050 because, unlike the initial example, "print" is not a variable: >vim9 vim9script var start: number + print # E1050: Colon required before a range: + print < After the range, an Ex command must follow. Without the colon you can call a function without `:call`, but after a range you do need it: >vim9 vim9script const PRINT_W_DIVIDERS: func = (): void => { echohl Statement :print echo "_"->repeat(70) echohl None } # With no range, call the function without `call`; when sourced, this # will print only the line with 'vim9script' preceded by a divider PRINT_W_DIVIDERS() # With the range, :call is required; when sourced, this prints lines # from 'const...' to the closing '}', separated by dividers :+,+6call PRINT_W_DIVIDERS() < However, the colon is not required for the |+cmd| argument. For example: >vim9 vim9script # Opens a new split of this help buffer and applies IncSearch # highlight group to instances of 'MATCHME'. split +/MATCHME match IncSearch _MATCHME_ < It is also possible to split a function's arguments over multiple lines. For example: >vim9 vim9script def SubBlankHyphen( text: string, separator: string = ' ' ): string return text->substitute('[[:blank:]]', separator, 'g') enddef echo 'A multiple lines of arguments example'->SubBlankHyphen() < Since a continuation line cannot be easily recognized, parsing of commands is stricter. In legacy Vim script, an error could result in unintended interpretation of continuation lines. For example, consider the following, working script: >vim9 vim9script def Msg(..._): void popup_notification("Job finished successfully!", {time: 1500}) enddef var myjob = job_start([&shell, &shellcmdflag, 'date'], { exit_cb: Msg}) < However, if there is an error in the command, like in the script below, Vim9 script will give errors. >vim9 vim9script var myjob = job_start([&shell, INVALID_LIST_ITEM_HERE, 'date'], { exit_cb: Msg}) # Gives E121, E116 and the script stops executing < The equivalent legacy Vim script, below, fails on the `:let` command. However, then it continues and interprets "exit" as the `:exit` command with argument "_cb: Msg})", causing Vim to save changes to a file literally with that name and exits: > > " *** DO NOT SOURCE this legacy Vim script *** " If sourced, this will write the file '_cb: Msg})' and exit! " let myjob = job_start([&shell, INVALID_ITEM_HERE, 'date'], { exit_cb: Msg}) < *E1144* To prevent unintended consequences, like the one above, Vim9 script requires white space between most command names and their arguments. (Note: Delimited commands, like `:global` and `:substitute`, are exceptions.) For example: >vim9 vim9script exit_abc # E1144: Command "exit" is not followed by white space: exit_abc < However, the argument of a command that is a command itself won't be recognized consistently. For example, after "windo echo {expr}" a line break inside the expression will only apply to the current window, not to subsequent windows: >vim9 vim9script windo echo 'hi' ->toupper() # 'HI' (current window) and 'hi' (for others) < So, in instances like this, the "\" continuation character must still be used: >vim9 vim9script windo echo 'hi' \ ->toupper() # 'HI' (for every window) < Note: This could have serious consequences if, for example, the command was "windo execute ':global/something/'" and the continuation line was ".. d". The lines with "something" would be deleted only in the current window and the other windows would have only `:print` (i.e., default ":p") performed on their "something" lines. Other line continuation considerations: - `:enddef` cannot be used at the start of a continuation line. It ends the current `:def` function. See |E1057|. - No line break is allowed in the LHS of an assignment. Specifically, when unpacking a list (|:let-unpack|), this is okay: >vim9 vim9script const UNPACK: func = (a: string, b: string): list => [a, b] var [v1, v2] = UNPACK('all', 'good') echo $'{v1} {v2}' < whereas this would not work - it would give |E475|: > var [v1, v2] = UNPACK('all', 'good') < - No line break is allowed in between arguments of an `:echo`, `:execute` and similar commands. This is okay: >vim9 vim9script echo [1, 2] [3, 4] < whereas this does not work (i.e., "[3, 4]" is not echoed): >vim9 vim9script echo [1, 2] [3, 4] < - In some cases it is difficult for Vim to parse a command, especially when commands are used as an argument to another command, such as `:windo`, `:command` or `:autocmd`. In those cases the line continuation with a backslash must be used. For example: > command! Foo call Bar('x', { \ 'key': 'value', \ }) autocmd BufWritePre * call Bar('x', { \ 'key': 'value', \ }) < See also the "windo echo" example and note, above. White space ~ *vim9-white-space* Vim9 script enforces proper use of white space. There must be white space before and after the "=" of variable assignment, for example: >vim9 vim9script var num = 234 < White space is required: *E1004* - Before and after the "=" in variable declaration: >vim9 vim9script var num=234 # E1004: White space required before and after '=' at… # Similarly, these would also give E1004: var num= 234 var num =234 < - Around most operators. So, the first example here works whereas the second gives E1004: >vim9 vim9cmd echo 'Yes' .. '!' # Yes! vim9cmd echo 'F'..'ail' # E1004: White space required before … < - In a sublist (list slice) around the ":", except at the start and end: >vim9 vim9script var mylist: list = [7, 8, 9] echo mylist[:] # [7, 8, 9] echo mylist[1 : 2] # [8, 9] echo mylist[: 1] # [7, 8] echo mylist[2 :] # [9] echo mylist[1:2] # E1004: White space required before and after ":"… < *E1069* - After a variable name and its ":" (preceding a type declaration): >vim9 vim9script var okay_list: list = ['Is', 'good'] var fail_list:list = ['Is', 'a', 'fail'] # E1069: White space … < - Before the '#' starting a comment. If it isn't present, errors such as |E121| or |E488| are given: >vim9 vim9cmd echo 'No'# E121: Undefined variable: # vim9cmd var f: number = 99# E488: Trailing characters: … < White space is not allowed: *E1068* - Before the comma separating dictionary key-value pairs or list items (though it is allowed with tuples). Examples: >vim9 vim9cmd echo (1 , 2) # (1, 2) [Note: Vim normalizes the tuple] vim9cmd echo {1: 1 , 2: 2} # E1068: No white space allowed before ',' vim9cmd echo [1 , 2] # E1068: No white space allowed before ',' < - Before the comma separating function arguments: >vim9 vim9script def F1068(arg: string , arg2: bool): void # E1068: No white space allowed before ',': , arg2: bool): void enddef < - Before either the "<" or "(" in the declaration of a generic function: >vim9 vim9script def F1068 (): T # E1068: No white space allowed before '(': (): T enddef F1068() < *E1074* - After the '.' of an imported item. In this example, a temporary Vim9 script is written, then imported. The script's exported "okay" variable is echoed successfully, but the space after the '.' of the second "Imp" item gives E1074: >vim9 vim9script var tmp: string = $'{tempname()}.vim'->substitute('\\', '/', 'g') var temp_lines: list = ['vim9script', 'export var okay: bool = true', 'export var err: bool'] temp_lines->writefile(tmp) import tmp as Imp echo Imp.okay # true echo Imp. err # E1074: No white space allowed after dot < - Between a function name and the "(", though it is allowed before any argument and after the last argument: >vim9 vim9script def MyN(...arg: list): void echo arg enddef MyN(1) # [1] MyN( 2) # [2] MyN(3 ) # [3] MyN( 4, 5, 6 ) # [4, 5, 6] MyN (7, 8, 9) # E492: Not an editor command < Note: The following are also not allowed, and give |E492|: > MyN \ (7, 8, 9) MyN (7, 8, 9) < *E1202* - After the '.' when accessing object properties, methods, or enum members. An enum method example: >vim9 vim9script enum Metal Au((79, 'Gold')), Hg((80, 'Mercury')) var data: tuple def Get_name(): string return this.data[1] enddef endenum echo Metal.Au.Get_name() # Gold echo Metal.Hg. Get_name() # E1202: No white space allowed after '.':… < *E1205* - In a `:set` command between the option name and a following "&", "!", "<", "=", "+=", "-=" or "^=". For example: >vim9 vim9script # This is okay set tabstop=8 echo &tabstop # This is E1205: No white space allowed between option and: =8 set tabstop =8 < - In a :set command between the option name and a following ':', which gives |E518|. For example: >vim9 vim9script # This is okay set tabstop:8 echo &tabstop # This is E518: Unknown option :8 set tabstop :8 < No curly braces expansion ~ *vim9-no-curly-braces-expansion* Dynamic variable name construction using curly braces (|curly-braces-names|) does not work in Vim9 script scopes. This example shows two curly braces names expanding and working to form script level variable names in a legacy Vim script `:function` but failing in a `:def` function: >vim9 vim9script var [O, O3] = ['oxygen', 'ozone'] function Al(arg, n = null_string) abort return s:{a:arg}{a:n} endfunction def Al9(arg: string, n: any = null_string): string return {arg}{n} enddef echo Al('O', 3) # ozone echo Al9('O', 3) # E720: Missing colon in Dictionary: }{n} < Similarly, |curly-braces-function-names| are only possible in legacy Vim script scopes: >vim9 vim9script var low_line: string = '_' function F_curly() echo 'A curly-braces-function-name: okay in legacy Vim script scope' endfunction legacy call s:F{s:low_line}curly() F{low_line}curly() # E1144: Command "F" is not followed by white… < Command modifiers may not always be ignored and give an error ~ In some scenarios, using a command modifier for a command that does not use it may give an error. However, some modifiers do not give an error (just like how they do not error in legacy Vim script). For example, in this script the meaningless |:vertical|, |:keepmarks|, and |:hide| modifiers are ignored: >vim9 vim9script vertical if 1 == 1 keepmarks echo 'Starting...' try echo ERROR catch hide echo 'Caught!' endtry endif < *E1176* However, if a modifier is applied to certain control flow commands, E1176 is given. An example is prepending |:silent| to |:endif|: >vim9 vim9script if 1 echo "Hi!" silent endif # E1176: Misplaced command modifier < Note: When lines 2 to 4 only of this script are sourced, you can see it does not give E1176 (because then the script is executed in a legacy Vim script context). Similarly, adding modifiers to any of |:try|, |:endtry|, |:for|, |:endfor|, |:while|, |:endwhile|, |:catch|, or |:finally| may result in an E1176 error, though it depends on the redundant modifier used. For example, adding the |:silent| modifier to |:for| is ignored whereas adding |:keepmarks| to |:endfor| is an error. (Note the behavior of `:silent` is intentional. It works like that so that error messages are suppressed when Vim does not support the |+eval| feature.) *E1082* Also, using a command modifier without a following command gives E1082: >vim9 vim9script silent # E1082: Command modifier without command < Dictionary literals ~ *vim9-literal-dict* Traditionally Vim has supported dictionary literals with a {} syntax: > let dict = {'key': value} < Later it became clear that using a simple text key is very common, thus literal dictionaries were introduced in a backwards compatible way: > let dict = #{key: value} < However, this #{} syntax is unlike any existing language. As it turns out, using a literal key is much more common than using an expression, and considering that JavaScript uses this syntax, using the {} form for dictionary literals is considered a much more useful syntax. In Vim9 script the {} form uses literal keys: > var dict = {key: value} < For example: >vim9 vim9script var dict = {key: 9} echo dict # {'key': 9} < Note: Vim normalizes the key, adding the ' characters. Dictionary keys are always strings. Literal keys work using alphanumeric characters, underscore, and dash. If you want to use a character other than those, or even use an expression, you may: - Use a single or double quoted string, or - Use `extend()` and the literal key syntax, or - For an expression, enclose the key in [] (like in a JavaScript computed property). All three are illustrated in this example: >vim9 vim9script var dict: dict dict["key\twith\ttabs"] = true # double quoted key dict->extend({[40.9 + 1.1]: true}) # evaluated expression key dict['¡non–ASCII! w/ spaces'] = true # single quoted key for k in dict->keys() echo [k, dict[k]] endfor < The key type can be string, number, bool, or float, though all keys are stored as strings. Trying to use other types will give an error. For example: >vim9 vim9script var dict: dict dict[9] = true # number key dict[true] = true # bool key dict[9.2] = true # float key echo dict # {'true': true, '9.2': true, '9': true} dict[(9, 2)] = false # E1522: Using a Tuple as a String < Without using [], the value is literal so retains any leading zeros. An expression given with [] is evaluated and then converted to a string. Expression evaluation means any leading zeros are omitted. For example: >vim9 vim9script var dict = {09: '09 is literal "09"', [09]: '[09] becomes "9"'} echo dict['09'] # '09 is literal "09"' echo dict['9'] # '[09] becomes "9"' < *E1139* If the key within [] is invalid, errors such as E1139 may be given, for example: >vim9 vim9script var E1139 = {[0😢9]: 2} # E1139: Missing matching bracket after dict … < *E1014* An invalid key gives E1014: >vim9 vim9script # This tries to use an unquoted control code character, U+0007 (ALERT) var E1014: dict = {: 'E1014'} # E1014: Invalid key: ^G < A float key must appear inside [], either in a dictionary literal or in a subscript assignment. The '.' of a float outside of either context is an invalid Vim9 script dictionary literal key: >vim9 vim9script var dict: dict = {[.09]: 'ok'} dict[0.10] = 'ok' echo dict # {'0.09': 'ok', '0.1': 'ok'} try dict->extend({0.11: 'fail!'}) catch echo v:exception # E720: Missing colon in Dictionary: .11: 'fail!' endtry < *E1127* If the name after a '.' is omitted, E1127 is given: >vim9 vim9script def F1127(): void var d = {x: 0} echo d. enddef F1127() # E1127: Missing name after dot < No :xit, :t, :k, :Print, :append, :change, :insert, or :open ~ Some commands are too easily confused with local variable names, though they have alternative commands that do the same thing: Not allowed Instead use ~ `:k` |:mark| `:Print` |:print| `:t` |:copy| `:xit` |:exit| Note: Shortened forms like `:x` also are not allowed. *E1100* For example, using "mark x" in the following script would work, whereas using "k x" gives E1100: >vim9 vim9script :+2 k x # E1100: Command not supported in Vim9 script (missing :var?): k x < Some commands are not available at all in Vim9 script. These will give E1100 if they are used, including their shortened forms, like `:a`, `:o`, and `:ch`: `:append` `:change` `:insert` `:open` See also |vim9-invalid-Ex-commands|. Comparators ~ *vim9-comparators* The 'ignorecase' option is not used for string comparators. Consequently, "=~" and "=~#" work identically (i.e., comparisons are case sensitive): >vim9 vim9script var ic: bool = &ignorecase set ignorecase # Both of these echo 'false' because 'ignorecase' isn't used echo 'a' =~# 'A' echo 'a' =~ 'A' # Case sensitive '=~#' echoes 0. Case insensitive '=~' echoes 1 legacy echo 'a' =~# 'A' legacy echo 'a' =~ 'A' # Revert 'ignorecase' to its setting before running this script &ignorecase = ic < The expression "is" (|expr-is|), when used on strings, returns false (except where the strings being compared are either explicitly null or uninitialized). Similarly, the expression "isnot" (|expr-isnot|) returns true. This is because, whereas in a legacy Vim script scope strings' content is compared, in a |Vim9| script scope identity is compared. Consequently, because strings are copied when used, two strings are not the same, though this might change someday if strings are not copied but reference counted. For example: >vim9 vim9script var str: string = '' echo str is str # false legacy echo s:str is s:str | # 1 var x: string var y: string = null_string echo x is y # true < For boolean, number, and float types, in legacy Vim script "is" and "isnot" work like string comparison. In Vim9 script, except when comparing a number with a float, "is" will give either |E1037| or |E1072|. For example: >vim vim9cmd var [boo: bool, num: number, flo: float] = [true, 9, 9.2] legacy echo s:boo is v:true | " 1 legacy echo s:num is 9 | " 1 legacy echo s:flo is 9.2 | " 1 legacy echo s:boo is 9 | " 0 legacy echo s:boo is 9.2 | " 0 legacy echo s:num is 9.2 | " 0 vim9cmd echo boo is true # E1037: Cannot use "is" with bool vim9cmd echo num is 9 # E1037: Cannot use "is" with number vim9cmd echo flo is 9.2 # E1037: Cannot use "is" with float vim9cmd echo boo is 9 # E1072: Cannot compare bool with number vim9cmd echo boo is 9.2 # E1072: Cannot compare bool with float vim9cmd echo num is 9.2 # false < Similarly, "is" and "isnot" may not be used to compare job and channel types. This example shows job comparison working with "is" in a legacy Vim script scope but giving |E1072| in a Vim9 script scope: >vim9 vim9script var job1: job var job2: job = job1 legacy echo s:job1 is s:job2 | # 1 echo job1 is job2 # E1072: Cannot compare job with job < Comparing container types list, dict, tuple, and blob using "is" and "isnot" behaves the same in Vim9 script as it does in legacy Vim script. The comparison checks instances, not content. Because they behave similarly, only a Vim9 script list example is provided in this example, with legacy Vim script scope comparisons to show the same behavior: >vim9 vim9script var l1: list var l2: list = l1 echo l1 is l2 # true (same instance) legacy echo s:l1 is s:l2 | # 1 echo l1 is [] # false (different instance) legacy echo s:l1 is [] | # 0 echo l1 is null_list # false (different instance) < Comparing a `Funcref` variable is almost the same as comparing container variables, though an uninitialized `Funcref` variable compared to Vim9 script's `null_function` behaves differently: >vim9 vim9script var F1: func var F2: func = F1 echo F1 is F2 # true (same uninitialized instance) echo F1 is null_function # true < In Vim9 script, comparing class objects behaves similarly: >vim9 vim9script class C endclass # Uninitialized class objects var O1: C var O2: C echo O1 is O2 # true (same uninitialized class object) echo O1 is null_object # true # Initialized class objects var O4: C = C.new() var O5: C = O4 var O6: C = C.new() echo O4 is O5 # true (same initialized class object) echo O5 is O6 # false (different class objects) < Note: Classes themselves cannot be compared: >vim9 vim9script class C endclass echo C is null_class # E1401: Class "C" cannot be used as a value < Comparison of enum objects differs from class objects. Each enumvalue is a singleton, so variables assigned the same enumvalue always reference the identical instance. Even when a mutable instance variable of an enum value is modified, the change affects all references to that enumvalue: >vim9 vim9script enum Switch On(['active', true]), Off(['inactive', false]) final state: list endenum var on1: Switch = Switch.On var on2: Switch = Switch.On on2.state[0] = 'engaged' # The change affects on1 and on2 because they're the same enumvalue echo on1 is on2 # true # Uninitialized enumvalue (and there is no null_enumvalue): var uninitialized: Switch echo uninitialized is null_object # true < In summary, in relation to the "is" and "isnot" comparison operators: - Vim9 script introduces stricter rules than legacy Vim script and: - Behaves differently for strings, - Behaves the same for lists, dictionaries, tuples, and blobs, - Does not allow comparison of booleans, numbers, floats, jobs, and channels (except for comparing a number with a float), and - Behaves the same for function references (though Vim9 script's `null_function` behaves differently). - Entirely exclusive to Vim9 script: - Comparing class objects is similar to comparing function references, and - For enum objects, "is" and "isnot" always compare the same instance of a given enumvalue. Abort after error ~ In legacy Vim script, when an error is encountered, Vim continues to execute the lines following the error. This can lead to a long sequence of errors and need to type CTRL-C to stop it. For example, this script produces two |E121| errors: >vim " legacy Vim script let x = does_not_exist let y = does_not_exist_too < However, in Vim9 script, execution of commands stops at the first error: >vim9 vim9script var x = does_not_exist # E121: Undefined variable: does_not_exist # Execution stops and the following line is not executed var y = does_not_exist_too < For loop ~ The loop variable must not be declared yet: >vim9 vim9script var it: list for it in [1, 2, 3] # E1041: Redefining script item: "it" < But it is possible to use a prefixed variable, e.g., a buffer local variable: >vim9 vim9script b:i = [] for b:i in [1, 2, 3] echo b:i endfor < *E1254* A loop variable in a `:def` function cannot be a s: variable: >vim9 vim9script def F() for s:n in range(9) # E1254: Cannot use script variable in for loop endfor enddef defcompile < Legacy Vim script has some tricks to make a for loop over a list handle deleting items at the current or previous item. In Vim9 script, the same trick applies in a non-compiled scope. However, in a compiled Vim9 script scope, when an item is deleted the following item in the list is skipped ("iterator invalidation"), producing the same result as what you would see in Python and Ruby. The following script demonstrates the differing behaviors in non-compiled and compiled Vim9 script scopes: >vim9 vim9script echo 'Removing items from a list in a Vim9 script non-compiled scope:' # This echoes 10, then 20, 30, 40, and [] var list_one: list = [10, 20, 30, 40] for n in list_one echo n list_one->remove(index(list_one, n)) endfor echo list_one echo 'Removing items from a list in a Vim9 script compiled scope:' # This echoes 10, then 30, and the list [20, 40] # This happens because when 10 is removed, 20 moves to index 0, but # the iterator moves to index 1, which is now 30! var list_two: list = [10, 20, 30, 40] var Remove_items: func = (): void => { for n in list_two echo n list_two->remove(index(list_two, n)) endfor echo list_two } Remove_items() < What this example shows is usually it is better not to change a list that is iterated over. Making a copy first is often safer. When looping over a list of lists, the nested lists can be changed. The loop variable is "final" - that is, it cannot be changed but its value can be changed. For example: >vim9 vim9script var lst: list> = [[1, 2], [3, 4], [5, 6]] for subl in lst subl[0] = 9 endfor echo lst # [[9, 2], [9, 4], [9, 6]] for subl in lst subl = [9, subl[1]] # E46: Cannot change read-only variable "subl" endfor < *E1306* The depth of |:for| and |:while| loops added together, cannot exceed 10. Conditions and expressions ~ Vim9 script has stricter type checking than legacy Vim script in boolean contexts. Most operators require either a boolean, or 0/1, or a |Special| type. The falsy (|??|) and logical NOT (|expr-!|) operators use truthiness rules. – Strict Boolean Expressions ~ *vim9-boolean* In Vim9 script, the conditionals |:if|, |ternary|, |:while|, `||` (|expr-barbar|), and `&&` (|expr-&&|), require strict boolean types. This is different to legacy Vim script, which treats any non-zero number as 1 and implicitly infers a string or |Special| as a number equivalent. To illustrate, in legacy Vim script, all these conditional expressions work: >vim " legacy Vim script " These evaluate to 1: echo 1 ? 1 : 0 echo 0 || 1 echo 1 || v:false echo 1 && v:true echo v:null || 1 echo 99 ? 1 : 0 echo "99" ? 1 : 0 " These evaluate to 0: echo 0 || v:none echo 0 && 1 echo "text" ? 1 : 0 < In Vim9 script, conditional expressions (excluding `??` and `!`) have stricter |type-checking|, which means: - For numbers, only 0 (falsy) or 1 (truthy) are permitted, otherwise |E1023| is given, and - Strings are not permitted (|E1135|). >vim vim9cmd echo 1 ? 1 : 0 # 1 vim9cmd echo 0 || 1 # true vim9cmd echo 1 || false # true vim9cmd echo 1 && true # true vim9cmd echo null || 1 # true vim9cmd echo 0 || v:none # false vim9cmd echo 0 && v:true # false vim9cmd echo 9 ? 1 : 0 # E1023: Using a Number as a Bool: 9 vim9cmd echo "9" ? 1 : 0 # E1135: Using a String as a Bool: "9" vim9cmd echo "x" ? 1 : 0 # E1135: Using a String as a Bool: "x" < – Falsiness Operator ~ *vim9-falsy* For most types there is no error using `??` (the |falsy-operator|). Values are either falsy or truthy, with falsy evaluated as follows: Type Falsy when~ Number zero String empty Funcref null List empty Dictionary empty Float zero Boolean `false` (also |Special| `v:false`) None always (`v:null` and `v:none`) Job null Channel null Blob empty Class not applicable (see |E1405|) Object null Typealias not applicable (see |E1403|) Enum not applicable (see |E1421|) EnumValue null Tuple empty void always To illustrate, a script showing falsiness of all except error-giving types: >vim9 vim9script echo "Number: \t0\t\t" 0 ?? 'is falsy' echo "String: \t''\t\t" '' ?? 'is falsy' echo "Funcref:\tnull_function\t" null_function ?? 'is falsy' echo "List: \t[]\t\t" [] ?? 'is falsy' echo "Dictionary:\t{}\t\t" {} ?? 'is falsy' echo "Float: \t0.0\t\t" 0.0 ?? 'is falsy' echo "Boolean:\tfalse\t\t" false ?? 'is falsy' echo " \tv:false\t\t" v:false ?? 'is falsy' echo "None: \tv:none\t\t" v:none ?? 'is falsy' echo " \tv:null\t\t" v:null ?? 'is falsy' echo "Job: \tnull_job\t" null_job ?? 'is falsy' echo "Channel:\tnull_channel\t" null_channel ?? 'is falsy' echo "Blob: \t0z\t\t" 0z ?? 'is falsy' echo "Object: \tnull_object\t" null_object ?? 'is falsy' enum Enum endenum var null_enumval: Enum # NB: There is no inherent "null_enumvalue" echo "EnumValue:\t'null_enumval'\t" null_enumval ?? 'is falsy' echo "Tuple: \t()\t\t" () ?? 'is falsy' echo "void: \t\t\t" test_void() ?? 'is falsy' < Note: Vim9 script's falsiness is much the same as Python's (e.g., "if []:" in Python is falsy, the same as "if []" in Vim9 script. JavaScript is similar too, though it differs in its unusual truthy evaluation of an empty object/array. – Type Conversions and Exceptions ~ *vim9-!* When using the logical NOT operation, "!" (|expr-!|), for inverting, there is no error (except with a class - |E1405|, enum - |E1421|, or typealias - |E1403|) and the result is always a boolean. In this example, the falsy values are inverted and all evaluations return "true": >vim9 vim9script echo [!0, !'', !null_function, ![], !{}, !0.0, !false, !v:false, !v:none, !v:null, !null_job, !null_channel, !0z, !null_object, !(), !test_void()] < *vim9-!!* Similarly, when using "!!" to turn a value into a boolean all the evaluations return "false", as this example shows: >vim9 vim9script echo [!!0, !!'', !!null_function, !![], !!{}, !!0.0, !!false, !!v:false, !!v:none, !!v:null, !!null_job, !!null_channel, !!0z, !!null_object, !!(), !!test_void()] < Note: This is a rare instance where Vim9 script is more permissive than legacy Vim script. As the following example demonstrates, legacy Vim script gives errors when using "!" or "!!" with many types (including Funcref, List, Dictionary, Blob, Job, and Tuple): >vim " legacy Vim script: !! erroring examples let F = {x -> x} let j = job_start([&shell, &shellcmdflag, 'date'], {}) echo !!F | " E703: Using a Funcref as a Number echo !![] | " E745: Using a List as a Number echo !!{} | " E728: Using a Dictionary as a Number echo !!0z | " E974: Using a Blob as a Number echo !!j | " E910: Using a Job as a Number echo !!() | " E1520: Using a Tuple as a Number < When using ".." for string concatenation, number, float, bool and |Special| types are always converted to strings: >vim9 vim9script var mystr = 8 .. ', ' .. 9.2 .. ', ' .. true .. ' and ' .. v:none echo [mystr, mystr->typename()] < Notes: 1. Both `true` (and `v:true`, not shown) are stringified to "true" whereas legacy Vim script stringifies `v:true` to "v:true". 2. In Vim9 script '..' string concatenation handles floats consistently. Legacy Vim script doesn't, with the decimal point being interpreted as a concatenation "." after the first "." or "..". In the following legacy Vim script, 9.2 loses its decimal point: >vim let s:my8str = 8 .. ', ' .. 9.2 .. ', ' .. v:true .. ' and ' .. v:none echo s:my8str | " 8, 92, v:true and v:none < This illustrates that primitives (|v:t_number|, |v:t_float|, and |v:t_bool|), plus |Special| types may be compared directly with "==". For all other types, |string()| must be used. For example: >vim9 vim9script echo 'This is a list: ' .. [1, 2, 3]->string() # Whereas doing this gives E730: Using a List as a String: echo 'This does not work! ' .. [1, 2, 3] < Similarly, |string()| should be used for "==" comparisons, otherwise |E1072| is given. For example: >vim9 vim9script var l: list = [9, '9.2'] echo string(l) == "[9, '9.2']" # true echo l == "[9, '9.2']" # E1072: Cannot compare List with String < WARNING: Short-circuit evaluation may hide errors in boolean expressions when an OR expression can be determined to be `true` without evaluating all operands. Evaluation stops early, meaning invalid code may never execute, masking errors that would otherwise occur at runtime, including Vim9 script type-related errors. For example, a class itself cannot be used in a comparison, but here it does not give an error in the first ternary expression because "t" has already been evaluated to `true`: >vim9 vim9script var t: bool = true echo t || null_class ? true : false # true echo null_class || t ? true : false # E1405: Class "" cannot be used… < Predefined values ~ *false* *true* *null* *null_blob* *null_channel* *null_class* *null_dict* *null_function* *null_job* *null_list* *null_object* *null_partial* *null_string* Vim9 script has predefined values representing true, false, and null states. The following table lists those predefined values, along with their |type()|, |typename()|, and |string()| representations: Predefined value type() typename() string() ~ null_string |v:t_string| string '' null_function |v:t_func| func(...): unknown function() null_partial |v:t_func| func(...): unknown function('') null_list |v:t_list| list [] null_dict |v:t_dict| dict {} true |v:t_bool| bool true false |v:t_bool| bool false null |v:t_none| special null null_job |v:t_job| job no process null_channel |v:t_channel| channel channel fail null_blob |v:t_blob| blob 0z null_class |v:t_class| class class [unknown] null_object |v:t_object| object object of [unknown] null_tuple |v:t_tuple| tuple () The predefined value `true` is the same as `v:true`, `false` is the same as `v:false`, and `null` is the same as `v:null`. A "null_" value is treated the same as an empty value only in some cases. See |null-details|. The following types do not have predefined "null_" values: - Number (instead use 0, though it is not `null`) - Float (instead use 0.0, though, like the number 0, it also is not `null`) - Typealias (which cannot be used as a value; it gives |E1403|) - Enum (which cannot be used as a value; it gives |E1421|) - EnumValue (however, it can be a `null_object` - see the "Switch" example in |vim9-comparators|) The "null_" values can be useful for clearing script-local variables because they cannot be deleted with `:unlet`. For example: >vim9 vim9script var myvar: string = "not null_string" try unlet myvar catch echo v:exception # E1081: Cannot unlet myvar finally myvar = null_string echo $"'myvar' is {myvar->string()}" endtry < The values can also be useful as the default value for an argument: >vim9 vim9script def CheckMyList(l: list = null_list): string if l == null return 'No list was passed' elseif l->empty() return 'An empty list was passed' else return $"List {l->string()} was passed" endif enddef echo CheckMyList() echo CheckMyList([]) echo CheckMyList([8, 9]) < Note: This examples shows comparing the list "l" against `null`, not `null_list`. This is useful because it enables distinguishing the default value, null_list, from an empty list []. See |null-compare| and |null-anomalies| for more information testing against null. It is possible to compare `null` with any value - it does not give a type error. However, comparing `null` with a number, float or bool always results in `false`. This is different than number and float in legacy Vim script where comparing `v:null` with 0 or 0.0 returns 1. For example: >vim9 vim9script echo [0 == null, 0.0 == null] # [false, false] legacy echo [0 == v:null, 0.0 == v:null] | # [1, 1] < *vim9-false-true* When converting a boolean to a string, `false` and `true` are used. In Vim9 scripts, `v:false` is equal to `false` and `v:true` is equal to `true`. >vim9 vim9script echo $'{v:none} has no "none" equivalent, but' echo $'"v:true" is stringified to "{v:true}" in a string, and' echo 'Q: "v:false" and "false" can be used interchangeably?' echo $'A: {v:false == false}' < Note: There is no "none" for `v:none` because it has no equivalent in other languages. *vim9-string-index* Indexing a string with [idx] or taking a slice with [idx : idx] uses character indexes instead of byte indexes. Combining/composing characters are included. Example: >vim9 vim9script echo 'très'[2] # è (U+00E8) legacy echo 'très'[2] | # (Illegal byte 0xc3) < A negative index is counting from the end, "[-1]" is the last character. >vim9 vim9script echo 'fenêtre'[-4 : -1] # être legacy echo 'fenêtre'[-5 : -1] | # être (-5 because ê is two bytes) < Using the builtin function, |slice()|, can be a good choice because it uses character indexes in both legacy Vim script scopes and Vim9 script scopes: >vim9 vim9script echo 'fenêtre'->slice(-4) # être legacy echo 'fenêtre'->slice(-4) | # être < Use |strcharpart()| to count combining characters separately. The following example uses "a" (U+0061) and a combining macron (U+0304): >vim9 vim9script echo 'Ngā mihi'->strcharpart(2, 1) # a (excluding combining macron) echo 'Ngā mihi'[2] # ā (including combining macron) < If the index is out of range, an empty string is the result. >vim9 vim9script echo ['In range'[0 : 1]] # ['In'] echo ['Out of range'[19 : ]] # [''] < *E1148* Attempting to assign to or modify a string using an index gives an error. For example: >vim9 vim9script def F1148(): void b:s = 'Fails' b:s[4] = '!' # E1148: Cannot index a string enddef F1148() < Note: Other errors may be given depending on the scope and whether the variable is prefixed. For example, if the variable in this example was declared with `:var` instead of being a buffer variable, it would give |E1141| and, if the scope was script-local rather than a `:def`, it would give |E689|. In legacy Vim script, if either "++var" (|:++|) or "--var" (|:--|) are used in a character index they are ignored. In Vim9 script, they are invalid: >vim9 vim9script var int: number = 1 var str: string = 'hear' legacy echo s:str[++s:int : ] | # ear echo str[++int : ] # E15: Invalid expression: "++int : ] < Numbers starting with zero are not considered to be octal, only numbers starting with "0o" are octal: "0o744". (See |scriptversion-4|.) For example: >vim9 vim9script echo 017 # 17 (inferred decimal) legacy echo 017 | # 15 (inferred octal) echo 0o17 # 15 (explicit octal) < What to watch out for ~ *vim9-gotchas* Vim9 script was designed to be closer to contemporary programming languages, but at the same time tries to support legacy Vim commands. Some compromises had to be made. Here is a summary of what might be unexpected. Ex command ranges often need to be prefixed with a colon: - A line beginning with "%" in legacy Vim script means "all lines" (|:%|) whereas in Vim9 script it may mean modulo (|expr-%|) or give |E1050|. For example: >vim " legacy Vim script let g = 97 echo 1000 % g / 9.7 " 1000 (then prints all lines containing '9.7' to messages) < whereas: >vim9 vim9script var g = 97 echo 1000 % g / 9.7 # 3.092784 (which is 1000 % 97 / 9.7) echo 1000 :%g/9.7 # 1000 (then prints all lines containing '9.7' to messages) % g / 9.7 # E1050: Colon required before a range: % g / 9.7 < - An initial apostrophe in legacy Vim script means go to mark (|'|). In Vim9 script it's either the start of a quoted string or it gives |E115|: >vim " legacy Vim script :normal! mt " Sets mark t at the line with the comment " legacy Vim script 't " Jumps to mark t (which is at this line after sourcing this script) < whereas: >vim9 vim9script :normal! mt # Sets mark t on the line with the vim9script command 't'->popup_notification({time: 4000}) # Vim9 script method chain :'t # Jumps to mark t (which is at this line after sourcing this script) # 't by itself would be E115: Missing single quote < - In legacy Vim script, "->" shifts the prior line, which is prior to a range if it is a sourced script, right by 'shiftwidth' spaces. In Vim9 script, it is a continuation line of a chained method: >vim9 vim9script const mine: string = 'MINE' ->toupper() echo mine # MINE # In a modifiable buffer, using :-> on a line by itself would shift # the line before vim9script to the right by 'shiftwidth' spaces when # this script is sourced. < Some Ex commands can be confused with assignments in Vim9 script: >vim " legacy Vim script let let = 8 echo let | " 8 :g:let = 8 " Prints lines matching 'let = 8' to messages vim9 vim9script g:let = 9 echo g:let # 9 :g:let = 9 # E1241: Separator not supported: :let = 9 < To avoid confusion between a `:global` or `:substitute` command and an expression or assignment, a few separators cannot be used when these commands are abbreviated to a single character: '-', '.' and ':'. Examples using `:g`: >vim9 vim9cmd g-pattern-cmd # E1241: Separator not supported: -pattern-cm… vim9cmd g:pattern:cmd # E1069: White space required after ':': :cmd… vim9cmd g.pattern.cmd # E121: Undefined variable: g < Also, there cannot be a space between the command and the separator, unlike in legacy Vim script. For example: >vim g /[-:.]pattern/p | " This prints the three vim9cmd lines above < whereas in Vim9 script: >vim9 vim9cmd g /[-:.]pattern/p # E1242: No whitespace allowed before sepa… < Functions defined with `:def` compile the whole function, so any syntax or type errors will be detected during compilation, regardless of execution path. Legacy functions have no static type checking so type-related issues (if any) can only manifest for code that actually executes. For example, the following legacy Vim script `:function` returns "yes" (except in the very unlikely scenario that you source this in z/OS UNIX): >vim9 vim9script func Maybe() if !has('ebcdic') return 'yes' endif return [] + 'yes' endfunc echo Maybe() # yes < The equivalent Vim9 script gives |E1051|: >vim9 vim9script def Maybe(): any if !has('ebcdic') return 'yes' endif return [] + 'yes' # E1051: Wrong argument type for + enddef echo Maybe() < For a workaround, put the unsupported code inside a conditional with a constant expression that evaluates to false. The compiler then skips compiling the unsupported code. For example: >vim9 vim9script def Maybe(): any if has('ebcdic') return [] + 'yes' endif return 'yes' enddef echo Maybe() # yes < Another option is to split it into two functions: >vim9 vim9script if has('ebcdic') # This is not compiled at all unless on an EBCDIC system def MaybeInner(): any return [] + 'yes' enddef endif func Maybe() if has('ebcdic') return MaybeInner() else return 'yes' endif endfunc echo Maybe() # yes < Yet another option, though this time using a different scenario, is using `exists_compiled()`. Here the builtin function |luaeval()| will only be used when it's available: >vim9 vim9script def Version(): string if !exists_compiled('*luaeval') return $"Version using v:version: {v:version}" else return $"Version via Lua: {luaeval('900 + 2')}" endif enddef echo Version() < Unreachable code after `:return` gives an |E1095| error in a `:def` or Vim9 lambda function, whereas it is ignored in a legacy function: >vim9 vim9script function Legacy() return v:true let X = "Although this is unreachable, it's ignored." endfunction echo Legacy() # true var Vim9: func = (): bool => { return true const X = false # E1095: Unreachable code after :return } < *vim9-user-command* Another side effect of compiling a function is that the presence of a user command is checked at compile time. If the user command is defined later an error will result. This works: >vim9 vim9script command -nargs=1 MyCommand echomsg def Works() MyCommand 'this works' enddef Works() < This gives |E476| for "MyCommandFails" not being defined at compile time: >vim9 vim9script def Fails() command -nargs=1 MyCommandFails echomsg MyCommandFails 'this fails' enddef Fails() < A workaround is to invoke the command indirectly with `:execute`, like this: >vim9 vim9script def Works_Using_Execute() command -nargs=1 MyCommandUsingExecute echomsg execute "MyCommandUsingExecute 'this works'" enddef Works_Using_Execute() < For unrecognized commands in a conditional statement, there is no bailing out. So, if the condition evaluates to false, an invalid command will give |E171| and, if the condition evaluates to true, an invalid command will give |E476|. Examples: >vim9 vim9script def F171() if has('ebcdic') | Nah | endif enddef F171() # E171: Missing :endif < >vim9 vim9script def F476() if !has('ebcdic') | Nah | endif enddef F476() # E476: Invalid command: Nah | endif < Other differences ~ - Patterns use 'magic', unless explicitly overruled. That is, if the global option 'nomagic' is set, it is ignored. - If the option value 'edcompatible' is set, it is ignored. - If the option value 'gdefault' is set, it is ignored. *:++* *:--* - The ++ and -- commands have been added. They add and subtract one respectively. They work with number and float types. For example: >vim9 vim9script var flo: float = 41.0 ++flo echo flo # 42.0 < - Using ++var or --var in an expression is not supported yet. |E15| is given if either is used. For example: >vim9 vim9script var num: number = 43 # The following line gives E15: Invalid expression: "--num" echo --num < ============================================================================== 3. New style functions *fast-functions* *:def* :def[!] {name}([arguments])[: {return-type}] Define a new function by the name {name}. The body of the function follows in the next lines, until the matching `:enddef`. *E1073* {name} cannot be reused at the script-local level: >vim9 vim9script def F_1073() enddef def F_1073() # E1073: Name already defined: vim9 vim9script def F_1077(x): void # E1077: Missing argument type for x enddef < For the second form, because the declaration does not specify it, Vim infers the type. For both second and third forms, a default {value} applies when the caller omits it. Examples: >vim9 vim9script def SecondForm(arg = "Hi"): void echo $'2. arg is a "{arg->typename()}" type ' .. $'and the default value of arg is "{arg}"' enddef SecondForm() def ThirdForm(arg2: number = 9): void echo $'3. default value of arg2 is {arg2}' enddef ThirdForm() < *E1123* Arguments in a builtin function called in a `:def` function must have commas between arguments: >vim9 vim9script def F_1123(a: number, b: number): void echo max(a b) # E1123: Missing comma before ar... enddef F_1123(1, 2) < *E1003* *E1027* *E1096* The type of value used with `:return` must match {return-type}. When {return-type} is omitted or is "void" the function is not allowed to return anything. Examples: >vim9 vim9script def F_1003(): bool return # E1003: Missing return value enddef F_1003() < >vim9 vim9script def F_1027(): bool echo false # E1027: Missing return statement enddef F_1027() < >vim9 vim9script def F_1096(): void return false # E1096: Returning a value in a f... enddef F_1096() < *E1056* *E1059* When ": {return-type}" is specified, {return-type} cannot be omitted (leaving a hanging colon). The ": " also cannot be preceded by white space. Examples: >vim def F_1056(): # E1056: Expected a type: enddef def F_1059() : bool # E1059: No white space allowed before colon: ...  enddef < The function will be compiled into instructions when called or when either `:defcompile` or `:disassemble` is used. (For an example, see |:disassemble|.) Syntax and type errors will be produced at that time. *E1058* It is possible to nest `:def` inside another `:def` or `:function` only up to 49 levels deep. At 50 or more levels, it is a |E1058| error. *E1117* [!] is allowed only in legacy Vim script because it permits function redefinition (as with `:function`!). In Vim9 script, ! is not allowed because script-local functions cannot be deleted or redefined, though they can be removed by reloading the script. Also, nested functions cannot use ! for redefinition. Examples: >vim " Legacy Vim script :def! example def! LegacyFunc() echo "def! is allowed in a legacy Vim script" enddef call LegacyFunc() < >vim9 vim9script def F1117() def! InnerFunc() # E1117: Cannot use ! with nested :def enddef enddef F1117() < >vim9 vim9script def! F_477(): void # E477: No ! allowed enddef < >vim9 vim9script def F_1084(): void enddef delfunction! F_1084 # E1084: Cannot delete Vim9 script function F_1084 < Note: The generic error *E1028* ("Compiling :def function failed") indicates an undeterminable error during compilation. If reproducible, it may be reported at https://github.com/vim/vim/issues as it could represent a gap in Vim's error reporting. *:enddef* *E1057* *E1152* *E1173* :enddef End of a function defined with `:def`. It should be on a line by itself. Examples: >vim9 vim9script def MyFunc() echo 'Do Something' | enddef # E1057: Missing :enddef < >vim9 vim9script def F_1173() enddef echo 'X' # E1173: Text found after enddef: echo 'X' < >vim9 vim9script def F_1152() function X() enddef # E1152: Mismatched enddef enddef < You may also find this wiki useful. It was written by an early adopter of Vim9 script: https://github.com/lacygoill/wiki/blob/master/vim/vim9.md *vim9-s:var* When referencing a script-local variable, the context determines whether using the "s:" prefix is either mandatory, optional, or gives |E1268|. The context factors are whether the script version is Vim9 script or legacy Vim script and whether the reference is at the script-local level, within a `:def` function, or within a `:function`. The three rules are: 1. In a `:function`, "s:" is always mandatory. This is regardless of the script type or the function's parent context (such as nested within another function). Similarly, "s:" is also mandatory in the script-local scope of a legacy Vim script. 2. In a Vim9 script, "s:" always gives |E1268| when used in a `:def` function, regardless of the function's parent context. Similarly, it gives E1268 in the script-local scope of a Vim9 script. 3. In a legacy Vim script, "s:" is optional in a `:def` function, regardless of the function's parent context. A `:def` function cannot create a script-local variable, assigning to one that does not exist when the function is compiled gives |E1089|. The following three scripts demonstrate these rules: >vim " 1. In a :function, "s:" is always mandatory. It is also mandatory " in a legacy Vim script's script-local scope let s:MyVar = v:true echo s:MyVar | " v:true " echo MyVar (Would give E121: Undefined variable: MyVar) vim9cmd echo MyVar # true function! MyFunc() echo s:MyVar | " v:true " echo MyVar (Would give E121: Undefined variable: MyVar) vim9cmd echo MyVar # true endfunction call MyFunc() < >vim9 vim9script # 2. In a Vim9 script, "s:" gives E1268 when used in any :def function # and in the script-local scope var MyVar: bool = true echo MyVar # true # echo s:MyVar (Would give E1268: Cannot use s: in Vim9...) legacy echo s:MyVar | # v:true def MyFunc() echo MyVar # true # echo s:MyVar (Would give E1268: Cannot use s: in Vim9...) legacy echo s:MyVar | # v:true enddef MyFunc() < >vim " 3. In a legacy Vim script, "s:" is optional in a :def function let s:MyVar = v:true function! Outer() def! MyFunc() echo MyVar # true echo s:MyVar # true enddef call MyFunc() endfunction call Outer() < Using |exists()|, which is evaluated at runtime, cannot be used conditionally to skip undeclared variables, though |exists_compiled()|, which is evaluated at compile time, may be used. For example: >vim9 vim9script def MyDef() if exists_compiled('MyVar') # evaluated at compile time echo $"MyVar = {MyVar}" # MyVar = 1 endif if exists_compiled('MyVar2') # evaluated at compile time echo $"MyVar2 = {MyVar2}" # not reached else echo "MyVar2 does not exist at compile time" endif if exists('MyVar') # evaluated at runtime echo $"MyVar = {MyVar}" # MyVar = 1 endif if exists('MyVar2') # evaluated at runtime # The following would give E1001: Variable not found: MyVar2 # echo MyVar2 else echo "MyVar2 does not exist at runtime" endif enddef var MyVar: number = 1 # Declared before MyDef() is compiled MyDef() var MyVar2: number = 2 # Declared after MyDef() is compiled < *E1269* Script-local variables in a Vim9 script must be declared at the script level. They cannot be created in a `:def` function and may not be declared in a legacy function with the "s:" prefix. For example: >vim9 vim9script function F_1269() let s:i_wish = v:true endfunction F_1269() # E1269: Cannot create a Vim9 script variable in a function: s:i_wish < *:defc* *:defcompile* :defc[ompile] Compile functions and classes (|class-compile|) defined in the current script that were not compiled yet. This will report any errors found during compilation. Example: When the three lines (up to and including `enddef`) are sourced, there is no error because the Vim9 `:def` function is not compiled. However, if all four lines are sourced, compilation fails: >vim9 vim9script def F_1027(): string enddef defcompile F_1027 # E1027: Missing return statement < :defc[ompile] MyClass Compile all methods in a class. (See |:disassemble| for an example.) :defc[ompile] {func} :defc[ompile] debug {func} :defc[ompile] profile {func} Compile function {func}, if needed. Use "debug" and "profile" to specify the compilation mode. This will report any errors found during compilation. {func} can also be "ClassName.functionName" to compile a function or method in a class. {func} can also be "ClassName" to compile all functions and methods in a class. *:disa* *:disassemble* :disa[ssemble] {func} Show the instructions generated for {func}. This is for debugging and testing. If {func} is not found, error *E1061* occurs. {func} can also be "ClassName.functionName" to disassemble a function in a class. The following example demonstrates using `:defcompile` with a |class| and `:disassemble` with a "ClassName.functionName" (positioning the cursor on the last line of the visually sourced script): >vim9 vim9script class Line var lnum: number def new(this.lnum) enddef def SetLnum() cursor(this.lnum, 52) enddef endclass defcompile Line disassemble Line.SetLnum var vlast: Line = Line.new(line("'>")) vlast.SetLnum() # Cursor is positioned here->_ < :disa[ssemble] profile {func} Like `:disassemble` but with the instructions used for profiling. :disa[ssemble] debug {func} Like `:disassemble` but with the instructions used for debugging. Note: For command line completion of {func}, script-local functions are shown with their . Depending on options, including |wildmenumode()|, completion may work with "s:", "vim9 vim9script const SCRIPT_LOCAL = ['A', 'script-local', 'list'] def MapList(scope: string): list const DEF_LOCAL: list = ['A', 'def-local', 'list'] if scope == 'script-local' return [1]->map('SCRIPT_LOCAL[v:val]') else return [1]->map('DEF_LOCAL[v:val]') endif enddef echo 'script-local'->MapList() # ['script-local'] echo 'def-local'->MapList() # E121: Undefined variable: DEF_LOCAL < The map argument is a string expression, which is evaluated without the function scope. Instead, in Vim9 script, use a lambda: >vim9 vim9script def MapList(): list const DEF_LOCAL: list = ['A', 'def-local', 'list'] return [1]->map((_, v): string => DEF_LOCAL[v]) enddef echo MapList() # ['def-local'] < For commands that are not compiled, such as `:edit`, |backtick-expansion| can be used and it can use the local scope. Example: >vim9 vim9script def EditNewBlah() var fname: string = 'blah.txt' split edit `=fname` enddef EditNewBlah() # A new split is created as buffer 'blah.txt' < *vim9-closure* Closures defined in a loop can either share a variable or each have their own copy, depending on where the variable is declared. With a variable declared outside the loop, all closures reference the same shared variable. The following example demonstrates the consequences, with the "outloop" variable existing only once: >vim9 vim9script var flist: list def ClosureEg(n: number): void var outloop: number = 0 # outloop is declared outside the loop! for i in range(n) outloop = i flist[i] = (): number => outloop # Closures ref the same var endfor echo range(n)->map((i, _): number => flist[i]()) enddef ClosureEg(4) # [3, 3, 3, 3] < All closures put in the list refer to the same instance, which, in the end, is 3. However, when the variable is declared inside the loop, each closure gets its own copy, as shown in this example: >vim9 vim9script var flist: list def ClosureEg(n: number): void for i in range(n) var inloop: number = i # inloop is declared inside the loop flist[i] = (): number => inloop # Closures ref each inloop endfor echo range(n)->map((i, _): number => flist[i]()) enddef ClosureEg(4) # [0, 1, 2, 3] < Another way to have a separate context for each closure is to call a function to define it: >vim9 vim9script def GetClosure(i: number): func var infunc: number = i return (): number => infunc enddef var flist: list def ClosureEg(n: number): void for i in range(n) flist[i] = GetClosure(i) endfor echo range(n)->map((i, _): number => flist[i]()) enddef ClosureEg(4) # [0, 1, 2, 3] < *E1271* A closure must be compiled in the context that it is defined in, so that variables in that context can be found. This mostly happens correctly, except when a function is marked for debugging with `:breakadd` after it was compiled. Make sure to define the breakpoint before compiling the outer function. *E1248* In some situations, such as when a Vim9 closure which captures local variables is converted to a string and then executed, an error occurs. This happens because the string execution context cannot access the local variables from the original context where the closure was defined. For example: >vim9 vim9script def F_1248(): void var n: number var F: func = () => { n += 1 } try execute printf("call %s()", F) catch echo v:exception endtry enddef F_1248() # Vim(call):E1248: Closure called from invalid context < In Vim9 script, a loop variable is invalid after the loop is closed. For example, this timer will echo 0 to 2 on separate lines. However, if the variable "n" is used after the `:endfor`, that is an |E121| error: >vim9 vim9script for n in range(3) var nr: number = n timer_start(1000 * n, (_) => { echowindow nr }) endfor try echowindow n catch echo v:exception endtry < Note: Using `:echowindow` is useful in a timer because messages go into a popup and will not interfere with what the user is doing when it triggers. Converting a :function to a :def~ *convert_legacy_function_to_vim9* *convert_:function_to_:def* There are many changes that need to be made to convert a `:function` to a `:def` function. The following are some of them: - Change `let` used to declare variables to one of `var`, `const`, or `final`, and remove the "s:" from each |script-variable|. - Change `func` or `function` to `def`. - Change `endfunc` or `endfunction` to `enddef`. - Add the applicable type (or "any") to each function argument. - Remove "a:" from each |function-argument|. - Remove inapplicable options such as |:func-range|, |:func-abort|, |:func-dict|, and |:func-closure|. - If the function returns something, add the return type. (Ideally, add "void" if it does not return anything.) - Remove line continuation backslashes from places they are not required. - Remove `let` for assigning values to global (|g:|), buffer (|b:|), window (|w:|), tab (|t:|), and local (|l:|) variables. - Rewrite |lambda| expressions in Vim9 script syntax (see |vim9-lambda|). - Change comments to start with # (preceded by white space) instead of ". - Insert white space in expressions where required (see |vim9-white-space|). - Change "." used for string concatenation to " .. ". (Alternatively, use an |interpolated-string|.) The following legacy Vim script and Vim9 script examples demonstrate all those differences. First, legacy Vim script: >vim let s:lnum=0 function Leg8(arg) abort let l:pre=['Result', \': '] let b:arg=a:arg let s:lnum+=2 let b:arg*=4 let l:result={pre->join(pre,'')}(l:pre) return l:result.(b:arg+s:lnum)"no space before comment endfunction call Leg8(10)->popup_notification(#{time: 3000})" Pops up 'Result: 42' < The equivalent in Vim9 script: >vim9 vim9script var lnum: number def Vim9(arg: number): string final pre = ['Result', ': '] b:arg = arg lnum += 2 b:arg *= 4 const RESULT: string = ((lpre) => join(lpre, ''))(pre) return RESULT .. (b:arg + lnum) # space required before # comment enddef Vim9(10)->popup_notification({time: 3000}) # Pops up 'Result: 42' < Note: This example also demonstrates (outside the `:def` function): - Removing "#" from the legacy |#{}| - see |vim9-literal-dict|, and - Omitting `:call` (allowed, though unnecessary in Vim9 script) Calling a :def function in an expr option ~ *expr-option-function* The value of a few options, such as 'foldexpr', is an expression that is evaluated to get a value. The evaluation can have quite a bit of overhead. One way to minimize the overhead, and also to keep the option value simple, is to define a compiled function and set the option to call it without arguments. For example: >vim9 vim9script def MyFoldFunc(): string # This matches start of line (^), followed by a digit, a full stop # a space or tab, an uppercase character, with an empty next line return getline(v:lnum) =~ '^[[:digit:]]\.[[:blank:]][[:upper:]]' && getline(v:lnum + 1)->empty() ? '>1' : '1' enddef set foldexpr=MyFoldFunc() set foldmethod=expr normal! zM < Warning: This script creates and applies folds at the "Heading 1" level of this vim9.txt help buffer. (You can use |zR|, in Normal mode, to open all the folds after sourcing the script.) ============================================================================== 4. Types *vim9-types* The following types, each shown with its corresponding internal |v:t_TYPE| variable, are supported: number |v:t_number| string |v:t_string| func |v:t_func| func: {type} |v:t_func| func({type}, ...) |v:t_func| func({type}, ...): {type} |v:t_func| list<{type}> |v:t_list| dict<{type}> |v:t_dict| float |v:t_float| bool |v:t_bool| none |v:t_none| job |v:t_job| channel |v:t_channel| blob |v:t_blob| class |v:t_class| object |v:t_object| typealias |v:t_typealias| enum |v:t_enum| enumvalue |v:t_enumvalue| tuple<{type}> |v:t_tuple| tuple<{type}, {type}, ...> |v:t_tuple| tuple<...list<{type}>> |v:t_tuple| tuple<{type}, ...list<{type}>> |v:t_tuple| void *E1031* *E1186* These types can be used in declarations, though no simple value can have the "void" type. Trying to use a void as a value results in an error. Examples: >vim9 vim9script def NoReturnValue(): void enddef try const X: any = NoReturnValue() catch echo v:exception # E1031: Cannot use void value try echo NoReturnValue() catch echo v:exception # E1186: Expression does not result in a valu... endtry endtry < *E1008* *E1009* *E1010* *E1012* Ill-formed declarations and mismatching types result in errors. The following are examples of errors E1008, E1009, E1010, and E1012: >vim9 vim9cmd var l_1008: list vim9cmd var l_1009: list vim9cmd var l_1012: list = ['42'] < There is no array type. Instead, use either a list or a tuple. Those types may also be literals (constants). In the following example, [5, 6] is a list literal and (7, ) a tuple literal. The echoed list is a list literal too: >vim9 vim9script var l: list = [1, 2] var t: tuple<...list> = (3, 4) echo [l, t, [5, 6], (7, )] < *tuple-type* A tuple type may be declared in the following ways: tuple a tuple with a single item of type |Number| tuple a tuple with two items of type |Number| and |String| tuple a tuple with three items of type |Number|, |Float| and |Boolean| tuple<...list> a variadic tuple with zero or more items of type |Number| tuple> a tuple with an item of type |Number| followed by zero or more items of type |String| Examples: >vim9 vim9script var t1: tuple = (20,) var t2: tuple = (30, 'vim') var t3: tuple = (40, 1.1, true) var t4: tuple<...list> = ('a', 'b', 'c') var t5: tuple> = (3, 'a', 'b', 'c', 'd') < *variadic-tuple* *E1539* A variadic tuple has zero or more items of the same type. The type of a variadic tuple must end with a list type otherwise E1539 is given. Examples: >vim9 vim9script var t6: tuple<...list> = (1, 2, 3) var t7: tuple<...list> = ('a', 'b', 'c') var t8: tuple<...list> = () var tE: tuple<...any> = () # E1539: Variadic tuple must end with li... < *vim9-func-declaration* *vim9-partial-declaration* *vim9-func-type* A function (or partial) may be declared in many ways, including: > func func: void func: {type} func()[: void] func(): {type} func({type})[: void] func({type}): {type} func(?{type})[: void] func(?{type}): {type} func(...list<{type}>)[: void] func(...list<{type}>): {type} func({type}, ...list<{type}>)[: void] func({type}, ...list<{type}>): {type} < If the return type is "void", the function does not return a value. All the ways listed above are explained and demonstrated in the following examples, all of which echo '9'. func - any kind of function reference - any type of return value or no return value >vim9 vim9script const I = (n) => n + 1 const F: func = I->function() echo F(8) < func: void - any number and type of arguments - does not return a value >vim9 vim9script def I(n: number): void echo n + 1 enddef const F: func: void = I->function() F(8) < func: {type} - any number and type of arguments - returns a typed value >vim9 vim9script const I = (n): number => n + 1 const F: func: number = I->function() echo F(8) < func()[: void] - no arguments - does not return a value >vim9 vim9script var n: number = 8 def I(): void echo n + 1 enddef const F: func(): void = I->function() F() < func(): {type} - no arguments - returns a typed value >vim9 vim9script var n: number = 8 def I(): number return n + 1 enddef const F: func(): number = I->function() echo F() < func({type})[: void] - typed argument - does not return a value >vim9 vim9script def I(n: number): void echo n + 1 enddef const F: func(number): void = I->function() F(8) < func({type}): {type} - typed argument - returns a typed value >vim9 vim9script const I = (n: number): number => n + 1 const F: func(number): number = I->function() echo F(8) < func(?{type})[: void] - optional typed argument - does not return a value >vim9 vim9script def I(n: number = 8): void echo n + 1 enddef const F: func(?number): void = I->function() F() < func(?{type}): {type} - optional typed argument - returns a typed value >vim9 vim9script def I(n: number = 8): number return n + 1 enddef const F: func(?number): number = I->function() echo F() < func(...list<{type}>)[: void] - typed list for variable number of arguments - does not return a value >vim9 vim9script def L(...l: list): void echo l->reduce((x, y) => x + y) enddef const F: func(...list): void = L->function() F(8, 0, 0, 1) < func(...list<{type}>): {type} - typed list for variable number of arguments - returns a typed value >vim9 vim9script def L(...l: list): number return l->reduce((x, y) => x + y) enddef const F: func(...list): number = L->function() echo F(8, 0, 0, 1) < func({type}, ...list<{type}>)[: void] - typed mandatory argument - typed list for variable number of arguments - does not return a value >vim9 vim9script def D(a: float, ...l: list): void echo (a + l->reduce((x, y) => x + y))->float2nr() enddef const F: func(float, ...list): void = D->function() F(8.0, 0, 0, 1) < func({type}, ...list<{type}>): {type} - typed mandatory argument - typed list for variable number of arguments - returns a typed value >vim9 vim9script def D(a: float, ...l: list): number return (a + l->reduce((x, y) => x + y))->float2nr() enddef const F: func(float, ...list): number = D->function() echo F(8.0, 0, 0, 1) < The reference can also be a |Partial|, in which case it stores extra arguments and/or a dictionary, which are not visible to the caller. Since they are called in the same way, the declaration is the same. This interactive example prompts for a circle's radius and returns its area using a partial: >vim9 vim9script def CircleArea(pi: float, radius: float): float return pi * radius->pow(2) enddef const AREA: func(float): float = CircleArea->function([3.14]) const RADIUS: float = "Enter a radius value: "->input()->str2float() echo $"\nThe area of a circle with a radius of {RADIUS} is " .. $"{AREA(RADIUS)} (π to two d.p.)" < *E1005* No more than 19 argument types may be used in a Funcref (one less than what is allowed in a function, including a `:def` or lambda - see |E740|). Twenty or more argument types gives E1005, as this example shows: >vim9 vim9script var X: func X = (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t) => 0 var F: func(any, any, any, any, any, any, any, any, any, any, any, \ any, any, any, any, any, any, any, any, any): any = X->function() # E1005: Too many argument types < *E1007* A mandatory argument may not come after an optional argument in a Funcref: >vim9 vim9script def I(n: number, f: float): void echo n + f enddef const F: func(?number, float) = I->function() # E1007: Mandatory argument after optional argument < *vim9-typealias-type* Custom types (|typealias|) can be defined with `:type`. They must start with a capital letter (which avoids name clashes with either current or future builtin types) similar to user functions. This example creates a list of perfect squares, reporting on |type()| (14, a typealias) and the |typename()|: >vim9 vim9script type Ln = list final perfect_squares: Ln = [1, 4, 9, 16, 25] echo "Typename (Ln): " .. $"type() is {Ln->type()} and typename() is {Ln->typename()}" < *E1105* A typealias itself cannot be converted to a string: >vim9 vim9script type Ln = list const FAILS: func = (): string => { echo $"{Ln}" # E1105: Cannot convert typealias to string } < *vim9-class-type* *vim9-interface-type* *vim9-object-type* A |class|, |object|, and |interface| may all be used as types. The following interactive example prompts for a float value and returns the area of two different shapes. It also reports on the |type()| and |typename()| of the classes, objects, and interface: >vim9 vim9script interface Shape def InfoArea(): tuple endinterface class Circle implements Shape var radius: float def InfoArea(): tuple return ('Circle (π × r²)', 3.141593 * this.radius->pow(2)) enddef endclass class Square implements Shape var side: float def InfoArea(): tuple return ('Square (s²)', this.side->pow(2)) enddef endclass const INPUT: float = "Enter a float value: "->input()->str2float() echo "\nAreas of shapes:" var myCircle: object = Circle.new(INPUT) var mySquare: object = Square.new(INPUT) final shapes: list = [myCircle, mySquare] for shape in shapes const [N: string, A: float] = shape.InfoArea() echo $"\t- {N} has area of {A}" endfor echo "\n\t\ttype()\ttypename()\n\t\t------\t----------" echo $"Circle\t\t{Circle->type()}\t{Circle->typename()}" echo $"Square\t\t{Square->type()}\t{Square->typename()}" echo $"Shape\t\t{Shape->type()}\t{Shape->typename()}" echo $"MyCircle\t{myCircle->type()}\t{myCircle->typename()}" echo $"MySquare\t{mySquare->type()}\t{mySquare->typename()}" echo $"shapes\t\t{shapes->type()}\t{shapes->typename()}" < *vim9-enum-type* *vim9-enumvalue-type* An |enum| may be used as a type (|v:t_enum|). Variables holding enum values have the enumvalue type (|v:t_enumvalue|) at runtime. The following interactive example prompts for a character and returns information about either a square or a rhombus. It also reports on the |type()| and the |typename()| of the enum and enumvalue: >vim9 vim9script enum Quad Square('four', 'only'), Rhombus('opposite', 'no') var eq: string var ra: string def string(): string return $"\nA {this.name} has " .. $"{this.eq} equal sides and {this.ra} right angles\n\n" enddef endenum echo "Rhombus (r) or Square (s)?" var myQuad: Quad = getcharstr() =~ '\c^R' ? Quad.Rhombus : Quad.Square echo myQuad.string() .. "\ttype()\ttypename()" echo $"Quad \t{Quad->type()} \t{Quad->typename()}" echo $"myQuad\t{myQuad->type()}\t{myQuad->typename()}" < Notes: This uses builtin method "string()" - see |object-string()|. The typename() of Quad and myQuad are the same ("enum") whereas the type() is distinguished (myQuad returns 16, which is an EnumValue, whereas Quad returns 15, which is an Enum). Variable types and type casting ~ *variable-types* Variables declared in Vim9 script or in a `:def` function have a type, either specified explicitly or inferred from the initialization. Global, buffer, window and tab page variables do not have a specific type. Consequently, their values may change at any time, possibly changing the type. Therefore, in compiled code, the "any" type is assumed. This can be a problem when stricter typing is desired, for example, when declaring a list: > var l: list = [1, b:two] Since Vim doesn't know the type of "b:two", the expression becomes list. A runtime check verifies the list matches the declared type before assignment. *type-casting* To get more specific type checking, use type casting. This checks the variable's type before building the list, rather than checking whether list items match the declared type. For example: > var l: list = [1, b:two] < So, here the type cast checks whether "b:two" is a number and gives an error if it isn't. The difference is demonstrated in the following example. With funcref variable "NTC", Vim infers the expression type "[1, b:two]" as list, then verifies whether it can be assigned to the list return type. With funcref variable "TC", the type cast means Vim first checks whether "b:two" is a type: >vim9 vim9script b:two = '2' const NTC: func = (): list => { return [1, b:two] } disassemble NTC # 3 CHECKTYPE list stack [-1] try NTC() catch echo v:exception .. "\n\n" # E1012: Type mismatch; Expected list... endtry const TC: func = (): list => { return [1, b:two] } disassemble TC # 2 CHECKTYPE number stack [-1] try TC() catch echo v:exception # E1012: Type mismatch; Expected number but got... endtry < Note: Notice how the error messages differ, showing when type checking occurs. *E1104* The syntax of a type cast is "<{type}>". An error occurs if either the opening "<" (|E121|) or closing ">" (E1104) is omitted. Also, white space is not allowed either after the "<" (|E15|) or before the ">" (|E1068|), which avoids ambiguity with smaller-than and greater-than operators. Although a type casting forces explicit type checking, it neither changes the value of, nor the type of, a variable. If you need to alter the type, use a function such as |string()| to convert to a string, or |str2nr()| to convert a string to a number. If type casting is applied to a chained expression, it must be compatible with the final result. Examples: >vim9 vim9script # These type casts work echo >[3, 2, 1]->extend(['Go!']) echo [3, 2, 1]->extend(['Go!'])->string() echo >>[3, 2, 1]->list2tuple() # This type cast fails echo [3, 2, 1]->extend(['Go!'])->string() < *E1272* If a type is used in a context where types are not expected you can get E1272. For example: > :vim9cmd echo islocked('x: string') < Note: To see the error, this command must be executed from Vim's command line, not sourced. *E1363* *E1395* If a type is incomplete, such as when an object's class is unknown, E1363 or E1395 are given. Examples: >vim9 vim9script var E1363 = null_class.member # E1363: Incomplete type < >vim9 vim9script def F1395(): void echo null_class.member enddef F1395() # E1395: Using a null class < Another null object-related error is |E1360|: >vim9 vim9script var obj = null_object var E1360 = obj.MyMethod() # E1360: Using a null object < Type inference ~ *type-inference* Declaring types explicitly provides many benefits, including targeted type checking and clearer error messages. Nonetheless, Vim often can infer types automatically when they are omitted. For example, each of these variables' types are inferred, with the |type()| and |typename()| echoed showing those inferred types: >vim9 vim9script echo "\t type()\t typename()" var b = true | echo $"{b} \t {b->type()} \t {b->typename()}" var f = 4.2 | echo $"{f} \t {f->type()} \t {f->typename()}" var l = [1, 2] | echo $"{l} \t {l->type()} \t {l->typename()}" var n = 42 | echo $"{n} \t {n->type()} \t {n->typename()}" var s = 'yes' | echo $"{s} \t {s->type()} \t {s->typename()}" var t = (42, ) | echo $"{t} \t {t->type()} \t {t->typename()}" < The type of a list, tuple, or dictionary is inferred from the common type of its values. When the values are all the same type, that type is used. If there is a mix of types, the "any" type is used. In the following example, the echoed |typename()| for each literal demonstrates these points: >vim9 vim9script echo [1, 2]->typename() # list echo [1, 'x']->typename() # list echo {ints: [1, 2], bools: [false]}->typename() # dict> echo (true, false)->typename() # tuple < The common type of function references, when they do not all have the same number of arguments, is indicated with "(...)", meaning the number of arguments is unequal. This script demonstrates a "list": >vim9 vim9script def Foo(x: bool): void enddef def Bar(x: bool, y: bool): void enddef var funclist = [Foo, Bar] echo funclist->typename() < Script-local variables in a Vim9 script are type checked. The type is also checked for variables declared in a legacy function. For example: >vim9 vim9script var my_local = (1, 2) function Legacy() let b:legacy = [1, 2] endfunction Legacy() echo $"{my_local} is type {my_local->type()} ({my_local->typename()})" echo $"{b:legacy} is type {b:legacy->type()} ({b:legacy->typename()})" < *E1013* When a type is declared for a List, Tuple, or Dictionary, the type is attached to it. Similarly, if a type is not declared, the type Vim infers is attached. In either case, if an expression attempts to change the type, E1013 results. This example has its type inferred and demonstrates E1013: >vim9 vim9script var lb = [true, true] # Two bools, so Vim infers list type echo lb->typename() # list lb->extend([0]) # E1013 Argument 2: type mismatch, ... < If you want a permissive list, either explicitly use or declare an empty list initially (or both, i.e., `list = []`). Examples: >vim9 vim9script final la: list = [] echo la->extend(['two', 1]) final le = [] echo le->extend(la) < Similarly for a permissive dictionary: >vim9 vim9script final da: dict = {} echo da->extend({2: 2, 1: 'One'}) final de = {} echo de->extend(da)->string() < And, although tuples themselves are immutable, permissive tuple concatenation can be achieved with either "any" or an empty tuple: >vim9 vim9script var t_any: tuple<...list> = (3, '2') t_any = t_any + (true, ) echo t_any var t_dec_empty = () t_dec_empty = t_dec_empty + (3, '2', true) echo t_dec_empty < If a list literal or dictionary literal is not bound to a variable, its type may change, as this example shows: >vim9 vim9script echo [3, 2, 1]->typename() # list echo [3, 2, 1]->extend(['Zero'])->typename() # list echo {1: ['One']}->typename() # dict> echo {1: ['One']}->extend({2: [2]})->typename() # dict> < Stricter type checking ~ *type-checking* In legacy Vim script, where a number was expected, a string would be automatically converted to a number. This was convenient for an actual number such as "123", but leads to unexpected problems (and no error message) if the string doesn't start with a number. Quite often this leads to hard-to-find bugs. For example, in legacy Vim script this echoes "1": >vim echo 123 == '123' < However, if an unintended space is included, "0" is echoed: >vim echo 123 == ' 123' < *E1206* In Vim9 script this has been made stricter. In most places it works just as before if the value used matches the expected type. For example, in both legacy Vim script and Vim9 script trying to use anything other than a dictionary when it is required: >vim echo [8, 9]->keys() vim9cmd echo [8, 9]->keys() # E1206: Dictionary required < *E1023* *E1024* *E1029* *E1030* *E1174* *E1175* *E1210* *E1212* However, sometimes there will be an error in Vim9 script, which breaks backwards compatibility. The following examples illustrate various places this happens. The legacy Vim script behavior, which does not fail, is shown first. It is followed by the error that occurs if the same command is used in Vim9 script. - Using a number (except 0 or 1) where a bool is expected: >vim echo v:version ? v:true : v:false vim9cmd echo v:version ? true : false # E1023: Using a Number as ... < - Using a number where a string is expected: >vim echo filter([1, 2], 0) vim9cmd echo filter([1, 2], 0) # E1024: Using a Number as a String < - Assigning a number to an environment variable, a register or a String v: variable: >vim let $FOO = 123 vim9cmd $FOO = 123 # E1012: Type mismatch; expected string but ... < - Not using a number where a number is expected: >vim " In this example, legacy Vim script treats v:false as 0 function Not1029() let b:l = [42] | unlet b:l[v:false] endfunction call Not1029() | echo b:l < >vim9 vim9script def E1029(): void b:l = [42] | unlet b:l[false] enddef E1029() # E1029: Expected number but got bool < - Using a string as a number: >vim let b:l = [42] | unlet b:l['#'] | echo b:l vim9cmd b:l = [42] | vim9cmd unlet b:l['#'] # E1030: Using a string < - Not using a string where an argument requires a string: >vim9 echo substitute('Hallo', 'a', 'e', v:true) vim9cmd echo substitute('Hallo', 'a', 'e', true) # E1174: String ... < - Using an empty string in an argument that requires a non-empty string: >vim9 echo exepath('') vim9cmd echo exepath('') # E1175: Non-empty string required for ar... < - Not using a number when it is required: >vim echo gettabinfo('a') vim9cmd echo gettabinfo('a') # E1210: Number required for argument 1 < - Not using a bool when it is required: >vim echo char2nr('¡', 2) vim9cmd echo char2nr('¡', 2) # E1212: Bool required for argument 2 < - Not using a number when a number is required (|E521|): >vim let &laststatus='2' vim9cmd &laststatus = '2' < - Not using a string when a string is required (|E928|): >vim let &langmenu = 42 vim9cmd &langmenu = 42 # E928: String required < - Comparing a |Special| with "is" often fails (|E1037|, |E1072|): >vim " 1 is echoed because these are both true in legacy Vim script echo v:null is v:null && v:none is v:none " Similarly, 0 is echoed for these (false in legacy Vim script) echo v:none is v:null || v:none is 8 || v:true is v:none " All these are errors in Vim9 script vim9cmd echo v:null is v:null # E1037: Cannot use 'is' with special vim9cmd echo v:none is v:none # E1037: Cannot use 'is' with special vim9cmd echo v:none is v:null # E1037: Cannot use 'is' with special vim9cmd echo v:none is 8 # E1072: Cannot compare special wit... vim9cmd echo v:true is v:none # E1072: Cannot compare bool with s... < Note: Although the last two Vim9 script examples above error with `v:none`, they return `false` with `v:null` (which is the same as `null` - see |v:null|): >vim9 vim9script echo v:null is 8 # false echo true is v:null # false < - Using a string where a bool is required (|E1135|): >vim echo '42' ? v:true : v:false vim9cmd echo '42' ? true : false # E1135: Using a String as a Bool < - Using a bool as a number (|E1138|): >vim let &laststatus=v:true vim9cmd &laststatus = true < One consequence is that the item type of a list or dict given to |map()| must not change when its type is either declared or inferred. For example, this list's type is changed successfully in legacy Vim script: >vim " legacy Vim script changing list [0, 1] to ['item 0', 'item 1'] let s:mylist = [0, 1] call map(s:mylist, {i -> $"item {i}"}) echo s:mylist < whereas in Vim9 script it gives |E1012|: >vim9 vim9script var mylist = [0, 1] # Vim infers mylist is list map(mylist, (i, _) => $"item {i}") # E1012: Type mismatch; expected... < The error occurs because `map()` tries to modify the list elements to strings, which conflicts with the declared type. Use |mapnew()| instead. It creates a new list, and Vim infers its type when it is not specified. Inferred and declared types are shown in this example: >vim9 vim9script var mylist = [0, 1] var infer = mylist->mapnew((i, _) => $"item {i}") echo [infer, infer->typename()] var declare: list = mylist->mapnew((i, _) => $"item {i}") echo [declare, declare->typename()] < The key concept here is, variables with declared or inferred types cannot have the types of the elements within their containers change. However, type "changes" are allowed for either: - a container literal (not bound to a variable), or - a container where |copy()| or |deepcopy()| is used in method chaining. Both are demonstrated in this example: >vim9 vim9script # list literal echo [1, 2]->map((_, v) => $"#{v}") echo [1, 2]->map((_, v) => $"#{v}")->typename() # deepcopy() in a method chain var mylist = [1, 2] echo mylist->deepcopy()->map((_, v) => $"#{v}") echo mylist->deepcopy()->map((_, v) => $"#{v}")->typename() echo mylist < The reasoning behind this is, when a type is either declared or inferred and the list is passed around and changed, the declaration/inference must always hold so that you can rely on the type to match the declared/inferred type. For either a list literal or a fully copied list, that type safety is not needed because the original list is unchanged (as "echo mylist" shows, above). If the item type was not declared or determined to be "", it will not change, even if all items later become the same type. However, when `mapnew()` is used, inference means that the new list will reflect the type(s) present. For example: >vim9 vim9script # list var mylist = [1, '2'] # mixed types, i.e., list echo (mylist, mylist->typename()) # ([1, '2'], 'list') mylist->map((_, v) => $"item {v}") # all items are now strings echo (mylist, mylist->typename()) # both strings, but list # mapnew() var newlist = mylist->mapnew((_, v) => v) echo (newlist, newlist->typename()) # newlist is a list < Using |extend()| and |extendnew()| is similar, i.e., a list literal may use the former, so, this is okay: >vim9 vim9cmd echo [1, 2]->extend(['3']) # [1, 2, '3'] < whereas, this is not: >vim9 vim9script var mylist: list = [1, 2] echo mylist->extend(['3']) # E1013: Argument 2: type mismatch < Using |extendnew()| is needed for extending an existing typed list, except where the extension matches the list's type (or it is "any"). For example, first extending with an element of the same type, then extending with a different type: >vim9 vim9script var mylist: list = [1, 2] mylist->extend([3]) echo mylist->extendnew(['4']) # [1, 2, 3, '4'] < *E1158* Using |flatten()| is not allowed in Vim9 script, because it is intended always to change the type. This even applies to a list literal (unlike |map()| and |extend()|). Instead, use |flattennew()|: >vim9 vim9cmd [1, [2, 3]]->flatten() # E1158: Cannot use flatten vim9cmd echo [1, [2, 3]]->flattennew() # [1, 2, 3] < Assigning to a funcref with specified arguments (see |vim9-func-declaration|) involves strict type checking of the arguments. For example, this works: >vim9 vim9script var F_name_age: func(string, number): string F_name_age = (n: string, a: number): string => $"Name: {n}, Age: {a}" echo F_name_age('Bob', 42) < whereas this fails with error |E1012| (type mismatch): >vim9 vim9script var F_name_age: func(string, number): string F_name_age = (n: string, a: string): string => $"Name: {n}, Age: {a}" < If there is a variable number of arguments they must have the same type, as in this example: >vim9 vim9script var Fproduct: func(...list): number Fproduct = (...v: list): number => reduce(v, (a, b) => a * b) echo Fproduct(3, 2, 4) # 24 < And may be used to accommodate mixed types: >vim9 vim9script var FlatSort: func(...list): any FlatSort = (...v: list) => flattennew(v)->sort('n') echo FlatSort(true, [[[5, 3], 2], 4]) # [true, 2, 3, 4, 5] < Note: Using in a lambda does not avoid type checking of the funcref. It remains constrained by the declared funcref's type and, as these examples show, a runtime or compiling error occurs when the types mismatch: >vim9 vim9script var FuncSN: func(string): number FuncSN = (v: any): number => v->str2nr() echo FuncSN('162')->nr2char() # ¢ echo FuncSN(162)->nr2char() # E1013 (a runtime error) < >vim9 vim9script var FuncSN: func(string): number FuncSN = (v: any): number => v->str2nr() def FuncSNfail(): void echo FuncSN('162')->nr2char() # No echo because ... echo FuncSN(162)->nr2char() # E1013 (now, a compiling error) enddef FuncSNfail() < When the funcref has no arguments specified, there is no type checking. This example shows FlexArgs has a string argument the first time and a list the following time: >vim9 vim9script var FlexArgs: func: string FlexArgs = (s: string): string => $"It's countdown time {s}..." echo FlexArgs("everyone") FlexArgs = (...values: list): string => join(values, ', ') echo FlexArgs('3', '2', '1', 'GO!') < *E1211* *E1217* *E1218* *E1219* *E1220* *E1221* *E1222* *E1223* *E1224* *E1225* *E1226* *E1228* *E1235* *E1238* *E1251* *E1253* *E1256* *E1297* *E1298* *E1301* *E1528* *E1529* *E1530* *E1531* *E1534* Types are checked for most builtin functions to make it easier to spot mistakes. The following one-line |:vim9| commands, calling builtin functions, demonstrate many of those type-checking errors: >vim9 vim9 9->list2blob() # E1211: List required for argume... vim9 9->ch_close() # E1217: Channel or Job required ... vim9 9->job_info() # E1218: Job required for argumen... vim9 [9]->cos() # E1219: Float or Number required... vim9 {}->remove([]) # E1220: String or Number require... vim9 null_channel->ch_evalraw(9) # E1221: String or Blob required ... vim9 9->col() # E1222: String or List required ... vim9 9->complete_add() # E1223: String or Dictionary req... vim9 setbufline(9, 9, {}) # E1224: String, Number or List r... vim9 9->count(9) # E1225: String, List, Tuple or D... vim9 9->add(9) # E1226: List or Blob required fo... vim9 9->remove(9) # E1228: List, Dictionary, or Blo... vim9 getcharstr('9') # E1235: Bool or number required ... vim9 9->blob2list() # E1238: Blob required for argume... vim9 9->filter(9) # E1251: List, Tuple, Dictionary,... vim9 9->reverse() # E1253: String, List, Tuple or B... vim9 9->call(9) # E1256: String or Function requi... vim9 null_dict->winrestview() # E1297: Non-NULL Dictionary requ... vim9 {}->prop_add_list(null_list) # E1298: Non-NULL List required f... vim9 {}->repeat(9) # E1301: String, Number, List, Tu... vim9 9->index(9) # E1528: List or Tuple or Blob re... vim9 9->join() # E1529: List or Tuple required f... vim9 9->max() # E1530: List or Tuple or Diction... vim9 9->get(9) # E1531: Argument of get() must b... vim9 9->tuple2list() # E1534: Tuple required for argum... < Reserved for future use: *E1227* *E1250* *E1252* E1227: List or Dictionary required for argument %d E1250: Argument of %s must be a List, String, Dictionary or Blob E1252: String, List or Blob required for argument %d Categories of variables, defaults and null handling ~ *variable-categories* *null-variables* There are three categories of variables: primitive number, float, boolean container string, blob, list, tuple, dict specialized function, job, channel, user-defined-object When declaring a variable without an initializer, an explicit type must be provided. Each category has different default initialization semantics. Primitives default to type-specific values. All primitives are empty but do not equal `null`: >vim9 vim9script var n: number | echo [n, n->empty(), n == null] # [0, 1, false] var f: float | echo [f, f->empty(), f == null] # [0.0, 1, false] var b: bool | echo [b, b->empty(), b == null] # [false, 1, false] < Containers default to an empty container. Only an empty string equals `null`: >vim9 vim9script var s: string | echo [s, s->empty(), s == null] # ['', 1, true] var z: blob | echo [z, z->empty(), z == null] # [0z, 1, false] var l: list | echo [l, l->empty(), l == null] # [[], 1, false] var t: tuple | echo [t, t->empty(), t == null] # [(), 1, false] var d: dict | echo [d, d->empty(), d == null] # [{}, 1, false] < Specialized types default to equaling `null`: >vim9 vim9script var F: func | echo [F, F == null] # [function(''), true] var j: job | echo [j, j == null] # ['no process', true] var c: channel | echo [c, c == null] # ['channel fail', true] class Class endclass var o: Class | echo [o, o == null] # [object of [unknown], true] enum Enum endenum var e: Enum | echo [e, e == null] # [object of [unknown], true] < Notes: (1) See |empty()| for explanations of empty job, empty channel, and empty object types. (2) The `class`, `enum`, and `typealias` types cannot be used as values, so cannot be compared to `null` (see |E1405|, |E1421|, and |E1403| respectively). Vim does not have a familiar null value. Instead, it has various null_ predefined values including |null_string|, |null_list|, and |null_job|. Primitives do not have a null_. Typical use cases for null_ are: - to clear a variable and release its resources, - as a default for a parameter in a function definition (for an example, see |null_blob|), or - assigned to a container or specialized variable to set it to null for later comparison (for an example, see |null-compare|). For a specialized variable, like `job`, null_ is used to clear the resources. For example: >vim9 vim9script var mydate: list def Date(channel: channel, msg: string): void mydate->add(msg) enddef var myjob = job_start([&shell, &shellcmdflag, 'date'], {out_cb: Date}) echo [myjob, myjob->job_status()] sleep 2 echo $"The date and time is {mydate->join('')}" echo [myjob, myjob->job_status()] myjob = null_job # Clear the variable; release the job's resources. echo myjob < For a container variable, resources may also be cleared by assigning an empty container to the variable. For example: >vim9 vim9script var perfect: list = [1, 4] perfect->extend([9, 16, 25]) perfect = [] echo perfect < Using an empty container, rather than null_, to clear a container variable may avoid null complications - see |null-anomalies|. The initialization semantics of container variables and specialized variables differ. For containers: - An uninitialized container defaults to empty but does not equal `null` (except for an uninitialized string). - A container initialized to [], (), {}, "", or 0z is empty but does not equal `null`. - A container initialized as null_ defaults to empty and it also equals `null`. In the following example, the uninitialized list ("lu") and [] initialized list ("li") are equivalent and indistinguishable whereas "ln" is a null container, which is similar to, but not equivalent to, an empty container (see |null-anomalies|). >vim9 vim9script # uninitialized: empty container, not null var lu: list echo ['lu', $"empty={lu->empty()}", $"null={lu == null}"] # initialized: empty container, not null var li: list = [] echo ['li', $"empty={li->empty()}", $"null={li == null}"] # initialized: empty container, null var ln: list = null_list echo ['ln', $"empty={ln->empty()}", $"null={ln == null}"] < Specialized variables default to equaling null. These job initializations are equivalent and indistinguishable: >vim9 vim9script var j1: job var j2: job = null_job var j3 = null_job echo (j1 == j2) == (j2 == j3) # true (equivalent, indistinguishable) < When a list, tuple, or dict is declared, if the item type is not specified it cannot be inferred. Consequently, the item type defaults to "any": >vim9 vim9script var [t1, t2] = [(), null_tuple] echo $'t1 is {t1->typename()} and t2 is {t2->typename()} too' < Tuples and functions (or partials) may be declared in various ways. See |tuple-type|, |variadic-tuple|, and |vim9-func-declaration|. *null-compare* For familiar null compare semantics, where an empty container is not equal to a null container, do not use null_ in a comparison. That is because, in Vim9 script, although null_ == `null`, comparing an: - empty container to `null` is `false`, but - empty container to null_ is `true`. So, compare against `null`, not null_. For example: >vim9 vim9script var bonds: dict> = {g: ['007', '008'], o: ['007', '009']} def Search(query: string): list return query == "\r" ? null_list : bonds->get(query, []) enddef echo "Goldfinger (g) or Octopussy (o)?: " const C: string = getcharstr() var result: list = C->Search() if result == null # <<< DO NOT USE null_list HERE! echo "Error: Nothing was entered" else echo result->empty() ? $"No matches for '{C}'" : $"{result}" endif < Note: Using "result == null_list" instead of "result == null" would fail to distinguish the error (nothing entered) and the valid (nothing matched) result because [] == null_list whereas [] != null. Conceptually, think of the null_ construct as a hybrid/bridge between the general `null` and typed `empty` containers, having properties of both. In the following section there are details about comparison results. *null-details* *null-anomalies* This section describes issues about using null and null_; included below are the enumerated results of null comparisons. In some cases, if familiar with vim9 null semantics, the programmer may choose to use null_ in comparisons and/or other situations. Elsewhere in the documentation it says, "often a null value is handled the same as an empty value, but not always". For example, you cannot add to a null container: >vim9 vim9script var le: list = [] le->add('Okay') # le is now ['Okay'] var ln = null_list ln->add("E1130") # E1130: Cannot add to null list < As explained in |null-compare|, there is a non-transitive relationship among `null`, null_ containers, and `empty`. To recap, for example: >vim9 vim9cmd echo (null_dict == {}, null_dict == null, {} != null) < The exception is an uninitialized string. It is equal to `null` (and is the same instance as `null_string`). The "is" operator (|expr-is|) may be used to determine whether a string is uninitialized: >vim9 vim9script var s: string echo s == null_string # true echo s is null_string # true (the same instance) echo s == null # true (unexpected, perhaps) echo s is null # false (not the same instance) < However, don't do the same for the other containers because, when evaluated against their applicable null_ with "is", they return `false`: >vim9 vim9script var d: dict echo d == null_dict # true echo d is null_dict # false (not the same instance) echo d == null # false (as expected) echo d is null # false (not the same instance) < The key distinction here is an uninitialized string is implemented as `null_string`, while an uninitialized list, dict, tuple, or blob is implemented as an empty container ([], {}, (), and 0z respectively). So, those uninitialized types are equal to, but not the same instance as, their null_ counterparts, as this example shows: >vim9 vim9script var t: tuple echo t == null_tuple # true echo t is null_tuple # false < However, a variable initialized to the null_ is equal not only to the null_, it is also equal to null. For example: >vim9 vim9script var t: tuple = null_tuple echo t == null_tuple # true echo t is null_tuple # true echo t == null # true < An uninitialized container variable is not equal to null, except for an uninitialized string, which is explained in an example, above. So, these all echo `true`: >vim9 vim9script var b: blob | echo b != null var d: dict | echo d != null var l: list | echo l != null var t: tuple | echo t != null var s: string | echo s == null < An uninitialized specialized variable is equal to null. So, these all echo `true`: >vim9 vim9script var c: channel | echo c == null var F: func | echo F == null var j: job | echo j == null class Class endclass var nc: Class | echo nc == null enum Enum endenum var ne: Enum | echo ne == null < Note: the specialized variables, like job, default to null and no specialized variable has a corresponding empty value. A container variable initialized to empty equals null_, so these are all `true`: >vim9 vim9script var s: string = "" | echo s == null_string var b: blob = 0z | echo b == null_blob var l: list = [] | echo l == null_list var t: tuple = () | echo t == null_tuple var d: dict = {} | echo d == null_dict < However, a container variable initialized to empty does not equal null, so these are all `true`: >vim9 vim9script var s: string = "" | echo s != null var b: blob = 0z | echo b != null var l: list = [] | echo l != null var t: tuple = () | echo t != null var d: dict = {} | echo d != null < ============================================================================== 5. Generic functions *generic-functions* A generic function allows using the same function with different type arguments, while retaining type checking for arguments and the return value. This provides type safety and code reusability. Declaration~ *generic-function-declaration* *E1553* *E1554* The type variables for a generic function are declared as its type parameters within angle brackets ("<" and ">"), directly after the function name. Multiple type parameters are separated by commas: > def[!] {funcname}<{type} [, {types}]>([arguments])[: {return-type}] {function body} enddef < *generic-function-example* These type parameters may then be used, like any other type, within the function signature and its body. The following example combines two lists into a list of tuples: >vim9 vim9script def Zip(first: list, second: list): list> const LEN: number = ([first->len(), second->len()])->min() final result: list> = [] for i in range(LEN) result->add((first[i], second[i])) endfor return result enddef var n: list = [61, 62, 63] var s: list = ['a', 'b', 'c'] echo $"Zip example #1: {Zip(n, s)}" echo $"Zip example #2: {Zip(s, n)}" < *type-variable-naming* *E1552* *type-parameter-naming* As in the preceding example, the convention is to use a single capital letter for a name (e.g., T, U, A, etc.). Although they may comprise more than one letter, names must start with a capital letter. In this example, "Ok" is valid whereas "n" is not: >vim9 vim9script def MyFail(): void enddef # E1552: Type variable name must start with an uppercase letter: n>... < *E1558* *E1560* A function must be declared and used either as a generic function or as a regular function, but not both. The following Vim9 scripts demonstrate these errors: >vim9 vim9script My1558() # E1558: Unknown generic function: My1558 < >vim9 vim9script def My1560(): void enddef My1560() # E1560: Not a generic function: My1560 < *E1561* Type parameter names must not clash with other identifiers: >vim9 vim9script def My1561(): D enddef # E1561: Duplicate type variable name: D vim9script enum E Yes, No endenum def My1041(): E enddef # E1041: Redefining script item: "E" < Calling a generic function~ *generic-function-call* To call a generic function, specify the concrete types in "<" and ">" between the function name and the argument list: > MyFunc>() < Note: There are several working examples in this section, which may be sourced, including |generic-function-example|. *E1555* *E1556* *E1557* *E1559* The number of passed type arguments to the function must match the number of its declared type parameters. An empty type list is not allowed. Examples: >vim9 vim9script def My1555<>(): void enddef # E1555: Empty type list specified for generic function 'vim9 vim9script def My1556(): void enddef My1556() # E1556: Too many types specified for generic... < >vim9 vim9script def My1557(): void enddef My1557() # E1557: Not enough types specified for generic fun... < >vim9 vim9script def My1559(): T enddef My1559() # E1559: Type arguments missing for generic function '" and the opening "(" (|E1068|), or - Within the "<" and ">", except where required after the comma separating the types (|E1202|). A generic function can be exported and imported like a regular function. See |:export| and |:import|. A generic function can be defined inside another regular or generic function. An example: >vim9 vim9script def Outer(): void # Returns either the first item of a list or a default value def FirstOrDefault(lst: list, default: U): any return lst->len() > 0 ? lst[0] : default enddef echo FirstOrDefault(['B', 'C'], false) # B echo FirstOrDefault([], 42) # 42 enddef Outer() < Using a type variable as a type argument ~ A type variable may also be passed as a type argument. For example: >vim9 vim9script # T is declared as a type parameter # It is used for the 'value' parameter and the return type def Id(value: T): T return value enddef # U is declared as a type parameter # It is used for the 'value' parameter and the return type def CallId(value: U): U # U is a type variable passed/used as a type argument return Id(value) enddef echo CallId('I am') .. ' ' .. CallId(42) < This is useful for complex data structures like dictionaries of lists or, as in the following example, lists of dictionaries: >vim9 vim9script def Flatten(x: list>): list final result: list = [] for inner in x result->extend(inner) endfor return result enddef const ENGLISH: list> = [{1: 'one'}, {2: 'two'}] const MANDARIN: list> = [{1: '壹'}, {2: '贰'}] const ARABIC_N: list> = [{1: 1}, {2: 2}] echo Flatten>([ENGLISH, MANDARIN]) echo Flatten>([ENGLISH, ARABIC_N]) < In "Flatten", "T" is a declared type parameter. Everywhere else in the function, "T" is a type variable referencing that type parameter. Generic class method~ A Vim9 class method can be a generic function: >vim9 vim9script class Config var settings: dict def Get(key: string): T return this.settings[key] enddef endclass var c: Config = Config.new({timeout: 30, debug: true}) echo c.Get('timeout') echo c.Get('debug') < *E1432* *E1433* *E1434* A generic class method in a base class can be overridden by a generic method in a child class. The number of type variables must match between both methods. A concrete class method cannot be overridden by a generic method, and vice versa. Generic function reference~ A function reference (|Funcref|) can be a generic function. This allows for creating factories of functions that operate on specific types: >vim9 vim9script # Match a specified character in a string or the decimal value of the # character in a list. Note: '*' is decimal 42 (U+002A) var c: string = "*" var char_dec: tuple = (c, c->char2nr()->string()) def Matcher(pattern: string): func(T): bool return (value: T): bool => match(value, pattern) >= 0 enddef var StringMatch = Matcher(char_dec[0]) echo "*+"->StringMatch() # true (has *) echo ",-"->StringMatch() # false var ListMatch = Matcher>(char_dec[1]) echo [42, 43]->ListMatch() # true (has 42) echo [44, 45]->ListMatch() # false < Compiling and Disassembling Generic functions~ The |:defcompile| command can be used to compile a generic function with a specific list of concrete types: > defcompile MyFunc, dict> < The |:disassemble| command can be used to list the instructions generated for a generic function: > disassemble MyFunc> disassemble MyFunc> < Limitations and Future Work~ Currently, Vim does not support: - Type inference for type variables: All types must be explicitly specified when calling a generic function. - Type constraints: It's not possible to restrict a type variable to a specific class or interface (e.g., `T extends SomeInterface`). - Default type arguments: Providing a default type for a type parameter when not explicitly specified. ============================================================================== 6. Namespace, Import and Export *vim9script* *vim9-export* *vim9-import* A Vim9 script can be written to be imported. This means that some items are intentionally exported, made available to other scripts. When the exporting script is imported in another script, these exported items can then be used in that script. All the other items remain script-local in the exporting script and cannot be accessed by the importing script. This mechanism exists for writing a script that can be sourced (imported) by other scripts, while making sure these other scripts only have access to what you want them to. This also avoids using the global namespace, which has a risk of name collisions. For example when you have two plugins with similar functionality. You can cheat by using the global namespace explicitly. That should be done only for things that really are global. Namespace ~ *vim9-namespace* To recognize a file that can be imported, the `vim9script` command must appear as the first command in the file (though see |vim9-mix| for an exception). It tells Vim to interpret the script in its own namespace, instead of the global namespace. Consider this script: >vim9 vim9script var myvar = 'yes' < The variable "myvar" will only exist in this script's scope. That is different from legacy Vim script where "let myvar" would make "myvar" available to other scripts and functions (as `g:myvar`). *E1101* The variables at the file level are very much like the script-local "s:" variables in legacy Vim script, but the "s:" is omitted. And they cannot be deleted. *E1304* In Vim9 script the global (`g:`), buffer (`b:`), window (`w:`), and tab (`t:`) namespaces can be used like in legacy Vim script. In Vim9 script, namespace prefixed variables: - are not declared - have no specific type, and - can be deleted. If a namespace prefixed variable is declared, |E1016| is given. And, if a type is specified, E1304 is given: >vim9 vim9cmd var b:fails: bool # E1016: Cannot declare a buffer va... vim9cmd b:fails: bool = false # E1304: Cannot use type with this ... < A side effect of `:vim9script` is that the 'cpoptions' option is set to the Vim default value, like with: > :set cpo&vim < One of the effects is that |line-continuation| is always enabled. The original value of 'cpoptions' is restored at the end of the script, while flags added or removed in the script are also added to or removed from the original value to get the same effect. The order of flags may change. In the |vimrc| file sourced on startup this does not happen. *vim9-mix* There is one way to use both legacy and Vim9 syntax in one script file: >vim9 " _legacy Vim script_ comments are placed here if !has('vim9script') " _legacy Vim script_ comments and commands are placed here finish endif vim9script # _Vim9 script_ commands/commands from here onwards echowindow $"has('vim9script') == {has('vim9script')}" < This allows for writing a script that takes advantage of the Vim9 script syntax if possible, and prevents the `vim9script` command from giving an error if used in a version of Vim without Vim9 script. Note that Vim9 syntax changed before Vim 9 so that scripts using the current syntax (such as "import from" instead of "import") might give errors. To prevent these, a safer check may be |v:version| >= 900 instead (because "has('vim9script')" will return `v:true` back to Vim 8.2 with patch 3965). Sometimes it is prudent to cut off even later. Vim9 script's feature set continues to grow so, for example, if tuples are used (introduced in Vim 9.1 patch 1232), a better condition is: >vim9 if !has('patch-9.1.1232') echowindow $"Fail: Vim does not have patch 9.1.1232" finish endif vim9script echowindow $"Pass: version {v:versionlong}. Continuing ..." < Whichever vim-mix condition is used, it only works in one of two ways: 1. The "if" statement evaluates to false, the commands up to `endif` are skipped and `vim9script` is then the first command actually executed. 2. The "if" statement evaluates to true, the commands up to `endif` are executed and `finish` bails out before reaching `vim9script`. Export ~ *:export* Exporting an item can be written as: > export var myvar ... export const MYCONST ... export final myvar ... export def MyDef() ... export function MyFunc() ... export class MyClass ... export abstract class MyAbstractClass ... export interface MyInterface ... export enum MyEnum ... export type MyType ... < *E1043* As this suggests, variables, constants, functions, classes (including abstract classes), interfaces, enums, and types can be exported. Trying to export something else gives E1043: >vim9 vim9cmd export echo 0 # E1043: Invalid command after :export < *E1042* `:export` can only be used in a Vim9 script scope. So, for example, although exporting a `:function` is okay, trying to export an item within such a function gives E1042: >vim9 vim9script export function F1042() export var b: bool endfunction F1042() # E1042: Export can only be used in vim9script < *E1044* An invalid argument can give E1044: >vim9 vim9script export def /a1044(): void enddef # E1044: Export with invalid argument: ... < Import ~ *:import* The exported items can be imported in another script. The import syntax has two forms. The simpler form is: > import {filename} < Where {filename} is an expression that must evaluate to a string. In this form the filename should end in ".vim" and the portion before ".vim" will become the script-local name of the namespace. For example: > import "myscript.vim" < This makes each exported item in "myscript.vim" available as "myscript.item". *E1094* Importing is only allowed in the script-local scope. Trying to do so elsewhere gives E1094; for example, from a `:function` or `:def` scope: >vim9 vim9script def F1094(): void import 'nah.vim' # E1094: Import can only be used in a script enddef F1094() < *E1053* *E1071* Errors are given when either the {filename} is not found or it is invalid: >vim9 vim9cmd import 'e1053.vim' # E1053: Could not import "e1053.vim" vim9cmd import false # E1071: Invalid string for :import: false < *:import-as* When the name of the file is long, ambiguous (such as with filenames that are the same but in different directories), or if you just want to use a distinct structure for the name, this form can be used: > import {longfilename} as {name} < In this longer form, {name} becomes a specific script-local name for the imported namespace. Therefore {name} must consist of letters, digits, or '_', and cannot start with a digit, like |internal-variables|. The {longfilename} expression must evaluate to an existing filename. The following script demonstrates using `:import-as`. It: - Creates a constant, "TMP", for the {longfilename} of a temporary Vim9 script file to import - Writes a two-line Vim9 script to TMP - Imports the Vim9 script file "as" the {name}, "that", and - Echoes the result, showing the imported Vim9 script file's {longfilename} and, on a separate line, the content of "that.myvar" (where "myvar" is an exported variable in the imported script). >vim9 vim9script const TMP: string = tempname() ['vim9script', 'export var myvar: string = "YES!"']->writefile(TMP) import TMP as that echo $"Exported var 'myvar' in 'that' ({TMP}):\n" .. that.myvar < This example shows you can use "that.myvar", etc. You are free to choose the name "that", or something that will be recognized as referring to the imported script. It is best to avoid command names, command modifiers, and builtin function names, because {name} will shadow any of those. It also is better to begin the name with a lowercase letter because that avoids potential shadowing of global user commands and functions. The {name} cannot be used for anything else in the script, such as a function or variable name (see |E1213|), and it cannot be assigned something else (see |E1258|). In case the "." in the name is undesired, a local reference can be made for a function: > var LongDef = that.LongDefName This also works for constants: > const MAXLEN = that.MAXIMUM_LENGTH_OF_NAME This does not work for variables, since the value would be copied once and when changing the variable the copy will change, not the original variable. You need to use the full name (i.e., including the '.'). Imported items are intended to exist at the script level and only be imported once. Also, `:import` can not be used in a `:function` or `:def` - see |E1094|. The script name after `:import` can be: - A relative path, starting "." or "..". This finds a file relative to the location of the script file itself. This is useful to split up a large plugin into several files. - An absolute path, starting with "/" on Unix or "D:/" on MS-Windows. This will rarely be used. - A path not being relative or absolute. This will be found in the "import" subdirectories of 'runtimepath' entries. The name will usually be longer and unique, to avoid loading the wrong file. Note that "after/import" is not used. Once a Vim9 script file has been imported, the result is cached and it will not be read again. Many syntax and other errors may be given when importing. Examples: *E1047* - Using an invalid "as" {name}: >vim9 vim9script import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i-cc # E1047: Syntax error in import: i-cc < *E1048* - Trying to use a non-existent item in an imported script: >vim9 vim9script import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc echo i_cc.absent_item # E1048: Item not found in script: absent_item < *E1049* - Trying to use a declared, but non-exported, item in an imported script: >vim9 vim9script import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc echo i_cc.prepended # E1049: Item not exported in script: prepended < *E1060* When using the imported name, the '.' and the item name must be contiguous. So there can be neither white space nor a line break: - After the '.' (see |E1074|), or - Before the '.', for example: >vim9 vim9script import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc echo i_cc .GetPath() # E1060: Expected dot after name: i_cc .Get... < *E1088* - Attempting to have an imported script import itself: >vim9 vim9script const TMP: string = $'{tempname()}.vim'->substitute('\\', '/', 'g') var lines: list = ['vim9script', $'import "{TMP}" as e1088'] lines->writefile(TMP) import TMP # E1088: Script cannot import itself < *E1236* - Trying to use the script itself: >vim9 vim9script import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as cc cc() # E1236: Cannot use cc itself, it is imported < *E1257* - Not using "as {name}" when the imported filename does not end in ".vim": >vim9 vim9script const TMP: string = tempname() ['vim9script']->writefile(TMP) import TMP # E1257: Imported script must use "as" or end in .vim: ... < *E1258* - Omitting the '.' after an imported name: >vim9 vim9script import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc def F1258(): void i_cc = enddef defcompile # E1258: No '.' after imported name: i_cc = < *E1259* - Omitting the name after an imported name: >vim9 vim9script import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc def F1259(): void i_cc.8 = 0 enddef defcompile # E1259: Missing name after imported name: i_cc.8 = 0 < *E1260* - Attempting to `:unlet` an imported item: >vim9 vim9script const TMP: string = tempname() ['vim9script', 'export var b: bool']->writefile(TMP) import TMP as e_unlet unlet e_unlet.b # E1260: Cannot unlet an imported item: b < *E1261* - Attempting to import the filename ".vim" without using "as". This script writes the temporary file '.vim' to the operating system's applicable temporary directory, then attempts to import it: >vim9 vim9script const TMPDIR: string = tempname() ->substitute('\\', '/', 'g') # Ensure Windows \ chars are / ->substitute('/[^/]\+$', '/', '') # Remove the filename ['vim9script']->writefile($'{TMPDIR}.vim') echo $"Temporary import file name is: {TMPDIR}.vim" import $'{TMPDIR}.vim' # E1261: Cannot import .vim without using "as" < *E1262* - Trying to import the same script multiple times (including using different "as" names): >vim9 vim9script import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc1 import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc2 # E1262: Cannot import the same script twice: .../ccomplete.vim < *import-map* When you've imported a function from one script into a Vim9 script you can refer to the imported function in a mapping by prefixing it with ||: > noremap ,a :call name.Function() When the mapping is defined "name." will be replaced with and the script ID of the imported script. An even simpler solution is using ||: > noremap ,a name.Function() Note that this does not work for variables, only for functions. This self-contained example demonstrates using , creating and writing a temporary script, which is then imported and the function "exported.MyDef()" mapped to a: >vim9 vim9script const TMP: string = tempname() ['vim9script', 'export def MyDef(): void', ' popup_notification("exported.MyDef() was called", {time: 4000})', 'enddef']->writefile(TMP) import TMP as exported nnoremap a exported.MyDef() # Now, pressing a calls exported.MyDef(), generating a popup < *import-legacy* *legacy-import* *:imp* `:import`, including the shortened form `:imp`, can also be used in legacy Vim script. The imported namespace still becomes script-local, even when the "s:" prefix is not given. For example: > import "myfile.vim" call s:myfile.MyFunc() When using the "as name" form, the namespace cannot be resolved on its own (see also |E1060|). This example demonstrates using `:imp` with `as` successfully, then the error: >vim let s:tmp = $'{tempname()}.vim'->substitute('\\', '/', 'g') call writefile(['vim9script', \ 'export function L()', \ ' return "Vim9 script exporting a :function"', \ 'endfunction'], s:tmp) imp s:tmp as iLegacy echo s:iLegacy.L() |" echoes 'Vim9 script exporting a :function' echo s:iLegacy |" E1060: Expected dot after name: s:iLegacy < This also affects the use of || in the legacy mapping context. Since || is only a valid prefix for a function and NOT for a namespace, you cannot use it to scope a function in a script-local namespace. Instead of prefixing the function with || you should use ||. For example: > noremap ,a :call s:that.OtherFunc() < *:import-cycle* The `import` commands are executed when encountered. If script A imports script B, and B (directly or indirectly) imports A, this will be skipped over. At this point items in A after "import B" will not have been processed and defined yet. Therefore cyclic imports can exist and not result in an error directly, but may result in an error for items in A after "import B" not being defined. This does not apply to autoload imports, see the next section. Importing an autoload script ~ *vim9-autoload* *import-autoload* For optimal startup speed, loading scripts should be postponed until they are actually needed. Using the autoload mechanism is recommended: *E1264* 1. In the plugin, define user commands, functions and/or mappings referring to items imported from an autoload script. > import autoload 'for/search.vim' command -nargs=1 SearchForStuff search.Stuff() < This goes in .../plugin/anyname.vim. "anyname.vim" can be freely chosen. The "SearchForStuff" command is now available to the user. The "autoload" argument to `:import` means that the script is not loaded until one of the items is actually used. The script will be found under the "autoload" directory in 'runtimepath' instead of the "import" directory. Alternatively, either a relative or absolute name can be used - see below. 2. In the autoload script put the bulk of the code. > vim9script export def Stuff(arg: string): void ... < This goes in .../autoload/for/search.vim. Putting the "search.vim" script under the "/autoload/for/" directory has the effect that "for#search#" will be prefixed to every exported item. The prefix is obtained from the file name, just as you would add it manually in a legacy autoload script. Thus the exported function can be found with "for#search#Stuff", but you would normally use `import autoload` and not use the prefix (which has the side effect of loading the autoload script when compiling a function that encounters this name). You can split up the functionality and import other scripts from the autoload script as you like. This way you can share code between plugins. Searching for the autoload script in all entries in 'runtimepath' can be a bit slow. If the plugin knows where the script is located, quite often a relative path can be used. This avoids the search and should be quite a bit faster. Another advantage is that the script name does not need to be unique. Also, an absolute path is possible. Examples: > import autoload '../lib/implement.vim' import autoload MyScriptsDir .. '/lib/implement.vim' For defining a mapping that uses the imported autoload script the special key || is useful. It allows for a command in a mapping to use the script context of where the mapping was defined. When compiling a `:def` function and a function in an autoload script is encountered, the script is not loaded until the `:def` function is called. This also means you get any errors only at runtime, since the argument and return types are not known yet. If you would use the name with '#' characters then the autoload script IS loaded. Be careful to not refer to an item in an autoload script that does trigger loading it unintentionally. For example, when setting an option that takes a function name, make sure to use a string, not a function reference: > import autoload 'qftf.vim' &quickfixtextfunc = 'qftf.Func' # autoload script NOT loaded &quickfixtextfunc = qftf.Func # autoload script IS loaded On the other hand, it can be useful to load the script early, at a time when any errors should be given. For testing the |test_override()| function can be used to have the `import autoload` load the script right away, so that the items and types can be checked without waiting for them to be actually used: > test_override('autoload', 1) Reset it later with: > test_override('autoload', 0) Or: > test_override('ALL', 0) ============================================================================== 7. Classes and interfaces *vim9-classes* In legacy Vim script, a Dictionary could be used as a kind-of object by adding members that are functions. However, this is quite inefficient and requires the writer to do the work of making sure all the objects have the right members. See |Dictionary-function|. In |Vim9| script you can have classes, objects, interfaces, and enums like in most popular object-oriented programming languages. Since this is a lot of functionality, it is located in a separate help file, |vim9class.txt|, though there are several sourceable examples within this help file too (at |vim9-class-type|, |vim9-enum-type|, and elsewhere). ============================================================================== 8. Rationale *vim9-rationale* The :def command ~ Plugin writers have asked for much faster Vim script. Investigations have shown that keeping the existing semantics of function calls make this close to impossible, because of the overhead involved with calling a function, setting up the local function scope and executing lines. There are many details that need to be handled, such as error messages and exceptions. The need to create a dictionary for a: and l: scopes, the a:000 list and several others add too much overhead that cannot be avoided. Therefore the `:def` method to define a new-style function had to be added, which allows for a function with different semantics. Most things still work as before, but some parts do not. A new way to define a function was considered the best way to separate the legacy style code from Vim9 style code. Using "def" to define a function comes from Python. Other languages use "function" which clashes with legacy Vim script. Type checking ~ When compiling lines of Vim commands into instructions as much as possible should be done at compile time. Postponing it to runtime makes the execution slower and means mistakes are found only later. For example, when encountering the "+" character and compiling this into a generic add instruction, at runtime the instruction would have to inspect the type of the arguments and decide what kind of addition to do. And when the type is dictionary, give an error. If the types are known to be numbers then an "add number" instruction can be used, which is faster. The error can be given at compile time, no error handling is needed at runtime, since adding two numbers almost never fails. Note: As a tangential point, the exception is integer overflow, where the result exceeds the maximum integer value. For example, adding to a 64-bit signed integer where the result is greater than 2^63: >vim9 vim9script echo 9223372036854775807 + 1 # -9223372036854775808 echo 2->pow(63)->float2nr() + 1 # -9223372036854775808 < The syntax for types, using for compound types, is similar to Java. It is easy to understand and widely used. The type names are what were used in Vim before, with some additions such as "void" and "bool". Removing clutter and weirdness ~ Once decided that `:def` functions have different syntax than legacy functions, we are free to add improvements to make the code more familiar for users who know popular programming languages. In other words: remove weird things that only Vim does. We can also remove clutter, mainly things that were done to make Vim script backwards compatible with the good old Vi commands. Examples: - Drop `:call` for calling a function and `:eval` for evaluating an expression. - Drop using a leading backslash for line continuation, automatically figure out where an expression ends. However, this does require that some things need to change: - Comments start with # instead of ", to avoid confusing them with strings. This is good anyway, it is also used by several popular languages. - Ex command ranges need to be prefixed with a colon, to avoid confusion with expressions (single quote can be a string or a mark, "/" can be divide or a search command, etc.). Goal is to limit the differences. A good criteria is that when the old syntax is accidentally used you are very likely to get an error message. Syntax and semantics from popular languages ~ Script writers have complained that the Vim script syntax is unexpectedly different from what they are used to. To reduce this complaint popular languages are used as an example. At the same time, we do not want to abandon the well-known parts of legacy Vim script. For many things TypeScript is followed. It's a recent language that is gaining popularity and has similarities with Vim script. It also has a mix of static typing (a variable always has a known value type) and dynamic typing (a variable can have different types, this changes at runtime). Since legacy Vim script is dynamically typed and a lot of existing functionality (esp. builtin functions) depends on that, while static typing allows for much faster execution, we need to have this mix in Vim9 script. There is no intention to completely match TypeScript syntax and semantics. We just want to take those parts that we can use for Vim and we expect Vim users will be happy with. TypeScript is a complex language with its own history, advantages and disadvantages. To get an idea of the disadvantages read the book: "JavaScript: The Good Parts". Or find the article "TypeScript: the good parts" and read the "Things to avoid" section. People familiar with other languages (Java, Python, etc.) will also find things in TypeScript that they do not like or do not understand. We'll try to avoid those things. Specific items from TypeScript we avoid: - Overloading "+", using it both for addition and string concatenation. This goes against legacy Vim script and often leads to mistakes. For that reason we will keep using ".." for string concatenation. Lua also uses ".." this way. And it allows for conversion to string for more values. - TypeScript can use an expression like '99 || "yes"' in a condition, but cannot assign the value to a boolean. That is inconsistent and can be annoying. Vim recognizes an expression with && or || and allows using the result as a bool. The |falsy-operator| was added for the mechanism to use a default value - see |vim9-falsy|. - TypeScript considers an empty string as Falsy, but an empty list or dict as Truthy. That is inconsistent. In Vim an empty list and dict are also Falsy. - TypeScript has various "Readonly" types, which have limited usefulness, since a type cast can remove the immutable nature. Vim locks the value, which is more flexible, but is only checked at runtime. - TypeScript has a complicated "import" statement that does not match how the Vim import mechanism works. A much simpler mechanism is used instead, which matches that the imported script is only sourced once. Declarations ~ Legacy Vim script uses `:let` for every assignment, while in Vim9 declarations are used. That is different, thus it's good to use a different command: `:var`. This is used in many languages. The semantics might be slightly different, but it's easily recognized as a declaration. Using `:const` for constants is common, but the semantics varies. Some languages only make the variable immutable, others also make the value immutable. Since "final" is well known from Java for only making the variable immutable we decided to use that. And then `:const` can be used for making both immutable. This was also used in legacy Vim script and the meaning is almost the same. What we end up with is very similar to Dart: > :var name # mutable variable and value :final name # immutable variable, mutable value :const name # immutable variable and value Since legacy and Vim9 script will be mixed and global variables will be shared, optional type checking is desirable. Also, type inference will avoid the need for specifying the type in many cases. The TypeScript syntax fits best for adding types to declarations: >vim9 vim9script var name: string # string type is specified name = 'John' const GREETING = 'Hello' # string type is inferred echo $'{GREETING} {name}' < This is how we put types in a declaration: >vim9 vim9script var vlist: list final flist: list = ['Vim'] def Func(arg1: string, arg2: number): string return $'{arg1}{arg2}' enddef vlist[0] = 9 echo Func(flist[0], vlist[0]) # Vim9 < These alternatives were considered: 1. Put the type before the name, like Dart: > var list mylist final list mylist = ['foo'] def Func(number arg1, string arg2) bool < 2. Put the type after the variable name, but do not use a colon, like Go: > var mylist list final mylist list = ['foo'] def Func(arg1 number, arg2 string) bool < The first is more familiar for anyone used to C or Java. The second one doesn't really have an advantage over the first, so let's discard the second. Since we use type inference the type can be left out when it can be inferred from the value. This means that after `var` we don't know if a type or a name follows. That makes parsing harder, not only for Vim but also for humans. Also, it will not be allowed to use a variable name that could be a type name, using `var string string` is too confusing. The chosen syntax, using a colon to separate the name from the type, adds punctuation, but it actually makes it easier to recognize the parts of a declaration. Expressions ~ Expression evaluation was already close to what other languages are doing. Some details are unexpected and can be improved. For example a boolean condition would accept a string, convert it to a number and check if the number is non-zero. This is unexpected and often leads to mistakes, since text not starting with a number would be converted to zero, which is considered false. Thus using a string for a condition would often not give an error and be considered false. That is confusing. In Vim9 type checking is stricter to avoid mistakes. Where a condition is used, e.g. with the `:if` command and the `||` operator, only boolean-like values are accepted: true: `true`, `v:true`, `1`, `0 < 9` false: `false`, `v:false`, `0`, `0 > 9` Note that the number zero is false and the number one is true. This is more permissive than most other languages. It was done because many builtin functions return these values, and changing that causes more problems than it solves. After using this for a while it turned out to work well. If you have any type of value and want to use it as a boolean, use the `!!` operator (see also |vim9-!!|): >vim9 vim9script # The following are all true: echo [!!'text', !![1], !!{'x': 1}, !!1, !!1.1] # And these are all false: echo [!!'', !![], !!{}, !!0, !!0.0] < From a language like JavaScript we have this handy construct: > GetName() || 'unknown' However, this conflicts with only allowing a boolean for a condition. Therefore the "??" operator was added: > GetName() ?? 'unknown' Here you can explicitly express your intention to use the value as-is and not result in a boolean. This is called the |falsy-operator| - see |vim9-falsy|. Import and Export ~ A problem of legacy Vim script is that by default all functions and variables are global. It is possible to make them script-local, but then they are not available in other scripts. This defies the concept of a package that only exports selected items and keeps the rest local. In Vim9 script a mechanism very similar to the JavaScript import and export mechanism is supported. It is a variant to the existing `:source` command that works like one would expect: - Instead of making everything global by default, everything is script-local, some of these are exported. - When importing a script the symbols that are imported are explicitly listed, avoiding name conflicts and failures if functionality is added later. - The mechanism allows for writing a big, long script with a very clear API: the exported functions, variables and classes. - By using relative paths loading can be much faster for an import inside of a package, no need to search many directories. - Once an import has been used, its items are cached and loading it again is not needed. - The Vim-specific use of "s:" to make things script-local can be dropped. When sourcing a Vim9 script (from either a Vim9 script or legacy Vim script), only the items defined globally can be used, not the exported items. Alternatives considered: - All the exported items become available as script-local items. This makes it uncontrollable what items get defined and likely soon leads to trouble. - Use the exported items and make them global. Disadvantage is that it's then not possible to avoid name clashes in the global namespace. - Completely disallow sourcing a Vim9 script, require using `:import`. That makes it difficult to use scripts for testing, or sourcing them from the command line to try them out. Note that you CAN also use `:import` in legacy Vim script, see above. Compiling functions early ~ Functions are compiled when called or when `:defcompile` is used. Why not compile them early, so that syntax and type errors are reported early? The functions can't be compiled right away when encountered, because there may be forward references to functions defined later. Consider defining functions A, B and C, where A calls B, B calls C, and C calls A again. It's impossible to reorder the functions to avoid forward references. An alternative would be to first scan through the file to locate items and figure out their type, so that forward references are found, and only then execute the script and compile the functions. This means the script has to be parsed twice, which is slower, and some conditions at the script level, such as checking if a feature is supported, are hard to use. An attempt was made to see if it works, but it turned out to be impossible to make work well. It would be possible to compile all the functions at the end of the script. The drawback is that if a function never gets called, the overhead of compiling it counts anyway. Since startup speed is very important, in most cases it's better to do it later and accept that syntax and type errors are only reported then. In case these errors should be found early, e.g. when testing, a `:defcompile` command at the end of the script will help out. Why not use an existing embedded language? ~ Vim supports interfaces to Perl, Python, Lua, Tcl and a few others. But these interfaces have never become widely used, for various reasons. When Vim9 was designed a decision was made to make these interfaces lower priority and concentrate on Vim script. Still, plugin writers may find other languages more familiar, want to use existing libraries or see a performance benefit. We encourage plugin authors to write code in any language and run it as an external process, using jobs and channels. We can try to make this easier somehow. Using an external tool also has disadvantages. An alternative is to convert the tool into Vim script. For that to be possible without too much translation, and keeping the code fast at the same time, the constructs of the tool need to be supported. Since Vim9 script now includes support for classes, objects, interfaces, and enums, that is increasingly feasible. vim:tw=78:ts=8:noet:ft=help:norl: