vim9.txt For Vim version 9.2. Last change: 2026 Aug 21
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 150 sourceable scripts.
For a short primer on Vim9 script, other resources may be helpful too, e.g.,
https://learnxinyminutes.com/vim9script/.
1. What is Vim9 script? Vim9-script
2. Differences vim9-differences
3. New style functions fast-functions
4. Types vim9-types
5. Generic functions generic-functions
6. Namespace, Import and Export vim9script
7. Classes and interfaces vim9-classes
8. Rationale vim9-rationale
------------------------------------------------------------------------------
NOTE: In this vim9.txt help file, the Vim9 script code blocks beginning with
vim9script (and individual lines starting with vim9cmd) are Vim9 script
syntax highlighted. Also, they are sourceable, meaning you can run them to
see what they output. To source them, use :'<,'>source (see :source-range),
which is done by visually selecting the line(s) with V and typing :so.
For example, try it on the following Vim9 script:
>vim9
vim9script
echowindow "Welcome to Vim9 script!"
<
There are also code examples that should not be sourced - they explain
concepts that don't require a sourceable example. Such code blocks appear
in generic code syntax highlighting, like this:
==============================================================================
1. What is Vim9 script? Vim9-script
Vim script has been growing over time, while preserving backwards
compatibility. That means bad choices from the past often can't be changed
and compatibility with Vi restricts possible solutions. Execution is quite
slow, each line is parsed every time it is executed.
The main goal of Vim9 script is to drastically improve performance. This is
accomplished by compiling commands into instructions that can be efficiently
executed. An increase in execution speed of 10 to 100 times can be expected.
A secondary goal is to avoid Vim-specific constructs and get closer to
commonly used programming languages, such as JavaScript, TypeScript and Java.
The performance improvements can only be achieved by not being 100% backwards
compatible. For example, making function arguments available in the "a:"
dictionary adds quite a lot of overhead. In a Vim9 function this dictionary
is not available. Other differences are more subtle, such as how errors are
handled.
Vim9 script syntax, semantics, and behavior apply in:
- a function defined with the :def command
- a script file where the first command is vim9script
- an autocommand defined in the context of the above
- a command prefixed with the vim9cmd command modifier
When using :function in a Vim9 script file the legacy syntax is used, with
the highest scriptversion. However, this can be confusing and is therefore
discouraged.
Vim9 script and legacy Vim script can be mixed. There is no requirement to
rewrite old scripts, they keep working as before. You may want to use a few
:def functions for code that needs to be fast.
:vim9[cmd] {cmd} :vim9 :vim9cmd
Evaluate and execute {cmd} using Vim9 script syntax,
semantics, and behavior. Useful when typing a command,
in a :function, or a legacy Vim script.
The following short example shows how a legacy Vim script
command and a :vim9cmd (so Vim9 script context) may appear
similar, though may differ not just syntactically, but also
semantically and behaviorally.
>vim
call popup_notification('entrée'[5:]
\ ->str2list()->string(), #{time: 7000})
vim9cmd popup_notification('entrée'[5 :]
->str2list()->string(), {time: 7000})
<
Notes: 1. The reason for the different output is Vim9 script
uses character indexing whereas legacy Vim script uses byte
indexing - see vim9-string-index.
2. Syntax is different too. In Vim9 script:
- The space in "[5 :]" is mandatory (see vim9-white-space).
- Line continuation with "\" is not required.
- The "#" (to avoid putting quotes around dictionary keys) is
neither required nor allowed - see #{}.
E1164
:vim9cmd cannot stand alone; it must be followed by a command.
:leg[acy] {cmd} :leg :legacy
Evaluate and execute {cmd} using legacy Vim script syntax,
semantics, and behavior. It is only applicable in a Vim9
script or a :def function. Using an equivalent script to
the one, above (see its notes for why the output differs):
>vim9
vim9script
# In legacy Vim script context the popup is [769, 101]
legacy call popup_notification('entrée'[5:]
\ ->str2list()->string(), #{time: 7000})
# In Vim9 script context the popup is [101]
popup_notification('entrée'[5 :]
->str2list()->string(), {time: 7000})
<
Vim9 script's script-local variables may be used by prefixing
"s:", like in legacy Vim script. This example shows the
difference in syntax: "k" for the script-local variable in
Vim9 script, "s:k" in the legacy Vim script context.
>vim9
vim9script
var k: string = "Okay"
echo k
legacy echo s:k
<
E1189
Using :legacy is not allowed in compiled Vim9 script
control flow contexts. For example:
>vim9
vim9script
def F_1189()
if v:version == 900
# E1189: Cannot use :legacy with this command: endif
legacy endif
enddef
F_1189()
< E1234
:legacy cannot stand alone; it must be followed by a command.
==============================================================================
2. Differences from legacy Vim script vim9-differences
Overview
E1146
Brief summary of the differences you will most often encounter when using Vim9
script and :def functions; details are below:
- Comments start with #, not ":
see vim9-white-space.
- Assign values without :let E1126 , declare variables with :var:
- Variables and functions are script-local by default.
- Functions are declared with argument types and return type:
:Print
:append
:change
:d directly followed by 'd' or 'p'.
:insert
:k
:mode
:open
:s with only flags
:t
:xit
- Some commands, especially those used for flow control, cannot be shortened.
E.g., :throw cannot be written as :th. vim9-no-shorten
- You cannot use curly-braces names.
- A range before a command must be prefixed with a colon:
:exe:
- When defining an expression mapping, the expression will be evaluated in the
context of the script where it was defined.
- When indexing a string the index is counted in characters, not bytes:
vim9-string-index
- Some possibly unexpected differences: vim9-gotchas.
Comments starting with #
In legacy Vim script comments start with double quote. In Vim9 script
comments start with #.
The reason is that a double quote can also be the start of a string. In many
places, especially halfway through an expression with a line break, it's hard
to tell what the meaning is, since both a string and a comment can be followed
by arbitrary text. To avoid confusion only # comments are recognized. This
is the same as in shell scripts and Python programs.
In Vi # is a command to list text with numbers. In Vim9 script you can use
:number for that.
To improve readability there must be a space between a command and the #
that starts a comment:
Do not start a comment with #{, it looks like the legacy dictionary literal
and produces an error where this might be confusing. #{{ or #{{{ are OK,
these can be used to start a fold.
When starting to read a script file Vim doesn't know it is Vim9 script until
the vim9script command is found. Until that point you would need to use
legacy comments:
That looks ugly, better put vim9script in the very first line:
In legacy Vim script # is also used for the alternate file name. In Vim9
script you need to use %% instead. Instead of ## use %%% (stands for all
arguments).
Vim9 functions
E1099
A function defined with :def is compiled. Execution is many times faster,
often 10 to 100 times.
Many errors are already found when compiling, before the function is executed.
The syntax is strict, to enforce code that is easy to read and understand.
Compilation is done when any of these is encountered:
- the first time the function is called
- when the :defcompile command is encountered in the script after the
function was defined
- :disassemble is used for the function.
- a function that is compiled calls the function or uses it as a function
reference (so that the argument and return types can be checked)
E1091 E1191
If compilation fails it is not tried again on the next call, instead this
error is given: "E1091: Function is not compiled: {name}".
Compilation will fail when encountering a user command that has not been
created yet. In this case you can call execute() to invoke it at runtime.
:def has no options like :function does: "range", "abort", "dict" or
"closure". A :def function always aborts on an error (unless :silent! was
used for the command or the error was caught a :try block), does not get a
range passed, cannot be a "dict" function, and can always be a closure.
vim9-no-dict-function E1182
You can use a Vim9 Class (Vim9-class) instead of a "dict function".
You can also pass the dictionary explicitly:
You can call a legacy dict function though:
The argument types and return type need to be specified. The "any" type can
be used, type checking will then be done at runtime, like with legacy
functions.
E1106
Arguments are accessed by name, without "a:", just like any other language.
There is no "a:" dictionary or "a:000" list.
vim9-variable-arguments E1055 E1160 E1180
Variable arguments are defined as the last argument, with a name and have a
list type, similar to TypeScript. For example, a list of numbers:
When a function argument is optional (it has a default value) passing v:none
as the argument results in using the default value. This is useful when you
want to specify a value for an argument that comes after an argument that
should use its default value. Example:
vim9-ignored-argument E1181
The argument "_" (an underscore) can be used to ignore the argument. This is
most useful in callbacks where you don't need it, but do need to give an
argument to match the call. E.g. when using map() two arguments are passed,
the key and the value, to ignore the key:
be given.
Functions and variables are script-local by default
vim9-scopes
When using :function or :def to specify a new function at the script level
in a Vim9 script, the function is local to the script. Like prefixing "s:" in
legacy script. To define a global function or variable the "g:" prefix must
be used. For functions in a script that is to be imported and in an autoload
script "export" needs to be used for those to be used elsewhere.
When using :function or :def to specify a nested function inside a :def
function and no namespace was given, this nested function is local to the code
block it is defined in. It cannot be used in function() with a string
argument, pass the function reference itself:
Detail: this is because "Inner" will actually become a function reference to a
function with a generated name.
It is not possible to define a script-local function in a function. You can
define a local function and assign it to a script-local Funcref (it must have
been declared at the script level). It is possible to define a global
function by using the "g:" prefix.
When referring to a function and no "s:" or "g:" prefix is used, Vim will
search for the function:
- in the function scope, in block scopes
- in the script scope
Imported functions are found with the prefix from the :import command.
Since a script-local function reference can be used without "s:" the name must
start with an upper case letter even when using the "s:" prefix. In legacy
script "s:funcref" could be used, because it could not be referred to with
"funcref". In Vim9 script it can, therefore "s:Funcref" must be used to avoid
that the name interferes with builtin functions.
vim9-s-namespace E1268
The use of the "s:" prefix is not supported at the Vim9 script level. All
functions and variables without a prefix are script-local.
In :def functions the use of "s:" depends on the script: Script-local
variables and functions in a legacy script do use "s:", while in a Vim9 script
they do not use "s:". This matches what you see in the rest of the file.
In legacy functions the use of "s:" for script items is required, as before.
No matter if the script is Vim9 or legacy.
In all cases the function must be defined before used. That is when it is
called, when :defcompile causes it to be compiled, or when code that calls
it is being compiled (to figure out the return type).
The result is that functions and variables without a namespace can usually be
found in the script, either defined there or imported. Global functions and
variables could be defined anywhere (good luck finding out where! You can
often see where it was last set using :verbose).
E1102
Global functions can still be defined and deleted at nearly any time. In
Vim9 script script-local functions are defined once when the script is sourced
and cannot be deleted or replaced by itself (it can be by reloading the
script).
When compiling a function and a function call is encountered for a function
that is not (yet) defined, the FuncUndefined autocommand is not triggered.
You can use an autoload function if needed, or call a legacy function and have
FuncUndefined triggered there.
Reloading a Vim9 script clears functions and variables by default
vim9-reload E1149 E1150
When loading a legacy Vim script a second time nothing is removed, the
commands will replace existing variables and functions, create new ones, and
leave removed things hanging around.
When loading a Vim9 script a second time all existing script-local functions
and variables are deleted, thus you start with a clean slate. This is useful
if you are developing a plugin and want to try a new version. If you renamed
something you don't have to worry about the old name still hanging around.
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 items, use:
You want to use this in scripts that use a finish command to bail out at
some point when loaded again. E.g. when a buffer local option is set to a
function, the function does not need to be defined more than once:
Variable declarations with :var, :final and :const
vim9-declaration :var E1079
E1017 E1020 E1054 E1087 E1124
Local variables need to be declared with :var. Local constants need to be
declared with :final or :const. We refer to both as "variables" in this
section.
Variables can be local to a script, function or code block:
The variables are only visible in the block where they are defined and nested
blocks. Once the block ends the variable is no longer accessible:
The declaration must be done earlier:
Although this is shorter and faster for simple values:
To intentionally hide a variable from code that follows, a block can be
used:
This is especially useful in a user command:
And with autocommands:
Although using a :def function probably works better.
E1022 E1103 E1130 E1131 E1133
E1134 E1581
Declaring a variable with a type but without an initializer will initialize to
false (for bool), empty (for string, list, dict, etc.) or zero (for number,
any, etc.). This matters especially when using the "any" type, the value will
default to the number zero. For example, when declaring a list, items can be
added:
Initializing a variable to a null value, e.g. null_list, differs from not
initializing the variable. This throws an error:
E1016 E1052 E1066
In Vim9 script :let cannot be used. An existing variable is assigned to
without any command. The same for global, window, tab, buffer and Vim
variables, because they are not really declared. Those can also be deleted
with :unlet.
E1065
You cannot use :va to declare a variable, it must be written with the full
name :var. Just to make sure it is easy to read.
E1178
:lockvar does not work on local variables. Use :const and :final
instead.
The exists() and exists_compiled() functions do not work on local variables
or arguments.
E1006 E1041 E1167 E1168 E1213
Variables, functions and function arguments cannot shadow previously defined
or imported variables and functions in the same script file.
Variables may shadow Ex commands, rename the variable if needed.
Global variables must be prefixed with "g:", also at the script level.
Global functions must be prefixed with "g:":
vim9-function-defined-later
Although global functions can be called without the "g:" prefix, they must
exist when compiled. By adding the "g:" prefix the function can be defined
later. Example:
If you do it like this, you get an error at compile time that "PluginFunc"
does not exist, even when "g:loaded_plugin" does not exist:
You can use exists_compiled() to avoid the error, but then the function would
not be called, even when "g:loaded_plugin" is defined later:
Since &opt = value is now assigning a value to option "opt", ":&" cannot be
used to repeat a :substitute command.
vim9-unpack-ignore
For an unpack assignment the underscore can be used to ignore a list item,
similar to how a function argument can be ignored:
Declaring more than one variable at a time, using the unpack notation, is
possible. Each variable can have a type or infer it from the value:
line is much easier to read and change later.
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:
gets type "any".
Constants
vim9-const vim9-final
How constants work varies between languages. Some consider a variable that
can't be assigned another value a constant. JavaScript is an example. Others
also make the value immutable, thus when a constant uses a list, the list
cannot be changed. In Vim9 we can use both.
E1021 E1307
:const is used for making both the variable and the value a constant. Use
this for composite structures that you want to make sure will not be modified.
Example:
:final is used for making only the variable a constant, the value can be
changed. This is well known from Java. Example:
It is common to write constants as ALL_CAPS, but you don't have to.
The constant only applies to the value itself, not what it refers to.
Omitting :call and :eval
E1190
Functions can be called without :call:
A method call without eval is possible, so long as the start is an
identifier or can't be an Ex command. For a function either "(" or "->" must
be following, without a line break. Examples:
In the rare case there is ambiguity between a function name and an Ex command,
prepend ":" to make clear you want to use the Ex command. For example, there
is both the :substitute command and the substitute() function. When the
line starts with substitute( this will use the function. Prepend a colon to
use the command instead:
If the expression starts with "!" this is interpreted as a shell command, not
negation of a condition. Thus this is a shell command:
Note that while variables need to be defined before they can be used,
functions can be called before being defined. This is required to allow
for cyclic dependencies between functions. It is slightly less efficient,
since the function has to be looked up by name. And a typo in the function
name will only be found when the function is called.
Omitting function()
A user defined function can be used as a function reference in an expression
without function(). The argument types and return type will then be checked.
The function must already have been defined.
When using function() the resulting type is "func", a function with any
number of arguments and any return type (including void). The function can be
defined later if the argument is in quotes.
Lambda using => instead of ->
vim9-lambda
In legacy script there can be confusion between using "->" for a method call
and for a lambda. Also, when a "{" is found the parser needs to figure out if
it is the start of a lambda or a dictionary, which is now more complicated
because of the use of argument types.
To avoid these problems Vim9 script uses a different syntax for a lambda,
which is similar to JavaScript:
No line break is allowed in the arguments of a lambda up to and including the
"=>" (so that Vim can tell the difference between an expression in parentheses
and lambda arguments). This is OK:
In legacy script a lambda could be called with any number of extra arguments,
there was no way to warn for not using them. In Vim9 script the number of
arguments must match. If you do want to accept any arguments, or any further
arguments, use "..._", which makes the function accept
vim9-variable-arguments. Example:
inline-function E1171
Additionally, a lambda can contain statements in {}:
The ending "}" must be at the start of a line. It can be followed by other
characters, e.g.:
Since the block ends at the first line starting with "}", the closing "}" of a
dictionary inside the block must not be at the start of a line. See
command-block for an example and the workaround.
command-block E1026
The block can also be used for defining a user command. Inside the block Vim9
syntax will be used.
This is an example of using here-docs:
If the statements include a dictionary, its closing bracket must not be
written at the start of a line. Otherwise, it would be parsed as the end of
the block. This does not work:
Rationale: The "}" cannot be after a command because it would require parsing
the commands to find it. For consistency with that no command can follow the
"{". Unfortunately this means using "() => { command }" does not work, line
breaks are always required.
vim9-curly
To avoid the "{" of a dictionary literal to be recognized as a statement block
wrap it in parentheses:
Also when confused with the start of a command block:
Automatic line continuation
vim9-line-continuation E1097
In many cases it is obvious that an expression continues on the next line. In
those cases there is no need to prefix the line with a backslash (see
line-continuation). For example, when a list spans multiple lines:
For binary operators in expressions not in [], {} or () a line break is
possible just before or after the operator. For example:
For a method call using "->" and a member using a dot, a line break is allowed
before it:
For commands that have an argument that is a list of commands, the | character
at the start of the line indicates line continuation:
Note that this means that in heredoc the first line cannot start with a bar:
add the "C" flag to 'cpoptions':
restored after the :enddef.
In places where line continuation with a backslash is still needed, such as
splitting up a long Ex command, comments can start with '#\ ':
continuation is used without a backslash and a line starts with a bar:
E1050
To make it possible for the operator at the start of the line to be
recognized, it is required to put a colon before a range. This example will
add "start" and "print":
This will assign "start" and print a line:
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:
Note that the colon is not required for the +cmd argument:
It is also possible to split a function header over multiple lines, in between
arguments:
Since a continuation line cannot be easily recognized the parsing of commands
has been made stricter. E.g., because of the error in the first line, the
second line is seen as a separate command:
file "_cb: Func})" and exit. To avoid this kind of mistake in Vim9 script
there must be white space between most command names and the argument.
E1144
However, the argument of a command that is a command won't be recognized. For
example, after "windo echo expr" a line break inside "expr" will not be seen.
Notes:
- "enddef" cannot be used at the start of a continuation line, it ends the
current function.
- No line break is allowed in the LHS of an assignment. Specifically when
unpacking a list :let-unpack. This is OK:
similar commands. This is OK:
commands are used as an argument to another command, such as :windo,
:command or :autocmd. In those cases the line continuation with a
backslash has to be used. For example:
White space
vim9-white-space E1004 E1068 E1069 E1074 E1127 E1202
Vim9 script enforces proper use of white space. This is no longer allowed:
command:
White space is required around most operators.
White space is required in a sublist (list slice) around the ":", except at
the start and end:
White space is not allowed:
- Between a function name and the "(":
White space is not allowed in a :set command between the option name and a
following "&", "!", "<", "=", "+=", "-=" or "^=".
No curly braces expansion
curly-braces-names cannot be used.
Command modifiers are not ignored
E1176
Using a command modifier for a command that does not use it gives an error.
E1082
Also, using a command modifier without a following command is now an error.
Dictionary literals
vim9-literal-dict E1014
Traditionally Vim has supported dictionary literals with a {} syntax:
Later it became clear that using a simple text key is very common, thus
literal dictionaries were introduced in a backwards compatible way:
However, this #{} syntax is unlike any existing language. As it turns out
that using a literal key is much more common than using an expression, and
considering that JavaScript uses this syntax, using the {} form for dictionary
literals is considered a much more useful syntax. In Vim9 script the {} form
uses literal keys:
This works for alphanumeric characters, underscore and dash. If you want to
use another character, use a single or double quoted string:
In case the key needs to be an expression, square brackets can be used, just
like in JavaScript:
The key type can be string, number, bool or float. Other types result in an
error. Without using [] the value is used as a string, keeping leading zeros.
An expression given with [] is evaluated and then converted to a string.
Leading zeros will then be dropped:
No :xit, :t, :k, :append, :change or :insert
E1100
These commands are too easily confused with local variable names.
Instead of :x or :xit you can use :exit.
Instead of :t you can use :copy.
Instead of :k you can use :mark.
Comparators
The 'ignorecase' option is not used for comparators that use strings.
Thus "=~" works like "=~#".
"is" and "isnot" (expr-is and expr-isnot) when used on strings now return
false. In legacy script they just compare the strings, in Vim9 script they
check identity, and strings are copied when used, thus two strings are never
the same (this might change someday if strings are not copied but reference
counted).
Abort after error
In legacy script, when an error is encountered, Vim continues to execute
following lines. This can lead to a long sequence of errors and need to type
CTRL-C to stop it. In Vim9 script execution of commands stops at the first
error. Example:
For loop
E1254
The loop variable must not be declared yet:
It is possible to use a global variable though:
Legacy Vim script has some tricks to make a for loop over a list handle
deleting items at the current or previous item. In Vim9 script it just uses
the index, if items are deleted then items in the list will be skipped.
Example legacy script:
1
2
3
4
In compiled Vim9 script you get:
1
3
Generally, you should not change the list that is iterated over. Make a copy
first if needed.
When looping over a list of lists, the nested lists can be changed. The loop
variable is "final", it cannot be changed but what its value can be changed.
E1306
The depth of loops, :for and :while loops added together, cannot exceed 10.
Conditions and expressions
vim9-boolean
Conditions and expressions are mostly working like they do in other languages.
Some values are different from legacy Vim script:
value legacy Vim script Vim9 script
0 falsy falsy
1 truthy truthy
99 truthy Error!
"0" falsy Error!
"99" truthy Error!
"text" falsy Error!
For the "??" operator and when using "!" then there is no error, every value
is either falsy or truthy. This is mostly like JavaScript, except that an
empty list and dict is falsy:
type truthy when
bool true, v:true or 1
number non-zero
float non-zero
string non-empty
blob non-empty
list non-empty (different from JavaScript)
tuple non-empty (different from JavaScript)
dictionary non-empty (different from JavaScript)
func when there is a function name
special true or v:true
job when not NULL
channel when not NULL
class not applicable
object when not NULL
enum not applicable
enum value always
typealias not applicable
The boolean operators "||" and "&&" expect the values to be boolean, zero or
one:
When using "!" for inverting, there is no error for using any type and the
result is a boolean. "!!" can be used to turn any value into boolean:
When using ".." for string concatenation arguments of simple types are
always converted to string:
Simple types are Number, Float, Special and Bool. For other types string()
should be used.
false true null null_blob null_channel
null_class null_dict null_function null_job
null_list null_object null_partial null_string
E1034
In Vim9 script one can use the following predefined values:
as v:null.
While null has the type "special", the other "null_" values have the type
indicated by their name. Quite often a null value is handled the same as an
empty value, but not always. The values can be useful to clear a script-local
variable, since they cannot be deleted with :unlet. E.g.:
The values can also be useful as the default value for an argument:
It is possible to compare null with any value, this will not give a type
error. However, comparing null with a number, float or bool will always
result in false. This is different from legacy script, where comparing
null with zero or false would return true.
vim9-false-true
When converting a boolean to a string false and true are used, not
v:false and v:true like in legacy script. v:none has no none
replacement, it has no equivalent in other languages.
vim9-string-index
Indexing a string with [idx] or taking a slice with [idx : idx] uses character
indexes instead of byte indexes. Composing characters are included.
Example:
script this results in the string 'á'.
A negative index is counting from the end, "[-1]" is the last character.
To exclude the last character use slice().
To count composing characters separately use strcharpart().
If the index is out of range then an empty string results.
In legacy script "++var" and "--var" would be silently accepted and have no
effect. This is an error in Vim9 script.
Numbers starting with zero are not considered to be octal, only numbers
starting with "0o" are octal: "0o744". scriptversion-4
What to watch out for
vim9-gotchas
Vim9 was designed to be closer to often used programming languages, but at the
same time tries to support the legacy Vim commands. Some compromises had to
be made. Here is a summary of what might be unexpected.
Ex command ranges need to be prefixed with a colon.
Some Ex commands can be confused with assignments in Vim9 script:
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 '.'.
Also, there cannot be a space between the command and the separator:
Functions defined with :def compile the whole function. Legacy functions
can bail out, and the following lines are not parsed:
evaluates to false:
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:
Note that for unrecognized commands there is no check for "|" and a following
command. This will give an error for missing endif:
Other differences
Patterns are used like 'magic' is set, unless explicitly overruled.
The 'edcompatible' option value is not used.
The 'gdefault' option value is not used.
You may also find this wiki useful. It was written by an early adopter of
Vim9 script: https://github.com/lacygoill/wiki/blob/master/vim/vim9.md
:++ :--
The ++ and -- commands have been added. They are very similar to adding or
subtracting one:
Using ++var or --var in an expression is not supported yet.
==============================================================================
3. New style functions fast-functions
:def
:def[!] {name}([arguments])[: {return-type}]
Define a new function by the name {name}. The body of
the function follows in the next lines, until the
matching :enddef.
E1073
{name} cannot be reused at the script-local level:
>vim9
vim9script
def F_1073()
enddef
def F_1073() # E1073: Name already defined: <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:
>vim9
vim9script
def F_1077(x): void
# E1077: Missing argument type for x
enddef
<
For the second form, because the declaration does not
specify it, Vim infers the type. For both second and
third forms, a default {value} applies when the
caller omits it. Examples:
>vim9
vim9script
def SecondForm(arg = "Hi"): void
echo $'2. arg is a "{arg->typename()}" type ' ..
$'and the default value of arg is "{arg}"'
enddef
SecondForm()
def ThirdForm(arg2: number = 9): void
echo $'3. default value of arg2 is {arg2}'
enddef
ThirdForm()
< E1123
Arguments in a builtin function called in a :def
function must have commas between arguments:
>vim9
vim9script
def F_1123(a: number, b: number): void
echo max(a b) # E1123: Missing comma before ar...
enddef
F_1123(1, 2)
< E1003 E1027 E1096
The type of value used with :return must match
{return-type}. When {return-type} is omitted or is
"void" the function is not allowed to return
anything. Examples:
>vim9
vim9script
def F_1003(): bool
return # E1003: Missing return value
enddef
F_1003()
< >vim9
vim9script
def F_1027(): bool
echo false # E1027: Missing return statement
enddef
F_1027()
< >vim9
vim9script
def F_1096(): void
return false # E1096: Returning a value in a f...
enddef
F_1096()
< E1056 E1059
When ": {return-type}" is specified, {return-type}
cannot be omitted (leaving a hanging colon). The ": "
also cannot be preceded by white space. Examples:
>vim
def F_1056():
# E1056: Expected a type:
enddef
def F_1059() : bool
# E1059: No white space allowed before colon: ...
enddef
<
The function will be compiled into instructions when
called or when either :defcompile or :disassemble is
used. (For an example, see :disassemble.) Syntax
and type errors will be produced at that time.
E1058
It is possible to nest :def inside another :def or
:function only up to 49 levels deep. At 50 or more
levels, it is a E1058 error.
E1117
[!] is allowed only in legacy Vim script because it
permits function redefinition (as with :function!).
In Vim9 script, ! is not allowed because script-local
functions cannot be deleted or redefined, though they
can be removed by reloading the script. Also, nested
functions cannot use ! for redefinition. Examples:
>vim
" Legacy Vim script :def! example
def! LegacyFunc()
echo "def! is allowed in a legacy Vim script"
enddef
call LegacyFunc()
< >vim9
vim9script
def F1117()
def! InnerFunc()
# E1117: Cannot use ! with nested :def
enddef
enddef
F1117()
< >vim9
vim9script
def! F_477(): void # E477: No ! allowed
enddef
< >vim9
vim9script
def F_1084(): void
enddef
delfunction! F_1084
# E1084: Cannot delete Vim9 script function F_1084
<
Note: The generic error E1028 ("Compiling :def
function failed") indicates an undeterminable error
during compilation. If reproducible, it may be
reported at https://github.com/vim/vim/issues as
it could represent a gap in Vim's error reporting.
:enddef
E1057 E1152 E1173
:enddef End of a function defined with :def. It should be on
a line by itself. Examples:
>vim9
vim9script
def MyFunc()
echo 'Do Something' | enddef
# E1057: Missing :enddef
< >vim9
vim9script
def F_1173()
enddef echo 'X'
# E1173: Text found after enddef: echo 'X'
< >vim9
vim9script
def F_1152()
function X()
enddef # E1152: Mismatched enddef
enddef
<
You may also find this wiki useful. It was written by an early adopter of
Vim9 script: https://github.com/lacygoill/wiki/blob/master/vim/vim9.md
vim9-s:var
When referencing a script-local variable, the context determines whether using
the "s:" prefix is either mandatory, optional, or gives E1268. The context
factors are whether the script version is Vim9 script or legacy Vim script and
whether the reference is at the script-local level, within a :def function,
or within a :function. The three rules are:
1. In a :function, "s:" is always mandatory. This is regardless of the
script type or the function's parent context (such as nested within
another function). Similarly, "s:" is also mandatory in the script-local
scope of a legacy Vim script.
2. In a Vim9 script, "s:" always gives E1268 when used in a :def function,
regardless of the function's parent context. Similarly, it gives E1268 in
the script-local scope of a Vim9 script.
3. In a legacy Vim script, "s:" is optional in a :def function, regardless
of the function's parent context.
The following three scripts demonstrate these rules:
>vim
" 1. In a :function, "s:" is always mandatory. It is also mandatory
" in a legacy Vim script's script-local scope
let s:MyVar = v:true
echo s:MyVar | " v:true
" echo MyVar (Would give E121: Undefined variable: MyVar)
vim9cmd echo MyVar # true
function! MyFunc()
echo s:MyVar | " v:true
" echo MyVar (Would give E121: Undefined variable: MyVar)
vim9cmd echo MyVar # true
endfunction
call MyFunc()
< >vim9
vim9script
# 2. In a Vim9 script, "s:" gives E1268 when used in any :def function
# and in the script-local scope
var MyVar: bool = true
echo MyVar # true
# echo s:MyVar (Would give E1268: Cannot use s: in Vim9...)
legacy echo s:MyVar | # v:true
def MyFunc()
echo MyVar # true
# echo s:MyVar (Would give E1268: Cannot use s: in Vim9...)
legacy echo s:MyVar | # v:true
enddef
MyFunc()
< >vim
" 3. In a legacy Vim script, "s:" is optional in a :def function
let s:MyVar = v:true
function! Outer()
def! MyFunc()
echo MyVar # true
echo s:MyVar # true
enddef
call MyFunc()
endfunction
call Outer()
<
Using exists(), which is evaluated at runtime, cannot be used conditionally
to skip undeclared variables, though exists_compiled(), which is evaluated at
compile time, may be used. For example:
>vim9
vim9script
def MyDef()
if exists_compiled('MyVar') # evaluated at compile time
echo $"MyVar = {MyVar}" # MyVar = 1
endif
if exists_compiled('MyVar2') # evaluated at compile time
echo $"MyVar2 = {MyVar2}" # not reached
else
echo "MyVar2 does not exist at compile time"
endif
if exists('MyVar') # evaluated at runtime
echo $"MyVar = {MyVar}" # MyVar = 1
endif
if exists('MyVar2') # evaluated at runtime
# The following would give E1001: Variable not found: MyVar2
# echo MyVar2
else
echo "MyVar2 does not exist at runtime"
endif
enddef
var MyVar: number = 1 # Declared before MyDef() is compiled
MyDef()
var MyVar2: number = 2 # Declared after MyDef() is compiled
<
< E1269
Script-local variables in a Vim9 script must be declared at the script
level. They cannot be created in a :def function and may not be declared
in a legacy function with the "s:" prefix. For example:
>vim9
vim9script
function F_1269()
let s:i_wish = v:true
endfunction
F_1269()
# E1269: Cannot create a Vim9 script variable in a function: s:i_wish
<
:defc :defcompile
:defc[ompile] Compile functions and classes (class-compile)
defined in the current script that were not compiled
yet. This will report any errors found during
compilation.
Example: When the three lines (up to and including
enddef) are sourced, there is no error because the
Vim9 :def function is not compiled. However, if all
four lines are sourced, compilation fails:
>vim9
vim9script
def F_1027(): string
enddef
defcompile F_1027 # E1027: Missing return statement
<
:defc[ompile] MyClass Compile all methods in a class. (See :disassemble
for an example.)
:defc[ompile] {func}
:defc[ompile] debug {func}
:defc[ompile] profile {func}
Compile function {func}, if needed. Use "debug" and
"profile" to specify the compilation mode.
This will report any errors found during compilation.
{func} can also be "ClassName.functionName" to
compile a function or method in a class.
{func} can also be "ClassName" to compile all
functions and methods in a class.
:disa :disassemble
:disa[ssemble] {func} Show the instructions generated for {func}.
This is for debugging and testing.
If {func} is not found, error E1061 occurs.
{func} can also be "ClassName.functionName" to
disassemble a function in a class.
The following example demonstrates using :defcompile
with a class and :disassemble with a
"ClassName.functionName" (positioning the cursor on
the last line of the visually sourced script):
>vim9
vim9script
class Line
var lnum: number
def new(this.lnum)
enddef
def SetLnum()
cursor(this.lnum, 52)
enddef
endclass
defcompile Line
disassemble Line.SetLnum
var vlast: Line = Line.new(line("'>"))
vlast.SetLnum() # Cursor is positioned here->_
<
:disa[ssemble] profile {func}
Like :disassemble but with the instructions used for
profiling.
:disa[ssemble] debug {func}
Like :disassemble but with the instructions used for
debugging.
Note: For command line completion of {func}, script-local functions
are shown with their <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:
>vim9
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:
>vim9
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:
>vim9
vim9script
def EditNewBlah()
var fname: string = 'blah.txt'
split
edit =fname
enddef
EditNewBlah() # A new split is created as buffer 'blah.txt'
<
vim9-closure
Closures defined in a loop can either share a variable or each have their own
copy, depending on where the variable is declared. With a variable declared
outside the loop, all closures reference the same shared variable.
The following example demonstrates the consequences, with the "outloop"
variable existing only once:
>vim9
vim9script
var flist: list<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:
>vim9
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:
>vim9
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:
>vim9
vim9script
def F_1248(): void
var n: number
var F: func = () => {
n += 1
}
try
execute printf("call %s()", F)
catch
echo v:exception
endtry
enddef
F_1248() # Vim(call):E1248: Closure called from invalid context
<
In Vim9 script, a loop variable is invalid after the loop is closed.
For example, this timer will echo 0 to 2 on separate lines. However, if
the variable "n" is used after the :endfor, that is an E121 error:
>vim9
vim9script
for n in range(3)
var nr: number = n
timer_start(1000 * n, (_) => {
echowindow nr
})
endfor
try
echowindow n
catch
echo v:exception
endtry
<
Note: Using :echowindow is useful in a timer because messages go
into a popup and will not interfere with what the user is doing when
it triggers.
Converting a :function to a :def
convert_legacy_function_to_vim9
convert_:function_to_:def
There are many changes that need to be made to convert a :function to
a :def function. The following are some of them:
- Change let used to declare variables to one of var, const, or final,
and remove the "s:" from each script-variable.
- Change func or function to def.
- Change endfunc or endfunction to enddef.
- Add the applicable type (or "any") to each function argument.
- Remove "a:" from each function-argument.
- Remove inapplicable options such as :func-range, :func-abort,
:func-dict, and :func-closure.
- If the function returns something, add the return type. (Ideally, add
"void" if it does not return anything.)
- Remove line continuation backslashes from places they are not required.
- Remove let for assigning values to global (g:), buffer (b:),
window (w:), tab (t:), and local (l:) variables.
- Rewrite lambda expressions in Vim9 script syntax (see vim9-lambda).
- Change comments to start with # (preceded by white space) instead of ".
- Insert white space in expressions where required (see vim9-white-space).
- Change "." used for string concatenation to " .. ". (Alternatively, use
an interpolated-string.)
The following legacy Vim script and Vim9 script examples demonstrate all
those differences. First, legacy Vim script:
>vim
let s:lnum=0
function Leg8(arg) abort
let l:pre=['Result',
\': ']
let b:arg=a:arg
let s:lnum+=2
let b:arg*=4
let l:result={pre->join(pre,'')}(l:pre)
return l:result.(b:arg+s:lnum)"no space before comment
endfunction
call Leg8(10)->popup_notification(#{time: 3000})" Pops up 'Result: 42'
<
The equivalent in Vim9 script:
>vim9
vim9script
var lnum: number
def Vim9(arg: number): string
final pre = ['Result',
': ']
b:arg = arg
lnum += 2
b:arg *= 4
const RESULT: string = ((lpre) => join(lpre, ''))(pre)
return RESULT .. (b:arg + lnum) # space required before # comment
enddef
Vim9(10)->popup_notification({time: 3000}) # Pops up 'Result: 42'
<
Note: This example also demonstrates (outside the :def function):
- Removing "#" from the legacy #{} - see vim9-literal-dict, and
- Omitting :call (allowed, though unnecessary in Vim9 script)
Calling a :def function in an expr option
expr-option-function
The value of a few options, such as 'foldexpr', is an expression that is
evaluated to get a value. The evaluation can have quite a bit of overhead.
One way to minimize the overhead, and also to keep the option value simple,
is to define a compiled function and set the option to call it without
arguments. For example:
>vim9
vim9script
def MyFoldFunc(): string
# This matches start of line (^), followed by a digit, a full stop
# a space or tab, an uppercase character, with an empty next line
return getline(v:lnum) =~ '^[[:digit:]]\.[[:blank:]][[:upper:]]'
&& getline(v:lnum + 1)->empty() ? '>1' : '1'
enddef
set foldexpr=MyFoldFunc()
set foldmethod=expr
normal! zM
<
Warning: This script creates and applies folds at the "Heading 1" level of
this vim9.txt help buffer. (You can use zR, in Normal mode, to open all the
folds after sourcing the script.)
==============================================================================
4. Types vim9-types
The following types, each shown with its corresponding internal v:t_TYPE
variable, are supported:
number v:t_number
string v:t_string
func v:t_func
func: {type} v:t_func
func({type}, ...) v:t_func
func({type}, ...): {type} v:t_func
list<{type}> v:t_list
dict<{type}> v:t_dict
float v:t_float
bool v:t_bool
none v:t_none
job v:t_job
channel v:t_channel
blob v:t_blob
class v:t_class
object v:t_object
typealias v:t_typealias
enum v:t_enum
enumvalue v:t_enumvalue
tuple<{type}> v:t_tuple
tuple<{type}, {type}, ...> v:t_tuple
tuple<...list<{type}>> v:t_tuple
tuple<{type}, ...list<{type}>> v:t_tuple
void
E1031 E1186
These types can be used in declarations, though no simple value can have the
"void" type. Trying to use a void as a value results in an error.
Examples:
>vim9
vim9script
def NoReturnValue(): void
enddef
try
const X: any = NoReturnValue()
catch
echo v:exception # E1031: Cannot use void value
try
echo NoReturnValue()
catch
echo v:exception # E1186: Expression does not result in a valu...
endtry
endtry
< E1008 E1009 E1010 E1012
Ill-formed declarations and mismatching types result in errors. The following
are examples of errors E1008, E1009, E1010, and E1012:
>vim9
vim9cmd var l_1008: list
vim9cmd var l_1009: list<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:
>vim9
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:
>vim9
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:
>vim9
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:
If the return type is "void", the function does not return a value. All the
ways listed above are explained and demonstrated in the following examples,
all of which echo '9'.
func
- any kind of function reference
- any type of return value or no return value
>vim9
vim9script
const I = (n) => n + 1
const F: func = I->function()
echo F(8)
<
func: void
- any number and type of arguments
- does not return a value
>vim9
vim9script
def I(n: number): void
echo n + 1
enddef
const F: func: void = I->function()
F(8)
<
func: {type}
- any number and type of arguments
- returns a typed value
>vim9
vim9script
const I = (n): number => n + 1
const F: func: number = I->function()
echo F(8)
<
func()[: void]
- no arguments
- does not return a value
>vim9
vim9script
var n: number = 8
def I(): void
echo n + 1
enddef
const F: func(): void = I->function()
F()
<
func(): {type}
- no arguments
- returns a typed value
>vim9
vim9script
var n: number = 8
def I(): number
return n + 1
enddef
const F: func(): number = I->function()
echo F()
<
func({type})[: void]
- typed argument
- does not return a value
>vim9
vim9script
def I(n: number): void
echo n + 1
enddef
const F: func(number): void = I->function()
F(8)
<
func({type}): {type}
- typed argument
- returns a typed value
>vim9
vim9script
const I = (n: number): number => n + 1
const F: func(number): number = I->function()
echo F(8)
<
func(?{type})[: void]
- optional typed argument
- does not return a value
>vim9
vim9script
def I(n: number = 8): void
echo n + 1
enddef
const F: func(?number): void = I->function()
F()
<
func(?{type}): {type}
- optional typed argument
- returns a typed value
>vim9
vim9script
def I(n: number = 8): number
return n + 1
enddef
const F: func(?number): number = I->function()
echo F()
<
func(...list<{type}>)[: void]
- typed list for variable number of arguments
- does not return a value
>vim9
vim9script
def L(...l: list<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
>vim9
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
>vim9
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
>vim9
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:
>vim9
vim9script
def CircleArea(pi: float, radius: float): float
return pi * radius->pow(2)
enddef
const AREA: func(float): float = CircleArea->function([3.14])
const RADIUS: float = "Enter a radius value: "->input()->str2float()
echo $"\nThe area of a circle with a radius of {RADIUS} is " ..
$"{AREA(RADIUS)} (π to two d.p.)"
<
E1005
No more than 19 argument types may be used in a Funcref (one less than what is
allowed in a function, including a :def or lambda - see E740). Twenty or
more argument types gives E1005, as this example shows:
>vim9
vim9script
var X: func
X = (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t) => 0
var F: func(any, any, any, any, any, any, any, any, any, any, any,
\ any, any, any, any, any, any, any, any, any): any = X->function()
# E1005: Too many argument types
<
E1007
A mandatory argument may not come after an optional argument in a Funcref:
>vim9
vim9script
def I(n: number, f: float): void
echo n + f
enddef
const F: func(?number, float) = I->function()
# E1007: Mandatory argument after optional argument
<
vim9-typealias-type
Custom types (typealias) can be defined with :type. They must start with
a capital letter (which avoids name clashes with either current or future
builtin types) similar to user functions. This example creates a list of
perfect squares, reporting on type() (14, a typealias) and the typename():
>vim9
vim9script
type Ln = list<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:
>vim9
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:
>vim9
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:
>vim9
vim9script
enum Quad
Square('four', 'only'),
Rhombus('opposite', 'no')
var eq: string
var ra: string
def string(): string
return $"\nA {this.name} has " ..
$"{this.eq} equal sides and {this.ra} right angles\n\n"
enddef
endenum
echo "Rhombus (r) or Square (s)?"
var myQuad: Quad = getcharstr() =~ '\c^R' ? Quad.Rhombus : Quad.Square
echo myQuad.string() .. "\ttype()\ttypename()"
echo $"Quad \t{Quad->type()} \t{Quad->typename()}"
echo $"myQuad\t{myQuad->type()}\t{myQuad->typename()}"
<
Notes: This uses builtin method "string()" - see object-string().
The typename() of Quad and myQuad are the same ("enum<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:
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:
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:
>vim9
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:
>vim9
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:
line, not sourced.
E1363 E1395
If a type is incomplete, such as when an object's class is unknown, E1363
or E1395 are given. Examples:
>vim9
vim9script
var E1363 = null_class.member # E1363: Incomplete type
< >vim9
vim9script
def F1395(): void
echo null_class.member
enddef
F1395() # E1395: Using a null class
<
Another null object-related error is E1360:
>vim9
vim9script
var obj = null_object
var E1360 = obj.MyMethod() # E1360: Using a null object
<
Type inference
type-inference
Declaring types explicitly provides many benefits, including targeted type
checking and clearer error messages. Nonetheless, Vim often can infer types
automatically when they are omitted. For example, each of these variables'
types are inferred, with the type() and typename() echoed showing those
inferred types:
>vim9
vim9script
echo "\t type()\t typename()"
var b = true | echo $"{b} \t {b->type()} \t {b->typename()}"
var f = 4.2 | echo $"{f} \t {f->type()} \t {f->typename()}"
var l = [1, 2] | echo $"{l} \t {l->type()} \t {l->typename()}"
var n = 42 | echo $"{n} \t {n->type()} \t {n->typename()}"
var s = 'yes' | echo $"{s} \t {s->type()} \t {s->typename()}"
var t = (42, ) | echo $"{t} \t {t->type()} \t {t->typename()}"
<
The type of a list, tuple, or dictionary is inferred from the common type of
its values. When the values are all the same type, that type is used.
If there is a mix of types, the "any" type is used. In the following example,
the echoed typename() for each literal demonstrates these points:
>vim9
vim9script
echo [1, 2]->typename() # list<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>":
>vim9
vim9script
def Foo(x: bool): void
enddef
def Bar(x: bool, y: bool): void
enddef
var funclist = [Foo, Bar]
echo funclist->typename()
<
Script-local variables in a Vim9 script are type checked. The type is
also checked for variables declared in a legacy function. For example:
>vim9
vim9script
var my_local = (1, 2)
function Legacy()
let b:legacy = [1, 2]
endfunction
Legacy()
echo $"{my_local} is type {my_local->type()} ({my_local->typename()})"
echo $"{b:legacy} is type {b:legacy->type()} ({b:legacy->typename()})"
<
E1013
When a type is declared for a List, Tuple, or Dictionary, the type is attached
to it. Similarly, if a type is not declared, the type Vim infers is attached.
In either case, if an expression attempts to change the type, E1013 results.
This example has its type inferred and demonstrates E1013:
>vim9
vim9script
var lb = [true, true] # Two bools, so Vim infers list<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:
>vim9
vim9script
final la: list<any> = []
echo la->extend(['two', 1])
final le = []
echo le->extend(la)
<
Similarly for a permissive dictionary:
>vim9
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:
>vim9
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:
>vim9
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":
>vim
echo 123 == '123'
<
However, if an unintended space is included, "0" is echoed:
>vim
echo 123 == ' 123'
<
E1206
In Vim9 script this has been made stricter. In most places it works just as
before if the value used matches the expected type. For example, in both
legacy Vim script and Vim9 script trying to use anything other than a
dictionary when it is required:
>vim
echo [8, 9]->keys()
vim9cmd echo [8, 9]->keys() # E1206: Dictionary required
<
E1023 E1024 E1029
E1030 E1174 E1175
E1210 E1212
However, sometimes there will be an error in Vim9 script, which breaks
backwards compatibility. The following examples illustrate various places
this happens. The legacy Vim script behavior, which does not fail, is shown
first. It is followed by the error that occurs if the same command is used
in Vim9 script.
- Using a number (except 0 or 1) where a bool is expected:
>vim
echo v:version ? v:true : v:false
vim9cmd echo v:version ? true : false # E1023: Using a Number as ...
<
- Using a number where a string is expected:
>vim
echo filter([1, 2], 0)
vim9cmd echo filter([1, 2], 0) # E1024: Using a Number as a String
<
- Not using a number where a number is expected:
>vim
" In this example, legacy Vim script treats v:false as 0
function Not1029()
let b:l = [42] | unlet b:l[v:false]
endfunction
call Not1029() | echo b:l
< >vim9
vim9script
def E1029(): void
b:l = [42] | unlet b:l[false]
enddef
E1029() # E1029: Expected number but got bool
<
- Using a string as a number:
>vim
let b:l = [42] | unlet b:l['#'] | echo b:l
vim9cmd b:l = [42] | vim9cmd unlet b:l['#'] # E1030: Using a string
<
- Not using a string where an argument requires a string:
>vim9
echo substitute('Hallo', 'a', 'e', v:true)
vim9cmd echo substitute('Hallo', 'a', 'e', true) # E1174: String ...
<
- Using an empty string in an argument that requires a non-empty string:
>vim9
echo exepath('')
vim9cmd echo exepath('') # E1175: Non-empty string required for ar...
<
- Not using a number when it is required:
>vim
echo gettabinfo('a')
vim9cmd echo gettabinfo('a') # E1210: Number required for argument 1
<
- Not using a bool when it is required:
>vim
echo char2nr('¡', 2)
vim9cmd echo char2nr('¡', 2) # E1212: Bool required for argument 2
<
- Not using a number when a number is required (E521):
>vim
let &laststatus='2'
vim9cmd &laststatus = '2'
<
- Not using a string when a string is required (E928):
>vim
let &langmenu = 42
vim9cmd &langmenu = 42 # E928: String required
<
- Comparing a Special with "is" often fails (E1037, E1072):
>vim
" 1 is echoed because these are both true in legacy Vim script
echo v:null is v:null && v:none is v:none
" Similarly, 0 is echoed for these (false in legacy Vim script)
echo v:none is v:null || v:none is 8 || v:true is v:none
" All these are errors in Vim9 script
vim9cmd echo v:null is v:null # E1037: Cannot use 'is' with special
vim9cmd echo v:none is v:none # E1037: Cannot use 'is' with special
vim9cmd echo v:none is v:null # E1037: Cannot use 'is' with special
vim9cmd echo v:none is 8 # E1072: Cannot compare special wit...
vim9cmd echo v:true is v:none # E1072: Cannot compare bool with s...
<
Note: Although the last two Vim9 script examples above error with
v:none, they return false with v:null (which is the same as
null - see v:null):
>vim9
vim9script
echo v:null is 8 # false
echo true is v:null # false
<
- Using a string where a bool is required (E1135):
>vim
echo '42' ? v:true : v:false
vim9cmd echo '42' ? true : false # E1135: Using a String as a Bool
<
- Using a bool as a number (E1138):
>vim
let &laststatus=v:true
vim9cmd &laststatus = true
<
One consequence is that the item type of a list or dict given to map() must
not change when its type is either declared or inferred. For example, this
list's type is changed successfully in legacy Vim script:
>vim
" legacy Vim script changing list [0, 1] to ['item 0', 'item 1']
let s:mylist = [0, 1]
call map(s:mylist, {i -> $"item {i}"})
echo s:mylist
<
whereas in Vim9 script it gives E1012:
>vim9
vim9script
var mylist = [0, 1] # Vim infers mylist is list<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:
>vim9
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:
>vim9
vim9script
# list literal
echo [1, 2]->map((_, v) => $"#{v}")
echo [1, 2]->map((_, v) => $"#{v}")->typename()
# deepcopy() in a method chain
var mylist = [1, 2]
echo mylist->deepcopy()->map((_, v) => $"#{v}")
echo mylist->deepcopy()->map((_, v) => $"#{v}")->typename()
echo mylist
<
The reasoning behind this is, when a type is either declared or inferred
and the list is passed around and changed, the declaration/inference must
always hold so that you can rely on the type to match the declared/inferred
type. For either a list literal or a fully copied list, that type safety is
not needed because the original list is unchanged (as "echo mylist" shows,
above).
If the item type was not declared or determined to be "<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:
>vim9
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:
>vim9
vim9cmd echo [1, 2]->extend(['3']) # [1, 2, '3']
<
whereas, this is not:
>vim9
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:
>vim9
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():
>vim9
vim9cmd [1, [2, 3]]->flatten() # E1158: Cannot use flatten
vim9cmd echo [1, [2, 3]]->flattennew() # [1, 2, 3]
<
Assigning to a funcref with specified arguments (see vim9-func-declaration)
involves strict type checking of the arguments. For example, this works:
>vim9
vim9script
var F_name_age: func(string, number): string
F_name_age = (n: string, a: number): string => $"Name: {n}, Age: {a}"
echo F_name_age('Bob', 42)
<
whereas this fails with error E1012 (type mismatch):
>vim9
vim9script
var F_name_age: func(string, number): string
F_name_age = (n: string, a: string): string => $"Name: {n}, Age: {a}"
<
If there is a variable number of arguments they must have the same type, as in
this example:
>vim9
vim9script
var Fproduct: func(...list<number>): 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:
>vim9
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:
>vim9
vim9script
var FuncSN: func(string): number
FuncSN = (v: any): number => v->str2nr()
echo FuncSN('162')->nr2char() # ¢
echo FuncSN(162)->nr2char() # E1013 (a runtime error)
< >vim9
vim9script
var FuncSN: func(string): number
FuncSN = (v: any): number => v->str2nr()
def FuncSNfail(): void
echo FuncSN('162')->nr2char() # No echo because ...
echo FuncSN(162)->nr2char() # E1013 (now, a compiling error)
enddef
FuncSNfail()
<
When the funcref has no arguments specified, there is no type checking. This
example shows FlexArgs has a string argument the first time and a list the
following time:
>vim9
vim9script
var FlexArgs: func: string
FlexArgs = (s: string): string => $"It's countdown time {s}..."
echo FlexArgs("everyone")
FlexArgs = (...values: list<string>): string => join(values, ', ')
echo FlexArgs('3', '2', '1', 'GO!')
<
E1211 E1217 E1218 E1219 E1220
E1221 E1222 E1223 E1224 E1225
E1226 E1228 E1235 E1238 E1251
E1253 E1256 E1297 E1298 E1301
E1528 E1529 E1530 E1531 E1534
Types are checked for most builtin functions to make it easier to spot
mistakes. The following one-line :vim9 commands, calling builtin functions,
demonstrate many of those type-checking errors:
>vim9
vim9 9->list2blob() # E1211: List required for argume...
vim9 9->ch_close() # E1217: Channel or Job required ...
vim9 9->job_info() # E1218: Job required for argumen...
vim9 [9]->cos() # E1219: Float or Number required...
vim9 {}->remove([]) # E1220: String or Number require...
vim9 null_channel->ch_evalraw(9) # E1221: String or Blob required ...
vim9 9->col() # E1222: String or List required ...
vim9 9->complete_add() # E1223: String or Dictionary req...
vim9 setbufline(9, 9, {}) # E1224: String, Number or List r...
vim9 9->count(9) # E1225: String, List, Tuple or D...
vim9 9->add(9) # E1226: List or Blob required fo...
vim9 9->remove(9) # E1228: List, Dictionary, or Blo...
vim9 getcharstr('9') # E1235: Bool or number required ...
vim9 9->blob2list() # E1238: Blob required for argume...
vim9 9->filter(9) # E1251: List, Tuple, Dictionary,...
vim9 9->reverse() # E1253: String, List, Tuple or B...
vim9 9->call(9) # E1256: String or Function requi...
vim9 null_dict->winrestview() # E1297: Non-NULL Dictionary requ...
vim9 {}->prop_add_list(null_list) # E1298: Non-NULL List required f...
vim9 {}->repeat(9) # E1301: String, Number, List, Tu...
vim9 9->index(9) # E1528: List or Tuple or Blob re...
vim9 9->join() # E1529: List or Tuple required f...
vim9 9->max() # E1530: List or Tuple or Diction...
vim9 9->get(9) # E1531: Argument of get() must b...
vim9 9->tuple2list() # E1534: Tuple required for argum...
<
Reserved for future use: E1227 E1250 E1252
E1227: List or Dictionary required for argument %d
E1250: Argument of %s must be a List, String, Dictionary or Blob
E1252: String, List or Blob required for argument %d
Categories of variables, defaults and null handling
variable-categories null-variables
There are three categories of variables:
primitive number, float, boolean
container string, blob, list, tuple, dict
specialized function, job, channel, user-defined-object
When declaring a variable without an initializer, an explicit type must be
provided. Each category has different default initialization semantics.
Primitives default to type-specific values. All primitives are empty but do
not equal null:
>vim9
vim9script
var n: number | echo [n, n->empty(), n == null] # [0, 1, false]
var f: float | echo [f, f->empty(), f == null] # [0.0, 1, false]
var b: bool | echo [b, b->empty(), b == null] # [false, 1, false]
<
Containers default to an empty container. Only an empty string equals null:
>vim9
vim9script
var s: string | echo [s, s->empty(), s == null] # ['', 1, true]
var z: blob | echo [z, z->empty(), z == null] # [0z, 1, false]
var l: list<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:
>vim9
vim9script
var F: func | echo [F, F == null] # [function(''), true]
var j: job | echo [j, j == null] # ['no process', true]
var c: channel | echo [c, c == null] # ['channel fail', true]
class Class
endclass
var o: Class | echo [o, o == null] # [object of [unknown], true]
enum Enum
endenum
var e: Enum | echo [e, e == null] # [object of [unknown], true]
<
Notes: (1) See empty() for explanations of empty job, empty channel,
and empty object types. (2) The class, enum, and typealias
types cannot be used as values, so cannot be compared to null (see
E1405, E1421, and E1403 respectively).
Vim does not have a familiar null value. Instead, it has various null_<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:
>vim9
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:
>vim9
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).
>vim9
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:
>vim9
vim9script
var j1: job
var j2: job = null_job
var j3 = null_job
echo (j1 == j2) == (j2 == j3) # true (equivalent, indistinguishable)
<
When a list, tuple, or dict is declared, if the item type is not specified
it cannot be inferred. Consequently, the item type defaults to "any":
>vim9
vim9script
var [t1, t2] = [(), null_tuple]
echo $'t1 is {t1->typename()} and t2 is {t2->typename()} too'
<
Tuples and functions (or partials) may be declared in various ways.
See tuple-type, variadic-tuple, and vim9-func-declaration.
null-compare
For familiar null compare semantics, where an empty container is not equal to
a null container, do not use null_<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:
>vim9
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:
>vim9
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:
>vim9
vim9cmd echo (null_dict == {}, null_dict == null, {} != null)
<
The exception is an uninitialized string. It is equal to null (and is the
same instance as null_string). The "is" operator (expr-is) may be used to
determine whether a string is uninitialized:
>vim9
vim9script
var s: string
echo s == null_string # true
echo s is null_string # true (the same instance)
echo s == null # true (unexpected, perhaps)
echo s is null # false (not the same instance)
<
However, don't do the same for the other containers because, when evaluated
against their applicable null_<type> with "is", they return false:
>vim9
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:
>vim9
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:
>vim9
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:
>vim9
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:
>vim9
vim9script
var c: channel | echo c == null
var F: func | echo F == null
var j: job | echo j == null
class Class
endclass
var nc: Class | echo nc == null
enum Enum
endenum
var ne: Enum | echo ne == null
<
Note: the specialized variables, like job, default to null and no
specialized variable has a corresponding empty value.
A container variable initialized to empty equals null_<type>, so these are all
true:
>vim9
vim9script
var s: string = "" | echo s == null_string
var b: blob = 0z | echo b == null_blob
var l: list<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:
>vim9
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:
These type parameters may then be used, like any other type, within the
function signature and its body. The following example combines two lists
into a list of tuples:
>vim9
vim9script
def Zip<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:
>vim9
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:
>vim9
vim9script
My1558<number>()
# E1558: Unknown generic function: My1558
< >vim9
vim9script
def My1560(): void
enddef
My1560<string>()
# E1560: Not a generic function: My1560
<
E1561
Type parameter names must not clash with other identifiers:
>vim9
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:
Note: There are several working examples in this section, which may be
sourced, including generic-function-example.
E1555 E1556 E1557 E1559
The number of passed type arguments to the function must match the number
of its declared type parameters. An empty type list is not allowed.
Examples:
>vim9
vim9script
def My1555<>(): void
enddef # E1555: Empty type list specified for generic function '<S...
< >vim9
vim9script
def My1556<T>(): void
enddef
My1556<bool, bool>() # E1556: Too many types specified for generic...
< >vim9
vim9script
def My1557<T, U>(): void
enddef
My1557<bool>() # E1557: Not enough types specified for generic fun...
< >vim9
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:
>vim9
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:
>vim9
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:
>vim9
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:
>vim9
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:
>vim9
vim9script
# Match a specified character in a string or the decimal value of the
# character in a list. Note: '*' is decimal 42 (U+002A)
var c: string = "*"
var char_dec: tuple<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:
The :disassemble command can be used to list the instructions generated for
a generic function:
Limitations and Future Work
Currently, Vim does not support:
- Type inference for type variables: All types must be explicitly specified
when calling a generic function.
- Type constraints: It's not possible to restrict a type variable to a
specific class or interface (e.g., T extends SomeInterface).
- Default type arguments: Providing a default type for a type parameter
when not explicitly specified.
==============================================================================
6. Namespace, Import and Export vim9script
vim9-export vim9-import
A Vim9 script can be written to be imported. This means that some items are
intentionally exported, made available to other scripts. When the exporting
script is imported in another script, these exported items can then be used in
that script. All the other items remain script-local in the exporting script
and cannot be accessed by the importing script.
This mechanism exists for writing a script that can be sourced (imported) by
other scripts, while making sure these other scripts only have access to what
you want them to. This also avoids using the global namespace, which has a
risk of name collisions. For example when you have two plugins with similar
functionality.
You can cheat by using the global namespace explicitly. That should be done
only for things that really are global.
Namespace
vim9-namespace
To recognize a file that can be imported, the vim9script command must appear
as the first command in the file (though see vim9-mix for an exception).
It tells Vim to interpret the script in its own namespace, instead of the
global namespace. Consider this script:
>vim9
vim9script
var myvar = 'yes'
<
The variable "myvar" will only exist in this script's scope. That is
different from legacy Vim script where "let myvar" would make "myvar"
available to other scripts and functions (as g:myvar).
E1101
The variables at the file level are very much like the script-local "s:"
variables in legacy Vim script, but the "s:" is omitted. And they cannot be
deleted.
E1304
In Vim9 script the global (g:), buffer (b:), window (w:), and tab (t:)
namespaces can be used like in legacy Vim script. In Vim9 script, namespace
prefixed variables:
- are not declared
- have no specific type, and
- can be deleted.
If a namespace prefixed variable is declared, E1016 is given. And, if a
type is specified, E1304 is given:
>vim9
vim9cmd var b:fails: bool # E1016: Cannot declare a buffer va...
vim9cmd b:fails: bool = false # E1304: Cannot use type with this ...
<
A side effect of :vim9script is that the 'cpoptions' option is set to the
Vim default value, like with:
One of the effects is that line-continuation is always enabled.
The original value of 'cpoptions' is restored at the end of the script, while
flags added or removed in the script are also added to or removed from the
original value to get the same effect. The order of flags may change.
In the vimrc file sourced on startup this does not happen.
vim9-mix
There is one way to use both legacy and Vim9 syntax in one script file:
>vim9
" _legacy Vim script_ comments are placed here
if !has('vim9script')
" _legacy Vim script_ comments and commands are placed here
finish
endif
vim9script
# _Vim9 script_ commands/commands from here onwards
echowindow $"has('vim9script') == {has('vim9script')}"
<
This allows for writing a script that takes advantage of the Vim9 script
syntax if possible, and prevents the vim9script command from giving an
error if used in a version of Vim without Vim9 script.
Note that Vim9 syntax changed before Vim 9 so that scripts using the current
syntax (such as "import from" instead of "import") might give errors.
To prevent these, a safer check may be v:version >= 900 instead (because
"has('vim9script')" will return v:true back to Vim 8.2 with patch 3965).
Sometimes it is prudent to cut off even later. Vim9 script's feature set
continues to grow so, for example, if tuples are used (introduced in Vim 9.1
patch 1232), a better condition is:
>vim9
if !has('patch-9.1.1232')
echowindow $"Fail: Vim does not have patch 9.1.1232"
finish
endif
vim9script
echowindow $"Pass: version {v:versionlong}. Continuing ..."
<
Whichever vim-mix condition is used, it only works in one of two ways:
1. The "if" statement evaluates to false, the commands up to endif are
skipped and vim9script is then the first command actually executed.
2. The "if" statement evaluates to true, the commands up to endif are
executed and finish bails out before reaching vim9script.
Export
:export
Exporting an item can be written as:
As this suggests, variables, constants, functions, classes (including abstract
classes), interfaces, enums, and types can be exported. Trying to export
something else gives E1043:
>vim9
vim9cmd export echo 0 # E1043: Invalid command after :export
<
E1042
:export can only be used in a Vim9 script scope. So, for example, although
exporting a :function is okay, trying to export an item within such a
function gives E1042:
>vim9
vim9script
export function F1042()
export var b: bool
endfunction
F1042() # E1042: Export can only be used in vim9script
<
E1044
An invalid argument can give E1044:
>vim9
vim9script
export def /a1044(): void
enddef # E1044: Export with invalid argument: ...
<
Import
:import
The exported items can be imported in another script. The import syntax has
two forms. The simpler form is:
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:
This makes each exported item in "myscript.vim" available as "myscript.item".
E1094
Importing is only allowed in the script-local scope. Trying to do so
elsewhere gives E1094; for example, from a :function or :def scope:
>vim9
vim9script
def F1094(): void
import 'nah.vim' # E1094: Import can only be used in a script
enddef
F1094()
<
E1053 E1071
Errors are given when either the {filename} is not found or it is invalid:
>vim9
vim9cmd import 'e1053.vim' # E1053: Could not import "e1053.vim"
vim9cmd import false # E1071: Invalid string for :import: false
<
:import-as
When the name of the file is long, ambiguous (such as with filenames that are
the same but in different directories), or if you just want to use a distinct
structure for the name, this form can be used:
In this longer form, {name} becomes a specific script-local name for the
imported namespace. Therefore {name} must consist of letters, digits, or '_',
and cannot start with a digit, like internal-variables. The {longfilename}
expression must evaluate to an existing filename.
The following script demonstrates using :import-as. It:
- Creates a constant, "TMP", for the {longfilename} of a temporary Vim9 script
file to import
- Writes a two-line Vim9 script to TMP
- Imports the Vim9 script file "as" the {name}, "that", and
- Echoes the result, showing the imported Vim9 script file's {longfilename}
and, on a separate line, the content of "that.myvar" (where "myvar" is an
exported variable in the imported script).
>vim9
vim9script
const TMP: string = tempname()
['vim9script', 'export var myvar: string = "YES!"']->writefile(TMP)
import TMP as that
echo $"Exported var 'myvar' in 'that' ({TMP}):\n" .. that.myvar
<
This example shows you can use "that.myvar", etc. You are free to choose the
name "that", or something that will be recognized as referring to the imported
script. It is best to avoid command names, command modifiers, and builtin
function names, because {name} will shadow any of those. It also is better to
begin the name with a lowercase letter because that avoids potential shadowing
of global user commands and functions. The {name} cannot be used for anything
else in the script, such as a function or variable name (see E1213), and it
cannot be assigned something else (see E1258).
In case the "." in the name is undesired, a local reference can be made for a
function:
This also works for constants:
This does not work for variables, since the value would be copied once and
when changing the variable the copy will change, not the original variable.
You need to use the full name (i.e., including the '.').
Imported items are intended to exist at the script level and only be imported
once. Also, :import can not be used in a :function or :def - see E1094.
The script name after :import can be:
- A relative path, starting "." or "..". This finds a file relative to the
location of the script file itself. This is useful to split up a large
plugin into several files.
- An absolute path, starting with "/" on Unix or "D:/" on MS-Windows. This
will rarely be used.
- A path not being relative or absolute. This will be found in the
"import" subdirectories of 'runtimepath' entries. The name will usually be
longer and unique, to avoid loading the wrong file.
Note that "after/import" is not used.
Once a Vim9 script file has been imported, the result is cached and it will
not be read again.
Many syntax and other errors may be given when importing. Examples:
E1047
- Using an invalid "as" {name}:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i-cc
# E1047: Syntax error in import: i-cc
<
E1048
- Trying to use a non-existent item in an imported script:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
echo i_cc.absent_item # E1048: Item not found in script: absent_item
<
E1049
- Trying to use a declared, but non-exported, item in an imported script:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
echo i_cc.prepended # E1049: Item not exported in script: prepended
<
E1060
When using the imported name, the '.' and the item name must be contiguous.
So there can be neither white space nor a line break:
- After the '.' (see E1074), or
- Before the '.', for example:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
echo i_cc .GetPath() # E1060: Expected dot after name: i_cc .Get...
<
E1088
- Attempting to have an imported script import itself:
>vim9
vim9script
const TMP: string = $'{tempname()}.vim'->substitute('\\', '/', 'g')
var lines: list<string> = ['vim9script', $'import "{TMP}" as e1088']
lines->writefile(TMP)
import TMP # E1088: Script cannot import itself
<
E1236
- Trying to use the script itself:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as cc
cc() # E1236: Cannot use cc itself, it is imported
<
E1257
- Not using "as {name}" when the imported filename does not end in ".vim":
>vim9
vim9script
const TMP: string = tempname()
['vim9script']->writefile(TMP)
import TMP # E1257: Imported script must use "as" or end in .vim: ...
<
E1258
- Omitting the '.' after an imported name:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
def F1258(): void
i_cc =
enddef
defcompile # E1258: No '.' after imported name: i_cc =
<
E1259
- Omitting the name after an imported name:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
def F1259(): void
i_cc.8 = 0
enddef
defcompile # E1259: Missing name after imported name: i_cc.8 = 0
<
E1260
- Attempting to :unlet an imported item:
>vim9
vim9script
const TMP: string = tempname()
['vim9script', 'export var b: bool']->writefile(TMP)
import TMP as e_unlet
unlet e_unlet.b # E1260: Cannot unlet an imported item: b
<
E1261
- Attempting to import the filename ".vim" without using "as". This script
writes the temporary file '.vim' to the operating system's applicable
temporary directory, then attempts to import it:
>vim9
vim9script
const TMPDIR: string = tempname()
->substitute('\\', '/', 'g') # Ensure Windows \ chars are /
->substitute('/[^/]\+$', '/', '') # Remove the filename
['vim9script']->writefile($'{TMPDIR}.vim')
echo $"Temporary import file name is: {TMPDIR}.vim"
import $'{TMPDIR}.vim' # E1261: Cannot import .vim without using "as"
<
E1262
- Trying to import the same script multiple times (including using different
"as" names):
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc1
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc2
# E1262: Cannot import the same script twice: .../ccomplete.vim
<
import-map
When you've imported a function from one script into a Vim9 script you can
refer to the imported function in a mapping by prefixing it with <SID>:
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>:
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:
>vim9
vim9script
const TMP: string = tempname()
['vim9script',
'export def MyDef(): void',
' popup_notification("exported.MyDef() was called", {time: 4000})',
'enddef']->writefile(TMP)
import TMP as exported
nnoremap <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:
When using the "as name" form, the namespace cannot be resolved on its own
(see also E1060). This example demonstrates using :imp with as successfully,
then the error:
>vim
let s:tmp = $'{tempname()}.vim'->substitute('\\', '/', 'g')
call writefile(['vim9script',
\ 'export function L()',
\ ' return "Vim9 script exporting a :function"',
\ 'endfunction'], s:tmp)
imp s:tmp as iLegacy
echo s:iLegacy.L() |" echoes 'Vim9 script exporting a :function'
echo s:iLegacy |" E1060: Expected dot after name: s:iLegacy
<
This also affects the use of <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:
: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.
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.
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:
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:
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:
==============================================================================
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 throw an error. If the types are known to be numbers then an "add
number" instruction can be used, which is faster. The error can be given at
compile time, no error handling is needed at runtime, since adding two numbers
almost never fails.
NOTE: As a tangential point, the exception is integer overflow, where the
result exceeds the maximum integer value. For example, adding to a 64-bit
signed integer where the result is greater than 2^63: >vim9
vim9script
echo 9223372036854775807 + 1 # -9223372036854775808
echo 2->pow(63)->float2nr() + 1 # -9223372036854775808
<
The syntax for types, using <type> for compound types, is similar to Java.
It is easy to understand and widely used. The type names are what were used
in Vim before, with some additions such as "void" and "bool".
Removing clutter and weirdness
Once decided that :def functions have different syntax than legacy functions,
we are free to add improvements to make the code more familiar for users who
know popular programming languages. In other words: remove weird things that
only Vim does.
We can also remove clutter, mainly things that were done to make Vim script
backwards compatible with the good old Vi commands.
Examples:
- Drop :call for calling a function and :eval for evaluating an
expression.
- Drop using a leading backslash for line continuation, automatically figure
out where an expression ends.
However, this does require that some things need to change:
- Comments start with # instead of ", to avoid confusing them with strings.
This is good anyway, it is also used by several popular languages.
- Ex command ranges need to be prefixed with a colon, to avoid confusion with
expressions (single quote can be a string or a mark, "/" can be divide or a
search command, etc.).
Goal is to limit the differences. A good criteria is that when the old syntax
is accidentally used you are very likely to get an error message.
Syntax and semantics from popular languages
Script writers have complained that the Vim script syntax is unexpectedly
different from what they are used to. To reduce this complaint popular
languages are used as an example. At the same time, we do not want to abandon
the well-known parts of legacy Vim script.
For many things TypeScript is followed. It's a recent language that is
gaining popularity and has similarities with Vim script. It also has a
mix of static typing (a variable always has a known value type) and dynamic
typing (a variable can have different types, this changes at runtime). Since
legacy Vim script is dynamically typed and a lot of existing functionality
(esp. builtin functions) depends on that, while static typing allows for much
faster execution, we need to have this mix in Vim9 script.
There is no intention to completely match TypeScript syntax and semantics. We
just want to take those parts that we can use for Vim and we expect Vim users
will be happy with. TypeScript is a complex language with its own history,
advantages and disadvantages. To get an idea of the disadvantages read the
book: "JavaScript: The Good Parts". Or find the article "TypeScript: the good
parts" and read the "Things to avoid" section.
People familiar with other languages (Java, Python, etc.) will also find
things in TypeScript that they do not like or do not understand. We'll try to
avoid those things.
Specific items from TypeScript we avoid:
- Overloading "+", using it both for addition and string concatenation. This
goes against legacy Vim script and often leads to mistakes. For that reason
we will keep using ".." for string concatenation. Lua also uses ".." this
way. And it allows for conversion to string for more values.
- TypeScript can use an expression like "99 || 'yes'" in a condition, but
cannot assign the value to a boolean. That is inconsistent and can be
annoying. Vim recognizes an expression with && or || and allows using the
result as a bool. The falsy-operator was added for the mechanism to use a
default value.
- TypeScript considers an empty string as Falsy, but an empty list or dict as
Truthy. That is inconsistent. In Vim an empty list and dict are also
Falsy.
- TypeScript has various "Readonly" types, which have limited usefulness,
since a type cast can remove the immutable nature. Vim locks the value,
which is more flexible, but is only checked at runtime.
- TypeScript has a complicated "import" statement that does not match how the
Vim import mechanism works. A much simpler mechanism is used instead, which
matches that the imported script is only sourced once.
Declarations
Legacy Vim script uses :let for every assignment, while in Vim9 declarations
are used. That is different, thus it's good to use a different command:
:var. This is used in many languages. The semantics might be slightly
different, but it's easily recognized as a declaration.
Using :const for constants is common, but the semantics varies. Some
languages only make the variable immutable, others also make the value
immutable. Since "final" is well known from Java for only making the variable
immutable we decided to use that. And then :const can be used for making
both immutable. This was also used in legacy Vim script and the meaning is
almost the same.
What we end up with is very similar to Dart:
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:
This is how we put types in a declaration:
Two alternatives were considered:
1. Put the type before the name, like Dart:
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 expr-!): >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:
Therefore the "??" operator was added:
result in a boolean. This is called the falsy-operator.
Import and Export
A problem of legacy Vim script is that by default all functions and variables
are global. It is possible to make them script-local, but then they are not
available in other scripts. This defies the concept of a package that only
exports selected items and keeps the rest local.
In Vim9 script a mechanism very similar to the JavaScript import and export
mechanism is supported. It is a variant to the existing :source command
that works like one would expect:
- Instead of making everything global by default, everything is script-local,
some of these are exported.
- When importing a script the symbols that are imported are explicitly listed,
avoiding name conflicts and failures if functionality is added later.
- The mechanism allows for writing a big, long script with a very clear API:
the exported functions, variables and classes.
- By using relative paths loading can be much faster for an import inside of a
package, no need to search many directories.
- Once an import has been used, its items are cached and loading it again is
not needed.
- The Vim-specific use of "s:" to make things script-local can be dropped.
When sourcing a Vim9 script (from 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:
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 150 sourceable scripts.
For a short primer on Vim9 script, other resources may be helpful too, e.g.,
https://learnxinyminutes.com/vim9script/.
1. What is Vim9 script? Vim9-script
2. Differences vim9-differences
3. New style functions fast-functions
4. Types vim9-types
5. Generic functions generic-functions
6. Namespace, Import and Export vim9script
7. Classes and interfaces vim9-classes
8. Rationale vim9-rationale
------------------------------------------------------------------------------
NOTE: In this vim9.txt help file, the Vim9 script code blocks beginning with
vim9script (and individual lines starting with vim9cmd) are Vim9 script
syntax highlighted. Also, they are sourceable, meaning you can run them to
see what they output. To source them, use :'<,'>source (see :source-range),
which is done by visually selecting the line(s) with V and typing :so.
For example, try it on the following Vim9 script:
>vim9
vim9script
echowindow "Welcome to Vim9 script!"
<
There are also code examples that should not be sourced - they explain
concepts that don't require a sourceable example. Such code blocks appear
in generic code syntax highlighting, like this:
def ThisFunction() # script-local
def g:ThatFunction() # global
export def Function() # for import and import autoload
def g:ThatFunction() # global
export def Function() # for import and import autoload
==============================================================================
1. What is Vim9 script? Vim9-script
Vim script has been growing over time, while preserving backwards
compatibility. That means bad choices from the past often can't be changed
and compatibility with Vi restricts possible solutions. Execution is quite
slow, each line is parsed every time it is executed.
The main goal of Vim9 script is to drastically improve performance. This is
accomplished by compiling commands into instructions that can be efficiently
executed. An increase in execution speed of 10 to 100 times can be expected.
A secondary goal is to avoid Vim-specific constructs and get closer to
commonly used programming languages, such as JavaScript, TypeScript and Java.
The performance improvements can only be achieved by not being 100% backwards
compatible. For example, making function arguments available in the "a:"
dictionary adds quite a lot of overhead. In a Vim9 function this dictionary
is not available. Other differences are more subtle, such as how errors are
handled.
Vim9 script syntax, semantics, and behavior apply in:
- a function defined with the :def command
- a script file where the first command is vim9script
- an autocommand defined in the context of the above
- a command prefixed with the vim9cmd command modifier
When using :function in a Vim9 script file the legacy syntax is used, with
the highest scriptversion. However, this can be confusing and is therefore
discouraged.
Vim9 script and legacy Vim script can be mixed. There is no requirement to
rewrite old scripts, they keep working as before. You may want to use a few
:def functions for code that needs to be fast.
:vim9[cmd] {cmd} :vim9 :vim9cmd
Evaluate and execute {cmd} using Vim9 script syntax,
semantics, and behavior. Useful when typing a command,
in a :function, or a legacy Vim script.
The following short example shows how a legacy Vim script
command and a :vim9cmd (so Vim9 script context) may appear
similar, though may differ not just syntactically, but also
semantically and behaviorally.
>vim
call popup_notification('entrée'[5:]
\ ->str2list()->string(), #{time: 7000})
vim9cmd popup_notification('entrée'[5 :]
->str2list()->string(), {time: 7000})
<
Notes: 1. The reason for the different output is Vim9 script
uses character indexing whereas legacy Vim script uses byte
indexing - see vim9-string-index.
2. Syntax is different too. In Vim9 script:
- The space in "[5 :]" is mandatory (see vim9-white-space).
- Line continuation with "\" is not required.
- The "#" (to avoid putting quotes around dictionary keys) is
neither required nor allowed - see #{}.
E1164
:vim9cmd cannot stand alone; it must be followed by a command.
:leg[acy] {cmd} :leg :legacy
Evaluate and execute {cmd} using legacy Vim script syntax,
semantics, and behavior. It is only applicable in a Vim9
script or a :def function. Using an equivalent script to
the one, above (see its notes for why the output differs):
>vim9
vim9script
# In legacy Vim script context the popup is [769, 101]
legacy call popup_notification('entrée'[5:]
\ ->str2list()->string(), #{time: 7000})
# In Vim9 script context the popup is [101]
popup_notification('entrée'[5 :]
->str2list()->string(), {time: 7000})
<
Vim9 script's script-local variables may be used by prefixing
"s:", like in legacy Vim script. This example shows the
difference in syntax: "k" for the script-local variable in
Vim9 script, "s:k" in the legacy Vim script context.
>vim9
vim9script
var k: string = "Okay"
echo k
legacy echo s:k
<
E1189
Using :legacy is not allowed in compiled Vim9 script
control flow contexts. For example:
>vim9
vim9script
def F_1189()
if v:version == 900
# E1189: Cannot use :legacy with this command: endif
legacy endif
enddef
F_1189()
< E1234
:legacy cannot stand alone; it must be followed by a command.
==============================================================================
2. Differences from legacy Vim script vim9-differences
Overview
E1146
Brief summary of the differences you will most often encounter when using Vim9
script and :def functions; details are below:
- Comments start with #, not ":
echo "hello" # comment
- Using a backslash for line continuation is hardly ever needed: echo "hello "
.. yourName
.. ", how are you?"
- White space is required in many places to improve readability,.. yourName
.. ", how are you?"
see vim9-white-space.
- Assign values without :let E1126 , declare variables with :var:
var count = 0
count += 3
- Constants can be declared with :final and :const:count += 3
final matches = [] # add to the list later
const names = ['Betty', 'Peter'] # cannot be changed
- :final cannot be used as an abbreviation of :finally.const names = ['Betty', 'Peter'] # cannot be changed
- Variables and functions are script-local by default.
- Functions are declared with argument types and return type:
def CallMe(count: number, message: string): bool
- Call functions without :call: writefile(['done'], 'file.txt')
- You cannot use old Ex commands::append
:change
:d directly followed by 'd' or 'p'.
:insert
:k
:mode
:open
:s with only flags
:t
:xit
- Some commands, especially those used for flow control, cannot be shortened.
E.g., :throw cannot be written as :th. vim9-no-shorten
- You cannot use curly-braces names.
- A range before a command must be prefixed with a colon:
:%s/this/that
- Executing a register with "@r" does not work, you can prepend a colon or use:exe:
:exe @a
- Unless mentioned specifically, the highest scriptversion is used.- When defining an expression mapping, the expression will be evaluated in the
context of the script where it was defined.
- When indexing a string the index is counted in characters, not bytes:
vim9-string-index
- Some possibly unexpected differences: vim9-gotchas.
Comments starting with #
In legacy Vim script comments start with double quote. In Vim9 script
comments start with #.
# declarations
var count = 0 # number of occurrences
var count = 0 # number of occurrences
The reason is that a double quote can also be the start of a string. In many
places, especially halfway through an expression with a line break, it's hard
to tell what the meaning is, since both a string and a comment can be followed
by arbitrary text. To avoid confusion only # comments are recognized. This
is the same as in shell scripts and Python programs.
In Vi # is a command to list text with numbers. In Vim9 script you can use
:number for that.
:101 number
To improve readability there must be a space between a command and the #
that starts a comment:
var name = value # comment
var name = value# error!
E1170var name = value# error!
Do not start a comment with #{, it looks like the legacy dictionary literal
and produces an error where this might be confusing. #{{ or #{{{ are OK,
these can be used to start a fold.
When starting to read a script file Vim doesn't know it is Vim9 script until
the vim9script command is found. Until that point you would need to use
legacy comments:
" legacy comment
vim9script
# Vim9 comment
vim9script
# Vim9 comment
That looks ugly, better put vim9script in the very first line:
vim9script
# Vim9 comment
# Vim9 comment
In legacy Vim script # is also used for the alternate file name. In Vim9
script you need to use %% instead. Instead of ## use %%% (stands for all
arguments).
Vim9 functions
E1099
A function defined with :def is compiled. Execution is many times faster,
often 10 to 100 times.
Many errors are already found when compiling, before the function is executed.
The syntax is strict, to enforce code that is easy to read and understand.
Compilation is done when any of these is encountered:
- the first time the function is called
- when the :defcompile command is encountered in the script after the
function was defined
- :disassemble is used for the function.
- a function that is compiled calls the function or uses it as a function
reference (so that the argument and return types can be checked)
E1091 E1191
If compilation fails it is not tried again on the next call, instead this
error is given: "E1091: Function is not compiled: {name}".
Compilation will fail when encountering a user command that has not been
created yet. In this case you can call execute() to invoke it at runtime.
def MyFunc()
execute('DefinedLater')
enddef
execute('DefinedLater')
enddef
:def has no options like :function does: "range", "abort", "dict" or
"closure". A :def function always aborts on an error (unless :silent! was
used for the command or the error was caught a :try block), does not get a
range passed, cannot be a "dict" function, and can always be a closure.
vim9-no-dict-function E1182
You can use a Vim9 Class (Vim9-class) instead of a "dict function".
You can also pass the dictionary explicitly:
def DictFunc(self: dict<any>, arg: string)
echo self[arg]
enddef
var ad = {item: 'value', func: DictFunc}
ad.func(ad, 'item')
echo self[arg]
enddef
var ad = {item: 'value', func: DictFunc}
ad.func(ad, 'item')
You can call a legacy dict function though:
func Legacy() dict
echo self.value
endfunc
def CallLegacy()
var d = {func: Legacy, value: 'text'}
d.func()
enddef
echo self.value
endfunc
def CallLegacy()
var d = {func: Legacy, value: 'text'}
d.func()
enddef
The argument types and return type need to be specified. The "any" type can
be used, type checking will then be done at runtime, like with legacy
functions.
E1106
Arguments are accessed by name, without "a:", just like any other language.
There is no "a:" dictionary or "a:000" list.
vim9-variable-arguments E1055 E1160 E1180
Variable arguments are defined as the last argument, with a name and have a
list type, similar to TypeScript. For example, a list of numbers:
def MyFunc(...itemlist: list<number>)
for item in itemlist
...
for item in itemlist
...
When a function argument is optional (it has a default value) passing v:none
as the argument results in using the default value. This is useful when you
want to specify a value for an argument that comes after an argument that
should use its default value. Example:
def MyFunc(one = 'one', last = 'last')
...
enddef
MyFunc(v:none, 'LAST') # first argument uses default value 'one'
...
enddef
MyFunc(v:none, 'LAST') # first argument uses default value 'one'
vim9-ignored-argument E1181
The argument "_" (an underscore) can be used to ignore the argument. This is
most useful in callbacks where you don't need it, but do need to give an
argument to match the call. E.g. when using map() two arguments are passed,
the key and the value, to ignore the key:
map(numberList, (_, v) => v * 2)
There is no error for using the "_" argument multiple times. No type needs tobe given.
Functions and variables are script-local by default
vim9-scopes
When using :function or :def to specify a new function at the script level
in a Vim9 script, the function is local to the script. Like prefixing "s:" in
legacy script. To define a global function or variable the "g:" prefix must
be used. For functions in a script that is to be imported and in an autoload
script "export" needs to be used for those to be used elsewhere.
def ThisFunction() # script-local
def g:ThatFunction() # global
export def Function() # for import and import autoload
E1075def g:ThatFunction() # global
export def Function() # for import and import autoload
When using :function or :def to specify a nested function inside a :def
function and no namespace was given, this nested function is local to the code
block it is defined in. It cannot be used in function() with a string
argument, pass the function reference itself:
def Outer()
def Inner()
echo 'inner'
enddef
var Fok = function(Inner) # OK
var Fbad = function('Inner') # does not work
def Inner()
echo 'inner'
enddef
var Fok = function(Inner) # OK
var Fbad = function('Inner') # does not work
Detail: this is because "Inner" will actually become a function reference to a
function with a generated name.
It is not possible to define a script-local function in a function. You can
define a local function and assign it to a script-local Funcref (it must have
been declared at the script level). It is possible to define a global
function by using the "g:" prefix.
When referring to a function and no "s:" or "g:" prefix is used, Vim will
search for the function:
- in the function scope, in block scopes
- in the script scope
Imported functions are found with the prefix from the :import command.
Since a script-local function reference can be used without "s:" the name must
start with an upper case letter even when using the "s:" prefix. In legacy
script "s:funcref" could be used, because it could not be referred to with
"funcref". In Vim9 script it can, therefore "s:Funcref" must be used to avoid
that the name interferes with builtin functions.
vim9-s-namespace E1268
The use of the "s:" prefix is not supported at the Vim9 script level. All
functions and variables without a prefix are script-local.
In :def functions the use of "s:" depends on the script: Script-local
variables and functions in a legacy script do use "s:", while in a Vim9 script
they do not use "s:". This matches what you see in the rest of the file.
In legacy functions the use of "s:" for script items is required, as before.
No matter if the script is Vim9 or legacy.
In all cases the function must be defined before used. That is when it is
called, when :defcompile causes it to be compiled, or when code that calls
it is being compiled (to figure out the return type).
The result is that functions and variables without a namespace can usually be
found in the script, either defined there or imported. Global functions and
variables could be defined anywhere (good luck finding out where! You can
often see where it was last set using :verbose).
E1102
Global functions can still be defined and deleted at nearly any time. In
Vim9 script script-local functions are defined once when the script is sourced
and cannot be deleted or replaced by itself (it can be by reloading the
script).
When compiling a function and a function call is encountered for a function
that is not (yet) defined, the FuncUndefined autocommand is not triggered.
You can use an autoload function if needed, or call a legacy function and have
FuncUndefined triggered there.
Reloading a Vim9 script clears functions and variables by default
vim9-reload E1149 E1150
When loading a legacy Vim script a second time nothing is removed, the
commands will replace existing variables and functions, create new ones, and
leave removed things hanging around.
When loading a Vim9 script a second time all existing script-local functions
and variables are deleted, thus you start with a clean slate. This is useful
if you are developing a plugin and want to try a new version. If you renamed
something you don't have to worry about the old name still hanging around.
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 items, use:
vim9script noclear
You want to use this in scripts that use a finish command to bail out at
some point when loaded again. E.g. when a buffer local option is set to a
function, the function does not need to be defined more than once:
vim9script noclear
setlocal completefunc=SomeFunc
if exists('*SomeFunc')
finish
endif
def SomeFunc()
....
setlocal completefunc=SomeFunc
if exists('*SomeFunc')
finish
endif
def SomeFunc()
....
Variable declarations with :var, :final and :const
vim9-declaration :var E1079
E1017 E1020 E1054 E1087 E1124
Local variables need to be declared with :var. Local constants need to be
declared with :final or :const. We refer to both as "variables" in this
section.
Variables can be local to a script, function or code block:
vim9script
var script_var = 123
def SomeFunc()
var func_var = script_var
if cond
var block_var = func_var
...
var script_var = 123
def SomeFunc()
var func_var = script_var
if cond
var block_var = func_var
...
The variables are only visible in the block where they are defined and nested
blocks. Once the block ends the variable is no longer accessible:
if cond
var inner = 5
else
var inner = 0
endif
echo inner # Error!
var inner = 5
else
var inner = 0
endif
echo inner # Error!
The declaration must be done earlier:
var inner: number
if cond
inner = 5
else
inner = 0
endif
echo inner
if cond
inner = 5
else
inner = 0
endif
echo inner
Although this is shorter and faster for simple values:
var inner = 0
if cond
inner = 5
endif
echo inner
E1025 E1128if cond
inner = 5
endif
echo inner
To intentionally hide a variable from code that follows, a block can be
used:
{
var temp = 'temp'
...
}
echo temp # Error!
var temp = 'temp'
...
}
echo temp # Error!
This is especially useful in a user command:
command -range Rename {
var save = @a
@a = 'some expression'
echo 'do something with ' .. @a
@a = save
}
var save = @a
@a = 'some expression'
echo 'do something with ' .. @a
@a = save
}
And with autocommands:
au BufWritePre *.go {
var save = winsaveview()
silent! exe ':%! some formatting command'
winrestview(save)
}
var save = winsaveview()
silent! exe ':%! some formatting command'
winrestview(save)
}
Although using a :def function probably works better.
E1022 E1103 E1130 E1131 E1133
E1134 E1581
Declaring a variable with a type but without an initializer will initialize to
false (for bool), empty (for string, list, dict, etc.) or zero (for number,
any, etc.). This matters especially when using the "any" type, the value will
default to the number zero. For example, when declaring a list, items can be
added:
var myList: list<number>
myList->add(7)
myList->add(7)
Initializing a variable to a null value, e.g. null_list, differs from not
initializing the variable. This throws an error:
var myList = null_list
myList->add(7) # E1130: Cannot add to null list
myList->add(7) # E1130: Cannot add to null list
E1016 E1052 E1066
In Vim9 script :let cannot be used. An existing variable is assigned to
without any command. The same for global, window, tab, buffer and Vim
variables, because they are not really declared. Those can also be deleted
with :unlet.
E1065
You cannot use :va to declare a variable, it must be written with the full
name :var. Just to make sure it is easy to read.
E1178
:lockvar does not work on local variables. Use :const and :final
instead.
The exists() and exists_compiled() functions do not work on local variables
or arguments.
E1006 E1041 E1167 E1168 E1213
Variables, functions and function arguments cannot shadow previously defined
or imported variables and functions in the same script file.
Variables may shadow Ex commands, rename the variable if needed.
Global variables must be prefixed with "g:", also at the script level.
vim9script
var script_local = 'text'
g:global = 'value'
var Funcref = g:ThatFunction
var script_local = 'text'
g:global = 'value'
var Funcref = g:ThatFunction
Global functions must be prefixed with "g:":
vim9script
def g:GlobalFunc(): string
return 'text'
enddef
echo g:GlobalFunc()
The "g:" prefix is not needed for auto-load functions.def g:GlobalFunc(): string
return 'text'
enddef
echo g:GlobalFunc()
vim9-function-defined-later
Although global functions can be called without the "g:" prefix, they must
exist when compiled. By adding the "g:" prefix the function can be defined
later. Example:
def CallPluginFunc()
if exists('g:loaded_plugin')
g:PluginFunc()
endif
enddef
if exists('g:loaded_plugin')
g:PluginFunc()
endif
enddef
If you do it like this, you get an error at compile time that "PluginFunc"
does not exist, even when "g:loaded_plugin" does not exist:
def CallPluginFunc()
if exists('g:loaded_plugin')
PluginFunc() # Error - function not found
endif
enddef
if exists('g:loaded_plugin')
PluginFunc() # Error - function not found
endif
enddef
You can use exists_compiled() to avoid the error, but then the function would
not be called, even when "g:loaded_plugin" is defined later:
def CallPluginFunc()
if exists_compiled('g:loaded_plugin')
PluginFunc() # Function may never be called
endif
enddef
if exists_compiled('g:loaded_plugin')
PluginFunc() # Function may never be called
endif
enddef
Since &opt = value is now assigning a value to option "opt", ":&" cannot be
used to repeat a :substitute command.
vim9-unpack-ignore
For an unpack assignment the underscore can be used to ignore a list item,
similar to how a function argument can be ignored:
[a, _, c] = theList
To ignore any remaining items: [a, b; _] = longList
E1163 E1080Declaring more than one variable at a time, using the unpack notation, is
possible. Each variable can have a type or infer it from the value:
var [v1: number, v2] = GetValues()
Use this only when there is a list with values, declaring one variable perline is much easier to read and change later.
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:
var [v1; v2] = [1, 2, 3] # v2 has type list<number>
var [v3; v4] = (1, 'a', true) # v4 has type tuple<string, bool>
When the value has type "any" the item types are not known and every variablevar [v3; v4] = (1, 'a', true) # v4 has type tuple<string, bool>
gets type "any".
Constants
vim9-const vim9-final
How constants work varies between languages. Some consider a variable that
can't be assigned another value a constant. JavaScript is an example. Others
also make the value immutable, thus when a constant uses a list, the list
cannot be changed. In Vim9 we can use both.
E1021 E1307
:const is used for making both the variable and the value a constant. Use
this for composite structures that you want to make sure will not be modified.
Example:
const myList = [1, 2]
myList = [3, 4] # Error!
myList[0] = 9 # Error!
myList->add(3) # Error!
:final E1125myList = [3, 4] # Error!
myList[0] = 9 # Error!
myList->add(3) # Error!
:final is used for making only the variable a constant, the value can be
changed. This is well known from Java. Example:
final myList = [1, 2]
myList = [3, 4] # Error!
myList[0] = 9 # OK
myList->add(3) # OK
myList = [3, 4] # Error!
myList[0] = 9 # OK
myList->add(3) # OK
It is common to write constants as ALL_CAPS, but you don't have to.
The constant only applies to the value itself, not what it refers to.
final females = ["Mary"]
const NAMES = [["John", "Peter"], females]
NAMES[0] = ["Jack"] # Error!
NAMES[0][0] = "Jack" # Error!
NAMES[1] = ["Emma"] # Error!
NAMES[1][0] = "Emma" # OK, now females[0] == "Emma"
const NAMES = [["John", "Peter"], females]
NAMES[0] = ["Jack"] # Error!
NAMES[0][0] = "Jack" # Error!
NAMES[1] = ["Emma"] # Error!
NAMES[1][0] = "Emma" # OK, now females[0] == "Emma"
Omitting :call and :eval
E1190
Functions can be called without :call:
writefile(lines, 'file')
Using :call is still possible, but this is discouraged.A method call without eval is possible, so long as the start is an
identifier or can't be an Ex command. For a function either "(" or "->" must
be following, without a line break. Examples:
myList->add(123)
g:myList->add(123)
[1, 2, 3]->Process()
{a: 1, b: 2}->Process()
"foobar"->Process()
("foobar")->Process()
'foobar'->Process()
('foobar')->Process()
g:myList->add(123)
[1, 2, 3]->Process()
{a: 1, b: 2}->Process()
"foobar"->Process()
("foobar")->Process()
'foobar'->Process()
('foobar')->Process()
In the rare case there is ambiguity between a function name and an Ex command,
prepend ":" to make clear you want to use the Ex command. For example, there
is both the :substitute command and the substitute() function. When the
line starts with substitute( this will use the function. Prepend a colon to
use the command instead:
:substitute(pattern (replacement (
If the expression starts with "!" this is interpreted as a shell command, not
negation of a condition. Thus this is a shell command:
!shellCommand->something
Put the expression in parentheses to use the "!" for negation: (!expression)->Method()
Note that while variables need to be defined before they can be used,
functions can be called before being defined. This is required to allow
for cyclic dependencies between functions. It is slightly less efficient,
since the function has to be looked up by name. And a typo in the function
name will only be found when the function is called.
Omitting function()
A user defined function can be used as a function reference in an expression
without function(). The argument types and return type will then be checked.
The function must already have been defined.
var Funcref = MyFunction
When using function() the resulting type is "func", a function with any
number of arguments and any return type (including void). The function can be
defined later if the argument is in quotes.
Lambda using => instead of ->
vim9-lambda
In legacy script there can be confusion between using "->" for a method call
and for a lambda. Also, when a "{" is found the parser needs to figure out if
it is the start of a lambda or a dictionary, which is now more complicated
because of the use of argument types.
To avoid these problems Vim9 script uses a different syntax for a lambda,
which is similar to JavaScript:
var Lambda = (arg) => expression
var Lambda = (arg): type => expression
E1157var Lambda = (arg): type => expression
No line break is allowed in the arguments of a lambda up to and including the
"=>" (so that Vim can tell the difference between an expression in parentheses
and lambda arguments). This is OK:
filter(list, (k, v) =>
v > 0)
This does not work:v > 0)
filter(list, (k, v)
=> v > 0)
This also does not work:=> v > 0)
filter(list, (k,
v) => v > 0)
But you can use a backslash to concatenate the lines before parsing:v) => v > 0)
filter(list, (k,
\ v)
\ => v > 0)
vim9-lambda-arguments E1172\ v)
\ => v > 0)
In legacy script a lambda could be called with any number of extra arguments,
there was no way to warn for not using them. In Vim9 script the number of
arguments must match. If you do want to accept any arguments, or any further
arguments, use "..._", which makes the function accept
vim9-variable-arguments. Example:
var Callback = (..._) => 'anything'
echo Callback(1, 2, 3) # displays "anything"
echo Callback(1, 2, 3) # displays "anything"
inline-function E1171
Additionally, a lambda can contain statements in {}:
var Lambda = (arg) => {
g:was_called = 'yes'
return expression
}
This can be useful for a timer, for example:g:was_called = 'yes'
return expression
}
var count = 0
var timer = timer_start(500, (_) => {
count += 1
echom 'Handler called ' .. count
}, {repeat: 3})
var timer = timer_start(500, (_) => {
count += 1
echom 'Handler called ' .. count
}, {repeat: 3})
The ending "}" must be at the start of a line. It can be followed by other
characters, e.g.:
var d = mapnew(dict, (k, v): string => {
return 'value'
})
No command can follow the "{", only a comment can be used there.return 'value'
})
Since the block ends at the first line starting with "}", the closing "}" of a
dictionary inside the block must not be at the start of a line. See
command-block for an example and the workaround.
command-block E1026
The block can also be used for defining a user command. Inside the block Vim9
syntax will be used.
This is an example of using here-docs:
com SomeCommand {
g:someVar =<< trim eval END
ccc
ddd
END
}
g:someVar =<< trim eval END
ccc
ddd
END
}
If the statements include a dictionary, its closing bracket must not be
written at the start of a line. Otherwise, it would be parsed as the end of
the block. This does not work:
command NewCommand {
g:mydict = {
'key': 'value',
} # ERROR: will be recognized as the end of the block
}
Put the '}' after the last item to avoid this:g:mydict = {
'key': 'value',
} # ERROR: will be recognized as the end of the block
}
command NewCommand {
g:mydict = {
'key': 'value' }
}
g:mydict = {
'key': 'value' }
}
Rationale: The "}" cannot be after a command because it would require parsing
the commands to find it. For consistency with that no command can follow the
"{". Unfortunately this means using "() => { command }" does not work, line
breaks are always required.
vim9-curly
To avoid the "{" of a dictionary literal to be recognized as a statement block
wrap it in parentheses:
var Lambda = (arg) => ({key: 42})
Also when confused with the start of a command block:
({
key: value
})->method()
key: value
})->method()
Automatic line continuation
vim9-line-continuation E1097
In many cases it is obvious that an expression continues on the next line. In
those cases there is no need to prefix the line with a backslash (see
line-continuation). For example, when a list spans multiple lines:
var mylist = [
'one',
'two',
]
And when a dict spans multiple lines:'one',
'two',
]
var mydict = {
one: 1,
two: 2,
}
With a function call:one: 1,
two: 2,
}
var result = Func(
arg1,
arg2
)
arg1,
arg2
)
For binary operators in expressions not in [], {} or () a line break is
possible just before or after the operator. For example:
var text = lead
.. middle
.. end
var total = start +
end -
correction
var result = positive
? PosFunc(arg)
: NegFunc(arg)
.. middle
.. end
var total = start +
end -
correction
var result = positive
? PosFunc(arg)
: NegFunc(arg)
For a method call using "->" and a member using a dot, a line break is allowed
before it:
var result = GetBuilder()
->BuilderSetWidth(333)
->BuilderSetHeight(777)
->BuilderBuild()
var result = MyDict
.member
->BuilderSetWidth(333)
->BuilderSetHeight(777)
->BuilderBuild()
var result = MyDict
.member
For commands that have an argument that is a list of commands, the | character
at the start of the line indicates line continuation:
autocmd BufNewFile *.match if condition
| echo 'match'
| endif
| echo 'match'
| endif
Note that this means that in heredoc the first line cannot start with a bar:
var lines =<< trim END
| this doesn't work
END
Either use an empty line at the start or do not use heredoc. Or temporarily| this doesn't work
END
add the "C" flag to 'cpoptions':
set cpo+=C
var lines =<< trim END
| this works
END
set cpo-=C
If the heredoc is inside a function 'cpoptions' must be set before :def andvar lines =<< trim END
| this works
END
set cpo-=C
restored after the :enddef.
In places where line continuation with a backslash is still needed, such as
splitting up a long Ex command, comments can start with '#\ ':
syn region Text
\ start='foo'
#\ comment
\ end='bar'
Like with legacy script '"\ ' is used. This is also needed when line\ start='foo'
#\ comment
\ end='bar'
continuation is used without a backslash and a line starts with a bar:
au CursorHold * echom 'BEFORE bar'
#\ some comment
| echom 'AFTER bar'
#\ some comment
| echom 'AFTER bar'
E1050
To make it possible for the operator at the start of the line to be
recognized, it is required to put a colon before a range. This example will
add "start" and "print":
var result = start
+ print
Like this: var result = start + print
This will assign "start" and print a line:
var result = start
:+ print
After the range an Ex command must follow. Without the colon you can call a
function without :call, but after a range you do need it:
MyFunc()
:% call MyFunc()
:% call MyFunc()
Note that the colon is not required for the +cmd argument:
edit +6 fname
It is also possible to split a function header over multiple lines, in between
arguments:
def MyFunc(
text: string,
separator = '-'
): string
text: string,
separator = '-'
): string
Since a continuation line cannot be easily recognized the parsing of commands
has been made stricter. E.g., because of the error in the first line, the
second line is seen as a separate command:
popup_create(some invalid expression, {
exit_cb: Func})
Now "exit_cb: Func})" is actually a valid command: save any changes to theexit_cb: Func})
file "_cb: Func})" and exit. To avoid this kind of mistake in Vim9 script
there must be white space between most command names and the argument.
E1144
However, the argument of a command that is a command won't be recognized. For
example, after "windo echo expr" a line break inside "expr" will not be seen.
Notes:
- "enddef" cannot be used at the start of a continuation line, it ends the
current function.
- No line break is allowed in the LHS of an assignment. Specifically when
unpacking a list :let-unpack. This is OK:
[var1, var2] =
Func()
This does not work:Func()
[var1,
var2] =
Func()
- No line break is allowed in between arguments of an :echo, :execute andvar2] =
Func()
similar commands. This is OK:
echo [1,
2] [3,
4]
This does not work:2] [3,
4]
echo [1, 2]
[3, 4]
- In some cases it is difficult for Vim to parse a command, especially when[3, 4]
commands are used as an argument to another command, such as :windo,
:command or :autocmd. In those cases the line continuation with a
backslash has to be used. For example:
command! Foo call Bar('x', {
\ 'key': 'value',
\ })
autocmd BufWritePre * call Bar('x', {
\ 'key': 'value',
\ })
\ 'key': 'value',
\ })
autocmd BufWritePre * call Bar('x', {
\ 'key': 'value',
\ })
White space
vim9-white-space E1004 E1068 E1069 E1074 E1127 E1202
Vim9 script enforces proper use of white space. This is no longer allowed:
var name=234 # Error!
var name= 234 # Error!
var name =234 # Error!
There must be white space before and after the "=":var name= 234 # Error!
var name =234 # Error!
var name = 234 # OK
White space must also be put before the # that starts a comment after acommand:
var name = 234# Error!
var name = 234 # OK
var name = 234 # OK
White space is required around most operators.
White space is required in a sublist (list slice) around the ":", except at
the start and end:
otherlist = mylist[v : count] # v:count has a different meaning
otherlist = mylist[:] # make a copy of the List
otherlist = mylist[v :]
otherlist = mylist[: v]
otherlist = mylist[:] # make a copy of the List
otherlist = mylist[v :]
otherlist = mylist[: v]
White space is not allowed:
- Between a function name and the "(":
Func (arg) # Error!
Func
\ (arg) # Error!
Func
(arg) # Error!
Func(arg) # OK
Func(
arg) # OK
Func(
arg # OK
)
E1205Func
\ (arg) # Error!
Func
(arg) # Error!
Func(arg) # OK
Func(
arg) # OK
Func(
arg # OK
)
White space is not allowed in a :set command between the option name and a
following "&", "!", "<", "=", "+=", "-=" or "^=".
No curly braces expansion
curly-braces-names cannot be used.
Command modifiers are not ignored
E1176
Using a command modifier for a command that does not use it gives an error.
E1082
Also, using a command modifier without a following command is now an error.
Dictionary literals
vim9-literal-dict E1014
Traditionally Vim has supported dictionary literals with a {} syntax:
let dict = {'key': value}
Later it became clear that using a simple text key is very common, thus
literal dictionaries were introduced in a backwards compatible way:
let dict = #{key: value}
However, this #{} syntax is unlike any existing language. As it turns out
that using a literal key is much more common than using an expression, and
considering that JavaScript uses this syntax, using the {} form for dictionary
literals is considered a much more useful syntax. In Vim9 script the {} form
uses literal keys:
var dict = {key: value}
This works for alphanumeric characters, underscore and dash. If you want to
use another character, use a single or double quoted string:
var dict = {'key with space': value}
var dict = {"key\twith\ttabs": value}
var dict = {'': value} # empty key
E1139var dict = {"key\twith\ttabs": value}
var dict = {'': value} # empty key
In case the key needs to be an expression, square brackets can be used, just
like in JavaScript:
var dict = {["key" .. nr]: value}
The key type can be string, number, bool or float. Other types result in an
error. Without using [] the value is used as a string, keeping leading zeros.
An expression given with [] is evaluated and then converted to a string.
Leading zeros will then be dropped:
var dict = {000123: 'without', [000456]: 'with'}
echo dict
{'456': 'with', '000123': 'without'}
A float only works inside [] because the dot is not accepted otherwise:echo dict
{'456': 'with', '000123': 'without'}
var dict = {[00.013]: 'float'}
echo dict
{'0.013': 'float'}
echo dict
{'0.013': 'float'}
No :xit, :t, :k, :append, :change or :insert
E1100
These commands are too easily confused with local variable names.
Instead of :x or :xit you can use :exit.
Instead of :t you can use :copy.
Instead of :k you can use :mark.
Comparators
The 'ignorecase' option is not used for comparators that use strings.
Thus "=~" works like "=~#".
"is" and "isnot" (expr-is and expr-isnot) when used on strings now return
false. In legacy script they just compare the strings, in Vim9 script they
check identity, and strings are copied when used, thus two strings are never
the same (this might change someday if strings are not copied but reference
counted).
Abort after error
In legacy script, when an error is encountered, Vim continues to execute
following lines. This can lead to a long sequence of errors and need to type
CTRL-C to stop it. In Vim9 script execution of commands stops at the first
error. Example:
vim9script
var x = does-not-exist
echo 'not executed'
var x = does-not-exist
echo 'not executed'
For loop
E1254
The loop variable must not be declared yet:
var i = 1
for i in [1, 2, 3] # Error!
for i in [1, 2, 3] # Error!
It is possible to use a global variable though:
g:i = 1
for g:i in [1, 2, 3]
echo g:i
endfor
for g:i in [1, 2, 3]
echo g:i
endfor
Legacy Vim script has some tricks to make a for loop over a list handle
deleting items at the current or previous item. In Vim9 script it just uses
the index, if items are deleted then items in the list will be skipped.
Example legacy script:
let l = [1, 2, 3, 4]
for i in l
echo i
call remove(l, index(l, i))
endfor
Would echo:for i in l
echo i
call remove(l, index(l, i))
endfor
1
2
3
4
In compiled Vim9 script you get:
1
3
Generally, you should not change the list that is iterated over. Make a copy
first if needed.
When looping over a list of lists, the nested lists can be changed. The loop
variable is "final", it cannot be changed but what its value can be changed.
E1306
The depth of loops, :for and :while loops added together, cannot exceed 10.
Conditions and expressions
vim9-boolean
Conditions and expressions are mostly working like they do in other languages.
Some values are different from legacy Vim script:
value legacy Vim script Vim9 script
0 falsy falsy
1 truthy truthy
99 truthy Error!
"0" falsy Error!
"99" truthy Error!
"text" falsy Error!
For the "??" operator and when using "!" then there is no error, every value
is either falsy or truthy. This is mostly like JavaScript, except that an
empty list and dict is falsy:
type truthy when
bool true, v:true or 1
number non-zero
float non-zero
string non-empty
blob non-empty
list non-empty (different from JavaScript)
tuple non-empty (different from JavaScript)
dictionary non-empty (different from JavaScript)
func when there is a function name
special true or v:true
job when not NULL
channel when not NULL
class not applicable
object when not NULL
enum not applicable
enum value always
typealias not applicable
The boolean operators "||" and "&&" expect the values to be boolean, zero or
one:
1 || false == true
0 || 1 == true
0 || false == false
1 && true == true
0 && 1 == false
8 || 0 Error!
'yes' && 0 Error!
[] || 99 Error!
0 || 1 == true
0 || false == false
1 && true == true
0 && 1 == false
8 || 0 Error!
'yes' && 0 Error!
[] || 99 Error!
When using "!" for inverting, there is no error for using any type and the
result is a boolean. "!!" can be used to turn any value into boolean:
!'yes' == false
!![] == false
!![1, 2, 3] == true
!![] == false
!![1, 2, 3] == true
When using ".." for string concatenation arguments of simple types are
always converted to string:
'hello ' .. 123 == 'hello 123'
'hello ' .. v:true == 'hello true'
'hello ' .. v:true == 'hello true'
Simple types are Number, Float, Special and Bool. For other types string()
should be used.
false true null null_blob null_channel
null_class null_dict null_function null_job
null_list null_object null_partial null_string
E1034
In Vim9 script one can use the following predefined values:
true
false
null
null_blob
null_channel
null_class
null_dict
null_function
null_job
null_list
null_tuple
null_object
null_partial
null_string
true is the same as v:true, false the same as v:false, null the samefalse
null
null_blob
null_channel
null_class
null_dict
null_function
null_job
null_list
null_tuple
null_object
null_partial
null_string
as v:null.
While null has the type "special", the other "null_" values have the type
indicated by their name. Quite often a null value is handled the same as an
empty value, but not always. The values can be useful to clear a script-local
variable, since they cannot be deleted with :unlet. E.g.:
var theJob = job_start(...)
# let the job do its work
theJob = null_job
# let the job do its work
theJob = null_job
The values can also be useful as the default value for an argument:
def MyFunc(b: blob = null_blob)
# Note: compare against null, not null_blob,
# to distinguish the default value from an empty blob.
if b == null
# b argument was not given
See null-compare for more information about testing against null.# Note: compare against null, not null_blob,
# to distinguish the default value from an empty blob.
if b == null
# b argument was not given
It is possible to compare null with any value, this will not give a type
error. However, comparing null with a number, float or bool will always
result in false. This is different from legacy script, where comparing
null with zero or false would return true.
vim9-false-true
When converting a boolean to a string false and true are used, not
v:false and v:true like in legacy script. v:none has no none
replacement, it has no equivalent in other languages.
vim9-string-index
Indexing a string with [idx] or taking a slice with [idx : idx] uses character
indexes instead of byte indexes. Composing characters are included.
Example:
echo 'bár'[1]
In legacy script this results in the character 0xc3 (an illegal byte), in Vim9script this results in the string 'á'.
A negative index is counting from the end, "[-1]" is the last character.
To exclude the last character use slice().
To count composing characters separately use strcharpart().
If the index is out of range then an empty string results.
In legacy script "++var" and "--var" would be silently accepted and have no
effect. This is an error in Vim9 script.
Numbers starting with zero are not considered to be octal, only numbers
starting with "0o" are octal: "0o744". scriptversion-4
What to watch out for
vim9-gotchas
Vim9 was designed to be closer to often used programming languages, but at the
same time tries to support the legacy Vim commands. Some compromises had to
be made. Here is a summary of what might be unexpected.
Ex command ranges need to be prefixed with a colon.
-> legacy Vim: shifts the previous line to the right
->func() Vim9: method call in a continuation line
:-> Vim9: shifts the previous line to the right
->func() Vim9: method call in a continuation line
:-> Vim9: shifts the previous line to the right
%s/a/b legacy Vim: substitute on all lines
x = alongname
% another Vim9: modulo operator in a continuation line
:%s/a/b Vim9: substitute on all lines
't legacy Vim: jump to mark t
'text'->func() Vim9: method call
:'t Vim9: jump to mark t
x = alongname
% another Vim9: modulo operator in a continuation line
:%s/a/b Vim9: substitute on all lines
't legacy Vim: jump to mark t
'text'->func() Vim9: method call
:'t Vim9: jump to mark t
Some Ex commands can be confused with assignments in Vim9 script:
g:name = value # assignment
:g:pattern:cmd # :global command
:g:pattern:cmd # :global command
To avoid confusion between a :global or :substitute command and an
expression or assignment, a few separators cannot be used when these commands
are abbreviated to a single character: ':', '-' and '.'.
g:pattern:cmd # invalid command - ERROR
s:pattern:repl # invalid command - ERROR
g-pattern-cmd # invalid command - ERROR
s-pattern-repl # invalid command - ERROR
g.pattern.cmd # invalid command - ERROR
s.pattern.repl # invalid command - ERROR
s:pattern:repl # invalid command - ERROR
g-pattern-cmd # invalid command - ERROR
s-pattern-repl # invalid command - ERROR
g.pattern.cmd # invalid command - ERROR
s.pattern.repl # invalid command - ERROR
Also, there cannot be a space between the command and the separator:
g /pattern/cmd # invalid command - ERROR
s /pattern/repl # invalid command - ERROR
s /pattern/repl # invalid command - ERROR
Functions defined with :def compile the whole function. Legacy functions
can bail out, and the following lines are not parsed:
func Maybe()
if !has('feature')
return
endif
use-feature
endfunc
Vim9 functions are compiled as a whole:if !has('feature')
return
endif
use-feature
endfunc
def Maybe()
if !has('feature')
return
endif
use-feature # May give a compilation error
enddef
For a workaround, split it in two functions:if !has('feature')
return
endif
use-feature # May give a compilation error
enddef
func Maybe()
if has('feature')
call MaybeInner()
endif
endfunc
if has('feature')
def MaybeInner()
use-feature
enddef
endif
Or put the unsupported code inside an if with a constant expression thatif has('feature')
call MaybeInner()
endif
endfunc
if has('feature')
def MaybeInner()
use-feature
enddef
endif
evaluates to false:
def Maybe()
if has('feature')
use-feature
endif
enddef
The exists_compiled() function can also be used for this.if has('feature')
use-feature
endif
enddef
vim9-user-command
Another side effect of compiling a function is that the presence of a user
command is checked at compile time. If the user command is defined later an
error will result. This works:
command -nargs=1 MyCommand echom <q-args>
def Works()
MyCommand 123
enddef
This will give an error for "MyCommand" not being defined:def Works()
MyCommand 123
enddef
def Works()
command -nargs=1 MyCommand echom <q-args>
MyCommand 123
enddef
A workaround is to invoke the command indirectly with :execute:command -nargs=1 MyCommand echom <q-args>
MyCommand 123
enddef
def Works()
command -nargs=1 MyCommand echom <q-args>
execute 'MyCommand 123'
enddef
command -nargs=1 MyCommand echom <q-args>
execute 'MyCommand 123'
enddef
Note that for unrecognized commands there is no check for "|" and a following
command. This will give an error for missing endif:
def Maybe()
if has('feature') | use-feature | endif
enddef
if has('feature') | use-feature | endif
enddef
Other differences
Patterns are used like 'magic' is set, unless explicitly overruled.
The 'edcompatible' option value is not used.
The 'gdefault' option value is not used.
You may also find this wiki useful. It was written by an early adopter of
Vim9 script: https://github.com/lacygoill/wiki/blob/master/vim/vim9.md
:++ :--
The ++ and -- commands have been added. They are very similar to adding or
subtracting one:
++var
var += 1
--var
var -= 1
var += 1
--var
var -= 1
Using ++var or --var in an expression is not supported yet.
==============================================================================
3. New style functions fast-functions
:def
:def[!] {name}([arguments])[: {return-type}]
Define a new function by the name {name}. The body of
the function follows in the next lines, until the
matching :enddef.
E1073
{name} cannot be reused at the script-local level:
>vim9
vim9script
def F_1073()
enddef
def F_1073() # E1073: Name already defined: <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:
>vim9
vim9script
def F_1077(x): void
# E1077: Missing argument type for x
enddef
<
For the second form, because the declaration does not
specify it, Vim infers the type. For both second and
third forms, a default {value} applies when the
caller omits it. Examples:
>vim9
vim9script
def SecondForm(arg = "Hi"): void
echo $'2. arg is a "{arg->typename()}" type ' ..
$'and the default value of arg is "{arg}"'
enddef
SecondForm()
def ThirdForm(arg2: number = 9): void
echo $'3. default value of arg2 is {arg2}'
enddef
ThirdForm()
< E1123
Arguments in a builtin function called in a :def
function must have commas between arguments:
>vim9
vim9script
def F_1123(a: number, b: number): void
echo max(a b) # E1123: Missing comma before ar...
enddef
F_1123(1, 2)
< E1003 E1027 E1096
The type of value used with :return must match
{return-type}. When {return-type} is omitted or is
"void" the function is not allowed to return
anything. Examples:
>vim9
vim9script
def F_1003(): bool
return # E1003: Missing return value
enddef
F_1003()
< >vim9
vim9script
def F_1027(): bool
echo false # E1027: Missing return statement
enddef
F_1027()
< >vim9
vim9script
def F_1096(): void
return false # E1096: Returning a value in a f...
enddef
F_1096()
< E1056 E1059
When ": {return-type}" is specified, {return-type}
cannot be omitted (leaving a hanging colon). The ": "
also cannot be preceded by white space. Examples:
>vim
def F_1056():
# E1056: Expected a type:
enddef
def F_1059() : bool
# E1059: No white space allowed before colon: ...
enddef
<
The function will be compiled into instructions when
called or when either :defcompile or :disassemble is
used. (For an example, see :disassemble.) Syntax
and type errors will be produced at that time.
E1058
It is possible to nest :def inside another :def or
:function only up to 49 levels deep. At 50 or more
levels, it is a E1058 error.
E1117
[!] is allowed only in legacy Vim script because it
permits function redefinition (as with :function!).
In Vim9 script, ! is not allowed because script-local
functions cannot be deleted or redefined, though they
can be removed by reloading the script. Also, nested
functions cannot use ! for redefinition. Examples:
>vim
" Legacy Vim script :def! example
def! LegacyFunc()
echo "def! is allowed in a legacy Vim script"
enddef
call LegacyFunc()
< >vim9
vim9script
def F1117()
def! InnerFunc()
# E1117: Cannot use ! with nested :def
enddef
enddef
F1117()
< >vim9
vim9script
def! F_477(): void # E477: No ! allowed
enddef
< >vim9
vim9script
def F_1084(): void
enddef
delfunction! F_1084
# E1084: Cannot delete Vim9 script function F_1084
<
Note: The generic error E1028 ("Compiling :def
function failed") indicates an undeterminable error
during compilation. If reproducible, it may be
reported at https://github.com/vim/vim/issues as
it could represent a gap in Vim's error reporting.
:enddef
E1057 E1152 E1173
:enddef End of a function defined with :def. It should be on
a line by itself. Examples:
>vim9
vim9script
def MyFunc()
echo 'Do Something' | enddef
# E1057: Missing :enddef
< >vim9
vim9script
def F_1173()
enddef echo 'X'
# E1173: Text found after enddef: echo 'X'
< >vim9
vim9script
def F_1152()
function X()
enddef # E1152: Mismatched enddef
enddef
<
You may also find this wiki useful. It was written by an early adopter of
Vim9 script: https://github.com/lacygoill/wiki/blob/master/vim/vim9.md
vim9-s:var
When referencing a script-local variable, the context determines whether using
the "s:" prefix is either mandatory, optional, or gives E1268. The context
factors are whether the script version is Vim9 script or legacy Vim script and
whether the reference is at the script-local level, within a :def function,
or within a :function. The three rules are:
1. In a :function, "s:" is always mandatory. This is regardless of the
script type or the function's parent context (such as nested within
another function). Similarly, "s:" is also mandatory in the script-local
scope of a legacy Vim script.
2. In a Vim9 script, "s:" always gives E1268 when used in a :def function,
regardless of the function's parent context. Similarly, it gives E1268 in
the script-local scope of a Vim9 script.
3. In a legacy Vim script, "s:" is optional in a :def function, regardless
of the function's parent context.
The following three scripts demonstrate these rules:
>vim
" 1. In a :function, "s:" is always mandatory. It is also mandatory
" in a legacy Vim script's script-local scope
let s:MyVar = v:true
echo s:MyVar | " v:true
" echo MyVar (Would give E121: Undefined variable: MyVar)
vim9cmd echo MyVar # true
function! MyFunc()
echo s:MyVar | " v:true
" echo MyVar (Would give E121: Undefined variable: MyVar)
vim9cmd echo MyVar # true
endfunction
call MyFunc()
< >vim9
vim9script
# 2. In a Vim9 script, "s:" gives E1268 when used in any :def function
# and in the script-local scope
var MyVar: bool = true
echo MyVar # true
# echo s:MyVar (Would give E1268: Cannot use s: in Vim9...)
legacy echo s:MyVar | # v:true
def MyFunc()
echo MyVar # true
# echo s:MyVar (Would give E1268: Cannot use s: in Vim9...)
legacy echo s:MyVar | # v:true
enddef
MyFunc()
< >vim
" 3. In a legacy Vim script, "s:" is optional in a :def function
let s:MyVar = v:true
function! Outer()
def! MyFunc()
echo MyVar # true
echo s:MyVar # true
enddef
call MyFunc()
endfunction
call Outer()
<
Using exists(), which is evaluated at runtime, cannot be used conditionally
to skip undeclared variables, though exists_compiled(), which is evaluated at
compile time, may be used. For example:
>vim9
vim9script
def MyDef()
if exists_compiled('MyVar') # evaluated at compile time
echo $"MyVar = {MyVar}" # MyVar = 1
endif
if exists_compiled('MyVar2') # evaluated at compile time
echo $"MyVar2 = {MyVar2}" # not reached
else
echo "MyVar2 does not exist at compile time"
endif
if exists('MyVar') # evaluated at runtime
echo $"MyVar = {MyVar}" # MyVar = 1
endif
if exists('MyVar2') # evaluated at runtime
# The following would give E1001: Variable not found: MyVar2
# echo MyVar2
else
echo "MyVar2 does not exist at runtime"
endif
enddef
var MyVar: number = 1 # Declared before MyDef() is compiled
MyDef()
var MyVar2: number = 2 # Declared after MyDef() is compiled
<
< E1269
Script-local variables in a Vim9 script must be declared at the script
level. They cannot be created in a :def function and may not be declared
in a legacy function with the "s:" prefix. For example:
>vim9
vim9script
function F_1269()
let s:i_wish = v:true
endfunction
F_1269()
# E1269: Cannot create a Vim9 script variable in a function: s:i_wish
<
:defc :defcompile
:defc[ompile] Compile functions and classes (class-compile)
defined in the current script that were not compiled
yet. This will report any errors found during
compilation.
Example: When the three lines (up to and including
enddef) are sourced, there is no error because the
Vim9 :def function is not compiled. However, if all
four lines are sourced, compilation fails:
>vim9
vim9script
def F_1027(): string
enddef
defcompile F_1027 # E1027: Missing return statement
<
:defc[ompile] MyClass Compile all methods in a class. (See :disassemble
for an example.)
:defc[ompile] {func}
:defc[ompile] debug {func}
:defc[ompile] profile {func}
Compile function {func}, if needed. Use "debug" and
"profile" to specify the compilation mode.
This will report any errors found during compilation.
{func} can also be "ClassName.functionName" to
compile a function or method in a class.
{func} can also be "ClassName" to compile all
functions and methods in a class.
:disa :disassemble
:disa[ssemble] {func} Show the instructions generated for {func}.
This is for debugging and testing.
If {func} is not found, error E1061 occurs.
{func} can also be "ClassName.functionName" to
disassemble a function in a class.
The following example demonstrates using :defcompile
with a class and :disassemble with a
"ClassName.functionName" (positioning the cursor on
the last line of the visually sourced script):
>vim9
vim9script
class Line
var lnum: number
def new(this.lnum)
enddef
def SetLnum()
cursor(this.lnum, 52)
enddef
endclass
defcompile Line
disassemble Line.SetLnum
var vlast: Line = Line.new(line("'>"))
vlast.SetLnum() # Cursor is positioned here->_
<
:disa[ssemble] profile {func}
Like :disassemble but with the instructions used for
profiling.
:disa[ssemble] debug {func}
Like :disassemble but with the instructions used for
debugging.
Note: For command line completion of {func}, script-local functions
are shown with their <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:
>vim9
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:
>vim9
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:
>vim9
vim9script
def EditNewBlah()
var fname: string = 'blah.txt'
split
edit =fname
enddef
EditNewBlah() # A new split is created as buffer 'blah.txt'
<
vim9-closure
Closures defined in a loop can either share a variable or each have their own
copy, depending on where the variable is declared. With a variable declared
outside the loop, all closures reference the same shared variable.
The following example demonstrates the consequences, with the "outloop"
variable existing only once:
>vim9
vim9script
var flist: list<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:
>vim9
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:
>vim9
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:
>vim9
vim9script
def F_1248(): void
var n: number
var F: func = () => {
n += 1
}
try
execute printf("call %s()", F)
catch
echo v:exception
endtry
enddef
F_1248() # Vim(call):E1248: Closure called from invalid context
<
In Vim9 script, a loop variable is invalid after the loop is closed.
For example, this timer will echo 0 to 2 on separate lines. However, if
the variable "n" is used after the :endfor, that is an E121 error:
>vim9
vim9script
for n in range(3)
var nr: number = n
timer_start(1000 * n, (_) => {
echowindow nr
})
endfor
try
echowindow n
catch
echo v:exception
endtry
<
Note: Using :echowindow is useful in a timer because messages go
into a popup and will not interfere with what the user is doing when
it triggers.
Converting a :function to a :def
convert_legacy_function_to_vim9
convert_:function_to_:def
There are many changes that need to be made to convert a :function to
a :def function. The following are some of them:
- Change let used to declare variables to one of var, const, or final,
and remove the "s:" from each script-variable.
- Change func or function to def.
- Change endfunc or endfunction to enddef.
- Add the applicable type (or "any") to each function argument.
- Remove "a:" from each function-argument.
- Remove inapplicable options such as :func-range, :func-abort,
:func-dict, and :func-closure.
- If the function returns something, add the return type. (Ideally, add
"void" if it does not return anything.)
- Remove line continuation backslashes from places they are not required.
- Remove let for assigning values to global (g:), buffer (b:),
window (w:), tab (t:), and local (l:) variables.
- Rewrite lambda expressions in Vim9 script syntax (see vim9-lambda).
- Change comments to start with # (preceded by white space) instead of ".
- Insert white space in expressions where required (see vim9-white-space).
- Change "." used for string concatenation to " .. ". (Alternatively, use
an interpolated-string.)
The following legacy Vim script and Vim9 script examples demonstrate all
those differences. First, legacy Vim script:
>vim
let s:lnum=0
function Leg8(arg) abort
let l:pre=['Result',
\': ']
let b:arg=a:arg
let s:lnum+=2
let b:arg*=4
let l:result={pre->join(pre,'')}(l:pre)
return l:result.(b:arg+s:lnum)"no space before comment
endfunction
call Leg8(10)->popup_notification(#{time: 3000})" Pops up 'Result: 42'
<
The equivalent in Vim9 script:
>vim9
vim9script
var lnum: number
def Vim9(arg: number): string
final pre = ['Result',
': ']
b:arg = arg
lnum += 2
b:arg *= 4
const RESULT: string = ((lpre) => join(lpre, ''))(pre)
return RESULT .. (b:arg + lnum) # space required before # comment
enddef
Vim9(10)->popup_notification({time: 3000}) # Pops up 'Result: 42'
<
Note: This example also demonstrates (outside the :def function):
- Removing "#" from the legacy #{} - see vim9-literal-dict, and
- Omitting :call (allowed, though unnecessary in Vim9 script)
Calling a :def function in an expr option
expr-option-function
The value of a few options, such as 'foldexpr', is an expression that is
evaluated to get a value. The evaluation can have quite a bit of overhead.
One way to minimize the overhead, and also to keep the option value simple,
is to define a compiled function and set the option to call it without
arguments. For example:
>vim9
vim9script
def MyFoldFunc(): string
# This matches start of line (^), followed by a digit, a full stop
# a space or tab, an uppercase character, with an empty next line
return getline(v:lnum) =~ '^[[:digit:]]\.[[:blank:]][[:upper:]]'
&& getline(v:lnum + 1)->empty() ? '>1' : '1'
enddef
set foldexpr=MyFoldFunc()
set foldmethod=expr
normal! zM
<
Warning: This script creates and applies folds at the "Heading 1" level of
this vim9.txt help buffer. (You can use zR, in Normal mode, to open all the
folds after sourcing the script.)
==============================================================================
4. Types vim9-types
The following types, each shown with its corresponding internal v:t_TYPE
variable, are supported:
number v:t_number
string v:t_string
func v:t_func
func: {type} v:t_func
func({type}, ...) v:t_func
func({type}, ...): {type} v:t_func
list<{type}> v:t_list
dict<{type}> v:t_dict
float v:t_float
bool v:t_bool
none v:t_none
job v:t_job
channel v:t_channel
blob v:t_blob
class v:t_class
object v:t_object
typealias v:t_typealias
enum v:t_enum
enumvalue v:t_enumvalue
tuple<{type}> v:t_tuple
tuple<{type}, {type}, ...> v:t_tuple
tuple<...list<{type}>> v:t_tuple
tuple<{type}, ...list<{type}>> v:t_tuple
void
E1031 E1186
These types can be used in declarations, though no simple value can have the
"void" type. Trying to use a void as a value results in an error.
Examples:
>vim9
vim9script
def NoReturnValue(): void
enddef
try
const X: any = NoReturnValue()
catch
echo v:exception # E1031: Cannot use void value
try
echo NoReturnValue()
catch
echo v:exception # E1186: Expression does not result in a valu...
endtry
endtry
< E1008 E1009 E1010 E1012
Ill-formed declarations and mismatching types result in errors. The following
are examples of errors E1008, E1009, E1010, and E1012:
>vim9
vim9cmd var l_1008: list
vim9cmd var l_1009: list<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:
>vim9
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:
>vim9
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:
>vim9
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}
func: void
func: {type}
func()[: void]
func(): {type}
func({type})[: void]
func({type}): {type}
func(?{type})[: void]
func(?{type}): {type}
func(...list<{type}>)[: void]
func(...list<{type}>): {type}
func({type}, ...list<{type}>)[: void]
func({type}, ...list<{type}>): {type}
If the return type is "void", the function does not return a value. All the
ways listed above are explained and demonstrated in the following examples,
all of which echo '9'.
func
- any kind of function reference
- any type of return value or no return value
>vim9
vim9script
const I = (n) => n + 1
const F: func = I->function()
echo F(8)
<
func: void
- any number and type of arguments
- does not return a value
>vim9
vim9script
def I(n: number): void
echo n + 1
enddef
const F: func: void = I->function()
F(8)
<
func: {type}
- any number and type of arguments
- returns a typed value
>vim9
vim9script
const I = (n): number => n + 1
const F: func: number = I->function()
echo F(8)
<
func()[: void]
- no arguments
- does not return a value
>vim9
vim9script
var n: number = 8
def I(): void
echo n + 1
enddef
const F: func(): void = I->function()
F()
<
func(): {type}
- no arguments
- returns a typed value
>vim9
vim9script
var n: number = 8
def I(): number
return n + 1
enddef
const F: func(): number = I->function()
echo F()
<
func({type})[: void]
- typed argument
- does not return a value
>vim9
vim9script
def I(n: number): void
echo n + 1
enddef
const F: func(number): void = I->function()
F(8)
<
func({type}): {type}
- typed argument
- returns a typed value
>vim9
vim9script
const I = (n: number): number => n + 1
const F: func(number): number = I->function()
echo F(8)
<
func(?{type})[: void]
- optional typed argument
- does not return a value
>vim9
vim9script
def I(n: number = 8): void
echo n + 1
enddef
const F: func(?number): void = I->function()
F()
<
func(?{type}): {type}
- optional typed argument
- returns a typed value
>vim9
vim9script
def I(n: number = 8): number
return n + 1
enddef
const F: func(?number): number = I->function()
echo F()
<
func(...list<{type}>)[: void]
- typed list for variable number of arguments
- does not return a value
>vim9
vim9script
def L(...l: list<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
>vim9
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
>vim9
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
>vim9
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:
>vim9
vim9script
def CircleArea(pi: float, radius: float): float
return pi * radius->pow(2)
enddef
const AREA: func(float): float = CircleArea->function([3.14])
const RADIUS: float = "Enter a radius value: "->input()->str2float()
echo $"\nThe area of a circle with a radius of {RADIUS} is " ..
$"{AREA(RADIUS)} (π to two d.p.)"
<
E1005
No more than 19 argument types may be used in a Funcref (one less than what is
allowed in a function, including a :def or lambda - see E740). Twenty or
more argument types gives E1005, as this example shows:
>vim9
vim9script
var X: func
X = (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t) => 0
var F: func(any, any, any, any, any, any, any, any, any, any, any,
\ any, any, any, any, any, any, any, any, any): any = X->function()
# E1005: Too many argument types
<
E1007
A mandatory argument may not come after an optional argument in a Funcref:
>vim9
vim9script
def I(n: number, f: float): void
echo n + f
enddef
const F: func(?number, float) = I->function()
# E1007: Mandatory argument after optional argument
<
vim9-typealias-type
Custom types (typealias) can be defined with :type. They must start with
a capital letter (which avoids name clashes with either current or future
builtin types) similar to user functions. This example creates a list of
perfect squares, reporting on type() (14, a typealias) and the typename():
>vim9
vim9script
type Ln = list<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:
>vim9
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:
>vim9
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:
>vim9
vim9script
enum Quad
Square('four', 'only'),
Rhombus('opposite', 'no')
var eq: string
var ra: string
def string(): string
return $"\nA {this.name} has " ..
$"{this.eq} equal sides and {this.ra} right angles\n\n"
enddef
endenum
echo "Rhombus (r) or Square (s)?"
var myQuad: Quad = getcharstr() =~ '\c^R' ? Quad.Rhombus : Quad.Square
echo myQuad.string() .. "\ttype()\ttypename()"
echo $"Quad \t{Quad->type()} \t{Quad->typename()}"
echo $"myQuad\t{myQuad->type()}\t{myQuad->typename()}"
<
Notes: This uses builtin method "string()" - see object-string().
The typename() of Quad and myQuad are the same ("enum<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:
>vim9
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:
>vim9
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 commandline, not sourced.
E1363 E1395
If a type is incomplete, such as when an object's class is unknown, E1363
or E1395 are given. Examples:
>vim9
vim9script
var E1363 = null_class.member # E1363: Incomplete type
< >vim9
vim9script
def F1395(): void
echo null_class.member
enddef
F1395() # E1395: Using a null class
<
Another null object-related error is E1360:
>vim9
vim9script
var obj = null_object
var E1360 = obj.MyMethod() # E1360: Using a null object
<
Type inference
type-inference
Declaring types explicitly provides many benefits, including targeted type
checking and clearer error messages. Nonetheless, Vim often can infer types
automatically when they are omitted. For example, each of these variables'
types are inferred, with the type() and typename() echoed showing those
inferred types:
>vim9
vim9script
echo "\t type()\t typename()"
var b = true | echo $"{b} \t {b->type()} \t {b->typename()}"
var f = 4.2 | echo $"{f} \t {f->type()} \t {f->typename()}"
var l = [1, 2] | echo $"{l} \t {l->type()} \t {l->typename()}"
var n = 42 | echo $"{n} \t {n->type()} \t {n->typename()}"
var s = 'yes' | echo $"{s} \t {s->type()} \t {s->typename()}"
var t = (42, ) | echo $"{t} \t {t->type()} \t {t->typename()}"
<
The type of a list, tuple, or dictionary is inferred from the common type of
its values. When the values are all the same type, that type is used.
If there is a mix of types, the "any" type is used. In the following example,
the echoed typename() for each literal demonstrates these points:
>vim9
vim9script
echo [1, 2]->typename() # list<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>":
>vim9
vim9script
def Foo(x: bool): void
enddef
def Bar(x: bool, y: bool): void
enddef
var funclist = [Foo, Bar]
echo funclist->typename()
<
Script-local variables in a Vim9 script are type checked. The type is
also checked for variables declared in a legacy function. For example:
>vim9
vim9script
var my_local = (1, 2)
function Legacy()
let b:legacy = [1, 2]
endfunction
Legacy()
echo $"{my_local} is type {my_local->type()} ({my_local->typename()})"
echo $"{b:legacy} is type {b:legacy->type()} ({b:legacy->typename()})"
<
E1013
When a type is declared for a List, Tuple, or Dictionary, the type is attached
to it. Similarly, if a type is not declared, the type Vim infers is attached.
In either case, if an expression attempts to change the type, E1013 results.
This example has its type inferred and demonstrates E1013:
>vim9
vim9script
var lb = [true, true] # Two bools, so Vim infers list<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:
>vim9
vim9script
final la: list<any> = []
echo la->extend(['two', 1])
final le = []
echo le->extend(la)
<
Similarly for a permissive dictionary:
>vim9
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:
>vim9
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:
>vim9
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":
>vim
echo 123 == '123'
<
However, if an unintended space is included, "0" is echoed:
>vim
echo 123 == ' 123'
<
E1206
In Vim9 script this has been made stricter. In most places it works just as
before if the value used matches the expected type. For example, in both
legacy Vim script and Vim9 script trying to use anything other than a
dictionary when it is required:
>vim
echo [8, 9]->keys()
vim9cmd echo [8, 9]->keys() # E1206: Dictionary required
<
E1023 E1024 E1029
E1030 E1174 E1175
E1210 E1212
However, sometimes there will be an error in Vim9 script, which breaks
backwards compatibility. The following examples illustrate various places
this happens. The legacy Vim script behavior, which does not fail, is shown
first. It is followed by the error that occurs if the same command is used
in Vim9 script.
- Using a number (except 0 or 1) where a bool is expected:
>vim
echo v:version ? v:true : v:false
vim9cmd echo v:version ? true : false # E1023: Using a Number as ...
<
- Using a number where a string is expected:
>vim
echo filter([1, 2], 0)
vim9cmd echo filter([1, 2], 0) # E1024: Using a Number as a String
<
- Not using a number where a number is expected:
>vim
" In this example, legacy Vim script treats v:false as 0
function Not1029()
let b:l = [42] | unlet b:l[v:false]
endfunction
call Not1029() | echo b:l
< >vim9
vim9script
def E1029(): void
b:l = [42] | unlet b:l[false]
enddef
E1029() # E1029: Expected number but got bool
<
- Using a string as a number:
>vim
let b:l = [42] | unlet b:l['#'] | echo b:l
vim9cmd b:l = [42] | vim9cmd unlet b:l['#'] # E1030: Using a string
<
- Not using a string where an argument requires a string:
>vim9
echo substitute('Hallo', 'a', 'e', v:true)
vim9cmd echo substitute('Hallo', 'a', 'e', true) # E1174: String ...
<
- Using an empty string in an argument that requires a non-empty string:
>vim9
echo exepath('')
vim9cmd echo exepath('') # E1175: Non-empty string required for ar...
<
- Not using a number when it is required:
>vim
echo gettabinfo('a')
vim9cmd echo gettabinfo('a') # E1210: Number required for argument 1
<
- Not using a bool when it is required:
>vim
echo char2nr('¡', 2)
vim9cmd echo char2nr('¡', 2) # E1212: Bool required for argument 2
<
- Not using a number when a number is required (E521):
>vim
let &laststatus='2'
vim9cmd &laststatus = '2'
<
- Not using a string when a string is required (E928):
>vim
let &langmenu = 42
vim9cmd &langmenu = 42 # E928: String required
<
- Comparing a Special with "is" often fails (E1037, E1072):
>vim
" 1 is echoed because these are both true in legacy Vim script
echo v:null is v:null && v:none is v:none
" Similarly, 0 is echoed for these (false in legacy Vim script)
echo v:none is v:null || v:none is 8 || v:true is v:none
" All these are errors in Vim9 script
vim9cmd echo v:null is v:null # E1037: Cannot use 'is' with special
vim9cmd echo v:none is v:none # E1037: Cannot use 'is' with special
vim9cmd echo v:none is v:null # E1037: Cannot use 'is' with special
vim9cmd echo v:none is 8 # E1072: Cannot compare special wit...
vim9cmd echo v:true is v:none # E1072: Cannot compare bool with s...
<
Note: Although the last two Vim9 script examples above error with
v:none, they return false with v:null (which is the same as
null - see v:null):
>vim9
vim9script
echo v:null is 8 # false
echo true is v:null # false
<
- Using a string where a bool is required (E1135):
>vim
echo '42' ? v:true : v:false
vim9cmd echo '42' ? true : false # E1135: Using a String as a Bool
<
- Using a bool as a number (E1138):
>vim
let &laststatus=v:true
vim9cmd &laststatus = true
<
One consequence is that the item type of a list or dict given to map() must
not change when its type is either declared or inferred. For example, this
list's type is changed successfully in legacy Vim script:
>vim
" legacy Vim script changing list [0, 1] to ['item 0', 'item 1']
let s:mylist = [0, 1]
call map(s:mylist, {i -> $"item {i}"})
echo s:mylist
<
whereas in Vim9 script it gives E1012:
>vim9
vim9script
var mylist = [0, 1] # Vim infers mylist is list<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:
>vim9
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:
>vim9
vim9script
# list literal
echo [1, 2]->map((_, v) => $"#{v}")
echo [1, 2]->map((_, v) => $"#{v}")->typename()
# deepcopy() in a method chain
var mylist = [1, 2]
echo mylist->deepcopy()->map((_, v) => $"#{v}")
echo mylist->deepcopy()->map((_, v) => $"#{v}")->typename()
echo mylist
<
The reasoning behind this is, when a type is either declared or inferred
and the list is passed around and changed, the declaration/inference must
always hold so that you can rely on the type to match the declared/inferred
type. For either a list literal or a fully copied list, that type safety is
not needed because the original list is unchanged (as "echo mylist" shows,
above).
If the item type was not declared or determined to be "<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:
>vim9
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:
>vim9
vim9cmd echo [1, 2]->extend(['3']) # [1, 2, '3']
<
whereas, this is not:
>vim9
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:
>vim9
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():
>vim9
vim9cmd [1, [2, 3]]->flatten() # E1158: Cannot use flatten
vim9cmd echo [1, [2, 3]]->flattennew() # [1, 2, 3]
<
Assigning to a funcref with specified arguments (see vim9-func-declaration)
involves strict type checking of the arguments. For example, this works:
>vim9
vim9script
var F_name_age: func(string, number): string
F_name_age = (n: string, a: number): string => $"Name: {n}, Age: {a}"
echo F_name_age('Bob', 42)
<
whereas this fails with error E1012 (type mismatch):
>vim9
vim9script
var F_name_age: func(string, number): string
F_name_age = (n: string, a: string): string => $"Name: {n}, Age: {a}"
<
If there is a variable number of arguments they must have the same type, as in
this example:
>vim9
vim9script
var Fproduct: func(...list<number>): 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:
>vim9
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:
>vim9
vim9script
var FuncSN: func(string): number
FuncSN = (v: any): number => v->str2nr()
echo FuncSN('162')->nr2char() # ¢
echo FuncSN(162)->nr2char() # E1013 (a runtime error)
< >vim9
vim9script
var FuncSN: func(string): number
FuncSN = (v: any): number => v->str2nr()
def FuncSNfail(): void
echo FuncSN('162')->nr2char() # No echo because ...
echo FuncSN(162)->nr2char() # E1013 (now, a compiling error)
enddef
FuncSNfail()
<
When the funcref has no arguments specified, there is no type checking. This
example shows FlexArgs has a string argument the first time and a list the
following time:
>vim9
vim9script
var FlexArgs: func: string
FlexArgs = (s: string): string => $"It's countdown time {s}..."
echo FlexArgs("everyone")
FlexArgs = (...values: list<string>): string => join(values, ', ')
echo FlexArgs('3', '2', '1', 'GO!')
<
E1211 E1217 E1218 E1219 E1220
E1221 E1222 E1223 E1224 E1225
E1226 E1228 E1235 E1238 E1251
E1253 E1256 E1297 E1298 E1301
E1528 E1529 E1530 E1531 E1534
Types are checked for most builtin functions to make it easier to spot
mistakes. The following one-line :vim9 commands, calling builtin functions,
demonstrate many of those type-checking errors:
>vim9
vim9 9->list2blob() # E1211: List required for argume...
vim9 9->ch_close() # E1217: Channel or Job required ...
vim9 9->job_info() # E1218: Job required for argumen...
vim9 [9]->cos() # E1219: Float or Number required...
vim9 {}->remove([]) # E1220: String or Number require...
vim9 null_channel->ch_evalraw(9) # E1221: String or Blob required ...
vim9 9->col() # E1222: String or List required ...
vim9 9->complete_add() # E1223: String or Dictionary req...
vim9 setbufline(9, 9, {}) # E1224: String, Number or List r...
vim9 9->count(9) # E1225: String, List, Tuple or D...
vim9 9->add(9) # E1226: List or Blob required fo...
vim9 9->remove(9) # E1228: List, Dictionary, or Blo...
vim9 getcharstr('9') # E1235: Bool or number required ...
vim9 9->blob2list() # E1238: Blob required for argume...
vim9 9->filter(9) # E1251: List, Tuple, Dictionary,...
vim9 9->reverse() # E1253: String, List, Tuple or B...
vim9 9->call(9) # E1256: String or Function requi...
vim9 null_dict->winrestview() # E1297: Non-NULL Dictionary requ...
vim9 {}->prop_add_list(null_list) # E1298: Non-NULL List required f...
vim9 {}->repeat(9) # E1301: String, Number, List, Tu...
vim9 9->index(9) # E1528: List or Tuple or Blob re...
vim9 9->join() # E1529: List or Tuple required f...
vim9 9->max() # E1530: List or Tuple or Diction...
vim9 9->get(9) # E1531: Argument of get() must b...
vim9 9->tuple2list() # E1534: Tuple required for argum...
<
Reserved for future use: E1227 E1250 E1252
E1227: List or Dictionary required for argument %d
E1250: Argument of %s must be a List, String, Dictionary or Blob
E1252: String, List or Blob required for argument %d
Categories of variables, defaults and null handling
variable-categories null-variables
There are three categories of variables:
primitive number, float, boolean
container string, blob, list, tuple, dict
specialized function, job, channel, user-defined-object
When declaring a variable without an initializer, an explicit type must be
provided. Each category has different default initialization semantics.
Primitives default to type-specific values. All primitives are empty but do
not equal null:
>vim9
vim9script
var n: number | echo [n, n->empty(), n == null] # [0, 1, false]
var f: float | echo [f, f->empty(), f == null] # [0.0, 1, false]
var b: bool | echo [b, b->empty(), b == null] # [false, 1, false]
<
Containers default to an empty container. Only an empty string equals null:
>vim9
vim9script
var s: string | echo [s, s->empty(), s == null] # ['', 1, true]
var z: blob | echo [z, z->empty(), z == null] # [0z, 1, false]
var l: list<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:
>vim9
vim9script
var F: func | echo [F, F == null] # [function(''), true]
var j: job | echo [j, j == null] # ['no process', true]
var c: channel | echo [c, c == null] # ['channel fail', true]
class Class
endclass
var o: Class | echo [o, o == null] # [object of [unknown], true]
enum Enum
endenum
var e: Enum | echo [e, e == null] # [object of [unknown], true]
<
Notes: (1) See empty() for explanations of empty job, empty channel,
and empty object types. (2) The class, enum, and typealias
types cannot be used as values, so cannot be compared to null (see
E1405, E1421, and E1403 respectively).
Vim does not have a familiar null value. Instead, it has various null_<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:
>vim9
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:
>vim9
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).
>vim9
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:
>vim9
vim9script
var j1: job
var j2: job = null_job
var j3 = null_job
echo (j1 == j2) == (j2 == j3) # true (equivalent, indistinguishable)
<
When a list, tuple, or dict is declared, if the item type is not specified
it cannot be inferred. Consequently, the item type defaults to "any":
>vim9
vim9script
var [t1, t2] = [(), null_tuple]
echo $'t1 is {t1->typename()} and t2 is {t2->typename()} too'
<
Tuples and functions (or partials) may be declared in various ways.
See tuple-type, variadic-tuple, and vim9-func-declaration.
null-compare
For familiar null compare semantics, where an empty container is not equal to
a null container, do not use null_<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:
>vim9
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:
>vim9
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:
>vim9
vim9cmd echo (null_dict == {}, null_dict == null, {} != null)
<
The exception is an uninitialized string. It is equal to null (and is the
same instance as null_string). The "is" operator (expr-is) may be used to
determine whether a string is uninitialized:
>vim9
vim9script
var s: string
echo s == null_string # true
echo s is null_string # true (the same instance)
echo s == null # true (unexpected, perhaps)
echo s is null # false (not the same instance)
<
However, don't do the same for the other containers because, when evaluated
against their applicable null_<type> with "is", they return false:
>vim9
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:
>vim9
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:
>vim9
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:
>vim9
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:
>vim9
vim9script
var c: channel | echo c == null
var F: func | echo F == null
var j: job | echo j == null
class Class
endclass
var nc: Class | echo nc == null
enum Enum
endenum
var ne: Enum | echo ne == null
<
Note: the specialized variables, like job, default to null and no
specialized variable has a corresponding empty value.
A container variable initialized to empty equals null_<type>, so these are all
true:
>vim9
vim9script
var s: string = "" | echo s == null_string
var b: blob = 0z | echo b == null_blob
var l: list<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:
>vim9
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{function body}
enddef
These type parameters may then be used, like any other type, within the
function signature and its body. The following example combines two lists
into a list of tuples:
>vim9
vim9script
def Zip<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:
>vim9
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:
>vim9
vim9script
My1558<number>()
# E1558: Unknown generic function: My1558
< >vim9
vim9script
def My1560(): void
enddef
My1560<string>()
# E1560: Not a generic function: My1560
<
E1561
Type parameter names must not clash with other identifiers:
>vim9
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:
>vim9
vim9script
def My1555<>(): void
enddef # E1555: Empty type list specified for generic function '<S...
< >vim9
vim9script
def My1556<T>(): void
enddef
My1556<bool, bool>() # E1556: Too many types specified for generic...
< >vim9
vim9script
def My1557<T, U>(): void
enddef
My1557<bool>() # E1557: Not enough types specified for generic fun...
< >vim9
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:
>vim9
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:
>vim9
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:
>vim9
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:
>vim9
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:
>vim9
vim9script
# Match a specified character in a string or the decimal value of the
# character in a list. Note: '*' is decimal 42 (U+002A)
var c: string = "*"
var char_dec: tuple<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>>
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:
>vim9
vim9script
var myvar = 'yes'
<
The variable "myvar" will only exist in this script's scope. That is
different from legacy Vim script where "let myvar" would make "myvar"
available to other scripts and functions (as g:myvar).
E1101
The variables at the file level are very much like the script-local "s:"
variables in legacy Vim script, but the "s:" is omitted. And they cannot be
deleted.
E1304
In Vim9 script the global (g:), buffer (b:), window (w:), and tab (t:)
namespaces can be used like in legacy Vim script. In Vim9 script, namespace
prefixed variables:
- are not declared
- have no specific type, and
- can be deleted.
If a namespace prefixed variable is declared, E1016 is given. And, if a
type is specified, E1304 is given:
>vim9
vim9cmd var b:fails: bool # E1016: Cannot declare a buffer va...
vim9cmd b:fails: bool = false # E1304: Cannot use type with this ...
<
A side effect of :vim9script is that the 'cpoptions' option is set to the
Vim default value, like with:
:set cpo&vim
One of the effects is that line-continuation is always enabled.
The original value of 'cpoptions' is restored at the end of the script, while
flags added or removed in the script are also added to or removed from the
original value to get the same effect. The order of flags may change.
In the vimrc file sourced on startup this does not happen.
vim9-mix
There is one way to use both legacy and Vim9 syntax in one script file:
>vim9
" _legacy Vim script_ comments are placed here
if !has('vim9script')
" _legacy Vim script_ comments and commands are placed here
finish
endif
vim9script
# _Vim9 script_ commands/commands from here onwards
echowindow $"has('vim9script') == {has('vim9script')}"
<
This allows for writing a script that takes advantage of the Vim9 script
syntax if possible, and prevents the vim9script command from giving an
error if used in a version of Vim without Vim9 script.
Note that Vim9 syntax changed before Vim 9 so that scripts using the current
syntax (such as "import from" instead of "import") might give errors.
To prevent these, a safer check may be v:version >= 900 instead (because
"has('vim9script')" will return v:true back to Vim 8.2 with patch 3965).
Sometimes it is prudent to cut off even later. Vim9 script's feature set
continues to grow so, for example, if tuples are used (introduced in Vim 9.1
patch 1232), a better condition is:
>vim9
if !has('patch-9.1.1232')
echowindow $"Fail: Vim does not have patch 9.1.1232"
finish
endif
vim9script
echowindow $"Pass: version {v:versionlong}. Continuing ..."
<
Whichever vim-mix condition is used, it only works in one of two ways:
1. The "if" statement evaluates to false, the commands up to endif are
skipped and vim9script is then the first command actually executed.
2. The "if" statement evaluates to true, the commands up to endif are
executed and finish bails out before reaching vim9script.
Export
:export
Exporting an item can be written as:
export var myvar ...
export const MYCONST ...
export final myvar ...
export def MyDef() ...
export function MyFunc() ...
export class MyClass ...
export abstract class MyAbstractClass ...
export interface MyInterface ...
export enum MyEnum ...
export type MyType ...
E1043export 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 ...
As this suggests, variables, constants, functions, classes (including abstract
classes), interfaces, enums, and types can be exported. Trying to export
something else gives E1043:
>vim9
vim9cmd export echo 0 # E1043: Invalid command after :export
<
E1042
:export can only be used in a Vim9 script scope. So, for example, although
exporting a :function is okay, trying to export an item within such a
function gives E1042:
>vim9
vim9script
export function F1042()
export var b: bool
endfunction
F1042() # E1042: Export can only be used in vim9script
<
E1044
An invalid argument can give E1044:
>vim9
vim9script
export def /a1044(): void
enddef # E1044: Export with invalid argument: ...
<
Import
:import
The exported items can be imported in another script. The import syntax has
two forms. The simpler form is:
import {filename}
Where {filename} is an expression that must evaluate to a string. In this
form the filename should end in ".vim" and the portion before ".vim" will
become the script-local name of the namespace. For example:
import "myscript.vim"
This makes each exported item in "myscript.vim" available as "myscript.item".
E1094
Importing is only allowed in the script-local scope. Trying to do so
elsewhere gives E1094; for example, from a :function or :def scope:
>vim9
vim9script
def F1094(): void
import 'nah.vim' # E1094: Import can only be used in a script
enddef
F1094()
<
E1053 E1071
Errors are given when either the {filename} is not found or it is invalid:
>vim9
vim9cmd import 'e1053.vim' # E1053: Could not import "e1053.vim"
vim9cmd import false # E1071: Invalid string for :import: false
<
:import-as
When the name of the file is long, ambiguous (such as with filenames that are
the same but in different directories), or if you just want to use a distinct
structure for the name, this form can be used:
import {longfilename} as {name}
In this longer form, {name} becomes a specific script-local name for the
imported namespace. Therefore {name} must consist of letters, digits, or '_',
and cannot start with a digit, like internal-variables. The {longfilename}
expression must evaluate to an existing filename.
The following script demonstrates using :import-as. It:
- Creates a constant, "TMP", for the {longfilename} of a temporary Vim9 script
file to import
- Writes a two-line Vim9 script to TMP
- Imports the Vim9 script file "as" the {name}, "that", and
- Echoes the result, showing the imported Vim9 script file's {longfilename}
and, on a separate line, the content of "that.myvar" (where "myvar" is an
exported variable in the imported script).
>vim9
vim9script
const TMP: string = tempname()
['vim9script', 'export var myvar: string = "YES!"']->writefile(TMP)
import TMP as that
echo $"Exported var 'myvar' in 'that' ({TMP}):\n" .. that.myvar
<
This example shows you can use "that.myvar", etc. You are free to choose the
name "that", or something that will be recognized as referring to the imported
script. It is best to avoid command names, command modifiers, and builtin
function names, because {name} will shadow any of those. It also is better to
begin the name with a lowercase letter because that avoids potential shadowing
of global user commands and functions. The {name} cannot be used for anything
else in the script, such as a function or variable name (see E1213), and it
cannot be assigned something else (see E1258).
In case the "." in the name is undesired, a local reference can be made for a
function:
var LongDef = that.LongDefName
This also works for constants:
const MAXLEN = that.MAXIMUM_LENGTH_OF_NAME
This does not work for variables, since the value would be copied once and
when changing the variable the copy will change, not the original variable.
You need to use the full name (i.e., including the '.').
Imported items are intended to exist at the script level and only be imported
once. Also, :import can not be used in a :function or :def - see E1094.
The script name after :import can be:
- A relative path, starting "." or "..". This finds a file relative to the
location of the script file itself. This is useful to split up a large
plugin into several files.
- An absolute path, starting with "/" on Unix or "D:/" on MS-Windows. This
will rarely be used.
- A path not being relative or absolute. This will be found in the
"import" subdirectories of 'runtimepath' entries. The name will usually be
longer and unique, to avoid loading the wrong file.
Note that "after/import" is not used.
Once a Vim9 script file has been imported, the result is cached and it will
not be read again.
Many syntax and other errors may be given when importing. Examples:
E1047
- Using an invalid "as" {name}:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i-cc
# E1047: Syntax error in import: i-cc
<
E1048
- Trying to use a non-existent item in an imported script:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
echo i_cc.absent_item # E1048: Item not found in script: absent_item
<
E1049
- Trying to use a declared, but non-exported, item in an imported script:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
echo i_cc.prepended # E1049: Item not exported in script: prepended
<
E1060
When using the imported name, the '.' and the item name must be contiguous.
So there can be neither white space nor a line break:
- After the '.' (see E1074), or
- Before the '.', for example:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
echo i_cc .GetPath() # E1060: Expected dot after name: i_cc .Get...
<
E1088
- Attempting to have an imported script import itself:
>vim9
vim9script
const TMP: string = $'{tempname()}.vim'->substitute('\\', '/', 'g')
var lines: list<string> = ['vim9script', $'import "{TMP}" as e1088']
lines->writefile(TMP)
import TMP # E1088: Script cannot import itself
<
E1236
- Trying to use the script itself:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as cc
cc() # E1236: Cannot use cc itself, it is imported
<
E1257
- Not using "as {name}" when the imported filename does not end in ".vim":
>vim9
vim9script
const TMP: string = tempname()
['vim9script']->writefile(TMP)
import TMP # E1257: Imported script must use "as" or end in .vim: ...
<
E1258
- Omitting the '.' after an imported name:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
def F1258(): void
i_cc =
enddef
defcompile # E1258: No '.' after imported name: i_cc =
<
E1259
- Omitting the name after an imported name:
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc
def F1259(): void
i_cc.8 = 0
enddef
defcompile # E1259: Missing name after imported name: i_cc.8 = 0
<
E1260
- Attempting to :unlet an imported item:
>vim9
vim9script
const TMP: string = tempname()
['vim9script', 'export var b: bool']->writefile(TMP)
import TMP as e_unlet
unlet e_unlet.b # E1260: Cannot unlet an imported item: b
<
E1261
- Attempting to import the filename ".vim" without using "as". This script
writes the temporary file '.vim' to the operating system's applicable
temporary directory, then attempts to import it:
>vim9
vim9script
const TMPDIR: string = tempname()
->substitute('\\', '/', 'g') # Ensure Windows \ chars are /
->substitute('/[^/]\+$', '/', '') # Remove the filename
['vim9script']->writefile($'{TMPDIR}.vim')
echo $"Temporary import file name is: {TMPDIR}.vim"
import $'{TMPDIR}.vim' # E1261: Cannot import .vim without using "as"
<
E1262
- Trying to import the same script multiple times (including using different
"as" names):
>vim9
vim9script
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc1
import $'{$VIMRUNTIME}/autoload/ccomplete.vim' as i_cc2
# E1262: Cannot import the same script twice: .../ccomplete.vim
<
import-map
When you've imported a function from one script into a Vim9 script you can
refer to the imported function in a mapping by prefixing it with <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:
>vim9
vim9script
const TMP: string = tempname()
['vim9script',
'export def MyDef(): void',
' popup_notification("exported.MyDef() was called", {time: 4000})',
'enddef']->writefile(TMP)
import TMP as exported
nnoremap <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()
call s:myfile.MyFunc()
When using the "as name" form, the namespace cannot be resolved on its own
(see also E1060). This example demonstrates using :imp with as successfully,
then the error:
>vim
let s:tmp = $'{tempname()}.vim'->substitute('\\', '/', 'g')
call writefile(['vim9script',
\ 'export function L()',
\ ' return "Vim9 script exporting a :function"',
\ 'endfunction'], s:tmp)
imp s:tmp as iLegacy
echo s:iLegacy.L() |" echoes 'Vim9 script exporting a :function'
echo s:iLegacy |" E1060: Expected dot after name: s:iLegacy
<
This also affects the use of <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>)
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
...
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'
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&quickfixtextfunc = 'qftf.Func' # autoload script NOT loaded
&quickfixtextfunc = qftf.Func # autoload script IS loaded
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 throw an error. If the types are known to be numbers then an "add
number" instruction can be used, which is faster. The error can be given at
compile time, no error handling is needed at runtime, since adding two numbers
almost never fails.
NOTE: As a tangential point, the exception is integer overflow, where the
result exceeds the maximum integer value. For example, adding to a 64-bit
signed integer where the result is greater than 2^63: >vim9
vim9script
echo 9223372036854775807 + 1 # -9223372036854775808
echo 2->pow(63)->float2nr() + 1 # -9223372036854775808
<
The syntax for types, using <type> for compound types, is similar to Java.
It is easy to understand and widely used. The type names are what were used
in Vim before, with some additions such as "void" and "bool".
Removing clutter and weirdness
Once decided that :def functions have different syntax than legacy functions,
we are free to add improvements to make the code more familiar for users who
know popular programming languages. In other words: remove weird things that
only Vim does.
We can also remove clutter, mainly things that were done to make Vim script
backwards compatible with the good old Vi commands.
Examples:
- Drop :call for calling a function and :eval for evaluating an
expression.
- Drop using a leading backslash for line continuation, automatically figure
out where an expression ends.
However, this does require that some things need to change:
- Comments start with # instead of ", to avoid confusing them with strings.
This is good anyway, it is also used by several popular languages.
- Ex command ranges need to be prefixed with a colon, to avoid confusion with
expressions (single quote can be a string or a mark, "/" can be divide or a
search command, etc.).
Goal is to limit the differences. A good criteria is that when the old syntax
is accidentally used you are very likely to get an error message.
Syntax and semantics from popular languages
Script writers have complained that the Vim script syntax is unexpectedly
different from what they are used to. To reduce this complaint popular
languages are used as an example. At the same time, we do not want to abandon
the well-known parts of legacy Vim script.
For many things TypeScript is followed. It's a recent language that is
gaining popularity and has similarities with Vim script. It also has a
mix of static typing (a variable always has a known value type) and dynamic
typing (a variable can have different types, this changes at runtime). Since
legacy Vim script is dynamically typed and a lot of existing functionality
(esp. builtin functions) depends on that, while static typing allows for much
faster execution, we need to have this mix in Vim9 script.
There is no intention to completely match TypeScript syntax and semantics. We
just want to take those parts that we can use for Vim and we expect Vim users
will be happy with. TypeScript is a complex language with its own history,
advantages and disadvantages. To get an idea of the disadvantages read the
book: "JavaScript: The Good Parts". Or find the article "TypeScript: the good
parts" and read the "Things to avoid" section.
People familiar with other languages (Java, Python, etc.) will also find
things in TypeScript that they do not like or do not understand. We'll try to
avoid those things.
Specific items from TypeScript we avoid:
- Overloading "+", using it both for addition and string concatenation. This
goes against legacy Vim script and often leads to mistakes. For that reason
we will keep using ".." for string concatenation. Lua also uses ".." this
way. And it allows for conversion to string for more values.
- TypeScript can use an expression like "99 || 'yes'" in a condition, but
cannot assign the value to a boolean. That is inconsistent and can be
annoying. Vim recognizes an expression with && or || and allows using the
result as a bool. The falsy-operator was added for the mechanism to use a
default value.
- TypeScript considers an empty string as Falsy, but an empty list or dict as
Truthy. That is inconsistent. In Vim an empty list and dict are also
Falsy.
- TypeScript has various "Readonly" types, which have limited usefulness,
since a type cast can remove the immutable nature. Vim locks the value,
which is more flexible, but is only checked at runtime.
- TypeScript has a complicated "import" statement that does not match how the
Vim import mechanism works. A much simpler mechanism is used instead, which
matches that the imported script is only sourced once.
Declarations
Legacy Vim script uses :let for every assignment, while in Vim9 declarations
are used. That is different, thus it's good to use a different command:
:var. This is used in many languages. The semantics might be slightly
different, but it's easily recognized as a declaration.
Using :const for constants is common, but the semantics varies. Some
languages only make the variable immutable, others also make the value
immutable. Since "final" is well known from Java for only making the variable
immutable we decided to use that. And then :const can be used for making
both immutable. This was also used in legacy Vim script and the meaning is
almost the same.
What we end up with is very similar to Dart:
:var name # mutable variable and value
:final name # immutable variable, mutable value
:const name # immutable variable and value
:final name # immutable variable, mutable value
:const name # immutable variable and value
Since legacy and Vim9 script will be mixed and global variables will be
shared, optional type checking is desirable. Also, type inference will avoid
the need for specifying the type in many cases. The TypeScript syntax fits
best for adding types to declarations:
var name: string # string type is specified
...
name = 'John'
const greeting = 'hello' # string type is inferred
...
name = 'John'
const greeting = 'hello' # string type is inferred
This is how we put types in a declaration:
var mylist: list<string>
final mylist: list<string> = ['foo']
def Func(arg1: number, arg2: string): bool
final mylist: list<string> = ['foo']
def Func(arg1: number, arg2: string): bool
Two alternatives were considered:
1. Put the type before the name, like Dart:
var list<string> mylist
final list<string> mylist = ['foo']
def Func(number arg1, string arg2) bool
2. Put the type after the variable name, but do not use a colon, like Go:final list<string> mylist = ['foo']
def Func(number arg1, string arg2) bool
var mylist list<string>
final mylist list<string> = ['foo']
def Func(arg1 number, arg2 string) bool
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 expr-!): >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 notresult in a boolean. This is called the falsy-operator.
Import and Export
A problem of legacy Vim script is that by default all functions and variables
are global. It is possible to make them script-local, but then they are not
available in other scripts. This defies the concept of a package that only
exports selected items and keeps the rest local.
In Vim9 script a mechanism very similar to the JavaScript import and export
mechanism is supported. It is a variant to the existing :source command
that works like one would expect:
- Instead of making everything global by default, everything is script-local,
some of these are exported.
- When importing a script the symbols that are imported are explicitly listed,
avoiding name conflicts and failures if functionality is added later.
- The mechanism allows for writing a big, long script with a very clear API:
the exported functions, variables and classes.
- By using relative paths loading can be much faster for an import inside of a
package, no need to search many directories.
- Once an import has been used, its items are cached and loading it again is
not needed.
- The Vim-specific use of "s:" to make things script-local can be dropped.
When sourcing a Vim9 script (from 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: