Update runtime files.
diff --git a/runtime/doc/vim9.txt b/runtime/doc/vim9.txt
index b30db0b..a7b91db 100644
--- a/runtime/doc/vim9.txt
+++ b/runtime/doc/vim9.txt
@@ -1,4 +1,4 @@
-*vim9.txt* For Vim version 8.2. Last change: 2021 Jan 03
+*vim9.txt* For Vim version 8.2. Last change: 2021 Jan 10
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -52,8 +52,9 @@
- a script file where the first command is `vim9script`
- an autocommand defined in the context of the above
-When using `:function` in a Vim9 script file the legacy syntax is used.
-However, this can be confusing and is therefore discouraged.
+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
@@ -70,28 +71,29 @@
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
+ echo "hello" # comment
- Using a backslash for line continuation is hardly ever needed: >
- echo "hello "
+ echo "hello "
.. yourName
.. ", how are you?"
- White space is required in many places.
- Assign values without `:let`, declare variables with `:var`: >
- var count = 0
+ var count = 0
count += 3
- Constants can be declared with `:final` and `:const`: >
- final matches = [] # add matches
+ final matches = [] # add matches
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')
+ writefile(['done'], 'file.txt')
- You cannot use `:xit`, `:t`, `:append`, `:change`, `:insert` or curly-braces
names.
- A range before a command must be prefixed with a colon: >
- :%s/this/that
+ :%s/this/that
+- Unless mentioned specifically, the highest |scriptversion| is used.
Comments starting with # ~
@@ -315,7 +317,7 @@
NAMES[0] = ["Jack"] # Error!
NAMES[0][0] = "Jack" # Error!
NAMES[1] = ["Emma"] # Error!
- Names[1][0] = "Emma" # OK, now females[0] == "Emma"
+ NAMES[1][0] = "Emma" # OK, now females[0] == "Emma"
< *E1092*
Declaring more than one variable at a time, using the unpack notation, is
@@ -432,7 +434,7 @@
.. middle
.. end
var total = start +
- end -
+ end -
correction
var result = positive
? PosFunc(arg)
@@ -629,9 +631,9 @@
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
+ !'yes' == false
!![] == false
- !![1, 2, 3] == true
+ !![1, 2, 3] == true
When using "`.."` for string concatenation arguments of simple types are
always converted to string: >
@@ -651,6 +653,14 @@
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.
+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 ~
@@ -689,7 +699,7 @@
if !has('feature')
return
endif
- use-feature # May give compilation error
+ use-feature # May give a compilation error
enddef
For a workaround, split it in two functions: >
func Maybe()
@@ -709,6 +719,25 @@
use-feature
endif
enddef
+< *vim9-user-command*
+Another side effect of compiling a function is that the precense 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()
@@ -946,6 +975,12 @@
- Using a string value when setting a number options.
- Using a number where a string is expected. *E1024*
+One consequence is that the item type of a list or dict given to map() must
+not change. This will give an error in compiled code: >
+ map([1, 2, 3], (i, v) => 'item ' .. i)
+ E1012: Type mismatch; expected list<number> but got list<string>
+Instead use |mapnew()|.
+
==============================================================================
5. Namespace, Import and Export
@@ -1055,14 +1090,14 @@
1. In the plugin define user commands, functions and/or mappings that refer to
an autoload script. >
- command -nargs=1 SearchForStuff call searchfor#Stuff(<f-args>)
+ command -nargs=1 SearchForStuff call searchfor#Stuff(<f-args>)
< This goes in .../plugin/anyname.vim. "anyname.vim" can be freely chosen.
2. In the autoload script do the actual work. You can import items from
other files to split up functionality in appropriate pieces. >
vim9script
- import FilterFunc from "../import/someother.vim"
+ import FilterFunc from "../import/someother.vim"
def searchfor#Stuff(arg: string)
var filtered = FilterFunc(arg)
...