diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 156 |
1 files changed, 90 insertions, 66 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index b5fe9967b2..193153e8a3 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 7.4. Last change: 2016 Jan 16 +*eval.txt* For Vim version 7.4. Last change: 2016 Feb 19 VIM REFERENCE MANUAL by Bram Moolenaar @@ -100,6 +100,9 @@ When mixing Number and Float the Number is converted to Float. Otherwise there is no automatic conversion of Float. You can use str2float() for String to Float, printf() for Float to String and float2nr() for Float to Number. + *E891* *E892* *E893* *E894* +When expecting a Float a Number can also be used, but nothing else. + *E706* *sticky-type-checking* You will get an error if you try to change the type of a variable. You need to |:unlet| it first to avoid this error. String and Number are considered @@ -870,7 +873,7 @@ cursor: > :let c = getline(".")[col(".") - 1] If the length of the String is less than the index, the result is an empty -String. A negative index always results in an empty string (reason: backwards +String. A negative index always results in an empty string (reason: backward compatibility). Use [-1:] to get the last byte. If expr8 is a |List| then it results the item at index expr1. See |list-index| @@ -1650,9 +1653,9 @@ v:scrollstart String describing the script or function that caused the hit-enter prompt. *v:servername* *servername-variable* + *$NVIM_LISTEN_ADDRESS* v:servername Default {Nvim} server address. Equivalent to - |$NVIM_LISTEN_ADDRESS| on startup, but may differ if the - latter is modified or unset. |serverstop()| + |$NVIM_LISTEN_ADDRESS| on startup. |serverstop()| Read-only. @@ -1780,6 +1783,7 @@ abs({expr}) Float or Number absolute value of {expr} acos({expr}) Float arc cosine of {expr} add({list}, {item}) List append {item} to |List| {list} and({expr}, {expr}) Number bitwise AND +api_info() Dict api metadata append({lnum}, {string}) Number append {string} below line {lnum} append({lnum}, {list}) Number append lines {list} below line {lnum} argc() Number number of files in the argument list @@ -1788,7 +1792,8 @@ arglistid([{winnr} [, {tabnr}]]) Number argument list id argv({nr}) String {nr} entry of the argument list argv() List the argument list assert_equal({exp}, {act} [, {msg}]) none assert {exp} equals {act} -assert_exception({error} [, {msg}]) none assert {error} is in v:exception +assert_exception( {error} [, {msg}]) none assert {error} is in v:exception +assert_fails( {cmd} [, {error}]) none assert {cmd} fails assert_false({actual} [, {msg}]) none assert {actual} is false assert_true({actual} [, {msg}]) none assert {actual} is true asin({expr}) Float arc sine of {expr} @@ -1887,7 +1892,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([{scope}]) String the current working directory +getcwd([{winnr} [, {tabnr}]]) 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} @@ -1918,10 +1923,11 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) String do glob({expr}) for all dirs in {path} has({feature}) Number TRUE if feature {feature} supported has_key({dict}, {key}) Number TRUE if {dict} has entry {key} -haslocaldir() Number TRUE if current window executed |:lcd| +haslocaldir([{winnr} [, {tabnr}]]) + Number TRUE if current window executed |:lcd| hasmapto({what} [, {mode} [, {abbr}]]) Number TRUE if mapping to {what} exists -histadd({history},{item}) String add an item to a history +histadd({history}, {item}) String add an item to a history histdel({history} [, {item}]) String 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 @@ -2027,11 +2033,11 @@ resolve({filename}) String get filename a shortcut points to reverse({list}) List reverse {list} in-place round({expr}) Float round off {expr} rpcnotify({channel}, {event}[, {args}...]) - Sends a |msgpack-rpc| notification to {channel} + Sends an |RPC| notification to {channel} rpcrequest({channel}, {method}[, {args}...]) - Sends a |msgpack-rpc| request to {channel} -rpcstart({prog}[, {argv}]) Spawns {prog} and opens a |msgpack-rpc| channel -rpcstop({channel}) Closes a |msgpack-rpc| {channel} + Sends an |RPC| request to {channel} +rpcstart({prog}[, {argv}]) Spawns {prog} and opens an |RPC| channel +rpcstop({channel}) Closes an |RPC| {channel} screenattr({row}, {col}) Number attribute at screen position screenchar({row}, {col}) Number character at screen position screencol() Number current cursor column @@ -2192,6 +2198,10 @@ and({expr}, {expr}) *and()* :let flag = and(bits, 0x80) +api_info() *api_info()* + Returns Dictionary of |api-metadata|. + + append({lnum}, {expr}) *append()* When {expr} is a |List|: Append each item of the |List| as a text line below line {lnum} in the current buffer. @@ -2212,7 +2222,7 @@ argidx() The result is the current index in the argument list. 0 is the first file. argc() - 1 is the last one. See |arglist|. *arglistid()* -arglistid([{winnr}, [ {tabnr} ]]) +arglistid([{winnr} [, {tabnr}]]) Return the argument list ID. This is a number which identifies the argument list being used. Zero is used for the global argument list. See |arglist|. @@ -2264,6 +2274,11 @@ assert_exception({error} [, {msg}]) *assert_exception()* call assert_exception('E492:') endtry +assert_fails({cmd} [, {error}]) *assert_fails()* + Run {cmd} and add an error message to |v:errors| if it does + NOT produce an error. + When {error} is given it must match |v:errmsg|. + assert_false({actual} [, {msg}]) *assert_false()* When {actual} is not false an error message is added to |v:errors|, like with |assert_equal()|. @@ -2484,23 +2499,20 @@ call({func}, {arglist} [, {dict}]) *call()* *E699* capture({command}) *capture()* Capture output of {command}. - If {command} is a |String|, it returns {command} output. - If {command} is a |List|, it returns concatenated outputs of - each item. + If {command} is a |String|, returns {command} output. + If {command} is a |List|, returns concatenated outputs. Examples: > - let a = capture('echon "foo"') - echo a + echo capture('echon "foo"') < foo > - let a = capture(['echon "foo"', 'echon "bar"']) - echo a + echo capture(['echon "foo"', 'echon "bar"']) < foobar This function is not available in the |sandbox|. - Note: The commands are run as if they were prepended with - |:silent| modifier. |:redir| and |capture()| work together. - Unlike nested |:redir|s, outer capture will not catch - commands' output of the inner one, but the inner capture will - not cancel the outer. - Note: highlighting is ignored. + Note: {command}s run as if prepended with |:silent| (output is + captured, but not displayed). If multiple capture() calls are + nested, the outer capture() will not catch the command output + of the inner capture(); the inner capture will not cancel the + outer. + Note: Text attributes (highlights) are not captured. ceil({expr}) *ceil()* Return the smallest integral value greater than or equal to @@ -3186,6 +3198,11 @@ feedkeys({string} [, {mode}]) *feedkeys()* if coming from a mapping. This matters for undo, opening folds, etc. '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() + several times without 'x' and then one time with 'x' + (possibly with an empty {string}) to execute all the + typeahead. Return value is always 0. filereadable({file}) *filereadable()* @@ -3597,7 +3614,7 @@ getcmdwintype() *getcmdwintype()* *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] + [bufnum, lnum, col, off, curswant] ~ The "curswant" number is the preferred column when moving the cursor vertically. This can be used to save and restore the cursor position: > @@ -3605,17 +3622,17 @@ getcurpos() Get the position of the cursor. This is like getpos('.'), but MoveTheCursorAround call setpos('.', save_cursor) < -getcwd([{window}[, {tab}]]) *getcwd()* +getcwd([{winnr}[, {tabnr}]]) *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. + the current effective working directory. With {winnr} or + {tabnr} 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. +< If {winnr} is -1 it is ignored, only the tab is resolved. getfsize({fname}) *getfsize()* @@ -3680,7 +3697,8 @@ getftype({fname}) *getftype()* getftype("/home") < Note that a type such as "link" will only be returned on systems that support it. On some systems only "dir" and - "file" are returned. + "file" are returned. On MS-Windows a symbolic link to a + directory returns "dir" instead of "link". *getline()* getline({lnum} [, {end}]) @@ -3953,7 +3971,7 @@ 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([{window}[, {tab}]]) *haslocaldir()* +haslocaldir([{winnr}[, {tabnr}]]) *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. @@ -3964,7 +3982,7 @@ haslocaldir([{window}[, {tab}]]) *haslocaldir()* haslocaldir() haslocaldir(0) haslocaldir(0, 0) -< If {window} is -1 it is ignored, only the tab is resolved. +< If {winnr} 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 @@ -4315,21 +4333,24 @@ jobstart({cmd}[, {opts}]) {Nvim} *jobstart()* with 'shell' or 'shellcmdflag' options. The above call is only written to show the idea, one needs to perform unquoting and do split taking quotes into account. - If passed, {opts} must be a dictionary with any of the - following keys: - - on_stdout: stdout event handler - - on_stderr: stderr event handler - - on_exit: exit event handler - - pty: If set, the job will be connected to a new pseudo - terminal, and the job streams are connected to the master - file descriptor. - - width: Width of the terminal screen(only if pty is set) - - height: Height of the terminal screen(only if pty is set) - - TERM: $TERM environment variable(only if pty is set) - - detach: Detach the job process from the nvim process. The - process won't get killed when nvim exists. If the process - dies before nvim exits, on_exit will still be invoked. - This option is only allowed for non-pty jobs. + + {opts} is a dictionary with these keys: + on_stdout: stdout event handler + on_stderr: stderr event handler + on_exit : exit event handler + cwd : Working directory of the job; defaults to + |current-directory|. + pty : If set, the job will be connected to a new pseudo + terminal, and the job streams are connected to + the master file descriptor. + width : (pty only) Width of the terminal screen + height : (pty only) Height of the terminal screen + TERM : (pty only) $TERM environment variable + detach : (non-pty only) Detach the job process from the + nvim process. The process will not get killed + when nvim exits. If the process dies before + nvim exits, on_exit will still be invoked. + Either funcrefs or function names can be passed as event handlers. The {opts} object is also used as the "self" argument for the callback, so the caller may pass arbitrary @@ -4761,8 +4782,8 @@ matchadd({group}, {pattern}[, {priority}[, {id} [, {dict}]]]) respectively. If the {id} argument is not specified or -1, |matchadd()| automatically chooses a free ID. - The optional {dict} argmument allows for further custom - values. Currently this is used to specify a match specifc + The optional {dict} argument allows for further custom + values. Currently this is used to specify a match specific conceal character that will be shown for |hl-Conceal| highlighted matches. The dict can have the following members: @@ -5528,31 +5549,31 @@ round({expr}) *round()* < -5.0 rpcnotify({channel}, {event}[, {args}...]) {Nvim} *rpcnotify()* - Sends {event} to {channel} via |msgpack-rpc| and returns - immediately. If {channel} is 0, the event is broadcast to all - channels. Example: > + Sends {event} to {channel} via |RPC| and returns immediately. + If {channel} is 0, the event is broadcast to all channels. + Example: > :au VimLeave call rpcnotify(0, "leaving") rpcrequest({channel}, {method}[, {args}...]) {Nvim} *rpcrequest()* Sends a request to {channel} to invoke {method} via - |msgpack-rpc| and blocks until a response is received. + |RPC| and blocks until a response is received. Example: > :let result = rpcrequest(rpc_chan, "func", 1, 2, 3) rpcstart({prog}[, {argv}]) {Nvim} *rpcstart()* Spawns {prog} as a job (optionally passing the list {argv}), - and opens a |msgpack-rpc| channel with the spawned process's - stdin/stdout. It returns: - - The channel id on success, which is used by |rpcrequest()|, + and opens an |RPC| channel with the spawned process's + stdin/stdout. Returns: + - channel id on success, which is used by |rpcrequest()|, |rpcnotify()| and |rpcstop()| - - 0 on failure. + - 0 on failure Example: > :let rpc_chan = rpcstart('prog', ['arg1', 'arg2']) rpcstop({channel}) {Nvim} *rpcstop()* - Closes a |msgpack-rpc| {channel}, possibly created via + Closes an |RPC| {channel}, possibly created via |rpcstart()|. Also closes channels created by connections to - |$NVIM_LISTEN_ADDRESS|. + |v:servername|. screenattr(row, col) *screenattr()* Like screenchar(), but return the attribute. This is a rather @@ -5615,7 +5636,7 @@ search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()* 'ignorecase', 'smartcase' and 'magic' are used. - When the 'z' flag is not given seaching always starts in + When the 'z' flag is not given, searching 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 @@ -6041,7 +6062,7 @@ setqflist({list} [, {action}[, {title}]]) *setqflist()* *setreg()* -setreg({regname}, {value} [,{options}]) +setreg({regname}, {value} [, {options}]) Set the register {regname} to {value}. {value} may be any value returned by |getreg()|, including a |List|. @@ -6222,6 +6243,9 @@ sort({list} [, {func} [, {dict}]]) *sort()* *E702* sorted numerical. This is like 'n' but a string containing digits will be used as the number they represent. + When {func} is given and it is 'f' then all items will be + sorted numerical. All values must be a Number or a Float. + 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 @@ -6840,7 +6864,7 @@ termopen({cmd}[, {opts}]) {Nvim} *termopen()* and `$TERM` is set to "xterm-256color". Returns the same values as |jobstart()|. - See |nvim-terminal-emulator| for more information. + See |terminal-emulator| for more information. tan({expr}) *tan()* Return the tangent of {expr}, measured in radians, as a |Float| @@ -7302,7 +7326,7 @@ dialog_gui Compiled with GUI dialog support. digraphs Compiled with support for digraphs. eval Compiled with expression evaluation support. Always true, of course! -ex_extra Compiled with extra Ex commands |+ex_extra|. +ex_extra |+ex_extra|, always true now extra_search Compiled with support for |'incsearch'| and |'hlsearch'| farsi Compiled with Farsi support |farsi|. @@ -8009,7 +8033,7 @@ This does NOT work: > From Vim version 4.5 until 5.0, every Ex command in between the ":if" and ":endif" is ignored. These two commands were just to allow for future expansions in a - backwards compatible way. Nesting was allowed. Note + backward compatible way. Nesting was allowed. Note that any ":else" or ":elseif" was ignored, the "else" part was not executed either. |