summaryrefslogtreecommitdiffstats
path: root/runtime/doc/vim9.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/vim9.txt')
-rw-r--r--runtime/doc/vim9.txt2427
1 files changed, 2427 insertions, 0 deletions
diff --git a/runtime/doc/vim9.txt b/runtime/doc/vim9.txt
new file mode 100644
index 0000000..b12b1cc
--- /dev/null
+++ b/runtime/doc/vim9.txt
@@ -0,0 +1,2427 @@
+*vim9.txt* For Vim version 9.1. Last change: 2023 Dec 24
+
+
+ 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.
+
+
+
+1. What is Vim9 script? |Vim9-script|
+2. Differences |vim9-differences|
+3. New style functions |fast-functions|
+4. Types |vim9-types|
+5. Namespace, Import and Export |vim9script|
+6. Classes and interfaces |vim9-classes|
+
+9. Rationale |vim9-rationale|
+
+==============================================================================
+
+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.
+
+The Vim9 script syntax and semantics are used 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* *E1164*
+ Evaluate and execute {cmd} using Vim9 script syntax and
+ semantics. Useful when typing a command and in a legacy
+ script or function.
+
+:leg[acy] {cmd} *:leg* *:legacy* *E1189* *E1234*
+ Evaluate and execute {cmd} using legacy script syntax and
+ semantics. Only useful in a Vim9 script or a :def function.
+ Note that {cmd} cannot use local variables, since it is parsed
+ with legacy expression syntax.
+
+==============================================================================
+
+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.
+- Assign values without `:let` *E1126* , declare variables with `:var`: >
+ var count = 0
+ count += 3
+- Constants can be declared with `:final` and `:const`: >
+ final matches = [] # add to the list later
+ const names = ['Betty', 'Peter'] # cannot be changed
+- `:final` cannot be used as an abbreviation of `:finally`.
+- 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:
+ `: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: >
+ :%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
+
+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!
+< *E1170*
+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
+
+That looks ugly, better put `vim9script` in the very first line: >
+ vim9script
+ # 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
+
+`: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*
+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')
+
+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
+< *E1096* *E1174* *E1175*
+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
+ ...
+
+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'
+<
+ *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 to
+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. >
+ def ThisFunction() # script-local
+ def g:ThatFunction() # global
+ export def Function() # for import and import autoload
+< *E1058* *E1075*
+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
+
+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.
+
+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()
+ ....
+
+
+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
+ ...
+
+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!
+
+The declaration must be done earlier: >
+ var inner: number
+ 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* *E1128*
+To intentionally hide a variable from code that follows, a block can be
+used: >
+ {
+ 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
+ }
+
+And with autocommands: >
+ au BufWritePre *.go {
+ var save = winsaveview()
+ silent! exe ':%! some formatting command'
+ winrestview(save)
+ }
+
+Although using a :def function probably works better.
+
+ *E1022* *E1103* *E1130* *E1131* *E1133*
+ *E1134*
+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)
+
+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
+
+< *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
+
+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.
+
+ *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 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
+
+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
+
+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* *E1080*
+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: >
+ var [v1: number, v2] = GetValues()
+Use this only when there is a list with values, declaring one variable per
+line is much easier to read and change later.
+
+
+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* *E1125*
+`: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
+
+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"
+
+
+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()
+
+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
+< *E1157*
+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: >
+ filter(list, (k, v)
+ => v > 0)
+This also does not work: >
+ filter(list, (k,
+ v) => v > 0)
+But you can use a backslash to concatenate the lines before parsing: >
+ filter(list, (k,
+ \ v)
+ \ => v > 0)
+< *vim9-lambda-arguments* *E1172*
+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"
+
+< *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: >
+ var count = 0
+ 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.
+
+ *command-block* *E1026*
+The block can also be used for defining a user command. Inside the block Vim9
+syntax will be used.
+
+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: >
+ command NewCommand {
+ 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()
+
+
+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: >
+ var mydict = {
+ one: 1,
+ two: 2,
+ }
+With a function call: >
+ var result = Func(
+ 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)
+
+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
+
+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
+
+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
+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 and
+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
+continuation is used without a backslash and a line starts with a bar: >
+ au CursorHold * echom 'BEFORE 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()
+
+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
+
+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 the
+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: >
+ [var1,
+ var2] =
+ Func()
+- No line break is allowed in between arguments of an `:echo`, `:execute` and
+ similar commands. This is OK: >
+ echo [1,
+ 2] [3,
+ 4]
+< This does not work: >
+ echo [1, 2]
+ [3, 4]
+- In some cases it is difficult for Vim to parse a command, especially when
+ commands are used as an argument to another command, such as `:windo`. In
+ those cases the line continuation with a backslash has to be used.
+
+
+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 # OK
+White space must also be put before the # that starts a comment after a
+command: >
+ var name = 234# Error!
+ 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]
+
+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
+ )
+< *E1205*
+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
+< *E1139*
+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: >
+ var dict = {[00.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'
+
+
+For loop ~
+ *E1254*
+The loop variable must not be declared yet: >
+ var i = 1
+ 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
+
+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:
+ 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)
+ 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 when not NULL
+ object when not NULL (TODO: when isTrue() returns true)
+
+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!
+
+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
+
+When using "`.."` for string concatenation arguments of simple types are
+always converted to string: >
+ 'hello ' .. 123 == 'hello 123'
+ '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_object
+ null_partial
+ null_string
+`true` is the same as `v:true`, `false` the same as `v:false`, `null` the same
+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
+
+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.
+
+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 Vim9
+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. >
+ -> 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
+
+ %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
+
+Some Ex commands can be confused with assignments in Vim9 script: >
+ g:name = value # assignment
+ :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
+
+Also, there cannot be a space between the command and the separator: >
+ g /pattern/cmd # 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: >
+ def Maybe()
+ if !has('feature')
+ return
+ endif
+ use-feature # May give a compilation error
+ enddef
+For a workaround, split it in two functions: >
+ 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 that
+evaluates to false: >
+ def Maybe()
+ if has('feature')
+ use-feature
+ endif
+ enddef
+The `exists_compiled()` function can also be used for this.
+ *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()
+ command -nargs=1 MyCommand echom <q-args>
+ MyCommand 123
+ enddef
+A workaround is to invoke the command indirectly with `:execute`: >
+ def Works()
+ 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
+
+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
+
+Using ++var or --var in an expression is not supported yet.
+
+==============================================================================
+
+3. New style functions *fast-functions*
+
+ *:def* *E1028*
+: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*
+ *E1011*
+ The {name} must be less than 100 bytes long.
+ *E1003* *E1027* *E1056* *E1059*
+ The type of value used with `:return` must match
+ {return-type}. When {return-type} is omitted or is
+ "void" the function is not expected to return
+ anything.
+ *E1077* *E1123*
+ {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, the caller
+ must always provide them.
+ The second and third form are optional arguments.
+ When the caller omits an argument the {value} is used.
+
+ The function will be compiled into instructions when
+ called, or when `:disassemble` or `:defcompile` is
+ used. Syntax and type errors will be produced at that
+ time.
+
+ It is possible to nest `:def` inside another `:def` or
+ `:function` up to about 50 levels deep.
+ *E1117*
+ [!] is used as with `:function`. Note that
+ script-local functions cannot be deleted or redefined
+ later in Vim9 script. They can only be removed by
+ reloading the same script.
+
+ *:enddef* *E1057* *E1152* *E1173*
+:enddef End of a function defined with `:def`. It should be on
+ a line by its own.
+
+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
+
+If the script the function is defined in is Vim9 script, then script-local
+variables can be accessed without the "s:" prefix. They must be defined
+before the function is compiled. If the script the function is defined in is
+legacy script, then script-local variables must be accessed with the "s:"
+prefix if they do not exist at the time of compiling.
+ *E1269*
+Script-local variables in a |Vim9| script must be declared at the script
+level. They cannot be created in a function, also not in a legacy function.
+
+ *:defc* *:defcompile*
+:defc[ompile] Compile functions defined in the current script that
+ were not compiled yet.
+ This will report any errors found during compilation.
+ This excludes functions defined inside a class.
+
+: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} call also be "ClassName.functionName" to
+ compile a function or method in a class.
+ {func} call 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. *E1061*
+ Note that for command line completion of {func} you
+ can prepend "s:" to find script-local functions.
+
+: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.
+
+Limitations ~
+
+Local variables will not be visible to string evaluation. For example: >
+ def MapList(): list<string>
+ var list = ['aa', 'bb', 'cc', 'dd']
+ return range(1, 2)->map('list[v:val]')
+ enddef
+
+The map argument is a string expression, which is evaluated without the
+function scope. Instead, use a lambda: >
+ def MapList(): list<string>
+ var list = ['aa', 'bb', 'cc', 'dd']
+ return range(1, 2)->map((_, v) => list[v])
+ enddef
+
+For commands that are not compiled, such as `:edit`, backtick expansion can be
+used and it can use the local scope. Example: >
+ def Replace()
+ var fname = 'blah.txt'
+ edit `=fname`
+ enddef
+
+Closures defined in a loop will share the same context. For example: >
+ var flist: list<func>
+ for i in range(5)
+ var inloop = i
+ flist[i] = () => inloop
+ endfor
+ echo range(5)->map((i, _) => flist[i]())
+ # Result: [4, 4, 4, 4, 4]
+< *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.
+
+The "inloop" variable will exist only once, all closures put in the list refer
+to the same instance, which in the end will have the value 4. This is
+efficient, also when looping many times. If you do want a separate context
+for each closure, call a function to define it: >
+ def GetClosure(i: number): func
+ var infunc = i
+ return () => infunc
+ enddef
+
+ var flist: list<func>
+ for i in range(5)
+ flist[i] = GetClosure(i)
+ endfor
+ echo range(5)->map((i, _) => flist[i]())
+ # Result: [0, 1, 2, 3, 4]
+
+In some situations, especially when calling a Vim9 closure from legacy
+context, the evaluation will fail. *E1248*
+
+Note that at the script level the loop variable will be invalid after the
+loop, also when used in a closure that is called later, e.g. with a timer.
+This will generate error |E1302|: >
+ for n in range(4)
+ timer_start(500 * n, (_) => {
+ echowin n
+ })
+ endfor
+
+You need to use a block and define a variable there, and use that one in the
+closure: >
+ for n in range(4)
+ {
+ var nr = n
+ timer_start(500 * n, (_) => {
+ echowin nr
+ })
+ }
+ endfor
+
+Using `:echowindow` is useful in a timer, the messages go into a popup and will
+not interfere with what the user is doing when it triggers.
+
+
+Converting a function from legacy to Vim9 ~
+ *convert_legacy_function_to_vim9*
+These are the most changes that need to be made to convert a legacy function
+to a Vim9 function:
+
+- Change `func` or `function` to `def`.
+- Change `endfunc` or `endfunction` to `enddef`.
+- Add types to the function arguments.
+- If the function returns something, add the return type.
+- Change comments to start with # instead of ".
+
+ For example, a legacy function: >
+ func MyFunc(text)
+ " function body
+ endfunc
+< Becomes: >
+ def MyFunc(text: string): number
+ # function body
+ enddef
+
+- Remove "a:" used for arguments. E.g.: >
+ return len(a:text)
+< Becomes: >
+ return len(text)
+
+- Change `let` used to declare a variable to `var`.
+- Remove `let` used to assign a value to a variable. This is for local
+ variables already declared and b: w: g: and t: variables.
+
+ For example, legacy function: >
+ let lnum = 1
+ let lnum += 3
+ let b:result = 42
+< Becomes: >
+ var lnum = 1
+ lnum += 3
+ b:result = 42
+
+- Insert white space in expressions where needed.
+- Change "." used for concatenation to "..".
+
+ For example, legacy function: >
+ echo line(1).line(2)
+< Becomes: >
+ echo line(1) .. line(2)
+
+- line continuation does not always require a backslash: >
+ echo ['one',
+ \ 'two',
+ \ 'three'
+ \ ]
+< Becomes: >
+ echo ['one',
+ 'two',
+ 'three'
+ ]
+
+
+Calling a 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 very
+simple, is to define a compiled function and set the option to call it
+without arguments. Example: >
+ vim9script
+ def MyFoldFunc(): any
+ ... compute fold level for line v:lnum
+ return level
+ enddef
+ set foldexpr=s:MyFoldFunc()
+
+==============================================================================
+
+4. Types *vim9-types*
+ *E1008* *E1009* *E1010* *E1012*
+ *E1013* *E1029* *E1030*
+The following builtin types are supported:
+ bool
+ number
+ float
+ string
+ blob
+ list<{type}>
+ dict<{type}>
+ job
+ channel
+ func
+ func: {type}
+ func({type}, ...)
+ func({type}, ...): {type}
+ void
+
+Not supported yet:
+ tuple<a: {type}, b: {type}, ...>
+
+These types can be used in declarations, but no simple value will actually
+have the "void" type. Trying to use a void (e.g. a function without a
+return value) results in error *E1031* *E1186* .
+
+There is no array type, use list<{type}> instead. For a list constant an
+efficient implementation is used that avoids allocating a lot of small pieces
+of memory.
+ *vim9-func-declaration* *E1005* *E1007*
+A partial and function can be declared in more or less specific ways:
+func any kind of function reference, no type
+ checking for arguments or return value
+func: void any number and type of arguments, no return
+ value
+func: {type} any number and type of arguments with specific
+ return type
+
+func() function with no argument, does not return a
+ value
+func(): void same
+func(): {type} function with no argument and return type
+
+func({type}) function with argument type, does not return
+ a value
+func({type}): {type} function with argument type and return type
+func(?{type}) function with type of optional argument, does
+ not return a value
+func(...list<{type}>) function with type of list for variable number
+ of arguments, does not return a value
+func({type}, ?{type}, ...list<{type}>): {type}
+ function with:
+ - type of mandatory argument
+ - type of optional argument
+ - type of list for variable number of
+ arguments
+ - return type
+
+If the return type is "void" the function does not return a value.
+
+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.
+
+Custom types can be defined with `:type`: >
+ :type MyList list<string>
+Custom types must start with a capital letter, to avoid name clashes with
+builtin types added later, similarly to user functions.
+{not implemented yet}
+
+And classes and interfaces can be used as types: >
+ :class MyClass
+ :var mine: MyClass
+
+ :interface MyInterface
+ :var mine: MyInterface
+
+ :class MyTemplate<Targ>
+ :var mine: MyTemplate<number>
+ :var mine: MyTemplate<string>
+
+ :class MyInterface<Targ>
+ :var mine: MyInterface<number>
+ :var mine: MyInterface<string>
+{not implemented yet}
+
+
+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, the
+value can be changed at any time, possibly changing the type. Therefore, in
+compiled code the "any" type is assumed.
+
+This can be a problem when the "any" type is undesired and the actual type is
+expected to always be the same. For example, when declaring a list: >
+ var l: list<number> = [1, g:two]
+At compile time Vim doesn't know the type of "g:two" and the expression type
+becomes list<any>. An instruction is generated to check the list type before
+doing the assignment, which is a bit inefficient.
+ *type-casting* *E1104*
+To avoid this, use a type cast: >
+ var l: list<number> = [1, <number>g:two]
+The compiled code will then only check that "g:two" is a number and give an
+error if it isn't. This is called type casting.
+
+The syntax of a type cast is: "<" {type} ">". There cannot be white space
+after the "<" or before the ">" (to avoid them being confused with
+smaller-than and bigger-than operators).
+
+The semantics is that, if needed, a runtime type check is performed. The
+value is not actually changed. If you need to change the type, e.g. to change
+it to a string, use the |string()| function. Or use |str2nr()| to convert a
+string to a number.
+
+If a type is given where it is not expected you can get *E1272* .
+
+If a type is incomplete you get *E1363* , e.g. when you have an object for
+which the class is not known (usually that is a null object).
+
+Type inference ~
+ *type-inference*
+In general: Whenever the type is clear it can be omitted. For example, when
+declaring a variable and giving it a value: >
+ var name = 0 # infers number type
+ var name = 'hello' # infers string type
+
+The type of a list and dictionary comes from the common type of the values.
+If the values all have the same type, that type is used for the list or
+dictionary. If there is a mix of types, the "any" type is used. >
+ [1, 2, 3] list<number>
+ ['a', 'b', 'c'] list<string>
+ [1, 'x', 3] list<any>
+
+The common type of function references, if they do not all have the same
+number of arguments, uses "(...)" to indicate the number of arguments is not
+specified. For example: >
+ def Foo(x: bool)
+ enddef
+ def Bar(x: bool, y: bool)
+ enddef
+ var funclist = [Foo, Bar]
+ echo funclist->typename()
+Results in:
+ list<func(...)>
+
+For script-local variables in Vim9 script the type is checked, also when the
+variable was declared in a legacy function.
+
+When a type has been declared this is attached to a List or Dictionary. When
+later some expression attempts to change the type an error will be given: >
+ var ll: list<number> = [1, 2, 3]
+ ll->extend(['x']) # Error, 'x' is not a number
+
+If the type is not declared then it is allowed to change: >
+ [1, 2, 3]->extend(['x']) # result: [1, 2, 3, 'x']
+
+For a variable declaration an inferred type matters: >
+ var ll = [1, 2, 3]
+ ll->extend(['x']) # Error, 'x' is not a number
+That is because the declaration looks like a list of numbers, thus is
+equivalent to: >
+ var ll: list<number> = [1, 2, 3]
+If you do want a more permissive list you need to declare the type: >
+ var ll: list<any> = [1, 2, 3]
+ ll->extend(['x']) # OK
+
+
+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. e.g.: >
+ echo 123 == '123'
+< 1 ~
+With an accidental space: >
+ echo 123 == ' 123'
+< 0 ~
+ *E1206* *E1210* *E1212*
+In Vim9 script this has been made stricter. In most places it works just as
+before if the value used matches the expected type. There will sometimes be
+an error, thus breaking backwards compatibility. For example:
+- Using a number other than 0 or 1 where a boolean is expected. *E1023*
+- Using a string value when setting a number option.
+- Using a number where a string is expected. *E1024* *E1105*
+
+One consequence is that the item type of a list or dict given to |map()| must
+not change, if the type was declared. This will give an error in Vim9
+script: >
+ var mylist: list<number> = [1, 2, 3]
+ echo map(mylist, (i, v) => 'item ' .. i)
+< E1012: Type mismatch; expected number but got string in map() ~
+
+Instead use |mapnew()|, it creates a new list: >
+ var mylist: list<number> = [1, 2, 3]
+ echo mapnew(mylist, (i, v) => 'item ' .. i)
+< ['item 0', 'item 1', 'item 2'] ~
+
+If the item type was not declared or determined to be "any" it can change to a
+more specific type. E.g. when a list of mixed types gets changed to a list of
+strings: >
+ var mylist = [1, 2.0, '3']
+ # typename(mylist) == "list<any>"
+ map(mylist, (i, v) => 'item ' .. i)
+ # typename(mylist) == "list<string>", no error
+
+There is a subtle difference between using a list constant directly and
+through a variable declaration. Because of type inference, when using a list
+constant to initialize a variable, this also sets the declared type: >
+ var mylist = [1, 2, 3]
+ # typename(mylist) == "list<number>"
+ echo map(mylist, (i, v) => 'item ' .. i) # Error!
+
+When using the list constant directly, the type is not declared and is allowed
+to change: >
+ echo map([1, 2, 3], (i, v) => 'item ' .. i) # OK
+
+The reasoning behind this is that when a type is declared and the list is
+passed around and changed, the declaration must always hold. So that you can
+rely on the type to match the declared type. For a constant this is not
+needed.
+
+ *E1158*
+Same for |extend()|, use |extendnew()| instead, and for |flatten()|, use
+|flattennew()| instead. Since |flatten()| is intended to always change the
+type, it can not be used in Vim9 script.
+
+Assigning to a funcref with specified arguments (see |vim9-func-declaration|)
+does strict type checking of the arguments. For variable number of arguments
+the type must match: >
+ var FuncRef: func(string, number, bool): number
+ FuncRef = (v1: string, v2: number, v3: bool) => 777 # OK
+ FuncRef = (v1: string, v2: number, v3: number) => 777 # Error!
+ # variable number of arguments must have same type
+ var FuncVA: func(...list<string>): number
+ FuncVA = (...v: list<number>): number => v # Error!
+ FuncVA = (...v: list<any>): number => v # OK, `any` runtime check
+ FuncVA = (v1: string, v: string2): number => 333 # Error!
+ FuncVA = (v: list<string>): number => 3 # Error!
+
+If the destination funcref has no specified arguments, then there is no
+argument type checking: >
+ var FuncUnknownArgs: func: number
+ FuncUnknownArgs = (v): number => v # OK
+ FuncUnknownArgs = (v1: string, v2: string): number => 3 # OK
+ FuncUnknownArgs = (...v1: list<string>): number => 333 # OK
+<
+ *E1211* *E1217* *E1218* *E1219* *E1220* *E1221*
+ *E1222* *E1223* *E1224* *E1225* *E1226* *E1227*
+ *E1228* *E1238* *E1250* *E1251* *E1252* *E1256*
+ *E1297* *E1298* *E1301*
+Types are checked for most builtin functions to make it easier to spot
+mistakes.
+
+Categories of variables, defaults and null handling ~
+ *variable-categories* *null-variables*
+There are categories of variables:
+ primitive number, float, boolean
+ container string, blob, list, 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. Here's
+an example for each category: >
+ var num: number # primitives default to a 0 equivalent
+ var cont: list<string> # containers default to an empty container
+ var spec: job # specialized variables default to null
+<
+Vim does not have a familiar null value; it has various null_<type> predefined
+values, for example |null_string|, |null_list|, |null_job|. Primitives do not
+have a null_<type>. The 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, see |null-compare|.
+
+For a specialized variable, like `job`, null_<type> is used to clear the
+resources. For a container variable, resources can also be cleared by
+assigning an empty container to the variable. For example: >
+ var j: job = job_start(...)
+ # ... job does its work
+ j = null_job # clear the variable and release the job's resources
+
+ var l: list<any>
+ # ... add lots of stuff to list
+ l = [] # clear the variable and release container resources
+Using the empty container, rather than null_<type>, to clear a container
+variable may avoid null complications as described in |null-anomalies|.
+
+The initialization semantics of container variables and specialized variables
+differ. An uninitialized container defaults to an empty container: >
+ var l1: list<string> # empty container
+ var l2: list<string> = [] # empty container
+ var l3: list<string> = null_list # null container
+"l1" and "l2" are equivalent and indistinguishable initializations; but "l3"
+is a null container. A null container is similar to, but different from, an
+empty container, see |null-anomalies|.
+
+Specialized variables default to null. These job initializations are
+equivalent and indistinguishable: >
+ var j1: job
+ var j2: job = null_job
+ var j3 = null_job
+
+When a list or dict is declared, if the item type is not specified and can not
+be inferred, then the type is "any": >
+ var d1 = {} # type is "dict<any>"
+ var d2 = null_dict # type is "dict<any>"
+
+Declaring a function, see |vim9-func-declaration|, is particularly unique.
+
+ *null-compare*
+For familiar null compare semantics, where a null container is not equal to
+an empty container, do not use null_<type> in a comparison: >
+ vim9script
+ def F(arg: list<string> = null_list)
+ if arg == null
+ echo "null"
+ else
+ echo printf("not null, %sempty", empty(arg) ? '' : 'not ')
+ endif
+ enddef
+ F() # output: "null"
+ F(null_list) # output: "null"
+ F([]) # output: "not null, empty"
+ F(['']) # output: "not null, not empty"
+The above function takes a `list of strings` and reports on it.
+Change the above function signature to accept different types of arguments: >
+ def F(arg: list<any> = null_list) # any type of list
+ def F(arg: any = null) # any type
+<
+In the above example, where the goal is to distinguish a null list from an
+empty list, comparing against `null` instead of `null_list` is the correct
+choice. The basic reason is because "null_list == null" and "[] != null".
+Comparing to `null_list` fails since "[] == null_list". 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 chose to use null_<type> in
+comparisons and/or other situations.
+
+Elsewhere in the documentation it says:
+ Quite often a null value is handled the same as an
+ empty value, but not always
+Here's an example: >
+ vim9script
+ var s1: list<string>
+ var s2: list<string> = null_list
+ echo s1 # output: "[]"
+ echo s2 # output: "[]"
+
+ echo s1 + ['a'] # output: "['a']"
+ echo s2 + ['a'] # output: "['a']"
+
+ echo s1->add('a') # output: "['a']"
+ echo s2->add('a') # E1130: Can not add to null list
+<
+Two values equal to a null_<type> are not necessarily equal to each other: >
+ vim9script
+ echo {} == null_dict # true
+ echo null_dict == null # true
+ echo {} == null # false
+<
+Unlike the other containers, an uninitialized string is equal to null. The
+'is' operator can be used to determine if it is a null_string: >
+ vim9script
+ var s1: string
+ var s2 = null_string
+ echo s1 == null # true - this is unexpected
+ echo s2 == null # true
+ echo s2 is null_string # true
+
+ var b1: blob
+ var b2 = null_blob
+ echo b1 == null # false
+ echo b2 == null # true
+<
+Any variable initialized to the null_<type> is equal to the null_<type> and is
+also equal to null. For example: >
+ vim9script
+ var x = null_blob
+ echo x == null_blob # true
+ echo x == null # true
+<
+An uninitialized variable is usually equal to null; it depends on its type:
+ var s: string s == null
+ var b: blob b != null ***
+ var l: list<any> l != null ***
+ var d: dict<any> d != null ***
+ var f: func f == null
+ var j: job j == null
+ var c: channel c == null
+ var o: Class o == null
+
+A variable initialized to empty equals null_<type>; but not null:
+ var s2: string = "" == null_string != null
+ var b2: blob = 0z == null_blob != null
+ var l2: list<any> = [] == null_list != null
+ var d2: dict<any> = {} == null_dict != null
+
+NOTE: the specialized variables, like job, default to null value and have no
+corresponding empty value.
+
+==============================================================================
+
+5. 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` statement must
+appear as the first statement in the file (see |vim9-mix| for an exception).
+It tells Vim to interpret the script in its own namespace, instead of the
+global namespace. If a file starts with: >
+ vim9script
+ var myvar = 'yes'
+Then "myvar" will only exist in this file. While without `vim9script` it would
+be available as `g:myvar` from any other script and function.
+ *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.
+
+In Vim9 script the global "g:" namespace can still be used as before. And the
+"w:", "b:" and "t:" namespaces. These have in common that variables are not
+declared, have no specific type and they can be deleted. *E1304*
+
+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: >
+ " comments may go here
+ if !has('vim9script')
+ " legacy script commands go here
+ finish
+ endif
+ vim9script
+ # Vim9 script commands go here
+This allows for writing a script that takes advantage of the Vim9 script
+syntax if possible, but will also work on a Vim version without it.
+
+This can only work in 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* *:exp*
+Exporting an item can be written as: >
+ export const EXPORTED_CONST = 1234
+ export var someValue = ...
+ export final someValue = ...
+ export const someValue = ...
+ export def MyFunc() ...
+ export class MyClass ...
+ export interface MyClass ...
+< *E1043* *E1044*
+As this suggests, only constants, variables, `:def` functions and classes can
+be exported.
+
+ *E1042*
+`:export` can only be used in Vim9 script, at the script level.
+
+
+Import ~
+ *:import* *:imp* *E1094* *E1047* *E1262*
+ *E1048* *E1049* *E1053* *E1071* *E1088* *E1236*
+The exported items can be imported in another script. The import syntax has
+two forms. The simple form: >
+ 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".
+ *:import-as* *E1257* *E1261*
+In case the name is long or ambiguous, this form can be used to specify
+another name: >
+ import {longfilename} as {name}
+<
+In this form {name} becomes a specific script local name for the imported
+namespace. Therefore {name} must consist of letters, digits and '_', like
+|internal-variables|. The {longfilename} expression must evaluate to any
+filename. For example: >
+ import "thatscript.vim.v2" as that
+< *E1060* *E1258* *E1259* *E1260*
+Then you can use "that.item", etc. You are free to choose the name "that".
+Use something that will be recognized as referring to the imported script.
+Avoid command names, command modifiers and builtin function names, because the
+name will shadow them. It's better not to start the name with a capital
+letter, since it can then also shadow global user commands and functions.
+Also, you cannot use the name for something else in the script, such as a
+function or variable name.
+
+In case the dot in the name is undesired, a local reference can be made for a
+function: >
+ var LongFunc = that.LongFuncName
+
+This also works for constants: >
+ const MAXLEN = that.MAX_LEN_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 will need to use the full name, with the dot.
+
+`:import` can not be used in a function. Imported items are intended to exist
+at the script level and only imported once.
+
+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.
+
+If the name does not end in ".vim" then the use of "as name" is required.
+
+Once a vim9 script file has been imported, the result is cached and used the
+next time the same script is imported. It will not be read again.
+
+It is not allowed to import the same script twice, also when using two
+different "as" names.
+
+When using the imported name the dot and the item name must be in the same
+line, there can be no line break: >
+ echo that.
+ name # Error!
+ echo that
+ .name # Error!
+< *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.
+
+ *import-legacy* *legacy-import*
+`:import` 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()
+
+And using the "as name" form: >
+ import "otherfile.vim9script" as that
+ call s:that.OtherFunc()
+
+However, the namespace cannot be resolved on its own: >
+ import "that.vim"
+ echo s:that
+ " ERROR: E1060: Expected dot after name: s:that
+<
+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 that refer to
+ items imported from an autoload script. >
+ import autoload 'for/search.vim'
+ command -nargs=1 SearchForStuff search.Stuff(<f-args>)
+
+< This goes in .../plugin/anyname.vim. "anyname.vim" can be freely chosen.
+ The "SearchForStuff" command is now available to the user.
+
+ The "autoload" argument to `:import` means that the script is not loaded
+ until one of the items is actually used. The script will be found under
+ the "autoload" directory in 'runtimepath' instead of the "import"
+ directory. Alternatively 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)
+ ...
+
+< 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, as you would to 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. An
+absolute path is also possible. Examples: >
+ import autoload '../lib/implement.vim'
+ import autoload MyScriptsDir .. '/lib/implement.vim'
+
+For defining a mapping that uses the imported autoload script the special key
+|<ScriptCmd>| is useful. It allows for a command in a mapping to use the
+script context of where the mapping was defined.
+
+When compiling a `:def` function and a function in an autoload script is
+encountered, the script is not loaded until the `:def` function is called.
+This also means you get any errors only at runtime, since the argument and
+return types are not known yet. If you would use the name with '#' characters
+then the autoload script IS loaded.
+
+Be careful to not refer to an item in an autoload script that does trigger
+loading it unintentionally. For example, when setting an option that takes a
+function name, make sure to use a string, not a function reference: >
+ import autoload 'qftf.vim'
+ &quickfixtextfunc = 'qftf.Func' # autoload script NOT loaded
+ &quickfixtextfunc = qftf.Func # autoload script IS loaded
+On the other hand, it can be useful to load the script early, at a time when
+any errors should be given.
+
+For testing the |test_override()| function can be used to have the
+`import autoload` load the script right away, so that the items and types can
+be checked without waiting for them to be actually used: >
+ test_override('autoload', 1)
+Reset it later with: >
+ test_override('autoload', 0)
+Or: >
+ test_override('ALL', 0)
+
+
+==============================================================================
+
+6. Classes and interfaces *vim9-classes*
+
+In legacy 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 and interfaces 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|.
+
+
+==============================================================================
+
+9. 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
+cannot fail.
+
+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
+
+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
+
+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
+
+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: >
+ var mylist list<string>
+ final mylist list<string> = ['foo']
+ def Func(arg1 number, arg2 string) bool
+
+The first is more familiar for anyone used to C or Java. The second one
+doesn't really have an advantage over the first, so let's discard the second.
+
+Since we use type inference the type can be left out when it can be inferred
+from the value. This means that after `var` we don't know if a type or a name
+follows. That makes parsing harder, not only for Vim but also for humans.
+Also, it will not be allowed to use a variable name that could be a type name,
+using `var string string` is too confusing.
+
+The chosen syntax, using a colon to separate the name from the type, adds
+punctuation, but it actually makes it easier to recognize the parts of a
+declaration.
+
+
+Expressions ~
+
+Expression evaluation was already close to what other languages are doing.
+Some details are unexpected and can be improved. For example a boolean
+condition would accept a string, convert it to a number and check if the
+number is non-zero. This is unexpected and often leads to mistakes, since
+text not starting with a number would be converted to zero, which is
+considered false. Thus using a string for a condition would often not give an
+error and be considered false. That is confusing.
+
+In Vim9 type checking is stricter to avoid mistakes. Where a condition is
+used, e.g. with the `:if` command and the `||` operator, only boolean-like
+values are accepted:
+ true: `true`, `v:true`, `1`, `0 < 9`
+ false: `false`, `v:false`, `0`, `0 > 9`
+Note that the number zero is false and the number one is true. This is more
+permissive than most other languages. It was done because many builtin
+functions return these values, and changing that causes more problems than it
+solves. After using this for a while it turned out to work well.
+
+If you have any type of value and want to use it as a boolean, use the `!!`
+operator:
+ true: `!!'text'` `!![99]` `!!{'x': 1}` `!!99`
+ false: `!!''` `!![]` `!!{}`
+
+From a language like JavaScript we have this handy construct: >
+ GetName() || 'unknown'
+However, this conflicts with only allowing a boolean for a condition.
+Therefore the "??" operator was added: >
+ GetName() ?? 'unknown'
+Here you can explicitly express your intention to use the value as-is and not
+result in a boolean. This is called the |falsy-operator|.
+
+
+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 a Vim9 or legacy 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 most languages support classes the lack of
+support for classes in Vim is then a problem.
+
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: