diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 203 |
1 files changed, 160 insertions, 43 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index cf1394d799..e341a2247a 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 7.4. Last change: 2015 Jul 21 +*eval.txt* For Vim version 7.4. Last change: 2016 Jan 16 VIM REFERENCE MANUAL by Bram Moolenaar @@ -1418,6 +1418,13 @@ v:exception The value of the exception most recently caught and not :endtry < Output: "caught oops". + *v:false* *false-variable* +v:false Special value used to put "false" in JSON and msgpack. See + |json_encode()|. This value is converted to "false" when used + as a String (e.g. in |expr5| with string concatenation + operator) and to zero when used as a Number (e.g. in |expr5| + or |expr7| when used with numeric operators). + *v:fcs_reason* *fcs_reason-variable* v:fcs_reason The reason why the |FileChangedShell| event was triggered. Can be used in an autocommand to decide what to do and/or what @@ -1557,6 +1564,13 @@ v:msgpack_types Dictionary containing msgpack types used by |msgpackparse()| (not editable) empty lists. To check whether some list is one of msgpack types, use |is| operator. + *v:null* *null-variable* +v:null Special value used to put "null" in JSON and NIL in msgpack. + See |json_encode()|. This value is converted to "null" when + used as a String (e.g. in |expr5| with string concatenation + operator) and to zero when used as a Number (e.g. in |expr5| + or |expr7| when used with numeric operators). + *v:oldfiles* *oldfiles-variable* v:oldfiles List of file names that is loaded from the |shada| file on startup. These are the files that Vim remembers marks for. @@ -1722,6 +1736,13 @@ v:throwpoint The point where the exception most recently caught and not :endtry < Output: "Exception from test.vim, line 2" + *v:true* *true-variable* +v:true Special value used to put "true" in JSON and msgpack. See + |json_encode()|. This value is converted to "true" when used + as a String (e.g. in |expr5| with string concatenation + operator) and to one when used as a Number (e.g. in |expr5| or + |expr7| when used with numeric operators). + *v:val* *val-variable* v:val Value of the current item of a |List| or |Dictionary|. Only valid while evaluating the expression used with |map()| and @@ -1742,7 +1763,8 @@ v:version Version number of Vim: Major version number times 100 plus v:warningmsg Last given warning message. It's allowed to set this variable. *v:windowid* *windowid-variable* {Nvim} -v:windowid Is a no-op at the moment; the value is always set to 0. +v:windowid Application-specific window ID ("window handle" in MS-Windows) + which may be set by any attached UI. Defaults to zero. Note: for windows inside Vim use |winnr()|. ============================================================================== @@ -1779,7 +1801,7 @@ bufexists( {expr}) Number TRUE if buffer {expr} exists buflisted( {expr}) Number TRUE if buffer {expr} is listed bufloaded( {expr}) Number TRUE if buffer {expr} is loaded bufname( {expr}) String Name of the buffer {expr} -bufnr( {expr}) Number Number of the buffer {expr} +bufnr( {expr} [, {create}]) Number Number of the buffer {expr} bufwinnr( {expr}) Number window number of buffer {expr} byte2line( {byte}) Number line number at byte count {byte} byteidx( {expr}, {nr}) Number byte index of {nr}'th char in {expr} @@ -1808,7 +1830,7 @@ cursor( {lnum}, {col} [, {off}]) Number move cursor to {lnum}, {col}, {off} cursor( {list}) Number move cursor to position in {list} deepcopy( {expr} [, {noref}]) any make a full copy of {expr} -delete( {fname}) Number delete file {fname} +delete( {fname} [, {flags}]) Number delete the file or directory {fname} dictwatcheradd( {dict}, {pattern}, {callback}) Start watching a dictionary dictwatcherdel( {dict}, {pattern}, {callback}) @@ -1864,7 +1886,7 @@ getcmdpos() Number return cursor position in command-line getcmdtype() String return current command-line type getcmdwintype() String return current command-line window type getcurpos() List position of the cursor -getcwd() String the current working directory +getcwd( [{scope}]) String the current working directory getfontname( [{name}]) String name of font being used getfperm( {fname}) String file permissions of file {fname} getfsize( {fname}) Number size in bytes of file {fname} @@ -1932,6 +1954,8 @@ jobstart( {cmd}[, {opts}]) Number Spawns {cmd} as a job jobstop( {job}) Number Stops a job jobwait( {ids}[, {timeout}]) Number Wait for a set of jobs join( {list} [, {sep}]) String join {list} items into one String +json_decode( {expr}) any Convert {expr} from JSON +json_encode( {expr}) String Convert {expr} to JSON keys( {dict}) List keys in {dict} len( {expr}) Number the length of {expr} libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg} @@ -2222,17 +2246,17 @@ assert_equal({expected}, {actual}, [, {msg}]) assert_false({actual}, [, {msg}]) *assert_false()* When {actual} is not false an error message is added to - |v:errors|, like with |assert_equal()|.. - A value is false when it is zero. When "{actual}" is not a - number the assert fails. + |v:errors|, like with |assert_equal()|. + A value is false when it is zero or |v:false|. When "{actual}" + is not a number or |v:false| the assert fails. When {msg} is omitted an error in the form "Expected False but got {actual}" is produced. assert_true({actual}, [, {msg}]) *assert_true()* When {actual} is not true an error message is added to - |v:errors|, like with |assert_equal()|.. - A value is true when it is a non-zeron number. When {actual} - is not a number the assert fails. + |v:errors|, like with |assert_equal()|. + A value is true when it is a non-zero number or |v:true|. + When {actual} is not a number or |v:true| the assert fails. When {msg} is omitted an error in the form "Expected True but got {actual}" is produced. @@ -2746,13 +2770,19 @@ deepcopy({expr}[, {noref}]) *deepcopy()* *E698* {noref} set to 1 will fail. Also see |copy()|. -delete({fname}) *delete()* - Deletes the file by the name {fname}. The result is a Number, - which is 0 if the file was deleted successfully, and non-zero - when the deletion failed. - Use |remove()| to delete an item from a |List|. - To delete a line from the buffer use |:delete|. Use |:exe| - when the line number is in a variable. +delete({fname} [, {flags}]) *delete()* + Without {flags} or with {flags} empty: Deletes the file by the + name {fname}. This also works when {fname} is a symbolic link. + A symbolic link itself is deleted, not what it points to. + + When {flags} is "d": Deletes the directory by the name + {fname}. This fails when directory {fname} is not empty. + + When {flags} is "rf": Deletes the directory by the name + {fname} and everything in it, recursively. BE CAREFUL! + + The result is a Number, which is 0 if the delete operation was + successful and -1 when the deletion failed or partly failed. dictwatcheradd({dict}, {pattern}, {callback}) *dictwatcheradd()* Adds a watcher to a dictionary. A dictionary watcher is @@ -2826,9 +2856,8 @@ diff_hlID({lnum}, {col}) *diff_hlID()* empty({expr}) *empty()* Return the Number 1 if {expr} is empty, zero otherwise. A |List| or |Dictionary| is empty when it does not have any - items. A Number is empty when its value is zero. - For a long |List| this is much faster than comparing the - length with zero. + items. A Number is empty when its value is zero. Special + variable is empty when it is |v:false| or |v:null|. escape({string}, {chars}) *escape()* Escape the characters in {chars} that occur in {string} with a @@ -3536,9 +3565,18 @@ getcurpos() Get the position of the cursor. This is like getpos('.'), but MoveTheCursorAround call setpos('.', save_cursor) < - *getcwd()* -getcwd() The result is a String, which is the name of the current - working directory. +getcwd([{window}[, {tab}]]) *getcwd()* + With no arguments the result is a String, which is the name of + the current effective working directory. With {window} or + {tab} the working directory of that scope is returned. + Tabs and windows are identified by their respective numbers, + 0 means current tab or window. Missing argument implies 0. + Thus the following are equivalent: > + getcwd() + getcwd(0) + getcwd(0, 0) +< If {window} is -1 it is ignored, only the tab is resolved. + getfsize({fname}) *getfsize()* The result is a Number, which is the size in bytes of the @@ -3873,9 +3911,18 @@ has_key({dict}, {key}) *has_key()* The result is a Number, which is 1 if |Dictionary| {dict} has an entry with key {key}. Zero otherwise. -haslocaldir() *haslocaldir()* - The result is a Number, which is 1 when the current - window has set a local path via |:lcd|, and 0 otherwise. +haslocaldir([{window}[, {tab}]]) *haslocaldir()* + The result is a Number, which is 1 when the specified tabpage + or window has a local path set via |:lcd| or |:tcd|, and + 0 otherwise. + + Tabs and windows are identified by their respective numbers, + 0 means current tab or window. Missing argument implies 0. + Thus the following are equivalent: > + haslocaldir() + haslocaldir(0) + haslocaldir(0, 0) +< If {window} is -1 it is ignored, only the tab is resolved. hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* The result is a Number, which is 1 if there is a mapping that @@ -4291,6 +4338,46 @@ join({list} [, {sep}]) *join()* converted into a string like with |string()|. The opposite function is |split()|. +json_decode({expr}) *json_decode()* + Convert {expr} from JSON object. Accepts |readfile()|-style + list as the input, as well as regular string. May output any + Vim value. When 'encoding' is not UTF-8 string is converted + from UTF-8 to 'encoding', failing conversion fails + json_decode(). In the following cases it will output + |msgpack-special-dict|: + 1. Dictionary contains duplicate key. + 2. Dictionary contains empty key. + 3. String contains NUL byte. Two special dictionaries: for + dictionary and for string will be emitted in case string + with NUL byte was a dictionary key. + + Note: function treats its input as UTF-8 always regardless of + 'encoding' value. This is needed because JSON source is + supposed to be external (e.g. |readfile()|) and JSON standard + allows only a few encodings, of which UTF-8 is recommended and + the only one required to be supported. Non-UTF-8 characters + are an error. + +json_encode({expr}) *json_encode()* + Convert {expr} into a JSON string. Accepts + |msgpack-special-dict| as the input. Converts from 'encoding' + to UTF-8 when encoding strings. Will not convert |Funcref|s, + mappings with non-string keys (can be created as + |msgpack-special-dict|), values with self-referencing + containers, strings which contain non-UTF-8 characters, + pseudo-UTF-8 strings which contain codepoints reserved for + surrogate pairs (such strings are not valid UTF-8 strings). + When converting 'encoding' is taken into account, if it is not + "utf-8", then conversion is performed before encoding strings. + Non-printable characters are converted into "\u1234" escapes + or special escapes like "\t", other are dumped as-is. + + Note: all characters above U+0079 are considered non-printable + when 'encoding' is not UTF-8. This function always outputs + UTF-8 strings as required by the standard thus when 'encoding' + is not unicode resulting string will look incorrect if + "\u1234" notation is not used. + keys({dict}) *keys()* Return a |List| with all the keys of {dict}. The |List| is in arbitrary order. @@ -4818,7 +4905,7 @@ msgpackdump({list}) {Nvim} *msgpackdump()* (dictionary with zero items is represented by 0x80 byte in messagepack). - Limitations: *E951* *E952* + Limitations: *E951* *E952* *E953* 1. |Funcref|s cannot be dumped. 2. Containers that reference themselves cannot be dumped. 3. Dictionary keys are always dumped as STR strings. @@ -4853,9 +4940,13 @@ msgpackparse({list}) {Nvim} *msgpackparse()* contains name of the key from |v:msgpack_types|): Key Value ~ - nil Zero, ignored when dumping. - boolean One or zero. When dumping it is only checked that - value is a |Number|. + nil Zero, ignored when dumping. This value cannot + possibly appear in |msgpackparse()| output in Neovim + versions which have |v:null|. + boolean One or zero. When dumping it is only checked that + value is a |Number|. This value cannot possibly + appear in |msgpackparse()| output in Neovim versions + which have |v:true| and |v:false|. integer |List| with four numbers: sign (-1 or 1), highest two bits, number with bits from 62nd to 31st, lowest 31 bits. I.e. to get actual number one will need to use @@ -5457,14 +5548,15 @@ search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()* move. No error message is given. {flags} is a String, which can contain these character flags: - 'b' search backward instead of forward - 'c' accept a match at the cursor position + 'b' search Backward instead of forward + 'c' accept a match at the Cursor position 'e' move to the End of the match 'n' do Not move the cursor - 'p' return number of matching sub-pattern (see below) - 's' set the ' mark at the previous location of the cursor - 'w' wrap around the end of the file - 'W' don't wrap around the end of the file + 'p' return number of matching sub-Pattern (see below) + 's' Set the ' mark at the previous location of the cursor + 'w' Wrap around the end of the file + 'W' don't Wrap around the end of the file + 'z' start searching at the cursor column instead of Zero If neither 'w' or 'W' is given, the 'wrapscan' option applies. If the 's' flag is supplied, the ' mark is set, only if the @@ -5472,6 +5564,12 @@ search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()* flag. 'ignorecase', 'smartcase' and 'magic' are used. + + When the 'z' flag is not given seaching always starts in + column zero and then matches before the cursor are skipped. + When the 'c' flag is present in 'cpo' the next search starts + after the match. Without the 'c' flag the next search starts + one column further. When the {stopline} argument is given then the search stops after searching this line. This is useful to restrict the @@ -5710,7 +5808,7 @@ setbufvar({expr}, {varname}, {val}) *setbufvar()* :call setbufvar("todo", "myvar", "foobar") < This function is not available in the |sandbox|. -setcharsearch() *setcharsearch()* +setcharsearch({dict}) *setcharsearch()* Set the current character search information to {dict}, which contains one or more of the following entries: @@ -6053,6 +6151,10 @@ sort({list} [, {func} [, {dict}]]) *sort()* *E702* strtod() function to parse numbers, Strings, Lists, Dicts and Funcrefs will be considered as being 0). + When {func} is given and it is 'N' then all items will be + sorted numerical. This is like 'n' but a string containing + digits will be used as the number they represent. + When {func} is a |Funcref| or a function name, this function is called to compare items. The function is invoked with two items as argument and must return zero if they are equal, 1 or @@ -6067,6 +6169,11 @@ sort({list} [, {func} [, {dict}]]) *sort()* *E702* on numbers, text strings will sort next to each other, in the same order as they were originally. + The sort is stable, items which compare equal (as number or as + string) will keep their relative position. E.g., when sorting + on numbers, text strings will sort next to each other, in the + same order as they were originally. + Also see |uniq()|. Example: > @@ -6154,7 +6261,8 @@ split({expr} [, {pattern} [, {keepempty}]]) *split()* :let words = split(getline('.'), '\W\+') < To split a string in individual characters: > :for c in split(mystring, '\zs') -< If you want to keep the separator you can also use '\zs': > +< If you want to keep the separator you can also use '\zs' at + the end of the pattern: > :echo split('abc:def:ghi', ':\zs') < ['abc:', 'def:', 'ghi'] ~ Splitting a table where the first element can be empty: > @@ -6424,6 +6532,9 @@ synID({lnum}, {col}, {trans}) *synID()* {col} is 1 for the leftmost column, {lnum} is 1 for the first line. 'synmaxcol' applies, in a longer line zero is returned. + Note that when the position is after the last character, + that's where the cursor can be in Insert mode, synID() returns + zero. When {trans} is non-zero, transparent items are reduced to the item that they reveal. This is useful when wanting to know @@ -6729,12 +6840,14 @@ trunc({expr}) *trunc()* type({expr}) *type()* The result is a Number, depending on the type of {expr}: - Number: 0 - String: 1 + Number: 0 + String: 1 Funcref: 2 - List: 3 + List: 3 Dictionary: 4 - Float: 5 + Float: 5 + Boolean: 6 (|v:true| and |v:false|) + Null: 7 (|v:null|) To avoid the magic numbers it should be used this way: > :if type(myvar) == type(0) :if type(myvar) == type("") @@ -6742,6 +6855,10 @@ type({expr}) *type()* :if type(myvar) == type([]) :if type(myvar) == type({}) :if type(myvar) == type(0.0) + :if type(myvar) == type(v:true) +< In place of checking for |v:null| type it is better to check + for |v:null| directly as it is the only value of this type: > + :if myvar is v:null undofile({name}) *undofile()* Return the name of the undo file that would be used for a file |