diff -Nrudb /home/dindinx/Web/dindinx/vim/orig/eval.txt doc/eval.txt --- /home/dindinx/Web/dindinx/vim/orig/eval.txt 2006-09-04 21:44:11.000000000 +0200 +++ doc/eval.txt 2007-04-23 21:57:12.000000000 +0200 @@ -873,52 +1695,112 @@ remote_read( {serverid}) String read reply string remote_send( {server}, {string} [, {idvar}]) String send key sequence +remove( {list}, {idx} [, {end}]) any remove items {idx}-{end} from {list} +remove( {dict}, {key}) any remove entry {key} from {dict} rename( {from}, {to}) Number rename (move) file from {from} to {to} +repeat( {expr}, {count}) String repeat {expr} {count} times resolve( {filename}) String get filename a shortcut points to +reverse( {list}) List reverse {list} in-place search( {pattern} [, {flags}]) Number search for {pattern} -searchpair( {start}, {middle}, {end} [, {flags} [, {skip}]]) +searchdecl({name} [, {global} [, {thisblock}]]) + Number search for variable declaration +searchpair( {start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]]) Number search for other end of start/end pair +searchpairpos( {start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]]) + List search for other end of start/end pair +searchpos( {pattern} [, {flags} [, {stopline}]]) + List search for {pattern} server2client( {clientid}, {string}) Number send reply string serverlist() String get a list of available servers setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val} +setcmdpos( {pos}) Number set cursor position in command-line setline( {lnum}, {line}) Number set line {lnum} to {line} +setloclist( {nr}, {list}[, {action}]) + Number modify location list using {list} +setpos( {expr}, {list}) none 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 + {winnr} in tab page {tabnr} to {val} setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val} +shellescape( {string}) String escape {string} for use as shell + command argument +simplify( {filename}) String simplify filename as much as possible +sort( {list} [, {func}]) List sort {list}, using {func} to compare +soundfold( {word}) String sound-fold {word} +spellbadword() String badly spelled word at cursor +spellsuggest( {word} [, {max} [, {capital}]]) + List spelling suggestions +split( {expr} [, {pat} [, {keepempty}]]) + List make |List| from {pat} separated {expr} +str2nr( {expr} [, {base}]) Number convert string to number strftime( {format}[, {time}]) String time in specified format -stridx( {haystack}, {needle}) Number first index of {needle} in {haystack} +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( {src}, {start}[, {len}]) String {len} characters of {src} at {start} -strridx( {haystack}, {needle}) Number last index of {needle} in {haystack} +strridx( {haystack}, {needle} [, {start}]) + Number last index of {needle} in {haystack} strtrans( {expr}) String translate string to make it printable submatch( {nr}) String specific match in ":substitute" substitute( {expr}, {pat}, {sub}, {flags}) String all {pat} in {expr} replaced with {sub} -synID( {line}, {col}, {trans}) Number syntax ID at {line} and {col} +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} -system( {expr}) String output of shell command {expr} +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 +tabpagewinnr( {tabarg}[, {arg}]) + Number number of current window in tab page +taglist( {expr}) List list of tags matching {expr} +tagfiles() List tags files used tempname() String name for a temporary file 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} type( {name}) Number type of variable {name} +values( {dict}) List values in {dict} virtcol( {expr}) Number screen column of cursor or mark visualmode( [expr]) String last visual mode used winbufnr( {nr}) Number buffer number of window {nr} wincol() Number window column of the cursor winheight( {nr}) Number height of window {nr} winline() Number window line of the cursor -winnr() Number number of current window +winnr( [{expr}]) Number number of current window +winrestcmd() String returns command to restore window sizes +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}]) + Number write list of lines to file {fname} + +add({list}, {expr}) *add()* + Append the item {expr} to |List| {list}. Returns the + resulting |List|. Examples: > + :let alist = add([1, 2, 3], item) + :call add(mylist, "woodstock") +< Note that when {expr} is a |List| it is appended as a single + item. Use |extend()| to concatenate |Lists|. + Use |insert()| to add an item at another position. -append({lnum}, {string}) *append()* - Append the text {string} after line {lnum} in the current - buffer. {lnum} can be zero, to insert a line before the first - one. Returns 1 for failure ({lnum} out of range) or 0 for - success. +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. + Otherwise append {expr} as one text line below line {lnum} in + the current buffer. + {lnum} can be zero to insert a line before the first one. + Returns 1 for failure ({lnum} out of range or out of memory), + 0 for success. Example: > + :let failed = append(line('$'), "# THE END") + :let failed = append(0, ["Chapter 1", "the beginning"]) +< *argc()* argc() The result is the number of files in the argument list of the current window. See |arglist|. @@ -928,7 +1810,7 @@ the first file. argc() - 1 is the last one. See |arglist|. *argv()* -argv({nr}) The result is the {nr}th file in the argument list of the +argv([{nr}]) The result is the {nr}th file in the argument list of the current window. See |arglist|. "argv(0)" is the first one. Example: > :let i = 0 @@ -937,7 +1819,9 @@ : exe 'amenu Arg.' . f . ' :e ' . f . '' : let i = i + 1 :endwhile -< +< Without the {nr} argument a |List| with the whole |arglist| is + returned. + *browse()* browse({save}, {title}, {initdir}, {default}) Put up a file requester. This only works when "has("browse")" @@ -950,12 +1834,29 @@ When the "Cancel" button is hit, something went wrong, or browsing is not possible, an empty string is returned. + *browsedir()* +browsedir({title}, {initdir}) + Put up a directory requester. This only works when + "has("browse")" returns non-zero (only in some GUI versions). + On systems where a directory browser is not supported a file + browser is used. In that case: select a file in the directory + to be used. + The input fields are: + {title} title for the requester + {initdir} directory to start browsing in + When the "Cancel" button is hit, something went wrong, or + browsing is not possible, an empty string is returned. + bufexists({expr}) *bufexists()* The result is a Number, which is non-zero if a buffer called {expr} exists. + If the {expr} argument is a number, buffer numbers are used. If the {expr} argument is a string it must match a buffer name - exactly. - If the {expr} argument is a number buffer numbers are used. + exactly. The name can be: + - Relative to the current directory. + - A full path. + - The name of a buffer with 'filetype' set to "nofile". + - A URL name. Unlisted buffers will be found. Note that help files are listed by their short name in the output of |:buffers|, but bufexists() requires using their @@ -968,19 +1869,19 @@ buflisted({expr}) *buflisted()* The result is a Number, which is non-zero if a buffer called {expr} exists and is listed (has the 'buflisted' option set). - The {expr} argument is used like with bufexists(). + The {expr} argument is used like with |bufexists()|. bufloaded({expr}) *bufloaded()* The result is a Number, which is non-zero if a buffer called {expr} exists and is loaded (shown in a window or hidden). - The {expr} argument is used like with bufexists(). + The {expr} argument is used like with |bufexists()|. bufname({expr}) *bufname()* The result is the name of a buffer, as it is displayed by the ":ls" command. If {expr} is a Number, that buffer number's name is given. Number zero is the alternate buffer for the current window. - If {expr} is a String, it is used as a regexp pattern to match + If {expr} is a String, it is used as a |file-pattern| to match with the buffer names. This is always done like 'magic' is set and 'cpoptions' is empty. When there is more than one match an empty string is returned. @@ -1004,9 +1905,13 @@ Obsolete name: buffer_name(). *bufnr()* -bufnr({expr}) The result is the number of a buffer, as it is displayed by +bufnr({expr} [, {create}]) + The result is the number of a buffer, as it is displayed by the ":ls" command. For the use of {expr}, see |bufname()| - above. If the buffer doesn't exist, -1 is returned. + above. + If the buffer doesn't exist, -1 is returned. Or, if the + {create} argument is present and not zero, a new, unlisted, + buffer is created and its number is returned. bufnr("$") is the last buffer: > :let last_buffer = bufnr("$") < The result is a Number, which is the highest buffer number @@ -1023,8 +1928,13 @@ window associated with buffer {expr}. For the use of {expr}, see |bufname()| above. If buffer {expr} doesn't exist or there is no such window, -1 is returned. Example: > + echo "A window containing buffer 1 is " . (bufwinnr(1)) -< + +< The number can be used with |CTRL-W_w| and ":wincmd w" + |:wincmd|. + + byte2line({byte}) *byte2line()* Return the line number that contains the character at byte count {byte} in the current buffer. This includes the @@ -1035,13 +1945,47 @@ {not available when compiled without the |+byte_offset| feature} +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. + This function is only useful when there are multibyte + characters, otherwise the returned value is equal to {nr}. + Composing characters are counted as a separate character. + Example : > + echo matchstr(str, ".", byteidx(str, 3)) +< will display the fourth character. Another way to do the + same: > + let s = strpart(str, byteidx(str, 3)) + echo strpart(s, 0, byteidx(s, 1)) +< If there are less than {nr} characters -1 is returned. + If there are exactly {nr} characters the length of the string + is returned. + +call({func}, {arglist} [, {dict}]) *call()* *E699* + Call function {func} with the items in |List| {arglist} as + arguments. + {func} can either be a |Funcref| or the name of a function. + a:firstline and a:lastline are set to the cursor line. + Returns the return value of the called function. + {dict} is for functions with the "dict" attribute. It will be + used to set the local variable "self". |Dictionary-function| + +changenr() *changenr()* + Return the number of the most recent change. This is the same + number as what is displayed with |:undolist| and can be used + with the |:undo| command. + When a change was made it is the number of that change. After + redo it is the number of the redone change. After undo it is + one less than the number of the undone change. + char2nr({expr}) *char2nr()* Return number value of the first char in {expr}. Examples: > char2nr(" ") returns 32 char2nr("ABC") returns 65 < The current 'encoding' is used. Example for "utf-8": > - char2nr("á") returns 225 - char2nr("á"[0]) returns 195 + char2nr("?") returns 225 + char2nr("?"[0]) returns 195 +< nr2char() does the opposite. cindent({lnum}) *cindent()* Get the amount of indent for line {lnum} according the C @@ -1050,15 +1994,19 @@ relevant. {lnum} is used just like in |getline()|. When {lnum} is invalid or Vim was not compiled the |+cindent| feature, -1 is returned. + See |C-indenting|. *col()* -col({expr}) The result is a Number, which is the column of the file +col({expr}) The result is a Number, which is the byte index of the column position given with {expr}. The accepted positions are: . the cursor position $ the end of the cursor line (the result is the number of characters in the cursor line plus one) 'x position of mark x (if the mark is not set, 0 is returned) + To get the line number use |col()|. To get both use + |getpos()|. + For the screen column position use |virtcol()|. Note that only marks in the current file can be used. Examples: > col(".") column of cursor @@ -1074,6 +2022,53 @@ \:echo col(".") . "\n" \let &ve = save_ve < + +complete({startcol}, {matches}) *complete()* *E785* + Set the matches for Insert mode completion. + Can only be used in Insert mode. You need to use a mapping + with an expression argument |:map-| or CTRL-R = + |i_CTRL-R|. It does not work after CTRL-O. + {startcol} is the byte offset in the line where the completed + text start. The text up to the cursor is the original text + that will be replaced by the matches. Use col('.') for an + empty string. "col('.') - 1" will replace one character by a + match. + {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. + 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|. + Example: > + inoremap ListMonths() + + func! ListMonths() + call complete(col('.'), ['January', 'February', 'March', + \ 'April', 'May', 'June', 'July', 'August', 'September', + \ 'October', 'November', 'December']) + return '' + endfunc +< This isn't very useful, but it shows how it works. Note that + an empty string is returned to avoid a zero being inserted. + +complete_add({expr}) *complete_add()* + Add {expr} to the list of matches. Only to be used by the + function specified with the 'completefunc' option. + Returns 0 for failure (empty string or out of memory), + 1 when the match was added, 2 when the match was already in + the list. + See |complete-functions| for an explanation of {expr}. It is + the same as one item in the list that 'omnifunc' would return. + +complete_check() *complete_check()* + Check for a key typed while looking for completion matches. + This is to be used when looking for matches takes some time. + Returns non-zero when searching for matches is to be aborted, + zero otherwise. + Only to be used by the function specified with the + 'completefunc' option. + *confirm()* confirm({msg} [, {choices} [, {default} [, {type}]]]) Confirm() offers the user a dialog, from which a choice can be @@ -1090,7 +2085,7 @@ by '\n', e.g. > confirm("Save changes?", "&Yes\n&No\n&Cancel") < The letter after the '&' is the shortcut key for that choice. - Thus you can type 'c' to select "Cancel". The shorcut does + Thus you can type 'c' to select "Cancel". The shortcut does not need to be the first letter: > confirm("file has been modified", "&Save\nSave &All") < For the console, the first letter of each choice is used as @@ -1098,7 +2093,7 @@ The optional {default} argument is the number of the choice that is made if the user hits . Use 1 to make the first choice the default one. Use 0 to not set a default. If - {default} is omitted, 0 is used. + {default} is omitted, 1 is used. The optional {type} argument gives the type of dialog. This is only used for the icon of the Win32 GUI. It can be one of these values: "Error", "Question", "Info", "Warning" or @@ -1123,6 +2118,23 @@ don't fit, a vertical layout is used anyway. For some systems the horizontal layout is always used. + *copy()* +copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't + different from using {expr} directly. + When {expr} is a |List| a shallow copy is created. This means + that the original |List| can be changed without changing the + copy, and vise versa. But the items are identical, thus + changing an item changes the contents of both |Lists|. Also + see |deepcopy()|. + +count({comp}, {expr} [, {ic} [, {start}]]) *count()* + Return the number of times an item with value {expr} appears + in |List| or |Dictionary| {comp}. + If {start} is given then start with the item with this index. + {start} can only be used with a |List|. + When {ic} is given and it's non-zero then case is ignored. + + *cscope_connection()* cscope_connection([{num} , {dbpath} [, {prepend}]]) Checks for the existence of a |cscope| connection. If no @@ -1153,7 +2165,7 @@ # pid database name prepend path 0 27664 cscope.out /usr/local < - Invokation Return Val ~ + Invocation Return Val ~ ---------- ---------- > cscope_connection() 1 cscope_connection(1, "out") 1 @@ -1164,21 +2176,50 @@ cscope_connection(4, "out", "local") 0 cscope_connection(4, "cscope.out", "/usr/local") 1 < -cursor({lnum}, {col}) *cursor()* +cursor({lnum}, {col} [, {off}]) *cursor()* +cursor({list}) Positions the cursor at the column {col} in the line {lnum}. + The first column is one. + When there is one argument {list} this is used as a |List| + with two or three items {lnum}, {col} and {off}. This is like + the return value of |getpos()|, but without the first item. Does not change the jumplist. If {lnum} is greater than the number of lines in the buffer, the cursor will be positioned at the last line in the buffer. If {lnum} is zero, the cursor will stay in the current line. - If {col} is greater than the number of characters in the line, + If {col} is greater than the number of bytes in the line, the cursor will be positioned at the last character in the line. If {col} is zero, the cursor will stay in the current column. + When 'virtualedit' is used {off} specifies the offset in + screen columns from the start of the character. E.g., a + position within a Tab or after the last character. - *delete()* -delete({fname}) Deletes the file by the name {fname}. The result is a Number, + +deepcopy({expr}[, {noref}]) *deepcopy()* *E698* + Make a copy of {expr}. For Numbers and Strings this isn't + different from using {expr} directly. + When {expr} is a |List| a full copy is created. This means + that the original |List| can be changed without changing the + copy, and vise versa. When an item is a |List|, a copy for it + is made, recursively. Thus changing an item in the copy does + not change the contents of the original |List|. + When {noref} is omitted or zero a contained |List| or + |Dictionary| is only copied once. All references point to + this single copy. With {noref} set to 1 every occurrence of a + |List| or |Dictionary| results in a new copy. This also means + that a cyclic reference causes deepcopy() to fail. + *E724* + Nesting is possible up to 100 levels. When there is an item + that refers back to a higher level making a deep copy with + {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|. *did_filetype()* did_filetype() Returns non-zero when autocommands are being executed and the @@ -1188,34 +2229,83 @@ When editing another file, the counter is reset, thus this really checks if the FileType event has been triggered for the current buffer. This allows an autocommand that starts - editing another buffer to set 'filetype' and load a sytnax + editing another buffer to set 'filetype' and load a syntax file. +diff_filler({lnum}) *diff_filler()* + Returns the number of filler lines above line {lnum}. + These are the lines that were inserted at this point in + another diff'ed window. These filler lines are shown in the + display but don't exist in the buffer. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. + Returns 0 if the current window is not in diff mode. + +diff_hlID({lnum}, {col}) *diff_hlID()* + Returns the highlight ID for diff mode at line {lnum} column + {col} (byte index). When the current line does not have a + diff change zero is returned. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. + {col} is 1 for the leftmost column, {lnum} is 1 for the first + line. + The highlight ID can be used with |synIDattr()| to obtain + syntax information about the highlighting. + +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 + length with zero. + escape({string}, {chars}) *escape()* Escape the characters in {chars} that occur in {string} with a backslash. Example: > :echo escape('c:\program files\vim', ' \') < results in: > c:\\program\ files\\vim -< + +< *eval()* +eval({string}) Evaluate {string} and return the result. Especially useful to + turn the result of |string()| back into the original value. + This works for Numbers, Strings and composites of them. + Also works for |Funcref|s that refer to existing functions. + eventhandler() *eventhandler()* - Returns 1 when inside an event handler. This means - interactive commands cannot be used. Otherwise zero is - returned. + Returns 1 when inside an event handler. That is that Vim got + interrupted while waiting for the user to type a character, + e.g., when dropping a file on Vim. This means interactive + commands cannot be used. Otherwise zero is returned. executable({expr}) *executable()* This function checks if an executable with the name {expr} exists. {expr} must be the name of the program without any - arguments. executable() uses the normal $PATH. + arguments. + executable() uses the value of $PATH and/or the normal + searchpath for programs. *PATHEXT* + On MS-DOS and 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 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. + On MS-DOS and MS-Windows it only checks if the file exists and + is not a directory, not if it's really executable. + On MS-Windows an executable in the same directory as Vim is + always found. Since this directory is added to $PATH it + should also work to execute it |win32-PATH|. The result is a Number: 1 exists 0 does not exist -1 not implemented on this system *exists()* -exists({expr}) The result is a Number, which is non-zero if {var} is defined, - zero otherwise. The {expr} argument is a string, which - contains one of these: +exists({expr}) The result is a Number, which is non-zero if {expr} is + defined, zero otherwise. The {expr} argument is a string, + which contains one of these: &option-name Vim option (only checks if it exists, not if it really works) +option-name Vim option that works. @@ -1226,20 +2316,37 @@ or user defined function (see |user-functions|). varname internal variable (see - |internal-variables|). Does not work - for |curly-braces-names|. - :cmdname Ex command, both built-in and user - commands |:command| - returns: + |internal-variables|). Also works + for |curly-braces-names|, |Dictionary| + entries, |List| items, etc. Beware + that this may cause functions to be + invoked cause an error message for an + invalid expression. + :cmdname Ex command: built-in command, user + command or command modifier |:command|. + Returns: 1 for match with start of a command 2 full match with a command 3 matches several user commands + To check for a supported command + always check the return value to be 2. + :2match The |:2match| command. + :3match The |:3match| command. #event autocommand defined for this event #event#pattern autocommand defined for this event and pattern (the pattern is taken literally and compared to the autocommand patterns character by character) + #group autocommand group exists + #group#event autocommand defined for this group and + event. + #group#event#pattern + autocommand defined for this group, + event and pattern. + ##event autocommand for this event is + supported. + For checking for a supported feature use |has()|. Examples: > exists("&shortname") @@ -1248,16 +2355,27 @@ exists("*s:MyFunc") exists("bufcount") exists(":Make") - exists("#CursorHold"); + exists("#CursorHold") exists("#BufReadPre#*.gz") + exists("#filetypeindent") + exists("#filetypeindent#FileType") + exists("#filetypeindent#FileType#*") + exists("##ColorScheme") < There must be no space between the symbol (&/$/*/#) and the name. - Note that the argument must be a string, not the name of the - variable itself! For example: > + There must be no extra characters after the name, although in + a few cases this is ignored. That may become more strict in + the future, thus don't count on it! + Working example: > + exists(":make") +< NOT working example: > + exists(":make install") + +< Note that the argument must be a string, not the name of the + variable itself. For example: > exists(bufcount) < This doesn't check for existence of the "bufcount" variable, - but gets the contents of "bufcount", and checks if that - exists. + but gets the value of "bufcount", and checks if that exists. expand({expr} [, {flag}]) *expand()* Expand wildcards and the following special keywords in {expr}. @@ -1319,17 +2437,73 @@ expanded like a file name is expanded on the command line. 'suffixes' and 'wildignore' are used, unless the optional {flag} argument is given and it is non-zero. Names for - non-existing files are included. - + non-existing files are included. The "**" item can be used to + search in a directory tree. For example, to find all "README" + files in the current directory and below: > + :echo expand("**/README") +< Expand() can also be used to expand variables and environment variables that are only known in a shell. But this can be slow, because a shell must be started. See |expr-env-expand|. The expanded variable is still handled like a list of file - names. + names. When an environment variable cannot be expanded, it is + left unchanged. Thus ":echo expand('$FOOBAR')" results in + "$FOOBAR". See |glob()| for finding existing files. See |system()| for getting the raw output of an external command. +extend({expr1}, {expr2} [, {expr3}]) *extend()* + {expr1} and {expr2} must be both |Lists| or both + |Dictionaries|. + + If they are |Lists|: Append {expr2} to {expr1}. + If {expr3} is given insert the items of {expr2} before item + {expr3} in {expr1}. When {expr3} is zero insert before the + first item. When {expr3} is equal to len({expr1}) then + {expr2} is appended. + Examples: > + :echo sort(extend(mylist, [7, 5])) + :call extend(mylist, [2, 3], 1) +< Use |add()| to concatenate one item to a list. To concatenate + two lists into a new list use the + operator: > + :let newlist = [1, 2, 3] + [4, 5] +< + If they are |Dictionaries|: + Add all entries from {expr2} to {expr1}. + If a key exists in both {expr1} and {expr2} then {expr3} is + used to decide what to do: + {expr3} = "keep": keep the value of {expr1} + {expr3} = "force": use the value of {expr2} + {expr3} = "error": give an error message *E737* + When {expr3} is omitted then "force" is assumed. + + {expr1} is changed when {expr2} is not empty. If necessary + make a copy of {expr1} first. + {expr2} remains unchanged. + Returns {expr1}. + + +feedkeys({string} [, {mode}]) *feedkeys()* + Characters in {string} are queued for processing as if they + come from a mapping or were typed by user. They are added to + the end of the typeahead buffer, thus if a mapping is still + being executed these characters come after them. + The function does not wait for processing of keys contained in + {string}. + To include special keys into {string}, use double-quotes + and "\..." notation |expr-quote|. For example, + feedkeys("\") simulates pressing of the Enter key. But + feedkeys('\') pushes 5 characters. + If {mode} is absent, keys are remapped. + {mode} is a String, which can contain these character flags: + 'm' Remap keys. This is default. + 'n' Do not remap keys. + 't' Handle keys as if typed; otherwise they are handled as + if coming from a mapping. This matters for undo, + opening folds, etc. + Return value is always 0. + filereadable({file}) *filereadable()* The result is a Number, which is TRUE when a file with the name {file} exists, and can be read. If {file} doesn't exist, @@ -1338,6 +2512,56 @@ *file_readable()* Obsolete name: file_readable(). + +filter({expr}, {string}) *filter()* + {expr} must be a |List| or a |Dictionary|. + For each item in {expr} evaluate {string} and when the result + is zero remove the item from the |List| or |Dictionary|. + Inside {string} |v:val| has the value of the current item. + For a |Dictionary| |v:key| has the key of the current item. + Examples: > + :call filter(mylist, 'v:val !~ "OLD"') +< Removes the items where "OLD" appears. > + :call filter(mydict, 'v:key >= 8') +< Removes the items with a key below 8. > + :call filter(var, 0) +< Removes all the items, thus clears the |List| or |Dictionary|. + + Note that {string} is the result of expression and is then + used as an expression again. Often it is good to use a + |literal-string| to avoid having to double backslashes. + + The operation is done in-place. If you want a |List| or + |Dictionary| to remain unmodified make a copy first: > + :let l = filter(copy(mylist), 'v:val =~ "KEEP"') + +< Returns {expr}, the |List| or |Dictionary| that was filtered. + When an error is encountered while evaluating {string} no + further items in {expr} are processed. + + +finddir({name}[, {path}[, {count}]]) *finddir()* + Find directory {name} in {path}. Supports both downwards and + upwards recursive directory searches. See |file-searching| + for the syntax of {path}. + Returns the path of the first found match. When the found + directory is below the current directory a relative path is + returned. Otherwise a full path is returned. + If {path} is omitted or empty then 'path' is used. + If the optional {count} is given, find {count}'s occurrence of + {name} in {path} instead of the first one. + When {count} is negative return all the matches in a |List|. + This is quite similar to the ex-command |:find|. + {only available when compiled with the +file_in_path feature} + +findfile({name}[, {path}[, {count}]]) *findfile()* + Just like |finddir()|, but find a file instead of a directory. + Uses 'suffixesadd'. + Example: > + :echo findfile("tags.vim", ".;") +< Searches from the current directory upwards until it finds + the file "tags.vim". + filewritable({file}) *filewritable()* The result is a Number, which is 1 when a file with the name {file} exists, and can be written. If {file} doesn't @@ -1372,7 +2596,8 @@ returned. It doesn't matter if the folds are open or closed. When used while updating folds (from 'foldexpr') -1 is returned for lines where folds are still to be updated and the - foldlevel is unknown. + foldlevel is unknown. As a special case the level of the + previous line is usually available. *foldtext()* foldtext() Returns a String, to be displayed for a closed fold. This is @@ -1388,6 +2613,16 @@ options is removed. {not available when compiled without the |+folding| feature} +foldtextresult({lnum}) *foldtextresult()* + Returns the text that is displayed for the closed fold at line + {lnum}. Evaluates 'foldtext' in the appropriate context. + When there is no closed fold at {lnum} an empty string is + returned. + {lnum} is used like with |getline()|. Thus "." is the current + line, "'m" mark m, etc. + Useful when exporting folded text, e.g., to HTML. + {not available when compiled without the |+folding| feature} + *foreground()* foreground() Move the Vim window to the foreground. Useful when sent from a client to a Vim server. |remote_send()| @@ -1397,27 +2632,104 @@ {only in the Win32, Athena, Motif and GTK GUI versions and the Win32 console version} + +function({name}) *function()* *E700* + Return a |Funcref| variable that refers to function {name}. + {name} can be a user defined function or an internal function. + + +garbagecollect() *garbagecollect()* + Cleanup unused |Lists| and |Dictionaries| that have circular + references. There is hardly ever a need to invoke this + function, as it is automatically done when Vim runs out of + memory or is waiting for the user to press a key after + 'updatetime'. Items without circular references are always + freed when they become unused. + This is useful if you have deleted a very big |List| and/or + |Dictionary| with circular references in a script that runs + for a long time. + +get({list}, {idx} [, {default}]) *get()* + Get item {idx} from |List| {list}. When this item is not + available return {default}. Return zero when {default} is + omitted. +get({dict}, {key} [, {default}]) + Get item with key {key} from |Dictionary| {dict}. When this + item is not available return {default}. Return zero when + {default} is omitted. + + *getbufline()* +getbufline({expr}, {lnum} [, {end}]) + Return a |List| with the lines starting from {lnum} to {end} + (inclusive) in the buffer {expr}. If {end} is omitted, a + |List| with only the line {lnum} is returned. + + For the use of {expr}, see |bufname()| above. + + For {lnum} and {end} "$" can be used for the last line of the + buffer. Otherwise a number must be used. + + When {lnum} is smaller than 1 or bigger than the number of + lines in the buffer, an empty |List| is returned. + + When {end} is greater than the number of lines in the buffer, + it is treated as {end} is set to the number of lines in the + buffer. When {end} is before {lnum} an empty |List| is + returned. + + This function works only for loaded buffers. For unloaded and + non-existing buffers, an empty |List| is returned. + + Example: > + :let lines = getbufline(bufnr("myfile"), 1, "$") + +getbufvar({expr}, {varname}) *getbufvar()* + The result is the value of option or local buffer variable + {varname} in buffer {expr}. Note that the name without "b:" + must be used. + This also works for a global or buffer-local option, but it + doesn't work for a global variable, window-local variable or + window-local option. + For the use of {expr}, see |bufname()| above. + When the buffer or variable doesn't exist an empty string is + returned, there is no error message. + Examples: > + :let bufmodified = getbufvar(1, "&mod") + :echo "todo myvar = " . getbufvar("todo", "myvar") +< getchar([expr]) *getchar()* - Get a single character from the user. If it is an 8-bit - character, the result is a number. Otherwise a String is - returned with the encoded character. For a special key it's a - sequence of bytes starting with 0x80 (decimal: 128). + Get a single character from the user or input stream. If [expr] is omitted, wait until a character is available. If [expr] is 0, only get a character when one is available. + Return zero otherwise. If [expr] is 1, only check if a character is available, it is - not consumed. If a normal character is - available, it is returned, otherwise a - non-zero value is returned. - If a character available, it is returned as a Number. Use - nr2char() to convert it to a String. - To turn a multi-byte character string also to a Number use - this: > + not consumed. Return zero if no character available. + + Without {expr} and when {expr} is 0 a whole character or + special key is returned. If it is an 8-bit character, the + result is a number. Use nr2char() to convert it to a String. + Otherwise a String is returned with the encoded character. + For a special key it's a sequence of bytes starting with 0x80 + (decimal: 128). This is the same value as the string + "\", e.g., "\". The returned value is also a + String when a modifier (shift, control, alt) was used that is + not included in the character. + + When {expr} is 1 only the first byte is returned. For a + one-byte character it is the character itself as a number. + Use nr2char() to convert it to a String. + + When the user clicks a mouse button, the mouse event will be + returned. The position can then be found in |v:mouse_col|, + |v:mouse_lnum| and |v:mouse_win|. This example positions the + mouse as it would normally happen: > let c = getchar() - if c == 0 - let c = char2nr(c) + if c == "\" && v:mouse_win > 0 + exe v:mouse_win . "wincmd w" + exe v:mouse_lnum + exe "normal " . v:mouse_col . "|" endif -< The returned value is negative for special keys. - The returned value is zero if no character is available. +< There is no prompt, you will somehow have to make clear to the user that a character has to be typed. There is no mapping for the character. @@ -1453,19 +2765,35 @@ character itself are obtained. Thus Shift-a results in "A" with no modifier. -getbufvar({expr}, {varname}) *getbufvar()* - The result is the value of option or local buffer variable - {varname} in buffer {expr}. Note that the name without "b:" - must be used. - This also works for a global or local window option, but it - doesn't work for a global or local window variable. - For the use of {expr}, see |bufname()| above. - When the buffer or variable doesn't exist an empty string is - returned, there is no error message. - Examples: > - :let bufmodified = getbufvar(1, "&mod") - :echo "todo myvar = " . getbufvar("todo", "myvar") -< +getcmdline() *getcmdline()* + Return the current command-line. Only works when the command + line is being edited, thus requires use of |c_CTRL-\_e| or + |c_CTRL-R_=|. + Example: > + :cmap eescape(getcmdline(), ' \') +< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|. + +getcmdpos() *getcmdpos()* + Return the position of the cursor in the command line as a + byte count. The first column is 1. + Only works when editing the command line, thus requires use of + |c_CTRL-\_e| or |c_CTRL-R_=|. Returns 0 otherwise. + Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|. + +getcmdtype() *getcmdtype()* + Return the current command-line type. Possible return values + are: + : normal Ex command + > debug mode command |debug-mode| + / forward search command + ? backward search command + @ |input()| command + - |:insert| or |:append| command + Only works when editing the command line, thus requires use of + |c_CTRL-\_e| or |c_CTRL-R_=|. Returns an empty string + otherwise. + Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|. + *getcwd()* getcwd() The result is a String, which is the name of the current working directory. @@ -1476,6 +2804,34 @@ If {fname} is a directory, 0 is returned. If the file {fname} can't be found, -1 is returned. +getfontname([{name}]) *getfontname()* + Without an argument returns the name of the normal font being + used. Like what is used for the Normal highlight group + |hl-Normal|. + With an argument a check is done whether {name} is a valid + font name. If not then an empty string is returned. + Otherwise the actual font name is returned, or {name} if the + GUI does not support obtaining the real name. + Only works when the GUI is running, thus not in your vimrc or + gvimrc file. Use the |GUIEnter| autocommand to use this + function just after the GUI has started. + Note that the GTK 2 GUI accepts any font name, thus checking + for a valid name does not work. + +getfperm({fname}) *getfperm()* + The result is a String, which is the read, write, and execute + permissions of the given file {fname}. + If {fname} does not exist or its directory cannot be read, an + empty string is returned. + The result is of the form "rwxrwxrwx", where each group of + "rwx" flags represent, in turn, the permissions of the owner + of the file, the group the file belongs to, and other users. + If a user does not have a given permission the flag for this + is replaced with the string "-". Example: > + :echo getfperm("/etc/passwd") +< This will hopefully (from a security point of view) display + the string "rw-r--r--" or even "rw-------". + getftime({fname}) *getftime()* The result is a Number, which is the last modification time of the given file {fname}. The value is measured as seconds @@ -1483,9 +2839,30 @@ |localtime()| and |strftime()|. If the file {fname} can't be found -1 is returned. +getftype({fname}) *getftype()* + The result is a String, which is a description of the kind of + file of the given file {fname}. + If {fname} does not exist an empty string is returned. + Here is a table over different kinds of files and their + results: + Normal file "file" + Directory "dir" + Symbolic link "link" + Block device "bdev" + Character device "cdev" + Socket "socket" + FIFO "fifo" + All other "other" + Example: > + 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. + *getline()* -getline({lnum}) The result is a String, which is line {lnum} from the current - buffer. Example: > +getline({lnum} [, {end}]) + Without {end} the result is a String, which is line {lnum} + from the current buffer. Example: > getline(1) < When {lnum} is a String that doesn't start with a digit, line() is called to translate the String into a Number. @@ -1494,14 +2871,63 @@ < When {lnum} is smaller than 1 or bigger than the number of lines in the buffer, an empty string is returned. -getreg([{regname}]) *getreg()* + When {end} is given the result is a |List| where each item is + a line from the current buffer in the range {lnum} to {end}, + including line {end}. + {end} is used in the same way as {lnum}. + Non-existing lines are silently omitted. + When {end} is before {lnum} an empty |List| is returned. + Example: > + :let start = line('.') + :let end = search("^$") - 1 + :let lines = getline(start, end) + +getloclist({nr}) *getloclist()* + Returns a list with all the entries in the location list for + 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(). + +getqflist() *getqflist()* + Returns a list with all the current quickfix errors. Each + list item is a dictionary with these entries: + bufnr number of buffer that has the file name, use + bufname() to get the name + lnum line number in the buffer (first line is 1) + col column number (first column is 1) + vcol non-zero: "col" is visual column + zero: "col" is byte index + nr error number + pattern search pattern used to locate the error + text description of the error + type type of the error, 'E', '1', etc. + valid non-zero: recognized error message + + When there is no error list or it's empty an empty list is + returned. Quickfix list entries with non-existing buffer + number are returned with "bufnr" set to zero. + + Useful application: Find pattern matches in multiple files and + do something with them: > + :vimgrep /theword/jg *.c + :for d in getqflist() + : echo bufname(d.bufnr) ':' d.lnum '=' d.text + :endfor + + +getreg([{regname} [, 1]]) *getreg()* The result is a String, which is the contents of register {regname}. Example: > :let cliptext = getreg('*') < getreg('=') returns the last evaluated value of the expression - register. (For use in maps). + register. (For use in maps.) + getreg('=', 1) returns the expression itself, so that it can + be restored with |setreg()|. For other registers the extra + argument is ignored, thus you can always give it. If {regname} is not specified, |v:register| is used. + getregtype([{regname}]) *getregtype()* The result is a String, which is type of register {regname}. The value will be one of: @@ -1512,6 +2938,20 @@ is one character with value 0x16. If {regname} is not specified, |v:register| is used. +gettabwinvar({tabnr}, {winnr}, {varname}) *gettabwinvar()* + Get the value of an option or local window variable {varname} + in window {winnr} in tab page {tabnr}. + Tabs are numbered starting with one. For the current tabpage + use |getwinvar()|. + When {winnr} is zero the current window is used. + This also works for a global option, buffer-local option and + window-local option, but it doesn't work for a global variable + or buffer-local variable. + Note that the name without "w:" must be used. + Examples: > + :let list_is_on = gettabwinvar(1, 2, '&list') + :echo "myvar = " . gettabwinvar(3, 1, 'myvar') + *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 @@ -1522,12 +2962,8 @@ the top of the GUI Vim window. The result will be -1 if the information is not available. -getwinvar({nr}, {varname}) *getwinvar()* - The result is the value of option or local window variable - {varname} in window {nr}. - This also works for a global or local buffer option, but it - doesn't work for a global or local buffer variable. - Note that the name without "w:" must be used. +getwinvar({winnr}, {varname}) *getwinvar()* + Like |gettabwinvar()| for the current tabpage. Examples: > :let list_is_on = getwinvar(2, '&list') :echo "myvar = " . getwinvar(1, 'myvar') @@ -1556,21 +2992,39 @@ < {path} is a comma-separated list of directory names. Each directory name is prepended to {expr} and expanded like with glob(). A path separator is inserted when needed. + To add a comma inside a directory name escape it with a + backslash. Note that on MS-Windows a directory may have a + trailing backslash, remove it if you put a comma after it. If the expansion fails for one of the directories, there is no error message. The 'wildignore' option applies: Names matching one of the patterns in 'wildignore' will be skipped. + The "**" item can be used to search in a directory tree. + For example, to find all "README.txt" files in the directories + in 'runtimepath' and below: > + :echo globpath(&rtp, "**/README.txt") +< *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. + Also see |exists()|. -hasmapto({what} [, {mode}]) *hasmapto()* + +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. + + +hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* The result is a Number, which is 1 if there is a mapping that contains {what} in somewhere in the rhs (what it is mapped to) and this mapping exists in one of the modes indicated by {mode}. + When {abbr} is there and it is non-zero use abbreviations + instead of mappings. Don't forget to specify Insert and/or + Command-line mode. Both the global mappings and the mappings local to the current buffer are checked for a match. If no matching mapping is found 0 is returned. @@ -1609,7 +3063,7 @@ < This function is not available in the |sandbox|. histdel({history} [, {item}]) *histdel()* - Clear {history}, ie. delete all its entries. See |hist-names| + Clear {history}, i.e. delete all its entries. See |hist-names| for the possible values of {history}. If the parameter {item} is given as String, this is seen @@ -1713,19 +3167,48 @@ |getline()|. When {lnum} is invalid -1 is returned. -input({prompt} [, {text}]) *input()* + +index({list}, {expr} [, {start} [, {ic}]]) *index()* + Return the lowest index in |List| {list} where the item has a + value equal to {expr}. + 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 + case must match. + -1 is returned when {expr} is not found in {list}. + Example: > + :let idx = index(words, "the") + :if index(numbers, 123) >= 0 + + +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 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 for lines typed for - input(). - If the optional {text} is present, this is used for the - default reply, as if the user typed this. - NOTE: This must not be used in a startup file, for the - versions that only run in GUI mode (e.g., the Win32 GUI). + 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 + for lines typed for input(). + Example: > + :if input("Coffee or beer? ") == "beer" + : 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: > + :let color = input("Color? ", "white") + +< The optional {completion} argument specifies the type of + completion supported for the input. Without it completion is + not performed. The supported completion types are the same as + that can be supplied to a user-defined command using the + "-complete=" argument. Refer to |:command-completion| for + more information. Example: > + let fname = input("File: ", "", "file") +< + NOTE: This function must not be used in a startup file, for + the versions that only run in GUI mode (e.g., the Win32 GUI). Note: When input() is called from within a mapping it will consume remaining characters from that mapping, because a mapping is handled like the characters were typed. @@ -1734,13 +3217,7 @@ that further characters follow in the mapping, e.g., by using |:execute| or |:normal|. - Example: > - :if input("Coffee or beer? ") == "beer" - : echo "Cheers!" - :endif -< Example with default text: > - :let color = input("Color? ", "white") -< Example with a mapping: > + Example with a mapping: > :nmap \x :call GetFoo():exe "/" . Foo :function GetFoo() : call inputsave() @@ -1760,6 +3237,22 @@ omitted an empty string is returned. Hitting works like pressing the OK button. Hitting works like pressing the Cancel button. + NOTE: Command-line completion is not supported. + +inputlist({textlist}) *inputlist()* + {textlist} must be a |List| of strings. This |List| is + displayed, one string per line. The user will be prompted to + enter a number, which is returned. + The user can also select an item by clicking on it with the + mouse. For the first string 0 is returned. When clicking + 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 + it won't work. It's a good idea to put the entry number at + the start of the string. Example: > + let color = inputlist(['Select color:', '1. red', + \ '2. green', '3. blue']) inputrestore() *inputrestore()* Restore typeahead that was saved with a previous inputsave(). @@ -1784,6 +3277,21 @@ |history| stack. The result is a String, which is whatever the user actually typed on the command-line in response to the issued prompt. + NOTE: Command-line completion is not supported. + +insert({list}, {item} [, {idx}]) *insert()* + Insert {item} at the start of |List| {list}. + If {idx} is specified insert {item} before the item with index + {idx}. If {idx} is zero it goes before the first item, just + like omitting {idx}. A negative {idx} is also possible, see + |list-index|. -1 inserts just before the last item. + Returns the resulting |List|. Examples: > + :let mylist = insert([2, 3, 5], 1) + :call insert(mylist, 4, -1) + :call insert(mylist, 6, len(mylist)) +< The last example can be done simpler with |add()|. + Note that when {item} is a |List| it is inserted as a single + item. Use |extend()| to concatenate |Lists|. isdirectory({directory}) *isdirectory()* The result is a Number, which is non-zero when a directory @@ -1791,6 +3299,51 @@ exist, or isn't a directory, the result is FALSE. {directory} is any expression, which is used as a String. +islocked({expr}) *islocked()* *E786* + The result is a Number, which is non-zero when {expr} is the + name of a locked variable. + {expr} must be the name of a variable, |List| item or + |Dictionary| entry, not the variable itself! Example: > + :let alist = [0, ['a', 'b'], 2, 3] + :lockvar 1 alist + :echo islocked('alist') " 1 + :echo islocked('alist[1]') " 0 + +< When {expr} is a variable that does not exist you get an error + message. Use |exists()| to check for existence. + +items({dict}) *items()* + Return a |List| with all the key-value pairs of {dict}. Each + |List| item is a list with two items: the key of a {dict} + entry and the value of this entry. The |List| is in arbitrary + order. + + +join({list} [, {sep}]) *join()* + Join the items in {list} together into one String. + When {sep} is specified it is put in between the items. If + {sep} is omitted a single space is used. + Note that {sep} is not added at the end. You might want to + add it there too: > + let lines = join(mylist, "\n") . "\n" +< String items are used as-is. |Lists| and |Dictionaries| are + converted into a string like with |string()|. + The opposite function is |split()|. + +keys({dict}) *keys()* + Return a |List| with all the keys of {dict}. The |List| is in + arbitrary order. + + *len()* *E701* +len({expr}) The result is a Number, which is the length of the argument. + When {expr} is a String or a Number the length in bytes is + used, as with |strlen()|. + When {expr} is a |List| the number of items in the |List| is + returned. + When {expr} is a |Dictionary| the number of entries in the + |Dictionary| is returned. + Otherwise an error is given. + *libcall()* *E364* *E368* libcall({libname}, {funcname}, {argument}) Call function {funcname} in the run-time library {libname} @@ -1831,7 +3384,7 @@ without the ".DLL" suffix. A full path is only required if 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-independant ('PIC'). + object code must be compiled as position-independent ('PIC'). {only in Win32 on some Unix versions, when the |+libcall| feature is present} Examples: > @@ -1855,7 +3408,11 @@ $ the last line in the current buffer 'x position of mark x (if the mark is not set, 0 is returned) - Note that only marks in the current file can be used. + w0 first line visible in current window + w$ last line visible in current window + Note that a mark in another file can be used. + To get the column number use |col()|. To get both use + |getpos()|. Examples: > line(".") line number of the cursor line("'t") line number of mark t @@ -1864,7 +3421,7 @@ This autocommand jumps to the last known position in a file just after opening it, if the '" mark is set: > :au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | exe "normal g'\"" | endif -< + line2byte({lnum}) *line2byte()* Return the byte count from the start of the buffer for line {lnum}. This includes the end-of-line character, depending on @@ -1890,10 +3447,35 @@ Return the current time, measured as seconds since 1st Jan 1970. See also |strftime()| and |getftime()|. -maparg({name}[, {mode}]) *maparg()* + +map({expr}, {string}) *map()* + {expr} must be a |List| or a |Dictionary|. + Replace each item in {expr} with the result of evaluating + {string}. + Inside {string} |v:val| has the value of the current item. + For a |Dictionary| |v:key| has the key of the current item. + Example: > + :call map(mylist, '"> " . v:val . " <"') +< This puts "> " before and " <" after each item in "mylist". + + Note that {string} is the result of an expression and is then + used as an expression again. Often it is good to use a + |literal-string| to avoid having to double backslashes. You + still have to double ' quotes + + The operation is done in-place. If you want a |List| or + |Dictionary| to remain unmodified make a copy first: > + :let tlist = map(copy(mylist), ' & . "\t"') + +< Returns {expr}, the |List| or |Dictionary| that was filtered. + When an error is encountered while evaluating {string} no + further items in {expr} are processed. + + +maparg({name}[, {mode} [, {abbr}]]) *maparg()* Return the rhs of mapping {name} in mode {mode}. When there is no mapping for {name}, an empty String is returned. - These characters can be used for {mode}: + {mode} can be one of these strings: "n" Normal "v" Visual "o" Operator-pending @@ -1901,17 +3483,25 @@ "c" Cmd-line "l" langmap |language-mapping| "" Normal, Visual and Operator-pending - When {mode} is omitted, the modes from "" are used. + When {mode} is omitted, the modes for "" are used. + When {abbr} is there and it is non-zero use abbreviations + instead of mappings. The {name} can have special key names, like in the ":map" command. The returned String has special characters translated like in the output of the ":map" command listing. The mappings local to the current buffer are checked first, then the global mappings. + This function can be used to map a key even when it's already + mapped, and have it do the original mapping too. Sketch: > + exe 'nnoremap ==' . maparg('', 'n') -mapcheck({name}[, {mode}]) *mapcheck()* + +mapcheck({name}[, {mode} [, {abbr}]]) *mapcheck()* Check if there is a mapping that matches with {name} in mode {mode}. See |maparg()| for {mode} and special names in {name}. + When {abbr} is there and it is non-zero use abbreviations + instead of mappings. A match happens with a mapping that starts with {name} and with a mapping which is equal to the start of {name}. @@ -1938,41 +3528,102 @@ < This avoids adding the "_vv" mapping when there already is a mapping for "_v" or for "_vvv". -match({expr}, {pat}[, {start}]) *match()* - The result is a Number, which gives the index in {expr} where - {pat} matches. A match at the first character returns zero. - If there is no match -1 is returned. Example: > - :echo match("testing", "ing") -< results in "4". - See |string-match| for how {pat} is used. - If {start} is given, the search starts from character {start}. +match({expr}, {pat}[, {start}[, {count}]]) *match()* + When {expr} is a |List| then this returns the index of the + first item where {pat} matches. Each item is used as a + String, |Lists| and |Dictionaries| are used as echoed. + Otherwise, {expr} is used as a String. The result is a + Number, which gives the index (byte offset) in {expr} where + {pat} matches. + A match at the first character or |List| item returns zero. + If there is no match -1 is returned. + Example: > + :echo match("testing", "ing") " results in 4 + :echo match([1, 'x'], '\a') " results in 1 +< See |string-match| for how {pat} is used. + *strpbrk()* + Vim doesn't have a strpbrk() function. But you can do: > + :let sepidx = match(line, '[.,;: \t]') +< *strcasestr()* + Vim doesn't have a strcasestr() function. But you can add + "\c" to the pattern to ignore case: > + :let idx = match(haystack, '\cneedle') +< + If {start} is given, the search starts from byte index + {start} in a String or item {start} in a |List|. The result, however, is still the index counted from the - first character. Example: > + first character/item. Example: > :echo match("testing", "ing", 2) < result is again "4". > :echo match("testing", "ing", 4) < result is again "4". > :echo match("testing", "t", 2) < result is "3". - If {start} < 0, it will be set to 0. - If {start} > strlen({expr}) -1 is returned. + For a String, if {start} > 0 then it is like the string starts + {start} bytes later, thus "^" will match at {start}. Except + when {count} is given, then it's like matches before the + {start} byte are ignored (this is a bit complicated to keep it + backwards compatible). + For a String, if {start} < 0, it will be set to 0. For a list + the index is counted from the end. + If {start} is out of range ({start} > strlen({expr}) for a + String or {start} > len({expr}) for a |List|) -1 is returned. + + When {count} is given use the {count}'th match. When a match + is found in a String the search for the next one starts one + character further. Thus this example results in 1: > + echo match("testing", "..", 0, 2) +< In a |List| the search continues in the next item. + Note that when {count} is added the way {start} works changes, + see above. + See |pattern| for the patterns that are accepted. The 'ignorecase' option is used to set the ignore-caseness of the pattern. 'smartcase' is NOT used. The matching is always done like 'magic' is set and 'cpoptions' is empty. -matchend({expr}, {pat}[, {start}]) *matchend()* + +matcharg({nr}) *matcharg()* + Selects the {nr} match item, as set with a |:match|, + |:2match| or |:3match| command. + Return a |List| with two elements: + The name of the highlight group used + The pattern used. + When {nr} is not 1, 2 or 3 returns an empty |List|. + When there is no match item set returns ['', '']. + This is usef to save and restore a |:match|. + + +matchend({expr}, {pat}[, {start}[, {count}]]) *matchend()* Same as match(), but return the index of first character after the match. Example: > :echo matchend("testing", "ing") < results in "7". + *strspn()* *strcspn()* + Vim doesn't have a strspn() or strcspn() function, but you can + do it with matchend(): > + :let span = matchend(line, '[a-zA-Z]') + :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(). > :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(). -matchstr({expr}, {pat}[, {start}]) *matchstr()* +matchlist({expr}, {pat}[, {start}[, {count}]]) *matchlist()* + 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 + empty string is used. Example: > + echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)') +< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] + When there is no match an empty list is returned. + +matchstr({expr}, {pat}[, {start}[, {count}]]) *matchstr()* Same as match(), but return the matched string. Example: > :echo matchstr("testing", "ing") < results in "ing". @@ -1982,7 +3633,34 @@ < results in "ing". > :echo matchstr("testing", "ing", 5) < result is "". + When {expr} is a |List| then the matching item is returned. + The type isn't changed, it's not necessarily a String. + + *max()* +max({list}) Return the maximum value of all items in {list}. + If {list} is not a list or one of the items in {list} cannot + be used as a Number this results in an error. + An empty |List| results in zero. + *min()* +min({list}) Return the minumum value of all items in {list}. + If {list} is not a list or one of the items in {list} cannot + be used as a Number this results in an error. + An empty |List| results in zero. + + *mkdir()* *E739* +mkdir({name} [, {path} [, {prot}]]) + Create directory {name}. + If {path} is "p" then intermediate directories are created as + necessary. Otherwise it must be "". + If {prot} is given it is used to set the protection bits of + the new directory. The default is 0755 (rwxr-xr-x: r/w for + the user readable for others). Use 0700 to make it unreadable + for others. + This function is not available in the |sandbox|. + Not available on all systems. To check use: > + :if exists("*mkdir") +< *mode()* mode() Return a string that indicates the current mode: n Normal @@ -2014,6 +3692,38 @@ nr2char(32) returns " " < The current 'encoding' is used. Example for "utf-8": > nr2char(300) returns I with bow character +< Note that a NUL character in the file is specified with + nr2char(10), because NULs are represented with newline + characters. nr2char(0) is a real NUL and terminates the + string, thus results in an empty string. + + *getpos()* +getpos({expr}) Get the position for {expr}. For possible values of {expr} + see |line()|. + The result is a |List| with four numbers: + [bufnum, lnum, col, off] + "bufnum" is zero, unless a mark like '0 or 'A is used, then it + is the buffer number of the mark. + "lnum" and "col" are the position in the buffer. The first + column is 1. + The "off" number is zero, unless 'virtualedit' is used. Then + it is the offset in screen columns from the start of the + character. E.g., a position within a Tab or after the last + character. + This can be used to save and restore the cursor position: > + let save_cursor = getpos(".") + MoveTheCursorAround + call setpos('.', save_cursor) +< Also see |setpos()|. + +pathshorten({expr}) *pathshorten()* + Shorten directory names in the path {expr} and return the + result. The tail, the file name, is kept as-is. The other + components in the path are reduced to single letters. Leading + '~' and '.' characters are kept. Example: > + :echo pathshorten('~/.vim/autoload/myfile.vim') +< ~/.v/a/myfile.vim ~ + It doesn't matter if the path exists or not. prevnonblank({lnum}) *prevnonblank()* Return the line number of the first line at or above {lnum} @@ -2023,10 +3733,221 @@ above it, zero is returned. Also see |nextnonblank()|. + +printf({fmt}, {expr1} ...) *printf()* + Return a String with {fmt}, where "%" items are replaced by + the formatted form of their respective arguments. Example: > + printf("%4d: E%d %.30s", lnum, errno, msg) +< May result in: + " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~ + + Often used items are: + %s string + %6s string right-aligned in 6 bytes + %.9s string truncated to 9 bytes + %c single byte + %d decimal number + %5d decimal number padded with spaces to 5 characters + %x hex number + %04x hex number padded with zeros to at least 4 characters + %X hex number using upper case letters + %o octal number + %% the % character itself + + Conversion specifications start with '%' and end with the + conversion type. All other characters are copied unchanged to + the result. + + The "%" starts a conversion specification. The following + arguments appear in sequence: + + % [flags] [field-width] [.precision] type + + flags + Zero or more of the following flags: + + # The value should be converted to an "alternate + form". For c, d, and s conversions, this option + has no effect. For o conversions, the precision + of the number is increased to force the first + character of the output string to a zero (except + if a zero value is printed with an explicit + precision of zero). + For x and X conversions, a non-zero result has + the string "0x" (or "0X" for X conversions) + prepended to it. + + 0 (zero) Zero padding. For all conversions the converted + value is padded on the left with zeros rather + than blanks. If a precision is given with a + numeric conversion (d, o, x, and X), the 0 flag + is ignored. + + - A negative field width flag; the converted value + is to be left adjusted on the field boundary. + The converted value is padded on the right with + blanks, rather than on the left with blanks or + zeros. A - overrides a 0 if both are given. + + ' ' (space) A blank should be left before a positive + number produced by a signed conversion (d). + + + A sign must always be placed before a number + produced by a signed conversion. A + overrides + a space if both are used. + + field-width + An optional decimal digit string specifying a minimum + field width. If the converted value has fewer bytes + than the field width, it will be padded with spaces on + the left (or right, if the left-adjustment flag has + been given) to fill out the field width. + + .precision + An optional precision, in the form of a period '.' + followed by an optional digit string. If the digit + string is omitted, the precision is taken as zero. + This gives the minimum number of digits to appear for + d, o, x, and X conversions, or the maximum number of + bytes to be printed from a string for s conversions. + + type + A character that specifies the type of conversion to + be applied, see below. + + A field width or precision, or both, may be indicated by an + asterisk '*' instead of a digit string. In this case, a + Number argument supplies the field width or precision. A + negative field width is treated as a left adjustment flag + followed by a positive field width; a negative precision is + treated as though it were missing. Example: > + :echo printf("%d: %.*s", nr, width, line) +< This limits the length of the text used from "line" to + "width" bytes. + + The conversion specifiers and their meanings are: + + doxX The Number argument is converted to signed decimal + (d), unsigned octal (o), or unsigned hexadecimal (x + and X) notation. The letters "abcdef" are used for + x conversions; the letters "ABCDEF" are used for X + conversions. + The precision, if any, gives the minimum number of + digits that must appear; if the converted value + requires fewer digits, it is padded on the left with + zeros. + In no case does a non-existent or small field width + cause truncation of a numeric field; if the result of + a conversion is wider than the field width, the field + is expanded to contain the conversion result. + + c The Number argument is converted to a byte, and the + resulting character is written. + + s The text of the String argument is used. If a + precision is specified, no more bytes than the number + specified are used. + + % A '%' is written. No argument is converted. The + complete conversion specification is "%%". + + Each argument can be Number or String and is converted + automatically to fit the conversion specifier. Any other + argument type results in an error message. + + *E766* *E767* + The number of {exprN} arguments must exactly match the number + of "%" items. If there are not sufficient or too many + arguments an error is given. Up to 18 arguments can be used. + + +pumvisible() *pumvisible()* + Returns non-zero when the popup menu is visible, zero + otherwise. See |ins-completion-menu|. + This can be used to avoid some things that would remove the + popup menu. + + *E726* *E727* +range({expr} [, {max} [, {stride}]]) *range()* + Returns a |List| with Numbers: + - If only {expr} is specified: [0, 1, ..., {expr} - 1] + - If {max} is specified: [{expr}, {expr} + 1, ..., {max}] + - If {stride} is specified: [{expr}, {expr} + {stride}, ..., + {max}] (increasing {expr} with {stride} each time, not + producing a value past {max}). + When the maximum is one before the start the result is an + empty list. When the maximum is more than one before the + start this is an error. + Examples: > + range(4) " [0, 1, 2, 3] + range(2, 4) " [2, 3, 4] + range(2, 9, 3) " [2, 5, 8] + range(2, -2, -1) " [2, 1, 0, -1, -2] + range(0) " [] + range(2, 0) " error! +< + *readfile()* +readfile({fname} [, {binary} [, {max}]]) + Read file {fname} and return a |List|, each line of the file + as an item. Lines broken at NL characters. Macintosh files + separated with CR will result in a single long line (unless a + NL appears somewhere). + When {binary} is equal to "b" binary mode is used: + - When the last line ends in a NL an extra empty list item is + added. + - No CR characters are removed. + Otherwise: + - CR characters that appear before a NL are removed. + - Whether the last line ends in a NL or not does not matter. + All NUL characters are replaced with a NL character. + When {max} is given this specifies the maximum number of lines + to be read. Useful if you only want to check the first ten + lines of a file: > + :for line in readfile(fname, '', 10) + : if line =~ 'Date' | echo line | endif + :endfor +< When {max} is negative -{max} lines from the end of the file + are returned, or as many as there are. + When {max} is zero the result is an empty list. + Note that without {max} the whole file is read into memory. + Also note that there is no recognition of encoding. Read a + file into a buffer if you need to. + When the file can't be opened an error message is given and + the result is an empty list. + Also see |writefile()|. + +reltime([{start} [, {end}]]) *reltime()* + Return an item that represents a time value. The format of + the item depends on the system. It can be passed to + |reltimestr()| to convert it to a string. + Without an argument it returns the current time. + With one argument is returns the time passed since the time + specified in the argument. + With two arguments it returns the time passed between {start} + and {end}. + The {start} and {end} arguments must be values returned by + reltime(). + {only available when compiled with the +reltime feature} + +reltimestr({time}) *reltimestr()* + Return a String that represents the time value of {time}. + This is the number of seconds, a dot and the number of + microseconds. Example: > + let start = reltime() + call MyFunction() + echo reltimestr(reltime(start)) +< Note that overhead for the commands will be added to the time. + The accuracy depends on the system. + Also see |profiling|. + {only available when compiled with the +reltime feature} + *remote_expr()* *E449* remote_expr({server}, {string} [, {idvar}]) Send the {string} to {server}. The string is sent as an expression and the result is returned after evaluation. + The result must be a String or a |List|. A |List| is turned + into a String by joining the items with a line break in + between (not at the end), like with join(expr, "\n"). If {idvar} is present, it is taken as the name of a variable and a {serverid} for later use with remote_read() is stored there. @@ -2047,6 +3968,8 @@ < Except that on Win32 systems the client does the work, to work around the problem that the OS doesn't always allow the server to bring itself to the foreground. + Note: This does not restore the window if it was minimized, + like foreground() does. This function is not available in the |sandbox|. {only in the Win32, Athena, Motif and GTK GUI versions and the Win32 console version} @@ -2077,11 +4000,12 @@ < *remote_send()* *E241* remote_send({server}, {string} [, {idvar}]) - Send the {string} to {server}. The string is sent as - input keys and the function returns immediately. - If {idvar} is present, it is taken as the name of a - variable and a {serverid} for later use with - remote_read() is stored there. + Send the {string} to {server}. The string is sent as input + keys and the function returns immediately. At the Vim server + the keys are not mapped |:map|. + If {idvar} is present, it is taken as the name of a variable + and a {serverid} for later use with remote_read() is stored + there. See also |clientserver| |RemoteReply|. This function is not available in the |sandbox|. {only available when compiled with the |+clientserver| feature} @@ -2095,7 +4019,24 @@ \ echo remote_read(expand("")) :echo remote_send("gvim", ":sleep 10 | echo ". \ 'server2client(expand(""), "HELLO")') +< +remove({list}, {idx} [, {end}]) *remove()* + Without {end}: Remove the item at {idx} from |List| {list} and + return it. + With {end}: Remove items from {idx} to {end} (inclusive) and + 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}. + Example: > + :echo "last item: " . remove(mylist, -1) + :call remove(mylist, 0, 9) +remove({dict}, {key}) + Remove the entry from {dict} with key {key}. Example: > + :echo "removed " . remove(dict, "one") +< If there is no {key} in {dict} this is an error. + Use |delete()| to remove a file. rename({from}, {to}) *rename()* Rename the file by the name {from} to the name {to}. This @@ -2104,27 +4045,74 @@ successfully, and non-zero when the renaming failed. This function is not available in the |sandbox|. -resolve({filename}) *resolve()* +repeat({expr}, {count}) *repeat()* + Repeat {expr} {count} times and return the concatenated + result. Example: > + :let separator = repeat('-', 80) +< When {count} is zero or negative the result is empty. + When {expr} is a |List| the result is {expr} concatenated + {count} times. Example: > + :let longlist = repeat(['a', 'b'], 3) +< Results in ['a', 'b', 'a', 'b', 'a', 'b']. + + +resolve({filename}) *resolve()* *E655* On MS-Windows, when {filename} is a shortcut (a .lnk file), - returns the path the shortcut points to. - On Unix, when {filename} is a symbolic link, returns the path - the symlink points to. This only happens once, the returned - path could be a symlink again. - Otherwise {filename} is returned. + returns the path the shortcut points to in a simplified form. + On Unix, repeat resolving symbolic links in all path + components of {filename} and return the simplified result. + To cope with link cycles, resolving of symbolic links is + stopped after 100 iterations. + On other systems, return the simplified {filename}. + The simplification step is done as by |simplify()|. + resolve() keeps a leading path component specifying the + current directory (provided the result is still a relative + path name) and also keeps a trailing path separator. -search({pattern} [, {flags}]) *search()* + *reverse()* +reverse({list}) Reverse the order of items in {list} in-place. Returns + {list}. + If you want a list to remain unmodified make a copy first: > + :let revlist = reverse(copy(mylist)) + +search({pattern} [, {flags} [, {stopline}]]) *search()* Search for regexp pattern {pattern}. The search starts at the - cursor position. + cursor position (you can use |cursor()| to set it). + {flags} is a String, which can contain these character flags: '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 If neither 'w' or 'W' is given, the 'wrapscan' option applies. - When a match has been found its line number is returned, and - the cursor will be positioned at the match. If there is no - match a 0 is returned and the cursor doesn't move. No error - message is given. + If the 's' flag is supplied, the ' mark is set, only if the + cursor is moved. The 's' flag cannot be combined with the 'n' + flag. + + When the {stopline} argument is given then the search stops + after searching this line. This is useful to restrict the + search to a range of lines. Examples: > + let match = search('(', 'b', line("w0")) + let end = search('END', '', line("w$")) +< When {stopline} is used and it is not zero this also implies + that the search does not wrap around the end of the file. + + If there is no match a 0 is returned and the cursor doesn't + move. No error message is given. + When a match has been found its line number is returned. + *search()-sub-match* + With the 'p' flag the returned value is one more than the + first sub-match in \(\). One if none of them matched but the + whole pattern did match. + To get the column number too use |searchpos()|. + + The cursor will be positioned at the match, unless the 'n' + flag is used. Example (goes over all files in the argument list): > :let n = 1 @@ -2142,15 +4130,49 @@ : let n = n + 1 :endwhile < + Example for using some flags: > + :echo search('\ + if searchdecl('myvar') == 0 + echo getline('.') + endif +< *searchpair()* -searchpair({start}, {middle}, {end} [, {flags} [, {skip}]]) +searchpair({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]]) Search for the match of a nested start-end pair. This can be used to find the "endif" that matches an "if", while other if/endif pairs in between are ignored. - The search starts at the cursor. If a match is found, the - cursor is positioned at it and the line number is returned. - If no match is found 0 or -1 is returned and the cursor - doesn't move. No error message is given. + The search starts at the cursor. The default is to search + forward, include 'b' in {flags} to search backward. + If a match is found, the cursor is positioned at it and the + line number is returned. If no match is found 0 or -1 is + returned and the cursor doesn't move. No error message is + given. {start}, {middle} and {end} are patterns, see |pattern|. They must not contain \( \) pairs. Use of \%( \) is allowed. When @@ -2160,12 +4182,12 @@ searchpair('\', '\', '\') < By leaving {middle} empty the "else" is skipped. - {flags} are used like with |search()|. Additionally: - 'n' do Not move the cursor + {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with + |search()|. Additionally: 'r' Repeat until no more matches found; will find the outer pair 'm' return number of Matches instead of line number with - the match; will only be > 1 when 'r' is used. + the match; will be > 1 when 'r' is used. When a match for {start}, {middle} or {end} is found, the {skip} expression is evaluated with the cursor positioned on @@ -2176,6 +4198,8 @@ When evaluating {skip} causes an error the search is aborted and -1 returned. + For {stopline} see |search()|. + The value of 'ignorecase' is used. 'magic' is ignored, the patterns are used like it's on. @@ -2192,6 +4216,10 @@ found. That's because the "if 2" will be found first, and then this is considered to be a nested if/endif from "if 2" to "endif 2". + When searching backwards and {end} is more than one character, + it may be useful to put "\zs" at the end of the pattern, so + that when the cursor is inside a match with the end it finds + the matching start. Example, to find the "endif" command in a Vim script: > @@ -2215,13 +4243,40 @@ :echo searchpair('{', '', '}', 'bW', \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"') < + *searchpairpos()* +searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [, {stopline}]]]) + 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, + returns [0, 0]. +> + :let [lnum,col] = searchpairpos('{', '', '}', 'n') +< + See |match-parens| for a bigger and more useful example. + +searchpos({pattern} [, {flags} [, {stopline}]]) *searchpos()* + Same as |search()|, 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, + returns [0, 0]. + Example: > + :let [lnum, col] = searchpos('mypattern', 'n') + +< When the 'p' flag is given then there is an extra item with + the sub-pattern match number |search()-sub-match|. Example: > + :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np') +< In this example "submatch" is 2 when a lowercase letter is + found |/\l|, 3 when an uppercase letter is found |/\u|. + server2client( {clientid}, {string}) *server2client()* Send a reply string to {clientid}. The most recent {clientid} that sent a string can be retrieved with expand(""). {only available when compiled with the |+clientserver| feature} Note: This id has to be stored before the next command can be - received. Ie. before returning from the received command and + received. I.e. before returning from the received command and before calling any commands that waits for input. See also |clientserver|. Example: > @@ -2229,8 +4284,8 @@ < serverlist() *serverlist()* Return a list of available server names, one per line. - When there are no servers an empty string is returned. - See also |clientserver|. + When there are no servers or the information is not available + an empty string is returned. See also |clientserver|. {only available when compiled with the |+clientserver| feature} Example: > :echo serverlist() @@ -2248,13 +4303,116 @@ :call setbufvar("todo", "myvar", "foobar") < This function is not available in the |sandbox|. +setcmdpos({pos}) *setcmdpos()* + Set the cursor position in the command line to byte position + {pos}. The first position is 1. + Use |getcmdpos()| to obtain the current position. + Only works while editing the command line, thus you must use + |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For + |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is + set after the command line is set to the expression. For + |c_CTRL-R_=| it is set after evaluating the expression but + before inserting the resulting text. + When the number is too big the cursor is put at the end of the + line. A number smaller than one has undefined results. + Returns 0 when successful, 1 when not editing the command + line. + setline({lnum}, {line}) *setline()* - Set line {lnum} of the current buffer to {line}. If this - succeeds, 0 is returned. If this fails (most likely because - {lnum} is invalid) 1 is returned. Example: > + Set line {lnum} of the current buffer to {line}. + {lnum} is used like with |getline()|. + When {lnum} is just below the last line the {line} will be + added as a new line. + If this succeeds, 0 is returned. If this fails (most likely + because {lnum} is invalid) 1 is returned. Example: > :call setline(5, strftime("%c")) +< When {line} is a |List| then line {lnum} and following lines + will be set to the items in the list. Example: > + :call setline(5, ['aaa', 'bbb', 'ccc']) +< This is equivalent to: > + :for [n, l] in [[5, 6, 7], ['aaa', 'bbb', 'ccc']] + : call setline(n, l) + :endfor < Note: The '[ and '] marks are not set. +setloclist({nr}, {list} [, {action}]) *setloclist()* + Create or replace or add to the location list for window {nr}. + When {nr} is zero the current window is used. For a location + list window, the displayed location list is modified. For an + invalid window number {nr}, -1 is returned. + Otherwise, same as setqflist(). + + *setpos()* +setpos({expr}, {list}) + Set the position for {expr}. Possible values: + . the cursor + 'x mark x + + {list} must be a |List| with four numbers: + [bufnum, lnum, col, off] + + "bufnum" is the buffer number. Zero can be used for the + current buffer. Setting the cursor is only possible for + the current buffer. To set a mark in another buffer you can + use the |bufnr()| function to turn a file name into a buffer + number. + 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. + + The "off" number is only used when 'virtualedit' is set. Then + it is the offset in screen columns from the start of the + character. E.g., a position within a Tab or after the last + character. + + Also see |getpos()| + + +setqflist({list} [, {action}]) *setqflist()* + Create or replace or add to the quickfix list using the items + in {list}. Each item in {list} is a dictionary. + Non-dictionary items in {list} are ignored. Each dictionary + item can contain the following entries: + + bufnr buffer number; must be the number of a valid + buffer + filename name of a file; only used when "bufnr" is not + present or it is invalid. + lnum line number in the file + pattern search pattern used to locate the error + col column number + vcol when non-zero: "col" is visual column + when zero: "col" is byte index + nr error number + text description of the error + type single-character error type, 'E', 'W', etc. + + The "col", "vcol", "nr", "type" and "text" entries are + optional. Either "lnum" or "pattern" entry can be used to + locate a matching error line. + If the "filename" and "bufnr" entries are not present or + neither the "lnum" or "pattern" entries are present, then the + item will not be handled as an error line. + If both "pattern" and "lnum" are present then "pattern" will + be used. + Note that the list is not exactly the same as what + |getqflist()| returns. + + If {action} is set to 'a', then the items from {list} are + added to the existing quickfix list. If there is no existing + list, then a new list is created. If {action} is set to 'r', + then the items from the current quickfix list are replaced + with the items from {list}. If {action} is not present or is + set to ' ', then a new list is created. + + Returns zero for success, -1 for failure. + + This function can be used to create a quickfix list + independent of the 'errorformat' setting. Use a command like + ":cc 1" to jump to the first position. + + *setreg()* setreg({regname}, {value} [,{options}]) Set the register {regname} to {value}. @@ -2281,7 +4439,7 @@ < This example shows using the functions to save and restore a register. > - :let var_a = getreg('a') + :let var_a = getreg('a', 1) :let var_amode = getregtype('a') .... :call setreg('a', var_a, var_amode) @@ -2290,17 +4448,170 @@ nothing: > :call setreg('a', '', 'al') -setwinvar({nr}, {varname}, {val}) *setwinvar()* - Set option or local variable {varname} in window {nr} to +settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* + Set option or local variable {varname} in window {winnr} to {val}. + Tabs are numbered starting with one. For the current tabpage + use |setwinvar()|. + When {winnr} is zero the current window is used. This also works for a global or local buffer option, but it doesn't work for a global or local buffer variable. For a local buffer option the global value is unchanged. Note that the variable name without "w:" must be used. + Vim briefly goes to the tab page {tabnr}, this may trigger + TabLeave and TabEnter autocommands. + Examples: > + :call settabwinvar(1, 1, "&list", 0) + :call settabwinvar(3, 2, "myvar", "foobar") +< This function is not available in the |sandbox|. + +setwinvar({nr}, {varname}, {val}) *setwinvar()* + Like |settabwinvar()| for the current tab page. Examples: > :call setwinvar(1, "&list", 0) :call setwinvar(2, "myvar", "foobar") -< This function is not available in the |sandbox|. + +shellescape({string}) *shellescape()* + Escape {string} for use as shell command argument. + On MS-Windows and MS-DOS, when 'shellslash' is not set, it + will enclose {string} double quotes and double all double + quotes within {string}. + For other systems, it will enclose {string} in single quotes + and replace all "'" with "'\''". + Example: > + :echo shellescape('c:\program files\vim') +< results in: + "c:\program files\vim" ~ + Example usage: > + :call system("chmod +x -- " . shellescape(expand("%"))) + + +simplify({filename}) *simplify()* + Simplify the file name as much as possible without changing + the meaning. Shortcuts (on MS-Windows) or symbolic links (on + Unix) are not resolved. If the first path component in + {filename} designates the current directory, this will be + valid for the result as well. A trailing path separator is + not removed either. + Example: > + simplify("./dir/.././/file/") == "./file/" +< Note: The combination "dir/.." is only removed if "dir" is + a searchable directory or does not exist. On Unix, it is also + removed when "dir" is a symbolic link within the same + directory. In order to resolve all the involved symbolic + links before simplifying the path name, use |resolve()|. + + +sort({list} [, {func}]) *sort()* *E702* + Sort the items in {list} in-place. Returns {list}. If you + want a list to remain unmodified make a copy first: > + :let sortedlist = sort(copy(mylist)) +< Uses the string representation of each item to sort on. + Numbers sort after Strings, |Lists| after Numbers. + For sorting text in the current buffer use |:sort|. + 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: > + func MyCompare(i1, i2) + return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 + endfunc + let sortedlist = sort(mylist, "MyCompare") +< + + *soundfold()* +soundfold({word}) + Return the sound-folded equivalent of {word}. Uses the first + language in 'spellang' for the current window that supports + soundfolding. 'spell' must be set. When no sound folding is + possible the {word} is returned unmodified. + This can be used for making spelling suggestions. Note that + the method can be quite slow. + + *spellbadword()* +spellbadword([{sentence}]) + Without argument: The result is the badly spelled word under + or after the cursor. The cursor is moved to the start of the + bad word. When no bad word is found in the cursor line the + result is an empty string and the cursor doesn't move. + + With argument: The result is the first word in {sentence} that + is badly spelled. If there are no spelling mistakes the + result is an empty string. + + The return value is a list with two items: + - The badly spelled word or an empty string. + - The type of the spelling error: + "bad" spelling mistake + "rare" rare word + "local" word only valid in another region + "caps" word should start with Capital + Example: > + echo spellbadword("the quik brown fox") +< ['quik', 'bad'] ~ + + The spelling information for the current window is used. The + 'spell' option must be set and the value of 'spelllang' is + used. + + *spellsuggest()* +spellsuggest({word} [, {max} [, {capital}]]) + Return a |List| with spelling suggestions to replace {word}. + When {max} is given up to this number of suggestions are + returned. Otherwise up to 25 suggestions are returned. + + When the {capital} argument is given and it's non-zero only + suggestions with a leading capital will be given. Use this + after a match with 'spellcapcheck'. + + {word} can be a badly spelled word followed by other text. + This allows for joining two words that were split. The + suggestions also include the following text, thus you can + replace a line. + + {word} may also be a good word. Similar words will then be + returned. {word} itself is not included in the suggestions, + although it may appear capitalized. + + The spelling information for the current window is used. The + 'spell' option must be set and the values of 'spelllang' and + 'spellsuggest' are used. + + +split({expr} [, {pattern} [, {keepempty}]]) *split()* + Make a |List| out of {expr}. When {pattern} is omitted or + empty each white-separated sequence of characters becomes an + item. + Otherwise the string is split where {pattern} matches, + removing the matched characters. + When the first or last item is empty it is omitted, unless the + {keepempty} argument is given and it's non-zero. + Other empty items are kept when {pattern} matches at least one + character or when {keepempty} is non-zero. + Example: > + :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': > + :echo split('abc:def:ghi', ':\zs') +< ['abc:', 'def:', 'ghi'] ~ + Splitting a table where the first element can be empty: > + :let items = split(line, ':', 1) +< The opposite function is |join()|. + + +str2nr( {expr} [, {base}]) *str2nr()* + Convert string {expr} to a number. + {base} is the conversion base, it can be 8, 10 or 16. + When {base} is omitted base 10 is used. This also means that + a leading zero doesn't cause octal conversion to be used, as + with the default String to Number conversion. + When {base} is 16 a leading "0x" or "0X" is ignored. With a + different base the result will be zero. + Text after the number is silently ignored. + strftime({format} [, {time}]) *strftime()* The result is a String, which is a formatted date and time, as @@ -2318,51 +4629,85 @@ :echo strftime("%H:%M") 11:55 :echo strftime("%c", getftime("file.c")) Show mod time of file.c. -< -stridx({haystack}, {needle}) *stridx()* - The result is a Number, which gives the index in {haystack} of - the first occurrence of the String {needle} in the String - {haystack}. The search is done case-sensitive. For advanced - searches use |match()|. - If the {needle} does not occur in {haystack} it returns -1. - See also |strridx()|. Examples: > +< Not available on all systems. To check use: > + :if exists("*strftime") + +stridx({haystack}, {needle} [, {start}]) *stridx()* + The result is a Number, which gives the byte index in + {haystack} of the first occurrence of the String {needle}. + If {start} is specified, the search starts at index {start}. + This can be used to find a second match: > + :let comma1 = stridx(line, ",") + :let comma2 = stridx(line, ",", comma1 + 1) +< The search is done case-sensitive. + For pattern searches use |match()|. + -1 is returned if the {needle} does not occur in {haystack}. + See also |strridx()|. + Examples: > :echo stridx("An Example", "Example") 3 :echo stridx("Starting point", "Start") 0 :echo stridx("Starting point", "start") -1 -< +< *strstr()* *strchr()* + stridx() works similar to the C function strstr(). When used + with a single character it works similar to strchr(). + + *string()* +string({expr}) Return {expr} converted to a String. If {expr} is a Number, + String or a composition of them, then the result can be parsed + back with |eval()|. + {expr} type result ~ + String 'string' + Number 123 + Funcref function('name') + List [item, item] + Dictionary {key: value, key: value} + Note that in String values the ' character is doubled. + *strlen()* strlen({expr}) The result is a Number, which is the length of the String - {expr} in bytes. If you want to count the number of - multi-byte characters use something like this: > + {expr} in bytes. + If you want to count the number of multi-byte characters (not + counting composing characters) use something like this: > :let len = strlen(substitute(str, ".", "x", "g")) - -< Composing characters are not counted. +< + If the argument is a Number it is first converted to a String. + For other types an error is given. + Also see |len()|. strpart({src}, {start}[, {len}]) *strpart()* - The result is a String, which is part of {src}, - starting from character {start}, with the length {len}. - When non-existing characters are included, this doesn't result - in an error, the characters are simply omitted. - If {len} is missing, the copy continues from {start} till - the end of the {src}. > + The result is a String, which is part of {src}, starting from + byte {start}, with the byte length {len}. + When non-existing bytes are included, this doesn't result in + an error, the bytes are simply omitted. + If {len} is missing, the copy continues from {start} till the + end of the {src}. > strpart("abcdefg", 3, 2) == "de" strpart("abcdefg", -2, 4) == "ab" strpart("abcdefg", 5, 4) == "fg" strpart("abcdefg", 3) == "defg" < Note: To get the first character, {start} must be 0. For - example, to get three characters under and after the cursor: > - strpart(getline(line(".")), col(".") - 1, 3) + example, to get three bytes under and after the cursor: > + strpart(getline("."), col(".") - 1, 3) < -strridx({haystack}, {needle}) *strridx()* - The result is a Number, which gives the index in {haystack} of - the last occurrence of the String {needle} in the String - {haystack}. The search is done case-sensitive. For advanced - searches use |match()|. - If the {needle} does not occur in {haystack} it returns -1. +strridx({haystack}, {needle} [, {start}]) *strridx()* + The result is a Number, which gives the byte index in + {haystack} of the last occurrence of the String {needle}. + When {start} is specified, matches beyond this index are + ignored. This can be used to find a match before a previous + match: > + :let lastcomma = strridx(line, ",") + :let comma2 = strridx(line, ",", lastcomma - 1) +< The search is done case-sensitive. + For pattern searches use |match()|. + -1 is returned if the {needle} does not occur in {haystack}. + If the {needle} is empty the length of {haystack} is returned. See also |stridx()|. Examples: > :echo strridx("an angry armadillo", "an") 3 -< +< *strrchr()* + When used with a single character it works similar to the C + function strrchr(). + strtrans({expr}) *strtrans()* The result is a String, which is {expr} with all unprintable characters translated into printable characters |'isprint'|. @@ -2378,7 +4723,7 @@ Example: > :s/\d\+/\=submatch(0) + 1/ < This finds the first number in the line and adds one to it. - Line breaks are included as a newline character. + A line break is included as a newline character. substitute({expr}, {pat}, {sub}, {flags}) *substitute()* The result is a String, which is a copy of {expr}, in which @@ -2386,11 +4731,12 @@ like the ":substitute" command (without any flags). But the matching with {pat} is always done like the 'magic' option is set and 'cpoptions' is empty (to make scripts portable). + 'ignorecase' is still relevant. See |string-match| for how {pat} is used. And a "~" in {sub} is not replaced with the previous {sub}. Note that some codes in {sub} have a special meaning |sub-replace-special|. For example, to replace something with - a literal "\n", use "\\\\n" or '\\n'. + "\n" (two characters), use "\\\\n" or '\\n'. When {pat} does not match in {expr}, {expr} is returned unmodified. When {flags} is "g", all matches of {pat} in {expr} are @@ -2401,13 +4747,15 @@ :echo substitute("testing", ".*", "\\U\\0", "") < results in "TESTING". -synID({line}, {col}, {trans}) *synID()* +synID({lnum}, {col}, {trans}) *synID()* The result is a Number, which is the syntax ID at the position - {line} and {col} in the current window. + {lnum} and {col} in the current window. The syntax ID can be used with |synIDattr()| and |synIDtrans()| to obtain syntax information about text. - {col} is 1 for the leftmost column, {line} is 1 for the first - line. + + {col} is 1 for the leftmost column, {lnum} is 1 for the first + line. 'synmaxcol' applies, in a longer line zero is returned. + When {trans} is non-zero, transparent items are reduced to the item that they reveal. This is useful when wanting to know the effective color. When {trans} is zero, the transparent @@ -2442,6 +4790,7 @@ "reverse" "1" if reverse "inverse" "1" if inverse (= reverse) "underline" "1" if underlined + "undercurl" "1" if undercurled Example (echoes the color of the syntax item under the cursor): > @@ -2453,10 +4802,15 @@ highlight the character. Highlight links given with ":highlight link" are followed. - *system()* -system({expr}) Get the output of the shell command {expr}. Note: newlines - in {expr} may cause the command to fail. The characters in - 'shellquote' and 'shellxquote' may also cause trouble. +system({expr} [, {input}]) *system()* *E677* + Get the output of the shell command {expr}. + When {input} is given, this string is written to a file and + passed as stdin to the command. The string is written as-is, + you need to take care of using the correct line separators + yourself. Pipes are not used. + Note: newlines in {expr} may cause the command to fail. The + characters in 'shellquote' and 'shellxquote' may also cause + trouble. This is not to be used for interactive commands. The result is a String. Example: > @@ -2471,11 +4825,95 @@ For Unix and OS/2 braces are put around {expr} to allow for concatenated commands. + The command will be executed in "cooked" mode, so that a + CTRL-C will interrupt the command (on Unix at least). + The resulting error code can be found in |v:shell_error|. This function will fail in |restricted-mode|. + + Note that any wrong value in the options mentioned above may + make the function fail. It has also been reported to fail + when using a security agent application. Unlike ":!cmd" there is no automatic check for changed files. Use |:checktime| to force a check. + +tabpagebuflist([{arg}]) *tabpagebuflist()* + The result is a |List|, where each item is the number of the + buffer associated with each window in the current tab page. + {arg} specifies the number of tab page to be used. When + omitted the current tab page is used. + When {arg} is invalid the number zero is returned. + To get a list of all buffers in all tabs use this: > + tablist = [] + for i in range(tabpagenr('$')) + call extend(tablist, tabpagebuflist(i + 1)) + endfor +< Note that a buffer may appear in more than one window. + + +tabpagenr([{arg}]) *tabpagenr()* + The result is a Number, which is the number of the current + tab page. The first tab page has number 1. + When the optional argument is "$", the number of the last tab + page is returned (the tab page count). + The number can be used with the |:tab| command. + + +tabpagewinnr({tabarg}, [{arg}]) *tabpagewinnr()* + Like |winnr()| but for tab page {arg}. + {tabarg} specifies the number of tab page to be used. + {arg} is used like with |winnr()|: + - When omitted the current window number is returned. This is + the window which will be used when going to this tab page. + - When "$" the number of windows is returned. + - When "#" the previous window nr is returned. + Useful examples: > + tabpagewinnr(1) " current window of tab page 1 + tabpagewinnr(4, '$') " number of windows in tab page 4 +< When {tabarg} is invalid zero is returned. + + *tagfiles()* +tagfiles() Returns a |List| with the file names used to search for tags + for the current buffer. This is the 'tags' option expanded. + + +taglist({expr}) *taglist()* + Returns a list of tags matching the regular expression {expr}. + Each list item is a dictionary with at least the following + entries: + name Name of the tag. + filename Name of the file where the tag is + defined. + cmd Ex command used to locate the tag in + the file. + kind Type of the tag. The value for this + entry depends on the language specific + kind values generated by the ctags + tool. + static A file specific tag. Refer to + |static-tag| for more information. + The "kind" entry is only available when using Exuberant ctags + generated tags file. More entries may be present, depending + on the content of the tags file: access, implementation, + inherits and signature. Refer to the ctags documentation for + information about these fields. For C code the fields + "struct", "class" and "enum" may appear, they give the name of + the entity the tag is contained in. + + The ex-command 'cmd' can be either an ex search pattern, a + line number or a line number followed by a byte number. + + If there are no matching tags, then an empty list is returned. + + To get an exact tag match, the anchors '^' and '$' should be + used in {expr}. Refer to |tag-regexp| for more information + about the tag search regular expression pattern. + + Refer to |'tags'| for information about how the tags file is + located by Vim. Refer to |tags-file-format| for the format of + the tags file generated by the different ctags tools. + tempname() *tempname()* *temp-file-name* The result is a String, which is the name of a file that doesn't exist. It can be used for a temporary file. The name @@ -2499,10 +4937,38 @@ characters turned into uppercase (just like applying |gU| to the string). -type({expr}) *type()* - The result is a Number: - 0 if {expr} has the type Number - 1 if {expr} has the type String +tr({src}, {fromstr}, {tostr}) *tr()* + The result is a copy of the {src} string with all characters + which appear in {fromstr} replaced by the character in that + position in the {tostr} string. Thus the first character in + {fromstr} is translated into the first character in {tostr} + and so on. Exactly like the unix "tr" command. + This code also deals with multibyte characters properly. + + Examples: > + echo tr("hello there", "ht", "HT") +< returns "Hello THere" > + echo tr("", "<>", "{}") +< returns "{blob}" + + *type()* +type({expr}) The result is a Number, depending on the type of {expr}: + Number: 0 + String: 1 + Funcref: 2 + List: 3 + Dictionary: 4 + To avoid the magic numbers it should be used this way: > + :if type(myvar) == type(0) + :if type(myvar) == type("") + :if type(myvar) == type(function("tr")) + :if type(myvar) == type([]) + :if type(myvar) == type({}) + +values({dict}) *values()* + Return a |List| with all the values of {dict}. The |List| is + in arbitrary order. + virtcol({expr}) *virtcol()* The result is a Number, which is the screen column of the file @@ -2512,6 +4978,14 @@ position, the returned Number will be the column at the end of the . For example, for a in column 1, with 'ts' set to 8, it returns 8. + For the use of {expr} see |col()|. Additionally you can use + [lnum, col]: a |List| with the line and column number. When + "lnum" or "col" is out of range then virtcol() returns zero. + When 'virtualedit' is used it can be [lnum, col, off], where + "off" is the offset in screen columns from the start of the + character. E.g., a position within a Tab or after the last + character. + For the byte position use |col()|. When Virtual editing is active in the current mode, a position beyond the end of the line can be returned. |'virtualedit'| The accepted positions are: @@ -2530,10 +5004,11 @@ visualmode([expr]) *visualmode()* The result is a String, which describes the last Visual mode - used. Initially it returns an empty string, but once Visual - mode has been used, it returns "v", "V", or "" (a - single CTRL-V character) for character-wise, line-wise, or - block-wise Visual mode respectively. + used in the current buffer. Initially it returns an empty + string, but once Visual mode has been used, it returns "v", + "V", or "" (a single CTRL-V character) for + character-wise, line-wise, or block-wise Visual mode + respectively. Example: > :exe "normal " . visualmode() < This enters the same Visual mode as before. It is also useful @@ -2570,10 +5045,57 @@ winline() The result is a Number, which is the screen line of the cursor in the window. This is counting screen lines from the top of the window. The first line is one. + If the cursor was moved the view on the file will be updated + first, this may cause a scroll. *winnr()* -winnr() The result is a Number, which is the number of the current +winnr([{arg}]) The result is a Number, which is the number of the current window. The top window has number 1. + When the optional argument is "$", the number of the + last window is returned (the window count). + When the optional argument is "#", the number of the last + accessed window is returned (where |CTRL-W_p| goes to). + If there is no previous window 0 is returned. + The number can be used with |CTRL-W_w| and ":wincmd w" + |:wincmd|. + + *winrestcmd()* +winrestcmd() Returns a sequence of |:resize| commands that should restore + the current window sizes. Only works properly when no windows + are opened or closed and the current window and tab page is + unchanged. + Example: > + :let cmd = winrestcmd() + :call MessWithWindowSizes() + :exe cmd +< + *winrestview()* +winrestview({dict}) + Uses the |Dictionary| returned by |winsaveview()| to restore + the view of the current window. + If you have changed the values the result is unpredictable. + If the window size changed the result won't be the same. + + *winsaveview()* +winsaveview() Returns a |Dictionary| that contains information to restore + the view of the current window. Use |winrestview()| to + restore the view. + This is useful if you have a mapping that jumps around in the + buffer and you want to go back to the original view. + This does not save fold information. Use the 'foldenable' + option to temporarily switch off folding, so that folds are + not opened when moving around. + The return value includes: + lnum cursor line number + col cursor column + coladd cursor column offset for 'virtualedit' + curswant column for vertical movement + topline first line in the window + topfill filler lines, only in diff mode + leftcol first column displayed + skipcol columns skipped + Note that no option values are saved. + winwidth({nr}) *winwidth()* The result is a Number, which is the width of window {nr}. @@ -2586,6 +5108,26 @@ : exe "normal 50\|" :endif < + *writefile()* +writefile({list}, {fname} [, {binary}]) + Write |List| {list} to file {fname}. Each list item is + separated with a NL. Each list item must be a String or + Number. + When {binary} is equal to "b" binary mode is used: There will + not be a NL after the last list item. An empty item at the + end does cause the last line in the file to end in a NL. + All NL characters are replaced with a NUL character. + Inserting CR characters needs to be done before passing {list} + to writefile(). + An existing file is overwritten, if possible. + When the write fails -1 is returned, otherwise 0. There is an + error message if the file can't be created or when writing + fails. + Also see |readfile()|. + To copy a file byte for byte: > + :let fl = readfile("foo", "b") + :call writefile(fl, "foocopy", "b") +< *feature-list* There are three types of features: @@ -2595,16 +5137,19 @@ 2. Features that are only supported when certain conditions have been met. Example: > :if has("gui_running") +< *has-patch* 3. Included patches. First check |v:version| for the version of Vim. Then the "patch123" feature means that patch 123 has been included for - this version. + this version. Example (checking version 6.2.148 or later): > + :if v:version > 602 || v:version == 602 && has("patch148") all_builtin_terms Compiled with all builtin terminals enabled. amiga Amiga version of Vim. arabic Compiled with Arabic support |Arabic|. arp Compiled with ARP support (Amiga). -autocmd Compiled with autocommands support. +autocmd Compiled with autocommand support. |autocommand| balloon_eval Compiled with |balloon-eval| support. +balloon_multiline GUI supports multiline balloons. beos BeOS version of Vim. browse Compiled with |:browse| support, and browse() will work. @@ -2637,6 +5182,8 @@ |'hlsearch'| farsi Compiled with Farsi support |farsi|. file_in_path Compiled with support for |gf| and || +filterpipe When 'shelltemp' is off pipes are used for shell + read/write/filter commands find_in_path Compiled with support for include file searches |+find_in_path|. fname_case Case in file names matters (for Amiga, MS-DOS, and @@ -2647,7 +5194,6 @@ gettext Compiled with message translation |multi-lang| gui Compiled with GUI enabled. gui_athena Compiled with Athena GUI. -gui_beos Compiled with BeOs GUI. gui_gtk Compiled with GTK+ GUI (any version). gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined). gui_mac Compiled with Macintosh GUI. @@ -2685,7 +5231,9 @@ multi_byte Compiled with support for editing Korean et al. multi_byte_ime Compiled with support for IME input method. multi_lang Compiled with support for multiple languages. +mzscheme Compiled with MzScheme interface |mzscheme|. netbeans_intg Compiled with support for |netbeans|. +netbeans_enabled Compiled with support for |netbeans| and it's used. ole Compiled with OLE automation support for Win32. os2 OS/2 version of Vim. osfiletype Compiled with support for osfiletypes |+osfiletype| @@ -2693,20 +5241,23 @@ perl Compiled with Perl interface. postscript Compiled with PostScript file printing. printer Compiled with |:hardcopy| support. +profile Compiled with |:profile| support. python Compiled with Python interface. qnx QNX version of Vim. quickfix Compiled with |quickfix| support. +reltime Compiled with |reltime()| support. rightleft Compiled with 'rightleft' support. ruby Compiled with Ruby interface |ruby|. scrollbind Compiled with 'scrollbind' support. showcmd Compiled with 'showcmd' support. signs Compiled with |:sign| support. smartindent Compiled with 'smartindent' support. -sniff Compiled with SniFF interface support. +sniff Compiled with SNiFF interface support. statusline Compiled with support for 'statusline', 'rulerformat' and special formats of 'titlestring' and 'iconstring'. sun_workshop Compiled with support for Sun |workshop|. -syntax Compiled with syntax highlighting support. +spell Compiled with spell checking support |spell|. +syntax Compiled with syntax highlighting support |syntax|. syntax_items There are active syntax highlighting items for the current buffer. system Compiled to use system() instead of fork()/exec(). @@ -2741,6 +5292,7 @@ winaltkeys Compiled with 'winaltkeys' option. win16 Win16 version of Vim (MS-Windows 3.1). win32 Win32 version of Vim (MS-Windows 95/98/ME/NT/2000/XP). +win64 Win64 version of Vim (MS-Windows 64 bit). win32unix Win32 version of Vim, using Unix files (Cygwin) win95 Win32 version for MS-Windows 95/98/ME. writebackup Compiled with 'writebackup' default on. @@ -2786,7 +5338,8 @@ avoid obvious, short names. A good habit is to start the function name with the name of the script, e.g., "HTMLcolor()". -It's also possible to use curly braces, see |curly-braces-names|. +It's also possible to use curly braces, see |curly-braces-names|. And the +|autoload| facility is useful to define a function only when it's called. *local-function* A function local to a script must start with "s:". A local script function @@ -2799,34 +5352,47 @@ :fu[nction] List all functions and their arguments. :fu[nction] {name} List function {name}. + {name} can also be a |Dictionary| entry that is a + |Funcref|: > + :function dict.init + +:fu[nction] /{pattern} List functions with a name matching {pattern}. + Example that lists all functions ending with "File": > + :function /File$ +< + *:function-verbose* +When 'verbose' is non-zero, listing a function will also display where it was +last defined. Example: > + + :verbose function SetFileTypeSH + function SetFileTypeSH(name) + Last set from /usr/share/vim/vim-7.0/filetype.vim +< +See |:verbose-cmd| for more information. + *E124* *E125* -:fu[nction][!] {name}([arguments]) [range] [abort] +:fu[nction][!] {name}([arguments]) [range] [abort] [dict] Define a new function by the name {name}. The name must be made of alphanumeric characters and '_', and must start with a capital or "s:" (see above). - *function-argument* *a:var* - An argument can be defined by giving its name. In the - function this can then be used as "a:name" ("a:" for - argument). - Up to 20 arguments can be given, separated by commas. - Finally, an argument "..." can be specified, which - means that more arguments may be following. In the - function they can be used as "a:1", "a:2", etc. "a:0" - is set to the number of extra arguments (which can be - 0). - When not using "...", the number of arguments in a - function call must be equal to the number of named - arguments. When using "...", the number of arguments - may be larger. - It is also possible to define a function without any - arguments. You must still supply the () then. - The body of the function follows in the next lines, - until the matching |:endfunction|. It is allowed to - define another function inside a function body. + + {name} can also be a |Dictionary| entry that is a + |Funcref|: > + :function dict.init(arg) +< "dict" must be an existing dictionary. The entry + "init" is added if it didn't exist yet. Otherwise [!] + is required to overwrite an existing function. The + result is a |Funcref| to a numbered function. The + function can only be used with a |Funcref| and will be + deleted if there are no more references to it. *E127* *E122* When a function by this name already exists and [!] is not used an error message is given. When [!] is used, - an existing function is silently replaced. + an existing function is silently replaced. Unless it + is currently being executed, that is an error. + + For the {arguments} see |function-argument|. + *a:firstline* *a:lastline* When the [range] argument is added, the function is expected to take care of a range itself. The range is @@ -2834,8 +5400,15 @@ is excluded, ":{range}call" will call the function for each line in the range, with the cursor on the start of each line. See |function-range-example|. + When the [abort] argument is added, the function will abort as soon as an error is detected. + + When the [dict] argument is added, the function must + be invoked through an entry in a |Dictionary|. The + local variable "self" will then be set to the + dictionary. See |Dictionary-function|. + The last used search pattern and the redo command "." will not be changed by the function. @@ -2845,7 +5418,12 @@ *:delf* *:delfunction* *E130* *E131* :delf[unction] {name} Delete function {name}. - + {name} can also be a |Dictionary| entry that is a + |Funcref|: > + :delfunc dict.init +< This will remove the "init" entry from "dict". The + function is deleted if there are no more references to + it. *:retu* *:return* *E133* :retu[rn] [expr] Return from a function. When "[expr]" is given, it is evaluated and returned as the result of the function. @@ -2862,7 +5440,33 @@ nested ":try"s inside the function. The function returns at the outermost ":endtry". + *function-argument* *a:var* +An argument can be defined by giving its name. In the function this can then +be used as "a:name" ("a:" for argument). + *a:0* *a:1* *a:000* *E740* +Up to 20 arguments can be given, separated by commas. After the named +arguments an argument "..." can be specified, which means that more arguments +may optionally be following. In the function the extra arguments can be used +as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which +can be 0). "a:000" is set to a |List| that contains these arguments. Note +that "a:1" is the same as "a:000[0]". + *E742* +The a: scope and the variables in it cannot be changed, they are fixed. +However, if a |List| or |Dictionary| is used, you can changes their contents. +Thus you can pass a |List| to a function and have the function add an item to +it. If you want to make sure the function cannot change a |List| or +|Dictionary| use |:lockvar|. +When not using "...", the number of arguments in a function call must be equal +to the number of named arguments. When using "...", the number of arguments +may be larger. + +It is also possible to define a function without any arguments. You must +still supply the () then. The body of the function follows in the next lines, +until the matching |:endfunction|. It is allowed to define another function +inside a function body. + + *local-variables* Inside a function variables can be used. These are local variables, which will disappear when the function returns. G