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:
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.
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):
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.
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:
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 ":
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:
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):
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:
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:
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:
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:
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:
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 #
In legacy Vim script, comments start with a quotation mark ("). In Vim9
script, comments start with a number sign (#).
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.
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:
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:
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:
" 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:
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:
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:
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:
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:
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:
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:
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):
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:
" 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:
vim9script
var dic: dict<list<number>> = {'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):
vim9script
class MyClass
var ln: list<number>
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:
vim9script
def DicLen(self: dict<any>, arg: string): number
return self[arg]->len()
enddef
var da: dict<any> = {func: DicLen, item: [0, 1, 2, 3]}
echo da.func(da, 'item') # 4
- Call a legacy Vim script dict function (Dictionary-function):
vim9script
function LegDicLen() dict
return self.item->len()
endfunc
def CallLegDicLen(): number
var da: dict<any> = {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:
vim9script
var avar: any
echo avar->typename() # number
avar = 'A string'
echo avar->typename() # string
avar = [['A', 'list'], ['of', 'lists']]
echo avar->typename() # list<list<string>>
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:
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:
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:
vim9script
def MyFirst(s: string, d: dict<string>, n: number,
...l: list<any>): string
return s .. d[n] .. l[1]
enddef
var MyDict: dict<string> = {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<any>") defined as
the last argument. In Vim9 script, variable arguments require a name and
list<type>, similar to TypeScript. This example iterates a variadic list
of numbers:
vim9script
def MyProduct(...ln: list<number>): 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:
vim9script
def F1055(n: number, ...): void # E1055: Missing name after ...
enddef
E1160
- Trying to use a default for a variable argument:
vim9script
def F1160(...l = []): void # E1160: Cannot use a default for variabl…
enddef
E1180
- Failing to declare a variable argument as a list<type>:
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:
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:
vim9script
var ln: list<number> = [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:
vim9script
final nl: list<number> = [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.
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:
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:
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:
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.
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()):
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):
vim9script
execute ('function cos()') # E1267: Function name must start with a …
vim9script
execute ('function s:cos()') # E1268: Cannot use s: in Vim9 script: …
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:
" 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()
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:
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:
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:
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:
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:
vim9script noclear
var MyList: list<number> = !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:
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:
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:
vim9script
var my_var: string = "string"
def g:Get_myvar(): void
echo my_var
enddef
g:Get_myvar()
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:
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:
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:
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:
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:
vim9script
# Create the YankHelpGrep command (to :helpgrep a visual selection)
command -register YankHelpGrep {
const SAVE = @"
normal! y
execute $"helpgrep {getreg('<register>')}"
@" = SAVE
copen
}
# Map YH in Visual mode to YankLhelpGrep
xnoremap YH <ScriptCmd>YankHelpGrep "<CR>
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:
vim9script
def F1025()
}
enddef
defcompile F1025 # E1025: Using } outside of a block scope
and
vim9cmd } # E1128: } without {
Errors given when incorrectly declaring or initializing a variable include:
E1017
vim9script
var F1017: func = (): void => {
var a: any
var a = 'error' # E1017: Variable already declared: a
}
E1020
vim9script
var x += 4 # E1020: Cannot use an operator on a new variable: x += 4
E1022
vim9script
var x # E1022: Type or initialization required
E1034
vim9script
var this = 'reserved' # E1034: Cannot use reserved name this
E1054
vim9script
var x: bool
var F1054: func = (): void => {
var x = 'no' # E1054: Variable already declared in the script: x
}
E1087
vim9script
var F1087: func = (): void => {
var x.y = 0 # E1087: Cannot use an index when declaring a variable
}
E1124
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:
vim9script
feedkeys(":vim9cmd var x = 0\<CR>")
# 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:
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<any> | var d: dict<any> |
\ var j: job | var c: channel | var z: blob | var t: tuple<any>
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:
vim9script
var myDict: dict<list<number>>
var myList: list<number>
myList->add(9)
myDict['version'] = myList
echo myDict # {'version': [9]}
Initializing a variable to a null value differs from initializing a variable
with "null_<type>". Particularly, null_dict, null_list, and null_blob
give errors when trying to add to/extend variables initialized to them:
- null_dict:
E1103
vim9script
var nd = null_dict
def F1103(): void
nd['a'] = 'fail' # E1103: Dictionary not set
enddef
F1103()
E1133
vim9script
var ed: dict<string> # An empty dict can be extended
ed->extend({'a': 'okay'})
echo ed # {'a': 'okay'}
var nd: dict<string> = null_dict
nd->extend({'a': 'fail'}) # E1133: Cannot extend a null_dict
- null_list:
E1147
vim9script
var nl = null_list
def F1147(): void
nl[0] = 'fail' # E1147: List not set
enddef
F1147()
E1130
vim9script
var el: list<string> # An empty list can be added to
el->add('okay')
echo el # ['okay']
var nl: list<string> = null_list
nl->add('fail') # E1130: Cannot add to null_list
E1134
vim9script
var el: list<string> # An empty list can be extended
el->extend(['okay'])
echo el # ['okay']
var nl: list<string> = null_list
nl->extend(['fail']) # E1134: Cannot extend a null_list
- null_blob:
E1581
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
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:
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:
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
vim9script
var t:err = 'err' # E1016: Cannot declare a tab variable: t:err
E1052
vim9script
var &ts = 8 # E1052: Cannot declare an option: &ts = 8
E1066
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.
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:
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:
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:
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
vim9script
def F1006(n: number): void
var n: number = 10 # E1006: n is used as an argument
enddef
F1006(9)
E1041
vim9script
def X(): void
enddef
var X: number # E1041: Redefining script item: "X"
E1167
vim9script
var ll: list<number> = [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
vim9script
var ll: list<number> = [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:
vim9script
const TMP: string = tempname()
var lines: list<string> = ['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):
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.
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:
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:
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":
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:
vim9script
var theList: list<string> = ['A', 'M', 'Z']
var [first, _, last] = theList # ignore the second item
echo $"{first} to {last}"
To ignore any remaining items, use "; _":
vim9script
def GetNameCountry(): list<string>
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:
vim9script
var one: tuple<...list<any>> = (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:
vim9script
var [v1; v2] = [8, 9, 10] # v2 has type list<number>
var [v3; v4] = (null, 'a', true) # v4 has type tuple<string, bool>
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:
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:
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.
vim9script
try
const MISSING_VAL: any
catch
echo v:exception # E1021: Const requires a value
endtry
def F1307(): void
const L: list<number> = [7, 8]
L->add(9) # E1307: Argument 1: Trying to modify a const list<number>
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:
vim9script
final ln: list<number> = [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<any> # 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:
vim9script
final females: list<string> = ['Martha']
const NAMES: list<list<string>> = [['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).
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:
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<number, number>
'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:
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:
vim9cmd !(900 == v:version)
Put the expression in parentheses to use the "!" for negation:
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:
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:
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:
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]:
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:
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.
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:
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:
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:
vim9script
var list: list<number> = [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:
vim9script
var list: list<number> = [1, -2, 2, -3, -1, 3]
filter(list,
\ (_,
\ val: number):
\ bool
\ => val > 0)
echowindow list
E1172
Default values are not allowed in a lambda:
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:
vim9script
b:fruits = ['apple', 'apricot', 'avocado']
def Complete(..._): list<string>
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<Tab> 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<any>" 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:
vim9script
var Get_bv: func = (...args: list<string>): dict<any> => {
var opts: dict<any>
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:
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:
vim9script
var numbers: list<number> = [1, 2, 3, 4, 5]
var Square: func = (ln: list<number>): list<number> => 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:
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):
vim9script
command MyHeredoc {
var someVar: list<string> =<< 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:
command FailingNewCommand {
g:mydict = {
'k1': 'v1',
'k2': 'v2'
}
}
To avoid this, place the dictionary's "}" after the last item:
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 }"):
vim9script
command C1026 {
vim9-curly
To avoid the "{" of a dictionary being recognized as a statement block, wrap
the dictionary in parentheses:
vim9script
var AgeDict: func = (arg: number): dict<number> => ({'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:
vim9script
command -nargs=+ PopDict {
var [key, val] = split(<q-args>)
({
[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:
vim9script
var mylist: list<number> = [
1,
2,
]
var mydict: dict<number> = {
1: 1,
2: 2,
}
var mytuple: tuple<number, number> = (
1,
2,
)
var MyDef: func = (...l: list<any>): list<any> => 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:
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:
vim9script
def Run5(ms: string): dict<any>
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<any> = 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:
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:
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':
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:
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):
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:
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):
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:
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:
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:
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:
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:
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:
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.
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:
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:
vim9script
windo echo 'hi'
->toupper() # 'HI' (current window) and 'hi' (for others)
So, in instances like this, the "\" continuation character must still be used:
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:
vim9script
const UNPACK: func = (a: string, b: string): list<string> => [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:
vim9script
echo [1,
2] [3,
4]
whereas this does not work (i.e., "[3, 4]" is not echoed):
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:
vim9script
var num = 234
White space is required:
E1004
- Before and after the "=" in variable declaration:
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:
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:
vim9script
var mylist: list<number> = [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):
vim9script
var okay_list: list<any> = ['Is', 'good']
var fail_list:list<any> = ['Is', 'a', 'fail'] # E1069: White space …
- Before the '#' starting a comment. If it isn't present, errors such as
E121 or E488 are given:
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:
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:
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:
vim9script
def F1068<T> (): 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:
vim9script
var tmp: string = $'{tempname()}.vim'->substitute('\\', '/', 'g')
var temp_lines: list<string> = ['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:
vim9script
def MyN(...arg: list<number>): 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:
vim9script
enum Metal
Au((79, 'Gold')),
Hg((80, 'Mercury'))
var data: tuple<number, string>
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:
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:
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:
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:
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:
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:
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:
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:
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:
vim9script
var dict: dict<bool>
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:
vim9script
var dict: dict<bool>
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:
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:
vim9script
var E1139 = {[0😢9]: 2} # E1139: Missing matching bracket after dict …
E1014
An invalid key gives E1014:
vim9script
# This tries to use an unquoted control code character, U+0007 (ALERT)
var E1014: dict<string> = {: '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:
vim9script
var dict: dict<string> = {[.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:
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:
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):
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:
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:
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:
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:
vim9script
var l1: list<any>
var l2: list<any> = 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:
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:
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:
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:
vim9script
enum Switch
On(['active', true]),
Off(['inactive', false])
final state: list<any>
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:
" 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:
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:
vim9script
var it: list<number>
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:
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:
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:
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<number> = [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<number> = [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:
vim9script
var lst: list<list<number>> = [[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:
" 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).
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:
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":
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:
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):
" 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:
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:
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:
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:
vim9script
var l: list<any> = [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:
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<any> []
null_dict v:t_dict dict<any> {}
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<Unknown> class [unknown]
null_object v:t_object object<any> object of [unknown]
null_tuple v:t_tuple tuple<any> ()
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_<type>" value is treated the same as an empty value only in some
cases. See null-details.
The following types do not have predefined "null_<type>" 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_<type>" values can be useful for clearing script-local variables
because they cannot be deleted with :unlet. For example:
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:
vim9script
def CheckMyList(l: list<number> = 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:
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.
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:
vim9script
echo 'très'[2] # è (U+00E8)
legacy echo 'très'[2] | # <c3> (Illegal byte 0xc3)
A negative index is counting from the end, "[-1]" is the last character.
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:
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):
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.
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:
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:
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:
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:
" legacy Vim script
let g = 97
echo 1000
% g / 9.7
" 1000 (then prints all lines containing '9.7' to messages)
whereas:
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:
" 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:
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:
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:
" legacy Vim script
let let = 8
echo let | " 8
:g:let = 8
" Prints lines matching 'let = 8' to messages
whereas:
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:
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:
g /[-:.]pattern/p | " This prints the three vim9cmd lines above
whereas in Vim9 script:
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):
vim9script
func Maybe()
if !has('ebcdic')
return 'yes'
endif
return [] + 'yes'
endfunc
echo Maybe() # yes
The equivalent Vim9 script gives E1051:
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:
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:
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:
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:
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:
vim9script
command -nargs=1 MyCommand echomsg <q-args>
def Works()
MyCommand 'this works'
enddef
Works()
This gives E476 for "MyCommandFails" not being defined at compile time:
vim9script
def Fails()
command -nargs=1 MyCommandFails echomsg <q-args>
MyCommandFails 'this fails'
enddef
Fails()
A workaround is to invoke the command indirectly with :execute, like this:
vim9script
def Works_Using_Execute()
command -nargs=1 MyCommandUsingExecute echomsg <q-args>
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:
vim9script
def F171()
if has('ebcdic') | Nah | endif
enddef
F171() # E171: Missing :endif
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:
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:
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:
vim9script
def F_1073()
enddef
def F_1073() # E1073: Name already defined: <SNR...
enddef
E1011
{name} must be less than 100 bytes long.
E1077
{arguments} is a sequence of zero or more argument
declarations. There are three forms:
{name}: {type}
{name} = {value}
{name}: {type} = {value}
The first form is a mandatory argument. So, the
declaration must provide a type. Example:
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:
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:
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:
vim9script
def F_1003(): bool
return # E1003: Missing return value
enddef
F_1003()
vim9script
def F_1027(): bool
echo false # E1027: Missing return statement
enddef
F_1027()
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:
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:
" Legacy Vim script :def! example
def! LegacyFunc()
echo "def! is allowed in a legacy Vim script"
enddef
call LegacyFunc()
vim9script
def F1117()
def! InnerFunc()
# E1117: Cannot use ! with nested :def
enddef
enddef
F1117()
vim9script
def! F_477(): void # E477: No ! allowed
enddef
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:
vim9script
def MyFunc()
echo 'Do Something' | enddef
# E1057: Missing :enddef
vim9script
def F_1173()
enddef echo 'X'
# E1173: Text found after enddef: echo 'X'
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:
" 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()
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()
" 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:
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:
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:
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):
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 <SNR>. Depending on options, including
wildmenumode(), completion may work with "s:", "<S", or the function
name directly. (For example, in Vim started with -u NONE,
":disa s:" and c_CTRL-E lists script-local function names.)
Limitations
Variables local to :def functions are not visible to string evaluation.
The following example shows that the script-local constant "SCRIPT_LOCAL" is
visible whereas the function-local constant "DEF_LOCAL" is not:
vim9script
const SCRIPT_LOCAL = ['A', 'script-local', 'list']
def MapList(scope: string): list<string>
const DEF_LOCAL: list<string> = ['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:
vim9script
def MapList(): list<string>
const DEF_LOCAL: list<string> = ['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:
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:
vim9script
var flist: list<func>
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:
vim9script
var flist: list<func>
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:
vim9script
def GetClosure(i: number): func
var infunc: number = i
return (): number => infunc
enddef
var flist: list<func>
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:
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:
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:
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:
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:
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:
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:
vim9cmd var l_1008: list
vim9cmd var l_1009: list<number
vim9cmd var l_1010: list<invalidtype>
vim9cmd var l_1012: list<number> = ['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:
vim9script
var l: list<number> = [1, 2]
var t: tuple<...list<number>> = (3, 4)
echo [l, t, [5, 6], (7, )]
tuple-type
A tuple type may be declared in the following ways:
tuple<number> a tuple with a single item of type Number
tuple<number, string> a tuple with two items of type Number and
String
tuple<number, float, bool> a tuple with three items of type Number,
Float and Boolean
tuple<...list<number>> a variadic tuple with zero or more items of
type Number
tuple<number, ...list<string>> a tuple with an item of type Number followed
by zero or more items of type String
Examples:
vim9script
var t1: tuple<number> = (20,)
var t2: tuple<number, string> = (30, 'vim')
var t3: tuple<number, float, bool> = (40, 1.1, true)
var t4: tuple<...list<string>> = ('a', 'b', 'c')
var t5: tuple<number, ...list<string>> = (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:
vim9script
var t6: tuple<...list<number>> = (1, 2, 3)
var t7: tuple<...list<string>> = ('a', 'b', 'c')
var t8: tuple<...list<bool>> = ()
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
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
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
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
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
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
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
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
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
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
vim9script
def L(...l: list<number>): void
echo l->reduce((x, y) => x + y)
enddef
const F: func(...list<number>): void = L->function()
F(8, 0, 0, 1)
func(...list<{type}>): {type}
- typed list for variable number of arguments
- returns a typed value
vim9script
def L(...l: list<number>): number
return l->reduce((x, y) => x + y)
enddef
const F: func(...list<number>): 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
vim9script
def D(a: float, ...l: list<number>): void
echo (a + l->reduce((x, y) => x + y))->float2nr()
enddef
const F: func(float, ...list<number>): 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
vim9script
def D(a: float, ...l: list<number>): number
return (a + l->reduce((x, y) => x + y))->float2nr()
enddef
const F: func(float, ...list<number>): 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:
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:
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:
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():
vim9script
type Ln = list<number>
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:
vim9script
type Ln = list<number>
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:
vim9script
interface Shape
def InfoArea(): tuple<string, float>
endinterface
class Circle implements Shape
var radius: float
def InfoArea(): tuple<string, float>
return ('Circle (π × r²)', 3.141593 * this.radius->pow(2))
enddef
endclass
class Square implements Shape
var side: float
def InfoArea(): tuple<string, float>
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> = Circle.new(INPUT)
var mySquare: object<Square> = Square.new(INPUT)
final shapes: list<Shape> = [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:
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<Quad>") 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<number> = [1, b:two]
Since Vim doesn't know the type of "b:two", the expression becomes list<any>.
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<number> = [1, <number>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<any>, then
verifies whether it can be assigned to the list<number> return type. With
funcref variable "TC", the type cast means Vim first checks whether "b:two" is
a <number> type:
vim9script
b:two = '2'
const NTC: func = (): list<number> => {
return [1, b:two]
}
disassemble NTC # 3 CHECKTYPE list<number> stack [-1]
try
NTC()
catch
echo v:exception .. "\n\n" # E1012: Type mismatch; Expected list...
endtry
const TC: func = (): list<number> => {
return [1, <number>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:
vim9script
# These type casts work
echo <list<any>>[3, 2, 1]->extend(['Go!'])
echo <string>[3, 2, 1]->extend(['Go!'])->string()
echo <tuple<...list<number>>>[3, 2, 1]->list2tuple()
# This type cast fails
echo <number>[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:
vim9script
var E1363 = null_class.member # E1363: Incomplete type
vim9script
def F1395(): void
echo null_class.member
enddef
F1395() # E1395: Using a null class
Another null object-related error is E1360:
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:
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:
vim9script
echo [1, 2]->typename() # list<number>
echo [1, 'x']->typename() # list<any>
echo {ints: [1, 2], bools: [false]}->typename() # dict<list<any>>
echo (true, false)->typename() # tuple<bool, bool>
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<func(...): void>":
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:
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:
vim9script
var lb = [true, true] # Two bools, so Vim infers list<bool> type
echo lb->typename() # list<bool>
lb->extend([0]) # E1013 Argument 2: type mismatch, ...
If you want a permissive list, either explicitly use <any> or declare an
empty list initially (or both, i.e., `list<any> = []`). Examples:
vim9script
final la: list<any> = []
echo la->extend(['two', 1])
final le = []
echo le->extend(la)
Similarly for a permissive dictionary:
vim9script
final da: dict<any> = {}
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:
vim9script
var t_any: tuple<...list<any>> = (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:
vim9script
echo [3, 2, 1]->typename() # list<number>
echo [3, 2, 1]->extend(['Zero'])->typename() # list<any>
echo {1: ['One']}->typename() # dict<list<string>>
echo {1: ['One']}->extend({2: [2]})->typename() # dict<list<any>>
Stricter type checking
type-checking
In legacy Vim script, where a number was expected, a string would be
automatically converted to a number. This was convenient for an actual number
such as "123", but leads to unexpected problems (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":
echo 123 == '123'
However, if an unintended space is included, "0" is echoed:
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:
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:
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:
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:
let $FOO = 123
vim9cmd $FOO = 123 # E1012: Type mismatch; expected string but ...
- Not using a number where a number is expected:
" 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
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:
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:
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:
echo exepath('')
vim9cmd echo exepath('') # E1175: Non-empty string required for ar...
- Not using a number when it is required:
echo gettabinfo('a')
vim9cmd echo gettabinfo('a') # E1210: Number required for argument 1
- Not using a bool when it is required:
echo char2nr('¡', 2)
vim9cmd echo char2nr('¡', 2) # E1212: Bool required for argument 2
- Not using a number when a number is required (E521):
let &laststatus='2'
vim9cmd &laststatus = '2'
- Not using a string when a string is required (E928):
let &langmenu = 42
vim9cmd &langmenu = 42 # E928: String required
- Comparing a Special with "is" often fails (E1037, E1072):
" 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):
vim9script
echo v:null is 8 # false
echo true is v:null # false
- Using a string where a bool is required (E1135):
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):
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:
" 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:
vim9script
var mylist = [0, 1] # Vim infers mylist is list<number>
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:
vim9script
var mylist = [0, 1]
var infer = mylist->mapnew((i, _) => $"item {i}")
echo [infer, infer->typename()]
var declare: list<string> = 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:
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 "<any>", 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:
vim9script
# list<any>
var mylist = [1, '2'] # mixed types, i.e., list<any>
echo (mylist, mylist->typename()) # ([1, '2'], 'list<any>')
mylist->map((_, v) => $"item {v}") # all items are now strings
echo (mylist, mylist->typename()) # both strings, but list<any>
# mapnew()
var newlist = mylist->mapnew((_, v) => v)
echo (newlist, newlist->typename()) # newlist is a list<string>
Using extend() and extendnew() is similar, i.e., a list literal may use
the former, so, this is okay:
vim9cmd echo [1, 2]->extend(['3']) # [1, 2, '3']
whereas, this is not:
vim9script
var mylist: list<number> = [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:
vim9script
var mylist: list<number> = [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():
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:
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):
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:
vim9script
var Fproduct: func(...list<number>): number
Fproduct = (...v: list<number>): number => reduce(v, (a, b) => a * b)
echo Fproduct(3, 2, 4) # 24
And <any> may be used to accommodate mixed types:
vim9script
var FlatSort: func(...list<any>): any
FlatSort = (...v: list<any>) => flattennew(v)->sort('n')
echo FlatSort(true, [[[5, 3], 2], 4]) # [true, 2, 3, 4, 5]
Note: Using <any> 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:
vim9script
var FuncSN: func(string): number
FuncSN = (v: any): number => v->str2nr()
echo FuncSN('162')->nr2char() # ¢
echo FuncSN(162)->nr2char() # E1013 (a runtime error)
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:
vim9script
var FlexArgs: func: string
FlexArgs = (s: string): string => $"It's countdown time {s}..."
echo FlexArgs("everyone")
FlexArgs = (...values: list<string>): 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 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:
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:
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<string> | echo [l, l->empty(), l == null] # [[], 1, false]
var t: tuple<any> | echo [t, t->empty(), t == null] # [(), 1, false]
var d: dict<number> | echo [d, d->empty(), d == null] # [{}, 1, false]
Specialized types default to equaling null:
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_<type>
predefined values including null_string, null_list, and null_job.
Primitives do not have a null_<type>. Typical use cases for null_<type> are:
- to clear a variable and release its resources,
- as a default for a parameter in a function definition (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_<type> is used to clear the
resources. For example:
vim9script
var mydate: list<string>
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:
vim9script
var perfect: list<number> = [1, 4]
perfect->extend([9, 16, 25])
perfect = []
echo perfect
Using an empty container, rather than null_<type>, 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_<type> 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).
vim9script
# uninitialized: empty container, not null
var lu: list<any>
echo ['lu', $"empty={lu->empty()}", $"null={lu == null}"]
# initialized: empty container, not null
var li: list<any> = []
echo ['li', $"empty={li->empty()}", $"null={li == null}"]
# initialized: empty container, null
var ln: list<any> = null_list
echo ['ln', $"empty={ln->empty()}", $"null={ln == null}"]
Specialized variables default to equaling null. These job initializations
are equivalent and indistinguishable:
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":
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_<type> in a comparison. That is because,
in Vim9 script, although null_<type> == null, comparing an:
- empty container to null is false, but
- empty container to null_<type> is true.
So, compare against null, not null_<type>. For example:
vim9script
var bonds: dict<list<string>> = {g: ['007', '008'], o: ['007', '009']}
def Search(query: string): list<string>
return query == "\r" ? null_list : bonds->get(query, [])
enddef
echo "Goldfinger (g) or Octopussy (o)?: "
const C: string = getcharstr()
var result: list<string> = 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_<type> 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_<type>; 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_<type> 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:
vim9script
var le: list<any> = []
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_<type> containers, and empty. To recap, for example:
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:
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_<type> with "is", they return false:
vim9script
var d: dict<any>
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_<type> counterparts, as this example shows:
vim9script
var t: tuple<any>
echo t == null_tuple # true
echo t is null_tuple # false
However, a variable initialized to the null_<type> is equal not only to the
null_<type>, it is also equal to null. For example:
vim9script
var t: tuple<any> = 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:
vim9script
var b: blob | echo b != null
var d: dict<any> | echo d != null
var l: list<any> | echo l != null
var t: tuple<any> | echo t != null
var s: string | echo s == null
An uninitialized specialized variable is equal to null. So, these all
echo true:
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_<type>, so these are all
true:
vim9script
var s: string = "" | echo s == null_string
var b: blob = 0z | echo b == null_blob
var l: list<any> = [] | echo l == null_list
var t: tuple<any> = () | echo t == null_tuple
var d: dict<any> = {} | echo d == null_dict
However, a container variable initialized to empty does not equal null, so
these are all true:
vim9script
var s: string = "" | echo s != null
var b: blob = 0z | echo b != null
var l: list<any> = [] | echo l != null
var t: tuple<any> = () | echo t != null
var d: dict<any> = {} | 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:
vim9script
def Zip<T, U>(first: list<T>, second: list<U>): list<tuple<T, U>>
const LEN: number = ([first->len(), second->len()])->min()
final result: list<tuple<T, U>> = []
for i in range(LEN)
result->add((first[i], second[i]))
endfor
return result
enddef
var n: list<number> = [61, 62, 63]
var s: list<string> = ['a', 'b', 'c']
echo $"Zip example #1: {Zip<number, string>(n, s)}"
echo $"Zip example #2: {Zip<string, number>(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:
vim9script
def MyFail<Ok, n>(): 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:
vim9script
My1558<number>()
# E1558: Unknown generic function: My1558
vim9script
def My1560(): void
enddef
My1560<string>()
# E1560: Not a generic function: My1560
E1561
Type parameter names must not clash with other identifiers:
vim9script
def My1561<D, E, D>(): D
enddef
# E1561: Duplicate type variable name: D
vim9script
enum E
Yes, No
endenum
def My1041<E>(): 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<number, string, list<number>>()
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:
vim9script
def My1555<>(): void
enddef # E1555: Empty type list specified for generic function '<S...
vim9script
def My1556<T>(): void
enddef
My1556<bool, bool>() # E1556: Too many types specified for generic...
vim9script
def My1557<T, U>(): void
enddef
My1557<bool>() # E1557: Not enough types specified for generic fun...
vim9script
def My1559<T>(): T
enddef
My1559() # E1559: Type arguments missing for generic function '<SN...
Any Vim9 type (vim9-types) can be used as a concrete type in a generic
function.
Spaces are not allowed:
- Between the function name and "<" (E1068)
- Between ">" 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:
vim9script
def Outer(): void
# Returns either the first item of a list or a default value
def FirstOrDefault<T, U>(lst: list<T>, default: U): any
return lst->len() > 0 ? lst[0] : default
enddef
echo FirstOrDefault<string, bool>(['B', 'C'], false) # B
echo FirstOrDefault<number, number>([], 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:
vim9script
# T is declared as a type parameter
# It is used for the 'value' parameter and the return type
def Id<T>(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<U>(value: U): U
# U is a type variable passed/used as a type argument
return Id<U>(value)
enddef
echo CallId<string>('I am') .. ' ' .. CallId<number>(42)
This is useful for complex data structures like dictionaries of lists or,
as in the following example, lists of dictionaries:
vim9script
def Flatten<T>(x: list<list<T>>): list<T>
final result: list<T> = []
for inner in x
result->extend(inner)
endfor
return result
enddef
const ENGLISH: list<dict<string>> = [{1: 'one'}, {2: 'two'}]
const MANDARIN: list<dict<string>> = [{1: '壹'}, {2: '贰'}]
const ARABIC_N: list<dict<number>> = [{1: 1}, {2: 2}]
echo Flatten<dict<string>>([ENGLISH, MANDARIN])
echo Flatten<dict<any>>([ENGLISH, ARABIC_N])
In "Flatten<T>", "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:
vim9script
class Config
var settings: dict<any>
def Get<T>(key: string): T
return this.settings[key]
enddef
endclass
var c: Config = Config.new({timeout: 30, debug: true})
echo c.Get<number>('timeout')
echo c.Get<bool>('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:
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<string, string> = (c, c->char2nr()->string())
def Matcher<T>(pattern: string): func(T): bool
return (value: T): bool => match(value, pattern) >= 0
enddef
var StringMatch = Matcher<string>(char_dec[0])
echo "*+"->StringMatch() # true (has *)
echo ",-"->StringMatch() # false
var ListMatch = Matcher<list<number>>(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<number, list<number>, dict<string>>
The :disassemble command can be used to list the instructions generated for
a generic function:
disassemble MyFunc<string, dict<string>>
disassemble MyFunc<number, list<blob>>
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:
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:
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:
" _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:
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:
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:
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:
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:
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:
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).
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}:
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:
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:
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:
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:
vim9script
const TMP: string = $'{tempname()}.vim'->substitute('\\', '/', 'g')
var lines: list<string> = ['vim9script', $'import "{TMP}" as e1088']
lines->writefile(TMP)
import TMP # E1088: Script cannot import itself
E1236
- Trying to use the script itself:
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":
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:
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:
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:
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:
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):
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 <SID>:
noremap <silent> ,a :call <SID>name.Function()<CR>
When the mapping is defined "<SID>name." will be replaced with <SNR> and the
script ID of the imported script.
An even simpler solution is using <ScriptCmd>:
noremap ,a <ScriptCmd>name.Function()<CR>
Note that this does not work for variables, only for functions.
This self-contained example demonstrates using <ScriptCmd>, creating and
writing a temporary script, which is then imported and the function
"exported.MyDef()" mapped to <leader>a:
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 <leader>a <ScriptCmd>exported.MyDef()<CR>
# Now, pressing <leader>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:
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 <SID> in the legacy mapping context. Since
<SID> is only a valid prefix for a function and NOT for a namespace, you
cannot use it to scope a function in a script-local namespace. Instead of
prefixing the function with <SID> you should use <ScriptCmd>.
For example:
noremap ,a <ScriptCmd>:call s:that.OtherFunc()<CR>
:import-cycle
The import commands are executed when encountered. If script A imports
script B, and B (directly or indirectly) imports A, this will be skipped over.
At this point items in A after "import B" will not have been processed and
defined yet. Therefore cyclic imports can exist and not result in an error
directly, but may result in an error for items in A after "import B" not being
defined. This does not apply to autoload imports, see the next section.
Importing an autoload script
vim9-autoload import-autoload
For optimal startup speed, loading scripts should be postponed until they are
actually needed. Using the autoload mechanism is recommended:
E1264
1. In the plugin, define user commands, functions and/or mappings
referring to items imported from an autoload script.
import autoload 'for/search.vim'
command -nargs=1 SearchForStuff search.Stuff(<f-args>)
This goes in .../plugin/anyname.vim. "anyname.vim" can be freely
chosen. The "SearchForStuff" command is now available to the user.
The "autoload" argument to :import means that the script is not
loaded until one of the items is actually used. The script will be
found under the "autoload" directory in 'runtimepath' instead of the
"import" directory. Alternatively, 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
<ScriptCmd> is useful. It allows for a command in a mapping to use the
script context of where the mapping was defined.
When compiling a :def function and a function in an autoload script is
encountered, the script is not loaded until the :def function is called.
This also means you get any errors only at runtime, since the argument and
return types are not known yet. If you would use the name with '#' characters
then the autoload script IS loaded.
Be careful to not refer to an item in an autoload script that does trigger
loading it unintentionally. For example, when setting an option that takes a
function name, make sure to use a string, not a function reference:
import autoload 'qftf.vim'
&quickfixtextfunc = 'qftf.Func' # autoload script NOT loaded
&quickfixtextfunc = qftf.Func # autoload script IS loaded
On the other hand, it can be useful to load the script early, at a time when
any errors should be given.
For testing the test_override() function can be used to have the
`import autoload` load the script right away, so that the items and types can
be checked without waiting for them to be actually used:
test_override('autoload', 1)
Reset it later with:
test_override('autoload', 0)
Or:
test_override('ALL', 0)
==============================================================================
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:
vim9script
echo 9223372036854775807 + 1 # -9223372036854775808
echo 2->pow(63)->float2nr() + 1 # -9223372036854775808
The syntax for types, using <type> for compound types, is similar to Java.
It is easy to understand and widely used. The type names are what were used
in Vim before, with some additions such as "void" and "bool".
Removing clutter and weirdness
Once decided that :def functions have different syntax than legacy
functions, we are free to add improvements to make the code more familiar for
users who know popular programming languages. In other words: remove weird
things that only Vim does.
We can also remove clutter, mainly things that were done to make Vim script
backwards compatible with the good old Vi commands.
Examples:
- Drop :call for calling a function and :eval for evaluating an
expression.
- Drop using a leading backslash for line continuation, automatically figure
out where an expression ends.
However, this does require that some things need to change:
- Comments start with # instead of ", to avoid confusing them with strings.
This is good anyway, it is also used by several popular languages.
- Ex command ranges need to be prefixed with a colon, to avoid confusion with
expressions (single quote can be a string or a mark, "/" can be divide or a
search command, etc.).
Goal is to limit the differences. A good criteria is that when the old syntax
is accidentally used you are very likely to get an error message.
Syntax and semantics from popular languages
Script writers have complained that the Vim script syntax is unexpectedly
different from what they are used to. To reduce this complaint popular
languages are used as an example. At the same time, we do not want to abandon
the well-known parts of legacy Vim script.
For many things TypeScript is followed. It's a recent language that is
gaining popularity and has similarities with Vim script. It also has a
mix of static typing (a variable always has a known value type) and dynamic
typing (a variable can have different types, this changes at runtime). Since
legacy Vim script is dynamically typed and a lot of existing functionality
(esp. builtin functions) depends on that, while static typing allows for much
faster execution, we need to have this mix in Vim9 script.
There is no intention to completely match TypeScript syntax and semantics. We
just want to take those parts that we can use for Vim and we expect Vim users
will be happy with. TypeScript is a complex language with its own history,
advantages and disadvantages. To get an idea of the disadvantages read the
book: "JavaScript: The Good Parts". Or find the article "TypeScript: the good
parts" and read the "Things to avoid" section.
People familiar with other languages (Java, Python, etc.) will also find
things in TypeScript that they do not like or do not understand. We'll try to
avoid those things.
Specific items from TypeScript we avoid:
- Overloading "+", using it both for addition and string concatenation. This
goes against legacy Vim script and often leads to mistakes. For that reason
we will keep using ".." for string concatenation. Lua also uses ".." this
way. And it allows for conversion to string for more values.
- TypeScript can use an expression like '99 || "yes"' in a condition, but
cannot assign the value to a boolean. That is inconsistent and can be
annoying. Vim recognizes an expression with && or || and allows using the
result as a bool. The falsy-operator was added for the mechanism to use a
default value - 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:
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:
vim9script
var vlist: list<number>
final flist: list<string> = ['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<string> mylist
final list<string> mylist = ['foo']
def Func(number arg1, string arg2) bool
2. Put the type after the variable name, but do not use a colon, like Go:
var mylist list<string>
final mylist list<string> = ['foo']
def Func(arg1 number, arg2 string) bool
The first is more familiar for anyone used to C or Java. The second one
doesn't really have an advantage over the first, so let's discard the second.
Since we use type inference the type can be left out when it can be inferred
from the value. This means that after var we don't know if a type or a name
follows. That makes parsing harder, not only for Vim but also for humans.
Also, it will not be allowed to use a variable name that could be a type name,
using `var string string` is too confusing.
The chosen syntax, using a colon to separate the name from the type, adds
punctuation, but it actually makes it easier to recognize the parts of a
declaration.
Expressions
Expression evaluation was already close to what other languages are doing.
Some details are unexpected and can be improved. For example a boolean
condition would accept a string, convert it to a number and check if the
number is non-zero. This is unexpected and often leads to mistakes, since
text not starting with a number would be converted to zero, which is
considered false. Thus using a string for a condition would often not give an
error and be considered false. That is confusing.
In Vim9 type checking is stricter to avoid mistakes. Where a condition is
used, e.g. with the :if command and the || operator, only boolean-like
values are accepted:
true: true, v:true, 1, `0 < 9`
false: false, v:false, 0, `0 > 9`
Note that the number zero is false and the number one is true. This is more
permissive than most other languages. It was done because many builtin
functions return these values, and changing that causes more problems than it
solves. After using this for a while it turned out to work well.
If you have any type of value and want to use it as a boolean, use the !!
operator (see also 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: