blob: 87edd49ecea810c18ff369401ce0dba6b7339a2c [file] [log] [blame]
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001*eval.txt* For Vim version 8.2. Last change: 2022 Feb 21
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
Bram Moolenaar446cb832008-06-24 21:56:24 +00004 VIM REFERENCE MANUAL by Bram Moolenaar
Bram Moolenaar071d4272004-06-13 20:20:40 +00005
6
7Expression evaluation *expression* *expr* *E15* *eval*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00008 *E1002*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009Using expressions is introduced in chapter 41 of the user manual |usr_41.txt|.
10
11Note: Expression evaluation can be disabled at compile time. If this has been
Bram Moolenaar58b85342016-08-14 19:54:54 +020012done, the features in this document are not available. See |+eval| and
Bram Moolenaard8b02732005-01-14 21:48:43 +000013|no-eval-feature|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000014
Bram Moolenaar1cae5a02021-12-27 21:28:34 +000015This file is mainly about the backwards compatible (legacy) Vim script. For
Bram Moolenaar2f0936c2022-01-08 21:51:59 +000016specifics of Vim9 script, which can execute much faster, supports type
17checking and much more, see |vim9.txt|. Where the syntax or semantics differ
18a remark is given.
Bram Moolenaar8a7d6542020-01-26 15:56:19 +010019
Bram Moolenaar13065c42005-01-08 16:08:21 +0000201. Variables |variables|
21 1.1 Variable types
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000022 1.2 Function references |Funcref|
Bram Moolenaar7c626922005-02-07 22:01:03 +000023 1.3 Lists |Lists|
Bram Moolenaard8b02732005-01-14 21:48:43 +000024 1.4 Dictionaries |Dictionaries|
Bram Moolenaard8968242019-01-15 22:51:57 +010025 1.5 Blobs |Blobs|
26 1.6 More about variables |more-variables|
Bram Moolenaar13065c42005-01-08 16:08:21 +0000272. Expression syntax |expression-syntax|
283. Internal variable |internal-variables|
294. Builtin Functions |functions|
305. Defining functions |user-functions|
316. Curly braces names |curly-braces-names|
327. Commands |expression-commands|
338. Exception handling |exception-handling|
349. Examples |eval-examples|
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02003510. Vim script version |vimscript-version|
3611. No +eval feature |no-eval-feature|
3712. The sandbox |eval-sandbox|
3813. Textlock |textlock|
Bram Moolenaared997ad2019-07-21 16:42:00 +020039
40Testing support is documented in |testing.txt|.
41Profiling is documented at |profiling|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000042
Bram Moolenaar071d4272004-06-13 20:20:40 +000043==============================================================================
441. Variables *variables*
45
Bram Moolenaar13065c42005-01-08 16:08:21 +0000461.1 Variable types ~
Bram Moolenaarf10911e2022-01-29 22:20:48 +000047 *E712* *E896* *E897* *E899* *E1098*
48 *E1107* *E1135* *E1138*
Bram Moolenaar06fe74a2019-08-31 16:20:32 +020049There are ten types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000050
Bram Moolenaar664f3cf2019-12-07 16:03:51 +010051 *Number* *Integer*
52Number A 32 or 64 bit signed number. |expr-number|
Bram Moolenaarf9706e92020-02-22 14:27:04 +010053 The number of bits is available in |v:numbersize|.
Bram Moolenaar6f02b002021-01-10 20:22:54 +010054 Examples: -123 0x10 0177 0o177 0b1011
Bram Moolenaard8b02732005-01-14 21:48:43 +000055
Bram Moolenaar446cb832008-06-24 21:56:24 +000056Float A floating point number. |floating-point-format| *Float*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +000057 {only when compiled with the |+float| feature} *E1076*
Bram Moolenaar446cb832008-06-24 21:56:24 +000058 Examples: 123.456 1.15e-6 -1.1e3
59
Bram Moolenaard8b02732005-01-14 21:48:43 +000060String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000061 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000062
Bram Moolenaard8968242019-01-15 22:51:57 +010063List An ordered sequence of items, see |List| for details.
Bram Moolenaard8b02732005-01-14 21:48:43 +000064 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000065
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000066Dictionary An associative, unordered array: Each entry has a key and a
67 value. |Dictionary|
Bram Moolenaard5abb4c2019-07-13 22:46:10 +020068 Examples:
69 {'blue': "#0000ff", 'red': "#ff0000"}
Bram Moolenaar4c6d9042019-07-16 22:04:02 +020070 #{blue: "#0000ff", red: "#ff0000"}
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000071
Bram Moolenaar835dc632016-02-07 14:27:38 +010072Funcref A reference to a function |Funcref|.
73 Example: function("strlen")
Bram Moolenaar1d429612016-05-24 15:44:17 +020074 It can be bound to a dictionary and arguments, it then works
75 like a Partial.
76 Example: function("Callback", [arg], myDict)
Bram Moolenaar835dc632016-02-07 14:27:38 +010077
Bram Moolenaar02e83b42016-02-21 20:10:26 +010078Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010079
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020080Job Used for a job, see |job_start()|. *Job* *Jobs*
Bram Moolenaar38a55632016-02-15 22:07:32 +010081
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020082Channel Used for a channel, see |ch_open()|. *Channel* *Channels*
Bram Moolenaar835dc632016-02-07 14:27:38 +010083
Bram Moolenaard8968242019-01-15 22:51:57 +010084Blob Binary Large Object. Stores any sequence of bytes. See |Blob|
85 for details
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010086 Example: 0zFF00ED015DAF
87 0z is an empty Blob.
88
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000089The Number and String types are converted automatically, depending on how they
90are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000091
92Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020093the Number. Examples:
94 Number 123 --> String "123" ~
95 Number 0 --> String "0" ~
96 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020097 *octal*
Bram Moolenaard43906d2020-07-20 21:31:32 +020098Conversion from a String to a Number only happens in legacy Vim script, not in
99Vim9 script. It is done by converting the first digits to a number.
100Hexadecimal "0xf9", Octal "017" or "0o17", and Binary "0b10"
Bram Moolenaar6f02b002021-01-10 20:22:54 +0100101numbers are recognized
Bram Moolenaar5da36052021-12-27 15:39:57 +0000102NOTE: when using |Vim9| script or |scriptversion-4| octal with a leading "0"
103is not recognized. The 0o notation requires patch 8.2.0886.
Bram Moolenaar6f02b002021-01-10 20:22:54 +0100104If the String doesn't start with digits, the result is zero.
Bram Moolenaarfa735342016-01-03 22:14:44 +0100105Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200106 String "456" --> Number 456 ~
107 String "6bar" --> Number 6 ~
108 String "foo" --> Number 0 ~
109 String "0xf1" --> Number 241 ~
110 String "0100" --> Number 64 ~
Bram Moolenaarc17e66c2020-06-02 21:38:22 +0200111 String "0o100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +0100112 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200113 String "-8" --> Number -8 ~
114 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000115
116To force conversion from String to Number, add zero to it: >
117 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000118< 64 ~
119
120To avoid a leading zero to cause octal conversion, or for using a different
121base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000122
Bram Moolenaard09091d2019-01-17 16:07:22 +0100123 *TRUE* *FALSE* *Boolean*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000124For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200125You can also use |v:false| and |v:true|, in Vim9 script |false| and |true|.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200126When TRUE is returned from a function it is the Number one, FALSE is the
127number zero.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000128
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200129Note that in the command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000130 :if "foo"
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200131 :" NOT executed
132"foo" is converted to 0, which means FALSE. If the string starts with a
133non-zero number it means TRUE: >
134 :if "8foo"
135 :" executed
136To test for a non-empty string, use empty(): >
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200137 :if !empty("foo")
Bram Moolenaar92f26c22020-10-03 20:17:30 +0200138
139< *falsy* *truthy*
140An expression can be used as a condition, ignoring the type and only using
141whether the value is "sort of true" or "sort of false". Falsy is:
142 the number zero
143 empty string, blob, list or dictionary
144Other values are truthy. Examples:
145 0 falsy
146 1 truthy
147 -1 truthy
148 0.0 falsy
149 0.1 truthy
150 '' falsy
151 'x' truthy
152 [] falsy
153 [0] truthy
154 {} falsy
155 #{x: 1} truthy
156 0z falsy
157 0z00 truthy
158
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200159 *non-zero-arg*
160Function arguments often behave slightly different from |TRUE|: If the
161argument is present and it evaluates to a non-zero Number, |v:true| or a
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200162non-empty String, then the value is considered to be TRUE.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100163Note that " " and "0" are also non-empty strings, thus considered to be TRUE.
164A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200165
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000166 *E611* *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910*
167 *E913* *E974* *E975* *E976*
Bram Moolenaard09091d2019-01-17 16:07:22 +0100168|List|, |Dictionary|, |Funcref|, |Job|, |Channel| and |Blob| types are not
169automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000170
Bram Moolenaar446cb832008-06-24 21:56:24 +0000171 *E805* *E806* *E808*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200172When mixing Number and Float the Number is converted to Float. Otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +0000173there is no automatic conversion of Float. You can use str2float() for String
174to Float, printf() for Float to String and float2nr() for Float to Number.
175
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000176 *E362* *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100177When expecting a Float a Number can also be used, but nothing else.
178
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100179 *no-type-checking*
180You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000181
Bram Moolenaar13065c42005-01-08 16:08:21 +0000182
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001831.2 Function references ~
Bram Moolenaara2baa732022-02-04 16:09:54 +0000184 *Funcref* *E695* *E718* *E1086* *E1192*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200185A Funcref variable is obtained with the |function()| function, the |funcref()|
186function or created with the lambda expression |expr-lambda|. It can be used
187in an expression in the place of a function name, before the parenthesis
188around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000189
190 :let Fn = function("MyFunc")
191 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000192< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000193A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200194can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000195cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000196
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000197A special case is defining a function and directly assigning its Funcref to a
198Dictionary entry. Example: >
199 :function dict.init() dict
200 : let self.val = 0
201 :endfunction
202
203The key of the Dictionary can start with a lower case letter. The actual
204function name is not used here. Also see |numbered-function|.
205
206A Funcref can also be used with the |:call| command: >
207 :call Fn()
208 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000209
210The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000211 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000212
213You can use |call()| to invoke a Funcref and use a list variable for the
214arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000215 :let r = call(Fn, mylist)
Bram Moolenaar1d429612016-05-24 15:44:17 +0200216<
217 *Partial*
218A Funcref optionally binds a Dictionary and/or arguments. This is also called
219a Partial. This is created by passing the Dictionary and/or arguments to
Bram Moolenaar58b85342016-08-14 19:54:54 +0200220function() or funcref(). When calling the function the Dictionary and/or
221arguments will be passed to the function. Example: >
Bram Moolenaar1d429612016-05-24 15:44:17 +0200222
223 let Cb = function('Callback', ['foo'], myDict)
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100224 call Cb('bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200225
226This will invoke the function as if using: >
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100227 call myDict.Callback('foo', 'bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200228
229This is very useful when passing a function around, e.g. in the arguments of
230|ch_open()|.
231
232Note that binding a function to a Dictionary also happens when the function is
233a member of the Dictionary: >
234
235 let myDict.myFunction = MyFunction
236 call myDict.myFunction()
237
238Here MyFunction() will get myDict passed as "self". This happens when the
239"myFunction" member is accessed. When making assigning "myFunction" to
240otherDict and calling it, it will be bound to otherDict: >
241
242 let otherDict.myFunction = myDict.myFunction
243 call otherDict.myFunction()
244
245Now "self" will be "otherDict". But when the dictionary was bound explicitly
246this won't happen: >
247
248 let myDict.myFunction = function(MyFunction, myDict)
249 let otherDict.myFunction = myDict.myFunction
250 call otherDict.myFunction()
251
Bram Moolenaard823fa92016-08-12 16:29:27 +0200252Here "self" will be "myDict", because it was bound explicitly.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000253
254
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002551.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200256 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000257A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar58b85342016-08-14 19:54:54 +0200258can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000259position in the sequence.
260
Bram Moolenaar13065c42005-01-08 16:08:21 +0000261
262List creation ~
263 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000264A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000265Examples: >
266 :let mylist = [1, two, 3, "four"]
267 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000268
Bram Moolenaar58b85342016-08-14 19:54:54 +0200269An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000270List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000271 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000272
273An extra comma after the last item is ignored.
274
Bram Moolenaar13065c42005-01-08 16:08:21 +0000275
276List index ~
277 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000278An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000279after the List. Indexes are zero-based, thus the first item has index zero. >
280 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000281 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000282
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000283When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000284 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000285<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000286A negative index is counted from the end. Index -1 refers to the last item in
287the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000288 :let last = mylist[-1] " get the last item: "four"
289
Bram Moolenaar13065c42005-01-08 16:08:21 +0000290To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000291is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000292 :echo get(mylist, idx)
293 :echo get(mylist, idx, "NONE")
294
295
296List concatenation ~
Bram Moolenaar34453202021-01-31 13:08:38 +0100297 *list-concatenation*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000298Two lists can be concatenated with the "+" operator: >
299 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000300 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000301
Bram Moolenaar34453202021-01-31 13:08:38 +0100302To prepend or append an item, turn the item into a list by putting [] around
303it. To change a list in-place, refer to |list-modification| below.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000304
305
306Sublist ~
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200307 *sublist*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000308A part of the List can be obtained by specifying the first and last index,
309separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000310 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000311
312Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000313similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000314 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
315 :let shortlist = mylist[2:2] " List with one item: [3]
316 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000317
Bram Moolenaar6601b622021-01-13 21:47:15 +0100318Notice that the last index is inclusive. If you prefer using an exclusive
319index use the |slice()| method.
320
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000321If the first index is beyond the last item of the List or the second item is
322before the first item, the result is an empty list. There is no error
323message.
324
325If the second index is equal to or greater than the length of the list the
326length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000327 :let mylist = [0, 1, 2, 3]
328 :echo mylist[2:8] " result: [2, 3]
329
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000330NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar58b85342016-08-14 19:54:54 +0200331using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000332mylist[s : e].
333
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000334
Bram Moolenaar13065c42005-01-08 16:08:21 +0000335List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000336 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000337When variable "aa" is a list and you assign it to another variable "bb", both
338variables refer to the same list. Thus changing the list "aa" will also
339change "bb": >
340 :let aa = [1, 2, 3]
341 :let bb = aa
342 :call add(aa, 4)
343 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000344< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000345
346Making a copy of a list is done with the |copy()| function. Using [:] also
347works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000348a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000349 :let aa = [[1, 'a'], 2, 3]
350 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000351 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000352 :let aa[0][1] = 'aaa'
353 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000354< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000355 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000356< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000357
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000358To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000359copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000360
361The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000362List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000363the same value. >
364 :let alist = [1, 2, 3]
365 :let blist = [1, 2, 3]
366 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000367< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000368 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000369< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000370
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000371Note about comparing lists: Two lists are considered equal if they have the
372same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000373exception: When comparing a number with a string they are considered
374different. There is no automatic type conversion, as with using "==" on
375variables. Example: >
376 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000377< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000378 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000379< 0
380
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000381Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000382can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000383
384 :let a = 5
385 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000386 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000387< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000388 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000389< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000390
Bram Moolenaar13065c42005-01-08 16:08:21 +0000391
392List unpack ~
393
394To unpack the items in a list to individual variables, put the variables in
395square brackets, like list items: >
396 :let [var1, var2] = mylist
397
398When the number of variables does not match the number of items in the list
399this produces an error. To handle any extra items from the list append ";"
400and a variable name: >
401 :let [var1, var2; rest] = mylist
402
403This works like: >
404 :let var1 = mylist[0]
405 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000406 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000407
408Except that there is no error if there are only two items. "rest" will be an
409empty list then.
410
411
412List modification ~
413 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000414To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000415 :let list[4] = "four"
416 :let listlist[0][3] = item
417
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000418To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000419modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000420 :let list[3:5] = [3, 4, 5]
421
Bram Moolenaar13065c42005-01-08 16:08:21 +0000422Adding and removing items from a list is done with functions. Here are a few
423examples: >
424 :call insert(list, 'a') " prepend item 'a'
425 :call insert(list, 'a', 3) " insert item 'a' before list[3]
426 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000427 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000428 :call extend(list, [1, 2]) " extend the list with two more items
429 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000430 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000431 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000432 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000433 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000434
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000435Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000436 :call sort(list) " sort a list alphabetically
437 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100438 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000439
Bram Moolenaar13065c42005-01-08 16:08:21 +0000440
441For loop ~
442
Bram Moolenaar74e54fc2021-03-26 20:41:29 +0100443The |:for| loop executes commands for each item in a List, String or Blob.
444A variable is set to each item in sequence. Example with a List: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000445 :for item in mylist
446 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000447 :endfor
448
449This works like: >
450 :let index = 0
451 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000452 : let item = mylist[index]
453 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000454 : let index = index + 1
455 :endwhile
456
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000457If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000458function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000459
Bram Moolenaar58b85342016-08-14 19:54:54 +0200460Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar74e54fc2021-03-26 20:41:29 +0100461requires the argument to be a List of Lists. >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000462 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
463 : call Doit(lnum, col)
464 :endfor
465
466This works like a |:let| command is done for each list item. Again, the types
467must remain the same to avoid an error.
468
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000469It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000470 :for [i, j; rest] in listlist
471 : call Doit(i, j)
472 : if !empty(rest)
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000473 : echo "remainder: " .. string(rest)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000474 : endif
475 :endfor
476
Bram Moolenaar74e54fc2021-03-26 20:41:29 +0100477For a Blob one byte at a time is used.
478
479For a String one character, including any composing characters, is used as a
480String. Example: >
481 for c in text
482 echo 'This character is ' .. c
483 endfor
484
Bram Moolenaar13065c42005-01-08 16:08:21 +0000485
486List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000487 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000488Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000489 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000490 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000491 :let l = len(list) " number of items in list
492 :let big = max(list) " maximum value in list
493 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000494 :let xs = count(list, 'x') " count nr of times 'x' appears in list
495 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000496 :let lines = getline(1, 10) " get ten text lines from buffer
497 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000498 :let list = split("a b c") " create list from items in a string
499 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000500 :let s = string(list) " String representation of list
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000501 :call map(list, '">> " .. v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000502
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000503Don't forget that a combination of features can make things simple. For
504example, to add up all the numbers in a list: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000505 :exe 'let sum = ' .. join(nrlist, '+')
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000506
Bram Moolenaar13065c42005-01-08 16:08:21 +0000507
Bram Moolenaard8b02732005-01-14 21:48:43 +00005081.4 Dictionaries ~
Bram Moolenaard8968242019-01-15 22:51:57 +0100509 *dict* *Dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000510A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000511entry can be located with the key. The entries are stored without a specific
512ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000513
514
515Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000516 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000517A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000518braces. Each entry has a key and a value, separated by a colon. Each key can
519only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000520 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
521 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000522< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000523A key is always a String. You can use a Number, it will be converted to a
524String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar58b85342016-08-14 19:54:54 +0200525entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaard5abb4c2019-07-13 22:46:10 +0200526Number will be converted to the String '4'. The empty string can also be used
527as a key.
Bram Moolenaar5da36052021-12-27 15:39:57 +0000528
529In |Vim9| script literaly keys can be used if the key consists of alphanumeric
530characters, underscore and dash, see |vim9-literal-dict|.
Bram Moolenaar56c860c2019-08-17 20:09:31 +0200531 *literal-Dict* *#{}*
Bram Moolenaar5da36052021-12-27 15:39:57 +0000532To avoid having to put quotes around every key the #{} form can be used in
533legacy script. This does require the key to consist only of ASCII letters,
534digits, '-' and '_'. Example: >
Bram Moolenaar10455d42019-11-21 15:36:18 +0100535 :let mydict = #{zero: 0, one_key: 1, two-key: 2, 333: 3}
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200536Note that 333 here is the string "333". Empty keys are not possible with #{}.
Bram Moolenaar5da36052021-12-27 15:39:57 +0000537In |Vim9| script the #{} form cannot be used.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000538
Bram Moolenaar58b85342016-08-14 19:54:54 +0200539A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000540nested Dictionary: >
541 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
542
543An extra comma after the last entry is ignored.
544
545
546Accessing entries ~
547
548The normal way to access an entry is by putting the key in square brackets: >
549 :let val = mydict["one"]
550 :let mydict["four"] = 4
551
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000552You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000553
554For keys that consist entirely of letters, digits and underscore the following
555form can be used |expr-entry|: >
556 :let val = mydict.one
557 :let mydict.four = 4
558
559Since an entry can be any type, also a List and a Dictionary, the indexing and
560key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000561 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000562
563
564Dictionary to List conversion ~
565
Bram Moolenaar58b85342016-08-14 19:54:54 +0200566You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000567turn the Dictionary into a List and pass it to |:for|.
568
569Most often you want to loop over the keys, using the |keys()| function: >
570 :for key in keys(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000571 : echo key .. ': ' .. mydict[key]
Bram Moolenaard8b02732005-01-14 21:48:43 +0000572 :endfor
573
574The List of keys is unsorted. You may want to sort them first: >
575 :for key in sort(keys(mydict))
576
577To loop over the values use the |values()| function: >
578 :for v in values(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000579 : echo "value: " .. v
Bram Moolenaard8b02732005-01-14 21:48:43 +0000580 :endfor
581
582If you want both the key and the value use the |items()| function. It returns
Bram Moolenaard47d5222018-12-09 20:43:55 +0100583a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000584 :for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000585 : echo key .. ': ' .. value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000586 :endfor
587
588
589Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000590 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000591Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
592Dictionary. Otherwise, assignment results in referring to the same
593Dictionary: >
594 :let onedict = {'a': 1, 'b': 2}
595 :let adict = onedict
596 :let adict['a'] = 11
597 :echo onedict['a']
598 11
599
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000600Two Dictionaries compare equal if all the key-value pairs compare equal. For
601more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000602
603
604Dictionary modification ~
605 *dict-modification*
606To change an already existing entry of a Dictionary, or to add a new entry,
607use |:let| this way: >
608 :let dict[4] = "four"
609 :let dict['one'] = item
610
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000611Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
612Three ways to remove the entry with key "aaa" from dict: >
613 :let i = remove(dict, 'aaa')
614 :unlet dict.aaa
615 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000616
617Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000618 :call extend(adict, bdict)
619This extends adict with all entries from bdict. Duplicate keys cause entries
620in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000621Note that the order of entries in a Dictionary is irrelevant, thus don't
622expect ":echo adict" to show the items from bdict after the older entries in
623adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000624
625Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000626 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000627This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar388a5d42020-05-26 21:20:45 +0200628This can also be used to remove all entries: >
629 call filter(dict, 0)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000630
631
632Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100633 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000634When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar58b85342016-08-14 19:54:54 +0200635special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000636 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000637 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000638 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000639 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
640 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000641
642This is like a method in object oriented programming. The entry in the
643Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
644the function was invoked from.
645
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000646It is also possible to add a function without the "dict" attribute as a
647Funcref to a Dictionary, but the "self" variable is not available then.
648
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000649 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000650To avoid the extra name for the function it can be defined and directly
651assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000652 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200653 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000654 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000655 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000656 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000657
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000658The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar58b85342016-08-14 19:54:54 +0200659that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000660|Funcref|. It will automatically be deleted when there is no |Funcref|
661remaining that refers to it.
662
663It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000664
Bram Moolenaar1affd722010-08-04 17:49:30 +0200665If you get an error for a numbered function, you can find out what it is with
666a trick. Assuming the function is 42, the command is: >
Bram Moolenaar34cc7d82021-09-21 20:09:51 +0200667 :function g:42
Bram Moolenaar1affd722010-08-04 17:49:30 +0200668
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000669
670Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000671 *E715*
672Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000673 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
674 :if empty(dict) " TRUE if dict is empty
675 :let l = len(dict) " number of items in dict
676 :let big = max(dict) " maximum value in dict
677 :let small = min(dict) " minimum value in dict
678 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
679 :let s = string(dict) " String representation of dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000680 :call map(dict, '">> " .. v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000681
682
Bram Moolenaard8968242019-01-15 22:51:57 +01006831.5 Blobs ~
684 *blob* *Blob* *Blobs* *E978*
Bram Moolenaaraff74912019-03-30 18:11:49 +0100685A Blob is a binary object. It can be used to read an image from a file and
686send it over a channel, for example.
687
688A Blob mostly behaves like a |List| of numbers, where each number has the
689value of an 8-bit byte, from 0 to 255.
Bram Moolenaard8968242019-01-15 22:51:57 +0100690
691
692Blob creation ~
693
694A Blob can be created with a |blob-literal|: >
695 :let b = 0zFF00ED015DAF
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +0100696Dots can be inserted between bytes (pair of hex characters) for readability,
697they don't change the value: >
698 :let b = 0zFF00.ED01.5DAF
Bram Moolenaard8968242019-01-15 22:51:57 +0100699
700A blob can be read from a file with |readfile()| passing the {type} argument
701set to "B", for example: >
702 :let b = readfile('image.png', 'B')
703
704A blob can be read from a channel with the |ch_readblob()| function.
705
706
707Blob index ~
708 *blob-index* *E979*
709A byte in the Blob can be accessed by putting the index in square brackets
710after the Blob. Indexes are zero-based, thus the first byte has index zero. >
711 :let myblob = 0z00112233
712 :let byte = myblob[0] " get the first byte: 0x00
713 :let byte = myblob[2] " get the third byte: 0x22
714
715A negative index is counted from the end. Index -1 refers to the last byte in
716the Blob, -2 to the last but one byte, etc. >
717 :let last = myblob[-1] " get the last byte: 0x33
718
719To avoid an error for an invalid index use the |get()| function. When an item
720is not available it returns -1 or the default value you specify: >
721 :echo get(myblob, idx)
722 :echo get(myblob, idx, 999)
723
724
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100725Blob iteration ~
726
727The |:for| loop executes commands for each byte of a Blob. The loop variable is
728set to each byte in the Blob. Example: >
729 :for byte in 0z112233
730 : call Doit(byte)
731 :endfor
732This calls Doit() with 0x11, 0x22 and 0x33.
733
734
Bram Moolenaard8968242019-01-15 22:51:57 +0100735Blob concatenation ~
736
737Two blobs can be concatenated with the "+" operator: >
738 :let longblob = myblob + 0z4455
739 :let myblob += 0z6677
740
741To change a blob in-place see |blob-modification| below.
742
743
744Part of a blob ~
745
746A part of the Blob can be obtained by specifying the first and last index,
747separated by a colon in square brackets: >
748 :let myblob = 0z00112233
Bram Moolenaard09091d2019-01-17 16:07:22 +0100749 :let shortblob = myblob[1:2] " get 0z1122
Bram Moolenaard8968242019-01-15 22:51:57 +0100750 :let shortblob = myblob[2:-1] " get 0z2233
751
752Omitting the first index is similar to zero. Omitting the last index is
753similar to -1. >
754 :let endblob = myblob[2:] " from item 2 to the end: 0z2233
755 :let shortblob = myblob[2:2] " Blob with one byte: 0z22
756 :let otherblob = myblob[:] " make a copy of the Blob
757
Bram Moolenaard09091d2019-01-17 16:07:22 +0100758If the first index is beyond the last byte of the Blob or the second index is
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +0100759before the first index, the result is an empty Blob. There is no error
Bram Moolenaard8968242019-01-15 22:51:57 +0100760message.
761
762If the second index is equal to or greater than the length of the list the
763length minus one is used: >
764 :echo myblob[2:8] " result: 0z2233
765
766
767Blob modification ~
Bram Moolenaara2baa732022-02-04 16:09:54 +0000768 *blob-modification* *E1182* *E1184*
Bram Moolenaard8968242019-01-15 22:51:57 +0100769To change a specific byte of a blob use |:let| this way: >
770 :let blob[4] = 0x44
771
772When the index is just one beyond the end of the Blob, it is appended. Any
773higher index is an error.
774
775To change a sequence of bytes the [:] notation can be used: >
776 let blob[1:3] = 0z445566
Bram Moolenaard09091d2019-01-17 16:07:22 +0100777The length of the replaced bytes must be exactly the same as the value
Bram Moolenaard8968242019-01-15 22:51:57 +0100778provided. *E972*
779
780To change part of a blob you can specify the first and last byte to be
Bram Moolenaard09091d2019-01-17 16:07:22 +0100781modified. The value must have the same number of bytes in the range: >
782 :let blob[3:5] = 0z334455
Bram Moolenaard8968242019-01-15 22:51:57 +0100783
784You can also use the functions |add()|, |remove()| and |insert()|.
785
786
787Blob identity ~
788
789Blobs can be compared for equality: >
790 if blob == 0z001122
791And for equal identity: >
792 if blob is otherblob
793< *blob-identity* *E977*
794When variable "aa" is a Blob and you assign it to another variable "bb", both
795variables refer to the same Blob. Then the "is" operator returns true.
796
797When making a copy using [:] or |copy()| the values are the same, but the
798identity is different: >
799 :let blob = 0z112233
800 :let blob2 = blob
801 :echo blob == blob2
802< 1 >
803 :echo blob is blob2
804< 1 >
805 :let blob3 = blob[:]
806 :echo blob == blob3
807< 1 >
808 :echo blob is blob3
809< 0
810
Bram Moolenaard09091d2019-01-17 16:07:22 +0100811Making a copy of a Blob is done with the |copy()| function. Using [:] also
Bram Moolenaard8968242019-01-15 22:51:57 +0100812works, as explained above.
813
814
8151.6 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000816 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000817If you need to know the type of a variable or expression, use the |type()|
818function.
819
820When the '!' flag is included in the 'viminfo' option, global variables that
821start with an uppercase letter, and don't contain a lowercase letter, are
822stored in the viminfo file |viminfo-file|.
823
824When the 'sessionoptions' option contains "global", global variables that
825start with an uppercase letter and contain at least one lowercase letter are
826stored in the session file |session-file|.
827
828variable name can be stored where ~
829my_var_6 not
830My_Var_6 session file
831MY_VAR_6 viminfo file
832
833
Bram Moolenaar5da36052021-12-27 15:39:57 +0000834In legacy script it is possible to form a variable name with curly braces, see
Bram Moolenaar071d4272004-06-13 20:20:40 +0000835|curly-braces-names|.
836
837==============================================================================
8382. Expression syntax *expression-syntax*
Bram Moolenaarf10911e2022-01-29 22:20:48 +0000839 *E1143*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000840Expression syntax summary, from least to most significant:
841
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200842|expr1| expr2
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200843 expr2 ? expr1 : expr1 if-then-else
Bram Moolenaar071d4272004-06-13 20:20:40 +0000844
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200845|expr2| expr3
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200846 expr3 || expr3 ... logical OR
Bram Moolenaar071d4272004-06-13 20:20:40 +0000847
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200848|expr3| expr4
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200849 expr4 && expr4 ... logical AND
Bram Moolenaar071d4272004-06-13 20:20:40 +0000850
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200851|expr4| expr5
852 expr5 == expr5 equal
Bram Moolenaar071d4272004-06-13 20:20:40 +0000853 expr5 != expr5 not equal
854 expr5 > expr5 greater than
855 expr5 >= expr5 greater than or equal
856 expr5 < expr5 smaller than
857 expr5 <= expr5 smaller than or equal
858 expr5 =~ expr5 regexp matches
859 expr5 !~ expr5 regexp doesn't match
860
861 expr5 ==? expr5 equal, ignoring case
862 expr5 ==# expr5 equal, match case
863 etc. As above, append ? for ignoring case, # for
864 matching case
865
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100866 expr5 is expr5 same |List|, |Dictionary| or |Blob| instance
867 expr5 isnot expr5 different |List|, |Dictionary| or |Blob|
868 instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000869
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200870|expr5| expr6
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200871 expr6 + expr6 ... number addition, list or blob concatenation
872 expr6 - expr6 ... number subtraction
873 expr6 . expr6 ... string concatenation
874 expr6 .. expr6 ... string concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000875
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200876|expr6| expr7
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200877 expr7 * expr7 ... number multiplication
878 expr7 / expr7 ... number division
879 expr7 % expr7 ... number modulo
Bram Moolenaar071d4272004-06-13 20:20:40 +0000880
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200881|expr7| expr8
Bram Moolenaar5da36052021-12-27 15:39:57 +0000882 <type>expr8 type check and conversion (|Vim9| only)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000883
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200884|expr8| expr9
Bram Moolenaar5da36052021-12-27 15:39:57 +0000885 ! expr8 logical NOT
886 - expr8 unary minus
887 + expr8 unary plus
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000888
Bram Moolenaar5da36052021-12-27 15:39:57 +0000889|expr9| expr10
890 expr9[expr1] byte of a String or item of a |List|
891 expr9[expr1 : expr1] substring of a String or sublist of a |List|
892 expr9.name entry in a |Dictionary|
893 expr9(expr1, ...) function call with |Funcref| variable
894 expr9->name(expr1, ...) |method| call
895
896|expr10| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000897 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000898 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000899 [expr1, ...] |List|
900 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar5da36052021-12-27 15:39:57 +0000901 #{key: expr1, ...} legacy |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000902 &option option value
903 (expr1) nested expression
904 variable internal variable
905 va{ria}ble internal variable with curly braces
906 $VAR environment variable
907 @r contents of register 'r'
908 function(expr1, ...) function call
909 func{ti}on(expr1, ...) function call with curly braces
Bram Moolenaar5da36052021-12-27 15:39:57 +0000910 {args -> expr1} legacy lambda expression
911 (args) => expr1 Vim9 lambda expression
Bram Moolenaar071d4272004-06-13 20:20:40 +0000912
913
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200914"..." indicates that the operations in this level can be concatenated.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000915Example: >
916 &nu || &list && &shell == "csh"
917
918All expressions within one level are parsed from left to right.
919
Bram Moolenaarf10911e2022-01-29 22:20:48 +0000920Expression nesting is limited to 1000 levels deep (300 when build with MSVC)
921to avoid running out of stack and crashing. *E1169*
922
Bram Moolenaar071d4272004-06-13 20:20:40 +0000923
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000924expr1 *expr1* *ternary* *falsy-operator* *??* *E109*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000925-----
926
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000927The ternary operator: expr2 ? expr1 : expr1
Bram Moolenaar92f26c22020-10-03 20:17:30 +0200928The falsy operator: expr2 ?? expr1
929
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000930Ternary operator ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000931
Bram Moolenaar5da36052021-12-27 15:39:57 +0000932In legacy script the expression before the '?' is evaluated to a number. If
933it evaluates to |TRUE|, the result is the value of the expression between the
934'?' and ':', otherwise the result is the value of the expression after the
935':'.
936
937In |Vim9| script the first expression must evaluate to a boolean, see
938|vim9-boolean|.
939
Bram Moolenaar071d4272004-06-13 20:20:40 +0000940Example: >
941 :echo lnum == 1 ? "top" : lnum
942
943Since the first expression is an "expr2", it cannot contain another ?:. The
944other two expressions can, thus allow for recursive use of ?:.
945Example: >
946 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
947
948To keep this readable, using |line-continuation| is suggested: >
949 :echo lnum == 1
950 :\ ? "top"
951 :\ : lnum == 1000
952 :\ ? "last"
953 :\ : lnum
954
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000955You should always put a space before the ':', otherwise it can be mistaken for
956use in a variable such as "a:1".
957
Bram Moolenaar92f26c22020-10-03 20:17:30 +0200958Falsy operator ~
959
960This is also known as the "null coalescing operator", but that's too
961complicated, thus we just call it the falsy operator.
962
963The expression before the '??' is evaluated. If it evaluates to
964|truthy|, this is used as the result. Otherwise the expression after the '??'
965is evaluated and used as the result. This is most useful to have a default
966value for an expression that may result in zero or empty: >
967 echo theList ?? 'list is empty'
968 echo GetName() ?? 'unknown'
969
970These are similar, but not equal: >
971 expr2 ?? expr1
972 expr2 ? expr2 : expr1
Bram Moolenaar5da36052021-12-27 15:39:57 +0000973In the second line "expr2" is evaluated twice. And in |Vim9| script the type
974of expr2 before "?" must be a boolean.
Bram Moolenaar92f26c22020-10-03 20:17:30 +0200975
Bram Moolenaar071d4272004-06-13 20:20:40 +0000976
977expr2 and expr3 *expr2* *expr3*
978---------------
979
Bram Moolenaar04186092016-08-29 21:55:35 +0200980expr3 || expr3 .. logical OR *expr-barbar*
981expr4 && expr4 .. logical AND *expr-&&*
982
Bram Moolenaar5da36052021-12-27 15:39:57 +0000983The "||" and "&&" operators take one argument on each side.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000984
Bram Moolenaar5da36052021-12-27 15:39:57 +0000985In legacy script the arguments are (converted to) Numbers.
986
987In |Vim9| script the values must be boolean, see |vim9-boolean|. Use "!!" to
988convert any type to a boolean.
989
990The result is:
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200991 input output ~
992n1 n2 n1 || n2 n1 && n2 ~
993|FALSE| |FALSE| |FALSE| |FALSE|
994|FALSE| |TRUE| |TRUE| |FALSE|
995|TRUE| |FALSE| |TRUE| |FALSE|
996|TRUE| |TRUE| |TRUE| |TRUE|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000997
998The operators can be concatenated, for example: >
999
1000 &nu || &list && &shell == "csh"
1001
1002Note that "&&" takes precedence over "||", so this has the meaning of: >
1003
1004 &nu || (&list && &shell == "csh")
1005
1006Once the result is known, the expression "short-circuits", that is, further
1007arguments are not evaluated. This is like what happens in C. For example: >
1008
1009 let a = 1
1010 echo a || b
1011
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001012This is valid even if there is no variable called "b" because "a" is |TRUE|,
1013so the result must be |TRUE|. Similarly below: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001014
1015 echo exists("b") && b == "yes"
1016
1017This is valid whether "b" has been defined or not. The second clause will
1018only be evaluated if "b" has been defined.
1019
1020
Bram Moolenaara2baa732022-02-04 16:09:54 +00001021expr4 *expr4* *E1153*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001022-----
1023
1024expr5 {cmp} expr5
1025
Bram Moolenaar5da36052021-12-27 15:39:57 +00001026Compare two expr5 expressions. In legacy script the result is a 0 if it
1027evaluates to false, or 1 if it evaluates to true. In |Vim9| script the result
1028is |true| or |false|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001029
Bram Moolenaar446cb832008-06-24 21:56:24 +00001030 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001031 *expr-<* *expr-<=* *expr-=~* *expr-!~*
1032 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
1033 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
1034 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
1035 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001036 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001037 *expr-is?* *expr-isnot?* *E1072*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001038 use 'ignorecase' match case ignore case ~
1039equal == ==# ==?
1040not equal != !=# !=?
1041greater than > ># >?
1042greater than or equal >= >=# >=?
1043smaller than < <# <?
1044smaller than or equal <= <=# <=?
1045regexp matches =~ =~# =~?
1046regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +02001047same instance is is# is?
1048different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +00001049
1050Examples:
1051"abc" ==# "Abc" evaluates to 0
1052"abc" ==? "Abc" evaluates to 1
1053"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
Bram Moolenaar5da36052021-12-27 15:39:57 +00001054NOTE: In |Vim9| script 'ignorecase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001055
Bram Moolenaar13065c42005-01-08 16:08:21 +00001056 *E691* *E692*
Bram Moolenaar01164a62017-11-02 22:58:42 +01001057A |List| can only be compared with a |List| and only "equal", "not equal",
1058"is" and "isnot" can be used. This compares the values of the list,
1059recursively. Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001060
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00001061 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001062A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
Bram Moolenaar01164a62017-11-02 22:58:42 +01001063equal", "is" and "isnot" can be used. This compares the key/values of the
1064|Dictionary| recursively. Ignoring case means case is ignored when comparing
1065item values.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00001066
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02001067 *E694*
Bram Moolenaare18dbe82016-07-02 21:42:23 +02001068A |Funcref| can only be compared with a |Funcref| and only "equal", "not
1069equal", "is" and "isnot" can be used. Case is never ignored. Whether
1070arguments or a Dictionary are bound (with a partial) matters. The
1071Dictionaries must also be equal (or the same, in case of "is") and the
1072arguments must be equal (or the same).
1073
1074To compare Funcrefs to see if they refer to the same function, ignoring bound
1075Dictionary and arguments, use |get()| to get the function name: >
1076 if get(Part1, 'name') == get(Part2, 'name')
1077 " Part1 and Part2 refer to the same function
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001078< *E1037*
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001079Using "is" or "isnot" with a |List|, |Dictionary| or |Blob| checks whether
1080the expressions are referring to the same |List|, |Dictionary| or |Blob|
1081instance. A copy of a |List| is different from the original |List|. When
1082using "is" without a |List|, |Dictionary| or |Blob|, it is equivalent to
1083using "equal", using "isnot" equivalent to using "not equal". Except that
1084a different type means the values are different: >
Bram Moolenaar86edef62016-03-13 18:07:30 +01001085 echo 4 == '4'
1086 1
1087 echo 4 is '4'
1088 0
1089 echo 0 is []
1090 0
1091"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001092
Bram Moolenaar5da36052021-12-27 15:39:57 +00001093In legacy script, when comparing a String with a Number, the String is
1094converted to a Number, and the comparison is done on Numbers. This means
1095that: >
Bram Moolenaar86edef62016-03-13 18:07:30 +01001096 echo 0 == 'x'
1097 1
1098because 'x' converted to a Number is zero. However: >
1099 echo [0] == ['x']
1100 0
1101Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001102
Bram Moolenaar5da36052021-12-27 15:39:57 +00001103In |Vim9| script the types must match.
1104
Bram Moolenaar071d4272004-06-13 20:20:40 +00001105When comparing two Strings, this is done with strcmp() or stricmp(). This
1106results in the mathematical difference (comparing byte values), not
1107necessarily the alphabetical difference in the local language.
1108
Bram Moolenaar446cb832008-06-24 21:56:24 +00001109When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001110'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001111
1112When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001113'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
1114
1115'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001116
1117The "=~" and "!~" operators match the lefthand argument with the righthand
1118argument, which is used as a pattern. See |pattern| for what a pattern is.
1119This matching is always done like 'magic' was set and 'cpoptions' is empty, no
1120matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
1121portable. To avoid backslashes in the regexp pattern to be doubled, use a
1122single-quote string, see |literal-string|.
1123Since a string is considered to be a single line, a multi-line pattern
1124(containing \n, backslash-n) will not match. However, a literal NL character
1125can be matched like an ordinary character. Examples:
1126 "foo\nbar" =~ "\n" evaluates to 1
1127 "foo\nbar" =~ "\\n" evaluates to 0
1128
1129
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001130expr5 and expr6 *expr5* *expr6* *E1036* *E1051*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001131---------------
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001132expr6 + expr6 Number addition, |List| or |Blob| concatenation *expr-+*
1133expr6 - expr6 Number subtraction *expr--*
1134expr6 . expr6 String concatenation *expr-.*
1135expr6 .. expr6 String concatenation *expr-..*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001136
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001137For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001138result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001139
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001140For String concatenation ".." is preferred, since "." is ambiguous, it is also
1141used for |Dict| member access and floating point numbers.
Bram Moolenaar5da36052021-12-27 15:39:57 +00001142In |Vim9| script and when |vimscript-version| is 2 or higher, using "." is not
1143allowed.
1144
1145In |Vim9| script the arguments of ".." are converted to String for simple
1146types: Number, Float, Special and Bool. For other types |string()| should be
1147used.
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001148
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001149expr7 * expr7 Number multiplication *expr-star*
1150expr7 / expr7 Number division *expr-/*
1151expr7 % expr7 Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001152
Bram Moolenaar5da36052021-12-27 15:39:57 +00001153In legacy script, for all operators except "." and "..", Strings are converted
1154to Numbers.
1155
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001156For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001157
Bram Moolenaar5da36052021-12-27 15:39:57 +00001158Note the difference between "+" and ".." in legacy script:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001159 "123" + "456" = 579
Bram Moolenaar5da36052021-12-27 15:39:57 +00001160 "123" .. "456" = "123456"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001161
Bram Moolenaar5da36052021-12-27 15:39:57 +00001162Since '..' has the same precedence as '+' and '-', you need to read: >
1163 1 .. 90 + 90.0
Bram Moolenaar446cb832008-06-24 21:56:24 +00001164As: >
Bram Moolenaar5da36052021-12-27 15:39:57 +00001165 (1 .. 90) + 90.0
1166That works in legacy script, since the String "190" is automatically converted
1167to the Number 190, which can be added to the Float 90.0. However: >
1168 1 .. 90 * 90.0
Bram Moolenaar446cb832008-06-24 21:56:24 +00001169Should be read as: >
Bram Moolenaar5da36052021-12-27 15:39:57 +00001170 1 .. (90 * 90.0)
1171Since '..' has lower precedence than '*'. This does NOT work, since this
Bram Moolenaar446cb832008-06-24 21:56:24 +00001172attempts to concatenate a Float and a String.
1173
1174When dividing a Number by zero the result depends on the value:
1175 0 / 0 = -0x80000000 (like NaN for Float)
1176 >0 / 0 = 0x7fffffff (like positive infinity)
1177 <0 / 0 = -0x7fffffff (like negative infinity)
1178 (before Vim 7.2 it was always 0x7fffffff)
Bram Moolenaara2baa732022-02-04 16:09:54 +00001179In |Vim9| script dividing a number by zero is an error. *E1154*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001180
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02001181When 64-bit Number support is enabled:
1182 0 / 0 = -0x8000000000000000 (like NaN for Float)
1183 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
1184 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
1185
Bram Moolenaar071d4272004-06-13 20:20:40 +00001186When the righthand side of '%' is zero, the result is 0.
1187
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001188None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001189
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001190".", ".." and "%" do not work for Float. *E804* *E1035*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001191
Bram Moolenaar071d4272004-06-13 20:20:40 +00001192
1193expr7 *expr7*
1194-----
Bram Moolenaar5da36052021-12-27 15:39:57 +00001195<type>expr8
1196
1197This is only available in |Vim9| script, see |type-casting|.
1198
1199
1200expr8 *expr8*
1201-----
1202! expr8 logical NOT *expr-!*
1203- expr8 unary minus *expr-unary--*
1204+ expr8 unary plus *expr-unary-+*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001205
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001206For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001207For '-' the sign of the number is changed.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001208For '+' the number is unchanged. Note: "++" has no effect.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001209
Bram Moolenaar5da36052021-12-27 15:39:57 +00001210In legacy script a String will be converted to a Number first. Note that if
1211the string does not start with a digit you likely don't get what you expect.
1212
1213In |Vim9| script an error is given when "-" or "+" is used and the type is not
1214a number.
1215
1216In |Vim9| script "!" can be used for any type and the result is always a
1217boolean. Use "!!" to convert any type to a boolean, according to whether the
1218value is |falsy|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001219
Bram Moolenaar58b85342016-08-14 19:54:54 +02001220These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001221 !-1 == 0
1222 !!8 == 1
1223 --9 == 9
1224
1225
Bram Moolenaar5da36052021-12-27 15:39:57 +00001226expr9 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001227-----
Bram Moolenaar5da36052021-12-27 15:39:57 +00001228This expression is either |expr10| or a sequence of the alternatives below,
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001229in any order. E.g., these are all possible:
Bram Moolenaar5da36052021-12-27 15:39:57 +00001230 expr9[expr1].name
1231 expr9.name[expr1]
1232 expr9(expr1, ...)[expr1].name
1233 expr9->(expr1, ...)[expr1]
Bram Moolenaarac92e252019-08-03 21:58:38 +02001234Evaluation is always from left to right.
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001235
Bram Moolenaar5da36052021-12-27 15:39:57 +00001236expr9[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001237 *E909* *subscript* *E1062*
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001238In legacy Vim script:
Bram Moolenaar5da36052021-12-27 15:39:57 +00001239If expr9 is a Number or String this results in a String that contains the
1240expr1'th single byte from expr9. expr9 is used as a String (a number is
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001241automatically converted to a String), expr1 as a Number. This doesn't
Bram Moolenaar207f0092020-08-30 17:20:20 +02001242recognize multibyte encodings, see `byteidx()` for an alternative, or use
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001243`split()` to turn the string into a list of characters. Example, to get the
1244byte under the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00001245 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001246
Bram Moolenaara2baa732022-02-04 16:09:54 +00001247In |Vim9| script: *E1147* *E1148*
Bram Moolenaar5da36052021-12-27 15:39:57 +00001248If expr9 is a String this results in a String that contains the expr1'th
1249single character (including any composing characters) from expr9. To use byte
Bram Moolenaar02b4d9b2021-03-14 19:46:45 +01001250indexes use |strpart()|.
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001251
1252Index zero gives the first byte or character. Careful: text column numbers
1253start with one!
1254
Bram Moolenaar071d4272004-06-13 20:20:40 +00001255If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +01001256String. A negative index always results in an empty string (reason: backward
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001257compatibility). Use [-1:] to get the last byte or character.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001258In Vim9 script a negative index is used like with a list: count from the end.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001259
Bram Moolenaar5da36052021-12-27 15:39:57 +00001260If expr9 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001261for possible index values. If the index is out of range this results in an
Bram Moolenaar58b85342016-08-14 19:54:54 +02001262error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001263 :let item = mylist[-1] " get last item
1264
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001265Generally, if a |List| index is equal to or higher than the length of the
1266|List|, or more negative than the length of the |List|, this results in an
1267error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001268
Bram Moolenaard8b02732005-01-14 21:48:43 +00001269
Bram Moolenaar5da36052021-12-27 15:39:57 +00001270expr9[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001271
Bram Moolenaar5da36052021-12-27 15:39:57 +00001272If expr9 is a String this results in the substring with the bytes or
1273characters from expr1a to and including expr1b. expr9 is used as a String,
Bram Moolenaar207f0092020-08-30 17:20:20 +02001274expr1a and expr1b are used as a Number.
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001275
1276In legacy Vim script the indexes are byte indexes. This doesn't recognize
Bram Moolenaar5da36052021-12-27 15:39:57 +00001277multibyte encodings, see |byteidx()| for computing the indexes. If expr9 is
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001278a Number it is first converted to a String.
1279
Bram Moolenaar02b4d9b2021-03-14 19:46:45 +01001280In Vim9 script the indexes are character indexes and include composing
1281characters. To use byte indexes use |strpart()|. To use character indexes
1282without including composing characters use |strcharpart()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001283
Bram Moolenaar6601b622021-01-13 21:47:15 +01001284The item at index expr1b is included, it is inclusive. For an exclusive index
1285use the |slice()| function.
1286
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001287If expr1a is omitted zero is used. If expr1b is omitted the length of the
1288string minus one is used.
1289
1290A negative number can be used to measure from the end of the string. -1 is
1291the last character, -2 the last but one, etc.
1292
1293If an index goes out of range for the string characters are omitted. If
1294expr1b is smaller than expr1a the result is an empty string.
1295
1296Examples: >
1297 :let c = name[-1:] " last byte of a string
Bram Moolenaar207f0092020-08-30 17:20:20 +02001298 :let c = name[0:-1] " the whole string
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001299 :let c = name[-2:-2] " last but one byte of a string
1300 :let s = line(".")[4:] " from the fifth byte to the end
1301 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001302<
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001303 *slice*
Bram Moolenaar5da36052021-12-27 15:39:57 +00001304If expr9 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar58b85342016-08-14 19:54:54 +02001305the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001306just above. Also see |sublist| below. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001307 :let l = mylist[:3] " first four items
1308 :let l = mylist[4:4] " List with one item
1309 :let l = mylist[:] " shallow copy of a List
1310
Bram Moolenaar5da36052021-12-27 15:39:57 +00001311If expr9 is a |Blob| this results in a new |Blob| with the bytes in the
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001312indexes expr1a and expr1b, inclusive. Examples: >
1313 :let b = 0zDEADBEEF
1314 :let bs = b[1:2] " 0zADBE
Bram Moolenaard09091d2019-01-17 16:07:22 +01001315 :let bs = b[:] " copy of 0zDEADBEEF
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001316
Bram Moolenaar5da36052021-12-27 15:39:57 +00001317Using expr9[expr1] or expr9[expr1a : expr1b] on a |Funcref| results in an
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001318error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001319
Bram Moolenaarda440d22016-01-16 21:27:23 +01001320Watch out for confusion between a namespace and a variable followed by a colon
1321for a sublist: >
1322 mylist[n:] " uses variable n
1323 mylist[s:] " uses namespace s:, error!
1324
Bram Moolenaard8b02732005-01-14 21:48:43 +00001325
Bram Moolenaar5da36052021-12-27 15:39:57 +00001326expr9.name entry in a |Dictionary| *expr-entry*
Bram Moolenaara2baa732022-02-04 16:09:54 +00001327 *E1203* *E1229*
Bram Moolenaar5da36052021-12-27 15:39:57 +00001328If expr9 is a |Dictionary| and it is followed by a dot, then the following
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001329name will be used as a key in the |Dictionary|. This is just like:
Bram Moolenaar5da36052021-12-27 15:39:57 +00001330expr9[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +00001331
1332The name must consist of alphanumeric characters, just like a variable name,
1333but it may start with a number. Curly braces cannot be used.
1334
1335There must not be white space before or after the dot.
1336
1337Examples: >
1338 :let dict = {"one": 1, 2: "two"}
Bram Moolenaar68e65602019-05-26 21:33:31 +02001339 :echo dict.one " shows "1"
1340 :echo dict.2 " shows "two"
1341 :echo dict .2 " error because of space before the dot
Bram Moolenaard8b02732005-01-14 21:48:43 +00001342
1343Note that the dot is also used for String concatenation. To avoid confusion
1344always put spaces around the dot for String concatenation.
1345
1346
Bram Moolenaarf10911e2022-01-29 22:20:48 +00001347expr9(expr1, ...) |Funcref| function call *E1085*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001348
Bram Moolenaar5da36052021-12-27 15:39:57 +00001349When expr9 is a |Funcref| type variable, invoke the function it refers to.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001350
1351
Bram Moolenaar5da36052021-12-27 15:39:57 +00001352expr9->name([args]) method call *method* *->*
1353expr9->{lambda}([args])
Bram Moolenaara2baa732022-02-04 16:09:54 +00001354 *E260* *E276* *E1265*
Bram Moolenaar25e42232019-08-04 15:04:10 +02001355For methods that are also available as global functions this is the same as: >
Bram Moolenaar5da36052021-12-27 15:39:57 +00001356 name(expr9 [, args])
1357There can also be methods specifically for the type of "expr9".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001358
Bram Moolenaar51841322019-08-08 21:10:01 +02001359This allows for chaining, passing the value that one method returns to the
1360next method: >
Bram Moolenaar25e42232019-08-04 15:04:10 +02001361 mylist->filter(filterexpr)->map(mapexpr)->sort()->join()
1362<
Bram Moolenaar22a0c0c2019-08-09 23:25:08 +02001363Example of using a lambda: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02001364 GetPercentage()->{x -> x * 100}()->printf('%d%%')
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001365<
Bram Moolenaar5da36052021-12-27 15:39:57 +00001366When using -> the |expr8| operators will be applied first, thus: >
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02001367 -1.234->string()
1368Is equivalent to: >
1369 (-1.234)->string()
1370And NOT: >
1371 -(1.234->string())
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001372
1373What comes after "->" can be a name, a simple expression (not containing any
Bram Moolenaar944697a2022-02-20 19:48:20 +00001374parenthesis), or any expression in parentheses: >
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001375 base->name(args)
1376 base->some.name(args)
1377 base->alist[idx](args)
1378 base->(getFuncRef())(args)
1379Note that in the last call the base is passed to the function resulting from
1380"(getFuncRef())", inserted before "args".
1381
Bram Moolenaar51841322019-08-08 21:10:01 +02001382 *E274*
1383"->name(" must not contain white space. There can be white space before the
1384"->" and after the "(", thus you can split the lines like this: >
1385 mylist
1386 \ ->filter(filterexpr)
1387 \ ->map(mapexpr)
1388 \ ->sort()
1389 \ ->join()
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001390
1391When using the lambda form there must be no white space between the } and the
1392(.
1393
Bram Moolenaar25e42232019-08-04 15:04:10 +02001394
Bram Moolenaar5da36052021-12-27 15:39:57 +00001395 *expr10*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001396number
1397------
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001398number number constant *expr-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001399
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001400 *0x* *hex-number* *0o* *octal-number* *binary-number*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001401Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
Bram Moolenaarc17e66c2020-06-02 21:38:22 +02001402and Octal (starting with 0, 0o or 0O).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001403
Bram Moolenaar446cb832008-06-24 21:56:24 +00001404 *floating-point-format*
1405Floating point numbers can be written in two forms:
1406
1407 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +01001408 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001409
1410{N} and {M} are numbers. Both {N} and {M} must be present and can only
Bram Moolenaar6aa57292021-08-14 21:25:52 +02001411contain digits, except that in |Vim9| script in {N} single quotes between
1412digits are ignored.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001413[-+] means there is an optional plus or minus sign.
1414{exp} is the exponent, power of 10.
Bram Moolenaar58b85342016-08-14 19:54:54 +02001415Only a decimal point is accepted, not a comma. No matter what the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00001416locale is.
1417{only when compiled with the |+float| feature}
1418
1419Examples:
1420 123.456
1421 +0.0001
1422 55.0
1423 -0.123
1424 1.234e03
1425 1.0E-6
1426 -3.1416e+88
1427
1428These are INVALID:
1429 3. empty {M}
1430 1e40 missing .{M}
1431
1432Rationale:
1433Before floating point was introduced, the text "123.456" was interpreted as
1434the two numbers "123" and "456", both converted to a string and concatenated,
1435resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001436could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001437incompatibility was accepted in favor of being able to use the normal notation
1438for floating point numbers.
1439
Bram Moolenaard47d5222018-12-09 20:43:55 +01001440 *float-pi* *float-e*
1441A few useful values to copy&paste: >
1442 :let pi = 3.14159265359
1443 :let e = 2.71828182846
1444Or, if you don't want to write them in as floating-point literals, you can
1445also use functions, like the following: >
1446 :let pi = acos(-1.0)
1447 :let e = exp(1.0)
Bram Moolenaar98aefe72018-12-13 22:20:09 +01001448<
Bram Moolenaar446cb832008-06-24 21:56:24 +00001449 *floating-point-precision*
1450The precision and range of floating points numbers depends on what "double"
1451means in the library Vim was compiled with. There is no way to change this at
1452runtime.
1453
1454The default for displaying a |Float| is to use 6 decimal places, like using
1455printf("%g", f). You can select something else when using the |printf()|
1456function. Example: >
1457 :echo printf('%.15e', atan(1))
1458< 7.853981633974483e-01
1459
1460
Bram Moolenaar071d4272004-06-13 20:20:40 +00001461
Bram Moolenaar979243b2015-06-26 19:35:49 +02001462string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001463------
1464"string" string constant *expr-quote*
1465
1466Note that double quotes are used.
1467
1468A string constant accepts these special characters:
1469\... three-digit octal number (e.g., "\316")
1470\.. two-digit octal number (must be followed by non-digit)
1471\. one-digit octal number (must be followed by non-digit)
1472\x.. byte specified with two hex numbers (e.g., "\x1f")
1473\x. byte specified with one hex number (must be followed by non-hex char)
1474\X.. same as \x..
1475\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001476\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001477 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001478\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001479\b backspace <BS>
1480\e escape <Esc>
Bram Moolenaar6e649222021-10-04 21:32:54 +01001481\f formfeed 0x0C
Bram Moolenaar071d4272004-06-13 20:20:40 +00001482\n newline <NL>
1483\r return <CR>
1484\t tab <Tab>
1485\\ backslash
1486\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001487\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
Bram Moolenaar58b85342016-08-14 19:54:54 +02001488 in mappings, the 0x80 byte is escaped.
1489 To use the double quote character it must be escaped: "<M-\">".
Bram Moolenaar6e649222021-10-04 21:32:54 +01001490 Don't use <Char-xxxx> to get a UTF-8 character, use \uxxxx as
Bram Moolenaar58b85342016-08-14 19:54:54 +02001491 mentioned above.
Bram Moolenaarfccd93f2020-05-31 22:06:51 +02001492\<*xxx> Like \<xxx> but prepends a modifier instead of including it in the
1493 character. E.g. "\<C-w>" is one character 0x17 while "\<*C-w>" is four
Bram Moolenaarebe9d342020-05-30 21:52:54 +02001494 bytes: 3 for the CTRL modifier and then character "W".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001495
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001496Note that "\xff" is stored as the byte 255, which may be invalid in some
1497encodings. Use "\u00ff" to store character 255 according to the current value
1498of 'encoding'.
1499
Bram Moolenaar071d4272004-06-13 20:20:40 +00001500Note that "\000" and "\x00" force the end of the string.
1501
1502
Bram Moolenaard8968242019-01-15 22:51:57 +01001503blob-literal *blob-literal* *E973*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001504------------
1505
1506Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
1507The sequence must be an even number of hex characters. Example: >
1508 :let b = 0zFF00ED015DAF
1509
1510
Bram Moolenaar071d4272004-06-13 20:20:40 +00001511literal-string *literal-string* *E115*
1512---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001513'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001514
1515Note that single quotes are used.
1516
Bram Moolenaar58b85342016-08-14 19:54:54 +02001517This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001518meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001519
1520Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar58b85342016-08-14 19:54:54 +02001521to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001522 if a =~ "\\s*"
1523 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001524
1525
1526option *expr-option* *E112* *E113*
1527------
1528&option option value, local value if possible
1529&g:option global option value
1530&l:option local option value
1531
1532Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001533 echo "tabstop is " .. &tabstop
Bram Moolenaar071d4272004-06-13 20:20:40 +00001534 if &insertmode
1535
1536Any option name can be used here. See |options|. When using the local value
1537and there is no buffer-local or window-local value, the global value is used
1538anyway.
1539
1540
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001541register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001542--------
1543@r contents of register 'r'
1544
1545The result is the contents of the named register, as a single string.
1546Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar58b85342016-08-14 19:54:54 +02001547register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001548registers.
1549
1550When using the '=' register you get the expression itself, not what it
1551evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001552
1553
Bram Moolenaara2baa732022-02-04 16:09:54 +00001554nesting *expr-nesting* *E110*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001555-------
1556(expr1) nested expression
1557
1558
1559environment variable *expr-env*
1560--------------------
1561$VAR environment variable
1562
1563The String value of any environment variable. When it is not defined, the
1564result is an empty string.
Bram Moolenaar691ddee2019-05-09 14:52:41 +02001565
1566The functions `getenv()` and `setenv()` can also be used and work for
1567environment variables with non-alphanumeric names.
1568The function `environ()` can be used to get a Dict with all environment
1569variables.
1570
1571
Bram Moolenaar071d4272004-06-13 20:20:40 +00001572 *expr-env-expand*
1573Note that there is a difference between using $VAR directly and using
1574expand("$VAR"). Using it directly will only expand environment variables that
1575are known inside the current Vim session. Using expand() will first try using
1576the environment variables known inside the current Vim session. If that
1577fails, a shell will be used to expand the variable. This can be slow, but it
1578does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001579 :echo $shell
1580 :echo expand("$shell")
1581The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001582variable (if your shell supports it).
1583
1584
Bram Moolenaarf10911e2022-01-29 22:20:48 +00001585internal variable *expr-variable* *E1015* *E1089*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001586-----------------
1587variable internal variable
1588See below |internal-variables|.
1589
1590
Bram Moolenaar05159a02005-02-26 23:04:13 +00001591function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001592-------------
1593function(expr1, ...) function call
1594See below |functions|.
1595
1596
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001597lambda expression *expr-lambda* *lambda*
1598-----------------
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00001599{args -> expr1} legacy lambda expression *E451*
Bram Moolenaar5da36052021-12-27 15:39:57 +00001600(args) => expr1 |Vim9| lambda expression
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001601
1602A lambda expression creates a new unnamed function which returns the result of
Bram Moolenaar42ebd062016-07-17 13:35:14 +02001603evaluating |expr1|. Lambda expressions differ from |user-functions| in
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001604the following ways:
1605
16061. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
1607 commands.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020016082. The prefix "a:" should not be used for arguments. E.g.: >
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001609 :let F = {arg1, arg2 -> arg1 - arg2}
1610 :echo F(5, 2)
1611< 3
1612
1613The arguments are optional. Example: >
1614 :let F = {-> 'error function'}
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001615 :echo F('ignored')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001616< error function
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001617
Bram Moolenaar5da36052021-12-27 15:39:57 +00001618The |Vim9| lambda does not only use a different syntax, it also adds type
1619checking and can be split over multiple lines, see |vim9-lambda|.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001620
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001621 *closure*
1622Lambda expressions can access outer scope variables and arguments. This is
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001623often called a closure. Example where "i" and "a:arg" are used in a lambda
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001624while they already exist in the function scope. They remain valid even after
1625the function returns: >
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001626 :function Foo(arg)
1627 : let i = 3
1628 : return {x -> x + i - a:arg}
1629 :endfunction
1630 :let Bar = Foo(4)
1631 :echo Bar(6)
1632< 5
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001633
Bram Moolenaar388a5d42020-05-26 21:20:45 +02001634Note that the variables must exist in the outer scope before the lambda is
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001635defined for this to work. See also |:func-closure|.
1636
1637Lambda and closure support can be checked with: >
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001638 if has('lambda')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001639
1640Examples for using a lambda expression with |sort()|, |map()| and |filter()|: >
1641 :echo map([1, 2, 3], {idx, val -> val + 1})
1642< [2, 3, 4] >
1643 :echo sort([3,7,2,1,4], {a, b -> a - b})
1644< [1, 2, 3, 4, 7]
1645
1646The lambda expression is also useful for Channel, Job and timer: >
1647 :let timer = timer_start(500,
1648 \ {-> execute("echo 'Handler called'", "")},
1649 \ {'repeat': 3})
1650< Handler called
1651 Handler called
1652 Handler called
1653
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001654Note that it is possible to cause memory to be used and not freed if the
1655closure is referenced by the context it depends on: >
1656 function Function()
1657 let x = 0
1658 let F = {-> x}
1659 endfunction
1660The closure uses "x" from the function scope, and "F" in that same scope
1661refers to the closure. This cycle results in the memory not being freed.
1662Recommendation: don't do this.
1663
1664Notice how execute() is used to execute an Ex command. That's ugly though.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001665In Vim9 script you can use a command block, see |inline-function|.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001666
1667Lambda expressions have internal names like '<lambda>42'. If you get an error
1668for a lambda expression, you can find what it is with the following command: >
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001669 :function <lambda>42
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001670See also: |numbered-function|
1671
Bram Moolenaar071d4272004-06-13 20:20:40 +00001672==============================================================================
Bram Moolenaar6f4754b2022-01-23 12:07:04 +000016733. Internal variable *internal-variables* *E461* *E1001*
Bram Moolenaar4a748032010-09-30 21:47:56 +02001674
Bram Moolenaar071d4272004-06-13 20:20:40 +00001675An internal variable name can be made up of letters, digits and '_'. But it
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00001676cannot start with a digit. In legacy script it is also possible to use curly
Bram Moolenaar5da36052021-12-27 15:39:57 +00001677braces, see |curly-braces-names|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001678
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00001679In legacy script an internal variable is created with the ":let" command
Bram Moolenaar5da36052021-12-27 15:39:57 +00001680|:let|. An internal variable is explicitly destroyed with the ":unlet"
1681command |:unlet|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001682Using a name that is not an internal variable or refers to a variable that has
1683been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001684
Bram Moolenaar5da36052021-12-27 15:39:57 +00001685In |Vim9| script `:let` is not used and variables work differently, see |:var|.
1686
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001687 *variable-scope*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001688There are several name spaces for variables. Which one is to be used is
1689specified by what is prepended:
1690
Bram Moolenaar5da36052021-12-27 15:39:57 +00001691 (nothing) In a function: local to the function;
1692 in a legacy script: global;
1693 in a |Vim9| script: local to the script
Bram Moolenaar071d4272004-06-13 20:20:40 +00001694|buffer-variable| b: Local to the current buffer.
1695|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001696|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001697|global-variable| g: Global.
Bram Moolenaar5da36052021-12-27 15:39:57 +00001698|local-variable| l: Local to a function (only in a legacy function)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001699|script-variable| s: Local to a |:source|'ed Vim script.
Bram Moolenaar5da36052021-12-27 15:39:57 +00001700|function-argument| a: Function argument (only in a legacy function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001701|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001702
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001703The scope name by itself can be used as a |Dictionary|. For example, to
1704delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001705 :for k in keys(s:)
1706 : unlet s:[k]
1707 :endfor
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001708
Bram Moolenaar5da36052021-12-27 15:39:57 +00001709Note: in Vim9 script variables can also be local to a block of commands, see
1710|vim9-scopes|.
Bram Moolenaar531da592013-05-06 05:58:55 +02001711 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001712A variable name that is preceded with "b:" is local to the current buffer.
1713Thus you can have several "b:foo" variables, one for each buffer.
1714This kind of variable is deleted when the buffer is wiped out or deleted with
1715|:bdelete|.
1716
1717One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001718 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001719b:changedtick The total number of changes to the current buffer. It is
1720 incremented for each change. An undo command is also a change
Bram Moolenaarc024b462019-06-08 18:07:21 +02001721 in this case. Resetting 'modified' when writing the buffer is
1722 also counted.
1723 This can be used to perform an action only when the buffer has
1724 changed. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001725 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001726 : let my_changedtick = b:changedtick
1727 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001728 :endif
Bram Moolenaar3df01732017-02-17 22:47:16 +01001729< You cannot change or delete the b:changedtick variable.
1730
Bram Moolenaar531da592013-05-06 05:58:55 +02001731 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001732A variable name that is preceded with "w:" is local to the current window. It
1733is deleted when the window is closed.
1734
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001735 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001736A variable name that is preceded with "t:" is local to the current tab page,
1737It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001738without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001739
Bram Moolenaar531da592013-05-06 05:58:55 +02001740 *global-variable* *g:var* *g:*
Bram Moolenaar04fb9162021-12-30 20:24:12 +00001741Inside functions and in |Vim9| script global variables are accessed with "g:".
1742Omitting this will access a variable local to a function or script. "g:"
1743can also be used in any other place if you like.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001744
Bram Moolenaar531da592013-05-06 05:58:55 +02001745 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001746Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001747But you can also prepend "l:" if you like. However, without prepending "l:"
1748you may run into reserved variable names. For example "count". By itself it
1749refers to "v:count". Using "l:count" you can have a local variable with the
1750same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001751
1752 *script-variable* *s:var*
Bram Moolenaar04fb9162021-12-30 20:24:12 +00001753In a legacy Vim script variables starting with "s:" can be used. They cannot
1754be accessed from outside of the scripts, thus are local to the script.
1755In |Vim9| script the "s:" prefix can be omitted, variables are script-local by
1756default.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001757
1758They can be used in:
1759- commands executed while the script is sourced
1760- functions defined in the script
1761- autocommands defined in the script
1762- functions and autocommands defined in functions and autocommands which were
1763 defined in the script (recursively)
1764- user defined commands defined in the script
1765Thus not in:
1766- other scripts sourced from this one
1767- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001768- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001769- etc.
1770
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001771Script variables can be used to avoid conflicts with global variable names.
1772Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001773
1774 let s:counter = 0
1775 function MyCounter()
1776 let s:counter = s:counter + 1
1777 echo s:counter
1778 endfunction
1779 command Tick call MyCounter()
1780
1781You can now invoke "Tick" from any script, and the "s:counter" variable in
1782that script will not be changed, only the "s:counter" in the script where
1783"Tick" was defined is used.
1784
1785Another example that does the same: >
1786
1787 let s:counter = 0
1788 command Tick let s:counter = s:counter + 1 | echo s:counter
1789
1790When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001791script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001792defined.
1793
1794The script variables are also available when a function is defined inside a
1795function that is defined in a script. Example: >
1796
1797 let s:counter = 0
1798 function StartCounting(incr)
1799 if a:incr
1800 function MyCounter()
1801 let s:counter = s:counter + 1
1802 endfunction
1803 else
1804 function MyCounter()
1805 let s:counter = s:counter - 1
1806 endfunction
1807 endif
1808 endfunction
1809
1810This defines the MyCounter() function either for counting up or counting down
1811when calling StartCounting(). It doesn't matter from where StartCounting() is
1812called, the s:counter variable will be accessible in MyCounter().
1813
1814When the same script is sourced again it will use the same script variables.
1815They will remain valid as long as Vim is running. This can be used to
1816maintain a counter: >
1817
1818 if !exists("s:counter")
1819 let s:counter = 1
1820 echo "script executed for the first time"
1821 else
1822 let s:counter = s:counter + 1
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001823 echo "script executed " .. s:counter .. " times now"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001824 endif
1825
1826Note that this means that filetype plugins don't get a different set of script
1827variables for each buffer. Use local buffer variables instead |b:var|.
1828
1829
Bram Moolenaard47d5222018-12-09 20:43:55 +01001830PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001831 *E963* *E1063*
Bram Moolenaard47d5222018-12-09 20:43:55 +01001832Some variables can be set by the user, but the type cannot be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001833
Bram Moolenaar69bf6342019-10-29 04:16:57 +01001834 *v:argv* *argv-variable*
1835v:argv The command line arguments Vim was invoked with. This is a
1836 list of strings. The first item is the Vim command.
1837
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001838 *v:beval_col* *beval_col-variable*
1839v:beval_col The number of the column, over which the mouse pointer is.
1840 This is the byte index in the |v:beval_lnum| line.
1841 Only valid while evaluating the 'balloonexpr' option.
1842
1843 *v:beval_bufnr* *beval_bufnr-variable*
1844v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1845 valid while evaluating the 'balloonexpr' option.
1846
1847 *v:beval_lnum* *beval_lnum-variable*
1848v:beval_lnum The number of the line, over which the mouse pointer is. Only
1849 valid while evaluating the 'balloonexpr' option.
1850
1851 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001852v:beval_text The text under or after the mouse pointer. Usually a word as
1853 it is useful for debugging a C program. 'iskeyword' applies,
1854 but a dot and "->" before the position is included. When on a
1855 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001856 word before it. When on a Visual area within one line the
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02001857 highlighted text is used. Also see |<cexpr>|.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001858 Only valid while evaluating the 'balloonexpr' option.
1859
1860 *v:beval_winnr* *beval_winnr-variable*
1861v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001862 valid while evaluating the 'balloonexpr' option. The first
1863 window has number zero (unlike most other places where a
1864 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001865
Bram Moolenaar511972d2016-06-04 18:09:59 +02001866 *v:beval_winid* *beval_winid-variable*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001867v:beval_winid The |window-ID| of the window, over which the mouse pointer
1868 is. Otherwise like v:beval_winnr.
Bram Moolenaar511972d2016-06-04 18:09:59 +02001869
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001870 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001871v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001872 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001873 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001874
Bram Moolenaar071d4272004-06-13 20:20:40 +00001875 *v:charconvert_from* *charconvert_from-variable*
1876v:charconvert_from
1877 The name of the character encoding of a file to be converted.
1878 Only valid while evaluating the 'charconvert' option.
1879
1880 *v:charconvert_to* *charconvert_to-variable*
1881v:charconvert_to
1882 The name of the character encoding of a file after conversion.
1883 Only valid while evaluating the 'charconvert' option.
1884
1885 *v:cmdarg* *cmdarg-variable*
1886v:cmdarg This variable is used for two purposes:
1887 1. The extra arguments given to a file read/write command.
1888 Currently these are "++enc=" and "++ff=". This variable is
1889 set before an autocommand event for a file read/write
1890 command is triggered. There is a leading space to make it
1891 possible to append this variable directly after the
Bram Moolenaar58b85342016-08-14 19:54:54 +02001892 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001893 included here, because it will be executed anyway.
1894 2. When printing a PostScript file with ":hardcopy" this is
1895 the argument for the ":hardcopy" command. This can be used
1896 in 'printexpr'.
1897
1898 *v:cmdbang* *cmdbang-variable*
1899v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1900 was used the value is 1, otherwise it is 0. Note that this
1901 can only be used in autocommands. For user commands |<bang>|
1902 can be used.
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02001903 *v:collate* *collate-variable*
1904v:collate The current locale setting for collation order of the runtime
1905 environment. This allows Vim scripts to be aware of the
1906 current locale encoding. Technical: it's the value of
1907 LC_COLLATE. When not using a locale the value is "C".
1908 This variable can not be set directly, use the |:language|
1909 command.
1910 See |multi-lang|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001911
Drew Vogele30d1022021-10-24 20:35:07 +01001912 *v:colornames*
1913v:colornames A dictionary that maps color names to hex color strings. These
1914 color names can be used with the |highlight-guifg|,
1915 |highlight-guibg|, and |highlight-guisp| parameters. Updating
1916 an entry in v:colornames has no immediate effect on the syntax
1917 highlighting. The highlight commands (probably in a
1918 colorscheme script) need to be re-evaluated in order to use
1919 the updated color values. For example: >
1920
1921 :let v:colornames['fuscia'] = '#cf3ab4'
1922 :let v:colornames['mauve'] = '#915f6d'
1923 :highlight Normal guifg=fuscia guibg=mauve
1924<
1925 This cannot be used to override the |cterm-colors| but it can
1926 be used to override other colors. For example, the X11 colors
1927 defined in the `colors/lists/default.vim` (previously defined
1928 in |rgb.txt|). When defining new color names in a plugin, the
1929 recommended practice is to set a color entry only when it does
1930 not already exist. For example: >
1931
1932 :call extend(v:colornames, {
1933 \ 'fuscia': '#cf3ab4',
1934 \ 'mauve': '#915f6d,
1935 \ }, 'keep')
1936<
Bram Moolenaar113cb512021-11-07 20:27:04 +00001937 Using |extend()| with the 'keep' option updates each color only
Drew Vogele30d1022021-10-24 20:35:07 +01001938 if it did not exist in |v:colornames|. Doing so allows the
1939 user to choose the precise color value for a common name
1940 by setting it in their |.vimrc|.
1941
1942 It is possible to remove entries from this dictionary but
Drew Vogela0fca172021-11-13 10:50:01 +00001943 doing so is NOT recommended, because it is disruptive to
Drew Vogele30d1022021-10-24 20:35:07 +01001944 other scripts. It is also unlikely to achieve the desired
Bram Moolenaar113cb512021-11-07 20:27:04 +00001945 result because the |:colorscheme| and |:highlight| commands will
Drew Vogele30d1022021-10-24 20:35:07 +01001946 both automatically load all `colors/lists/default.vim` color
1947 scripts.
1948
Bram Moolenaar42a45122015-07-10 17:56:23 +02001949 *v:completed_item* *completed_item-variable*
1950v:completed_item
1951 |Dictionary| containing the |complete-items| for the most
1952 recently completed word after |CompleteDone|. The
1953 |Dictionary| is empty if the completion failed.
1954
Bram Moolenaar071d4272004-06-13 20:20:40 +00001955 *v:count* *count-variable*
1956v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar58b85342016-08-14 19:54:54 +02001957 to get the count before a mapping. Read-only. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001958 :map _x :<C-U>echo "the count is " .. v:count<CR>
Bram Moolenaar071d4272004-06-13 20:20:40 +00001959< Note: The <C-U> is required to remove the line range that you
1960 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001961 When there are two counts, as in "3d2w", they are multiplied,
1962 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001963 Also used for evaluating the 'formatexpr' option.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02001964 "count" also works, for backwards compatibility, unless
1965 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001966
1967 *v:count1* *count1-variable*
1968v:count1 Just like "v:count", but defaults to one when no count is
1969 used.
1970
1971 *v:ctype* *ctype-variable*
1972v:ctype The current locale setting for characters of the runtime
1973 environment. This allows Vim scripts to be aware of the
1974 current locale encoding. Technical: it's the value of
1975 LC_CTYPE. When not using a locale the value is "C".
1976 This variable can not be set directly, use the |:language|
1977 command.
1978 See |multi-lang|.
1979
1980 *v:dying* *dying-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001981v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001982 one. When multiple signals are caught the number increases.
1983 Can be used in an autocommand to check if Vim didn't
1984 terminate normally. {only works on Unix}
1985 Example: >
1986 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001987< Note: if another deadly signal is caught when v:dying is one,
1988 VimLeave autocommands will not be executed.
1989
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001990 *v:exiting* *exiting-variable*
1991v:exiting Vim exit code. Normally zero, non-zero when something went
1992 wrong. The value is v:null before invoking the |VimLeavePre|
1993 and |VimLeave| autocmds. See |:q|, |:x| and |:cquit|.
1994 Example: >
1995 :au VimLeave * echo "Exit value is " .. v:exiting
1996<
Bram Moolenaar37f4cbd2019-08-23 20:58:45 +02001997 *v:echospace* *echospace-variable*
1998v:echospace Number of screen cells that can be used for an `:echo` message
1999 in the last screen line before causing the |hit-enter-prompt|.
2000 Depends on 'showcmd', 'ruler' and 'columns'. You need to
2001 check 'cmdheight' for whether there are full-width lines
2002 available above the last line.
2003
Bram Moolenaar071d4272004-06-13 20:20:40 +00002004 *v:errmsg* *errmsg-variable*
2005v:errmsg Last given error message. It's allowed to set this variable.
2006 Example: >
2007 :let v:errmsg = ""
2008 :silent! next
2009 :if v:errmsg != ""
2010 : ... handle error
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002011< "errmsg" also works, for backwards compatibility, unless
2012 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002013
Bram Moolenaar65a54642018-04-28 16:56:53 +02002014 *v:errors* *errors-variable* *assert-return*
Bram Moolenaar683fa182015-11-30 21:38:24 +01002015v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01002016 This is a list of strings.
2017 The assert functions append an item when an assert fails.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002018 The return value indicates this: a one is returned if an item
2019 was added to v:errors, otherwise zero is returned.
Bram Moolenaar43345542015-11-29 17:35:35 +01002020 To remove old results make it empty: >
2021 :let v:errors = []
2022< If v:errors is set to anything but a list it is made an empty
2023 list by the assert function.
2024
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01002025 *v:event* *event-variable*
2026v:event Dictionary containing information about the current
Bram Moolenaar560979e2020-02-04 22:53:05 +01002027 |autocommand|. See the specific event for what it puts in
2028 this dictionary.
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +02002029 The dictionary is emptied when the |autocommand| finishes,
2030 please refer to |dict-identity| for how to get an independent
2031 copy of it. Use |deepcopy()| if you want to keep the
2032 information after the event triggers. Example: >
2033 au TextYankPost * let g:foo = deepcopy(v:event)
2034<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002035 *v:exception* *exception-variable*
2036v:exception The value of the exception most recently caught and not
2037 finished. See also |v:throwpoint| and |throw-variables|.
2038 Example: >
2039 :try
2040 : throw "oops"
2041 :catch /.*/
Bram Moolenaar54775062019-07-31 21:07:14 +02002042 : echo "caught " .. v:exception
Bram Moolenaar071d4272004-06-13 20:20:40 +00002043 :endtry
2044< Output: "caught oops".
2045
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002046 *v:false* *false-variable*
2047v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002048 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002049 When used as a string this evaluates to "v:false". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002050 echo v:false
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002051< v:false ~
2052 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002053 value. Read-only.
Bram Moolenaar5da36052021-12-27 15:39:57 +00002054 In |Vim9| script "false" can be used which has a boolean type.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002055
Bram Moolenaar19a09a12005-03-04 23:39:37 +00002056 *v:fcs_reason* *fcs_reason-variable*
2057v:fcs_reason The reason why the |FileChangedShell| event was triggered.
2058 Can be used in an autocommand to decide what to do and/or what
2059 to set v:fcs_choice to. Possible values:
2060 deleted file no longer exists
2061 conflict file contents, mode or timestamp was
2062 changed and buffer is modified
2063 changed file contents has changed
2064 mode mode of file changed
2065 time only file timestamp changed
2066
2067 *v:fcs_choice* *fcs_choice-variable*
2068v:fcs_choice What should happen after a |FileChangedShell| event was
2069 triggered. Can be used in an autocommand to tell Vim what to
2070 do with the affected buffer:
2071 reload Reload the buffer (does not work if
2072 the file was deleted).
Rob Pilling8196e942022-02-11 15:12:10 +00002073 edit Reload the buffer and detect the
2074 values for options such as
2075 'fileformat', 'fileencoding', 'binary'
2076 (does not work if the file was
2077 deleted).
Bram Moolenaar19a09a12005-03-04 23:39:37 +00002078 ask Ask the user what to do, as if there
2079 was no autocommand. Except that when
2080 only the timestamp changed nothing
2081 will happen.
2082 <empty> Nothing, the autocommand should do
2083 everything that needs to be done.
2084 The default is empty. If another (invalid) value is used then
2085 Vim behaves like it is empty, there is no warning message.
2086
Bram Moolenaar4c295022021-05-02 17:19:11 +02002087 *v:fname* *fname-variable*
Bram Moolenaar90df4b92021-07-07 20:26:08 +02002088v:fname When evaluating 'includeexpr': the file name that was
2089 detected. Empty otherwise.
Bram Moolenaar4c295022021-05-02 17:19:11 +02002090
Bram Moolenaar071d4272004-06-13 20:20:40 +00002091 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002092v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002093 option used for ~
2094 'charconvert' file to be converted
2095 'diffexpr' original file
2096 'patchexpr' original file
2097 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00002098 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002099
2100 *v:fname_out* *fname_out-variable*
2101v:fname_out The name of the output file. Only valid while
2102 evaluating:
2103 option used for ~
2104 'charconvert' resulting converted file (*)
2105 'diffexpr' output of diff
2106 'patchexpr' resulting patched file
2107 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar58b85342016-08-14 19:54:54 +02002108 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00002109 for a read command (e.g., ":e file") it will be a temporary
2110 file and different from v:fname_in.
2111
2112 *v:fname_new* *fname_new-variable*
2113v:fname_new The name of the new version of the file. Only valid while
2114 evaluating 'diffexpr'.
2115
2116 *v:fname_diff* *fname_diff-variable*
2117v:fname_diff The name of the diff (patch) file. Only valid while
2118 evaluating 'patchexpr'.
2119
2120 *v:folddashes* *folddashes-variable*
2121v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
2122 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002123 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002124
2125 *v:foldlevel* *foldlevel-variable*
2126v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002127 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002128
2129 *v:foldend* *foldend-variable*
2130v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002131 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002132
2133 *v:foldstart* *foldstart-variable*
2134v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002135 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002136
Bram Moolenaar817a8802013-11-09 01:44:43 +01002137 *v:hlsearch* *hlsearch-variable*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002138v:hlsearch Variable that indicates whether search highlighting is on.
Bram Moolenaar76440e22014-11-27 19:14:49 +01002139 Setting it makes sense only if 'hlsearch' is enabled which
2140 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01002141 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01002142 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02002143< Note that the value is restored when returning from a
2144 function. |function-search-undo|.
2145
Bram Moolenaar843ee412004-06-30 16:16:41 +00002146 *v:insertmode* *insertmode-variable*
2147v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
2148 events. Values:
2149 i Insert mode
2150 r Replace mode
2151 v Virtual Replace mode
2152
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002153 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002154v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002155 evaluating the expression used with |map()| and |filter()|.
2156 Read-only.
2157
Bram Moolenaar071d4272004-06-13 20:20:40 +00002158 *v:lang* *lang-variable*
2159v:lang The current locale setting for messages of the runtime
2160 environment. This allows Vim scripts to be aware of the
2161 current language. Technical: it's the value of LC_MESSAGES.
2162 The value is system dependent.
2163 This variable can not be set directly, use the |:language|
2164 command.
2165 It can be different from |v:ctype| when messages are desired
2166 in a different language than what is used for character
2167 encoding. See |multi-lang|.
2168
2169 *v:lc_time* *lc_time-variable*
2170v:lc_time The current locale setting for time messages of the runtime
2171 environment. This allows Vim scripts to be aware of the
2172 current language. Technical: it's the value of LC_TIME.
2173 This variable can not be set directly, use the |:language|
2174 command. See |multi-lang|.
2175
2176 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02002177v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
2178 'indentexpr' expressions, tab page number for 'guitablabel'
2179 and 'guitabtooltip'. Only valid while one of these
2180 expressions is being evaluated. Read-only when in the
2181 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002182
naohiro ono56200ee2022-01-01 14:59:44 +00002183 *v:maxcol* *maxcol-variable*
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002184v:maxcol Maximum line length. Depending on where it is used it can be
Bram Moolenaar944697a2022-02-20 19:48:20 +00002185 screen columns, characters or bytes. The value currently is
2186 2147483647 on all systems.
naohiro ono56200ee2022-01-01 14:59:44 +00002187
Bram Moolenaar219b8702006-11-01 14:32:36 +00002188 *v:mouse_win* *mouse_win-variable*
2189v:mouse_win Window number for a mouse click obtained with |getchar()|.
2190 First window has number 1, like with |winnr()|. The value is
2191 zero when there was no mouse button click.
2192
Bram Moolenaar511972d2016-06-04 18:09:59 +02002193 *v:mouse_winid* *mouse_winid-variable*
2194v:mouse_winid Window ID for a mouse click obtained with |getchar()|.
2195 The value is zero when there was no mouse button click.
2196
Bram Moolenaar219b8702006-11-01 14:32:36 +00002197 *v:mouse_lnum* *mouse_lnum-variable*
2198v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
2199 This is the text line number, not the screen line number. The
2200 value is zero when there was no mouse button click.
2201
2202 *v:mouse_col* *mouse_col-variable*
2203v:mouse_col Column number for a mouse click obtained with |getchar()|.
2204 This is the screen column number, like with |virtcol()|. The
2205 value is zero when there was no mouse button click.
2206
Bram Moolenaard09091d2019-01-17 16:07:22 +01002207 *v:none* *none-variable* *None*
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002208v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002209 |json_encode()|.
Bram Moolenaar2547aa92020-07-26 17:00:44 +02002210 This can also be used as a function argument to use the
2211 default value, see |none-function_argument|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01002212 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002213 When used as a string this evaluates to "v:none". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002214 echo v:none
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002215< v:none ~
2216 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002217 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002218
2219 *v:null* *null-variable*
2220v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002221 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01002222 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002223 When used as a string this evaluates to "v:null". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002224 echo v:null
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002225< v:null ~
2226 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002227 value. Read-only.
Bram Moolenaar5da36052021-12-27 15:39:57 +00002228 In |Vim9| script "null" can be used without "v:".
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002229
Bram Moolenaar57d5a012021-01-21 21:42:31 +01002230 *v:numbermax* *numbermax-variable*
2231v:numbermax Maximum value of a number.
2232
Bram Moolenaare0e39172021-01-25 21:14:57 +01002233 *v:numbermin* *numbermin-variable*
Bram Moolenaar2346a632021-06-13 19:02:49 +02002234v:numbermin Minimum value of a number (negative).
Bram Moolenaar57d5a012021-01-21 21:42:31 +01002235
Bram Moolenaarf9706e92020-02-22 14:27:04 +01002236 *v:numbersize* *numbersize-variable*
2237v:numbersize Number of bits in a Number. This is normally 64, but on some
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01002238 systems it may be 32.
Bram Moolenaarf9706e92020-02-22 14:27:04 +01002239
Bram Moolenaard812df62008-11-09 12:46:09 +00002240 *v:oldfiles* *oldfiles-variable*
2241v:oldfiles List of file names that is loaded from the |viminfo| file on
2242 startup. These are the files that Vim remembers marks for.
2243 The length of the List is limited by the ' argument of the
2244 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01002245 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00002246 Also see |:oldfiles| and |c_#<|.
2247 The List can be modified, but this has no effect on what is
2248 stored in the |viminfo| file later. If you use values other
2249 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02002250 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00002251
Bram Moolenaar53744302015-07-17 17:38:22 +02002252 *v:option_new*
2253v:option_new New value of the option. Valid while executing an |OptionSet|
2254 autocommand.
2255 *v:option_old*
2256v:option_old Old value of the option. Valid while executing an |OptionSet|
Bram Moolenaard7c96872019-06-15 17:12:48 +02002257 autocommand. Depending on the command used for setting and the
2258 kind of option this is either the local old value or the
2259 global old value.
2260 *v:option_oldlocal*
2261v:option_oldlocal
2262 Old local value of the option. Valid while executing an
2263 |OptionSet| autocommand.
2264 *v:option_oldglobal*
2265v:option_oldglobal
2266 Old global value of the option. Valid while executing an
2267 |OptionSet| autocommand.
Bram Moolenaar53744302015-07-17 17:38:22 +02002268 *v:option_type*
2269v:option_type Scope of the set command. Valid while executing an
2270 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaard7c96872019-06-15 17:12:48 +02002271 *v:option_command*
2272v:option_command
2273 Command used to set the option. Valid while executing an
2274 |OptionSet| autocommand.
2275 value option was set via ~
2276 "setlocal" |:setlocal| or ":let l:xxx"
2277 "setglobal" |:setglobal| or ":let g:xxx"
2278 "set" |:set| or |:let|
2279 "modeline" |modeline|
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00002280 *v:operator* *operator-variable*
2281v:operator The last operator given in Normal mode. This is a single
2282 character except for commands starting with <g> or <z>,
2283 in which case it is two characters. Best used alongside
2284 |v:prevcount| and |v:register|. Useful if you want to cancel
2285 Operator-pending mode and then use the operator, e.g.: >
2286 :omap O <Esc>:call MyMotion(v:operator)<CR>
2287< The value remains set until another operator is entered, thus
2288 don't expect it to be empty.
2289 v:operator is not set for |:delete|, |:yank| or other Ex
2290 commands.
2291 Read-only.
2292
Bram Moolenaar071d4272004-06-13 20:20:40 +00002293 *v:prevcount* *prevcount-variable*
2294v:prevcount The count given for the last but one Normal mode command.
2295 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00002296 you want to cancel Visual or Operator-pending mode and then
2297 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002298 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
2299< Read-only.
2300
Bram Moolenaar05159a02005-02-26 23:04:13 +00002301 *v:profiling* *profiling-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002302v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00002303 See |profiling|.
2304
Bram Moolenaar071d4272004-06-13 20:20:40 +00002305 *v:progname* *progname-variable*
2306v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02002307 invoked. Allows you to do special initialisations for |view|,
2308 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002309 Read-only.
2310
Bram Moolenaara1706c92014-04-01 19:55:49 +02002311 *v:progpath* *progpath-variable*
Bram Moolenaar56c860c2019-08-17 20:09:31 +02002312v:progpath Contains the command with which Vim was invoked, in a form
2313 that when passed to the shell will run the same Vim executable
2314 as the current one (if $PATH remains unchanged).
2315 Useful if you want to message a Vim server using a
Bram Moolenaara1706c92014-04-01 19:55:49 +02002316 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02002317 To get the full path use: >
2318 echo exepath(v:progpath)
Bram Moolenaar56c860c2019-08-17 20:09:31 +02002319< If the command has a relative path it will be expanded to the
2320 full path, so that it still works after `:cd`. Thus starting
2321 "./vim" results in "/home/user/path/to/vim/src/vim".
2322 On Linux and other systems it will always be the full path.
2323 On Mac it may just be "vim" and using exepath() as mentioned
2324 above should be used to get the full path.
Bram Moolenaar08cab962017-03-04 14:37:18 +01002325 On MS-Windows the executable may be called "vim.exe", but the
2326 ".exe" is not added to v:progpath.
Bram Moolenaara1706c92014-04-01 19:55:49 +02002327 Read-only.
2328
Bram Moolenaar071d4272004-06-13 20:20:40 +00002329 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01002330v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02002331 command (regardless of whether that command actually used a
2332 register). Or for the currently executing normal mode mapping
2333 (use this in custom commands that take a register).
2334 If none is supplied it is the default register '"', unless
2335 'clipboard' contains "unnamed" or "unnamedplus", then it is
2336 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01002337 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002338
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002339 *v:scrollstart* *scrollstart-variable*
2340v:scrollstart String describing the script or function that caused the
2341 screen to scroll up. It's only set when it is empty, thus the
2342 first reason is remembered. It is set to "Unknown" for a
2343 typed command.
2344 This can be used to find out why your script causes the
2345 hit-enter prompt.
2346
Bram Moolenaar071d4272004-06-13 20:20:40 +00002347 *v:servername* *servername-variable*
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002348v:servername The resulting registered |client-server-name| if any.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002349 Read-only.
2350
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002351
Bram Moolenaar446cb832008-06-24 21:56:24 +00002352v:searchforward *v:searchforward* *searchforward-variable*
2353 Search direction: 1 after a forward search, 0 after a
2354 backward search. It is reset to forward when directly setting
2355 the last search pattern, see |quote/|.
2356 Note that the value is restored when returning from a
2357 function. |function-search-undo|.
2358 Read-write.
2359
Bram Moolenaar071d4272004-06-13 20:20:40 +00002360 *v:shell_error* *shell_error-variable*
2361v:shell_error Result of the last shell command. When non-zero, the last
2362 shell command had an error. When zero, there was no problem.
2363 This only works when the shell returns the error code to Vim.
2364 The value -1 is often used when the command could not be
2365 executed. Read-only.
2366 Example: >
2367 :!mv foo bar
2368 :if v:shell_error
2369 : echo 'could not rename "foo" to "bar"!'
2370 :endif
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002371< "shell_error" also works, for backwards compatibility, unless
2372 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002373
Bram Moolenaar113cb512021-11-07 20:27:04 +00002374 *v:sizeofint* *sizeofint-variable*
2375v:sizeofint Number of bytes in an int. Depends on how Vim was compiled.
2376 This is only useful for deciding whether a test will give the
2377 expected result.
2378
2379 *v:sizeoflong* *sizeoflong-variable*
2380v:sizeoflong Number of bytes in a long. Depends on how Vim was compiled.
2381 This is only useful for deciding whether a test will give the
2382 expected result.
2383
2384 *v:sizeofpointer* *sizeofpointer-variable*
2385v:sizeofpointer Number of bytes in a pointer. Depends on how Vim was compiled.
2386 This is only useful for deciding whether a test will give the
2387 expected result.
2388
Bram Moolenaar071d4272004-06-13 20:20:40 +00002389 *v:statusmsg* *statusmsg-variable*
2390v:statusmsg Last given status message. It's allowed to set this variable.
2391
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002392 *v:swapname* *swapname-variable*
2393v:swapname Only valid when executing |SwapExists| autocommands: Name of
2394 the swap file found. Read-only.
2395
2396 *v:swapchoice* *swapchoice-variable*
2397v:swapchoice |SwapExists| autocommands can set this to the selected choice
2398 for handling an existing swap file:
2399 'o' Open read-only
2400 'e' Edit anyway
2401 'r' Recover
2402 'd' Delete swapfile
2403 'q' Quit
2404 'a' Abort
Bram Moolenaar58b85342016-08-14 19:54:54 +02002405 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002406 results in the user being asked, as would happen when there is
2407 no SwapExists autocommand. The default is empty.
2408
Bram Moolenaarb3480382005-12-11 21:33:32 +00002409 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00002410v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00002411 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar58b85342016-08-14 19:54:54 +02002412 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00002413 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00002414 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00002415
Bram Moolenaard823fa92016-08-12 16:29:27 +02002416 *v:t_TYPE* *v:t_bool* *t_bool-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002417v:t_bool Value of |Boolean| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002418 *v:t_channel* *t_channel-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002419v:t_channel Value of |Channel| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002420 *v:t_dict* *t_dict-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002421v:t_dict Value of |Dictionary| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002422 *v:t_float* *t_float-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002423v:t_float Value of |Float| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002424 *v:t_func* *t_func-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002425v:t_func Value of |Funcref| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002426 *v:t_job* *t_job-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002427v:t_job Value of |Job| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002428 *v:t_list* *t_list-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002429v:t_list Value of |List| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002430 *v:t_none* *t_none-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002431v:t_none Value of |None| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002432 *v:t_number* *t_number-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002433v:t_number Value of |Number| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002434 *v:t_string* *t_string-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002435v:t_string Value of |String| type. Read-only. See: |type()|
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002436 *v:t_blob* *t_blob-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002437v:t_blob Value of |Blob| type. Read-only. See: |type()|
Bram Moolenaarf562e722016-07-19 17:25:25 +02002438
Bram Moolenaar071d4272004-06-13 20:20:40 +00002439 *v:termresponse* *termresponse-variable*
2440v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar58b85342016-08-14 19:54:54 +02002441 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaarb4230122019-05-30 18:40:53 +02002442 that starts with ESC [ or CSI, then '>' or '?' and ends in a
2443 'c', with only digits and ';' in between.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002444 When this option is set, the TermResponse autocommand event is
2445 fired, so that you can react to the response from the
Bram Moolenaar0c0eddd2020-06-13 15:47:25 +02002446 terminal. You can use |terminalprops()| to see what Vim
2447 figured out about the terminal.
Bram Moolenaarb4230122019-05-30 18:40:53 +02002448 The response from a new xterm is: "<Esc>[> Pp ; Pv ; Pc c". Pp
Bram Moolenaar071d4272004-06-13 20:20:40 +00002449 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
2450 patch level (since this was introduced in patch 95, it's
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00002451 always 95 or higher). Pc is always zero.
2452 If Pv is 141 or higher then Vim will try to request terminal
2453 codes. This only works with xterm |xterm-codes|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002454 {only when compiled with |+termresponse| feature}
2455
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002456 *v:termblinkresp*
2457v:termblinkresp The escape sequence returned by the terminal for the |t_RC|
2458 termcap entry. This is used to find out whether the terminal
2459 cursor is blinking. This is used by |term_getcursor()|.
2460
2461 *v:termstyleresp*
2462v:termstyleresp The escape sequence returned by the terminal for the |t_RS|
2463 termcap entry. This is used to find out what the shape of the
2464 cursor is. This is used by |term_getcursor()|.
2465
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002466 *v:termrbgresp*
2467v:termrbgresp The escape sequence returned by the terminal for the |t_RB|
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002468 termcap entry. This is used to find out what the terminal
2469 background color is, see 'background'.
2470
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002471 *v:termrfgresp*
2472v:termrfgresp The escape sequence returned by the terminal for the |t_RF|
2473 termcap entry. This is used to find out what the terminal
2474 foreground color is.
2475
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002476 *v:termu7resp*
2477v:termu7resp The escape sequence returned by the terminal for the |t_u7|
2478 termcap entry. This is used to find out what the terminal
2479 does with ambiguous width characters, see 'ambiwidth'.
2480
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002481 *v:testing* *testing-variable*
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002482v:testing Must be set before using `test_garbagecollect_now()`.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002483 Also, when set certain error messages won't be shown for 2
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002484 seconds. (e.g. "'dictionary' option is empty")
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002485
Bram Moolenaar071d4272004-06-13 20:20:40 +00002486 *v:this_session* *this_session-variable*
2487v:this_session Full filename of the last loaded or saved session file. See
2488 |:mksession|. It is allowed to set this variable. When no
2489 session file has been saved, this variable is empty.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002490 "this_session" also works, for backwards compatibility, unless
2491 |scriptversion| is 3 or higher
Bram Moolenaar071d4272004-06-13 20:20:40 +00002492
2493 *v:throwpoint* *throwpoint-variable*
2494v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar58b85342016-08-14 19:54:54 +02002495 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00002496 also |v:exception| and |throw-variables|.
2497 Example: >
2498 :try
2499 : throw "oops"
2500 :catch /.*/
2501 : echo "Exception from" v:throwpoint
2502 :endtry
2503< Output: "Exception from test.vim, line 2"
2504
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002505 *v:true* *true-variable*
2506v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002507 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002508 When used as a string this evaluates to "v:true". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002509 echo v:true
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002510< v:true ~
2511 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002512 value. Read-only.
Bram Moolenaar5da36052021-12-27 15:39:57 +00002513 In |Vim9| script "true" can be used which has a boolean type.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002514 *v:val* *val-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002515v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002516 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002517 |filter()|. Read-only.
2518
Bram Moolenaar071d4272004-06-13 20:20:40 +00002519 *v:version* *version-variable*
2520v:version Version number of Vim: Major version number times 100 plus
Bram Moolenaar9b283522019-06-17 22:19:33 +02002521 minor version number. Version 5.0 is 500. Version 5.1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002522 is 501. Read-only. "version" also works, for backwards
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002523 compatibility, unless |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002524 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02002525 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002526< Note that patch numbers are specific to the version, thus both
2527 version 5.0 and 5.1 may have a patch 123, but these are
2528 completely different.
2529
Bram Moolenaar37df9a42019-06-14 14:39:51 +02002530 *v:versionlong* *versionlong-variable*
Bram Moolenaar9b283522019-06-17 22:19:33 +02002531v:versionlong Like v:version, but also including the patchlevel in the last
2532 four digits. Version 8.1 with patch 123 has value 8010123.
2533 This can be used like this: >
2534 if v:versionlong >= 8010123
Bram Moolenaar37df9a42019-06-14 14:39:51 +02002535< However, if there are gaps in the list of patches included
2536 this will not work well. This can happen if a recent patch
2537 was included into an older version, e.g. for a security fix.
2538 Use the has() function to make sure the patch is actually
2539 included.
2540
Bram Moolenaar14735512016-03-26 21:00:08 +01002541 *v:vim_did_enter* *vim_did_enter-variable*
2542v:vim_did_enter Zero until most of startup is done. It is set to one just
2543 before |VimEnter| autocommands are triggered.
2544
Bram Moolenaar071d4272004-06-13 20:20:40 +00002545 *v:warningmsg* *warningmsg-variable*
2546v:warningmsg Last given warning message. It's allowed to set this variable.
2547
Bram Moolenaar727c8762010-10-20 19:17:48 +02002548 *v:windowid* *windowid-variable*
2549v:windowid When any X11 based GUI is running or when running in a
2550 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02002551 set to the window ID.
2552 When an MS-Windows GUI is running this will be set to the
2553 window handle.
2554 Otherwise the value is zero.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002555 Note: for windows inside Vim use |winnr()| or |win_getid()|,
2556 see |window-ID|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02002557
Bram Moolenaar071d4272004-06-13 20:20:40 +00002558==============================================================================
25594. Builtin Functions *functions*
2560
2561See |function-list| for a list grouped by what the function is used for.
2562
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002563The alphabetic list of all builtin functions and details are in a separate
2564help file: |builtin-functions|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002565
2566==============================================================================
25675. Defining functions *user-functions*
2568
2569New functions can be defined. These can be called just like builtin
2570functions. The function executes a sequence of Ex commands. Normal mode
2571commands can be executed with the |:normal| command.
2572
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01002573This section is about the legacy functions. For the Vim9 functions, which
2574execute much faster, support type checking and more, see |vim9.txt|.
2575
Bram Moolenaar071d4272004-06-13 20:20:40 +00002576The function name must start with an uppercase letter, to avoid confusion with
2577builtin functions. To prevent from using the same name in different scripts
2578avoid obvious, short names. A good habit is to start the function name with
2579the name of the script, e.g., "HTMLcolor()".
2580
Bram Moolenaar5da36052021-12-27 15:39:57 +00002581In legacy script it is also possible to use curly braces, see
2582|curly-braces-names|.
2583The |autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002584
2585 *local-function*
Bram Moolenaar5da36052021-12-27 15:39:57 +00002586A function local to a legacy script must start with "s:". A local script
2587function can only be called from within the script and from functions, user
2588commands and autocommands defined in the script. It is also possible to call
2589the function from a mapping defined in the script, but then |<SID>| must be
2590used instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +02002591There are only script-local functions, no buffer-local or window-local
2592functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002593
Bram Moolenaar5da36052021-12-27 15:39:57 +00002594In |Vim9| script functions are local to the script by default, prefix "g:" to
2595define a global function.
2596
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002597 *:fu* *:function* *E128* *E129* *E123* *E454*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002598:fu[nction] List all functions and their arguments.
2599
2600:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002601 {name} can also be a |Dictionary| entry that is a
2602 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002603 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +00002604
2605:fu[nction] /{pattern} List functions with a name matching {pattern}.
2606 Example that lists all functions ending with "File": >
2607 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00002608<
2609 *:function-verbose*
2610When 'verbose' is non-zero, listing a function will also display where it was
2611last defined. Example: >
2612
2613 :verbose function SetFileTypeSH
2614 function SetFileTypeSH(name)
2615 Last set from /usr/share/vim/vim-7.0/filetype.vim
2616<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00002617See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00002618
Bram Moolenaarbcb98982014-05-01 14:08:19 +02002619 *E124* *E125* *E853* *E884*
Bram Moolenaar10ce39a2016-07-29 22:37:06 +02002620:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
Bram Moolenaar01164a62017-11-02 22:58:42 +01002621 Define a new function by the name {name}. The body of
2622 the function follows in the next lines, until the
2623 matching |:endfunction|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002624
Bram Moolenaar01164a62017-11-02 22:58:42 +01002625 The name must be made of alphanumeric characters and
2626 '_', and must start with a capital or "s:" (see
2627 above). Note that using "b:" or "g:" is not allowed.
2628 (since patch 7.4.260 E884 is given if the function
2629 name has a colon in the name, e.g. for "foo:bar()".
2630 Before that patch no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002631
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002632 {name} can also be a |Dictionary| entry that is a
2633 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002634 :function dict.init(arg)
Bram Moolenaar58b85342016-08-14 19:54:54 +02002635< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002636 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar58b85342016-08-14 19:54:54 +02002637 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002638 result is a |Funcref| to a numbered function. The
2639 function can only be used with a |Funcref| and will be
2640 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002641 *E127* *E122*
2642 When a function by this name already exists and [!] is
Bram Moolenaarded5f1b2018-11-10 17:33:29 +01002643 not used an error message is given. There is one
2644 exception: When sourcing a script again, a function
2645 that was previously defined in that script will be
2646 silently replaced.
2647 When [!] is used, an existing function is silently
2648 replaced. Unless it is currently being executed, that
2649 is an error.
Bram Moolenaarf8be4612017-06-23 20:52:40 +02002650 NOTE: Use ! wisely. If used without care it can cause
2651 an existing function to be replaced unexpectedly,
2652 which is hard to debug.
Bram Moolenaar388a5d42020-05-26 21:20:45 +02002653 NOTE: In Vim9 script script-local functions cannot be
2654 deleted or redefined.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002655
2656 For the {arguments} see |function-argument|.
2657
Bram Moolenaar8d043172014-01-23 14:24:41 +01002658 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002659 When the [range] argument is added, the function is
2660 expected to take care of a range itself. The range is
2661 passed as "a:firstline" and "a:lastline". If [range]
2662 is excluded, ":{range}call" will call the function for
2663 each line in the range, with the cursor on the start
2664 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +01002665 The cursor is still moved to the first line of the
2666 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +01002667 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002668 When the [abort] argument is added, the function will
2669 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +01002670 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002671 When the [dict] argument is added, the function must
Bram Moolenaar58b85342016-08-14 19:54:54 +02002672 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002673 local variable "self" will then be set to the
2674 dictionary. See |Dictionary-function|.
Bram Moolenaar10ce39a2016-07-29 22:37:06 +02002675 *:func-closure* *E932*
2676 When the [closure] argument is added, the function
2677 can access variables and arguments from the outer
2678 scope. This is usually called a closure. In this
2679 example Bar() uses "x" from the scope of Foo(). It
2680 remains referenced even after Foo() returns: >
2681 :function! Foo()
2682 : let x = 0
2683 : function! Bar() closure
2684 : let x += 1
2685 : return x
2686 : endfunction
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02002687 : return funcref('Bar')
Bram Moolenaar10ce39a2016-07-29 22:37:06 +02002688 :endfunction
2689
2690 :let F = Foo()
2691 :echo F()
2692< 1 >
2693 :echo F()
2694< 2 >
2695 :echo F()
2696< 3
Bram Moolenaar071d4272004-06-13 20:20:40 +00002697
Bram Moolenaar446cb832008-06-24 21:56:24 +00002698 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +00002699 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +00002700 will not be changed by the function. This also
2701 implies that the effect of |:nohlsearch| is undone
2702 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +00002703
Bram Moolenaara2baa732022-02-04 16:09:54 +00002704 *:endf* *:endfunction* *E126* *E193* *W22* *E1151*
Bram Moolenaar663bb232017-06-22 19:12:10 +02002705:endf[unction] [argument]
2706 The end of a function definition. Best is to put it
2707 on a line by its own, without [argument].
2708
2709 [argument] can be:
2710 | command command to execute next
2711 \n command command to execute next
2712 " comment always ignored
Bram Moolenaarf8be4612017-06-23 20:52:40 +02002713 anything else ignored, warning given when
2714 'verbose' is non-zero
Bram Moolenaar663bb232017-06-22 19:12:10 +02002715 The support for a following command was added in Vim
2716 8.0.0654, before that any argument was silently
2717 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002718
Bram Moolenaarf8be4612017-06-23 20:52:40 +02002719 To be able to define a function inside an `:execute`
2720 command, use line breaks instead of |:bar|: >
2721 :exe "func Foo()\necho 'foo'\nendfunc"
2722<
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002723 *:delf* *:delfunction* *E131* *E933* *E1084*
Bram Moolenaar663bb232017-06-22 19:12:10 +02002724:delf[unction][!] {name}
2725 Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002726 {name} can also be a |Dictionary| entry that is a
2727 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002728 :delfunc dict.init
Bram Moolenaar58b85342016-08-14 19:54:54 +02002729< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002730 function is deleted if there are no more references to
2731 it.
Bram Moolenaar663bb232017-06-22 19:12:10 +02002732 With the ! there is no error if the function does not
2733 exist.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002734 *:retu* *:return* *E133*
2735:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
2736 evaluated and returned as the result of the function.
2737 If "[expr]" is not given, the number 0 is returned.
2738 When a function ends without an explicit ":return",
2739 the number 0 is returned.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002740 In a :def function *E1095* is given if unreachable
2741 code follows after the `:return`.
2742 In legacy script there is no check for unreachable
2743 lines, thus there is no warning if commands follow
2744 `:return`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002745
2746 If the ":return" is used after a |:try| but before the
2747 matching |:finally| (if present), the commands
2748 following the ":finally" up to the matching |:endtry|
2749 are executed first. This process applies to all
2750 nested ":try"s inside the function. The function
2751 returns at the outermost ":endtry".
2752
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002753 *function-argument* *a:var*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002754An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002755be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002756 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002757Up to 20 arguments can be given, separated by commas. After the named
2758arguments an argument "..." can be specified, which means that more arguments
2759may optionally be following. In the function the extra arguments can be used
2760as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002761can be 0). "a:000" is set to a |List| that contains these arguments. Note
2762that "a:1" is the same as "a:000[0]".
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002763 *E742* *E1090*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00002764The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaar069c1e72016-07-15 21:25:08 +02002765However, if a composite type is used, such as |List| or |Dictionary| , you can
2766change their contents. Thus you can pass a |List| to a function and have the
2767function add an item to it. If you want to make sure the function cannot
2768change a |List| or |Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002769
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002770It is also possible to define a function without any arguments. You must
Bram Moolenaar01164a62017-11-02 22:58:42 +01002771still supply the () then.
2772
Bram Moolenaar98ef2332018-03-18 14:44:37 +01002773It is allowed to define another function inside a function body.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002774
Bram Moolenaar42ae78c2019-05-09 21:08:58 +02002775 *optional-function-argument*
2776You can provide default values for positional named arguments. This makes
2777them optional for function calls. When a positional argument is not
2778specified at a call, the default expression is used to initialize it.
Bram Moolenaard1caa942020-04-10 22:10:56 +02002779This only works for functions declared with `:function` or `:def`, not for
2780lambda expressions |expr-lambda|.
Bram Moolenaar42ae78c2019-05-09 21:08:58 +02002781
2782Example: >
2783 function Something(key, value = 10)
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02002784 echo a:key .. ": " .. a:value
Bram Moolenaar42ae78c2019-05-09 21:08:58 +02002785 endfunction
2786 call Something('empty') "empty: 10"
Bram Moolenaar8aad88d2019-05-12 13:53:50 +02002787 call Something('key', 20) "key: 20"
Bram Moolenaar42ae78c2019-05-09 21:08:58 +02002788
2789The argument default expressions are evaluated at the time of the function
2790call, not definition. Thus it is possible to use an expression which is
Bram Moolenaar68e65602019-05-26 21:33:31 +02002791invalid the moment the function is defined. The expressions are also only
Bram Moolenaar42ae78c2019-05-09 21:08:58 +02002792evaluated when arguments are not specified during a call.
Bram Moolenaar2547aa92020-07-26 17:00:44 +02002793 *none-function_argument*
Bram Moolenaar42ae78c2019-05-09 21:08:58 +02002794You can pass |v:none| to use the default expression. Note that this means you
2795cannot pass v:none as an ordinary value when an argument has a default
2796expression.
2797
2798Example: >
2799 function Something(a = 10, b = 20, c = 30)
2800 endfunction
2801 call Something(1, v:none, 3) " b = 20
2802<
2803 *E989*
2804Optional arguments with default expressions must occur after any mandatory
2805arguments. You can use "..." after all optional named arguments.
2806
2807It is possible for later argument defaults to refer to prior arguments,
2808but not the other way around. They must be prefixed with "a:", as with all
2809arguments.
2810
2811Example that works: >
2812 :function Okay(mandatory, optional = a:mandatory)
2813 :endfunction
2814Example that does NOT work: >
2815 :function NoGood(first = a:second, second = 10)
2816 :endfunction
2817<
Bram Moolenaard1caa942020-04-10 22:10:56 +02002818When not using "...", the number of arguments in a function call must be at
2819least equal to the number of mandatory named arguments. When using "...", the
2820number of arguments may be larger than the total of mandatory and optional
2821arguments.
Bram Moolenaar42ae78c2019-05-09 21:08:58 +02002822
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002823 *local-variables*
Bram Moolenaar069c1e72016-07-15 21:25:08 +02002824Inside a function local variables can be used. These will disappear when the
2825function returns. Global variables need to be accessed with "g:".
Bram Moolenaar071d4272004-06-13 20:20:40 +00002826
2827Example: >
2828 :function Table(title, ...)
2829 : echohl Title
2830 : echo a:title
2831 : echohl None
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002832 : echo a:0 .. " items:"
Bram Moolenaar677ee682005-01-27 14:41:15 +00002833 : for s in a:000
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002834 : echon ' ' .. s
Bram Moolenaar677ee682005-01-27 14:41:15 +00002835 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +00002836 :endfunction
2837
2838This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +00002839 call Table("Table", "line1", "line2")
2840 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002841
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002842To return more than one value, return a |List|: >
2843 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002844 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002845 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +00002846 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002847 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +00002848 :endfunction
2849
2850This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002851 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002852 :if success == "ok"
2853 : echo div
2854 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002855<
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00002856 *:cal* *:call* *E107*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002857:[range]cal[l] {name}([arguments])
2858 Call a function. The name of the function and its arguments
Bram Moolenaar68e65602019-05-26 21:33:31 +02002859 are as specified with `:function`. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002860 used. The returned value is discarded.
Bram Moolenaar5da36052021-12-27 15:39:57 +00002861 In |Vim9| script using `:call` is optional, these two lines do
2862 the same thing: >
2863 call SomeFunc(arg)
2864 SomeFunc(arg)
2865< Without a range and for functions that accept a range, the
Bram Moolenaar071d4272004-06-13 20:20:40 +00002866 function is called once. When a range is given the cursor is
2867 positioned at the start of the first line before executing the
2868 function.
2869 When a range is given and the function doesn't handle it
2870 itself, the function is executed for each line in the range,
2871 with the cursor in the first column of that line. The cursor
2872 is left at the last line (possibly moved by the last function
Bram Moolenaar58b85342016-08-14 19:54:54 +02002873 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +00002874 this works:
2875 *function-range-example* >
2876 :function Mynumber(arg)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002877 : echo line(".") .. " " .. a:arg
Bram Moolenaar071d4272004-06-13 20:20:40 +00002878 :endfunction
2879 :1,5call Mynumber(getline("."))
2880<
2881 The "a:firstline" and "a:lastline" are defined anyway, they
2882 can be used to do something different at the start or end of
2883 the range.
2884
2885 Example of a function that handles the range itself: >
2886
2887 :function Cont() range
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002888 : execute (a:firstline + 1) .. "," .. a:lastline .. 's/^/\t\\ '
Bram Moolenaar071d4272004-06-13 20:20:40 +00002889 :endfunction
2890 :4,8call Cont()
2891<
2892 This function inserts the continuation character "\" in front
2893 of all the lines in the range, except the first one.
2894
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002895 When the function returns a composite value it can be further
2896 dereferenced, but the range will not be used then. Example: >
2897 :4,8call GetDict().method()
2898< Here GetDict() gets the range but method() does not.
2899
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00002900 *E117*
2901When a function cannot be found the error "E117: Unknown function" will be
2902given. If the function was using an autoload path or an autoload import and
2903the script is a |Vim9| script, this may also be caused by the function not
2904being exported.
2905
Bram Moolenaar071d4272004-06-13 20:20:40 +00002906 *E132*
2907The recursiveness of user functions is restricted with the |'maxfuncdepth'|
2908option.
2909
Bram Moolenaar25e42232019-08-04 15:04:10 +02002910It is also possible to use `:eval`. It does not support a range, but does
2911allow for method chaining, e.g.: >
2912 eval GetList()->Filter()->append('$')
2913
Bram Moolenaar088e8e32019-08-08 22:15:18 +02002914A function can also be called as part of evaluating an expression or when it
2915is used as a method: >
2916 let x = GetList()
2917 let y = GetList()->Filter()
2918
Bram Moolenaar7c626922005-02-07 22:01:03 +00002919
2920AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00002921 *autoload-functions*
2922When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +00002923only when they are used. There are two methods: with an autocommand and with
2924the "autoload" directory in 'runtimepath'.
2925
2926
2927Using an autocommand ~
2928
Bram Moolenaar05159a02005-02-26 23:04:13 +00002929This is introduced in the user manual, section |41.14|.
2930
Bram Moolenaar7c626922005-02-07 22:01:03 +00002931The autocommand is useful if you have a plugin that is a long Vim script file.
Bram Moolenaar68e65602019-05-26 21:33:31 +02002932You can define the autocommand and quickly quit the script with `:finish`.
Bram Moolenaar58b85342016-08-14 19:54:54 +02002933That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar68e65602019-05-26 21:33:31 +02002934again, setting a variable to skip the `:finish` command.
Bram Moolenaar7c626922005-02-07 22:01:03 +00002935
2936Use the FuncUndefined autocommand event with a pattern that matches the
2937function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002938
2939 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
2940
2941The file "~/vim/bufnetfuncs.vim" should then define functions that start with
2942"BufNet". Also see |FuncUndefined|.
2943
Bram Moolenaar7c626922005-02-07 22:01:03 +00002944
2945Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002946 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +00002947This is introduced in the user manual, section |41.15|.
2948
Bram Moolenaar7c626922005-02-07 22:01:03 +00002949Using a script in the "autoload" directory is simpler, but requires using
2950exactly the right file name. A function that can be autoloaded has a name
2951like this: >
2952
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002953 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00002954
Bram Moolenaar65e0d772020-06-14 17:29:55 +02002955These functions are always global, in Vim9 script "g:" needs to be used: >
2956 :call g:filename#funcname()
2957
Bram Moolenaar7c626922005-02-07 22:01:03 +00002958When such a function is called, and it is not defined yet, Vim will search the
2959"autoload" directories in 'runtimepath' for a script file called
2960"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
2961then define the function like this: >
2962
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002963 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00002964 echo "Done!"
2965 endfunction
2966
Bram Moolenaar60a795a2005-09-16 21:55:43 +00002967The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +00002968exactly, and the defined function must have the name exactly as it will be
Bram Moolenaar65e0d772020-06-14 17:29:55 +02002969called. In Vim9 script the "g:" prefix must be used: >
2970 function g:filename#funcname()
2971
2972or for a compiled function: >
2973 def g:filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +00002974
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002975It is possible to use subdirectories. Every # in the function name works like
2976a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +00002977
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002978 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +00002979
2980Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
2981
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002982This also works when reading a variable that has not been set yet: >
2983
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002984 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002985
Bram Moolenaara5792f52005-11-23 21:25:05 +00002986However, when the autoload script was already loaded it won't be loaded again
2987for an unknown variable.
2988
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002989When assigning a value to such a variable nothing special happens. This can
2990be used to pass settings to the autoload script before it's loaded: >
2991
Bram Moolenaara7fc0102005-05-18 22:17:12 +00002992 :let foo#bar#toggle = 1
2993 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002994
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002995Note that when you make a mistake and call a function that is supposed to be
2996defined in an autoload script, but the script doesn't actually define the
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01002997function, you will get an error message for the missing function. If you fix
2998the autoload script it won't be automatically loaded again. Either restart
2999Vim or manually source the script.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003000
3001Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003002other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00003003Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +00003004
Bram Moolenaar944697a2022-02-20 19:48:20 +00003005In |Vim9| script you will get error *E1263* if you define a function with
3006a "#" character in the name. You should use a name without "#" and use
3007`:export`.
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003008
Bram Moolenaar433f7c82006-03-21 21:29:36 +00003009Hint: If you distribute a bunch of scripts you can pack them together with the
3010|vimball| utility. Also read the user manual |distribute-script|.
3011
Bram Moolenaar071d4272004-06-13 20:20:40 +00003012==============================================================================
30136. Curly braces names *curly-braces-names*
3014
Bram Moolenaar84f72352012-03-11 15:57:40 +01003015In most places where you can use a variable, you can use a "curly braces name"
3016variable. This is a regular variable name with one or more expressions
3017wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003018 my_{adjective}_variable
3019
Bram Moolenaar5da36052021-12-27 15:39:57 +00003020This only works in legacy Vim script, not in |Vim9| script.
3021
Bram Moolenaar071d4272004-06-13 20:20:40 +00003022When Vim encounters this, it evaluates the expression inside the braces, puts
3023that in place of the expression, and re-interprets the whole as a variable
3024name. So in the above example, if the variable "adjective" was set to
3025"noisy", then the reference would be to "my_noisy_variable", whereas if
3026"adjective" was set to "quiet", then it would be to "my_quiet_variable".
3027
3028One application for this is to create a set of variables governed by an option
Bram Moolenaar58b85342016-08-14 19:54:54 +02003029value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003030 echo my_{&background}_message
3031
3032would output the contents of "my_dark_message" or "my_light_message" depending
3033on the current value of 'background'.
3034
3035You can use multiple brace pairs: >
3036 echo my_{adverb}_{adjective}_message
3037..or even nest them: >
3038 echo my_{ad{end_of_word}}_message
3039where "end_of_word" is either "verb" or "jective".
3040
3041However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003042variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003043 :let foo='a + b'
3044 :echo c{foo}d
3045.. since the result of expansion is "ca + bd", which is not a variable name.
3046
3047 *curly-braces-function-names*
3048You can call and define functions by an evaluated name in a similar way.
3049Example: >
3050 :let func_end='whizz'
3051 :call my_func_{func_end}(parameter)
3052
3053This would call the function "my_func_whizz(parameter)".
3054
Bram Moolenaar84f72352012-03-11 15:57:40 +01003055This does NOT work: >
3056 :let i = 3
3057 :let @{i} = '' " error
3058 :echo @{i} " error
3059
Bram Moolenaar071d4272004-06-13 20:20:40 +00003060==============================================================================
30617. Commands *expression-commands*
3062
Bram Moolenaar5da36052021-12-27 15:39:57 +00003063Note: in |Vim9| script `:let` is not used. `:var` is used for variable
3064declarations and assignments do not use a command. |vim9-declaration|
Bram Moolenaar65e0d772020-06-14 17:29:55 +02003065
Bram Moolenaar071d4272004-06-13 20:20:40 +00003066:let {var-name} = {expr1} *:let* *E18*
3067 Set internal variable {var-name} to the result of the
3068 expression {expr1}. The variable will get the type
3069 from the {expr}. If {var-name} didn't exist yet, it
3070 is created.
3071
Bram Moolenaarf10911e2022-01-29 22:20:48 +00003072:let {var-name}[{idx}] = {expr1} *E689* *E1141*
Bram Moolenaar13065c42005-01-08 16:08:21 +00003073 Set a list item to the result of the expression
3074 {expr1}. {var-name} must refer to a list and {idx}
3075 must be a valid index in that list. For nested list
3076 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003077 This cannot be used to add an item to a |List|.
Bram Moolenaar58b85342016-08-14 19:54:54 +02003078 This cannot be used to set a byte in a String. You
Bram Moolenaar446cb832008-06-24 21:56:24 +00003079 can do that like this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003080 :let var = var[0:2] .. 'X' .. var[4:]
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003081< When {var-name} is a |Blob| then {idx} can be the
3082 length of the blob, in which case one byte is
3083 appended.
3084
Bram Moolenaara2baa732022-02-04 16:09:54 +00003085 *E711* *E719* *E1165* *E1166* *E1183*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003086:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003087 Set a sequence of items in a |List| to the result of
3088 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003089 correct number of items.
3090 {idx1} can be omitted, zero is used instead.
3091 {idx2} can be omitted, meaning the end of the list.
3092 When the selected range of items is partly past the
3093 end of the list, items will be added.
3094
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003095 *:let+=* *:let-=* *:letstar=* *:let/=* *:let%=*
3096 *:let.=* *:let..=* *E734* *E985* *E1019*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003097:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
3098:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
Bram Moolenaarff697e62019-02-12 22:28:33 +01003099:let {var} *= {expr1} Like ":let {var} = {var} * {expr1}".
3100:let {var} /= {expr1} Like ":let {var} = {var} / {expr1}".
3101:let {var} %= {expr1} Like ":let {var} = {var} % {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003102:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02003103:let {var} ..= {expr1} Like ":let {var} = {var} .. {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003104 These fail if {var} was not set yet and when the type
3105 of {var} and {expr1} don't fit the operator.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02003106 `.=` is not supported with Vim script version 2 and
3107 later, see |vimscript-version|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003108
3109
Bram Moolenaar071d4272004-06-13 20:20:40 +00003110:let ${env-name} = {expr1} *:let-environment* *:let-$*
3111 Set environment variable {env-name} to the result of
3112 the expression {expr1}. The type is always String.
Bram Moolenaar56c860c2019-08-17 20:09:31 +02003113
3114 On some systems making an environment variable empty
3115 causes it to be deleted. Many systems do not make a
3116 difference between an environment variable that is not
3117 set and an environment variable that is empty.
3118
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003119:let ${env-name} .= {expr1}
3120 Append {expr1} to the environment variable {env-name}.
3121 If the environment variable didn't exist yet this
3122 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003123
3124:let @{reg-name} = {expr1} *:let-register* *:let-@*
3125 Write the result of the expression {expr1} in register
3126 {reg-name}. {reg-name} must be a single letter, and
3127 must be the name of a writable register (see
3128 |registers|). "@@" can be used for the unnamed
3129 register, "@/" for the search pattern.
3130 If the result of {expr1} ends in a <CR> or <NL>, the
3131 register will be linewise, otherwise it will be set to
3132 characterwise.
3133 This can be used to clear the last search pattern: >
3134 :let @/ = ""
3135< This is different from searching for an empty string,
3136 that would match everywhere.
3137
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003138:let @{reg-name} .= {expr1}
Bram Moolenaar58b85342016-08-14 19:54:54 +02003139 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003140 register was empty it's like setting it to {expr1}.
3141
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003142:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003143 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00003144 expression {expr1}. A String or Number value is
3145 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003146 For an option local to a window or buffer the effect
3147 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00003148 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00003149 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003150 :let &path = &path .. ',/usr/local/include'
Bram Moolenaar3df01732017-02-17 22:47:16 +01003151< This also works for terminal codes in the form t_xx.
3152 But only for alphanumerical names. Example: >
3153 :let &t_k1 = "\<Esc>[234;"
3154< When the code does not exist yet it will be created as
3155 a terminal key code, there is no error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003156
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003157:let &{option-name} .= {expr1}
3158 For a string option: Append {expr1} to the value.
3159 Does not insert a comma like |:set+=|.
3160
3161:let &{option-name} += {expr1}
3162:let &{option-name} -= {expr1}
3163 For a number or boolean option: Add or subtract
3164 {expr1}.
3165
Bram Moolenaar071d4272004-06-13 20:20:40 +00003166:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003167:let &l:{option-name} .= {expr1}
3168:let &l:{option-name} += {expr1}
3169:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003170 Like above, but only set the local value of an option
3171 (if there is one). Works like |:setlocal|.
3172
3173:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003174:let &g:{option-name} .= {expr1}
3175:let &g:{option-name} += {expr1}
3176:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003177 Like above, but only set the global value of an option
3178 (if there is one). Works like |:setglobal|.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00003179 *E1093*
Bram Moolenaar13065c42005-01-08 16:08:21 +00003180:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003181 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00003182 the list is assigned to {name1}, the second item to
3183 {name2}, etc.
3184 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003185 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00003186 Each name can be one of the items of the ":let"
3187 command as mentioned above.
3188 Example: >
3189 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003190< Detail: {expr1} is evaluated first, then the
3191 assignments are done in sequence. This matters if
3192 {name2} depends on {name1}. Example: >
3193 :let x = [0, 1]
3194 :let i = 0
3195 :let [i, x[i]] = [1, 2]
3196 :echo x
3197< The result is [0, 2].
3198
3199:let [{name1}, {name2}, ...] .= {expr1}
3200:let [{name1}, {name2}, ...] += {expr1}
3201:let [{name1}, {name2}, ...] -= {expr1}
3202 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003203 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00003204
Bram Moolenaard1caa942020-04-10 22:10:56 +02003205:let [{name}, ..., ; {lastname}] = {expr1} *E452*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003206 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003207 items than there are names. A list of the remaining
3208 items is assigned to {lastname}. If there are no
3209 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00003210 Example: >
3211 :let [a, b; rest] = ["aval", "bval", 3, 4]
3212<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003213:let [{name}, ..., ; {lastname}] .= {expr1}
3214:let [{name}, ..., ; {lastname}] += {expr1}
3215:let [{name}, ..., ; {lastname}] -= {expr1}
3216 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003217 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +02003218
Bram Moolenaar24582002019-07-21 14:14:26 +02003219 *:let=<<* *:let-heredoc*
Bram Moolenaarf10911e2022-01-29 22:20:48 +00003220 *E990* *E991* *E172* *E221* *E1145*
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003221:let {var-name} =<< [trim] {endmarker}
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003222text...
3223text...
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003224{endmarker}
Bram Moolenaare46a4402020-06-30 20:38:27 +02003225 Set internal variable {var-name} to a |List|
3226 containing the lines of text bounded by the string
Bram Moolenaaraa970ab2020-08-02 16:10:39 +02003227 {endmarker}. The lines of text is used as a
3228 |literal-string|.
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003229 {endmarker} must not contain white space.
3230 {endmarker} cannot start with a lower case character.
3231 The last line should end only with the {endmarker}
3232 string without any other character. Watch out for
3233 white space after {endmarker}!
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003234
Bram Moolenaare7eb9272019-06-24 00:58:07 +02003235 Without "trim" any white space characters in the lines
3236 of text are preserved. If "trim" is specified before
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003237 {endmarker}, then indentation is stripped so you can
3238 do: >
Bram Moolenaare7eb9272019-06-24 00:58:07 +02003239 let text =<< trim END
3240 if ok
3241 echo 'done'
3242 endif
3243 END
3244< Results in: ["if ok", " echo 'done'", "endif"]
3245 The marker must line up with "let" and the indentation
3246 of the first line is removed from all the text lines.
3247 Specifically: all the leading indentation exactly
3248 matching the leading indentation of the first
3249 non-empty text line is stripped from the input lines.
3250 All leading indentation exactly matching the leading
3251 indentation before `let` is stripped from the line
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003252 containing {endmarker}. Note that the difference
3253 between space and tab matters here.
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003254
3255 If {var-name} didn't exist yet, it is created.
3256 Cannot be followed by another command, but can be
3257 followed by a comment.
3258
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003259 To avoid line continuation to be applied, consider
3260 adding 'C' to 'cpoptions': >
3261 set cpo+=C
3262 let var =<< END
3263 \ leading backslash
3264 END
3265 set cpo-=C
3266<
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003267 Examples: >
3268 let var1 =<< END
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003269 Sample text 1
3270 Sample text 2
3271 Sample text 3
3272 END
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003273
3274 let data =<< trim DATA
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003275 1 2 3 4
3276 5 6 7 8
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003277 DATA
3278<
Bram Moolenaar4a748032010-09-30 21:47:56 +02003279 *E121*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003280:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00003281 variable names may be given. Special names recognized
3282 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00003283 g: global variables
3284 b: local buffer variables
3285 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003286 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00003287 s: script-local variables
3288 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00003289 v: Vim variables.
Bram Moolenaar65e0d772020-06-14 17:29:55 +02003290 This does not work in Vim9 script. |vim9-declaration|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003291
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003292:let List the values of all variables. The type of the
3293 variable is indicated before the value:
3294 <nothing> String
3295 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003296 * Funcref
Bram Moolenaar65e0d772020-06-14 17:29:55 +02003297 This does not work in Vim9 script. |vim9-declaration|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003298
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003299:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795* *E1081*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003300 Remove the internal variable {name}. Several variable
3301 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003302 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003303 With [!] no error message is given for non-existing
3304 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003305 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00003306 :unlet list[3] " remove fourth item
3307 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003308< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00003309 :unlet dict['two']
3310 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +00003311< This is especially useful to clean up used global
3312 variables and script-local variables (these are not
3313 deleted when the script ends). Function-local
3314 variables are automatically deleted when the function
3315 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003316
Bram Moolenaar137374f2018-05-13 15:59:50 +02003317:unl[et] ${env-name} ... *:unlet-environment* *:unlet-$*
3318 Remove environment variable {env-name}.
3319 Can mix {name} and ${env-name} in one :unlet command.
3320 No error message is given for a non-existing
3321 variable, also without !.
3322 If the system does not support deleting an environment
Bram Moolenaar9937a052019-06-15 15:45:06 +02003323 variable, it is made empty.
Bram Moolenaar137374f2018-05-13 15:59:50 +02003324
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003325 *:cons* *:const* *E1018*
Bram Moolenaar9937a052019-06-15 15:45:06 +02003326:cons[t] {var-name} = {expr1}
3327:cons[t] [{name1}, {name2}, ...] = {expr1}
Bram Moolenaar9937a052019-06-15 15:45:06 +02003328:cons[t] [{name}, ..., ; {lastname}] = {expr1}
3329:cons[t] {var-name} =<< [trim] {marker}
3330text...
3331text...
3332{marker}
3333 Similar to |:let|, but additionally lock the variable
3334 after setting the value. This is the same as locking
3335 the variable with |:lockvar| just after |:let|, thus: >
3336 :const x = 1
3337< is equivalent to: >
3338 :let x = 1
Bram Moolenaar021bda52020-08-17 21:07:22 +02003339 :lockvar! x
Bram Moolenaara187c432020-09-16 21:08:28 +02003340< NOTE: in Vim9 script `:const` works differently, see
3341 |vim9-const|
3342 This is useful if you want to make sure the variable
Bram Moolenaar021bda52020-08-17 21:07:22 +02003343 is not modified. If the value is a List or Dictionary
3344 literal then the items also cannot be changed: >
3345 const ll = [1, 2, 3]
3346 let ll[1] = 5 " Error!
Bram Moolenaar6e649222021-10-04 21:32:54 +01003347< Nested references are not locked: >
Bram Moolenaar021bda52020-08-17 21:07:22 +02003348 let lvar = ['a']
3349 const lconst = [0, lvar]
3350 let lconst[0] = 2 " Error!
3351 let lconst[1][0] = 'b' " OK
3352< *E995*
Bram Moolenaar9b283522019-06-17 22:19:33 +02003353 |:const| does not allow to for changing a variable: >
Bram Moolenaar9937a052019-06-15 15:45:06 +02003354 :let x = 1
3355 :const x = 2 " Error!
Bram Moolenaar1c196e72019-06-16 15:41:58 +02003356< *E996*
3357 Note that environment variables, option values and
3358 register values cannot be used here, since they cannot
3359 be locked.
3360
Bram Moolenaar85850f32019-07-19 22:05:51 +02003361:cons[t]
3362:cons[t] {var-name}
3363 If no argument is given or only {var-name} is given,
3364 the behavior is the same as |:let|.
3365
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003366:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
3367 Lock the internal variable {name}. Locking means that
3368 it can no longer be changed (until it is unlocked).
3369 A locked variable can be deleted: >
3370 :lockvar v
Bram Moolenaardad44732021-03-31 20:07:33 +02003371 :let v = 'asdf' " fails!
3372 :unlet v " works
Bram Moolenaarf10911e2022-01-29 22:20:48 +00003373< *E741* *E940* *E1118* *E1119* *E1120* *E1121* *E1122*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003374 If you try to change a locked variable you get an
Bram Moolenaare7877fe2017-02-20 22:35:33 +01003375 error message: "E741: Value is locked: {name}".
3376 If you try to lock or unlock a built-in variable you
3377 get an error message: "E940: Cannot lock or unlock
3378 variable {name}".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003379
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003380 [depth] is relevant when locking a |List| or
3381 |Dictionary|. It specifies how deep the locking goes:
Bram Moolenaara187c432020-09-16 21:08:28 +02003382 0 Lock the variable {name} but not its
3383 value.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003384 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003385 cannot add or remove items, but can
3386 still change their values.
3387 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003388 the items. If an item is a |List| or
3389 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003390 items, but can still change the
3391 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003392 3 Like 2 but for the |List| /
3393 |Dictionary| in the |List| /
3394 |Dictionary|, one level deeper.
3395 The default [depth] is 2, thus when {name} is a |List|
3396 or |Dictionary| the values cannot be changed.
Bram Moolenaara187c432020-09-16 21:08:28 +02003397
3398 Example with [depth] 0: >
3399 let mylist = [1, 2, 3]
3400 lockvar 0 mylist
Bram Moolenaar6e649222021-10-04 21:32:54 +01003401 let mylist[0] = 77 " OK
3402 call add(mylist, 4] " OK
Bram Moolenaara187c432020-09-16 21:08:28 +02003403 let mylist = [7, 8, 9] " Error!
3404< *E743*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003405 For unlimited depth use [!] and omit [depth].
3406 However, there is a maximum depth of 100 to catch
3407 loops.
3408
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003409 Note that when two variables refer to the same |List|
3410 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003411 locked when used through the other variable.
3412 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003413 :let l = [0, 1, 2, 3]
3414 :let cl = l
3415 :lockvar l
3416 :let cl[1] = 99 " won't work!
3417< You may want to make a copy of a list to avoid this.
3418 See |deepcopy()|.
3419
3420
Bram Moolenaara2baa732022-02-04 16:09:54 +00003421:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo* *E1246*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003422 Unlock the internal variable {name}. Does the
3423 opposite of |:lockvar|.
3424
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02003425:if {expr1} *:if* *:end* *:endif* *:en* *E171* *E579* *E580*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003426:en[dif] Execute the commands until the next matching ":else"
3427 or ":endif" if {expr1} evaluates to non-zero.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003428 Although the short forms work, it is recommended to
3429 always use `:endif` to avoid confusion.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003430
3431 From Vim version 4.5 until 5.0, every Ex command in
3432 between the ":if" and ":endif" is ignored. These two
3433 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +01003434 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +00003435 that any ":else" or ":elseif" was ignored, the "else"
3436 part was not executed either.
3437
3438 You can use this to remain compatible with older
3439 versions: >
3440 :if version >= 500
3441 : version-5-specific-commands
3442 :endif
3443< The commands still need to be parsed to find the
3444 "endif". Sometimes an older Vim has a problem with a
3445 new command. For example, ":silent" is recognized as
3446 a ":substitute" command. In that case ":execute" can
3447 avoid problems: >
3448 :if version >= 600
3449 : execute "silent 1,$delete"
3450 :endif
3451<
3452 NOTE: The ":append" and ":insert" commands don't work
3453 properly in between ":if" and ":endif".
3454
3455 *:else* *:el* *E581* *E583*
3456:el[se] Execute the commands until the next matching ":else"
3457 or ":endif" if they previously were not being
3458 executed.
3459
3460 *:elseif* *:elsei* *E582* *E584*
3461:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
3462 is no extra ":endif".
3463
3464:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003465 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003466:endw[hile] Repeat the commands between ":while" and ":endwhile",
3467 as long as {expr1} evaluates to non-zero.
3468 When an error is detected from a command inside the
3469 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +00003470 Example: >
3471 :let lnum = 1
3472 :while lnum <= line("$")
3473 :call FixLine(lnum)
3474 :let lnum = lnum + 1
3475 :endwhile
3476<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003477 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +00003478 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003479
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003480:for {var} in {object} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00003481:endfo[r] *:endfo* *:endfor*
3482 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003483 each item in {object}. {object} can be a |List| or
Bram Moolenaara2baa732022-02-04 16:09:54 +00003484 a |Blob|. *E1177*
Bram Moolenaar5da36052021-12-27 15:39:57 +00003485
3486 Variable {var} is set to the value of each item.
3487 In |Vim9| script the loop variable must not have been
3488 declared yet, unless when it is a
3489 global/window/tab/buffer variable.
3490
3491 When an error is detected for a command inside the
3492 loop, execution continues after the "endfor".
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003493 Changing {object} inside the loop affects what items
3494 are used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003495 :for item in copy(mylist)
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003496<
Bram Moolenaar5da36052021-12-27 15:39:57 +00003497 When {object} is a |List| and not making a copy, in
3498 legacy script Vim stores a reference to the next item
3499 in the |List| before executing the commands with the
3500 current item. Thus the current item can be removed
3501 without effect. Removing any later item means it will
3502 not be found. Thus the following example works (an
3503 inefficient way to make a |List| empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003504 for item in mylist
3505 call remove(mylist, 0)
3506 endfor
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003507< Note that reordering the |List| (e.g., with sort() or
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003508 reverse()) may have unexpected effects.
Bram Moolenaar5da36052021-12-27 15:39:57 +00003509 In |Vim9| script the index is used. If an item before
3510 the current one is deleted the next item will be
3511 skipped.
Bram Moolenaar12805862005-01-05 22:16:17 +00003512
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003513 When {object} is a |Blob|, Vim always makes a copy to
3514 iterate over. Unlike with |List|, modifying the
3515 |Blob| does not affect the iteration.
3516
Bram Moolenaar12805862005-01-05 22:16:17 +00003517:for [{var1}, {var2}, ...] in {listlist}
Bram Moolenaarf10911e2022-01-29 22:20:48 +00003518:endfo[r] *E1140*
Bram Moolenaar12805862005-01-05 22:16:17 +00003519 Like ":for" above, but each item in {listlist} must be
3520 a list, of which each item is assigned to {var1},
3521 {var2}, etc. Example: >
3522 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
3523 :echo getline(lnum)[col]
3524 :endfor
3525<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003526 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +00003527:con[tinue] When used inside a ":while" or ":for" loop, jumps back
3528 to the start of the loop.
3529 If it is used after a |:try| inside the loop but
3530 before the matching |:finally| (if present), the
3531 commands following the ":finally" up to the matching
3532 |:endtry| are executed first. This process applies to
3533 all nested ":try"s inside the loop. The outermost
3534 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003535
3536 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +00003537:brea[k] When used inside a ":while" or ":for" loop, skips to
3538 the command after the matching ":endwhile" or
3539 ":endfor".
3540 If it is used after a |:try| inside the loop but
3541 before the matching |:finally| (if present), the
3542 commands following the ":finally" up to the matching
3543 |:endtry| are executed first. This process applies to
3544 all nested ":try"s inside the loop. The outermost
3545 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003546
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003547:try *:try* *:endt* *:endtry*
3548 *E600* *E601* *E602* *E1032*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003549:endt[ry] Change the error handling for the commands between
3550 ":try" and ":endtry" including everything being
3551 executed across ":source" commands, function calls,
3552 or autocommand invocations.
3553
3554 When an error or interrupt is detected and there is
3555 a |:finally| command following, execution continues
3556 after the ":finally". Otherwise, or when the
3557 ":endtry" is reached thereafter, the next
3558 (dynamically) surrounding ":try" is checked for
3559 a corresponding ":finally" etc. Then the script
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01003560 processing is terminated. Whether a function
3561 definition has an "abort" argument does not matter.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003562 Example: >
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01003563 try | call Unknown() | finally | echomsg "cleanup" | endtry
3564 echomsg "not reached"
Bram Moolenaar071d4272004-06-13 20:20:40 +00003565<
3566 Moreover, an error or interrupt (dynamically) inside
3567 ":try" and ":endtry" is converted to an exception. It
3568 can be caught as if it were thrown by a |:throw|
3569 command (see |:catch|). In this case, the script
3570 processing is not terminated.
3571
3572 The value "Vim:Interrupt" is used for an interrupt
3573 exception. An error in a Vim command is converted
3574 to a value of the form "Vim({command}):{errmsg}",
3575 other errors are converted to a value of the form
3576 "Vim:{errmsg}". {command} is the full command name,
3577 and {errmsg} is the message that is displayed if the
3578 error exception is not caught, always beginning with
3579 the error number.
3580 Examples: >
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01003581 try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
3582 try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
Bram Moolenaar071d4272004-06-13 20:20:40 +00003583<
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003584 *:cat* *:catch*
3585 *E603* *E604* *E605* *E654* *E1033*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003586:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003587 |:finally|, or |:endtry| that belongs to the same
3588 |:try| as the ":catch" are executed when an exception
3589 matching {pattern} is being thrown and has not yet
3590 been caught by a previous ":catch". Otherwise, these
3591 commands are skipped.
3592 When {pattern} is omitted all errors are caught.
3593 Examples: >
Bram Moolenaar647e24b2019-03-17 16:39:46 +01003594 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
3595 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
3596 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
3597 :catch /^Vim(write):/ " catch all errors in :write
3598 :catch /^Vim\%((\a\+)\)\=:E123:/ " catch error E123
3599 :catch /my-exception/ " catch user exception
3600 :catch /.*/ " catch everything
3601 :catch " same as /.*/
Bram Moolenaar071d4272004-06-13 20:20:40 +00003602<
3603 Another character can be used instead of / around the
3604 {pattern}, so long as it does not have a special
3605 meaning (e.g., '|' or '"') and doesn't occur inside
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003606 {pattern}. *E1067*
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02003607 Information about the exception is available in
3608 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003609 NOTE: It is not reliable to ":catch" the TEXT of
3610 an error message because it may vary in different
3611 locales.
3612
3613 *:fina* *:finally* *E606* *E607*
3614:fina[lly] The following commands until the matching |:endtry|
3615 are executed whenever the part between the matching
3616 |:try| and the ":finally" is left: either by falling
3617 through to the ":finally" or by a |:continue|,
3618 |:break|, |:finish|, or |:return|, or by an error or
3619 interrupt or exception (see |:throw|).
3620
Bram Moolenaarf10911e2022-01-29 22:20:48 +00003621 *:th* *:throw* *E608* *E1129*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003622:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
3623 If the ":throw" is used after a |:try| but before the
3624 first corresponding |:catch|, commands are skipped
3625 until the first ":catch" matching {expr1} is reached.
3626 If there is no such ":catch" or if the ":throw" is
3627 used after a ":catch" but before the |:finally|, the
3628 commands following the ":finally" (if present) up to
3629 the matching |:endtry| are executed. If the ":throw"
3630 is after the ":finally", commands up to the ":endtry"
3631 are skipped. At the ":endtry", this process applies
3632 again for the next dynamically surrounding ":try"
3633 (which may be found in a calling function or sourcing
3634 script), until a matching ":catch" has been found.
3635 If the exception is not caught, the command processing
3636 is terminated.
3637 Example: >
3638 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +01003639< Note that "catch" may need to be on a separate line
3640 for when an error causes the parsing to skip the whole
3641 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003642
3643 *:ec* *:echo*
3644:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
3645 first {expr1} starts on a new line.
3646 Also see |:comment|.
3647 Use "\n" to start a new line. Use "\r" to move the
3648 cursor to the first column.
3649 Uses the highlighting set by the |:echohl| command.
3650 Cannot be followed by a comment.
3651 Example: >
3652 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003653< *:echo-redraw*
3654 A later redraw may make the message disappear again.
3655 And since Vim mostly postpones redrawing until it's
3656 finished with a sequence of commands this happens
3657 quite often. To avoid that a command from before the
3658 ":echo" causes a redraw afterwards (redraws are often
3659 postponed until you type something), force a redraw
3660 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003661 :new | redraw | echo "there is a new window"
3662<
3663 *:echon*
3664:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
3665 |:comment|.
3666 Uses the highlighting set by the |:echohl| command.
3667 Cannot be followed by a comment.
3668 Example: >
3669 :echon "the value of 'shell' is " &shell
3670<
3671 Note the difference between using ":echo", which is a
3672 Vim command, and ":!echo", which is an external shell
3673 command: >
3674 :!echo % --> filename
3675< The arguments of ":!" are expanded, see |:_%|. >
3676 :!echo "%" --> filename or "filename"
3677< Like the previous example. Whether you see the double
3678 quotes or not depends on your 'shell'. >
3679 :echo % --> nothing
3680< The '%' is an illegal character in an expression. >
3681 :echo "%" --> %
3682< This just echoes the '%' character. >
3683 :echo expand("%") --> filename
3684< This calls the expand() function to expand the '%'.
3685
3686 *:echoh* *:echohl*
3687:echoh[l] {name} Use the highlight group {name} for the following
3688 |:echo|, |:echon| and |:echomsg| commands. Also used
3689 for the |input()| prompt. Example: >
3690 :echohl WarningMsg | echo "Don't panic!" | echohl None
3691< Don't forget to set the group back to "None",
3692 otherwise all following echo's will be highlighted.
3693
3694 *:echom* *:echomsg*
3695:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
3696 message in the |message-history|.
3697 Spaces are placed between the arguments as with the
3698 |:echo| command. But unprintable characters are
3699 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003700 The parsing works slightly different from |:echo|,
3701 more like |:execute|. All the expressions are first
3702 evaluated and concatenated before echoing anything.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +01003703 If expressions does not evaluate to a Number or
3704 String, string() is used to turn it into a string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003705 Uses the highlighting set by the |:echohl| command.
3706 Example: >
3707 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003708< See |:echo-redraw| to avoid the message disappearing
3709 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003710 *:echoe* *:echoerr*
3711:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
3712 message in the |message-history|. When used in a
3713 script or function the line number will be added.
3714 Spaces are placed between the arguments as with the
Bram Moolenaar461a7fc2018-12-22 13:28:07 +01003715 |:echomsg| command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003716 the message is raised as an error exception instead
3717 (see |try-echoerr|).
3718 Example: >
3719 :echoerr "This script just failed!"
3720< If you just want a highlighted message use |:echohl|.
3721 And to get a beep: >
3722 :exe "normal \<Esc>"
Bram Moolenaar4c868302021-03-22 16:19:45 +01003723
3724:echoc[onsole] {expr1} .. *:echoc* *:echoconsole*
3725 Intended for testing: works like `:echomsg` but when
3726 running in the GUI and started from a terminal write
3727 the text to stdout.
3728
Bram Moolenaar09c6f262019-11-17 15:55:14 +01003729 *:eval*
3730:eval {expr} Evaluate {expr} and discard the result. Example: >
3731 :eval Getlist()->Filter()->append('$')
3732
3733< The expression is supposed to have a side effect,
3734 since the resulting value is not used. In the example
3735 the `append()` call appends the List with text to the
3736 buffer. This is similar to `:call` but works with any
3737 expression.
Bram Moolenaara2baa732022-02-04 16:09:54 +00003738 In |Vim9| script an expression without an effect will
3739 result in error *E1207* . This should help noticing
3740 mistakes.
Bram Moolenaar09c6f262019-11-17 15:55:14 +01003741
3742 The command can be shortened to `:ev` or `:eva`, but
3743 these are hard to recognize and therefore not to be
3744 used.
3745
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01003746 The command cannot be followed by "|" and another
3747 command, since "|" is seen as part of the expression.
3748
Bram Moolenaar09c6f262019-11-17 15:55:14 +01003749
Bram Moolenaar071d4272004-06-13 20:20:40 +00003750 *:exe* *:execute*
3751:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +02003752 of {expr1} as an Ex command.
3753 Multiple arguments are concatenated, with a space in
Bram Moolenaar7e6a5152021-01-02 16:39:53 +01003754 between. To avoid the extra space use the ".."
Bram Moolenaar00a927d2010-05-14 23:24:24 +02003755 operator to concatenate strings into one argument.
3756 {expr1} is used as the processed command, command line
3757 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003758 Cannot be followed by a comment.
3759 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +02003760 :execute "buffer" nextbuf
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01003761 :execute "normal" count .. "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +00003762<
3763 ":execute" can be used to append a command to commands
3764 that don't accept a '|'. Example: >
3765 :execute '!ls' | echo "theend"
3766
3767< ":execute" is also a nice way to avoid having to type
3768 control characters in a Vim script for a ":normal"
3769 command: >
3770 :execute "normal ixxx\<Esc>"
3771< This has an <Esc> character, see |expr-string|.
3772
Bram Moolenaar446cb832008-06-24 21:56:24 +00003773 Be careful to correctly escape special characters in
3774 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +00003775 for Vim commands, |shellescape()| for |:!| commands.
3776 Examples: >
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01003777 :execute "e " .. fnameescape(filename)
3778 :execute "!ls " .. shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +00003779<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003780 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01003781 starting or ending "if", "while" and "for" does not
3782 always work, because when commands are skipped the
3783 ":execute" is not evaluated and Vim loses track of
3784 where blocks start and end. Also "break" and
3785 "continue" should not be inside ":execute".
3786 This example does not work, because the ":execute" is
3787 not evaluated and Vim does not see the "while", and
3788 gives an error for finding an ":endwhile": >
3789 :if 0
3790 : execute 'while i > 5'
3791 : echo "test"
3792 : endwhile
3793 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00003794<
3795 It is allowed to have a "while" or "if" command
3796 completely in the executed string: >
3797 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
3798<
3799
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003800 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003801 ":execute", ":echo" and ":echon" cannot be followed by
3802 a comment directly, because they see the '"' as the
3803 start of a string. But, you can use '|' followed by a
3804 comment. Example: >
3805 :echo "foo" | "this is a comment
3806
3807==============================================================================
38088. Exception handling *exception-handling*
3809
3810The Vim script language comprises an exception handling feature. This section
3811explains how it can be used in a Vim script.
3812
3813Exceptions may be raised by Vim on an error or on interrupt, see
3814|catch-errors| and |catch-interrupt|. You can also explicitly throw an
3815exception by using the ":throw" command, see |throw-catch|.
3816
3817
3818TRY CONDITIONALS *try-conditionals*
3819
3820Exceptions can be caught or can cause cleanup code to be executed. You can
3821use a try conditional to specify catch clauses (that catch exceptions) and/or
3822a finally clause (to be executed for cleanup).
3823 A try conditional begins with a |:try| command and ends at the matching
3824|:endtry| command. In between, you can use a |:catch| command to start
3825a catch clause, or a |:finally| command to start a finally clause. There may
3826be none or multiple catch clauses, but there is at most one finally clause,
3827which must not be followed by any catch clauses. The lines before the catch
3828clauses and the finally clause is called a try block. >
3829
3830 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +00003831 : ...
3832 : ... TRY BLOCK
3833 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00003834 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00003835 : ...
3836 : ... CATCH CLAUSE
3837 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00003838 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00003839 : ...
3840 : ... CATCH CLAUSE
3841 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00003842 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +00003843 : ...
3844 : ... FINALLY CLAUSE
3845 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00003846 :endtry
3847
3848The try conditional allows to watch code for exceptions and to take the
3849appropriate actions. Exceptions from the try block may be caught. Exceptions
3850from the try block and also the catch clauses may cause cleanup actions.
3851 When no exception is thrown during execution of the try block, the control
3852is transferred to the finally clause, if present. After its execution, the
3853script continues with the line following the ":endtry".
3854 When an exception occurs during execution of the try block, the remaining
3855lines in the try block are skipped. The exception is matched against the
3856patterns specified as arguments to the ":catch" commands. The catch clause
3857after the first matching ":catch" is taken, other catch clauses are not
3858executed. The catch clause ends when the next ":catch", ":finally", or
3859":endtry" command is reached - whatever is first. Then, the finally clause
3860(if present) is executed. When the ":endtry" is reached, the script execution
3861continues in the following line as usual.
3862 When an exception that does not match any of the patterns specified by the
3863":catch" commands is thrown in the try block, the exception is not caught by
3864that try conditional and none of the catch clauses is executed. Only the
3865finally clause, if present, is taken. The exception pends during execution of
3866the finally clause. It is resumed at the ":endtry", so that commands after
3867the ":endtry" are not executed and the exception might be caught elsewhere,
3868see |try-nesting|.
3869 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar58b85342016-08-14 19:54:54 +02003870remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003871not matched against the patterns in any of the ":catch" commands of the same
3872try conditional and none of its catch clauses is taken. If there is, however,
3873a finally clause, it is executed, and the exception pends during its
3874execution. The commands following the ":endtry" are not executed. The new
3875exception might, however, be caught elsewhere, see |try-nesting|.
3876 When during execution of the finally clause (if present) an exception is
Bram Moolenaar58b85342016-08-14 19:54:54 +02003877thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00003878clause has been taken because of an exception from the try block or one of the
3879catch clauses, the original (pending) exception is discarded. The commands
3880following the ":endtry" are not executed, and the exception from the finally
3881clause is propagated and can be caught elsewhere, see |try-nesting|.
3882
3883The finally clause is also executed, when a ":break" or ":continue" for
3884a ":while" loop enclosing the complete try conditional is executed from the
3885try block or a catch clause. Or when a ":return" or ":finish" is executed
3886from the try block or a catch clause of a try conditional in a function or
3887sourced script, respectively. The ":break", ":continue", ":return", or
3888":finish" pends during execution of the finally clause and is resumed when the
3889":endtry" is reached. It is, however, discarded when an exception is thrown
3890from the finally clause.
3891 When a ":break" or ":continue" for a ":while" loop enclosing the complete
3892try conditional or when a ":return" or ":finish" is encountered in the finally
3893clause, the rest of the finally clause is skipped, and the ":break",
3894":continue", ":return" or ":finish" is executed as usual. If the finally
3895clause has been taken because of an exception or an earlier ":break",
3896":continue", ":return", or ":finish" from the try block or a catch clause,
3897this pending exception or command is discarded.
3898
3899For examples see |throw-catch| and |try-finally|.
3900
3901
3902NESTING OF TRY CONDITIONALS *try-nesting*
3903
3904Try conditionals can be nested arbitrarily. That is, a complete try
3905conditional can be put into the try block, a catch clause, or the finally
3906clause of another try conditional. If the inner try conditional does not
3907catch an exception thrown in its try block or throws a new exception from one
3908of its catch clauses or its finally clause, the outer try conditional is
3909checked according to the rules above. If the inner try conditional is in the
3910try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar58b85342016-08-14 19:54:54 +02003911otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +00003912nesting, whether the inner try conditional is directly contained in the outer
3913one, or whether the outer one sources a script or calls a function containing
3914the inner try conditional.
3915
3916When none of the active try conditionals catches an exception, just their
3917finally clauses are executed. Thereafter, the script processing terminates.
3918An error message is displayed in case of an uncaught exception explicitly
3919thrown by a ":throw" command. For uncaught error and interrupt exceptions
3920implicitly raised by Vim, the error message(s) or interrupt message are shown
3921as usual.
3922
3923For examples see |throw-catch|.
3924
3925
3926EXAMINING EXCEPTION HANDLING CODE *except-examine*
3927
3928Exception handling code can get tricky. If you are in doubt what happens, set
3929'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
3930script file. Then you see when an exception is thrown, discarded, caught, or
3931finished. When using a verbosity level of at least 14, things pending in
3932a finally clause are also shown. This information is also given in debug mode
3933(see |debug-scripts|).
3934
3935
3936THROWING AND CATCHING EXCEPTIONS *throw-catch*
3937
3938You can throw any number or string as an exception. Use the |:throw| command
3939and pass the value to be thrown as argument: >
3940 :throw 4711
3941 :throw "string"
3942< *throw-expression*
3943You can also specify an expression argument. The expression is then evaluated
3944first, and the result is thrown: >
3945 :throw 4705 + strlen("string")
3946 :throw strpart("strings", 0, 6)
3947
3948An exception might be thrown during evaluation of the argument of the ":throw"
3949command. Unless it is caught there, the expression evaluation is abandoned.
3950The ":throw" command then does not throw a new exception.
3951 Example: >
3952
3953 :function! Foo(arg)
3954 : try
3955 : throw a:arg
3956 : catch /foo/
3957 : endtry
3958 : return 1
3959 :endfunction
3960 :
3961 :function! Bar()
3962 : echo "in Bar"
3963 : return 4710
3964 :endfunction
3965 :
3966 :throw Foo("arrgh") + Bar()
3967
3968This throws "arrgh", and "in Bar" is not displayed since Bar() is not
3969executed. >
3970 :throw Foo("foo") + Bar()
3971however displays "in Bar" and throws 4711.
3972
3973Any other command that takes an expression as argument might also be
Bram Moolenaar58b85342016-08-14 19:54:54 +02003974abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00003975exception is then propagated to the caller of the command.
3976 Example: >
3977
3978 :if Foo("arrgh")
3979 : echo "then"
3980 :else
3981 : echo "else"
3982 :endif
3983
3984Here neither of "then" or "else" is displayed.
3985
3986 *catch-order*
3987Exceptions can be caught by a try conditional with one or more |:catch|
3988commands, see |try-conditionals|. The values to be caught by each ":catch"
3989command can be specified as a pattern argument. The subsequent catch clause
3990gets executed when a matching exception is caught.
3991 Example: >
3992
3993 :function! Foo(value)
3994 : try
3995 : throw a:value
3996 : catch /^\d\+$/
3997 : echo "Number thrown"
3998 : catch /.*/
3999 : echo "String thrown"
4000 : endtry
4001 :endfunction
4002 :
4003 :call Foo(0x1267)
4004 :call Foo('string')
4005
4006The first call to Foo() displays "Number thrown", the second "String thrown".
4007An exception is matched against the ":catch" commands in the order they are
4008specified. Only the first match counts. So you should place the more
4009specific ":catch" first. The following order does not make sense: >
4010
4011 : catch /.*/
4012 : echo "String thrown"
4013 : catch /^\d\+$/
4014 : echo "Number thrown"
4015
4016The first ":catch" here matches always, so that the second catch clause is
4017never taken.
4018
4019 *throw-variables*
4020If you catch an exception by a general pattern, you may access the exact value
4021in the variable |v:exception|: >
4022
4023 : catch /^\d\+$/
4024 : echo "Number thrown. Value is" v:exception
4025
4026You may also be interested where an exception was thrown. This is stored in
4027|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
4028exception most recently caught as long it is not finished.
4029 Example: >
4030
4031 :function! Caught()
4032 : if v:exception != ""
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004033 : echo 'Caught "' . v:exception .. '" in ' .. v:throwpoint
Bram Moolenaar071d4272004-06-13 20:20:40 +00004034 : else
4035 : echo 'Nothing caught'
4036 : endif
4037 :endfunction
4038 :
4039 :function! Foo()
4040 : try
4041 : try
4042 : try
4043 : throw 4711
4044 : finally
4045 : call Caught()
4046 : endtry
4047 : catch /.*/
4048 : call Caught()
4049 : throw "oops"
4050 : endtry
4051 : catch /.*/
4052 : call Caught()
4053 : finally
4054 : call Caught()
4055 : endtry
4056 :endfunction
4057 :
4058 :call Foo()
4059
4060This displays >
4061
4062 Nothing caught
4063 Caught "4711" in function Foo, line 4
4064 Caught "oops" in function Foo, line 10
4065 Nothing caught
4066
4067A practical example: The following command ":LineNumber" displays the line
4068number in the script or function where it has been used: >
4069
4070 :function! LineNumber()
4071 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
4072 :endfunction
4073 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
4074<
4075 *try-nested*
4076An exception that is not caught by a try conditional can be caught by
4077a surrounding try conditional: >
4078
4079 :try
4080 : try
4081 : throw "foo"
4082 : catch /foobar/
4083 : echo "foobar"
4084 : finally
4085 : echo "inner finally"
4086 : endtry
4087 :catch /foo/
4088 : echo "foo"
4089 :endtry
4090
4091The inner try conditional does not catch the exception, just its finally
4092clause is executed. The exception is then caught by the outer try
4093conditional. The example displays "inner finally" and then "foo".
4094
4095 *throw-from-catch*
4096You can catch an exception and throw a new one to be caught elsewhere from the
4097catch clause: >
4098
4099 :function! Foo()
4100 : throw "foo"
4101 :endfunction
4102 :
4103 :function! Bar()
4104 : try
4105 : call Foo()
4106 : catch /foo/
4107 : echo "Caught foo, throw bar"
4108 : throw "bar"
4109 : endtry
4110 :endfunction
4111 :
4112 :try
4113 : call Bar()
4114 :catch /.*/
4115 : echo "Caught" v:exception
4116 :endtry
4117
4118This displays "Caught foo, throw bar" and then "Caught bar".
4119
4120 *rethrow*
4121There is no real rethrow in the Vim script language, but you may throw
4122"v:exception" instead: >
4123
4124 :function! Bar()
4125 : try
4126 : call Foo()
4127 : catch /.*/
4128 : echo "Rethrow" v:exception
4129 : throw v:exception
4130 : endtry
4131 :endfunction
4132< *try-echoerr*
4133Note that this method cannot be used to "rethrow" Vim error or interrupt
4134exceptions, because it is not possible to fake Vim internal exceptions.
4135Trying so causes an error exception. You should throw your own exception
4136denoting the situation. If you want to cause a Vim error exception containing
4137the original error exception value, you can use the |:echoerr| command: >
4138
4139 :try
4140 : try
4141 : asdf
4142 : catch /.*/
4143 : echoerr v:exception
4144 : endtry
4145 :catch /.*/
4146 : echo v:exception
4147 :endtry
4148
4149This code displays
4150
Bram Moolenaar446cb832008-06-24 21:56:24 +00004151 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004152
4153
4154CLEANUP CODE *try-finally*
4155
4156Scripts often change global settings and restore them at their end. If the
4157user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar58b85342016-08-14 19:54:54 +02004158an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +00004159a script when an error occurs or you explicitly throw an exception without
4160catching it. You can solve these problems by using a try conditional with
4161a finally clause for restoring the settings. Its execution is guaranteed on
4162normal control flow, on error, on an explicit ":throw", and on interrupt.
4163(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar58b85342016-08-14 19:54:54 +02004164to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00004165clause has been executed.)
4166Example: >
4167
4168 :try
4169 : let s:saved_ts = &ts
4170 : set ts=17
4171 :
4172 : " Do the hard work here.
4173 :
4174 :finally
4175 : let &ts = s:saved_ts
4176 : unlet s:saved_ts
4177 :endtry
4178
4179This method should be used locally whenever a function or part of a script
4180changes global settings which need to be restored on failure or normal exit of
4181that function or script part.
4182
4183 *break-finally*
4184Cleanup code works also when the try block or a catch clause is left by
4185a ":continue", ":break", ":return", or ":finish".
4186 Example: >
4187
4188 :let first = 1
4189 :while 1
4190 : try
4191 : if first
4192 : echo "first"
4193 : let first = 0
4194 : continue
4195 : else
4196 : throw "second"
4197 : endif
4198 : catch /.*/
4199 : echo v:exception
4200 : break
4201 : finally
4202 : echo "cleanup"
4203 : endtry
4204 : echo "still in while"
4205 :endwhile
4206 :echo "end"
4207
4208This displays "first", "cleanup", "second", "cleanup", and "end". >
4209
4210 :function! Foo()
4211 : try
4212 : return 4711
4213 : finally
4214 : echo "cleanup\n"
4215 : endtry
4216 : echo "Foo still active"
4217 :endfunction
4218 :
4219 :echo Foo() "returned by Foo"
4220
4221This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar58b85342016-08-14 19:54:54 +02004222extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004223return value.)
4224
4225 *except-from-finally*
4226Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
4227a finally clause is possible, but not recommended since it abandons the
4228cleanup actions for the try conditional. But, of course, interrupt and error
4229exceptions might get raised from a finally clause.
4230 Example where an error in the finally clause stops an interrupt from
4231working correctly: >
4232
4233 :try
4234 : try
4235 : echo "Press CTRL-C for interrupt"
4236 : while 1
4237 : endwhile
4238 : finally
4239 : unlet novar
4240 : endtry
4241 :catch /novar/
4242 :endtry
4243 :echo "Script still running"
4244 :sleep 1
4245
4246If you need to put commands that could fail into a finally clause, you should
4247think about catching or ignoring the errors in these commands, see
4248|catch-errors| and |ignore-errors|.
4249
4250
4251CATCHING ERRORS *catch-errors*
4252
4253If you want to catch specific errors, you just have to put the code to be
4254watched in a try block and add a catch clause for the error message. The
4255presence of the try conditional causes all errors to be converted to an
4256exception. No message is displayed and |v:errmsg| is not set then. To find
4257the right pattern for the ":catch" command, you have to know how the format of
4258the error exception is.
4259 Error exceptions have the following format: >
4260
4261 Vim({cmdname}):{errmsg}
4262or >
4263 Vim:{errmsg}
4264
4265{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar58b85342016-08-14 19:54:54 +02004266the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +00004267when the error occurs outside try conditionals. It always begins with
4268a capital "E", followed by a two or three-digit error number, a colon, and
4269a space.
4270
4271Examples:
4272
4273The command >
4274 :unlet novar
4275normally produces the error message >
4276 E108: No such variable: "novar"
4277which is converted inside try conditionals to an exception >
4278 Vim(unlet):E108: No such variable: "novar"
4279
4280The command >
4281 :dwim
4282normally produces the error message >
4283 E492: Not an editor command: dwim
4284which is converted inside try conditionals to an exception >
4285 Vim:E492: Not an editor command: dwim
4286
4287You can catch all ":unlet" errors by a >
4288 :catch /^Vim(unlet):/
4289or all errors for misspelled command names by a >
4290 :catch /^Vim:E492:/
4291
4292Some error messages may be produced by different commands: >
4293 :function nofunc
4294and >
4295 :delfunction nofunc
4296both produce the error message >
4297 E128: Function name must start with a capital: nofunc
4298which is converted inside try conditionals to an exception >
4299 Vim(function):E128: Function name must start with a capital: nofunc
4300or >
4301 Vim(delfunction):E128: Function name must start with a capital: nofunc
4302respectively. You can catch the error by its number independently on the
4303command that caused it if you use the following pattern: >
4304 :catch /^Vim(\a\+):E128:/
4305
4306Some commands like >
4307 :let x = novar
4308produce multiple error messages, here: >
4309 E121: Undefined variable: novar
4310 E15: Invalid expression: novar
4311Only the first is used for the exception value, since it is the most specific
4312one (see |except-several-errors|). So you can catch it by >
4313 :catch /^Vim(\a\+):E121:/
4314
4315You can catch all errors related to the name "nofunc" by >
4316 :catch /\<nofunc\>/
4317
4318You can catch all Vim errors in the ":write" and ":read" commands by >
4319 :catch /^Vim(\(write\|read\)):E\d\+:/
4320
4321You can catch all Vim errors by the pattern >
4322 :catch /^Vim\((\a\+)\)\=:E\d\+:/
4323<
4324 *catch-text*
4325NOTE: You should never catch the error message text itself: >
4326 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01004327only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +00004328a different language by the |:language| command. It is however helpful to
4329cite the message text in a comment: >
4330 :catch /^Vim(\a\+):E108:/ " No such variable
4331
4332
4333IGNORING ERRORS *ignore-errors*
4334
4335You can ignore errors in a specific Vim command by catching them locally: >
4336
4337 :try
4338 : write
4339 :catch
4340 :endtry
4341
4342But you are strongly recommended NOT to use this simple form, since it could
4343catch more than you want. With the ":write" command, some autocommands could
4344be executed and cause errors not related to writing, for instance: >
4345
4346 :au BufWritePre * unlet novar
4347
4348There could even be such errors you are not responsible for as a script
4349writer: a user of your script might have defined such autocommands. You would
4350then hide the error from the user.
4351 It is much better to use >
4352
4353 :try
4354 : write
4355 :catch /^Vim(write):/
4356 :endtry
4357
4358which only catches real write errors. So catch only what you'd like to ignore
4359intentionally.
4360
4361For a single command that does not cause execution of autocommands, you could
4362even suppress the conversion of errors to exceptions by the ":silent!"
4363command: >
4364 :silent! nunmap k
4365This works also when a try conditional is active.
4366
4367
4368CATCHING INTERRUPTS *catch-interrupt*
4369
4370When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar58b85342016-08-14 19:54:54 +02004371the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00004372script is not terminated, then.
4373 Example: >
4374
4375 :function! TASK1()
4376 : sleep 10
4377 :endfunction
4378
4379 :function! TASK2()
4380 : sleep 20
4381 :endfunction
4382
4383 :while 1
4384 : let command = input("Type a command: ")
4385 : try
4386 : if command == ""
4387 : continue
4388 : elseif command == "END"
4389 : break
4390 : elseif command == "TASK1"
4391 : call TASK1()
4392 : elseif command == "TASK2"
4393 : call TASK2()
4394 : else
4395 : echo "\nIllegal command:" command
4396 : continue
4397 : endif
4398 : catch /^Vim:Interrupt$/
4399 : echo "\nCommand interrupted"
4400 : " Caught the interrupt. Continue with next prompt.
4401 : endtry
4402 :endwhile
4403
4404You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar58b85342016-08-14 19:54:54 +02004405a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004406
4407For testing what happens when CTRL-C would be pressed on a specific line in
4408your script, use the debug mode and execute the |>quit| or |>interrupt|
4409command on that line. See |debug-scripts|.
4410
4411
4412CATCHING ALL *catch-all*
4413
4414The commands >
4415
4416 :catch /.*/
4417 :catch //
4418 :catch
4419
4420catch everything, error exceptions, interrupt exceptions and exceptions
4421explicitly thrown by the |:throw| command. This is useful at the top level of
4422a script in order to catch unexpected things.
4423 Example: >
4424
4425 :try
4426 :
4427 : " do the hard work here
4428 :
4429 :catch /MyException/
4430 :
4431 : " handle known problem
4432 :
4433 :catch /^Vim:Interrupt$/
4434 : echo "Script interrupted"
4435 :catch /.*/
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004436 : echo "Internal error (" .. v:exception .. ")"
4437 : echo " - occurred at " .. v:throwpoint
Bram Moolenaar071d4272004-06-13 20:20:40 +00004438 :endtry
4439 :" end of script
4440
4441Note: Catching all might catch more things than you want. Thus, you are
4442strongly encouraged to catch only for problems that you can really handle by
4443specifying a pattern argument to the ":catch".
4444 Example: Catching all could make it nearly impossible to interrupt a script
4445by pressing CTRL-C: >
4446
4447 :while 1
4448 : try
4449 : sleep 1
4450 : catch
4451 : endtry
4452 :endwhile
4453
4454
4455EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
4456
4457Exceptions may be used during execution of autocommands. Example: >
4458
4459 :autocmd User x try
4460 :autocmd User x throw "Oops!"
4461 :autocmd User x catch
4462 :autocmd User x echo v:exception
4463 :autocmd User x endtry
4464 :autocmd User x throw "Arrgh!"
4465 :autocmd User x echo "Should not be displayed"
4466 :
4467 :try
4468 : doautocmd User x
4469 :catch
4470 : echo v:exception
4471 :endtry
4472
4473This displays "Oops!" and "Arrgh!".
4474
4475 *except-autocmd-Pre*
4476For some commands, autocommands get executed before the main action of the
4477command takes place. If an exception is thrown and not caught in the sequence
4478of autocommands, the sequence and the command that caused its execution are
4479abandoned and the exception is propagated to the caller of the command.
4480 Example: >
4481
4482 :autocmd BufWritePre * throw "FAIL"
4483 :autocmd BufWritePre * echo "Should not be displayed"
4484 :
4485 :try
4486 : write
4487 :catch
4488 : echo "Caught:" v:exception "from" v:throwpoint
4489 :endtry
4490
4491Here, the ":write" command does not write the file currently being edited (as
4492you can see by checking 'modified'), since the exception from the BufWritePre
4493autocommand abandons the ":write". The exception is then caught and the
4494script displays: >
4495
4496 Caught: FAIL from BufWrite Auto commands for "*"
4497<
4498 *except-autocmd-Post*
4499For some commands, autocommands get executed after the main action of the
4500command has taken place. If this main action fails and the command is inside
4501an active try conditional, the autocommands are skipped and an error exception
4502is thrown that can be caught by the caller of the command.
4503 Example: >
4504
4505 :autocmd BufWritePost * echo "File successfully written!"
4506 :
4507 :try
4508 : write /i/m/p/o/s/s/i/b/l/e
4509 :catch
4510 : echo v:exception
4511 :endtry
4512
4513This just displays: >
4514
4515 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
4516
4517If you really need to execute the autocommands even when the main action
4518fails, trigger the event from the catch clause.
4519 Example: >
4520
4521 :autocmd BufWritePre * set noreadonly
4522 :autocmd BufWritePost * set readonly
4523 :
4524 :try
4525 : write /i/m/p/o/s/s/i/b/l/e
4526 :catch
4527 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
4528 :endtry
4529<
4530You can also use ":silent!": >
4531
4532 :let x = "ok"
4533 :let v:errmsg = ""
4534 :autocmd BufWritePost * if v:errmsg != ""
4535 :autocmd BufWritePost * let x = "after fail"
4536 :autocmd BufWritePost * endif
4537 :try
4538 : silent! write /i/m/p/o/s/s/i/b/l/e
4539 :catch
4540 :endtry
4541 :echo x
4542
4543This displays "after fail".
4544
4545If the main action of the command does not fail, exceptions from the
4546autocommands will be catchable by the caller of the command: >
4547
4548 :autocmd BufWritePost * throw ":-("
4549 :autocmd BufWritePost * echo "Should not be displayed"
4550 :
4551 :try
4552 : write
4553 :catch
4554 : echo v:exception
4555 :endtry
4556<
4557 *except-autocmd-Cmd*
4558For some commands, the normal action can be replaced by a sequence of
4559autocommands. Exceptions from that sequence will be catchable by the caller
4560of the command.
4561 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar58b85342016-08-14 19:54:54 +02004562had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +00004563some way. >
4564
4565 :if !exists("cnt")
4566 : let cnt = 0
4567 :
4568 : autocmd BufWriteCmd * if &modified
4569 : autocmd BufWriteCmd * let cnt = cnt + 1
4570 : autocmd BufWriteCmd * if cnt % 3 == 2
4571 : autocmd BufWriteCmd * throw "BufWriteCmdError"
4572 : autocmd BufWriteCmd * endif
4573 : autocmd BufWriteCmd * write | set nomodified
4574 : autocmd BufWriteCmd * if cnt % 3 == 0
4575 : autocmd BufWriteCmd * throw "BufWriteCmdError"
4576 : autocmd BufWriteCmd * endif
4577 : autocmd BufWriteCmd * echo "File successfully written!"
4578 : autocmd BufWriteCmd * endif
4579 :endif
4580 :
4581 :try
4582 : write
4583 :catch /^BufWriteCmdError$/
4584 : if &modified
4585 : echo "Error on writing (file contents not changed)"
4586 : else
4587 : echo "Error after writing"
4588 : endif
4589 :catch /^Vim(write):/
4590 : echo "Error on writing"
4591 :endtry
4592
4593When this script is sourced several times after making changes, it displays
4594first >
4595 File successfully written!
4596then >
4597 Error on writing (file contents not changed)
4598then >
4599 Error after writing
4600etc.
4601
4602 *except-autocmd-ill*
4603You cannot spread a try conditional over autocommands for different events.
4604The following code is ill-formed: >
4605
4606 :autocmd BufWritePre * try
4607 :
4608 :autocmd BufWritePost * catch
4609 :autocmd BufWritePost * echo v:exception
4610 :autocmd BufWritePost * endtry
4611 :
4612 :write
4613
4614
4615EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
4616
4617Some programming languages allow to use hierarchies of exception classes or to
4618pass additional information with the object of an exception class. You can do
4619similar things in Vim.
4620 In order to throw an exception from a hierarchy, just throw the complete
4621class name with the components separated by a colon, for instance throw the
4622string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
4623 When you want to pass additional information with your exception class, add
4624it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
4625for an error when writing "myfile".
4626 With the appropriate patterns in the ":catch" command, you can catch for
4627base classes or derived classes of your hierarchy. Additional information in
4628parentheses can be cut out from |v:exception| with the ":substitute" command.
4629 Example: >
4630
4631 :function! CheckRange(a, func)
4632 : if a:a < 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004633 : throw "EXCEPT:MATHERR:RANGE(" .. a:func .. ")"
Bram Moolenaar071d4272004-06-13 20:20:40 +00004634 : endif
4635 :endfunction
4636 :
4637 :function! Add(a, b)
4638 : call CheckRange(a:a, "Add")
4639 : call CheckRange(a:b, "Add")
4640 : let c = a:a + a:b
4641 : if c < 0
4642 : throw "EXCEPT:MATHERR:OVERFLOW"
4643 : endif
4644 : return c
4645 :endfunction
4646 :
4647 :function! Div(a, b)
4648 : call CheckRange(a:a, "Div")
4649 : call CheckRange(a:b, "Div")
4650 : if (a:b == 0)
4651 : throw "EXCEPT:MATHERR:ZERODIV"
4652 : endif
4653 : return a:a / a:b
4654 :endfunction
4655 :
4656 :function! Write(file)
4657 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +00004658 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004659 : catch /^Vim(write):/
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004660 : throw "EXCEPT:IO(" .. getcwd() .. ", " .. a:file .. "):WRITEERR"
Bram Moolenaar071d4272004-06-13 20:20:40 +00004661 : endtry
4662 :endfunction
4663 :
4664 :try
4665 :
4666 : " something with arithmetics and I/O
4667 :
4668 :catch /^EXCEPT:MATHERR:RANGE/
4669 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
4670 : echo "Range error in" function
4671 :
4672 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
4673 : echo "Math error"
4674 :
4675 :catch /^EXCEPT:IO/
4676 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
4677 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
4678 : if file !~ '^/'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004679 : let file = dir .. "/" .. file
Bram Moolenaar071d4272004-06-13 20:20:40 +00004680 : endif
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004681 : echo 'I/O error for "' .. file .. '"'
Bram Moolenaar071d4272004-06-13 20:20:40 +00004682 :
4683 :catch /^EXCEPT/
4684 : echo "Unspecified error"
4685 :
4686 :endtry
4687
4688The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
4689a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
4690exceptions with the "Vim" prefix; they are reserved for Vim.
4691 Vim error exceptions are parameterized with the name of the command that
4692failed, if known. See |catch-errors|.
4693
4694
4695PECULIARITIES
4696 *except-compat*
4697The exception handling concept requires that the command sequence causing the
4698exception is aborted immediately and control is transferred to finally clauses
4699and/or a catch clause.
4700
4701In the Vim script language there are cases where scripts and functions
4702continue after an error: in functions without the "abort" flag or in a command
4703after ":silent!", control flow goes to the following line, and outside
4704functions, control flow goes to the line following the outermost ":endwhile"
4705or ":endif". On the other hand, errors should be catchable as exceptions
4706(thus, requiring the immediate abortion).
4707
4708This problem has been solved by converting errors to exceptions and using
4709immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar58b85342016-08-14 19:54:54 +02004710conditional is active. This is no restriction since an (error) exception can
4711be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +00004712termination without catching the error, just use a try conditional without
4713catch clause. (You can cause cleanup code being executed before termination
4714by specifying a finally clause.)
4715
4716When no try conditional is active, the usual abortion and continuation
4717behavior is used instead of immediate abortion. This ensures compatibility of
4718scripts written for Vim 6.1 and earlier.
4719
4720However, when sourcing an existing script that does not use exception handling
4721commands (or when calling one of its functions) from inside an active try
4722conditional of a new script, you might change the control flow of the existing
4723script on error. You get the immediate abortion on error and can catch the
4724error in the new script. If however the sourced script suppresses error
4725messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar58b85342016-08-14 19:54:54 +02004726|v:errmsg| if appropriate), its execution path is not changed. The error is
4727not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +00004728where this happens is for scripts that don't care about errors and produce
4729error messages. You probably won't want to use such code from your new
4730scripts.
4731
4732 *except-syntax-err*
4733Syntax errors in the exception handling commands are never caught by any of
4734the ":catch" commands of the try conditional they belong to. Its finally
4735clauses, however, is executed.
4736 Example: >
4737
4738 :try
4739 : try
4740 : throw 4711
4741 : catch /\(/
4742 : echo "in catch with syntax error"
4743 : catch
4744 : echo "inner catch-all"
4745 : finally
4746 : echo "inner finally"
4747 : endtry
4748 :catch
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004749 : echo 'outer catch-all caught "' .. v:exception .. '"'
Bram Moolenaar071d4272004-06-13 20:20:40 +00004750 : finally
4751 : echo "outer finally"
4752 :endtry
4753
4754This displays: >
4755 inner finally
4756 outer catch-all caught "Vim(catch):E54: Unmatched \("
4757 outer finally
4758The original exception is discarded and an error exception is raised, instead.
4759
4760 *except-single-line*
4761The ":try", ":catch", ":finally", and ":endtry" commands can be put on
4762a single line, but then syntax errors may make it difficult to recognize the
4763"catch" line, thus you better avoid this.
4764 Example: >
4765 :try | unlet! foo # | catch | endtry
4766raises an error exception for the trailing characters after the ":unlet!"
4767argument, but does not see the ":catch" and ":endtry" commands, so that the
4768error exception is discarded and the "E488: Trailing characters" message gets
4769displayed.
4770
4771 *except-several-errors*
4772When several errors appear in a single command, the first error message is
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02004773usually the most specific one and therefore converted to the error exception.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004774 Example: >
4775 echo novar
4776causes >
4777 E121: Undefined variable: novar
4778 E15: Invalid expression: novar
4779The value of the error exception inside try conditionals is: >
4780 Vim(echo):E121: Undefined variable: novar
4781< *except-syntax-error*
4782But when a syntax error is detected after a normal error in the same command,
4783the syntax error is used for the exception being thrown.
4784 Example: >
4785 unlet novar #
4786causes >
4787 E108: No such variable: "novar"
4788 E488: Trailing characters
4789The value of the error exception inside try conditionals is: >
4790 Vim(unlet):E488: Trailing characters
4791This is done because the syntax error might change the execution path in a way
4792not intended by the user. Example: >
4793 try
4794 try | unlet novar # | catch | echo v:exception | endtry
4795 catch /.*/
4796 echo "outer catch:" v:exception
4797 endtry
4798This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
4799a "E600: Missing :endtry" error message is given, see |except-single-line|.
4800
4801==============================================================================
48029. Examples *eval-examples*
4803
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004804Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004805>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004806 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004807 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004808 : let n = a:nr
4809 : let r = ""
4810 : while n
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004811 : let r = '01'[n % 2] .. r
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004812 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00004813 : endwhile
4814 : return r
4815 :endfunc
4816
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004817 :" The function String2Bin() converts each character in a string to a
4818 :" binary string, separated with dashes.
4819 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004820 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004821 : for ix in range(strlen(a:str))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004822 : let out = out .. '-' .. Nr2Bin(char2nr(a:str[ix]))
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004823 : endfor
4824 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004825 :endfunc
4826
4827Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004828 :echo Nr2Bin(32)
4829result: "100000" >
4830 :echo String2Bin("32")
4831result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +00004832
4833
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004834Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004835
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004836This example sorts lines with a specific compare function. >
4837
4838 :func SortBuffer()
4839 : let lines = getline(1, '$')
4840 : call sort(lines, function("Strcmp"))
4841 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004842 :endfunction
4843
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004844As a one-liner: >
4845 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +00004846
Bram Moolenaar071d4272004-06-13 20:20:40 +00004847
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004848scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004849 *sscanf*
4850There is no sscanf() function in Vim. If you need to extract parts from a
4851line, you can use matchstr() and substitute() to do it. This example shows
4852how to get the file name, line number and column number out of a line like
4853"foobar.txt, 123, 45". >
4854 :" Set up the match bit
4855 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
4856 :"get the part matching the whole expression
4857 :let l = matchstr(line, mx)
4858 :"get each item out of the match
4859 :let file = substitute(l, mx, '\1', '')
4860 :let lnum = substitute(l, mx, '\2', '')
4861 :let col = substitute(l, mx, '\3', '')
4862
4863The input is in the variable "line", the results in the variables "file",
4864"lnum" and "col". (idea from Michael Geddes)
4865
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004866
4867getting the scriptnames in a Dictionary ~
4868 *scriptnames-dictionary*
4869The |:scriptnames| command can be used to get a list of all script files that
4870have been sourced. There is no equivalent function or variable for this
4871(because it's rarely needed). In case you need to manipulate the list this
4872code can be used: >
4873 " Get the output of ":scriptnames" in the scriptnames_output variable.
4874 let scriptnames_output = ''
4875 redir => scriptnames_output
4876 silent scriptnames
4877 redir END
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004878
Bram Moolenaar446cb832008-06-24 21:56:24 +00004879 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004880 " "scripts" dictionary.
4881 let scripts = {}
4882 for line in split(scriptnames_output, "\n")
4883 " Only do non-blank lines.
4884 if line =~ '\S'
4885 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004886 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004887 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +00004888 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004889 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +00004890 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004891 endif
4892 endfor
4893 unlet scriptnames_output
4894
Bram Moolenaar071d4272004-06-13 20:20:40 +00004895==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +0200489610. Vim script versions *vimscript-version* *vimscript-versions*
Bram Moolenaar911ead12019-04-21 00:03:35 +02004897 *scriptversion*
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004898Over time many features have been added to Vim script. This includes Ex
4899commands, functions, variable types, etc. Each individual feature can be
4900checked with the |has()| and |exists()| functions.
4901
4902Sometimes old syntax of functionality gets in the way of making Vim better.
4903When support is taken away this will break older Vim scripts. To make this
4904explicit the |:scriptversion| command can be used. When a Vim script is not
4905compatible with older versions of Vim this will give an explicit error,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02004906instead of failing in mysterious ways.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004907
Bram Moolenaara2baa732022-02-04 16:09:54 +00004908When using a legacy function, defined with `:function`, in |Vim9| script then
4909scriptversion 4 is used.
4910
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02004911 *scriptversion-1* >
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004912 :scriptversion 1
4913< This is the original Vim script, same as not using a |:scriptversion|
4914 command. Can be used to go back to old syntax for a range of lines.
4915 Test for support with: >
4916 has('vimscript-1')
4917
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02004918< *scriptversion-2* >
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004919 :scriptversion 2
Bram Moolenaar68e65602019-05-26 21:33:31 +02004920< String concatenation with "." is not supported, use ".." instead.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004921 This avoids the ambiguity using "." for Dict member access and
4922 floating point numbers. Now ".5" means the number 0.5.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02004923
4924 *scriptversion-3* >
Bram Moolenaar911ead12019-04-21 00:03:35 +02004925 :scriptversion 3
4926< All |vim-variable|s must be prefixed by "v:". E.g. "version" doesn't
4927 work as |v:version| anymore, it can be used as a normal variable.
4928 Same for some obvious names as "count" and others.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004929
Bram Moolenaar911ead12019-04-21 00:03:35 +02004930 Test for support with: >
4931 has('vimscript-3')
Bram Moolenaar60a8de22019-09-15 14:33:22 +02004932<
4933 *scriptversion-4* >
4934 :scriptversion 4
Bram Moolenaarc17e66c2020-06-02 21:38:22 +02004935< Numbers with a leading zero are not recognized as octal. "0o" or "0O"
4936 is still recognized as octal. With the
Bram Moolenaar60a8de22019-09-15 14:33:22 +02004937 previous version you get: >
Bram Moolenaarc17e66c2020-06-02 21:38:22 +02004938 echo 017 " displays 15 (octal)
4939 echo 0o17 " displays 15 (octal)
4940 echo 018 " displays 18 (decimal)
Bram Moolenaar60a8de22019-09-15 14:33:22 +02004941< with script version 4: >
Bram Moolenaarc17e66c2020-06-02 21:38:22 +02004942 echo 017 " displays 17 (decimal)
4943 echo 0o17 " displays 15 (octal)
4944 echo 018 " displays 18 (decimal)
Bram Moolenaar60a8de22019-09-15 14:33:22 +02004945< Also, it is possible to use single quotes inside numbers to make them
4946 easier to read: >
4947 echo 1'000'000
4948< The quotes must be surrounded by digits.
4949
4950 Test for support with: >
4951 has('vimscript-4')
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004952
4953==============================================================================
495411. No +eval feature *no-eval-feature*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004955
4956When the |+eval| feature was disabled at compile time, none of the expression
4957evaluation commands are available. To prevent this from causing Vim scripts
4958to generate all kinds of errors, the ":if" and ":endif" commands are still
4959recognized, though the argument of the ":if" and everything between the ":if"
4960and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
4961only if the commands are at the start of the line. The ":else" command is not
4962recognized.
4963
4964Example of how to avoid executing commands when the |+eval| feature is
4965missing: >
4966
4967 :if 1
4968 : echo "Expression evaluation is compiled in"
4969 :else
4970 : echo "You will _never_ see this message"
4971 :endif
4972
Bram Moolenaar773a97c2019-06-06 20:39:55 +02004973To execute a command only when the |+eval| feature is disabled can be done in
4974two ways. The simplest is to exit the script (or Vim) prematurely: >
4975 if 1
4976 echo "commands executed with +eval"
4977 finish
4978 endif
4979 args " command executed without +eval
4980
4981If you do not want to abort loading the script you can use a trick, as this
4982example shows: >
Bram Moolenaar45d2cca2017-04-30 16:36:05 +02004983
4984 silent! while 0
4985 set history=111
4986 silent! endwhile
4987
4988When the |+eval| feature is available the command is skipped because of the
4989"while 0". Without the |+eval| feature the "while 0" is an error, which is
4990silently ignored, and the command is executed.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004991
Bram Moolenaar071d4272004-06-13 20:20:40 +00004992==============================================================================
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000499312. The sandbox *eval-sandbox* *sandbox*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004994
Bram Moolenaar368373e2010-07-19 20:46:22 +02004995The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
4996'foldtext' options may be evaluated in a sandbox. This means that you are
4997protected from these expressions having nasty side effects. This gives some
4998safety for when these options are set from a modeline. It is also used when
4999the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00005000The sandbox is also used for the |:sandbox| command.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00005001 *E48*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005002These items are not allowed in the sandbox:
5003 - changing the buffer text
Bram Moolenaarb477af22018-07-15 20:20:18 +02005004 - defining or changing mapping, autocommands, user commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00005005 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005006 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005007 - executing a shell command
5008 - reading or writing a file
5009 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +00005010 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00005011This is not guaranteed 100% secure, but it should block most attacks.
5012
5013 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00005014:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00005015 option that may have been set from a modeline, e.g.
5016 'foldexpr'.
5017
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00005018 *sandbox-option*
5019A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00005020have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00005021restrictive, thus this only happens when the option was set from an insecure
5022location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005023- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00005024- while executing in the sandbox
5025- value coming from a modeline
Bram Moolenaarb477af22018-07-15 20:20:18 +02005026- executing a function that was defined in the sandbox
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00005027
5028Note that when in the sandbox and saving an option value and restoring it, the
5029option will still be marked as it was set in the sandbox.
5030
5031==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +0200503213. Textlock *textlock*
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00005033
5034In a few situations it is not allowed to change the text in the buffer, jump
5035to another window and some other things that might confuse or break what Vim
5036is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar58b85342016-08-14 19:54:54 +02005037actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00005038happen any moment the mouse cursor is resting at some position.
5039
5040This is not allowed when the textlock is active:
5041 - changing the buffer text
5042 - jumping to another buffer or window
5043 - editing another file
5044 - closing a window or quitting Vim
5045 - etc.
5046
Bram Moolenaar071d4272004-06-13 20:20:40 +00005047
Bram Moolenaar91f84f62018-07-29 15:07:52 +02005048 vim:tw=78:ts=8:noet:ft=help:norl: