diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 183 |
1 files changed, 133 insertions, 50 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index efb6272e58..800de63a55 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -38,7 +38,9 @@ List An ordered sequence of items |List|. Dictionary An associative, unordered array: Each entry has a key and a value. |Dictionary| - Example: {'blue': "#0000ff", 'red': "#ff0000"} + Examples: + {'blue': "#0000ff", 'red': "#ff0000"} + #{blue: "#0000ff", red: "#ff0000"} The Number and String types are converted automatically, depending on how they are used. @@ -436,8 +438,14 @@ only appear once. Examples: > A key is always a String. You can use a Number, it will be converted to a String automatically. Thus the String '4' and the number 4 will find the same entry. Note that the String '04' and the Number 04 are different, since the -Number will be converted to the String '4'. The empty string can be used as a -key. +Number will be converted to the String '4'. The empty string can also be used +as a key. + *literal-Dict* +To avoid having to put quotes around every key the #{} form can be used. This +does require the key to consist only of ASCII letters, digits, '-' and '_'. +Example: > + let mydict = #{zero: 0, one_key: 1, two-key: 2, 333: 3} +Note that 333 here is the string "333". Empty keys are not possible with #{}. A value can be any expression. Using a Dictionary for a value creates a nested Dictionary: > @@ -2224,6 +2232,7 @@ inputsecret({prompt} [, {text}]) String like input() but hiding the text insert({list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}] +interrupt() none interrupt script execution invert({expr}) Number bitwise invert isdirectory({directory}) Number |TRUE| if {directory} is a directory isinf({expr}) Number determine if {expr} is infinity value @@ -2287,6 +2296,7 @@ nr2char({expr}[, {utf8}]) String single char with ASCII/UTF8 value {expr} nvim_...({args}...) any call nvim |api| functions or({expr}, {expr}) Number bitwise OR pathshorten({expr}) String shorten directory names in a path +perleval({expr}) any evaluate |perl| expression 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 @@ -2326,6 +2336,7 @@ repeat({expr}, {count}) String repeat {expr} {count} times resolve({filename}) String get filename a shortcut points to reverse({list}) List reverse {list} in-place round({expr}) Float round off {expr} +rubyeval({expr}) any evaluate |Ruby| expression rpcnotify({channel}, {event}[, {args}...]) Sends an |RPC| notification to {channel} rpcrequest({channel}, {method}[, {args}...]) @@ -2408,7 +2419,8 @@ str2list({expr} [, {utf8}]) List convert each character of {expr} to str2nr({expr} [, {base}]) 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} + String {len} characters of {str} at + character {start} strdisplaywidth({expr} [, {col}]) Number display length of the String {expr} strftime({format} [, {time}]) String time in specified format strgetchar({str}, {index}) Number get char {index} from {str} @@ -2416,8 +2428,9 @@ stridx({haystack}, {needle} [, {start}]) Number index of {needle} in {haystack} string({expr}) String String representation of {expr} value strlen({expr}) Number length of the String {expr} -strpart({str}, {start} [, {len}]) - String {len} characters of {str} at {start} +strpart({str}, {start} [, {len} [, {chars}]]) + String {len} bytes/chars of {str} at + byte {start} strridx({haystack}, {needle} [, {start}]) Number last index of {needle} in {haystack} strtrans({expr}) String translate string to make it printable @@ -2456,7 +2469,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} @@ -2905,7 +2919,8 @@ byte2line({byte}) *byte2line()* byteidx({expr}, {nr}) *byteidx()* Return byte index of the {nr}'th character in the string - {expr}. Use zero for the first character, it returns zero. + {expr}. Use zero for the first character, it then returns + zero. This function is only useful when there are multibyte characters, otherwise the returned value is equal to {nr}. Composing characters are not counted separately, their byte @@ -3826,7 +3841,7 @@ feedkeys({string} [, {mode}]) *feedkeys()* stuck, waiting for a character to be typed before the script continues. Note that if you manage to call feedkeys() while - executing commands, thus calling it recursively, the + executing commands, thus calling it recursively, then all typehead 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 @@ -4629,7 +4644,7 @@ getloclist({nr},[, {what}]) *getloclist()* If {what} contains 'filewinid', then returns the id of the window used to display files from the location list. This field is applicable only when called from a location list - window. + window. See |location-list-file-window| for more details. getmatches([{win}]) *getmatches()* Returns a |List| with all matches previously defined for the @@ -4720,7 +4735,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 list + idx index of the current entry in the quickfix + list specified by 'id' or 'nr'. + See |quickfix-index| items quickfix list entries lines parse a list of lines using 'efm' and return the resulting entries. Only a |List| type is @@ -4913,6 +4930,19 @@ getwinpos([{timeout}]) *getwinpos()* {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. + When using a value less than 10 and no response is received + within that time, a previously reported position is returned, + if available. This can be used to poll for the position and + do some work in the meantime: > + while 1 + let res = getwinpos(1) + if res[0] >= 0 + break + endif + " Do some work here + endwhile +< *getwinposx()* getwinposx() The result is a Number, which is the X coordinate in pixels of the left hand side of the GUI Vim window. The result will be @@ -5412,6 +5442,19 @@ insert({list}, {item} [, {idx}]) *insert()* Note that when {item} is a |List| it is inserted as a single item. Use |extend()| to concatenate |Lists|. +interrupt() *interrupt()* + Interrupt script execution. It works more or less like the + user typing CTRL-C, most commands won't execute and control + returns to the user. This is useful to abort execution + from lower down, e.g. in an autocommand. Example: > + :function s:check_typoname(file) + : if fnamemodify(a:file, ':t') == '[' + : echomsg 'Maybe typo' + : call interrupt() + : endif + :endfunction + :au BufWritePre * call s:check_typoname(expand('<amatch>')) + invert({expr}) *invert()* Bitwise invert. The argument is converted to a number. A List, Dict or Float argument causes an error. Example: > @@ -6237,6 +6280,7 @@ mode([expr]) Return a string that indicates the current mode. nov Operator-pending (forced charwise |o_v|) noV Operator-pending (forced linewise |o_V|) noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|) + CTRL-V is one character niI Normal using |i_CTRL-O| in |Insert-mode| niR Normal using |i_CTRL-O| in |Replace-mode| niV Normal using |i_CTRL-O| in |Virtual-Replace-mode| @@ -6406,6 +6450,21 @@ pathshorten({expr}) *pathshorten()* < ~/.c/n/a/file1.vim ~ It doesn't matter if the path exists or not. +perleval({expr}) *perleval()* + Evaluate |perl| expression {expr} and return its result + converted to Vim data structures. + Numbers and strings are returned as they are (strings are + copied though). + Lists are represented as Vim |List| type. + Dictionaries are represented as Vim |Dictionary| type, + non-string keys result in error. + + Note: If you want an array or hash, {expr} must return a + reference to it. + Example: > + :echo perleval('[1 .. 4]') +< [1, 2, 3, 4] + pow({x}, {y}) *pow()* Return the power of {x} to the exponent {y} as a |Float|. {x} and {y} must evaluate to a |Float| or a |Number|. @@ -7012,6 +7071,17 @@ rpcstart({prog}[, {argv}]) *rpcstart()* < with > :let id = jobstart(['prog', 'arg1', 'arg2'], {'rpc': v:true}) +rubyeval({expr}) *rubyeval()* + Evaluate Ruby expression {expr} and return its result + converted to Vim data structures. + Numbers, floats and strings are returned as they are (strings + are copied though). + Arrays are represented as Vim |List| type. + Hashes are represented as Vim |Dictionary| type. + Other objects are represented as strings resulted from their + "Object#to_s" method. + {only available when compiled with the |+ruby| feature} + screenattr({row}, {col}) *screenattr()* Like |screenchar()|, but return the attribute. This is a rather arbitrary number that can only be used to compare to the @@ -7581,16 +7651,22 @@ setqflist({list} [, {action}[, {what}]]) *setqflist()* efm errorformat to use when parsing text from "lines". If this is not present, then the 'errorformat' option value is used. + See |quickfix-parse| id quickfix list identifier |quickfix-ID| + idx index of the current entry in the quickfix + list specified by 'id' or 'nr'. If set to '$', + 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. 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. + See |quickfix-parse| nr list number in the quickfix stack; zero means the current quickfix list and "$" means - the last quickfix list - title quickfix list title text + the last quickfix list. + 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 @@ -7737,26 +7813,23 @@ sha256({string}) *sha256()* shellescape({string} [, {special}]) *shellescape()* Escape {string} for use as a shell command argument. - On Windows when 'shellslash' is not set, it - will enclose {string} in double quotes and double all double - quotes within {string}. - Otherwise, it will enclose {string} in single quotes and - replace all "'" with "'\''". - - When the {special} argument is present and it's a non-zero - Number or a non-empty String (|non-zero-arg|), then special - items such as "!", "%", "#" and "<cword>" will be preceded by - a backslash. This backslash will be removed again by the |:!| - command. - The "!" character will be escaped (again with a |non-zero-arg| - {special}) when 'shell' contains "csh" in the tail. That is - because for csh and tcsh "!" is used for history replacement - even when inside single quotes. + On Windows when 'shellslash' is not set, encloses {string} in + double-quotes and doubles all double-quotes within {string}. + Otherwise encloses {string} in single-quotes and replaces all + "'" with "'\''". - With a |non-zero-arg| {special} the <NL> character is also - escaped. When 'shell' containing "csh" in the tail it's - escaped a second time. + If {special} is a ||non-zero-arg|: + - Special items such as "!", "%", "#" and "<cword>" will be + preceded by a backslash. The backslash will be removed again + by the |:!| command. + - The <NL> character is escaped. + + If 'shell' contains "csh" in the tail: + - The "!" character will be escaped. This is because csh and + tcsh use "!" for history replacement even in single-quotes. + - The <NL> character is escaped (twice if {special} is + a ||non-zero-arg|). Example of use with a |:!| command: > :exe '!dir ' . shellescape(expand('<cfile>'), 1) @@ -8229,15 +8302,13 @@ sqrt({expr}) *sqrt()* stdioopen({opts}) *stdioopen()* - In a nvim launched with the |--headless| option, this opens - stdin and stdout as a |channel|. This function can only be - invoked once per instance. See |channel-stdio| for more - information and examples. Note that stderr is not handled by - this function, see |v:stderr|. + With |--headless| this opens stdin and stdout as a |channel|. + May be called only once. See |channel-stdio|. stderr is not + handled by this function, see |v:stderr|. - Returns a |channel| ID. Close the stdio descriptors with |chanclose()|. - Use |chansend()| to send data to stdout, and - |rpcrequest()| and |rpcnotify()| to communicate over RPC. + Close the stdio handles with |chanclose()|. Use |chansend()| + to send data to stdout, and |rpcrequest()| and |rpcnotify()| + to communicate over RPC. {opts} is a dictionary with these keys: |on_stdin| : callback invoked when stdin is written to. @@ -8245,7 +8316,7 @@ stdioopen({opts}) *stdioopen()* rpc : If set, |msgpack-rpc| will be used to communicate over stdio Returns: - - The channel ID on success (this is always 1) + - |channel-id| on success (value is always 1) - 0 on invalid arguments @@ -8424,14 +8495,19 @@ strlen({expr}) The result is a Number, which is the length of the String {expr} in bytes. If the argument is a Number it is first converted to a String. For other types an error is given. - If you want to count the number of multi-byte characters use + If you want to count the number of multibyte characters use |strchars()|. Also see |len()|, |strdisplaywidth()| and |strwidth()|. -strpart({src}, {start} [, {len}]) *strpart()* +strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* The result is a String, which is part of {src}, starting from byte {start}, with the byte length {len}. - To count characters instead of bytes use |strcharpart()|. + When {chars} is present and TRUE then {len} is the number of + characters positions (composing characters are not counted + separately, thus "1" means one base character and any + following composing characters). + To count {start} as characters instead of bytes use + |strcharpart()|. When bytes are selected which do not exist, this doesn't result in an error, the bytes are simply omitted. @@ -8443,8 +8519,8 @@ strpart({src}, {start} [, {len}]) *strpart()* strpart("abcdefg", 3) == "defg" < Note: To get the first character, {start} must be 0. For - example, to get three bytes under and after the cursor: > - strpart(getline("."), col(".") - 1, 3) + example, to get the character under the cursor: > + strpart(getline("."), col(".") - 1, 1, v:true) < strridx({haystack}, {needle} [, {start}]) *strridx()* The result is a Number, which gives the byte index in @@ -8974,21 +9050,28 @@ tr({src}, {fromstr}, {tostr}) *tr()* echo tr("<blob>", "<>", "{}") < returns "{blob}" -trim({text} [, {mask}]) *trim()* +trim({text} [, {mask} [, {dir}]]) *trim()* Return {text} as a String where any character in {mask} is - removed from the beginning and end of {text}. + removed from the beginning and/or end of {text}. If {mask} is not given, {mask} is all characters up to 0x20, which includes Tab, space, NL and CR, plus the non-breaking space character 0xa0. - This code deals with multibyte characters properly. - + The optional {dir} argument specifies where to remove the + characters: + 0 remove from the beginning and end of {text} + 1 remove only at the beginning of {text} + 2 remove only at the end of {text} + When omitted both ends are trimmed. + This function deals with multibyte characters properly. Examples: > echo trim(" some text ") < returns "some text" > echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL" < returns "RESERVE_TAIL" > echo trim("rm<Xrm<>X>rrm", "rm<>") -< returns "Xrm<>X" (characters in the middle are not removed) +< returns "Xrm<>X" (characters in the middle are not removed) > + echo trim(" vim ", " ", 2) +< returns " vim" trunc({expr}) *trunc()* Return the largest integral value with magnitude less than or |