diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 145 |
1 files changed, 82 insertions, 63 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index afa38a493..b813706a5 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 7.2. Last change: 2008 Nov 27 +*eval.txt* For Vim version 7.2. Last change: 2010 Jan 05 VIM REFERENCE MANUAL by Bram Moolenaar @@ -853,7 +853,8 @@ expr8[expr1] item of String or |List| *expr-[]* *E111* If expr8 is a Number or String this results in a String that contains the expr1'th single byte from expr8. expr8 is used as a String, expr1 as a -Number. Note that this doesn't recognize multi-byte encodings. +Number. This doesn't recognize multi-byte encodings, see |byteidx()| for +an alternative. Index zero gives the first character. This is like it works in C. Careful: text column numbers start with one! Example, to get the character under the @@ -878,8 +879,8 @@ expr8[expr1a : expr1b] substring or sublist *expr-[:]* If expr8 is a Number or String this results in the substring with the bytes from expr1a to and including expr1b. expr8 is used as a String, expr1a and -expr1b are used as a Number. Note that this doesn't recognize multi-byte -encodings. +expr1b are used as a Number. This doesn't recognize multi-byte encodings, see +|byteidx()| for computing the indexes. If expr1a is omitted zero is used. If expr1b is omitted the length of the string minus one is used. @@ -895,7 +896,8 @@ Examples: > :let c = name[-2:-2] " last but one byte of a string :let s = line(".")[4:] " from the fifth byte to the end :let s = s[:-3] " remove last two bytes - +< + *sublist* *slice* If expr8 is a |List| this results in a new |List| with the items indicated by the indexes expr1a and expr1b. This works like with a String, as explained just above, except that indexes out of range cause an error. Examples: > @@ -1190,6 +1192,7 @@ They can be used in: Thus not in: - other scripts sourced from this one - mappings +- menus - etc. Script variables can be used to avoid conflicts with global variable names. @@ -1280,7 +1283,8 @@ v:beval_winnr The number of the window, over which the mouse pointer is. Only valid while evaluating the 'balloonexpr' option. *v:char* *char-variable* -v:char Argument for evaluating 'formatexpr'. +v:char Argument for evaluating 'formatexpr' and used for the typed + character when using <expr> in an abbreviation |map-<expr>|. *v:charconvert_from* *charconvert_from-variable* v:charconvert_from @@ -1317,6 +1321,8 @@ v:count The count given for the last Normal mode command. Can be used :map _x :<C-U>echo "the count is " . v:count<CR> < Note: The <C-U> is required to remove the line range that you get when typing ':' after a count. + When there are two counts, as in "3d2w", they are multiplied, + just like what happens in the command, "d6w" for the example. Also used for evaluating the 'formatexpr' option. "count" also works, for backwards compatibility. @@ -1677,9 +1683,9 @@ ceil( {expr}) Float round {expr} up changenr() Number current change number char2nr( {expr}) Number ASCII value of first char in {expr} cindent( {lnum}) Number C indent for line {lnum} -clearmatches() None clear all matches +clearmatches() none clear all matches col( {expr}) Number column nr of cursor or mark -complete({startcol}, {matches}) String set Insert mode completion +complete( {startcol}, {matches}) none set Insert mode completion complete_add( {expr}) Number add completion match complete_check() Number check for key typed during completion confirm( {msg} [, {choices} [, {default} [, {type}]]]) @@ -1704,7 +1710,7 @@ eval( {string}) any evaluate {string} into its value eventhandler( ) Number TRUE if inside an event handler executable( {expr}) Number 1 if executable {expr} exists exists( {expr}) Number TRUE if {expr} exists -extend({expr1}, {expr2} [, {expr3}]) +extend( {expr1}, {expr2} [, {expr3}]) List/Dict insert items of {expr2} into {expr1} expand( {expr} [, {flag}]) String expand special keywords in {expr} feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer @@ -1746,7 +1752,7 @@ getftime( {fname}) Number last modification time of file getftype( {fname}) String description of type of file {fname} getline( {lnum}) String line {lnum} of current buffer getline( {lnum}, {end}) List lines {lnum} to {end} of current buffer -getloclist({nr}) List list of location list items +getloclist( {nr}) List list of location list items getmatches() List list of current matches getpid() Number process ID of Vim getpos( {expr}) List position of cursor, mark, etc. @@ -1815,9 +1821,9 @@ matchlist( {expr}, {pat}[, {start}[, {count}]]) List match and submatches of {pat} in {expr} matchstr( {expr}, {pat}[, {start}[, {count}]]) String {count}'th match of {pat} in {expr} -max({list}) Number maximum value of items in {list} -min({list}) Number minimum value of items in {list} -mkdir({name} [, {path} [, {prot}]]) +max( {list}) Number maximum value of items in {list} +min( {list}) Number minimum value of items in {list} +mkdir( {name} [, {path} [, {prot}]]) Number create directory {name} mode( [expr]) String current editing mode nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum} @@ -1829,7 +1835,7 @@ printf( {fmt}, {expr1}...) String format text pumvisible() Number whether popup menu is visible range( {expr} [, {max} [, {stride}]]) List items from {expr} to {max} -readfile({fname} [, {binary} [, {max}]]) +readfile( {fname} [, {binary} [, {max}]]) List get list of lines from file {fname} reltime( [{start} [, {end}]]) List get time value reltimestr( {time}) String turn time value into a String @@ -1850,7 +1856,7 @@ reverse( {list}) List reverse {list} in-place round( {expr}) Float round off {expr} search( {pattern} [, {flags} [, {stopline} [, {timeout}]]]) Number search for {pattern} -searchdecl({name} [, {global} [, {thisblock}]]) +searchdecl( {name} [, {global} [, {thisblock}]]) Number search for variable declaration searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [...]]]) Number search for other end of start/end pair @@ -1867,7 +1873,7 @@ setline( {lnum}, {line}) Number set line {lnum} to {line} setloclist( {nr}, {list}[, {action}]) Number modify location list using {list} setmatches( {list}) Number restore a list of matches -setpos( {expr}, {list}) none set the {expr} position to {list} +setpos( {expr}, {list}) Number set the {expr} position to {list} setqflist( {list}[, {action}]) Number modify quickfix list using {list} setreg( {n}, {v}[, {opt}]) Number set register to value and type settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window @@ -1905,7 +1911,7 @@ synID( {lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col} synIDattr( {synID}, {what} [, {mode}]) String attribute {what} of syntax ID {synID} synIDtrans( {synID}) Number translated syntax ID of {synID} -synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col} +synstack( {lnum}, {col}) List stack of syntax IDs at {lnum} and {col} system( {expr} [, {input}]) String 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 @@ -1929,10 +1935,10 @@ winheight( {nr}) Number height of window {nr} winline() Number window line of the cursor winnr( [{expr}]) Number number of current window winrestcmd() String returns command to restore window sizes -winrestview({dict}) None restore view of current window +winrestview( {dict}) none restore view of current window winsaveview() Dict save view of current window winwidth( {nr}) Number width of window {nr} -writefile({list}, {fname} [, {binary}]) +writefile( {list}, {fname} [, {binary}]) Number write list of lines to file {fname} abs({expr}) *abs()* @@ -2245,7 +2251,7 @@ complete({startcol}, {matches}) *complete()* *E785* {matches} must be a |List|. Each |List| item is one match. See |complete-items| for the kind of items that are possible. Note that the after calling this function you need to avoid - inserting anything that would completion to stop. + inserting anything that would cause completion to stop. The match can be selected with CTRL-N and CTRL-P as usual with Insert mode completion. The popup menu will appear if specified, see |ins-completion-menu|. @@ -2477,7 +2483,7 @@ 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 then comparing the + For a long |List| this is much faster than comparing the length with zero. escape({string}, {chars}) *escape()* @@ -3053,7 +3059,7 @@ getcharmod() *getcharmod()* 128 Macintosh only: command Only the modifiers that have not been included in the character itself are obtained. Thus Shift-a results in "A" - with no modifier. + without a modifier. getcmdline() *getcmdline()* Return the current command-line. Only works when the command @@ -3181,7 +3187,7 @@ getloclist({nr}) *getloclist()* window {nr}. When {nr} is zero the current window is used. For a location list window, the displayed location list is returned. For an invalid window number {nr}, an empty list is - returned. Otherwise, same as getqflist(). + returned. Otherwise, same as |getqflist()|. getmatches() *getmatches()* Returns a |List| with all matches previously defined by @@ -3478,7 +3484,9 @@ hostname() *hostname()* iconv({expr}, {from}, {to}) *iconv()* The result is a String, which is the text {expr} converted from encoding {from} to encoding {to}. - When the conversion fails an empty string is returned. + When the conversion completely fails an empty string is + returned. When some characters could not be converted they + are replaced with "?". The encoding names are whatever the iconv() library function can accept, see ":!man 3 iconv". Most conversions require Vim to be compiled with the |+iconv| @@ -3503,7 +3511,10 @@ indent({lnum}) The result is a Number, which is indent of line {lnum} in the index({list}, {expr} [, {start} [, {ic}]]) *index()* Return the lowest index in |List| {list} where the item has a - value equal to {expr}. + value equal to {expr}. There is no automatic conversion, so + the String "4" is different from the Number 4. And the number + 4 is different from the Float 4.0. The value of 'ignorecase' + is not used here, case always matters. If {start} is given then start looking at the item with index {start} (may be negative for an item relative to the end). When {ic} is given and it is non-zero, ignore case. Otherwise @@ -3516,9 +3527,9 @@ index({list}, {expr} [, {start} [, {ic}]]) *index()* input({prompt} [, {text} [, {completion}]]) *input()* The result is a String, which is whatever the user typed on - the command-line. The parameter is either a prompt string, or - a blank string (for no prompt). A '\n' can be used in the - prompt to start a new line. + the command-line. The {prompt} argument is either a prompt + string, or a blank string (for no prompt). A '\n' can be used + in the prompt to start a new line. The highlighting set with |:echohl| is used for the prompt. The input is entered just like a command-line, with the same editing commands and mappings. There is a separate history @@ -3528,8 +3539,9 @@ input({prompt} [, {text} [, {completion}]]) *input()* : echo "Cheers!" :endif < - If the optional {text} is present and not empty, this is used - for the default reply, as if the user typed this. Example: > + If the optional {text} argument is present and not empty, this + is used for the default reply, as if the user typed this. + Example: > :let color = input("Color? ", "white") < The optional {completion} argument specifies the type of @@ -3559,8 +3571,8 @@ input({prompt} [, {text} [, {completion}]]) *input()* :endfunction inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()* - Like input(), but when the GUI is running and text dialogs are - supported, a dialog window pops up to input the text. + Like |input()|, but when the GUI is running and text dialogs + are supported, a dialog window pops up to input the text. Example: > :let n = inputdialog("value for shiftwidth", &sw) :if n != "" @@ -3581,7 +3593,7 @@ inputlist({textlist}) *inputlist()* above the first item a negative number is returned. When clicking on the prompt one more than the length of {textlist} is returned. - Make sure {textlist} has less then 'lines' entries, otherwise + Make sure {textlist} has less than 'lines' entries, otherwise it won't work. It's a good idea to put the entry number at the start of the string. And put a prompt in the first item. Example: > @@ -3589,7 +3601,7 @@ inputlist({textlist}) *inputlist()* \ '2. green', '3. blue']) inputrestore() *inputrestore()* - Restore typeahead that was saved with a previous inputsave(). + Restore typeahead that was saved with a previous |inputsave()|. Should be called the same number of times inputsave() is called. Calling it more often is harmless though. Returns 1 when there is nothing to restore, 0 otherwise. @@ -3719,14 +3731,14 @@ libcall({libname}, {funcname}, {argument}) the DLL is not in the usual places. For Unix: When compiling your own plugins, remember that the object code must be compiled as position-independent ('PIC'). - {only in Win32 on some Unix versions, when the |+libcall| + {only in Win32 and some Unix versions, when the |+libcall| feature is present} Examples: > :echo libcall("libc.so", "getenv", "HOME") < *libcallnr()* libcallnr({libname}, {funcname}, {argument}) - Just like libcall(), but used for a function that returns an + Just like |libcall()|, but used for a function that returns an int instead of a string. {only in Win32 on some Unix versions, when the |+libcall| feature is present} @@ -3759,7 +3771,7 @@ line({expr}) The result is a Number, which is the line number of the file < *last-position-jump* This autocommand jumps to the last known position in a file just after opening it, if the '" mark is set: > - :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g'\"" | endif + :au BufReadPost * if line("'\"") > 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif line2byte({lnum}) *line2byte()* Return the byte count from the start of the buffer for line @@ -3990,8 +4002,8 @@ matchdelete({id}) *matchdelete()* *E802* *E803* be deleted in one operation by |clearmatches()|. matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()* - Same as match(), but return the index of first character after - the match. Example: > + Same as |match()|, but return the index of first character + after the match. Example: > :echo matchend("testing", "ing") < results in "7". *strspn()* *strcspn()* @@ -4001,15 +4013,15 @@ matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()* :let span = matchend(line, '[^a-zA-Z]') < Except that -1 is returned when there are no matches. - The {start}, if given, has the same meaning as for match(). > + The {start}, if given, has the same meaning as for |match()|. > :echo matchend("testing", "ing", 2) < results in "7". > :echo matchend("testing", "ing", 5) < result is "-1". - When {expr} is a |List| the result is equal to match(). + When {expr} is a |List| the result is equal to |match()|. matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()* - Same as match(), but return a |List|. The first item in the + Same as |match()|, but return a |List|. The first item in the list is the matched string, same as what matchstr() would return. Following items are submatches, like "\1", "\2", etc. in |:substitute|. When an optional submatch didn't match an @@ -4023,7 +4035,7 @@ matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()* :echo matchstr("testing", "ing") < results in "ing". When there is no match "" is returned. - The {start}, if given, has the same meaning as for match(). > + The {start}, if given, has the same meaning as for |match()|. > :echo matchstr("testing", "ing", 2) < results in "ing". > :echo matchstr("testing", "ing", 5) @@ -4497,9 +4509,9 @@ remote_send({server}, {string} [, {idvar}]) < remove({list}, {idx} [, {end}]) *remove()* Without {end}: Remove the item at {idx} from |List| {list} and - return it. + return the item. With {end}: Remove items from {idx} to {end} (inclusive) and - return a list with these items. When {idx} points to the same + return a List with these items. When {idx} points to the same item as {end} a list with one item is returned. When {end} points to an item before {idx} this is an error. See |list-index| for possible values of {idx} and {end}. @@ -4750,7 +4762,7 @@ searchpair({start}, {middle}, {end} [, {flags} [, {skip} *searchpairpos()* searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline} [, {timeout}]]]]) - Same as searchpair(), but returns a |List| with the line and + Same as |searchpair()|, but returns a |List| with the line and column position of the match. The first element of the |List| is the line number and the second element is the byte index of the column position of the match. If no match is found, @@ -4870,7 +4882,8 @@ setpos({expr}, {list}) Does not change the jumplist. "lnum" and "col" are the position in the buffer. The first - column is 1. Use a zero "lnum" to delete a mark. + column is 1. Use a zero "lnum" to delete a mark. If "col" is + smaller than 1 then 1 is used. The "off" number is only used when 'virtualedit' is set. Then it is the offset in screen columns from the start of the @@ -4989,7 +5002,7 @@ setwinvar({nr}, {varname}, {val}) *setwinvar()* :call setwinvar(2, "myvar", "foobar") shellescape({string} [, {special}]) *shellescape()* - Escape {string} for use as shell command argument. + Escape {string} for use as a shell command argument. On MS-Windows and MS-DOS, when 'shellslash' is not set, it will enclose {string} in double quotes and double all double quotes within {string}. @@ -5051,15 +5064,20 @@ sort({list} [, {func}]) *sort()* *E702* When {func} is given and it is one then case is ignored. 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 if - the first one sorts after the second one, -1 if the first one - sorts before the second one. Example: > + items as argument and must return zero if they are equal, 1 or + bigger if the first one sorts after the second one, -1 or + smaller if the first one sorts before the second one. + Example: > func MyCompare(i1, i2) return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 endfunc let sortedlist = sort(mylist, "MyCompare") +< A shorter compare version for this specific simple case, which + ignores overflow: > + func MyCompare(i1, i2) + return a:i1 - a:i2 + endfunc < - *soundfold()* soundfold({word}) Return the sound-folded equivalent of {word}. Uses the first @@ -5508,10 +5526,7 @@ tempname() *tempname()* *temp-file-name* is different for at least 26 consecutive calls. Example: > :let tmpfile = tempname() :exe "redir > " . tmpfile -< For Unix, the file will be in a private directory (only - accessible by the current user) to avoid security problems - (e.g., a symlink attack or other people reading your file). - When Vim exits the directory and all files in it are deleted. +< For Unix, the file will be in a private directory |tempfile|. For MS-Windows forward slashes are used when the 'shellslash' option is set or when 'shellcmdflag' starts with '-'. @@ -6575,15 +6590,19 @@ This would call the function "my_func_whizz(parameter)". removed without effect. Removing any later item means it will not be found. Thus the following example works (an inefficient way to make a list empty): > - :for item in mylist - :call remove(mylist, 0) - :endfor + for item in mylist + call remove(mylist, 0) + endfor < Note that reordering the list (e.g., with sort() or reverse()) may have unexpected effects. Note that the type of each list item should be identical to avoid errors for the type of {var} changing. Unlet the variable at the end of the loop - to allow multiple item types. + to allow multiple item types: > + for item in ["foo", ["bar"]] + echo item + unlet item " E706 without this + endfor :for [{var1}, {var2}, ...] in {listlist} :endfo[r] @@ -6652,7 +6671,7 @@ This would call the function "my_func_whizz(parameter)". :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry < *:cat* *:catch* *E603* *E604* *E605* -:cat[ch] /{pattern}/ The following commands until the next ":catch", +:cat[ch] /{pattern}/ The following commands until the next |:catch|, |:finally|, or |:endtry| that belongs to the same |:try| as the ":catch" are executed when an exception matching {pattern} is being thrown and has not yet @@ -6825,7 +6844,7 @@ This would call the function "my_func_whizz(parameter)". :execute 'while i < 5 | echo i | let i = i + 1 | endwhile' < - *:comment* + *:exe-comment* ":execute", ":echo" and ":echon" cannot be followed by a comment directly, because they see the '"' as the start of a string. But, you can use '|' followed by a @@ -7831,7 +7850,7 @@ a "E600: Missing :endtry" error message is given, see |except-single-line|. Printing in Binary ~ > - :" The function Nr2Bin() returns the Hex string of a number. + :" The function Nr2Bin() returns the binary string representation of a number. :func Nr2Bin(nr) : let n = a:nr : let r = "" |