+
usr_46.txt For
Vim version 8.2. Last change: 2020 Jun 14
+
+ VIM USER MANUAL - by Bram Moolenaar
+
+ Write plugins using Vim9 script
+
+
+The Vim9 script language is used for writing plugins, especially larger ones
+that use multiple files. This chapter explains how to split up a plugin into
+modules, import and export items and keep the rest local.
+
+
46.1 Introduction
+
46.2 Variable declarations
+
46.3 Functions and types
+
46.? Using a Vim9 script from legacy script
+
+ Next chapter:
usr_90.txt Installing Vim
+ Previous chapter:
usr_45.txt Select your language (locale)
+Table of contents:
usr_toc.txt
+
+
==============================================================================
+
46.1 Introduction
vim9-script-intro
+
+Vim9 script was designed to make it easier to write large Vim scripts. It
+looks more like other script languages, especially Typescript. Also,
+functions are compiled into instructions that can be executed quickly. This
+makes Vim9 script a lot faster, up to a 100 times.
+
+The basic idea is that a script file has items that are private, only used
+inside the script file, and items that are exported, used outside of the
+script file. The exported items can then be used by scripts that import them.
+That makes very clear what is defined where.
+
+Let's start with an example, a script that exports one function and has one
+private function:
+
+
vim9script " This indicates a Vim9 script file.
+
+
export def GetMessage(): string
+ let result = ''
+ ...
+ result = GetPart(count)
+ ...
+ return result
+ enddef
+
+
def GetPart(nr: number): string
+ if nr == 4
+ return 'yes'
+ else
+ return 'no'
+ endif
+ enddef
+
+The command must be the very first command in the file. Without
+it Vim will assume legacy script syntax.
+
+The line starts with , meaning that
+this function can be imported and called by other scripts. The line
+ does not start with , this is a script-local
+function, it can only be used inside this script file.
+
+In the line you will notice the colon and
+the return type. Vim9 functions, defined with , require specifying the
+type of arguments and the return type. That way Vim can compile the code
+efficiently. The GetPart function defines an argument "nr" of type "number".
+
+Notice that the assignment does not use the
+command. That is explained in the next section.
+
+
==============================================================================
+
46.2 Variable declarations
vim9-declarations
+
+In Vim9 script variables are declared once with a or command.
+Assigning a value is done without and it is not possible to
+the variable.
+
+In most cases you will want to declare the variable and initialize it at the
+same time:
+
let myText = 'some text'
+ ...
+ myText = 'other text'
+
+The type of the variable will be inferred from the expression. In this case
+it is a string. If you initialize with a number, then the type is number:
+
let myNumber = 1234
+ ...
+ myNumber = 0
+
+If you try to assign a string to this variable, you will get an error:
+
let myNumber = 'this fails!'
+
+In the rare case you want a variable that can take values of any type, you
+have to specify the type:
+
let myVar: any = 1234
+ myVar = 'text also works'
+
+You can also declare a variable without assigning a value. In that case Vim
+will initialize it to zero or empty:
+
let word: string
+ if condition
+ word = 'yes'
+ else
+ word = 'no'
+ endif
+
+Although it's shorter to do:
+
let word = condition ? 'yes' : 'no'
+
+
==============================================================================
+
46.3 Functions and types
+
+Legacy Vim script does have type checking, but this happens at runtime, when
+the code is executed. And it's permissive, often a computation gives an
+unexpected value instead of reporting an error. Thus you can define a
+function and think it's fine, but see a problem only later when it is called:
+
let s:collected = ''
+ func ExtendAndReturn(add)
+ let s:collected += a:add
+ return s:collected
+ endfunc
+
+Can you spot the error? Try this:
+
echo ExtendAndReturn('text')
+And you'll see zero. Why? Because in legacy Vim script "+=" will convert the
+arguments to numbers, and any string without a number results in zero!
+
+With the type checking happens when compiling the function. For that
+you need to specify the argument types and the return type. Also notice that
+the argument is used without the "a:" prefix:
+
let s:collected = ''
+ def ExtendAndReturn(add: string): string
+ s:collected += add
+ return s:collected
+ enddef
+ defcompile
+
+Here we use to do the compilation right away, without it the
+compilation would happen when the function is called. Vim will tell you what
+you did wrong:
+
E1013: type mismatch, expected number but got string
+
+Vim9 script is strict, it uses the "+" operator only for numbers and floats.
+For string concatenation ".." must be used. This avoids mistakes and avoids
+the automatic conversion that gave a surprising result above. So you change
+the first line of the function to:
+
s:collected ..= add
+And now it works.
+
+If the function does not return anything, just leave out the return type:
+
def ReportResult(result: string)
+ echo 'The result is: ' .. result
+ enddef
+
+This is also checked, if you try to return a value you'll get an error.
+
+In case you don't care about types or have a function that does work with
+multiple types, you can use the "any" type:
+
def Store(key: string, value: any)
+ resultDict[key] = value
+ enddef
+
+
==============================================================================
+
46.? Using a Vim9 script from legacy script
source-vim9-script
+
+In some cases you have a legacy Vim script where you want to use items from a
+Vim9 script. For example in your .vimrc you want to initialize a plugin. The
+best way to do this is to use . For example:
+
+
import Init as NiceInit from 'myNicePlugin.vim'
+ call NiceInit('today')
+
+This finds the exported function "Init" in the Vim9 script file and makes it
+available as script-local item "NiceInit". always uses the script
+namespace, even when "s:" is not given. If "myNicePlugin.vim" was already
+sourced it is not sourced again.
+
+Besides avoiding putting any items in the global namespace (where name clashes
+can cause unexpected errors), this also means the script is sourced only once,
+no matter how many times items from it are imported.
+
+In some cases, e.g. for testing, you may just want to source the Vim9 script.
+That is OK, but then only global items will be available. The Vim9 script
+will have to make sure to use a unique name for these global items. Example:
+
source ~/.vim/extra/myNicePlugin.vim
+ call g:NicePluginTest()
+
+
==============================================================================
+
+Next chapter:
usr_90.txt Installing Vim
+
+Copyright: see
manual-copyright vim:tw=78:ts=8:noet:ft=help:norl:
+