diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 243 |
1 files changed, 128 insertions, 115 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index fc788fba59..ca2334500c 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -402,7 +402,7 @@ It is also possible to put remaining items in a List variable: > :for [i, j; rest] in listlist : call Doit(i, j) : if !empty(rest) - : echo "remainder: " . string(rest) + : echo "remainder: " .. string(rest) : endif :endfor @@ -430,11 +430,11 @@ Functions that are useful with a List: > :let list = split("a b c") " create list from items in a string :let string = join(list, ', ') " create string from list items :let s = string(list) " String representation of list - :call map(list, '">> " . v:val') " prepend ">> " to each item + :call map(list, '">> " .. v:val') " prepend ">> " to each item Don't forget that a combination of features can make things simple. For example, to add up all the numbers in a list: > - :exe 'let sum = ' . join(nrlist, '+') + :exe 'let sum = ' .. join(nrlist, '+') 1.4 Dictionaries ~ @@ -496,7 +496,7 @@ turn the Dictionary into a List and pass it to |:for|. Most often you want to loop over the keys, using the |keys()| function: > :for key in keys(mydict) - : echo key . ': ' . mydict[key] + : echo key .. ': ' .. mydict[key] :endfor The List of keys is unsorted. You may want to sort them first: > @@ -504,13 +504,13 @@ The List of keys is unsorted. You may want to sort them first: > To loop over the values use the |values()| function: > :for v in values(mydict) - : echo "value: " . v + : echo "value: " .. v :endfor If you want both the key and the value use the |items()| function. It returns a List in which each item is a List with two items, the key and the value: > :for [key, value] in items(mydict) - : echo key . ': ' . value + : echo key .. ': ' .. value :endfor @@ -605,7 +605,7 @@ Functions that can be used with a Dictionary: > :let small = min(dict) " minimum value in dict :let xs = count(dict, 'x') " count nr of times 'x' appears in dict :let s = string(dict) " String representation of dict - :call map(dict, '">> " . v:val') " prepend ">> " to each item + :call map(dict, '">> " .. v:val') " prepend ">> " to each item 1.5 Blobs ~ @@ -840,7 +840,7 @@ Example: > All expressions within one level are parsed from left to right. -expr1 *expr1* *trinary* *E109* +expr1 *expr1* *ternary* *E109* ----- expr2 ? expr1 : expr1 @@ -1362,7 +1362,7 @@ option *expr-option* *E112* *E113* &l:option local option value Examples: > - echo "tabstop is " . &tabstop + echo "tabstop is " .. &tabstop if &insertmode Any option name can be used here. See |options|. When using the local value @@ -1637,7 +1637,7 @@ maintain a counter: > echo "script executed for the first time" else let s:counter = s:counter + 1 - echo "script executed " . s:counter . " times now" + echo "script executed " .. s:counter .. " times now" endif Note that this means that filetype plugins don't get a different set of script @@ -1651,6 +1651,7 @@ Some variables can be set by the user, but the type cannot be changed. *v:argv* *argv-variable* v:argv The command line arguments Vim was invoked with. This is a list of strings. The first item is the Vim command. + See |v:progpath| for the command with full path. *v:beval_col* *beval_col-variable* v:beval_col The number of the column, over which the mouse pointer is. @@ -1736,7 +1737,7 @@ v:completed_item *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> + :map _x :<C-U>echo "the count is " .. v:count<CR> < Note: The <C-U> is required to remove the line range that you get when typing ':' after a count. When there are two counts, as in "3d2w", they are multiplied, @@ -1882,6 +1883,11 @@ v:fcs_choice What should happen after a |FileChangedShell| event was do with the affected buffer: reload Reload the buffer (does not work if the file was deleted). + edit Reload the buffer and detect the + values for options such as + 'fileformat', 'fileencoding', 'binary' + (does not work if the file was + deleted). ask Ask the user what to do, as if there was no autocommand. Except that when only the timestamp changed nothing @@ -2022,6 +2028,9 @@ v:null Special value used to put "null" in JSON and NIL in msgpack. used as a String (e.g. in |expr5| with string concatenation operator) and to zero when used as a Number (e.g. in |expr5| or |expr7| when used with numeric operators). Read-only. + In some places `v:null` can be used for a List, Dict, etc. + that is not set. That is slightly different than an empty + List, Dict, etc. *v:numbermax* *numbermax-variable* v:numbermax Maximum value of a number. @@ -2526,9 +2535,9 @@ Example: > : echohl Title : echo a:title : echohl None - : echo a:0 . " items:" + : echo a:0 .. " items:" : for s in a:000 - : echon ' ' . s + : echon ' ' .. s : endfor :endfunction @@ -2567,7 +2576,7 @@ This function can then be called with: > this works: *function-range-example* > :function Mynumber(arg) - : echo line(".") . " " . a:arg + : echo line(".") .. " " .. a:arg :endfunction :1,5call Mynumber(getline(".")) < @@ -2578,7 +2587,7 @@ This function can then be called with: > Example of a function that handles the range itself: > :function Cont() range - : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ ' + : execute (a:firstline + 1) .. "," .. a:lastline .. 's/^/\t\\ ' :endfunction :4,8call Cont() < @@ -2740,7 +2749,7 @@ This does NOT work: > This cannot be used to add an item to a |List|. This cannot be used to set a byte in a String. You can do that like this: > - :let var = var[0:2] . 'X' . var[4:] + :let var = var[0:2] .. 'X' .. var[4:] < When {var-name} is a |Blob| then {idx} can be the length of the blob, in which case one byte is appended. @@ -2802,7 +2811,7 @@ This does NOT work: > is just like using the |:set| command: both the local value and the global value are changed. Example: > - :let &path = &path . ',/usr/local/include' + :let &path = &path .. ',/usr/local/include' :let &{option-name} .= {expr1} For a string option: Append {expr1} to the value. @@ -3057,14 +3066,17 @@ text... opposite of |:lockvar|. :if {expr1} *:if* *:end* *:endif* *:en* *E171* *E579* *E580* -:en[dif] Execute the commands until the next matching ":else" - or ":endif" if {expr1} evaluates to non-zero. +:en[dif] Execute the commands until the next matching `:else` + or `:endif` if {expr1} evaluates to non-zero. + Although the short forms work, it is recommended to + always use `:endif` to avoid confusion and to make + auto-indenting work properly. From Vim version 4.5 until 5.0, every Ex command in - between the ":if" and ":endif" is ignored. These two + between the `:if` and `:endif` is ignored. These two commands were just to allow for future expansions in a backward compatible way. Nesting was allowed. Note - that any ":else" or ":elseif" was ignored, the "else" + that any `:else` or `:elseif` was ignored, the `else` part was not executed either. You can use this to remain compatible with older @@ -3073,32 +3085,32 @@ text... : version-5-specific-commands :endif < The commands still need to be parsed to find the - "endif". Sometimes an older Vim has a problem with a - new command. For example, ":silent" is recognized as - a ":substitute" command. In that case ":execute" can + `endif`. Sometimes an older Vim has a problem with a + new command. For example, `:silent` is recognized as + a `:substitute` command. In that case `:execute` can avoid problems: > :if version >= 600 : execute "silent 1,$delete" :endif < - NOTE: The ":append" and ":insert" commands don't work - properly in between ":if" and ":endif". + NOTE: The `:append` and `:insert` commands don't work + properly in between `:if` and `:endif`. *:else* *:el* *E581* *E583* -:el[se] Execute the commands until the next matching ":else" - or ":endif" if they previously were not being +:el[se] Execute the commands until the next matching `:else` + or `:endif` if they previously were not being executed. *:elseif* *:elsei* *E582* *E584* -:elsei[f] {expr1} Short for ":else" ":if", with the addition that there - is no extra ":endif". +:elsei[f] {expr1} Short for `:else` `:if`, with the addition that there + is no extra `:endif`. :wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw* *E170* *E585* *E588* *E733* -:endw[hile] Repeat the commands between ":while" and ":endwhile", +:endw[hile] Repeat the commands between `:while` and `:endwhile`, as long as {expr1} evaluates to non-zero. When an error is detected from a command inside the - loop, execution continues after the "endwhile". + loop, execution continues after the `endwhile`. Example: > :let lnum = 1 :while lnum <= line("$") @@ -3106,16 +3118,16 @@ text... :let lnum = lnum + 1 :endwhile < - NOTE: The ":append" and ":insert" commands don't work - properly inside a ":while" and ":for" loop. + NOTE: The `:append` and `:insert` commands don't work + properly inside a `:while` and `:for` loop. :for {var} in {object} *:for* *E690* *E732* :endfo[r] *:endfo* *:endfor* - Repeat the commands between ":for" and ":endfor" for + Repeat the commands between `:for` and `:endfor` for each item in {object}. {object} can be a |List| or a |Blob|. Variable {var} is set to the value of each item. When an error is detected for a command inside - the loop, execution continues after the "endfor". + the loop, execution continues after the `endfor`. Changing {object} inside the loop affects what items are used. Make a copy if this is unwanted: > :for item in copy(mylist) @@ -3139,7 +3151,7 @@ text... :for [{var1}, {var2}, ...] in {listlist} :endfo[r] - Like ":for" above, but each item in {listlist} must be + Like `:for` above, but each item in {listlist} must be a list, of which each item is assigned to {var1}, {var2}, etc. Example: > :for [lnum, col] in [[1, 3], [2, 5], [3, 8]] @@ -3147,38 +3159,39 @@ text... :endfor < *:continue* *:con* *E586* -:con[tinue] When used inside a ":while" or ":for" loop, jumps back +:con[tinue] When used inside a `:while` or `:for` loop, jumps back to the start of the loop. - If it is used after a |:try| inside the loop but - before the matching |:finally| (if present), the - commands following the ":finally" up to the matching - |:endtry| are executed first. This process applies to - all nested ":try"s inside the loop. The outermost - ":endtry" then jumps back to the start of the loop. + + If it is used after a `:try` inside the loop but + before the matching `:finally` (if present), the + commands following the `:finally` up to the matching + `:endtry` are executed first. This process applies to + all nested `:try`s inside the loop. The outermost + `:endtry` then jumps back to the start of the loop. *:break* *:brea* *E587* -:brea[k] When used inside a ":while" or ":for" loop, skips to - the command after the matching ":endwhile" or - ":endfor". - If it is used after a |:try| inside the loop but - before the matching |:finally| (if present), the - commands following the ":finally" up to the matching - |:endtry| are executed first. This process applies to - all nested ":try"s inside the loop. The outermost - ":endtry" then jumps to the command after the loop. +:brea[k] When used inside a `:while` or `:for` loop, skips to + the command after the matching `:endwhile` or + `:endfor`. + If it is used after a `:try` inside the loop but + before the matching `:finally` (if present), the + commands following the `:finally` up to the matching + `:endtry` are executed first. This process applies to + all nested `:try`s inside the loop. The outermost + `:endtry` then jumps to the command after the loop. :try *:try* *:endt* *:endtry* *E600* *E601* *E602* :endt[ry] Change the error handling for the commands between - ":try" and ":endtry" including everything being - executed across ":source" commands, function calls, + `:try` and `:endtry` including everything being + executed across `:source` commands, function calls, or autocommand invocations. When an error or interrupt is detected and there is - a |:finally| command following, execution continues - after the ":finally". Otherwise, or when the - ":endtry" is reached thereafter, the next - (dynamically) surrounding ":try" is checked for - a corresponding ":finally" etc. Then the script + a `:finally` command following, execution continues + after the `:finally`. Otherwise, or when the + `:endtry` is reached thereafter, the next + (dynamically) surrounding `:try` is checked for + a corresponding `:finally` etc. Then the script processing is terminated. Whether a function definition has an "abort" argument does not matter. Example: > @@ -3186,9 +3199,9 @@ text... echomsg "not reached" < Moreover, an error or interrupt (dynamically) inside - ":try" and ":endtry" is converted to an exception. It - can be caught as if it were thrown by a |:throw| - command (see |:catch|). In this case, the script + `:try` and `:endtry` is converted to an exception. It + can be caught as if it were thrown by a `:throw` + command (see `:catch`). In this case, the script processing is not terminated. The value "Vim:Interrupt" is used for an interrupt @@ -3204,22 +3217,22 @@ text... try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry < *:cat* *:catch* *E603* *E604* *E605* -:cat[ch] /{pattern}/ The following commands until the next |:catch|, - |:finally|, or |:endtry| that belongs to the same - |:try| as the ":catch" are executed when an exception +:cat[ch] /{pattern}/ The following commands until the next `:catch`, + `:finally`, or `:endtry` that belongs to the same + `:try` as the `:catch` are executed when an exception matching {pattern} is being thrown and has not yet - been caught by a previous ":catch". Otherwise, these + been caught by a previous `:catch`. Otherwise, these commands are skipped. When {pattern} is omitted all errors are caught. Examples: > - :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C) - :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors - :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts - :catch /^Vim(write):/ " catch all errors in :write - :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123 - :catch /my-exception/ " catch user exception - :catch /.*/ " catch everything - :catch " same as /.*/ + :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C) + :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors + :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts + :catch /^Vim(write):/ " catch all errors in :write + :catch /^Vim\%((\a\+)\)\=:E123:/ " catch error E123 + :catch /my-exception/ " catch user exception + :catch /.*/ " catch everything + :catch " same as /.*/ < Another character can be used instead of / around the {pattern}, so long as it does not have a special @@ -3232,27 +3245,27 @@ text... locales. *:fina* *:finally* *E606* *E607* -:fina[lly] The following commands until the matching |:endtry| +:fina[lly] The following commands until the matching `:endtry` are executed whenever the part between the matching - |:try| and the ":finally" is left: either by falling - through to the ":finally" or by a |:continue|, - |:break|, |:finish|, or |:return|, or by an error or - interrupt or exception (see |:throw|). + `:try` and the `:finally` is left: either by falling + through to the `:finally` or by a `:continue`, + `:break`, `:finish`, or `:return`, or by an error or + interrupt or exception (see `:throw`). *:th* *:throw* *E608* :th[row] {expr1} The {expr1} is evaluated and thrown as an exception. - If the ":throw" is used after a |:try| but before the - first corresponding |:catch|, commands are skipped - until the first ":catch" matching {expr1} is reached. - If there is no such ":catch" or if the ":throw" is - used after a ":catch" but before the |:finally|, the - commands following the ":finally" (if present) up to - the matching |:endtry| are executed. If the ":throw" - is after the ":finally", commands up to the ":endtry" - are skipped. At the ":endtry", this process applies - again for the next dynamically surrounding ":try" + If the `:throw` is used after a `:try` but before the + first corresponding `:catch`, commands are skipped + until the first `:catch` matching {expr1} is reached. + If there is no such `:catch` or if the `:throw` is + used after a `:catch` but before the `:finally`, the + commands following the `:finally` (if present) up to + the matching `:endtry` are executed. If the `:throw` + is after the `:finally`, commands up to the `:endtry` + are skipped. At the `:endtry`, this process applies + again for the next dynamically surrounding `:try` (which may be found in a calling function or sourcing - script), until a matching ":catch" has been found. + script), until a matching `:catch` has been found. If the exception is not caught, the command processing is terminated. Example: > @@ -3267,7 +3280,7 @@ text... Also see |:comment|. Use "\n" to start a new line. Use "\r" to move the cursor to the first column. - Uses the highlighting set by the |:echohl| command. + Uses the highlighting set by the `:echohl` command. Cannot be followed by a comment. Example: > :echo "the value of 'shell' is" &shell @@ -3276,9 +3289,9 @@ text... And since Vim mostly postpones redrawing until it's finished with a sequence of commands this happens quite often. To avoid that a command from before the - ":echo" causes a redraw afterwards (redraws are often + `:echo` causes a redraw afterwards (redraws are often postponed until you type something), force a redraw - with the |:redraw| command. Example: > + with the `:redraw` command. Example: > :new | redraw | echo "there is a new window" < *:echo-self-refer* When printing nested containers echo prints second @@ -3297,13 +3310,13 @@ text... *:echon* :echon {expr1} .. Echoes each {expr1}, without anything added. Also see |:comment|. - Uses the highlighting set by the |:echohl| command. + Uses the highlighting set by the `:echohl` command. Cannot be followed by a comment. Example: > :echon "the value of 'shell' is " &shell < - Note the difference between using ":echo", which is a - Vim command, and ":!echo", which is an external shell + Note the difference between using `:echo`, which is a + Vim command, and `:!echo`, which is an external shell command: > :!echo % --> filename < The arguments of ":!" are expanded, see |:_%|. > @@ -3319,8 +3332,8 @@ text... *:echoh* *:echohl* :echoh[l] {name} Use the highlight group {name} for the following - |:echo|, |:echon| and |:echomsg| commands. Also used - for the |input()| prompt. Example: > + `:echo`, `:echon` and `:echomsg` commands. Also used + for the `input()` prompt. Example: > :echohl WarningMsg | echo "Don't panic!" | echohl None < Don't forget to set the group back to "None", otherwise all following echo's will be highlighted. @@ -3329,14 +3342,14 @@ text... :echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the message in the |message-history|. Spaces are placed between the arguments as with the - |:echo| command. But unprintable characters are + `:echo` command. But unprintable characters are displayed, not interpreted. - The parsing works slightly different from |:echo|, - more like |:execute|. All the expressions are first + The parsing works slightly different from `:echo`, + more like `:execute`. All the expressions are first evaluated and concatenated before echoing anything. If expressions does not evaluate to a Number or String, string() is used to turn it into a string. - Uses the highlighting set by the |:echohl| command. + Uses the highlighting set by the `:echohl` command. Example: > :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see." < See |:echo-redraw| to avoid the message disappearing @@ -3346,12 +3359,12 @@ text... message in the |message-history|. When used in a script or function the line number will be added. Spaces are placed between the arguments as with the - |:echomsg| command. When used inside a try conditional, + `:echomsg` command. When used inside a try conditional, the message is raised as an error exception instead (see |try-echoerr|). Example: > :echoerr "This script just failed!" -< If you just want a highlighted message use |:echohl|. +< If you just want a highlighted message use `:echohl`. And to get a beep: > :exe "normal \<Esc>" < @@ -3656,7 +3669,7 @@ exception most recently caught as long it is not finished. :function! Caught() : if v:exception != "" - : echo 'Caught "' . v:exception . '" in ' . v:throwpoint + : echo 'Caught "' .. v:exception .. '" in ' .. v:throwpoint : else : echo 'Nothing caught' : endif @@ -4059,8 +4072,8 @@ a script in order to catch unexpected things. :catch /^Vim:Interrupt$/ : echo "Script interrupted" :catch /.*/ - : echo "Internal error (" . v:exception . ")" - : echo " - occurred at " . v:throwpoint + : echo "Internal error (" .. v:exception .. ")" + : echo " - occurred at " .. v:throwpoint :endtry :" end of script @@ -4256,7 +4269,7 @@ parentheses can be cut out from |v:exception| with the ":substitute" command. :function! CheckRange(a, func) : if a:a < 0 - : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")" + : throw "EXCEPT:MATHERR:RANGE(" .. a:func .. ")" : endif :endfunction : @@ -4283,7 +4296,7 @@ parentheses can be cut out from |v:exception| with the ":substitute" command. : try : execute "write" fnameescape(a:file) : catch /^Vim(write):/ - : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR" + : throw "EXCEPT:IO(" .. getcwd() .. ", " .. a:file .. "):WRITEERR" : endtry :endfunction : @@ -4302,9 +4315,9 @@ parentheses can be cut out from |v:exception| with the ":substitute" command. : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "") : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "") : if file !~ '^/' - : let file = dir . "/" . file + : let file = dir .. "/" .. file : endif - : echo 'I/O error for "' . file . '"' + : echo 'I/O error for "' .. file .. '"' : :catch /^EXCEPT/ : echo "Unspecified error" @@ -4372,7 +4385,7 @@ clauses, however, is executed. : echo "inner finally" : endtry :catch - : echo 'outer catch-all caught "' . v:exception . '"' + : echo 'outer catch-all caught "' .. v:exception .. '"' : finally : echo "outer finally" :endtry @@ -4434,7 +4447,7 @@ Printing in Binary ~ : let n = a:nr : let r = "" : while n - : let r = '01'[n % 2] . r + : let r = '01'[n % 2] .. r : let n = n / 2 : endwhile : return r @@ -4445,7 +4458,7 @@ Printing in Binary ~ :func String2Bin(str) : let out = '' : for ix in range(strlen(a:str)) - : let out = out . '-' . Nr2Bin(char2nr(a:str[ix])) + : let out = out .. '-' .. Nr2Bin(char2nr(a:str[ix])) : endfor : return out[1:] :endfunc |