Merge remote-tracking branch 'vim/master'

Author: ichizok

runtime/doc/eval.txt

@@ -2653,6 +2653,7 @@ matcharg({nr})			List	arguments of |:match|
 matchdelete({id} [, {win}])	Number	delete match identified by {id}
 matchend({expr}, {pat} [, {start} [, {count}]])
 				Number	position where {pat} ends in {expr}
+matchfuzzy({list}, {str})	List	fuzzy match {str} in {list}
 matchlist({expr}, {pat} [, {start} [, {count}]])
 				List	match and submatches of {pat} in {expr}
 matchstr({expr}, {pat} [, {start} [, {count}]])
@@ -7319,6 +7320,29 @@ matchend({expr}, {pat} [, {start} [, {count}]])			*matchend()*
 		Can also be used as a |method|: >
 			GetText()->matchend('word')
 
+
+matchfuzzy({list}, {str})			*matchfuzzy()*
+		Returns a list with all the strings in {list} that fuzzy
+		match {str}. The strings in the returned list are sorted
+		based on the matching score. {str} is treated as a literal
+		string and regular expression matching is NOT supported.
+		The maximum supported {str} length is 256.
+
+		If there are no matching strings or there is an error, then an
+		empty list is returned. If length of {str} is greater than
+		256, then returns an empty list.
+
+		Example: >
+		   :echo matchfuzzy(["clay", "crow"], "cay")
+<		results in ["clay"]. >
+		   :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl")
+<		results in a list of buffer names fuzzy matching "ndl". >
+		   :echo v:oldfiles->matchfuzzy("test")
+<		results in a list of file names fuzzy matching "test". >
+		   :let l = readfile("buffer.c")->matchfuzzy("str")
+<		results in a list of lines in "buffer.c" fuzzy matching "str".
+
+
 matchlist({expr}, {pat} [, {start} [, {count}]])		*matchlist()*
 		Same as |match()|, but return a |List|.  The first item in the
 		list is the matched string, same as what matchstr() would
@@ -12357,7 +12381,9 @@ text...
 <			is equivalent to: >
 				:let x = 1
 				:lockvar! x
-<			This is useful if you want to make sure the variable
+<			NOTE: in Vim9 script `:const` works differently, see
+			|vim9-const|
+			This is useful if you want to make sure the variable
 			is not modified.  If the value is a List or Dictionary
 			literal then the items also cannot be changed: >
 				const ll = [1, 2, 3]
@@ -12397,6 +12423,8 @@ text...
 
 			[depth] is relevant when locking a |List| or
 			|Dictionary|.  It specifies how deep the locking goes:
+				0	Lock the variable {name} but not its
+					value.
 				1	Lock the |List| or |Dictionary| itself,
 					cannot add or remove items, but can
 					still change their values.
@@ -12410,7 +12438,14 @@ text...
 					|Dictionary|, one level deeper.
 			The default [depth] is 2, thus when {name} is a |List|
 			or |Dictionary| the values cannot be changed.
-								*E743*
+
+			Example with [depth] 0: >
+				let mylist = [1, 2, 3]
+				lockvar 0 mylist
+				let mylist[0] = 77   	" OK
+				call add(mylist, 4]  	" OK
+				let mylist = [7, 8, 9]  " Error!
+<								*E743*
 			For unlimited depth use [!] and omit [depth].
 			However, there is a maximum depth of 100 to catch
 			loops.

runtime/doc/usr_41.txt

@@ -603,6 +603,7 @@ String manipulation:					*string-functions*
 	charclass()		class of a character
 	match()			position where a pattern matches in a string
 	matchend()		position where a pattern match ends in a string
+	matchfuzzy()		fuzzy matches a string in a list of strings
 	matchstr()		match of a pattern in a string
 	matchstrpos()		match and positions of a pattern in a string
 	matchlist()		like matchstr() and also return submatches

runtime/doc/vim9.txt

@@ -1,4 +1,4 @@
-*vim9.txt*	For Vim version 8.2.  Last change: 2020 Sep 07
+*vim9.txt*	For Vim version 8.2.  Last change: 2020 Sep 13
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -192,6 +192,9 @@ To intentionally avoid a variable being available later, a block can be used:
 	}
 	echo temp  # Error!
 
+Declaring a variable with a type but without an initializer will initialize to
+zero, false or empty.
+
 An existing variable cannot be assigned to with `:let`, since that implies a
 declaration.  Global, window, tab, buffer and Vim variables can only be used
 without `:let`, because they are not really declared, they can also be deleted
@@ -210,6 +213,40 @@ at the script level. >
 
 Since "&opt = value" is now assigning a value to option "opt", ":&" cannot be
 used to repeat a `:substitute` command.
+							*vim9-const*
+In legacy Vim script "const list = []" would make the variable "list"
+immutable and also the value.  Thus you cannot add items to the list.  This
+differs from what many languages do. Vim9 script does it like TypeScript: only
+"list" is immutable, the value can be changed.
+
+One can use `:const!` to make both the variable and the value immutable.  Use
+this for composite structures that you want to make sure will not be modified.
+
+How this works: >
+	vim9script
+	const list = [1, 2]
+	list = [3, 4]	     # Error!
+	list[0] = 2          # OK
+
+	const! LIST = [1, 2]
+	LIST = [3, 4]	     # Error!
+	LIST[0] = 2          # Error!
+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. >
+	cont 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"
+
+Rationale: TypeScript has no way to make the value immutable.  One can use
+immutable types, but that quickly gets complicated for nested values.  And
+with a type cast the value can be made mutable again, which means there is no
+guarantee the value won't change.  Vim supports immutable values, in legacy
+script this was done with `:lockvar`.  But that is an extra statement and also
+applies to nested values.  Therefore the solution to use `:const!`.
 
 							*E1092*
 Declaring more than one variable at a time, using the unpack notation, is
@@ -408,7 +445,7 @@ for using a list or job.  This is very much like JavaScript, but there are a
 few exceptions.
 
 	type		TRUE when ~
-	bool		v:true
+	bool		v:true or 1
 	number		non-zero
 	float		non-zero
 	string		non-empty
@@ -946,26 +983,41 @@ declarations: >
 Expression evaluation was already close to what JavaScript and other languages
 are doing.  Some details are unexpected and can be fixed.  For example how the
 || and && operators work.  Legacy Vim script: >
-	let result = 44
+	let value = 44
 	...
-	return result || 0	# returns 1
+	let result = value || 0  # result == 1
 
 Vim9 script works like JavaScript/TypeScript, keep the value: >
-	let result = 44
+	let value = 44
 	...
-	return result || 0	# returns 44
-
-On the other hand, overloading "+" to use both for addition and string
-concatenation 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.
+	let result = value || 0  # result == 44
 
 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
-are happy with.  TypeScript is a complex language with its own advantages and
-disadvantages.  People used to 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.
+will be happy with.  TypeScript is a complex language with its own 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 used to 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.
+- 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.
 
 
 Import and Export ~