diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 4583 |
1 files changed, 4583 insertions, 0 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt new file mode 100644 index 0000000000..4685ff5e6a --- /dev/null +++ b/runtime/doc/eval.txt @@ -0,0 +1,4583 @@ +*eval.txt* For Vim version 7.0aa. Last change: 2004 May 18 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Expression evaluation *expression* *expr* *E15* *eval* + +Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|. + +Note: Expression evaluation can be disabled at compile time. If this has been +done, the features in this document are not available. See |+eval| and the +last chapter below. + +1. Variables |variables| +2. Expression syntax |expression-syntax| +3. Internal variable |internal-variables| +4. Builtin Functions |functions| +5. Defining functions |user-functions| +6. Curly braces names |curly-braces-names| +7. Commands |expression-commands| +8. Exception handling |exception-handling| +9. Examples |eval-examples| +10. No +eval feature |no-eval-feature| +11. The sandbox |eval-sandbox| + +{Vi does not have any of these commands} + +============================================================================== +1. Variables *variables* + +There are two types of variables: + +Number a 32 bit signed number. +String a NUL terminated string of 8-bit unsigned characters. + +These are converted automatically, depending on how they are used. + +Conversion from a Number to a String is by making the ASCII representation of +the Number. Examples: > + Number 123 --> String "123" + Number 0 --> String "0" + Number -1 --> String "-1" + +Conversion from a String to a Number is done by converting the first digits +to a number. Hexadecimal "0xf9" and Octal "017" numbers are recognized. If +the String doesn't start with digits, the result is zero. Examples: > + String "456" --> Number 456 + String "6bar" --> Number 6 + String "foo" --> Number 0 + String "0xf1" --> Number 241 + String "0100" --> Number 64 + String "-8" --> Number -8 + String "+8" --> Number 0 + +To force conversion from String to Number, add zero to it: > + :echo "0100" + 0 + +For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE. + +Note that in the command > + :if "foo" +"foo" is converted to 0, which means FALSE. To test for a non-empty string, +use strlen(): > + :if strlen("foo") + +If you need to know the type of a variable or expression, use the |type()| +function. + +When the '!' flag is included in the 'viminfo' option, global variables that +start with an uppercase letter, and don't contain a lowercase letter, are +stored in the viminfo file |viminfo-file|. + +When the 'sessionoptions' option contains "global", global variables that +start with an uppercase letter and contain at least one lowercase letter are +stored in the session file |session-file|. + +variable name can be stored where ~ +my_var_6 not +My_Var_6 session file +MY_VAR_6 viminfo file + + +It's possible to form a variable name with curly braces, see +|curly-braces-names|. + +============================================================================== +2. Expression syntax *expression-syntax* + +Expression syntax summary, from least to most significant: + +|expr1| expr2 ? expr1 : expr1 if-then-else + +|expr2| expr3 || expr3 .. logical OR + +|expr3| expr4 && expr4 .. logical AND + +|expr4| expr5 == expr5 equal + expr5 != expr5 not equal + expr5 > expr5 greater than + expr5 >= expr5 greater than or equal + expr5 < expr5 smaller than + expr5 <= expr5 smaller than or equal + expr5 =~ expr5 regexp matches + expr5 !~ expr5 regexp doesn't match + + expr5 ==? expr5 equal, ignoring case + expr5 ==# expr5 equal, match case + etc. As above, append ? for ignoring case, # for + matching case + +|expr5| expr6 + expr6 .. number addition + expr6 - expr6 .. number subtraction + expr6 . expr6 .. string concatenation + +|expr6| expr7 * expr7 .. number multiplication + expr7 / expr7 .. number division + expr7 % expr7 .. number modulo + +|expr7| ! expr7 logical NOT + - expr7 unary minus + + expr7 unary plus + expr8 + +|expr8| expr9[expr1] index in String + +|expr9| number number constant + "string" string constant + 'string' literal string constant + &option option value + (expr1) nested expression + variable internal variable + va{ria}ble internal variable with curly braces + $VAR environment variable + @r contents of register 'r' + function(expr1, ...) function call + func{ti}on(expr1, ...) function call with curly braces + + +".." indicates that the operations in this level can be concatenated. +Example: > + &nu || &list && &shell == "csh" + +All expressions within one level are parsed from left to right. + + +expr1 *expr1* *E109* +----- + +expr2 ? expr1 : expr1 + +The expression before the '?' is evaluated to a number. If it evaluates to +non-zero, the result is the value of the expression between the '?' and ':', +otherwise the result is the value of the expression after the ':'. +Example: > + :echo lnum == 1 ? "top" : lnum + +Since the first expression is an "expr2", it cannot contain another ?:. The +other two expressions can, thus allow for recursive use of ?:. +Example: > + :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum + +To keep this readable, using |line-continuation| is suggested: > + :echo lnum == 1 + :\ ? "top" + :\ : lnum == 1000 + :\ ? "last" + :\ : lnum + + +expr2 and expr3 *expr2* *expr3* +--------------- + + *expr-barbar* *expr-&&* +The "||" and "&&" operators take one argument on each side. The arguments +are (converted to) Numbers. The result is: + + input output ~ +n1 n2 n1 || n2 n1 && n2 ~ +zero zero zero zero +zero non-zero non-zero zero +non-zero zero non-zero zero +non-zero non-zero non-zero non-zero + +The operators can be concatenated, for example: > + + &nu || &list && &shell == "csh" + +Note that "&&" takes precedence over "||", so this has the meaning of: > + + &nu || (&list && &shell == "csh") + +Once the result is known, the expression "short-circuits", that is, further +arguments are not evaluated. This is like what happens in C. For example: > + + let a = 1 + echo a || b + +This is valid even if there is no variable called "b" because "a" is non-zero, +so the result must be non-zero. Similarly below: > + + echo exists("b") && b == "yes" + +This is valid whether "b" has been defined or not. The second clause will +only be evaluated if "b" has been defined. + + +expr4 *expr4* +----- + +expr5 {cmp} expr5 + +Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1 +if it evaluates to true. + + *expr-==* *expr-!=* *expr->* *expr->=* + *expr-<* *expr-<=* *expr-=~* *expr-!~* + *expr-==#* *expr-!=#* *expr->#* *expr->=#* + *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#* + *expr-==?* *expr-!=?* *expr->?* *expr->=?* + *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?* + use 'ignorecase' match case ignore case ~ +equal == ==# ==? +not equal != !=# !=? +greater than > ># >? +greater than or equal >= >=# >=? +smaller than < <# <? +smaller than or equal <= <=# <=? +regexp matches =~ =~# =~? +regexp doesn't match !~ !~# !~? + +Examples: +"abc" ==# "Abc" evaluates to 0 +"abc" ==? "Abc" evaluates to 1 +"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise + +When comparing a String with a Number, the String is converted to a Number, +and the comparison is done on Numbers. This means that "0 == 'x'" is TRUE, +because 'x' converted to a Number is zero. + +When comparing two Strings, this is done with strcmp() or stricmp(). This +results in the mathematical difference (comparing byte values), not +necessarily the alphabetical difference in the local language. + +When using the operators with a trailing '#", or the short version and +'ignorecase' is off, the comparing is done with strcmp(). + +When using the operators with a trailing '?', or the short version and +'ignorecase' is set, the comparing is done with stricmp(). + +The "=~" and "!~" operators match the lefthand argument with the righthand +argument, which is used as a pattern. See |pattern| for what a pattern is. +This matching is always done like 'magic' was set and 'cpoptions' is empty, no +matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts +portable. To avoid backslashes in the regexp pattern to be doubled, use a +single-quote string, see |literal-string|. +Since a string is considered to be a single line, a multi-line pattern +(containing \n, backslash-n) will not match. However, a literal NL character +can be matched like an ordinary character. Examples: + "foo\nbar" =~ "\n" evaluates to 1 + "foo\nbar" =~ "\\n" evaluates to 0 + + +expr5 and expr6 *expr5* *expr6* +--------------- +expr6 + expr6 .. number addition *expr-+* +expr6 - expr6 .. number subtraction *expr--* +expr6 . expr6 .. string concatenation *expr-.* + +expr7 * expr7 .. number multiplication *expr-star* +expr7 / expr7 .. number division *expr-/* +expr7 % expr7 .. number modulo *expr-%* + +For all, except ".", Strings are converted to Numbers. + +Note the difference between "+" and ".": + "123" + "456" = 579 + "123" . "456" = "123456" + +When the righthand side of '/' is zero, the result is 0x7fffffff. +When the righthand side of '%' is zero, the result is 0. + + +expr7 *expr7* +----- +! expr7 logical NOT *expr-!* +- expr7 unary minus *expr-unary--* ++ expr7 unary plus *expr-unary-+* + +For '!' non-zero becomes zero, zero becomes one. +For '-' the sign of the number is changed. +For '+' the number is unchanged. + +A String will be converted to a Number first. + +These three can be repeated and mixed. Examples: + !-1 == 0 + !!8 == 1 + --9 == 9 + + +expr8 *expr8* +----- +expr9[expr1] index in String *expr-[]* *E111* + +This results in a String that contains the expr1'th single byte from expr9. +expr9 is used as a String, expr1 as a Number. Note that this doesn't work for +multi-byte encodings. + +Note that index zero gives the first character. This is like it works in C. +Careful: text column numbers start with one! Example, to get the character +under the cursor: > + :let c = getline(line("."))[col(".") - 1] + +If the length of the String is less than the index, the result is an empty +String. + + *expr9* +number +------ +number number constant *expr-number* + +Decimal, Hexadecimal (starting with 0x or 0X), or Octal (starting with 0). + + +string *expr-string* *E114* +------ +"string" string constant *expr-quote* + +Note that double quotes are used. + +A string constant accepts these special characters: +\... three-digit octal number (e.g., "\316") +\.. two-digit octal number (must be followed by non-digit) +\. one-digit octal number (must be followed by non-digit) +\x.. byte specified with two hex numbers (e.g., "\x1f") +\x. byte specified with one hex number (must be followed by non-hex char) +\X.. same as \x.. +\X. same as \x. +\u.... character specified with up to 4 hex numbers, stored according to the + current value of 'encoding' (e.g., "\u02a4") +\U.... same as \u.... +\b backspace <BS> +\e escape <Esc> +\f formfeed <FF> +\n newline <NL> +\r return <CR> +\t tab <Tab> +\\ backslash +\" double quote +\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. + +Note that "\000" and "\x00" force the end of the string. + + +literal-string *literal-string* *E115* +--------------- +'string' literal string constant *expr-'* + +Note that single quotes are used. + +This string is taken literally. No backslashes are removed or have a special +meaning. A literal-string cannot contain a single quote. Use a normal string +for that. + + +option *expr-option* *E112* *E113* +------ +&option option value, local value if possible +&g:option global option value +&l:option local option value + +Examples: > + echo "tabstop is " . &tabstop + if &insertmode + +Any option name can be used here. See |options|. When using the local value +and there is no buffer-local or window-local value, the global value is used +anyway. + + +register *expr-register* +-------- +@r contents of register 'r' + +The result is the contents of the named register, as a single string. +Newlines are inserted where required. To get the contents of the unnamed +register use @" or @@. The '=' register can not be used here. See +|registers| for an explanation of the available registers. + + +nesting *expr-nesting* *E110* +------- +(expr1) nested expression + + +environment variable *expr-env* +-------------------- +$VAR environment variable + +The String value of any environment variable. When it is not defined, the +result is an empty string. + *expr-env-expand* +Note that there is a difference between using $VAR directly and using +expand("$VAR"). Using it directly will only expand environment variables that +are known inside the current Vim session. Using expand() will first try using +the environment variables known inside the current Vim session. If that +fails, a shell will be used to expand the variable. This can be slow, but it +does expand all variables that the shell knows about. Example: > + :echo $version + :echo expand("$version") +The first one probably doesn't echo anything, the second echoes the $version +variable (if your shell supports it). + + +internal variable *expr-variable* +----------------- +variable internal variable +See below |internal-variables|. + + +function call *expr-function* *E116* *E117* *E118* *E119* *E120* +------------- +function(expr1, ...) function call +See below |functions|. + + +============================================================================== +3. Internal variable *internal-variables* *E121* + *E461* +An internal variable name can be made up of letters, digits and '_'. But it +cannot start with a digit. It's also possible to use curly braces, see +|curly-braces-names|. + +An internal variable is created with the ":let" command |:let|. +An internal variable is destroyed with the ":unlet" command |:unlet|. +Using a name that isn't an internal variable, or an internal variable that has +been destroyed, results in an error. + +There are several name spaces for variables. Which one is to be used is +specified by what is prepended: + + (nothing) In a function: local to a function; otherwise: global +|buffer-variable| b: Local to the current buffer. +|window-variable| w: Local to the current window. +|global-variable| g: Global. +|local-variable| l: Local to a function. +|script-variable| s: Local to a |:source|'ed Vim script. +|function-argument| a: Function argument (only inside a function). +|vim-variable| v: Global, predefined by Vim. + + *buffer-variable* *b:var* +A variable name that is preceded with "b:" is local to the current buffer. +Thus you can have several "b:foo" variables, one for each buffer. +This kind of variable is deleted when the buffer is wiped out or deleted with +|:bdelete|. + +One local buffer variable is predefined: + *b:changedtick-variable* *changetick* +b:changedtick The total number of changes to the current buffer. It is + incremented for each change. An undo command is also a change + in this case. This can be used to perform an action only when + the buffer has changed. Example: > + :if my_changedtick != b:changedtick + : let my_changedtick = b:changedtick + : call My_Update() + :endif +< + *window-variable* *w:var* +A variable name that is preceded with "w:" is local to the current window. It +is deleted when the window is closed. + + *global-variable* *g:var* +Inside functions global variables are accessed with "g:". Omitting this will +access a variable local to a function. But "g:" can also be used in any other +place if you like. + + *local-variable* *l:var* +Inside functions local variables are accessed without prepending anything. +But you can also prepend "l:" if you like. + + *script-variable* *s:var* +In a Vim script variables starting with "s:" can be used. They cannot be +accessed from outside of the scripts, thus are local to the script. + +They can be used in: +- commands executed while the script is sourced +- functions defined in the script +- autocommands defined in the script +- functions and autocommands defined in functions and autocommands which were + defined in the script (recursively) +- user defined commands defined in the script +Thus not in: +- other scripts sourced from this one +- mappings +- etc. + +script variables can be used to avoid conflicts with global variable names. +Take this example: + + let s:counter = 0 + function MyCounter() + let s:counter = s:counter + 1 + echo s:counter + endfunction + command Tick call MyCounter() + +You can now invoke "Tick" from any script, and the "s:counter" variable in +that script will not be changed, only the "s:counter" in the script where +"Tick" was defined is used. + +Another example that does the same: > + + let s:counter = 0 + command Tick let s:counter = s:counter + 1 | echo s:counter + +When calling a function and invoking a user-defined command, the context for +script varialbes is set to the script where the function or command was +defined. + +The script variables are also available when a function is defined inside a +function that is defined in a script. Example: > + + let s:counter = 0 + function StartCounting(incr) + if a:incr + function MyCounter() + let s:counter = s:counter + 1 + endfunction + else + function MyCounter() + let s:counter = s:counter - 1 + endfunction + endif + endfunction + +This defines the MyCounter() function either for counting up or counting down +when calling StartCounting(). It doesn't matter from where StartCounting() is +called, the s:counter variable will be accessible in MyCounter(). + +When the same script is sourced again it will use the same script variables. +They will remain valid as long as Vim is running. This can be used to +maintain a counter: > + + if !exists("s:counter") + let s:counter = 1 + echo "script executed for the first time" + else + let s:counter = s:counter + 1 + echo "script executed " . s:counter . " times now" + endif + +Note that this means that filetype plugins don't get a different set of script +variables for each buffer. Use local buffer variables instead |b:var|. + + +Predefined Vim variables: *vim-variable* *v:var* + + *v:charconvert_from* *charconvert_from-variable* +v:charconvert_from + The name of the character encoding of a file to be converted. + Only valid while evaluating the 'charconvert' option. + + *v:charconvert_to* *charconvert_to-variable* +v:charconvert_to + The name of the character encoding of a file after conversion. + Only valid while evaluating the 'charconvert' option. + + *v:cmdarg* *cmdarg-variable* +v:cmdarg This variable is used for two purposes: + 1. The extra arguments given to a file read/write command. + Currently these are "++enc=" and "++ff=". This variable is + set before an autocommand event for a file read/write + command is triggered. There is a leading space to make it + possible to append this variable directly after the + read/write command. Note: The "+cmd" argument isn't + included here, because it will be executed anyway. + 2. When printing a PostScript file with ":hardcopy" this is + the argument for the ":hardcopy" command. This can be used + in 'printexpr'. + + *v:cmdbang* *cmdbang-variable* +v:cmdbang Set like v:cmdarg for a file read/write command. When a "!" + was used the value is 1, otherwise it is 0. Note that this + can only be used in autocommands. For user commands |<bang>| + can be used. + + *v:count* *count-variable* +v:count The count given for the last Normal mode command. Can be used + to get the count before a mapping. Read-only. Example: > + :map _x :<C-U>echo "the count is " . v:count<CR> +< Note: The <C-U> is required to remove the line range that you + get when typing ':' after a count. + "count" also works, for backwards compatibility. + + *v:count1* *count1-variable* +v:count1 Just like "v:count", but defaults to one when no count is + used. + + *v:ctype* *ctype-variable* +v:ctype The current locale setting for characters of the runtime + environment. This allows Vim scripts to be aware of the + current locale encoding. Technical: it's the value of + LC_CTYPE. When not using a locale the value is "C". + This variable can not be set directly, use the |:language| + command. + See |multi-lang|. + + *v:dying* *dying-variable* +v:dying Normally zero. When a deadly signal is caught it's set to + one. When multiple signals are caught the number increases. + Can be used in an autocommand to check if Vim didn't + terminate normally. {only works on Unix} + Example: > + :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif +< + *v:errmsg* *errmsg-variable* +v:errmsg Last given error message. It's allowed to set this variable. + Example: > + :let v:errmsg = "" + :silent! next + :if v:errmsg != "" + : ... handle error +< "errmsg" also works, for backwards compatibility. + + *v:exception* *exception-variable* +v:exception The value of the exception most recently caught and not + finished. See also |v:throwpoint| and |throw-variables|. + Example: > + :try + : throw "oops" + :catch /.*/ + : echo "caught" v:exception + :endtry +< Output: "caught oops". + + *v:fname_in* *fname_in-variable* +v:fname_in The name of the input file. Only valid while evaluating: + option used for ~ + 'charconvert' file to be converted + 'diffexpr' original file + 'patchexpr' original file + 'printexpr' file to be printed + + *v:fname_out* *fname_out-variable* +v:fname_out The name of the output file. Only valid while + evaluating: + option used for ~ + 'charconvert' resulting converted file (*) + 'diffexpr' output of diff + 'patchexpr' resulting patched file + (*) When doing conversion for a write command (e.g., ":w + file") it will be equal to v:fname_in. When doing conversion + for a read command (e.g., ":e file") it will be a temporary + file and different from v:fname_in. + + *v:fname_new* *fname_new-variable* +v:fname_new The name of the new version of the file. Only valid while + evaluating 'diffexpr'. + + *v:fname_diff* *fname_diff-variable* +v:fname_diff The name of the diff (patch) file. Only valid while + evaluating 'patchexpr'. + + *v:folddashes* *folddashes-variable* +v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed + fold. + Read-only. |fold-foldtext| + + *v:foldlevel* *foldlevel-variable* +v:foldlevel Used for 'foldtext': foldlevel of closed fold. + Read-only. |fold-foldtext| + + *v:foldend* *foldend-variable* +v:foldend Used for 'foldtext': last line of closed fold. + Read-only. |fold-foldtext| + + *v:foldstart* *foldstart-variable* +v:foldstart Used for 'foldtext': first line of closed fold. + Read-only. |fold-foldtext| + + *v:lang* *lang-variable* +v:lang The current locale setting for messages of the runtime + environment. This allows Vim scripts to be aware of the + current language. Technical: it's the value of LC_MESSAGES. + The value is system dependent. + This variable can not be set directly, use the |:language| + command. + It can be different from |v:ctype| when messages are desired + in a different language than what is used for character + encoding. See |multi-lang|. + + *v:lc_time* *lc_time-variable* +v:lc_time The current locale setting for time messages of the runtime + environment. This allows Vim scripts to be aware of the + current language. Technical: it's the value of LC_TIME. + This variable can not be set directly, use the |:language| + command. See |multi-lang|. + + *v:lnum* *lnum-variable* +v:lnum Line number for the 'foldexpr' and 'indentexpr' expressions. + Only valid while one of these expressions is being evaluated. + Read-only. |fold-expr| 'indentexpr' + + *v:prevcount* *prevcount-variable* +v:prevcount The count given for the last but one Normal mode command. + This is the v:count value of the previous command. Useful if + you want to cancel Visual mode and then use the count. > + :vmap % <Esc>:call MyFilter(v:prevcount)<CR> +< Read-only. + + *v:progname* *progname-variable* +v:progname Contains the name (with path removed) with which Vim was + invoked. Allows you to do special initialisations for "view", + "evim" etc., or any other name you might symlink to Vim. + Read-only. + + *v:register* *register-variable* +v:register The name of the register supplied to the last normal mode + command. Empty if none were supplied. |getreg()| |setreg()| + + *v:servername* *servername-variable* +v:servername The resulting registered |x11-clientserver| name if any. + Read-only. + + *v:shell_error* *shell_error-variable* +v:shell_error Result of the last shell command. When non-zero, the last + shell command had an error. When zero, there was no problem. + This only works when the shell returns the error code to Vim. + The value -1 is often used when the command could not be + executed. Read-only. + Example: > + :!mv foo bar + :if v:shell_error + : echo 'could not rename "foo" to "bar"!' + :endif +< "shell_error" also works, for backwards compatibility. + + *v:statusmsg* *statusmsg-variable* +v:statusmsg Last given status message. It's allowed to set this variable. + + *v:termresponse* *termresponse-variable* +v:termresponse The escape sequence returned by the terminal for the |t_RV| + termcap entry. It is set when Vim receives an escape sequence + that starts with ESC [ or CSI and ends in a 'c', with only + digits, ';' and '.' in between. + When this option is set, the TermResponse autocommand event is + fired, so that you can react to the response from the + terminal. + The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp + is the terminal type: 0 for vt100 and 1 for vt220. Pv is the + patch level (since this was introduced in patch 95, it's + always 95 or bigger). Pc is always zero. + {only when compiled with |+termresponse| feature} + + *v:this_session* *this_session-variable* +v:this_session Full filename of the last loaded or saved session file. See + |:mksession|. It is allowed to set this variable. When no + session file has been saved, this variable is empty. + "this_session" also works, for backwards compatibility. + + *v:throwpoint* *throwpoint-variable* +v:throwpoint The point where the exception most recently caught and not + finished was thrown. Not set when commands are typed. See + also |v:exception| and |throw-variables|. + Example: > + :try + : throw "oops" + :catch /.*/ + : echo "Exception from" v:throwpoint + :endtry +< Output: "Exception from test.vim, line 2" + + *v:version* *version-variable* +v:version Version number of Vim: Major version number times 100 plus + minor version number. Version 5.0 is 500. Version 5.1 (5.01) + is 501. Read-only. "version" also works, for backwards + compatibility. + Use |has()| to check if a certain patch was included, e.g.: > + if has("patch123") +< Note that patch numbers are specific to the version, thus both + version 5.0 and 5.1 may have a patch 123, but these are + completely different. + + *v:warningmsg* *warningmsg-variable* +v:warningmsg Last given warning message. It's allowed to set this variable. + +============================================================================== +4. Builtin Functions *functions* + +See |function-list| for a list grouped by what the function is used for. + +(Use CTRL-] on the function name to jump to the full explanation) + +USAGE RESULT DESCRIPTION ~ + +append( {lnum}, {string}) Number append {string} below line {lnum} +argc() Number number of files in the argument list +argidx() Number current index in the argument list +argv( {nr}) String {nr} entry of the argument list +browse( {save}, {title}, {initdir}, {default}) + String put up a file requester +bufexists( {expr}) Number TRUE if buffer {expr} exists +buflisted( {expr}) Number TRUE if buffer {expr} is listed +bufloaded( {expr}) Number TRUE if buffer {expr} is loaded +bufname( {expr}) String Name of the buffer {expr} +bufnr( {expr}) Number Number of the buffer {expr} +bufwinnr( {expr}) Number window number of buffer {expr} +byte2line( {byte}) Number line number at byte count {byte} +char2nr( {expr}) Number ASCII value of first char in {expr} +cindent( {lnum}) Number C indent for line {lnum} +col( {expr}) Number column nr of cursor or mark +confirm( {msg} [, {choices} [, {default} [, {type}]]]) + Number number of choice picked by user +cscope_connection( [{num} , {dbpath} [, {prepend}]]) + Number checks existence of cscope connection +cursor( {lnum}, {col}) Number position cursor at {lnum}, {col} +delete( {fname}) Number delete file {fname} +did_filetype() Number TRUE if FileType autocommand event used +escape( {string}, {chars}) String escape {chars} in {string} with '\' +eventhandler( ) Number TRUE if inside an event handler +executable( {expr}) Number 1 if executable {expr} exists +exists( {expr}) Number TRUE if {expr} exists +expand( {expr}) String expand special keywords in {expr} +filereadable( {file}) Number TRUE if {file} is a readable file +filewritable( {file}) Number TRUE if {file} is a writable file +fnamemodify( {fname}, {mods}) String modify file name +foldclosed( {lnum}) Number first line of fold at {lnum} if closed +foldclosedend( {lnum}) Number last line of fold at {lnum} if closed +foldlevel( {lnum}) Number fold level at {lnum} +foldtext( ) String line displayed for closed fold +foreground( ) Number bring the Vim window to the foreground +getchar( [expr]) Number get one character from the user +getcharmod( ) Number modifiers for the last typed character +getbufvar( {expr}, {varname}) variable {varname} in buffer {expr} +getcmdline() String return the current command-line +getcmdpos() Number return cursor position in command-line +getcwd() String the current working directory +getfsize( {fname}) Number size in bytes of file +getftime( {fname}) Number last modification time of file +getline( {lnum}) String line {lnum} from current buffer +getreg( [{regname}]) String contents of register +getregtype( [{regname}]) String type of register +getwinposx() Number X coord in pixels of GUI Vim window +getwinposy() Number Y coord in pixels of GUI Vim window +getwinvar( {nr}, {varname}) variable {varname} in window {nr} +glob( {expr}) String expand file wildcards in {expr} +globpath( {path}, {expr}) String do glob({expr}) for all dirs in {path} +has( {feature}) Number TRUE if feature {feature} supported +hasmapto( {what} [, {mode}]) Number TRUE if mapping to {what} exists +histadd( {history},{item}) String add an item to a history +histdel( {history} [, {item}]) String remove an item from a history +histget( {history} [, {index}]) String get the item {index} from a history +histnr( {history}) Number highest index of a history +hlexists( {name}) Number TRUE if highlight group {name} exists +hlID( {name}) Number syntax ID of highlight group {name} +hostname() String name of the machine Vim is running on +iconv( {expr}, {from}, {to}) String convert encoding of {expr} +indent( {lnum}) Number indent of line {lnum} +input( {prompt} [, {text}]) String get input from the user +inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog +inputrestore() Number restore typeahead +inputsave() Number save and clear typeahead +inputsecret( {prompt} [, {text}]) String like input() but hiding the text +isdirectory( {directory}) Number TRUE if {directory} is a directory +libcall( {lib}, {func}, {arg}) String call {func} in library {lib} with {arg} +libcallnr( {lib}, {func}, {arg}) Number idem, but return a Number +line( {expr}) Number line nr of cursor, last line or mark +line2byte( {lnum}) Number byte count of line {lnum} +lispindent( {lnum}) Number Lisp indent for line {lnum} +localtime() Number current time +maparg( {name}[, {mode}]) String rhs of mapping {name} in mode {mode} +mapcheck( {name}[, {mode}]) String check for mappings matching {name} +match( {expr}, {pat}[, {start}]) + Number position where {pat} matches in {expr} +matchend( {expr}, {pat}[, {start}]) + Number position where {pat} ends in {expr} +matchstr( {expr}, {pat}[, {start}]) + String match of {pat} in {expr} +mode() String current editing mode +nextnonblank( {lnum}) Number line nr of non-blank line >= {lnum} +nr2char( {expr}) String single char with ASCII value {expr} +prevnonblank( {lnum}) Number line nr of non-blank line <= {lnum} +remote_expr( {server}, {string} [, {idvar}]) + String send expression +remote_foreground( {server}) Number bring Vim server to the foreground +remote_peek( {serverid} [, {retvar}]) + Number check for reply string +remote_read( {serverid}) String read reply string +remote_send( {server}, {string} [, {idvar}]) + String send key sequence +rename( {from}, {to}) Number rename (move) file from {from} to {to} +resolve( {filename}) String get filename a shortcut points to +search( {pattern} [, {flags}]) Number search for {pattern} +searchpair( {start}, {middle}, {end} [, {flags} [, {skip}]]) + Number search for other end of start/end pair +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} +setreg( {n}, {v}[, {opt}]) Number set register to value and type +setwinvar( {nr}, {varname}, {val}) set {varname} in window {nr} to {val} +simplify( {filename}) String simplify filename as much as possible +strftime( {format}[, {time}]) String time in specified format +stridx( {haystack}, {needle}) Number first index of {needle} in {haystack} +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} +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} +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} +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 +type( {name}) Number type of variable {name} +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 +winrestcmd() String returns command to restore window sizes +winwidth( {nr}) Number width of window {nr} + +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. + + *argc()* +argc() The result is the number of files in the argument list of the + current window. See |arglist|. + + *argidx()* +argidx() The result is the current index in the argument list. 0 is + 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 + current window. See |arglist|. "argv(0)" is the first one. + Example: > + :let i = 0 + :while i < argc() + : let f = escape(argv(i), '. ') + : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>' + : let i = i + 1 + :endwhile +< + *browse()* +browse({save}, {title}, {initdir}, {default}) + Put up a file requester. This only works when "has("browse")" + returns non-zero (only in some GUI versions). + The input fields are: + {save} when non-zero, select file to write + {title} title for the requester + {initdir} directory to start browsing in + {default} default file name + 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 string it must match a buffer name + exactly. + If the {expr} argument is a number buffer numbers are used. + 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 + long name to be able to find them. + Use "bufexists(0)" to test for the existence of an alternate + file name. + *buffer_exists()* + Obsolete name: buffer_exists(). + +buflisted({expr}) *buflisted()* + The result is a Number, which |