diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 6057b57c6..ff21486e5 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2511,13 +2511,15 @@ 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 @@ -2756,12 +2758,17 @@ 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 + properties using {what} setmatches({list} [, {win}]) Number restore a list of matches setpos({expr}, {list}) Number set the {expr} position to {list} -setqflist({list} [, {action} [, {what}]]) - Number modify quickfix list using {list} +setqflist({list} [, {action}]) Number modify quickfix list using {list} +setqflist({list}, {action}, {what}) + Number modify specific quickfix list + properties using {what} 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}) @@ -3635,7 +3642,7 @@ complete_check() *complete_check()* *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. @@ -5392,8 +5399,8 @@ getline({lnum} [, {end}]) < To get lines from another buffer see |getbufline()| -getloclist({nr} [, {what}]) *getloclist()* - Returns a list with all the entries in the location list for +getloclist({nr}) *getloclist()* + 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. @@ -5401,9 +5408,13 @@ getloclist({nr} [, {what}]) *getloclist()* returned. For an invalid window number {nr}, an empty list is returned. Otherwise, same as |getqflist()|. - If the optional {what} dictionary argument is supplied, then - returns the items listed in {what} as a dictionary. Refer to - |getqflist()| for the supported items in {what}. + Returns an empty list if there is no location list or the list + is empty for the window {nr} or the window is not present. + +getloclist({nr}, {what}) + Returns a |Dictionary| with the the location list properties + specified in the Dict argument {what} for window {nr} . Refer + to |getqflist()| for the supported items in {what}. In addition to the items supported by |getqflist()| in {what}, the following item is supported by |getloclist()|: @@ -5415,6 +5426,13 @@ getloclist({nr} [, {what}]) *getloclist()* |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| @@ -5459,7 +5477,7 @@ getmatches([{win}]) *getmatches()* :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 @@ -5518,9 +5536,8 @@ getpos({expr}) Get the position for {expr}. For possible values of {expr} Can also be used as a |method|: > GetMark()->getpos() - -getqflist([{what}]) *getqflist()* - Returns a list with all the current quickfix errors. Each +getqflist() *getqflist()* + Returns a |List| with all the current quickfix errors. Each list item is a dictionary with these entries: bufnr number of buffer that has the file name, use bufname() to get the name @@ -5545,10 +5562,10 @@ getqflist([{what}]) *getqflist()* :for d in getqflist() : echo bufname(d.bufnr) ':' d.lnum '=' d.text :endfor -< - If the optional {what} dictionary argument is supplied, then - returns only the items listed in {what} as a dictionary. The - following string items are supported in {what}: +getqflist({what}) + Returns a |Dictionary| with the quickfix list properties + specified in the Dict argument {what}. + The following string items are supported in {what}: changedtick get the total number of changes made to the list |quickfix-changedtick| context get the |quickfix-context| @@ -5610,8 +5627,8 @@ getqflist([{what}]) *getqflist()* winid quickfix |window-ID|. If not present, set to 0 Examples (See also |getqflist-examples|): > - :echo getqflist({'all': 1}) - :echo getqflist({'nr': 2, 'title': 1}) + :echo getqflist({'all': 0}) + :echo getqflist({'nr': 2, 'title': 0}) :echo getqflist({'lines' : ["F1:10:L10"]}) < getreg([{regname} [, 1 [, {list}]]]) *getreg()* @@ -5736,7 +5753,7 @@ gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* GetTabnr()->gettabwinvar(winnr, varname) gettagstack([{nr}]) *gettagstack()* - The result is a Dict, which is the tag stack of window {nr}. + Returns a |Dictionary| with the tag stack of window {nr}. {nr} can be the window number or the |window-ID|. When {nr} is not specified, the current window is used. When window {nr} doesn't exist, an empty Dict is returned. @@ -6930,7 +6947,7 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* When {abbr} is there and it is |TRUE| use abbreviations instead of mappings. - When {dict} is there and it is |TRUE| return a dictionary + When {dict} is there and it is |TRUE| returns a dictionary containing all the information of the mapping with the following items: "lhs" The {lhs} of the mapping as it would be typed @@ -8989,24 +9006,32 @@ setline({lnum}, {text}) *setline()* second argument: > GetText()->setline(lnum) -setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()* +setloclist({nr}, {list} [, {action}]) *setloclist()* Create or replace or add to 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 modified. For an invalid window number {nr}, -1 is returned. - Otherwise, same as |setqflist()|. - Also see |location-list|. + Otherwise, same as |setqflist()|. Also see |location-list|. - If the optional {what} dictionary argument is supplied, then - only the items listed in {what} are set. Refer to |setqflist()| - for the list of supported keys in {what}. + Returns zero for success, -1 for failure. Can also be used as a |method|, the base is passed as the second argument: > GetLoclist()->setloclist(winnr) +setloclist({nr}, {list}, {action}, {what}) + Create or replace or add to the location list using the items + in the {what} Dict argument for window {nr}. The second {list} + argument is ignored. + + Only the location list properties listed in {what} are set. + Refer to |setqflist()| for the supported values in {action} + and the list of supported keys in {what}. + + Returns zero for success, -1 for failure. + setmatches({list} [, {win}]) *setmatches()* Restores a list of matches saved by |getmatches()| for the current window. Returns 0 if successful, otherwise -1. All @@ -9070,18 +9095,13 @@ setpos({expr}, {list}) Can also be used as a |method|: > GetPosition()->setpos('.') -setqflist({list} [, {action} [, {what}]]) *setqflist()* - Create or replace or add to the quickfix list. - - If the optional {what} dictionary argument is supplied, then - only the items listed in {what} are set. The first {list} - argument is ignored. See below for the supported items in - {what}. +setqflist({list} [, {action}]) *setqflist()* + Create or replace or add to the quickfix list using the items + in {list}. - When {what} is not present, the items in {list} or used. Each - item must be a dictionary. Non-dictionary items in {list} are - ignored. Each dictionary item can contain the following - entries: + Each item in {list} must be a dictionary. Non-dictionary + items in {list} are ignored. Each dictionary item can contain + the following entries: bufnr buffer number; must be the number of a valid buffer @@ -9130,8 +9150,24 @@ setqflist({list} [, {action} [, {what}]]) *setqflist()* If {action} is not present or is set to ' ', then a new list is created. The new quickfix list is added after the current quickfix list in the stack and all the following lists are - freed. To add a new quickfix list at the end of the stack, - set "nr" in {what} to "$". + freed. + + Returns zero for success, -1 for failure. + + This function can be used to create a quickfix list + independent of the 'errorformat' setting. Use a command like + `:cc 1` to jump to the first position. + + Can also be used as a |method|, the base is passed as the + second argument: > + GetErrorlist()->setqflist() + +setqflist({list}, {action}, {what}) + Create or modify or add to the quickfix list using the items + in the {what} Dict argument. The first {list} argument is + ignored. + + The supported values for {action} are described above. The following items can be specified in dictionary {what}: context quickfix list context. See |quickfix-context| @@ -9145,7 +9181,7 @@ setqflist({list} [, {action} [, {what}]]) *setqflist()* then the last entry in the list is set as the current entry. See |quickfix-index| items list of quickfix entries. Same as the {list} - argument. + argument described above. lines use 'errorformat' to parse a list of lines and add the resulting entries to the quickfix list {nr} or {id}. Only a |List| value is supported. @@ -9160,27 +9196,20 @@ setqflist({list} [, {action} [, {what}]]) *setqflist()* of how to write the function and an example. title quickfix list title text. See |quickfix-title| Unsupported keys in {what} are ignored. - If the "nr" item is not present, then the current quickfix list - is modified. When creating a new quickfix list, "nr" can be - set to a value one greater than the quickfix stack size. - When modifying a quickfix list, to guarantee that the correct - list is modified, "id" should be used instead of "nr" to - specify the list. + If the "nr" item is not present, then the current quickfix + list is modified. When creating a new quickfix list, "nr" can + be set to a value one greater than the quickfix stack size. + To add a new quickfix list at the end of the stack, set "nr" + in {what} to "$". When modifying a quickfix list, to + guarantee that the correct list is modified, "id" should be + used instead of "nr" to specify the list. + + Returns zero for success, -1 for failure. Examples (See also |setqflist-examples|): > :call setqflist([], 'r', {'title': 'My search'}) :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'}) :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]}) -< - Returns zero for success, -1 for failure. - - This function can be used to create a quickfix list - independent of the 'errorformat' setting. Use a command like - `:cc 1` to jump to the first position. - - Can also be used as a |method|, the base is passed as the - second argument: > - GetErrorlist()->setqflist() < *setreg()* setreg({regname}, {value} [, {options}]) @@ -10346,7 +10375,7 @@ tagfiles() Returns a |List| with the file names used to search for tags taglist({expr} [, {filename}]) *taglist()* - Returns a list of tags matching the regular expression {expr}. + Returns a |List| of tags matching the regular expression {expr}. If {filename} is passed it is used to prioritize the results in the same way that |:tselect| does. See |tag-priority|. @@ -10438,7 +10467,7 @@ term_ functions are documented here: |terminal-function-details| terminalprops() *terminalprops()* - Returns a dictionary with properties of the terminal that Vim + Returns a |Dictionary| with properties of the terminal that Vim detected from the response to |t_RV| request. See |v:termresponse| for the response itself. If |v:termresponse| is empty most values here will be 'u' for unknown. @@ -10845,7 +10874,7 @@ win_execute({id}, {command} [, {silent}]) *win_execute()* GetCommand()->win_execute(winid) win_findbuf({bufnr}) *win_findbuf()* - Returns a list with |window-ID|s for windows that contain + Returns a |List| with |window-ID|s for windows that contain buffer {bufnr}. When there is none the list is empty. Can also be used as a |method|: >