vim: runtime/doc/eval.txt comparison

comparison runtime/doc/eval.txt @ 21093:99a602b27e0e

Runtime file updates Commit: https://github.com/vim/vim/commit/e46a4405056276b4cbdacee76b11f85c8ea1830b Author: Bram Moolenaar <Bram@vim.org> Date: Tue Jun 30 20:38:27 2020 +0200 Runtime file updates

author	Bram Moolenaar <Bram@vim.org>
date	Tue, 30 Jun 2020 20:45:06 +0200
parents	59f93c2d2551
children	e67123c115d2

comparison

equal deleted inserted replaced

-:f49405905ef6
+:99a602b27e0e
-*eval.txt*	For Vim version 8.2.  Last change: 2020 Jun 17
+*eval.txt*	For Vim version 8.2.  Last change: 2020 Jun 30
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
 						*no-type-checking*
 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*
 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
 around the arguments, to invoke the function it refers to.  Example: >
 getimstatus()			Number	|TRUE| if the IME status is active
 getjumplist([{winnr} [, {tabnr}]])
 				List	list of jump list items
 getline({lnum})			String	line {lnum} of current buffer
 getline({lnum}, {end})		List	lines {lnum} to {end} of current buffer
-getloclist({nr} [, {what}])	List	list of location list items
+getloclist({nr})		List	list of location list items
+getloclist({nr}, {what})	Dict	get specific location list properties
 getmarklist([{expr}])		List	list of global/local marks
 getmatches([{win}])		List	list of current matches
 getmousepos()			Dict	last known mouse position
 getpid()			Number	process ID of Vim
 getpos({expr})			List	position of cursor, mark, etc.
-getqflist([{what}])		List	list of quickfix items
+getqflist()			List	list of quickfix items
+getqflist({what})		Dict	get specific quickfix list properties
 getreg([{regname} [, 1 [, {list}]]])
 				String or List   contents of a register
 getreginfo([{regname}])		Dict	information about a register
 getregtype([{regname}])		String	type of a register
 gettabinfo([{expr}])		List	list of tab pages
 setcharsearch({dict})		Dict	set character search from {dict}
 setcmdpos({pos})		Number	set cursor position in command-line
 setenv({name}, {val})		none	set environment variable
 setfperm({fname}, {mode})	Number	set {fname} file permissions to {mode}
 setline({lnum}, {line})		Number	set line {lnum} to {line}
-setloclist({nr}, {list} [, {action} [, {what}]])
+setloclist({nr}, {list} [, {action}])
 				Number	modify location list using {list}
+setloclist({nr}, {list}, {action}, {what})
+				Number	modify specific location list props
 setmatches({list} [, {win}])	Number	restore a list of matches
 setpos({expr}, {list})		Number	set the {expr} position to {list}
-setqflist({list} [, {action} [, {what}]])
+setqflist({list} [, {action}])	Number	modify quickfix list using {list}
-				Number	modify quickfix list using {list}
+setqflist({list}, {action}, {what})
+				Number	modify specific quickfix list props
 setreg({n}, {v} [, {opt}])	Number	set register to value and type
 settabvar({nr}, {varname}, {val}) none	set {varname} in tab page {nr} to {val}
 settabwinvar({tabnr}, {winnr}, {varname}, {val})
 				none	set {varname} in window {winnr} in tab
 					page {tabnr} to {val}
 		Only to be used by the function specified with the
 		'completefunc' option.
 							*complete_info()*
 complete_info([{what}])
-		Returns a Dictionary with information about Insert mode
+		Returns a |Dictionary| with information about Insert mode
 		completion.  See |ins-completion|.
 		The items are:
 		   mode		Current completion mode name string.
 				See |complete_info_mode| for the values.
 		   pum_visible	|TRUE| if popup menu is visible.
 		Get information about buffers as a List of Dictionaries.
 		Without an argument information about all the buffers is
 		returned.
-		When the argument is a Dictionary only the buffers matching
+		When the argument is a |Dictionary| only the buffers matching
 		the specified criteria are returned.  The following keys can
 		be specified in {dict}:
 			buflisted	include only listed buffers.
 			bufloaded	include only loaded buffers.
 			bufmodified	include only modified buffers.
 			ComputeLnum()->getline()
 <		To get lines from another buffer see |getbufline()|
 getloclist({nr} [, {what}])				*getloclist()*
-		Returns a list with all the entries in the location list for
+		Returns a |List| with all the entries in the location list for
 		window {nr}.  {nr} can be the window number or the |window-ID|.
 		When {nr} is zero the current window is used.
 		For a location list window, the displayed location list is
 		returned.  For an invalid window number {nr}, an empty list is
 					from the location list. This field is
 					applicable only when called from a
 					location list window. See
 					|location-list-file-window| for more
 					details.
+		Returns an empty Dictionary if there is no location list for
+		the window {nr} or the window is not present.
+		Examples (See also |getqflist-examples|): >
+			:echo getloclist(3, {'all': 0})
+			:echo getloclist(5, {'filewinid': 0})
 getmarklist([{expr}]					*getmarklist()*
 		Without the {expr} argument returns a |List| with information
 		about all the global marks. |mark|
 			'priority': 10, 'id': 1}, {'group': 'MyGroup2',
 			'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
 			:unlet m
 <
 getmousepos()						*getmousepos()*
-		Returns a Dictionary with the last known position of the
+		Returns a |Dictionary| with the last known position of the
 		mouse.  This can be used in a mapping for a mouse click or in
 		a filter of a popup window.  The items are:
 			screenrow	screen row
 			screencol	screen column
 			winid		Window ID of the click
 		Can also be used as a |method|: >
 			GetRegname()->getregtype()
 gettabinfo([{arg}])					*gettabinfo()*
 		If {arg} is not specified, then information about all the tab
-		pages is returned as a List. Each List item is a Dictionary.
+		pages is returned as a |List|. Each List item is a |Dictionary|.
 		Otherwise, {arg} specifies the tab page number and information
 		about that one is returned.  If the tab page does not exist an
 		empty List is returned.
-		Each List item is a Dictionary with the following entries:
+		Each List item is a |Dictionary| with the following entries:
 			tabnr		tab page number.
 			variables	a reference to the dictionary with
 					tabpage-local variables
 			windows		List of |window-ID|s in the tab page.
 		Get the value of window-local variable {varname} in window
 		{winnr} in tab page {tabnr}.
 		When {varname} is empty a dictionary with all window-local
 		variables is returned.
 		When {varname} is equal to "&" get the values of all
-		window-local options in a Dictionary.
+		window-local options in a |Dictionary|.
 		Otherwise, when {varname} starts with "&" get the value of a
 		window-local option.
 		Note that {varname} must be the name without "w:".
 		Tabs are numbered starting with one.  For the current tabpage
 		use |getwinvar()|.
 		Can also be used as a |method|: >
 			GetWinnr()->gettagstack()
 getwininfo([{winid}])					*getwininfo()*
-		Returns information about windows as a List with Dictionaries.
+		Returns information about windows as a |List| with Dictionaries.
 		If {winid} is given Information about the window with that ID
-		is returned, as a List with one item.  If the window does not
+		is returned, as a |List| with one item.  If the window does not
 		exist the result is an empty list.
 		Without {winid} information about all the windows in all the
 		tab pages is returned.
-		Each List item is a Dictionary with the following entries:
+		Each List item is a |Dictionary| with the following entries:
 			botline		last displayed buffer line
 			bufnr		number of buffer in the window
 			height		window height (excluding winbar)
 			loclist		1 if showing a location list
 					{only with the +quickfix feature}
 		Can also be used as a |method|: >
 			GetWinnr()->getwininfo()
 getwinpos([{timeout}])					*getwinpos()*
-		The result is a List with two numbers, the result of
+		The result is a |List| with two numbers, the result of
 		|getwinposx()| and |getwinposy()| combined:
 			[x-pos, y-pos]
 		{timeout} can be used to specify how long to wait in msec for
 		a response from the terminal.  When omitted 100 msec is used.
 		Use a longer time for a remote terminal.
 		the 'suffixes' and 'wildignore' options apply: Names matching
 		one of the patterns in 'wildignore' will be skipped and
 		'suffixes' affect the ordering of matches.
 		'wildignorecase' always applies.
-		When {list} is present and it is |TRUE| the result is a List
+		When {list} is present and it is |TRUE| the result is a |List|
 		with all matching files. The advantage of using a List is,
 		you also get filenames containing newlines correctly.
 		Otherwise the result is a String and when there are several
 		matches, they are separated by <NL> characters.
 		Unless the optional {nosuf} argument is given and is |TRUE|,
 		the 'suffixes' and 'wildignore' options apply: Names matching
 		one of the patterns in 'wildignore' will be skipped and
 		'suffixes' affect the ordering of matches.
-		When {list} is present and it is |TRUE| the result is a List
+		When {list} is present and it is |TRUE| the result is a |List|
 		with all matching files. The advantage of using a List is, you
 		also get filenames containing newlines correctly. Otherwise
 		the result is a String and when there are several matches,
 		they are separated by <NL> characters.  Example: >
 			:echo globpath(&rtp, "syntax/c.vim", 0, 1)
 			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,
+		{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
 		items in {expr} cannot be used as a Number this results in
 		an error.  An empty |List| or |Dictionary| results in zero.
 			GetMenuName()->menu_info('v')
 <							*min()*
 min({expr})	Return the minimum value of all items in {expr}.
-		{expr} can be a List or a Dictionary.  For a Dictionary,
+		{expr} can be a |List| or a |Dictionary|.  For a Dictionary,
 		it returns the minimum of all values in the Dictionary.
 		If {expr} is neither a List nor a Dictionary, or one of the
 		items in {expr} cannot be used as a Number this results in
 		an error.  An empty |List| or |Dictionary| results in zero.
 			If {expr} results in 0 then this entry will not be
 			added to the list.
 			If {expr} results in 1 then this entry will be added
 			to the list.
 		The entries "." and ".." are always excluded.
-		Each time {expr} is evaluated |v:val| is set to a Dictionary
+		Each time {expr} is evaluated |v:val| is set to a |Dictionary|
 		of the entry.
 		When {expr} is a function the entry is passed as the argument.
 		For example, to get a list of files ending in ".txt": >
 		  readdirex(dirname, {e -> e.name =~ '.txt$'})
 <
 remove({list}, {idx} [, {end}])				*remove()*
 		Without {end}: Remove the item at {idx} from |List| {list} and
 		return the item.
 		With {end}: Remove items from {idx} to {end} (inclusive) and
-		return a List with these items.  When {idx} points to the same
+		return a |List| with these items.  When {idx} points to the same
 		item as {end} a list with one item is returned.  When {end}
 		points to an item before {idx} this is an error.
 		See |list-index| for possible values of {idx} and {end}.
 		Example: >
 			:echo "last item: " . remove(mylist, -1)
 		Can also be used as a |method|: >
 			GetRow()->screenchar(col)
 screenchars({row}, {col})					*screenchars()*
-		The result is a List of Numbers.  The first number is the same
+		The result is a |List| of Numbers.  The first number is the same
 		as what |screenchar()| returns.  Further numbers are
 		composing characters on top of the base character.
 		This is mainly to be used for testing.
 		Returns an empty List when row or col is out of range.
 searchcount([{options}])					*searchcount()*
 		Get or update the last search count, like what is displayed
 		without the "S" flag in 'shortmess'.  This works even if
 		'shortmess' does contain the "S" flag.
-		This returns a Dictionary. The dictionary is empty if the
+		This returns a |Dictionary|. The dictionary is empty if the
 		previous pattern was not set and "pattern" was not specified.
 		  key		type		meaning ~
 		  current	|Number|	current position of match;
 						0 if the cursor position is
 			" To restore old search count by old pattern,
 			" search again
 			call searchcount()
 <
-		{options} must be a Dictionary. It can contain:
+		{options} must be a |Dictionary|. It can contain:
 		  key		type		meaning ~
 		  recompute	|Boolean|	if |TRUE|, recompute the count
 						like |n| or |N| was executed.
 						otherwise returns the last
 						computed result (when |n| or
 <
 							*setreg()*
 setreg({regname}, {value} [, {options}])
 		Set the register {regname} to {value}.
 		If {regname} is "" or "@", the unnamed register '"' is used.
 		{value} may be any value returned by |getreg()| or
 		|getreginfo()|, including a |List| or |Dict|.
 		If {options} contains "a" or {regname} is upper case,
 		then the value is appended.
 		{options} can also contain a register type specification:
 		    "c" or "v"	      |characterwise| mode
 		    "l" or "V"	      |linewise| mode
 		    "b" or "<CTRL-V>" |blockwise-visual| mode
 		If a number immediately follows "b" or "<CTRL-V>" then this is
 <		This example shows using the functions to save and restore a
 		register: >
 			:let var_a = getreginfo()
 			:call setreg('a', var_a)
-<		or:
+<		or: >
 			:let var_a = getreg('a', 1, 1)
 			:let var_amode = getregtype('a')
 			    ....
 			:call setreg('a', var_a, var_amode)
 <		Note: you may not reliably restore register value
 <
 		These characters indicate the state, generally indicating that
 		something is busy:
 		    m	halfway a mapping, :normal command, feedkeys() or
 			stuffed command
-		    o	operator pending or waiting for a command argument,
+		    o	operator pending, e.g. after |d|
-			e.g. after |f|
 		    a	Insert mode autocomplete active
 		    x	executing an autocommand
 		    w	blocked on waiting, e.g. ch_evalexpr(), ch_read() and
-			ch_readraw() when reading json.
+			ch_readraw() when reading json
-		    S	not triggering SafeState or SafeStateAgain
+		    S	not triggering SafeState or SafeStateAgain, e.g. after
+		    	|f| or a count
 		    c	callback invoked, including timer (repeats for
 			recursiveness up to "ccc")
 		    s	screen has scrolled for messages
 str2float({expr})					*str2float()*
 			Funcref		function('name')
 			Blob		0z00112233.44556677.8899
 			List		[item, item]
 			Dictionary	{key: value, key: value}
-		When a List or Dictionary has a recursive reference it is
+		When a |List| or |Dictionary| has a recursive reference it is
 		replaced by "[...]" or "{...}".  Using eval() on the result
 		will then fail.
 		Can also be used as a |method|: >
 			mylist->string()
 		Can also be used as a |method|: >
 	:echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg")
 synconcealed({lnum}, {col})				*synconcealed()*
-		The result is a List with currently three items:
+		The result is a |List| with currently three items:
 		1. The first item in the list is 0 if the character at the
 		   position {lnum} and {col} is not part of a concealable
 		   region, 1 if it is.
 		2. The second item in the list is a string. If the first item
 		   is 1, the second item contains the text which will be
 		character in a line and the first column in an empty line are
 		valid positions.
 system({expr} [, {input}])				*system()* *E677*
 		Get the output of the shell command {expr} as a string.  See
-		|systemlist()| to get the output as a List.
+		|systemlist()| to get the output as a |List|.
 		When {input} is given and is a string this string is written
 		to a file and passed as stdin to the command.  The string is
 		written as-is, you need to take care of using the correct line
 		separators yourself.
 		When {id} is given only information about this timer is
 		returned.  When timer {id} does not exist an empty list is
 		returned.
 		When {id} is omitted information about all timers is returned.
-		For each timer the information is stored in a Dictionary with
+		For each timer the information is stored in a |Dictionary| with
 		these items:
 		    "id"	    the timer ID
 		    "time"	    time the timer was started with
 		    "remaining"	    time until the timer fires
 		    "repeat"	    number of times the timer will still fire;
 				user.  See |undo-blocks|.
 		  "entries"	A list of dictionaries with information about
 				undo blocks.
 		The first item in the "entries" list is the oldest undo item.
-		Each List item is a Dictionary with these items:
+		Each List item is a |Dictionary| with these items:
 		  "seq"		Undo sequence number.  Same as what appears in
 				|:undolist|.
 		  "time"	Timestamp when the change happened.  Use
 				|strftime()| to convert to something readable.
 		  "newhead"	Only appears in the item that is the last one
 		Both {nr} and {target} can be window numbers or |window-ID|s.
 		Both must be in the current tab page.
 		Returns zero for success, non-zero for failure.
-		{options} is a Dictionary with the following optional entries:
+		{options} is a |Dictionary| with the following optional entries:
 		  "vertical"	When TRUE, the split is created vertically,
 				like with |:vsplit|.
 		  "rightbelow"	When TRUE, the split is made below or to the
 				right (if vertical).  When FALSE, it is done
 				above or to the left (if vertical).  When not
 						*E990* *E991* *E172* *E221*
 :let {var-name} =<< [trim] {endmarker}
 text...
 text...
 {endmarker}
-			Set internal variable {var-name} to a List containing
+			Set internal variable {var-name} to a |List|
-			the lines of text bounded by the string {endmarker}.
+			containing the lines of text bounded by the string
+			{endmarker}.
 			{endmarker} must not contain white space.
 			{endmarker} cannot start with a lower case character.
 			The last line should end only with the {endmarker}
 			string without any other character.  Watch out for
 			white space after {endmarker}!

Mercurial > vim

comparison runtime/doc/eval.txt @ 21093:99a602b27e0e