vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 18343:375a7ecdb351

Update runtime files. Commit: https://github.com/vim/vim/commit/2e693a88b24dc6b12883fad78ff2cb9cd4469c98 Author: Bram Moolenaar <Bram@vim.org> Date: Wed Oct 16 22:35:02 2019 +0200 Update runtime files.

author	Bram Moolenaar <Bram@vim.org>
date	Wed, 16 Oct 2019 22:45:04 +0200
parents	03b854983b14
children	6d11fc4aa683

comparison

equal deleted inserted replaced

-:fedab77fee7b
+:375a7ecdb351
-*eval.txt*	For Vim version 8.1.  Last change: 2019 Sep 27
+*eval.txt*	For Vim version 8.1.  Last change: 2019 Oct 13
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
 win_gotoid({expr})		Number	go to window with ID {expr}
 win_id2tabwin({expr})		List	get tab and window nr from window ID
 win_id2win({expr})		Number	get window nr from window ID
 win_screenpos({nr})		List	get screen position of window {nr}
 win_splitmove({nr}, {target} [, {options}])
-				none	move window {nr} to split of {target}
+				Number	move window {nr} to split of {target}
 winbufnr({nr})			Number	buffer number of window {nr}
 wincol()			Number	window column of the cursor
 winheight({nr})			Number	height of window {nr}
 winlayout([{tabnr}])		List	layout of windows in tab {tabnr}
 winline()			Number	window line of the cursor
 			mylist->append(lnum)
 appendbufline({expr}, {lnum}, {text})			*appendbufline()*
 		Like |append()| but append the text in buffer {expr}.
+		This function works only for loaded buffers. First call
+		|bufload()| if needed.
 		For the use of {expr}, see |bufname()|.
 		{lnum} is used like with |append()|.  Note that using |line()|
 		would use the current buffer, not the one appending to.
 	  return ''
 	endfunc
 <		This isn't very useful, but it shows how it works.  Note that
 		an empty string is returned to avoid a zero being inserted.
-		Can also be used as a |method|, the second argument is passed
+		Can also be used as a |method|, the base is passed as the
-		in: >
+		second argument: >
 			GetMatches()->complete(col('.'))
 complete_add({expr})				*complete_add()*
 		Add {expr} to the list of matches.  Only to be used by the
 		function specified with the 'completefunc' option.
 		don't fit, a vertical layout is used anyway.  For some systems
 		the horizontal layout is always used.
 		Can also be used as a |method|in: >
 			BuildMessage()->confirm("&Yes\n&No")
+<
 							*copy()*
 copy({expr})	Make a copy of {expr}.  For Numbers and Strings this isn't
 		different from using {expr} directly.
 		When {expr} is a |List| a shallow copy is created.  This means
 		that the original |List| can be changed without changing the
 deletebufline({expr}, {first} [, {last}])		*deletebufline()*
 		Delete lines {first} to {last} (inclusive) from buffer {expr}.
 		If {last} is omitted then delete line {first} only.
 		On success 0 is returned, on failure 1 is returned.
+		This function works only for loaded buffers. First call
+		|bufload()| if needed.
 		For the use of {expr}, see |bufname()| above.
 		{first} and {last} are used like with |getline()|. Note that
 		when using |line()| this refers to the current buffer. Use "$"
 		to refer to the last line in buffer {expr}.
 		Can also be used as a |method|: >
 			GetBuffer()->deletebufline(1)
+<
 							*did_filetype()*
 did_filetype()	Returns |TRUE| when autocommands are being executed and the
 		FileType event has been triggered at least once.  Can be used
 		to avoid triggering the FileType event again in the scripts
 		that detect the file type. |FileType|
 <		If {expr} cannot be found in $PATH or is not executable then
 		an empty string is returned.
 		Can also be used as a |method|: >
 			GetCommand()->exepath()
+<
 							*exists()*
 exists({expr})	The result is a Number, which is |TRUE| if {expr} is defined,
 		zero otherwise.
 		For checking for a supported feature use |has()|.
 		foldlevel is unknown.  As a special case the level of the
 		previous line is usually available.
 		Can also be used as a |method|: >
 			GetLnum()->foldlevel()
+<
 							*foldtext()*
 foldtext()	Returns a String, to be displayed for a closed fold.  This is
 		the default function used for the 'foldtext' option and should
 		only be called from evaluating 'foldtext'.  It uses the
 		|v:foldstart|, |v:foldend| and |v:folddashes| variables.
 		Example: >
 			:call histadd("input", strftime("%Y %b %d"))
 			:let date=input("Enter date: ")
 <		This function is not available in the |sandbox|.
-		Can also be used as a |method|, the base is used for the
+		Can also be used as a |method|, the base is passed as the
 		second argument: >
 			GetHistory()->histadd('search')
 histdel({history} [, {item}])				*histdel()*
 		Clear {history}, i.e. delete all its entries.  See |hist-names|
 		{only in Win32 and some Unix versions, when the |+libcall|
 		feature is present}
 		Examples: >
 			:echo libcall("libc.so", "getenv", "HOME")
-<		Can also be used as a |method|, where the base is passed as
+<		Can also be used as a |method|, the base is passed as the
-		the argument to the called function: >
+		third argument: >
 			GetValue()->libcall("libc.so", "getenv")
 <
 							*libcallnr()*
 libcallnr({libname}, {funcname}, {argument})
 		Just like |libcall()|, but used for a function that returns an
 		Examples: >
 			:echo libcallnr("/usr/lib/libc.so", "getpid", "")
 			:call libcallnr("libc.so", "printf", "Hello World!\n")
 			:call libcallnr("libc.so", "sleep", 10)
 <
-		Can also be used as a |method|, where the base is passed as
+		Can also be used as a |method|, the base is passed as the
-		the argument to the called function: >
+		third argument: >
 			GetValue()->libcallnr("libc.so", "printf")
 <
 line({expr} [, {winid}])				*line()*
 		The result is a Number, which is the line number of the file
 		Use the |BufReadPost| autocmd event to handle the initial text
 		of a buffer.
 		The {callback} is also not invoked when the buffer is
 		unloaded, use the |BufUnload| autocmd event for that.
-		Can also be used as a |method|, where the base is passed as
+		Can also be used as a |method|, the base is passed as the
-		the second argument, the buffer: >
+		second argument: >
 			GetBuffer()->listener_add(callback)
 listener_flush([{buf}])					*listener_flush()*
 		Invoke listener callbacks for buffer {buf}.  If there are no
 		pending changes then no callbacks are invoked.
 <		result is ["x", 1, 2, 3].
 		The type isn't changed, it's not necessarily a String.
 		Can also be used as a |method|: >
 			GetText()->matchstrpos('word')
+<
 							*max()*
 max({expr})	Return the maximum value of all items in {expr}.
 		{expr} can be a list or a dictionary.  For a dictionary,
 		it returns the maximum of all values in the dictionary.
 		If {expr} is neither a list nor a dictionary, or one of the
 		{only available when compiled with the |+clientserver| feature}
 		Example: >
 			:echo serverlist()
 <
 setbufline({expr}, {lnum}, {text})			*setbufline()*
-		Set line {lnum} to {text} in buffer {expr}.  To insert
+		Set line {lnum} to {text} in buffer {expr}.  This works like
-		lines use |append()|.  Any text properties in {lnum} are
+		|setline()| for the specified buffer.
-		cleared.
+		This function works only for loaded buffers. First call
+		|bufload()| if needed.
+		To insert lines use |appendbufline()|.
+		Any text properties in {lnum} are cleared.
+		{text} can be a string to set one line, or a list of strings
+		to set multiple lines.  If the list extends below the last
+		line then those lines are added.
 		For the use of {expr}, see |bufname()| above.
 		{lnum} is used like with |setline()|.
-		This works like |setline()| for the specified buffer.
+		When {lnum} is just below the last line the {text} will be
+		added below the last line.
 		When {expr} is not a valid buffer, the buffer is not loaded or
 		{lnum} is not valid then 1 is returned.  On success 0 is
 		returned.
-		Can also be used as a |method|: >
+		Can also be used as a |method|, the base is passed as the
+		third argument: >
 			GetText()->setbufline(buf, lnum)
 setbufvar({expr}, {varname}, {val})			*setbufvar()*
 		Set option or local variable {varname} in buffer {expr} to
 		{val}.
 		Examples: >
 			:call setbufvar(1, "&mod", 1)
 			:call setbufvar("todo", "myvar", "foobar")
 <		This function is not available in the |sandbox|.
-		Can also be used as a |method|: >
+		Can also be used as a |method|, the base is passed as the
+		third argument: >
 			GetValue()->setbufvar(buf, varname)
 setcharsearch({dict})					*setcharsearch()*
 		Set the current character search information to {dict},
 		which contains one or more of the following entries:
 setenv({name}, {val})						*setenv()*
 		Set environment variable {name} to {val}.
 		When {val} is |v:null| the environment variable is deleted.
 		See also |expr-env|.
-		Can also be used as a |method|, passing the value as the base: >
+		Can also be used as a |method|, the base is passed as the
+		second argument: >
 			GetPath()->setenv('PATH')
 setfperm({fname}, {mode})				*setfperm()* *chmod*
 		Set the file permissions for {fname} to {mode}.
 		{mode} must be a string with 9 characters.  It is of the form
 		lines use |append()|. To set lines in another buffer use
 		|setbufline()|.  Any text properties in {lnum} are cleared.
 		{lnum} is used like with |getline()|.
 		When {lnum} is just below the last line the {text} will be
-		added as a new line.
+		added below the last line.
 		If this succeeds, 0 is returned.  If this fails (most likely
 		because {lnum} is invalid) 1 is returned.
 		Example: >
 			:  call setline(n, l)
 			:endfor
 <		Note: The '[ and '] marks are not set.
-		Can also be used as a |method|, passing the text as the base: >
+		Can also be used as a |method|, the base is passed as the
+		second argument: >
 			GetText()->setline(lnum)
 setloclist({nr}, {list} [, {action} [, {what}]])		*setloclist()*
 		Create or replace or add to the location list for window {nr}.
 		{nr} can be the window number or the |window-ID|.
 		triggered, e.g. when setting 'filetype'.
 		Note that the variable name without "t:" must be used.
 		Tabs are numbered starting with one.
 		This function is not available in the |sandbox|.
-		Can also be used as a |method|, the base is used as the value: >
+		Can also be used as a |method|, the base is passed as the
+		third argument: >
 			GetValue()->settabvar(tab, name)
 settabwinvar({tabnr}, {winnr}, {varname}, {val})	*settabwinvar()*
 		Set option or local variable {varname} in window {winnr} to
 		{val}.
 		Examples: >
 			:call settabwinvar(1, 1, "&list", 0)
 			:call settabwinvar(3, 2, "myvar", "foobar")
 <		This function is not available in the |sandbox|.
-		Can also be used as a |method|, the base is used as the value: >
+		Can also be used as a |method|, the base is passed as the
+		fourth argument: >
 			GetValue()->settabvar(tab, winnr, name)
 settagstack({nr}, {dict} [, {action}])			*settagstack()*
 		Modify the tag stack of the window {nr} using {dict}.
 		{nr} can be the window number or the |window-ID|.
 			let stack = gettagstack(1003)
 			" do something else
 			call settagstack(1003, stack)
 			unlet stack
 <
-		Can also be used as a |method|, the base is used as the Dict: >
+		Can also be used as a |method|, the base is passed as the
+		second argument: >
 			GetStack()->settagstack(winnr)
 setwinvar({winnr}, {varname}, {val})			*setwinvar()*
 		Like |settabwinvar()| for the current tab page.
 		Examples: >
 			:call setwinvar(1, "&list", 0)
 			:call setwinvar(2, "myvar", "foobar")
-<		Can also be used as a |method|, the base is used as the value: >
+<		Can also be used as a |method|, the base is passed as the
+		third argument: >
 			GetValue()->setwinvar(winnr, name)
 sha256({string})						*sha256()*
 		Returns a String with 64 hex characters, which is the SHA256
 		checksum of {string}.
 			stuffed command
 		    o	operator pending or waiting for a command argument,
 		        e.g. after |f|
 		    a	Insert mode autocomplete active
 		    x	executing an autocommand
-		    w	blocked on waiting, e.g. ch_evalexpr() and
+		    w	blocked on waiting, e.g. ch_evalexpr(), ch_read() and
-			ch_read(), ch_readraw() when reading json.
+			ch_readraw() when reading json.
 		    S	not triggering SafeState or SafeStateAgain
 		    c	callback invoked, including timer (repeats for
 			recursiveness up to "ccc")
 		    s	screen has scrolled for messages
 		quotes are ignored, thus "1'000'000" is a million.
 		When {base} is omitted base 10 is used.  This also means that
 		a leading zero doesn't cause octal conversion to be used, as
 		with the default String to Number conversion.  Example: >
-			let nr = str2nr('123')
+			let nr = str2nr('0123')
 <
 		When {base} is 16 a leading "0x" or "0X" is ignored.  With a
 		different base the result will be zero.  Similarly, when
 		{base} is 8 a leading "0" is ignored, and when {base} is 2 a
 		leading "0b" or "0B" is ignored.
 		stridx() works similar to the C function strstr().  When used
 		with a single character it works similar to strchr().
 		Can also be used as a |method|: >
 			GetHaystack()->stridx(needle)
+<
 							*string()*
 string({expr})	Return {expr} converted to a String.  If {expr} is a Number,
 		Float, String, Blob or a composition of them, then the result
 		can be parsed back with |eval()|.
 			{expr} type	result ~
 		autocommands and not actually show syntax highlighting.
 							*E994*
 		Not all commands are allowed in popup windows.
 		When window {id} does not exist then no error is given.
-		Can also be used as a |method|, the base is used for the
+		Can also be used as a |method|, the base is passed as the
-		command: >
+		second argument: >
 			GetCommand()->win_execute(winid)
 win_findbuf({bufnr})					*win_findbuf()*
 		Returns a list with |window-ID|s for windows that contain
 		buffer {bufnr}.  When there is none the list is empty.
 xor({expr}, {expr})					*xor()*
 		Bitwise XOR on the two arguments.  The arguments are converted
 		to a number.  A List, Dict or Float argument causes an error.
 		Example: >
 			:let bits = xor(bits, 0x80)
-<		Can also be used as a |method|: >
+<
+		Can also be used as a |method|: >
 			:let bits = bits->xor(0x80)
 <
 							*feature-list*
 There are four types of features:
 1.  Features that are only supported when they have been enabled when Vim
 was compiled |+feature-list|.  Example: >
 			Like above, but append/add/subtract the value for each
 			|List| item.
 						*:let=<<* *:let-heredoc*
 						*E990* *E991* *E172* *E221*
-:let {var-name} =<< [trim] {marker}
+:let {var-name} =<< [trim] {endmarker}
 text...
 text...
-{marker}
+{endmarker}
 			Set internal variable {var-name} to a List containing
-			the lines of text bounded by the string {marker}.
+			the lines of text bounded by the string {endmarker}.
-			{marker} must not contain white space.
+			{endmarker} must not contain white space.
-			{marker} cannot start with a lower case character.
+			{endmarker} cannot start with a lower case character.
-			The last line should end only with the {marker} string
+			The last line should end only with the {endmarker}
-			without any other character.  Watch out for white
+			string without any other character.  Watch out for
-			space after {marker}!
+			white space after {endmarker}!
 			Without "trim" any white space characters in the lines
 			of text are preserved.  If "trim" is specified before
-			{marker}, then indentation is stripped so you can do: >
+			{endmarker}, then indentation is stripped so you can
+			do: >
 				let text =<< trim END
 				   if ok
 				     echo 'done'
 				   endif
 				END
 			Specifically: all the leading indentation exactly
 			matching the leading indentation of the first
 			non-empty text line is stripped from the input lines.
 			All leading indentation exactly matching the leading
 			indentation before `let` is stripped from the line
-			containing {marker}.  Note that the difference between
+			containing {endmarker}.  Note that the difference
-			space and tab matters here.
+			between space and tab matters here.
 			If {var-name} didn't exist yet, it is created.
 			Cannot be followed by another command, but can be
 			followed by a comment.
+			To avoid line continuation to be applied, consider
+			adding 'C' to 'cpoptions': >
+				set cpo+=C
+				let var =<< END
+				   \ leading backslash
+				END
+				set cpo-=C
+<
 			Examples: >
 				let var1 =<< END
-			Sample text 1
+				Sample text 1
-			    Sample text 2
+				    Sample text 2
-			Sample text 3
+				Sample text 3
-			END
+				END
 				let data =<< trim DATA
-				1 2 3 4
+					1 2 3 4
-				5 6 7 8
+					5 6 7 8
 				DATA
 <
 								*E121*
 :let {var-name}	..	List the value of variable {var-name}.  Multiple
 			variable names may be given.  Special names recognized

Mercurial > vim

comparison runtime/doc/eval.txt @ 18343:375a7ecdb351