diff options
Diffstat (limited to 'runtime/doc/eval.txt')
| -rw-r--r-- | runtime/doc/eval.txt | 4763 |
1 files changed, 4763 insertions, 0 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt new file mode 100644 index 0000000..84f5f5f --- /dev/null +++ b/runtime/doc/eval.txt @@ -0,0 +1,4763 @@ +*eval.txt* For Vim version 9.0. Last change: 2023 Feb 25 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Expression evaluation *expression* *expr* *E15* *eval* + *E1002* +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 +|no-eval-feature|. + +This file is mainly about the backwards compatible (legacy) Vim script. For +specifics of Vim9 script, which can execute much faster, supports type +checking and much more, see |vim9.txt|. Where the syntax or semantics differ +a remark is given. + +1. Variables |variables| + 1.1 Variable types + 1.2 Function references |Funcref| + 1.3 Lists |Lists| + 1.4 Dictionaries |Dictionaries| + 1.5 Blobs |Blobs| + 1.6 More about variables |more-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. Vim script version |vimscript-version| +11. No +eval feature |no-eval-feature| +12. The sandbox |eval-sandbox| +13. Textlock |textlock| + +Testing support is documented in |testing.txt|. +Profiling is documented at |profiling|. + +============================================================================== +1. Variables *variables* + +1.1 Variable types ~ + *E712* *E896* *E897* *E899* *E1098* + *E1107* *E1135* *E1138* +There are ten types of variables: + + *Number* *Integer* +Number A 32 or 64 bit signed number. |expr-number| + The number of bits is available in |v:numbersize|. + Examples: -123 0x10 0177 0o177 0b1011 + +Float A floating point number. |floating-point-format| *Float* + Examples: 123.456 1.15e-6 -1.1e3 + +String A NUL terminated string of 8-bit unsigned characters (bytes). + |expr-string| Examples: "ab\txx\"--" 'x-z''a,c' + +List An ordered sequence of items, see |List| for details. + Example: [1, 2, ['a', 'b']] + +Dictionary An associative, unordered array: Each entry has a key and a + value. |Dictionary| + Examples: + {'blue': "#0000ff", 'red': "#ff0000"} + #{blue: "#0000ff", red: "#ff0000"} + +Funcref A reference to a function |Funcref|. + Example: function("strlen") + It can be bound to a dictionary and arguments, it then works + like a Partial. + Example: function("Callback", [arg], myDict) + +Special |v:false|, |v:true|, |v:none| and |v:null|. *Special* + +Job Used for a job, see |job_start()|. *Job* *Jobs* + +Channel Used for a channel, see |ch_open()|. *Channel* *Channels* + +Blob Binary Large Object. Stores any sequence of bytes. See |Blob| + for details + Example: 0zFF00ED015DAF + 0z is an empty Blob. + +The Number and String types 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" ~ + *octal* +Conversion from a String to a Number only happens in legacy Vim script, not in +Vim9 script. It is done by converting the first digits to a number. +Hexadecimal "0xf9", Octal "017" or "0o17", and Binary "0b10" +numbers are recognized +NOTE: when using |Vim9| script or |scriptversion-4| octal with a leading "0" +is not recognized. The 0o notation requires patch 8.2.0886. +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 "0o100" --> Number 64 ~ + String "0b101" --> Number 5 ~ + String "-8" --> Number -8 ~ + String "+8" --> Number 0 ~ + +To force conversion from String to Number, add zero to it: > + :echo "0100" + 0 +< 64 ~ + +To avoid a leading zero to cause octal conversion, or for using a different +base, use |str2nr()|. + + *TRUE* *FALSE* *Boolean* +For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE. +You can also use |v:false| and |v:true|, in Vim9 script |false| and |true|. +When TRUE is returned from a function it is the Number one, FALSE is the +number zero. + +Note that in the command: > + :if "foo" + :" NOT executed +"foo" is converted to 0, which means FALSE. If the string starts with a +non-zero number it means TRUE: > + :if "8foo" + :" executed +To test for a non-empty string, use empty(): > + :if !empty("foo") + +< *falsy* *truthy* +An expression can be used as a condition, ignoring the type and only using +whether the value is "sort of true" or "sort of false". Falsy is: + the number zero + empty string, blob, list or dictionary +Other values are truthy. Examples: + 0 falsy + 1 truthy + -1 truthy + 0.0 falsy + 0.1 truthy + '' falsy + 'x' truthy + [] falsy + [0] truthy + {} falsy + #{x: 1} truthy + 0z falsy + 0z00 truthy + + *non-zero-arg* +Function arguments often behave slightly different from |TRUE|: If the +argument is present and it evaluates to a non-zero Number, |v:true| or a +non-empty String, then the value is considered to be TRUE. +Note that " " and "0" are also non-empty strings, thus considered to be TRUE. +A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE. + + *E611* *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* + *E913* *E974* *E975* *E976* *E1319* *E1320* *E1321* *E1322* + *E1323* *E1324* +|List|, |Dictionary|, |Funcref|, |Job|, |Channel|, |Blob|, |Class| and +|object| types are not automatically converted. + + *E805* *E806* *E808* +When mixing Number and Float the Number is converted to Float. Otherwise +there is no automatic conversion of Float. You can use str2float() for String +to Float, printf() for Float to String and float2nr() for Float to Number. + + *E362* *E891* *E892* *E893* *E894* *E907* *E911* *E914* +When expecting a Float a Number can also be used, but nothing else. + + *no-type-checking* +You will not get an error if you try to change the type of a variable. + + +1.2 Function references ~ + *Funcref* *E695* *E718* *E1192* +A Funcref variable is obtained with the |function()| function, the |funcref()| +function, (in |Vim9| script) the name of a function, or created with the +lambda expression |expr-lambda|. It can be used in an expression in the place +of a function name, before the parenthesis around the arguments, to invoke the +function it refers to. Example in |Vim9| script: > + + :var Fn = MyFunc + :echo Fn() + +Legacy script: > + :let Fn = function("MyFunc") + :echo Fn() +< *E704* *E705* *E707* +A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You +can use "g:" but the following name must still start with a capital. You +cannot have both a Funcref variable and a function with the same name. + +A special case is defining a function and directly assigning its Funcref to a +Dictionary entry. Example: > + :function dict.init() dict + : let self.val = 0 + :endfunction + +The key of the Dictionary can start with a lower case letter. The actual +function name is not used here. Also see |numbered-function|. + +A Funcref can also be used with the |:call| command: > + :call Fn() + :call dict.init() + +The name of the referenced function can be obtained with |string()|. > + :let func = string(Fn) + +You can use |call()| to invoke a Funcref and use a list variable for the +arguments: > + :let r = call(Fn, mylist) +< + *Partial* +A Funcref optionally binds a Dictionary and/or arguments. This is also called +a Partial. This is created by passing the Dictionary and/or arguments to +function() or funcref(). When calling the function the Dictionary and/or +arguments will be passed to the function. Example: > + + let Cb = function('Callback', ['foo'], myDict) + call Cb('bar') + +This will invoke the function as if using: > + call myDict.Callback('foo', 'bar') + +This is very useful when passing a function around, e.g. in the arguments of +|ch_open()|. + +Note that binding a function to a Dictionary also happens when the function is +a member of the Dictionary: > + + let myDict.myFunction = MyFunction + call myDict.myFunction() + +Here MyFunction() will get myDict passed as "self". This happens when the +"myFunction" member is accessed. When making assigning "myFunction" to +otherDict and calling it, it will be bound to otherDict: > + + let otherDict.myFunction = myDict.myFunction + call otherDict.myFunction() + +Now "self" will be "otherDict". But when the dictionary was bound explicitly +this won't happen: > + + let myDict.myFunction = function(MyFunction, myDict) + let otherDict.myFunction = myDict.myFunction + call otherDict.myFunction() + +Here "self" will be "myDict", because it was bound explicitly. + + +1.3 Lists ~ + *list* *List* *Lists* *E686* +A List is an ordered sequence of items. An item can be of any type. Items +can be accessed by their index number. Items can be added and removed at any +position in the sequence. + + +List creation ~ + *E696* *E697* +A List is created with a comma-separated list of items in square brackets. +Examples: > + :let mylist = [1, two, 3, "four"] + :let emptylist = [] + +An item can be any expression. Using a List for an item creates a +List of Lists: > + :let nestlist = [[11, 12], [21, 22], [31, 32]] + +An extra comma after the last item is ignored. + + +List index ~ + *list-index* *E684* +An item in the List can be accessed by putting the index in square brackets +after the List. Indexes are zero-based, thus the first item has index zero. > + :let item = mylist[0] " get the first item: 1 + :let item = mylist[2] " get the third item: 3 + +When the resulting item is a list this can be repeated: > + :let item = nestlist[0][1] " get the first list, second item: 12 +< +A negative index is counted from the end. Index -1 refers to the last item in +the List, -2 to the last but one item, etc. > + :let last = mylist[-1] " get the last item: "four" + +To avoid an error for an invalid index use the |get()| function. When an item +is not available it returns zero or the default value you specify: > + :echo get(mylist, idx) + :echo get(mylist, idx, "NONE") + + +List concatenation ~ + *list-concatenation* +Two lists can be concatenated with the "+" operator: > + :let longlist = mylist + [5, 6] + :let mylist += [7, 8] + +To prepend or append an item, turn the item into a list by putting [] around +it. To change a list in-place, refer to |list-modification| below. + + +Sublist ~ + *sublist* +A part of the List can be obtained by specifying the first and last index, +separated by a colon in square brackets: > + :let shortlist = mylist[2:-1] " get List [3, "four"] + +Omitting the first index is similar to zero. Omitting the last index is +similar to -1. > + :let endlist = mylist[2:] " from item 2 to the end: [3, "four"] + :let shortlist = mylist[2:2] " List with one item: [3] + :let otherlist = mylist[:] " make a copy of the List + +Notice that the last index is inclusive. If you prefer using an exclusive +index use the |slice()| method. + +If the first index is beyond the last item of the List or the second item is +before the first item, the result is an empty list. There is no error +message. + +If the second index is equal to or greater than the length of the list the +length minus one is used: > + :let mylist = [0, 1, 2, 3] + :echo mylist[2:8] " result: [2, 3] + +NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for +using a single letter variable before the ":". Insert a space when needed: +mylist[s : e]. + + +List identity ~ + *list-identity* +When variable "aa" is a list and you assign it to another variable "bb", both +variables refer to the same list. Thus changing the list "aa" will also +change "bb": > + :let aa = [1, 2, 3] + :let bb = aa + :call add(aa, 4) + :echo bb +< [1, 2, 3, 4] + +Making a copy of a list is done with the |copy()| function. Using [:] also +works, as explained above. This creates a shallow copy of the list: Changing +a list item in the list will also change the item in the copied list: > + :let aa = [[1, 'a'], 2, 3] + :let bb = copy(aa) + :call add(aa, 4) + :let aa[0][1] = 'aaa' + :echo aa +< [[1, aaa], 2, 3, 4] > + :echo bb +< [[1, aaa], 2, 3] + +To make a completely independent list use |deepcopy()|. This also makes a +copy of the values in the list, recursively. Up to a hundred levels deep. + +The operator "is" can be used to check if two variables refer to the same +List. "isnot" does the opposite. In contrast "==" compares if two lists have +the same value. > + :let alist = [1, 2, 3] + :let blist = [1, 2, 3] + :echo alist is blist +< 0 > + :echo alist == blist +< 1 + +Note about comparing lists: Two lists are considered equal if they have the +same length and all items compare equal, as with using "==". There is one +exception: When comparing a number with a string they are considered +different. There is no automatic type conversion, as with using "==" on +variables. Example: > + echo 4 == "4" +< 1 > + echo [4] == ["4"] +< 0 + +Thus comparing Lists is more strict than comparing numbers and strings. You +can compare simple values this way too by putting them in a list: > + + :let a = 5 + :let b = "5" + :echo a == b +< 1 > + :echo [a] == [b] +< 0 + + +List unpack ~ + +To unpack the items in a list to individual variables, put the variables in +square brackets, like list items: > + :let [var1, var2] = mylist + +When the number of variables does not match the number of items in the list +this produces an error. To handle any extra items from the list append ";" +and a variable name: > + :let [var1, var2; rest] = mylist + +This works like: > + :let var1 = mylist[0] + :let var2 = mylist[1] + :let rest = mylist[2:] + +Except that there is no error if there are only two items. "rest" will be an +empty list then. + + +List modification ~ + *list-modification* +To change a specific item of a list use |:let| this way: > + :let list[4] = "four" + :let listlist[0][3] = item + +To change part of a list you can specify the first and last item to be +modified. The value must at least have the number of items in the range: > + :let list[3:5] = [3, 4, 5] + +Adding and removing items from a list is done with functions. Here are a few +examples: > + :call insert(list, 'a') " prepend item 'a' + :call insert(list, 'a', 3) " insert item 'a' before list[3] + :call add(list, "new") " append String item + :call add(list, [1, 2]) " append a List as one new item + :call extend(list, [1, 2]) " extend the list with two more items + :let i = remove(list, 3) " remove item 3 + :unlet list[3] " idem + :let l = remove(list, 3, -1) " remove items 3 to last item + :unlet list[3 : ] " idem + :call filter(list, 'v:val !~ "x"') " remove items with an 'x' + +Changing the order of items in a list: > + :call sort(list) " sort a list alphabetically + :call reverse(list) " reverse the order of items + :call uniq(sort(list)) " sort and remove duplicates + + +For loop ~ + +The |:for| loop executes commands for each item in a List, String or Blob. +A variable is set to each item in sequence. Example with a List: > + :for item in mylist + : call Doit(item) + :endfor + +This works like: > + :let index = 0 + :while index < len(mylist) + : let item = mylist[index] + : :call Doit(item) + : let index = index + 1 + :endwhile + +If all you want to do is modify each item in the list then the |map()| +function will be a simpler method than a for loop. + +Just like the |:let| command, |:for| also accepts a list of variables. This +requires the argument to be a List of Lists. > + :for [lnum, col] in [[1, 3], [2, 8], [3, 0]] + : call Doit(lnum, col) + :endfor + +This works like a |:let| command is done for each list item. Again, the types +must remain the same to avoid an error. + +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) + : endif + :endfor + +For a Blob one byte at a time is used. + +For a String one character, including any composing characters, is used as a +String. Example: > + for c in text + echo 'This character is ' .. c + endfor + + +List functions ~ + *E714* +Functions that are useful with a List: > + :let r = call(funcname, list) " call a function with an argument list + :if empty(list) " check if list is empty + :let l = len(list) " number of items in list + :let big = max(list) " maximum value in list + :let small = min(list) " minimum value in list + :let xs = count(list, 'x') " count nr of times 'x' appears in list + :let i = index(list, 'x') " index of first 'x' in list + :let lines = getline(1, 10) " get ten text lines from buffer + :call append('$', lines) " append text lines in buffer + :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 + +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, '+') + + +1.4 Dictionaries ~ + *dict* *Dict* *Dictionaries* *Dictionary* +A Dictionary is an associative array: Each entry has a key and a value. The +entry can be located with the key. The entries are stored without a specific +ordering. + + +Dictionary creation ~ + *E720* *E721* *E722* *E723* +A Dictionary is created with a comma-separated list of entries in curly +braces. Each entry has a key and a value, separated by a colon. Each key can +only appear once. Examples: > + :let mydict = {1: 'one', 2: 'two', 3: 'three'} + :let emptydict = {} +< *E713* *E716* *E717* +A key is always a String. You can use a Number, it will be converted to a +String automatically. Thus the String '4' and the number 4 will find the same +entry. Note that the String '04' and the Number 04 are different, since the +Number will be converted to the String '4', leading zeros are dropped. The +empty string can also be used as a key. + +In |Vim9| script a literal key can be used if it consists only of alphanumeric +characters, underscore and dash, see |vim9-literal-dict|. + *literal-Dict* *#{}* +To avoid having to put quotes around every key the #{} form can be used in +legacy script. This does require the key to consist only of ASCII letters, +digits, '-' and '_'. Example: > + :let mydict = #{zero: 0, one_key: 1, two-key: 2, 333: 3} +Note that 333 here is the string "333". Empty keys are not possible with #{}. +In |Vim9| script the #{} form cannot be used because it can be confused with +the start of a comment. + +A value can be any expression. Using a Dictionary for a value creates a +nested Dictionary: > + :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}} + +An extra comma after the last entry is ignored. + + +Accessing entries ~ + +The normal way to access an entry is by putting the key in square brackets: > + :let val = mydict["one"] + :let mydict["four"] = 4 + +You can add new entries to an existing Dictionary this way, unlike Lists. + +For keys that consist entirely of letters, digits and underscore the following +form can be used |expr-entry|: > + :let val = mydict.one + :let mydict.four = 4 + +Since an entry can be any type, also a List and a Dictionary, the indexing and +key lookup can be repeated: > + :echo dict.key[idx].key + + +Dictionary to List conversion ~ + +You may want to loop over the entries in a dictionary. For this you need to +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] + :endfor + +The List of keys is unsorted. You may want to sort them first: > + :for key in sort(keys(mydict)) + +To loop over the values use the |values()| function: > + :for v in values(mydict) + : 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 + :endfor + + +Dictionary identity ~ + *dict-identity* +Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a +Dictionary. Otherwise, assignment results in referring to the same +Dictionary: > + :let onedict = {'a': 1, 'b': 2} + :let adict = onedict + :let adict['a'] = 11 + :echo onedict['a'] + 11 + +Two Dictionaries compare equal if all the key-value pairs compare equal. For +more info see |list-identity|. + + +Dictionary modification ~ + *dict-modification* +To change an already existing entry of a Dictionary, or to add a new entry, +use |:let| this way: > + :let dict[4] = "four" + :let dict['one'] = item + +Removing an entry from a Dictionary is done with |remove()| or |:unlet|. +Three ways to remove the entry with key "aaa" from dict: > + :let i = remove(dict, 'aaa') + :unlet dict.aaa + :unlet dict['aaa'] + +Merging a Dictionary with another is done with |extend()|: > + :call extend(adict, bdict) +This extends adict with all entries from bdict. Duplicate keys cause entries +in adict to be overwritten. An optional third argument can change this. +Note that the order of entries in a Dictionary is irrelevant, thus don't +expect ":echo adict" to show the items from bdict after the older entries in +adict. + +Weeding out entries from a Dictionary can be done with |filter()|: > + :call filter(dict, 'v:val =~ "x"') +This removes all entries from "dict" with a value not matching 'x'. +This can also be used to remove all entries: > + call filter(dict, 0) + +In some situations it is not allowed to remove or add entries to a Dictionary. +Especially when iterating over all the entries. You will get *E1313* or +another error in that case. + + +Dictionary function ~ + *Dictionary-function* *self* *E725* *E862* +When a function is defined with the "dict" attribute it can be used in a +special way with a dictionary. Example: > + :function Mylen() dict + : return len(self.data) + :endfunction + :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")} + :echo mydict.len() + +This is like a method in object oriented programming. The entry in the +Dictionary is a |Funcref|. The local variable "self" refers to the dictionary +the function was invoked from. When using |Vim9| script you can use classes +and objects, see `:class`. + +It is also possible to add a function without the "dict" attribute as a +Funcref to a Dictionary, but the "self" variable is not available then. + + *numbered-function* *anonymous-function* +To avoid the extra name for the function it can be defined and directly +assigned to a Dictionary in this way: > + :let mydict = {'data': [0, 1, 2, 3]} + :function mydict.len() + : return len(self.data) + :endfunction + :echo mydict.len() + +The function will then get a number and the value of dict.len is a |Funcref| +that references this function. The function can only be used through a +|Funcref|. It will automatically be deleted when there is no |Funcref| +remaining that refers to it. + +It is not necessary to use the "dict" attribute for a numbered function. + +If you get an error for a numbered function, you can find out what it is with +a trick. Assuming the function is 42, the command is: > + :function g:42 + + +Functions for Dictionaries ~ + *E715* +Functions that can be used with a Dictionary: > + :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo" + :if empty(dict) " TRUE if dict is empty + :let l = len(dict) " number of items in dict + :let big = max(dict) " maximum value in dict + :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 + + +1.5 Blobs ~ + *blob* *Blob* *Blobs* *E978* +A Blob is a binary object. It can be used to read an image from a file and +send it over a channel, for example. + +A Blob mostly behaves like a |List| of numbers, where each number has the +value of an 8-bit byte, from 0 to 255. + + +Blob creation ~ + +A Blob can be created with a |blob-literal|: > + :let b = 0zFF00ED015DAF +Dots can be inserted between bytes (pair of hex characters) for readability, +they don't change the value: > + :let b = 0zFF00.ED01.5DAF + +A blob can be read from a file with |readfile()| passing the {type} argument +set to "B", for example: > + :let b = readfile('image.png', 'B') + +A blob can be read from a channel with the |ch_readblob()| function. + + +Blob index ~ + *blob-index* *E979* +A byte in the Blob can be accessed by putting the index in square brackets +after the Blob. Indexes are zero-based, thus the first byte has index zero. > + :let myblob = 0z00112233 + :let byte = myblob[0] " get the first byte: 0x00 + :let byte = myblob[2] " get the third byte: 0x22 + +A negative index is counted from the end. Index -1 refers to the last byte in +the Blob, -2 to the last but one byte, etc. > + :let last = myblob[-1] " get the last byte: 0x33 + +To avoid an error for an invalid index use the |get()| function. When an item +is not available it returns -1 or the default value you specify: > + :echo get(myblob, idx) + :echo get(myblob, idx, 999) + + +Blob iteration ~ + +The |:for| loop executes commands for each byte of a Blob. The loop variable is +set to each byte in the Blob. Example: > + :for byte in 0z112233 + : call Doit(byte) + :endfor +This calls Doit() with 0x11, 0x22 and 0x33. + + +Blob concatenation ~ + +Two blobs can be concatenated with the "+" operator: > + :let longblob = myblob + 0z4455 + :let myblob += 0z6677 + +To change a blob in-place see |blob-modification| below. + + +Part of a blob ~ + +A part of the Blob can be obtained by specifying the first and last index, +separated by a colon in square brackets: > + :let myblob = 0z00112233 + :let shortblob = myblob[1:2] " get 0z1122 + :let shortblob = myblob[2:-1] " get 0z2233 + +Omitting the first index is similar to zero. Omitting the last index is +similar to -1. > + :let endblob = myblob[2:] " from item 2 to the end: 0z2233 + :let shortblob = myblob[2:2] " Blob with one byte: 0z22 + :let otherblob = myblob[:] " make a copy of the Blob + +If the first index is beyond the last byte of the Blob or the second index is +before the first index, the result is an empty Blob. There is no error +message. + +If the second index is equal to or greater than the length of the list the +length minus one is used: > + :echo myblob[2:8] " result: 0z2233 + + +Blob modification ~ + *blob-modification* *E1182* *E1184* +To change a specific byte of a blob use |:let| this way: > + :let blob[4] = 0x44 + +When the index is just one beyond the end of the Blob, it is appended. Any +higher index is an error. + +To change a sequence of bytes the [:] notation can be used: > + let blob[1:3] = 0z445566 +The length of the replaced bytes must be exactly the same as the value +provided. *E972* + +To change part of a blob you can specify the first and last byte to be +modified. The value must have the same number of bytes in the range: > + :let blob[3:5] = 0z334455 + +You can also use the functions |add()|, |remove()| and |insert()|. + + +Blob identity ~ + +Blobs can be compared for equality: > + if blob == 0z001122 +And for equal identity: > + if blob is otherblob +< *blob-identity* *E977* +When variable "aa" is a Blob and you assign it to another variable "bb", both +variables refer to the same Blob. Then the "is" operator returns true. + +When making a copy using [:] or |copy()| the values are the same, but the +identity is different: > + :let blob = 0z112233 + :let blob2 = blob + :echo blob == blob2 +< 1 > + :echo blob is blob2 +< 1 > + :let blob3 = blob[:] + :echo blob == blob3 +< 1 > + :echo blob is blob3 +< 0 + +Making a copy of a Blob is done with the |copy()| function. Using [:] also +works, as explained above. + + +1.6 More about variables ~ + *more-variables* +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 + + +In legacy script it is possible to form a variable name with curly braces, see +|curly-braces-names|. + +============================================================================== +2. Expression syntax *expression-syntax* + *E1143* +Expression syntax summary, from least to most significant: + +|expr1| expr2 + expr2 ? expr1 : expr1 if-then-else + +|expr2| expr3 + expr3 || expr3 ... logical OR + +|expr3| expr4 + expr4 && expr4 ... logical AND + +|expr4| expr5 + 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 is expr5 same |List|, |Dictionary| or |Blob| instance + expr5 isnot expr5 different |List|, |Dictionary| or |Blob| + instance + +|expr5| expr6 << expr6 bitwise left shift + expr6 >> expr6 bitwise right shift + +|expr6| expr7 + expr7 + expr7 ... number addition, list or blob concatenation + expr7 - expr7 ... number subtraction + expr7 . expr7 ... string concatenation + expr7 .. expr7 ... string concatenation + +|expr7| expr8 + expr8 * expr8 ... number multiplication + expr8 / expr8 ... number division + expr8 % expr8 ... number modulo + +|expr8| expr9 + <type>expr9 type check and conversion (|Vim9| only) + +|expr9| expr10 + ! expr9 logical NOT + - expr9 unary minus + + expr9 unary plus + +|expr10| expr11 + expr10[expr1] byte of a String or item of a |List| + expr10[expr1 : expr1] substring of a String or sublist of a |List| + expr10.name entry in a |Dictionary| + expr10(expr1, ...) function call with |Funcref| variable + expr10->name(expr1, ...) |method| call + +|expr11| number number constant + "string" string constant, backslash is special + 'string' string constant, ' is doubled + [expr1, ...] |List| + {expr1: expr1, ...} |Dictionary| + #{key: expr1, ...} legacy |Dictionary| + &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 + {args -> expr1} legacy lambda expression + (args) => expr1 Vim9 lambda expression + + +"..." 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. + +Expression nesting is limited to 1000 levels deep (300 when build with MSVC) +to avoid running out of stack and crashing. *E1169* + + +expr1 *expr1* *ternary* *falsy-operator* *??* *E109* +----- + +The ternary operator: expr2 ? expr1 : expr1 +The falsy operator: expr2 ?? expr1 + +Ternary operator ~ + +In legacy script the expression before the '?' is evaluated to a number. If +it evaluates to |TRUE|, the result is the value of the expression between the +'?' and ':', otherwise the result is the value of the expression after the +':'. + +In |Vim9| script the first expression must evaluate to a boolean, see +|vim9-boolean|. + +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 + +You should always put a space before the ':', otherwise it can be mistaken for +use in a variable such as "a:1". + +Falsy operator ~ + +This is also known as the "null coalescing operator", but that's too +complicated, thus we just call it the falsy operator. + +The expression before the '??' is evaluated. If it evaluates to +|truthy|, this is used as the result. Otherwise the expression after the '??' +is evaluated and used as the result. This is most useful to have a default +value for an expression that may result in zero or empty: > + echo theList ?? 'list is empty' + echo GetName() ?? 'unknown' + +These are similar, but not equal: > + expr2 ?? expr1 + expr2 ? expr2 : expr1 +In the second line "expr2" is evaluated twice. And in |Vim9| script the type +of expr2 before "?" must be a boolean. + + +expr2 and expr3 *expr2* *expr3* +--------------- + +expr3 || expr3 .. logical OR *expr-barbar* +expr4 && expr4 .. logical AND *expr-&&* + +The "||" and "&&" operators take one argument on each side. + +In legacy script the arguments are (converted to) Numbers. + +In |Vim9| script the values must be boolean, see |vim9-boolean|. Use "!!" to +convert any type to a boolean. + +The result is: + input output ~ +n1 n2 n1 || n2 n1 && n2 ~ +|FALSE| |FALSE| |FALSE| |FALSE| +|FALSE| |TRUE| |TRUE| |FALSE| +|TRUE| |FALSE| |TRUE| |FALSE| +|TRUE| |TRUE| |TRUE| |TRUE| + +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 |TRUE|, +so the result must be |TRUE|. 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* *E1153* +----- + +expr5 {cmp} expr5 + +Compare two expr5 expressions. In legacy script the result is a 0 if it +evaluates to false, or 1 if it evaluates to true. In |Vim9| script the result +is |true| or |false|. + + *expr-==* *expr-!=* *expr->* *expr->=* + *expr-<* *expr-<=* *expr-=~* *expr-!~* + *expr-==#* *expr-!=#* *expr->#* *expr->=#* + *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#* + *expr-==?* *expr-!=?* *expr->?* *expr->=?* + *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?* + *expr-is* *expr-isnot* *expr-is#* *expr-isnot#* + *expr-is?* *expr-isnot?* *E1072* + 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 !~ !~# !~? +same instance is is# is? +different instance isnot isnot# isnot? + +Examples: +"abc" ==# "Abc" evaluates to 0 +"abc" ==? "Abc" evaluates to 1 +"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise +NOTE: In |Vim9| script 'ignorecase' is not used. + + *E691* *E692* +A |List| can only be compared with a |List| and only "equal", "not equal", +"is" and "isnot" can be used. This compares the values of the list, +recursively. Ignoring case means case is ignored when comparing item values. + + *E735* *E736* +A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not +equal", "is" and "isnot" can be used. This compares the key/values of the +|Dictionary| recursively. Ignoring case means case is ignored when comparing +item values. + + *E694* +A |Funcref| can only be compared with a |Funcref| and only "equal", "not +equal", "is" and "isnot" can be used. Case is never ignored. Whether +arguments or a Dictionary are bound (with a partial) matters. The +Dictionaries must also be equal (or the same, in case of "is") and the +arguments must be equal (or the same). + +To compare Funcrefs to see if they refer to the same function, ignoring bound +Dictionary and arguments, use |get()| to get the function name: > + if get(Part1, 'name') == get(Part2, 'name') + " Part1 and Part2 refer to the same function +< *E1037* +Using "is" or "isnot" with a |List|, |Dictionary| or |Blob| checks whether +the expressions are referring to the same |List|, |Dictionary| or |Blob| +instance. A copy of a |List| is different from the original |List|. When +using "is" without a |List|, |Dictionary| or |Blob|, it is equivalent to +using "equal", using "isnot" equivalent to using "not equal". Except that +a different type means the values are different: > + echo 4 == '4' + 1 + echo 4 is '4' + 0 + echo 0 is [] + 0 +"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case. +In |Vim9| script this doesn't work, two strings are never identical. + +In legacy script, when comparing a String with a Number, the String is +converted to a Number, and the comparison is done on Numbers. This means +that: > + echo 0 == 'x' + 1 +because 'x' converted to a Number is zero. However: > + echo [0] == ['x'] + 0 +Inside a List or Dictionary this conversion is not used. + +In |Vim9| script the types must match. + +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(): case matters. + +When using the operators with a trailing '?', or the short version and +'ignorecase' is set, the comparing is done with stricmp(): case is ignored. + +'smartcase' is not used. + +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 *expr5* *bitwise-shift* +----- +expr6 << expr6 bitwise left shift *expr-<<* +expr6 >> expr6 bitwise right shift *expr->>* + *E1282* *E1283* +The "<<" and ">>" operators can be used to perform bitwise left or right shift +of the left operand by the number of bits specified by the right operand. The +operands are used as positive numbers. When shifting right with ">>" the +topmost bit (sometimes called the sign bit) is cleared. If the right operand +(shift amount) is more than the maximum number of bits in a number +(|v:numbersize|) the result is zero. + + +expr6 and expr7 *expr6* *expr7* *E1036* *E1051* +--------------- +expr7 + expr7 Number addition, |List| or |Blob| concatenation *expr-+* +expr7 - expr7 Number subtraction *expr--* +expr7 . expr7 String concatenation *expr-.* +expr7 .. expr7 String concatenation *expr-..* + +For |Lists| only "+" is possible and then both expr7 must be a list. The +result is a new list with the two lists Concatenated. + +For String concatenation ".." is preferred, since "." is ambiguous, it is also +used for |Dict| member access and floating point numbers. +In |Vim9| script and when |vimscript-version| is 2 or higher, using "." is not +allowed. + +In |Vim9| script the arguments of ".." are converted to String for simple +types: Number, Float, Special and Bool. For other types |string()| should be +used. + +expr8 * expr8 Number multiplication *expr-star* +expr8 / expr8 Number division *expr-/* +expr8 % expr8 Number modulo *expr-%* + +In legacy script, for all operators except "." and "..", Strings are converted +to Numbers. + +For bitwise operators see |and()|, |or()| and |xor()|. + +Note the difference between "+" and ".." in legacy script: + "123" + "456" = 579 + "123" .. "456" = "123456" + +Since '..' has the same precedence as '+' and '-', you need to read: > + 1 .. 90 + 90.0 +As: > + (1 .. 90) + 90.0 +That works in legacy script, since the String "190" is automatically converted +to the Number 190, which can be added to the Float 90.0. However: > + 1 .. 90 * 90.0 +Should be read as: > + 1 .. (90 * 90.0) +Since '..' has lower precedence than '*'. This does NOT work, since this +attempts to concatenate a Float and a String. + +When dividing a Number by zero the result depends on the value: + 0 / 0 = -0x80000000 (like NaN for Float) + >0 / 0 = 0x7fffffff (like positive infinity) + <0 / 0 = -0x7fffffff (like negative infinity) + (before Vim 7.2 it was always 0x7fffffff) +In |Vim9| script dividing a number by zero is an error. *E1154* + +When 64-bit Number support is enabled: + 0 / 0 = -0x8000000000000000 (like NaN for Float) + >0 / 0 = 0x7fffffffffffffff (like positive infinity) + <0 / 0 = -0x7fffffffffffffff (like negative infinity) + +When the righthand side of '%' is zero, the result is 0. + +None of these work for |Funcref|s. + +".", ".." and "%" do not work for Float. *E804* *E1035* + + +expr8 *expr8* +----- +<type>expr9 + +This is only available in |Vim9| script, see |type-casting|. + + +expr9 *expr9* +----- +! expr9 logical NOT *expr-!* +- expr9 unary minus *expr-unary--* ++ expr9 unary plus *expr-unary-+* + +For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one). +For '-' the sign of the number is changed. +For '+' the number is unchanged. Note: "++" has no effect. + +In legacy script a String will be converted to a Number first. Note that if +the string does not start with a digit you likely don't get what you expect. + +In |Vim9| script an error is given when "-" or "+" is used and the type is not +a number. + +In |Vim9| script "!" can be used for any type and the result is always a +boolean. Use "!!" to convert any type to a boolean, according to whether the +value is |falsy|. + +These three can be repeated and mixed. Examples: + !-1 == 0 + !!8 == 1 + --9 == 9 + + +expr10 *expr10* +------ +This expression is either |expr11| or a sequence of the alternatives below, +in any order. E.g., these are all possible: + expr10[expr1].name + expr10.name[expr1] + expr10(expr1, ...)[expr1].name + expr10->(expr1, ...)[expr1] +Evaluation is always from left to right. + +expr10[expr1] item of String or |List| *expr-[]* *E111* + *E909* *subscript* *E1062* +In legacy Vim script: +If expr10 is a Number or String this results in a String that contains the +expr1'th single byte from expr10. expr10 is used as a String (a number is +automatically converted to a String), expr1 as a Number. This doesn't +recognize multibyte encodings, see `byteidx()` for an alternative, or use +`split()` to turn the string into a list of characters. Example, to get the +byte under the cursor: > + :let c = getline(".")[col(".") - 1] + +In |Vim9| script: *E1147* *E1148* +If expr10 is a String this results in a String that contains the expr1'th +single character (including any composing characters) from expr10. To use byte +indexes use |strpart()|. + +Index zero gives the first byte or character. Careful: text column numbers +start with one! + +If the length of the String is less than the index, the result is an empty +String. A negative index always results in an empty string (reason: backward +compatibility). Use [-1:] to get the last byte or character. +In Vim9 script a negative index is used like with a list: count from the end. + +If expr10 is a |List| then it results the item at index expr1. See |list-index| +for possible index values. If the index is out of range this results in an +error. Example: > + :let item = mylist[-1] " get last item + +Generally, if a |List| index is equal to or higher than the length of the +|List|, or more negative than the length of the |List|, this results in an +error. + + +expr10[expr1a : expr1b] substring or |sublist| *expr-[:]* *substring* + +If expr10 is a String this results in the substring with the bytes or +characters from expr1a to and including expr1b. expr10 is used as a String, +expr1a and expr1b are used as a Number. + +In legacy Vim script the indexes are byte indexes. This doesn't recognize +multibyte encodings, see |byteidx()| for computing the indexes. If expr10 is +a Number it is first converted to a String. + +In Vim9 script the indexes are character indexes and include composing +characters. To use byte indexes use |strpart()|. To use character indexes +without including composing characters use |strcharpart()|. + +The item at index expr1b is included, it is inclusive. For an exclusive index +use the |slice()| function. + +If expr1a is omitted zero is used. If expr1b is omitted the length of the +string minus one is used. + +A negative number can be used to measure from the end of the string. -1 is +the last character, -2 the last but one, etc. + +If an index goes out of range for the string characters are omitted. If +expr1b is smaller than expr1a the result is an empty string. + +Examples: > + :let c = name[-1:] " last byte of a string + :let c = name[0:-1] " the whole string + :let c = name[-2:-2] " last but one byte of a string + :let s = line(".")[4:] " from the fifth byte to the end + :let s = s[:-3] " remove last two bytes +< + *slice* +If expr10 is a |List| this results in a new |List| with the items indicated by +the indexes expr1a and expr1b. This works like with a String, as explained +just above. Also see |sublist| below. Examples: > + :let l = mylist[:3] " first four items + :let l = mylist[4:4] " List with one item + :let l = mylist[:] " shallow copy of a List + +If expr10 is a |Blob| this results in a new |Blob| with the bytes in the +indexes expr1a and expr1b, inclusive. Examples: > + :let b = 0zDEADBEEF + :let bs = b[1:2] " 0zADBE + :let bs = b[:] " copy of 0zDEADBEEF + +Using expr10[expr1] or expr10[expr1a : expr1b] on a |Funcref| results in an +error. + +Watch out for confusion between a namespace and a variable followed by a colon +for a sublist: > + mylist[n:] " uses variable n + mylist[s:] " uses namespace s:, error! + + +expr10.name entry in a |Dictionary| *expr-entry* + *E1203* *E1229* +If expr10 is a |Dictionary| and it is followed by a dot, then the following +name will be used as a key in the |Dictionary|. This is just like: +expr10[name]. + +The name must consist of alphanumeric characters, just like a variable name, +but it may start with a number. Curly braces cannot be used. + +There must not be white space before or after the dot. + +Examples: > + :let dict = {"one": 1, 2: "two"} + :echo dict.one " shows "1" + :echo dict.2 " shows "two" + :echo dict .2 " error because of space before the dot + +Note that the dot is also used for String concatenation. To avoid confusion +always put spaces around the dot for String concatenation. + + +expr10(expr1, ...) |Funcref| function call *E1085* + +When expr10 is a |Funcref| type variable, invoke the function it refers to. + + +expr10->name([args]) method call *method* *->* +expr10->{lambda}([args]) + *E260* *E276* *E1265* +For methods that are also available as global functions this is the same as: > + name(expr10 [, args]) +There can also be methods specifically for the type of "expr10". + +This allows for chaining, passing the value that one method returns to the +next method: > + mylist->filter(filterexpr)->map(mapexpr)->sort()->join() +< +Example of using a lambda: > + GetPercentage()->{x -> x * 100}()->printf('%d%%') +< +When using -> the |expr9| operators will be applied first, thus: > + -1.234->string() +Is equivalent to: > + (-1.234)->string() +And NOT: > + -(1.234->string()) + +What comes after "->" can be a name, a simple expression (not containing any +parenthesis), or any expression in parentheses: > + base->name(args) + base->some.name(args) + base->alist[idx](args) + base->(getFuncRef())(args) +Note that in the last call the base is passed to the function resulting from +"(getFuncRef())", inserted before "args". *E1275* + + *E274* +"->name(" must not contain white space. There can be white space before the +"->" and after the "(", thus you can split the lines like this: > + mylist + \ ->filter(filterexpr) + \ ->map(mapexpr) + \ ->sort() + \ ->join() + +When using the lambda form there must be no white space between the } and the +(. + + + *expr11* +number +------ +number number constant *expr-number* + + *0x* *hex-number* *0o* *octal-number* *binary-number* +Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B) +and Octal (starting with 0, 0o or 0O). + +Assuming 64 bit numbers are used (see |v:numbersize|) an unsigned number is +truncated to 0x7fffffffffffffff or 9223372036854775807. You can use -1 to get +0xffffffffffffffff. + + *floating-point-format* +Floating point numbers can be written in two forms: + + [-+]{N}.{M} + [-+]{N}.{M}[eE][-+]{exp} + +{N} and {M} are numbers. Both {N} and {M} must be present and can only +contain digits, except that in |Vim9| script in {N} single quotes between +digits are ignored. +[-+] means there is an optional plus or minus sign. +{exp} is the exponent, power of 10. +Only a decimal point is accepted, not a comma. No matter what the current +locale is. + +Examples: + 123.456 + +0.0001 + 55.0 + -0.123 + 1.234e03 + 1.0E-6 + -3.1416e+88 + +These are INVALID: + 3. empty {M} + 1e40 missing .{M} + +Rationale: +Before floating point was introduced, the text "123.456" was interpreted as +the two numbers "123" and "456", both converted to a string and concatenated, +resulting in the string "123456". Since this was considered pointless, and we +could not find it intentionally being used in Vim scripts, this backwards +incompatibility was accepted in favor of being able to use the normal notation +for floating point numbers. + + *float-pi* *float-e* +A few useful values to copy&paste: > + :let pi = 3.14159265359 + :let e = 2.71828182846 +Or, if you don't want to write them in as floating-point literals, you can +also use functions, like the following: > + :let pi = acos(-1.0) + :let e = exp(1.0) +< + *floating-point-precision* +The precision and range of floating points numbers depends on what "double" +means in the library Vim was compiled with. There is no way to change this at +runtime. + +The default for displaying a |Float| is to use 6 decimal places, like using +printf("%g", f). You can select something else when using the |printf()| +function. Example: > + :echo printf('%.15e', atan(1)) +< 7.853981633974483e-01 + + + +string *string* *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 but allows up to 8 hex numbers. +\b backspace <BS> +\e escape <Esc> +\f formfeed 0x0C +\n newline <NL> +\r return <CR> +\t tab <Tab> +\\ backslash +\" double quote +\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use + in mappings, the 0x80 byte is escaped. + To use the double quote character it must be escaped: "<M-\">". + Don't use <Char-xxxx> to get a UTF-8 character, use \uxxxx as + mentioned above. +\<*xxx> Like \<xxx> but prepends a modifier instead of including it in the + character. E.g. "\<C-w>" is one character 0x17 while "\<*C-w>" is four + bytes: 3 for the CTRL modifier and then character "W". + +Note that "\xff" is stored as the byte 255, which may be invalid in some +encodings. Use "\u00ff" to store character 255 according to the current value +of 'encoding'. + +Note that "\000" and "\x00" force the end of the string. + + +blob-literal *blob-literal* *E973* +------------ + +Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes. +The sequence must be an even number of hex characters. Example: > + :let b = 0zFF00ED015DAF + + +literal-string *literal-string* *E115* +--------------- +'string' string constant *expr-'* + +Note that single quotes are used. + +This string is taken as it is. No backslashes are removed or have a special +meaning. The only exception is that two quotes stand for one quote. + +Single quoted strings are useful for patterns, so that backslashes do not need +to be doubled. These two commands are equivalent: > + if a =~ "\\s*" + if a =~ '\s*' + + +interpolated-string *$quote* *interpolated-string* +-------------------- +$"string" interpolated string constant *expr-$quote* +$'string' interpolated literal string constant *expr-$'* + +Interpolated strings are an extension of the |string| and |literal-string|, +allowing the inclusion of Vim script expressions (see |expr1|). Any +expression returning a value can be enclosed between curly braces. The value +is converted to a string. All the text and results of the expressions +are concatenated to make a new string. + *E1278* *E1279* +To include an opening brace '{' or closing brace '}' in the string content +double it. For double quoted strings using a backslash also works. A single +closing brace '}' will result in an error. + +Examples: > + let your_name = input("What's your name? ") +< What's your name? Peter ~ +> + echo + echo $"Hello, {your_name}!" +< Hello, Peter! ~ +> + echo $"The square root of {{9}} is {sqrt(9)}" +< The square root of {9} is 3.0 ~ + + +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* +-------- +@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 @@. See |registers| for an explanation of the available +registers. + +When using the '=' register you get the expression itself, not what it +evaluates to. Use |eval()| to evaluate it. + + +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. + +The functions `getenv()` and `setenv()` can also be used and work for +environment variables with non-alphanumeric names. +The function `environ()` can be used to get a Dict with all environment +variables. + + + *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 $shell + :echo expand("$shell") +The first one probably doesn't echo anything, the second echoes the $shell +variable (if your shell supports it). + + +internal variable *expr-variable* *E1015* *E1089* +----------------- +variable internal variable +See below |internal-variables|. + + +function call *expr-function* *E116* *E118* *E119* *E120* +------------- +function(expr1, ...) function call +See below |functions|. + + +lambda expression *expr-lambda* *lambda* +----------------- +{args -> expr1} legacy lambda expression *E451* +(args) => expr1 |Vim9| lambda expression + +A lambda expression creates a new unnamed function which returns the result of +evaluating |expr1|. Lambda expressions differ from |user-functions| in +the following ways: + +1. The body of the lambda expression is an |expr1| and not a sequence of |Ex| + commands. +2. The prefix "a:" should not be used for arguments. E.g.: > + :let F = {arg1, arg2 -> arg1 - arg2} + :echo F(5, 2) +< 3 + +The arguments are optional. Example: > + :let F = {-> 'error function'} + :echo F('ignored') +< error function + +The |Vim9| lambda does not only use a different syntax, it also adds type +checking and can be split over multiple lines, see |vim9-lambda|. + + *closure* +Lambda expressions can access outer scope variables and arguments. This is +often called a closure. Example where "i" and "a:arg" are used in a lambda +while they already exist in the function scope. They remain valid even after +the function returns: > + :function Foo(arg) + : let i = 3 + : return {x -> x + i - a:arg} + :endfunction + :let Bar = Foo(4) + :echo Bar(6) +< 5 + +Note that the variables must exist in the outer scope before the lambda is +defined for this to work. See also |:func-closure|. + +Lambda and closure support can be checked with: > + if has('lambda') + +Examples for using a lambda expression with |sort()|, |map()| and |filter()|: > + :echo map([1, 2, 3], {idx, val -> val + 1}) +< [2, 3, 4] > + :echo sort([3,7,2,1,4], {a, b -> a - b}) +< [1, 2, 3, 4, 7] + +The lambda expression is also useful for Channel, Job and timer: > + :let timer = timer_start(500, + \ {-> execute("echo 'Handler called'", "")}, + \ {'repeat': 3}) +< Handler called + Handler called + Handler called + +Note that it is possible to cause memory to be used and not freed if the +closure is referenced by the context it depends on: > + function Function() + let x = 0 + let F = {-> x} + endfunction +The closure uses "x" from the function scope, and "F" in that same scope +refers to the closure. This cycle results in the memory not being freed. +Recommendation: don't do this. + +Notice how execute() is used to execute an Ex command. That's ugly though. +In Vim9 script you can use a command block, see |inline-function|. + +Although you can use the loop variable of a `for` command, it must still exist +when the closure is called, otherwise you get an error. *E1302* + +Lambda expressions have internal names like '<lambda>42'. If you get an error +for a lambda expression, you can find what it is with the following command: > + :function <lambda>42 +See also: |numbered-function| + +============================================================================== +3. Internal variable *internal-variables* *E461* *E1001* + +An internal variable name can be made up of letters, digits and '_'. But it +cannot start with a digit. In legacy script it is also possible to use curly +braces, see |curly-braces-names|. + +In legacy script an internal variable is created with the ":let" command +|:let|. An internal variable is explicitly destroyed with the ":unlet" +command |:unlet|. +Using a name that is not an internal variable or refers to a variable that has +been destroyed results in an error. + +In |Vim9| script `:let` is not used and variables work differently, see |:var|. + + *variable-scope* +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 the function; + in a legacy script: global; + in a |Vim9| script: local to the script +|buffer-variable| b: Local to the current buffer. +|window-variable| w: Local to the current window. +|tabpage-variable| t: Local to the current tab page. +|global-variable| g: Global. +|local-variable| l: Local to a function (only in a legacy function) +|script-variable| s: Local to a |:source|'ed Vim script. +|function-argument| a: Function argument (only in a legacy function). +|vim-variable| v: Global, predefined by Vim. + +The scope name by itself can be used as a |Dictionary|. For example, to +delete all script-local variables: > + :for k in keys(s:) + : unlet s:[k] + :endfor + +Note: in Vim9 script variables can also be local to a block of commands, see +|vim9-scopes|. + *buffer-variable* *b:var* *b:* +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* *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. Resetting 'modified' when writing the buffer is + also counted. + 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 +< You cannot change or delete the b:changedtick variable. + + *window-variable* *w:var* *w:* +A variable name that is preceded with "w:" is local to the current window. It +is deleted when the window is closed. + + *tabpage-variable* *t:var* *t:* +A variable name that is preceded with "t:" is local to the current tab page, +It is deleted when the tab page is closed. {not available when compiled +without the |+windows| feature} + + *global-variable* *g:var* *g:* +Inside functions and in |Vim9| script global variables are accessed with "g:". +Omitting this will access a variable local to a function or script. "g:" +can also be used in any other place if you like. + + *local-variable* *l:var* *l:* +Inside functions local variables are accessed without prepending anything. +But you can also prepend "l:" if you like. However, without prepending "l:" +you may run into reserved variable names. For example "count". By itself it +refers to "v:count". Using "l:count" you can have a local variable with the +same name. + + *script-variable* *s:var* +In a legacy Vim script variables starting with "s:" can be used. They cannot +be accessed from outside of the scripts, thus are local to the script. +In |Vim9| script the "s:" prefix can be omitted, variables are script-local by +default. + +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 +- menus +- 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 variables 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:* + *E963* *E1063* +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. + This is the byte index in the |v:beval_lnum| line. + Only valid while evaluating the 'balloonexpr' option. + + *v:beval_bufnr* *beval_bufnr-variable* +v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only + valid while evaluating the 'balloonexpr' option. + + *v:beval_lnum* *beval_lnum-variable* +v:beval_lnum The number of the line, over which the mouse pointer is. Only + valid while evaluating the 'balloonexpr' option. + + *v:beval_text* *beval_text-variable* +v:beval_text The text under or after the mouse pointer. Usually a word as + it is useful for debugging a C program. 'iskeyword' applies, + but a dot and "->" before the position is included. When on a + ']' the text before it is used, including the matching '[' and + word before it. When on a Visual area within one line the + highlighted text is used. Also see |<cexpr>|. + Only valid while evaluating the 'balloonexpr' option. + + *v:beval_winnr* *beval_winnr-variable* +v:beval_winnr The number of the window, over which the mouse pointer is. Only + valid while evaluating the 'balloonexpr' option. The first + window has number zero (unlike most other places where a + window gets a number). + + *v:beval_winid* *beval_winid-variable* +v:beval_winid The |window-ID| of the window, over which the mouse pointer + is. Otherwise like v:beval_winnr. + + *v:char* *char-variable* +v:char Argument for evaluating 'formatexpr' and used for the typed + character when using <expr> in an abbreviation |:map-<expr>|. + It is also used by the |InsertCharPre| and |InsertEnter| events. + + *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:collate* *collate-variable* +v:collate The current locale setting for collation order of the runtime + environment. This allows Vim scripts to be aware of the + current locale encoding. Technical: it's the value of + LC_COLLATE. When not using a locale the value is "C". + This variable can not be set directly, use the |:language| + command. + See |multi-lang|. + + *v:colornames* +v:colornames A dictionary that maps color names to hex color strings. These + color names can be used with the |highlight-guifg|, + |highlight-guibg|, and |highlight-guisp| parameters. Updating + an entry in v:colornames has no immediate effect on the syntax + highlighting. The highlight commands (probably in a + colorscheme script) need to be re-evaluated in order to use + the updated color values. For example: > + + :let v:colornames['fuscia'] = '#cf3ab4' + :let v:colornames['mauve'] = '#915f6d' + :highlight Normal guifg=fuscia guibg=mauve +< + This cannot be used to override the |cterm-colors| but it can + be used to override other colors. For example, the X11 colors + defined in the `colors/lists/default.vim` (previously defined + in |rgb.txt|). When defining new color names in a plugin, the + recommended practice is to set a color entry only when it does + not already exist. For example: > + + :call extend(v:colornames, { + \ 'fuscia': '#cf3ab4', + \ 'mauve': '#915f6d, + \ }, 'keep') +< + Using |extend()| with the 'keep' option updates each color only + if it did not exist in |v:colornames|. Doing so allows the + user to choose the precise color value for a common name + by setting it in their |.vimrc|. + + It is possible to remove entries from this dictionary but + doing so is NOT recommended, because it is disruptive to + other scripts. It is also unlikely to achieve the desired + result because the |:colorscheme| and |:highlight| commands will + both automatically load all `colors/lists/default.vim` color + scripts. + + *v:completed_item* *completed_item-variable* +v:completed_item + |Dictionary| containing the |complete-items| for the most + recently completed word after |CompleteDone|. The + |Dictionary| is empty if the completion failed. + Note: Plugins can modify the value to emulate the builtin + |CompleteDone| event behavior. + + *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. + When there are two counts, as in "3d2w", they are multiplied, + just like what happens in the command, "d6w" for the example. + Also used for evaluating the 'formatexpr' option. + "count" also works, for backwards compatibility, unless + |scriptversion| is 3 or higher. + + *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 +< Note: if another deadly signal is caught when v:dying is one, + VimLeave autocommands will not be executed. + + *v:exiting* *exiting-variable* +v:exiting Vim exit code. Normally zero, non-zero when something went + wrong. The value is v:null before invoking the |VimLeavePre| + and |VimLeave| autocmds. See |:q|, |:x| and |:cquit|. + Example: > + :au VimLeave * echo "Exit value is " .. v:exiting +< + *v:echospace* *echospace-variable* +v:echospace Number of screen cells that can be used for an `:echo` message + in the last screen line before causing the |hit-enter-prompt|. + Depends on 'showcmd', 'ruler' and 'columns'. You need to + check 'cmdheight' for whether there are full-width lines + available above the last line. + + *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, unless + |scriptversion| is 3 or higher. + + *v:errors* *errors-variable* *assert-return* +v:errors Errors found by assert functions, such as |assert_true()|. + This is a list of strings. + The assert functions append an item when an assert fails. + The return value indicates this: a one is returned if an item + was added to v:errors, otherwise zero is returned. + To remove old results make it empty: > + :let v:errors = [] +< If v:errors is set to anything but a list it is made an empty + list by the assert function. + + *v:event* *event-variable* +v:event Dictionary containing information about the current + |autocommand|. See the specific event for what it puts in + this dictionary. + The dictionary is emptied when the |autocommand| finishes, + please refer to |dict-identity| for how to get an independent + copy of it. Use |deepcopy()| if you want to keep the + information after the event triggers. Example: > + au TextYankPost * let g:foo = deepcopy(v:event) +< + *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:false* *false-variable* +v:false A Number with value zero. Used to put "false" in JSON. See + |json_encode()|. + When used as a string this evaluates to "v:false". > + echo v:false +< v:false ~ + That is so that eval() can parse the string back to the same + value. Read-only. + In |Vim9| script "false" can be used which has a boolean type. + + *v:fcs_reason* *fcs_reason-variable* +v:fcs_reason The reason why the |FileChangedShell| event was triggered. + Can be used in an autocommand to decide what to do and/or what + to set v:fcs_choice to. Possible values: + deleted file no longer exists + conflict file contents, mode or timestamp was + changed and buffer is modified + changed file contents has changed + mode mode of file changed + time only file timestamp changed + + *v:fcs_choice* *fcs_choice-variable* +v:fcs_choice What should happen after a |FileChangedShell| event was + triggered. Can be used in an autocommand to tell Vim what to + 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 + will happen. + <empty> Nothing, the autocommand should do + everything that needs to be done. + The default is empty. If another (invalid) value is used then + Vim behaves like it is empty, there is no warning message. + + *v:fname* *fname-variable* +v:fname When evaluating 'includeexpr': the file name that was + detected. Empty otherwise. + + *v:fname_in* *fname_in-variable* +v:fname_in The name of the input file. Valid while evaluating: + option used for ~ + 'charconvert' file to be converted + 'diffexpr' original file + 'patchexpr' original file + 'printexpr' file to be printed + And set to the swap file name for |SwapExists|. + + *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 in the |sandbox|. |fold-foldtext| + + *v:foldlevel* *foldlevel-variable* +v:foldlevel Used for 'foldtext': foldlevel of closed fold. + Read-only in the |sandbox|. |fold-foldtext| + + *v:foldend* *foldend-variable* +v:foldend Used for 'foldtext': last line of closed fold. + Read-only in the |sandbox|. |fold-foldtext| + + *v:foldstart* *foldstart-variable* +v:foldstart Used for 'foldtext': first line of closed fold. + Read-only in the |sandbox|. |fold-foldtext| + + *v:hlsearch* *hlsearch-variable* +v:hlsearch Variable that indicates whether search highlighting is on. + Setting it makes sense only if 'hlsearch' is enabled which + requires |+extra_search|. Setting this variable to zero acts + like the |:nohlsearch| command, setting it to one acts like > + let &hlsearch = &hlsearch +< Note that the value is restored when returning from a + function. |function-search-undo|. + + *v:insertmode* *insertmode-variable* +v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand + events. Values: + i Insert mode + r Replace mode + v Virtual Replace mode + + *v:key* *key-variable* +v:key Key of the current item of a |Dictionary|. Only valid while + evaluating the expression used with |map()| and |filter()|. + Read-only. + + *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' |fold-expr|, 'formatexpr' and + 'indentexpr' expressions, tab page number for 'guitablabel' + and 'guitabtooltip'. Only valid while one of these + expressions is being evaluated. Read-only when in the + |sandbox|. + + *v:maxcol* *maxcol-variable* +v:maxcol Maximum line length. Depending on where it is used it can be + screen columns, characters or bytes. The value currently is + 2147483647 on all systems. + + *v:mouse_win* *mouse_win-variable* +v:mouse_win Window number for a mouse click obtained with |getchar()|. + First window has number 1, like with |winnr()|. The value is + zero when there was no mouse button click. + + *v:mouse_winid* *mouse_winid-variable* +v:mouse_winid Window ID for a mouse click obtained with |getchar()|. + The value is zero when there was no mouse button click. + + *v:mouse_lnum* *mouse_lnum-variable* +v:mouse_lnum Line number for a mouse click obtained with |getchar()|. + This is the text line number, not the screen line number. The + value is zero when there was no mouse button click. + + *v:mouse_col* *mouse_col-variable* +v:mouse_col Column number for a mouse click obtained with |getchar()|. + This is the screen column number, like with |virtcol()|. The + value is zero when there was no mouse button click. + + *v:none* *none-variable* *None* +v:none An empty String. Used to put an empty item in JSON. See + |json_encode()|. + This can also be used as a function argument to use the + default value, see |none-function_argument|. + When used as a number this evaluates to zero. + When used as a string this evaluates to "v:none". > + echo v:none +< v:none ~ + That is so that eval() can parse the string back to the same + value. Read-only. + Note that using `== v:none` and `!= v:none` will often give + an error. Instead, use `is v:none` and `isnot v:none` . + + *v:null* *null-variable* +v:null An empty String. Used to put "null" in JSON. See + |json_encode()|. + When used as a number this evaluates to zero. + When used as a string this evaluates to "v:null". > + echo v:null +< v:null ~ + That is so that eval() can parse the string back to the same + value. Read-only. + In |Vim9| script `null` can be used without "v:". + In some places `v:null` and `null` can be used for a List, + Dict, Job, 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. + + *v:numbermin* *numbermin-variable* +v:numbermin Minimum value of a number (negative). + + *v:numbersize* *numbersize-variable* +v:numbersize Number of bits in a Number. This is normally 64, but on some + systems it may be 32. + + *v:oldfiles* *oldfiles-variable* +v:oldfiles List of file names that is loaded from the |viminfo| file on + startup. These are the files that Vim remembers marks for. + The length of the List is limited by the ' argument of the + 'viminfo' option (default is 100). + When the |viminfo| file is not used the List is empty. + Also see |:oldfiles| and |c_#<|. + The List can be modified, but this has no effect on what is + stored in the |viminfo| file later. If you use values other + than String this will cause trouble. + {only when compiled with the |+viminfo| feature} + + *v:option_new* +v:option_new New value of the option. Valid while executing an |OptionSet| + autocommand. + *v:option_old* +v:option_old Old value of the option. Valid while executing an |OptionSet| + autocommand. Depending on the command used for setting and the + kind of option this is either the local old value or the + global old value. + *v:option_oldlocal* +v:option_oldlocal + Old local value of the option. Valid while executing an + |OptionSet| autocommand. + *v:option_oldglobal* +v:option_oldglobal + Old global value of the option. Valid while executing an + |OptionSet| autocommand. + *v:option_type* +v:option_type Scope of the set command. Valid while executing an + |OptionSet| autocommand. Can be either "global" or "local" + *v:option_command* +v:option_command + Command used to set the option. Valid while executing an + |OptionSet| autocommand. + value option was set via ~ + "setlocal" |:setlocal| or ":let l:xxx" + "setglobal" |:setglobal| or ":let g:xxx" + "set" |:set| or |:let| + "modeline" |modeline| + *v:operator* *operator-variable* +v:operator The last operator given in Normal mode. This is a single + character except for commands starting with <g> or <z>, + in which case it is two characters. Best used alongside + |v:prevcount| and |v:register|. Useful if you want to cancel + Operator-pending mode and then use the operator, e.g.: > + :omap O <Esc>:call MyMotion(v:operator)<CR> +< The value remains set until another operator is entered, thus + don't expect it to be empty. + v:operator is not set for |:delete|, |:yank| or other Ex + commands. + Read-only. + + *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 or Operator-pending mode and then + use the count, e.g.: > + :vmap % <Esc>:call MyFilter(v:prevcount)<CR> +< Read-only. + + *v:profiling* *profiling-variable* +v:profiling Normally zero. Set to one after using ":profile start". + See |profiling|. + + *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:progpath* *progpath-variable* +v:progpath Contains the command with which Vim was invoked, in a form + that when passed to the shell will run the same Vim executable + as the current one (if $PATH remains unchanged). + Useful if you want to message a Vim server using a + |--remote-expr|. + To get the full path use: > + echo exepath(v:progpath) +< If the command has a relative path it will be expanded to the + full path, so that it still works after `:cd`. Thus starting + "./vim" results in "/home/user/path/to/vim/src/vim". + On Linux and other systems it will always be the full path. + On Mac it may just be "vim" and using exepath() as mentioned + above should be used to get the full path. + On MS-Windows the executable may be called "vim.exe", but the + ".exe" is not added to v:progpath. + Read-only. + + *v:register* *register-variable* +v:register The name of the register in effect for the current normal mode + command (regardless of whether that command actually used a + register). Or for the currently executing normal mode mapping + (use this in custom commands that take a register). + If none is supplied it is the default register '"', unless + 'clipboard' contains "unnamed" or "unnamedplus", then it is + '*' or '+'. + Also see |getreg()| and |setreg()| + + *v:scrollstart* *scrollstart-variable* +v:scrollstart String describing the script or function that caused the + screen to scroll up. It's only set when it is empty, thus the + first reason is remembered. It is set to "Unknown" for a + typed command. + This can be used to find out why your script causes the + hit-enter prompt. + + *v:servername* *servername-variable* +v:servername The resulting registered |client-server-name| if any. + Read-only. + + +v:searchforward *v:searchforward* *searchforward-variable* + Search direction: 1 after a forward search, 0 after a + backward search. It is reset to forward when directly setting + the last search pattern, see |quote/|. + Note that the value is restored when returning from a + function. |function-search-undo|. + Read-write. + + *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, unless + |scriptversion| is 3 or higher. + + *v:sizeofint* *sizeofint-variable* +v:sizeofint Number of bytes in an int. Depends on how Vim was compiled. + This is only useful for deciding whether a test will give the + expected result. + + *v:sizeoflong* *sizeoflong-variable* +v:sizeoflong Number of bytes in a long. Depends on how Vim was compiled. + This is only useful for deciding whether a test will give the + expected result. + + *v:sizeofpointer* *sizeofpointer-variable* +v:sizeofpointer Number of bytes in a pointer. Depends on how Vim was compiled. + This is only useful for deciding whether a test will give the + expected result. + + *v:statusmsg* *statusmsg-variable* +v:statusmsg Last given status message. It's allowed to set this variable. + + *v:swapname* *swapname-variable* +v:swapname Only valid when executing |SwapExists| autocommands: Name of + the swap file found. Read-only. + + *v:swapchoice* *swapchoice-variable* +v:swapchoice |SwapExists| autocommands can set this to the selected choice + for handling an existing swap file: + 'o' Open read-only + 'e' Edit anyway + 'r' Recover + 'd' Delete swapfile + 'q' Quit + 'a' Abort + The value should be a single-character string. An empty value + results in the user being asked, as would happen when there is + no SwapExists autocommand. The default is empty. + + *v:swapcommand* *swapcommand-variable* +v:swapcommand Normal mode command to be executed after a file has been + opened. Can be used for a |SwapExists| autocommand to have + another Vim open the file and jump to the right place. For + example, when jumping to a tag the value is ":tag tagname\r". + For ":edit +cmd file" the value is ":cmd\r". + + *v:t_TYPE* *v:t_bool* *t_bool-variable* +v:t_bool Value of |Boolean| type. Read-only. See: |type()| + *v:t_channel* *t_channel-variable* +v:t_channel Value of |Channel| type. Read-only. See: |type()| + *v:t_dict* *t_dict-variable* +v:t_dict Value of |Dictionary| type. Read-only. See: |type()| + *v:t_float* *t_float-variable* +v:t_float Value of |Float| type. Read-only. See: |type()| + *v:t_func* *t_func-variable* +v:t_func Value of |Funcref| type. Read-only. See: |type()| + *v:t_job* *t_job-variable* +v:t_job Value of |Job| type. Read-only. See: |type()| + *v:t_list* *t_list-variable* +v:t_list Value of |List| type. Read-only. See: |type()| + *v:t_none* *t_none-variable* +v:t_none Value of |None| type. Read-only. See: |type()| + *v:t_number* *t_number-variable* +v:t_number Value of |Number| type. Read-only. See: |type()| + *v:t_string* *t_string-variable* +v:t_string Value of |String| type. Read-only. See: |type()| + *v:t_blob* *t_blob-variable* +v:t_blob Value of |Blob| type. Read-only. See: |type()| + *v:t_class* *t_class-variable* +v:t_class Value of |class| type. Read-only. See: |type()| + *v:t_object* *t_object-variable* +v:t_object Value of |object| type. Read-only. See: |type()| + + *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, then '>' or '?' 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. You can use |terminalprops()| to see what Vim + figured out about 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 higher). Pc is always zero. + If Pv is 141 or higher then Vim will try to request terminal + codes. This only works with xterm |xterm-codes|. + {only when compiled with |+termresponse| feature} + + *v:termblinkresp* +v:termblinkresp The escape sequence returned by the terminal for the |t_RC| + termcap entry. This is used to find out whether the terminal + cursor is blinking. This is used by |term_getcursor()|. + + *v:termstyleresp* +v:termstyleresp The escape sequence returned by the terminal for the |t_RS| + termcap entry. This is used to find out what the shape of the + cursor is. This is used by |term_getcursor()|. + + *v:termrbgresp* +v:termrbgresp The escape sequence returned by the terminal for the |t_RB| + termcap entry. This is used to find out what the terminal + background color is, see 'background'. + + *v:termrfgresp* +v:termrfgresp The escape sequence returned by the terminal for the |t_RF| + termcap entry. This is used to find out what the terminal + foreground color is. + + *v:termu7resp* +v:termu7resp The escape sequence returned by the terminal for the |t_u7| + termcap entry. This is used to find out what the terminal + does with ambiguous width characters, see 'ambiwidth'. + + *v:testing* *testing-variable* +v:testing Must be set before using `test_garbagecollect_now()`. + Also, when set certain error messages won't be shown for 2 + seconds. (e.g. "'dictionary' option is empty") + + *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, unless + |scriptversion| is 3 or higher + + *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:true* *true-variable* +v:true A Number with value one. Used to put "true" in JSON. See + |json_encode()|. + When used as a string this evaluates to "v:true". > + echo v:true +< v:true ~ + That is so that eval() can parse the string back to the same + value. Read-only. + In |Vim9| script "true" can be used which has a boolean type. + *v:val* *val-variable* +v:val Value of the current item of a |List| or |Dictionary|. Only + valid while evaluating the expression used with |map()| and + |filter()|. Read-only. + + *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 + is 501. Read-only. "version" also works, for backwards + compatibility, unless |scriptversion| is 3 or higher. + Use |has()| to check if a certain patch was included, e.g.: > + if has("patch-7.4.123") +< 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:versionlong* *versionlong-variable* +v:versionlong Like v:version, but also including the patchlevel in the last + four digits. Version 8.1 with patch 123 has value 8010123. + This can be used like this: > + if v:versionlong >= 8010123 +< However, if there are gaps in the list of patches included + this will not work well. This can happen if a recent patch + was included into an older version, e.g. for a security fix. + Use the has() function to make sure the patch is actually + included. + + *v:vim_did_enter* *vim_did_enter-variable* +v:vim_did_enter Zero until most of startup is done. It is set to one just + before |VimEnter| autocommands are triggered. + + *v:warningmsg* *warningmsg-variable* +v:warningmsg Last given warning message. It's allowed to set this variable. + + *v:windowid* *windowid-variable* +v:windowid When any X11 based GUI is running or when running in a + terminal and Vim connects to the X server (|-X|) this will be + set to the window ID. + When an MS-Windows GUI is running this will be set to the + window handle. + Otherwise the value is zero. + Note: for windows inside Vim use |winnr()| or |win_getid()|, + see |window-ID|. + +============================================================================== +4. Builtin Functions *functions* + +See |function-list| for a list grouped by what the function is used for. + +The alphabetic list of all builtin functions and details are in a separate +help file: |builtin-functions|. + +============================================================================== +5. Defining functions *user-functions* + +New functions can be defined. These can be called just like builtin +functions. The function takes arguments, executes a sequence of Ex commands +and can return a value. + +You can find most information about defining functions in |userfunc.txt|. +For Vim9 functions, which execute much faster, support type checking and more, +see |vim9.txt|. + +============================================================================== +6. Curly braces names *curly-braces-names* + +In most places where you can use a variable, you can use a "curly braces name" +variable. This is a regular variable name with one or more expressions +wrapped in braces {} like this: > + my_{adjective}_variable + +This only works in legacy Vim script, not in |Vim9| script. + +When Vim encounters this, it evaluates the expression inside the braces, puts +that in place of the expression, and re-interprets the whole as a variable +name. So in the above example, if the variable "adjective" was set to +"noisy", then the reference would be to "my_noisy_variable", whereas if +"adjective" was set to "quiet", then it would be to "my_quiet_variable". + +One application for this is to create a set of variables governed by an option +value. For example, the statement > + echo my_{&background}_message + +would output the contents of "my_dark_message" or "my_light_message" depending +on the current value of 'background'. + +You can use multiple brace pairs: > + echo my_{adverb}_{adjective}_message +..or even nest them: > + echo my_{ad{end_of_word}}_message +where "end_of_word" is either "verb" or "jective". + +However, the expression inside the braces must evaluate to a valid single +variable name, e.g. this is invalid: > + :let foo='a + b' + :echo c{foo}d +.. since the result of expansion is "ca + bd", which is not a variable name. + + *curly-braces-function-names* +You can call and define functions by an evaluated name in a similar way. +Example: > + :let func_end='whizz' + :call my_func_{func_end}(parameter) + +This would call the function "my_func_whizz(parameter)". + +This does NOT work: > + :let i = 3 + :let @{i} = '' " error + :echo @{i} " error + +============================================================================== +7. Commands *expression-commands* + +Note: in |Vim9| script `:let` is not used. `:var` is used for variable +declarations and assignments do not use a command. |vim9-declaration| + +:let {var-name} = {expr1} *:let* *E18* + Set internal variable {var-name} to the result of the + expression {expr1}. The variable will get the type + from the {expr}. If {var-name} didn't exist yet, it + is created. + +:let {var-name}[{idx}] = {expr1} *E689* *E1141* + Set a list item to the result of the expression + {expr1}. {var-name} must refer to a list and {idx} + must be a valid index in that list. For nested list + the index can be repeated. + 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:] +< When {var-name} is a |Blob| then {idx} can be the + length of the blob, in which case one byte is + appended. + + *E711* *E719* *E1165* *E1166* *E1183* +:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710* + Set a sequence of items in a |List| to the result of + the expression {expr1}, which must be a list with the + correct number of items. + {idx1} can be omitted, zero is used instead. + {idx2} can be omitted, meaning the end of the list. + When the selected range of items is partly past the + end of the list, items will be added. + + *:let+=* *:let-=* *:letstar=* *:let/=* *:let%=* + *:let.=* *:let..=* *E734* *E985* *E1019* +:let {var} += {expr1} Like ":let {var} = {var} + {expr1}". +:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}". +:let {var} *= {expr1} Like ":let {var} = {var} * {expr1}". +:let {var} /= {expr1} Like ":let {var} = {var} / {expr1}". +:let {var} %= {expr1} Like ":let {var} = {var} % {expr1}". +:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}". +:let {var} ..= {expr1} Like ":let {var} = {var} .. {expr1}". + These fail if {var} was not set yet and when the type + of {var} and {expr1} don't fit the operator. + `.=` is not supported with Vim script version 2 and + later, see |vimscript-version|. + + +:let ${env-name} = {expr1} *:let-environment* *:let-$* + Set environment variable {env-name} to the result of + the expression {expr1}. The type is always String. + + On some systems making an environment variable empty + causes it to be deleted. Many systems do not make a + difference between an environment variable that is not + set and an environment variable that is empty. + +:let ${env-name} .= {expr1} + Append {expr1} to the environment variable {env-name}. + If the environment variable didn't exist yet this + works like "=". + +:let @{reg-name} = {expr1} *:let-register* *:let-@* + Write the result of the expression {expr1} in register + {reg-name}. {reg-name} must be a single letter, and + must be the name of a writable register (see + |registers|). "@@" can be used for the unnamed + register, "@/" for the search pattern. + If the result of {expr1} ends in a <CR> or <NL>, the + register will be linewise, otherwise it will be set to + characterwise. + This can be used to clear the last search pattern: > + :let @/ = "" +< This is different from searching for an empty string, + that would match everywhere. + +:let @{reg-name} .= {expr1} + Append {expr1} to register {reg-name}. If the + register was empty it's like setting it to {expr1}. + +:let &{option-name} = {expr1} *:let-option* *:let-&* + Set option {option-name} to the result of the + expression {expr1}. A String or Number value is + always converted to the type of the option. + For an option local to a window or buffer the effect + is just like using the |:set| command: both the local + value and the global value are changed. + Example: > + :let &path = &path .. ',/usr/local/include' +< This also works for terminal codes in the form t_xx. + But only for alphanumerical names. Example: > + :let &t_k1 = "\<Esc>[234;" +< When the code does not exist yet it will be created as + a terminal key code, there is no error. + +:let &{option-name} .= {expr1} + For a string option: Append {expr1} to the value. + Does not insert a comma like |:set+=|. + +:let &{option-name} += {expr1} +:let &{option-name} -= {expr1} + For a number or boolean option: Add or subtract + {expr1}. + +:let &l:{option-name} = {expr1} +:let &l:{option-name} .= {expr1} +:let &l:{option-name} += {expr1} +:let &l:{option-name} -= {expr1} + Like above, but only set the local value of an option + (if there is one). Works like |:setlocal|. + +:let &g:{option-name} = {expr1} +:let &g:{option-name} .= {expr1} +:let &g:{option-name} += {expr1} +:let &g:{option-name} -= {expr1} + Like above, but only set the global value of an option + (if there is one). Works like |:setglobal|. + *E1093* +:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688* + {expr1} must evaluate to a |List|. The first item in + the list is assigned to {name1}, the second item to + {name2}, etc. + The number of names must match the number of items in + the |List|. + Each name can be one of the items of the ":let" + command as mentioned above. + Example: > + :let [s, item] = GetItem(s) +< Detail: {expr1} is evaluated first, then the + assignments are done in sequence. This matters if + {name2} depends on {name1}. Example: > + :let x = [0, 1] + :let i = 0 + :let [i, x[i]] = [1, 2] + :echo x +< The result is [0, 2]. + +:let [{name1}, {name2}, ...] .= {expr1} +:let [{name1}, {name2}, ...] += {expr1} +:let [{name1}, {name2}, ...] -= {expr1} + Like above, but append/add/subtract the value for each + |List| item. + +:let [{name}, ..., ; {lastname}] = {expr1} *E452* + Like |:let-unpack| above, but the |List| may have more + items than there are names. A list of the remaining + items is assigned to {lastname}. If there are no + remaining items {lastname} is set to an empty list. + Example: > + :let [a, b; rest] = ["aval", "bval", 3, 4] +< +:let [{name}, ..., ; {lastname}] .= {expr1} +:let [{name}, ..., ; {lastname}] += {expr1} +:let [{name}, ..., ; {lastname}] -= {expr1} + Like above, but append/add/subtract the value for each + |List| item. + + *:let=<<* *:let-heredoc* + *E990* *E991* *E172* *E221* *E1145* +:let {var-name} =<< [trim] [eval] {endmarker} +text... +text... +{endmarker} + Set internal variable {var-name} to a |List| + containing the lines of text bounded by the string + {endmarker}. + + If "eval" is not specified, then each line of text is + used as a |literal-string|, except that single quotes + does not need to be doubled. + If "eval" is specified, then any Vim expression in the + form {expr} is evaluated and the result replaces the + expression, like with |interpolated-string|. + Example where $HOME is expanded: > + let lines =<< trim eval END + some text + See the file {$HOME}/.vimrc + more text + END +< There can be multiple Vim expressions in a single line + but an expression cannot span multiple lines. If any + expression evaluation fails, then the assignment fails. + + {endmarker} must not contain white space. + {endmarker} cannot start with a lower case character. + The last line should end only with the {endmarker} + string without any other character. Watch out for + white space after {endmarker}! + + Without "trim" any white space characters in the lines + of text are preserved. If "trim" is specified before + {endmarker}, then indentation is stripped so you can + do: > + let text =<< trim END + if ok + echo 'done' + endif + END +< Results in: ["if ok", " echo 'done'", "endif"] + The marker must line up with "let" and the indentation + of the first line is removed from all the text lines. + Specifically: all the leading indentation exactly + matching the leading indentation of the first + non-empty text line is stripped from the input lines. + All leading indentation exactly matching the leading + indentation before `let` is stripped from the line + containing {endmarker}. Note that the difference + between space and tab matters here. + + If {var-name} didn't exist yet, it is created. + Cannot be followed by another command, but can be + followed by a comment. + + To avoid line continuation to be applied, consider + adding 'C' to 'cpoptions': > + set cpo+=C + let var =<< END + \ leading backslash + END + set cpo-=C +< + Examples: > + let var1 =<< END + Sample text 1 + Sample text 2 + Sample text 3 + END + + let data =<< trim DATA + 1 2 3 4 + 5 6 7 8 + DATA + + let code =<< trim eval CODE + let v = {10 + 20} + let h = "{$HOME}" + let s = "{Str1()} abc {Str2()}" + let n = {MyFunc(3, 4)} + CODE +< + *E121* +:let {var-name} .. List the value of variable {var-name}. Multiple + variable names may be given. Special names recognized + here: *E738* + g: global variables + b: local buffer variables + w: local window variables + t: local tab page variables + s: script-local variables + l: local function variables + v: Vim variables. + This does not work in Vim9 script. |vim9-declaration| + +:let List the values of all variables. The type of the + variable is indicated before the value: + <nothing> String + # Number + * Funcref + This does not work in Vim9 script. |vim9-declaration| + +:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795* *E1081* + Remove the internal variable {name}. Several variable + names can be given, they are all removed. The name + may also be a |List| or |Dictionary| item. + With [!] no error message is given for non-existing + variables. + One or more items from a |List| can be removed: > + :unlet list[3] " remove fourth item + :unlet list[3:] " remove fourth item to last +< One item from a |Dictionary| can be removed at a time: > + :unlet dict['two'] + :unlet dict.two +< This is especially useful to clean up used global + variables and script-local variables (these are not + deleted when the script ends). Function-local + variables are automatically deleted when the function + ends. + In |Vim9| script variables declared in a function or + script cannot be removed. + +:unl[et] ${env-name} ... *:unlet-environment* *:unlet-$* + Remove environment variable {env-name}. + Can mix {name} and ${env-name} in one :unlet command. + No error message is given for a non-existing + variable, also without !. + If the system does not support deleting an environment + variable, it is made empty. + + *:cons* *:const* *E1018* +:cons[t] {var-name} = {expr1} +:cons[t] [{name1}, {name2}, ...] = {expr1} +:cons[t] [{name}, ..., ; {lastname}] = {expr1} +:cons[t] {var-name} =<< [trim] {marker} +text... +text... +{marker} + Similar to |:let|, but additionally lock the variable + after setting the value. This is the same as locking + the variable with |:lockvar| just after |:let|, thus: > + :const x = 1 +< is equivalent to: > + :let x = 1 + :lockvar! x +< NOTE: in Vim9 script `:const` works differently, see + |vim9-const| + This is useful if you want to make sure the variable + is not modified. If the value is a List or Dictionary + literal then the items also cannot be changed: > + const ll = [1, 2, 3] + let ll[1] = 5 " Error! +< Nested references are not locked: > + let lvar = ['a'] + const lconst = [0, lvar] + let lconst[0] = 2 " Error! + let lconst[1][0] = 'b' " OK +< *E995* + |:const| does not allow to for changing a variable: > + :let x = 1 + :const x = 2 " Error! +< *E996* + Note that environment variables, option values and + register values cannot be used here, since they cannot + be locked. + +:cons[t] +:cons[t] {var-name} + If no argument is given or only {var-name} is given, + the behavior is the same as |:let|. + +:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv* + Lock the internal variable {name}. Locking means that + it can no longer be changed (until it is unlocked). + A locked variable can be deleted: > + :lockvar v + :let v = 'asdf' " fails! + :unlet v " works +< *E741* *E940* *E1118* *E1119* *E1120* *E1121* *E1122* + If you try to change a locked variable you get an + error message: "E741: Value is locked: {name}". + If you try to lock or unlock a built-in variable you + get an error message: "E940: Cannot lock or unlock + variable {name}". + + [depth] is relevant when locking a |List| or + |Dictionary|. It specifies how deep the locking goes: + 0 Lock the variable {name} but not its + value. + 1 Lock the |List| or |Dictionary| itself, + cannot add or remove items, but can + still change their values. + 2 Also lock the values, cannot change + the items. If an item is a |List| or + |Dictionary|, cannot add or remove + items, but can still change the + values. + 3 Like 2 but for the |List| / + |Dictionary| in the |List| / + |Dictionary|, one level deeper. + The default [depth] is 2, thus when {name} is a |List| + or |Dictionary| the values cannot be changed. + + Example with [depth] 0: > + let mylist = [1, 2, 3] + lockvar 0 mylist + let mylist[0] = 77 " OK + call add(mylist, 4] " OK + let mylist = [7, 8, 9] " Error! +< *E743* + For unlimited depth use [!] and omit [depth]. + However, there is a maximum depth of 100 to catch + loops. + + Note that when two variables refer to the same |List| + and you lock one of them, the |List| will also be + locked when used through the other variable. + Example: > + :let l = [0, 1, 2, 3] + :let cl = l + :lockvar l + :let cl[1] = 99 " won't work! +< You may want to make a copy of a list to avoid this. + See |deepcopy()|. + + +:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo* *E1246* + Unlock the internal variable {name}. Does the + opposite of |:lockvar|. + + If {name} does not exist: + - In |Vim9| script an error is given. + - In legacy script this is silently ignored. + +: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. + 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 + 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` + part was not executed either. + + You can use this to remain compatible with older + versions: > + :if version >= 500 + : 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 + avoid problems: > + :if version >= 600 + : execute "silent 1,$delete" + :endif +< + In |Vim9| script `:endif` cannot be shortened, to + improve script readability. + 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 + executed. + In |Vim9| script `:else` cannot be shortened, to + improve script readability. + + *:elseif* *:elsei* *E582* *E584* +:elsei[f] {expr1} Short for `:else` `:if`, with the addition that there + is no extra `:endif`. + In |Vim9| script `:elseif` cannot be shortened, to + improve script readability. + +:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw* + *E170* *E585* *E588* *E733* +: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`. + Example: > + :let lnum = 1 + :while lnum <= line("$") + :call FixLine(lnum) + :let lnum = lnum + 1 + :endwhile +< + In |Vim9| script `:while` and `:endwhile` cannot be + shortened, to improve script readability. + 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 + each item in {object}. {object} can be a |List|, + a |Blob| or a |String|. *E1177* + + Variable {var} is set to the value of each item. + In |Vim9| script the loop variable must not have been + declared yet, unless when it is a + global/window/tab/buffer variable. + + When an error is detected for a command inside 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) +< + When {object} is a |List| and not making a copy, in + legacy script Vim stores a reference to the next item + in the |List| before executing the commands with the + current item. Thus the current item can be removed + without effect. Removing any later item means it will + not be found. Thus the following example works (an + inefficient way to make a |List| empty): > + for item in mylist + call remove(mylist, 0) + endfor +< Note that reordering the |List| (e.g., with sort() or + reverse()) may have unexpected effects. + In |Vim9| script the index is used. If an item before + the current one is deleted the next item will be + skipped. + + When {object} is a |Blob|, Vim always makes a copy to + iterate over. Unlike with |List|, modifying the + |Blob| does not affect the iteration. + + When {object} is a |String| each item is a string with + one character, plus any combining characters. + + In |Vim9| script `:endfor` cannot be shortened, to + improve script readability. + +:for [{var1}, {var2}, ...] in {listlist} +:endfo[r] *E1140* + 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]] + :echo getline(lnum)[col] + :endfor +< + *:continue* *:con* *E586* +: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. + + In |Vim9| script `:cont` is the shortest form, to + improve script readability. + *: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. + + In |Vim9| script `:break` cannot be shortened, to + improve script readability. + +:try *:try* *:endt* *:endtry* + *E600* *E601* *E602* *E1032* +:endt[ry] Change the error handling for the commands between + `: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 + processing is terminated. Whether a function + definition has an "abort" argument does not matter. + Example: > + try | call Unknown() | finally | echomsg "cleanup" | endtry + 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 + processing is not terminated. + + The value "Vim:Interrupt" is used for an interrupt + exception. An error in a Vim command is converted + to a value of the form "Vim({command}):{errmsg}", + other errors are converted to a value of the form + "Vim:{errmsg}". {command} is the full command name, + and {errmsg} is the message that is displayed if the + error exception is not caught, always beginning with + the error number. + Examples: > + try | sleep 100 | catch /^Vim:Interrupt$/ | endtry + try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry +< + In |Vim9| script `:endtry` cannot be shortened, to + improve script readability. + + *:cat* *:catch* + *E603* *E604* *E605* *E654* *E1033* +: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 + 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 /.*/ +< + Another character can be used instead of / around the + {pattern}, so long as it does not have a special + meaning (e.g., '|' or '"') and doesn't occur inside + {pattern}. *E1067* + Information about the exception is available in + |v:exception|. Also see |throw-variables|. + NOTE: It is not reliable to ":catch" the TEXT of + an error message because it may vary in different + locales. + In |Vim9| script `:catch` cannot be shortened, to + improve script readability. + + *:fina* *:finally* *E606* *E607* +: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`). + + In |Vim9| script `:finally` cannot be shortened, to + improve script readability and avoid confusion with + `:final`. + + *:th* *:throw* *E608* *E1129* +: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` + (which may be found in a calling function or sourcing + script), until a matching `:catch` has been found. + If the exception is not caught, the command processing + is terminated. + Example: > + :try | throw "oops" | catch /^oo/ | echo "caught" | endtry +< Note that "catch" may need to be on a separate line + for when an error causes the parsing to skip the whole + line and not see the "|" that separates the commands. + + In |Vim9| script `:throw` cannot be shortened, to + improve script readability. + + *:ec* *:echo* +:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The + first {expr1} starts on a new line. + 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. + Cannot be followed by a comment. + Example: > + :echo "the value of 'shell' is" &shell +< *:echo-redraw* + A later redraw may make the message disappear again. + 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 + postponed until you type something), force a redraw + with the `:redraw` command. Example: > + :new | redraw | echo "there is a new window" +< + *:echon* +:echon {expr1} .. Echoes each {expr1}, without anything added. Also see + |:comment|. + 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 + command: > + :!echo % --> filename +< The arguments of ":!" are expanded, see |:_%|. > + :!echo "%" --> filename or "filename" +< Like the previous example. Whether you see the double + quotes or not depends on your 'shell'. > + :echo % --> nothing +< The '%' is an illegal character in an expression. > + :echo "%" --> % +< This just echoes the '%' character. > + :echo expand("%") --> filename +< This calls the expand() function to expand the '%'. + + *: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: > + :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. + + *:echom* *:echomsg* +: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 + displayed, not interpreted. + 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. + Example: > + :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see." +< See |:echo-redraw| to avoid the message disappearing + when the screen is redrawn. + + *:echow* *:echowin* *:echowindow* +:[N]echow[indow] {expr1} .. + Like |:echomsg| but when the messages popup window is + available the message is displayed there. This means + it will show for three seconds and avoid a + |hit-enter| prompt. If you want to hide it before + that, press Esc in Normal mode (when it would + otherwise beep). If it disappears too soon you can + use `:messages` to see the text. + When [N] is given then the window will show up for + this number of seconds. The last `:echowindow` with a + count matters, it is used once only. + The message window is available when Vim was compiled + with the +timer and the +popupwin features. + + *:echoe* *:echoerr* +:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the + 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, + 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`. + And to get a beep: > + :exe "normal \<Esc>" + +:echoc[onsole] {expr1} .. *:echoc* *:echoconsole* + Intended for testing: works like `:echomsg` but when + running in the GUI and started from a terminal write + the text to stdout. + + *:eval* +:eval {expr} Evaluate {expr} and discard the result. Example: > + :eval Getlist()->Filter()->append('$') + +< The expression is supposed to have a side effect, + since the resulting value is not used. In the example + the `append()` call appends the List with text to the + buffer. This is similar to `:call` but works with any + expression. + In |Vim9| script an expression without an effect will + result in error *E1207* . This should help noticing + mistakes. + + The command can be shortened to `:ev` or `:eva`, but + these are hard to recognize and therefore not to be + used. + + The command cannot be followed by "|" and another + command, since "|" is seen as part of the expression. + + + *:exe* *:execute* +:exe[cute] {expr1} .. Executes the string that results from the evaluation + of {expr1} as an Ex command. + Multiple arguments are concatenated, with a space in + between. To avoid the extra space use the ".." + operator to concatenate strings into one argument. + {expr1} is used as the processed command, command line + editing keys are not recognized. + Cannot be followed by a comment. + Examples: > + :execute "buffer" nextbuf + :execute "normal" count .. "w" +< + ":execute" can be used to append a command to commands + that don't accept a '|'. Example: > + :execute '!ls' | echo "theend" + +< ":execute" is also a nice way to avoid having to type + control characters in a Vim script for a ":normal" + command: > + :execute "normal ixxx\<Esc>" +< This has an <Esc> character, see |expr-string|. + + Be careful to correctly escape special characters in + file names. The |fnameescape()| function can be used + for Vim commands, |shellescape()| for |:!| commands. + Examples: > + :execute "e " .. fnameescape(filename) + :execute "!ls " .. shellescape(filename, 1) +< + Note: The executed string may be any command-line, but + starting or ending "if", "while" and "for" does not + always work, because when commands are skipped the + ":execute" is not evaluated and Vim loses track of + where blocks start and end. Also "break" and + "continue" should not be inside ":execute". + This example does not work, because the ":execute" is + not evaluated and Vim does not see the "while", and + gives an error for finding an ":endwhile": > + :if 0 + : execute 'while i > 5' + : echo "test" + : endwhile + :endif +< + It is allowed to have a "while" or "if" command + completely in the executed string: > + :execute 'while i < 5 | echo i | let i = i + 1 | endwhile' +< + + *:exe-comment* + ":execute", ":echo" and ":echon" cannot be followed by + a comment directly, because they see the '"' as the + start of a string. But, you can use '|' followed by a + comment. Example: > + :echo "foo" | "this is a comment + +============================================================================== +8. Exception handling *exception-handling* + +The Vim script language comprises an exception handling feature. This section +explains how it can be used in a Vim script. + +Exceptions may be raised by Vim on an error or on interrupt, see +|catch-errors| and |catch-interrupt|. You can also explicitly throw an +exception by using the ":throw" command, see |throw-catch|. + + +TRY CONDITIONALS *try-conditionals* + +Exceptions can be caught or can cause cleanup code to be executed. You can +use a try conditional to specify catch clauses (that catch exceptions) and/or +a finally clause (to be executed for cleanup). + A try conditional begins with a |:try| command and ends at the matching +|:endtry| command. In between, you can use a |:catch| command to start +a catch clause, or a |:finally| command to start a finally clause. There may +be none or multiple catch clauses, but there is at most one finally clause, +which must not be followed by any catch clauses. The lines before the catch +clauses and the finally clause is called a try block. > + + :try + : ... + : ... TRY BLOCK + : ... + :catch /{pattern}/ + : ... + : ... CATCH CLAUSE + : ... + :catch /{pattern}/ + : ... + : ... CATCH CLAUSE + : ... + :finally + : ... + : ... FINALLY CLAUSE + : ... + :endtry + +The try conditional allows to watch code for exceptions and to take the +appropriate actions. Exceptions from the try block may be caught. Exceptions +from the try block and also the catch clauses may cause cleanup actions. + When no exception is thrown during execution of the try block, the control +is transferred to the finally clause, if present. After its execution, the +script continues with the line following the ":endtry". + When an exception occurs during execution of the try block, the remaining +lines in the try block are skipped. The exception is matched against the +patterns specified as arguments to the ":catch" commands. The catch clause +after the first matching ":catch" is taken, other catch clauses are not +executed. The catch clause ends when the next ":catch", ":finally", or +":endtry" command is reached - whatever is first. Then, the finally clause +(if present) is executed. When the ":endtry" is reached, the script execution +continues in the following line as usual. + When an exception that does not match any of the patterns specified by the +":catch" commands is thrown in the try block, the exception is not caught by +that try conditional and none of the catch clauses is executed. Only the +finally clause, if present, is taken. The exception pends during execution of +the finally clause. It is resumed at the ":endtry", so that commands after +the ":endtry" are not executed and the exception might be caught elsewhere, +see |try-nesting|. + When during execution of a catch clause another exception is thrown, the +remaining lines in that catch clause are not executed. The new exception is +not matched against the patterns in any of the ":catch" commands of the same +try conditional and none of its catch clauses is taken. If there is, however, +a finally clause, it is executed, and the exception pends during its +execution. The commands following the ":endtry" are not executed. The new +exception might, however, be caught elsewhere, see |try-nesting|. + When during execution of the finally clause (if present) an exception is +thrown, the remaining lines in the finally clause are skipped. If the finally +clause has been taken because of an exception from the try block or one of the +catch clauses, the original (pending) exception is discarded. The commands +following the ":endtry" are not executed, and the exception from the finally +clause is propagated and can be caught elsewhere, see |try-nesting|. + +The finally clause is also executed, when a ":break" or ":continue" for +a ":while" loop enclosing the complete try conditional is executed from the +try block or a catch clause. Or when a ":return" or ":finish" is executed +from the try block or a catch clause of a try conditional in a function or +sourced script, respectively. The ":break", ":continue", ":return", or +":finish" pends during execution of the finally clause and is resumed when the +":endtry" is reached. It is, however, discarded when an exception is thrown +from the finally clause. + When a ":break" or ":continue" for a ":while" loop enclosing the complete +try conditional or when a ":return" or ":finish" is encountered in the finally +clause, the rest of the finally clause is skipped, and the ":break", +":continue", ":return" or ":finish" is executed as usual. If the finally +clause has been taken because of an exception or an earlier ":break", +":continue", ":return", or ":finish" from the try block or a catch clause, +this pending exception or command is discarded. + +For examples see |throw-catch| and |try-finally|. + + +NESTING OF TRY CONDITIONALS *try-nesting* + +Try conditionals can be nested arbitrarily. That is, a complete try +conditional can be put into the try block, a catch clause, or the finally +clause of another try conditional. If the inner try conditional does not +catch an exception thrown in its try block or throws a new exception from one +of its catch clauses or its finally clause, the outer try conditional is +checked according to the rules above. If the inner try conditional is in the +try block of the outer try conditional, its catch clauses are checked, but +otherwise only the finally clause is executed. It does not matter for +nesting, whether the inner try conditional is directly contained in the outer +one, or whether the outer one sources a script or calls a function containing +the inner try conditional. + +When none of the active try conditionals catches an exception, just their +finally clauses are executed. Thereafter, the script processing terminates. +An error message is displayed in case of an uncaught exception explicitly +thrown by a ":throw" command. For uncaught error and interrupt exceptions +implicitly raised by Vim, the error message(s) or interrupt message are shown +as usual. + +For examples see |throw-catch|. + + +EXAMINING EXCEPTION HANDLING CODE *except-examine* + +Exception handling code can get tricky. If you are in doubt what happens, set +'verbose' to 13 or use the ":13verbose" command modifier when sourcing your +script file. Then you see when an exception is thrown, discarded, caught, or +finished. When using a verbosity level of at least 14, things pending in +a finally clause are also shown. This information is also given in debug mode +(see |debug-scripts|). + + +THROWING AND CATCHING EXCEPTIONS *throw-catch* + +You can throw any number or string as an exception. Use the |:throw| command +and pass the value to be thrown as argument: > + :throw 4711 + :throw "string" +< *throw-expression* +You can also specify an expression argument. The expression is then evaluated +first, and the result is thrown: > + :throw 4705 + strlen("string") + :throw strpart("strings", 0, 6) + +An exception might be thrown during evaluation of the argument of the ":throw" +command. Unless it is caught there, the expression evaluation is abandoned. +The ":throw" command then does not throw a new exception. + Example: > + + :function! Foo(arg) + : try + : throw a:arg + : catch /foo/ + : endtry + : return 1 + :endfunction + : + :function! Bar() + : echo "in Bar" + : return 4710 + :endfunction + : + :throw Foo("arrgh") + Bar() + +This throws "arrgh", and "in Bar" is not displayed since Bar() is not +executed. > + :throw Foo("foo") + Bar() +however displays "in Bar" and throws 4711. + +Any other command that takes an expression as argument might also be +abandoned by an (uncaught) exception during the expression evaluation. The +exception is then propagated to the caller of the command. + Example: > + + :if Foo("arrgh") + : echo "then" + :else + : echo "else" + :endif + +Here neither of "then" or "else" is displayed. + + *catch-order* +Exceptions can be caught by a try conditional with one or more |:catch| +commands, see |try-conditionals|. The values to be caught by each ":catch" +command can be specified as a pattern argument. The subsequent catch clause +gets executed when a matching exception is caught. + Example: > + + :function! Foo(value) + : try + : throw a:value + : catch /^\d\+$/ + : echo "Number thrown" + : catch /.*/ + : echo "String thrown" + : endtry + :endfunction + : + :call Foo(0x1267) + :call Foo('string') + +The first call to Foo() displays "Number thrown", the second "String thrown". +An exception is matched against the ":catch" commands in the order they are +specified. Only the first match counts. So you should place the more +specific ":catch" first. The following order does not make sense: > + + : catch /.*/ + : echo "String thrown" + : catch /^\d\+$/ + : echo "Number thrown" + +The first ":catch" here matches always, so that the second catch clause is +never taken. + + *throw-variables* +If you catch an exception by a general pattern, you may access the exact value +in the variable |v:exception|: > + + : catch /^\d\+$/ + : echo "Number thrown. Value is" v:exception + +You may also be interested where an exception was thrown. This is stored in +|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the +exception most recently caught as long it is not finished. + Example: > + + :function! Caught() + : if v:exception != "" + : echo 'Caught "' . v:exception .. '" in ' .. v:throwpoint + : else + : echo 'Nothing caught' + : endif + :endfunction + : + :function! Foo() + : try + : try + : try + : throw 4711 + : finally + : call Caught() + : endtry + : catch /.*/ + : call Caught() + : throw "oops" + : endtry + : catch /.*/ + : call Caught() + : finally + : call Caught() + : endtry + :endfunction + : + :call Foo() + +This displays > + + Nothing caught + Caught "4711" in function Foo, line 4 + Caught "oops" in function Foo, line 10 + Nothing caught + +A practical example: The following command ":LineNumber" displays the line +number in the script or function where it has been used: > + + :function! LineNumber() + : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "") + :endfunction + :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry +< + *try-nested* +An exception that is not caught by a try conditional can be caught by +a surrounding try conditional: > + + :try + : try + : throw "foo" + : catch /foobar/ + : echo "foobar" + : finally + : echo "inner finally" + : endtry + :catch /foo/ + : echo "foo" + :endtry + +The inner try conditional does not catch the exception, just its finally +clause is executed. The exception is then caught by the outer try +conditional. The example displays "inner finally" and then "foo". + + *throw-from-catch* +You can catch an exception and throw a new one to be caught elsewhere from the +catch clause: > + + :function! Foo() + : throw "foo" + :endfunction + : + :function! Bar() + : try + : call Foo() + : catch /foo/ + : echo "Caught foo, throw bar" + : throw "bar" + : endtry + :endfunction + : + :try + : call Bar() + :catch /.*/ + : echo "Caught" v:exception + :endtry + +This displays "Caught foo, throw bar" and then "Caught bar". + + *rethrow* +There is no real rethrow in the Vim script language, but you may throw +"v:exception" instead: > + + :function! Bar() + : try + : call Foo() + : catch /.*/ + : echo "Rethrow" v:exception + : throw v:exception + : endtry + :endfunction +< *try-echoerr* +Note that this method cannot be used to "rethrow" Vim error or interrupt +exceptions, because it is not possible to fake Vim internal exceptions. +Trying so causes an error exception. You should throw your own exception +denoting the situation. If you want to cause a Vim error exception containing +the original error exception value, you can use the |:echoerr| command: > + + :try + : try + : asdf + : catch /.*/ + : echoerr v:exception + : endtry + :catch /.*/ + : echo v:exception + :endtry + +This code displays + + Vim(echoerr):Vim:E492: Not an editor command: asdf ~ + + +CLEANUP CODE *try-finally* + +Scripts often change global settings and restore them at their end. If the +user however interrupts the script by pressing CTRL-C, the settings remain in +an inconsistent state. The same may happen to you in the development phase of +a script when an error occurs or you explicitly throw an exception without +catching it. You can solve these problems by using a try conditional with +a finally clause for restoring the settings. Its execution is guaranteed on +normal control flow, on error, on an explicit ":throw", and on interrupt. +(Note that errors and interrupts from inside the try conditional are converted +to exceptions. When not caught, they terminate the script after the finally +clause has been executed.) +Example: > + + :try + : let s:saved_ts = &ts + : set ts=17 + : + : " Do the hard work here. + : + :finally + : let &ts = s:saved_ts + : unlet s:saved_ts + :endtry + +This method should be used locally whenever a function or part of a script +changes global settings which need to be restored on failure or normal exit of +that function or script part. + + *break-finally* +Cleanup code works also when the try block or a catch clause is left by +a ":continue", ":break", ":return", or ":finish". + Example: > + + :let first = 1 + :while 1 + : try + : if first + : echo "first" + : let first = 0 + : continue + : else + : throw "second" + : endif + : catch /.*/ + : echo v:exception + : break + : finally + : echo "cleanup" + : endtry + : echo "still in while" + :endwhile + :echo "end" + +This displays "first", "cleanup", "second", "cleanup", and "end". > + + :function! Foo() + : try + : return 4711 + : finally + : echo "cleanup\n" + : endtry + : echo "Foo still active" + :endfunction + : + :echo Foo() "returned by Foo" + +This displays "cleanup" and "4711 returned by Foo". You don't need to add an +extra ":return" in the finally clause. (Above all, this would override the +return value.) + + *except-from-finally* +Using either of ":continue", ":break", ":return", ":finish", or ":throw" in +a finally clause is possible, but not recommended since it abandons the +cleanup actions for the try conditional. But, of course, interrupt and error +exceptions might get raised from a finally clause. + Example where an error in the finally clause stops an interrupt from +working correctly: > + + :try + : try + : echo "Press CTRL-C for interrupt" + : while 1 + : endwhile + : finally + : unlet novar + : endtry + :catch /novar/ + :endtry + :echo "Script still running" + :sleep 1 + +If you need to put commands that could fail into a finally clause, you should +think about catching or ignoring the errors in these commands, see +|catch-errors| and |ignore-errors|. + + +CATCHING ERRORS *catch-errors* + +If you want to catch specific errors, you just have to put the code to be +watched in a try block and add a catch clause for the error message. The +presence of the try conditional causes all errors to be converted to an +exception. No message is displayed and |v:errmsg| is not set then. To find +the right pattern for the ":catch" command, you have to know how the format of +the error exception is. + Error exceptions have the following format: > + + Vim({cmdname}):{errmsg} +or > + Vim:{errmsg} + +{cmdname} is the name of the command that failed; the second form is used when +the command name is not known. {errmsg} is the error message usually produced +when the error occurs outside try conditionals. It always begins with +a capital "E", followed by a two or three-digit error number, a colon, and +a space. + +Examples: + +The command > + :unlet novar +normally produces the error message > + E108: No such variable: "novar" +which is converted inside try conditionals to an exception > + Vim(unlet):E108: No such variable: "novar" + +The command > + :dwim +normally produces the error message > + E492: Not an editor command: dwim +which is converted inside try conditionals to an exception > + Vim:E492: Not an editor command: dwim + +You can catch all ":unlet" errors by a > + :catch /^Vim(unlet):/ +or all errors for misspelled command names by a > + :catch /^Vim:E492:/ + +Some error messages may be produced by different commands: > + :function nofunc +and > + :delfunction nofunc +both produce the error message > + E128: Function name must start with a capital: nofunc +which is converted inside try conditionals to an exception > + Vim(function):E128: Function name must start with a capital: nofunc +or > + Vim(delfunction):E128: Function name must start with a capital: nofunc +respectively. You can catch the error by its number independently on the +command that caused it if you use the following pattern: > + :catch /^Vim(\a\+):E128:/ + +Some commands like > + :let x = novar +produce multiple error messages, here: > + E121: Undefined variable: novar + E15: Invalid expression: novar +Only the first is used for the exception value, since it is the most specific +one (see |except-several-errors|). So you can catch it by > + :catch /^Vim(\a\+):E121:/ + +You can catch all errors related to the name "nofunc" by > + :catch /\<nofunc\>/ + +You can catch all Vim errors in the ":write" and ":read" commands by > + :catch /^Vim(\(write\|read\)):E\d\+:/ + +You can catch all Vim errors by the pattern > + :catch /^Vim\((\a\+)\)\=:E\d\+:/ +< + *catch-text* +NOTE: You should never catch the error message text itself: > + :catch /No such variable/ +only works in the English locale, but not when the user has selected +a different language by the |:language| command. It is however helpful to +cite the message text in a comment: > + :catch /^Vim(\a\+):E108:/ " No such variable + + +IGNORING ERRORS *ignore-errors* + +You can ignore errors in a specific Vim command by catching them locally: > + + :try + : write + :catch + :endtry + +But you are strongly recommended NOT to use this simple form, since it could +catch more than you want. With the ":write" command, some autocommands could +be executed and cause errors not related to writing, for instance: > + + :au BufWritePre * unlet novar + +There could even be such errors you are not responsible for as a script +writer: a user of your script might have defined such autocommands. You would +then hide the error from the user. + It is much better to use > + + :try + : write + :catch /^Vim(write):/ + :endtry + +which only catches real write errors. So catch only what you'd like to ignore +intentionally. + +For a single command that does not cause execution of autocommands, you could +even suppress the conversion of errors to exceptions by the ":silent!" +command: > + :silent! nunmap k +This works also when a try conditional is active. + + +CATCHING INTERRUPTS *catch-interrupt* + +When there are active try conditionals, an interrupt (CTRL-C) is converted to +the exception "Vim:Interrupt". You can catch it like every exception. The +script is not terminated, then. + Example: > + + :function! TASK1() + : sleep 10 + :endfunction + + :function! TASK2() + : sleep 20 + :endfunction + + :while 1 + : let command = input("Type a command: ") + : try + : if command == "" + : continue + : elseif command == "END" + : break + : elseif command == "TASK1" + : call TASK1() + : elseif command == "TASK2" + : call TASK2() + : else + : echo "\nIllegal command:" command + : continue + : endif + : catch /^Vim:Interrupt$/ + : echo "\nCommand interrupted" + : " Caught the interrupt. Continue with next prompt. + : endtry + :endwhile + +You can interrupt a task here by pressing CTRL-C; the script then asks for +a new command. If you press CTRL-C at the prompt, the script is terminated. + +For testing what happens when CTRL-C would be pressed on a specific line in +your script, use the debug mode and execute the |>quit| or |>interrupt| +command on that line. See |debug-scripts|. + + +CATCHING ALL *catch-all* + +The commands > + + :catch /.*/ + :catch // + :catch + +catch everything, error exceptions, interrupt exceptions and exceptions +explicitly thrown by the |:throw| command. This is useful at the top level of +a script in order to catch unexpected things. + Example: > + + :try + : + : " do the hard work here + : + :catch /MyException/ + : + : " handle known problem + : + :catch /^Vim:Interrupt$/ + : echo "Script interrupted" + :catch /.*/ + : echo "Internal error (" .. v:exception .. ")" + : echo " - occurred at " .. v:throwpoint + :endtry + :" end of script + +Note: Catching all might catch more things than you want. Thus, you are +strongly encouraged to catch only for problems that you can really handle by +specifying a pattern argument to the ":catch". + Example: Catching all could make it nearly impossible to interrupt a script +by pressing CTRL-C: > + + :while 1 + : try + : sleep 1 + : catch + : endtry + :endwhile + + +EXCEPTIONS AND AUTOCOMMANDS *except-autocmd* + +Exceptions may be used during execution of autocommands. Example: > + + :autocmd User x try + :autocmd User x throw "Oops!" + :autocmd User x catch + :autocmd User x echo v:exception + :autocmd User x endtry + :autocmd User x throw "Arrgh!" + :autocmd User x echo "Should not be displayed" + : + :try + : doautocmd User x + :catch + : echo v:exception + :endtry + +This displays "Oops!" and "Arrgh!". + + *except-autocmd-Pre* +For some commands, autocommands get executed before the main action of the +command takes place. If an exception is thrown and not caught in the sequence +of autocommands, the sequence and the command that caused its execution are +abandoned and the exception is propagated to the caller of the command. + Example: > + + :autocmd BufWritePre * throw "FAIL" + :autocmd BufWritePre * echo "Should not be displayed" + : + :try + : write + :catch + : echo "Caught:" v:exception "from" v:throwpoint + :endtry + +Here, the ":write" command does not write the file currently being edited (as +you can see by checking 'modified'), since the exception from the BufWritePre +autocommand abandons the ":write". The exception is then caught and the +script displays: > + + Caught: FAIL from BufWrite Auto commands for "*" +< + *except-autocmd-Post* +For some commands, autocommands get executed after the main action of the +command has taken place. If this main action fails and the command is inside +an active try conditional, the autocommands are skipped and an error exception +is thrown that can be caught by the caller of the command. + Example: > + + :autocmd BufWritePost * echo "File successfully written!" + : + :try + : write /i/m/p/o/s/s/i/b/l/e + :catch + : echo v:exception + :endtry + +This just displays: > + + Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e) + +If you really need to execute the autocommands even when the main action +fails, trigger the event from the catch clause. + Example: > + + :autocmd BufWritePre * set noreadonly + :autocmd BufWritePost * set readonly + : + :try + : write /i/m/p/o/s/s/i/b/l/e + :catch + : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e + :endtry +< +You can also use ":silent!": > + + :let x = "ok" + :let v:errmsg = "" + :autocmd BufWritePost * if v:errmsg != "" + :autocmd BufWritePost * let x = "after fail" + :autocmd BufWritePost * endif + :try + : silent! write /i/m/p/o/s/s/i/b/l/e + :catch + :endtry + :echo x + +This displays "after fail". + +If the main action of the command does not fail, exceptions from the +autocommands will be catchable by the caller of the command: > + + :autocmd BufWritePost * throw ":-(" + :autocmd BufWritePost * echo "Should not be displayed" + : + :try + : write + :catch + : echo v:exception + :endtry +< + *except-autocmd-Cmd* +For some commands, the normal action can be replaced by a sequence of +autocommands. Exceptions from that sequence will be catchable by the caller +of the command. + Example: For the ":write" command, the caller cannot know whether the file +had actually been written when the exception occurred. You need to tell it in +some way. > + + :if !exists("cnt") + : let cnt = 0 + : + : autocmd BufWriteCmd * if &modified + : autocmd BufWriteCmd * let cnt = cnt + 1 + : autocmd BufWriteCmd * if cnt % 3 == 2 + : autocmd BufWriteCmd * throw "BufWriteCmdError" + : autocmd BufWriteCmd * endif + : autocmd BufWriteCmd * write | set nomodified + : autocmd BufWriteCmd * if cnt % 3 == 0 + : autocmd BufWriteCmd * throw "BufWriteCmdError" + : autocmd BufWriteCmd * endif + : autocmd BufWriteCmd * echo "File successfully written!" + : autocmd BufWriteCmd * endif + :endif + : + :try + : write + :catch /^BufWriteCmdError$/ + : if &modified + : echo "Error on writing (file contents not changed)" + : else + : echo "Error after writing" + : endif + :catch /^Vim(write):/ + : echo "Error on writing" + :endtry + +When this script is sourced several times after making changes, it displays +first > + File successfully written! +then > + Error on writing (file contents not changed) +then > + Error after writing +etc. + + *except-autocmd-ill* +You cannot spread a try conditional over autocommands for different events. +The following code is ill-formed: > + + :autocmd BufWritePre * try + : + :autocmd BufWritePost * catch + :autocmd BufWritePost * echo v:exception + :autocmd BufWritePost * endtry + : + :write + + +EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param* + +Some programming languages allow to use hierarchies of exception classes or to +pass additional information with the object of an exception class. You can do +similar things in Vim. + In order to throw an exception from a hierarchy, just throw the complete +class name with the components separated by a colon, for instance throw the +string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library. + When you want to pass additional information with your exception class, add +it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)" +for an error when writing "myfile". + With the appropriate patterns in the ":catch" command, you can catch for +base classes or derived classes of your hierarchy. Additional information in +parentheses can be cut out from |v:exception| with the ":substitute" command. + Example: > + + :function! CheckRange(a, func) + : if a:a < 0 + : throw "EXCEPT:MATHERR:RANGE(" .. a:func .. ")" + : endif + :endfunction + : + :function! Add(a, b) + : call CheckRange(a:a, "Add") + : call CheckRange(a:b, "Add") + : let c = a:a + a:b + : if c < 0 + : throw "EXCEPT:MATHERR:OVERFLOW" + : endif + : return c + :endfunction + : + :function! Div(a, b) + : call CheckRange(a:a, "Div") + : call CheckRange(a:b, "Div") + : if (a:b == 0) + : throw "EXCEPT:MATHERR:ZERODIV" + : endif + : return a:a / a:b + :endfunction + : + :function! Write(file) + : try + : execute "write" fnameescape(a:file) + : catch /^Vim(write):/ + : throw "EXCEPT:IO(" .. getcwd() .. ", " .. a:file .. "):WRITEERR" + : endtry + :endfunction + : + :try + : + : " something with arithmetic and I/O + : + :catch /^EXCEPT:MATHERR:RANGE/ + : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "") + : echo "Range error in" function + : + :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV + : echo "Math error" + : + :catch /^EXCEPT:IO/ + : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "") + : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "") + : if file !~ '^/' + : let file = dir .. "/" .. file + : endif + : echo 'I/O error for "' .. file .. '"' + : + :catch /^EXCEPT/ + : echo "Unspecified error" + : + :endtry + +The exceptions raised by Vim itself (on error or when pressing CTRL-C) use +a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself +exceptions with the "Vim" prefix; they are reserved for Vim. + Vim error exceptions are parameterized with the name of the command that +failed, if known. See |catch-errors|. + + +PECULIARITIES + *except-compat* +The exception handling concept requires that the command sequence causing the +exception is aborted immediately and control is transferred to finally clauses +and/or a catch clause. + +In the Vim script language there are cases where scripts and functions +continue after an error: in functions without the "abort" flag or in a command +after ":silent!", control flow goes to the following line, and outside +functions, control flow goes to the line following the outermost ":endwhile" +or ":endif". On the other hand, errors should be catchable as exceptions +(thus, requiring the immediate abortion). + +This problem has been solved by converting errors to exceptions and using +immediate abortion (if not suppressed by ":silent!") only when a try +conditional is active. This is no restriction since an (error) exception can +be caught only from an active try conditional. If you want an immediate +termination without catching the error, just use a try conditional without +catch clause. (You can cause cleanup code being executed before termination +by specifying a finally clause.) + +When no try conditional is active, the usual abortion and continuation +behavior is used instead of immediate abortion. This ensures compatibility of +scripts written for Vim 6.1 and earlier. + +However, when sourcing an existing script that does not use exception handling +commands (or when calling one of its functions) from inside an active try +conditional of a new script, you might change the control flow of the existing +script on error. You get the immediate abortion on error and can catch the +error in the new script. If however the sourced script suppresses error +messages by using the ":silent!" command (checking for errors by testing +|v:errmsg| if appropriate), its execution path is not changed. The error is +not converted to an exception. (See |:silent|.) So the only remaining cause +where this happens is for scripts that don't care about errors and produce +error messages. You probably won't want to use such code from your new +scripts. + + *except-syntax-err* +Syntax errors in the exception handling commands are never caught by any of +the ":catch" commands of the try conditional they belong to. Its finally +clauses, however, is executed. + Example: > + + :try + : try + : throw 4711 + : catch /\(/ + : echo "in catch with syntax error" + : catch + : echo "inner catch-all" + : finally + : echo "inner finally" + : endtry + :catch + : echo 'outer catch-all caught "' .. v:exception .. '"' + : finally + : echo "outer finally" + :endtry + +This displays: > + inner finally + outer catch-all caught "Vim(catch):E54: Unmatched \(" + outer finally +The original exception is discarded and an error exception is raised, instead. + + *except-single-line* +The ":try", ":catch", ":finally", and ":endtry" commands can be put on +a single line, but then syntax errors may make it difficult to recognize the +"catch" line, thus you better avoid this. + Example: > + :try | unlet! foo # | catch | endtry +raises an error exception for the trailing characters after the ":unlet!" +argument, but does not see the ":catch" and ":endtry" commands, so that the +error exception is discarded and the "E488: Trailing characters" message gets +displayed. + + *except-several-errors* +When several errors appear in a single command, the first error message is +usually the most specific one and therefore converted to the error exception. + Example: > + echo novar +causes > + E121: Undefined variable: novar + E15: Invalid expression: novar +The value of the error exception inside try conditionals is: > + Vim(echo):E121: Undefined variable: novar +< *except-syntax-error* +But when a syntax error is detected after a normal error in the same command, +the syntax error is used for the exception being thrown. + Example: > + unlet novar # +causes > + E108: No such variable: "novar" + E488: Trailing characters +The value of the error exception inside try conditionals is: > + Vim(unlet):E488: Trailing characters +This is done because the syntax error might change the execution path in a way +not intended by the user. Example: > + try + try | unlet novar # | catch | echo v:exception | endtry + catch /.*/ + echo "outer catch:" v:exception + endtry +This displays "outer catch: Vim(unlet):E488: Trailing characters", and then +a "E600: Missing :endtry" error message is given, see |except-single-line|. + +============================================================================== +9. Examples *eval-examples* + +Printing in Binary ~ +> + :" The function Nr2Bin() returns the binary string representation of a number. + :func Nr2Bin(nr) + : let n = a:nr + : let r = "" + : while n + : let r = '01'[n % 2] .. r + : let n = n / 2 + : endwhile + : return r + :endfunc + + :" The function String2Bin() converts each character in a string to a + :" binary string, separated with dashes. + :func String2Bin(str) + : let out = '' + : for ix in range(strlen(a:str)) + : let out = out .. '-' .. Nr2Bin(char2nr(a:str[ix])) + : endfor + : return out[1:] + :endfunc + +Example of its use: > + :echo Nr2Bin(32) +result: "100000" > + :echo String2Bin("32") +result: "110011-110010" + + +Sorting lines ~ + +This example sorts lines with a specific compare function. > + + :func SortBuffer() + : let lines = getline(1, '$') + : call sort(lines, function("Strcmp")) + : call setline(1, lines) + :endfunction + +As a one-liner: > + :call setline(1, sort(getline(1, '$'), function("Strcmp"))) + + +scanf() replacement ~ + *sscanf* +There is no sscanf() function in Vim. If you need to extract parts from a +line, you can use matchstr() and substitute() to do it. This example shows +how to get the file name, line number and column number out of a line like +"foobar.txt, 123, 45". > + :" Set up the match bit + :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)' + :"get the part matching the whole expression + :let l = matchstr(line, mx) + :"get each item out of the match + :let file = substitute(l, mx, '\1', '') + :let lnum = substitute(l, mx, '\2', '') + :let col = substitute(l, mx, '\3', '') + +The input is in the variable "line", the results in the variables "file", +"lnum" and "col". (idea from Michael Geddes) + + +getting the scriptnames in a Dictionary ~ + *scriptnames-dictionary* +The `:scriptnames` command can be used to get a list of all script files that +have been sourced. There is also the `getscriptinfo()` function, but the +information returned is not exactly the same. In case you need to manipulate +the output of `scriptnames` this code can be used: > + " Get the output of ":scriptnames" in the scriptnames_output variable. + let scriptnames_output = '' + redir => scriptnames_output + silent scriptnames + redir END + + " Split the output into lines and parse each line. Add an entry to the + " "scripts" dictionary. + let scripts = {} + for line in split(scriptnames_output, "\n") + " Only do non-blank lines. + if line =~ '\S' + " Get the first number in the line. + let nr = matchstr(line, '\d\+') + " Get the file name, remove the script number " 123: ". + let name = substitute(line, '.\+:\s*', '', '') + " Add an item to the Dictionary + let scripts[nr] = name + endif + endfor + unlet scriptnames_output + +============================================================================== +10. Vim script versions *vimscript-version* *vimscript-versions* + *scriptversion* +Over time many features have been added to Vim script. This includes Ex +commands, functions, variable types, etc. Each individual feature can be +checked with the |has()| and |exists()| functions. + +Sometimes old syntax of functionality gets in the way of making Vim better. +When support is taken away this will break older Vim scripts. To make this +explicit the |:scriptversion| command can be used. When a Vim script is not +compatible with older versions of Vim this will give an explicit error, +instead of failing in mysterious ways. + +When using a legacy function, defined with `:function`, in |Vim9| script then +scriptversion 4 is used. + + *scriptversion-1* > + :scriptversion 1 +< This is the original Vim script, same as not using a |:scriptversion| + command. Can be used to go back to old syntax for a range of lines. + Test for support with: > + has('vimscript-1') + +< *scriptversion-2* > + :scriptversion 2 +< String concatenation with "." is not supported, use ".." instead. + This avoids the ambiguity using "." for Dict member access and + floating point numbers. Now ".5" means the number 0.5. + + *scriptversion-3* > + :scriptversion 3 +< All |vim-variable|s must be prefixed by "v:". E.g. "version" doesn't + work as |v:version| anymore, it can be used as a normal variable. + Same for some obvious names as "count" and others. + + Test for support with: > + has('vimscript-3') +< + *scriptversion-4* > + :scriptversion 4 +< Numbers with a leading zero are not recognized as octal. "0o" or "0O" + is still recognized as octal. With the + previous version you get: > + echo 017 " displays 15 (octal) + echo 0o17 " displays 15 (octal) + echo 018 " displays 18 (decimal) +< with script version 4: > + echo 017 " displays 17 (decimal) + echo 0o17 " displays 15 (octal) + echo 018 " displays 18 (decimal) +< Also, it is possible to use single quotes inside numbers to make them + easier to read: > + echo 1'000'000 +< The quotes must be surrounded by digits. + + Test for support with: > + has('vimscript-4') + +============================================================================== +11. No +eval feature *no-eval-feature* + +When the |+eval| feature was disabled at compile time, none of the expression +evaluation commands are available. To prevent this from causing Vim scripts +to generate all kinds of errors, the ":if" and ":endif" commands are still +recognized, though the argument of the ":if" and everything between the ":if" +and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but +only if the commands are at the start of the line. The ":else" command is not +recognized. + +Example of how to avoid executing commands when the |+eval| feature is +missing: > + + :if 1 + : echo "Expression evaluation is compiled in" + :else + : echo "You will _never_ see this message" + :endif + +To execute a command only when the |+eval| feature is disabled can be done in +two ways. The simplest is to exit the script (or Vim) prematurely: > + if 1 + echo "commands executed with +eval" + finish + endif + args " command executed without +eval + +If you do not want to abort loading the script you can use a trick, as this +example shows: > + + silent! while 0 + set history=111 + silent! endwhile + +When the |+eval| feature is available the command is skipped because of the +"while 0". Without the |+eval| feature the "while 0" is an error, which is +silently ignored, and the command is executed. + +============================================================================== +12. The sandbox *eval-sandbox* *sandbox* + +The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and +'foldtext' options may be evaluated in a sandbox. This means that you are +protected from these expressions having nasty side effects. This gives some +safety for when these options are set from a modeline. It is also used when +the command from a tags file is executed and for CTRL-R = in the command line. +The sandbox is also used for the |:sandbox| command. + *E48* +These items are not allowed in the sandbox: + - changing the buffer text + - defining or changing mapping, autocommands, user commands + - setting certain options (see |option-summary|) + - setting certain v: variables (see |v:var|) *E794* + - executing a shell command + - reading or writing a file + - jumping to another buffer or editing a file + - executing Python, Perl, etc. commands +This is not guaranteed 100% secure, but it should block most attacks. + + *:san* *:sandbox* +:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an + option that may have been set from a modeline, e.g. + 'foldexpr'. + + *sandbox-option* +A few options contain an expression. When this expression is evaluated it may +have to be done in the sandbox to avoid a security risk. But the sandbox is +restrictive, thus this only happens when the option was set from an insecure +location. Insecure in this context are: +- sourcing a .vimrc or .exrc in the current directory +- while executing in the sandbox +- value coming from a modeline +- executing a function that was defined in the sandbox + +Note that when in the sandbox and saving an option value and restoring it, the +option will still be marked as it was set in the sandbox. + +============================================================================== +13. Textlock *textlock* + +In a few situations it is not allowed to change the text in the buffer, jump +to another window and some other things that might confuse or break what Vim +is currently doing. This mostly applies to things that happen when Vim is +actually doing something else. For example, evaluating the 'balloonexpr' may +happen any moment the mouse cursor is resting at some position. + +This is not allowed when the textlock is active: + - changing the buffer text + - jumping to another buffer or window + - editing another file + - closing a window or quitting Vim + - etc. + + + vim:tw=78:ts=8:noet:ft=help:norl: |