Merge remote-tracking branch 'upstream/master' into aucmd_textputpostaucmd_textputpost

1 files changed, 201 insertions, 83 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 58759a6053..a73932be00 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -39,7 +39,7 @@ List		An ordered sequence of items, see |List| for details.
 
 Dictionary	An associative, unordered array: Each entry has a key and a
 		value. |Dictionary|
-		Examples:
+		Examples: >
 			{"blue": "#0000ff", "red": "#ff0000"}
 			#{blue: "#0000ff", red: "#ff0000"}
 
@@ -93,7 +93,27 @@ non-zero number it means TRUE: >
 	:" executed
 To test for a non-empty string, use empty(): >
 	:if !empty("foo")
-<
+
+<						*falsy* *truthy*
+An expression can be used as a condition, ignoring the type and only using
+whether the value is "sort of true" or "sort of false".  Falsy is:
+	the number zero
+	empty string, blob, list or dictionary
+Other values are truthy.  Examples:
+	0	falsy
+	1	truthy
+	-1	truthy
+	0.0	falsy
+	0.1	truthy
+	''	falsy
+	'x'	truthy
+	[]	falsy
+	[0]	truthy
+	{}	falsy
+	#{x: 1} truthy
+	0z	falsy
+	0z00	truthy
+
 							*non-zero-arg*
 Function arguments often behave slightly different from |TRUE|: If the
 argument is present and it evaluates to a non-zero Number, |v:true| or a
@@ -119,7 +139,7 @@ You will not get an error if you try to change the type of a variable.
 
 
 1.2 Function references ~
-							*Funcref* *E695* *E718*
+					*Funcref* *E695* *E718* *E1192*
 A Funcref variable is obtained with the |function()| function, the |funcref()|
 function or created with the lambda expression |expr-lambda|.  It can be used
 in an expression in the place of a function name, before the parenthesis
@@ -250,6 +270,9 @@ similar to -1. >
 	:let shortlist = mylist[2:2]	" List with one item: [3]
 	:let otherlist = mylist[:]	" make a copy of the List
 
+Notice that the last index is inclusive.  If you prefer using an exclusive
+index use the |slice()| method.
+
 If the first index is beyond the last item of the List or the second item is
 before the first item, the result is an empty list.  There is no error
 message.
@@ -818,19 +841,19 @@ Expression syntax summary, from least to most significant:
 
 |expr9|	number			number constant
 	"string"		string constant, backslash is special
-	'string'		string constant, ' is doubled
+	`'string'`		string constant, ' is doubled
 	[expr1, ...]		|List|
-	{expr1: expr1, ...}	|Dictionary|
+	`{expr1: expr1, ...}`	|Dictionary|
 	#{key: expr1, ...}	|Dictionary|
 	&option			option value
 	(expr1)			nested expression
 	variable		internal variable
 	va{ria}ble		internal variable with curly braces
 	$VAR			environment variable
-	@r			contents of register 'r'
+	@r			contents of register "r"
 	function(expr1, ...)	function call
 	func{ti}on(expr1, ...)	function call with curly braces
-	{args -> expr1}		lambda expression
+	`{args -> expr1}`	lambda expression
 
 
 "..." indicates that the operations in this level can be concatenated.
@@ -841,9 +864,12 @@ All expressions within one level are parsed from left to right.
 
 
 ------------------------------------------------------------------------------
-expr1							*expr1* *ternary* *E109*
+expr1				*expr1* *ternary* *falsy-operator* *??* *E109*
+
+The ternary operator: expr2 ? expr1 : expr1
+The falsy operator:   expr2 ?? expr1
 
-expr2 ? expr1 : expr1
+Ternary operator ~
 
 The expression before the '?' is evaluated to a number.  If it evaluates to
 |TRUE|, the result is the value of the expression between the '?' and ':',
@@ -866,6 +892,23 @@ To keep this readable, using |line-continuation| is suggested: >
 You should always put a space before the ':', otherwise it can be mistaken for
 use in a variable such as "a:1".
 
+Falsy operator ~
+
+This is also known as the "null coalescing operator", but that's too
+complicated, thus we just call it the falsy operator.
+
+The expression before the '??' is evaluated.  If it evaluates to
+|truthy|, this is used as the result.  Otherwise the expression after the '??'
+is evaluated and used as the result.  This is most useful to have a default
+value for an expression that may result in zero or empty: >
+	echo theList ?? 'list is empty'
+	echo GetName() ?? 'unknown'
+
+These are similar, but not equal: >
+	expr2 ?? expr1
+	expr2 ? expr2 : expr1
+In the second line "expr2" is evaluated twice.
+
 
 ------------------------------------------------------------------------------
 expr2 and expr3						*expr2* *expr3*
@@ -1044,7 +1087,7 @@ That works, since the String "190" is automatically converted to the Number
 	1 . 90 * 90.0
 Should be read as: >
 	1 . (90 * 90.0)
-Since '.' has lower precedence than '*'.  This does NOT work, since this
+Since '.' has lower precedence than "*".  This does NOT work, since this
 attempts to concatenate a Float and a String.
 
 When dividing a Number by zero the result depends on the value:
@@ -1112,6 +1155,8 @@ text column numbers start with one!  Example, to get the byte under the
 cursor: >
 	:let c = getline(".")[col(".") - 1]
 
+Index zero gives the first byte.  Careful: text column numbers start with one!
+
 If the length of the String is less than the index, the result is an empty
 String.  A negative index always results in an empty string (reason: backward
 compatibility).  Use [-1:] to get the last byte.
@@ -1136,6 +1181,9 @@ In legacy Vim script the indexes are byte indexes.  This doesn't recognize
 multibyte encodings, see |byteidx()| for computing the indexes.  If expr8 is
 a Number it is first converted to a String.
 
+The item at index expr1b is included, it is inclusive.  For an exclusive index
+use the |slice()| function.
+
 If expr1a is omitted zero is used.  If expr1b is omitted the length of the
 string minus one is used.
 
@@ -1196,7 +1244,7 @@ Note that the dot is also used for String concatenation.  To avoid confusion
 always put spaces around the dot for String concatenation.
 
 
-expr8(expr1, ...)	|Funcref| function call
+expr8(expr1, ...)	|Funcref| function call		*E1085*
 
 When expr8 is a |Funcref| type variable, invoke the function it refers to.
 
@@ -1367,6 +1415,60 @@ to be doubled.  These two commands are equivalent: >
 
 
 ------------------------------------------------------------------------------
+interpolated-string				*$quote* *interpolated-string*
+
+$"string"		interpolated string constant		*expr-$quote*
+$'string'		interpolated literal string constant	*expr-$'*
+
+Interpolated strings are an extension of the |string| and |literal-string|,
+allowing the inclusion of Vim script expressions (see |expr1|).  Any
+expression returning a value can be enclosed between curly braces.  The value
+is converted to a string.  All the text and results of the expressions
+are concatenated to make a new string.
+								*E1278*
+To include an opening brace '{' or closing brace '}' in the string content
+double it.  For double quoted strings using a backslash also works.  A single
+closing brace '}' will result in an error.
+
+Examples: >
+	let your_name = input("What's your name? ")
+<	What's your name?  Peter ~
+>
+	echo
+	echo $"Hello, {your_name}!"
+<	Hello, Peter! ~
+>
+	echo $"The square root of {{9}} is {sqrt(9)}"
+<	The square root of {9} is 3.0 ~
+
+						*string-offset-encoding*
+A string consists of multiple characters.  UTF-8 uses one byte for ASCII
+characters, two bytes for other latin characters and more bytes for other
+characters.
+
+A string offset can count characters or bytes.  Other programs may use
+UTF-16 encoding (16-bit words) and an offset of UTF-16 words.  Some functions
+use byte offsets, usually for UTF-8 encoding.  Other functions use character
+offsets, in which case the encoding doesn't matter.
+
+The different offsets for the string "a©😊" are below:
+
+  UTF-8 offsets:
+      [0]: 61, [1]: C2, [2]: A9, [3]: F0, [4]: 9F, [5]: 98, [6]: 8A
+  UTF-16 offsets:
+      [0]: 0061, [1]: 00A9, [2]: D83D, [3]: DE0A
+  UTF-32 (character) offsets:
+      [0]: 00000061, [1]: 000000A9, [2]: 0001F60A
+
+You can use the "g8" and "ga" commands on a character to see the
+decimal/hex/octal values.
+
+The functions |byteidx()|, |utf16idx()| and |charidx()| can be used to convert
+between these indices.  The functions |strlen()|, |strutf16len()| and
+|strcharlen()| return the number of bytes, UTF-16 code units and characters in
+a string respectively.
+
+------------------------------------------------------------------------------
 option						*expr-option* *E112* *E113*
 
 &option			option value, local value if possible
@@ -1445,7 +1547,7 @@ See below |functions|.
 ------------------------------------------------------------------------------
 lambda expression				*expr-lambda* *lambda*
 
-{args -> expr1}		lambda expression
+`{args -> expr1}`	lambda expression			*E451*
 
 A lambda expression creates a new unnamed function which returns the result of
 evaluating |expr1|.  Lambda expressions differ from |user-function|s in
@@ -1670,38 +1772,6 @@ v:argv		The command line arguments Vim was invoked with.  This is a
 		list of strings.  The first item is the Vim command.
 		See |v:progpath| for the command with full path.
 
-					*v:beval_col* *beval_col-variable*
-v:beval_col	The number of the column, over which the mouse pointer is.
-		This is the byte index in the |v:beval_lnum| line.
-		Only valid while evaluating the 'balloonexpr' option.
-
-					*v:beval_bufnr* *beval_bufnr-variable*
-v:beval_bufnr	The number of the buffer, over which the mouse pointer is. Only
-		valid while evaluating the 'balloonexpr' option.
-
-					*v:beval_lnum* *beval_lnum-variable*
-v:beval_lnum	The number of the line, over which the mouse pointer is. Only
-		valid while evaluating the 'balloonexpr' option.
-
-					*v:beval_text* *beval_text-variable*
-v:beval_text	The text under or after the mouse pointer.  Usually a word as
-		it is useful for debugging a C program.  'iskeyword' applies,
-		but a dot and "->" before the position is included.  When on a
-		']' the text before it is used, including the matching '[' and
-		word before it.  When on a Visual area within one line the
-		highlighted text is used.  Also see |<cexpr>|.
-		Only valid while evaluating the 'balloonexpr' option.
-
-					*v:beval_winnr* *beval_winnr-variable*
-v:beval_winnr	The number of the window, over which the mouse pointer is. Only
-		valid while evaluating the 'balloonexpr' option.  The first
-		window has number zero (unlike most other places where a
-		window gets a number).
-
-					*v:beval_winid* *beval_winid-variable*
-v:beval_winid	The |window-ID| of the window, over which the mouse pointer
-		is.  Otherwise like v:beval_winnr.
-
 					*v:char* *char-variable*
 v:char		Argument for evaluating 'formatexpr' and used for the typed
 		character when using <expr> in an abbreviation |:map-<expr>|.
@@ -1776,7 +1846,7 @@ v:ctype		The current locale setting for characters of the runtime
 v:dying		Normally zero.  When a deadly signal is caught it's set to
 		one.  When multiple signals are caught the number increases.
 		Can be used in an autocommand to check if Vim didn't
-		terminate normally. {only works on Unix}
+		terminate normally.
 		Example: >
 	:au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
 <		Note: if another deadly signal is caught when v:dying is one,
@@ -1826,7 +1896,7 @@ v:event		Dictionary of event data for the current |autocommand|.  Valid
 			abort		Whether the event triggered during
 					an aborting condition (e.g. |c_Esc| or
 					|c_CTRL-C| for |CmdlineLeave|).
-			chan		|channel-id| or 0 for "internal".
+			chan		|channel-id|
 			cmdlevel	Level of cmdline.
 			cmdtype		Type of cmdline, |cmdline-char|.
 			cwd		Current working directory.
@@ -1849,18 +1919,18 @@ v:event		Dictionary of event data for the current |autocommand|.  Valid
 			completed_item    Current selected complete item on
 					|CompleteChanged|, Is `{}` when no complete
 					item selected.
-			height 		Height of popup menu on |CompleteChanged|
-			width   	width of popup menu on |CompleteChanged|
-			row  	 	Row count of popup menu on |CompleteChanged|,
+			height		Height of popup menu on |CompleteChanged|
+			width		width of popup menu on |CompleteChanged|
+			row		Row count of popup menu on |CompleteChanged|,
 					relative to screen.
-			col  	 	Col count of popup menu on |CompleteChanged|,
+			col		Col count of popup menu on |CompleteChanged|,
 					relative to screen.
-			size 		Total number of completion items on
+			size		Total number of completion items on
 					|CompleteChanged|.
-			scrollbar 	Is |v:true| if popup menu have scrollbar, or
+			scrollbar	Is |v:true| if popup menu have scrollbar, or
 					|v:false| if not.
-			changed_window 	Is |v:true| if the the event fired
-					while changing window (or tab) on |DirChanged|.
+			changed_window	Is |v:true| if the event fired while
+					changing window (or tab) on |DirChanged|.
 			status		Job status or exit code, -1 means "unknown". |TermClose|
 
 					*v:exception* *exception-variable*
@@ -2011,6 +2081,11 @@ v:lnum		Line number for the 'foldexpr' |fold-expr|, 'formatexpr',
 v:lua		Prefix for calling Lua functions from expressions.
 		See |v:lua-call| for more information.
 
+						*v:maxcol* *maxcol-variable*
+v:maxcol	Maximum line length.  Depending on where it is used it can be
+		screen columns, characters or bytes.  The value currently is
+		2147483647 on all systems.
+
 					*v:mouse_win* *mouse_win-variable*
 v:mouse_win	Window number for a mouse click obtained with |getchar()|.
 		First window has number 1, like with |winnr()|.  The value is
@@ -2135,7 +2210,7 @@ v:register	The name of the register in effect for the current normal mode
 		(use this in custom commands that take a register).
 		If none is supplied it is the default register '"', unless
 		'clipboard' contains "unnamed" or "unnamedplus", then it is
-		'*' or '+'.
+		"*" or '+'.
 		Also see |getreg()| and |setreg()|
 
 					*v:relnum* *relnum-variable*
@@ -2201,12 +2276,13 @@ v:stderr	|channel-id| corresponding to stderr. The value is always 2;
 			:call chansend(v:stderr, "error: toaster empty\n")
 <
 					*v:swapname* *swapname-variable*
-v:swapname	Only valid when executing |SwapExists| autocommands: Name of
-		the swap file found.  Read-only.
+v:swapname	Name of the swapfile found.
+		Only valid during |SwapExists| event.
+		Read-only.
 
 					*v:swapchoice* *swapchoice-variable*
 v:swapchoice	|SwapExists| autocommands can set this to the selected choice
-		for handling an existing swap file:
+		for handling an existing swapfile:
 			'o'	Open read-only
 			'e'	Edit anyway
 			'r'	Recover
@@ -2242,18 +2318,10 @@ v:t_string	Value of |String| type.  Read-only.  See: |type()|
 v:t_blob	Value of |Blob| type.  Read-only.  See: |type()|
 
 				*v:termresponse* *termresponse-variable*
-v:termresponse	The escape sequence returned by the terminal for the DA
-		(request primary device attributes) control sequence.  It is
-		set when Vim receives an escape sequence that starts with ESC
-		[ or CSI and ends in a 'c', with only digits, ';' and '.' in
-		between.
-		When this option is set, the TermResponse autocommand event is
-		fired, so that you can react to the response from the
-		terminal.
-		The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c".  Pp
-		is the terminal type: 0 for vt100 and 1 for vt220.  Pv is the
-		patch level (since this was introduced in patch 95, it's
-		always 95 or bigger).  Pc is always zero.
+v:termresponse	The value of the most recent OSC or DCS escape sequence
+		received by Nvim from the terminal. This can be read in a
+		|TermResponse| event handler after querying the terminal using
+		another escape sequence.
 
 					*v:testing* *testing-variable*
 v:testing	Must be set before using `test_garbagecollect_now()`.
@@ -2418,7 +2486,7 @@ This does NOT work: >
 			*:let/=* *:let%=* *:let.=* *:let..=* *E734*
 :let {var} += {expr1}	Like ":let {var} = {var} + {expr1}".
 :let {var} -= {expr1}	Like ":let {var} = {var} - {expr1}".
-:let {var} *= {expr1}	Like ":let {var} = {var} * {expr1}".
+`:let {var} *= {expr1}`	Like ":let {var} = {var} * {expr1}".
 :let {var} /= {expr1}	Like ":let {var} = {var} / {expr1}".
 :let {var} %= {expr1}	Like ":let {var} = {var} % {expr1}".
 :let {var} .= {expr1}	Like ":let {var} = {var} . {expr1}".
@@ -2526,15 +2594,31 @@ This does NOT work: >
 			|List| item.
 
 						*:let=<<* *:let-heredoc*
-						*E990* *E991* *E172* *E221*
-:let {var-name} =<< [trim] {endmarker}
+					*E990* *E991* *E172* *E221* *E1145*
+:let {var-name} =<< [trim] [eval] {endmarker}
 text...
 text...
 {endmarker}
 			Set internal variable {var-name} to a |List|
 			containing the lines of text bounded by the string
-			{endmarker}. The lines of text is used as a
-			|literal-string|.
+			{endmarker}.
+
+			If "eval" is not specified, then each line of text is
+			used as a |literal-string|, except that single quotes
+			does not need to be doubled.
+			If "eval" is specified, then any Vim expression in the
+			form {expr} is evaluated and the result replaces the
+			expression, like with |interpolated-string|.
+			Example where $HOME is expanded: >
+				let lines =<< trim eval END
+				  some text
+				  See the file {$HOME}/.vimrc
+				  more text
+				END
+<			There can be multiple Vim expressions in a single line
+			but an expression cannot span multiple lines.  If any
+			expression evaluation fails, then the assignment fails.
+
 			{endmarker} must not contain white space.
 			{endmarker} cannot start with a lower case character.
 			The last line should end only with the {endmarker}
@@ -2584,6 +2668,13 @@ text...
 					1 2 3 4
 					5 6 7 8
 				DATA
+
+				let code =<< trim eval CODE
+				   let v = {10 + 20}
+				   let h = "{$HOME}"
+				   let s = "{Str1()} abc {Str2()}"
+				   let n = {MyFunc(3, 4)}
+				CODE
 <
 								*E121*
 :let {var-name}	..	List the value of variable {var-name}.  Multiple
@@ -2700,8 +2791,8 @@ text...
 			Example with [depth] 0: >
 				let mylist = [1, 2, 3]
 				lockvar 0 mylist
-				let mylist[0] = 77   	" OK
-				call add(mylist, 4]  	" OK
+				let mylist[0] = 77	" OK
+				call add(mylist, 4)	" OK
 				let mylist = [7, 8, 9]  " Error!
 <								*E743*
 			For unlimited depth use [!] and omit [depth].
@@ -4172,10 +4263,10 @@ The input is in the variable "line", the results in the variables "file",
 
 getting the scriptnames in a Dictionary ~
 						*scriptnames-dictionary*
-The |:scriptnames| command can be used to get a list of all script files that
-have been sourced.  There is no equivalent function or variable for this
-(because it's rarely needed).  In case you need to manipulate the list this
-code can be used: >
+The `:scriptnames` command can be used to get a list of all script files that
+have been sourced.  There is also the `getscriptinfo()` function, but the
+information returned is not exactly the same.  In case you need to manipulate
+the output of `scriptnames` this code can be used: >
     " Get the output of ":scriptnames" in the scriptnames_output variable.
     let scriptnames_output = ''
     redir => scriptnames_output
@@ -4244,8 +4335,8 @@ Textlock							*textlock*
 In a few situations it is not allowed to change the text in the buffer, jump
 to another window and some other things that might confuse or break what Vim
 is currently doing.  This mostly applies to things that happen when Vim is
-actually doing something else.  For example, evaluating the 'balloonexpr' may
-happen any moment the mouse cursor is resting at some position.
+actually doing something else.  For example, a TextYankPost autocommand cannot
+edit the text it is yanking.
 
 This is not allowed when the textlock is active:
 	- changing the buffer text
@@ -4255,6 +4346,33 @@ This is not allowed when the textlock is active:
 	- etc.
 
 ==============================================================================
+Vim script library					*vim-script-library*
+
+Vim comes bundled with a Vim script library, that can be used by runtime,
+script authors.  Currently, it only includes very few functions, but it may
+grow over time.
+
+								*dist#vim*
+The functions make use of the autoloaded prefix "dist#vim".
+
+The following functions are available:
+
+dist#vim#IsSafeExecutable(filetype, executable) ~
+
+This function takes a filetype and an executable and checks whether it is safe
+to execute the given executable.  For security reasons users may not want to
+have Vim execute random executables or may have forbidden to do so for
+specific filetypes by setting the "<filetype>_exec" variable (|plugin_exec|).
+
+It returns |TRUE| or |FALSE| to indicate whether the plugin should run the given
+exectuable.  It takes the following arguments:
+
+	argument	type ~
+
+	filetype	string
+	executable	string
+
+==============================================================================
 Command-line expressions highlighting		*expr-highlight*
 
 Expressions entered by the user in |i_CTRL-R_=|, |c_CTRL-\_e|, |quote=| are