blob: f2ff3a883f974582943575b9c015f0765345bca1 [file] [log] [blame]
Alin Mr6d1d1802024-03-20 20:26:23 +01001*eval.txt* For Vim version 9.1. Last change: 2024 Mar 20
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|
Christian Brabandtda4e4332023-11-05 10:45:12 +01003914. Vim script library |vim-script-library|
Bram Moolenaared997ad2019-07-21 16:42:00 +020040
41Testing support is documented in |testing.txt|.
42Profiling is documented at |profiling|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000043
Bram Moolenaar071d4272004-06-13 20:20:40 +000044==============================================================================
451. Variables *variables*
46
Bram Moolenaar13065c42005-01-08 16:08:21 +0000471.1 Variable types ~
Bram Moolenaarf10911e2022-01-29 22:20:48 +000048 *E712* *E896* *E897* *E899* *E1098*
49 *E1107* *E1135* *E1138*
Bram Moolenaar06fe74a2019-08-31 16:20:32 +020050There are ten types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000051
Bram Moolenaar664f3cf2019-12-07 16:03:51 +010052 *Number* *Integer*
53Number A 32 or 64 bit signed number. |expr-number|
Bram Moolenaarf9706e92020-02-22 14:27:04 +010054 The number of bits is available in |v:numbersize|.
Bram Moolenaar6f02b002021-01-10 20:22:54 +010055 Examples: -123 0x10 0177 0o177 0b1011
Bram Moolenaard8b02732005-01-14 21:48:43 +000056
Bram Moolenaar446cb832008-06-24 21:56:24 +000057Float A floating point number. |floating-point-format| *Float*
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*
Bram Moolenaar7db29e42022-12-11 15:53:04 +0000167 *E913* *E974* *E975* *E976* *E1319* *E1320* *E1321* *E1322*
168 *E1323* *E1324*
169|List|, |Dictionary|, |Funcref|, |Job|, |Channel|, |Blob|, |Class| and
170|object| types are not automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000171
Bram Moolenaar446cb832008-06-24 21:56:24 +0000172 *E805* *E806* *E808*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200173When mixing Number and Float the Number is converted to Float. Otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +0000174there is no automatic conversion of Float. You can use str2float() for String
175to Float, printf() for Float to String and float2nr() for Float to Number.
176
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000177 *E362* *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100178When expecting a Float a Number can also be used, but nothing else.
179
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100180 *no-type-checking*
181You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000182
Bram Moolenaar13065c42005-01-08 16:08:21 +0000183
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001841.2 Function references ~
Bram Moolenaar8a3b8052022-06-26 12:21:15 +0100185 *Funcref* *E695* *E718* *E1192*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200186A Funcref variable is obtained with the |function()| function, the |funcref()|
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +0100187function, (in |Vim9| script) the name of a function, or created with the
188lambda expression |expr-lambda|. It can be used in an expression in the place
189of a function name, before the parenthesis around the arguments, to invoke the
190function it refers to. Example in |Vim9| script: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000191
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +0100192 :var Fn = MyFunc
193 :echo Fn()
194
195Legacy script: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000196 :let Fn = function("MyFunc")
197 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000198< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000199A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200200can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000201cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000202
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000203A special case is defining a function and directly assigning its Funcref to a
204Dictionary entry. Example: >
205 :function dict.init() dict
206 : let self.val = 0
207 :endfunction
208
209The key of the Dictionary can start with a lower case letter. The actual
210function name is not used here. Also see |numbered-function|.
211
212A Funcref can also be used with the |:call| command: >
213 :call Fn()
214 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000215
216The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000217 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000218
219You can use |call()| to invoke a Funcref and use a list variable for the
220arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000221 :let r = call(Fn, mylist)
Bram Moolenaar1d429612016-05-24 15:44:17 +0200222<
223 *Partial*
224A Funcref optionally binds a Dictionary and/or arguments. This is also called
225a Partial. This is created by passing the Dictionary and/or arguments to
Bram Moolenaar58b85342016-08-14 19:54:54 +0200226function() or funcref(). When calling the function the Dictionary and/or
227arguments will be passed to the function. Example: >
Bram Moolenaar1d429612016-05-24 15:44:17 +0200228
229 let Cb = function('Callback', ['foo'], myDict)
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100230 call Cb('bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200231
232This will invoke the function as if using: >
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100233 call myDict.Callback('foo', 'bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200234
235This is very useful when passing a function around, e.g. in the arguments of
236|ch_open()|.
237
238Note that binding a function to a Dictionary also happens when the function is
239a member of the Dictionary: >
240
241 let myDict.myFunction = MyFunction
242 call myDict.myFunction()
243
244Here MyFunction() will get myDict passed as "self". This happens when the
245"myFunction" member is accessed. When making assigning "myFunction" to
246otherDict and calling it, it will be bound to otherDict: >
247
248 let otherDict.myFunction = myDict.myFunction
249 call otherDict.myFunction()
250
251Now "self" will be "otherDict". But when the dictionary was bound explicitly
252this won't happen: >
253
254 let myDict.myFunction = function(MyFunction, myDict)
255 let otherDict.myFunction = myDict.myFunction
256 call otherDict.myFunction()
257
Bram Moolenaard823fa92016-08-12 16:29:27 +0200258Here "self" will be "myDict", because it was bound explicitly.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000259
260
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002611.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200262 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000263A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar58b85342016-08-14 19:54:54 +0200264can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000265position in the sequence.
266
Bram Moolenaar13065c42005-01-08 16:08:21 +0000267
268List creation ~
269 *E696* *E697*
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +0100270A List is created with a comma-separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000271Examples: >
272 :let mylist = [1, two, 3, "four"]
273 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000274
Bram Moolenaar58b85342016-08-14 19:54:54 +0200275An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000276List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000277 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000278
279An extra comma after the last item is ignored.
280
Bram Moolenaar13065c42005-01-08 16:08:21 +0000281
282List index ~
283 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000284An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000285after the List. Indexes are zero-based, thus the first item has index zero. >
286 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000287 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000288
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000289When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000290 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000291<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000292A negative index is counted from the end. Index -1 refers to the last item in
293the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000294 :let last = mylist[-1] " get the last item: "four"
295
Bram Moolenaar13065c42005-01-08 16:08:21 +0000296To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000297is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000298 :echo get(mylist, idx)
299 :echo get(mylist, idx, "NONE")
300
301
302List concatenation ~
Bram Moolenaar34453202021-01-31 13:08:38 +0100303 *list-concatenation*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000304Two lists can be concatenated with the "+" operator: >
305 :let longlist = mylist + [5, 6]
zeertzjqb8170142024-02-08 11:21:44 +0100306 :let longlist = [5, 6] + mylist
307To prepend or append an item, turn it into a list by putting [] around it.
308
309A list can be concatenated with another one in-place using |:let+=| or
310|extend()|: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000311 :let mylist += [7, 8]
qeatzyc9c2e2d2024-02-07 17:52:25 +0100312 :call extend(mylist, [7, 8])
zeertzjqb8170142024-02-08 11:21:44 +0100313<
314See |list-modification| below for more about changing a list in-place.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000315
316
317Sublist ~
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200318 *sublist*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000319A part of the List can be obtained by specifying the first and last index,
320separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000321 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000322
323Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000324similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000325 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
326 :let shortlist = mylist[2:2] " List with one item: [3]
327 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000328
Bram Moolenaar6601b622021-01-13 21:47:15 +0100329Notice that the last index is inclusive. If you prefer using an exclusive
330index use the |slice()| method.
331
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000332If the first index is beyond the last item of the List or the second item is
333before the first item, the result is an empty list. There is no error
334message.
335
336If the second index is equal to or greater than the length of the list the
337length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000338 :let mylist = [0, 1, 2, 3]
339 :echo mylist[2:8] " result: [2, 3]
340
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000341NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar58b85342016-08-14 19:54:54 +0200342using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000343mylist[s : e].
344
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000345
Bram Moolenaar13065c42005-01-08 16:08:21 +0000346List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000347 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000348When variable "aa" is a list and you assign it to another variable "bb", both
349variables refer to the same list. Thus changing the list "aa" will also
350change "bb": >
351 :let aa = [1, 2, 3]
352 :let bb = aa
353 :call add(aa, 4)
354 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000355< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000356
357Making a copy of a list is done with the |copy()| function. Using [:] also
358works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000359a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000360 :let aa = [[1, 'a'], 2, 3]
361 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000362 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000363 :let aa[0][1] = 'aaa'
364 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000365< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000366 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000367< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000368
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000369To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000370copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000371
372The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000373List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000374the same value. >
375 :let alist = [1, 2, 3]
376 :let blist = [1, 2, 3]
377 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000378< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000379 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000380< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000381
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000382Note about comparing lists: Two lists are considered equal if they have the
383same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000384exception: When comparing a number with a string they are considered
385different. There is no automatic type conversion, as with using "==" on
386variables. Example: >
387 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000388< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000389 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000390< 0
391
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000392Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000393can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000394
395 :let a = 5
396 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000397 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000398< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000399 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000400< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000401
Bram Moolenaar13065c42005-01-08 16:08:21 +0000402
403List unpack ~
404
405To unpack the items in a list to individual variables, put the variables in
406square brackets, like list items: >
407 :let [var1, var2] = mylist
408
409When the number of variables does not match the number of items in the list
410this produces an error. To handle any extra items from the list append ";"
411and a variable name: >
412 :let [var1, var2; rest] = mylist
413
414This works like: >
415 :let var1 = mylist[0]
416 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000417 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000418
419Except that there is no error if there are only two items. "rest" will be an
420empty list then.
421
422
423List modification ~
424 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000425To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000426 :let list[4] = "four"
427 :let listlist[0][3] = item
428
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000429To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000430modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000431 :let list[3:5] = [3, 4, 5]
432
zeertzjqb8170142024-02-08 11:21:44 +0100433To add items to a List in-place, you can use |:let+=| (|list-concatenation|): >
Yegappan Lakshmanan1af35632024-02-06 11:03:36 +0100434 :let listA = [1, 2]
435 :let listA += [3, 4]
436<
437When two variables refer to the same List, changing one List in-place will
438cause the referenced List to be changed in-place: >
439 :let listA = [1, 2]
440 :let listB = listA
441 :let listB += [3, 4]
442 :echo listA
443 [1, 2, 3, 4]
444<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000445Adding and removing items from a list is done with functions. Here are a few
446examples: >
447 :call insert(list, 'a') " prepend item 'a'
448 :call insert(list, 'a', 3) " insert item 'a' before list[3]
449 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000450 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000451 :call extend(list, [1, 2]) " extend the list with two more items
452 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000453 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000454 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000455 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000456 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000457
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000458Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000459 :call sort(list) " sort a list alphabetically
460 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100461 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000462
Bram Moolenaar13065c42005-01-08 16:08:21 +0000463
464For loop ~
465
Bram Moolenaar74e54fc2021-03-26 20:41:29 +0100466The |:for| loop executes commands for each item in a List, String or Blob.
467A variable is set to each item in sequence. Example with a List: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000468 :for item in mylist
469 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000470 :endfor
471
472This works like: >
473 :let index = 0
474 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000475 : let item = mylist[index]
476 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000477 : let index = index + 1
478 :endwhile
479
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000480If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000481function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000482
Bram Moolenaar58b85342016-08-14 19:54:54 +0200483Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar74e54fc2021-03-26 20:41:29 +0100484requires the argument to be a List of Lists. >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000485 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
486 : call Doit(lnum, col)
487 :endfor
488
489This works like a |:let| command is done for each list item. Again, the types
490must remain the same to avoid an error.
491
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000492It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000493 :for [i, j; rest] in listlist
494 : call Doit(i, j)
495 : if !empty(rest)
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000496 : echo "remainder: " .. string(rest)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000497 : endif
498 :endfor
499
Bram Moolenaar74e54fc2021-03-26 20:41:29 +0100500For a Blob one byte at a time is used.
501
502For a String one character, including any composing characters, is used as a
503String. Example: >
504 for c in text
505 echo 'This character is ' .. c
506 endfor
507
Bram Moolenaar13065c42005-01-08 16:08:21 +0000508
509List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000510 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000511Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000512 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000513 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000514 :let l = len(list) " number of items in list
515 :let big = max(list) " maximum value in list
516 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000517 :let xs = count(list, 'x') " count nr of times 'x' appears in list
518 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000519 :let lines = getline(1, 10) " get ten text lines from buffer
520 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000521 :let list = split("a b c") " create list from items in a string
522 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000523 :let s = string(list) " String representation of list
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000524 :call map(list, '">> " .. v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000525
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000526Don't forget that a combination of features can make things simple. For
527example, to add up all the numbers in a list: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000528 :exe 'let sum = ' .. join(nrlist, '+')
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000529
Bram Moolenaar13065c42005-01-08 16:08:21 +0000530
Bram Moolenaard8b02732005-01-14 21:48:43 +00005311.4 Dictionaries ~
Bram Moolenaard8968242019-01-15 22:51:57 +0100532 *dict* *Dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000533A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000534entry can be located with the key. The entries are stored without a specific
535ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000536
537
538Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000539 *E720* *E721* *E722* *E723*
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +0100540A Dictionary is created with a comma-separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000541braces. Each entry has a key and a value, separated by a colon. Each key can
542only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000543 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
544 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000545< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000546A key is always a String. You can use a Number, it will be converted to a
547String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar58b85342016-08-14 19:54:54 +0200548entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaard899e512022-05-07 21:54:03 +0100549Number will be converted to the String '4', leading zeros are dropped. The
550empty string can also be used as a key.
Bram Moolenaar5da36052021-12-27 15:39:57 +0000551
Bram Moolenaard799daa2022-06-20 11:17:32 +0100552In |Vim9| script a literal key can be used if it consists only of alphanumeric
Bram Moolenaar5da36052021-12-27 15:39:57 +0000553characters, underscore and dash, see |vim9-literal-dict|.
Bram Moolenaar56c860c2019-08-17 20:09:31 +0200554 *literal-Dict* *#{}*
Bram Moolenaar5da36052021-12-27 15:39:57 +0000555To avoid having to put quotes around every key the #{} form can be used in
556legacy script. This does require the key to consist only of ASCII letters,
557digits, '-' and '_'. Example: >
Bram Moolenaar10455d42019-11-21 15:36:18 +0100558 :let mydict = #{zero: 0, one_key: 1, two-key: 2, 333: 3}
Bram Moolenaar4c6d9042019-07-16 22:04:02 +0200559Note that 333 here is the string "333". Empty keys are not possible with #{}.
Bram Moolenaard899e512022-05-07 21:54:03 +0100560In |Vim9| script the #{} form cannot be used because it can be confused with
561the start of a comment.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000562
Bram Moolenaar58b85342016-08-14 19:54:54 +0200563A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000564nested Dictionary: >
565 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
566
567An extra comma after the last entry is ignored.
568
569
570Accessing entries ~
571
572The normal way to access an entry is by putting the key in square brackets: >
573 :let val = mydict["one"]
574 :let mydict["four"] = 4
575
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000576You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000577
578For keys that consist entirely of letters, digits and underscore the following
579form can be used |expr-entry|: >
580 :let val = mydict.one
581 :let mydict.four = 4
582
583Since an entry can be any type, also a List and a Dictionary, the indexing and
584key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000585 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000586
587
588Dictionary to List conversion ~
589
Bram Moolenaar58b85342016-08-14 19:54:54 +0200590You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000591turn the Dictionary into a List and pass it to |:for|.
592
593Most often you want to loop over the keys, using the |keys()| function: >
594 :for key in keys(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000595 : echo key .. ': ' .. mydict[key]
Bram Moolenaard8b02732005-01-14 21:48:43 +0000596 :endfor
597
598The List of keys is unsorted. You may want to sort them first: >
599 :for key in sort(keys(mydict))
600
601To loop over the values use the |values()| function: >
602 :for v in values(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000603 : echo "value: " .. v
Bram Moolenaard8b02732005-01-14 21:48:43 +0000604 :endfor
605
606If you want both the key and the value use the |items()| function. It returns
Bram Moolenaard47d5222018-12-09 20:43:55 +0100607a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000608 :for [key, value] in items(mydict)
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000609 : echo key .. ': ' .. value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000610 :endfor
611
612
613Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000614 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000615Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
616Dictionary. Otherwise, assignment results in referring to the same
617Dictionary: >
618 :let onedict = {'a': 1, 'b': 2}
619 :let adict = onedict
620 :let adict['a'] = 11
621 :echo onedict['a']
622 11
623
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000624Two Dictionaries compare equal if all the key-value pairs compare equal. For
625more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000626
627
628Dictionary modification ~
629 *dict-modification*
630To change an already existing entry of a Dictionary, or to add a new entry,
631use |:let| this way: >
632 :let dict[4] = "four"
633 :let dict['one'] = item
634
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000635Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
636Three ways to remove the entry with key "aaa" from dict: >
637 :let i = remove(dict, 'aaa')
638 :unlet dict.aaa
639 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000640
641Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000642 :call extend(adict, bdict)
643This extends adict with all entries from bdict. Duplicate keys cause entries
644in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000645Note that the order of entries in a Dictionary is irrelevant, thus don't
646expect ":echo adict" to show the items from bdict after the older entries in
647adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000648
649Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000650 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000651This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar388a5d42020-05-26 21:20:45 +0200652This can also be used to remove all entries: >
653 call filter(dict, 0)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000654
Bram Moolenaar86b48162022-12-06 18:20:10 +0000655In some situations it is not allowed to remove or add entries to a Dictionary.
656Especially when iterating over all the entries. You will get *E1313* or
657another error in that case.
658
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000659
660Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100661 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000662When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar58b85342016-08-14 19:54:54 +0200663special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000664 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000665 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000666 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000667 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
668 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000669
670This is like a method in object oriented programming. The entry in the
671Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
Bram Moolenaar86b48162022-12-06 18:20:10 +0000672the function was invoked from. When using |Vim9| script you can use classes
673and objects, see `:class`.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000674
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000675It is also possible to add a function without the "dict" attribute as a
676Funcref to a Dictionary, but the "self" variable is not available then.
677
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000678 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000679To avoid the extra name for the function it can be defined and directly
680assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000681 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200682 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000683 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000684 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000685 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000686
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000687The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar58b85342016-08-14 19:54:54 +0200688that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000689|Funcref|. It will automatically be deleted when there is no |Funcref|
690remaining that refers to it.
691
692It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000693
Bram Moolenaar1affd722010-08-04 17:49:30 +0200694If you get an error for a numbered function, you can find out what it is with
695a trick. Assuming the function is 42, the command is: >
Bram Moolenaar34cc7d82021-09-21 20:09:51 +0200696 :function g:42
Bram Moolenaar1affd722010-08-04 17:49:30 +0200697
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000698
699Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000700 *E715*
701Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000702 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
703 :if empty(dict) " TRUE if dict is empty
704 :let l = len(dict) " number of items in dict
705 :let big = max(dict) " maximum value in dict
706 :let small = min(dict) " minimum value in dict
707 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
708 :let s = string(dict) " String representation of dict
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000709 :call map(dict, '">> " .. v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000710
711
Bram Moolenaard8968242019-01-15 22:51:57 +01007121.5 Blobs ~
713 *blob* *Blob* *Blobs* *E978*
Bram Moolenaaraff74912019-03-30 18:11:49 +0100714A Blob is a binary object. It can be used to read an image from a file and
715send it over a channel, for example.
716
717A Blob mostly behaves like a |List| of numbers, where each number has the
718value of an 8-bit byte, from 0 to 255.
Bram Moolenaard8968242019-01-15 22:51:57 +0100719
720
721Blob creation ~
722
723A Blob can be created with a |blob-literal|: >
724 :let b = 0zFF00ED015DAF
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +0100725Dots can be inserted between bytes (pair of hex characters) for readability,
726they don't change the value: >
727 :let b = 0zFF00.ED01.5DAF
Bram Moolenaard8968242019-01-15 22:51:57 +0100728
729A blob can be read from a file with |readfile()| passing the {type} argument
730set to "B", for example: >
731 :let b = readfile('image.png', 'B')
732
733A blob can be read from a channel with the |ch_readblob()| function.
734
735
736Blob index ~
737 *blob-index* *E979*
738A byte in the Blob can be accessed by putting the index in square brackets
739after the Blob. Indexes are zero-based, thus the first byte has index zero. >
740 :let myblob = 0z00112233
741 :let byte = myblob[0] " get the first byte: 0x00
742 :let byte = myblob[2] " get the third byte: 0x22
743
744A negative index is counted from the end. Index -1 refers to the last byte in
745the Blob, -2 to the last but one byte, etc. >
746 :let last = myblob[-1] " get the last byte: 0x33
747
748To avoid an error for an invalid index use the |get()| function. When an item
749is not available it returns -1 or the default value you specify: >
750 :echo get(myblob, idx)
751 :echo get(myblob, idx, 999)
752
753
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100754Blob iteration ~
755
756The |:for| loop executes commands for each byte of a Blob. The loop variable is
757set to each byte in the Blob. Example: >
758 :for byte in 0z112233
759 : call Doit(byte)
760 :endfor
761This calls Doit() with 0x11, 0x22 and 0x33.
762
763
Bram Moolenaard8968242019-01-15 22:51:57 +0100764Blob concatenation ~
zeertzjqb8170142024-02-08 11:21:44 +0100765 *blob-concatenation*
Bram Moolenaard8968242019-01-15 22:51:57 +0100766Two blobs can be concatenated with the "+" operator: >
767 :let longblob = myblob + 0z4455
zeertzjqb8170142024-02-08 11:21:44 +0100768 :let longblob = 0z4455 + myblob
769<
770A blob can be concatenated with another one in-place using |:let+=|: >
Bram Moolenaard8968242019-01-15 22:51:57 +0100771 :let myblob += 0z6677
zeertzjqb8170142024-02-08 11:21:44 +0100772<
773See |blob-modification| below for more about changing a blob in-place.
Bram Moolenaard8968242019-01-15 22:51:57 +0100774
775
776Part of a blob ~
777
778A part of the Blob can be obtained by specifying the first and last index,
779separated by a colon in square brackets: >
780 :let myblob = 0z00112233
Bram Moolenaard09091d2019-01-17 16:07:22 +0100781 :let shortblob = myblob[1:2] " get 0z1122
Bram Moolenaard8968242019-01-15 22:51:57 +0100782 :let shortblob = myblob[2:-1] " get 0z2233
783
784Omitting the first index is similar to zero. Omitting the last index is
785similar to -1. >
786 :let endblob = myblob[2:] " from item 2 to the end: 0z2233
787 :let shortblob = myblob[2:2] " Blob with one byte: 0z22
788 :let otherblob = myblob[:] " make a copy of the Blob
789
Bram Moolenaard09091d2019-01-17 16:07:22 +0100790If the first index is beyond the last byte of the Blob or the second index is
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +0100791before the first index, the result is an empty Blob. There is no error
Bram Moolenaard8968242019-01-15 22:51:57 +0100792message.
793
794If the second index is equal to or greater than the length of the list the
795length minus one is used: >
796 :echo myblob[2:8] " result: 0z2233
797
798
799Blob modification ~
Bram Moolenaara2baa732022-02-04 16:09:54 +0000800 *blob-modification* *E1182* *E1184*
Bram Moolenaard8968242019-01-15 22:51:57 +0100801To change a specific byte of a blob use |:let| this way: >
802 :let blob[4] = 0x44
803
804When the index is just one beyond the end of the Blob, it is appended. Any
805higher index is an error.
806
807To change a sequence of bytes the [:] notation can be used: >
808 let blob[1:3] = 0z445566
Bram Moolenaard09091d2019-01-17 16:07:22 +0100809The length of the replaced bytes must be exactly the same as the value
Bram Moolenaard8968242019-01-15 22:51:57 +0100810provided. *E972*
811
812To change part of a blob you can specify the first and last byte to be
Bram Moolenaard09091d2019-01-17 16:07:22 +0100813modified. The value must have the same number of bytes in the range: >
814 :let blob[3:5] = 0z334455
Bram Moolenaard8968242019-01-15 22:51:57 +0100815
zeertzjqb8170142024-02-08 11:21:44 +0100816To add items to a Blob in-place, you can use |:let+=| (|blob-concatenation|): >
817 :let blobA = 0z1122
818 :let blobA += 0z3344
819<
820When two variables refer to the same Blob, changing one Blob in-place will
821cause the referenced Blob to be changed in-place: >
822 :let blobA = 0z1122
823 :let blobB = blobA
824 :let blobB += 0z3344
825 :echo blobA
826 0z11223344
827<
Bram Moolenaard8968242019-01-15 22:51:57 +0100828You can also use the functions |add()|, |remove()| and |insert()|.
829
830
831Blob identity ~
832
833Blobs can be compared for equality: >
834 if blob == 0z001122
835And for equal identity: >
836 if blob is otherblob
837< *blob-identity* *E977*
838When variable "aa" is a Blob and you assign it to another variable "bb", both
839variables refer to the same Blob. Then the "is" operator returns true.
840
841When making a copy using [:] or |copy()| the values are the same, but the
842identity is different: >
843 :let blob = 0z112233
844 :let blob2 = blob
845 :echo blob == blob2
846< 1 >
847 :echo blob is blob2
848< 1 >
849 :let blob3 = blob[:]
850 :echo blob == blob3
851< 1 >
852 :echo blob is blob3
853< 0
854
Bram Moolenaard09091d2019-01-17 16:07:22 +0100855Making a copy of a Blob is done with the |copy()| function. Using [:] also
Bram Moolenaard8968242019-01-15 22:51:57 +0100856works, as explained above.
857
858
8591.6 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000860 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000861If you need to know the type of a variable or expression, use the |type()|
862function.
863
864When the '!' flag is included in the 'viminfo' option, global variables that
865start with an uppercase letter, and don't contain a lowercase letter, are
866stored in the viminfo file |viminfo-file|.
867
868When the 'sessionoptions' option contains "global", global variables that
869start with an uppercase letter and contain at least one lowercase letter are
870stored in the session file |session-file|.
871
872variable name can be stored where ~
873my_var_6 not
874My_Var_6 session file
875MY_VAR_6 viminfo file
876
877
Bram Moolenaar5da36052021-12-27 15:39:57 +0000878In legacy script it is possible to form a variable name with curly braces, see
Bram Moolenaar071d4272004-06-13 20:20:40 +0000879|curly-braces-names|.
880
881==============================================================================
8822. Expression syntax *expression-syntax*
Bram Moolenaarf10911e2022-01-29 22:20:48 +0000883 *E1143*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000884Expression syntax summary, from least to most significant:
885
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200886|expr1| expr2
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200887 expr2 ? expr1 : expr1 if-then-else
Bram Moolenaar071d4272004-06-13 20:20:40 +0000888
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200889|expr2| expr3
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200890 expr3 || expr3 ... logical OR
Bram Moolenaar071d4272004-06-13 20:20:40 +0000891
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200892|expr3| expr4
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200893 expr4 && expr4 ... logical AND
Bram Moolenaar071d4272004-06-13 20:20:40 +0000894
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200895|expr4| expr5
896 expr5 == expr5 equal
Bram Moolenaar071d4272004-06-13 20:20:40 +0000897 expr5 != expr5 not equal
898 expr5 > expr5 greater than
899 expr5 >= expr5 greater than or equal
900 expr5 < expr5 smaller than
901 expr5 <= expr5 smaller than or equal
902 expr5 =~ expr5 regexp matches
903 expr5 !~ expr5 regexp doesn't match
904
905 expr5 ==? expr5 equal, ignoring case
906 expr5 ==# expr5 equal, match case
907 etc. As above, append ? for ignoring case, # for
908 matching case
909
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100910 expr5 is expr5 same |List|, |Dictionary| or |Blob| instance
911 expr5 isnot expr5 different |List|, |Dictionary| or |Blob|
912 instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000913
K.Takatac23fc362023-12-09 05:51:04 +0900914|expr5| expr6
915 expr6 << expr6 bitwise left shift
Yegappan Lakshmanana061f342022-05-22 19:13:49 +0100916 expr6 >> expr6 bitwise right shift
Bram Moolenaar071d4272004-06-13 20:20:40 +0000917
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200918|expr6| expr7
Yegappan Lakshmanana061f342022-05-22 19:13:49 +0100919 expr7 + expr7 ... number addition, list or blob concatenation
920 expr7 - expr7 ... number subtraction
921 expr7 . expr7 ... string concatenation
922 expr7 .. expr7 ... string concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000923
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200924|expr7| expr8
Yegappan Lakshmanana061f342022-05-22 19:13:49 +0100925 expr8 * expr8 ... number multiplication
926 expr8 / expr8 ... number division
927 expr8 % expr8 ... number modulo
Bram Moolenaar071d4272004-06-13 20:20:40 +0000928
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200929|expr8| expr9
Yegappan Lakshmanana061f342022-05-22 19:13:49 +0100930 <type>expr9 type check and conversion (|Vim9| only)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000931
Bram Moolenaar5da36052021-12-27 15:39:57 +0000932|expr9| expr10
Yegappan Lakshmanana061f342022-05-22 19:13:49 +0100933 ! expr9 logical NOT
934 - expr9 unary minus
935 + expr9 unary plus
Bram Moolenaar5da36052021-12-27 15:39:57 +0000936
Yegappan Lakshmanana061f342022-05-22 19:13:49 +0100937|expr10| expr11
938 expr10[expr1] byte of a String or item of a |List|
939 expr10[expr1 : expr1] substring of a String or sublist of a |List|
940 expr10.name entry in a |Dictionary|
941 expr10(expr1, ...) function call with |Funcref| variable
942 expr10->name(expr1, ...) |method| call
943
944|expr11| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000945 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000946 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000947 [expr1, ...] |List|
948 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar5da36052021-12-27 15:39:57 +0000949 #{key: expr1, ...} legacy |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000950 &option option value
951 (expr1) nested expression
952 variable internal variable
953 va{ria}ble internal variable with curly braces
954 $VAR environment variable
955 @r contents of register 'r'
956 function(expr1, ...) function call
957 func{ti}on(expr1, ...) function call with curly braces
Bram Moolenaar5da36052021-12-27 15:39:57 +0000958 {args -> expr1} legacy lambda expression
959 (args) => expr1 Vim9 lambda expression
Bram Moolenaar071d4272004-06-13 20:20:40 +0000960
961
Bram Moolenaar0f248b02019-04-04 15:36:05 +0200962"..." indicates that the operations in this level can be concatenated.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000963Example: >
964 &nu || &list && &shell == "csh"
965
966All expressions within one level are parsed from left to right.
967
Bram Moolenaarf10911e2022-01-29 22:20:48 +0000968Expression nesting is limited to 1000 levels deep (300 when build with MSVC)
969to avoid running out of stack and crashing. *E1169*
970
Bram Moolenaar071d4272004-06-13 20:20:40 +0000971
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000972expr1 *expr1* *ternary* *falsy-operator* *??* *E109*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000973-----
974
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000975The ternary operator: expr2 ? expr1 : expr1
Bram Moolenaar92f26c22020-10-03 20:17:30 +0200976The falsy operator: expr2 ?? expr1
977
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000978Ternary operator ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000979
Bram Moolenaar5da36052021-12-27 15:39:57 +0000980In legacy script the expression before the '?' is evaluated to a number. If
981it evaluates to |TRUE|, the result is the value of the expression between the
982'?' and ':', otherwise the result is the value of the expression after the
983':'.
984
985In |Vim9| script the first expression must evaluate to a boolean, see
986|vim9-boolean|.
987
Bram Moolenaar071d4272004-06-13 20:20:40 +0000988Example: >
989 :echo lnum == 1 ? "top" : lnum
990
991Since the first expression is an "expr2", it cannot contain another ?:. The
992other two expressions can, thus allow for recursive use of ?:.
993Example: >
994 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
995
996To keep this readable, using |line-continuation| is suggested: >
997 :echo lnum == 1
998 :\ ? "top"
999 :\ : lnum == 1000
1000 :\ ? "last"
1001 :\ : lnum
1002
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001003You should always put a space before the ':', otherwise it can be mistaken for
1004use in a variable such as "a:1".
1005
Bram Moolenaar92f26c22020-10-03 20:17:30 +02001006Falsy operator ~
1007
1008This is also known as the "null coalescing operator", but that's too
1009complicated, thus we just call it the falsy operator.
1010
1011The expression before the '??' is evaluated. If it evaluates to
1012|truthy|, this is used as the result. Otherwise the expression after the '??'
1013is evaluated and used as the result. This is most useful to have a default
1014value for an expression that may result in zero or empty: >
1015 echo theList ?? 'list is empty'
1016 echo GetName() ?? 'unknown'
1017
1018These are similar, but not equal: >
1019 expr2 ?? expr1
1020 expr2 ? expr2 : expr1
Bram Moolenaar5da36052021-12-27 15:39:57 +00001021In the second line "expr2" is evaluated twice. And in |Vim9| script the type
1022of expr2 before "?" must be a boolean.
Bram Moolenaar92f26c22020-10-03 20:17:30 +02001023
Bram Moolenaar071d4272004-06-13 20:20:40 +00001024
1025expr2 and expr3 *expr2* *expr3*
1026---------------
1027
Bram Moolenaar04186092016-08-29 21:55:35 +02001028expr3 || expr3 .. logical OR *expr-barbar*
1029expr4 && expr4 .. logical AND *expr-&&*
1030
Bram Moolenaar5da36052021-12-27 15:39:57 +00001031The "||" and "&&" operators take one argument on each side.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001032
Bram Moolenaar5da36052021-12-27 15:39:57 +00001033In legacy script the arguments are (converted to) Numbers.
1034
1035In |Vim9| script the values must be boolean, see |vim9-boolean|. Use "!!" to
1036convert any type to a boolean.
1037
1038The result is:
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001039 input output ~
1040n1 n2 n1 || n2 n1 && n2 ~
1041|FALSE| |FALSE| |FALSE| |FALSE|
1042|FALSE| |TRUE| |TRUE| |FALSE|
1043|TRUE| |FALSE| |TRUE| |FALSE|
1044|TRUE| |TRUE| |TRUE| |TRUE|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001045
1046The operators can be concatenated, for example: >
1047
1048 &nu || &list && &shell == "csh"
1049
1050Note that "&&" takes precedence over "||", so this has the meaning of: >
1051
1052 &nu || (&list && &shell == "csh")
1053
1054Once the result is known, the expression "short-circuits", that is, further
1055arguments are not evaluated. This is like what happens in C. For example: >
1056
1057 let a = 1
1058 echo a || b
1059
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001060This is valid even if there is no variable called "b" because "a" is |TRUE|,
1061so the result must be |TRUE|. Similarly below: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001062
1063 echo exists("b") && b == "yes"
1064
1065This is valid whether "b" has been defined or not. The second clause will
1066only be evaluated if "b" has been defined.
1067
1068
Bram Moolenaara2baa732022-02-04 16:09:54 +00001069expr4 *expr4* *E1153*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001070-----
1071
1072expr5 {cmp} expr5
1073
Bram Moolenaar5da36052021-12-27 15:39:57 +00001074Compare two expr5 expressions. In legacy script the result is a 0 if it
1075evaluates to false, or 1 if it evaluates to true. In |Vim9| script the result
1076is |true| or |false|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001077
Bram Moolenaar446cb832008-06-24 21:56:24 +00001078 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001079 *expr-<* *expr-<=* *expr-=~* *expr-!~*
1080 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
1081 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
1082 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
1083 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001084 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001085 *expr-is?* *expr-isnot?* *E1072*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001086 use 'ignorecase' match case ignore case ~
1087equal == ==# ==?
1088not equal != !=# !=?
1089greater than > ># >?
1090greater than or equal >= >=# >=?
1091smaller than < <# <?
1092smaller than or equal <= <=# <=?
1093regexp matches =~ =~# =~?
1094regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +02001095same instance is is# is?
1096different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +00001097
1098Examples:
1099"abc" ==# "Abc" evaluates to 0
1100"abc" ==? "Abc" evaluates to 1
1101"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
Bram Moolenaar5da36052021-12-27 15:39:57 +00001102NOTE: In |Vim9| script 'ignorecase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001103
Bram Moolenaar13065c42005-01-08 16:08:21 +00001104 *E691* *E692*
Bram Moolenaar01164a62017-11-02 22:58:42 +01001105A |List| can only be compared with a |List| and only "equal", "not equal",
1106"is" and "isnot" can be used. This compares the values of the list,
1107recursively. Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001108
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00001109 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001110A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
Bram Moolenaar01164a62017-11-02 22:58:42 +01001111equal", "is" and "isnot" can be used. This compares the key/values of the
1112|Dictionary| recursively. Ignoring case means case is ignored when comparing
1113item values.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00001114
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02001115 *E694*
Bram Moolenaare18dbe82016-07-02 21:42:23 +02001116A |Funcref| can only be compared with a |Funcref| and only "equal", "not
1117equal", "is" and "isnot" can be used. Case is never ignored. Whether
1118arguments or a Dictionary are bound (with a partial) matters. The
1119Dictionaries must also be equal (or the same, in case of "is") and the
1120arguments must be equal (or the same).
1121
1122To compare Funcrefs to see if they refer to the same function, ignoring bound
1123Dictionary and arguments, use |get()| to get the function name: >
1124 if get(Part1, 'name') == get(Part2, 'name')
1125 " Part1 and Part2 refer to the same function
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001126< *E1037*
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001127Using "is" or "isnot" with a |List|, |Dictionary| or |Blob| checks whether
1128the expressions are referring to the same |List|, |Dictionary| or |Blob|
1129instance. A copy of a |List| is different from the original |List|. When
1130using "is" without a |List|, |Dictionary| or |Blob|, it is equivalent to
1131using "equal", using "isnot" equivalent to using "not equal". Except that
1132a different type means the values are different: >
Bram Moolenaar86edef62016-03-13 18:07:30 +01001133 echo 4 == '4'
1134 1
1135 echo 4 is '4'
1136 0
1137 echo 0 is []
1138 0
1139"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaare1f3fd12022-08-15 18:51:32 +01001140In |Vim9| script this doesn't work, two strings are never identical.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001141
Bram Moolenaar5da36052021-12-27 15:39:57 +00001142In legacy script, when comparing a String with a Number, the String is
1143converted to a Number, and the comparison is done on Numbers. This means
1144that: >
Bram Moolenaar86edef62016-03-13 18:07:30 +01001145 echo 0 == 'x'
1146 1
1147because 'x' converted to a Number is zero. However: >
1148 echo [0] == ['x']
1149 0
1150Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001151
Bram Moolenaar5da36052021-12-27 15:39:57 +00001152In |Vim9| script the types must match.
1153
Bram Moolenaar071d4272004-06-13 20:20:40 +00001154When comparing two Strings, this is done with strcmp() or stricmp(). This
1155results in the mathematical difference (comparing byte values), not
1156necessarily the alphabetical difference in the local language.
1157
Bram Moolenaar446cb832008-06-24 21:56:24 +00001158When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001159'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001160
1161When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001162'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
1163
1164'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001165
1166The "=~" and "!~" operators match the lefthand argument with the righthand
1167argument, which is used as a pattern. See |pattern| for what a pattern is.
1168This matching is always done like 'magic' was set and 'cpoptions' is empty, no
1169matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
1170portable. To avoid backslashes in the regexp pattern to be doubled, use a
1171single-quote string, see |literal-string|.
1172Since a string is considered to be a single line, a multi-line pattern
1173(containing \n, backslash-n) will not match. However, a literal NL character
1174can be matched like an ordinary character. Examples:
1175 "foo\nbar" =~ "\n" evaluates to 1
1176 "foo\nbar" =~ "\\n" evaluates to 0
1177
1178
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001179expr5 *expr5* *bitwise-shift*
1180-----
1181expr6 << expr6 bitwise left shift *expr-<<*
1182expr6 >> expr6 bitwise right shift *expr->>*
1183 *E1282* *E1283*
1184The "<<" and ">>" operators can be used to perform bitwise left or right shift
1185of the left operand by the number of bits specified by the right operand. The
Bram Moolenaar338bf582022-05-22 20:16:32 +01001186operands are used as positive numbers. When shifting right with ">>" the
Bram Moolenaard592deb2022-06-17 15:42:40 +01001187topmost bit (sometimes called the sign bit) is cleared. If the right operand
Bram Moolenaar338bf582022-05-22 20:16:32 +01001188(shift amount) is more than the maximum number of bits in a number
1189(|v:numbersize|) the result is zero.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001190
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001191
1192expr6 and expr7 *expr6* *expr7* *E1036* *E1051*
1193---------------
1194expr7 + expr7 Number addition, |List| or |Blob| concatenation *expr-+*
1195expr7 - expr7 Number subtraction *expr--*
1196expr7 . expr7 String concatenation *expr-.*
1197expr7 .. expr7 String concatenation *expr-..*
1198
1199For |Lists| only "+" is possible and then both expr7 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001200result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001201
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001202For String concatenation ".." is preferred, since "." is ambiguous, it is also
1203used for |Dict| member access and floating point numbers.
Bram Moolenaar5da36052021-12-27 15:39:57 +00001204In |Vim9| script and when |vimscript-version| is 2 or higher, using "." is not
1205allowed.
1206
1207In |Vim9| script the arguments of ".." are converted to String for simple
1208types: Number, Float, Special and Bool. For other types |string()| should be
1209used.
Bram Moolenaar0f248b02019-04-04 15:36:05 +02001210
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001211expr8 * expr8 Number multiplication *expr-star*
1212expr8 / expr8 Number division *expr-/*
1213expr8 % expr8 Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001214
Bram Moolenaar5da36052021-12-27 15:39:57 +00001215In legacy script, for all operators except "." and "..", Strings are converted
1216to Numbers.
1217
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001218For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001219
Bram Moolenaar5da36052021-12-27 15:39:57 +00001220Note the difference between "+" and ".." in legacy script:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001221 "123" + "456" = 579
Bram Moolenaar5da36052021-12-27 15:39:57 +00001222 "123" .. "456" = "123456"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001223
Bram Moolenaar5da36052021-12-27 15:39:57 +00001224Since '..' has the same precedence as '+' and '-', you need to read: >
1225 1 .. 90 + 90.0
Bram Moolenaar446cb832008-06-24 21:56:24 +00001226As: >
Bram Moolenaar5da36052021-12-27 15:39:57 +00001227 (1 .. 90) + 90.0
1228That works in legacy script, since the String "190" is automatically converted
1229to the Number 190, which can be added to the Float 90.0. However: >
1230 1 .. 90 * 90.0
Bram Moolenaar446cb832008-06-24 21:56:24 +00001231Should be read as: >
Bram Moolenaar5da36052021-12-27 15:39:57 +00001232 1 .. (90 * 90.0)
1233Since '..' has lower precedence than '*'. This does NOT work, since this
Bram Moolenaar446cb832008-06-24 21:56:24 +00001234attempts to concatenate a Float and a String.
1235
1236When dividing a Number by zero the result depends on the value:
1237 0 / 0 = -0x80000000 (like NaN for Float)
1238 >0 / 0 = 0x7fffffff (like positive infinity)
1239 <0 / 0 = -0x7fffffff (like negative infinity)
1240 (before Vim 7.2 it was always 0x7fffffff)
Bram Moolenaara2baa732022-02-04 16:09:54 +00001241In |Vim9| script dividing a number by zero is an error. *E1154*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001242
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02001243When 64-bit Number support is enabled:
1244 0 / 0 = -0x8000000000000000 (like NaN for Float)
1245 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
1246 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
1247
Bram Moolenaar071d4272004-06-13 20:20:40 +00001248When the righthand side of '%' is zero, the result is 0.
1249
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001250None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001251
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001252".", ".." and "%" do not work for Float. *E804* *E1035*
Bram Moolenaar446cb832008-06-24 21:56:24 +00001253
Bram Moolenaar071d4272004-06-13 20:20:40 +00001254
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001255expr8 *expr8*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001256-----
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001257<type>expr9
Bram Moolenaar5da36052021-12-27 15:39:57 +00001258
1259This is only available in |Vim9| script, see |type-casting|.
1260
1261
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001262expr9 *expr9*
Bram Moolenaar5da36052021-12-27 15:39:57 +00001263-----
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001264! expr9 logical NOT *expr-!*
1265- expr9 unary minus *expr-unary--*
1266+ expr9 unary plus *expr-unary-+*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001267
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001268For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001269For '-' the sign of the number is changed.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001270For '+' the number is unchanged. Note: "++" has no effect.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001271
Bram Moolenaar5da36052021-12-27 15:39:57 +00001272In legacy script a String will be converted to a Number first. Note that if
1273the string does not start with a digit you likely don't get what you expect.
1274
1275In |Vim9| script an error is given when "-" or "+" is used and the type is not
1276a number.
1277
1278In |Vim9| script "!" can be used for any type and the result is always a
1279boolean. Use "!!" to convert any type to a boolean, according to whether the
1280value is |falsy|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001281
Bram Moolenaar58b85342016-08-14 19:54:54 +02001282These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001283 !-1 == 0
1284 !!8 == 1
1285 --9 == 9
1286
1287
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001288expr10 *expr10*
1289------
1290This expression is either |expr11| or a sequence of the alternatives below,
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001291in any order. E.g., these are all possible:
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001292 expr10[expr1].name
1293 expr10.name[expr1]
1294 expr10(expr1, ...)[expr1].name
1295 expr10->(expr1, ...)[expr1]
Bram Moolenaarac92e252019-08-03 21:58:38 +02001296Evaluation is always from left to right.
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001297
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001298expr10[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001299 *E909* *subscript* *E1062*
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001300In legacy Vim script:
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001301If expr10 is a Number or String this results in a String that contains the
1302expr1'th single byte from expr10. expr10 is used as a String (a number is
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001303automatically converted to a String), expr1 as a Number. This doesn't
Bram Moolenaar207f0092020-08-30 17:20:20 +02001304recognize multibyte encodings, see `byteidx()` for an alternative, or use
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001305`split()` to turn the string into a list of characters. Example, to get the
1306byte under the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00001307 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001308
Bram Moolenaara2baa732022-02-04 16:09:54 +00001309In |Vim9| script: *E1147* *E1148*
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001310If expr10 is a String this results in a String that contains the expr1'th
1311single character (including any composing characters) from expr10. To use byte
Bram Moolenaar02b4d9b2021-03-14 19:46:45 +01001312indexes use |strpart()|.
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001313
1314Index zero gives the first byte or character. Careful: text column numbers
1315start with one!
1316
Bram Moolenaar071d4272004-06-13 20:20:40 +00001317If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +01001318String. A negative index always results in an empty string (reason: backward
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001319compatibility). Use [-1:] to get the last byte or character.
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001320In Vim9 script a negative index is used like with a list: count from the end.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001321
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001322If expr10 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001323for possible index values. If the index is out of range this results in an
Bram Moolenaar58b85342016-08-14 19:54:54 +02001324error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001325 :let item = mylist[-1] " get last item
1326
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001327Generally, if a |List| index is equal to or higher than the length of the
1328|List|, or more negative than the length of the |List|, this results in an
1329error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001330
Bram Moolenaard8b02732005-01-14 21:48:43 +00001331
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01001332expr10[expr1a : expr1b] substring or |sublist| *expr-[:]* *substring*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001333
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001334If expr10 is a String this results in the substring with the bytes or
1335characters from expr1a to and including expr1b. expr10 is used as a String,
Bram Moolenaar207f0092020-08-30 17:20:20 +02001336expr1a and expr1b are used as a Number.
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001337
1338In legacy Vim script the indexes are byte indexes. This doesn't recognize
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001339multibyte encodings, see |byteidx()| for computing the indexes. If expr10 is
Bram Moolenaare3c37d82020-08-15 18:39:05 +02001340a Number it is first converted to a String.
1341
Bram Moolenaar02b4d9b2021-03-14 19:46:45 +01001342In Vim9 script the indexes are character indexes and include composing
1343characters. To use byte indexes use |strpart()|. To use character indexes
1344without including composing characters use |strcharpart()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001345
Bram Moolenaar6601b622021-01-13 21:47:15 +01001346The item at index expr1b is included, it is inclusive. For an exclusive index
1347use the |slice()| function.
1348
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001349If expr1a is omitted zero is used. If expr1b is omitted the length of the
1350string minus one is used.
1351
1352A negative number can be used to measure from the end of the string. -1 is
1353the last character, -2 the last but one, etc.
1354
1355If an index goes out of range for the string characters are omitted. If
1356expr1b is smaller than expr1a the result is an empty string.
1357
1358Examples: >
1359 :let c = name[-1:] " last byte of a string
Bram Moolenaar207f0092020-08-30 17:20:20 +02001360 :let c = name[0:-1] " the whole string
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001361 :let c = name[-2:-2] " last but one byte of a string
1362 :let s = line(".")[4:] " from the fifth byte to the end
1363 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001364<
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001365 *slice*
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001366If expr10 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar58b85342016-08-14 19:54:54 +02001367the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001368just above. Also see |sublist| below. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001369 :let l = mylist[:3] " first four items
1370 :let l = mylist[4:4] " List with one item
1371 :let l = mylist[:] " shallow copy of a List
1372
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001373If expr10 is a |Blob| this results in a new |Blob| with the bytes in the
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001374indexes expr1a and expr1b, inclusive. Examples: >
1375 :let b = 0zDEADBEEF
1376 :let bs = b[1:2] " 0zADBE
Bram Moolenaard09091d2019-01-17 16:07:22 +01001377 :let bs = b[:] " copy of 0zDEADBEEF
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001378
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001379Using expr10[expr1] or expr10[expr1a : expr1b] on a |Funcref| results in an
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001380error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001381
Bram Moolenaarda440d22016-01-16 21:27:23 +01001382Watch out for confusion between a namespace and a variable followed by a colon
1383for a sublist: >
1384 mylist[n:] " uses variable n
1385 mylist[s:] " uses namespace s:, error!
1386
Bram Moolenaard8b02732005-01-14 21:48:43 +00001387
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001388expr10.name entry in a |Dictionary| *expr-entry*
Bram Moolenaara2baa732022-02-04 16:09:54 +00001389 *E1203* *E1229*
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001390If expr10 is a |Dictionary| and it is followed by a dot, then the following
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001391name will be used as a key in the |Dictionary|. This is just like:
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001392expr10[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +00001393
1394The name must consist of alphanumeric characters, just like a variable name,
1395but it may start with a number. Curly braces cannot be used.
1396
1397There must not be white space before or after the dot.
1398
1399Examples: >
1400 :let dict = {"one": 1, 2: "two"}
Bram Moolenaar68e65602019-05-26 21:33:31 +02001401 :echo dict.one " shows "1"
1402 :echo dict.2 " shows "two"
1403 :echo dict .2 " error because of space before the dot
Bram Moolenaard8b02732005-01-14 21:48:43 +00001404
1405Note that the dot is also used for String concatenation. To avoid confusion
1406always put spaces around the dot for String concatenation.
1407
1408
Bram Moolenaar938ae282023-02-20 20:44:55 +00001409expr10(expr1, ...) |Funcref| function call *E1085*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001410
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001411When expr10 is a |Funcref| type variable, invoke the function it refers to.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001412
1413
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001414expr10->name([args]) method call *method* *->*
1415expr10->{lambda}([args])
Bram Moolenaara2baa732022-02-04 16:09:54 +00001416 *E260* *E276* *E1265*
Bram Moolenaar25e42232019-08-04 15:04:10 +02001417For methods that are also available as global functions this is the same as: >
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001418 name(expr10 [, args])
1419There can also be methods specifically for the type of "expr10".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001420
Bram Moolenaar51841322019-08-08 21:10:01 +02001421This allows for chaining, passing the value that one method returns to the
1422next method: >
Bram Moolenaar25e42232019-08-04 15:04:10 +02001423 mylist->filter(filterexpr)->map(mapexpr)->sort()->join()
1424<
Bram Moolenaar22a0c0c2019-08-09 23:25:08 +02001425Example of using a lambda: >
Bram Moolenaar02b31112019-08-31 22:16:38 +02001426 GetPercentage()->{x -> x * 100}()->printf('%d%%')
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001427<
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001428When using -> the |expr9| operators will be applied first, thus: >
Bram Moolenaar93cf85f2019-08-17 21:36:28 +02001429 -1.234->string()
1430Is equivalent to: >
1431 (-1.234)->string()
1432And NOT: >
1433 -(1.234->string())
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001434
1435What comes after "->" can be a name, a simple expression (not containing any
Bram Moolenaar944697a2022-02-20 19:48:20 +00001436parenthesis), or any expression in parentheses: >
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001437 base->name(args)
1438 base->some.name(args)
1439 base->alist[idx](args)
1440 base->(getFuncRef())(args)
1441Note that in the last call the base is passed to the function resulting from
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01001442"(getFuncRef())", inserted before "args". *E1275*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001443
Bram Moolenaar51841322019-08-08 21:10:01 +02001444 *E274*
1445"->name(" must not contain white space. There can be white space before the
1446"->" and after the "(", thus you can split the lines like this: >
1447 mylist
1448 \ ->filter(filterexpr)
1449 \ ->map(mapexpr)
1450 \ ->sort()
1451 \ ->join()
Bram Moolenaar56c860c2019-08-17 20:09:31 +02001452
1453When using the lambda form there must be no white space between the } and the
1454(.
1455
Bram Moolenaar25e42232019-08-04 15:04:10 +02001456
Yegappan Lakshmanana061f342022-05-22 19:13:49 +01001457 *expr11*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001458number
1459------
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001460number number constant *expr-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001461
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001462 *0x* *hex-number* *0o* *octal-number* *binary-number*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001463Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
Bram Moolenaarc17e66c2020-06-02 21:38:22 +02001464and Octal (starting with 0, 0o or 0O).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001465
Bram Moolenaar338bf582022-05-22 20:16:32 +01001466Assuming 64 bit numbers are used (see |v:numbersize|) an unsigned number is
1467truncated to 0x7fffffffffffffff or 9223372036854775807. You can use -1 to get
14680xffffffffffffffff.
1469
Bram Moolenaar446cb832008-06-24 21:56:24 +00001470 *floating-point-format*
1471Floating point numbers can be written in two forms:
1472
1473 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +01001474 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001475
1476{N} and {M} are numbers. Both {N} and {M} must be present and can only
Bram Moolenaar6aa57292021-08-14 21:25:52 +02001477contain digits, except that in |Vim9| script in {N} single quotes between
1478digits are ignored.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001479[-+] means there is an optional plus or minus sign.
1480{exp} is the exponent, power of 10.
Bram Moolenaar58b85342016-08-14 19:54:54 +02001481Only a decimal point is accepted, not a comma. No matter what the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00001482locale is.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001483
1484Examples:
1485 123.456
1486 +0.0001
1487 55.0
1488 -0.123
1489 1.234e03
1490 1.0E-6
1491 -3.1416e+88
1492
1493These are INVALID:
1494 3. empty {M}
1495 1e40 missing .{M}
1496
1497Rationale:
1498Before floating point was introduced, the text "123.456" was interpreted as
1499the two numbers "123" and "456", both converted to a string and concatenated,
1500resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001501could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001502incompatibility was accepted in favor of being able to use the normal notation
1503for floating point numbers.
1504
Bram Moolenaard47d5222018-12-09 20:43:55 +01001505 *float-pi* *float-e*
1506A few useful values to copy&paste: >
1507 :let pi = 3.14159265359
1508 :let e = 2.71828182846
1509Or, if you don't want to write them in as floating-point literals, you can
1510also use functions, like the following: >
1511 :let pi = acos(-1.0)
1512 :let e = exp(1.0)
Bram Moolenaar98aefe72018-12-13 22:20:09 +01001513<
Bram Moolenaar446cb832008-06-24 21:56:24 +00001514 *floating-point-precision*
1515The precision and range of floating points numbers depends on what "double"
1516means in the library Vim was compiled with. There is no way to change this at
1517runtime.
1518
1519The default for displaying a |Float| is to use 6 decimal places, like using
1520printf("%g", f). You can select something else when using the |printf()|
1521function. Example: >
1522 :echo printf('%.15e', atan(1))
1523< 7.853981633974483e-01
1524
1525
Bram Moolenaar071d4272004-06-13 20:20:40 +00001526
Bram Moolenaar979243b2015-06-26 19:35:49 +02001527string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001528------
1529"string" string constant *expr-quote*
1530
1531Note that double quotes are used.
1532
1533A string constant accepts these special characters:
1534\... three-digit octal number (e.g., "\316")
1535\.. two-digit octal number (must be followed by non-digit)
1536\. one-digit octal number (must be followed by non-digit)
1537\x.. byte specified with two hex numbers (e.g., "\x1f")
1538\x. byte specified with one hex number (must be followed by non-hex char)
1539\X.. same as \x..
1540\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001541\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001542 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001543\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001544\b backspace <BS>
1545\e escape <Esc>
Bram Moolenaar6e649222021-10-04 21:32:54 +01001546\f formfeed 0x0C
Bram Moolenaar071d4272004-06-13 20:20:40 +00001547\n newline <NL>
1548\r return <CR>
1549\t tab <Tab>
1550\\ backslash
1551\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001552\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
Bram Moolenaar58b85342016-08-14 19:54:54 +02001553 in mappings, the 0x80 byte is escaped.
1554 To use the double quote character it must be escaped: "<M-\">".
Bram Moolenaar6e649222021-10-04 21:32:54 +01001555 Don't use <Char-xxxx> to get a UTF-8 character, use \uxxxx as
Bram Moolenaar58b85342016-08-14 19:54:54 +02001556 mentioned above.
Bram Moolenaarfccd93f2020-05-31 22:06:51 +02001557\<*xxx> Like \<xxx> but prepends a modifier instead of including it in the
1558 character. E.g. "\<C-w>" is one character 0x17 while "\<*C-w>" is four
Bram Moolenaarebe9d342020-05-30 21:52:54 +02001559 bytes: 3 for the CTRL modifier and then character "W".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001560
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001561Note that "\xff" is stored as the byte 255, which may be invalid in some
1562encodings. Use "\u00ff" to store character 255 according to the current value
1563of 'encoding'.
1564
Bram Moolenaar071d4272004-06-13 20:20:40 +00001565Note that "\000" and "\x00" force the end of the string.
1566
1567
Bram Moolenaard8968242019-01-15 22:51:57 +01001568blob-literal *blob-literal* *E973*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001569------------
1570
1571Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
1572The sequence must be an even number of hex characters. Example: >
1573 :let b = 0zFF00ED015DAF
1574
1575
Bram Moolenaar071d4272004-06-13 20:20:40 +00001576literal-string *literal-string* *E115*
1577---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001578'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001579
1580Note that single quotes are used.
1581
Bram Moolenaar58b85342016-08-14 19:54:54 +02001582This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001583meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001584
1585Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar58b85342016-08-14 19:54:54 +02001586to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001587 if a =~ "\\s*"
1588 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001589
1590
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001591interpolated-string *$quote* *interpolated-string*
LemonBoy2eaef102022-05-06 13:14:50 +01001592--------------------
1593$"string" interpolated string constant *expr-$quote*
1594$'string' interpolated literal string constant *expr-$'*
1595
1596Interpolated strings are an extension of the |string| and |literal-string|,
1597allowing the inclusion of Vim script expressions (see |expr1|). Any
1598expression returning a value can be enclosed between curly braces. The value
1599is converted to a string. All the text and results of the expressions
1600are concatenated to make a new string.
Bram Moolenaar2ecbe532022-07-29 21:36:21 +01001601 *E1278* *E1279*
LemonBoy2eaef102022-05-06 13:14:50 +01001602To include an opening brace '{' or closing brace '}' in the string content
Bram Moolenaar3f32a5f2022-05-12 20:34:15 +01001603double it. For double quoted strings using a backslash also works. A single
1604closing brace '}' will result in an error.
LemonBoy2eaef102022-05-06 13:14:50 +01001605
1606Examples: >
1607 let your_name = input("What's your name? ")
Bram Moolenaar3f32a5f2022-05-12 20:34:15 +01001608< What's your name? Peter ~
1609>
1610 echo
LemonBoy2eaef102022-05-06 13:14:50 +01001611 echo $"Hello, {your_name}!"
Bram Moolenaar3f32a5f2022-05-12 20:34:15 +01001612< Hello, Peter! ~
1613>
1614 echo $"The square root of {{9}} is {sqrt(9)}"
1615< The square root of {9} is 3.0 ~
1616
Christian Brabandt67672ef2023-04-24 21:09:54 +01001617 *string-offset-encoding*
1618A string consists of multiple characters. How the characters are stored
1619depends on 'encoding'. Most common is UTF-8, which uses one byte for ASCII
1620characters, two bytes for other latin characters and more bytes for other
1621characters.
1622
1623A string offset can count characters or bytes. Other programs may use
1624UTF-16 encoding (16-bit words) and an offset of UTF-16 words. Some functions
1625use byte offsets, usually for UTF-8 encoding. Other functions use character
1626offsets, in which case the encoding doesn't matter.
1627
1628The different offsets for the string "a©😊" are below:
1629
1630 UTF-8 offsets:
1631 [0]: 61, [1]: C2, [2]: A9, [3]: F0, [4]: 9F, [5]: 98, [6]: 8A
1632 UTF-16 offsets:
1633 [0]: 0061, [1]: 00A9, [2]: D83D, [3]: DE0A
1634 UTF-32 (character) offsets:
1635 [0]: 00000061, [1]: 000000A9, [2]: 0001F60A
1636
1637You can use the "g8" and "ga" commands on a character to see the
1638decimal/hex/octal values.
1639
1640The functions |byteidx()|, |utf16idx()| and |charidx()| can be used to convert
1641between these indices. The functions |strlen()|, |strutf16len()| and
1642|strcharlen()| return the number of bytes, UTF-16 code units and characters in
1643a string respectively.
LemonBoy2eaef102022-05-06 13:14:50 +01001644
Bram Moolenaar071d4272004-06-13 20:20:40 +00001645option *expr-option* *E112* *E113*
1646------
1647&option option value, local value if possible
1648&g:option global option value
1649&l:option local option value
1650
1651Examples: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001652 echo "tabstop is " .. &tabstop
Bram Moolenaar071d4272004-06-13 20:20:40 +00001653 if &insertmode
1654
1655Any option name can be used here. See |options|. When using the local value
1656and there is no buffer-local or window-local value, the global value is used
1657anyway.
1658
1659
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001660register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001661--------
1662@r contents of register 'r'
1663
1664The result is the contents of the named register, as a single string.
1665Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar58b85342016-08-14 19:54:54 +02001666register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001667registers.
1668
1669When using the '=' register you get the expression itself, not what it
1670evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001671
1672
Bram Moolenaara2baa732022-02-04 16:09:54 +00001673nesting *expr-nesting* *E110*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001674-------
1675(expr1) nested expression
1676
1677
1678environment variable *expr-env*
1679--------------------
1680$VAR environment variable
1681
1682The String value of any environment variable. When it is not defined, the
1683result is an empty string.
Bram Moolenaar691ddee2019-05-09 14:52:41 +02001684
1685The functions `getenv()` and `setenv()` can also be used and work for
1686environment variables with non-alphanumeric names.
1687The function `environ()` can be used to get a Dict with all environment
1688variables.
1689
1690
Bram Moolenaar071d4272004-06-13 20:20:40 +00001691 *expr-env-expand*
1692Note that there is a difference between using $VAR directly and using
1693expand("$VAR"). Using it directly will only expand environment variables that
1694are known inside the current Vim session. Using expand() will first try using
1695the environment variables known inside the current Vim session. If that
1696fails, a shell will be used to expand the variable. This can be slow, but it
1697does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001698 :echo $shell
1699 :echo expand("$shell")
1700The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001701variable (if your shell supports it).
1702
1703
Bram Moolenaarf10911e2022-01-29 22:20:48 +00001704internal variable *expr-variable* *E1015* *E1089*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001705-----------------
1706variable internal variable
1707See below |internal-variables|.
1708
1709
Bram Moolenaar05159a02005-02-26 23:04:13 +00001710function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001711-------------
1712function(expr1, ...) function call
1713See below |functions|.
1714
1715
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001716lambda expression *expr-lambda* *lambda*
1717-----------------
Bram Moolenaar938ae282023-02-20 20:44:55 +00001718{args -> expr1} legacy lambda expression *E451*
Bram Moolenaar5da36052021-12-27 15:39:57 +00001719(args) => expr1 |Vim9| lambda expression
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001720
1721A lambda expression creates a new unnamed function which returns the result of
Bram Moolenaar42ebd062016-07-17 13:35:14 +02001722evaluating |expr1|. Lambda expressions differ from |user-functions| in
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001723the following ways:
1724
17251. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
1726 commands.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020017272. The prefix "a:" should not be used for arguments. E.g.: >
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001728 :let F = {arg1, arg2 -> arg1 - arg2}
1729 :echo F(5, 2)
1730< 3
1731
1732The arguments are optional. Example: >
1733 :let F = {-> 'error function'}
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001734 :echo F('ignored')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001735< error function
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001736
Bram Moolenaar5da36052021-12-27 15:39:57 +00001737The |Vim9| lambda does not only use a different syntax, it also adds type
1738checking and can be split over multiple lines, see |vim9-lambda|.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001739
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001740 *closure*
1741Lambda expressions can access outer scope variables and arguments. This is
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001742often called a closure. Example where "i" and "a:arg" are used in a lambda
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001743while they already exist in the function scope. They remain valid even after
1744the function returns: >
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001745 :function Foo(arg)
1746 : let i = 3
1747 : return {x -> x + i - a:arg}
1748 :endfunction
1749 :let Bar = Foo(4)
1750 :echo Bar(6)
1751< 5
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001752
Bram Moolenaar388a5d42020-05-26 21:20:45 +02001753Note that the variables must exist in the outer scope before the lambda is
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001754defined for this to work. See also |:func-closure|.
1755
1756Lambda and closure support can be checked with: >
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001757 if has('lambda')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001758
1759Examples for using a lambda expression with |sort()|, |map()| and |filter()|: >
1760 :echo map([1, 2, 3], {idx, val -> val + 1})
1761< [2, 3, 4] >
1762 :echo sort([3,7,2,1,4], {a, b -> a - b})
1763< [1, 2, 3, 4, 7]
1764
1765The lambda expression is also useful for Channel, Job and timer: >
1766 :let timer = timer_start(500,
1767 \ {-> execute("echo 'Handler called'", "")},
1768 \ {'repeat': 3})
1769< Handler called
1770 Handler called
1771 Handler called
1772
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001773Note that it is possible to cause memory to be used and not freed if the
1774closure is referenced by the context it depends on: >
1775 function Function()
1776 let x = 0
1777 let F = {-> x}
1778 endfunction
1779The closure uses "x" from the function scope, and "F" in that same scope
1780refers to the closure. This cycle results in the memory not being freed.
1781Recommendation: don't do this.
1782
1783Notice how execute() is used to execute an Ex command. That's ugly though.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02001784In Vim9 script you can use a command block, see |inline-function|.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001785
Bram Moolenaar71b6d332022-09-10 13:13:14 +01001786Although you can use the loop variable of a `for` command, it must still exist
1787when the closure is called, otherwise you get an error. *E1302*
1788
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001789Lambda expressions have internal names like '<lambda>42'. If you get an error
1790for a lambda expression, you can find what it is with the following command: >
Bram Moolenaar6f02b002021-01-10 20:22:54 +01001791 :function <lambda>42
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001792See also: |numbered-function|
1793
Bram Moolenaar071d4272004-06-13 20:20:40 +00001794==============================================================================
Bram Moolenaar6f4754b2022-01-23 12:07:04 +000017953. Internal variable *internal-variables* *E461* *E1001*
Bram Moolenaar4a748032010-09-30 21:47:56 +02001796
Bram Moolenaar071d4272004-06-13 20:20:40 +00001797An internal variable name can be made up of letters, digits and '_'. But it
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00001798cannot start with a digit. In legacy script it is also possible to use curly
Bram Moolenaar5da36052021-12-27 15:39:57 +00001799braces, see |curly-braces-names|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001800
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00001801In legacy script an internal variable is created with the ":let" command
Bram Moolenaar5da36052021-12-27 15:39:57 +00001802|:let|. An internal variable is explicitly destroyed with the ":unlet"
1803command |:unlet|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001804Using a name that is not an internal variable or refers to a variable that has
1805been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001806
Bram Moolenaar5da36052021-12-27 15:39:57 +00001807In |Vim9| script `:let` is not used and variables work differently, see |:var|.
1808
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001809 *variable-scope*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001810There are several name spaces for variables. Which one is to be used is
1811specified by what is prepended:
1812
Bram Moolenaar5da36052021-12-27 15:39:57 +00001813 (nothing) In a function: local to the function;
1814 in a legacy script: global;
1815 in a |Vim9| script: local to the script
Bram Moolenaar071d4272004-06-13 20:20:40 +00001816|buffer-variable| b: Local to the current buffer.
1817|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001818|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001819|global-variable| g: Global.
Bram Moolenaar5da36052021-12-27 15:39:57 +00001820|local-variable| l: Local to a function (only in a legacy function)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001821|script-variable| s: Local to a |:source|'ed Vim script.
Bram Moolenaar5da36052021-12-27 15:39:57 +00001822|function-argument| a: Function argument (only in a legacy function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001823|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001824
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001825The scope name by itself can be used as a |Dictionary|. For example, to
1826delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001827 :for k in keys(s:)
1828 : unlet s:[k]
1829 :endfor
Bram Moolenaar65e0d772020-06-14 17:29:55 +02001830
Bram Moolenaar5da36052021-12-27 15:39:57 +00001831Note: in Vim9 script variables can also be local to a block of commands, see
1832|vim9-scopes|.
Bram Moolenaar531da592013-05-06 05:58:55 +02001833 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001834A variable name that is preceded with "b:" is local to the current buffer.
1835Thus you can have several "b:foo" variables, one for each buffer.
1836This kind of variable is deleted when the buffer is wiped out or deleted with
1837|:bdelete|.
1838
1839One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001840 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001841b:changedtick The total number of changes to the current buffer. It is
1842 incremented for each change. An undo command is also a change
Bram Moolenaarc024b462019-06-08 18:07:21 +02001843 in this case. Resetting 'modified' when writing the buffer is
1844 also counted.
1845 This can be used to perform an action only when the buffer has
1846 changed. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001847 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001848 : let my_changedtick = b:changedtick
1849 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001850 :endif
Bram Moolenaar3df01732017-02-17 22:47:16 +01001851< You cannot change or delete the b:changedtick variable.
Bram Moolenaar71badf92023-04-22 22:40:14 +01001852 If you need more information about the change see
1853 |listener_add()|.
Bram Moolenaar3df01732017-02-17 22:47:16 +01001854
Bram Moolenaar531da592013-05-06 05:58:55 +02001855 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001856A variable name that is preceded with "w:" is local to the current window. It
1857is deleted when the window is closed.
1858
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001859 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001860A variable name that is preceded with "t:" is local to the current tab page,
1861It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001862without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001863
Bram Moolenaar531da592013-05-06 05:58:55 +02001864 *global-variable* *g:var* *g:*
Bram Moolenaar04fb9162021-12-30 20:24:12 +00001865Inside functions and in |Vim9| script global variables are accessed with "g:".
1866Omitting this will access a variable local to a function or script. "g:"
1867can also be used in any other place if you like.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001868
Bram Moolenaar531da592013-05-06 05:58:55 +02001869 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001870Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001871But you can also prepend "l:" if you like. However, without prepending "l:"
1872you may run into reserved variable names. For example "count". By itself it
1873refers to "v:count". Using "l:count" you can have a local variable with the
1874same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001875
1876 *script-variable* *s:var*
Bram Moolenaar04fb9162021-12-30 20:24:12 +00001877In a legacy Vim script variables starting with "s:" can be used. They cannot
1878be accessed from outside of the scripts, thus are local to the script.
1879In |Vim9| script the "s:" prefix can be omitted, variables are script-local by
1880default.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001881
1882They can be used in:
1883- commands executed while the script is sourced
1884- functions defined in the script
1885- autocommands defined in the script
1886- functions and autocommands defined in functions and autocommands which were
1887 defined in the script (recursively)
1888- user defined commands defined in the script
1889Thus not in:
1890- other scripts sourced from this one
1891- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001892- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001893- etc.
1894
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001895Script variables can be used to avoid conflicts with global variable names.
1896Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001897
1898 let s:counter = 0
1899 function MyCounter()
1900 let s:counter = s:counter + 1
1901 echo s:counter
1902 endfunction
1903 command Tick call MyCounter()
1904
1905You can now invoke "Tick" from any script, and the "s:counter" variable in
1906that script will not be changed, only the "s:counter" in the script where
1907"Tick" was defined is used.
1908
1909Another example that does the same: >
1910
1911 let s:counter = 0
1912 command Tick let s:counter = s:counter + 1 | echo s:counter
1913
1914When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001915script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001916defined.
1917
1918The script variables are also available when a function is defined inside a
1919function that is defined in a script. Example: >
1920
1921 let s:counter = 0
1922 function StartCounting(incr)
1923 if a:incr
1924 function MyCounter()
1925 let s:counter = s:counter + 1
1926 endfunction
1927 else
1928 function MyCounter()
1929 let s:counter = s:counter - 1
1930 endfunction
1931 endif
1932 endfunction
1933
1934This defines the MyCounter() function either for counting up or counting down
1935when calling StartCounting(). It doesn't matter from where StartCounting() is
1936called, the s:counter variable will be accessible in MyCounter().
1937
1938When the same script is sourced again it will use the same script variables.
1939They will remain valid as long as Vim is running. This can be used to
1940maintain a counter: >
1941
1942 if !exists("s:counter")
1943 let s:counter = 1
1944 echo "script executed for the first time"
1945 else
1946 let s:counter = s:counter + 1
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001947 echo "script executed " .. s:counter .. " times now"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001948 endif
1949
1950Note that this means that filetype plugins don't get a different set of script
1951variables for each buffer. Use local buffer variables instead |b:var|.
1952
1953
Bram Moolenaard47d5222018-12-09 20:43:55 +01001954PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:*
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001955 *E963* *E1063*
Bram Moolenaard47d5222018-12-09 20:43:55 +01001956Some variables can be set by the user, but the type cannot be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001957
Bram Moolenaar69bf6342019-10-29 04:16:57 +01001958 *v:argv* *argv-variable*
1959v:argv The command line arguments Vim was invoked with. This is a
1960 list of strings. The first item is the Vim command.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00001961 See |v:progpath| for the command with full path.
Bram Moolenaar69bf6342019-10-29 04:16:57 +01001962
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001963 *v:beval_col* *beval_col-variable*
1964v:beval_col The number of the column, over which the mouse pointer is.
1965 This is the byte index in the |v:beval_lnum| line.
1966 Only valid while evaluating the 'balloonexpr' option.
1967
1968 *v:beval_bufnr* *beval_bufnr-variable*
1969v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1970 valid while evaluating the 'balloonexpr' option.
1971
1972 *v:beval_lnum* *beval_lnum-variable*
1973v:beval_lnum The number of the line, over which the mouse pointer is. Only
1974 valid while evaluating the 'balloonexpr' option.
1975
1976 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001977v:beval_text The text under or after the mouse pointer. Usually a word as
1978 it is useful for debugging a C program. 'iskeyword' applies,
1979 but a dot and "->" before the position is included. When on a
1980 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001981 word before it. When on a Visual area within one line the
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02001982 highlighted text is used. Also see |<cexpr>|.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001983 Only valid while evaluating the 'balloonexpr' option.
1984
1985 *v:beval_winnr* *beval_winnr-variable*
1986v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001987 valid while evaluating the 'balloonexpr' option. The first
1988 window has number zero (unlike most other places where a
1989 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001990
Bram Moolenaar511972d2016-06-04 18:09:59 +02001991 *v:beval_winid* *beval_winid-variable*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001992v:beval_winid The |window-ID| of the window, over which the mouse pointer
1993 is. Otherwise like v:beval_winnr.
Bram Moolenaar511972d2016-06-04 18:09:59 +02001994
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001995 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001996v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001997 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001998 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001999
Bram Moolenaar071d4272004-06-13 20:20:40 +00002000 *v:charconvert_from* *charconvert_from-variable*
2001v:charconvert_from
2002 The name of the character encoding of a file to be converted.
2003 Only valid while evaluating the 'charconvert' option.
2004
2005 *v:charconvert_to* *charconvert_to-variable*
2006v:charconvert_to
2007 The name of the character encoding of a file after conversion.
2008 Only valid while evaluating the 'charconvert' option.
2009
2010 *v:cmdarg* *cmdarg-variable*
2011v:cmdarg This variable is used for two purposes:
2012 1. The extra arguments given to a file read/write command.
2013 Currently these are "++enc=" and "++ff=". This variable is
2014 set before an autocommand event for a file read/write
2015 command is triggered. There is a leading space to make it
2016 possible to append this variable directly after the
Bram Moolenaar58b85342016-08-14 19:54:54 +02002017 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00002018 included here, because it will be executed anyway.
2019 2. When printing a PostScript file with ":hardcopy" this is
2020 the argument for the ":hardcopy" command. This can be used
2021 in 'printexpr'.
2022
2023 *v:cmdbang* *cmdbang-variable*
2024v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
2025 was used the value is 1, otherwise it is 0. Note that this
2026 can only be used in autocommands. For user commands |<bang>|
2027 can be used.
Bram Moolenaar84cf6bd2020-06-16 20:03:43 +02002028 *v:collate* *collate-variable*
2029v:collate The current locale setting for collation order of the runtime
2030 environment. This allows Vim scripts to be aware of the
2031 current locale encoding. Technical: it's the value of
2032 LC_COLLATE. When not using a locale the value is "C".
2033 This variable can not be set directly, use the |:language|
2034 command.
2035 See |multi-lang|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002036
Bram Moolenaar76db9e02022-11-09 21:21:04 +00002037 *v:colornames*
Drew Vogele30d1022021-10-24 20:35:07 +01002038v:colornames A dictionary that maps color names to hex color strings. These
2039 color names can be used with the |highlight-guifg|,
Christian Brabandt0f4054f2024-02-05 10:30:01 +01002040 |highlight-guibg|, and |highlight-guisp| parameters.
2041
2042 The key values in the dictionary (the color names) should be
2043 lower cased, because Vim looks up a color by its lower case
2044 name.
2045
2046 Updating an entry in v:colornames has no immediate effect on
2047 the syntax highlighting. The highlight commands (probably in a
Drew Vogele30d1022021-10-24 20:35:07 +01002048 colorscheme script) need to be re-evaluated in order to use
2049 the updated color values. For example: >
2050
2051 :let v:colornames['fuscia'] = '#cf3ab4'
2052 :let v:colornames['mauve'] = '#915f6d'
2053 :highlight Normal guifg=fuscia guibg=mauve
2054<
2055 This cannot be used to override the |cterm-colors| but it can
2056 be used to override other colors. For example, the X11 colors
2057 defined in the `colors/lists/default.vim` (previously defined
2058 in |rgb.txt|). When defining new color names in a plugin, the
2059 recommended practice is to set a color entry only when it does
2060 not already exist. For example: >
2061
2062 :call extend(v:colornames, {
2063 \ 'fuscia': '#cf3ab4',
2064 \ 'mauve': '#915f6d,
2065 \ }, 'keep')
2066<
Bram Moolenaar113cb512021-11-07 20:27:04 +00002067 Using |extend()| with the 'keep' option updates each color only
Drew Vogele30d1022021-10-24 20:35:07 +01002068 if it did not exist in |v:colornames|. Doing so allows the
2069 user to choose the precise color value for a common name
2070 by setting it in their |.vimrc|.
2071
2072 It is possible to remove entries from this dictionary but
Drew Vogela0fca172021-11-13 10:50:01 +00002073 doing so is NOT recommended, because it is disruptive to
Drew Vogele30d1022021-10-24 20:35:07 +01002074 other scripts. It is also unlikely to achieve the desired
Bram Moolenaar113cb512021-11-07 20:27:04 +00002075 result because the |:colorscheme| and |:highlight| commands will
Drew Vogele30d1022021-10-24 20:35:07 +01002076 both automatically load all `colors/lists/default.vim` color
2077 scripts.
2078
Alin Mr6d1d1802024-03-20 20:26:23 +01002079 You can make changes to that file, but make sure to add new
2080 keys instead of updating existing ones, otherwise Vim will skip
2081 loading the file (thinking is hasn't been changed).
2082
Bram Moolenaar42a45122015-07-10 17:56:23 +02002083 *v:completed_item* *completed_item-variable*
2084v:completed_item
2085 |Dictionary| containing the |complete-items| for the most
2086 recently completed word after |CompleteDone|. The
2087 |Dictionary| is empty if the completion failed.
Shougo Matsushita61021aa2022-07-27 14:40:00 +01002088 Note: Plugins can modify the value to emulate the builtin
2089 |CompleteDone| event behavior.
Bram Moolenaar42a45122015-07-10 17:56:23 +02002090
Bram Moolenaar071d4272004-06-13 20:20:40 +00002091 *v:count* *count-variable*
2092v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar58b85342016-08-14 19:54:54 +02002093 to get the count before a mapping. Read-only. Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002094 :map _x :<C-U>echo "the count is " .. v:count<CR>
Bram Moolenaar071d4272004-06-13 20:20:40 +00002095< Note: The <C-U> is required to remove the line range that you
2096 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002097 When there are two counts, as in "3d2w", they are multiplied,
2098 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002099 Also used for evaluating the 'formatexpr' option.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002100 "count" also works, for backwards compatibility, unless
2101 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002102
2103 *v:count1* *count1-variable*
2104v:count1 Just like "v:count", but defaults to one when no count is
2105 used.
2106
2107 *v:ctype* *ctype-variable*
2108v:ctype The current locale setting for characters of the runtime
2109 environment. This allows Vim scripts to be aware of the
2110 current locale encoding. Technical: it's the value of
2111 LC_CTYPE. When not using a locale the value is "C".
2112 This variable can not be set directly, use the |:language|
2113 command.
2114 See |multi-lang|.
2115
2116 *v:dying* *dying-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002117v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00002118 one. When multiple signals are caught the number increases.
2119 Can be used in an autocommand to check if Vim didn't
2120 terminate normally. {only works on Unix}
2121 Example: >
2122 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02002123< Note: if another deadly signal is caught when v:dying is one,
2124 VimLeave autocommands will not be executed.
2125
Bram Moolenaarf0068c52020-11-30 17:42:10 +01002126 *v:exiting* *exiting-variable*
2127v:exiting Vim exit code. Normally zero, non-zero when something went
2128 wrong. The value is v:null before invoking the |VimLeavePre|
2129 and |VimLeave| autocmds. See |:q|, |:x| and |:cquit|.
2130 Example: >
2131 :au VimLeave * echo "Exit value is " .. v:exiting
2132<
Bram Moolenaar37f4cbd2019-08-23 20:58:45 +02002133 *v:echospace* *echospace-variable*
2134v:echospace Number of screen cells that can be used for an `:echo` message
2135 in the last screen line before causing the |hit-enter-prompt|.
2136 Depends on 'showcmd', 'ruler' and 'columns'. You need to
2137 check 'cmdheight' for whether there are full-width lines
2138 available above the last line.
2139
Bram Moolenaar071d4272004-06-13 20:20:40 +00002140 *v:errmsg* *errmsg-variable*
2141v:errmsg Last given error message. It's allowed to set this variable.
2142 Example: >
2143 :let v:errmsg = ""
2144 :silent! next
2145 :if v:errmsg != ""
2146 : ... handle error
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002147< "errmsg" also works, for backwards compatibility, unless
2148 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002149
Bram Moolenaar65a54642018-04-28 16:56:53 +02002150 *v:errors* *errors-variable* *assert-return*
Bram Moolenaar683fa182015-11-30 21:38:24 +01002151v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01002152 This is a list of strings.
2153 The assert functions append an item when an assert fails.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002154 The return value indicates this: a one is returned if an item
2155 was added to v:errors, otherwise zero is returned.
Bram Moolenaar43345542015-11-29 17:35:35 +01002156 To remove old results make it empty: >
2157 :let v:errors = []
2158< If v:errors is set to anything but a list it is made an empty
2159 list by the assert function.
2160
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01002161 *v:event* *event-variable*
2162v:event Dictionary containing information about the current
Bram Moolenaar560979e2020-02-04 22:53:05 +01002163 |autocommand|. See the specific event for what it puts in
2164 this dictionary.
Bram Moolenaar2c7f8c52020-04-20 19:52:53 +02002165 The dictionary is emptied when the |autocommand| finishes,
2166 please refer to |dict-identity| for how to get an independent
2167 copy of it. Use |deepcopy()| if you want to keep the
2168 information after the event triggers. Example: >
2169 au TextYankPost * let g:foo = deepcopy(v:event)
2170<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002171 *v:exception* *exception-variable*
2172v:exception The value of the exception most recently caught and not
2173 finished. See also |v:throwpoint| and |throw-variables|.
2174 Example: >
2175 :try
2176 : throw "oops"
2177 :catch /.*/
Bram Moolenaar54775062019-07-31 21:07:14 +02002178 : echo "caught " .. v:exception
Bram Moolenaar071d4272004-06-13 20:20:40 +00002179 :endtry
2180< Output: "caught oops".
2181
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002182 *v:false* *false-variable*
2183v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002184 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002185 When used as a string this evaluates to "v:false". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002186 echo v:false
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002187< v:false ~
2188 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002189 value. Read-only.
Bram Moolenaar5da36052021-12-27 15:39:57 +00002190 In |Vim9| script "false" can be used which has a boolean type.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002191
Bram Moolenaar19a09a12005-03-04 23:39:37 +00002192 *v:fcs_reason* *fcs_reason-variable*
2193v:fcs_reason The reason why the |FileChangedShell| event was triggered.
2194 Can be used in an autocommand to decide what to do and/or what
2195 to set v:fcs_choice to. Possible values:
2196 deleted file no longer exists
2197 conflict file contents, mode or timestamp was
2198 changed and buffer is modified
2199 changed file contents has changed
2200 mode mode of file changed
2201 time only file timestamp changed
2202
2203 *v:fcs_choice* *fcs_choice-variable*
2204v:fcs_choice What should happen after a |FileChangedShell| event was
2205 triggered. Can be used in an autocommand to tell Vim what to
2206 do with the affected buffer:
2207 reload Reload the buffer (does not work if
2208 the file was deleted).
Rob Pilling8196e942022-02-11 15:12:10 +00002209 edit Reload the buffer and detect the
2210 values for options such as
2211 'fileformat', 'fileencoding', 'binary'
2212 (does not work if the file was
2213 deleted).
Bram Moolenaar19a09a12005-03-04 23:39:37 +00002214 ask Ask the user what to do, as if there
2215 was no autocommand. Except that when
2216 only the timestamp changed nothing
2217 will happen.
2218 <empty> Nothing, the autocommand should do
2219 everything that needs to be done.
2220 The default is empty. If another (invalid) value is used then
2221 Vim behaves like it is empty, there is no warning message.
2222
Bram Moolenaar4c295022021-05-02 17:19:11 +02002223 *v:fname* *fname-variable*
Bram Moolenaar90df4b92021-07-07 20:26:08 +02002224v:fname When evaluating 'includeexpr': the file name that was
2225 detected. Empty otherwise.
Bram Moolenaar4c295022021-05-02 17:19:11 +02002226
Bram Moolenaar071d4272004-06-13 20:20:40 +00002227 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002228v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002229 option used for ~
2230 'charconvert' file to be converted
2231 'diffexpr' original file
2232 'patchexpr' original file
2233 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00002234 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002235
2236 *v:fname_out* *fname_out-variable*
2237v:fname_out The name of the output file. Only valid while
2238 evaluating:
2239 option used for ~
2240 'charconvert' resulting converted file (*)
2241 'diffexpr' output of diff
2242 'patchexpr' resulting patched file
2243 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar58b85342016-08-14 19:54:54 +02002244 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00002245 for a read command (e.g., ":e file") it will be a temporary
2246 file and different from v:fname_in.
2247
2248 *v:fname_new* *fname_new-variable*
2249v:fname_new The name of the new version of the file. Only valid while
2250 evaluating 'diffexpr'.
2251
2252 *v:fname_diff* *fname_diff-variable*
2253v:fname_diff The name of the diff (patch) file. Only valid while
2254 evaluating 'patchexpr'.
2255
2256 *v:folddashes* *folddashes-variable*
2257v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
2258 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002259 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002260
2261 *v:foldlevel* *foldlevel-variable*
2262v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002263 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002264
2265 *v:foldend* *foldend-variable*
2266v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002267 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002268
2269 *v:foldstart* *foldstart-variable*
2270v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00002271 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002272
Bram Moolenaar817a8802013-11-09 01:44:43 +01002273 *v:hlsearch* *hlsearch-variable*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002274v:hlsearch Variable that indicates whether search highlighting is on.
Bram Moolenaar76440e22014-11-27 19:14:49 +01002275 Setting it makes sense only if 'hlsearch' is enabled which
2276 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01002277 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01002278 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02002279< Note that the value is restored when returning from a
2280 function. |function-search-undo|.
2281
Bram Moolenaar843ee412004-06-30 16:16:41 +00002282 *v:insertmode* *insertmode-variable*
2283v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
2284 events. Values:
2285 i Insert mode
2286 r Replace mode
2287 v Virtual Replace mode
2288
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002289 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002290v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002291 evaluating the expression used with |map()| and |filter()|.
2292 Read-only.
2293
Bram Moolenaar071d4272004-06-13 20:20:40 +00002294 *v:lang* *lang-variable*
2295v:lang The current locale setting for messages of the runtime
2296 environment. This allows Vim scripts to be aware of the
2297 current language. Technical: it's the value of LC_MESSAGES.
2298 The value is system dependent.
2299 This variable can not be set directly, use the |:language|
2300 command.
2301 It can be different from |v:ctype| when messages are desired
2302 in a different language than what is used for character
2303 encoding. See |multi-lang|.
2304
2305 *v:lc_time* *lc_time-variable*
2306v:lc_time The current locale setting for time messages of the runtime
2307 environment. This allows Vim scripts to be aware of the
2308 current language. Technical: it's the value of LC_TIME.
2309 This variable can not be set directly, use the |:language|
2310 command. See |multi-lang|.
2311
2312 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02002313v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
2314 'indentexpr' expressions, tab page number for 'guitablabel'
2315 and 'guitabtooltip'. Only valid while one of these
2316 expressions is being evaluated. Read-only when in the
2317 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002318
naohiro ono56200ee2022-01-01 14:59:44 +00002319 *v:maxcol* *maxcol-variable*
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00002320v:maxcol Maximum line length. Depending on where it is used it can be
Bram Moolenaar944697a2022-02-20 19:48:20 +00002321 screen columns, characters or bytes. The value currently is
2322 2147483647 on all systems.
naohiro ono56200ee2022-01-01 14:59:44 +00002323
Bram Moolenaar219b8702006-11-01 14:32:36 +00002324 *v:mouse_win* *mouse_win-variable*
2325v:mouse_win Window number for a mouse click obtained with |getchar()|.
2326 First window has number 1, like with |winnr()|. The value is
2327 zero when there was no mouse button click.
2328
Bram Moolenaar511972d2016-06-04 18:09:59 +02002329 *v:mouse_winid* *mouse_winid-variable*
2330v:mouse_winid Window ID for a mouse click obtained with |getchar()|.
2331 The value is zero when there was no mouse button click.
2332
Bram Moolenaar219b8702006-11-01 14:32:36 +00002333 *v:mouse_lnum* *mouse_lnum-variable*
2334v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
2335 This is the text line number, not the screen line number. The
2336 value is zero when there was no mouse button click.
2337
2338 *v:mouse_col* *mouse_col-variable*
2339v:mouse_col Column number for a mouse click obtained with |getchar()|.
2340 This is the screen column number, like with |virtcol()|. The
2341 value is zero when there was no mouse button click.
2342
Bram Moolenaard09091d2019-01-17 16:07:22 +01002343 *v:none* *none-variable* *None*
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002344v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002345 |json_encode()|.
Bram Moolenaar2547aa92020-07-26 17:00:44 +02002346 This can also be used as a function argument to use the
2347 default value, see |none-function_argument|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01002348 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002349 When used as a string this evaluates to "v:none". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002350 echo v:none
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002351< v:none ~
2352 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002353 value. Read-only.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00002354 Note that using `== v:none` and `!= v:none` will often give
2355 an error. Instead, use `is v:none` and `isnot v:none` .
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002356
2357 *v:null* *null-variable*
2358v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002359 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01002360 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002361 When used as a string this evaluates to "v:null". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002362 echo v:null
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002363< v:null ~
2364 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002365 value. Read-only.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00002366 In |Vim9| script `null` can be used without "v:".
2367 In some places `v:null` and `null` can be used for a List,
2368 Dict, Job, etc. that is not set. That is slightly different
2369 than an empty List, Dict, etc.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002370
Bram Moolenaar57d5a012021-01-21 21:42:31 +01002371 *v:numbermax* *numbermax-variable*
2372v:numbermax Maximum value of a number.
2373
Bram Moolenaare0e39172021-01-25 21:14:57 +01002374 *v:numbermin* *numbermin-variable*
Bram Moolenaar2346a632021-06-13 19:02:49 +02002375v:numbermin Minimum value of a number (negative).
Bram Moolenaar57d5a012021-01-21 21:42:31 +01002376
Bram Moolenaarf9706e92020-02-22 14:27:04 +01002377 *v:numbersize* *numbersize-variable*
2378v:numbersize Number of bits in a Number. This is normally 64, but on some
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01002379 systems it may be 32.
Bram Moolenaarf9706e92020-02-22 14:27:04 +01002380
Bram Moolenaard812df62008-11-09 12:46:09 +00002381 *v:oldfiles* *oldfiles-variable*
2382v:oldfiles List of file names that is loaded from the |viminfo| file on
2383 startup. These are the files that Vim remembers marks for.
2384 The length of the List is limited by the ' argument of the
2385 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01002386 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00002387 Also see |:oldfiles| and |c_#<|.
2388 The List can be modified, but this has no effect on what is
2389 stored in the |viminfo| file later. If you use values other
2390 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02002391 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00002392
Bram Moolenaar53744302015-07-17 17:38:22 +02002393 *v:option_new*
2394v:option_new New value of the option. Valid while executing an |OptionSet|
2395 autocommand.
2396 *v:option_old*
2397v:option_old Old value of the option. Valid while executing an |OptionSet|
Bram Moolenaard7c96872019-06-15 17:12:48 +02002398 autocommand. Depending on the command used for setting and the
2399 kind of option this is either the local old value or the
2400 global old value.
2401 *v:option_oldlocal*
2402v:option_oldlocal
2403 Old local value of the option. Valid while executing an
2404 |OptionSet| autocommand.
2405 *v:option_oldglobal*
2406v:option_oldglobal
2407 Old global value of the option. Valid while executing an
2408 |OptionSet| autocommand.
Bram Moolenaar53744302015-07-17 17:38:22 +02002409 *v:option_type*
2410v:option_type Scope of the set command. Valid while executing an
2411 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaard7c96872019-06-15 17:12:48 +02002412 *v:option_command*
2413v:option_command
2414 Command used to set the option. Valid while executing an
2415 |OptionSet| autocommand.
2416 value option was set via ~
2417 "setlocal" |:setlocal| or ":let l:xxx"
2418 "setglobal" |:setglobal| or ":let g:xxx"
2419 "set" |:set| or |:let|
2420 "modeline" |modeline|
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00002421 *v:operator* *operator-variable*
2422v:operator The last operator given in Normal mode. This is a single
2423 character except for commands starting with <g> or <z>,
2424 in which case it is two characters. Best used alongside
2425 |v:prevcount| and |v:register|. Useful if you want to cancel
2426 Operator-pending mode and then use the operator, e.g.: >
2427 :omap O <Esc>:call MyMotion(v:operator)<CR>
2428< The value remains set until another operator is entered, thus
2429 don't expect it to be empty.
2430 v:operator is not set for |:delete|, |:yank| or other Ex
2431 commands.
2432 Read-only.
2433
Bram Moolenaar071d4272004-06-13 20:20:40 +00002434 *v:prevcount* *prevcount-variable*
2435v:prevcount The count given for the last but one Normal mode command.
2436 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00002437 you want to cancel Visual or Operator-pending mode and then
2438 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002439 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
2440< Read-only.
2441
Bram Moolenaar05159a02005-02-26 23:04:13 +00002442 *v:profiling* *profiling-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002443v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00002444 See |profiling|.
2445
Bram Moolenaar071d4272004-06-13 20:20:40 +00002446 *v:progname* *progname-variable*
2447v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02002448 invoked. Allows you to do special initialisations for |view|,
2449 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002450 Read-only.
2451
Bram Moolenaara1706c92014-04-01 19:55:49 +02002452 *v:progpath* *progpath-variable*
Bram Moolenaar56c860c2019-08-17 20:09:31 +02002453v:progpath Contains the command with which Vim was invoked, in a form
2454 that when passed to the shell will run the same Vim executable
2455 as the current one (if $PATH remains unchanged).
2456 Useful if you want to message a Vim server using a
Bram Moolenaara1706c92014-04-01 19:55:49 +02002457 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02002458 To get the full path use: >
2459 echo exepath(v:progpath)
Bram Moolenaar56c860c2019-08-17 20:09:31 +02002460< If the command has a relative path it will be expanded to the
2461 full path, so that it still works after `:cd`. Thus starting
2462 "./vim" results in "/home/user/path/to/vim/src/vim".
2463 On Linux and other systems it will always be the full path.
2464 On Mac it may just be "vim" and using exepath() as mentioned
2465 above should be used to get the full path.
Bram Moolenaar08cab962017-03-04 14:37:18 +01002466 On MS-Windows the executable may be called "vim.exe", but the
2467 ".exe" is not added to v:progpath.
Bram Moolenaara1706c92014-04-01 19:55:49 +02002468 Read-only.
2469
h_eastba77bbb2023-10-03 04:47:13 +09002470 *v:python3_version* *python3-version-variable*
Yee Cheng Chinc13b3d12023-08-20 21:18:38 +02002471v:python3_version
2472 Version of Python 3 that Vim was built against. When
2473 Python is loaded dynamically (|python-dynamic|), this version
2474 should exactly match the Python library up to the minor
2475 version (e.g. 3.10.2 and 3.10.3 are compatible as the minor
2476 version is "10", whereas 3.9.4 and 3.10.3 are not compatible).
2477 When |python-stable-abi| is used, this will be the minimum Python
2478 version that you can use instead. (e.g. if v:python3_version
2479 indicates 3.9, you can use 3.9, 3.10, or anything above).
2480
2481 This number is encoded as a hex number following Python ABI
2482 versioning conventions. Do the following to have a
2483 human-readable full version in hex: >
2484 echo printf("%08X", v:python3_version)
2485< You can obtain only the minor version by doing: >
2486 echo and(v:python3_version>>16,0xff)
2487< Read-only.
2488
Bram Moolenaar071d4272004-06-13 20:20:40 +00002489 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01002490v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02002491 command (regardless of whether that command actually used a
2492 register). Or for the currently executing normal mode mapping
2493 (use this in custom commands that take a register).
2494 If none is supplied it is the default register '"', unless
2495 'clipboard' contains "unnamed" or "unnamedplus", then it is
2496 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01002497 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002498
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002499 *v:scrollstart* *scrollstart-variable*
2500v:scrollstart String describing the script or function that caused the
2501 screen to scroll up. It's only set when it is empty, thus the
2502 first reason is remembered. It is set to "Unknown" for a
2503 typed command.
2504 This can be used to find out why your script causes the
2505 hit-enter prompt.
2506
Bram Moolenaar071d4272004-06-13 20:20:40 +00002507 *v:servername* *servername-variable*
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002508v:servername The resulting registered |client-server-name| if any.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002509 Read-only.
2510
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002511
Bram Moolenaar446cb832008-06-24 21:56:24 +00002512v:searchforward *v:searchforward* *searchforward-variable*
2513 Search direction: 1 after a forward search, 0 after a
2514 backward search. It is reset to forward when directly setting
2515 the last search pattern, see |quote/|.
2516 Note that the value is restored when returning from a
2517 function. |function-search-undo|.
2518 Read-write.
2519
Bram Moolenaar071d4272004-06-13 20:20:40 +00002520 *v:shell_error* *shell_error-variable*
2521v:shell_error Result of the last shell command. When non-zero, the last
2522 shell command had an error. When zero, there was no problem.
2523 This only works when the shell returns the error code to Vim.
2524 The value -1 is often used when the command could not be
2525 executed. Read-only.
2526 Example: >
2527 :!mv foo bar
2528 :if v:shell_error
2529 : echo 'could not rename "foo" to "bar"!'
2530 :endif
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002531< "shell_error" also works, for backwards compatibility, unless
2532 |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002533
Bram Moolenaar113cb512021-11-07 20:27:04 +00002534 *v:sizeofint* *sizeofint-variable*
2535v:sizeofint Number of bytes in an int. Depends on how Vim was compiled.
2536 This is only useful for deciding whether a test will give the
2537 expected result.
2538
2539 *v:sizeoflong* *sizeoflong-variable*
2540v:sizeoflong Number of bytes in a long. Depends on how Vim was compiled.
2541 This is only useful for deciding whether a test will give the
2542 expected result.
2543
2544 *v:sizeofpointer* *sizeofpointer-variable*
2545v:sizeofpointer Number of bytes in a pointer. Depends on how Vim was compiled.
2546 This is only useful for deciding whether a test will give the
2547 expected result.
2548
Bram Moolenaar071d4272004-06-13 20:20:40 +00002549 *v:statusmsg* *statusmsg-variable*
2550v:statusmsg Last given status message. It's allowed to set this variable.
2551
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002552 *v:swapname* *swapname-variable*
2553v:swapname Only valid when executing |SwapExists| autocommands: Name of
2554 the swap file found. Read-only.
2555
2556 *v:swapchoice* *swapchoice-variable*
2557v:swapchoice |SwapExists| autocommands can set this to the selected choice
2558 for handling an existing swap file:
2559 'o' Open read-only
2560 'e' Edit anyway
2561 'r' Recover
2562 'd' Delete swapfile
2563 'q' Quit
2564 'a' Abort
Bram Moolenaar58b85342016-08-14 19:54:54 +02002565 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002566 results in the user being asked, as would happen when there is
2567 no SwapExists autocommand. The default is empty.
2568
Bram Moolenaarb3480382005-12-11 21:33:32 +00002569 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00002570v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00002571 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar58b85342016-08-14 19:54:54 +02002572 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00002573 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00002574 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00002575
Bram Moolenaard823fa92016-08-12 16:29:27 +02002576 *v:t_TYPE* *v:t_bool* *t_bool-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002577v:t_bool Value of |Boolean| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002578 *v:t_channel* *t_channel-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002579v:t_channel Value of |Channel| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002580 *v:t_dict* *t_dict-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002581v:t_dict Value of |Dictionary| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002582 *v:t_float* *t_float-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002583v:t_float Value of |Float| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002584 *v:t_func* *t_func-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002585v:t_func Value of |Funcref| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002586 *v:t_job* *t_job-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002587v:t_job Value of |Job| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002588 *v:t_list* *t_list-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002589v:t_list Value of |List| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002590 *v:t_none* *t_none-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002591v:t_none Value of |None| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002592 *v:t_number* *t_number-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002593v:t_number Value of |Number| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002594 *v:t_string* *t_string-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002595v:t_string Value of |String| type. Read-only. See: |type()|
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002596 *v:t_blob* *t_blob-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002597v:t_blob Value of |Blob| type. Read-only. See: |type()|
Bram Moolenaarc0c2c262023-01-12 21:08:53 +00002598 *v:t_class* *t_class-variable*
2599v:t_class Value of |class| type. Read-only. See: |type()|
2600 *v:t_object* *t_object-variable*
2601v:t_object Value of |object| type. Read-only. See: |type()|
Yegappan Lakshmanan2a71b542023-12-14 20:03:03 +01002602 *v:t_typealias* *t_typealias-variable*
2603v:t_typealias Value of |typealias| type. Read-only. See: |type()|
Bram Moolenaarf562e722016-07-19 17:25:25 +02002604
Bram Moolenaar071d4272004-06-13 20:20:40 +00002605 *v:termresponse* *termresponse-variable*
2606v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar58b85342016-08-14 19:54:54 +02002607 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaarb4230122019-05-30 18:40:53 +02002608 that starts with ESC [ or CSI, then '>' or '?' and ends in a
2609 'c', with only digits and ';' in between.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002610 When this option is set, the TermResponse autocommand event is
2611 fired, so that you can react to the response from the
Danek Duvalld7d56032024-01-14 20:19:59 +01002612 terminal. The TermResponseAll event is also fired, with
2613 <amatch> set to "version". You can use |terminalprops()| to see
2614 what Vim figured out about the terminal.
Bram Moolenaarb4230122019-05-30 18:40:53 +02002615 The response from a new xterm is: "<Esc>[> Pp ; Pv ; Pc c". Pp
Bram Moolenaar071d4272004-06-13 20:20:40 +00002616 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
2617 patch level (since this was introduced in patch 95, it's
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00002618 always 95 or higher). Pc is always zero.
2619 If Pv is 141 or higher then Vim will try to request terminal
2620 codes. This only works with xterm |xterm-codes|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002621 {only when compiled with |+termresponse| feature}
2622
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002623 *v:termblinkresp*
2624v:termblinkresp The escape sequence returned by the terminal for the |t_RC|
2625 termcap entry. This is used to find out whether the terminal
Danek Duvalld7d56032024-01-14 20:19:59 +01002626 cursor is blinking. This is used by |term_getcursor()|. When
2627 this option is set, the TermResponseAll autocommand event is
2628 fired, with <amatch> set to "cursorblink".
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002629
2630 *v:termstyleresp*
2631v:termstyleresp The escape sequence returned by the terminal for the |t_RS|
2632 termcap entry. This is used to find out what the shape of the
Danek Duvalld7d56032024-01-14 20:19:59 +01002633 cursor is. This is used by |term_getcursor()|. When this
2634 option is set, the TermResponseAll autocommand event is fired,
2635 with <amatch> set to "cursorshape".
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002636
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002637 *v:termrbgresp*
2638v:termrbgresp The escape sequence returned by the terminal for the |t_RB|
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002639 termcap entry. This is used to find out what the terminal
Danek Duvalld7d56032024-01-14 20:19:59 +01002640 background color is; see 'background'. When this option is
2641 set, the TermResponseAll autocommand event is fired, with
2642 <amatch> set to "background".
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002643
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002644 *v:termrfgresp*
2645v:termrfgresp The escape sequence returned by the terminal for the |t_RF|
2646 termcap entry. This is used to find out what the terminal
Danek Duvalld7d56032024-01-14 20:19:59 +01002647 foreground color is. When this option is set, the
2648 TermResponseAll autocommand event is fired, with <amatch> set
2649 to "foreground".
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002650
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002651 *v:termu7resp*
2652v:termu7resp The escape sequence returned by the terminal for the |t_u7|
2653 termcap entry. This is used to find out what the terminal
Danek Duvalld7d56032024-01-14 20:19:59 +01002654 does with ambiguous width characters, see 'ambiwidth'. When
2655 this option is set, the TermResponseAll autocommand event is
2656 fired, with <amatch> set to "ambiguouswidth".
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002657
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002658 *v:testing* *testing-variable*
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002659v:testing Must be set before using `test_garbagecollect_now()`.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002660 Also, when set certain error messages won't be shown for 2
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002661 seconds. (e.g. "'dictionary' option is empty")
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002662
Bram Moolenaar071d4272004-06-13 20:20:40 +00002663 *v:this_session* *this_session-variable*
2664v:this_session Full filename of the last loaded or saved session file. See
2665 |:mksession|. It is allowed to set this variable. When no
2666 session file has been saved, this variable is empty.
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002667 "this_session" also works, for backwards compatibility, unless
2668 |scriptversion| is 3 or higher
Bram Moolenaar071d4272004-06-13 20:20:40 +00002669
2670 *v:throwpoint* *throwpoint-variable*
2671v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar58b85342016-08-14 19:54:54 +02002672 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00002673 also |v:exception| and |throw-variables|.
2674 Example: >
2675 :try
2676 : throw "oops"
2677 :catch /.*/
2678 : echo "Exception from" v:throwpoint
2679 :endtry
2680< Output: "Exception from test.vim, line 2"
2681
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002682 *v:true* *true-variable*
2683v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002684 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002685 When used as a string this evaluates to "v:true". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002686 echo v:true
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002687< v:true ~
2688 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002689 value. Read-only.
Bram Moolenaar5da36052021-12-27 15:39:57 +00002690 In |Vim9| script "true" can be used which has a boolean type.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002691 *v:val* *val-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002692v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002693 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002694 |filter()|. Read-only.
2695
Bram Moolenaar071d4272004-06-13 20:20:40 +00002696 *v:version* *version-variable*
2697v:version Version number of Vim: Major version number times 100 plus
Bram Moolenaar9b283522019-06-17 22:19:33 +02002698 minor version number. Version 5.0 is 500. Version 5.1
Bram Moolenaar071d4272004-06-13 20:20:40 +00002699 is 501. Read-only. "version" also works, for backwards
Bram Moolenaard2e716e2019-04-20 14:39:52 +02002700 compatibility, unless |scriptversion| is 3 or higher.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002701 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02002702 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002703< Note that patch numbers are specific to the version, thus both
2704 version 5.0 and 5.1 may have a patch 123, but these are
2705 completely different.
2706
Bram Moolenaar37df9a42019-06-14 14:39:51 +02002707 *v:versionlong* *versionlong-variable*
Bram Moolenaar9b283522019-06-17 22:19:33 +02002708v:versionlong Like v:version, but also including the patchlevel in the last
2709 four digits. Version 8.1 with patch 123 has value 8010123.
2710 This can be used like this: >
2711 if v:versionlong >= 8010123
Bram Moolenaar37df9a42019-06-14 14:39:51 +02002712< However, if there are gaps in the list of patches included
2713 this will not work well. This can happen if a recent patch
2714 was included into an older version, e.g. for a security fix.
2715 Use the has() function to make sure the patch is actually
2716 included.
2717
Bram Moolenaar14735512016-03-26 21:00:08 +01002718 *v:vim_did_enter* *vim_did_enter-variable*
2719v:vim_did_enter Zero until most of startup is done. It is set to one just
2720 before |VimEnter| autocommands are triggered.
2721
Bram Moolenaar071d4272004-06-13 20:20:40 +00002722 *v:warningmsg* *warningmsg-variable*
2723v:warningmsg Last given warning message. It's allowed to set this variable.
2724
Bram Moolenaar727c8762010-10-20 19:17:48 +02002725 *v:windowid* *windowid-variable*
2726v:windowid When any X11 based GUI is running or when running in a
2727 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02002728 set to the window ID.
2729 When an MS-Windows GUI is running this will be set to the
2730 window handle.
2731 Otherwise the value is zero.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002732 Note: for windows inside Vim use |winnr()| or |win_getid()|,
2733 see |window-ID|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02002734
Bram Moolenaar071d4272004-06-13 20:20:40 +00002735==============================================================================
27364. Builtin Functions *functions*
2737
2738See |function-list| for a list grouped by what the function is used for.
2739
Bram Moolenaar1cae5a02021-12-27 21:28:34 +00002740The alphabetic list of all builtin functions and details are in a separate
2741help file: |builtin-functions|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002742
2743==============================================================================
27445. Defining functions *user-functions*
2745
2746New functions can be defined. These can be called just like builtin
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01002747functions. The function takes arguments, executes a sequence of Ex commands
2748and can return a value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002749
Bram Moolenaar0daafaa2022-09-04 17:45:43 +01002750You can find most information about defining functions in |userfunc.txt|.
2751For Vim9 functions, which execute much faster, support type checking and more,
2752see |vim9.txt|.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00002753
Bram Moolenaar071d4272004-06-13 20:20:40 +00002754==============================================================================
27556. Curly braces names *curly-braces-names*
2756
Bram Moolenaar84f72352012-03-11 15:57:40 +01002757In most places where you can use a variable, you can use a "curly braces name"
2758variable. This is a regular variable name with one or more expressions
2759wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002760 my_{adjective}_variable
2761
Bram Moolenaar5da36052021-12-27 15:39:57 +00002762This only works in legacy Vim script, not in |Vim9| script.
2763
Bram Moolenaar071d4272004-06-13 20:20:40 +00002764When Vim encounters this, it evaluates the expression inside the braces, puts
2765that in place of the expression, and re-interprets the whole as a variable
2766name. So in the above example, if the variable "adjective" was set to
2767"noisy", then the reference would be to "my_noisy_variable", whereas if
2768"adjective" was set to "quiet", then it would be to "my_quiet_variable".
2769
2770One application for this is to create a set of variables governed by an option
Bram Moolenaar58b85342016-08-14 19:54:54 +02002771value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002772 echo my_{&background}_message
2773
2774would output the contents of "my_dark_message" or "my_light_message" depending
2775on the current value of 'background'.
2776
2777You can use multiple brace pairs: >
2778 echo my_{adverb}_{adjective}_message
2779..or even nest them: >
2780 echo my_{ad{end_of_word}}_message
2781where "end_of_word" is either "verb" or "jective".
2782
2783However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002784variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002785 :let foo='a + b'
2786 :echo c{foo}d
2787.. since the result of expansion is "ca + bd", which is not a variable name.
2788
2789 *curly-braces-function-names*
2790You can call and define functions by an evaluated name in a similar way.
2791Example: >
2792 :let func_end='whizz'
2793 :call my_func_{func_end}(parameter)
2794
2795This would call the function "my_func_whizz(parameter)".
2796
Bram Moolenaar84f72352012-03-11 15:57:40 +01002797This does NOT work: >
2798 :let i = 3
2799 :let @{i} = '' " error
2800 :echo @{i} " error
2801
Bram Moolenaar071d4272004-06-13 20:20:40 +00002802==============================================================================
28037. Commands *expression-commands*
2804
Bram Moolenaar5da36052021-12-27 15:39:57 +00002805Note: in |Vim9| script `:let` is not used. `:var` is used for variable
2806declarations and assignments do not use a command. |vim9-declaration|
Bram Moolenaar65e0d772020-06-14 17:29:55 +02002807
Bram Moolenaar071d4272004-06-13 20:20:40 +00002808:let {var-name} = {expr1} *:let* *E18*
2809 Set internal variable {var-name} to the result of the
2810 expression {expr1}. The variable will get the type
2811 from the {expr}. If {var-name} didn't exist yet, it
2812 is created.
2813
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002814:let {var-name}[{idx}] = {expr1} *E689* *E1141*
Bram Moolenaar13065c42005-01-08 16:08:21 +00002815 Set a list item to the result of the expression
2816 {expr1}. {var-name} must refer to a list and {idx}
2817 must be a valid index in that list. For nested list
2818 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +00002819 This cannot be used to add an item to a |List|.
Bram Moolenaar58b85342016-08-14 19:54:54 +02002820 This cannot be used to set a byte in a String. You
Bram Moolenaar446cb832008-06-24 21:56:24 +00002821 can do that like this: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002822 :let var = var[0:2] .. 'X' .. var[4:]
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002823< When {var-name} is a |Blob| then {idx} can be the
2824 length of the blob, in which case one byte is
2825 appended.
2826
Bram Moolenaara2baa732022-02-04 16:09:54 +00002827 *E711* *E719* *E1165* *E1166* *E1183*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002828:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002829 Set a sequence of items in a |List| to the result of
2830 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002831 correct number of items.
2832 {idx1} can be omitted, zero is used instead.
2833 {idx2} can be omitted, meaning the end of the list.
2834 When the selected range of items is partly past the
2835 end of the list, items will be added.
2836
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00002837 *:let+=* *:let-=* *:letstar=* *:let/=* *:let%=*
2838 *:let.=* *:let..=* *E734* *E985* *E1019*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002839:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
2840:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
Bram Moolenaarff697e62019-02-12 22:28:33 +01002841:let {var} *= {expr1} Like ":let {var} = {var} * {expr1}".
2842:let {var} /= {expr1} Like ":let {var} = {var} / {expr1}".
2843:let {var} %= {expr1} Like ":let {var} = {var} % {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002844:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02002845:let {var} ..= {expr1} Like ":let {var} = {var} .. {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002846 These fail if {var} was not set yet and when the type
2847 of {var} and {expr1} don't fit the operator.
zeertzjqb8170142024-02-08 11:21:44 +01002848 `+=` modifies a |List| or a |Blob| in-place instead of
2849 creating a new one.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02002850 `.=` is not supported with Vim script version 2 and
2851 later, see |vimscript-version|.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002852
2853
Bram Moolenaar071d4272004-06-13 20:20:40 +00002854:let ${env-name} = {expr1} *:let-environment* *:let-$*
2855 Set environment variable {env-name} to the result of
2856 the expression {expr1}. The type is always String.
Bram Moolenaar56c860c2019-08-17 20:09:31 +02002857
2858 On some systems making an environment variable empty
2859 causes it to be deleted. Many systems do not make a
2860 difference between an environment variable that is not
2861 set and an environment variable that is empty.
2862
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002863:let ${env-name} .= {expr1}
2864 Append {expr1} to the environment variable {env-name}.
2865 If the environment variable didn't exist yet this
2866 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +00002867
2868:let @{reg-name} = {expr1} *:let-register* *:let-@*
2869 Write the result of the expression {expr1} in register
2870 {reg-name}. {reg-name} must be a single letter, and
2871 must be the name of a writable register (see
2872 |registers|). "@@" can be used for the unnamed
2873 register, "@/" for the search pattern.
2874 If the result of {expr1} ends in a <CR> or <NL>, the
2875 register will be linewise, otherwise it will be set to
2876 characterwise.
2877 This can be used to clear the last search pattern: >
2878 :let @/ = ""
2879< This is different from searching for an empty string,
2880 that would match everywhere.
2881
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002882:let @{reg-name} .= {expr1}
Bram Moolenaar58b85342016-08-14 19:54:54 +02002883 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002884 register was empty it's like setting it to {expr1}.
2885
Bram Moolenaaref2f6562007-05-06 13:32:59 +00002886:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002887 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +00002888 expression {expr1}. A String or Number value is
2889 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002890 For an option local to a window or buffer the effect
2891 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +00002892 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00002893 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00002894 :let &path = &path .. ',/usr/local/include'
Bram Moolenaar3df01732017-02-17 22:47:16 +01002895< This also works for terminal codes in the form t_xx.
2896 But only for alphanumerical names. Example: >
2897 :let &t_k1 = "\<Esc>[234;"
2898< When the code does not exist yet it will be created as
2899 a terminal key code, there is no error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002900
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002901:let &{option-name} .= {expr1}
2902 For a string option: Append {expr1} to the value.
2903 Does not insert a comma like |:set+=|.
2904
2905:let &{option-name} += {expr1}
2906:let &{option-name} -= {expr1}
2907 For a number or boolean option: Add or subtract
2908 {expr1}.
2909
Bram Moolenaar071d4272004-06-13 20:20:40 +00002910:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002911:let &l:{option-name} .= {expr1}
2912:let &l:{option-name} += {expr1}
2913:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002914 Like above, but only set the local value of an option
2915 (if there is one). Works like |:setlocal|.
2916
2917:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002918:let &g:{option-name} .= {expr1}
2919:let &g:{option-name} += {expr1}
2920:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002921 Like above, but only set the global value of an option
2922 (if there is one). Works like |:setglobal|.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002923 *E1093*
Bram Moolenaar13065c42005-01-08 16:08:21 +00002924:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002925 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +00002926 the list is assigned to {name1}, the second item to
2927 {name2}, etc.
2928 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002929 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00002930 Each name can be one of the items of the ":let"
2931 command as mentioned above.
2932 Example: >
2933 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002934< Detail: {expr1} is evaluated first, then the
2935 assignments are done in sequence. This matters if
2936 {name2} depends on {name1}. Example: >
2937 :let x = [0, 1]
2938 :let i = 0
2939 :let [i, x[i]] = [1, 2]
2940 :echo x
2941< The result is [0, 2].
2942
2943:let [{name1}, {name2}, ...] .= {expr1}
2944:let [{name1}, {name2}, ...] += {expr1}
2945:let [{name1}, {name2}, ...] -= {expr1}
2946 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002947 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00002948
Bram Moolenaard1caa942020-04-10 22:10:56 +02002949:let [{name}, ..., ; {lastname}] = {expr1} *E452*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002950 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002951 items than there are names. A list of the remaining
2952 items is assigned to {lastname}. If there are no
2953 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +00002954 Example: >
2955 :let [a, b; rest] = ["aval", "bval", 3, 4]
2956<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00002957:let [{name}, ..., ; {lastname}] .= {expr1}
2958:let [{name}, ..., ; {lastname}] += {expr1}
2959:let [{name}, ..., ; {lastname}] -= {expr1}
2960 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002961 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +02002962
Bram Moolenaar24582002019-07-21 14:14:26 +02002963 *:let=<<* *:let-heredoc*
Bram Moolenaarf10911e2022-01-29 22:20:48 +00002964 *E990* *E991* *E172* *E221* *E1145*
Yegappan Lakshmananefbfa862022-04-17 12:47:40 +01002965:let {var-name} =<< [trim] [eval] {endmarker}
Bram Moolenaarf5842c52019-05-19 18:41:26 +02002966text...
2967text...
Bram Moolenaar2e693a82019-10-16 22:35:02 +02002968{endmarker}
Bram Moolenaare46a4402020-06-30 20:38:27 +02002969 Set internal variable {var-name} to a |List|
2970 containing the lines of text bounded by the string
Yegappan Lakshmananefbfa862022-04-17 12:47:40 +01002971 {endmarker}.
2972
2973 If "eval" is not specified, then each line of text is
Bram Moolenaard899e512022-05-07 21:54:03 +01002974 used as a |literal-string|, except that single quotes
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01002975 does not need to be doubled.
Bram Moolenaard899e512022-05-07 21:54:03 +01002976 If "eval" is specified, then any Vim expression in the
2977 form {expr} is evaluated and the result replaces the
Bram Moolenaarb59ae592022-11-23 23:46:31 +00002978 expression, like with |interpolated-string|.
Yegappan Lakshmananefbfa862022-04-17 12:47:40 +01002979 Example where $HOME is expanded: >
2980 let lines =<< trim eval END
2981 some text
Bram Moolenaard899e512022-05-07 21:54:03 +01002982 See the file {$HOME}/.vimrc
Yegappan Lakshmananefbfa862022-04-17 12:47:40 +01002983 more text
2984 END
2985< There can be multiple Vim expressions in a single line
2986 but an expression cannot span multiple lines. If any
2987 expression evaluation fails, then the assignment fails.
Yegappan Lakshmananefbfa862022-04-17 12:47:40 +01002988
Bram Moolenaar2e693a82019-10-16 22:35:02 +02002989 {endmarker} must not contain white space.
2990 {endmarker} cannot start with a lower case character.
2991 The last line should end only with the {endmarker}
2992 string without any other character. Watch out for
2993 white space after {endmarker}!
Bram Moolenaarf5842c52019-05-19 18:41:26 +02002994
Bram Moolenaare7eb9272019-06-24 00:58:07 +02002995 Without "trim" any white space characters in the lines
2996 of text are preserved. If "trim" is specified before
Bram Moolenaar2e693a82019-10-16 22:35:02 +02002997 {endmarker}, then indentation is stripped so you can
2998 do: >
Bram Moolenaare7eb9272019-06-24 00:58:07 +02002999 let text =<< trim END
3000 if ok
3001 echo 'done'
3002 endif
3003 END
3004< Results in: ["if ok", " echo 'done'", "endif"]
3005 The marker must line up with "let" and the indentation
3006 of the first line is removed from all the text lines.
3007 Specifically: all the leading indentation exactly
3008 matching the leading indentation of the first
3009 non-empty text line is stripped from the input lines.
3010 All leading indentation exactly matching the leading
3011 indentation before `let` is stripped from the line
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003012 containing {endmarker}. Note that the difference
3013 between space and tab matters here.
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003014
3015 If {var-name} didn't exist yet, it is created.
3016 Cannot be followed by another command, but can be
3017 followed by a comment.
3018
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003019 To avoid line continuation to be applied, consider
3020 adding 'C' to 'cpoptions': >
3021 set cpo+=C
3022 let var =<< END
3023 \ leading backslash
3024 END
3025 set cpo-=C
3026<
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003027 Examples: >
3028 let var1 =<< END
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003029 Sample text 1
3030 Sample text 2
3031 Sample text 3
3032 END
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003033
3034 let data =<< trim DATA
Bram Moolenaar2e693a82019-10-16 22:35:02 +02003035 1 2 3 4
3036 5 6 7 8
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003037 DATA
Yegappan Lakshmananefbfa862022-04-17 12:47:40 +01003038
3039 let code =<< trim eval CODE
Bram Moolenaard899e512022-05-07 21:54:03 +01003040 let v = {10 + 20}
3041 let h = "{$HOME}"
3042 let s = "{Str1()} abc {Str2()}"
3043 let n = {MyFunc(3, 4)}
Yegappan Lakshmananefbfa862022-04-17 12:47:40 +01003044 CODE
Bram Moolenaarf5842c52019-05-19 18:41:26 +02003045<
Bram Moolenaar4a748032010-09-30 21:47:56 +02003046 *E121*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003047:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00003048 variable names may be given. Special names recognized
3049 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +00003050 g: global variables
3051 b: local buffer variables
3052 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003053 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +00003054 s: script-local variables
3055 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +00003056 v: Vim variables.
Bram Moolenaar65e0d772020-06-14 17:29:55 +02003057 This does not work in Vim9 script. |vim9-declaration|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003058
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003059:let List the values of all variables. The type of the
3060 variable is indicated before the value:
3061 <nothing> String
3062 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003063 * Funcref
Bram Moolenaar65e0d772020-06-14 17:29:55 +02003064 This does not work in Vim9 script. |vim9-declaration|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003065
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003066:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795* *E1081*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003067 Remove the internal variable {name}. Several variable
3068 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003069 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003070 With [!] no error message is given for non-existing
3071 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003072 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00003073 :unlet list[3] " remove fourth item
3074 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003075< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +00003076 :unlet dict['two']
3077 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +00003078< This is especially useful to clean up used global
3079 variables and script-local variables (these are not
3080 deleted when the script ends). Function-local
3081 variables are automatically deleted when the function
3082 ends.
Bram Moolenaar1b5f03e2023-01-09 20:12:45 +00003083 In |Vim9| script variables declared in a function or
3084 script cannot be removed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003085
Bram Moolenaar137374f2018-05-13 15:59:50 +02003086:unl[et] ${env-name} ... *:unlet-environment* *:unlet-$*
3087 Remove environment variable {env-name}.
3088 Can mix {name} and ${env-name} in one :unlet command.
3089 No error message is given for a non-existing
3090 variable, also without !.
3091 If the system does not support deleting an environment
Bram Moolenaar9937a052019-06-15 15:45:06 +02003092 variable, it is made empty.
Bram Moolenaar137374f2018-05-13 15:59:50 +02003093
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003094 *:cons* *:const* *E1018*
Bram Moolenaar9937a052019-06-15 15:45:06 +02003095:cons[t] {var-name} = {expr1}
3096:cons[t] [{name1}, {name2}, ...] = {expr1}
Bram Moolenaar9937a052019-06-15 15:45:06 +02003097:cons[t] [{name}, ..., ; {lastname}] = {expr1}
3098:cons[t] {var-name} =<< [trim] {marker}
3099text...
3100text...
3101{marker}
3102 Similar to |:let|, but additionally lock the variable
3103 after setting the value. This is the same as locking
3104 the variable with |:lockvar| just after |:let|, thus: >
3105 :const x = 1
3106< is equivalent to: >
3107 :let x = 1
Bram Moolenaar021bda52020-08-17 21:07:22 +02003108 :lockvar! x
Bram Moolenaara187c432020-09-16 21:08:28 +02003109< NOTE: in Vim9 script `:const` works differently, see
3110 |vim9-const|
3111 This is useful if you want to make sure the variable
Bram Moolenaar021bda52020-08-17 21:07:22 +02003112 is not modified. If the value is a List or Dictionary
3113 literal then the items also cannot be changed: >
3114 const ll = [1, 2, 3]
3115 let ll[1] = 5 " Error!
Bram Moolenaar6e649222021-10-04 21:32:54 +01003116< Nested references are not locked: >
Bram Moolenaar021bda52020-08-17 21:07:22 +02003117 let lvar = ['a']
3118 const lconst = [0, lvar]
3119 let lconst[0] = 2 " Error!
3120 let lconst[1][0] = 'b' " OK
3121< *E995*
Bram Moolenaar9b283522019-06-17 22:19:33 +02003122 |:const| does not allow to for changing a variable: >
Bram Moolenaar9937a052019-06-15 15:45:06 +02003123 :let x = 1
3124 :const x = 2 " Error!
Bram Moolenaar1c196e72019-06-16 15:41:58 +02003125< *E996*
3126 Note that environment variables, option values and
3127 register values cannot be used here, since they cannot
3128 be locked.
3129
Bram Moolenaar85850f32019-07-19 22:05:51 +02003130:cons[t]
3131:cons[t] {var-name}
3132 If no argument is given or only {var-name} is given,
3133 the behavior is the same as |:let|.
3134
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003135:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
3136 Lock the internal variable {name}. Locking means that
3137 it can no longer be changed (until it is unlocked).
3138 A locked variable can be deleted: >
3139 :lockvar v
Bram Moolenaardad44732021-03-31 20:07:33 +02003140 :let v = 'asdf' " fails!
3141 :unlet v " works
Bram Moolenaarf10911e2022-01-29 22:20:48 +00003142< *E741* *E940* *E1118* *E1119* *E1120* *E1121* *E1122*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003143 If you try to change a locked variable you get an
Bram Moolenaare7877fe2017-02-20 22:35:33 +01003144 error message: "E741: Value is locked: {name}".
3145 If you try to lock or unlock a built-in variable you
3146 get an error message: "E940: Cannot lock or unlock
3147 variable {name}".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003148
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003149 [depth] is relevant when locking a |List| or
3150 |Dictionary|. It specifies how deep the locking goes:
Bram Moolenaara187c432020-09-16 21:08:28 +02003151 0 Lock the variable {name} but not its
3152 value.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003153 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003154 cannot add or remove items, but can
3155 still change their values.
3156 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003157 the items. If an item is a |List| or
3158 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003159 items, but can still change the
3160 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003161 3 Like 2 but for the |List| /
3162 |Dictionary| in the |List| /
3163 |Dictionary|, one level deeper.
3164 The default [depth] is 2, thus when {name} is a |List|
3165 or |Dictionary| the values cannot be changed.
Bram Moolenaara187c432020-09-16 21:08:28 +02003166
3167 Example with [depth] 0: >
3168 let mylist = [1, 2, 3]
3169 lockvar 0 mylist
Bram Moolenaar6e649222021-10-04 21:32:54 +01003170 let mylist[0] = 77 " OK
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01003171 call add(mylist, 4) " OK
Bram Moolenaara187c432020-09-16 21:08:28 +02003172 let mylist = [7, 8, 9] " Error!
3173< *E743*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003174 For unlimited depth use [!] and omit [depth].
3175 However, there is a maximum depth of 100 to catch
3176 loops.
3177
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003178 Note that when two variables refer to the same |List|
3179 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003180 locked when used through the other variable.
3181 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003182 :let l = [0, 1, 2, 3]
3183 :let cl = l
3184 :lockvar l
3185 :let cl[1] = 99 " won't work!
3186< You may want to make a copy of a list to avoid this.
3187 See |deepcopy()|.
3188
Yegappan Lakshmanancd39b692023-10-02 12:50:45 -07003189 *E1391* *E1392*
3190 Locking and unlocking object and class variables is
3191 currently NOT supported.
3192
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003193
Bram Moolenaara2baa732022-02-04 16:09:54 +00003194:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo* *E1246*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00003195 Unlock the internal variable {name}. Does the
3196 opposite of |:lockvar|.
3197
Bram Moolenaard13166e2022-11-18 21:49:57 +00003198 If {name} does not exist:
3199 - In |Vim9| script an error is given.
3200 - In legacy script this is silently ignored.
3201
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02003202:if {expr1} *:if* *:end* *:endif* *:en* *E171* *E579* *E580*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003203:en[dif] Execute the commands until the next matching `:else`
3204 or `:endif` if {expr1} evaluates to non-zero.
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003205 Although the short forms work, it is recommended to
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003206 always use `:endif` to avoid confusion and to make
3207 auto-indenting work properly.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003208
3209 From Vim version 4.5 until 5.0, every Ex command in
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003210 between the `:if` and `:endif` is ignored. These two
Bram Moolenaar071d4272004-06-13 20:20:40 +00003211 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +01003212 backward compatible way. Nesting was allowed. Note
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003213 that any `:else` or `:elseif` was ignored, the `else`
Bram Moolenaar071d4272004-06-13 20:20:40 +00003214 part was not executed either.
3215
3216 You can use this to remain compatible with older
3217 versions: >
3218 :if version >= 500
3219 : version-5-specific-commands
3220 :endif
3221< The commands still need to be parsed to find the
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003222 `endif`. Sometimes an older Vim has a problem with a
3223 new command. For example, `:silent` is recognized as
3224 a `:substitute` command. In that case `:execute` can
Bram Moolenaar071d4272004-06-13 20:20:40 +00003225 avoid problems: >
3226 :if version >= 600
3227 : execute "silent 1,$delete"
3228 :endif
3229<
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003230 In |Vim9| script `:endif` cannot be shortened, to
3231 improve script readability.
3232 NOTE: The `:append` and `:insert` commands don't work
3233 properly in between `:if` and `:endif`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003234
3235 *:else* *:el* *E581* *E583*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003236:el[se] Execute the commands until the next matching `:else`
3237 or `:endif` if they previously were not being
Bram Moolenaar071d4272004-06-13 20:20:40 +00003238 executed.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003239 In |Vim9| script `:else` cannot be shortened, to
3240 improve script readability.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003241
3242 *:elseif* *:elsei* *E582* *E584*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003243:elsei[f] {expr1} Short for `:else` `:if`, with the addition that there
3244 is no extra `:endif`.
3245 In |Vim9| script `:elseif` cannot be shortened, to
3246 improve script readability.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003247
3248:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003249 *E170* *E585* *E588* *E733*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003250:endw[hile] Repeat the commands between `:while` and `:endwhile`,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003251 as long as {expr1} evaluates to non-zero.
3252 When an error is detected from a command inside the
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003253 loop, execution continues after the `endwhile`.
Bram Moolenaar12805862005-01-05 22:16:17 +00003254 Example: >
3255 :let lnum = 1
3256 :while lnum <= line("$")
3257 :call FixLine(lnum)
3258 :let lnum = lnum + 1
3259 :endwhile
3260<
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003261 In |Vim9| script `:while` and `:endwhile` cannot be
3262 shortened, to improve script readability.
3263 NOTE: The `:append` and `:insert` commands don't work
3264 properly inside a `:while` and `:for` loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003265
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003266:for {var} in {object} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +00003267:endfo[r] *:endfo* *:endfor*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003268 Repeat the commands between `:for` and `:endfor` for
Bram Moolenaar3f32a5f2022-05-12 20:34:15 +01003269 each item in {object}. {object} can be a |List|,
3270 a |Blob| or a |String|. *E1177*
Bram Moolenaar5da36052021-12-27 15:39:57 +00003271
3272 Variable {var} is set to the value of each item.
3273 In |Vim9| script the loop variable must not have been
3274 declared yet, unless when it is a
3275 global/window/tab/buffer variable.
3276
3277 When an error is detected for a command inside the
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003278 loop, execution continues after the `endfor`.
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003279 Changing {object} inside the loop affects what items
3280 are used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003281 :for item in copy(mylist)
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003282<
Bram Moolenaar5da36052021-12-27 15:39:57 +00003283 When {object} is a |List| and not making a copy, in
3284 legacy script Vim stores a reference to the next item
3285 in the |List| before executing the commands with the
3286 current item. Thus the current item can be removed
3287 without effect. Removing any later item means it will
3288 not be found. Thus the following example works (an
3289 inefficient way to make a |List| empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003290 for item in mylist
3291 call remove(mylist, 0)
3292 endfor
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003293< Note that reordering the |List| (e.g., with sort() or
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00003294 reverse()) may have unexpected effects.
Bram Moolenaar5da36052021-12-27 15:39:57 +00003295 In |Vim9| script the index is used. If an item before
3296 the current one is deleted the next item will be
3297 skipped.
Bram Moolenaar12805862005-01-05 22:16:17 +00003298
Bram Moolenaar5e66b422019-01-24 21:58:10 +01003299 When {object} is a |Blob|, Vim always makes a copy to
3300 iterate over. Unlike with |List|, modifying the
3301 |Blob| does not affect the iteration.
3302
Bram Moolenaar9b03d3e2022-08-30 20:26:34 +01003303 When {object} is a |String| each item is a string with
3304 one character, plus any combining characters.
3305
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003306 In |Vim9| script `:endfor` cannot be shortened, to
3307 improve script readability.
3308
Bram Moolenaar12805862005-01-05 22:16:17 +00003309:for [{var1}, {var2}, ...] in {listlist}
Bram Moolenaarf10911e2022-01-29 22:20:48 +00003310:endfo[r] *E1140*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003311 Like `:for` above, but each item in {listlist} must be
Bram Moolenaar12805862005-01-05 22:16:17 +00003312 a list, of which each item is assigned to {var1},
3313 {var2}, etc. Example: >
3314 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
3315 :echo getline(lnum)[col]
3316 :endfor
3317<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003318 *:continue* *:con* *E586*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003319:con[tinue] When used inside a `:while` or `:for` loop, jumps back
Bram Moolenaar12805862005-01-05 22:16:17 +00003320 to the start of the loop.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003321 If it is used after a `:try` inside the loop but
3322 before the matching `:finally` (if present), the
3323 commands following the `:finally` up to the matching
3324 `:endtry` are executed first. This process applies to
3325 all nested `:try`s inside the loop. The outermost
3326 `:endtry` then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003327
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003328 In |Vim9| script `:cont` is the shortest form, to
3329 improve script readability.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003330 *:break* *:brea* *E587*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003331:brea[k] When used inside a `:while` or `:for` loop, skips to
3332 the command after the matching `:endwhile` or
3333 `:endfor`.
3334 If it is used after a `:try` inside the loop but
3335 before the matching `:finally` (if present), the
3336 commands following the `:finally` up to the matching
3337 `:endtry` are executed first. This process applies to
3338 all nested `:try`s inside the loop. The outermost
3339 `:endtry` then jumps to the command after the loop.
3340
3341 In |Vim9| script `:break` cannot be shortened, to
3342 improve script readability.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003343
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003344:try *:try* *:endt* *:endtry*
3345 *E600* *E601* *E602* *E1032*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003346:endt[ry] Change the error handling for the commands between
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003347 `:try` and `:endtry` including everything being
3348 executed across `:source` commands, function calls,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003349 or autocommand invocations.
3350
3351 When an error or interrupt is detected and there is
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003352 a `:finally` command following, execution continues
3353 after the `:finally`. Otherwise, or when the
3354 `:endtry` is reached thereafter, the next
3355 (dynamically) surrounding `:try` is checked for
3356 a corresponding `:finally` etc. Then the script
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01003357 processing is terminated. Whether a function
3358 definition has an "abort" argument does not matter.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003359 Example: >
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01003360 try | call Unknown() | finally | echomsg "cleanup" | endtry
3361 echomsg "not reached"
Bram Moolenaar071d4272004-06-13 20:20:40 +00003362<
3363 Moreover, an error or interrupt (dynamically) inside
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003364 `:try` and `:endtry` is converted to an exception. It
3365 can be caught as if it were thrown by a `:throw`
3366 command (see `:catch`). In this case, the script
Bram Moolenaar071d4272004-06-13 20:20:40 +00003367 processing is not terminated.
3368
3369 The value "Vim:Interrupt" is used for an interrupt
3370 exception. An error in a Vim command is converted
3371 to a value of the form "Vim({command}):{errmsg}",
3372 other errors are converted to a value of the form
3373 "Vim:{errmsg}". {command} is the full command name,
3374 and {errmsg} is the message that is displayed if the
3375 error exception is not caught, always beginning with
3376 the error number.
3377 Examples: >
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01003378 try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
3379 try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
Bram Moolenaar071d4272004-06-13 20:20:40 +00003380<
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003381 In |Vim9| script `:endtry` cannot be shortened, to
3382 improve script readability.
3383
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003384 *:cat* *:catch*
3385 *E603* *E604* *E605* *E654* *E1033*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003386:cat[ch] /{pattern}/ The following commands until the next `:catch`,
3387 `:finally`, or `:endtry` that belongs to the same
3388 `:try` as the `:catch` are executed when an exception
Bram Moolenaar071d4272004-06-13 20:20:40 +00003389 matching {pattern} is being thrown and has not yet
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003390 been caught by a previous `:catch`. Otherwise, these
Bram Moolenaar071d4272004-06-13 20:20:40 +00003391 commands are skipped.
3392 When {pattern} is omitted all errors are caught.
3393 Examples: >
Bram Moolenaar647e24b2019-03-17 16:39:46 +01003394 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
3395 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
3396 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
3397 :catch /^Vim(write):/ " catch all errors in :write
3398 :catch /^Vim\%((\a\+)\)\=:E123:/ " catch error E123
3399 :catch /my-exception/ " catch user exception
3400 :catch /.*/ " catch everything
3401 :catch " same as /.*/
Bram Moolenaar071d4272004-06-13 20:20:40 +00003402<
3403 Another character can be used instead of / around the
3404 {pattern}, so long as it does not have a special
3405 meaning (e.g., '|' or '"') and doesn't occur inside
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003406 {pattern}. *E1067*
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02003407 Information about the exception is available in
3408 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003409 NOTE: It is not reliable to ":catch" the TEXT of
3410 an error message because it may vary in different
3411 locales.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003412 In |Vim9| script `:catch` cannot be shortened, to
3413 improve script readability.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003414
3415 *:fina* *:finally* *E606* *E607*
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003416:fina[lly] The following commands until the matching `:endtry`
Bram Moolenaar071d4272004-06-13 20:20:40 +00003417 are executed whenever the part between the matching
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003418 `:try` and the `:finally` is left: either by falling
3419 through to the `:finally` or by a `:continue`,
3420 `:break`, `:finish`, or `:return`, or by an error or
3421 interrupt or exception (see `:throw`).
3422
3423 In |Vim9| script `:finally` cannot be shortened, to
3424 improve script readability and avoid confusion with
3425 `:final`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003426
Bram Moolenaarf10911e2022-01-29 22:20:48 +00003427 *:th* *:throw* *E608* *E1129*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003428:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003429 If the ":throw" is used after a `:try` but before the
3430 first corresponding `:catch`, commands are skipped
3431 until the first `:catch` matching {expr1} is reached.
3432 If there is no such `:catch` or if the ":throw" is
3433 used after a `:catch` but before the `:finally`, the
3434 commands following the `:finally` (if present) up to
3435 the matching `:endtry` are executed. If the `:throw`
3436 is after the `:finally`, commands up to the `:endtry`
Bram Moolenaar071d4272004-06-13 20:20:40 +00003437 are skipped. At the ":endtry", this process applies
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003438 again for the next dynamically surrounding `:try`
Bram Moolenaar071d4272004-06-13 20:20:40 +00003439 (which may be found in a calling function or sourcing
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003440 script), until a matching `:catch` has been found.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003441 If the exception is not caught, the command processing
3442 is terminated.
3443 Example: >
3444 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +01003445< Note that "catch" may need to be on a separate line
3446 for when an error causes the parsing to skip the whole
3447 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003448
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003449 In |Vim9| script `:throw` cannot be shortened, to
3450 improve script readability.
3451
Bram Moolenaar071d4272004-06-13 20:20:40 +00003452 *:ec* *:echo*
3453:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
3454 first {expr1} starts on a new line.
3455 Also see |:comment|.
3456 Use "\n" to start a new line. Use "\r" to move the
3457 cursor to the first column.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003458 Uses the highlighting set by the `:echohl` command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003459 Cannot be followed by a comment.
3460 Example: >
3461 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003462< *:echo-redraw*
3463 A later redraw may make the message disappear again.
3464 And since Vim mostly postpones redrawing until it's
3465 finished with a sequence of commands this happens
3466 quite often. To avoid that a command from before the
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003467 `:echo` causes a redraw afterwards (redraws are often
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003468 postponed until you type something), force a redraw
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003469 with the `:redraw` command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003470 :new | redraw | echo "there is a new window"
3471<
3472 *:echon*
3473:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
3474 |:comment|.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003475 Uses the highlighting set by the `:echohl` command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003476 Cannot be followed by a comment.
3477 Example: >
3478 :echon "the value of 'shell' is " &shell
3479<
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003480 Note the difference between using `:echo`, which is a
3481 Vim command, and `:!echo`, which is an external shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00003482 command: >
3483 :!echo % --> filename
3484< The arguments of ":!" are expanded, see |:_%|. >
3485 :!echo "%" --> filename or "filename"
3486< Like the previous example. Whether you see the double
3487 quotes or not depends on your 'shell'. >
3488 :echo % --> nothing
3489< The '%' is an illegal character in an expression. >
3490 :echo "%" --> %
3491< This just echoes the '%' character. >
3492 :echo expand("%") --> filename
3493< This calls the expand() function to expand the '%'.
3494
3495 *:echoh* *:echohl*
3496:echoh[l] {name} Use the highlight group {name} for the following
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003497 `:echo`, `:echon` and `:echomsg` commands. Also used
3498 for the `input()` prompt. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003499 :echohl WarningMsg | echo "Don't panic!" | echohl None
3500< Don't forget to set the group back to "None",
3501 otherwise all following echo's will be highlighted.
3502
3503 *:echom* *:echomsg*
3504:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
3505 message in the |message-history|.
3506 Spaces are placed between the arguments as with the
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003507 `:echo` command. But unprintable characters are
Bram Moolenaar071d4272004-06-13 20:20:40 +00003508 displayed, not interpreted.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003509 The parsing works slightly different from `:echo`,
3510 more like `:execute`. All the expressions are first
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003511 evaluated and concatenated before echoing anything.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +01003512 If expressions does not evaluate to a Number or
3513 String, string() is used to turn it into a string.
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003514 Uses the highlighting set by the `:echohl` command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003515 Example: >
3516 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003517< See |:echo-redraw| to avoid the message disappearing
3518 when the screen is redrawn.
Bram Moolenaar37fef162022-08-29 18:16:32 +01003519
3520 *:echow* *:echowin* *:echowindow*
Bram Moolenaarbdc09a12022-10-07 14:31:45 +01003521:[N]echow[indow] {expr1} ..
Bram Moolenaar37fef162022-08-29 18:16:32 +01003522 Like |:echomsg| but when the messages popup window is
3523 available the message is displayed there. This means
3524 it will show for three seconds and avoid a
Bram Moolenaar9b03d3e2022-08-30 20:26:34 +01003525 |hit-enter| prompt. If you want to hide it before
3526 that, press Esc in Normal mode (when it would
Bram Moolenaar71b6d332022-09-10 13:13:14 +01003527 otherwise beep). If it disappears too soon you can
3528 use `:messages` to see the text.
Bram Moolenaarbdc09a12022-10-07 14:31:45 +01003529 When [N] is given then the window will show up for
3530 this number of seconds. The last `:echowindow` with a
3531 count matters, it is used once only.
Bram Moolenaar37fef162022-08-29 18:16:32 +01003532 The message window is available when Vim was compiled
3533 with the +timer and the +popupwin features.
3534
Bram Moolenaar071d4272004-06-13 20:20:40 +00003535 *:echoe* *:echoerr*
3536:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
3537 message in the |message-history|. When used in a
3538 script or function the line number will be added.
3539 Spaces are placed between the arguments as with the
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003540 `:echomsg` command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003541 the message is raised as an error exception instead
3542 (see |try-echoerr|).
3543 Example: >
3544 :echoerr "This script just failed!"
Bram Moolenaar1588bc82022-03-08 21:35:07 +00003545< If you just want a highlighted message use `:echohl`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003546 And to get a beep: >
3547 :exe "normal \<Esc>"
Bram Moolenaar4c868302021-03-22 16:19:45 +01003548
3549:echoc[onsole] {expr1} .. *:echoc* *:echoconsole*
3550 Intended for testing: works like `:echomsg` but when
3551 running in the GUI and started from a terminal write
3552 the text to stdout.
3553
Bram Moolenaar09c6f262019-11-17 15:55:14 +01003554 *:eval*
3555:eval {expr} Evaluate {expr} and discard the result. Example: >
3556 :eval Getlist()->Filter()->append('$')
3557
3558< The expression is supposed to have a side effect,
3559 since the resulting value is not used. In the example
3560 the `append()` call appends the List with text to the
3561 buffer. This is similar to `:call` but works with any
3562 expression.
Bram Moolenaara2baa732022-02-04 16:09:54 +00003563 In |Vim9| script an expression without an effect will
3564 result in error *E1207* . This should help noticing
3565 mistakes.
Bram Moolenaar09c6f262019-11-17 15:55:14 +01003566
3567 The command can be shortened to `:ev` or `:eva`, but
3568 these are hard to recognize and therefore not to be
3569 used.
3570
Bram Moolenaarbc93ceb2020-02-26 13:36:21 +01003571 The command cannot be followed by "|" and another
3572 command, since "|" is seen as part of the expression.
3573
Bram Moolenaar09c6f262019-11-17 15:55:14 +01003574
Bram Moolenaar071d4272004-06-13 20:20:40 +00003575 *:exe* *:execute*
3576:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +02003577 of {expr1} as an Ex command.
3578 Multiple arguments are concatenated, with a space in
Bram Moolenaar7e6a5152021-01-02 16:39:53 +01003579 between. To avoid the extra space use the ".."
Bram Moolenaar00a927d2010-05-14 23:24:24 +02003580 operator to concatenate strings into one argument.
3581 {expr1} is used as the processed command, command line
3582 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003583 Cannot be followed by a comment.
3584 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +02003585 :execute "buffer" nextbuf
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01003586 :execute "normal" count .. "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +00003587<
3588 ":execute" can be used to append a command to commands
3589 that don't accept a '|'. Example: >
3590 :execute '!ls' | echo "theend"
3591
3592< ":execute" is also a nice way to avoid having to type
3593 control characters in a Vim script for a ":normal"
3594 command: >
3595 :execute "normal ixxx\<Esc>"
3596< This has an <Esc> character, see |expr-string|.
3597
Bram Moolenaar446cb832008-06-24 21:56:24 +00003598 Be careful to correctly escape special characters in
3599 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +00003600 for Vim commands, |shellescape()| for |:!| commands.
3601 Examples: >
Bram Moolenaarc8cdf0f2021-03-13 13:28:13 +01003602 :execute "e " .. fnameescape(filename)
3603 :execute "!ls " .. shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +00003604<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003605 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01003606 starting or ending "if", "while" and "for" does not
3607 always work, because when commands are skipped the
3608 ":execute" is not evaluated and Vim loses track of
3609 where blocks start and end. Also "break" and
3610 "continue" should not be inside ":execute".
3611 This example does not work, because the ":execute" is
3612 not evaluated and Vim does not see the "while", and
3613 gives an error for finding an ":endwhile": >
3614 :if 0
3615 : execute 'while i > 5'
3616 : echo "test"
3617 : endwhile
3618 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00003619<
3620 It is allowed to have a "while" or "if" command
3621 completely in the executed string: >
3622 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
3623<
3624
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003625 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003626 ":execute", ":echo" and ":echon" cannot be followed by
3627 a comment directly, because they see the '"' as the
3628 start of a string. But, you can use '|' followed by a
3629 comment. Example: >
3630 :echo "foo" | "this is a comment
3631
3632==============================================================================
36338. Exception handling *exception-handling*
3634
3635The Vim script language comprises an exception handling feature. This section
3636explains how it can be used in a Vim script.
3637
3638Exceptions may be raised by Vim on an error or on interrupt, see
3639|catch-errors| and |catch-interrupt|. You can also explicitly throw an
3640exception by using the ":throw" command, see |throw-catch|.
3641
3642
3643TRY CONDITIONALS *try-conditionals*
3644
3645Exceptions can be caught or can cause cleanup code to be executed. You can
3646use a try conditional to specify catch clauses (that catch exceptions) and/or
3647a finally clause (to be executed for cleanup).
3648 A try conditional begins with a |:try| command and ends at the matching
3649|:endtry| command. In between, you can use a |:catch| command to start
3650a catch clause, or a |:finally| command to start a finally clause. There may
3651be none or multiple catch clauses, but there is at most one finally clause,
3652which must not be followed by any catch clauses. The lines before the catch
3653clauses and the finally clause is called a try block. >
3654
3655 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +00003656 : ...
3657 : ... TRY BLOCK
3658 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00003659 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00003660 : ...
3661 : ... CATCH CLAUSE
3662 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00003663 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +00003664 : ...
3665 : ... CATCH CLAUSE
3666 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00003667 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +00003668 : ...
3669 : ... FINALLY CLAUSE
3670 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +00003671 :endtry
3672
3673The try conditional allows to watch code for exceptions and to take the
3674appropriate actions. Exceptions from the try block may be caught. Exceptions
3675from the try block and also the catch clauses may cause cleanup actions.
3676 When no exception is thrown during execution of the try block, the control
3677is transferred to the finally clause, if present. After its execution, the
3678script continues with the line following the ":endtry".
3679 When an exception occurs during execution of the try block, the remaining
3680lines in the try block are skipped. The exception is matched against the
3681patterns specified as arguments to the ":catch" commands. The catch clause
3682after the first matching ":catch" is taken, other catch clauses are not
3683executed. The catch clause ends when the next ":catch", ":finally", or
3684":endtry" command is reached - whatever is first. Then, the finally clause
3685(if present) is executed. When the ":endtry" is reached, the script execution
3686continues in the following line as usual.
3687 When an exception that does not match any of the patterns specified by the
3688":catch" commands is thrown in the try block, the exception is not caught by
3689that try conditional and none of the catch clauses is executed. Only the
3690finally clause, if present, is taken. The exception pends during execution of
3691the finally clause. It is resumed at the ":endtry", so that commands after
3692the ":endtry" are not executed and the exception might be caught elsewhere,
3693see |try-nesting|.
3694 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar58b85342016-08-14 19:54:54 +02003695remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003696not matched against the patterns in any of the ":catch" commands of the same
3697try conditional and none of its catch clauses is taken. If there is, however,
3698a finally clause, it is executed, and the exception pends during its
3699execution. The commands following the ":endtry" are not executed. The new
3700exception might, however, be caught elsewhere, see |try-nesting|.
3701 When during execution of the finally clause (if present) an exception is
Bram Moolenaar58b85342016-08-14 19:54:54 +02003702thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00003703clause has been taken because of an exception from the try block or one of the
3704catch clauses, the original (pending) exception is discarded. The commands
3705following the ":endtry" are not executed, and the exception from the finally
3706clause is propagated and can be caught elsewhere, see |try-nesting|.
3707
3708The finally clause is also executed, when a ":break" or ":continue" for
3709a ":while" loop enclosing the complete try conditional is executed from the
3710try block or a catch clause. Or when a ":return" or ":finish" is executed
3711from the try block or a catch clause of a try conditional in a function or
3712sourced script, respectively. The ":break", ":continue", ":return", or
3713":finish" pends during execution of the finally clause and is resumed when the
3714":endtry" is reached. It is, however, discarded when an exception is thrown
3715from the finally clause.
3716 When a ":break" or ":continue" for a ":while" loop enclosing the complete
3717try conditional or when a ":return" or ":finish" is encountered in the finally
3718clause, the rest of the finally clause is skipped, and the ":break",
3719":continue", ":return" or ":finish" is executed as usual. If the finally
3720clause has been taken because of an exception or an earlier ":break",
3721":continue", ":return", or ":finish" from the try block or a catch clause,
3722this pending exception or command is discarded.
3723
3724For examples see |throw-catch| and |try-finally|.
3725
3726
Bram Moolenaar76db9e02022-11-09 21:21:04 +00003727NESTING OF TRY CONDITIONALS *try-nesting*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003728
3729Try conditionals can be nested arbitrarily. That is, a complete try
3730conditional can be put into the try block, a catch clause, or the finally
3731clause of another try conditional. If the inner try conditional does not
3732catch an exception thrown in its try block or throws a new exception from one
3733of its catch clauses or its finally clause, the outer try conditional is
3734checked according to the rules above. If the inner try conditional is in the
3735try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar58b85342016-08-14 19:54:54 +02003736otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +00003737nesting, whether the inner try conditional is directly contained in the outer
3738one, or whether the outer one sources a script or calls a function containing
3739the inner try conditional.
3740
3741When none of the active try conditionals catches an exception, just their
3742finally clauses are executed. Thereafter, the script processing terminates.
3743An error message is displayed in case of an uncaught exception explicitly
3744thrown by a ":throw" command. For uncaught error and interrupt exceptions
3745implicitly raised by Vim, the error message(s) or interrupt message are shown
3746as usual.
3747
3748For examples see |throw-catch|.
3749
3750
3751EXAMINING EXCEPTION HANDLING CODE *except-examine*
3752
3753Exception handling code can get tricky. If you are in doubt what happens, set
3754'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
3755script file. Then you see when an exception is thrown, discarded, caught, or
3756finished. When using a verbosity level of at least 14, things pending in
3757a finally clause are also shown. This information is also given in debug mode
3758(see |debug-scripts|).
3759
3760
3761THROWING AND CATCHING EXCEPTIONS *throw-catch*
3762
3763You can throw any number or string as an exception. Use the |:throw| command
3764and pass the value to be thrown as argument: >
3765 :throw 4711
3766 :throw "string"
3767< *throw-expression*
3768You can also specify an expression argument. The expression is then evaluated
3769first, and the result is thrown: >
3770 :throw 4705 + strlen("string")
3771 :throw strpart("strings", 0, 6)
3772
3773An exception might be thrown during evaluation of the argument of the ":throw"
3774command. Unless it is caught there, the expression evaluation is abandoned.
3775The ":throw" command then does not throw a new exception.
3776 Example: >
3777
3778 :function! Foo(arg)
3779 : try
3780 : throw a:arg
3781 : catch /foo/
3782 : endtry
3783 : return 1
3784 :endfunction
3785 :
3786 :function! Bar()
3787 : echo "in Bar"
3788 : return 4710
3789 :endfunction
3790 :
3791 :throw Foo("arrgh") + Bar()
3792
3793This throws "arrgh", and "in Bar" is not displayed since Bar() is not
3794executed. >
3795 :throw Foo("foo") + Bar()
3796however displays "in Bar" and throws 4711.
3797
3798Any other command that takes an expression as argument might also be
Bram Moolenaar58b85342016-08-14 19:54:54 +02003799abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00003800exception is then propagated to the caller of the command.
3801 Example: >
3802
3803 :if Foo("arrgh")
3804 : echo "then"
3805 :else
3806 : echo "else"
3807 :endif
3808
3809Here neither of "then" or "else" is displayed.
3810
3811 *catch-order*
3812Exceptions can be caught by a try conditional with one or more |:catch|
3813commands, see |try-conditionals|. The values to be caught by each ":catch"
3814command can be specified as a pattern argument. The subsequent catch clause
3815gets executed when a matching exception is caught.
3816 Example: >
3817
3818 :function! Foo(value)
3819 : try
3820 : throw a:value
3821 : catch /^\d\+$/
3822 : echo "Number thrown"
3823 : catch /.*/
3824 : echo "String thrown"
3825 : endtry
3826 :endfunction
3827 :
3828 :call Foo(0x1267)
3829 :call Foo('string')
3830
3831The first call to Foo() displays "Number thrown", the second "String thrown".
3832An exception is matched against the ":catch" commands in the order they are
3833specified. Only the first match counts. So you should place the more
3834specific ":catch" first. The following order does not make sense: >
3835
3836 : catch /.*/
3837 : echo "String thrown"
3838 : catch /^\d\+$/
3839 : echo "Number thrown"
3840
3841The first ":catch" here matches always, so that the second catch clause is
3842never taken.
3843
3844 *throw-variables*
3845If you catch an exception by a general pattern, you may access the exact value
3846in the variable |v:exception|: >
3847
3848 : catch /^\d\+$/
3849 : echo "Number thrown. Value is" v:exception
3850
3851You may also be interested where an exception was thrown. This is stored in
3852|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
3853exception most recently caught as long it is not finished.
3854 Example: >
3855
3856 :function! Caught()
3857 : if v:exception != ""
Bram Moolenaarc51cf032022-02-26 12:25:45 +00003858 : echo 'Caught "' . v:exception .. '" in ' .. v:throwpoint
Bram Moolenaar071d4272004-06-13 20:20:40 +00003859 : else
3860 : echo 'Nothing caught'
3861 : endif
3862 :endfunction
3863 :
3864 :function! Foo()
3865 : try
3866 : try
3867 : try
3868 : throw 4711
3869 : finally
3870 : call Caught()
3871 : endtry
3872 : catch /.*/
3873 : call Caught()
3874 : throw "oops"
3875 : endtry
3876 : catch /.*/
3877 : call Caught()
3878 : finally
3879 : call Caught()
3880 : endtry
3881 :endfunction
3882 :
3883 :call Foo()
3884
3885This displays >
3886
3887 Nothing caught
3888 Caught "4711" in function Foo, line 4
3889 Caught "oops" in function Foo, line 10
3890 Nothing caught
3891
3892A practical example: The following command ":LineNumber" displays the line
3893number in the script or function where it has been used: >
3894
3895 :function! LineNumber()
3896 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
3897 :endfunction
3898 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
3899<
3900 *try-nested*
3901An exception that is not caught by a try conditional can be caught by
3902a surrounding try conditional: >
3903
3904 :try
3905 : try
3906 : throw "foo"
3907 : catch /foobar/
3908 : echo "foobar"
3909 : finally
3910 : echo "inner finally"
3911 : endtry
3912 :catch /foo/
3913 : echo "foo"
3914 :endtry
3915
3916The inner try conditional does not catch the exception, just its finally
3917clause is executed. The exception is then caught by the outer try
3918conditional. The example displays "inner finally" and then "foo".
3919
3920 *throw-from-catch*
3921You can catch an exception and throw a new one to be caught elsewhere from the
3922catch clause: >
3923
3924 :function! Foo()
3925 : throw "foo"
3926 :endfunction
3927 :
3928 :function! Bar()
3929 : try
3930 : call Foo()
3931 : catch /foo/
3932 : echo "Caught foo, throw bar"
3933 : throw "bar"
3934 : endtry
3935 :endfunction
3936 :
3937 :try
3938 : call Bar()
3939 :catch /.*/
3940 : echo "Caught" v:exception
3941 :endtry
3942
3943This displays "Caught foo, throw bar" and then "Caught bar".
3944
3945 *rethrow*
3946There is no real rethrow in the Vim script language, but you may throw
3947"v:exception" instead: >
3948
3949 :function! Bar()
3950 : try
3951 : call Foo()
3952 : catch /.*/
3953 : echo "Rethrow" v:exception
3954 : throw v:exception
3955 : endtry
3956 :endfunction
3957< *try-echoerr*
3958Note that this method cannot be used to "rethrow" Vim error or interrupt
3959exceptions, because it is not possible to fake Vim internal exceptions.
3960Trying so causes an error exception. You should throw your own exception
3961denoting the situation. If you want to cause a Vim error exception containing
3962the original error exception value, you can use the |:echoerr| command: >
3963
3964 :try
3965 : try
3966 : asdf
3967 : catch /.*/
3968 : echoerr v:exception
3969 : endtry
3970 :catch /.*/
3971 : echo v:exception
3972 :endtry
3973
3974This code displays
3975
Bram Moolenaar446cb832008-06-24 21:56:24 +00003976 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00003977
3978
3979CLEANUP CODE *try-finally*
3980
3981Scripts often change global settings and restore them at their end. If the
3982user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar58b85342016-08-14 19:54:54 +02003983an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +00003984a script when an error occurs or you explicitly throw an exception without
3985catching it. You can solve these problems by using a try conditional with
3986a finally clause for restoring the settings. Its execution is guaranteed on
3987normal control flow, on error, on an explicit ":throw", and on interrupt.
3988(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar58b85342016-08-14 19:54:54 +02003989to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +00003990clause has been executed.)
3991Example: >
3992
3993 :try
3994 : let s:saved_ts = &ts
3995 : set ts=17
3996 :
3997 : " Do the hard work here.
3998 :
3999 :finally
4000 : let &ts = s:saved_ts
4001 : unlet s:saved_ts
4002 :endtry
4003
4004This method should be used locally whenever a function or part of a script
4005changes global settings which need to be restored on failure or normal exit of
4006that function or script part.
4007
4008 *break-finally*
4009Cleanup code works also when the try block or a catch clause is left by
4010a ":continue", ":break", ":return", or ":finish".
4011 Example: >
4012
4013 :let first = 1
4014 :while 1
4015 : try
4016 : if first
4017 : echo "first"
4018 : let first = 0
4019 : continue
4020 : else
4021 : throw "second"
4022 : endif
4023 : catch /.*/
4024 : echo v:exception
4025 : break
4026 : finally
4027 : echo "cleanup"
4028 : endtry
4029 : echo "still in while"
4030 :endwhile
4031 :echo "end"
4032
4033This displays "first", "cleanup", "second", "cleanup", and "end". >
4034
4035 :function! Foo()
4036 : try
4037 : return 4711
4038 : finally
4039 : echo "cleanup\n"
4040 : endtry
4041 : echo "Foo still active"
4042 :endfunction
4043 :
4044 :echo Foo() "returned by Foo"
4045
4046This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar58b85342016-08-14 19:54:54 +02004047extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004048return value.)
4049
4050 *except-from-finally*
4051Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
4052a finally clause is possible, but not recommended since it abandons the
4053cleanup actions for the try conditional. But, of course, interrupt and error
4054exceptions might get raised from a finally clause.
4055 Example where an error in the finally clause stops an interrupt from
4056working correctly: >
4057
4058 :try
4059 : try
4060 : echo "Press CTRL-C for interrupt"
4061 : while 1
4062 : endwhile
4063 : finally
4064 : unlet novar
4065 : endtry
4066 :catch /novar/
4067 :endtry
4068 :echo "Script still running"
4069 :sleep 1
4070
4071If you need to put commands that could fail into a finally clause, you should
4072think about catching or ignoring the errors in these commands, see
4073|catch-errors| and |ignore-errors|.
4074
4075
4076CATCHING ERRORS *catch-errors*
4077
4078If you want to catch specific errors, you just have to put the code to be
4079watched in a try block and add a catch clause for the error message. The
4080presence of the try conditional causes all errors to be converted to an
4081exception. No message is displayed and |v:errmsg| is not set then. To find
4082the right pattern for the ":catch" command, you have to know how the format of
4083the error exception is.
4084 Error exceptions have the following format: >
4085
4086 Vim({cmdname}):{errmsg}
4087or >
4088 Vim:{errmsg}
4089
4090{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar58b85342016-08-14 19:54:54 +02004091the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +00004092when the error occurs outside try conditionals. It always begins with
4093a capital "E", followed by a two or three-digit error number, a colon, and
4094a space.
4095
4096Examples:
4097
4098The command >
4099 :unlet novar
4100normally produces the error message >
4101 E108: No such variable: "novar"
4102which is converted inside try conditionals to an exception >
4103 Vim(unlet):E108: No such variable: "novar"
4104
4105The command >
4106 :dwim
4107normally produces the error message >
4108 E492: Not an editor command: dwim
4109which is converted inside try conditionals to an exception >
4110 Vim:E492: Not an editor command: dwim
4111
4112You can catch all ":unlet" errors by a >
4113 :catch /^Vim(unlet):/
4114or all errors for misspelled command names by a >
4115 :catch /^Vim:E492:/
4116
4117Some error messages may be produced by different commands: >
4118 :function nofunc
4119and >
4120 :delfunction nofunc
4121both produce the error message >
4122 E128: Function name must start with a capital: nofunc
4123which is converted inside try conditionals to an exception >
4124 Vim(function):E128: Function name must start with a capital: nofunc
4125or >
4126 Vim(delfunction):E128: Function name must start with a capital: nofunc
4127respectively. You can catch the error by its number independently on the
4128command that caused it if you use the following pattern: >
4129 :catch /^Vim(\a\+):E128:/
4130
4131Some commands like >
4132 :let x = novar
4133produce multiple error messages, here: >
4134 E121: Undefined variable: novar
4135 E15: Invalid expression: novar
4136Only the first is used for the exception value, since it is the most specific
4137one (see |except-several-errors|). So you can catch it by >
4138 :catch /^Vim(\a\+):E121:/
4139
4140You can catch all errors related to the name "nofunc" by >
4141 :catch /\<nofunc\>/
4142
4143You can catch all Vim errors in the ":write" and ":read" commands by >
4144 :catch /^Vim(\(write\|read\)):E\d\+:/
4145
4146You can catch all Vim errors by the pattern >
4147 :catch /^Vim\((\a\+)\)\=:E\d\+:/
4148<
4149 *catch-text*
4150NOTE: You should never catch the error message text itself: >
4151 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01004152only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +00004153a different language by the |:language| command. It is however helpful to
4154cite the message text in a comment: >
4155 :catch /^Vim(\a\+):E108:/ " No such variable
4156
4157
4158IGNORING ERRORS *ignore-errors*
4159
4160You can ignore errors in a specific Vim command by catching them locally: >
4161
4162 :try
4163 : write
4164 :catch
4165 :endtry
4166
4167But you are strongly recommended NOT to use this simple form, since it could
4168catch more than you want. With the ":write" command, some autocommands could
4169be executed and cause errors not related to writing, for instance: >
4170
4171 :au BufWritePre * unlet novar
4172
4173There could even be such errors you are not responsible for as a script
4174writer: a user of your script might have defined such autocommands. You would
4175then hide the error from the user.
4176 It is much better to use >
4177
4178 :try
4179 : write
4180 :catch /^Vim(write):/
4181 :endtry
4182
4183which only catches real write errors. So catch only what you'd like to ignore
4184intentionally.
4185
4186For a single command that does not cause execution of autocommands, you could
4187even suppress the conversion of errors to exceptions by the ":silent!"
4188command: >
4189 :silent! nunmap k
4190This works also when a try conditional is active.
4191
4192
4193CATCHING INTERRUPTS *catch-interrupt*
4194
4195When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar58b85342016-08-14 19:54:54 +02004196the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00004197script is not terminated, then.
4198 Example: >
4199
4200 :function! TASK1()
4201 : sleep 10
4202 :endfunction
4203
4204 :function! TASK2()
4205 : sleep 20
4206 :endfunction
4207
4208 :while 1
4209 : let command = input("Type a command: ")
4210 : try
4211 : if command == ""
4212 : continue
4213 : elseif command == "END"
4214 : break
4215 : elseif command == "TASK1"
4216 : call TASK1()
4217 : elseif command == "TASK2"
4218 : call TASK2()
4219 : else
4220 : echo "\nIllegal command:" command
4221 : continue
4222 : endif
4223 : catch /^Vim:Interrupt$/
4224 : echo "\nCommand interrupted"
4225 : " Caught the interrupt. Continue with next prompt.
4226 : endtry
4227 :endwhile
4228
4229You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar58b85342016-08-14 19:54:54 +02004230a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004231
4232For testing what happens when CTRL-C would be pressed on a specific line in
4233your script, use the debug mode and execute the |>quit| or |>interrupt|
4234command on that line. See |debug-scripts|.
4235
4236
4237CATCHING ALL *catch-all*
4238
4239The commands >
4240
4241 :catch /.*/
4242 :catch //
4243 :catch
4244
4245catch everything, error exceptions, interrupt exceptions and exceptions
4246explicitly thrown by the |:throw| command. This is useful at the top level of
4247a script in order to catch unexpected things.
4248 Example: >
4249
4250 :try
4251 :
4252 : " do the hard work here
4253 :
4254 :catch /MyException/
4255 :
4256 : " handle known problem
4257 :
4258 :catch /^Vim:Interrupt$/
4259 : echo "Script interrupted"
4260 :catch /.*/
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004261 : echo "Internal error (" .. v:exception .. ")"
4262 : echo " - occurred at " .. v:throwpoint
Bram Moolenaar071d4272004-06-13 20:20:40 +00004263 :endtry
4264 :" end of script
4265
4266Note: Catching all might catch more things than you want. Thus, you are
4267strongly encouraged to catch only for problems that you can really handle by
4268specifying a pattern argument to the ":catch".
4269 Example: Catching all could make it nearly impossible to interrupt a script
4270by pressing CTRL-C: >
4271
4272 :while 1
4273 : try
4274 : sleep 1
4275 : catch
4276 : endtry
4277 :endwhile
4278
4279
4280EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
4281
4282Exceptions may be used during execution of autocommands. Example: >
4283
4284 :autocmd User x try
4285 :autocmd User x throw "Oops!"
4286 :autocmd User x catch
4287 :autocmd User x echo v:exception
4288 :autocmd User x endtry
4289 :autocmd User x throw "Arrgh!"
4290 :autocmd User x echo "Should not be displayed"
4291 :
4292 :try
4293 : doautocmd User x
4294 :catch
4295 : echo v:exception
4296 :endtry
4297
4298This displays "Oops!" and "Arrgh!".
4299
4300 *except-autocmd-Pre*
4301For some commands, autocommands get executed before the main action of the
4302command takes place. If an exception is thrown and not caught in the sequence
4303of autocommands, the sequence and the command that caused its execution are
4304abandoned and the exception is propagated to the caller of the command.
4305 Example: >
4306
4307 :autocmd BufWritePre * throw "FAIL"
4308 :autocmd BufWritePre * echo "Should not be displayed"
4309 :
4310 :try
4311 : write
4312 :catch
4313 : echo "Caught:" v:exception "from" v:throwpoint
4314 :endtry
4315
4316Here, the ":write" command does not write the file currently being edited (as
4317you can see by checking 'modified'), since the exception from the BufWritePre
4318autocommand abandons the ":write". The exception is then caught and the
4319script displays: >
4320
4321 Caught: FAIL from BufWrite Auto commands for "*"
4322<
4323 *except-autocmd-Post*
4324For some commands, autocommands get executed after the main action of the
4325command has taken place. If this main action fails and the command is inside
4326an active try conditional, the autocommands are skipped and an error exception
4327is thrown that can be caught by the caller of the command.
4328 Example: >
4329
4330 :autocmd BufWritePost * echo "File successfully written!"
4331 :
4332 :try
4333 : write /i/m/p/o/s/s/i/b/l/e
4334 :catch
4335 : echo v:exception
4336 :endtry
4337
4338This just displays: >
4339
4340 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
4341
4342If you really need to execute the autocommands even when the main action
4343fails, trigger the event from the catch clause.
4344 Example: >
4345
4346 :autocmd BufWritePre * set noreadonly
4347 :autocmd BufWritePost * set readonly
4348 :
4349 :try
4350 : write /i/m/p/o/s/s/i/b/l/e
4351 :catch
4352 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
4353 :endtry
4354<
4355You can also use ":silent!": >
4356
4357 :let x = "ok"
4358 :let v:errmsg = ""
4359 :autocmd BufWritePost * if v:errmsg != ""
4360 :autocmd BufWritePost * let x = "after fail"
4361 :autocmd BufWritePost * endif
4362 :try
4363 : silent! write /i/m/p/o/s/s/i/b/l/e
4364 :catch
4365 :endtry
4366 :echo x
4367
4368This displays "after fail".
4369
4370If the main action of the command does not fail, exceptions from the
4371autocommands will be catchable by the caller of the command: >
4372
4373 :autocmd BufWritePost * throw ":-("
4374 :autocmd BufWritePost * echo "Should not be displayed"
4375 :
4376 :try
4377 : write
4378 :catch
4379 : echo v:exception
4380 :endtry
4381<
4382 *except-autocmd-Cmd*
4383For some commands, the normal action can be replaced by a sequence of
4384autocommands. Exceptions from that sequence will be catchable by the caller
4385of the command.
4386 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar58b85342016-08-14 19:54:54 +02004387had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +00004388some way. >
4389
4390 :if !exists("cnt")
4391 : let cnt = 0
4392 :
4393 : autocmd BufWriteCmd * if &modified
4394 : autocmd BufWriteCmd * let cnt = cnt + 1
4395 : autocmd BufWriteCmd * if cnt % 3 == 2
4396 : autocmd BufWriteCmd * throw "BufWriteCmdError"
4397 : autocmd BufWriteCmd * endif
4398 : autocmd BufWriteCmd * write | set nomodified
4399 : autocmd BufWriteCmd * if cnt % 3 == 0
4400 : autocmd BufWriteCmd * throw "BufWriteCmdError"
4401 : autocmd BufWriteCmd * endif
4402 : autocmd BufWriteCmd * echo "File successfully written!"
4403 : autocmd BufWriteCmd * endif
4404 :endif
4405 :
4406 :try
4407 : write
4408 :catch /^BufWriteCmdError$/
4409 : if &modified
4410 : echo "Error on writing (file contents not changed)"
4411 : else
4412 : echo "Error after writing"
4413 : endif
4414 :catch /^Vim(write):/
4415 : echo "Error on writing"
4416 :endtry
4417
4418When this script is sourced several times after making changes, it displays
4419first >
4420 File successfully written!
4421then >
4422 Error on writing (file contents not changed)
4423then >
4424 Error after writing
4425etc.
4426
4427 *except-autocmd-ill*
4428You cannot spread a try conditional over autocommands for different events.
4429The following code is ill-formed: >
4430
4431 :autocmd BufWritePre * try
4432 :
4433 :autocmd BufWritePost * catch
4434 :autocmd BufWritePost * echo v:exception
4435 :autocmd BufWritePost * endtry
4436 :
4437 :write
4438
4439
4440EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
4441
4442Some programming languages allow to use hierarchies of exception classes or to
4443pass additional information with the object of an exception class. You can do
4444similar things in Vim.
4445 In order to throw an exception from a hierarchy, just throw the complete
4446class name with the components separated by a colon, for instance throw the
4447string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
4448 When you want to pass additional information with your exception class, add
4449it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
4450for an error when writing "myfile".
4451 With the appropriate patterns in the ":catch" command, you can catch for
4452base classes or derived classes of your hierarchy. Additional information in
4453parentheses can be cut out from |v:exception| with the ":substitute" command.
4454 Example: >
4455
4456 :function! CheckRange(a, func)
4457 : if a:a < 0
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004458 : throw "EXCEPT:MATHERR:RANGE(" .. a:func .. ")"
Bram Moolenaar071d4272004-06-13 20:20:40 +00004459 : endif
4460 :endfunction
4461 :
4462 :function! Add(a, b)
4463 : call CheckRange(a:a, "Add")
4464 : call CheckRange(a:b, "Add")
4465 : let c = a:a + a:b
4466 : if c < 0
4467 : throw "EXCEPT:MATHERR:OVERFLOW"
4468 : endif
4469 : return c
4470 :endfunction
4471 :
4472 :function! Div(a, b)
4473 : call CheckRange(a:a, "Div")
4474 : call CheckRange(a:b, "Div")
4475 : if (a:b == 0)
4476 : throw "EXCEPT:MATHERR:ZERODIV"
4477 : endif
4478 : return a:a / a:b
4479 :endfunction
4480 :
4481 :function! Write(file)
4482 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +00004483 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004484 : catch /^Vim(write):/
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004485 : throw "EXCEPT:IO(" .. getcwd() .. ", " .. a:file .. "):WRITEERR"
Bram Moolenaar071d4272004-06-13 20:20:40 +00004486 : endtry
4487 :endfunction
4488 :
4489 :try
4490 :
Bram Moolenaar75ab5902022-04-18 15:36:40 +01004491 : " something with arithmetic and I/O
Bram Moolenaar071d4272004-06-13 20:20:40 +00004492 :
4493 :catch /^EXCEPT:MATHERR:RANGE/
4494 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
4495 : echo "Range error in" function
4496 :
4497 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
4498 : echo "Math error"
4499 :
4500 :catch /^EXCEPT:IO/
4501 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
4502 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
4503 : if file !~ '^/'
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004504 : let file = dir .. "/" .. file
Bram Moolenaar071d4272004-06-13 20:20:40 +00004505 : endif
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004506 : echo 'I/O error for "' .. file .. '"'
Bram Moolenaar071d4272004-06-13 20:20:40 +00004507 :
4508 :catch /^EXCEPT/
4509 : echo "Unspecified error"
4510 :
4511 :endtry
4512
4513The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
4514a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
4515exceptions with the "Vim" prefix; they are reserved for Vim.
4516 Vim error exceptions are parameterized with the name of the command that
4517failed, if known. See |catch-errors|.
4518
4519
4520PECULIARITIES
4521 *except-compat*
4522The exception handling concept requires that the command sequence causing the
4523exception is aborted immediately and control is transferred to finally clauses
4524and/or a catch clause.
4525
4526In the Vim script language there are cases where scripts and functions
4527continue after an error: in functions without the "abort" flag or in a command
4528after ":silent!", control flow goes to the following line, and outside
4529functions, control flow goes to the line following the outermost ":endwhile"
4530or ":endif". On the other hand, errors should be catchable as exceptions
4531(thus, requiring the immediate abortion).
4532
4533This problem has been solved by converting errors to exceptions and using
4534immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar58b85342016-08-14 19:54:54 +02004535conditional is active. This is no restriction since an (error) exception can
4536be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +00004537termination without catching the error, just use a try conditional without
4538catch clause. (You can cause cleanup code being executed before termination
4539by specifying a finally clause.)
4540
4541When no try conditional is active, the usual abortion and continuation
4542behavior is used instead of immediate abortion. This ensures compatibility of
4543scripts written for Vim 6.1 and earlier.
4544
4545However, when sourcing an existing script that does not use exception handling
4546commands (or when calling one of its functions) from inside an active try
4547conditional of a new script, you might change the control flow of the existing
4548script on error. You get the immediate abortion on error and can catch the
4549error in the new script. If however the sourced script suppresses error
4550messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar58b85342016-08-14 19:54:54 +02004551|v:errmsg| if appropriate), its execution path is not changed. The error is
4552not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +00004553where this happens is for scripts that don't care about errors and produce
4554error messages. You probably won't want to use such code from your new
4555scripts.
4556
4557 *except-syntax-err*
4558Syntax errors in the exception handling commands are never caught by any of
4559the ":catch" commands of the try conditional they belong to. Its finally
4560clauses, however, is executed.
4561 Example: >
4562
4563 :try
4564 : try
4565 : throw 4711
4566 : catch /\(/
4567 : echo "in catch with syntax error"
4568 : catch
4569 : echo "inner catch-all"
4570 : finally
4571 : echo "inner finally"
4572 : endtry
4573 :catch
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004574 : echo 'outer catch-all caught "' .. v:exception .. '"'
Bram Moolenaar071d4272004-06-13 20:20:40 +00004575 : finally
4576 : echo "outer finally"
4577 :endtry
4578
4579This displays: >
4580 inner finally
4581 outer catch-all caught "Vim(catch):E54: Unmatched \("
4582 outer finally
4583The original exception is discarded and an error exception is raised, instead.
4584
4585 *except-single-line*
4586The ":try", ":catch", ":finally", and ":endtry" commands can be put on
4587a single line, but then syntax errors may make it difficult to recognize the
4588"catch" line, thus you better avoid this.
4589 Example: >
4590 :try | unlet! foo # | catch | endtry
4591raises an error exception for the trailing characters after the ":unlet!"
4592argument, but does not see the ":catch" and ":endtry" commands, so that the
4593error exception is discarded and the "E488: Trailing characters" message gets
4594displayed.
4595
4596 *except-several-errors*
4597When several errors appear in a single command, the first error message is
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02004598usually the most specific one and therefore converted to the error exception.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004599 Example: >
4600 echo novar
4601causes >
4602 E121: Undefined variable: novar
4603 E15: Invalid expression: novar
4604The value of the error exception inside try conditionals is: >
4605 Vim(echo):E121: Undefined variable: novar
4606< *except-syntax-error*
4607But when a syntax error is detected after a normal error in the same command,
4608the syntax error is used for the exception being thrown.
4609 Example: >
4610 unlet novar #
4611causes >
4612 E108: No such variable: "novar"
4613 E488: Trailing characters
4614The value of the error exception inside try conditionals is: >
4615 Vim(unlet):E488: Trailing characters
4616This is done because the syntax error might change the execution path in a way
4617not intended by the user. Example: >
4618 try
4619 try | unlet novar # | catch | echo v:exception | endtry
4620 catch /.*/
4621 echo "outer catch:" v:exception
4622 endtry
4623This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
4624a "E600: Missing :endtry" error message is given, see |except-single-line|.
4625
4626==============================================================================
46279. Examples *eval-examples*
4628
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004629Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004630>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004631 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004632 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004633 : let n = a:nr
4634 : let r = ""
4635 : while n
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004636 : let r = '01'[n % 2] .. r
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004637 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00004638 : endwhile
4639 : return r
4640 :endfunc
4641
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004642 :" The function String2Bin() converts each character in a string to a
4643 :" binary string, separated with dashes.
4644 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004645 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004646 : for ix in range(strlen(a:str))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00004647 : let out = out .. '-' .. Nr2Bin(char2nr(a:str[ix]))
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004648 : endfor
4649 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004650 :endfunc
4651
4652Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004653 :echo Nr2Bin(32)
4654result: "100000" >
4655 :echo String2Bin("32")
4656result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +00004657
4658
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004659Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004660
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004661This example sorts lines with a specific compare function. >
4662
4663 :func SortBuffer()
4664 : let lines = getline(1, '$')
4665 : call sort(lines, function("Strcmp"))
4666 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004667 :endfunction
4668
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004669As a one-liner: >
4670 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +00004671
Bram Moolenaar071d4272004-06-13 20:20:40 +00004672
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004673scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00004674 *sscanf*
4675There is no sscanf() function in Vim. If you need to extract parts from a
4676line, you can use matchstr() and substitute() to do it. This example shows
4677how to get the file name, line number and column number out of a line like
4678"foobar.txt, 123, 45". >
4679 :" Set up the match bit
4680 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
4681 :"get the part matching the whole expression
4682 :let l = matchstr(line, mx)
4683 :"get each item out of the match
4684 :let file = substitute(l, mx, '\1', '')
4685 :let lnum = substitute(l, mx, '\2', '')
4686 :let col = substitute(l, mx, '\3', '')
4687
4688The input is in the variable "line", the results in the variables "file",
4689"lnum" and "col". (idea from Michael Geddes)
4690
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004691
4692getting the scriptnames in a Dictionary ~
4693 *scriptnames-dictionary*
Bram Moolenaardd60c362023-02-27 15:49:53 +00004694The `:scriptnames` command can be used to get a list of all script files that
4695have been sourced. There is also the `getscriptinfo()` function, but the
4696information returned is not exactly the same. In case you need to manipulate
Bram Moolenaar71badf92023-04-22 22:40:14 +01004697the list, this code can be used as a base: >
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004698
Bram Moolenaar71badf92023-04-22 22:40:14 +01004699 # Create or update scripts dictionary, indexed by SNR, and return it.
4700 def Scripts(scripts: dict<string> = {}): dict<string>
4701 for info in getscriptinfo()
4702 if scripts->has_key(info.sid)
4703 continue
4704 endif
4705 scripts[info.sid] = info.name
4706 endfor
4707 return scripts
4708 enddef
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004709
Bram Moolenaar071d4272004-06-13 20:20:40 +00004710==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +0200471110. Vim script versions *vimscript-version* *vimscript-versions*
Bram Moolenaar911ead12019-04-21 00:03:35 +02004712 *scriptversion*
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004713Over time many features have been added to Vim script. This includes Ex
4714commands, functions, variable types, etc. Each individual feature can be
4715checked with the |has()| and |exists()| functions.
4716
4717Sometimes old syntax of functionality gets in the way of making Vim better.
4718When support is taken away this will break older Vim scripts. To make this
4719explicit the |:scriptversion| command can be used. When a Vim script is not
4720compatible with older versions of Vim this will give an explicit error,
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02004721instead of failing in mysterious ways.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004722
Bram Moolenaara2baa732022-02-04 16:09:54 +00004723When using a legacy function, defined with `:function`, in |Vim9| script then
4724scriptversion 4 is used.
4725
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02004726 *scriptversion-1* >
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004727 :scriptversion 1
4728< This is the original Vim script, same as not using a |:scriptversion|
4729 command. Can be used to go back to old syntax for a range of lines.
4730 Test for support with: >
4731 has('vimscript-1')
4732
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02004733< *scriptversion-2* >
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004734 :scriptversion 2
Bram Moolenaar68e65602019-05-26 21:33:31 +02004735< String concatenation with "." is not supported, use ".." instead.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004736 This avoids the ambiguity using "." for Dict member access and
4737 floating point numbers. Now ".5" means the number 0.5.
Bram Moolenaar3ff5f0f2019-06-10 13:11:22 +02004738
4739 *scriptversion-3* >
Bram Moolenaar911ead12019-04-21 00:03:35 +02004740 :scriptversion 3
4741< All |vim-variable|s must be prefixed by "v:". E.g. "version" doesn't
4742 work as |v:version| anymore, it can be used as a normal variable.
4743 Same for some obvious names as "count" and others.
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004744
Bram Moolenaar911ead12019-04-21 00:03:35 +02004745 Test for support with: >
4746 has('vimscript-3')
Bram Moolenaar60a8de22019-09-15 14:33:22 +02004747<
4748 *scriptversion-4* >
4749 :scriptversion 4
Bram Moolenaarc17e66c2020-06-02 21:38:22 +02004750< Numbers with a leading zero are not recognized as octal. "0o" or "0O"
4751 is still recognized as octal. With the
Bram Moolenaar60a8de22019-09-15 14:33:22 +02004752 previous version you get: >
Bram Moolenaarc17e66c2020-06-02 21:38:22 +02004753 echo 017 " displays 15 (octal)
4754 echo 0o17 " displays 15 (octal)
4755 echo 018 " displays 18 (decimal)
Bram Moolenaar60a8de22019-09-15 14:33:22 +02004756< with script version 4: >
Bram Moolenaarc17e66c2020-06-02 21:38:22 +02004757 echo 017 " displays 17 (decimal)
4758 echo 0o17 " displays 15 (octal)
4759 echo 018 " displays 18 (decimal)
Bram Moolenaar60a8de22019-09-15 14:33:22 +02004760< Also, it is possible to use single quotes inside numbers to make them
4761 easier to read: >
4762 echo 1'000'000
4763< The quotes must be surrounded by digits.
4764
4765 Test for support with: >
4766 has('vimscript-4')
Bram Moolenaar558ca4a2019-04-04 18:15:38 +02004767
4768==============================================================================
476911. No +eval feature *no-eval-feature*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004770
4771When the |+eval| feature was disabled at compile time, none of the expression
4772evaluation commands are available. To prevent this from causing Vim scripts
4773to generate all kinds of errors, the ":if" and ":endif" commands are still
4774recognized, though the argument of the ":if" and everything between the ":if"
4775and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
4776only if the commands are at the start of the line. The ":else" command is not
4777recognized.
4778
4779Example of how to avoid executing commands when the |+eval| feature is
4780missing: >
4781
4782 :if 1
4783 : echo "Expression evaluation is compiled in"
4784 :else
4785 : echo "You will _never_ see this message"
4786 :endif
4787
Bram Moolenaar773a97c2019-06-06 20:39:55 +02004788To execute a command only when the |+eval| feature is disabled can be done in
4789two ways. The simplest is to exit the script (or Vim) prematurely: >
4790 if 1
4791 echo "commands executed with +eval"
4792 finish
4793 endif
4794 args " command executed without +eval
4795
4796If you do not want to abort loading the script you can use a trick, as this
4797example shows: >
Bram Moolenaar45d2cca2017-04-30 16:36:05 +02004798
4799 silent! while 0
4800 set history=111
4801 silent! endwhile
4802
4803When the |+eval| feature is available the command is skipped because of the
4804"while 0". Without the |+eval| feature the "while 0" is an error, which is
4805silently ignored, and the command is executed.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004806
Bram Moolenaar071d4272004-06-13 20:20:40 +00004807==============================================================================
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000480812. The sandbox *eval-sandbox* *sandbox*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004809
Bram Moolenaar368373e2010-07-19 20:46:22 +02004810The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
4811'foldtext' options may be evaluated in a sandbox. This means that you are
4812protected from these expressions having nasty side effects. This gives some
4813safety for when these options are set from a modeline. It is also used when
4814the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00004815The sandbox is also used for the |:sandbox| command.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00004816 *E48*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004817These items are not allowed in the sandbox:
4818 - changing the buffer text
Bram Moolenaarb477af22018-07-15 20:20:18 +02004819 - defining or changing mapping, autocommands, user commands
Bram Moolenaar071d4272004-06-13 20:20:40 +00004820 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004821 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004822 - executing a shell command
4823 - reading or writing a file
4824 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +00004825 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00004826This is not guaranteed 100% secure, but it should block most attacks.
4827
4828 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +00004829:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00004830 option that may have been set from a modeline, e.g.
4831 'foldexpr'.
4832
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004833 *sandbox-option*
4834A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00004835have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004836restrictive, thus this only happens when the option was set from an insecure
4837location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004838- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004839- while executing in the sandbox
4840- value coming from a modeline
Bram Moolenaarb477af22018-07-15 20:20:18 +02004841- executing a function that was defined in the sandbox
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004842
4843Note that when in the sandbox and saving an option value and restoring it, the
4844option will still be marked as it was set in the sandbox.
4845
4846==============================================================================
Bram Moolenaar558ca4a2019-04-04 18:15:38 +0200484713. Textlock *textlock*
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004848
4849In a few situations it is not allowed to change the text in the buffer, jump
4850to another window and some other things that might confuse or break what Vim
4851is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar58b85342016-08-14 19:54:54 +02004852actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004853happen any moment the mouse cursor is resting at some position.
4854
4855This is not allowed when the textlock is active:
4856 - changing the buffer text
4857 - jumping to another buffer or window
4858 - editing another file
4859 - closing a window or quitting Vim
4860 - etc.
4861
Christian Brabandtda4e4332023-11-05 10:45:12 +01004862==============================================================================
486314. Vim script library *vim-script-library*
4864
4865Vim comes bundled with a Vim script library, that can be used by runtime,
4866script authors. Currently, it only includes very few functions, but it may
4867grow over time.
4868
h_east596a9f22023-11-21 21:24:23 +09004869The functions are available as |Vim9-script| as well as using legacy Vim
Christian Brabandtda4e4332023-11-05 10:45:12 +01004870script (to be used for non Vim 9.0 versions and Neovim).
4871
4872 *dist#vim* *dist#vim9*
h_east596a9f22023-11-21 21:24:23 +09004873The functions make use of the autoloaded prefix "dist#vim" (for legacy Vim
4874script and Neovim) and "dist#vim9" for Vim9 script.
Christian Brabandtda4e4332023-11-05 10:45:12 +01004875
4876The following functions are available:
4877
4878dist#vim#IsSafeExecutable(filetype, executable) ~
4879dist#vim9#IsSafeExecutable(filetype:string, executable:string): bool ~
4880
4881This function takes a filetype and an executable and checks whether it is safe
4882to execute the given executable. For security reasons users may not want to
4883have Vim execute random executables or may have forbidden to do so for
4884specific filetypes by setting the "<filetype>_exec" variable (|plugin_exec|).
4885
4886It returns |true| or |false| to indicate whether the plugin should run the given
zeertzjq61e984e2023-12-09 15:18:33 +08004887executable. It takes the following arguments:
Christian Brabandtda4e4332023-11-05 10:45:12 +01004888
4889 argument type ~
4890
4891 filetype string
4892 executable string
4893
Bram Moolenaar071d4272004-06-13 20:20:40 +00004894
Bram Moolenaar91f84f62018-07-29 15:07:52 +02004895 vim:tw=78:ts=8:noet:ft=help:norl: