vim: runtime/doc/vim9.txt comparison

comparison runtime/doc/vim9.txt @ 27459:5825405e4e2c

Update runtime files Commit: https://github.com/vim/vim/commit/f10911e5db16f1fe6ab519c5d091ad0c1df0d063 Author: Bram Moolenaar <Bram@vim.org> Date: Sat Jan 29 22:20:48 2022 +0000 Update runtime files

author	Bram Moolenaar <Bram@vim.org>
date	Sat, 29 Jan 2022 23:30:04 +0100
parents	3649b5a6b1b6
children	4789f29c9595

comparison

equal deleted inserted replaced

-:2a7fc102cb91
+:5825405e4e2c
-*vim9.txt*	For Vim version 8.2.  Last change: 2022 Jan 23
+*vim9.txt*	For Vim version 8.2.  Last change: 2022 Jan 29
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
 - 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`, declare variables with `:var`: >
+- 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 matches
 	const names = ['Betty', 'Peter']  # cannot be changed
 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.
 	endfunc
 	def CallLegacy()
 	  var d = {func: Legacy, value: 'text'}
 	  d.func()
 	enddef
+<							*E1096*
 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*
 Variable arguments are defined as the last argument, with a name and have a
 list type, similar to TypeScript.  For example, a list of numbers: >
 When 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, possibly imported
-- in the list of global functions
-However, it is recommended to always use "g:" to refer to a global function
-for clarity.
 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
 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!).
+							*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.
 When compiling a function and a function call is encountered for a function
 	def g:SomeFunc()
 	....
 Variable declarations with :var, :final and :const ~
-					*vim9-declaration* *:var*
+				*vim9-declaration* *:var*
-					*E1017* *E1020* *E1054*
+				*E1017* *E1020* *E1054* *E1087* *E1108* *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: >
 	   inner = 5
 	else
 	   inner = 0
 	endif
 	echo inner
-<							*E1025*
+<							*E1025* *E1128*
 To intentionally hide a variable from code that follows, a block can be
 used: >
 	{
 	   var temp = 'temp'
 	   ...
 		 silent! exe ':%! some formatting command'
 		 winrestview(save)
 	   }
 Although using a :def function probably works better.
-						*E1022*
+				*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.
 						*E1016* *E1052* *E1066*
 Example: >
 	const myList = [1, 2]
 	myList = [3, 4]		# Error!
 	myList[0] = 9		# Error!
 	myList->add(3)		# Error!
-<							*:final*
+<							*: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
 	    key: value
 	 })->method()
 Automatic line continuation ~
-						*vim9-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',
 	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.
 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*
+				*E1004* *E1068* *E1069* *E1074* *E1127*
 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 "=": >
 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
 	echo dict
 	{'456': 'with', '123': 'without'}
 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`.
 					*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*
+							*E1077* *E1123*
 			{arguments} is a sequence of zero or more argument
 			declarations.  There are three forms:
 				{name}: {type}
 				{name} = {value}
 				{name}: {type} = {value}
 			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.
 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*
+						*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.
 	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 string.  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 inferred then the type is allowed to change: >
+	[1, 2, 3]->extend('x')  # result: [1, 2, 3, 'x']
 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
 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*
+- 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.  This will give an error in Vim9 script: >
 	echo map([1, 2, 3], (i, v) => 'item ' .. i)
 	E1012: Type mismatch; expected number but got string
 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
 In case the name is long or ambiguous, another name can be specified: >
 	import "thatscript.vim" as that
 <							*E1060*
 Then you can use "that.EXPORTED_CONST", "that.someValue", etc.  You are free
 to choose the name "that".  Use something that will be recognized as referring
-to the imported script.  Avoid command names and builtin function names,
+to the imported script.  Avoid command names, command modifiers and builtin
-because the name will shadow them.  If the name starts with a capital letter
+function names, because the name will shadow them.
-it can also shadow global user commands and functions.  Also, you cannot use
+If the name starts with a capital letter it can also shadow global user
-the name for something else in the script, such as a function or variable
+commands and functions.  Also, you cannot use the name for something else in
-name.
+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
 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

Mercurial > vim

comparison runtime/doc/vim9.txt @ 27459:5825405e4e2c