From f2e1c7dab70ab00084ffa2bb4b42396cb79fcde3 Mon Sep 17 00:00:00 2001 From: Tsuyoshi CHO Date: Sat, 6 Jun 2020 15:12:36 +0900 Subject: [PATCH 1/7] eval.txt: Update 8.2.0910 version help --- en/eval.txt | 577 +++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 484 insertions(+), 93 deletions(-) diff --git a/en/eval.txt b/en/eval.txt index 62a73048b..99b17a16b 100644 --- a/en/eval.txt +++ b/en/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 8.2. Last change: 2020 Feb 14 +*eval.txt* For Vim version 8.2. Last change: 2020 Jun 03 VIM REFERENCE MANUAL by Bram Moolenaar @@ -48,8 +48,7 @@ There are ten types of variables: *Number* *Integer* Number A 32 or 64 bit signed number. |expr-number| - 64-bit Numbers are available only when compiled with the - |+num64| feature. + The number of bits is available in |v:numbersize|. Examples: -123 0x10 0177 0b1011 Float A floating point number. |floating-point-format| *Float* @@ -96,15 +95,17 @@ the Number. Examples: Number -1 --> String "-1" ~ *octal* Conversion from a String to a Number is done by converting the first digits to -a number. Hexadecimal "0xf9", Octal "017", and Binary "0b10" numbers are -recognized (NOTE: when using |scriptversion-4| octal is not recognized). If -the String doesn't start with digits, the result is zero. +a number. Hexadecimal "0xf9", Octal "017" or "0o17", and Binary "0b10" +numbers are recognized (NOTE: when using |scriptversion-4| octal with a +leading "0" is not recognized). If the String doesn't start with digits, the +result is zero. Examples: String "456" --> Number 456 ~ String "6bar" --> Number 6 ~ String "foo" --> Number 0 ~ String "0xf1" --> Number 241 ~ String "0100" --> Number 64 ~ + String "0o100" --> Number 64 ~ String "0b101" --> Number 5 ~ String "-8" --> Number -8 ~ String "+8" --> Number 0 ~ @@ -585,6 +586,8 @@ adict. Weeding out entries from a Dictionary can be done with |filter()|: > :call filter(dict, 'v:val =~ "x"') This removes all entries from "dict" with a value not matching 'x'. +This can also be used to remove all entries: > + call filter(dict, 0) Dictionary function ~ @@ -1263,7 +1266,7 @@ number number constant *expr-number* *hex-number* *octal-number* *binary-number* Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B) -and Octal (starting with 0). +and Octal (starting with 0, 0o or 0O). *floating-point-format* Floating point numbers can be written in two forms: @@ -1352,6 +1355,9 @@ A string constant accepts these special characters: To use the double quote character it must be escaped: "". Don't use to get a utf-8 character, use \uxxxx as mentioned above. +\<*xxx> Like \ but prepends a modifier instead of including it in the + character. E.g. "\" is one character 0x17 while "\<*C-w>" is four + bytes: 3 for the CTRL modifier and then character "W". Note that "\xff" is stored as the byte 255, which may be invalid in some encodings. Use "\u00ff" to store character 255 according to the current value @@ -1486,7 +1492,7 @@ the function returns: > :echo Bar(6) < 5 -Note that the variables must exist in the outer scope before the lamba is +Note that the variables must exist in the outer scope before the lambda is defined for this to work. See also |:func-closure|. Lambda and closure support can be checked with: > @@ -1810,10 +1816,12 @@ v:errors Errors found by assert functions, such as |assert_true()|. v:event Dictionary containing information about the current |autocommand|. See the specific event for what it puts in this dictionary. - The dictionary is emptied when the |autocommand| - finishes, please refer to |dict-identity| for how to get an - independent copy of it. - + The dictionary is emptied when the |autocommand| finishes, + please refer to |dict-identity| for how to get an independent + copy of it. Use |deepcopy()| if you want to keep the + information after the event triggers. Example: > + au TextYankPost * let g:foo = deepcopy(v:event) +< *v:exception* *exception-variable* v:exception The value of the exception most recently caught and not finished. See also |v:throwpoint| and |throw-variables|. @@ -1991,6 +1999,10 @@ v:null An empty String. Used to put "null" in JSON. See That is so that eval() can parse the string back to the same value. Read-only. + *v:numbersize* *numbersize-variable* +v:numbersize Number of bits in a Number. This is normally 64, but on some + systems it may be 32. + *v:oldfiles* *oldfiles-variable* v:oldfiles List of file names that is loaded from the |viminfo| file on startup. These are the files that Vim remembers marks for. @@ -2312,11 +2324,12 @@ argidx() Number current index in the argument list arglistid([{winnr} [, {tabnr}]]) Number argument list id argv({nr} [, {winid}]) String {nr} entry of the argument list argv([-1, {winid}]) List the argument list +asin({expr}) Float arc sine of {expr} assert_beeps({cmd}) Number assert {cmd} causes a beep assert_equal({exp}, {act} [, {msg}]) Number assert {exp} is equal to {act} -assert_equalfile({fname-one}, {fname-two}) - Number assert file contents is equal +assert_equalfile({fname-one}, {fname-two} [, {msg}]) + Number assert file contents are equal assert_exception({error} [, {msg}]) Number assert {error} is in v:exception assert_fails({cmd} [, {error} [, {msg}]]) @@ -2333,7 +2346,6 @@ assert_notmatch({pat}, {text} [, {msg}]) Number assert {pat} not matches {text} assert_report({msg}) Number report a test failure assert_true({actual} [, {msg}]) Number assert {actual} is true -asin({expr}) Float arc sine of {expr} atan({expr}) Float arc tangent of {expr} atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2} balloon_gettext() String current text in the balloon @@ -2424,12 +2436,12 @@ executable({expr}) Number 1 if executable {expr} exists execute({command}) String execute {command} and get the output exepath({expr}) String full path of the command {expr} exists({expr}) Number |TRUE| if {expr} exists -extend({expr1}, {expr2} [, {expr3}]) - List/Dict insert items of {expr2} into {expr1} exp({expr}) Float exponential of {expr} expand({expr} [, {nosuf} [, {list}]]) any expand special keywords in {expr} expandcmd({expr}) String expand {expr} like with `:edit` +extend({expr1}, {expr2} [, {expr3}]) + List/Dict insert items of {expr2} into {expr1} feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer filereadable({file}) Number |TRUE| if {file} is a readable file filewritable({file}) Number |TRUE| if {file} is a writable file @@ -2487,6 +2499,7 @@ getjumplist([{winnr} [, {tabnr}]]) 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 +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 @@ -2512,7 +2525,7 @@ glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) glob2regpat({expr}) String convert a glob pat into a search pat globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) String do glob({expr}) for all dirs in {path} -has({feature}) Number |TRUE| if feature {feature} supported +has({feature} [, {check}]) Number |TRUE| if feature {feature} supported has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key} haslocaldir([{winnr} [, {tabnr}]]) Number |TRUE| if the window executed |:lcd| @@ -2523,8 +2536,8 @@ histadd({history}, {item}) Number add an item to a history histdel({history} [, {item}]) Number remove an item from a history histget({history} [, {index}]) String get the item {index} from a history histnr({history}) Number highest index of a history -hlexists({name}) Number |TRUE| if highlight group {name} exists hlID({name}) Number syntax ID of highlight group {name} +hlexists({name}) Number |TRUE| if highlight group {name} exists hostname() String name of the machine Vim is running on iconv({expr}, {from}, {to}) String convert encoding of {expr} indent({lnum}) Number indent of line {lnum} @@ -2581,6 +2594,8 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) rhs of mapping {name} in mode {mode} mapcheck({name} [, {mode} [, {abbr}]]) String check for mappings matching {name} +mapset({mode}, {abbr}, {dict}) + none restore mapping from |maparg()| result match({expr}, {pat} [, {start} [, {count}]]) Number position where {pat} matches in {expr} matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) @@ -2598,6 +2613,7 @@ matchstr({expr}, {pat} [, {start} [, {count}]]) matchstrpos({expr}, {pat} [, {start} [, {count}]]) List {count}'th match of {pat} in {expr} max({expr}) Number maximum value of items in {expr} +menu_info({name} [, {mode}]) Dict get menu item information min({expr}) Number minimum value of items in {expr} mkdir({name} [, {path} [, {prot}]]) Number create directory {name} @@ -2621,14 +2637,16 @@ popup_findpreview() Number get window ID of preview popup window popup_getoptions({id}) Dict get options of popup window {id} popup_getpos({id}) Dict get position of popup window {id} popup_hide({id}) none hide popup menu {id} +popup_list() List get a list of window IDs of all popups +popup_locate({row}, {col}) Number get window ID of popup at position popup_menu({what}, {options}) Number create a popup window used as a menu popup_move({id}, {options}) none set position of popup window {id} popup_notification({what}, {options}) Number create a notification popup window -popup_show({id}) none unhide popup window {id} popup_setoptions({id}, {options}) none set options for popup window {id} popup_settext({id}, {text}) none set the text of popup window {id} +popup_show({id}) none unhide popup window {id} pow({x}, {y}) Float {x} to the power of {y} prevnonblank({lnum}) Number line nr of non-blank line <= {lnum} printf({fmt}, {expr1}...) String format text @@ -2640,7 +2658,7 @@ prop_clear({lnum} [, {lnum-end} [, {props}]]) none remove all text properties prop_find({props} [, {direction}]) Dict search for a text property -prop_list({lnum} [, {props}) List text properties in {lnum} +prop_list({lnum} [, {props}]) List text properties in {lnum} prop_remove({props} [, {lnum} [, {lnum-end}]]) Number remove a text property prop_type_add({name}, {props}) none define a new property type @@ -2648,20 +2666,23 @@ prop_type_change({name}, {props}) none change an existing property type prop_type_delete({name} [, {props}]) none delete a property type -prop_type_get([{name} [, {props}]) +prop_type_get([{name} [, {props}]]) Dict get property type values prop_type_list([{props}]) List get list of property types pum_getpos() Dict position and size of pum if visible pumvisible() Number whether popup menu is visible -pyeval({expr}) any evaluate |Python| expression py3eval({expr}) any evaluate |python3| expression +pyeval({expr}) any evaluate |Python| expression pyxeval({expr}) any evaluate |python_x| expression rand([{expr}]) Number get pseudo-random number range({expr} [, {max} [, {stride}]]) List items from {expr} to {max} readdir({dir} [, {expr}]) List file names in {dir} selected by {expr} +readdirex({dir} [, {expr}]) List file info in {dir} selected by {expr} readfile({fname} [, {type} [, {max}]]) List get list of lines from file {fname} +reduce({object}, {func} [, {initial}]) + any reduce {object} using {func} reg_executing() String get the executing register name reg_recording() String get the recording register name reltime([{start} [, {end}]]) List get time value @@ -2697,6 +2718,7 @@ screenrow() Number current cursor row screenstring({row}, {col}) String characters at screen position search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) Number search for {pattern} +searchcount([{options}]) Dict get or update search stats searchdecl({name} [, {global} [, {thisblock}]]) Number search for variable declaration searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) @@ -2777,9 +2799,9 @@ str2list({expr} [, {utf8}]) List convert each character of {expr} to ASCII/UTF8 value str2nr({expr} [, {base} [, {quoted}]]) Number convert String to Number -strchars({expr} [, {skipcc}]) Number character length of the String {expr} strcharpart({str}, {start} [, {len}]) String {len} characters of {str} at {start} +strchars({expr} [, {skipcc}]) Number character length of the String {expr} strdisplaywidth({expr} [, {col}]) Number display length of the String {expr} strftime({format} [, {time}]) String format time with a specified format strgetchar({str}, {index}) Number get char {index} from {str} @@ -2812,8 +2834,8 @@ systemlist({expr} [, {input}]) List output of shell command/filter {expr} tabpagebuflist([{arg}]) List list of buffer numbers in tab page tabpagenr([{arg}]) Number number of current or last tab page tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page -taglist({expr} [, {filename}]) List list of tags matching {expr} tagfiles() List tags files used +taglist({expr} [, {filename}]) List list of tags matching {expr} tan({expr}) Float tangent of {expr} tanh({expr}) Float hyperbolic tangent of {expr} tempname() String name for a temporary file @@ -2837,9 +2859,9 @@ term_gettty({buf}, [{input}]) String get the tty name of a terminal term_list() List get the list of terminal buffers term_scrape({buf}, {row}) List get row of a terminal screen term_sendkeys({buf}, {keys}) none send keystrokes to a terminal -term_setapi({buf}, {expr}) none set |terminal-api| function name prefix term_setansicolors({buf}, {colors}) none set ANSI palette in GUI color mode +term_setapi({buf}, {expr}) none set |terminal-api| function name prefix term_setkill({buf}, {how}) none set signal to stop job in terminal term_setrestore({buf}, {command}) none set command to restore terminal term_setsize({buf}, {rows}, {cols}) @@ -2857,6 +2879,7 @@ test_ignore_error({expr}) none ignore a specific error test_null_blob() Blob null value for testing test_null_channel() Channel null value for testing test_null_dict() Dict null value for testing +test_null_function() Funcref null value for testing test_null_job() Job null value for testing test_null_list() List null value for testing test_null_partial() Funcref null value for testing @@ -2867,8 +2890,10 @@ test_refcount({expr}) Number get the reference count of {expr} test_scrollbar({which}, {value}, {dragging}) none scroll in the GUI for testing test_setmouse({row}, {col}) none set the mouse position for testing -test_srand_seed([seed]) none set seed for testing srand() test_settime({expr}) none set current time for testing +test_srand_seed([seed]) none set seed for testing srand() +test_unknown() any unknown value for testing +test_void() any void value for testing timer_info([{id}]) List information about timers timer_pause({id}, {pause}) none pause or unpause a timer timer_start({time}, {callback} [, {options}]) @@ -2879,7 +2904,8 @@ tolower({expr}) String the String {expr} switched to lowercase toupper({expr}) String the String {expr} switched to uppercase tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr} to chars in {tostr} -trim({text} [, {mask}]) String trim characters in {mask} from {text} +trim({text} [, {mask} [, {dir}]]) + String trim characters in {mask} from {text} trunc({expr}) Float truncate Float {expr} type({name}) Number type of variable {name} undofile({name}) String undo file name for {name} @@ -2894,15 +2920,16 @@ win_execute({id}, {command} [, {silent}]) String execute {command} in window {id} win_findbuf({bufnr}) List find windows containing {bufnr} win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab} +win_gettype([{nr}]) String type of window {nr} 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}]) Number move window {nr} to split of {target} -win_type([{nr}]) String type of window {nr} winbufnr({nr}) Number buffer number of window {nr} wincol() Number window column of the cursor +windowsversion() String MS-Windows OS version winheight({nr}) Number height of window {nr} winlayout([{tabnr}]) List layout of windows in tab {tabnr} winline() Number window line of the cursor @@ -3041,7 +3068,7 @@ arglistid([{winnr} [, {tabnr}]]) {winnr} can be the window number or the |window-ID|. *argv()* -argv([{nr} [, {winid}]) +argv([{nr} [, {winid}]]) The result is the {nr}th file in the argument list. See |arglist|. "argv(0)" is the first one. Example: > :let i = 0 @@ -4018,7 +4045,7 @@ executable({expr}) *executable()* On MS-Windows the ".exe", ".bat", etc. can optionally be included. Then the extensions in $PATHEXT are tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be found. If - $PATHEXT is not set then ".exe;.com;.bat;.cmd" is used. A dot + $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot by itself can be used in $PATHEXT to try using the name without an extension. When 'shell' looks like a Unix shell, then the name is also tried without adding an extension. @@ -4096,8 +4123,12 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined, string) *funcname built-in function (see |functions|) or user defined function (see - |user-functions|). Also works for a - variable that is a Funcref. + |user-functions|) that is implemented. + Also works for a variable that is a + Funcref. + ?funcname built-in function that could be + implemented; to be used to check if + "funcname" is valid varname internal variable (see |internal-variables|). Also works for |curly-braces-names|, |Dictionary| @@ -4352,6 +4383,8 @@ feedkeys({string} [, {mode}]) *feedkeys()* 'L' Lowlevel input. Only works for Unix or when using the GUI. Keys are used as if they were coming from the terminal. Other flags are not used. *E980* + When a CTRL-C interrupts and 't' is included it sets + the internal "got_int" flag. 'i' Insert the string instead of appending (see above). 'x' Execute commands until typeahead is empty. This is similar to using ":normal!". You can call feedkeys() @@ -4363,7 +4396,7 @@ feedkeys({string} [, {mode}]) *feedkeys()* script continues. Note that if you manage to call feedkeys() while executing commands, thus calling it recursively, then - all typehead will be consumed by the last call. + all typeahead will be consumed by the last call. '!' When used with 'x' will not end Insert mode. Can be used in a test when a timer is set to exit Insert mode a little later. Useful for testing CursorHoldI. @@ -4399,7 +4432,7 @@ filewritable({file}) *filewritable()* directory, and we can write to it, the result is 2. Can also be used as a |method|: > - GetName()->filewriteable() + GetName()->filewritable() filter({expr1}, {expr2}) *filter()* @@ -5124,10 +5157,11 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* < *getcurpos()* getcurpos() Get the position of the cursor. This is like getpos('.'), but - includes an extra item in the list: - [bufnum, lnum, col, off, curswant] ~ + includes an extra "curswant" item in the list: + [0, lnum, col, off, curswant] ~ The "curswant" number is the preferred column when moving the cursor vertically. Also see |getpos()|. + The first "bufnum" item is always zero. This can be used to save and restore the cursor position: > let save_cursor = getcurpos() @@ -5339,6 +5373,27 @@ getloclist({nr} [, {what}]) *getloclist()* |location-list-file-window| for more details. +getmarklist([{expr}] *getmarklist()* + Without the {expr} argument returns a |List| with information + about all the global marks. |mark| + + If the optional {expr} argument is specified, returns the + local marks defined in buffer {expr}. For the use of {expr}, + see |bufname()|. + + Each item in the retuned List is a |Dict| with the following: + name - name of the mark prefixed by "'" + pos - a |List| with the position of the mark: + [bufnum, lnum, col, off] + Refer to |getpos()| for more information. + file - file name + + Refer to |getpos()| for getting information about a specific + mark. + + Can also be used as a |method|: > + GetBufnr()->getmarklist() + getmatches([{win}]) *getmatches()* Returns a |List| with all matches previously defined for the current window by |matchadd()| and the |:match| commands. @@ -5378,7 +5433,7 @@ getmousepos() *getmousepos()* "screenrow" and "screencol" are valid, the others are zero. When on the status line below a window or the vertical - separater right of a window, the "line" and "column" values + separator right of a window, the "line" and "column" values are zero. When the position is after the text then "column" is the @@ -5461,8 +5516,9 @@ getqflist([{what}]) *getqflist()* id get information for the quickfix list with |quickfix-ID|; zero means the id for the current list or the list specified by "nr" - idx index of the current entry in the quickfix - list specified by 'id' or 'nr'. + idx get information for the quickfix entry at this + index in the list specified by 'id' or 'nr'. + If set to zero, then uses the current entry. See |quickfix-index| items quickfix list entries lines parse a list of lines using 'efm' and return @@ -5498,7 +5554,7 @@ getqflist([{what}]) *getqflist()* If not present, set to "". id quickfix list ID |quickfix-ID|. If not present, set to 0. - idx index of the current entry in the list. If not + idx index of the quickfix entry in the list. If not present, set to 0. items quickfix list entries. If not present, set to an empty list. @@ -5820,11 +5876,32 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) GetExpr()->globpath(&rtp) < *has()* -has({feature}) The result is a Number, which is 1 if the feature {feature} is - supported, zero otherwise. The {feature} argument is a - string. See |feature-list| below. +has({feature} [, {check}]) + When {check} is omitted or is zero: The result is a Number, + which is 1 if the feature {feature} is supported, zero + otherwise. The {feature} argument is a string, case is + ignored. See |feature-list| below. + + When {check} is present and not zero: The result is a Number, + which is 1 if the feature {feature} could ever be supported, + zero otherwise. This is useful to check for a typo in + {feature} and to detect dead code. Keep in mind that an older + Vim version will not know about a feature added later and + features that have been abandoned will not be know by the + current Vim version. + Also see |exists()|. + Note that to skip code that has a syntax error when the + feature is not available, Vim may skip the rest of the line + and miss a following `endif`. Therefore put the `endif` on a + separate line: > + if has('feature') + let x = this->breaks->without->the->feature + endif +< If the `endif` would be moved to the second line as "| endif" it + would not be found. + has_key({dict}, {key}) *has_key()* The result is a Number, which is 1 if |Dictionary| {dict} has @@ -6755,6 +6832,7 @@ map({expr1}, {expr2}) *map()* Can also be used as a |method|: > mylist->map(expr2) + maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* When {dict} is omitted or zero: Return the rhs of mapping {name} in mode {mode}. The returned String has special @@ -6787,10 +6865,14 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* When {dict} is there and it is |TRUE| return a dictionary containing all the information of the mapping with the following items: - "lhs" The {lhs} of the mapping. + "lhs" The {lhs} of the mapping as it would be typed + "lhsraw" The {lhs} of the mapping as raw bytes + "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate + form, only present when it differs from "lhsraw" "rhs" The {rhs} of the mapping as typed. "silent" 1 for a |:map-silent| mapping, else 0. "noremap" 1 if the {rhs} of the mapping is not remappable. + "script" 1 if mapping was defined with