blob: 535517d21d1a8553fe759dcff2b139749bd85701 [file] [log] [blame]
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +01001*eval.txt* For Vim version 8.1. Last change: 2019 Feb 03
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*
8
9Using 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 Moolenaar13065c42005-01-08 16:08:21 +0000151. Variables |variables|
16 1.1 Variable types
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000017 1.2 Function references |Funcref|
Bram Moolenaar7c626922005-02-07 22:01:03 +000018 1.3 Lists |Lists|
Bram Moolenaard8b02732005-01-14 21:48:43 +000019 1.4 Dictionaries |Dictionaries|
Bram Moolenaard8968242019-01-15 22:51:57 +010020 1.5 Blobs |Blobs|
21 1.6 More about variables |more-variables|
Bram Moolenaar13065c42005-01-08 16:08:21 +0000222. Expression syntax |expression-syntax|
233. Internal variable |internal-variables|
244. Builtin Functions |functions|
255. Defining functions |user-functions|
266. Curly braces names |curly-braces-names|
277. Commands |expression-commands|
288. Exception handling |exception-handling|
299. Examples |eval-examples|
3010. No +eval feature |no-eval-feature|
3111. The sandbox |eval-sandbox|
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003212. Textlock |textlock|
Bram Moolenaardc1f1642016-08-16 18:33:43 +02003313. Testing |testing|
Bram Moolenaar071d4272004-06-13 20:20:40 +000034
35{Vi does not have any of these commands}
36
37==============================================================================
381. Variables *variables*
39
Bram Moolenaar13065c42005-01-08 16:08:21 +0000401.1 Variable types ~
Bram Moolenaarbf821bc2019-01-23 21:15:02 +010041 *E712* *E896* *E897* *E899*
Bram Moolenaar38a55632016-02-15 22:07:32 +010042There are nine types of variables:
Bram Moolenaar071d4272004-06-13 20:20:40 +000043
Bram Moolenaar5302d9e2011-09-14 17:55:08 +020044Number A 32 or 64 bit signed number. |expr-number| *Number*
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020045 64-bit Numbers are available only when compiled with the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020046 |+num64| feature.
Bram Moolenaar7571d552016-08-18 22:54:46 +020047 Examples: -123 0x10 0177 0b1011
Bram Moolenaard8b02732005-01-14 21:48:43 +000048
Bram Moolenaar446cb832008-06-24 21:56:24 +000049Float A floating point number. |floating-point-format| *Float*
50 {only when compiled with the |+float| feature}
51 Examples: 123.456 1.15e-6 -1.1e3
52
Bram Moolenaar06481422016-04-30 15:13:38 +020053 *E928*
Bram Moolenaard8b02732005-01-14 21:48:43 +000054String A NUL terminated string of 8-bit unsigned characters (bytes).
Bram Moolenaar446cb832008-06-24 21:56:24 +000055 |expr-string| Examples: "ab\txx\"--" 'x-z''a,c'
Bram Moolenaard8b02732005-01-14 21:48:43 +000056
Bram Moolenaard8968242019-01-15 22:51:57 +010057List An ordered sequence of items, see |List| for details.
Bram Moolenaard8b02732005-01-14 21:48:43 +000058 Example: [1, 2, ['a', 'b']]
Bram Moolenaar071d4272004-06-13 20:20:40 +000059
Bram Moolenaar39a58ca2005-06-27 22:42:44 +000060Dictionary An associative, unordered array: Each entry has a key and a
61 value. |Dictionary|
62 Example: {'blue': "#0000ff", 'red': "#ff0000"}
63
Bram Moolenaar835dc632016-02-07 14:27:38 +010064Funcref A reference to a function |Funcref|.
65 Example: function("strlen")
Bram Moolenaar1d429612016-05-24 15:44:17 +020066 It can be bound to a dictionary and arguments, it then works
67 like a Partial.
68 Example: function("Callback", [arg], myDict)
Bram Moolenaar835dc632016-02-07 14:27:38 +010069
Bram Moolenaar02e83b42016-02-21 20:10:26 +010070Special |v:false|, |v:true|, |v:none| and |v:null|. *Special*
Bram Moolenaar835dc632016-02-07 14:27:38 +010071
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020072Job Used for a job, see |job_start()|. *Job* *Jobs*
Bram Moolenaar38a55632016-02-15 22:07:32 +010073
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +020074Channel Used for a channel, see |ch_open()|. *Channel* *Channels*
Bram Moolenaar835dc632016-02-07 14:27:38 +010075
Bram Moolenaard8968242019-01-15 22:51:57 +010076Blob Binary Large Object. Stores any sequence of bytes. See |Blob|
77 for details
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010078 Example: 0zFF00ED015DAF
79 0z is an empty Blob.
80
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000081The Number and String types are converted automatically, depending on how they
82are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000083
84Conversion from a Number to a String is by making the ASCII representation of
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020085the Number. Examples:
86 Number 123 --> String "123" ~
87 Number 0 --> String "0" ~
88 Number -1 --> String "-1" ~
Bram Moolenaar00a927d2010-05-14 23:24:24 +020089 *octal*
Bram Moolenaarfa735342016-01-03 22:14:44 +010090Conversion from a String to a Number is done by converting the first digits to
91a number. Hexadecimal "0xf9", Octal "017", and Binary "0b10" numbers are
92recognized. If the String doesn't start with digits, the result is zero.
93Examples:
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +020094 String "456" --> Number 456 ~
95 String "6bar" --> Number 6 ~
96 String "foo" --> Number 0 ~
97 String "0xf1" --> Number 241 ~
98 String "0100" --> Number 64 ~
Bram Moolenaarfa735342016-01-03 22:14:44 +010099 String "0b101" --> Number 5 ~
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200100 String "-8" --> Number -8 ~
101 String "+8" --> Number 0 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000102
103To force conversion from String to Number, add zero to it: >
104 :echo "0100" + 0
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000105< 64 ~
106
107To avoid a leading zero to cause octal conversion, or for using a different
108base, use |str2nr()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000109
Bram Moolenaard09091d2019-01-17 16:07:22 +0100110 *TRUE* *FALSE* *Boolean*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000111For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200112You can also use |v:false| and |v:true|. When TRUE is returned from a
113function it is the Number one, FALSE is the number zero.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000114
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200115Note that in the command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000116 :if "foo"
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200117 :" NOT executed
118"foo" is converted to 0, which means FALSE. If the string starts with a
119non-zero number it means TRUE: >
120 :if "8foo"
121 :" executed
122To test for a non-empty string, use empty(): >
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200123 :if !empty("foo")
Bram Moolenaar835dc632016-02-07 14:27:38 +0100124<
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200125 *non-zero-arg*
126Function arguments often behave slightly different from |TRUE|: If the
127argument is present and it evaluates to a non-zero Number, |v:true| or a
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200128non-empty String, then the value is considered to be TRUE.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100129Note that " " and "0" are also non-empty strings, thus considered to be TRUE.
130A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE.
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200131
Bram Moolenaar38a55632016-02-15 22:07:32 +0100132 *E745* *E728* *E703* *E729* *E730* *E731* *E908* *E910* *E913*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +0100133 *E974* *E975* *E976*
Bram Moolenaard09091d2019-01-17 16:07:22 +0100134|List|, |Dictionary|, |Funcref|, |Job|, |Channel| and |Blob| types are not
135automatically converted.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000136
Bram Moolenaar446cb832008-06-24 21:56:24 +0000137 *E805* *E806* *E808*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200138When mixing Number and Float the Number is converted to Float. Otherwise
Bram Moolenaar446cb832008-06-24 21:56:24 +0000139there is no automatic conversion of Float. You can use str2float() for String
140to Float, printf() for Float to String and float2nr() for Float to Number.
141
Bram Moolenaar38a55632016-02-15 22:07:32 +0100142 *E891* *E892* *E893* *E894* *E907* *E911* *E914*
Bram Moolenaar13d5aee2016-01-21 23:36:05 +0100143When expecting a Float a Number can also be used, but nothing else.
144
Bram Moolenaarf6f32c32016-03-12 19:03:59 +0100145 *no-type-checking*
146You will not get an error if you try to change the type of a variable.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000147
Bram Moolenaar13065c42005-01-08 16:08:21 +0000148
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001491.2 Function references ~
Bram Moolenaar748bf032005-02-02 23:04:36 +0000150 *Funcref* *E695* *E718*
Bram Moolenaar58b85342016-08-14 19:54:54 +0200151A Funcref variable is obtained with the |function()| function, the |funcref()|
152function or created with the lambda expression |expr-lambda|. It can be used
153in an expression in the place of a function name, before the parenthesis
154around the arguments, to invoke the function it refers to. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000155
156 :let Fn = function("MyFunc")
157 :echo Fn()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000158< *E704* *E705* *E707*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000159A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200160can use "g:" but the following name must still start with a capital. You
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000161cannot have both a Funcref variable and a function with the same name.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000162
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000163A special case is defining a function and directly assigning its Funcref to a
164Dictionary entry. Example: >
165 :function dict.init() dict
166 : let self.val = 0
167 :endfunction
168
169The key of the Dictionary can start with a lower case letter. The actual
170function name is not used here. Also see |numbered-function|.
171
172A Funcref can also be used with the |:call| command: >
173 :call Fn()
174 :call dict.init()
Bram Moolenaar13065c42005-01-08 16:08:21 +0000175
176The name of the referenced function can be obtained with |string()|. >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000177 :let func = string(Fn)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000178
179You can use |call()| to invoke a Funcref and use a list variable for the
180arguments: >
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000181 :let r = call(Fn, mylist)
Bram Moolenaar1d429612016-05-24 15:44:17 +0200182<
183 *Partial*
184A Funcref optionally binds a Dictionary and/or arguments. This is also called
185a Partial. This is created by passing the Dictionary and/or arguments to
Bram Moolenaar58b85342016-08-14 19:54:54 +0200186function() or funcref(). When calling the function the Dictionary and/or
187arguments will be passed to the function. Example: >
Bram Moolenaar1d429612016-05-24 15:44:17 +0200188
189 let Cb = function('Callback', ['foo'], myDict)
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100190 call Cb('bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200191
192This will invoke the function as if using: >
Bram Moolenaarba3ff532018-11-04 14:45:49 +0100193 call myDict.Callback('foo', 'bar')
Bram Moolenaar1d429612016-05-24 15:44:17 +0200194
195This is very useful when passing a function around, e.g. in the arguments of
196|ch_open()|.
197
198Note that binding a function to a Dictionary also happens when the function is
199a member of the Dictionary: >
200
201 let myDict.myFunction = MyFunction
202 call myDict.myFunction()
203
204Here MyFunction() will get myDict passed as "self". This happens when the
205"myFunction" member is accessed. When making assigning "myFunction" to
206otherDict and calling it, it will be bound to otherDict: >
207
208 let otherDict.myFunction = myDict.myFunction
209 call otherDict.myFunction()
210
211Now "self" will be "otherDict". But when the dictionary was bound explicitly
212this won't happen: >
213
214 let myDict.myFunction = function(MyFunction, myDict)
215 let otherDict.myFunction = myDict.myFunction
216 call otherDict.myFunction()
217
Bram Moolenaard823fa92016-08-12 16:29:27 +0200218Here "self" will be "myDict", because it was bound explicitly.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000219
220
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00002211.3 Lists ~
Bram Moolenaar7e38ea22014-04-05 22:55:53 +0200222 *list* *List* *Lists* *E686*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000223A List is an ordered sequence of items. An item can be of any type. Items
Bram Moolenaar58b85342016-08-14 19:54:54 +0200224can be accessed by their index number. Items can be added and removed at any
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000225position in the sequence.
226
Bram Moolenaar13065c42005-01-08 16:08:21 +0000227
228List creation ~
229 *E696* *E697*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000230A List is created with a comma separated list of items in square brackets.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000231Examples: >
232 :let mylist = [1, two, 3, "four"]
233 :let emptylist = []
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000234
Bram Moolenaar58b85342016-08-14 19:54:54 +0200235An item can be any expression. Using a List for an item creates a
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000236List of Lists: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000237 :let nestlist = [[11, 12], [21, 22], [31, 32]]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000238
239An extra comma after the last item is ignored.
240
Bram Moolenaar13065c42005-01-08 16:08:21 +0000241
242List index ~
243 *list-index* *E684*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000244An item in the List can be accessed by putting the index in square brackets
Bram Moolenaar13065c42005-01-08 16:08:21 +0000245after the List. Indexes are zero-based, thus the first item has index zero. >
246 :let item = mylist[0] " get the first item: 1
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000247 :let item = mylist[2] " get the third item: 3
Bram Moolenaar13065c42005-01-08 16:08:21 +0000248
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000249When the resulting item is a list this can be repeated: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000250 :let item = nestlist[0][1] " get the first list, second item: 12
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000251<
Bram Moolenaar13065c42005-01-08 16:08:21 +0000252A negative index is counted from the end. Index -1 refers to the last item in
253the List, -2 to the last but one item, etc. >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000254 :let last = mylist[-1] " get the last item: "four"
255
Bram Moolenaar13065c42005-01-08 16:08:21 +0000256To avoid an error for an invalid index use the |get()| function. When an item
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000257is not available it returns zero or the default value you specify: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000258 :echo get(mylist, idx)
259 :echo get(mylist, idx, "NONE")
260
261
262List concatenation ~
263
264Two lists can be concatenated with the "+" operator: >
265 :let longlist = mylist + [5, 6]
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000266 :let mylist += [7, 8]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000267
268To prepend or append an item turn the item into a list by putting [] around
269it. To change a list in-place see |list-modification| below.
270
271
272Sublist ~
Bram Moolenaarbc8801c2016-08-02 21:04:33 +0200273 *sublist*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000274A part of the List can be obtained by specifying the first and last index,
275separated by a colon in square brackets: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000276 :let shortlist = mylist[2:-1] " get List [3, "four"]
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000277
278Omitting the first index is similar to zero. Omitting the last index is
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000279similar to -1. >
Bram Moolenaar540d6e32005-01-09 21:20:18 +0000280 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
281 :let shortlist = mylist[2:2] " List with one item: [3]
282 :let otherlist = mylist[:] " make a copy of the List
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000283
Bram Moolenaarf9393ef2006-04-24 19:47:27 +0000284If the first index is beyond the last item of the List or the second item is
285before the first item, the result is an empty list. There is no error
286message.
287
288If the second index is equal to or greater than the length of the list the
289length minus one is used: >
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000290 :let mylist = [0, 1, 2, 3]
291 :echo mylist[2:8] " result: [2, 3]
292
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000293NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
Bram Moolenaar58b85342016-08-14 19:54:54 +0200294using a single letter variable before the ":". Insert a space when needed:
Bram Moolenaara7fc0102005-05-18 22:17:12 +0000295mylist[s : e].
296
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +0000297
Bram Moolenaar13065c42005-01-08 16:08:21 +0000298List identity ~
Bram Moolenaard8b02732005-01-14 21:48:43 +0000299 *list-identity*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000300When variable "aa" is a list and you assign it to another variable "bb", both
301variables refer to the same list. Thus changing the list "aa" will also
302change "bb": >
303 :let aa = [1, 2, 3]
304 :let bb = aa
305 :call add(aa, 4)
306 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000307< [1, 2, 3, 4]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000308
309Making a copy of a list is done with the |copy()| function. Using [:] also
310works, as explained above. This creates a shallow copy of the list: Changing
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000311a list item in the list will also change the item in the copied list: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000312 :let aa = [[1, 'a'], 2, 3]
313 :let bb = copy(aa)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000314 :call add(aa, 4)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000315 :let aa[0][1] = 'aaa'
316 :echo aa
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000317< [[1, aaa], 2, 3, 4] >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000318 :echo bb
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000319< [[1, aaa], 2, 3]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000320
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000321To make a completely independent list use |deepcopy()|. This also makes a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000322copy of the values in the list, recursively. Up to a hundred levels deep.
Bram Moolenaar13065c42005-01-08 16:08:21 +0000323
324The operator "is" can be used to check if two variables refer to the same
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000325List. "isnot" does the opposite. In contrast "==" compares if two lists have
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000326the same value. >
327 :let alist = [1, 2, 3]
328 :let blist = [1, 2, 3]
329 :echo alist is blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000330< 0 >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000331 :echo alist == blist
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000332< 1
Bram Moolenaar13065c42005-01-08 16:08:21 +0000333
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000334Note about comparing lists: Two lists are considered equal if they have the
335same length and all items compare equal, as with using "==". There is one
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000336exception: When comparing a number with a string they are considered
337different. There is no automatic type conversion, as with using "==" on
338variables. Example: >
339 echo 4 == "4"
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000340< 1 >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000341 echo [4] == ["4"]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000342< 0
343
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000344Thus comparing Lists is more strict than comparing numbers and strings. You
Bram Moolenaar446cb832008-06-24 21:56:24 +0000345can compare simple values this way too by putting them in a list: >
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000346
347 :let a = 5
348 :let b = "5"
Bram Moolenaar446cb832008-06-24 21:56:24 +0000349 :echo a == b
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000350< 1 >
Bram Moolenaar446cb832008-06-24 21:56:24 +0000351 :echo [a] == [b]
Bram Moolenaar7d1f5db2005-07-03 21:39:27 +0000352< 0
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +0000353
Bram Moolenaar13065c42005-01-08 16:08:21 +0000354
355List unpack ~
356
357To unpack the items in a list to individual variables, put the variables in
358square brackets, like list items: >
359 :let [var1, var2] = mylist
360
361When the number of variables does not match the number of items in the list
362this produces an error. To handle any extra items from the list append ";"
363and a variable name: >
364 :let [var1, var2; rest] = mylist
365
366This works like: >
367 :let var1 = mylist[0]
368 :let var2 = mylist[1]
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000369 :let rest = mylist[2:]
Bram Moolenaar13065c42005-01-08 16:08:21 +0000370
371Except that there is no error if there are only two items. "rest" will be an
372empty list then.
373
374
375List modification ~
376 *list-modification*
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000377To change a specific item of a list use |:let| this way: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000378 :let list[4] = "four"
379 :let listlist[0][3] = item
380
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000381To change part of a list you can specify the first and last item to be
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000382modified. The value must at least have the number of items in the range: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000383 :let list[3:5] = [3, 4, 5]
384
Bram Moolenaar13065c42005-01-08 16:08:21 +0000385Adding and removing items from a list is done with functions. Here are a few
386examples: >
387 :call insert(list, 'a') " prepend item 'a'
388 :call insert(list, 'a', 3) " insert item 'a' before list[3]
389 :call add(list, "new") " append String item
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000390 :call add(list, [1, 2]) " append a List as one new item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000391 :call extend(list, [1, 2]) " extend the list with two more items
392 :let i = remove(list, 3) " remove item 3
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000393 :unlet list[3] " idem
Bram Moolenaar13065c42005-01-08 16:08:21 +0000394 :let l = remove(list, 3, -1) " remove items 3 to last item
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000395 :unlet list[3 : ] " idem
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000396 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
Bram Moolenaar13065c42005-01-08 16:08:21 +0000397
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000398Changing the order of items in a list: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000399 :call sort(list) " sort a list alphabetically
400 :call reverse(list) " reverse the order of items
Bram Moolenaar327aa022014-03-25 18:24:23 +0100401 :call uniq(sort(list)) " sort and remove duplicates
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000402
Bram Moolenaar13065c42005-01-08 16:08:21 +0000403
404For loop ~
405
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000406The |:for| loop executes commands for each item in a list. A variable is set
407to each item in the list in sequence. Example: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000408 :for item in mylist
409 : call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000410 :endfor
411
412This works like: >
413 :let index = 0
414 :while index < len(mylist)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000415 : let item = mylist[index]
416 : :call Doit(item)
Bram Moolenaar13065c42005-01-08 16:08:21 +0000417 : let index = index + 1
418 :endwhile
419
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000420If all you want to do is modify each item in the list then the |map()|
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000421function will be a simpler method than a for loop.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000422
Bram Moolenaar58b85342016-08-14 19:54:54 +0200423Just like the |:let| command, |:for| also accepts a list of variables. This
Bram Moolenaar13065c42005-01-08 16:08:21 +0000424requires the argument to be a list of lists. >
425 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
426 : call Doit(lnum, col)
427 :endfor
428
429This works like a |:let| command is done for each list item. Again, the types
430must remain the same to avoid an error.
431
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000432It is also possible to put remaining items in a List variable: >
Bram Moolenaar13065c42005-01-08 16:08:21 +0000433 :for [i, j; rest] in listlist
434 : call Doit(i, j)
435 : if !empty(rest)
436 : echo "remainder: " . string(rest)
437 : endif
438 :endfor
439
440
441List functions ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000442 *E714*
Bram Moolenaar13065c42005-01-08 16:08:21 +0000443Functions that are useful with a List: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000444 :let r = call(funcname, list) " call a function with an argument list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000445 :if empty(list) " check if list is empty
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000446 :let l = len(list) " number of items in list
447 :let big = max(list) " maximum value in list
448 :let small = min(list) " minimum value in list
Bram Moolenaar9588a0f2005-01-08 21:45:39 +0000449 :let xs = count(list, 'x') " count nr of times 'x' appears in list
450 :let i = index(list, 'x') " index of first 'x' in list
Bram Moolenaar13065c42005-01-08 16:08:21 +0000451 :let lines = getline(1, 10) " get ten text lines from buffer
452 :call append('$', lines) " append text lines in buffer
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +0000453 :let list = split("a b c") " create list from items in a string
454 :let string = join(list, ', ') " create string from list items
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000455 :let s = string(list) " String representation of list
456 :call map(list, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaar13065c42005-01-08 16:08:21 +0000457
Bram Moolenaar0cb032e2005-04-23 20:52:00 +0000458Don't forget that a combination of features can make things simple. For
459example, to add up all the numbers in a list: >
460 :exe 'let sum = ' . join(nrlist, '+')
461
Bram Moolenaar13065c42005-01-08 16:08:21 +0000462
Bram Moolenaard8b02732005-01-14 21:48:43 +00004631.4 Dictionaries ~
Bram Moolenaard8968242019-01-15 22:51:57 +0100464 *dict* *Dict* *Dictionaries* *Dictionary*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000465A Dictionary is an associative array: Each entry has a key and a value. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000466entry can be located with the key. The entries are stored without a specific
467ordering.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000468
469
470Dictionary creation ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000471 *E720* *E721* *E722* *E723*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000472A Dictionary is created with a comma separated list of entries in curly
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000473braces. Each entry has a key and a value, separated by a colon. Each key can
474only appear once. Examples: >
Bram Moolenaard8b02732005-01-14 21:48:43 +0000475 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
476 :let emptydict = {}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000477< *E713* *E716* *E717*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000478A key is always a String. You can use a Number, it will be converted to a
479String automatically. Thus the String '4' and the number 4 will find the same
Bram Moolenaar58b85342016-08-14 19:54:54 +0200480entry. Note that the String '04' and the Number 04 are different, since the
Bram Moolenaar03413f42016-04-12 21:07:15 +0200481Number will be converted to the String '4'. The empty string can be used as a
482key.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000483
Bram Moolenaar58b85342016-08-14 19:54:54 +0200484A value can be any expression. Using a Dictionary for a value creates a
Bram Moolenaard8b02732005-01-14 21:48:43 +0000485nested Dictionary: >
486 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
487
488An extra comma after the last entry is ignored.
489
490
491Accessing entries ~
492
493The normal way to access an entry is by putting the key in square brackets: >
494 :let val = mydict["one"]
495 :let mydict["four"] = 4
496
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000497You can add new entries to an existing Dictionary this way, unlike Lists.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000498
499For keys that consist entirely of letters, digits and underscore the following
500form can be used |expr-entry|: >
501 :let val = mydict.one
502 :let mydict.four = 4
503
504Since an entry can be any type, also a List and a Dictionary, the indexing and
505key lookup can be repeated: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000506 :echo dict.key[idx].key
Bram Moolenaard8b02732005-01-14 21:48:43 +0000507
508
509Dictionary to List conversion ~
510
Bram Moolenaar58b85342016-08-14 19:54:54 +0200511You may want to loop over the entries in a dictionary. For this you need to
Bram Moolenaard8b02732005-01-14 21:48:43 +0000512turn the Dictionary into a List and pass it to |:for|.
513
514Most often you want to loop over the keys, using the |keys()| function: >
515 :for key in keys(mydict)
516 : echo key . ': ' . mydict[key]
517 :endfor
518
519The List of keys is unsorted. You may want to sort them first: >
520 :for key in sort(keys(mydict))
521
522To loop over the values use the |values()| function: >
523 :for v in values(mydict)
524 : echo "value: " . v
525 :endfor
526
527If you want both the key and the value use the |items()| function. It returns
Bram Moolenaard47d5222018-12-09 20:43:55 +0100528a List in which each item is a List with two items, the key and the value: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000529 :for [key, value] in items(mydict)
530 : echo key . ': ' . value
Bram Moolenaard8b02732005-01-14 21:48:43 +0000531 :endfor
532
533
534Dictionary identity ~
Bram Moolenaar7c626922005-02-07 22:01:03 +0000535 *dict-identity*
Bram Moolenaard8b02732005-01-14 21:48:43 +0000536Just like Lists you need to use |copy()| and |deepcopy()| to make a copy of a
537Dictionary. Otherwise, assignment results in referring to the same
538Dictionary: >
539 :let onedict = {'a': 1, 'b': 2}
540 :let adict = onedict
541 :let adict['a'] = 11
542 :echo onedict['a']
543 11
544
Bram Moolenaarf3bd51a2005-06-14 22:11:18 +0000545Two Dictionaries compare equal if all the key-value pairs compare equal. For
546more info see |list-identity|.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000547
548
549Dictionary modification ~
550 *dict-modification*
551To change an already existing entry of a Dictionary, or to add a new entry,
552use |:let| this way: >
553 :let dict[4] = "four"
554 :let dict['one'] = item
555
Bram Moolenaar9cd15162005-01-16 22:02:49 +0000556Removing an entry from a Dictionary is done with |remove()| or |:unlet|.
557Three ways to remove the entry with key "aaa" from dict: >
558 :let i = remove(dict, 'aaa')
559 :unlet dict.aaa
560 :unlet dict['aaa']
Bram Moolenaard8b02732005-01-14 21:48:43 +0000561
562Merging a Dictionary with another is done with |extend()|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000563 :call extend(adict, bdict)
564This extends adict with all entries from bdict. Duplicate keys cause entries
565in adict to be overwritten. An optional third argument can change this.
Bram Moolenaar383f9bc2005-01-19 22:18:32 +0000566Note that the order of entries in a Dictionary is irrelevant, thus don't
567expect ":echo adict" to show the items from bdict after the older entries in
568adict.
Bram Moolenaard8b02732005-01-14 21:48:43 +0000569
570Weeding out entries from a Dictionary can be done with |filter()|: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000571 :call filter(dict, 'v:val =~ "x"')
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000572This removes all entries from "dict" with a value not matching 'x'.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000573
574
575Dictionary function ~
Bram Moolenaar26402cb2013-02-20 21:26:00 +0100576 *Dictionary-function* *self* *E725* *E862*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000577When a function is defined with the "dict" attribute it can be used in a
Bram Moolenaar58b85342016-08-14 19:54:54 +0200578special way with a dictionary. Example: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000579 :function Mylen() dict
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000580 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000581 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000582 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
583 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000584
585This is like a method in object oriented programming. The entry in the
586Dictionary is a |Funcref|. The local variable "self" refers to the dictionary
587the function was invoked from.
588
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000589It is also possible to add a function without the "dict" attribute as a
590Funcref to a Dictionary, but the "self" variable is not available then.
591
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000592 *numbered-function* *anonymous-function*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000593To avoid the extra name for the function it can be defined and directly
594assigned to a Dictionary in this way: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000595 :let mydict = {'data': [0, 1, 2, 3]}
Bram Moolenaar5a5f4592015-04-13 12:43:06 +0200596 :function mydict.len()
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000597 : return len(self.data)
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000598 :endfunction
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000599 :echo mydict.len()
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000600
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000601The function will then get a number and the value of dict.len is a |Funcref|
Bram Moolenaar58b85342016-08-14 19:54:54 +0200602that references this function. The function can only be used through a
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000603|Funcref|. It will automatically be deleted when there is no |Funcref|
604remaining that refers to it.
605
606It is not necessary to use the "dict" attribute for a numbered function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000607
Bram Moolenaar1affd722010-08-04 17:49:30 +0200608If you get an error for a numbered function, you can find out what it is with
609a trick. Assuming the function is 42, the command is: >
610 :function {42}
611
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000612
613Functions for Dictionaries ~
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000614 *E715*
615Functions that can be used with a Dictionary: >
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000616 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
617 :if empty(dict) " TRUE if dict is empty
618 :let l = len(dict) " number of items in dict
619 :let big = max(dict) " maximum value in dict
620 :let small = min(dict) " minimum value in dict
621 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
622 :let s = string(dict) " String representation of dict
623 :call map(dict, '">> " . v:val') " prepend ">> " to each item
Bram Moolenaard8b02732005-01-14 21:48:43 +0000624
625
Bram Moolenaard8968242019-01-15 22:51:57 +01006261.5 Blobs ~
627 *blob* *Blob* *Blobs* *E978*
628A Blob mostly behaves like a |List| of numbers, where the numbers have an
6298-bit value, from 0 to 255.
630
631
632Blob creation ~
633
634A Blob can be created with a |blob-literal|: >
635 :let b = 0zFF00ED015DAF
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +0100636Dots can be inserted between bytes (pair of hex characters) for readability,
637they don't change the value: >
638 :let b = 0zFF00.ED01.5DAF
Bram Moolenaard8968242019-01-15 22:51:57 +0100639
640A blob can be read from a file with |readfile()| passing the {type} argument
641set to "B", for example: >
642 :let b = readfile('image.png', 'B')
643
644A blob can be read from a channel with the |ch_readblob()| function.
645
646
647Blob index ~
648 *blob-index* *E979*
649A byte in the Blob can be accessed by putting the index in square brackets
650after the Blob. Indexes are zero-based, thus the first byte has index zero. >
651 :let myblob = 0z00112233
652 :let byte = myblob[0] " get the first byte: 0x00
653 :let byte = myblob[2] " get the third byte: 0x22
654
655A negative index is counted from the end. Index -1 refers to the last byte in
656the Blob, -2 to the last but one byte, etc. >
657 :let last = myblob[-1] " get the last byte: 0x33
658
659To avoid an error for an invalid index use the |get()| function. When an item
660is not available it returns -1 or the default value you specify: >
661 :echo get(myblob, idx)
662 :echo get(myblob, idx, 999)
663
664
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100665Blob iteration ~
666
667The |:for| loop executes commands for each byte of a Blob. The loop variable is
668set to each byte in the Blob. Example: >
669 :for byte in 0z112233
670 : call Doit(byte)
671 :endfor
672This calls Doit() with 0x11, 0x22 and 0x33.
673
674
Bram Moolenaard8968242019-01-15 22:51:57 +0100675Blob concatenation ~
676
677Two blobs can be concatenated with the "+" operator: >
678 :let longblob = myblob + 0z4455
679 :let myblob += 0z6677
680
681To change a blob in-place see |blob-modification| below.
682
683
684Part of a blob ~
685
686A part of the Blob can be obtained by specifying the first and last index,
687separated by a colon in square brackets: >
688 :let myblob = 0z00112233
Bram Moolenaard09091d2019-01-17 16:07:22 +0100689 :let shortblob = myblob[1:2] " get 0z1122
Bram Moolenaard8968242019-01-15 22:51:57 +0100690 :let shortblob = myblob[2:-1] " get 0z2233
691
692Omitting the first index is similar to zero. Omitting the last index is
693similar to -1. >
694 :let endblob = myblob[2:] " from item 2 to the end: 0z2233
695 :let shortblob = myblob[2:2] " Blob with one byte: 0z22
696 :let otherblob = myblob[:] " make a copy of the Blob
697
Bram Moolenaard09091d2019-01-17 16:07:22 +0100698If the first index is beyond the last byte of the Blob or the second index is
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +0100699before the first index, the result is an empty Blob. There is no error
Bram Moolenaard8968242019-01-15 22:51:57 +0100700message.
701
702If the second index is equal to or greater than the length of the list the
703length minus one is used: >
704 :echo myblob[2:8] " result: 0z2233
705
706
707Blob modification ~
708 *blob-modification*
709To change a specific byte of a blob use |:let| this way: >
710 :let blob[4] = 0x44
711
712When the index is just one beyond the end of the Blob, it is appended. Any
713higher index is an error.
714
715To change a sequence of bytes the [:] notation can be used: >
716 let blob[1:3] = 0z445566
Bram Moolenaard09091d2019-01-17 16:07:22 +0100717The length of the replaced bytes must be exactly the same as the value
Bram Moolenaard8968242019-01-15 22:51:57 +0100718provided. *E972*
719
720To change part of a blob you can specify the first and last byte to be
Bram Moolenaard09091d2019-01-17 16:07:22 +0100721modified. The value must have the same number of bytes in the range: >
722 :let blob[3:5] = 0z334455
Bram Moolenaard8968242019-01-15 22:51:57 +0100723
724You can also use the functions |add()|, |remove()| and |insert()|.
725
726
727Blob identity ~
728
729Blobs can be compared for equality: >
730 if blob == 0z001122
731And for equal identity: >
732 if blob is otherblob
733< *blob-identity* *E977*
734When variable "aa" is a Blob and you assign it to another variable "bb", both
735variables refer to the same Blob. Then the "is" operator returns true.
736
737When making a copy using [:] or |copy()| the values are the same, but the
738identity is different: >
739 :let blob = 0z112233
740 :let blob2 = blob
741 :echo blob == blob2
742< 1 >
743 :echo blob is blob2
744< 1 >
745 :let blob3 = blob[:]
746 :echo blob == blob3
747< 1 >
748 :echo blob is blob3
749< 0
750
Bram Moolenaard09091d2019-01-17 16:07:22 +0100751Making a copy of a Blob is done with the |copy()| function. Using [:] also
Bram Moolenaard8968242019-01-15 22:51:57 +0100752works, as explained above.
753
754
7551.6 More about variables ~
Bram Moolenaar13065c42005-01-08 16:08:21 +0000756 *more-variables*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000757If you need to know the type of a variable or expression, use the |type()|
758function.
759
760When the '!' flag is included in the 'viminfo' option, global variables that
761start with an uppercase letter, and don't contain a lowercase letter, are
762stored in the viminfo file |viminfo-file|.
763
764When the 'sessionoptions' option contains "global", global variables that
765start with an uppercase letter and contain at least one lowercase letter are
766stored in the session file |session-file|.
767
768variable name can be stored where ~
769my_var_6 not
770My_Var_6 session file
771MY_VAR_6 viminfo file
772
773
774It's possible to form a variable name with curly braces, see
775|curly-braces-names|.
776
777==============================================================================
7782. Expression syntax *expression-syntax*
779
780Expression syntax summary, from least to most significant:
781
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200782|expr1| expr2
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200783 expr2 ? expr1 : expr1 if-then-else
Bram Moolenaar071d4272004-06-13 20:20:40 +0000784
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200785|expr2| expr3
786 expr3 || expr3 .. logical OR
Bram Moolenaar071d4272004-06-13 20:20:40 +0000787
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200788|expr3| expr4
789 expr4 && expr4 .. logical AND
Bram Moolenaar071d4272004-06-13 20:20:40 +0000790
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200791|expr4| expr5
792 expr5 == expr5 equal
Bram Moolenaar071d4272004-06-13 20:20:40 +0000793 expr5 != expr5 not equal
794 expr5 > expr5 greater than
795 expr5 >= expr5 greater than or equal
796 expr5 < expr5 smaller than
797 expr5 <= expr5 smaller than or equal
798 expr5 =~ expr5 regexp matches
799 expr5 !~ expr5 regexp doesn't match
800
801 expr5 ==? expr5 equal, ignoring case
802 expr5 ==# expr5 equal, match case
803 etc. As above, append ? for ignoring case, # for
804 matching case
805
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100806 expr5 is expr5 same |List|, |Dictionary| or |Blob| instance
807 expr5 isnot expr5 different |List|, |Dictionary| or |Blob|
808 instance
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000809
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200810|expr5| expr6
Bram Moolenaard09091d2019-01-17 16:07:22 +0100811 expr6 + expr6 .. number addition, list or blob concatenation
Bram Moolenaar071d4272004-06-13 20:20:40 +0000812 expr6 - expr6 .. number subtraction
813 expr6 . expr6 .. string concatenation
814
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200815|expr6| expr7
816 expr7 * expr7 .. number multiplication
Bram Moolenaar071d4272004-06-13 20:20:40 +0000817 expr7 / expr7 .. number division
818 expr7 % expr7 .. number modulo
819
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200820|expr7| expr8
821 ! expr7 logical NOT
Bram Moolenaar071d4272004-06-13 20:20:40 +0000822 - expr7 unary minus
823 + expr7 unary plus
Bram Moolenaar071d4272004-06-13 20:20:40 +0000824
Bram Moolenaar89bcfda2016-08-30 23:26:57 +0200825|expr8| expr9
826 expr8[expr1] byte of a String or item of a |List|
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000827 expr8[expr1 : expr1] substring of a String or sublist of a |List|
828 expr8.name entry in a |Dictionary|
829 expr8(expr1, ...) function call with |Funcref| variable
Bram Moolenaar2fda12f2005-01-15 22:14:15 +0000830
Bram Moolenaar50ba5262016-09-22 22:33:02 +0200831|expr9| number number constant
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000832 "string" string constant, backslash is special
Bram Moolenaard8b02732005-01-14 21:48:43 +0000833 'string' string constant, ' is doubled
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000834 [expr1, ...] |List|
835 {expr1: expr1, ...} |Dictionary|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000836 &option option value
837 (expr1) nested expression
838 variable internal variable
839 va{ria}ble internal variable with curly braces
840 $VAR environment variable
841 @r contents of register 'r'
842 function(expr1, ...) function call
843 func{ti}on(expr1, ...) function call with curly braces
Bram Moolenaar069c1e72016-07-15 21:25:08 +0200844 {args -> expr1} lambda expression
Bram Moolenaar071d4272004-06-13 20:20:40 +0000845
846
847".." indicates that the operations in this level can be concatenated.
848Example: >
849 &nu || &list && &shell == "csh"
850
851All expressions within one level are parsed from left to right.
852
853
854expr1 *expr1* *E109*
855-----
856
857expr2 ? expr1 : expr1
858
859The expression before the '?' is evaluated to a number. If it evaluates to
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200860|TRUE|, the result is the value of the expression between the '?' and ':',
Bram Moolenaar071d4272004-06-13 20:20:40 +0000861otherwise the result is the value of the expression after the ':'.
862Example: >
863 :echo lnum == 1 ? "top" : lnum
864
865Since the first expression is an "expr2", it cannot contain another ?:. The
866other two expressions can, thus allow for recursive use of ?:.
867Example: >
868 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
869
870To keep this readable, using |line-continuation| is suggested: >
871 :echo lnum == 1
872 :\ ? "top"
873 :\ : lnum == 1000
874 :\ ? "last"
875 :\ : lnum
876
Bram Moolenaaref2f6562007-05-06 13:32:59 +0000877You should always put a space before the ':', otherwise it can be mistaken for
878use in a variable such as "a:1".
879
Bram Moolenaar071d4272004-06-13 20:20:40 +0000880
881expr2 and expr3 *expr2* *expr3*
882---------------
883
Bram Moolenaar04186092016-08-29 21:55:35 +0200884expr3 || expr3 .. logical OR *expr-barbar*
885expr4 && expr4 .. logical AND *expr-&&*
886
Bram Moolenaar071d4272004-06-13 20:20:40 +0000887The "||" and "&&" operators take one argument on each side. The arguments
888are (converted to) Numbers. The result is:
889
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200890 input output ~
891n1 n2 n1 || n2 n1 && n2 ~
892|FALSE| |FALSE| |FALSE| |FALSE|
893|FALSE| |TRUE| |TRUE| |FALSE|
894|TRUE| |FALSE| |TRUE| |FALSE|
895|TRUE| |TRUE| |TRUE| |TRUE|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000896
897The operators can be concatenated, for example: >
898
899 &nu || &list && &shell == "csh"
900
901Note that "&&" takes precedence over "||", so this has the meaning of: >
902
903 &nu || (&list && &shell == "csh")
904
905Once the result is known, the expression "short-circuits", that is, further
906arguments are not evaluated. This is like what happens in C. For example: >
907
908 let a = 1
909 echo a || b
910
Bram Moolenaare381d3d2016-07-07 14:50:41 +0200911This is valid even if there is no variable called "b" because "a" is |TRUE|,
912so the result must be |TRUE|. Similarly below: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000913
914 echo exists("b") && b == "yes"
915
916This is valid whether "b" has been defined or not. The second clause will
917only be evaluated if "b" has been defined.
918
919
920expr4 *expr4*
921-----
922
923expr5 {cmp} expr5
924
925Compare two expr5 expressions, resulting in a 0 if it evaluates to false, or 1
926if it evaluates to true.
927
Bram Moolenaar446cb832008-06-24 21:56:24 +0000928 *expr-==* *expr-!=* *expr->* *expr->=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000929 *expr-<* *expr-<=* *expr-=~* *expr-!~*
930 *expr-==#* *expr-!=#* *expr->#* *expr->=#*
931 *expr-<#* *expr-<=#* *expr-=~#* *expr-!~#*
932 *expr-==?* *expr-!=?* *expr->?* *expr->=?*
933 *expr-<?* *expr-<=?* *expr-=~?* *expr-!~?*
Bram Moolenaar251e1912011-06-19 05:09:16 +0200934 *expr-is* *expr-isnot* *expr-is#* *expr-isnot#*
935 *expr-is?* *expr-isnot?*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000936 use 'ignorecase' match case ignore case ~
937equal == ==# ==?
938not equal != !=# !=?
939greater than > ># >?
940greater than or equal >= >=# >=?
941smaller than < <# <?
942smaller than or equal <= <=# <=?
943regexp matches =~ =~# =~?
944regexp doesn't match !~ !~# !~?
Bram Moolenaar251e1912011-06-19 05:09:16 +0200945same instance is is# is?
946different instance isnot isnot# isnot?
Bram Moolenaar071d4272004-06-13 20:20:40 +0000947
948Examples:
949"abc" ==# "Abc" evaluates to 0
950"abc" ==? "Abc" evaluates to 1
951"abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
952
Bram Moolenaar13065c42005-01-08 16:08:21 +0000953 *E691* *E692*
Bram Moolenaar01164a62017-11-02 22:58:42 +0100954A |List| can only be compared with a |List| and only "equal", "not equal",
955"is" and "isnot" can be used. This compares the values of the list,
956recursively. Ignoring case means case is ignored when comparing item values.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000957
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000958 *E735* *E736*
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000959A |Dictionary| can only be compared with a |Dictionary| and only "equal", "not
Bram Moolenaar01164a62017-11-02 22:58:42 +0100960equal", "is" and "isnot" can be used. This compares the key/values of the
961|Dictionary| recursively. Ignoring case means case is ignored when comparing
962item values.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +0000963
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200964 *E694*
Bram Moolenaare18dbe82016-07-02 21:42:23 +0200965A |Funcref| can only be compared with a |Funcref| and only "equal", "not
966equal", "is" and "isnot" can be used. Case is never ignored. Whether
967arguments or a Dictionary are bound (with a partial) matters. The
968Dictionaries must also be equal (or the same, in case of "is") and the
969arguments must be equal (or the same).
970
971To compare Funcrefs to see if they refer to the same function, ignoring bound
972Dictionary and arguments, use |get()| to get the function name: >
973 if get(Part1, 'name') == get(Part2, 'name')
974 " Part1 and Part2 refer to the same function
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000975
Bram Moolenaar5e66b422019-01-24 21:58:10 +0100976Using "is" or "isnot" with a |List|, |Dictionary| or |Blob| checks whether
977the expressions are referring to the same |List|, |Dictionary| or |Blob|
978instance. A copy of a |List| is different from the original |List|. When
979using "is" without a |List|, |Dictionary| or |Blob|, it is equivalent to
980using "equal", using "isnot" equivalent to using "not equal". Except that
981a different type means the values are different: >
Bram Moolenaar86edef62016-03-13 18:07:30 +0100982 echo 4 == '4'
983 1
984 echo 4 is '4'
985 0
986 echo 0 is []
987 0
988"is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
Bram Moolenaarde8866b2005-01-06 23:24:37 +0000989
Bram Moolenaar071d4272004-06-13 20:20:40 +0000990When comparing a String with a Number, the String is converted to a Number,
Bram Moolenaar58b85342016-08-14 19:54:54 +0200991and the comparison is done on Numbers. This means that: >
Bram Moolenaar86edef62016-03-13 18:07:30 +0100992 echo 0 == 'x'
993 1
994because 'x' converted to a Number is zero. However: >
995 echo [0] == ['x']
996 0
997Inside a List or Dictionary this conversion is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000998
999When comparing two Strings, this is done with strcmp() or stricmp(). This
1000results in the mathematical difference (comparing byte values), not
1001necessarily the alphabetical difference in the local language.
1002
Bram Moolenaar446cb832008-06-24 21:56:24 +00001003When using the operators with a trailing '#', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001004'ignorecase' is off, the comparing is done with strcmp(): case matters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001005
1006When using the operators with a trailing '?', or the short version and
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001007'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
1008
1009'smartcase' is not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001010
1011The "=~" and "!~" operators match the lefthand argument with the righthand
1012argument, which is used as a pattern. See |pattern| for what a pattern is.
1013This matching is always done like 'magic' was set and 'cpoptions' is empty, no
1014matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
1015portable. To avoid backslashes in the regexp pattern to be doubled, use a
1016single-quote string, see |literal-string|.
1017Since a string is considered to be a single line, a multi-line pattern
1018(containing \n, backslash-n) will not match. However, a literal NL character
1019can be matched like an ordinary character. Examples:
1020 "foo\nbar" =~ "\n" evaluates to 1
1021 "foo\nbar" =~ "\\n" evaluates to 0
1022
1023
1024expr5 and expr6 *expr5* *expr6*
1025---------------
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001026expr6 + expr6 Number addition, |List| or |Blob| concatenation *expr-+*
1027expr6 - expr6 Number subtraction *expr--*
1028expr6 . expr6 String concatenation *expr-.*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001029
Bram Moolenaara23ccb82006-02-27 00:08:02 +00001030For |Lists| only "+" is possible and then both expr6 must be a list. The
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001031result is a new list with the two lists Concatenated.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001032
Bram Moolenaar5e66b422019-01-24 21:58:10 +01001033expr7 * expr7 Number multiplication *expr-star*
1034expr7 / expr7 Number division *expr-/*
1035expr7 % expr7 Number modulo *expr-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001036
1037For all, except ".", Strings are converted to Numbers.
Bram Moolenaard6e256c2011-12-14 15:32:50 +01001038For bitwise operators see |and()|, |or()| and |xor()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001039
1040Note the difference between "+" and ".":
1041 "123" + "456" = 579
1042 "123" . "456" = "123456"
1043
Bram Moolenaar446cb832008-06-24 21:56:24 +00001044Since '.' has the same precedence as '+' and '-', you need to read: >
1045 1 . 90 + 90.0
1046As: >
1047 (1 . 90) + 90.0
1048That works, since the String "190" is automatically converted to the Number
1049190, which can be added to the Float 90.0. However: >
1050 1 . 90 * 90.0
1051Should be read as: >
1052 1 . (90 * 90.0)
1053Since '.' has lower precedence than '*'. This does NOT work, since this
1054attempts to concatenate a Float and a String.
1055
1056When dividing a Number by zero the result depends on the value:
1057 0 / 0 = -0x80000000 (like NaN for Float)
1058 >0 / 0 = 0x7fffffff (like positive infinity)
1059 <0 / 0 = -0x7fffffff (like negative infinity)
1060 (before Vim 7.2 it was always 0x7fffffff)
1061
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02001062When 64-bit Number support is enabled:
1063 0 / 0 = -0x8000000000000000 (like NaN for Float)
1064 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
1065 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
1066
Bram Moolenaar071d4272004-06-13 20:20:40 +00001067When the righthand side of '%' is zero, the result is 0.
1068
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001069None of these work for |Funcref|s.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00001070
Bram Moolenaar446cb832008-06-24 21:56:24 +00001071. and % do not work for Float. *E804*
1072
Bram Moolenaar071d4272004-06-13 20:20:40 +00001073
1074expr7 *expr7*
1075-----
1076! expr7 logical NOT *expr-!*
1077- expr7 unary minus *expr-unary--*
1078+ expr7 unary plus *expr-unary-+*
1079
Bram Moolenaare381d3d2016-07-07 14:50:41 +02001080For '!' |TRUE| becomes |FALSE|, |FALSE| becomes |TRUE| (one).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001081For '-' the sign of the number is changed.
1082For '+' the number is unchanged.
1083
1084A String will be converted to a Number first.
1085
Bram Moolenaar58b85342016-08-14 19:54:54 +02001086These three can be repeated and mixed. Examples:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001087 !-1 == 0
1088 !!8 == 1
1089 --9 == 9
1090
1091
1092expr8 *expr8*
1093-----
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001094This expression is either |expr9| or a sequence of the alternatives below,
1095in any order. E.g., these are all possible:
1096 expr9[expr1].name
1097 expr9.name[expr1]
1098 expr9(expr1, ...)[expr1].name
1099
1100
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001101expr8[expr1] item of String or |List| *expr-[]* *E111*
Bram Moolenaar03413f42016-04-12 21:07:15 +02001102 *E909* *subscript*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001103If expr8 is a Number or String this results in a String that contains the
1104expr1'th single byte from expr8. expr8 is used as a String, expr1 as a
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001105Number. This doesn't recognize multi-byte encodings, see `byteidx()` for
Bram Moolenaar03413f42016-04-12 21:07:15 +02001106an alternative, or use `split()` to turn the string into a list of characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001107
Bram Moolenaar256972a2015-12-29 19:10:25 +01001108Index zero gives the first byte. This is like it works in C. Careful:
1109text column numbers start with one! Example, to get the byte under the
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001110cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00001111 :let c = getline(".")[col(".") - 1]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001112
1113If the length of the String is less than the index, the result is an empty
Bram Moolenaar85084ef2016-01-17 22:26:33 +01001114String. A negative index always results in an empty string (reason: backward
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001115compatibility). Use [-1:] to get the last byte.
1116
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001117If expr8 is a |List| then it results the item at index expr1. See |list-index|
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001118for possible index values. If the index is out of range this results in an
Bram Moolenaar58b85342016-08-14 19:54:54 +02001119error. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001120 :let item = mylist[-1] " get last item
1121
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001122Generally, if a |List| index is equal to or higher than the length of the
1123|List|, or more negative than the length of the |List|, this results in an
1124error.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001125
Bram Moolenaard8b02732005-01-14 21:48:43 +00001126
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001127expr8[expr1a : expr1b] substring or sublist *expr-[:]*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001128
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001129If expr8 is a Number or String this results in the substring with the bytes
1130from expr1a to and including expr1b. expr8 is used as a String, expr1a and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001131expr1b are used as a Number. This doesn't recognize multi-byte encodings, see
1132|byteidx()| for computing the indexes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001133
1134If expr1a is omitted zero is used. If expr1b is omitted the length of the
1135string minus one is used.
1136
1137A negative number can be used to measure from the end of the string. -1 is
1138the last character, -2 the last but one, etc.
1139
1140If an index goes out of range for the string characters are omitted. If
1141expr1b is smaller than expr1a the result is an empty string.
1142
1143Examples: >
1144 :let c = name[-1:] " last byte of a string
1145 :let c = name[-2:-2] " last but one byte of a string
1146 :let s = line(".")[4:] " from the fifth byte to the end
1147 :let s = s[:-3] " remove last two bytes
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001148<
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001149 *slice*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001150If expr8 is a |List| this results in a new |List| with the items indicated by
Bram Moolenaar58b85342016-08-14 19:54:54 +02001151the indexes expr1a and expr1b. This works like with a String, as explained
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001152just above. Also see |sublist| below. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00001153 :let l = mylist[:3] " first four items
1154 :let l = mylist[4:4] " List with one item
1155 :let l = mylist[:] " shallow copy of a List
1156
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001157If expr8 is a |Blob| this results in a new |Blob| with the bytes in the
1158indexes expr1a and expr1b, inclusive. Examples: >
1159 :let b = 0zDEADBEEF
1160 :let bs = b[1:2] " 0zADBE
Bram Moolenaard09091d2019-01-17 16:07:22 +01001161 :let bs = b[:] " copy of 0zDEADBEEF
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001162
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001163Using expr8[expr1] or expr8[expr1a : expr1b] on a |Funcref| results in an
1164error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001165
Bram Moolenaarda440d22016-01-16 21:27:23 +01001166Watch out for confusion between a namespace and a variable followed by a colon
1167for a sublist: >
1168 mylist[n:] " uses variable n
1169 mylist[s:] " uses namespace s:, error!
1170
Bram Moolenaard8b02732005-01-14 21:48:43 +00001171
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001172expr8.name entry in a |Dictionary| *expr-entry*
Bram Moolenaard8b02732005-01-14 21:48:43 +00001173
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001174If expr8 is a |Dictionary| and it is followed by a dot, then the following
1175name will be used as a key in the |Dictionary|. This is just like:
1176expr8[name].
Bram Moolenaard8b02732005-01-14 21:48:43 +00001177
1178The name must consist of alphanumeric characters, just like a variable name,
1179but it may start with a number. Curly braces cannot be used.
1180
1181There must not be white space before or after the dot.
1182
1183Examples: >
1184 :let dict = {"one": 1, 2: "two"}
1185 :echo dict.one
1186 :echo dict .2
1187
1188Note that the dot is also used for String concatenation. To avoid confusion
1189always put spaces around the dot for String concatenation.
1190
1191
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001192expr8(expr1, ...) |Funcref| function call
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001193
1194When expr8 is a |Funcref| type variable, invoke the function it refers to.
1195
1196
1197
1198 *expr9*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001199number
1200------
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001201number number constant *expr-number*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001202 *hex-number* *octal-number* *binary-number*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001203
Bram Moolenaar7571d552016-08-18 22:54:46 +02001204Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
1205and Octal (starting with 0).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001206
Bram Moolenaar446cb832008-06-24 21:56:24 +00001207 *floating-point-format*
1208Floating point numbers can be written in two forms:
1209
1210 [-+]{N}.{M}
Bram Moolenaar8a94d872015-01-25 13:02:57 +01001211 [-+]{N}.{M}[eE][-+]{exp}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001212
1213{N} and {M} are numbers. Both {N} and {M} must be present and can only
1214contain digits.
1215[-+] means there is an optional plus or minus sign.
1216{exp} is the exponent, power of 10.
Bram Moolenaar58b85342016-08-14 19:54:54 +02001217Only a decimal point is accepted, not a comma. No matter what the current
Bram Moolenaar446cb832008-06-24 21:56:24 +00001218locale is.
1219{only when compiled with the |+float| feature}
1220
1221Examples:
1222 123.456
1223 +0.0001
1224 55.0
1225 -0.123
1226 1.234e03
1227 1.0E-6
1228 -3.1416e+88
1229
1230These are INVALID:
1231 3. empty {M}
1232 1e40 missing .{M}
1233
1234Rationale:
1235Before floating point was introduced, the text "123.456" was interpreted as
1236the two numbers "123" and "456", both converted to a string and concatenated,
1237resulting in the string "123456". Since this was considered pointless, and we
Bram Moolenaare37d50a2008-08-06 17:06:04 +00001238could not find it intentionally being used in Vim scripts, this backwards
Bram Moolenaar446cb832008-06-24 21:56:24 +00001239incompatibility was accepted in favor of being able to use the normal notation
1240for floating point numbers.
1241
Bram Moolenaard47d5222018-12-09 20:43:55 +01001242 *float-pi* *float-e*
1243A few useful values to copy&paste: >
1244 :let pi = 3.14159265359
1245 :let e = 2.71828182846
1246Or, if you don't want to write them in as floating-point literals, you can
1247also use functions, like the following: >
1248 :let pi = acos(-1.0)
1249 :let e = exp(1.0)
Bram Moolenaar98aefe72018-12-13 22:20:09 +01001250<
Bram Moolenaar446cb832008-06-24 21:56:24 +00001251 *floating-point-precision*
1252The precision and range of floating points numbers depends on what "double"
1253means in the library Vim was compiled with. There is no way to change this at
1254runtime.
1255
1256The default for displaying a |Float| is to use 6 decimal places, like using
1257printf("%g", f). You can select something else when using the |printf()|
1258function. Example: >
1259 :echo printf('%.15e', atan(1))
1260< 7.853981633974483e-01
1261
1262
Bram Moolenaar071d4272004-06-13 20:20:40 +00001263
Bram Moolenaar979243b2015-06-26 19:35:49 +02001264string *string* *String* *expr-string* *E114*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001265------
1266"string" string constant *expr-quote*
1267
1268Note that double quotes are used.
1269
1270A string constant accepts these special characters:
1271\... three-digit octal number (e.g., "\316")
1272\.. two-digit octal number (must be followed by non-digit)
1273\. one-digit octal number (must be followed by non-digit)
1274\x.. byte specified with two hex numbers (e.g., "\x1f")
1275\x. byte specified with one hex number (must be followed by non-hex char)
1276\X.. same as \x..
1277\X. same as \x.
Bram Moolenaar446cb832008-06-24 21:56:24 +00001278\u.... character specified with up to 4 hex numbers, stored according to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001279 current value of 'encoding' (e.g., "\u02a4")
Bram Moolenaar541f92d2015-06-19 13:27:23 +02001280\U.... same as \u but allows up to 8 hex numbers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001281\b backspace <BS>
1282\e escape <Esc>
1283\f formfeed <FF>
1284\n newline <NL>
1285\r return <CR>
1286\t tab <Tab>
1287\\ backslash
1288\" double quote
Bram Moolenaar00a927d2010-05-14 23:24:24 +02001289\<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
Bram Moolenaar58b85342016-08-14 19:54:54 +02001290 in mappings, the 0x80 byte is escaped.
1291 To use the double quote character it must be escaped: "<M-\">".
1292 Don't use <Char-xxxx> to get a utf-8 character, use \uxxxx as
1293 mentioned above.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001294
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001295Note that "\xff" is stored as the byte 255, which may be invalid in some
1296encodings. Use "\u00ff" to store character 255 according to the current value
1297of 'encoding'.
1298
Bram Moolenaar071d4272004-06-13 20:20:40 +00001299Note that "\000" and "\x00" force the end of the string.
1300
1301
Bram Moolenaard8968242019-01-15 22:51:57 +01001302blob-literal *blob-literal* *E973*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01001303------------
1304
1305Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
1306The sequence must be an even number of hex characters. Example: >
1307 :let b = 0zFF00ED015DAF
1308
1309
Bram Moolenaar071d4272004-06-13 20:20:40 +00001310literal-string *literal-string* *E115*
1311---------------
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001312'string' string constant *expr-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001313
1314Note that single quotes are used.
1315
Bram Moolenaar58b85342016-08-14 19:54:54 +02001316This string is taken as it is. No backslashes are removed or have a special
Bram Moolenaard8b02732005-01-14 21:48:43 +00001317meaning. The only exception is that two quotes stand for one quote.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001318
1319Single quoted strings are useful for patterns, so that backslashes do not need
Bram Moolenaar58b85342016-08-14 19:54:54 +02001320to be doubled. These two commands are equivalent: >
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001321 if a =~ "\\s*"
1322 if a =~ '\s*'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001323
1324
1325option *expr-option* *E112* *E113*
1326------
1327&option option value, local value if possible
1328&g:option global option value
1329&l:option local option value
1330
1331Examples: >
1332 echo "tabstop is " . &tabstop
1333 if &insertmode
1334
1335Any option name can be used here. See |options|. When using the local value
1336and there is no buffer-local or window-local value, the global value is used
1337anyway.
1338
1339
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001340register *expr-register* *@r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001341--------
1342@r contents of register 'r'
1343
1344The result is the contents of the named register, as a single string.
1345Newlines are inserted where required. To get the contents of the unnamed
Bram Moolenaar58b85342016-08-14 19:54:54 +02001346register use @" or @@. See |registers| for an explanation of the available
Bram Moolenaare7566042005-06-17 22:00:15 +00001347registers.
1348
1349When using the '=' register you get the expression itself, not what it
1350evaluates to. Use |eval()| to evaluate it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001351
1352
1353nesting *expr-nesting* *E110*
1354-------
1355(expr1) nested expression
1356
1357
1358environment variable *expr-env*
1359--------------------
1360$VAR environment variable
1361
1362The String value of any environment variable. When it is not defined, the
1363result is an empty string.
1364 *expr-env-expand*
1365Note that there is a difference between using $VAR directly and using
1366expand("$VAR"). Using it directly will only expand environment variables that
1367are known inside the current Vim session. Using expand() will first try using
1368the environment variables known inside the current Vim session. If that
1369fails, a shell will be used to expand the variable. This can be slow, but it
1370does expand all variables that the shell knows about. Example: >
Bram Moolenaar34401cc2014-08-29 15:12:19 +02001371 :echo $shell
1372 :echo expand("$shell")
1373The first one probably doesn't echo anything, the second echoes the $shell
Bram Moolenaar071d4272004-06-13 20:20:40 +00001374variable (if your shell supports it).
1375
1376
1377internal variable *expr-variable*
1378-----------------
1379variable internal variable
1380See below |internal-variables|.
1381
1382
Bram Moolenaar05159a02005-02-26 23:04:13 +00001383function call *expr-function* *E116* *E118* *E119* *E120*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001384-------------
1385function(expr1, ...) function call
1386See below |functions|.
1387
1388
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001389lambda expression *expr-lambda* *lambda*
1390-----------------
1391{args -> expr1} lambda expression
1392
1393A lambda expression creates a new unnamed function which returns the result of
Bram Moolenaar42ebd062016-07-17 13:35:14 +02001394evaluating |expr1|. Lambda expressions differ from |user-functions| in
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001395the following ways:
1396
13971. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
1398 commands.
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +020013992. The prefix "a:" should not be used for arguments. E.g.: >
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001400 :let F = {arg1, arg2 -> arg1 - arg2}
1401 :echo F(5, 2)
1402< 3
1403
1404The arguments are optional. Example: >
1405 :let F = {-> 'error function'}
1406 :echo F()
1407< error function
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001408 *closure*
1409Lambda expressions can access outer scope variables and arguments. This is
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001410often called a closure. Example where "i" and "a:arg" are used in a lambda
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001411while they already exist in the function scope. They remain valid even after
1412the function returns: >
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001413 :function Foo(arg)
1414 : let i = 3
1415 : return {x -> x + i - a:arg}
1416 :endfunction
1417 :let Bar = Foo(4)
1418 :echo Bar(6)
1419< 5
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001420
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01001421Note that the variables must exist in the outer scope before the lamba is
1422defined for this to work. See also |:func-closure|.
1423
1424Lambda and closure support can be checked with: >
Bram Moolenaar437bafe2016-08-01 15:40:54 +02001425 if has('lambda')
Bram Moolenaar069c1e72016-07-15 21:25:08 +02001426
1427Examples for using a lambda expression with |sort()|, |map()| and |filter()|: >
1428 :echo map([1, 2, 3], {idx, val -> val + 1})
1429< [2, 3, 4] >
1430 :echo sort([3,7,2,1,4], {a, b -> a - b})
1431< [1, 2, 3, 4, 7]
1432
1433The lambda expression is also useful for Channel, Job and timer: >
1434 :let timer = timer_start(500,
1435 \ {-> execute("echo 'Handler called'", "")},
1436 \ {'repeat': 3})
1437< Handler called
1438 Handler called
1439 Handler called
1440
1441Note how execute() is used to execute an Ex command. That's ugly though.
1442
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02001443
1444Lambda expressions have internal names like '<lambda>42'. If you get an error
1445for a lambda expression, you can find what it is with the following command: >
1446 :function {'<lambda>42'}
1447See also: |numbered-function|
1448
Bram Moolenaar071d4272004-06-13 20:20:40 +00001449==============================================================================
Bram Moolenaar4a748032010-09-30 21:47:56 +020014503. Internal variable *internal-variables* *E461*
1451
Bram Moolenaar071d4272004-06-13 20:20:40 +00001452An internal variable name can be made up of letters, digits and '_'. But it
1453cannot start with a digit. It's also possible to use curly braces, see
1454|curly-braces-names|.
1455
1456An internal variable is created with the ":let" command |:let|.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00001457An internal variable is explicitly destroyed with the ":unlet" command
1458|:unlet|.
1459Using a name that is not an internal variable or refers to a variable that has
1460been destroyed results in an error.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001461
1462There are several name spaces for variables. Which one is to be used is
1463specified by what is prepended:
1464
1465 (nothing) In a function: local to a function; otherwise: global
1466|buffer-variable| b: Local to the current buffer.
1467|window-variable| w: Local to the current window.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001468|tabpage-variable| t: Local to the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001469|global-variable| g: Global.
1470|local-variable| l: Local to a function.
1471|script-variable| s: Local to a |:source|'ed Vim script.
1472|function-argument| a: Function argument (only inside a function).
Bram Moolenaar75b81562014-04-06 14:09:13 +02001473|vim-variable| v: Global, predefined by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001474
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001475The scope name by itself can be used as a |Dictionary|. For example, to
1476delete all script-local variables: >
Bram Moolenaar8f999f12005-01-25 22:12:55 +00001477 :for k in keys(s:)
1478 : unlet s:[k]
1479 :endfor
1480<
Bram Moolenaar531da592013-05-06 05:58:55 +02001481 *buffer-variable* *b:var* *b:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001482A variable name that is preceded with "b:" is local to the current buffer.
1483Thus you can have several "b:foo" variables, one for each buffer.
1484This kind of variable is deleted when the buffer is wiped out or deleted with
1485|:bdelete|.
1486
1487One local buffer variable is predefined:
Bram Moolenaarbf884932013-04-05 22:26:15 +02001488 *b:changedtick* *changetick*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001489b:changedtick The total number of changes to the current buffer. It is
1490 incremented for each change. An undo command is also a change
1491 in this case. This can be used to perform an action only when
1492 the buffer has changed. Example: >
1493 :if my_changedtick != b:changedtick
Bram Moolenaar446cb832008-06-24 21:56:24 +00001494 : let my_changedtick = b:changedtick
1495 : call My_Update()
Bram Moolenaar071d4272004-06-13 20:20:40 +00001496 :endif
Bram Moolenaar3df01732017-02-17 22:47:16 +01001497< You cannot change or delete the b:changedtick variable.
1498
Bram Moolenaar531da592013-05-06 05:58:55 +02001499 *window-variable* *w:var* *w:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001500A variable name that is preceded with "w:" is local to the current window. It
1501is deleted when the window is closed.
1502
Bram Moolenaarad3b3662013-05-17 18:14:19 +02001503 *tabpage-variable* *t:var* *t:*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001504A variable name that is preceded with "t:" is local to the current tab page,
1505It is deleted when the tab page is closed. {not available when compiled
Bram Moolenaardb84e452010-08-15 13:50:43 +02001506without the |+windows| feature}
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001507
Bram Moolenaar531da592013-05-06 05:58:55 +02001508 *global-variable* *g:var* *g:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001509Inside functions global variables are accessed with "g:". Omitting this will
Bram Moolenaar58b85342016-08-14 19:54:54 +02001510access a variable local to a function. But "g:" can also be used in any other
Bram Moolenaar071d4272004-06-13 20:20:40 +00001511place if you like.
1512
Bram Moolenaar531da592013-05-06 05:58:55 +02001513 *local-variable* *l:var* *l:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001514Inside functions local variables are accessed without prepending anything.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001515But you can also prepend "l:" if you like. However, without prepending "l:"
1516you may run into reserved variable names. For example "count". By itself it
1517refers to "v:count". Using "l:count" you can have a local variable with the
1518same name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001519
1520 *script-variable* *s:var*
1521In a Vim script variables starting with "s:" can be used. They cannot be
1522accessed from outside of the scripts, thus are local to the script.
1523
1524They can be used in:
1525- commands executed while the script is sourced
1526- functions defined in the script
1527- autocommands defined in the script
1528- functions and autocommands defined in functions and autocommands which were
1529 defined in the script (recursively)
1530- user defined commands defined in the script
1531Thus not in:
1532- other scripts sourced from this one
1533- mappings
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001534- menus
Bram Moolenaar071d4272004-06-13 20:20:40 +00001535- etc.
1536
Bram Moolenaaref2f6562007-05-06 13:32:59 +00001537Script variables can be used to avoid conflicts with global variable names.
1538Take this example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001539
1540 let s:counter = 0
1541 function MyCounter()
1542 let s:counter = s:counter + 1
1543 echo s:counter
1544 endfunction
1545 command Tick call MyCounter()
1546
1547You can now invoke "Tick" from any script, and the "s:counter" variable in
1548that script will not be changed, only the "s:counter" in the script where
1549"Tick" was defined is used.
1550
1551Another example that does the same: >
1552
1553 let s:counter = 0
1554 command Tick let s:counter = s:counter + 1 | echo s:counter
1555
1556When calling a function and invoking a user-defined command, the context for
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001557script variables is set to the script where the function or command was
Bram Moolenaar071d4272004-06-13 20:20:40 +00001558defined.
1559
1560The script variables are also available when a function is defined inside a
1561function that is defined in a script. Example: >
1562
1563 let s:counter = 0
1564 function StartCounting(incr)
1565 if a:incr
1566 function MyCounter()
1567 let s:counter = s:counter + 1
1568 endfunction
1569 else
1570 function MyCounter()
1571 let s:counter = s:counter - 1
1572 endfunction
1573 endif
1574 endfunction
1575
1576This defines the MyCounter() function either for counting up or counting down
1577when calling StartCounting(). It doesn't matter from where StartCounting() is
1578called, the s:counter variable will be accessible in MyCounter().
1579
1580When the same script is sourced again it will use the same script variables.
1581They will remain valid as long as Vim is running. This can be used to
1582maintain a counter: >
1583
1584 if !exists("s:counter")
1585 let s:counter = 1
1586 echo "script executed for the first time"
1587 else
1588 let s:counter = s:counter + 1
1589 echo "script executed " . s:counter . " times now"
1590 endif
1591
1592Note that this means that filetype plugins don't get a different set of script
1593variables for each buffer. Use local buffer variables instead |b:var|.
1594
1595
Bram Moolenaard47d5222018-12-09 20:43:55 +01001596PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:*
1597 *E963*
1598Some variables can be set by the user, but the type cannot be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001599
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001600 *v:beval_col* *beval_col-variable*
1601v:beval_col The number of the column, over which the mouse pointer is.
1602 This is the byte index in the |v:beval_lnum| line.
1603 Only valid while evaluating the 'balloonexpr' option.
1604
1605 *v:beval_bufnr* *beval_bufnr-variable*
1606v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
1607 valid while evaluating the 'balloonexpr' option.
1608
1609 *v:beval_lnum* *beval_lnum-variable*
1610v:beval_lnum The number of the line, over which the mouse pointer is. Only
1611 valid while evaluating the 'balloonexpr' option.
1612
1613 *v:beval_text* *beval_text-variable*
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00001614v:beval_text The text under or after the mouse pointer. Usually a word as
1615 it is useful for debugging a C program. 'iskeyword' applies,
1616 but a dot and "->" before the position is included. When on a
1617 ']' the text before it is used, including the matching '[' and
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001618 word before it. When on a Visual area within one line the
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02001619 highlighted text is used. Also see |<cexpr>|.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001620 Only valid while evaluating the 'balloonexpr' option.
1621
1622 *v:beval_winnr* *beval_winnr-variable*
1623v:beval_winnr The number of the window, over which the mouse pointer is. Only
Bram Moolenaar00654022011-02-25 14:42:19 +01001624 valid while evaluating the 'balloonexpr' option. The first
1625 window has number zero (unlike most other places where a
1626 window gets a number).
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001627
Bram Moolenaar511972d2016-06-04 18:09:59 +02001628 *v:beval_winid* *beval_winid-variable*
Bram Moolenaar7571d552016-08-18 22:54:46 +02001629v:beval_winid The |window-ID| of the window, over which the mouse pointer
1630 is. Otherwise like v:beval_winnr.
Bram Moolenaar511972d2016-06-04 18:09:59 +02001631
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001632 *v:char* *char-variable*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001633v:char Argument for evaluating 'formatexpr' and used for the typed
Bram Moolenaar945e2db2010-06-05 17:43:32 +02001634 character when using <expr> in an abbreviation |:map-<expr>|.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02001635 It is also used by the |InsertCharPre| and |InsertEnter| events.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00001636
Bram Moolenaar071d4272004-06-13 20:20:40 +00001637 *v:charconvert_from* *charconvert_from-variable*
1638v:charconvert_from
1639 The name of the character encoding of a file to be converted.
1640 Only valid while evaluating the 'charconvert' option.
1641
1642 *v:charconvert_to* *charconvert_to-variable*
1643v:charconvert_to
1644 The name of the character encoding of a file after conversion.
1645 Only valid while evaluating the 'charconvert' option.
1646
1647 *v:cmdarg* *cmdarg-variable*
1648v:cmdarg This variable is used for two purposes:
1649 1. The extra arguments given to a file read/write command.
1650 Currently these are "++enc=" and "++ff=". This variable is
1651 set before an autocommand event for a file read/write
1652 command is triggered. There is a leading space to make it
1653 possible to append this variable directly after the
Bram Moolenaar58b85342016-08-14 19:54:54 +02001654 read/write command. Note: The "+cmd" argument isn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001655 included here, because it will be executed anyway.
1656 2. When printing a PostScript file with ":hardcopy" this is
1657 the argument for the ":hardcopy" command. This can be used
1658 in 'printexpr'.
1659
1660 *v:cmdbang* *cmdbang-variable*
1661v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
1662 was used the value is 1, otherwise it is 0. Note that this
1663 can only be used in autocommands. For user commands |<bang>|
1664 can be used.
1665
Bram Moolenaar42a45122015-07-10 17:56:23 +02001666 *v:completed_item* *completed_item-variable*
1667v:completed_item
1668 |Dictionary| containing the |complete-items| for the most
1669 recently completed word after |CompleteDone|. The
1670 |Dictionary| is empty if the completion failed.
1671
Bram Moolenaar071d4272004-06-13 20:20:40 +00001672 *v:count* *count-variable*
1673v:count The count given for the last Normal mode command. Can be used
Bram Moolenaar58b85342016-08-14 19:54:54 +02001674 to get the count before a mapping. Read-only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001675 :map _x :<C-U>echo "the count is " . v:count<CR>
1676< Note: The <C-U> is required to remove the line range that you
1677 get when typing ':' after a count.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001678 When there are two counts, as in "3d2w", they are multiplied,
1679 just like what happens in the command, "d6w" for the example.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001680 Also used for evaluating the 'formatexpr' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001681 "count" also works, for backwards compatibility.
1682
1683 *v:count1* *count1-variable*
1684v:count1 Just like "v:count", but defaults to one when no count is
1685 used.
1686
1687 *v:ctype* *ctype-variable*
1688v:ctype The current locale setting for characters of the runtime
1689 environment. This allows Vim scripts to be aware of the
1690 current locale encoding. Technical: it's the value of
1691 LC_CTYPE. When not using a locale the value is "C".
1692 This variable can not be set directly, use the |:language|
1693 command.
1694 See |multi-lang|.
1695
1696 *v:dying* *dying-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001697v:dying Normally zero. When a deadly signal is caught it's set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001698 one. When multiple signals are caught the number increases.
1699 Can be used in an autocommand to check if Vim didn't
1700 terminate normally. {only works on Unix}
1701 Example: >
1702 :au VimLeave * if v:dying | echo "\nAAAAaaaarrrggghhhh!!!\n" | endif
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001703< Note: if another deadly signal is caught when v:dying is one,
1704 VimLeave autocommands will not be executed.
1705
Bram Moolenaar071d4272004-06-13 20:20:40 +00001706 *v:errmsg* *errmsg-variable*
1707v:errmsg Last given error message. It's allowed to set this variable.
1708 Example: >
1709 :let v:errmsg = ""
1710 :silent! next
1711 :if v:errmsg != ""
1712 : ... handle error
1713< "errmsg" also works, for backwards compatibility.
1714
Bram Moolenaar65a54642018-04-28 16:56:53 +02001715 *v:errors* *errors-variable* *assert-return*
Bram Moolenaar683fa182015-11-30 21:38:24 +01001716v:errors Errors found by assert functions, such as |assert_true()|.
Bram Moolenaar43345542015-11-29 17:35:35 +01001717 This is a list of strings.
1718 The assert functions append an item when an assert fails.
Bram Moolenaar65a54642018-04-28 16:56:53 +02001719 The return value indicates this: a one is returned if an item
1720 was added to v:errors, otherwise zero is returned.
Bram Moolenaar43345542015-11-29 17:35:35 +01001721 To remove old results make it empty: >
1722 :let v:errors = []
1723< If v:errors is set to anything but a list it is made an empty
1724 list by the assert function.
1725
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001726 *v:event* *event-variable*
1727v:event Dictionary containing information about the current
1728 |autocommand|. The dictionary is emptied when the |autocommand|
1729 finishes, please refer to |dict-identity| for how to get an
1730 independent copy of it.
1731
Bram Moolenaar071d4272004-06-13 20:20:40 +00001732 *v:exception* *exception-variable*
1733v:exception The value of the exception most recently caught and not
1734 finished. See also |v:throwpoint| and |throw-variables|.
1735 Example: >
1736 :try
1737 : throw "oops"
1738 :catch /.*/
1739 : echo "caught" v:exception
1740 :endtry
1741< Output: "caught oops".
1742
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001743 *v:false* *false-variable*
1744v:false A Number with value zero. Used to put "false" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001745 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001746 When used as a string this evaluates to "v:false". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001747 echo v:false
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001748< v:false ~
1749 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001750 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001751
Bram Moolenaar19a09a12005-03-04 23:39:37 +00001752 *v:fcs_reason* *fcs_reason-variable*
1753v:fcs_reason The reason why the |FileChangedShell| event was triggered.
1754 Can be used in an autocommand to decide what to do and/or what
1755 to set v:fcs_choice to. Possible values:
1756 deleted file no longer exists
1757 conflict file contents, mode or timestamp was
1758 changed and buffer is modified
1759 changed file contents has changed
1760 mode mode of file changed
1761 time only file timestamp changed
1762
1763 *v:fcs_choice* *fcs_choice-variable*
1764v:fcs_choice What should happen after a |FileChangedShell| event was
1765 triggered. Can be used in an autocommand to tell Vim what to
1766 do with the affected buffer:
1767 reload Reload the buffer (does not work if
1768 the file was deleted).
1769 ask Ask the user what to do, as if there
1770 was no autocommand. Except that when
1771 only the timestamp changed nothing
1772 will happen.
1773 <empty> Nothing, the autocommand should do
1774 everything that needs to be done.
1775 The default is empty. If another (invalid) value is used then
1776 Vim behaves like it is empty, there is no warning message.
1777
Bram Moolenaar071d4272004-06-13 20:20:40 +00001778 *v:fname_in* *fname_in-variable*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001779v:fname_in The name of the input file. Valid while evaluating:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001780 option used for ~
1781 'charconvert' file to be converted
1782 'diffexpr' original file
1783 'patchexpr' original file
1784 'printexpr' file to be printed
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00001785 And set to the swap file name for |SwapExists|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001786
1787 *v:fname_out* *fname_out-variable*
1788v:fname_out The name of the output file. Only valid while
1789 evaluating:
1790 option used for ~
1791 'charconvert' resulting converted file (*)
1792 'diffexpr' output of diff
1793 'patchexpr' resulting patched file
1794 (*) When doing conversion for a write command (e.g., ":w
Bram Moolenaar58b85342016-08-14 19:54:54 +02001795 file") it will be equal to v:fname_in. When doing conversion
Bram Moolenaar071d4272004-06-13 20:20:40 +00001796 for a read command (e.g., ":e file") it will be a temporary
1797 file and different from v:fname_in.
1798
1799 *v:fname_new* *fname_new-variable*
1800v:fname_new The name of the new version of the file. Only valid while
1801 evaluating 'diffexpr'.
1802
1803 *v:fname_diff* *fname_diff-variable*
1804v:fname_diff The name of the diff (patch) file. Only valid while
1805 evaluating 'patchexpr'.
1806
1807 *v:folddashes* *folddashes-variable*
1808v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
1809 fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001810 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001811
1812 *v:foldlevel* *foldlevel-variable*
1813v:foldlevel Used for 'foldtext': foldlevel of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001814 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001815
1816 *v:foldend* *foldend-variable*
1817v:foldend Used for 'foldtext': last line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001818 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001819
1820 *v:foldstart* *foldstart-variable*
1821v:foldstart Used for 'foldtext': first line of closed fold.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001822 Read-only in the |sandbox|. |fold-foldtext|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001823
Bram Moolenaar817a8802013-11-09 01:44:43 +01001824 *v:hlsearch* *hlsearch-variable*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001825v:hlsearch Variable that indicates whether search highlighting is on.
Bram Moolenaar76440e22014-11-27 19:14:49 +01001826 Setting it makes sense only if 'hlsearch' is enabled which
1827 requires |+extra_search|. Setting this variable to zero acts
Bram Moolenaar705ada12016-01-24 17:56:50 +01001828 like the |:nohlsearch| command, setting it to one acts like >
Bram Moolenaar817a8802013-11-09 01:44:43 +01001829 let &hlsearch = &hlsearch
Bram Moolenaar86ae7202015-07-10 19:31:35 +02001830< Note that the value is restored when returning from a
1831 function. |function-search-undo|.
1832
Bram Moolenaar843ee412004-06-30 16:16:41 +00001833 *v:insertmode* *insertmode-variable*
1834v:insertmode Used for the |InsertEnter| and |InsertChange| autocommand
1835 events. Values:
1836 i Insert mode
1837 r Replace mode
1838 v Virtual Replace mode
1839
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001840 *v:key* *key-variable*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001841v:key Key of the current item of a |Dictionary|. Only valid while
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00001842 evaluating the expression used with |map()| and |filter()|.
1843 Read-only.
1844
Bram Moolenaar071d4272004-06-13 20:20:40 +00001845 *v:lang* *lang-variable*
1846v:lang The current locale setting for messages of the runtime
1847 environment. This allows Vim scripts to be aware of the
1848 current language. Technical: it's the value of LC_MESSAGES.
1849 The value is system dependent.
1850 This variable can not be set directly, use the |:language|
1851 command.
1852 It can be different from |v:ctype| when messages are desired
1853 in a different language than what is used for character
1854 encoding. See |multi-lang|.
1855
1856 *v:lc_time* *lc_time-variable*
1857v:lc_time The current locale setting for time messages of the runtime
1858 environment. This allows Vim scripts to be aware of the
1859 current language. Technical: it's the value of LC_TIME.
1860 This variable can not be set directly, use the |:language|
1861 command. See |multi-lang|.
1862
1863 *v:lnum* *lnum-variable*
Bram Moolenaar368373e2010-07-19 20:46:22 +02001864v:lnum Line number for the 'foldexpr' |fold-expr|, 'formatexpr' and
1865 'indentexpr' expressions, tab page number for 'guitablabel'
1866 and 'guitabtooltip'. Only valid while one of these
1867 expressions is being evaluated. Read-only when in the
1868 |sandbox|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001869
Bram Moolenaar219b8702006-11-01 14:32:36 +00001870 *v:mouse_win* *mouse_win-variable*
1871v:mouse_win Window number for a mouse click obtained with |getchar()|.
1872 First window has number 1, like with |winnr()|. The value is
1873 zero when there was no mouse button click.
1874
Bram Moolenaar511972d2016-06-04 18:09:59 +02001875 *v:mouse_winid* *mouse_winid-variable*
1876v:mouse_winid Window ID for a mouse click obtained with |getchar()|.
1877 The value is zero when there was no mouse button click.
1878
Bram Moolenaar219b8702006-11-01 14:32:36 +00001879 *v:mouse_lnum* *mouse_lnum-variable*
1880v:mouse_lnum Line number for a mouse click obtained with |getchar()|.
1881 This is the text line number, not the screen line number. The
1882 value is zero when there was no mouse button click.
1883
1884 *v:mouse_col* *mouse_col-variable*
1885v:mouse_col Column number for a mouse click obtained with |getchar()|.
1886 This is the screen column number, like with |virtcol()|. The
1887 value is zero when there was no mouse button click.
1888
Bram Moolenaard09091d2019-01-17 16:07:22 +01001889 *v:none* *none-variable* *None*
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001890v:none An empty String. Used to put an empty item in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001891 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001892 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001893 When used as a string this evaluates to "v:none". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001894 echo v:none
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001895< v:none ~
1896 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001897 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001898
1899 *v:null* *null-variable*
1900v:null An empty String. Used to put "null" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01001901 |json_encode()|.
Bram Moolenaar705ada12016-01-24 17:56:50 +01001902 When used as a number this evaluates to zero.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001903 When used as a string this evaluates to "v:null". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01001904 echo v:null
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001905< v:null ~
1906 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02001907 value. Read-only.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01001908
Bram Moolenaard812df62008-11-09 12:46:09 +00001909 *v:oldfiles* *oldfiles-variable*
1910v:oldfiles List of file names that is loaded from the |viminfo| file on
1911 startup. These are the files that Vim remembers marks for.
1912 The length of the List is limited by the ' argument of the
1913 'viminfo' option (default is 100).
Bram Moolenaar8d043172014-01-23 14:24:41 +01001914 When the |viminfo| file is not used the List is empty.
Bram Moolenaard812df62008-11-09 12:46:09 +00001915 Also see |:oldfiles| and |c_#<|.
1916 The List can be modified, but this has no effect on what is
1917 stored in the |viminfo| file later. If you use values other
1918 than String this will cause trouble.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001919 {only when compiled with the |+viminfo| feature}
Bram Moolenaard812df62008-11-09 12:46:09 +00001920
Bram Moolenaar53744302015-07-17 17:38:22 +02001921 *v:option_new*
1922v:option_new New value of the option. Valid while executing an |OptionSet|
1923 autocommand.
1924 *v:option_old*
1925v:option_old Old value of the option. Valid while executing an |OptionSet|
1926 autocommand.
1927 *v:option_type*
1928v:option_type Scope of the set command. Valid while executing an
1929 |OptionSet| autocommand. Can be either "global" or "local"
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001930 *v:operator* *operator-variable*
1931v:operator The last operator given in Normal mode. This is a single
1932 character except for commands starting with <g> or <z>,
1933 in which case it is two characters. Best used alongside
1934 |v:prevcount| and |v:register|. Useful if you want to cancel
1935 Operator-pending mode and then use the operator, e.g.: >
1936 :omap O <Esc>:call MyMotion(v:operator)<CR>
1937< The value remains set until another operator is entered, thus
1938 don't expect it to be empty.
1939 v:operator is not set for |:delete|, |:yank| or other Ex
1940 commands.
1941 Read-only.
1942
Bram Moolenaar071d4272004-06-13 20:20:40 +00001943 *v:prevcount* *prevcount-variable*
1944v:prevcount The count given for the last but one Normal mode command.
1945 This is the v:count value of the previous command. Useful if
Bram Moolenaar8af1fbf2008-01-05 12:35:21 +00001946 you want to cancel Visual or Operator-pending mode and then
1947 use the count, e.g.: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001948 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
1949< Read-only.
1950
Bram Moolenaar05159a02005-02-26 23:04:13 +00001951 *v:profiling* *profiling-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02001952v:profiling Normally zero. Set to one after using ":profile start".
Bram Moolenaar05159a02005-02-26 23:04:13 +00001953 See |profiling|.
1954
Bram Moolenaar071d4272004-06-13 20:20:40 +00001955 *v:progname* *progname-variable*
1956v:progname Contains the name (with path removed) with which Vim was
Bram Moolenaard38b0552012-04-25 19:07:41 +02001957 invoked. Allows you to do special initialisations for |view|,
1958 |evim| etc., or any other name you might symlink to Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001959 Read-only.
1960
Bram Moolenaara1706c92014-04-01 19:55:49 +02001961 *v:progpath* *progpath-variable*
1962v:progpath Contains the command with which Vim was invoked, including the
1963 path. Useful if you want to message a Vim server using a
1964 |--remote-expr|.
Bram Moolenaarc7f02552014-04-01 21:00:59 +02001965 To get the full path use: >
1966 echo exepath(v:progpath)
Bram Moolenaar08cab962017-03-04 14:37:18 +01001967< If the path is relative it will be expanded to the full path,
1968 so that it still works after `:cd`. Thus starting "./vim"
1969 results in "/home/user/path/to/vim/src/vim".
1970 On MS-Windows the executable may be called "vim.exe", but the
1971 ".exe" is not added to v:progpath.
Bram Moolenaara1706c92014-04-01 19:55:49 +02001972 Read-only.
1973
Bram Moolenaar071d4272004-06-13 20:20:40 +00001974 *v:register* *register-variable*
Bram Moolenaard58e9292011-02-09 17:07:58 +01001975v:register The name of the register in effect for the current normal mode
Bram Moolenaard38b0552012-04-25 19:07:41 +02001976 command (regardless of whether that command actually used a
1977 register). Or for the currently executing normal mode mapping
1978 (use this in custom commands that take a register).
1979 If none is supplied it is the default register '"', unless
1980 'clipboard' contains "unnamed" or "unnamedplus", then it is
1981 '*' or '+'.
Bram Moolenaard58e9292011-02-09 17:07:58 +01001982 Also see |getreg()| and |setreg()|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001983
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001984 *v:scrollstart* *scrollstart-variable*
1985v:scrollstart String describing the script or function that caused the
1986 screen to scroll up. It's only set when it is empty, thus the
1987 first reason is remembered. It is set to "Unknown" for a
1988 typed command.
1989 This can be used to find out why your script causes the
1990 hit-enter prompt.
1991
Bram Moolenaar071d4272004-06-13 20:20:40 +00001992 *v:servername* *servername-variable*
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02001993v:servername The resulting registered |client-server-name| if any.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001994 Read-only.
1995
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01001996
Bram Moolenaar446cb832008-06-24 21:56:24 +00001997v:searchforward *v:searchforward* *searchforward-variable*
1998 Search direction: 1 after a forward search, 0 after a
1999 backward search. It is reset to forward when directly setting
2000 the last search pattern, see |quote/|.
2001 Note that the value is restored when returning from a
2002 function. |function-search-undo|.
2003 Read-write.
2004
Bram Moolenaar071d4272004-06-13 20:20:40 +00002005 *v:shell_error* *shell_error-variable*
2006v:shell_error Result of the last shell command. When non-zero, the last
2007 shell command had an error. When zero, there was no problem.
2008 This only works when the shell returns the error code to Vim.
2009 The value -1 is often used when the command could not be
2010 executed. Read-only.
2011 Example: >
2012 :!mv foo bar
2013 :if v:shell_error
2014 : echo 'could not rename "foo" to "bar"!'
2015 :endif
2016< "shell_error" also works, for backwards compatibility.
2017
2018 *v:statusmsg* *statusmsg-variable*
2019v:statusmsg Last given status message. It's allowed to set this variable.
2020
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002021 *v:swapname* *swapname-variable*
2022v:swapname Only valid when executing |SwapExists| autocommands: Name of
2023 the swap file found. Read-only.
2024
2025 *v:swapchoice* *swapchoice-variable*
2026v:swapchoice |SwapExists| autocommands can set this to the selected choice
2027 for handling an existing swap file:
2028 'o' Open read-only
2029 'e' Edit anyway
2030 'r' Recover
2031 'd' Delete swapfile
2032 'q' Quit
2033 'a' Abort
Bram Moolenaar58b85342016-08-14 19:54:54 +02002034 The value should be a single-character string. An empty value
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00002035 results in the user being asked, as would happen when there is
2036 no SwapExists autocommand. The default is empty.
2037
Bram Moolenaarb3480382005-12-11 21:33:32 +00002038 *v:swapcommand* *swapcommand-variable*
Bram Moolenaar4770d092006-01-12 23:22:24 +00002039v:swapcommand Normal mode command to be executed after a file has been
Bram Moolenaarb3480382005-12-11 21:33:32 +00002040 opened. Can be used for a |SwapExists| autocommand to have
Bram Moolenaar58b85342016-08-14 19:54:54 +02002041 another Vim open the file and jump to the right place. For
Bram Moolenaarb3480382005-12-11 21:33:32 +00002042 example, when jumping to a tag the value is ":tag tagname\r".
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00002043 For ":edit +cmd file" the value is ":cmd\r".
Bram Moolenaarb3480382005-12-11 21:33:32 +00002044
Bram Moolenaard823fa92016-08-12 16:29:27 +02002045 *v:t_TYPE* *v:t_bool* *t_bool-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002046v:t_bool Value of |Boolean| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002047 *v:t_channel* *t_channel-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002048v:t_channel Value of |Channel| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002049 *v:t_dict* *t_dict-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002050v:t_dict Value of |Dictionary| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002051 *v:t_float* *t_float-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002052v:t_float Value of |Float| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002053 *v:t_func* *t_func-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002054v:t_func Value of |Funcref| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002055 *v:t_job* *t_job-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002056v:t_job Value of |Job| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002057 *v:t_list* *t_list-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002058v:t_list Value of |List| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002059 *v:t_none* *t_none-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002060v:t_none Value of |None| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002061 *v:t_number* *t_number-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002062v:t_number Value of |Number| type. Read-only. See: |type()|
Bram Moolenaard823fa92016-08-12 16:29:27 +02002063 *v:t_string* *t_string-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002064v:t_string Value of |String| type. Read-only. See: |type()|
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002065 *v:t_blob* *t_blob-variable*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002066v:t_blob Value of |Blob| type. Read-only. See: |type()|
Bram Moolenaarf562e722016-07-19 17:25:25 +02002067
Bram Moolenaar071d4272004-06-13 20:20:40 +00002068 *v:termresponse* *termresponse-variable*
2069v:termresponse The escape sequence returned by the terminal for the |t_RV|
Bram Moolenaar58b85342016-08-14 19:54:54 +02002070 termcap entry. It is set when Vim receives an escape sequence
Bram Moolenaar071d4272004-06-13 20:20:40 +00002071 that starts with ESC [ or CSI and ends in a 'c', with only
2072 digits, ';' and '.' in between.
2073 When this option is set, the TermResponse autocommand event is
2074 fired, so that you can react to the response from the
2075 terminal.
2076 The response from a new xterm is: "<Esc>[ Pp ; Pv ; Pc c". Pp
2077 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
2078 patch level (since this was introduced in patch 95, it's
2079 always 95 or bigger). Pc is always zero.
2080 {only when compiled with |+termresponse| feature}
2081
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002082 *v:termblinkresp*
2083v:termblinkresp The escape sequence returned by the terminal for the |t_RC|
2084 termcap entry. This is used to find out whether the terminal
2085 cursor is blinking. This is used by |term_getcursor()|.
2086
2087 *v:termstyleresp*
2088v:termstyleresp The escape sequence returned by the terminal for the |t_RS|
2089 termcap entry. This is used to find out what the shape of the
2090 cursor is. This is used by |term_getcursor()|.
2091
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002092 *v:termrbgresp*
2093v:termrbgresp The escape sequence returned by the terminal for the |t_RB|
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002094 termcap entry. This is used to find out what the terminal
2095 background color is, see 'background'.
2096
Bram Moolenaar65e4c4f2017-10-14 23:24:25 +02002097 *v:termrfgresp*
2098v:termrfgresp The escape sequence returned by the terminal for the |t_RF|
2099 termcap entry. This is used to find out what the terminal
2100 foreground color is.
2101
Bram Moolenaarf3af54e2017-08-30 14:53:06 +02002102 *v:termu7resp*
2103v:termu7resp The escape sequence returned by the terminal for the |t_u7|
2104 termcap entry. This is used to find out what the terminal
2105 does with ambiguous width characters, see 'ambiwidth'.
2106
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002107 *v:testing* *testing-variable*
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002108v:testing Must be set before using `test_garbagecollect_now()`.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002109 Also, when set certain error messages won't be shown for 2
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002110 seconds. (e.g. "'dictionary' option is empty")
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02002111
Bram Moolenaar071d4272004-06-13 20:20:40 +00002112 *v:this_session* *this_session-variable*
2113v:this_session Full filename of the last loaded or saved session file. See
2114 |:mksession|. It is allowed to set this variable. When no
2115 session file has been saved, this variable is empty.
2116 "this_session" also works, for backwards compatibility.
2117
2118 *v:throwpoint* *throwpoint-variable*
2119v:throwpoint The point where the exception most recently caught and not
Bram Moolenaar58b85342016-08-14 19:54:54 +02002120 finished was thrown. Not set when commands are typed. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00002121 also |v:exception| and |throw-variables|.
2122 Example: >
2123 :try
2124 : throw "oops"
2125 :catch /.*/
2126 : echo "Exception from" v:throwpoint
2127 :endtry
2128< Output: "Exception from test.vim, line 2"
2129
Bram Moolenaar520e1e42016-01-23 19:46:28 +01002130 *v:true* *true-variable*
2131v:true A Number with value one. Used to put "true" in JSON. See
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002132 |json_encode()|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002133 When used as a string this evaluates to "v:true". >
Bram Moolenaar705ada12016-01-24 17:56:50 +01002134 echo v:true
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002135< v:true ~
2136 That is so that eval() can parse the string back to the same
Bram Moolenaardf48fb42016-07-22 21:50:18 +02002137 value. Read-only.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002138 *v:val* *val-variable*
Bram Moolenaar58b85342016-08-14 19:54:54 +02002139v:val Value of the current item of a |List| or |Dictionary|. Only
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002140 valid while evaluating the expression used with |map()| and
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002141 |filter()|. Read-only.
2142
Bram Moolenaar071d4272004-06-13 20:20:40 +00002143 *v:version* *version-variable*
2144v:version Version number of Vim: Major version number times 100 plus
2145 minor version number. Version 5.0 is 500. Version 5.1 (5.01)
2146 is 501. Read-only. "version" also works, for backwards
2147 compatibility.
2148 Use |has()| to check if a certain patch was included, e.g.: >
Bram Moolenaar6716d9a2014-04-02 12:12:08 +02002149 if has("patch-7.4.123")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002150< Note that patch numbers are specific to the version, thus both
2151 version 5.0 and 5.1 may have a patch 123, but these are
2152 completely different.
2153
Bram Moolenaar14735512016-03-26 21:00:08 +01002154 *v:vim_did_enter* *vim_did_enter-variable*
2155v:vim_did_enter Zero until most of startup is done. It is set to one just
2156 before |VimEnter| autocommands are triggered.
2157
Bram Moolenaar071d4272004-06-13 20:20:40 +00002158 *v:warningmsg* *warningmsg-variable*
2159v:warningmsg Last given warning message. It's allowed to set this variable.
2160
Bram Moolenaar727c8762010-10-20 19:17:48 +02002161 *v:windowid* *windowid-variable*
2162v:windowid When any X11 based GUI is running or when running in a
2163 terminal and Vim connects to the X server (|-X|) this will be
Bram Moolenaar264e9fd2010-10-27 12:33:17 +02002164 set to the window ID.
2165 When an MS-Windows GUI is running this will be set to the
2166 window handle.
2167 Otherwise the value is zero.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002168 Note: for windows inside Vim use |winnr()| or |win_getid()|,
2169 see |window-ID|.
Bram Moolenaar727c8762010-10-20 19:17:48 +02002170
Bram Moolenaar071d4272004-06-13 20:20:40 +00002171==============================================================================
21724. Builtin Functions *functions*
2173
2174See |function-list| for a list grouped by what the function is used for.
2175
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00002176(Use CTRL-] on the function name to jump to the full explanation.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002177
2178USAGE RESULT DESCRIPTION ~
2179
Bram Moolenaar81edd172016-04-14 13:51:37 +02002180abs({expr}) Float or Number absolute value of {expr}
2181acos({expr}) Float arc cosine of {expr}
Bram Moolenaard8968242019-01-15 22:51:57 +01002182add({object}, {item}) List/Blob append {item} to {object}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002183and({expr}, {expr}) Number bitwise AND
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002184append({lnum}, {text}) Number append {text} below line {lnum}
2185appendbufline({expr}, {lnum}, {text})
2186 Number append {text} below line {lnum}
2187 in buffer {expr}
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002188argc([{winid}]) Number number of files in the argument list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002189argidx() Number current index in the argument list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002190arglistid([{winnr} [, {tabnr}]]) Number argument list id
Bram Moolenaare6e39892018-10-25 12:32:11 +02002191argv({nr} [, {winid}]) String {nr} entry of the argument list
2192argv([-1, {winid}]) List the argument list
Bram Moolenaar65a54642018-04-28 16:56:53 +02002193assert_beeps({cmd}) Number assert {cmd} causes a beep
Bram Moolenaar42205552017-03-18 19:42:22 +01002194assert_equal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002195 Number assert {exp} is equal to {act}
Bram Moolenaard96ff162018-02-18 22:13:29 +01002196assert_equalfile({fname-one}, {fname-two})
Bram Moolenaar65a54642018-04-28 16:56:53 +02002197 Number assert file contents is equal
Bram Moolenaar42205552017-03-18 19:42:22 +01002198assert_exception({error} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002199 Number assert {error} is in v:exception
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002200assert_fails({cmd} [, {error} [, {msg}]])
2201 Number assert {cmd} fails
Bram Moolenaar42205552017-03-18 19:42:22 +01002202assert_false({actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002203 Number assert {actual} is false
Bram Moolenaar61c04492016-07-23 15:35:35 +02002204assert_inrange({lower}, {upper}, {actual} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002205 Number assert {actual} is inside the range
Bram Moolenaar42205552017-03-18 19:42:22 +01002206assert_match({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002207 Number assert {pat} matches {text}
Bram Moolenaar42205552017-03-18 19:42:22 +01002208assert_notequal({exp}, {act} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002209 Number assert {exp} is not equal {act}
Bram Moolenaar42205552017-03-18 19:42:22 +01002210assert_notmatch({pat}, {text} [, {msg}])
Bram Moolenaar65a54642018-04-28 16:56:53 +02002211 Number assert {pat} not matches {text}
2212assert_report({msg}) Number report a test failure
2213assert_true({actual} [, {msg}]) Number assert {actual} is true
Bram Moolenaar81edd172016-04-14 13:51:37 +02002214asin({expr}) Float arc sine of {expr}
2215atan({expr}) Float arc tangent of {expr}
Bram Moolenaar04186092016-08-29 21:55:35 +02002216atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2}
Bram Moolenaar74240d32017-12-10 15:26:15 +01002217balloon_show({expr}) none show {expr} inside the balloon
Bram Moolenaar246fe032017-11-19 19:56:27 +01002218balloon_split({msg}) List split {msg} as used for a balloon
Bram Moolenaar81edd172016-04-14 13:51:37 +02002219browse({save}, {title}, {initdir}, {default})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002220 String put up a file requester
Bram Moolenaar81edd172016-04-14 13:51:37 +02002221browsedir({title}, {initdir}) String put up a directory requester
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002222bufexists({expr}) Number |TRUE| if buffer {expr} exists
2223buflisted({expr}) Number |TRUE| if buffer {expr} is listed
2224bufloaded({expr}) Number |TRUE| if buffer {expr} is loaded
Bram Moolenaar81edd172016-04-14 13:51:37 +02002225bufname({expr}) String Name of the buffer {expr}
2226bufnr({expr} [, {create}]) Number Number of the buffer {expr}
Bram Moolenaarb3619a92016-06-04 17:58:52 +02002227bufwinid({expr}) Number window ID of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002228bufwinnr({expr}) Number window number of buffer {expr}
2229byte2line({byte}) Number line number at byte count {byte}
2230byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2231byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr}
2232call({func}, {arglist} [, {dict}])
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00002233 any call {func} with arguments {arglist}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002234ceil({expr}) Float round {expr} up
Bram Moolenaar4b785f62016-11-29 21:54:44 +01002235ch_canread({handle}) Number check if there is something to read
Bram Moolenaar81edd172016-04-14 13:51:37 +02002236ch_close({handle}) none close {handle}
Bram Moolenaar0874a832016-09-01 15:11:51 +02002237ch_close_in({handle}) none close in part of {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002238ch_evalexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002239 any evaluate {expr} on JSON {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002240ch_evalraw({handle}, {string} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002241 any evaluate {string} on raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002242ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what}
2243ch_getjob({channel}) Job get the Job of {channel}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002244ch_info({handle}) String info about channel {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002245ch_log({msg} [, {handle}]) none write {msg} in the channel log file
2246ch_logfile({fname} [, {mode}]) none start logging channel activity
2247ch_open({address} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002248 Channel open a channel to {address}
2249ch_read({handle} [, {options}]) String read from {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002250ch_readblob({handle} [, {options}])
2251 Blob read Blob from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002252ch_readraw({handle} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002253 String read raw from {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002254ch_sendexpr({handle}, {expr} [, {options}])
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01002255 any send {expr} over JSON {handle}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002256ch_sendraw({handle}, {expr} [, {options}])
2257 any send {expr} over raw {handle}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002258ch_setoptions({handle}, {options})
2259 none set options for {handle}
Bram Moolenaar7ef38102016-09-26 22:36:58 +02002260ch_status({handle} [, {options}])
2261 String status of channel {handle}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002262changenr() Number current change number
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002263char2nr({expr} [, {utf8}]) Number ASCII/UTF8 value of first char in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002264cindent({lnum}) Number C indent for line {lnum}
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002265clearmatches() none clear all matches
Bram Moolenaar81edd172016-04-14 13:51:37 +02002266col({expr}) Number column nr of cursor or mark
2267complete({startcol}, {matches}) none set Insert mode completion
2268complete_add({expr}) Number add completion match
Bram Moolenaar446cb832008-06-24 21:56:24 +00002269complete_check() Number check for key typed during completion
Bram Moolenaar81edd172016-04-14 13:51:37 +02002270confirm({msg} [, {choices} [, {default} [, {type}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002271 Number number of choice picked by user
Bram Moolenaar81edd172016-04-14 13:51:37 +02002272copy({expr}) any make a shallow copy of {expr}
2273cos({expr}) Float cosine of {expr}
2274cosh({expr}) Float hyperbolic cosine of {expr}
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002275count({comp}, {expr} [, {ic} [, {start}]])
2276 Number count how many {expr} are in {comp}
Bram Moolenaardc1f1642016-08-16 18:33:43 +02002277cscope_connection([{num}, {dbpath} [, {prepend}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002278 Number checks existence of cscope connection
Bram Moolenaar81edd172016-04-14 13:51:37 +02002279cursor({lnum}, {col} [, {off}])
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01002280 Number move cursor to {lnum}, {col}, {off}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002281cursor({list}) Number move cursor to position in {list}
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02002282debugbreak({pid}) Number interrupt process being debugged
Bram Moolenaar81edd172016-04-14 13:51:37 +02002283deepcopy({expr} [, {noref}]) any make a full copy of {expr}
2284delete({fname} [, {flags}]) Number delete the file or directory {fname}
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002285deletebufline({expr}, {first} [, {last}])
Bram Moolenaard79a2622018-06-07 18:17:46 +02002286 Number delete lines from buffer {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002287did_filetype() Number |TRUE| if FileType autocmd event used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002288diff_filler({lnum}) Number diff filler lines about {lnum}
2289diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002290empty({expr}) Number |TRUE| if {expr} is empty
Bram Moolenaar81edd172016-04-14 13:51:37 +02002291escape({string}, {chars}) String escape {chars} in {string} with '\'
2292eval({string}) any evaluate {string} into its value
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002293eventhandler() Number |TRUE| if inside an event handler
Bram Moolenaar81edd172016-04-14 13:51:37 +02002294executable({expr}) Number 1 if executable {expr} exists
Bram Moolenaar79815f12016-07-09 17:07:29 +02002295execute({command}) String execute {command} and get the output
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002296exepath({expr}) String full path of the command {expr}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002297exists({expr}) Number |TRUE| if {expr} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002298extend({expr1}, {expr2} [, {expr3}])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002299 List/Dict insert items of {expr2} into {expr1}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002300exp({expr}) Float exponential of {expr}
2301expand({expr} [, {nosuf} [, {list}]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002302 any expand special keywords in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002303feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002304filereadable({file}) Number |TRUE| if {file} is a readable file
2305filewritable({file}) Number |TRUE| if {file} is a writable file
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002306filter({expr1}, {expr2}) List/Dict remove items from {expr1} where
2307 {expr2} is 0
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002308finddir({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002309 String find directory {name} in {path}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002310findfile({name} [, {path} [, {count}]])
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00002311 String find file {name} in {path}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002312float2nr({expr}) Number convert Float {expr} to a Number
2313floor({expr}) Float round {expr} down
2314fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2}
2315fnameescape({fname}) String escape special characters in {fname}
2316fnamemodify({fname}, {mods}) String modify file name
2317foldclosed({lnum}) Number first line of fold at {lnum} if closed
2318foldclosedend({lnum}) Number last line of fold at {lnum} if closed
2319foldlevel({lnum}) Number fold level at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002320foldtext() String line displayed for closed fold
Bram Moolenaar81edd172016-04-14 13:51:37 +02002321foldtextresult({lnum}) String text for closed fold at {lnum}
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002322foreground() Number bring the Vim window to the foreground
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002323funcref({name} [, {arglist}] [, {dict}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002324 Funcref reference to function {name}
Bram Moolenaar437bafe2016-08-01 15:40:54 +02002325function({name} [, {arglist}] [, {dict}])
2326 Funcref named reference to function {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002327garbagecollect([{atexit}]) none free memory, breaking cyclic references
Bram Moolenaar81edd172016-04-14 13:51:37 +02002328get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def}
2329get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def}
Bram Moolenaar03e19a02016-05-24 22:29:49 +02002330get({func}, {what}) any get property of funcref/partial {func}
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002331getbufinfo([{expr}]) List information about buffers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002332getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar45360022005-07-21 21:08:21 +00002333 List lines {lnum} to {end} of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002334getbufvar({expr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002335 any variable {varname} in buffer {expr}
Bram Moolenaar07ad8162018-02-13 13:59:59 +01002336getchangelist({expr}) List list of change list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002337getchar([expr]) Number get one character from the user
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002338getcharmod() Number modifiers for the last typed character
Bram Moolenaarfc39ecf2015-08-11 20:34:49 +02002339getcharsearch() Dict last character search
Bram Moolenaar071d4272004-06-13 20:20:40 +00002340getcmdline() String return the current command-line
2341getcmdpos() Number return cursor position in command-line
Bram Moolenaarfb539272014-08-22 19:21:47 +02002342getcmdtype() String return current command-line type
2343getcmdwintype() String return current command-line window type
Bram Moolenaare9d58a62016-08-13 15:07:41 +02002344getcompletion({pat}, {type} [, {filtered}])
2345 List list of cmdline completion matches
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02002346getcurpos() List position of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002347getcwd([{winnr} [, {tabnr}]]) String get the current working directory
2348getfontname([{name}]) String name of font being used
2349getfperm({fname}) String file permissions of file {fname}
2350getfsize({fname}) Number size in bytes of file {fname}
2351getftime({fname}) Number last modification time of file
2352getftype({fname}) String description of type of file {fname}
Bram Moolenaar4f505882018-02-10 21:06:32 +01002353getjumplist([{winnr} [, {tabnr}]])
2354 List list of jump list items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002355getline({lnum}) String line {lnum} of current buffer
2356getline({lnum}, {end}) List lines {lnum} to {end} of current buffer
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002357getloclist({nr} [, {what}]) List list of location list items
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002358getmatches() List list of current matches
Bram Moolenaar18081e32008-02-20 19:11:07 +00002359getpid() Number process ID of Vim
Bram Moolenaar81edd172016-04-14 13:51:37 +02002360getpos({expr}) List position of cursor, mark, etc.
Bram Moolenaard823fa92016-08-12 16:29:27 +02002361getqflist([{what}]) List list of quickfix items
Bram Moolenaar81edd172016-04-14 13:51:37 +02002362getreg([{regname} [, 1 [, {list}]]])
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02002363 String or List contents of register
Bram Moolenaar81edd172016-04-14 13:51:37 +02002364getregtype([{regname}]) String type of register
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002365gettabinfo([{expr}]) List list of tab pages
Bram Moolenaar81edd172016-04-14 13:51:37 +02002366gettabvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002367 any variable {varname} in tab {nr} or {def}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002368gettabwinvar({tabnr}, {winnr}, {name} [, {def}])
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00002369 any {name} in {winnr} in tab page {tabnr}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002370gettagstack([{nr}]) Dict get the tag stack of window {nr}
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02002371getwininfo([{winid}]) List list of info about each window
Bram Moolenaar98ef2332018-03-18 14:44:37 +01002372getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01002373getwinposx() Number X coord in pixels of the Vim window
2374getwinposy() Number Y coord in pixels of the Vim window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002375getwinvar({nr}, {varname} [, {def}])
Bram Moolenaar63dbda12013-02-20 21:12:10 +01002376 any variable {varname} in window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002377glob({expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar146e9c32012-03-07 19:18:23 +01002378 any expand file wildcards in {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002379glob2regpat({expr}) String convert a glob pat into a search pat
Bram Moolenaar81edd172016-04-14 13:51:37 +02002380globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00002381 String do glob({expr}) for all dirs in {path}
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002382has({feature}) Number |TRUE| if feature {feature} supported
2383has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002384haslocaldir([{winnr} [, {tabnr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002385 Number |TRUE| if the window executed |:lcd|
Bram Moolenaar81edd172016-04-14 13:51:37 +02002386hasmapto({what} [, {mode} [, {abbr}]])
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002387 Number |TRUE| if mapping to {what} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002388histadd({history}, {item}) String add an item to a history
2389histdel({history} [, {item}]) String remove an item from a history
2390histget({history} [, {index}]) String get the item {index} from a history
2391histnr({history}) Number highest index of a history
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002392hlexists({name}) Number |TRUE| if highlight group {name} exists
Bram Moolenaar81edd172016-04-14 13:51:37 +02002393hlID({name}) Number syntax ID of highlight group {name}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002394hostname() String name of the machine Vim is running on
Bram Moolenaar81edd172016-04-14 13:51:37 +02002395iconv({expr}, {from}, {to}) String convert encoding of {expr}
2396indent({lnum}) Number indent of line {lnum}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002397index({object}, {expr} [, {start} [, {ic}]])
2398 Number index in {object} where {expr} appears
Bram Moolenaar81edd172016-04-14 13:51:37 +02002399input({prompt} [, {text} [, {completion}]])
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00002400 String get input from the user
Bram Moolenaarb6e0ec62017-07-23 22:12:20 +02002401inputdialog({prompt} [, {text} [, {completion}]])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002402 String like input() but in a GUI dialog
Bram Moolenaar81edd172016-04-14 13:51:37 +02002403inputlist({textlist}) Number let the user pick from a choice list
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002404inputrestore() Number restore typeahead
2405inputsave() Number save and clear typeahead
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002406inputsecret({prompt} [, {text}]) String like input() but hiding the text
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002407insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}]
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002408invert({expr}) Number bitwise invert
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002409isdirectory({directory}) Number |TRUE| if {directory} is a directory
2410islocked({expr}) Number |TRUE| if {expr} is locked
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002411isnan({expr}) Number |TRUE| if {expr} is NaN
Bram Moolenaar81edd172016-04-14 13:51:37 +02002412items({dict}) List key-value pairs in {dict}
2413job_getchannel({job}) Channel get the channel handle for {job}
Bram Moolenaare1fc5152018-04-21 19:49:08 +02002414job_info([{job}]) Dict get information about {job}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002415job_setoptions({job}, {options}) none set options for {job}
2416job_start({command} [, {options}])
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002417 Job start a job
Bram Moolenaar81edd172016-04-14 13:51:37 +02002418job_status({job}) String get the status of {job}
2419job_stop({job} [, {how}]) Number stop {job}
2420join({list} [, {sep}]) String join {list} items into one String
2421js_decode({string}) any decode JS style JSON
2422js_encode({expr}) String encode JS style JSON
2423json_decode({string}) any decode JSON
2424json_encode({expr}) String encode JSON
2425keys({dict}) List keys in {dict}
2426len({expr}) Number the length of {expr}
2427libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002428libcallnr({lib}, {func}, {arg}) Number idem, but return a Number
Bram Moolenaar81edd172016-04-14 13:51:37 +02002429line({expr}) Number line nr of cursor, last line or mark
2430line2byte({lnum}) Number byte count of line {lnum}
2431lispindent({lnum}) Number Lisp indent for line {lnum}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002432localtime() Number current time
Bram Moolenaar81edd172016-04-14 13:51:37 +02002433log({expr}) Float natural logarithm (base e) of {expr}
2434log10({expr}) Float logarithm of Float {expr} to base 10
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002435luaeval({expr} [, {expr}]) any evaluate |Lua| expression
Bram Moolenaar50ba5262016-09-22 22:33:02 +02002436map({expr1}, {expr2}) List/Dict change each item in {expr1} to {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002437maparg({name} [, {mode} [, {abbr} [, {dict}]]])
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01002438 String or Dict
2439 rhs of mapping {name} in mode {mode}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002440mapcheck({name} [, {mode} [, {abbr}]])
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00002441 String check for mappings matching {name}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002442match({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002443 Number position where {pat} matches in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002444matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00002445 Number highlight {pattern} with {group}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002446matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02002447 Number highlight positions with {group}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002448matcharg({nr}) List arguments of |:match|
2449matchdelete({id}) Number delete match identified by {id}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002450matchend({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002451 Number position where {pat} ends in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002452matchlist({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00002453 List match and submatches of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002454matchstr({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00002455 String {count}'th match of {pat} in {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002456matchstrpos({expr}, {pat} [, {start} [, {count}]])
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02002457 List {count}'th match of {pat} in {expr}
Bram Moolenaar690afe12017-01-28 18:34:47 +01002458max({expr}) Number maximum value of items in {expr}
2459min({expr}) Number minimum value of items in {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002460mkdir({name} [, {path} [, {prot}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002461 Number create directory {name}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002462mode([expr]) String current editing mode
2463mzeval({expr}) any evaluate |MzScheme| expression
2464nextnonblank({lnum}) Number line nr of non-blank line >= {lnum}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002465nr2char({expr} [, {utf8}]) String single char with ASCII/UTF8 value {expr}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002466or({expr}, {expr}) Number bitwise OR
Bram Moolenaar81edd172016-04-14 13:51:37 +02002467pathshorten({expr}) String shorten directory names in a path
2468perleval({expr}) any evaluate |Perl| expression
2469pow({x}, {y}) Float {x} to the power of {y}
2470prevnonblank({lnum}) Number line nr of non-blank line <= {lnum}
2471printf({fmt}, {expr1}...) String format text
Bram Moolenaarf2732452018-06-03 14:47:35 +02002472prompt_setcallback({buf}, {expr}) none set prompt callback function
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02002473prompt_setinterrupt({buf}, {text}) none set prompt interrupt function
2474prompt_setprompt({buf}, {text}) none set prompt text
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002475prop_add({lnum}, {col}, {props}) none add a text property
Bram Moolenaare3d31b02018-12-24 23:07:04 +01002476prop_clear({lnum} [, {lnum-end} [, {props}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002477 none remove all text properties
2478prop_find({props} [, {direction}])
2479 Dict search for a text property
Bram Moolenaar5b69c222019-01-11 14:50:06 +01002480prop_list({lnum} [, {props}) List text properties in {lnum}
Bram Moolenaarc8c88492018-12-27 23:59:26 +01002481prop_remove({props} [, {lnum} [, {lnum-end}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002482 Number remove a text property
2483prop_type_add({name}, {props}) none define a new property type
2484prop_type_change({name}, {props})
2485 none change an existing property type
2486prop_type_delete({name} [, {props}])
2487 none delete a property type
2488prop_type_get([{name} [, {props}])
2489 Dict get property type values
2490prop_type_list([{props}]) List get list of property types
Bram Moolenaar446cb832008-06-24 21:56:24 +00002491pumvisible() Number whether popup menu is visible
Bram Moolenaar81edd172016-04-14 13:51:37 +02002492pyeval({expr}) any evaluate |Python| expression
2493py3eval({expr}) any evaluate |python3| expression
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01002494pyxeval({expr}) any evaluate |python_x| expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002495range({expr} [, {max} [, {stride}]])
Bram Moolenaard8b02732005-01-14 21:48:43 +00002496 List items from {expr} to {max}
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002497readfile({fname} [, {type} [, {max}]])
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002498 List get list of lines from file {fname}
Bram Moolenaarf2732452018-06-03 14:47:35 +02002499reg_executing() String get the executing register name
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02002500reg_recording() String get the recording register name
Bram Moolenaar81edd172016-04-14 13:51:37 +02002501reltime([{start} [, {end}]]) List get time value
2502reltimefloat({time}) Float turn the time value into a Float
2503reltimestr({time}) String turn time value into a String
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002504remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002505 String send expression
Bram Moolenaar81edd172016-04-14 13:51:37 +02002506remote_foreground({server}) Number bring Vim server to the foreground
2507remote_peek({serverid} [, {retvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002508 Number check for reply string
Bram Moolenaar3c2881d2017-03-21 19:18:29 +01002509remote_read({serverid} [, {timeout}])
2510 String read reply string
Bram Moolenaar81edd172016-04-14 13:51:37 +02002511remote_send({server}, {string} [, {idvar}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002512 String send key sequence
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01002513remote_startserver({name}) none become server {name}
Bram Moolenaar39536dd2019-01-29 22:58:21 +01002514remove({list}, {idx} [, {end}]) any/List
2515 remove items {idx}-{end} from {list}
2516remove({blob}, {idx} [, {end}]) Number/Blob
2517 remove bytes {idx}-{end} from {blob}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002518remove({dict}, {key}) any remove entry {key} from {dict}
2519rename({from}, {to}) Number rename (move) file from {from} to {to}
2520repeat({expr}, {count}) String repeat {expr} {count} times
2521resolve({filename}) String get filename a shortcut points to
2522reverse({list}) List reverse {list} in-place
2523round({expr}) Float round off {expr}
2524screenattr({row}, {col}) Number attribute at screen position
2525screenchar({row}, {col}) Number character at screen position
Bram Moolenaar9750bb12012-12-05 16:10:42 +01002526screencol() Number current cursor column
2527screenrow() Number current cursor row
Bram Moolenaar81edd172016-04-14 13:51:37 +02002528search({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar76929292008-01-06 19:07:36 +00002529 Number search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002530searchdecl({name} [, {global} [, {thisblock}]])
Bram Moolenaar446cb832008-06-24 21:56:24 +00002531 Number search for variable declaration
Bram Moolenaar81edd172016-04-14 13:51:37 +02002532searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002533 Number search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002534searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002535 List search for other end of start/end pair
Bram Moolenaar81edd172016-04-14 13:51:37 +02002536searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]])
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00002537 List search for {pattern}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002538server2client({clientid}, {string})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002539 Number send reply string
2540serverlist() String get a list of available servers
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002541setbufline({expr}, {lnum}, {text})
2542 Number set line {lnum} to {text} in buffer
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02002543 {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002544setbufvar({expr}, {varname}, {val})
2545 none set {varname} in buffer {expr} to {val}
2546setcharsearch({dict}) Dict set character search from {dict}
2547setcmdpos({pos}) Number set cursor position in command-line
2548setfperm({fname}, {mode}) Number set {fname} file permissions to {mode}
2549setline({lnum}, {line}) Number set line {lnum} to {line}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002550setloclist({nr}, {list} [, {action} [, {what}]])
Bram Moolenaar17c7c012006-01-26 22:25:15 +00002551 Number modify location list using {list}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002552setmatches({list}) Number restore a list of matches
2553setpos({expr}, {list}) Number set the {expr} position to {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002554setqflist({list} [, {action} [, {what}]])
Bram Moolenaard823fa92016-08-12 16:29:27 +02002555 Number modify quickfix list using {list}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002556setreg({n}, {v} [, {opt}]) Number set register to value and type
Bram Moolenaar81edd172016-04-14 13:51:37 +02002557settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val}
2558settabwinvar({tabnr}, {winnr}, {varname}, {val})
2559 none set {varname} in window {winnr} in tab
2560 page {tabnr} to {val}
Bram Moolenaarf49cc602018-11-11 15:21:05 +01002561settagstack({nr}, {dict} [, {action}])
2562 Number modify tag stack using {dict}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002563setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val}
2564sha256({string}) String SHA256 checksum of {string}
2565shellescape({string} [, {special}])
Bram Moolenaar05bb9532008-07-04 09:44:11 +00002566 String escape {string} for use as shell
Bram Moolenaar60a495f2006-10-03 12:44:42 +00002567 command argument
Bram Moolenaarf9514162018-11-22 03:08:29 +01002568shiftwidth([{col}]) Number effective value of 'shiftwidth'
Bram Moolenaar162b7142018-12-21 15:17:36 +01002569sign_define({name} [, {dict}]) Number define or update a sign
2570sign_getdefined([{name}]) List get a list of defined signs
2571sign_getplaced([{expr} [, {dict}]])
2572 List get a list of placed signs
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01002573sign_jump({id}, {group}, {expr})
2574 Number jump to a sign
Bram Moolenaar162b7142018-12-21 15:17:36 +01002575sign_place({id}, {group}, {name}, {expr} [, {dict}])
2576 Number place a sign
2577sign_undefine([{name}]) Number undefine a sign
2578sign_unplace({group} [, {dict}])
2579 Number unplace a sign
Bram Moolenaar81edd172016-04-14 13:51:37 +02002580simplify({filename}) String simplify filename as much as possible
2581sin({expr}) Float sine of {expr}
2582sinh({expr}) Float hyperbolic sine of {expr}
2583sort({list} [, {func} [, {dict}]])
Bram Moolenaar5f894962011-06-19 02:55:37 +02002584 List sort {list}, using {func} to compare
Bram Moolenaar81edd172016-04-14 13:51:37 +02002585soundfold({word}) String sound-fold {word}
Bram Moolenaard857f0e2005-06-21 22:37:39 +00002586spellbadword() String badly spelled word at cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002587spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00002588 List spelling suggestions
Bram Moolenaar81edd172016-04-14 13:51:37 +02002589split({expr} [, {pat} [, {keepempty}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002590 List make |List| from {pat} separated {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002591sqrt({expr}) Float square root of {expr}
2592str2float({expr}) Float convert String to Float
2593str2nr({expr} [, {base}]) Number convert String to Number
2594strchars({expr} [, {skipcc}]) Number character length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002595strcharpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002596 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002597strdisplaywidth({expr} [, {col}]) Number display length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002598strftime({format} [, {time}]) String time in specified format
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002599strgetchar({str}, {index}) Number get char {index} from {str}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002600stridx({haystack}, {needle} [, {start}])
Bram Moolenaar8f999f12005-01-25 22:12:55 +00002601 Number index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002602string({expr}) String String representation of {expr} value
2603strlen({expr}) Number length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002604strpart({str}, {start} [, {len}])
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02002605 String {len} characters of {str} at {start}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002606strridx({haystack}, {needle} [, {start}])
Bram Moolenaar677ee682005-01-27 14:41:15 +00002607 Number last index of {needle} in {haystack}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002608strtrans({expr}) String translate string to make it printable
2609strwidth({expr}) Number display cell length of the String {expr}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002610submatch({nr} [, {list}]) String or List
Bram Moolenaar41571762014-04-02 19:00:58 +02002611 specific match in ":s" or substitute()
Bram Moolenaar81edd172016-04-14 13:51:37 +02002612substitute({expr}, {pat}, {sub}, {flags})
Bram Moolenaar071d4272004-06-13 20:20:40 +00002613 String all {pat} in {expr} replaced with {sub}
Bram Moolenaar00f123a2018-08-21 20:28:54 +02002614swapinfo({fname}) Dict information about swap file {fname}
Bram Moolenaar110bd602018-09-16 18:46:59 +02002615swapname({expr}) String swap file of buffer {expr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002616synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col}
2617synIDattr({synID}, {what} [, {mode}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00002618 String attribute {what} of syntax ID {synID}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002619synIDtrans({synID}) Number translated syntax ID of {synID}
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002620synconcealed({lnum}, {col}) List info about concealing
Bram Moolenaar81edd172016-04-14 13:51:37 +02002621synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col}
2622system({expr} [, {input}]) String output of shell command/filter {expr}
2623systemlist({expr} [, {input}]) List output of shell command/filter {expr}
Bram Moolenaar802a0d92016-06-26 16:17:58 +02002624tabpagebuflist([{arg}]) List list of buffer numbers in tab page
Bram Moolenaar81edd172016-04-14 13:51:37 +02002625tabpagenr([{arg}]) Number number of current or last tab page
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002626tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page
2627taglist({expr} [, {filename}]) List list of tags matching {expr}
Bram Moolenaar446cb832008-06-24 21:56:24 +00002628tagfiles() List tags files used
Bram Moolenaar81edd172016-04-14 13:51:37 +02002629tan({expr}) Float tangent of {expr}
2630tanh({expr}) Float hyperbolic tangent of {expr}
Bram Moolenaar975b5272016-03-15 23:10:59 +01002631tempname() String name for a temporary file
Bram Moolenaard96ff162018-02-18 22:13:29 +01002632term_dumpdiff({filename}, {filename} [, {options}])
2633 Number display difference between two dumps
2634term_dumpload({filename} [, {options}])
2635 Number displaying a screen dump
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01002636term_dumpwrite({buf}, {filename} [, {options}])
Bram Moolenaard96ff162018-02-18 22:13:29 +01002637 none dump terminal window contents
Bram Moolenaare41e3b42017-08-11 16:24:50 +02002638term_getaltscreen({buf}) Number get the alternate screen flag
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002639term_getansicolors({buf}) List get ANSI palette in GUI color mode
Bram Moolenaar45356542017-08-06 17:53:31 +02002640term_getattr({attr}, {what}) Number get the value of attribute {what}
Bram Moolenaar97870002017-07-30 18:28:38 +02002641term_getcursor({buf}) List get the cursor position of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002642term_getjob({buf}) Job get the job associated with a terminal
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002643term_getline({buf}, {row}) String get a line of text from a terminal
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02002644term_getscrolled({buf}) Number get the scroll count of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002645term_getsize({buf}) List get the size of a terminal
Bram Moolenaarb000e322017-07-30 19:38:21 +02002646term_getstatus({buf}) String get the status of a terminal
2647term_gettitle({buf}) String get the title of a terminal
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01002648term_gettty({buf}, [{input}]) String get the tty name of a terminal
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002649term_list() List get the list of terminal buffers
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02002650term_scrape({buf}, {row}) List get row of a terminal screen
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02002651term_sendkeys({buf}, {keys}) none send keystrokes to a terminal
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02002652term_setansicolors({buf}, {colors})
2653 none set ANSI palette in GUI color mode
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002654term_setkill({buf}, {how}) none set signal to stop job in terminal
Bram Moolenaarb5b75622018-03-09 22:22:21 +01002655term_setrestore({buf}, {command}) none set command to restore terminal
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02002656term_setsize({buf}, {rows}, {cols})
2657 none set the size of a terminal
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002658term_start({cmd}, {options}) Number open a terminal window and run a job
Bram Moolenaarf3402b12017-08-06 19:07:08 +02002659term_wait({buf} [, {time}]) Number wait for screen to be updated
Bram Moolenaar8e8df252016-05-25 21:23:21 +02002660test_alloc_fail({id}, {countdown}, {repeat})
2661 none make memory allocation fail
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02002662test_autochdir() none enable 'autochdir' during startup
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002663test_feedinput({string}) none add key sequence to input buffer
Bram Moolenaar574860b2016-05-24 17:33:34 +02002664test_garbagecollect_now() none free memory right now for testing
Bram Moolenaare0c31f62017-03-01 15:07:05 +01002665test_ignore_error({expr}) none ignore a specific error
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01002666test_null_blob() Blob null value for testing
Bram Moolenaar574860b2016-05-24 17:33:34 +02002667test_null_channel() Channel null value for testing
2668test_null_dict() Dict null value for testing
2669test_null_job() Job null value for testing
2670test_null_list() List null value for testing
2671test_null_partial() Funcref null value for testing
2672test_null_string() String null value for testing
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002673test_option_not_set({name}) none reset flag indicating option was set
2674test_override({expr}, {val}) none test with Vim internal overrides
Bram Moolenaarab186732018-09-14 21:27:06 +02002675test_scrollbar({which}, {value}, {dragging})
2676 none scroll in the GUI for testing
Bram Moolenaarc95a3022016-06-12 23:01:46 +02002677test_settime({expr}) none set current time for testing
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02002678timer_info([{id}]) List information about timers
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002679timer_pause({id}, {pause}) none pause or unpause a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002680timer_start({time}, {callback} [, {options}])
Bram Moolenaar975b5272016-03-15 23:10:59 +01002681 Number create a timer
Bram Moolenaar81edd172016-04-14 13:51:37 +02002682timer_stop({timer}) none stop a timer
Bram Moolenaarb73598e2016-08-07 18:22:53 +02002683timer_stopall() none stop all timers
Bram Moolenaar81edd172016-04-14 13:51:37 +02002684tolower({expr}) String the String {expr} switched to lowercase
2685toupper({expr}) String the String {expr} switched to uppercase
2686tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr}
Bram Moolenaar8299df92004-07-10 09:47:34 +00002687 to chars in {tostr}
Bram Moolenaard473c8c2018-08-11 18:00:22 +02002688trim({text} [, {mask}]) String trim characters in {mask} from {text}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002689trunc({expr}) Float truncate Float {expr}
2690type({name}) Number type of variable {name}
2691undofile({name}) String undo file name for {name}
Bram Moolenaara800b422010-06-27 01:15:55 +02002692undotree() List undo file tree
Bram Moolenaar81edd172016-04-14 13:51:37 +02002693uniq({list} [, {func} [, {dict}]])
Bram Moolenaar327aa022014-03-25 18:24:23 +01002694 List remove adjacent duplicates from a list
Bram Moolenaar81edd172016-04-14 13:51:37 +02002695values({dict}) List values in {dict}
2696virtcol({expr}) Number screen column of cursor or mark
2697visualmode([expr]) String last visual mode used
Bram Moolenaar8738fc12013-02-20 17:59:11 +01002698wildmenumode() Number whether 'wildmenu' mode is active
Bram Moolenaar81edd172016-04-14 13:51:37 +02002699win_findbuf({bufnr}) List find windows containing {bufnr}
2700win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab}
2701win_gotoid({expr}) Number go to window with ID {expr}
2702win_id2tabwin({expr}) List get tab and window nr from window ID
2703win_id2win({expr}) Number get window nr from window ID
Bram Moolenaar22044dc2017-12-02 15:43:37 +01002704win_screenpos({nr}) List get screen position of window {nr}
Bram Moolenaar81edd172016-04-14 13:51:37 +02002705winbufnr({nr}) Number buffer number of window {nr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002706wincol() Number window column of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002707winheight({nr}) Number height of window {nr}
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +02002708winlayout([{tabnr}]) List layout of windows in tab {tabnr}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002709winline() Number window line of the cursor
Bram Moolenaar81edd172016-04-14 13:51:37 +02002710winnr([{expr}]) Number number of current window
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002711winrestcmd() String returns command to restore window sizes
Bram Moolenaar81edd172016-04-14 13:51:37 +02002712winrestview({dict}) none restore view of current window
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00002713winsaveview() Dict save view of current window
Bram Moolenaar81edd172016-04-14 13:51:37 +02002714winwidth({nr}) Number width of window {nr}
Bram Moolenaared767a22016-01-03 22:49:16 +01002715wordcount() Dict get byte/char/word statistics
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01002716writefile({object}, {fname} [, {flags}])
2717 Number write |Blob| or |List| of lines to file
Bram Moolenaara06ecab2016-07-16 14:47:36 +02002718xor({expr}, {expr}) Number bitwise XOR
Bram Moolenaar071d4272004-06-13 20:20:40 +00002719
Bram Moolenaar03413f42016-04-12 21:07:15 +02002720
Bram Moolenaar446cb832008-06-24 21:56:24 +00002721abs({expr}) *abs()*
2722 Return the absolute value of {expr}. When {expr} evaluates to
2723 a |Float| abs() returns a |Float|. When {expr} can be
2724 converted to a |Number| abs() returns a |Number|. Otherwise
2725 abs() gives an error message and returns -1.
2726 Examples: >
2727 echo abs(1.456)
2728< 1.456 >
2729 echo abs(-5.456)
2730< 5.456 >
2731 echo abs(-4)
2732< 4
2733 {only available when compiled with the |+float| feature}
2734
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002735
2736acos({expr}) *acos()*
2737 Return the arc cosine of {expr} measured in radians, as a
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002738 |Float| in the range of [0, pi].
2739 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002740 [-1, 1].
2741 Examples: >
2742 :echo acos(0)
2743< 1.570796 >
2744 :echo acos(-0.5)
2745< 2.094395
Bram Moolenaardb84e452010-08-15 13:50:43 +02002746 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002747
2748
Bram Moolenaard8968242019-01-15 22:51:57 +01002749add({object}, {expr}) *add()*
2750 Append the item {expr} to |List| or |Blob| {object}. Returns
2751 the resulting |List| or |Blob|. Examples: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002752 :let alist = add([1, 2, 3], item)
2753 :call add(mylist, "woodstock")
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002754< Note that when {expr} is a |List| it is appended as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002755 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard8968242019-01-15 22:51:57 +01002756 When {object} is a |Blob| then {expr} must be a number.
Bram Moolenaar13065c42005-01-08 16:08:21 +00002757 Use |insert()| to add an item at another position.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002758
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002759
Bram Moolenaard6e256c2011-12-14 15:32:50 +01002760and({expr}, {expr}) *and()*
2761 Bitwise AND on the two arguments. The arguments are converted
2762 to a number. A List, Dict or Float argument causes an error.
2763 Example: >
2764 :let flag = and(bits, 0x80)
2765
2766
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002767append({lnum}, {text}) *append()*
2768 When {text} is a |List|: Append each item of the |List| as a
Bram Moolenaar32466aa2006-02-24 23:53:04 +00002769 text line below line {lnum} in the current buffer.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002770 Otherwise append {text} as one text line below line {lnum} in
Bram Moolenaar748bf032005-02-02 23:04:36 +00002771 the current buffer.
2772 {lnum} can be zero to insert a line before the first one.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002773 Returns 1 for failure ({lnum} out of range or out of memory),
Bram Moolenaar58b85342016-08-14 19:54:54 +02002774 0 for success. Example: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002775 :let failed = append(line('$'), "# THE END")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00002776 :let failed = append(0, ["Chapter 1", "the beginning"])
Bram Moolenaarca851592018-06-06 21:04:07 +02002777
2778appendbufline({expr}, {lnum}, {text}) *appendbufline()*
2779 Like |append()| but append the text in buffer {expr}.
2780
2781 For the use of {expr}, see |bufname()|.
2782
2783 {lnum} is used like with |append()|. Note that using |line()|
2784 would use the current buffer, not the one appending to.
2785 Use "$" to append at the end of the buffer.
2786
2787 On success 0 is returned, on failure 1 is returned.
2788
2789 If {expr} is not a valid buffer or {lnum} is not valid, an
2790 error message is given. Example: >
2791 :let failed = appendbufline(13, 0, "# THE START")
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00002792<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002793 *argc()*
Bram Moolenaare6e39892018-10-25 12:32:11 +02002794argc([{winid}])
2795 The result is the number of files in the argument list. See
2796 |arglist|.
2797 If {winid} is not supplied, the argument list of the current
2798 window is used.
2799 If {winid} is -1, the global argument list is used.
2800 Otherwise {winid} specifies the window of which the argument
2801 list is used: either the window number or the window ID.
2802 Returns -1 if the {winid} argument is invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002803
2804 *argidx()*
2805argidx() The result is the current index in the argument list. 0 is
2806 the first file. argc() - 1 is the last one. See |arglist|.
2807
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002808 *arglistid()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002809arglistid([{winnr} [, {tabnr}]])
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002810 Return the argument list ID. This is a number which
2811 identifies the argument list being used. Zero is used for the
Bram Moolenaarfb539272014-08-22 19:21:47 +02002812 global argument list. See |arglist|.
Bram Moolenaare6e39892018-10-25 12:32:11 +02002813 Returns -1 if the arguments are invalid.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002814
2815 Without arguments use the current window.
2816 With {winnr} only use this window in the current tab page.
2817 With {winnr} and {tabnr} use the window in the specified tab
2818 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02002819 {winnr} can be the window number or the |window-ID|.
Bram Moolenaar2d1fe052014-05-28 18:22:57 +02002820
Bram Moolenaar071d4272004-06-13 20:20:40 +00002821 *argv()*
Bram Moolenaare6e39892018-10-25 12:32:11 +02002822argv([{nr} [, {winid}])
2823 The result is the {nr}th file in the argument list. See
2824 |arglist|. "argv(0)" is the first one. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00002825 :let i = 0
2826 :while i < argc()
Bram Moolenaar446cb832008-06-24 21:56:24 +00002827 : let f = escape(fnameescape(argv(i)), '.')
Bram Moolenaar071d4272004-06-13 20:20:40 +00002828 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>'
2829 : let i = i + 1
2830 :endwhile
Bram Moolenaare6e39892018-10-25 12:32:11 +02002831< Without the {nr} argument, or when {nr} is -1, a |List| with
2832 the whole |arglist| is returned.
2833
2834 The {winid} argument specifies the window ID, see |argc()|.
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002835
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01002836assert_beeps({cmd}) *assert_beeps()*
2837 Run {cmd} and add an error message to |v:errors| if it does
2838 NOT produce a beep or visual bell.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002839 Also see |assert_fails()| and |assert-return|.
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01002840
Bram Moolenaar683fa182015-11-30 21:38:24 +01002841 *assert_equal()*
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002842assert_equal({expected}, {actual} [, {msg}])
Bram Moolenaar43345542015-11-29 17:35:35 +01002843 When {expected} and {actual} are not equal an error message is
Bram Moolenaar65a54642018-04-28 16:56:53 +02002844 added to |v:errors| and 1 is returned. Otherwise zero is
2845 returned |assert-return|.
Bram Moolenaar43345542015-11-29 17:35:35 +01002846 There is no automatic conversion, the String "4" is different
2847 from the Number 4. And the number 4 is different from the
2848 Float 4.0. The value of 'ignorecase' is not used here, case
2849 always matters.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002850 When {msg} is omitted an error in the form "Expected
2851 {expected} but got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002852 Example: >
Bram Moolenaar683fa182015-11-30 21:38:24 +01002853 assert_equal('foo', 'bar')
Bram Moolenaar43345542015-11-29 17:35:35 +01002854< Will result in a string to be added to |v:errors|:
2855 test.vim line 12: Expected 'foo' but got 'bar' ~
2856
Bram Moolenaard96ff162018-02-18 22:13:29 +01002857 *assert_equalfile()*
2858assert_equalfile({fname-one}, {fname-two})
2859 When the files {fname-one} and {fname-two} do not contain
2860 exactly the same text an error message is added to |v:errors|.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002861 Also see |assert-return|.
Bram Moolenaard96ff162018-02-18 22:13:29 +01002862 When {fname-one} or {fname-two} does not exist the error will
2863 mention that.
2864 Mainly useful with |terminal-diff|.
2865
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002866assert_exception({error} [, {msg}]) *assert_exception()*
2867 When v:exception does not contain the string {error} an error
Bram Moolenaar65a54642018-04-28 16:56:53 +02002868 message is added to |v:errors|. Also see |assert-return|.
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002869 This can be used to assert that a command throws an exception.
2870 Using the error number, followed by a colon, avoids problems
2871 with translations: >
2872 try
2873 commandthatfails
2874 call assert_false(1, 'command should have failed')
2875 catch
2876 call assert_exception('E492:')
2877 endtry
2878
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02002879assert_fails({cmd} [, {error} [, {msg}]]) *assert_fails()*
Bram Moolenaara260b872016-01-15 20:48:22 +01002880 Run {cmd} and add an error message to |v:errors| if it does
Bram Moolenaar65a54642018-04-28 16:56:53 +02002881 NOT produce an error. Also see |assert-return|.
Bram Moolenaar25de4c22016-11-06 14:48:06 +01002882 When {error} is given it must match in |v:errmsg|.
Bram Moolenaarb48e96f2018-02-13 12:26:14 +01002883 Note that beeping is not considered an error, and some failing
2884 commands only beep. Use |assert_beeps()| for those.
Bram Moolenaara260b872016-01-15 20:48:22 +01002885
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002886assert_false({actual} [, {msg}]) *assert_false()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002887 When {actual} is not false an error message is added to
Bram Moolenaar9d87a372018-12-18 21:41:50 +01002888 |v:errors|, like with |assert_equal()|.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002889 Also see |assert-return|.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01002890 A value is false when it is zero. When {actual} is not a
Bram Moolenaar43345542015-11-29 17:35:35 +01002891 number the assert fails.
Bram Moolenaar61c04492016-07-23 15:35:35 +02002892 When {msg} is omitted an error in the form
2893 "Expected False but got {actual}" is produced.
2894
2895assert_inrange({lower}, {upper}, {actual} [, {msg}]) *assert_inrange()*
2896 This asserts number values. When {actual} is lower than
2897 {lower} or higher than {upper} an error message is added to
Bram Moolenaar65a54642018-04-28 16:56:53 +02002898 |v:errors|. Also see |assert-return|.
Bram Moolenaar61c04492016-07-23 15:35:35 +02002899 When {msg} is omitted an error in the form
2900 "Expected range {lower} - {upper}, but got {actual}" is
2901 produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002902
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002903 *assert_match()*
2904assert_match({pattern}, {actual} [, {msg}])
2905 When {pattern} does not match {actual} an error message is
Bram Moolenaar65a54642018-04-28 16:56:53 +02002906 added to |v:errors|. Also see |assert-return|.
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002907
2908 {pattern} is used as with |=~|: The matching is always done
2909 like 'magic' was set and 'cpoptions' is empty, no matter what
2910 the actual value of 'magic' or 'cpoptions' is.
2911
2912 {actual} is used as a string, automatic conversion applies.
2913 Use "^" and "$" to match with the start and end of the text.
2914 Use both to match the whole text.
2915
Bram Moolenaar61c04492016-07-23 15:35:35 +02002916 When {msg} is omitted an error in the form
2917 "Pattern {pattern} does not match {actual}" is produced.
Bram Moolenaarea6553b2016-03-27 15:13:38 +02002918 Example: >
2919 assert_match('^f.*o$', 'foobar')
2920< Will result in a string to be added to |v:errors|:
2921 test.vim line 12: Pattern '^f.*o$' does not match 'foobar' ~
2922
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002923 *assert_notequal()*
2924assert_notequal({expected}, {actual} [, {msg}])
2925 The opposite of `assert_equal()`: add an error message to
2926 |v:errors| when {expected} and {actual} are equal.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002927 Also see |assert-return|.
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002928
2929 *assert_notmatch()*
2930assert_notmatch({pattern}, {actual} [, {msg}])
2931 The opposite of `assert_match()`: add an error message to
2932 |v:errors| when {pattern} matches {actual}.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002933 Also see |assert-return|.
Bram Moolenaarb50e5f52016-04-03 20:57:20 +02002934
Bram Moolenaar42205552017-03-18 19:42:22 +01002935assert_report({msg}) *assert_report()*
2936 Report a test failure directly, using {msg}.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002937 Always returns one.
Bram Moolenaar42205552017-03-18 19:42:22 +01002938
2939assert_true({actual} [, {msg}]) *assert_true()*
Bram Moolenaar43345542015-11-29 17:35:35 +01002940 When {actual} is not true an error message is added to
Bram Moolenaara803c7f2016-01-15 15:31:39 +01002941 |v:errors|, like with |assert_equal()|.
Bram Moolenaar65a54642018-04-28 16:56:53 +02002942 Also see |assert-return|.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02002943 A value is TRUE when it is a non-zero number. When {actual}
Bram Moolenaar43345542015-11-29 17:35:35 +01002944 is not a number the assert fails.
Bram Moolenaar683fa182015-11-30 21:38:24 +01002945 When {msg} is omitted an error in the form "Expected True but
2946 got {actual}" is produced.
Bram Moolenaar43345542015-11-29 17:35:35 +01002947
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002948asin({expr}) *asin()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002949 Return the arc sine of {expr} measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002950 in the range of [-pi/2, pi/2].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002951 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002952 [-1, 1].
2953 Examples: >
2954 :echo asin(0.8)
2955< 0.927295 >
2956 :echo asin(-0.5)
2957< -0.523599
Bram Moolenaardb84e452010-08-15 13:50:43 +02002958 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002959
2960
Bram Moolenaar446cb832008-06-24 21:56:24 +00002961atan({expr}) *atan()*
2962 Return the principal value of the arc tangent of {expr}, in
2963 the range [-pi/2, +pi/2] radians, as a |Float|.
2964 {expr} must evaluate to a |Float| or a |Number|.
2965 Examples: >
2966 :echo atan(100)
2967< 1.560797 >
2968 :echo atan(-4.01)
2969< -1.326405
2970 {only available when compiled with the |+float| feature}
2971
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002972
2973atan2({expr1}, {expr2}) *atan2()*
2974 Return the arc tangent of {expr1} / {expr2}, measured in
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02002975 radians, as a |Float| in the range [-pi, pi].
2976 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002977 Examples: >
2978 :echo atan2(-1, 1)
2979< -0.785398 >
2980 :echo atan2(1, -1)
2981< 2.356194
Bram Moolenaardb84e452010-08-15 13:50:43 +02002982 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02002983
Bram Moolenaar246fe032017-11-19 19:56:27 +01002984balloon_show({expr}) *balloon_show()*
2985 Show {expr} inside the balloon. For the GUI {expr} is used as
2986 a string. For a terminal {expr} can be a list, which contains
2987 the lines of the balloon. If {expr} is not a list it will be
2988 split with |balloon_split()|.
2989
Bram Moolenaar214641f2017-03-05 17:04:09 +01002990 Example: >
Bram Moolenaar59716a22017-03-01 20:32:44 +01002991 func GetBalloonContent()
2992 " initiate getting the content
2993 return ''
2994 endfunc
2995 set balloonexpr=GetBalloonContent()
2996
2997 func BalloonCallback(result)
Bram Moolenaar214641f2017-03-05 17:04:09 +01002998 call balloon_show(a:result)
Bram Moolenaar59716a22017-03-01 20:32:44 +01002999 endfunc
3000<
3001 The intended use is that fetching the content of the balloon
3002 is initiated from 'balloonexpr'. It will invoke an
3003 asynchronous method, in which a callback invokes
3004 balloon_show(). The 'balloonexpr' itself can return an
3005 empty string or a placeholder.
Bram Moolenaar214641f2017-03-05 17:04:09 +01003006
3007 When showing a balloon is not possible nothing happens, no
3008 error message.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003009 {only available when compiled with the |+balloon_eval| or
3010 |+balloon_eval_term| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003011
Bram Moolenaar246fe032017-11-19 19:56:27 +01003012balloon_split({msg}) *balloon_split()*
3013 Split {msg} into lines to be displayed in a balloon. The
3014 splits are made for the current window size and optimize to
3015 show debugger output.
3016 Returns a |List| with the split lines.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003017 {only available when compiled with the |+balloon_eval_term|
Bram Moolenaar669a8282017-11-19 20:13:05 +01003018 feature}
Bram Moolenaar246fe032017-11-19 19:56:27 +01003019
Bram Moolenaar071d4272004-06-13 20:20:40 +00003020 *browse()*
3021browse({save}, {title}, {initdir}, {default})
3022 Put up a file requester. This only works when "has("browse")"
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003023 returns |TRUE| (only in some GUI versions).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003024 The input fields are:
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003025 {save} when |TRUE|, select file to write
Bram Moolenaar071d4272004-06-13 20:20:40 +00003026 {title} title for the requester
3027 {initdir} directory to start browsing in
3028 {default} default file name
3029 When the "Cancel" button is hit, something went wrong, or
3030 browsing is not possible, an empty string is returned.
3031
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003032 *browsedir()*
3033browsedir({title}, {initdir})
3034 Put up a directory requester. This only works when
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003035 "has("browse")" returns |TRUE| (only in some GUI versions).
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00003036 On systems where a directory browser is not supported a file
3037 browser is used. In that case: select a file in the directory
3038 to be used.
3039 The input fields are:
3040 {title} title for the requester
3041 {initdir} directory to start browsing in
3042 When the "Cancel" button is hit, something went wrong, or
3043 browsing is not possible, an empty string is returned.
3044
Bram Moolenaar071d4272004-06-13 20:20:40 +00003045bufexists({expr}) *bufexists()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003046 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003047 {expr} exists.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003048 If the {expr} argument is a number, buffer numbers are used.
Bram Moolenaara2a80162017-11-21 23:09:50 +01003049 Number zero is the alternate buffer for the current window.
3050
Bram Moolenaar071d4272004-06-13 20:20:40 +00003051 If the {expr} argument is a string it must match a buffer name
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003052 exactly. The name can be:
3053 - Relative to the current directory.
3054 - A full path.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003055 - The name of a buffer with 'buftype' set to "nofile".
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003056 - A URL name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003057 Unlisted buffers will be found.
3058 Note that help files are listed by their short name in the
3059 output of |:buffers|, but bufexists() requires using their
3060 long name to be able to find them.
Bram Moolenaar446cb832008-06-24 21:56:24 +00003061 bufexists() may report a buffer exists, but to use the name
3062 with a |:buffer| command you may need to use |expand()|. Esp
3063 for MS-Windows 8.3 names in the form "c:\DOCUME~1"
Bram Moolenaar071d4272004-06-13 20:20:40 +00003064 Use "bufexists(0)" to test for the existence of an alternate
3065 file name.
3066 *buffer_exists()*
3067 Obsolete name: buffer_exists().
3068
3069buflisted({expr}) *buflisted()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003070 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003071 {expr} exists and is listed (has the 'buflisted' option set).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003072 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003073
3074bufloaded({expr}) *bufloaded()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003075 The result is a Number, which is |TRUE| if a buffer called
Bram Moolenaar071d4272004-06-13 20:20:40 +00003076 {expr} exists and is loaded (shown in a window or hidden).
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00003077 The {expr} argument is used like with |bufexists()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003078
3079bufname({expr}) *bufname()*
3080 The result is the name of a buffer, as it is displayed by the
3081 ":ls" command.
3082 If {expr} is a Number, that buffer number's name is given.
3083 Number zero is the alternate buffer for the current window.
3084 If {expr} is a String, it is used as a |file-pattern| to match
Bram Moolenaar58b85342016-08-14 19:54:54 +02003085 with the buffer names. This is always done like 'magic' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00003086 set and 'cpoptions' is empty. When there is more than one
3087 match an empty string is returned.
3088 "" or "%" can be used for the current buffer, "#" for the
3089 alternate buffer.
3090 A full match is preferred, otherwise a match at the start, end
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003091 or middle of the buffer name is accepted. If you only want a
3092 full match then put "^" at the start and "$" at the end of the
3093 pattern.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003094 Listed buffers are found first. If there is a single match
3095 with a listed buffer, that one is returned. Next unlisted
3096 buffers are searched for.
3097 If the {expr} is a String, but you want to use it as a buffer
3098 number, force it to be a Number by adding zero to it: >
3099 :echo bufname("3" + 0)
3100< If the buffer doesn't exist, or doesn't have a name, an empty
3101 string is returned. >
3102 bufname("#") alternate buffer name
3103 bufname(3) name of buffer 3
3104 bufname("%") name of current buffer
3105 bufname("file2") name of buffer where "file2" matches.
3106< *buffer_name()*
3107 Obsolete name: buffer_name().
3108
3109 *bufnr()*
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003110bufnr({expr} [, {create}])
3111 The result is the number of a buffer, as it is displayed by
Bram Moolenaar071d4272004-06-13 20:20:40 +00003112 the ":ls" command. For the use of {expr}, see |bufname()|
Bram Moolenaar65c923a2006-03-03 22:56:30 +00003113 above.
3114 If the buffer doesn't exist, -1 is returned. Or, if the
3115 {create} argument is present and not zero, a new, unlisted,
3116 buffer is created and its number is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003117 bufnr("$") is the last buffer: >
3118 :let last_buffer = bufnr("$")
3119< The result is a Number, which is the highest buffer number
3120 of existing buffers. Note that not all buffers with a smaller
3121 number necessarily exist, because ":bwipeout" may have removed
3122 them. Use bufexists() to test for the existence of a buffer.
3123 *buffer_number()*
3124 Obsolete name: buffer_number().
3125 *last_buffer_nr()*
3126 Obsolete name for bufnr("$"): last_buffer_nr().
3127
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003128bufwinid({expr}) *bufwinid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02003129 The result is a Number, which is the |window-ID| of the first
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003130 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02003131 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaarb3619a92016-06-04 17:58:52 +02003132 there is no such window, -1 is returned. Example: >
3133
3134 echo "A window containing buffer 1 is " . (bufwinid(1))
3135<
3136 Only deals with the current tab page.
3137
Bram Moolenaar071d4272004-06-13 20:20:40 +00003138bufwinnr({expr}) *bufwinnr()*
3139 The result is a Number, which is the number of the first
3140 window associated with buffer {expr}. For the use of {expr},
Bram Moolenaar58b85342016-08-14 19:54:54 +02003141 see |bufname()| above. If buffer {expr} doesn't exist or
Bram Moolenaar071d4272004-06-13 20:20:40 +00003142 there is no such window, -1 is returned. Example: >
3143
3144 echo "A window containing buffer 1 is " . (bufwinnr(1))
3145
3146< The number can be used with |CTRL-W_w| and ":wincmd w"
3147 |:wincmd|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003148 Only deals with the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003149
Bram Moolenaar071d4272004-06-13 20:20:40 +00003150byte2line({byte}) *byte2line()*
3151 Return the line number that contains the character at byte
3152 count {byte} in the current buffer. This includes the
3153 end-of-line character, depending on the 'fileformat' option
3154 for the current buffer. The first character has byte count
3155 one.
3156 Also see |line2byte()|, |go| and |:goto|.
3157 {not available when compiled without the |+byte_offset|
3158 feature}
3159
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003160byteidx({expr}, {nr}) *byteidx()*
3161 Return byte index of the {nr}'th character in the string
3162 {expr}. Use zero for the first character, it returns zero.
3163 This function is only useful when there are multibyte
3164 characters, otherwise the returned value is equal to {nr}.
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003165 Composing characters are not counted separately, their byte
3166 length is added to the preceding base character. See
3167 |byteidxcomp()| below for counting composing characters
3168 separately.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003169 Example : >
3170 echo matchstr(str, ".", byteidx(str, 3))
3171< will display the fourth character. Another way to do the
3172 same: >
3173 let s = strpart(str, byteidx(str, 3))
3174 echo strpart(s, 0, byteidx(s, 1))
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02003175< Also see |strgetchar()| and |strcharpart()|.
3176
3177 If there are less than {nr} characters -1 is returned.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003178 If there are exactly {nr} characters the length of the string
Bram Moolenaar0ffbbf92013-11-02 23:29:26 +01003179 in bytes is returned.
3180
3181byteidxcomp({expr}, {nr}) *byteidxcomp()*
3182 Like byteidx(), except that a composing character is counted
3183 as a separate character. Example: >
3184 let s = 'e' . nr2char(0x301)
3185 echo byteidx(s, 1)
3186 echo byteidxcomp(s, 1)
3187 echo byteidxcomp(s, 2)
3188< The first and third echo result in 3 ('e' plus composing
3189 character is 3 bytes), the second echo results in 1 ('e' is
3190 one byte).
3191 Only works different from byteidx() when 'encoding' is set to
3192 a Unicode encoding.
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00003193
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003194call({func}, {arglist} [, {dict}]) *call()* *E699*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003195 Call function {func} with the items in |List| {arglist} as
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003196 arguments.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003197 {func} can either be a |Funcref| or the name of a function.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003198 a:firstline and a:lastline are set to the cursor line.
3199 Returns the return value of the called function.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003200 {dict} is for functions with the "dict" attribute. It will be
3201 used to set the local variable "self". |Dictionary-function|
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003202
Bram Moolenaar446cb832008-06-24 21:56:24 +00003203ceil({expr}) *ceil()*
3204 Return the smallest integral value greater than or equal to
3205 {expr} as a |Float| (round up).
3206 {expr} must evaluate to a |Float| or a |Number|.
3207 Examples: >
3208 echo ceil(1.456)
3209< 2.0 >
3210 echo ceil(-5.456)
3211< -5.0 >
3212 echo ceil(4.0)
3213< 4.0
3214 {only available when compiled with the |+float| feature}
3215
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003216ch_canread({handle}) *ch_canread()*
3217 Return non-zero when there is something to read from {handle}.
3218 {handle} can be a Channel or a Job that has a Channel.
3219
3220 This is useful to read from a channel at a convenient time,
3221 e.g. from a timer.
3222
3223 Note that messages are dropped when the channel does not have
3224 a callback. Add a close callback to avoid that.
3225
3226 {only available when compiled with the |+channel| feature}
3227
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003228ch_close({handle}) *ch_close()*
3229 Close {handle}. See |channel-close|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003230 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar0874a832016-09-01 15:11:51 +02003231 A close callback is not invoked.
3232
3233 {only available when compiled with the |+channel| feature}
3234
3235ch_close_in({handle}) *ch_close_in()*
3236 Close the "in" part of {handle}. See |channel-close-in|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003237 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar0874a832016-09-01 15:11:51 +02003238 A close callback is not invoked.
Bram Moolenaar328da0d2016-03-04 22:22:32 +01003239
Bram Moolenaar835dc632016-02-07 14:27:38 +01003240 {only available when compiled with the |+channel| feature}
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003241
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003242ch_evalexpr({handle}, {expr} [, {options}]) *ch_evalexpr()*
3243 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003244 according to the type of channel. The function cannot be used
Bram Moolenaardae8d212016-02-27 22:40:16 +01003245 with a raw channel. See |channel-use|.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003246 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003247 *E917*
3248 {options} must be a Dictionary. It must not have a "callback"
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003249 entry. It can have a "timeout" entry to specify the timeout
3250 for this specific request.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003251
3252 ch_evalexpr() waits for a response and returns the decoded
3253 expression. When there is an error or timeout it returns an
3254 empty string.
3255
3256 {only available when compiled with the |+channel| feature}
3257
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003258ch_evalraw({handle}, {string} [, {options}]) *ch_evalraw()*
3259 Send {string} over {handle}.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003260 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003261
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003262 Works like |ch_evalexpr()|, but does not encode the request or
3263 decode the response. The caller is responsible for the
3264 correct contents. Also does not add a newline for a channel
3265 in NL mode, the caller must do that. The NL in the response
3266 is removed.
Bram Moolenaar01164a62017-11-02 22:58:42 +01003267 Note that Vim does not know when the text received on a raw
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003268 channel is complete, it may only return the first part and you
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01003269 need to use |ch_readraw()| to fetch the rest.
Bram Moolenaar8b1862a2016-02-27 19:21:24 +01003270 See |channel-use|.
3271
3272 {only available when compiled with the |+channel| feature}
3273
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003274ch_getbufnr({handle}, {what}) *ch_getbufnr()*
3275 Get the buffer number that {handle} is using for {what}.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003276 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaarc7f0ebc2016-02-27 21:10:09 +01003277 {what} can be "err" for stderr, "out" for stdout or empty for
3278 socket output.
3279 Returns -1 when there is no buffer.
3280 {only available when compiled with the |+channel| feature}
3281
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003282ch_getjob({channel}) *ch_getjob()*
3283 Get the Job associated with {channel}.
3284 If there is no job calling |job_status()| on the returned Job
3285 will result in "fail".
3286
3287 {only available when compiled with the |+channel| and
3288 |+job| features}
3289
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003290ch_info({handle}) *ch_info()*
3291 Returns a Dictionary with information about {handle}. The
3292 items are:
3293 "id" number of the channel
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003294 "status" "open", "buffered" or "closed", like
3295 ch_status()
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003296 When opened with ch_open():
3297 "hostname" the hostname of the address
3298 "port" the port of the address
3299 "sock_status" "open" or "closed"
3300 "sock_mode" "NL", "RAW", "JSON" or "JS"
3301 "sock_io" "socket"
3302 "sock_timeout" timeout in msec
3303 When opened with job_start():
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003304 "out_status" "open", "buffered" or "closed"
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003305 "out_mode" "NL", "RAW", "JSON" or "JS"
3306 "out_io" "null", "pipe", "file" or "buffer"
3307 "out_timeout" timeout in msec
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003308 "err_status" "open", "buffered" or "closed"
Bram Moolenaar03602ec2016-03-20 20:57:45 +01003309 "err_mode" "NL", "RAW", "JSON" or "JS"
3310 "err_io" "out", "null", "pipe", "file" or "buffer"
3311 "err_timeout" timeout in msec
3312 "in_status" "open" or "closed"
3313 "in_mode" "NL", "RAW", "JSON" or "JS"
3314 "in_io" "null", "pipe", "file" or "buffer"
3315 "in_timeout" timeout in msec
3316
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003317ch_log({msg} [, {handle}]) *ch_log()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003318 Write {msg} in the channel log file, if it was opened with
3319 |ch_logfile()|.
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003320 When {handle} is passed the channel number is used for the
3321 message.
Bram Moolenaar51628222016-12-01 23:03:28 +01003322 {handle} can be a Channel or a Job that has a Channel. The
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02003323 Channel must be open for the channel number to be used.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003324
3325ch_logfile({fname} [, {mode}]) *ch_logfile()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003326 Start logging channel activity to {fname}.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003327 When {fname} is an empty string: stop logging.
3328
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003329 When {mode} is omitted or "a" append to the file.
3330 When {mode} is "w" start with an empty file.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003331
Bram Moolenaar98aefe72018-12-13 22:20:09 +01003332 Use |ch_log()| to write log messages. The file is flushed
3333 after every message, on Unix you can use "tail -f" to see what
3334 is going on in real time.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003335
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02003336 This function is not available in the |sandbox|.
3337 NOTE: the channel communication is stored in the file, be
3338 aware that this may contain confidential and privacy sensitive
3339 information, e.g. a password you type in a terminal window.
3340
Bram Moolenaar328da0d2016-03-04 22:22:32 +01003341
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003342ch_open({address} [, {options}]) *ch_open()*
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003343 Open a channel to {address}. See |channel|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003344 Returns a Channel. Use |ch_status()| to check for failure.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003345
3346 {address} has the form "hostname:port", e.g.,
3347 "localhost:8765".
3348
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003349 If {options} is given it must be a |Dictionary|.
3350 See |channel-open-options|.
3351
Bram Moolenaar835dc632016-02-07 14:27:38 +01003352 {only available when compiled with the |+channel| feature}
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01003353
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003354ch_read({handle} [, {options}]) *ch_read()*
3355 Read from {handle} and return the received message.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003356 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar74240d32017-12-10 15:26:15 +01003357 For a NL channel this waits for a NL to arrive, except when
3358 there is nothing more to read (channel was closed).
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003359 See |channel-more|.
3360 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003361
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003362ch_readblob({handle} [, {options}]) *ch_readblob()*
Bram Moolenaard09091d2019-01-17 16:07:22 +01003363 Like ch_read() but reads binary data and returns a |Blob|.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003364 See |channel-more|.
3365 {only available when compiled with the |+channel| feature}
3366
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003367ch_readraw({handle} [, {options}]) *ch_readraw()*
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003368 Like ch_read() but for a JS and JSON channel does not decode
Bram Moolenaar74240d32017-12-10 15:26:15 +01003369 the message. For a NL channel it does not block waiting for
3370 the NL to arrive, but otherwise works like ch_read().
3371 See |channel-more|.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003372 {only available when compiled with the |+channel| feature}
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003373
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003374ch_sendexpr({handle}, {expr} [, {options}]) *ch_sendexpr()*
3375 Send {expr} over {handle}. The {expr} is encoded
Bram Moolenaarcbebd482016-02-07 23:02:56 +01003376 according to the type of channel. The function cannot be used
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003377 with a raw channel.
3378 See |channel-use|. *E912*
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003379 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003380
Bram Moolenaar835dc632016-02-07 14:27:38 +01003381 {only available when compiled with the |+channel| feature}
3382
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01003383ch_sendraw({handle}, {expr} [, {options}]) *ch_sendraw()*
Bram Moolenaard09091d2019-01-17 16:07:22 +01003384 Send |String| or |Blob| {expr} over {handle}.
Bram Moolenaarcbebd482016-02-07 23:02:56 +01003385 Works like |ch_sendexpr()|, but does not encode the request or
3386 decode the response. The caller is responsible for the
Bram Moolenaar910b8aa2016-02-16 21:03:07 +01003387 correct contents. Also does not add a newline for a channel
3388 in NL mode, the caller must do that. The NL in the response
3389 is removed.
3390 See |channel-use|.
Bram Moolenaarf57969a2016-02-02 20:47:49 +01003391
Bram Moolenaar835dc632016-02-07 14:27:38 +01003392 {only available when compiled with the |+channel| feature}
3393
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003394ch_setoptions({handle}, {options}) *ch_setoptions()*
3395 Set options on {handle}:
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003396 "callback" the channel callback
3397 "timeout" default read timeout in msec
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003398 "mode" mode for the whole channel
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003399 See |ch_open()| for more explanation.
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003400 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003401
Bram Moolenaar02e83b42016-02-21 20:10:26 +01003402 Note that changing the mode may cause queued messages to be
3403 lost.
3404
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003405 These options cannot be changed:
Bram Moolenaar7571d552016-08-18 22:54:46 +02003406 "waittime" only applies to |ch_open()|
Bram Moolenaare0fa3742016-02-20 15:47:01 +01003407
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003408ch_status({handle} [, {options}]) *ch_status()*
Bram Moolenaar5f148ec2016-03-07 22:59:26 +01003409 Return the status of {handle}:
Bram Moolenaar38a55632016-02-15 22:07:32 +01003410 "fail" failed to open the channel
3411 "open" channel can be used
Bram Moolenaar06481422016-04-30 15:13:38 +02003412 "buffered" channel can be read, not written to
Bram Moolenaar38a55632016-02-15 22:07:32 +01003413 "closed" channel can not be used
Bram Moolenaar4b785f62016-11-29 21:54:44 +01003414 {handle} can be a Channel or a Job that has a Channel.
Bram Moolenaar06481422016-04-30 15:13:38 +02003415 "buffered" is used when the channel was closed but there is
3416 still data that can be obtained with |ch_read()|.
Bram Moolenaar38a55632016-02-15 22:07:32 +01003417
Bram Moolenaar7ef38102016-09-26 22:36:58 +02003418 If {options} is given it can contain a "part" entry to specify
3419 the part of the channel to return the status for: "out" or
3420 "err". For example, to get the error status: >
3421 ch_status(job, {"part": "err"})
3422<
Bram Moolenaar214641f2017-03-05 17:04:09 +01003423changenr() *changenr()*
3424 Return the number of the most recent change. This is the same
3425 number as what is displayed with |:undolist| and can be used
3426 with the |:undo| command.
3427 When a change was made it is the number of that change. After
3428 redo it is the number of the redone change. After undo it is
3429 one less than the number of the undone change.
3430
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003431char2nr({expr} [, {utf8}]) *char2nr()*
Bram Moolenaar214641f2017-03-05 17:04:09 +01003432 Return number value of the first char in {expr}. Examples: >
3433 char2nr(" ") returns 32
3434 char2nr("ABC") returns 65
3435< When {utf8} is omitted or zero, the current 'encoding' is used.
3436 Example for "utf-8": >
Bram Moolenaar98ef2332018-03-18 14:44:37 +01003437 char2nr("á") returns 225
3438 char2nr("á"[0]) returns 195
Bram Moolenaar214641f2017-03-05 17:04:09 +01003439< With {utf8} set to 1, always treat as utf-8 characters.
3440 A combining character is a separate character.
3441 |nr2char()| does the opposite.
3442
3443cindent({lnum}) *cindent()*
3444 Get the amount of indent for line {lnum} according the C
3445 indenting rules, as with 'cindent'.
3446 The indent is counted in spaces, the value of 'tabstop' is
3447 relevant. {lnum} is used just like in |getline()|.
3448 When {lnum} is invalid or Vim was not compiled the |+cindent|
3449 feature, -1 is returned.
3450 See |C-indenting|.
3451
3452clearmatches() *clearmatches()*
3453 Clears all matches previously defined by |matchadd()| and the
3454 |:match| commands.
3455
3456 *col()*
3457col({expr}) The result is a Number, which is the byte index of the column
3458 position given with {expr}. The accepted positions are:
3459 . the cursor position
3460 $ the end of the cursor line (the result is the
3461 number of bytes in the cursor line plus one)
3462 'x position of mark x (if the mark is not set, 0 is
3463 returned)
3464 v In Visual mode: the start of the Visual area (the
3465 cursor is the end). When not in Visual mode
3466 returns the cursor position. Differs from |'<| in
3467 that it's updated right away.
3468 Additionally {expr} can be [lnum, col]: a |List| with the line
3469 and column number. Most useful when the column is "$", to get
3470 the last column of a specific line. When "lnum" or "col" is
3471 out of range then col() returns zero.
3472 To get the line number use |line()|. To get both use
3473 |getpos()|.
3474 For the screen column position use |virtcol()|.
3475 Note that only marks in the current file can be used.
3476 Examples: >
3477 col(".") column of cursor
3478 col("$") length of cursor line plus one
3479 col("'t") column of mark t
3480 col("'" . markname) column of mark markname
3481< The first column is 1. 0 is returned for an error.
3482 For an uppercase mark the column may actually be in another
3483 buffer.
3484 For the cursor position, when 'virtualedit' is active, the
3485 column is one higher if the cursor is after the end of the
3486 line. This can be used to obtain the column in Insert mode: >
3487 :imap <F2> <C-O>:let save_ve = &ve<CR>
3488 \<C-O>:set ve=all<CR>
3489 \<C-O>:echo col(".") . "\n" <Bar>
3490 \let &ve = save_ve<CR>
3491<
3492
3493complete({startcol}, {matches}) *complete()* *E785*
3494 Set the matches for Insert mode completion.
3495 Can only be used in Insert mode. You need to use a mapping
3496 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O
3497 or with an expression mapping.
3498 {startcol} is the byte offset in the line where the completed
3499 text start. The text up to the cursor is the original text
3500 that will be replaced by the matches. Use col('.') for an
3501 empty string. "col('.') - 1" will replace one character by a
3502 match.
3503 {matches} must be a |List|. Each |List| item is one match.
3504 See |complete-items| for the kind of items that are possible.
3505 Note that the after calling this function you need to avoid
3506 inserting anything that would cause completion to stop.
3507 The match can be selected with CTRL-N and CTRL-P as usual with
3508 Insert mode completion. The popup menu will appear if
3509 specified, see |ins-completion-menu|.
3510 Example: >
3511 inoremap <F5> <C-R>=ListMonths()<CR>
3512
3513 func! ListMonths()
3514 call complete(col('.'), ['January', 'February', 'March',
3515 \ 'April', 'May', 'June', 'July', 'August', 'September',
3516 \ 'October', 'November', 'December'])
3517 return ''
3518 endfunc
3519< This isn't very useful, but it shows how it works. Note that
3520 an empty string is returned to avoid a zero being inserted.
3521
3522complete_add({expr}) *complete_add()*
3523 Add {expr} to the list of matches. Only to be used by the
3524 function specified with the 'completefunc' option.
3525 Returns 0 for failure (empty string or out of memory),
3526 1 when the match was added, 2 when the match was already in
3527 the list.
3528 See |complete-functions| for an explanation of {expr}. It is
3529 the same as one item in the list that 'omnifunc' would return.
3530
3531complete_check() *complete_check()*
3532 Check for a key typed while looking for completion matches.
3533 This is to be used when looking for matches takes some time.
3534 Returns |TRUE| when searching for matches is to be aborted,
3535 zero otherwise.
3536 Only to be used by the function specified with the
3537 'completefunc' option.
3538
3539 *confirm()*
3540confirm({msg} [, {choices} [, {default} [, {type}]]])
3541 Confirm() offers the user a dialog, from which a choice can be
3542 made. It returns the number of the choice. For the first
3543 choice this is 1.
3544 Note: confirm() is only supported when compiled with dialog
3545 support, see |+dialog_con| and |+dialog_gui|.
3546
3547 {msg} is displayed in a |dialog| with {choices} as the
3548 alternatives. When {choices} is missing or empty, "&OK" is
3549 used (and translated).
3550 {msg} is a String, use '\n' to include a newline. Only on
3551 some systems the string is wrapped when it doesn't fit.
3552
3553 {choices} is a String, with the individual choices separated
3554 by '\n', e.g. >
3555 confirm("Save changes?", "&Yes\n&No\n&Cancel")
3556< The letter after the '&' is the shortcut key for that choice.
3557 Thus you can type 'c' to select "Cancel". The shortcut does
3558 not need to be the first letter: >
3559 confirm("file has been modified", "&Save\nSave &All")
3560< For the console, the first letter of each choice is used as
3561 the default shortcut key.
3562
3563 The optional {default} argument is the number of the choice
3564 that is made if the user hits <CR>. Use 1 to make the first
3565 choice the default one. Use 0 to not set a default. If
3566 {default} is omitted, 1 is used.
3567
3568 The optional {type} argument gives the type of dialog. This
3569 is only used for the icon of the GTK, Mac, Motif and Win32
3570 GUI. It can be one of these values: "Error", "Question",
3571 "Info", "Warning" or "Generic". Only the first character is
3572 relevant. When {type} is omitted, "Generic" is used.
3573
3574 If the user aborts the dialog by pressing <Esc>, CTRL-C,
3575 or another valid interrupt key, confirm() returns 0.
3576
3577 An example: >
3578 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2)
3579 :if choice == 0
3580 : echo "make up your mind!"
3581 :elseif choice == 3
3582 : echo "tasteful"
3583 :else
3584 : echo "I prefer bananas myself."
3585 :endif
3586< In a GUI dialog, buttons are used. The layout of the buttons
3587 depends on the 'v' flag in 'guioptions'. If it is included,
3588 the buttons are always put vertically. Otherwise, confirm()
3589 tries to put the buttons in one horizontal line. If they
3590 don't fit, a vertical layout is used anyway. For some systems
3591 the horizontal layout is always used.
3592
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003593 *copy()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003594copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003595 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003596 When {expr} is a |List| a shallow copy is created. This means
3597 that the original |List| can be changed without changing the
Bram Moolenaar446cb832008-06-24 21:56:24 +00003598 copy, and vice versa. But the items are identical, thus
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01003599 changing an item changes the contents of both |Lists|.
3600 A |Dictionary| is copied in a similar way as a |List|.
3601 Also see |deepcopy()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003602
Bram Moolenaar446cb832008-06-24 21:56:24 +00003603cos({expr}) *cos()*
3604 Return the cosine of {expr}, measured in radians, as a |Float|.
3605 {expr} must evaluate to a |Float| or a |Number|.
3606 Examples: >
3607 :echo cos(100)
3608< 0.862319 >
3609 :echo cos(-4.01)
3610< -0.646043
3611 {only available when compiled with the |+float| feature}
3612
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003613
3614cosh({expr}) *cosh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003615 Return the hyperbolic cosine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003616 [1, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003617 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003618 Examples: >
3619 :echo cosh(0.5)
3620< 1.127626 >
3621 :echo cosh(-0.5)
3622< -1.127626
Bram Moolenaardb84e452010-08-15 13:50:43 +02003623 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003624
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003625
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003626count({comp}, {expr} [, {ic} [, {start}]]) *count()*
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003627 Return the number of times an item with value {expr} appears
Bram Moolenaar9966b212017-07-28 16:46:57 +02003628 in |String|, |List| or |Dictionary| {comp}.
3629
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00003630 If {start} is given then start with the item with this index.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003631 {start} can only be used with a |List|.
Bram Moolenaar9966b212017-07-28 16:46:57 +02003632
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003633 When {ic} is given and it's |TRUE| then case is ignored.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003634
Bram Moolenaar9966b212017-07-28 16:46:57 +02003635 When {comp} is a string then the number of not overlapping
Bram Moolenaar338e47f2017-12-19 11:55:26 +01003636 occurrences of {expr} is returned. Zero is returned when
3637 {expr} is an empty string.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00003638
Bram Moolenaar071d4272004-06-13 20:20:40 +00003639 *cscope_connection()*
3640cscope_connection([{num} , {dbpath} [, {prepend}]])
3641 Checks for the existence of a |cscope| connection. If no
3642 parameters are specified, then the function returns:
3643 0, if cscope was not available (not compiled in), or
3644 if there are no cscope connections;
3645 1, if there is at least one cscope connection.
3646
3647 If parameters are specified, then the value of {num}
3648 determines how existence of a cscope connection is checked:
3649
3650 {num} Description of existence check
3651 ----- ------------------------------
3652 0 Same as no parameters (e.g., "cscope_connection()").
3653 1 Ignore {prepend}, and use partial string matches for
3654 {dbpath}.
3655 2 Ignore {prepend}, and use exact string matches for
3656 {dbpath}.
3657 3 Use {prepend}, use partial string matches for both
3658 {dbpath} and {prepend}.
3659 4 Use {prepend}, use exact string matches for both
3660 {dbpath} and {prepend}.
3661
3662 Note: All string comparisons are case sensitive!
3663
3664 Examples. Suppose we had the following (from ":cs show"): >
3665
3666 # pid database name prepend path
3667 0 27664 cscope.out /usr/local
3668<
3669 Invocation Return Val ~
3670 ---------- ---------- >
3671 cscope_connection() 1
3672 cscope_connection(1, "out") 1
3673 cscope_connection(2, "out") 0
3674 cscope_connection(3, "out") 0
3675 cscope_connection(3, "out", "local") 1
3676 cscope_connection(4, "out") 0
3677 cscope_connection(4, "out", "local") 0
3678 cscope_connection(4, "cscope.out", "/usr/local") 1
3679<
Bram Moolenaar0b238792006-03-02 22:49:12 +00003680cursor({lnum}, {col} [, {off}]) *cursor()*
3681cursor({list})
Bram Moolenaaref2f6562007-05-06 13:32:59 +00003682 Positions the cursor at the column (byte count) {col} in the
3683 line {lnum}. The first column is one.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003684
Bram Moolenaar0b238792006-03-02 22:49:12 +00003685 When there is one argument {list} this is used as a |List|
Bram Moolenaar493c1782014-05-28 14:34:46 +02003686 with two, three or four item:
Bram Moolenaar03413f42016-04-12 21:07:15 +02003687 [{lnum}, {col}]
Bram Moolenaar493c1782014-05-28 14:34:46 +02003688 [{lnum}, {col}, {off}]
3689 [{lnum}, {col}, {off}, {curswant}]
Bram Moolenaar946e27a2014-06-25 18:50:27 +02003690 This is like the return value of |getpos()| or |getcurpos()|,
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003691 but without the first item.
Bram Moolenaar493c1782014-05-28 14:34:46 +02003692
Bram Moolenaar071d4272004-06-13 20:20:40 +00003693 Does not change the jumplist.
3694 If {lnum} is greater than the number of lines in the buffer,
3695 the cursor will be positioned at the last line in the buffer.
3696 If {lnum} is zero, the cursor will stay in the current line.
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00003697 If {col} is greater than the number of bytes in the line,
Bram Moolenaar071d4272004-06-13 20:20:40 +00003698 the cursor will be positioned at the last character in the
3699 line.
3700 If {col} is zero, the cursor will stay in the current column.
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02003701 If {curswant} is given it is used to set the preferred column
Bram Moolenaar34401cc2014-08-29 15:12:19 +02003702 for vertical movement. Otherwise {col} is used.
Bram Moolenaar2f3b5102014-11-19 18:54:17 +01003703
Bram Moolenaar0b238792006-03-02 22:49:12 +00003704 When 'virtualedit' is used {off} specifies the offset in
3705 screen columns from the start of the character. E.g., a
Bram Moolenaard46bbc72007-05-12 14:38:41 +00003706 position within a <Tab> or after the last character.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00003707 Returns 0 when the position could be set, -1 otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003708
Bram Moolenaar4551c0a2018-06-20 22:38:21 +02003709debugbreak({pid}) *debugbreak()*
3710 Specifically used to interrupt a program being debugged. It
3711 will cause process {pid} to get a SIGTRAP. Behavior for other
3712 processes is undefined. See |terminal-debugger|.
3713 {only available on MS-Windows}
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003714
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003715deepcopy({expr} [, {noref}]) *deepcopy()* *E698*
Bram Moolenaar58b85342016-08-14 19:54:54 +02003716 Make a copy of {expr}. For Numbers and Strings this isn't
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003717 different from using {expr} directly.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003718 When {expr} is a |List| a full copy is created. This means
3719 that the original |List| can be changed without changing the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01003720 copy, and vice versa. When an item is a |List| or
3721 |Dictionary|, a copy for it is made, recursively. Thus
3722 changing an item in the copy does not change the contents of
3723 the original |List|.
3724 A |Dictionary| is copied in a similar way as a |List|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003725 When {noref} is omitted or zero a contained |List| or
3726 |Dictionary| is only copied once. All references point to
3727 this single copy. With {noref} set to 1 every occurrence of a
3728 |List| or |Dictionary| results in a new copy. This also means
3729 that a cyclic reference causes deepcopy() to fail.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00003730 *E724*
3731 Nesting is possible up to 100 levels. When there is an item
Bram Moolenaar4399ef42005-02-12 14:29:27 +00003732 that refers back to a higher level making a deep copy with
3733 {noref} set to 1 will fail.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00003734 Also see |copy()|.
3735
Bram Moolenaarda440d22016-01-16 21:27:23 +01003736delete({fname} [, {flags}]) *delete()*
3737 Without {flags} or with {flags} empty: Deletes the file by the
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003738 name {fname}. This also works when {fname} is a symbolic link.
Bram Moolenaarda440d22016-01-16 21:27:23 +01003739
3740 When {flags} is "d": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003741 {fname}. This fails when directory {fname} is not empty.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003742
Bram Moolenaarda440d22016-01-16 21:27:23 +01003743 When {flags} is "rf": Deletes the directory by the name
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003744 {fname} and everything in it, recursively. BE CAREFUL!
Bram Moolenaar36f44c22016-08-28 18:17:20 +02003745 Note: on MS-Windows it is not possible to delete a directory
3746 that is being used.
Bram Moolenaar818078d2016-08-27 21:58:42 +02003747
Bram Moolenaar43a34f92016-01-17 15:56:34 +01003748 A symbolic link itself is deleted, not what it points to.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003749
Bram Moolenaarda440d22016-01-16 21:27:23 +01003750 The result is a Number, which is 0 if the delete operation was
3751 successful and -1 when the deletion failed or partly failed.
3752
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003753 Use |remove()| to delete an item from a |List|.
Bram Moolenaard79a2622018-06-07 18:17:46 +02003754 To delete a line from the buffer use |:delete| or
3755 |deletebufline()|.
3756
Bram Moolenaard473c8c2018-08-11 18:00:22 +02003757deletebufline({expr}, {first} [, {last}]) *deletebufline()*
Bram Moolenaard79a2622018-06-07 18:17:46 +02003758 Delete lines {first} to {last} (inclusive) from buffer {expr}.
3759 If {last} is omitted then delete line {first} only.
3760 On success 0 is returned, on failure 1 is returned.
3761
3762 For the use of {expr}, see |bufname()| above.
3763
Bram Moolenaar95bafa22018-10-02 13:26:25 +02003764 {first} and {last} are used like with |getline()|. Note that
Bram Moolenaard79a2622018-06-07 18:17:46 +02003765 when using |line()| this refers to the current buffer. Use "$"
3766 to refer to the last line in buffer {expr}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003767
3768 *did_filetype()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003769did_filetype() Returns |TRUE| when autocommands are being executed and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00003770 FileType event has been triggered at least once. Can be used
3771 to avoid triggering the FileType event again in the scripts
3772 that detect the file type. |FileType|
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +02003773 Returns |FALSE| when `:setf FALLBACK` was used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003774 When editing another file, the counter is reset, thus this
3775 really checks if the FileType event has been triggered for the
3776 current buffer. This allows an autocommand that starts
3777 editing another buffer to set 'filetype' and load a syntax
3778 file.
3779
Bram Moolenaar47136d72004-10-12 20:02:24 +00003780diff_filler({lnum}) *diff_filler()*
3781 Returns the number of filler lines above line {lnum}.
3782 These are the lines that were inserted at this point in
3783 another diff'ed window. These filler lines are shown in the
3784 display but don't exist in the buffer.
3785 {lnum} is used like with |getline()|. Thus "." is the current
3786 line, "'m" mark m, etc.
3787 Returns 0 if the current window is not in diff mode.
3788
3789diff_hlID({lnum}, {col}) *diff_hlID()*
3790 Returns the highlight ID for diff mode at line {lnum} column
3791 {col} (byte index). When the current line does not have a
3792 diff change zero is returned.
3793 {lnum} is used like with |getline()|. Thus "." is the current
3794 line, "'m" mark m, etc.
3795 {col} is 1 for the leftmost column, {lnum} is 1 for the first
3796 line.
3797 The highlight ID can be used with |synIDattr()| to obtain
3798 syntax information about the highlighting.
3799
Bram Moolenaar13065c42005-01-08 16:08:21 +00003800empty({expr}) *empty()*
3801 Return the Number 1 if {expr} is empty, zero otherwise.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003802 - A |List| or |Dictionary| is empty when it does not have any
3803 items.
Bram Moolenaard8968242019-01-15 22:51:57 +01003804 - A |String| is empty when its length is zero.
3805 - A |Number| and |Float| are empty when their value is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003806 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not.
Bram Moolenaard8968242019-01-15 22:51:57 +01003807 - A |Job| is empty when it failed to start.
3808 - A |Channel| is empty when it is closed.
Bram Moolenaard09091d2019-01-17 16:07:22 +01003809 - A |Blob| is empty when its length is zero.
Bram Moolenaar835dc632016-02-07 14:27:38 +01003810
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003811 For a long |List| this is much faster than comparing the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003812 length with zero.
Bram Moolenaar13065c42005-01-08 16:08:21 +00003813
Bram Moolenaar071d4272004-06-13 20:20:40 +00003814escape({string}, {chars}) *escape()*
3815 Escape the characters in {chars} that occur in {string} with a
3816 backslash. Example: >
3817 :echo escape('c:\program files\vim', ' \')
3818< results in: >
3819 c:\\program\ files\\vim
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02003820< Also see |shellescape()| and |fnameescape()|.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003821
Bram Moolenaar446cb832008-06-24 21:56:24 +00003822 *eval()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003823eval({string}) Evaluate {string} and return the result. Especially useful to
3824 turn the result of |string()| back into the original value.
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01003825 This works for Numbers, Floats, Strings, Blobs and composites
3826 of them. Also works for |Funcref|s that refer to existing
Bram Moolenaar446cb832008-06-24 21:56:24 +00003827 functions.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00003828
Bram Moolenaar071d4272004-06-13 20:20:40 +00003829eventhandler() *eventhandler()*
3830 Returns 1 when inside an event handler. That is that Vim got
3831 interrupted while waiting for the user to type a character,
3832 e.g., when dropping a file on Vim. This means interactive
3833 commands cannot be used. Otherwise zero is returned.
3834
3835executable({expr}) *executable()*
3836 This function checks if an executable with the name {expr}
3837 exists. {expr} must be the name of the program without any
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003838 arguments.
3839 executable() uses the value of $PATH and/or the normal
3840 searchpath for programs. *PATHEXT*
3841 On MS-DOS and MS-Windows the ".exe", ".bat", etc. can
3842 optionally be included. Then the extensions in $PATHEXT are
Bram Moolenaar58b85342016-08-14 19:54:54 +02003843 tried. Thus if "foo.exe" does not exist, "foo.exe.bat" can be
3844 found. If $PATHEXT is not set then ".exe;.com;.bat;.cmd" is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003845 used. A dot by itself can be used in $PATHEXT to try using
Bram Moolenaar58b85342016-08-14 19:54:54 +02003846 the name without an extension. When 'shell' looks like a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003847 Unix shell, then the name is also tried without adding an
3848 extension.
3849 On MS-DOS and MS-Windows it only checks if the file exists and
3850 is not a directory, not if it's really executable.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003851 On MS-Windows an executable in the same directory as Vim is
3852 always found. Since this directory is added to $PATH it
3853 should also work to execute it |win32-PATH|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003854 The result is a Number:
3855 1 exists
3856 0 does not exist
3857 -1 not implemented on this system
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02003858 |exepath()| can be used to get the full path of an executable.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003859
Bram Moolenaar79815f12016-07-09 17:07:29 +02003860execute({command} [, {silent}]) *execute()*
3861 Execute an Ex command or commands and return the output as a
3862 string.
3863 {command} can be a string or a List. In case of a List the
3864 lines are executed one by one.
3865 This is equivalent to: >
3866 redir => var
3867 {command}
3868 redir END
3869<
3870 The optional {silent} argument can have these values:
3871 "" no `:silent` used
3872 "silent" `:silent` used
3873 "silent!" `:silent!` used
Bram Moolenaar214641f2017-03-05 17:04:09 +01003874 The default is "silent". Note that with "silent!", unlike
Bram Moolenaar069c1e72016-07-15 21:25:08 +02003875 `:redir`, error messages are dropped. When using an external
3876 command the screen may be messed up, use `system()` instead.
Bram Moolenaar79815f12016-07-09 17:07:29 +02003877 *E930*
3878 It is not possible to use `:redir` anywhere in {command}.
3879
3880 To get a list of lines use |split()| on the result: >
Bram Moolenaar063b9d12016-07-09 20:21:48 +02003881 split(execute('args'), "\n")
Bram Moolenaar79815f12016-07-09 17:07:29 +02003882
3883< When used recursively the output of the recursive call is not
3884 included in the output of the higher level call.
3885
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003886exepath({expr}) *exepath()*
3887 If {expr} is an executable and is either an absolute path, a
3888 relative path or found in $PATH, return the full path.
3889 Note that the current directory is used when {expr} starts
3890 with "./", which may be a problem for Vim: >
3891 echo exepath(v:progpath)
Bram Moolenaar7e38ea22014-04-05 22:55:53 +02003892< If {expr} cannot be found in $PATH or is not executable then
Bram Moolenaarc7f02552014-04-01 21:00:59 +02003893 an empty string is returned.
3894
Bram Moolenaar071d4272004-06-13 20:20:40 +00003895 *exists()*
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02003896exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined,
3897 zero otherwise.
3898
3899 For checking for a supported feature use |has()|.
3900 For checking if a file exists use |filereadable()|.
3901
3902 The {expr} argument is a string, which contains one of these:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003903 &option-name Vim option (only checks if it exists,
3904 not if it really works)
3905 +option-name Vim option that works.
3906 $ENVNAME environment variable (could also be
3907 done by comparing with an empty
3908 string)
3909 *funcname built-in function (see |functions|)
3910 or user defined function (see
Bram Moolenaarbcb98982014-05-01 14:08:19 +02003911 |user-functions|). Also works for a
3912 variable that is a Funcref.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003913 varname internal variable (see
Bram Moolenaar58b85342016-08-14 19:54:54 +02003914 |internal-variables|). Also works
Bram Moolenaar32466aa2006-02-24 23:53:04 +00003915 for |curly-braces-names|, |Dictionary|
3916 entries, |List| items, etc. Beware
Bram Moolenaarc236c162008-07-13 17:41:49 +00003917 that evaluating an index may cause an
3918 error message for an invalid
3919 expression. E.g.: >
3920 :let l = [1, 2, 3]
3921 :echo exists("l[5]")
3922< 0 >
3923 :echo exists("l[xx]")
3924< E121: Undefined variable: xx
3925 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00003926 :cmdname Ex command: built-in command, user
3927 command or command modifier |:command|.
3928 Returns:
3929 1 for match with start of a command
3930 2 full match with a command
3931 3 matches several user commands
3932 To check for a supported command
3933 always check the return value to be 2.
Bram Moolenaar14716812006-05-04 21:54:08 +00003934 :2match The |:2match| command.
3935 :3match The |:3match| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003936 #event autocommand defined for this event
3937 #event#pattern autocommand defined for this event and
3938 pattern (the pattern is taken
3939 literally and compared to the
3940 autocommand patterns character by
3941 character)
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003942 #group autocommand group exists
3943 #group#event autocommand defined for this group and
3944 event.
3945 #group#event#pattern
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003946 autocommand defined for this group,
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003947 event and pattern.
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003948 ##event autocommand for this event is
3949 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003950
3951 Examples: >
3952 exists("&shortname")
3953 exists("$HOSTNAME")
3954 exists("*strftime")
3955 exists("*s:MyFunc")
3956 exists("bufcount")
3957 exists(":Make")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003958 exists("#CursorHold")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003959 exists("#BufReadPre#*.gz")
Bram Moolenaara9b1e742005-12-19 22:14:58 +00003960 exists("#filetypeindent")
3961 exists("#filetypeindent#FileType")
3962 exists("#filetypeindent#FileType#*")
Bram Moolenaarf4cd3e82005-12-22 22:47:02 +00003963 exists("##ColorScheme")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003964< There must be no space between the symbol (&/$/*/#) and the
3965 name.
Bram Moolenaar91170f82006-05-05 21:15:17 +00003966 There must be no extra characters after the name, although in
3967 a few cases this is ignored. That may become more strict in
3968 the future, thus don't count on it!
3969 Working example: >
3970 exists(":make")
3971< NOT working example: >
3972 exists(":make install")
Bram Moolenaar9c102382006-05-03 21:26:49 +00003973
3974< Note that the argument must be a string, not the name of the
3975 variable itself. For example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003976 exists(bufcount)
3977< This doesn't check for existence of the "bufcount" variable,
Bram Moolenaar06a89a52006-04-29 22:01:03 +00003978 but gets the value of "bufcount", and checks if that exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003979
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003980exp({expr}) *exp()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003981 Return the exponential of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003982 [0, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003983 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003984 Examples: >
3985 :echo exp(2)
3986< 7.389056 >
3987 :echo exp(-1)
3988< 0.367879
Bram Moolenaardb84e452010-08-15 13:50:43 +02003989 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02003990
3991
Bram Moolenaar84f72352012-03-11 15:57:40 +01003992expand({expr} [, {nosuf} [, {list}]]) *expand()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003993 Expand wildcards and the following special keywords in {expr}.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003994 'wildignorecase' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003995
Bram Moolenaare381d3d2016-07-07 14:50:41 +02003996 If {list} is given and it is |TRUE|, a List will be returned.
Bram Moolenaar84f72352012-03-11 15:57:40 +01003997 Otherwise the result is a String and when there are several
3998 matches, they are separated by <NL> characters. [Note: in
3999 version 5.0 a space was used, which caused problems when a
4000 file name contains a space]
Bram Moolenaar071d4272004-06-13 20:20:40 +00004001
Bram Moolenaar58b85342016-08-14 19:54:54 +02004002 If the expansion fails, the result is an empty string. A name
Bram Moolenaarec7944a2013-06-12 21:29:15 +02004003 for a non-existing file is not included, unless {expr} does
4004 not start with '%', '#' or '<', see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004005
4006 When {expr} starts with '%', '#' or '<', the expansion is done
4007 like for the |cmdline-special| variables with their associated
4008 modifiers. Here is a short overview:
4009
4010 % current file name
4011 # alternate file name
4012 #n alternate file name n
4013 <cfile> file name under the cursor
4014 <afile> autocmd file name
4015 <abuf> autocmd buffer number (as a String!)
4016 <amatch> autocmd matched name
Bram Moolenaara6878372014-03-22 21:02:50 +01004017 <sfile> sourced script file or function name
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02004018 <slnum> sourced script line number or function
4019 line number
4020 <sflnum> script file line number, also when in
4021 a function
Bram Moolenaar071d4272004-06-13 20:20:40 +00004022 <cword> word under the cursor
4023 <cWORD> WORD under the cursor
4024 <client> the {clientid} of the last received
4025 message |server2client()|
4026 Modifiers:
4027 :p expand to full path
4028 :h head (last path component removed)
4029 :t tail (last path component only)
4030 :r root (one extension removed)
4031 :e extension only
4032
4033 Example: >
4034 :let &tags = expand("%:p:h") . "/tags"
4035< Note that when expanding a string that starts with '%', '#' or
4036 '<', any following text is ignored. This does NOT work: >
4037 :let doesntwork = expand("%:h.bak")
4038< Use this: >
4039 :let doeswork = expand("%:h") . ".bak"
4040< Also note that expanding "<cfile>" and others only returns the
4041 referenced file name without further expansion. If "<cfile>"
4042 is "~/.cshrc", you need to do another expand() to have the
4043 "~/" expanded into the path of the home directory: >
4044 :echo expand(expand("<cfile>"))
4045<
4046 There cannot be white space between the variables and the
4047 following modifier. The |fnamemodify()| function can be used
4048 to modify normal file names.
4049
4050 When using '%' or '#', and the current or alternate file name
4051 is not defined, an empty string is used. Using "%:p" in a
4052 buffer with no name, results in the current directory, with a
4053 '/' added.
4054
4055 When {expr} does not start with '%', '#' or '<', it is
4056 expanded like a file name is expanded on the command line.
4057 'suffixes' and 'wildignore' are used, unless the optional
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004058 {nosuf} argument is given and it is |TRUE|.
Bram Moolenaar146e9c32012-03-07 19:18:23 +01004059 Names for non-existing files are included. The "**" item can
4060 be used to search in a directory tree. For example, to find
4061 all "README" files in the current directory and below: >
Bram Moolenaar02743632005-07-25 20:42:36 +00004062 :echo expand("**/README")
4063<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004064 Expand() can also be used to expand variables and environment
4065 variables that are only known in a shell. But this can be
Bram Moolenaar34401cc2014-08-29 15:12:19 +02004066 slow, because a shell may be used to do the expansion. See
4067 |expr-env-expand|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004068 The expanded variable is still handled like a list of file
Bram Moolenaar58b85342016-08-14 19:54:54 +02004069 names. When an environment variable cannot be expanded, it is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004070 left unchanged. Thus ":echo expand('$FOOBAR')" results in
4071 "$FOOBAR".
4072
4073 See |glob()| for finding existing files. See |system()| for
4074 getting the raw output of an external command.
4075
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004076extend({expr1}, {expr2} [, {expr3}]) *extend()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004077 {expr1} and {expr2} must be both |Lists| or both
4078 |Dictionaries|.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004079
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004080 If they are |Lists|: Append {expr2} to {expr1}.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004081 If {expr3} is given insert the items of {expr2} before item
4082 {expr3} in {expr1}. When {expr3} is zero insert before the
4083 first item. When {expr3} is equal to len({expr1}) then
4084 {expr2} is appended.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004085 Examples: >
4086 :echo sort(extend(mylist, [7, 5]))
4087 :call extend(mylist, [2, 3], 1)
Bram Moolenaardc9cf9c2008-08-08 10:36:31 +00004088< When {expr1} is the same List as {expr2} then the number of
4089 items copied is equal to the original length of the List.
4090 E.g., when {expr3} is 1 you get N new copies of the first item
4091 (where N is the original length of the List).
Bram Moolenaar58b85342016-08-14 19:54:54 +02004092 Use |add()| to concatenate one item to a list. To concatenate
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004093 two lists into a new list use the + operator: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004094 :let newlist = [1, 2, 3] + [4, 5]
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004095<
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004096 If they are |Dictionaries|:
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004097 Add all entries from {expr2} to {expr1}.
4098 If a key exists in both {expr1} and {expr2} then {expr3} is
4099 used to decide what to do:
4100 {expr3} = "keep": keep the value of {expr1}
4101 {expr3} = "force": use the value of {expr2}
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00004102 {expr3} = "error": give an error message *E737*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004103 When {expr3} is omitted then "force" is assumed.
4104
4105 {expr1} is changed when {expr2} is not empty. If necessary
4106 make a copy of {expr1} first.
4107 {expr2} remains unchanged.
Bram Moolenaarf2571c62015-06-09 19:44:55 +02004108 When {expr1} is locked and {expr2} is not empty the operation
4109 fails.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004110 Returns {expr1}.
4111
Bram Moolenaarde8866b2005-01-06 23:24:37 +00004112
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004113feedkeys({string} [, {mode}]) *feedkeys()*
4114 Characters in {string} are queued for processing as if they
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004115 come from a mapping or were typed by the user.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004116
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004117 By default the string is added to the end of the typeahead
4118 buffer, thus if a mapping is still being executed the
4119 characters come after them. Use the 'i' flag to insert before
4120 other characters, they will be executed next, before any
4121 characters from a mapping.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004122
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004123 The function does not wait for processing of keys contained in
4124 {string}.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004125
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004126 To include special keys into {string}, use double-quotes
4127 and "\..." notation |expr-quote|. For example,
Bram Moolenaar79166c42007-05-10 18:29:51 +00004128 feedkeys("\<CR>") simulates pressing of the <Enter> key. But
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004129 feedkeys('\<CR>') pushes 5 characters.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004130
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004131 {mode} is a String, which can contain these character flags:
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004132 'm' Remap keys. This is default. If {mode} is absent,
4133 keys are remapped.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00004134 'n' Do not remap keys.
4135 't' Handle keys as if typed; otherwise they are handled as
4136 if coming from a mapping. This matters for undo,
4137 opening folds, etc.
Bram Moolenaar5e66b422019-01-24 21:58:10 +01004138 'L' Lowlevel input. Only works for Unix or when using the
4139 GUI. Keys are used as if they were coming from the
4140 terminal. Other flags are not used. *E980*
Bram Moolenaar0a988df2015-01-27 15:19:24 +01004141 'i' Insert the string instead of appending (see above).
Bram Moolenaar25281632016-01-21 23:32:32 +01004142 'x' Execute commands until typeahead is empty. This is
4143 similar to using ":normal!". You can call feedkeys()
4144 several times without 'x' and then one time with 'x'
4145 (possibly with an empty {string}) to execute all the
Bram Moolenaar03413f42016-04-12 21:07:15 +02004146 typeahead. Note that when Vim ends in Insert mode it
4147 will behave as if <Esc> is typed, to avoid getting
4148 stuck, waiting for a character to be typed before the
4149 script continues.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004150 Note that if you manage to call feedkeys() while
Bram Moolenaar5b69c222019-01-11 14:50:06 +01004151 executing commands, thus calling it recursively, then
Bram Moolenaarb328cca2019-01-06 16:24:01 +01004152 all typehead will be consumed by the last call.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004153 '!' When used with 'x' will not end Insert mode. Can be
4154 used in a test when a timer is set to exit Insert mode
4155 a little later. Useful for testing CursorHoldI.
4156
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004157 Return value is always 0.
4158
Bram Moolenaar071d4272004-06-13 20:20:40 +00004159filereadable({file}) *filereadable()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004160 The result is a Number, which is |TRUE| when a file with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00004161 name {file} exists, and can be read. If {file} doesn't exist,
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004162 or is a directory, the result is |FALSE|. {file} is any
Bram Moolenaar071d4272004-06-13 20:20:40 +00004163 expression, which is used as a String.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004164 If you don't care about the file being readable you can use
4165 |glob()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004166 *file_readable()*
4167 Obsolete name: file_readable().
4168
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004169
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004170filewritable({file}) *filewritable()*
4171 The result is a Number, which is 1 when a file with the
4172 name {file} exists, and can be written. If {file} doesn't
Bram Moolenaar446cb832008-06-24 21:56:24 +00004173 exist, or is not writable, the result is 0. If {file} is a
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004174 directory, and we can write to it, the result is 2.
4175
4176
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004177filter({expr1}, {expr2}) *filter()*
4178 {expr1} must be a |List| or a |Dictionary|.
4179 For each item in {expr1} evaluate {expr2} and when the result
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004180 is zero remove the item from the |List| or |Dictionary|.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004181 {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004182
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004183 If {expr2} is a |string|, inside {expr2} |v:val| has the value
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004184 of the current item. For a |Dictionary| |v:key| has the key
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004185 of the current item and for a |List| |v:key| has the index of
4186 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004187 Examples: >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004188 call filter(mylist, 'v:val !~ "OLD"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004189< Removes the items where "OLD" appears. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004190 call filter(mydict, 'v:key >= 8')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004191< Removes the items with a key below 8. >
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004192 call filter(var, 0)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004193< Removes all the items, thus clears the |List| or |Dictionary|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00004194
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004195 Note that {expr2} is the result of expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004196 used as an expression again. Often it is good to use a
4197 |literal-string| to avoid having to double backslashes.
4198
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004199 If {expr2} is a |Funcref| it must take two arguments:
4200 1. the key or the index of the current item.
4201 2. the value of the current item.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02004202 The function must return |TRUE| if the item should be kept.
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004203 Example that keeps the odd items of a list: >
4204 func Odd(idx, val)
4205 return a:idx % 2 == 1
4206 endfunc
4207 call filter(mylist, function('Odd'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02004208< It is shorter when using a |lambda|: >
4209 call filter(myList, {idx, val -> idx * val <= 42})
4210< If you do not use "val" you can leave it out: >
4211 call filter(myList, {idx -> idx % 2 == 1})
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02004212<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004213 The operation is done in-place. If you want a |List| or
4214 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00004215 :let l = filter(copy(mylist), 'v:val =~ "KEEP"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004216
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02004217< Returns {expr1}, the |List| or |Dictionary| that was filtered.
4218 When an error is encountered while evaluating {expr2} no
4219 further items in {expr1} are processed. When {expr2} is a
4220 Funcref errors inside a function are ignored, unless it was
4221 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004222
4223
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004224finddir({name} [, {path} [, {count}]]) *finddir()*
Bram Moolenaar5b6b1ca2007-03-27 08:19:43 +00004225 Find directory {name} in {path}. Supports both downwards and
4226 upwards recursive directory searches. See |file-searching|
4227 for the syntax of {path}.
4228 Returns the path of the first found match. When the found
4229 directory is below the current directory a relative path is
4230 returned. Otherwise a full path is returned.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004231 If {path} is omitted or empty then 'path' is used.
4232 If the optional {count} is given, find {count}'s occurrence of
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004233 {name} in {path} instead of the first one.
Bram Moolenaar899dddf2006-03-26 21:06:50 +00004234 When {count} is negative return all the matches in a |List|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004235 This is quite similar to the ex-command |:find|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02004236 {only available when compiled with the |+file_in_path|
4237 feature}
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004238
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004239findfile({name} [, {path} [, {count}]]) *findfile()*
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00004240 Just like |finddir()|, but find a file instead of a directory.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00004241 Uses 'suffixesadd'.
4242 Example: >
4243 :echo findfile("tags.vim", ".;")
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004244< Searches from the directory of the current file upwards until
4245 it finds the file "tags.vim".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004246
Bram Moolenaar446cb832008-06-24 21:56:24 +00004247float2nr({expr}) *float2nr()*
4248 Convert {expr} to a Number by omitting the part after the
4249 decimal point.
4250 {expr} must evaluate to a |Float| or a Number.
4251 When the value of {expr} is out of range for a |Number| the
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004252 result is truncated to 0x7fffffff or -0x7fffffff (or when
4253 64-bit Number support is enabled, 0x7fffffffffffffff or
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02004254 -0x7fffffffffffffff). NaN results in -0x80000000 (or when
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004255 64-bit Number support is enabled, -0x8000000000000000).
Bram Moolenaar446cb832008-06-24 21:56:24 +00004256 Examples: >
4257 echo float2nr(3.95)
4258< 3 >
4259 echo float2nr(-23.45)
4260< -23 >
4261 echo float2nr(1.0e100)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004262< 2147483647 (or 9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004263 echo float2nr(-1.0e150)
Bram Moolenaar22fcfad2016-07-01 18:17:26 +02004264< -2147483647 (or -9223372036854775807) >
Bram Moolenaar446cb832008-06-24 21:56:24 +00004265 echo float2nr(1.0e-100)
4266< 0
4267 {only available when compiled with the |+float| feature}
4268
4269
4270floor({expr}) *floor()*
4271 Return the largest integral value less than or equal to
4272 {expr} as a |Float| (round down).
4273 {expr} must evaluate to a |Float| or a |Number|.
4274 Examples: >
4275 echo floor(1.856)
4276< 1.0 >
4277 echo floor(-5.456)
4278< -6.0 >
4279 echo floor(4.0)
4280< 4.0
4281 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004282
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004283
4284fmod({expr1}, {expr2}) *fmod()*
4285 Return the remainder of {expr1} / {expr2}, even if the
4286 division is not representable. Returns {expr1} - i * {expr2}
4287 for some integer i such that if {expr2} is non-zero, the
4288 result has the same sign as {expr1} and magnitude less than
4289 the magnitude of {expr2}. If {expr2} is zero, the value
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004290 returned is zero. The value returned is a |Float|.
4291 {expr1} and {expr2} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004292 Examples: >
4293 :echo fmod(12.33, 1.22)
4294< 0.13 >
4295 :echo fmod(-12.33, 1.22)
4296< -0.13
Bram Moolenaardb84e452010-08-15 13:50:43 +02004297 {only available when compiled with |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02004298
4299
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004300fnameescape({string}) *fnameescape()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004301 Escape {string} for use as file name command argument. All
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004302 characters that have a special meaning, such as '%' and '|'
4303 are escaped with a backslash.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004304 For most systems the characters escaped are
4305 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash
4306 appears in a filename, it depends on the value of 'isfname'.
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004307 A leading '+' and '>' is also escaped (special after |:edit|
4308 and |:write|). And a "-" by itself (special after |:cd|).
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004309 Example: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004310 :let fname = '+some str%nge|name'
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004311 :exe "edit " . fnameescape(fname)
4312< results in executing: >
Bram Moolenaar1b24e4b2008-08-08 10:59:17 +00004313 edit \+some\ str\%nge\|name
Bram Moolenaaraebaf892008-05-28 14:49:58 +00004314
Bram Moolenaar071d4272004-06-13 20:20:40 +00004315fnamemodify({fname}, {mods}) *fnamemodify()*
4316 Modify file name {fname} according to {mods}. {mods} is a
4317 string of characters like it is used for file names on the
4318 command line. See |filename-modifiers|.
4319 Example: >
4320 :echo fnamemodify("main.c", ":p:h")
4321< results in: >
4322 /home/mool/vim/vim/src
Bram Moolenaar446cb832008-06-24 21:56:24 +00004323< Note: Environment variables don't work in {fname}, use
Bram Moolenaar071d4272004-06-13 20:20:40 +00004324 |expand()| first then.
4325
4326foldclosed({lnum}) *foldclosed()*
4327 The result is a Number. If the line {lnum} is in a closed
4328 fold, the result is the number of the first line in that fold.
4329 If the line {lnum} is not in a closed fold, -1 is returned.
4330
4331foldclosedend({lnum}) *foldclosedend()*
4332 The result is a Number. If the line {lnum} is in a closed
4333 fold, the result is the number of the last line in that fold.
4334 If the line {lnum} is not in a closed fold, -1 is returned.
4335
4336foldlevel({lnum}) *foldlevel()*
4337 The result is a Number, which is the foldlevel of line {lnum}
Bram Moolenaar58b85342016-08-14 19:54:54 +02004338 in the current buffer. For nested folds the deepest level is
Bram Moolenaar071d4272004-06-13 20:20:40 +00004339 returned. If there is no fold at line {lnum}, zero is
4340 returned. It doesn't matter if the folds are open or closed.
4341 When used while updating folds (from 'foldexpr') -1 is
4342 returned for lines where folds are still to be updated and the
4343 foldlevel is unknown. As a special case the level of the
4344 previous line is usually available.
4345
4346 *foldtext()*
4347foldtext() Returns a String, to be displayed for a closed fold. This is
4348 the default function used for the 'foldtext' option and should
4349 only be called from evaluating 'foldtext'. It uses the
4350 |v:foldstart|, |v:foldend| and |v:folddashes| variables.
4351 The returned string looks like this: >
4352 +-- 45 lines: abcdef
Bram Moolenaar42205552017-03-18 19:42:22 +01004353< The number of leading dashes depends on the foldlevel. The
4354 "45" is the number of lines in the fold. "abcdef" is the text
4355 in the first non-blank line of the fold. Leading white space,
4356 "//" or "/*" and the text from the 'foldmarker' and
4357 'commentstring' options is removed.
4358 When used to draw the actual foldtext, the rest of the line
4359 will be filled with the fold char from the 'fillchars'
4360 setting.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004361 {not available when compiled without the |+folding| feature}
4362
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00004363foldtextresult({lnum}) *foldtextresult()*
4364 Returns the text that is displayed for the closed fold at line
4365 {lnum}. Evaluates 'foldtext' in the appropriate context.
4366 When there is no closed fold at {lnum} an empty string is
4367 returned.
4368 {lnum} is used like with |getline()|. Thus "." is the current
4369 line, "'m" mark m, etc.
4370 Useful when exporting folded text, e.g., to HTML.
4371 {not available when compiled without the |+folding| feature}
4372
Bram Moolenaar071d4272004-06-13 20:20:40 +00004373 *foreground()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02004374foreground() Move the Vim window to the foreground. Useful when sent from
Bram Moolenaar071d4272004-06-13 20:20:40 +00004375 a client to a Vim server. |remote_send()|
4376 On Win32 systems this might not work, the OS does not always
4377 allow a window to bring itself to the foreground. Use
4378 |remote_foreground()| instead.
4379 {only in the Win32, Athena, Motif and GTK GUI versions and the
4380 Win32 console version}
4381
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004382 *funcref()*
4383funcref({name} [, {arglist}] [, {dict}])
4384 Just like |function()|, but the returned Funcref will lookup
4385 the function by reference, not by name. This matters when the
4386 function {name} is redefined later.
4387
4388 Unlike |function()|, {name} must be an existing user function.
4389 Also for autoloaded functions. {name} cannot be a builtin
4390 function.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004391
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004392 *function()* *E700* *E922* *E923*
4393function({name} [, {arglist}] [, {dict}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004394 Return a |Funcref| variable that refers to function {name}.
Bram Moolenaar975b5272016-03-15 23:10:59 +01004395 {name} can be the name of a user defined function or an
4396 internal function.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00004397
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004398 {name} can also be a Funcref or a partial. When it is a
Bram Moolenaar975b5272016-03-15 23:10:59 +01004399 partial the dict stored in it will be used and the {dict}
4400 argument is not allowed. E.g.: >
4401 let FuncWithArg = function(dict.Func, [arg])
4402 let Broken = function(dict.Func, [arg], dict)
4403<
Bram Moolenaar437bafe2016-08-01 15:40:54 +02004404 When using the Funcref the function will be found by {name},
4405 also when it was redefined later. Use |funcref()| to keep the
4406 same function.
4407
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004408 When {arglist} or {dict} is present this creates a partial.
Bram Moolenaar06d2d382016-05-20 17:24:11 +02004409 That means the argument list and/or the dictionary is stored in
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004410 the Funcref and will be used when the Funcref is called.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004411
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004412 The arguments are passed to the function in front of other
4413 arguments. Example: >
4414 func Callback(arg1, arg2, name)
4415 ...
4416 let Func = function('Callback', ['one', 'two'])
4417 ...
4418 call Func('name')
4419< Invokes the function as with: >
4420 call Callback('one', 'two', 'name')
4421
Bram Moolenaar03602ec2016-03-20 20:57:45 +01004422< The function() call can be nested to add more arguments to the
4423 Funcref. The extra arguments are appended to the list of
4424 arguments. Example: >
4425 func Callback(arg1, arg2, name)
4426 ...
4427 let Func = function('Callback', ['one'])
4428 let Func2 = function(Func, ['two'])
4429 ...
4430 call Func2('name')
4431< Invokes the function as with: >
4432 call Callback('one', 'two', 'name')
4433
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004434< The Dictionary is only useful when calling a "dict" function.
4435 In that case the {dict} is passed in as "self". Example: >
4436 function Callback() dict
4437 echo "called for " . self.name
4438 endfunction
4439 ...
4440 let context = {"name": "example"}
4441 let Func = function('Callback', context)
4442 ...
4443 call Func() " will echo: called for example
Bram Moolenaar975b5272016-03-15 23:10:59 +01004444< The use of function() is not needed when there are no extra
4445 arguments, these two are equivalent: >
4446 let Func = function('Callback', context)
4447 let Func = context.Callback
Bram Moolenaar1735bc92016-03-14 23:05:14 +01004448
4449< The argument list and the Dictionary can be combined: >
4450 function Callback(arg1, count) dict
4451 ...
4452 let context = {"name": "example"}
4453 let Func = function('Callback', ['one'], context)
4454 ...
4455 call Func(500)
4456< Invokes the function as with: >
4457 call context.Callback('one', 500)
4458
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004459
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004460garbagecollect([{atexit}]) *garbagecollect()*
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004461 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs|
4462 that have circular references.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004463
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004464 There is hardly ever a need to invoke this function, as it is
4465 automatically done when Vim runs out of memory or is waiting
4466 for the user to press a key after 'updatetime'. Items without
4467 circular references are always freed when they become unused.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004468 This is useful if you have deleted a very big |List| and/or
4469 |Dictionary| with circular references in a script that runs
4470 for a long time.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004471
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004472 When the optional {atexit} argument is one, garbage
Bram Moolenaar9d2c8c12007-09-25 16:00:00 +00004473 collection will also be done when exiting Vim, if it wasn't
4474 done before. This is useful when checking for memory leaks.
Bram Moolenaar39a58ca2005-06-27 22:42:44 +00004475
Bram Moolenaar574860b2016-05-24 17:33:34 +02004476 The garbage collection is not done immediately but only when
4477 it's safe to perform. This is when waiting for the user to
4478 type a character. To force garbage collection immediately use
4479 |test_garbagecollect_now()|.
Bram Moolenaarebf7dfa2016-04-14 12:46:51 +02004480
Bram Moolenaar677ee682005-01-27 14:41:15 +00004481get({list}, {idx} [, {default}]) *get()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004482 Get item {idx} from |List| {list}. When this item is not
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004483 available return {default}. Return zero when {default} is
4484 omitted.
Bram Moolenaard8968242019-01-15 22:51:57 +01004485get({blob}, {idx} [, {default}])
4486 Get byte {idx} from |Blob| {blob}. When this byte is not
4487 available return {default}. Return -1 when {default} is
4488 omitted.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004489get({dict}, {key} [, {default}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004490 Get item with key {key} from |Dictionary| {dict}. When this
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004491 item is not available return {default}. Return zero when
4492 {default} is omitted.
Bram Moolenaar03e19a02016-05-24 22:29:49 +02004493get({func}, {what})
4494 Get an item with from Funcref {func}. Possible values for
Bram Moolenaar2bbf8ef2016-05-24 18:37:12 +02004495 {what} are:
Bram Moolenaar214641f2017-03-05 17:04:09 +01004496 "name" The function name
4497 "func" The function
4498 "dict" The dictionary
4499 "args" The list with arguments
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00004500
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004501 *getbufinfo()*
4502getbufinfo([{expr}])
4503getbufinfo([{dict}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02004504 Get information about buffers as a List of Dictionaries.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004505
4506 Without an argument information about all the buffers is
4507 returned.
4508
4509 When the argument is a Dictionary only the buffers matching
4510 the specified criteria are returned. The following keys can
4511 be specified in {dict}:
4512 buflisted include only listed buffers.
4513 bufloaded include only loaded buffers.
Bram Moolenaar8e6a31d2017-12-10 21:06:22 +01004514 bufmodified include only modified buffers.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004515
4516 Otherwise, {expr} specifies a particular buffer to return
4517 information for. For the use of {expr}, see |bufname()|
4518 above. If the buffer is found the returned List has one item.
4519 Otherwise the result is an empty list.
4520
4521 Each returned List item is a dictionary with the following
4522 entries:
Bram Moolenaar33928832016-08-18 21:22:04 +02004523 bufnr buffer number.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004524 changed TRUE if the buffer is modified.
4525 changedtick number of changes made to the buffer.
4526 hidden TRUE if the buffer is hidden.
4527 listed TRUE if the buffer is listed.
4528 lnum current line number in buffer.
4529 loaded TRUE if the buffer is loaded.
4530 name full path to the file in the buffer.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004531 signs list of signs placed in the buffer.
4532 Each list item is a dictionary with
4533 the following fields:
4534 id sign identifier
4535 lnum line number
4536 name sign name
Bram Moolenaar30567352016-08-27 21:25:44 +02004537 variables a reference to the dictionary with
4538 buffer-local variables.
4539 windows list of |window-ID|s that display this
4540 buffer
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004541
4542 Examples: >
4543 for buf in getbufinfo()
4544 echo buf.name
4545 endfor
4546 for buf in getbufinfo({'buflisted':1})
Bram Moolenaar30567352016-08-27 21:25:44 +02004547 if buf.changed
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02004548 ....
4549 endif
4550 endfor
4551<
Bram Moolenaar30567352016-08-27 21:25:44 +02004552 To get buffer-local options use: >
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004553 getbufvar({bufnr}, '&option_name')
Bram Moolenaar30567352016-08-27 21:25:44 +02004554
4555<
Bram Moolenaar45360022005-07-21 21:08:21 +00004556 *getbufline()*
4557getbufline({expr}, {lnum} [, {end}])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004558 Return a |List| with the lines starting from {lnum} to {end}
4559 (inclusive) in the buffer {expr}. If {end} is omitted, a
4560 |List| with only the line {lnum} is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004561
4562 For the use of {expr}, see |bufname()| above.
4563
Bram Moolenaar661b1822005-07-28 22:36:45 +00004564 For {lnum} and {end} "$" can be used for the last line of the
4565 buffer. Otherwise a number must be used.
Bram Moolenaar45360022005-07-21 21:08:21 +00004566
4567 When {lnum} is smaller than 1 or bigger than the number of
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004568 lines in the buffer, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004569
4570 When {end} is greater than the number of lines in the buffer,
4571 it is treated as {end} is set to the number of lines in the
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004572 buffer. When {end} is before {lnum} an empty |List| is
Bram Moolenaar45360022005-07-21 21:08:21 +00004573 returned.
4574
Bram Moolenaar661b1822005-07-28 22:36:45 +00004575 This function works only for loaded buffers. For unloaded and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004576 non-existing buffers, an empty |List| is returned.
Bram Moolenaar45360022005-07-21 21:08:21 +00004577
4578 Example: >
4579 :let lines = getbufline(bufnr("myfile"), 1, "$")
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004580
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004581getbufvar({expr}, {varname} [, {def}]) *getbufvar()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004582 The result is the value of option or local buffer variable
4583 {varname} in buffer {expr}. Note that the name without "b:"
4584 must be used.
Bram Moolenaarc236c162008-07-13 17:41:49 +00004585 When {varname} is empty returns a dictionary with all the
4586 buffer-local variables.
Bram Moolenaar30567352016-08-27 21:25:44 +02004587 When {varname} is equal to "&" returns a dictionary with all
4588 the buffer-local options.
4589 Otherwise, when {varname} starts with "&" returns the value of
4590 a buffer-local option.
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00004591 This also works for a global or buffer-local option, but it
4592 doesn't work for a global variable, window-local variable or
4593 window-local option.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004594 For the use of {expr}, see |bufname()| above.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01004595 When the buffer or variable doesn't exist {def} or an empty
4596 string is returned, there is no error message.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004597 Examples: >
4598 :let bufmodified = getbufvar(1, "&mod")
4599 :echo "todo myvar = " . getbufvar("todo", "myvar")
4600<
Bram Moolenaar07ad8162018-02-13 13:59:59 +01004601getchangelist({expr}) *getchangelist()*
4602 Returns the |changelist| for the buffer {expr}. For the use
4603 of {expr}, see |bufname()| above. If buffer {expr} doesn't
4604 exist, an empty list is returned.
4605
4606 The returned list contains two entries: a list with the change
4607 locations and the current position in the list. Each
4608 entry in the change list is a dictionary with the following
4609 entries:
4610 col column number
4611 coladd column offset for 'virtualedit'
4612 lnum line number
4613 If buffer {expr} is the current buffer, then the current
4614 position refers to the position in the list. For other
4615 buffers, it is set to the length of the list.
4616
Bram Moolenaar071d4272004-06-13 20:20:40 +00004617getchar([expr]) *getchar()*
Bram Moolenaar91170f82006-05-05 21:15:17 +00004618 Get a single character from the user or input stream.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004619 If [expr] is omitted, wait until a character is available.
4620 If [expr] is 0, only get a character when one is available.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004621 Return zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004622 If [expr] is 1, only check if a character is available, it is
Bram Moolenaar91170f82006-05-05 21:15:17 +00004623 not consumed. Return zero if no character available.
4624
Bram Moolenaardfb18412013-12-11 18:53:29 +01004625 Without [expr] and when [expr] is 0 a whole character or
Bram Moolenaarc577d812017-07-08 22:37:34 +02004626 special key is returned. If it is a single character, the
Bram Moolenaar91170f82006-05-05 21:15:17 +00004627 result is a number. Use nr2char() to convert it to a String.
4628 Otherwise a String is returned with the encoded character.
Bram Moolenaarc577d812017-07-08 22:37:34 +02004629 For a special key it's a String with a sequence of bytes
4630 starting with 0x80 (decimal: 128). This is the same value as
4631 the String "\<Key>", e.g., "\<Left>". The returned value is
4632 also a String when a modifier (shift, control, alt) was used
4633 that is not included in the character.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004634
Bram Moolenaar822ff862014-06-12 21:46:14 +02004635 When [expr] is 0 and Esc is typed, there will be a short delay
4636 while Vim waits to see if this is the start of an escape
4637 sequence.
4638
Bram Moolenaardfb18412013-12-11 18:53:29 +01004639 When [expr] is 1 only the first byte is returned. For a
Bram Moolenaar56a907a2006-05-06 21:44:30 +00004640 one-byte character it is the character itself as a number.
4641 Use nr2char() to convert it to a String.
Bram Moolenaar91170f82006-05-05 21:15:17 +00004642
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004643 Use getcharmod() to obtain any additional modifiers.
4644
Bram Moolenaar219b8702006-11-01 14:32:36 +00004645 When the user clicks a mouse button, the mouse event will be
4646 returned. The position can then be found in |v:mouse_col|,
Bram Moolenaar511972d2016-06-04 18:09:59 +02004647 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. This
4648 example positions the mouse as it would normally happen: >
Bram Moolenaar219b8702006-11-01 14:32:36 +00004649 let c = getchar()
Bram Moolenaar446cb832008-06-24 21:56:24 +00004650 if c == "\<LeftMouse>" && v:mouse_win > 0
Bram Moolenaar219b8702006-11-01 14:32:36 +00004651 exe v:mouse_win . "wincmd w"
4652 exe v:mouse_lnum
4653 exe "normal " . v:mouse_col . "|"
4654 endif
4655<
Bram Moolenaar690afe12017-01-28 18:34:47 +01004656 When using bracketed paste only the first character is
4657 returned, the rest of the pasted text is dropped.
4658 |xterm-bracketed-paste|.
4659
Bram Moolenaar071d4272004-06-13 20:20:40 +00004660 There is no prompt, you will somehow have to make clear to the
4661 user that a character has to be typed.
4662 There is no mapping for the character.
4663 Key codes are replaced, thus when the user presses the <Del>
4664 key you get the code for the <Del> key, not the raw character
4665 sequence. Examples: >
4666 getchar() == "\<Del>"
4667 getchar() == "\<S-Left>"
4668< This example redefines "f" to ignore case: >
4669 :nmap f :call FindChar()<CR>
4670 :function FindChar()
4671 : let c = nr2char(getchar())
4672 : while col('.') < col('$') - 1
4673 : normal l
4674 : if getline('.')[col('.') - 1] ==? c
4675 : break
4676 : endif
4677 : endwhile
4678 :endfunction
Bram Moolenaared32d942014-12-06 23:33:00 +01004679<
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01004680 You may also receive synthetic characters, such as
Bram Moolenaared32d942014-12-06 23:33:00 +01004681 |<CursorHold>|. Often you will want to ignore this and get
4682 another character: >
4683 :function GetKey()
4684 : let c = getchar()
4685 : while c == "\<CursorHold>"
4686 : let c = getchar()
4687 : endwhile
4688 : return c
4689 :endfunction
Bram Moolenaar071d4272004-06-13 20:20:40 +00004690
4691getcharmod() *getcharmod()*
4692 The result is a Number which is the state of the modifiers for
4693 the last obtained character with getchar() or in another way.
4694 These values are added together:
4695 2 shift
4696 4 control
4697 8 alt (meta)
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01004698 16 meta (when it's different from ALT)
4699 32 mouse double click
4700 64 mouse triple click
4701 96 mouse quadruple click (== 32 + 64)
4702 128 command (Macintosh only)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004703 Only the modifiers that have not been included in the
Bram Moolenaar58b85342016-08-14 19:54:54 +02004704 character itself are obtained. Thus Shift-a results in "A"
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004705 without a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004706
Bram Moolenaardbd24b52015-08-11 14:26:19 +02004707getcharsearch() *getcharsearch()*
4708 Return the current character search information as a {dict}
4709 with the following entries:
4710
4711 char character previously used for a character
4712 search (|t|, |f|, |T|, or |F|); empty string
4713 if no character search has been performed
4714 forward direction of character search; 1 for forward,
4715 0 for backward
4716 until type of character search; 1 for a |t| or |T|
4717 character search, 0 for an |f| or |F|
4718 character search
4719
4720 This can be useful to always have |;| and |,| search
4721 forward/backward regardless of the direction of the previous
4722 character search: >
4723 :nnoremap <expr> ; getcharsearch().forward ? ';' : ','
4724 :nnoremap <expr> , getcharsearch().forward ? ',' : ';'
4725< Also see |setcharsearch()|.
4726
Bram Moolenaar071d4272004-06-13 20:20:40 +00004727getcmdline() *getcmdline()*
4728 Return the current command-line. Only works when the command
4729 line is being edited, thus requires use of |c_CTRL-\_e| or
4730 |c_CTRL-R_=|.
4731 Example: >
4732 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004733< Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004734 Returns an empty string when entering a password or using
4735 |inputsecret()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004736
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00004737getcmdpos() *getcmdpos()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004738 Return the position of the cursor in the command line as a
4739 byte count. The first column is 1.
4740 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02004741 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4742 Returns 0 otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004743 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|.
4744
4745getcmdtype() *getcmdtype()*
4746 Return the current command-line type. Possible return values
4747 are:
Bram Moolenaar1e015462005-09-25 22:16:38 +00004748 : normal Ex command
4749 > debug mode command |debug-mode|
4750 / forward search command
4751 ? backward search command
4752 @ |input()| command
4753 - |:insert| or |:append| command
Bram Moolenaar6e932462014-09-09 18:48:09 +02004754 = |i_CTRL-R_=|
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004755 Only works when editing the command line, thus requires use of
Bram Moolenaar5b435d62012-04-05 17:33:26 +02004756 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping.
4757 Returns an empty string otherwise.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00004758 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004759
Bram Moolenaarfb539272014-08-22 19:21:47 +02004760getcmdwintype() *getcmdwintype()*
4761 Return the current |command-line-window| type. Possible return
4762 values are the same as |getcmdtype()|. Returns an empty string
4763 when not in the command-line window.
4764
Bram Moolenaare9d58a62016-08-13 15:07:41 +02004765getcompletion({pat}, {type} [, {filtered}]) *getcompletion()*
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004766 Return a list of command-line completion matches. {type}
4767 specifies what for. The following completion types are
4768 supported:
4769
Bram Moolenaarcd43eff2018-03-29 15:55:38 +02004770 arglist file names in argument list
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004771 augroup autocmd groups
4772 buffer buffer names
4773 behave :behave suboptions
4774 color color schemes
4775 command Ex command (and arguments)
4776 compiler compilers
4777 cscope |:cscope| suboptions
4778 dir directory names
4779 environment environment variable names
4780 event autocommand events
4781 expression Vim expression
4782 file file and directory names
4783 file_in_path file and directory names in |'path'|
4784 filetype filetype names |'filetype'|
4785 function function name
4786 help help subjects
4787 highlight highlight groups
4788 history :history suboptions
4789 locale locale names (as output of locale -a)
Bram Moolenaarcae92dc2017-08-06 15:22:15 +02004790 mapclear buffer argument
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004791 mapping mapping name
4792 menu menus
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02004793 messages |:messages| suboptions
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004794 option options
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02004795 packadd optional package |pack-add| names
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004796 shellcmd Shell command
4797 sign |:sign| suboptions
4798 syntax syntax file names |'syntax'|
4799 syntime |:syntime| suboptions
4800 tag tags
4801 tag_listfiles tags, file names
4802 user user names
4803 var user variables
4804
4805 If {pat} is an empty string, then all the matches are returned.
4806 Otherwise only items matching {pat} are returned. See
4807 |wildcards| for the use of special characters in {pat}.
4808
Bram Moolenaare9d58a62016-08-13 15:07:41 +02004809 If the optional {filtered} flag is set to 1, then 'wildignore'
4810 is applied to filter the results. Otherwise all the matches
4811 are returned. The 'wildignorecase' option always applies.
4812
Bram Moolenaaraa4d7322016-07-09 18:50:29 +02004813 If there are no matches, an empty list is returned. An
4814 invalid value for {type} produces an error.
4815
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004816 *getcurpos()*
4817getcurpos() Get the position of the cursor. This is like getpos('.'), but
4818 includes an extra item in the list:
Bram Moolenaar345efa02016-01-15 20:57:49 +01004819 [bufnum, lnum, col, off, curswant] ~
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004820 The "curswant" number is the preferred column when moving the
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004821 cursor vertically. Also see |getpos()|.
4822
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02004823 This can be used to save and restore the cursor position: >
4824 let save_cursor = getcurpos()
4825 MoveTheCursorAround
4826 call setpos('.', save_cursor)
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02004827< Note that this only works within the window. See
4828 |winrestview()| for restoring more state.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004829 *getcwd()*
Bram Moolenaarc9703302016-01-17 21:49:33 +01004830getcwd([{winnr} [, {tabnr}]])
4831 The result is a String, which is the name of the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00004832 working directory.
Bram Moolenaarc9703302016-01-17 21:49:33 +01004833
4834 With {winnr} return the local current directory of this window
Bram Moolenaar54591292018-02-09 20:53:59 +01004835 in the current tab page. {winnr} can be the window number or
4836 the |window-ID|.
4837 If {winnr} is -1 return the name of the global working
4838 directory. See also |haslocaldir()|.
4839
Bram Moolenaarc9703302016-01-17 21:49:33 +01004840 With {winnr} and {tabnr} return the local current directory of
4841 the window in the specified tab page.
4842 Return an empty string if the arguments are invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004843
4844getfsize({fname}) *getfsize()*
4845 The result is a Number, which is the size in bytes of the
4846 given file {fname}.
4847 If {fname} is a directory, 0 is returned.
4848 If the file {fname} can't be found, -1 is returned.
Bram Moolenaard827ada2007-06-19 15:19:55 +00004849 If the size of {fname} is too big to fit in a Number then -2
4850 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004851
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004852getfontname([{name}]) *getfontname()*
4853 Without an argument returns the name of the normal font being
4854 used. Like what is used for the Normal highlight group
4855 |hl-Normal|.
4856 With an argument a check is done whether {name} is a valid
4857 font name. If not then an empty string is returned.
4858 Otherwise the actual font name is returned, or {name} if the
4859 GUI does not support obtaining the real name.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00004860 Only works when the GUI is running, thus not in your vimrc or
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004861 gvimrc file. Use the |GUIEnter| autocommand to use this
4862 function just after the GUI has started.
Bram Moolenaar3df01732017-02-17 22:47:16 +01004863 Note that the GTK GUI accepts any font name, thus checking for
4864 a valid name does not work.
Bram Moolenaard8b0cf12004-12-12 11:33:30 +00004865
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004866getfperm({fname}) *getfperm()*
4867 The result is a String, which is the read, write, and execute
4868 permissions of the given file {fname}.
4869 If {fname} does not exist or its directory cannot be read, an
4870 empty string is returned.
4871 The result is of the form "rwxrwxrwx", where each group of
4872 "rwx" flags represent, in turn, the permissions of the owner
4873 of the file, the group the file belongs to, and other users.
4874 If a user does not have a given permission the flag for this
Bram Moolenaar9b451252012-08-15 17:43:31 +02004875 is replaced with the string "-". Examples: >
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004876 :echo getfperm("/etc/passwd")
Bram Moolenaar9b451252012-08-15 17:43:31 +02004877 :echo getfperm(expand("~/.vimrc"))
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004878< This will hopefully (from a security point of view) display
4879 the string "rw-r--r--" or even "rw-------".
Bram Moolenaare2cc9702005-03-15 22:43:58 +00004880
Bram Moolenaar2ec618c2016-10-01 14:47:05 +02004881 For setting permissions use |setfperm()|.
Bram Moolenaar80492532016-03-08 17:08:53 +01004882
Bram Moolenaar071d4272004-06-13 20:20:40 +00004883getftime({fname}) *getftime()*
4884 The result is a Number, which is the last modification time of
4885 the given file {fname}. The value is measured as seconds
4886 since 1st Jan 1970, and may be passed to strftime(). See also
4887 |localtime()| and |strftime()|.
4888 If the file {fname} can't be found -1 is returned.
4889
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004890getftype({fname}) *getftype()*
4891 The result is a String, which is a description of the kind of
4892 file of the given file {fname}.
4893 If {fname} does not exist an empty string is returned.
4894 Here is a table over different kinds of files and their
4895 results:
4896 Normal file "file"
4897 Directory "dir"
4898 Symbolic link "link"
4899 Block device "bdev"
4900 Character device "cdev"
4901 Socket "socket"
4902 FIFO "fifo"
4903 All other "other"
4904 Example: >
4905 getftype("/home")
4906< Note that a type such as "link" will only be returned on
4907 systems that support it. On some systems only "dir" and
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01004908 "file" are returned. On MS-Windows a symbolic link to a
4909 directory returns "dir" instead of "link".
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00004910
Bram Moolenaard96ff162018-02-18 22:13:29 +01004911getjumplist([{winnr} [, {tabnr}]]) *getjumplist()*
Bram Moolenaar4f505882018-02-10 21:06:32 +01004912 Returns the |jumplist| for the specified window.
4913
4914 Without arguments use the current window.
4915 With {winnr} only use this window in the current tab page.
4916 {winnr} can also be a |window-ID|.
4917 With {winnr} and {tabnr} use the window in the specified tab
4918 page.
4919
4920 The returned list contains two entries: a list with the jump
4921 locations and the last used jump position number in the list.
4922 Each entry in the jump location list is a dictionary with
4923 the following entries:
4924 bufnr buffer number
4925 col column number
4926 coladd column offset for 'virtualedit'
4927 filename filename if available
4928 lnum line number
4929
Bram Moolenaar071d4272004-06-13 20:20:40 +00004930 *getline()*
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004931getline({lnum} [, {end}])
4932 Without {end} the result is a String, which is line {lnum}
4933 from the current buffer. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004934 getline(1)
4935< When {lnum} is a String that doesn't start with a
Bram Moolenaarf2732452018-06-03 14:47:35 +02004936 digit, |line()| is called to translate the String into a Number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004937 To get the line under the cursor: >
4938 getline(".")
4939< When {lnum} is smaller than 1 or bigger than the number of
4940 lines in the buffer, an empty string is returned.
4941
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004942 When {end} is given the result is a |List| where each item is
4943 a line from the current buffer in the range {lnum} to {end},
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004944 including line {end}.
4945 {end} is used in the same way as {lnum}.
4946 Non-existing lines are silently omitted.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00004947 When {end} is before {lnum} an empty |List| is returned.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004948 Example: >
4949 :let start = line('.')
4950 :let end = search("^$") - 1
4951 :let lines = getline(start, end)
4952
Bram Moolenaaref2f6562007-05-06 13:32:59 +00004953< To get lines from another buffer see |getbufline()|
4954
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004955getloclist({nr} [, {what}]) *getloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004956 Returns a list with all the entries in the location list for
Bram Moolenaar7571d552016-08-18 22:54:46 +02004957 window {nr}. {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02004958 When {nr} is zero the current window is used.
4959
Bram Moolenaar17c7c012006-01-26 22:25:15 +00004960 For a location list window, the displayed location list is
Bram Moolenaar280f1262006-01-30 00:14:18 +00004961 returned. For an invalid window number {nr}, an empty list is
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004962 returned. Otherwise, same as |getqflist()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00004963
Bram Moolenaard823fa92016-08-12 16:29:27 +02004964 If the optional {what} dictionary argument is supplied, then
4965 returns the items listed in {what} as a dictionary. Refer to
4966 |getqflist()| for the supported items in {what}.
Bram Moolenaarc9cc9c72018-09-02 15:18:42 +02004967 If {what} contains 'filewinid', then returns the id of the
4968 window used to display files from the location list. This
4969 field is applicable only when called from a location list
Bram Moolenaar5b69c222019-01-11 14:50:06 +01004970 window. See |location-list-file-window| for more details.
Bram Moolenaard823fa92016-08-12 16:29:27 +02004971
Bram Moolenaar6ee10162007-07-26 20:58:42 +00004972getmatches() *getmatches()*
4973 Returns a |List| with all matches previously defined by
4974 |matchadd()| and the |:match| commands. |getmatches()| is
4975 useful in combination with |setmatches()|, as |setmatches()|
4976 can restore a list of matches saved by |getmatches()|.
4977 Example: >
4978 :echo getmatches()
4979< [{'group': 'MyGroup1', 'pattern': 'TODO',
4980 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4981 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4982 :let m = getmatches()
4983 :call clearmatches()
4984 :echo getmatches()
4985< [] >
4986 :call setmatches(m)
4987 :echo getmatches()
4988< [{'group': 'MyGroup1', 'pattern': 'TODO',
4989 'priority': 10, 'id': 1}, {'group': 'MyGroup2',
4990 'pattern': 'FIXME', 'priority': 10, 'id': 2}] >
4991 :unlet m
4992<
Bram Moolenaar822ff862014-06-12 21:46:14 +02004993 *getpid()*
4994getpid() Return a Number which is the process ID of the Vim process.
4995 On Unix and MS-Windows this is a unique number, until Vim
Bram Moolenaar58b85342016-08-14 19:54:54 +02004996 exits. On MS-DOS it's always zero.
Bram Moolenaar822ff862014-06-12 21:46:14 +02004997
4998 *getpos()*
4999getpos({expr}) Get the position for {expr}. For possible values of {expr}
5000 see |line()|. For getting the cursor position see
5001 |getcurpos()|.
5002 The result is a |List| with four numbers:
5003 [bufnum, lnum, col, off]
5004 "bufnum" is zero, unless a mark like '0 or 'A is used, then it
5005 is the buffer number of the mark.
5006 "lnum" and "col" are the position in the buffer. The first
5007 column is 1.
5008 The "off" number is zero, unless 'virtualedit' is used. Then
5009 it is the offset in screen columns from the start of the
5010 character. E.g., a position within a <Tab> or after the last
5011 character.
5012 Note that for '< and '> Visual mode matters: when it is "V"
5013 (visual line mode) the column of '< is zero and the column of
5014 '> is a large number.
5015 This can be used to save and restore the position of a mark: >
5016 let save_a_mark = getpos("'a")
5017 ...
Bram Moolenaared32d942014-12-06 23:33:00 +01005018 call setpos("'a", save_a_mark)
Bram Moolenaar822ff862014-06-12 21:46:14 +02005019< Also see |getcurpos()| and |setpos()|.
5020
Bram Moolenaar6ee10162007-07-26 20:58:42 +00005021
Bram Moolenaard823fa92016-08-12 16:29:27 +02005022getqflist([{what}]) *getqflist()*
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005023 Returns a list with all the current quickfix errors. Each
5024 list item is a dictionary with these entries:
5025 bufnr number of buffer that has the file name, use
5026 bufname() to get the name
Bram Moolenaard76ce852018-05-01 15:02:04 +02005027 module module name
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005028 lnum line number in the buffer (first line is 1)
5029 col column number (first column is 1)
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005030 vcol |TRUE|: "col" is visual column
5031 |FALSE|: "col" is byte index
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005032 nr error number
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005033 pattern search pattern used to locate the error
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005034 text description of the error
5035 type type of the error, 'E', '1', etc.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005036 valid |TRUE|: recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005037
Bram Moolenaar7571d552016-08-18 22:54:46 +02005038 When there is no error list or it's empty, an empty list is
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00005039 returned. Quickfix list entries with non-existing buffer
5040 number are returned with "bufnr" set to zero.
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00005041
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005042 Useful application: Find pattern matches in multiple files and
5043 do something with them: >
5044 :vimgrep /theword/jg *.c
5045 :for d in getqflist()
5046 : echo bufname(d.bufnr) ':' d.lnum '=' d.text
5047 :endfor
Bram Moolenaard823fa92016-08-12 16:29:27 +02005048<
5049 If the optional {what} dictionary argument is supplied, then
5050 returns only the items listed in {what} as a dictionary. The
5051 following string items are supported in {what}:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005052 changedtick get the total number of changes made
Bram Moolenaar15142e22018-04-30 22:19:58 +02005053 to the list |quickfix-changedtick|
5054 context get the |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02005055 efm errorformat to use when parsing "lines". If
Bram Moolenaar2f058492017-11-30 20:27:52 +01005056 not present, then the 'errorformat' option
Bram Moolenaar36538222017-09-02 19:51:44 +02005057 value is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005058 id get information for the quickfix list with
5059 |quickfix-ID|; zero means the id for the
Bram Moolenaar2f058492017-11-30 20:27:52 +01005060 current list or the list specified by "nr"
Bram Moolenaar5b69c222019-01-11 14:50:06 +01005061 idx index of the current entry in the quickfix
5062 list specified by 'id' or 'nr'.
5063 See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02005064 items quickfix list entries
Bram Moolenaar15142e22018-04-30 22:19:58 +02005065 lines parse a list of lines using 'efm' and return
5066 the resulting entries. Only a |List| type is
5067 accepted. The current quickfix list is not
5068 modified. See |quickfix-parse|.
Bram Moolenaar890680c2016-09-27 21:28:56 +02005069 nr get information for this quickfix list; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02005070 means the current quickfix list and "$" means
Bram Moolenaar875feea2017-06-11 16:07:51 +02005071 the last quickfix list
Bram Moolenaarfc2b2702017-09-15 22:43:07 +02005072 size number of entries in the quickfix list
Bram Moolenaar15142e22018-04-30 22:19:58 +02005073 title get the list title |quickfix-title|
Bram Moolenaar74240d32017-12-10 15:26:15 +01005074 winid get the quickfix |window-ID|
Bram Moolenaard823fa92016-08-12 16:29:27 +02005075 all all of the above quickfix properties
Bram Moolenaar74240d32017-12-10 15:26:15 +01005076 Non-string items in {what} are ignored. To get the value of a
Bram Moolenaara6d48492017-12-12 22:45:31 +01005077 particular item, set it to zero.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005078 If "nr" is not present then the current quickfix list is used.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02005079 If both "nr" and a non-zero "id" are specified, then the list
5080 specified by "id" is used.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005081 To get the number of lists in the quickfix stack, set "nr" to
5082 "$" in {what}. The "nr" value in the returned dictionary
Bram Moolenaar875feea2017-06-11 16:07:51 +02005083 contains the quickfix stack size.
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02005084 When "lines" is specified, all the other items except "efm"
5085 are ignored. The returned dictionary contains the entry
5086 "items" with the list of entries.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00005087
Bram Moolenaard823fa92016-08-12 16:29:27 +02005088 The returned dictionary contains the following entries:
Bram Moolenaarb254af32017-12-18 19:48:58 +01005089 changedtick total number of changes made to the
5090 list |quickfix-changedtick|
Bram Moolenaar15142e22018-04-30 22:19:58 +02005091 context quickfix list context. See |quickfix-context|
Bram Moolenaara6d48492017-12-12 22:45:31 +01005092 If not present, set to "".
5093 id quickfix list ID |quickfix-ID|. If not
5094 present, set to 0.
5095 idx index of the current entry in the list. If not
5096 present, set to 0.
5097 items quickfix list entries. If not present, set to
5098 an empty list.
5099 nr quickfix list number. If not present, set to 0
5100 size number of entries in the quickfix list. If not
5101 present, set to 0.
5102 title quickfix list title text. If not present, set
5103 to "".
Bram Moolenaar74240d32017-12-10 15:26:15 +01005104 winid quickfix |window-ID|. If not present, set to 0
Bram Moolenaard823fa92016-08-12 16:29:27 +02005105
Bram Moolenaar15142e22018-04-30 22:19:58 +02005106 Examples (See also |getqflist-examples|): >
Bram Moolenaard823fa92016-08-12 16:29:27 +02005107 :echo getqflist({'all': 1})
5108 :echo getqflist({'nr': 2, 'title': 1})
Bram Moolenaar2c809b72017-09-01 18:34:02 +02005109 :echo getqflist({'lines' : ["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02005110<
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005111getreg([{regname} [, 1 [, {list}]]]) *getreg()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005112 The result is a String, which is the contents of register
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005113 {regname}. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005114 :let cliptext = getreg('*')
Bram Moolenaardc1f1642016-08-16 18:33:43 +02005115< When {regname} was not set the result is an empty string.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005116
5117 getreg('=') returns the last evaluated value of the expression
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005118 register. (For use in maps.)
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00005119 getreg('=', 1) returns the expression itself, so that it can
5120 be restored with |setreg()|. For other registers the extra
5121 argument is ignored, thus you can always give it.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005122
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005123 If {list} is present and |TRUE|, the result type is changed
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005124 to |List|. Each list item is one text line. Use it if you care
Bram Moolenaarb7cb42b2014-04-02 19:55:10 +02005125 about zero bytes possibly present inside register: without
5126 third argument both NLs and zero bytes are represented as NLs
5127 (see |NL-used-for-Nul|).
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005128 When the register was not set an empty list is returned.
5129
Bram Moolenaar071d4272004-06-13 20:20:40 +00005130 If {regname} is not specified, |v:register| is used.
5131
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005132
Bram Moolenaar071d4272004-06-13 20:20:40 +00005133getregtype([{regname}]) *getregtype()*
5134 The result is a String, which is type of register {regname}.
5135 The value will be one of:
5136 "v" for |characterwise| text
5137 "V" for |linewise| text
5138 "<CTRL-V>{width}" for |blockwise-visual| text
Bram Moolenaar32b92012014-01-14 12:33:36 +01005139 "" for an empty or unknown register
Bram Moolenaar071d4272004-06-13 20:20:40 +00005140 <CTRL-V> is one character with value 0x16.
5141 If {regname} is not specified, |v:register| is used.
5142
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005143gettabinfo([{arg}]) *gettabinfo()*
5144 If {arg} is not specified, then information about all the tab
5145 pages is returned as a List. Each List item is a Dictionary.
5146 Otherwise, {arg} specifies the tab page number and information
5147 about that one is returned. If the tab page does not exist an
5148 empty List is returned.
5149
5150 Each List item is a Dictionary with the following entries:
Bram Moolenaar7571d552016-08-18 22:54:46 +02005151 tabnr tab page number.
Bram Moolenaar30567352016-08-27 21:25:44 +02005152 variables a reference to the dictionary with
5153 tabpage-local variables
Bram Moolenaar7571d552016-08-18 22:54:46 +02005154 windows List of |window-ID|s in the tag page.
Bram Moolenaarb5ae48e2016-08-12 22:23:25 +02005155
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005156gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()*
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005157 Get the value of a tab-local variable {varname} in tab page
5158 {tabnr}. |t:var|
5159 Tabs are numbered starting with one.
Bram Moolenaar0e2ea1b2014-09-09 16:13:08 +02005160 When {varname} is empty a dictionary with all tab-local
5161 variables is returned.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005162 Note that the name without "t:" must be used.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005163 When the tab or variable doesn't exist {def} or an empty
5164 string is returned, there is no error message.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005165
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005166gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()*
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005167 Get the value of window-local variable {varname} in window
5168 {winnr} in tab page {tabnr}.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005169 When {varname} is empty a dictionary with all window-local
5170 variables is returned.
Bram Moolenaar30567352016-08-27 21:25:44 +02005171 When {varname} is equal to "&" get the values of all
5172 window-local options in a Dictionary.
5173 Otherwise, when {varname} starts with "&" get the value of a
5174 window-local option.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005175 Note that {varname} must be the name without "w:".
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005176 Tabs are numbered starting with one. For the current tabpage
5177 use |getwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02005178 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005179 When {winnr} is zero the current window is used.
5180 This also works for a global option, buffer-local option and
5181 window-local option, but it doesn't work for a global variable
5182 or buffer-local variable.
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005183 When the tab, window or variable doesn't exist {def} or an
5184 empty string is returned, there is no error message.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005185 Examples: >
5186 :let list_is_on = gettabwinvar(1, 2, '&list')
5187 :echo "myvar = " . gettabwinvar(3, 1, 'myvar')
Bram Moolenaard46bbc72007-05-12 14:38:41 +00005188<
Bram Moolenaarb477af22018-07-15 20:20:18 +02005189 To obtain all window-local variables use: >
5190 gettabwinvar({tabnr}, {winnr}, '&')
5191
Bram Moolenaarf49cc602018-11-11 15:21:05 +01005192gettagstack([{nr}]) *gettagstack()*
5193 The result is a Dict, which is the tag stack of window {nr}.
5194 {nr} can be the window number or the |window-ID|.
5195 When {nr} is not specified, the current window is used.
5196 When window {nr} doesn't exist, an empty Dict is returned.
5197
5198 The returned dictionary contains the following entries:
5199 curidx Current index in the stack. When at
5200 top of the stack, set to (length + 1).
5201 Index of bottom of the stack is 1.
5202 items List of items in the stack. Each item
5203 is a dictionary containing the
5204 entries described below.
5205 length Number of entries in the stack.
5206
5207 Each item in the stack is a dictionary with the following
5208 entries:
5209 bufnr buffer number of the current jump
5210 from cursor position before the tag jump.
5211 See |getpos()| for the format of the
5212 returned list.
5213 matchnr current matching tag number. Used when
5214 multiple matching tags are found for a
5215 name.
5216 tagname name of the tag
5217
5218 See |tagstack| for more information about the tag stack.
5219
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005220getwininfo([{winid}]) *getwininfo()*
5221 Returns information about windows as a List with Dictionaries.
5222
5223 If {winid} is given Information about the window with that ID
5224 is returned. If the window does not exist the result is an
5225 empty list.
5226
5227 Without {winid} information about all the windows in all the
5228 tab pages is returned.
5229
5230 Each List item is a Dictionary with the following entries:
5231 bufnr number of buffer in the window
5232 height window height (excluding winbar)
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005233 loclist 1 if showing a location list
5234 {only with the +quickfix feature}
5235 quickfix 1 if quickfix or location list window
5236 {only with the +quickfix feature}
5237 terminal 1 if a terminal window
5238 {only with the +terminal feature}
5239 tabnr tab page number
5240 variables a reference to the dictionary with
5241 window-local variables
5242 width window width
Bram Moolenaarb477af22018-07-15 20:20:18 +02005243 winbar 1 if the window has a toolbar, 0
5244 otherwise
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02005245 wincol leftmost screen column of the window,
5246 col from |win_screenpos()|
5247 winid |window-ID|
5248 winnr window number
5249 winrow topmost screen column of the window,
5250 row from |win_screenpos()|
5251
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005252getwinpos([{timeout}]) *getwinpos()*
5253 The result is a list with two numbers, the result of
Bram Moolenaar9d87a372018-12-18 21:41:50 +01005254 getwinposx() and getwinposy() combined:
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005255 [x-pos, y-pos]
5256 {timeout} can be used to specify how long to wait in msec for
5257 a response from the terminal. When omitted 100 msec is used.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005258 Use a longer time for a remote terminal.
5259 When using a value less than 10 and no response is received
5260 within that time, a previously reported position is returned,
5261 if available. This can be used to poll for the position and
Bram Moolenaar5b69c222019-01-11 14:50:06 +01005262 do some work in the meantime: >
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005263 while 1
5264 let res = getwinpos(1)
5265 if res[0] >= 0
5266 break
5267 endif
5268 " Do some work here
5269 endwhile
5270<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005271 *getwinposx()*
5272getwinposx() The result is a Number, which is the X coordinate in pixels of
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005273 the left hand side of the GUI Vim window. Also works for an
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005274 xterm (uses a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005275 The result will be -1 if the information is not available.
5276 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005277
5278 *getwinposy()*
5279getwinposy() The result is a Number, which is the Y coordinate in pixels of
Bram Moolenaar3f54fd32018-03-03 21:29:55 +01005280 the top of the GUI Vim window. Also works for an xterm (uses
5281 a timeout of 100 msec).
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005282 The result will be -1 if the information is not available.
5283 The value can be used with `:winpos`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005284
Bram Moolenaar63dbda12013-02-20 21:12:10 +01005285getwinvar({winnr}, {varname} [, {def}]) *getwinvar()*
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00005286 Like |gettabwinvar()| for the current tabpage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005287 Examples: >
5288 :let list_is_on = getwinvar(2, '&list')
5289 :echo "myvar = " . getwinvar(1, 'myvar')
5290<
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005291glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()*
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005292 Expand the file wildcards in {expr}. See |wildcards| for the
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005293 use of special characters.
Bram Moolenaar84f72352012-03-11 15:57:40 +01005294
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005295 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005296 the 'suffixes' and 'wildignore' options apply: Names matching
5297 one of the patterns in 'wildignore' will be skipped and
5298 'suffixes' affect the ordering of matches.
Bram Moolenaar81af9252010-12-10 20:35:50 +01005299 'wildignorecase' always applies.
Bram Moolenaar84f72352012-03-11 15:57:40 +01005300
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005301 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar84f72352012-03-11 15:57:40 +01005302 with all matching files. The advantage of using a List is,
5303 you also get filenames containing newlines correctly.
5304 Otherwise the result is a String and when there are several
5305 matches, they are separated by <NL> characters.
5306
5307 If the expansion fails, the result is an empty String or List.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005308
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02005309 A name for a non-existing file is not included. A symbolic
5310 link is only included if it points to an existing file.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005311 However, when the {alllinks} argument is present and it is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005312 |TRUE| then all symbolic links are included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005313
5314 For most systems backticks can be used to get files names from
5315 any external command. Example: >
5316 :let tagfiles = glob("`find . -name tags -print`")
5317 :let &tags = substitute(tagfiles, "\n", ",", "g")
5318< The result of the program inside the backticks should be one
Bram Moolenaar58b85342016-08-14 19:54:54 +02005319 item per line. Spaces inside an item are allowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005320
5321 See |expand()| for expanding special Vim variables. See
5322 |system()| for getting the raw output of an external command.
5323
Bram Moolenaar5837f1f2015-03-21 18:06:14 +01005324glob2regpat({expr}) *glob2regpat()*
5325 Convert a file pattern, as used by glob(), into a search
5326 pattern. The result can be used to match with a string that
5327 is a file name. E.g. >
5328 if filename =~ glob2regpat('Make*.mak')
5329< This is equivalent to: >
5330 if filename =~ '^Make.*\.mak$'
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01005331< When {expr} is an empty string the result is "^$", match an
5332 empty string.
Bram Moolenaard823fa92016-08-12 16:29:27 +02005333 Note that the result depends on the system. On MS-Windows
Bram Moolenaar58b85342016-08-14 19:54:54 +02005334 a backslash usually means a path separator.
Bram Moolenaar3b5f9292016-01-28 22:37:01 +01005335
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005336 *globpath()*
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005337globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00005338 Perform glob() on all directories in {path} and concatenate
5339 the results. Example: >
5340 :echo globpath(&rtp, "syntax/c.vim")
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005341<
5342 {path} is a comma-separated list of directory names. Each
Bram Moolenaar071d4272004-06-13 20:20:40 +00005343 directory name is prepended to {expr} and expanded like with
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005344 |glob()|. A path separator is inserted when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005345 To add a comma inside a directory name escape it with a
5346 backslash. Note that on MS-Windows a directory may have a
5347 trailing backslash, remove it if you put a comma after it.
5348 If the expansion fails for one of the directories, there is no
5349 error message.
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005350
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005351 Unless the optional {nosuf} argument is given and is |TRUE|,
Bram Moolenaarbb5ddda2008-11-28 10:01:10 +00005352 the 'suffixes' and 'wildignore' options apply: Names matching
5353 one of the patterns in 'wildignore' will be skipped and
5354 'suffixes' affect the ordering of matches.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005355
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005356 When {list} is present and it is |TRUE| the result is a List
Bram Moolenaar1b1063a2014-05-07 18:35:30 +02005357 with all matching files. The advantage of using a List is, you
5358 also get filenames containing newlines correctly. Otherwise
5359 the result is a String and when there are several matches,
5360 they are separated by <NL> characters. Example: >
5361 :echo globpath(&rtp, "syntax/c.vim", 0, 1)
5362<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005363 {alllinks} is used as with |glob()|.
Bram Moolenaard8b77f72015-03-05 21:21:19 +01005364
Bram Moolenaar02743632005-07-25 20:42:36 +00005365 The "**" item can be used to search in a directory tree.
5366 For example, to find all "README.txt" files in the directories
5367 in 'runtimepath' and below: >
5368 :echo globpath(&rtp, "**/README.txt")
Bram Moolenaarc236c162008-07-13 17:41:49 +00005369< Upwards search and limiting the depth of "**" is not
5370 supported, thus using 'path' will not always work properly.
5371
Bram Moolenaar071d4272004-06-13 20:20:40 +00005372 *has()*
5373has({feature}) The result is a Number, which is 1 if the feature {feature} is
5374 supported, zero otherwise. The {feature} argument is a
5375 string. See |feature-list| below.
5376 Also see |exists()|.
5377
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005378
5379has_key({dict}, {key}) *has_key()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005380 The result is a Number, which is 1 if |Dictionary| {dict} has
5381 an entry with key {key}. Zero otherwise.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005382
Bram Moolenaarc9703302016-01-17 21:49:33 +01005383haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()*
5384 The result is a Number, which is 1 when the window has set a
5385 local path via |:lcd|, and 0 otherwise.
5386
5387 Without arguments use the current window.
5388 With {winnr} use this window in the current tab page.
5389 With {winnr} and {tabnr} use the window in the specified tab
5390 page.
Bram Moolenaar7571d552016-08-18 22:54:46 +02005391 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc9703302016-01-17 21:49:33 +01005392 Return 0 if the arguments are invalid.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00005393
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00005394hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005395 The result is a Number, which is 1 if there is a mapping that
5396 contains {what} in somewhere in the rhs (what it is mapped to)
5397 and this mapping exists in one of the modes indicated by
5398 {mode}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005399 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar39f05632006-03-19 22:15:26 +00005400 instead of mappings. Don't forget to specify Insert and/or
5401 Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005402 Both the global mappings and the mappings local to the current
5403 buffer are checked for a match.
5404 If no matching mapping is found 0 is returned.
5405 The following characters are recognized in {mode}:
5406 n Normal mode
5407 v Visual mode
5408 o Operator-pending mode
5409 i Insert mode
5410 l Language-Argument ("r", "f", "t", etc.)
5411 c Command-line mode
5412 When {mode} is omitted, "nvo" is used.
5413
5414 This function is useful to check if a mapping already exists
Bram Moolenaar58b85342016-08-14 19:54:54 +02005415 to a function in a Vim script. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005416 :if !hasmapto('\ABCdoit')
5417 : map <Leader>d \ABCdoit
5418 :endif
5419< This installs the mapping to "\ABCdoit" only if there isn't
5420 already a mapping to "\ABCdoit".
5421
5422histadd({history}, {item}) *histadd()*
5423 Add the String {item} to the history {history} which can be
5424 one of: *hist-names*
5425 "cmd" or ":" command line history
5426 "search" or "/" search pattern history
Bram Moolenaar446cb832008-06-24 21:56:24 +00005427 "expr" or "=" typed expression history
Bram Moolenaar071d4272004-06-13 20:20:40 +00005428 "input" or "@" input line history
Bram Moolenaar30b65812012-07-12 22:01:11 +02005429 "debug" or ">" debug command history
Bram Moolenaar3e496b02016-09-25 22:11:48 +02005430 empty the current or last used history
Bram Moolenaar30b65812012-07-12 22:01:11 +02005431 The {history} string does not need to be the whole name, one
5432 character is sufficient.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005433 If {item} does already exist in the history, it will be
5434 shifted to become the newest entry.
5435 The result is a Number: 1 if the operation was successful,
5436 otherwise 0 is returned.
5437
5438 Example: >
5439 :call histadd("input", strftime("%Y %b %d"))
5440 :let date=input("Enter date: ")
5441< This function is not available in the |sandbox|.
5442
5443histdel({history} [, {item}]) *histdel()*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005444 Clear {history}, i.e. delete all its entries. See |hist-names|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005445 for the possible values of {history}.
5446
Bram Moolenaarc236c162008-07-13 17:41:49 +00005447 If the parameter {item} evaluates to a String, it is used as a
5448 regular expression. All entries matching that expression will
5449 be removed from the history (if there are any).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005450 Upper/lowercase must match, unless "\c" is used |/\c|.
Bram Moolenaarc236c162008-07-13 17:41:49 +00005451 If {item} evaluates to a Number, it will be interpreted as
5452 an index, see |:history-indexing|. The respective entry will
5453 be removed if it exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005454
5455 The result is a Number: 1 for a successful operation,
5456 otherwise 0 is returned.
5457
5458 Examples:
5459 Clear expression register history: >
5460 :call histdel("expr")
5461<
5462 Remove all entries starting with "*" from the search history: >
5463 :call histdel("/", '^\*')
5464<
5465 The following three are equivalent: >
5466 :call histdel("search", histnr("search"))
5467 :call histdel("search", -1)
5468 :call histdel("search", '^'.histget("search", -1).'$')
5469<
5470 To delete the last search pattern and use the last-but-one for
5471 the "n" command and 'hlsearch': >
5472 :call histdel("search", -1)
5473 :let @/ = histget("search", -1)
5474
5475histget({history} [, {index}]) *histget()*
5476 The result is a String, the entry with Number {index} from
5477 {history}. See |hist-names| for the possible values of
5478 {history}, and |:history-indexing| for {index}. If there is
5479 no such entry, an empty String is returned. When {index} is
5480 omitted, the most recent item from the history is used.
5481
5482 Examples:
5483 Redo the second last search from history. >
5484 :execute '/' . histget("search", -2)
5485
5486< Define an Ex command ":H {num}" that supports re-execution of
5487 the {num}th entry from the output of |:history|. >
5488 :command -nargs=1 H execute histget("cmd", 0+<args>)
5489<
5490histnr({history}) *histnr()*
5491 The result is the Number of the current entry in {history}.
5492 See |hist-names| for the possible values of {history}.
5493 If an error occurred, -1 is returned.
5494
5495 Example: >
5496 :let inp_index = histnr("expr")
5497<
5498hlexists({name}) *hlexists()*
5499 The result is a Number, which is non-zero if a highlight group
5500 called {name} exists. This is when the group has been
5501 defined in some way. Not necessarily when highlighting has
5502 been defined for it, it may also have been used for a syntax
5503 item.
5504 *highlight_exists()*
5505 Obsolete name: highlight_exists().
5506
5507 *hlID()*
5508hlID({name}) The result is a Number, which is the ID of the highlight group
5509 with name {name}. When the highlight group doesn't exist,
5510 zero is returned.
5511 This can be used to retrieve information about the highlight
Bram Moolenaar58b85342016-08-14 19:54:54 +02005512 group. For example, to get the background color of the
Bram Moolenaar071d4272004-06-13 20:20:40 +00005513 "Comment" group: >
5514 :echo synIDattr(synIDtrans(hlID("Comment")), "bg")
5515< *highlightID()*
5516 Obsolete name: highlightID().
5517
5518hostname() *hostname()*
5519 The result is a String, which is the name of the machine on
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00005520 which Vim is currently running. Machine names greater than
Bram Moolenaar071d4272004-06-13 20:20:40 +00005521 256 characters long are truncated.
5522
5523iconv({expr}, {from}, {to}) *iconv()*
5524 The result is a String, which is the text {expr} converted
5525 from encoding {from} to encoding {to}.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005526 When the conversion completely fails an empty string is
5527 returned. When some characters could not be converted they
5528 are replaced with "?".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005529 The encoding names are whatever the iconv() library function
5530 can accept, see ":!man 3 iconv".
5531 Most conversions require Vim to be compiled with the |+iconv|
5532 feature. Otherwise only UTF-8 to latin1 conversion and back
5533 can be done.
5534 This can be used to display messages with special characters,
5535 no matter what 'encoding' is set to. Write the message in
5536 UTF-8 and use: >
5537 echo iconv(utf8_str, "utf-8", &enc)
5538< Note that Vim uses UTF-8 for all Unicode encodings, conversion
5539 from/to UCS-2 is automatically changed to use UTF-8. You
5540 cannot use UCS-2 in a string anyway, because of the NUL bytes.
Bram Moolenaardb84e452010-08-15 13:50:43 +02005541 {only available when compiled with the |+multi_byte| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005542
5543 *indent()*
5544indent({lnum}) The result is a Number, which is indent of line {lnum} in the
5545 current buffer. The indent is counted in spaces, the value
5546 of 'tabstop' is relevant. {lnum} is used just like in
5547 |getline()|.
5548 When {lnum} is invalid -1 is returned.
5549
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005550
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005551index({object}, {expr} [, {start} [, {ic}]]) *index()*
5552 If {object} is a |List| return the lowest index where the item
5553 has a value equal to {expr}. There is no automatic
5554 conversion, so the String "4" is different from the Number 4.
5555 And the number 4 is different from the Float 4.0. The value
5556 of 'ignorecase' is not used here, case always matters.
5557
5558 If {object} is |Blob| return the lowest index where the byte
5559 value is equal to {expr}.
5560
Bram Moolenaar748bf032005-02-02 23:04:36 +00005561 If {start} is given then start looking at the item with index
5562 {start} (may be negative for an item relative to the end).
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005563 When {ic} is given and it is |TRUE|, ignore case. Otherwise
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005564 case must match.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005565 -1 is returned when {expr} is not found in {object}.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005566 Example: >
5567 :let idx = index(words, "the")
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00005568 :if index(numbers, 123) >= 0
Bram Moolenaarde8866b2005-01-06 23:24:37 +00005569
5570
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005571input({prompt} [, {text} [, {completion}]]) *input()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005572 The result is a String, which is whatever the user typed on
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005573 the command-line. The {prompt} argument is either a prompt
5574 string, or a blank string (for no prompt). A '\n' can be used
5575 in the prompt to start a new line.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005576 The highlighting set with |:echohl| is used for the prompt.
5577 The input is entered just like a command-line, with the same
Bram Moolenaar58b85342016-08-14 19:54:54 +02005578 editing commands and mappings. There is a separate history
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005579 for lines typed for input().
5580 Example: >
5581 :if input("Coffee or beer? ") == "beer"
5582 : echo "Cheers!"
5583 :endif
5584<
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005585 If the optional {text} argument is present and not empty, this
5586 is used for the default reply, as if the user typed this.
5587 Example: >
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005588 :let color = input("Color? ", "white")
5589
5590< The optional {completion} argument specifies the type of
5591 completion supported for the input. Without it completion is
Bram Moolenaar58b85342016-08-14 19:54:54 +02005592 not performed. The supported completion types are the same as
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005593 that can be supplied to a user-defined command using the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005594 "-complete=" argument. Refer to |:command-completion| for
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005595 more information. Example: >
5596 let fname = input("File: ", "", "file")
5597<
5598 NOTE: This function must not be used in a startup file, for
5599 the versions that only run in GUI mode (e.g., the Win32 GUI).
Bram Moolenaar071d4272004-06-13 20:20:40 +00005600 Note: When input() is called from within a mapping it will
5601 consume remaining characters from that mapping, because a
5602 mapping is handled like the characters were typed.
5603 Use |inputsave()| before input() and |inputrestore()|
5604 after input() to avoid that. Another solution is to avoid
5605 that further characters follow in the mapping, e.g., by using
5606 |:execute| or |:normal|.
5607
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005608 Example with a mapping: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005609 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR>
5610 :function GetFoo()
5611 : call inputsave()
5612 : let g:Foo = input("enter search pattern: ")
5613 : call inputrestore()
5614 :endfunction
5615
5616inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005617 Like |input()|, but when the GUI is running and text dialogs
5618 are supported, a dialog window pops up to input the text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005619 Example: >
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02005620 :let n = inputdialog("value for shiftwidth", shiftwidth())
5621 :if n != ""
5622 : let &sw = n
5623 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +00005624< When the dialog is cancelled {cancelreturn} is returned. When
5625 omitted an empty string is returned.
5626 Hitting <Enter> works like pressing the OK button. Hitting
5627 <Esc> works like pressing the Cancel button.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005628 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005629
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005630inputlist({textlist}) *inputlist()*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005631 {textlist} must be a |List| of strings. This |List| is
5632 displayed, one string per line. The user will be prompted to
5633 enter a number, which is returned.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005634 The user can also select an item by clicking on it with the
Bram Moolenaar58b85342016-08-14 19:54:54 +02005635 mouse. For the first string 0 is returned. When clicking
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005636 above the first item a negative number is returned. When
5637 clicking on the prompt one more than the length of {textlist}
5638 is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005639 Make sure {textlist} has less than 'lines' entries, otherwise
Bram Moolenaar58b85342016-08-14 19:54:54 +02005640 it won't work. It's a good idea to put the entry number at
Bram Moolenaaref2f6562007-05-06 13:32:59 +00005641 the start of the string. And put a prompt in the first item.
5642 Example: >
Bram Moolenaar578b49e2005-09-10 19:22:57 +00005643 let color = inputlist(['Select color:', '1. red',
5644 \ '2. green', '3. blue'])
5645
Bram Moolenaar071d4272004-06-13 20:20:40 +00005646inputrestore() *inputrestore()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005647 Restore typeahead that was saved with a previous |inputsave()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005648 Should be called the same number of times inputsave() is
5649 called. Calling it more often is harmless though.
5650 Returns 1 when there is nothing to restore, 0 otherwise.
5651
5652inputsave() *inputsave()*
5653 Preserve typeahead (also from mappings) and clear it, so that
5654 a following prompt gets input from the user. Should be
5655 followed by a matching inputrestore() after the prompt. Can
5656 be used several times, in which case there must be just as
5657 many inputrestore() calls.
5658 Returns 1 when out of memory, 0 otherwise.
5659
5660inputsecret({prompt} [, {text}]) *inputsecret()*
5661 This function acts much like the |input()| function with but
5662 two exceptions:
5663 a) the user's response will be displayed as a sequence of
5664 asterisks ("*") thereby keeping the entry secret, and
5665 b) the user's response will not be recorded on the input
5666 |history| stack.
5667 The result is a String, which is whatever the user actually
5668 typed on the command-line in response to the issued prompt.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00005669 NOTE: Command-line completion is not supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005670
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005671insert({object}, {item} [, {idx}]) *insert()*
5672 When {object} is a |List| or a |Blob| insert {item} at the start
5673 of it.
5674
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005675 If {idx} is specified insert {item} before the item with index
Bram Moolenaar58b85342016-08-14 19:54:54 +02005676 {idx}. If {idx} is zero it goes before the first item, just
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005677 like omitting {idx}. A negative {idx} is also possible, see
5678 |list-index|. -1 inserts just before the last item.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01005679
5680 Returns the resulting |List| or |Blob|. Examples: >
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005681 :let mylist = insert([2, 3, 5], 1)
5682 :call insert(mylist, 4, -1)
5683 :call insert(mylist, 6, len(mylist))
Bram Moolenaara14de3d2005-01-07 21:48:26 +00005684< The last example can be done simpler with |add()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005685 Note that when {item} is a |List| it is inserted as a single
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005686 item. Use |extend()| to concatenate |Lists|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005687
Bram Moolenaard6e256c2011-12-14 15:32:50 +01005688invert({expr}) *invert()*
5689 Bitwise invert. The argument is converted to a number. A
5690 List, Dict or Float argument causes an error. Example: >
5691 :let bits = invert(bits)
5692
Bram Moolenaar071d4272004-06-13 20:20:40 +00005693isdirectory({directory}) *isdirectory()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005694 The result is a Number, which is |TRUE| when a directory
Bram Moolenaar071d4272004-06-13 20:20:40 +00005695 with the name {directory} exists. If {directory} doesn't
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005696 exist, or isn't a directory, the result is |FALSE|. {directory}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005697 is any expression, which is used as a String.
5698
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005699islocked({expr}) *islocked()* *E786*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005700 The result is a Number, which is |TRUE| when {expr} is the
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005701 name of a locked variable.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005702 {expr} must be the name of a variable, |List| item or
5703 |Dictionary| entry, not the variable itself! Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005704 :let alist = [0, ['a', 'b'], 2, 3]
5705 :lockvar 1 alist
5706 :echo islocked('alist') " 1
5707 :echo islocked('alist[1]') " 0
5708
5709< When {expr} is a variable that does not exist you get an error
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00005710 message. Use |exists()| to check for existence.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005711
Bram Moolenaarf3913272016-02-25 00:00:01 +01005712isnan({expr}) *isnan()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02005713 Return |TRUE| if {expr} is a float with value NaN. >
Bram Moolenaarf3913272016-02-25 00:00:01 +01005714 echo isnan(0.0 / 0.0)
5715< 1 ~
5716
5717 {only available when compiled with the |+float| feature}
5718
Bram Moolenaar677ee682005-01-27 14:41:15 +00005719items({dict}) *items()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005720 Return a |List| with all the key-value pairs of {dict}. Each
5721 |List| item is a list with two items: the key of a {dict}
5722 entry and the value of this entry. The |List| is in arbitrary
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01005723 order. Also see |keys()| and |values()|.
5724 Example: >
5725 for [key, value] in items(mydict)
5726 echo key . ': ' . value
5727 endfor
Bram Moolenaar677ee682005-01-27 14:41:15 +00005728
Bram Moolenaar38a55632016-02-15 22:07:32 +01005729job_getchannel({job}) *job_getchannel()*
5730 Get the channel handle that {job} is using.
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01005731 To check if the job has no channel: >
5732 if string(job_getchannel()) == 'channel fail'
5733<
Bram Moolenaar38a55632016-02-15 22:07:32 +01005734 {only available when compiled with the |+job| feature}
5735
Bram Moolenaar65a54642018-04-28 16:56:53 +02005736job_info([{job}]) *job_info()*
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005737 Returns a Dictionary with information about {job}:
5738 "status" what |job_status()| returns
5739 "channel" what |job_getchannel()| returns
Bram Moolenaar65a54642018-04-28 16:56:53 +02005740 "cmd" List of command arguments used to start the job
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02005741 "process" process ID
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02005742 "tty_in" terminal input name, empty when none
5743 "tty_out" terminal output name, empty when none
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005744 "exitval" only valid when "status" is "dead"
Bram Moolenaar975b5272016-03-15 23:10:59 +01005745 "exit_cb" function to be called on exit
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005746 "stoponexit" |job-stoponexit|
5747
Bram Moolenaarb3051ce2019-01-31 15:52:11 +01005748 Only in Unix:
5749 "termsig" the signal which terminated the process
5750 (See |job_stop()| for the values)
5751 only valid when "status" is "dead"
5752
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01005753 Only in MS-Windows:
5754 "tty_type" Type of virtual console in use.
5755 Values are "winpty" or "conpty".
5756 See 'termwintype'.
5757
Bram Moolenaar65a54642018-04-28 16:56:53 +02005758 Without any arguments, returns a List with all Job objects.
5759
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005760job_setoptions({job}, {options}) *job_setoptions()*
5761 Change options for {job}. Supported are:
Bram Moolenaarf6f32c32016-03-12 19:03:59 +01005762 "stoponexit" |job-stoponexit|
Bram Moolenaar975b5272016-03-15 23:10:59 +01005763 "exit_cb" |job-exit_cb|
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005764
Bram Moolenaar38a55632016-02-15 22:07:32 +01005765job_start({command} [, {options}]) *job_start()*
Bram Moolenaar835dc632016-02-07 14:27:38 +01005766 Start a job and return a Job object. Unlike |system()| and
5767 |:!cmd| this does not wait for the job to finish.
Bram Moolenaarc572da52017-08-27 16:52:01 +02005768 To start a job in a terminal window see |term_start()|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005769
Bram Moolenaar5e66b422019-01-24 21:58:10 +01005770 If the job fails to start then |job_status()| on the returned
5771 Job object results in "fail" and none of the callbacks will be
5772 invoked.
5773
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005774 {command} can be a String. This works best on MS-Windows. On
Bram Moolenaar835dc632016-02-07 14:27:38 +01005775 Unix it is split up in white-separated parts to be passed to
5776 execvp(). Arguments in double quotes can contain white space.
5777
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005778 {command} can be a List, where the first item is the executable
Bram Moolenaar835dc632016-02-07 14:27:38 +01005779 and further items are the arguments. All items are converted
5780 to String. This works best on Unix.
5781
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005782 On MS-Windows, job_start() makes a GUI application hidden. If
5783 want to show it, Use |:!start| instead.
5784
Bram Moolenaar835dc632016-02-07 14:27:38 +01005785 The command is executed directly, not through a shell, the
5786 'shell' option is not used. To use the shell: >
5787 let job = job_start(["/bin/sh", "-c", "echo hello"])
5788< Or: >
5789 let job = job_start('/bin/sh -c "echo hello"')
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005790< Note that this will start two processes, the shell and the
5791 command it executes. If you don't want this use the "exec"
5792 shell command.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005793
5794 On Unix $PATH is used to search for the executable only when
5795 the command does not contain a slash.
5796
5797 The job will use the same terminal as Vim. If it reads from
5798 stdin the job and Vim will be fighting over input, that
5799 doesn't work. Redirect stdin and stdout to avoid problems: >
5800 let job = job_start(['sh', '-c', "myserver </dev/null >/dev/null"])
5801<
5802 The returned Job object can be used to get the status with
5803 |job_status()| and stop the job with |job_stop()|.
5804
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02005805 Note that the job object will be deleted if there are no
5806 references to it. This closes the stdin and stderr, which may
5807 cause the job to fail with an error. To avoid this keep a
5808 reference to the job. Thus instead of: >
5809 call job_start('my-command')
5810< use: >
5811 let myjob = job_start('my-command')
5812< and unlet "myjob" once the job is not needed or is past the
5813 point where it would fail (e.g. when it prints a message on
5814 startup). Keep in mind that variables local to a function
5815 will cease to exist if the function returns. Use a
5816 script-local variable if needed: >
5817 let s:myjob = job_start('my-command')
5818<
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005819 {options} must be a Dictionary. It can contain many optional
5820 items, see |job-options|.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005821
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005822 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01005823
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005824job_status({job}) *job_status()* *E916*
Bram Moolenaar835dc632016-02-07 14:27:38 +01005825 Returns a String with the status of {job}:
5826 "run" job is running
5827 "fail" job failed to start
5828 "dead" job died or was stopped after running
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005829
Bram Moolenaar511972d2016-06-04 18:09:59 +02005830 On Unix a non-existing command results in "dead" instead of
5831 "fail", because a fork happens before the failure can be
5832 detected.
5833
Bram Moolenaar03413f42016-04-12 21:07:15 +02005834 If an exit callback was set with the "exit_cb" option and the
Bram Moolenaar02e83b42016-02-21 20:10:26 +01005835 job is now detected to be "dead" the callback will be invoked.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005836
Bram Moolenaar8950a562016-03-12 15:22:55 +01005837 For more information see |job_info()|.
5838
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005839 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01005840
5841job_stop({job} [, {how}]) *job_stop()*
5842 Stop the {job}. This can also be used to signal the job.
5843
Bram Moolenaar923d9262016-02-25 20:56:01 +01005844 When {how} is omitted or is "term" the job will be terminated.
5845 For Unix SIGTERM is sent. On MS-Windows the job will be
5846 terminated forcedly (there is no "gentle" way).
5847 This goes to the process group, thus children may also be
5848 affected.
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005849
Bram Moolenaar923d9262016-02-25 20:56:01 +01005850 Effect for Unix:
5851 "term" SIGTERM (default)
5852 "hup" SIGHUP
5853 "quit" SIGQUIT
5854 "int" SIGINT
5855 "kill" SIGKILL (strongest way to stop)
5856 number signal with that number
Bram Moolenaar835dc632016-02-07 14:27:38 +01005857
Bram Moolenaar923d9262016-02-25 20:56:01 +01005858 Effect for MS-Windows:
5859 "term" terminate process forcedly (default)
5860 "hup" CTRL_BREAK
5861 "quit" CTRL_BREAK
5862 "int" CTRL_C
5863 "kill" terminate process forcedly
5864 Others CTRL_BREAK
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005865
5866 On Unix the signal is sent to the process group. This means
5867 that when the job is "sh -c command" it affects both the shell
5868 and the command.
5869
Bram Moolenaar835dc632016-02-07 14:27:38 +01005870 The result is a Number: 1 if the operation could be executed,
5871 0 if "how" is not supported on the system.
5872 Note that even when the operation was executed, whether the
5873 job was actually stopped needs to be checked with
Bram Moolenaar45d2cca2017-04-30 16:36:05 +02005874 |job_status()|.
5875
5876 If the status of the job is "dead", the signal will not be
5877 sent. This is to avoid to stop the wrong job (esp. on Unix,
5878 where process numbers are recycled).
5879
5880 When using "kill" Vim will assume the job will die and close
5881 the channel.
Bram Moolenaar835dc632016-02-07 14:27:38 +01005882
Bram Moolenaar6463ca22016-02-13 17:04:46 +01005883 {only available when compiled with the |+job| feature}
Bram Moolenaar835dc632016-02-07 14:27:38 +01005884
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005885join({list} [, {sep}]) *join()*
5886 Join the items in {list} together into one String.
5887 When {sep} is specified it is put in between the items. If
5888 {sep} is omitted a single space is used.
5889 Note that {sep} is not added at the end. You might want to
5890 add it there too: >
5891 let lines = join(mylist, "\n") . "\n"
Bram Moolenaara23ccb82006-02-27 00:08:02 +00005892< String items are used as-is. |Lists| and |Dictionaries| are
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00005893 converted into a string like with |string()|.
5894 The opposite function is |split()|.
5895
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005896js_decode({string}) *js_decode()*
5897 This is similar to |json_decode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005898 - Object key names do not have to be in quotes.
Bram Moolenaaree142ad2017-01-11 21:50:08 +01005899 - Strings can be in single quotes.
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005900 - Empty items in an array (between two commas) are allowed and
5901 result in v:none items.
5902
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005903js_encode({expr}) *js_encode()*
5904 This is similar to |json_encode()| with these differences:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005905 - Object key names are not in quotes.
5906 - v:none items in an array result in an empty item between
5907 commas.
5908 For example, the Vim object:
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005909 [1,v:none,{"one":1},v:none] ~
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005910 Will be encoded as:
5911 [1,,{one:1},,] ~
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005912 While json_encode() would produce:
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005913 [1,null,{"one":1},null] ~
5914 This encoding is valid for JavaScript. It is more efficient
5915 than JSON, especially when using an array with optional items.
5916
5917
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005918json_decode({string}) *json_decode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01005919 This parses a JSON formatted string and returns the equivalent
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005920 in Vim values. See |json_encode()| for the relation between
Bram Moolenaar705ada12016-01-24 17:56:50 +01005921 JSON and Vim values.
5922 The decoding is permissive:
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005923 - A trailing comma in an array and object is ignored, e.g.
5924 "[1, 2, ]" is the same as "[1, 2]".
Bram Moolenaard09091d2019-01-17 16:07:22 +01005925 - Integer keys are accepted in objects, e.g. {1:2} is the
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01005926 same as {"1":2}.
Bram Moolenaar705ada12016-01-24 17:56:50 +01005927 - More floating point numbers are recognized, e.g. "1." for
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005928 "1.0", or "001.2" for "1.2". Special floating point values
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01005929 "Infinity", "-Infinity" and "NaN" (capitalization ignored)
5930 are accepted.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005931 - Leading zeroes in integer numbers are ignored, e.g. "012"
5932 for "12" or "-012" for "-12".
5933 - Capitalization is ignored in literal names null, true or
5934 false, e.g. "NULL" for "null", "True" for "true".
5935 - Control characters U+0000 through U+001F which are not
5936 escaped in strings are accepted, e.g. " " (tab
5937 character in string) for "\t".
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01005938 - An empty JSON expression or made of only spaces is accepted
5939 and results in v:none.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +02005940 - Backslash in an invalid 2-character sequence escape is
5941 ignored, e.g. "\a" is decoded as "a".
5942 - A correct surrogate pair in JSON strings should normally be
5943 a 12 character sequence such as "\uD834\uDD1E", but
5944 json_decode() silently accepts truncated surrogate pairs
5945 such as "\uD834" or "\uD834\u"
5946 *E938*
5947 A duplicate key in an object, valid in rfc7159, is not
5948 accepted by json_decode() as the result must be a valid Vim
5949 type, e.g. this fails: {"a":"b", "a":"c"}
5950
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005951
Bram Moolenaar7823a3b2016-02-11 21:08:32 +01005952json_encode({expr}) *json_encode()*
Bram Moolenaar705ada12016-01-24 17:56:50 +01005953 Encode {expr} as JSON and return this as a string.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005954 The encoding is specified in:
Bram Moolenaar009d84a2016-01-28 14:12:00 +01005955 https://tools.ietf.org/html/rfc7159.html
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005956 Vim values are converted as follows:
Bram Moolenaard09091d2019-01-17 16:07:22 +01005957 |Number| decimal number
5958 |Float| floating point number
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01005959 Float nan "NaN"
5960 Float inf "Infinity"
Bram Moolenaar5f6b3792019-01-12 14:24:27 +01005961 Float -inf "-Infinity"
Bram Moolenaard09091d2019-01-17 16:07:22 +01005962 |String| in double quotes (possibly null)
5963 |Funcref| not possible, error
5964 |List| as an array (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02005965 used recursively: []
Bram Moolenaard09091d2019-01-17 16:07:22 +01005966 |Dict| as an object (possibly null); when
Bram Moolenaar81edd172016-04-14 13:51:37 +02005967 used recursively: {}
Bram Moolenaard09091d2019-01-17 16:07:22 +01005968 |Blob| as an array of the individual bytes
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005969 v:false "false"
5970 v:true "true"
Bram Moolenaar595e64e2016-02-07 19:19:53 +01005971 v:none "null"
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005972 v:null "null"
Bram Moolenaar7ce686c2016-02-27 16:33:22 +01005973 Note that NaN and Infinity are passed on as values. This is
5974 missing in the JSON standard, but several implementations do
5975 allow it. If not then you will get an error.
Bram Moolenaar520e1e42016-01-23 19:46:28 +01005976
Bram Moolenaard8b02732005-01-14 21:48:43 +00005977keys({dict}) *keys()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005978 Return a |List| with all the keys of {dict}. The |List| is in
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01005979 arbitrary order. Also see |items()| and |values()|.
Bram Moolenaard8b02732005-01-14 21:48:43 +00005980
Bram Moolenaar13065c42005-01-08 16:08:21 +00005981 *len()* *E701*
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005982len({expr}) The result is a Number, which is the length of the argument.
5983 When {expr} is a String or a Number the length in bytes is
5984 used, as with |strlen()|.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005985 When {expr} is a |List| the number of items in the |List| is
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005986 returned.
Bram Moolenaard09091d2019-01-17 16:07:22 +01005987 When {expr} is a |Blob| the number of bytes is returned.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00005988 When {expr} is a |Dictionary| the number of entries in the
5989 |Dictionary| is returned.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00005990 Otherwise an error is given.
5991
Bram Moolenaar071d4272004-06-13 20:20:40 +00005992 *libcall()* *E364* *E368*
5993libcall({libname}, {funcname}, {argument})
5994 Call function {funcname} in the run-time library {libname}
5995 with single argument {argument}.
5996 This is useful to call functions in a library that you
5997 especially made to be used with Vim. Since only one argument
5998 is possible, calling standard library functions is rather
5999 limited.
6000 The result is the String returned by the function. If the
6001 function returns NULL, this will appear as an empty string ""
6002 to Vim.
6003 If the function returns a number, use libcallnr()!
6004 If {argument} is a number, it is passed to the function as an
6005 int; if {argument} is a string, it is passed as a
6006 null-terminated string.
6007 This function will fail in |restricted-mode|.
6008
6009 libcall() allows you to write your own 'plug-in' extensions to
6010 Vim without having to recompile the program. It is NOT a
6011 means to call system functions! If you try to do so Vim will
6012 very probably crash.
6013
6014 For Win32, the functions you write must be placed in a DLL
6015 and use the normal C calling convention (NOT Pascal which is
6016 used in Windows System DLLs). The function must take exactly
6017 one parameter, either a character pointer or a long integer,
6018 and must return a character pointer or NULL. The character
6019 pointer returned must point to memory that will remain valid
6020 after the function has returned (e.g. in static data in the
6021 DLL). If it points to allocated memory, that memory will
6022 leak away. Using a static buffer in the function should work,
6023 it's then freed when the DLL is unloaded.
6024
6025 WARNING: If the function returns a non-valid pointer, Vim may
Bram Moolenaar446cb832008-06-24 21:56:24 +00006026 crash! This also happens if the function returns a number,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006027 because Vim thinks it's a pointer.
6028 For Win32 systems, {libname} should be the filename of the DLL
6029 without the ".DLL" suffix. A full path is only required if
6030 the DLL is not in the usual places.
6031 For Unix: When compiling your own plugins, remember that the
6032 object code must be compiled as position-independent ('PIC').
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006033 {only in Win32 and some Unix versions, when the |+libcall|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006034 feature is present}
6035 Examples: >
6036 :echo libcall("libc.so", "getenv", "HOME")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006037<
6038 *libcallnr()*
6039libcallnr({libname}, {funcname}, {argument})
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006040 Just like |libcall()|, but used for a function that returns an
Bram Moolenaar071d4272004-06-13 20:20:40 +00006041 int instead of a string.
6042 {only in Win32 on some Unix versions, when the |+libcall|
6043 feature is present}
Bram Moolenaar446cb832008-06-24 21:56:24 +00006044 Examples: >
6045 :echo libcallnr("/usr/lib/libc.so", "getpid", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006046 :call libcallnr("libc.so", "printf", "Hello World!\n")
6047 :call libcallnr("libc.so", "sleep", 10)
6048<
6049 *line()*
6050line({expr}) The result is a Number, which is the line number of the file
6051 position given with {expr}. The accepted positions are:
6052 . the cursor position
6053 $ the last line in the current buffer
6054 'x position of mark x (if the mark is not set, 0 is
6055 returned)
Bram Moolenaara1d5fa62017-04-03 22:02:55 +02006056 w0 first line visible in current window (one if the
6057 display isn't updated, e.g. in silent Ex mode)
6058 w$ last line visible in current window (this is one
6059 less than "w0" if no lines are visible)
Bram Moolenaar9ecd0232008-06-20 15:31:51 +00006060 v In Visual mode: the start of the Visual area (the
6061 cursor is the end). When not in Visual mode
6062 returns the cursor position. Differs from |'<| in
6063 that it's updated right away.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00006064 Note that a mark in another file can be used. The line number
6065 then applies to another buffer.
Bram Moolenaar0b238792006-03-02 22:49:12 +00006066 To get the column number use |col()|. To get both use
6067 |getpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006068 Examples: >
6069 line(".") line number of the cursor
6070 line("'t") line number of mark t
6071 line("'" . marker) line number of mark marker
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006072<
6073 To jump to the last known position when opening a file see
6074 |last-position-jump|.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00006075
Bram Moolenaar071d4272004-06-13 20:20:40 +00006076line2byte({lnum}) *line2byte()*
6077 Return the byte count from the start of the buffer for line
6078 {lnum}. This includes the end-of-line character, depending on
6079 the 'fileformat' option for the current buffer. The first
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006080 line returns 1. 'encoding' matters, 'fileencoding' is ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006081 This can also be used to get the byte count for the line just
6082 below the last line: >
6083 line2byte(line("$") + 1)
Bram Moolenaarb6b046b2011-12-30 13:11:27 +01006084< This is the buffer size plus one. If 'fileencoding' is empty
6085 it is the file size plus one.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006086 When {lnum} is invalid, or the |+byte_offset| feature has been
6087 disabled at compile time, -1 is returned.
6088 Also see |byte2line()|, |go| and |:goto|.
6089
6090lispindent({lnum}) *lispindent()*
6091 Get the amount of indent for line {lnum} according the lisp
6092 indenting rules, as with 'lisp'.
6093 The indent is counted in spaces, the value of 'tabstop' is
6094 relevant. {lnum} is used just like in |getline()|.
6095 When {lnum} is invalid or Vim was not compiled the
6096 |+lispindent| feature, -1 is returned.
6097
6098localtime() *localtime()*
6099 Return the current time, measured as seconds since 1st Jan
6100 1970. See also |strftime()| and |getftime()|.
6101
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006102
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006103log({expr}) *log()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02006104 Return the natural logarithm (base e) of {expr} as a |Float|.
6105 {expr} must evaluate to a |Float| or a |Number| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006106 (0, inf].
6107 Examples: >
6108 :echo log(10)
6109< 2.302585 >
6110 :echo log(exp(5))
6111< 5.0
Bram Moolenaardb84e452010-08-15 13:50:43 +02006112 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02006113
6114
Bram Moolenaar446cb832008-06-24 21:56:24 +00006115log10({expr}) *log10()*
6116 Return the logarithm of Float {expr} to base 10 as a |Float|.
6117 {expr} must evaluate to a |Float| or a |Number|.
6118 Examples: >
6119 :echo log10(1000)
6120< 3.0 >
6121 :echo log10(0.01)
6122< -2.0
6123 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006124
6125luaeval({expr} [, {expr}]) *luaeval()*
6126 Evaluate Lua expression {expr} and return its result converted
6127 to Vim data structures. Second {expr} may hold additional
Bram Moolenaard38b0552012-04-25 19:07:41 +02006128 argument accessible as _A inside first {expr}.
6129 Strings are returned as they are.
6130 Boolean objects are converted to numbers.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006131 Numbers are converted to |Float| values if vim was compiled
Bram Moolenaard38b0552012-04-25 19:07:41 +02006132 with |+float| and to numbers otherwise.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006133 Dictionaries and lists obtained by vim.eval() are returned
Bram Moolenaard38b0552012-04-25 19:07:41 +02006134 as-is.
6135 Other objects are returned as zero without any errors.
6136 See |lua-luaeval| for more details.
6137 {only available when compiled with the |+lua| feature}
6138
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006139map({expr1}, {expr2}) *map()*
6140 {expr1} must be a |List| or a |Dictionary|.
6141 Replace each item in {expr1} with the result of evaluating
6142 {expr2}. {expr2} must be a |string| or |Funcref|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006143
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006144 If {expr2} is a |string|, inside {expr2} |v:val| has the value
6145 of the current item. For a |Dictionary| |v:key| has the key
6146 of the current item and for a |List| |v:key| has the index of
6147 the current item.
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006148 Example: >
6149 :call map(mylist, '"> " . v:val . " <"')
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006150< This puts "> " before and " <" after each item in "mylist".
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006151
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006152 Note that {expr2} is the result of an expression and is then
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006153 used as an expression again. Often it is good to use a
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006154 |literal-string| to avoid having to double backslashes. You
6155 still have to double ' quotes
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006156
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006157 If {expr2} is a |Funcref| it is called with two arguments:
6158 1. The key or the index of the current item.
6159 2. the value of the current item.
6160 The function must return the new value of the item. Example
6161 that changes each value by "key-value": >
6162 func KeyValue(key, val)
6163 return a:key . '-' . a:val
6164 endfunc
6165 call map(myDict, function('KeyValue'))
Bram Moolenaar50ba5262016-09-22 22:33:02 +02006166< It is shorter when using a |lambda|: >
6167 call map(myDict, {key, val -> key . '-' . val})
6168< If you do not use "val" you can leave it out: >
6169 call map(myDict, {key -> 'item: ' . key})
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006170<
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006171 The operation is done in-place. If you want a |List| or
6172 |Dictionary| to remain unmodified make a copy first: >
Bram Moolenaar30b65812012-07-12 22:01:11 +02006173 :let tlist = map(copy(mylist), ' v:val . "\t"')
Bram Moolenaar2fda12f2005-01-15 22:14:15 +00006174
Bram Moolenaarb33c7eb2016-07-04 22:29:49 +02006175< Returns {expr1}, the |List| or |Dictionary| that was filtered.
6176 When an error is encountered while evaluating {expr2} no
6177 further items in {expr1} are processed. When {expr2} is a
6178 Funcref errors inside a function are ignored, unless it was
6179 defined with the "abort" flag.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006180
6181
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006182maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()*
Bram Moolenaarbd743252010-10-20 21:23:33 +02006183 When {dict} is omitted or zero: Return the rhs of mapping
6184 {name} in mode {mode}. The returned String has special
6185 characters translated like in the output of the ":map" command
6186 listing.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006187
Bram Moolenaarbd743252010-10-20 21:23:33 +02006188 When there is no mapping for {name}, an empty String is
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006189 returned. When the mapping for {name} is empty, then "<Nop>"
6190 is returned.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006191
6192 The {name} can have special key names, like in the ":map"
6193 command.
6194
Bram Moolenaard12f5c12006-01-25 22:10:52 +00006195 {mode} can be one of these strings:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006196 "n" Normal
Bram Moolenaarbd743252010-10-20 21:23:33 +02006197 "v" Visual (including Select)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006198 "o" Operator-pending
6199 "i" Insert
6200 "c" Cmd-line
Bram Moolenaarbd743252010-10-20 21:23:33 +02006201 "s" Select
6202 "x" Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +00006203 "l" langmap |language-mapping|
Bram Moolenaar37c64c72017-09-19 22:06:03 +02006204 "t" Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +00006205 "" Normal, Visual and Operator-pending
Bram Moolenaard12f5c12006-01-25 22:10:52 +00006206 When {mode} is omitted, the modes for "" are used.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006207
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006208 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006209 instead of mappings.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006210
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006211 When {dict} is there and it is |TRUE| return a dictionary
Bram Moolenaarbd743252010-10-20 21:23:33 +02006212 containing all the information of the mapping with the
6213 following items:
6214 "lhs" The {lhs} of the mapping.
6215 "rhs" The {rhs} of the mapping as typed.
6216 "silent" 1 for a |:map-silent| mapping, else 0.
Bram Moolenaar05365702010-10-27 18:34:44 +02006217 "noremap" 1 if the {rhs} of the mapping is not remappable.
Bram Moolenaarbd743252010-10-20 21:23:33 +02006218 "expr" 1 for an expression mapping (|:map-<expr>|).
6219 "buffer" 1 for a buffer local mapping (|:map-local|).
6220 "mode" Modes for which the mapping is defined. In
6221 addition to the modes mentioned above, these
6222 characters will be used:
6223 " " Normal, Visual and Operator-pending
6224 "!" Insert and Commandline mode
Bram Moolenaar166af9b2010-11-16 20:34:40 +01006225 (|mapmode-ic|)
Bram Moolenaar05365702010-10-27 18:34:44 +02006226 "sid" The script local ID, used for <sid> mappings
6227 (|<SID>|).
Bram Moolenaarf29c1c62018-09-10 21:05:02 +02006228 "lnum" The line number in "sid", zero if unknown.
Bram Moolenaardfb18412013-12-11 18:53:29 +01006229 "nowait" Do not wait for other, longer mappings.
6230 (|:map-<nowait>|).
Bram Moolenaarbd743252010-10-20 21:23:33 +02006231
Bram Moolenaar071d4272004-06-13 20:20:40 +00006232 The mappings local to the current buffer are checked first,
6233 then the global mappings.
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00006234 This function can be used to map a key even when it's already
6235 mapped, and have it do the original mapping too. Sketch: >
6236 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n')
6237
Bram Moolenaar071d4272004-06-13 20:20:40 +00006238
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006239mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006240 Check if there is a mapping that matches with {name} in mode
6241 {mode}. See |maparg()| for {mode} and special names in
6242 {name}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006243 When {abbr} is there and it is |TRUE| use abbreviations
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00006244 instead of mappings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006245 A match happens with a mapping that starts with {name} and
6246 with a mapping which is equal to the start of {name}.
6247
Bram Moolenaar446cb832008-06-24 21:56:24 +00006248 matches mapping "a" "ab" "abc" ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00006249 mapcheck("a") yes yes yes
6250 mapcheck("abc") yes yes yes
6251 mapcheck("ax") yes no no
6252 mapcheck("b") no no no
6253
6254 The difference with maparg() is that mapcheck() finds a
6255 mapping that matches with {name}, while maparg() only finds a
6256 mapping for {name} exactly.
6257 When there is no mapping that starts with {name}, an empty
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006258 String is returned. If there is one, the RHS of that mapping
Bram Moolenaar071d4272004-06-13 20:20:40 +00006259 is returned. If there are several mappings that start with
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02006260 {name}, the RHS of one of them is returned. This will be
6261 "<Nop>" if the RHS is empty.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006262 The mappings local to the current buffer are checked first,
6263 then the global mappings.
6264 This function can be used to check if a mapping can be added
6265 without being ambiguous. Example: >
6266 :if mapcheck("_vv") == ""
6267 : map _vv :set guifont=7x13<CR>
6268 :endif
6269< This avoids adding the "_vv" mapping when there already is a
6270 mapping for "_v" or for "_vvv".
6271
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006272match({expr}, {pat} [, {start} [, {count}]]) *match()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006273 When {expr} is a |List| then this returns the index of the
6274 first item where {pat} matches. Each item is used as a
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006275 String, |Lists| and |Dictionaries| are used as echoed.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006276
Bram Moolenaar58b85342016-08-14 19:54:54 +02006277 Otherwise, {expr} is used as a String. The result is a
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006278 Number, which gives the index (byte offset) in {expr} where
6279 {pat} matches.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006280
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006281 A match at the first character or |List| item returns zero.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00006282 If there is no match -1 is returned.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02006283
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02006284 For getting submatches see |matchlist()|.
Bram Moolenaar89cb5e02004-07-19 20:55:54 +00006285 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006286 :echo match("testing", "ing") " results in 4
Bram Moolenaar362e1a32006-03-06 23:29:24 +00006287 :echo match([1, 'x'], '\a') " results in 1
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006288< See |string-match| for how {pat} is used.
Bram Moolenaar05159a02005-02-26 23:04:13 +00006289 *strpbrk()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02006290 Vim doesn't have a strpbrk() function. But you can do: >
Bram Moolenaar05159a02005-02-26 23:04:13 +00006291 :let sepidx = match(line, '[.,;: \t]')
6292< *strcasestr()*
6293 Vim doesn't have a strcasestr() function. But you can add
6294 "\c" to the pattern to ignore case: >
6295 :let idx = match(haystack, '\cneedle')
6296<
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006297 If {start} is given, the search starts from byte index
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006298 {start} in a String or item {start} in a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006299 The result, however, is still the index counted from the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006300 first character/item. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006301 :echo match("testing", "ing", 2)
6302< result is again "4". >
6303 :echo match("testing", "ing", 4)
6304< result is again "4". >
6305 :echo match("testing", "t", 2)
6306< result is "3".
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006307 For a String, if {start} > 0 then it is like the string starts
Bram Moolenaar0b238792006-03-02 22:49:12 +00006308 {start} bytes later, thus "^" will match at {start}. Except
6309 when {count} is given, then it's like matches before the
6310 {start} byte are ignored (this is a bit complicated to keep it
6311 backwards compatible).
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006312 For a String, if {start} < 0, it will be set to 0. For a list
6313 the index is counted from the end.
Bram Moolenaare224ffa2006-03-01 00:01:28 +00006314 If {start} is out of range ({start} > strlen({expr}) for a
6315 String or {start} > len({expr}) for a |List|) -1 is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006316
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006317 When {count} is given use the {count}'th match. When a match
Bram Moolenaare224ffa2006-03-01 00:01:28 +00006318 is found in a String the search for the next one starts one
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006319 character further. Thus this example results in 1: >
6320 echo match("testing", "..", 0, 2)
6321< In a |List| the search continues in the next item.
Bram Moolenaar0b238792006-03-02 22:49:12 +00006322 Note that when {count} is added the way {start} works changes,
6323 see above.
Bram Moolenaar5e3cb7e2006-02-27 23:58:35 +00006324
Bram Moolenaar071d4272004-06-13 20:20:40 +00006325 See |pattern| for the patterns that are accepted.
6326 The 'ignorecase' option is used to set the ignore-caseness of
Bram Moolenaar58b85342016-08-14 19:54:54 +02006327 the pattern. 'smartcase' is NOT used. The matching is always
Bram Moolenaar071d4272004-06-13 20:20:40 +00006328 done like 'magic' is set and 'cpoptions' is empty.
6329
Bram Moolenaar95e51472018-07-28 16:55:56 +02006330 *matchadd()* *E798* *E799* *E801* *E957*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006331matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006332 Defines a pattern to be highlighted in the current window (a
6333 "match"). It will be highlighted with {group}. Returns an
6334 identification number (ID), which can be used to delete the
6335 match using |matchdelete()|.
Bram Moolenaar8e69b4a2013-11-09 03:41:58 +01006336 Matching is case sensitive and magic, unless case sensitivity
6337 or magicness are explicitly overridden in {pattern}. The
6338 'magic', 'smartcase' and 'ignorecase' options are not used.
Bram Moolenaarf9132812015-07-21 19:19:13 +02006339 The "Conceal" value is special, it causes the match to be
6340 concealed.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006341
6342 The optional {priority} argument assigns a priority to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02006343 match. A match with a high priority will have its
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006344 highlighting overrule that of a match with a lower priority.
6345 A priority is specified as an integer (negative numbers are no
6346 exception). If the {priority} argument is not specified, the
6347 default priority is 10. The priority of 'hlsearch' is zero,
6348 hence all matches with a priority greater than zero will
6349 overrule it. Syntax highlighting (see 'syntax') is a separate
6350 mechanism, and regardless of the chosen priority a match will
6351 always overrule syntax highlighting.
6352
6353 The optional {id} argument allows the request for a specific
6354 match ID. If a specified ID is already taken, an error
6355 message will appear and the match will not be added. An ID
6356 is specified as a positive integer (zero excluded). IDs 1, 2
6357 and 3 are reserved for |:match|, |:2match| and |:3match|,
Bram Moolenaar6561d522015-07-21 15:48:27 +02006358 respectively. If the {id} argument is not specified or -1,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006359 |matchadd()| automatically chooses a free ID.
6360
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006361 The optional {dict} argument allows for further custom
6362 values. Currently this is used to specify a match specific
Bram Moolenaar6561d522015-07-21 15:48:27 +02006363 conceal character that will be shown for |hl-Conceal|
6364 highlighted matches. The dict can have the following members:
6365
6366 conceal Special character to show instead of the
Bram Moolenaar6463ca22016-02-13 17:04:46 +01006367 match (only for |hl-Conceal| highlighted
Bram Moolenaar6561d522015-07-21 15:48:27 +02006368 matches, see |:syn-cchar|)
Bram Moolenaar95e51472018-07-28 16:55:56 +02006369 window Instead of the current window use the
6370 window with this number or window ID.
Bram Moolenaar6561d522015-07-21 15:48:27 +02006371
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006372 The number of matches is not limited, as it is the case with
6373 the |:match| commands.
6374
6375 Example: >
6376 :highlight MyGroup ctermbg=green guibg=green
6377 :let m = matchadd("MyGroup", "TODO")
6378< Deletion of the pattern: >
6379 :call matchdelete(m)
6380
6381< A list of matches defined by |matchadd()| and |:match| are
Bram Moolenaar58b85342016-08-14 19:54:54 +02006382 available from |getmatches()|. All matches can be deleted in
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006383 one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006384
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02006385 *matchaddpos()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006386matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])
Bram Moolenaarb3414592014-06-17 17:48:32 +02006387 Same as |matchadd()|, but requires a list of positions {pos}
6388 instead of a pattern. This command is faster than |matchadd()|
6389 because it does not require to handle regular expressions and
6390 sets buffer line boundaries to redraw screen. It is supposed
6391 to be used when fast match additions and deletions are
6392 required, for example to highlight matching parentheses.
6393
6394 The list {pos} can contain one of these items:
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006395 - A number. This whole line will be highlighted. The first
Bram Moolenaarb3414592014-06-17 17:48:32 +02006396 line has number 1.
6397 - A list with one number, e.g., [23]. The whole line with this
6398 number will be highlighted.
6399 - A list with two numbers, e.g., [23, 11]. The first number is
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006400 the line number, the second one is the column number (first
6401 column is 1, the value must correspond to the byte index as
6402 |col()| would return). The character at this position will
6403 be highlighted.
Bram Moolenaarb3414592014-06-17 17:48:32 +02006404 - A list with three numbers, e.g., [23, 11, 3]. As above, but
Bram Moolenaarb6da44a2014-06-25 18:15:22 +02006405 the third number gives the length of the highlight in bytes.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006406
Bram Moolenaarb3414592014-06-17 17:48:32 +02006407 The maximum number of positions is 8.
6408
6409 Example: >
6410 :highlight MyGroup ctermbg=green guibg=green
6411 :let m = matchaddpos("MyGroup", [[23, 24], 34])
6412< Deletion of the pattern: >
6413 :call matchdelete(m)
6414
6415< Matches added by |matchaddpos()| are returned by
6416 |getmatches()| with an entry "pos1", "pos2", etc., with the
6417 value a list like the {pos} item.
Bram Moolenaarb3414592014-06-17 17:48:32 +02006418
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006419matcharg({nr}) *matcharg()*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006420 Selects the {nr} match item, as set with a |:match|,
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006421 |:2match| or |:3match| command.
6422 Return a |List| with two elements:
6423 The name of the highlight group used
6424 The pattern used.
6425 When {nr} is not 1, 2 or 3 returns an empty |List|.
6426 When there is no match item set returns ['', ''].
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006427 This is useful to save and restore a |:match|.
6428 Highlighting matches using the |:match| commands are limited
6429 to three matches. |matchadd()| does not have this limitation.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006430
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006431matchdelete({id}) *matchdelete()* *E802* *E803*
6432 Deletes a match with ID {id} previously defined by |matchadd()|
Bram Moolenaar446cb832008-06-24 21:56:24 +00006433 or one of the |:match| commands. Returns 0 if successful,
Bram Moolenaar6ee10162007-07-26 20:58:42 +00006434 otherwise -1. See example for |matchadd()|. All matches can
6435 be deleted in one operation by |clearmatches()|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006436
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006437matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006438 Same as |match()|, but return the index of first character
6439 after the match. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006440 :echo matchend("testing", "ing")
6441< results in "7".
Bram Moolenaar05159a02005-02-26 23:04:13 +00006442 *strspn()* *strcspn()*
6443 Vim doesn't have a strspn() or strcspn() function, but you can
6444 do it with matchend(): >
6445 :let span = matchend(line, '[a-zA-Z]')
6446 :let span = matchend(line, '[^a-zA-Z]')
6447< Except that -1 is returned when there are no matches.
6448
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006449 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006450 :echo matchend("testing", "ing", 2)
6451< results in "7". >
6452 :echo matchend("testing", "ing", 5)
6453< result is "-1".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006454 When {expr} is a |List| the result is equal to |match()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006455
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006456matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006457 Same as |match()|, but return a |List|. The first item in the
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006458 list is the matched string, same as what matchstr() would
6459 return. Following items are submatches, like "\1", "\2", etc.
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00006460 in |:substitute|. When an optional submatch didn't match an
6461 empty string is used. Example: >
6462 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)')
6463< Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', '']
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00006464 When there is no match an empty list is returned.
6465
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006466matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006467 Same as |match()|, but return the matched string. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006468 :echo matchstr("testing", "ing")
6469< results in "ing".
6470 When there is no match "" is returned.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006471 The {start}, if given, has the same meaning as for |match()|. >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006472 :echo matchstr("testing", "ing", 2)
6473< results in "ing". >
6474 :echo matchstr("testing", "ing", 5)
6475< result is "".
Bram Moolenaar32466aa2006-02-24 23:53:04 +00006476 When {expr} is a |List| then the matching item is returned.
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00006477 The type isn't changed, it's not necessarily a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006478
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006479matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()*
Bram Moolenaar7fed5c12016-03-29 23:10:31 +02006480 Same as |matchstr()|, but return the matched string, the start
6481 position and the end position of the match. Example: >
6482 :echo matchstrpos("testing", "ing")
6483< results in ["ing", 4, 7].
6484 When there is no match ["", -1, -1] is returned.
6485 The {start}, if given, has the same meaning as for |match()|. >
6486 :echo matchstrpos("testing", "ing", 2)
6487< results in ["ing", 4, 7]. >
6488 :echo matchstrpos("testing", "ing", 5)
6489< result is ["", -1, -1].
6490 When {expr} is a |List| then the matching item, the index
6491 of first item where {pat} matches, the start position and the
6492 end position of the match are returned. >
6493 :echo matchstrpos([1, '__x'], '\a')
6494< result is ["x", 1, 2, 3].
6495 The type isn't changed, it's not necessarily a String.
6496
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006497 *max()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01006498max({expr}) Return the maximum value of all items in {expr}.
6499 {expr} can be a list or a dictionary. For a dictionary,
6500 it returns the maximum of all values in the dictionary.
6501 If {expr} is neither a list nor a dictionary, or one of the
6502 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006503 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006504
6505 *min()*
Bram Moolenaar690afe12017-01-28 18:34:47 +01006506min({expr}) Return the minimum value of all items in {expr}.
6507 {expr} can be a list or a dictionary. For a dictionary,
6508 it returns the minimum of all values in the dictionary.
6509 If {expr} is neither a list nor a dictionary, or one of the
6510 items in {expr} cannot be used as a Number this results in
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006511 an error. An empty |List| or |Dictionary| results in zero.
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00006512
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00006513 *mkdir()* *E739*
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006514mkdir({name} [, {path} [, {prot}]])
6515 Create directory {name}.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006516
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006517 If {path} is "p" then intermediate directories are created as
6518 necessary. Otherwise it must be "".
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006519
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006520 If {prot} is given it is used to set the protection bits of
6521 the new directory. The default is 0755 (rwxr-xr-x: r/w for
Bram Moolenaar58b85342016-08-14 19:54:54 +02006522 the user readable for others). Use 0700 to make it unreadable
Bram Moolenaared39e1d2008-08-09 17:55:22 +00006523 for others. This is only used for the last part of {name}.
6524 Thus if you create /tmp/foo/bar then /tmp/foo will be created
6525 with 0755.
6526 Example: >
6527 :call mkdir($HOME . "/tmp/foo/bar", "p", 0700)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006528
Bram Moolenaared39e1d2008-08-09 17:55:22 +00006529< This function is not available in the |sandbox|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006530
Bram Moolenaar78a16b02018-04-14 13:51:55 +02006531 There is no error if the directory already exists and the "p"
Bram Moolenaar39536dd2019-01-29 22:58:21 +01006532 flag is passed (since patch 8.0.1708). However, without the
6533 "p" option the call will fail.
6534
6535 The function result is a Number, which is 1 if the call was
6536 successful or 0 if the directory creation failed or partly
6537 failed.
6538
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006539 Not available on all systems. To check use: >
6540 :if exists("*mkdir")
6541<
Bram Moolenaar071d4272004-06-13 20:20:40 +00006542 *mode()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00006543mode([expr]) Return a string that indicates the current mode.
Bram Moolenaar05bb9532008-07-04 09:44:11 +00006544 If [expr] is supplied and it evaluates to a non-zero Number or
6545 a non-empty String (|non-zero-arg|), then the full mode is
Bram Moolenaare381d3d2016-07-07 14:50:41 +02006546 returned, otherwise only the first letter is returned.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006547
Bram Moolenaar612cc382018-07-29 15:34:26 +02006548 n Normal, Terminal-Normal
6549 no Operator-pending
Bram Moolenaar5976f8f2018-12-27 23:44:44 +01006550 nov Operator-pending (forced characterwise |o_v|)
6551 noV Operator-pending (forced linewise |o_V|)
6552 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|);
Bram Moolenaar5b69c222019-01-11 14:50:06 +01006553 CTRL-V is one character
Bram Moolenaar612cc382018-07-29 15:34:26 +02006554 niI Normal using |i_CTRL-O| in |Insert-mode|
6555 niR Normal using |i_CTRL-O| in |Replace-mode|
6556 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode|
6557 v Visual by character
6558 V Visual by line
6559 CTRL-V Visual blockwise
6560 s Select by character
6561 S Select by line
6562 CTRL-S Select blockwise
6563 i Insert
6564 ic Insert mode completion |compl-generic|
6565 ix Insert mode |i_CTRL-X| completion
6566 R Replace |R|
6567 Rc Replace mode completion |compl-generic|
6568 Rv Virtual Replace |gR|
6569 Rx Replace mode |i_CTRL-X| completion
6570 c Command-line editing
6571 cv Vim Ex mode |gQ|
6572 ce Normal Ex mode |Q|
6573 r Hit-enter prompt
6574 rm The -- more -- prompt
6575 r? A |:confirm| query of some sort
6576 ! Shell or external command is executing
6577 t Terminal-Job mode: keys go to the job
Bram Moolenaar446cb832008-06-24 21:56:24 +00006578 This is useful in the 'statusline' option or when used
6579 with |remote_expr()| In most other places it always returns
6580 "c" or "n".
Bram Moolenaar612cc382018-07-29 15:34:26 +02006581 Note that in the future more modes and more specific modes may
6582 be added. It's better not to compare the whole string but only
6583 the leading character(s).
Bram Moolenaar446cb832008-06-24 21:56:24 +00006584 Also see |visualmode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006585
Bram Moolenaar7e506b62010-01-19 15:55:06 +01006586mzeval({expr}) *mzeval()*
6587 Evaluate MzScheme expression {expr} and return its result
Bram Moolenaard38b0552012-04-25 19:07:41 +02006588 converted to Vim data structures.
Bram Moolenaar7e506b62010-01-19 15:55:06 +01006589 Numbers and strings are returned as they are.
6590 Pairs (including lists and improper lists) and vectors are
6591 returned as Vim |Lists|.
6592 Hash tables are represented as Vim |Dictionary| type with keys
6593 converted to strings.
6594 All other types are converted to string with display function.
6595 Examples: >
6596 :mz (define l (list 1 2 3))
6597 :mz (define h (make-hash)) (hash-set! h "list" l)
6598 :echo mzeval("l")
6599 :echo mzeval("h")
6600<
6601 {only available when compiled with the |+mzscheme| feature}
6602
Bram Moolenaar071d4272004-06-13 20:20:40 +00006603nextnonblank({lnum}) *nextnonblank()*
6604 Return the line number of the first line at or below {lnum}
6605 that is not blank. Example: >
6606 if getline(nextnonblank(1)) =~ "Java"
6607< When {lnum} is invalid or there is no non-blank line at or
6608 below it, zero is returned.
6609 See also |prevnonblank()|.
6610
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006611nr2char({expr} [, {utf8}]) *nr2char()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006612 Return a string with a single character, which has the number
6613 value {expr}. Examples: >
6614 nr2char(64) returns "@"
6615 nr2char(32) returns " "
Bram Moolenaard35d7842013-01-23 17:17:10 +01006616< When {utf8} is omitted or zero, the current 'encoding' is used.
6617 Example for "utf-8": >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006618 nr2char(300) returns I with bow character
Bram Moolenaard35d7842013-01-23 17:17:10 +01006619< With {utf8} set to 1, always return utf-8 characters.
6620 Note that a NUL character in the file is specified with
Bram Moolenaar071d4272004-06-13 20:20:40 +00006621 nr2char(10), because NULs are represented with newline
6622 characters. nr2char(0) is a real NUL and terminates the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00006623 string, thus results in an empty string.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006624
Bram Moolenaard6e256c2011-12-14 15:32:50 +01006625or({expr}, {expr}) *or()*
6626 Bitwise OR on the two arguments. The arguments are converted
6627 to a number. A List, Dict or Float argument causes an error.
6628 Example: >
6629 :let bits = or(bits, 0x80)
6630
6631
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006632pathshorten({expr}) *pathshorten()*
6633 Shorten directory names in the path {expr} and return the
6634 result. The tail, the file name, is kept as-is. The other
6635 components in the path are reduced to single letters. Leading
6636 '~' and '.' characters are kept. Example: >
6637 :echo pathshorten('~/.vim/autoload/myfile.vim')
6638< ~/.v/a/myfile.vim ~
6639 It doesn't matter if the path exists or not.
6640
Bram Moolenaare9b892e2016-01-17 21:15:58 +01006641perleval({expr}) *perleval()*
6642 Evaluate Perl expression {expr} in scalar context and return
6643 its result converted to Vim data structures. If value can't be
Bram Moolenaar85084ef2016-01-17 22:26:33 +01006644 converted, it is returned as a string Perl representation.
6645 Note: If you want an array or hash, {expr} must return a
6646 reference to it.
Bram Moolenaare9b892e2016-01-17 21:15:58 +01006647 Example: >
6648 :echo perleval('[1 .. 4]')
6649< [1, 2, 3, 4]
6650 {only available when compiled with the |+perl| feature}
6651
Bram Moolenaar446cb832008-06-24 21:56:24 +00006652pow({x}, {y}) *pow()*
6653 Return the power of {x} to the exponent {y} as a |Float|.
6654 {x} and {y} must evaluate to a |Float| or a |Number|.
6655 Examples: >
6656 :echo pow(3, 3)
6657< 27.0 >
6658 :echo pow(2, 16)
6659< 65536.0 >
6660 :echo pow(32, 0.20)
6661< 2.0
6662 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006663
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00006664prevnonblank({lnum}) *prevnonblank()*
6665 Return the line number of the first line at or above {lnum}
6666 that is not blank. Example: >
6667 let ind = indent(prevnonblank(v:lnum - 1))
6668< When {lnum} is invalid or there is no non-blank line at or
6669 above it, zero is returned.
6670 Also see |nextnonblank()|.
6671
6672
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006673printf({fmt}, {expr1} ...) *printf()*
6674 Return a String with {fmt}, where "%" items are replaced by
6675 the formatted form of their respective arguments. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006676 printf("%4d: E%d %.30s", lnum, errno, msg)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006677< May result in:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006678 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006679
6680 Often used items are:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006681 %s string
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01006682 %6S string right-aligned in 6 display cells
Bram Moolenaar98692072006-02-04 00:57:42 +00006683 %6s string right-aligned in 6 bytes
Bram Moolenaar446cb832008-06-24 21:56:24 +00006684 %.9s string truncated to 9 bytes
6685 %c single byte
6686 %d decimal number
6687 %5d decimal number padded with spaces to 5 characters
6688 %x hex number
6689 %04x hex number padded with zeros to at least 4 characters
6690 %X hex number using upper case letters
6691 %o octal number
Bram Moolenaar91984b92016-08-16 21:58:41 +02006692 %08b binary number padded with zeros to at least 8 chars
Bram Moolenaar04186092016-08-29 21:55:35 +02006693 %f floating point number as 12.23, inf, -inf or nan
6694 %F floating point number as 12.23, INF, -INF or NAN
6695 %e floating point number as 1.23e3, inf, -inf or nan
6696 %E floating point number as 1.23E3, INF, -INF or NAN
Bram Moolenaar446cb832008-06-24 21:56:24 +00006697 %g floating point number, as %f or %e depending on value
Bram Moolenaar3df01732017-02-17 22:47:16 +01006698 %G floating point number, as %F or %E depending on value
Bram Moolenaar446cb832008-06-24 21:56:24 +00006699 %% the % character itself
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006700
6701 Conversion specifications start with '%' and end with the
6702 conversion type. All other characters are copied unchanged to
6703 the result.
6704
6705 The "%" starts a conversion specification. The following
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006706 arguments appear in sequence:
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006707
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006708 % [flags] [field-width] [.precision] type
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006709
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006710 flags
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006711 Zero or more of the following flags:
6712
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006713 # The value should be converted to an "alternate
6714 form". For c, d, and s conversions, this option
6715 has no effect. For o conversions, the precision
6716 of the number is increased to force the first
6717 character of the output string to a zero (except
6718 if a zero value is printed with an explicit
6719 precision of zero).
Bram Moolenaar91984b92016-08-16 21:58:41 +02006720 For b and B conversions, a non-zero result has
6721 the string "0b" (or "0B" for B conversions)
6722 prepended to it.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006723 For x and X conversions, a non-zero result has
6724 the string "0x" (or "0X" for X conversions)
6725 prepended to it.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006726
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006727 0 (zero) Zero padding. For all conversions the converted
6728 value is padded on the left with zeros rather
6729 than blanks. If a precision is given with a
Bram Moolenaar91984b92016-08-16 21:58:41 +02006730 numeric conversion (d, b, B, o, x, and X), the 0
6731 flag is ignored.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006732
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006733 - A negative field width flag; the converted value
6734 is to be left adjusted on the field boundary.
6735 The converted value is padded on the right with
6736 blanks, rather than on the left with blanks or
6737 zeros. A - overrides a 0 if both are given.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006738
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006739 ' ' (space) A blank should be left before a positive
6740 number produced by a signed conversion (d).
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006741
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006742 + A sign must always be placed before a number
Bram Moolenaar58b85342016-08-14 19:54:54 +02006743 produced by a signed conversion. A + overrides
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006744 a space if both are used.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006745
6746 field-width
6747 An optional decimal digit string specifying a minimum
Bram Moolenaar98692072006-02-04 00:57:42 +00006748 field width. If the converted value has fewer bytes
6749 than the field width, it will be padded with spaces on
6750 the left (or right, if the left-adjustment flag has
6751 been given) to fill out the field width.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006752
6753 .precision
6754 An optional precision, in the form of a period '.'
6755 followed by an optional digit string. If the digit
6756 string is omitted, the precision is taken as zero.
6757 This gives the minimum number of digits to appear for
6758 d, o, x, and X conversions, or the maximum number of
Bram Moolenaar98692072006-02-04 00:57:42 +00006759 bytes to be printed from a string for s conversions.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006760 For floating point it is the number of digits after
6761 the decimal point.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006762
6763 type
6764 A character that specifies the type of conversion to
6765 be applied, see below.
6766
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006767 A field width or precision, or both, may be indicated by an
6768 asterisk '*' instead of a digit string. In this case, a
Bram Moolenaar58b85342016-08-14 19:54:54 +02006769 Number argument supplies the field width or precision. A
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006770 negative field width is treated as a left adjustment flag
6771 followed by a positive field width; a negative precision is
6772 treated as though it were missing. Example: >
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006773 :echo printf("%d: %.*s", nr, width, line)
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006774< This limits the length of the text used from "line" to
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006775 "width" bytes.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006776
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00006777 The conversion specifiers and their meanings are:
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006778
Bram Moolenaar91984b92016-08-16 21:58:41 +02006779 *printf-d* *printf-b* *printf-B* *printf-o*
6780 *printf-x* *printf-X*
6781 dbBoxX The Number argument is converted to signed decimal
6782 (d), unsigned binary (b and B), unsigned octal (o), or
6783 unsigned hexadecimal (x and X) notation. The letters
6784 "abcdef" are used for x conversions; the letters
6785 "ABCDEF" are used for X conversions.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006786 The precision, if any, gives the minimum number of
6787 digits that must appear; if the converted value
6788 requires fewer digits, it is padded on the left with
6789 zeros.
6790 In no case does a non-existent or small field width
6791 cause truncation of a numeric field; if the result of
6792 a conversion is wider than the field width, the field
6793 is expanded to contain the conversion result.
Bram Moolenaar30567352016-08-27 21:25:44 +02006794 The 'h' modifier indicates the argument is 16 bits.
6795 The 'l' modifier indicates the argument is 32 bits.
6796 The 'L' modifier indicates the argument is 64 bits.
6797 Generally, these modifiers are not useful. They are
6798 ignored when type is known from the argument.
6799
6800 i alias for d
6801 D alias for ld
6802 U alias for lu
6803 O alias for lo
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006804
Bram Moolenaar446cb832008-06-24 21:56:24 +00006805 *printf-c*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006806 c The Number argument is converted to a byte, and the
6807 resulting character is written.
6808
Bram Moolenaar446cb832008-06-24 21:56:24 +00006809 *printf-s*
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006810 s The text of the String argument is used. If a
6811 precision is specified, no more bytes than the number
6812 specified are used.
Bram Moolenaar7571d552016-08-18 22:54:46 +02006813 If the argument is not a String type, it is
6814 automatically converted to text with the same format
6815 as ":echo".
Bram Moolenaar0122c402015-02-03 19:13:34 +01006816 *printf-S*
Bram Moolenaar3ab72c52012-11-14 18:10:56 +01006817 S The text of the String argument is used. If a
6818 precision is specified, no more display cells than the
6819 number specified are used. Without the |+multi_byte|
6820 feature works just like 's'.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006821
Bram Moolenaar446cb832008-06-24 21:56:24 +00006822 *printf-f* *E807*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01006823 f F The Float argument is converted into a string of the
Bram Moolenaar446cb832008-06-24 21:56:24 +00006824 form 123.456. The precision specifies the number of
6825 digits after the decimal point. When the precision is
6826 zero the decimal point is omitted. When the precision
6827 is not specified 6 is used. A really big number
Bram Moolenaar04186092016-08-29 21:55:35 +02006828 (out of range or dividing by zero) results in "inf"
Bram Moolenaarf8be4612017-06-23 20:52:40 +02006829 or "-inf" with %f (INF or -INF with %F).
6830 "0.0 / 0.0" results in "nan" with %f (NAN with %F).
Bram Moolenaar446cb832008-06-24 21:56:24 +00006831 Example: >
6832 echo printf("%.2f", 12.115)
6833< 12.12
6834 Note that roundoff depends on the system libraries.
6835 Use |round()| when in doubt.
6836
6837 *printf-e* *printf-E*
6838 e E The Float argument is converted into a string of the
6839 form 1.234e+03 or 1.234E+03 when using 'E'. The
6840 precision specifies the number of digits after the
6841 decimal point, like with 'f'.
6842
6843 *printf-g* *printf-G*
6844 g G The Float argument is converted like with 'f' if the
6845 value is between 0.001 (inclusive) and 10000000.0
6846 (exclusive). Otherwise 'e' is used for 'g' and 'E'
6847 for 'G'. When no precision is specified superfluous
6848 zeroes and '+' signs are removed, except for the zero
6849 immediately after the decimal point. Thus 10000000.0
6850 results in 1.0e7.
6851
6852 *printf-%*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006853 % A '%' is written. No argument is converted. The
6854 complete conversion specification is "%%".
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006855
Bram Moolenaarc236c162008-07-13 17:41:49 +00006856 When a Number argument is expected a String argument is also
6857 accepted and automatically converted.
6858 When a Float or String argument is expected a Number argument
6859 is also accepted and automatically converted.
6860 Any other argument type results in an error message.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006861
Bram Moolenaar83bab712005-08-01 21:58:57 +00006862 *E766* *E767*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006863 The number of {exprN} arguments must exactly match the number
6864 of "%" items. If there are not sufficient or too many
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00006865 arguments an error is given. Up to 18 arguments can be used.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00006866
6867
Bram Moolenaarf2732452018-06-03 14:47:35 +02006868prompt_setcallback({buf}, {expr}) *prompt_setcallback()*
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02006869 Set prompt callback for buffer {buf} to {expr}. When {expr}
6870 is an empty string the callback is removed. This has only
Bram Moolenaarf2732452018-06-03 14:47:35 +02006871 effect if {buf} has 'buftype' set to "prompt".
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02006872
Bram Moolenaarf2732452018-06-03 14:47:35 +02006873 The callback is invoked when pressing Enter. The current
6874 buffer will always be the prompt buffer. A new line for a
6875 prompt is added before invoking the callback, thus the prompt
6876 for which the callback was invoked will be in the last but one
6877 line.
6878 If the callback wants to add text to the buffer, it must
6879 insert it above the last line, since that is where the current
6880 prompt is. This can also be done asynchronously.
6881 The callback is invoked with one argument, which is the text
6882 that was entered at the prompt. This can be an empty string
6883 if the user only typed Enter.
6884 Example: >
6885 call prompt_setcallback(bufnr(''), function('s:TextEntered'))
6886 func s:TextEntered(text)
6887 if a:text == 'exit' || a:text == 'quit'
6888 stopinsert
6889 close
6890 else
6891 call append(line('$') - 1, 'Entered: "' . a:text . '"')
6892 " Reset 'modified' to allow the buffer to be closed.
6893 set nomodified
6894 endif
6895 endfunc
6896
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02006897prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()*
6898 Set a callback for buffer {buf} to {expr}. When {expr} is an
6899 empty string the callback is removed. This has only effect if
6900 {buf} has 'buftype' set to "prompt".
6901
6902 This callback will be invoked when pressing CTRL-C in Insert
6903 mode. Without setting a callback Vim will exit Insert mode,
6904 as in any buffer.
6905
6906prompt_setprompt({buf}, {text}) *prompt_setprompt()*
6907 Set prompt for buffer {buf} to {text}. You most likely want
6908 {text} to end in a space.
6909 The result is only visible if {buf} has 'buftype' set to
6910 "prompt". Example: >
6911 call prompt_setprompt(bufnr(''), 'command: ')
Bram Moolenaar98aefe72018-12-13 22:20:09 +01006912<
6913 *prop_add()* *E965*
6914prop_add({lnum}, {col}, {props})
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01006915 Attach a text property at position {lnum}, {col}. {col} is
6916 counted in bytes, use one for the first column.
Bram Moolenaar98aefe72018-12-13 22:20:09 +01006917 If {lnum} is invalid an error is given. *E966*
6918 If {col} is invalid an error is given. *E964*
6919
6920 {props} is a dictionary with these fields:
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01006921 length length of text in bytes, can only be used
Bram Moolenaarc8c88492018-12-27 23:59:26 +01006922 for a property that does not continue in
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01006923 another line; can be zero
6924 end_lnum line number for the end of text
Bram Moolenaar5b69c222019-01-11 14:50:06 +01006925 end_col column just after the text; not used when
6926 "length" is present; when {col} and "end_col"
6927 are equal, and "end_lnum" is omitted or equal
6928 to {lnum}, this is a zero-width text property
Bram Moolenaarc8c88492018-12-27 23:59:26 +01006929 bufnr buffer to add the property to; when omitted
Bram Moolenaar5b69c222019-01-11 14:50:06 +01006930 the current buffer is used
Bram Moolenaarc8c88492018-12-27 23:59:26 +01006931 id user defined ID for the property; when omitted
6932 zero is used
6933 type name of the text property type
Bram Moolenaar98aefe72018-12-13 22:20:09 +01006934 All fields except "type" are optional.
6935
6936 It is an error when both "length" and "end_lnum" or "end_col"
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01006937 are given. Either use "length" or "end_col" for a property
Bram Moolenaar98aefe72018-12-13 22:20:09 +01006938 within one line, or use "end_lnum" and "end_col" for a
6939 property that spans more than one line.
Bram Moolenaarb9c67a52019-01-01 19:49:20 +01006940 When neither "length" nor "end_col" are given the property
6941 will be zero-width. That means it will not be highlighted but
6942 will move with the text, as a kind of mark.
Bram Moolenaare3d31b02018-12-24 23:07:04 +01006943 The property can end exactly at the last character of the
6944 text, or just after it. In the last case, if text is appended
6945 to the line, the text property size will increase, also when
6946 the property type does not have "end_incl" set.
Bram Moolenaar98aefe72018-12-13 22:20:09 +01006947
6948 "type" will first be looked up in the buffer the property is
6949 added to. When not found, the global property types are used.
6950 If not found an error is given.
6951
6952 See |text-properties| for information about text properties.
6953
6954
Bram Moolenaar9d87a372018-12-18 21:41:50 +01006955prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()*
Bram Moolenaar98aefe72018-12-13 22:20:09 +01006956 Remove all text properties from line {lnum}.
Bram Moolenaar9d87a372018-12-18 21:41:50 +01006957 When {lnum-end} is given, remove all text properties from line
6958 {lnum} to {lnum-end} (inclusive).
Bram Moolenaar98aefe72018-12-13 22:20:09 +01006959
6960 When {props} contains a "bufnr" item use this buffer,
6961 otherwise use the current buffer.
6962
6963 See |text-properties| for information about text properties.
6964
6965 *prop_find()*
6966prop_find({props} [, {direction}])
6967 NOT IMPLEMENTED YET
6968 Search for a text property as specified with {props}:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01006969 id property with this ID
6970 type property with this type name
6971 bufnr buffer to search in; when present a
6972 start position with "lnum" and "col"
6973 must be given; when omitted the
6974 current buffer is used
Bram Moolenaar5b69c222019-01-11 14:50:06 +01006975 lnum start in this line (when omitted start
Bram Moolenaarc8c88492018-12-27 23:59:26 +01006976 at the cursor)
6977 col start at this column (when omitted
6978 and "lnum" is given: use column 1,
6979 otherwise start at the cursor)
6980 skipstart do not look for a match at the start
6981 position
Bram Moolenaar98aefe72018-12-13 22:20:09 +01006982
6983 {direction} can be "f" for forward and "b" for backward. When
6984 omitted forward search is performed.
6985
6986 If a match is found then a Dict is returned with the entries
6987 as with prop_list(), and additionally an "lnum" entry.
6988 If no match is found then an empty Dict is returned.
6989
6990 See |text-properties| for information about text properties.
6991
6992
Bram Moolenaar5b69c222019-01-11 14:50:06 +01006993prop_list({lnum} [, {props}]) *prop_list()*
Bram Moolenaar98aefe72018-12-13 22:20:09 +01006994 Return a List with all text properties in line {lnum}.
6995
6996 When {props} contains a "bufnr" item, use this buffer instead
6997 of the current buffer.
6998
6999 The properties are ordered by starting column and priority.
7000 Each property is a Dict with these entries:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007001 col starting column
Bram Moolenaar4c05fa02019-01-01 15:32:17 +01007002 length length in bytes, one more if line break is
7003 included
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007004 id property ID
7005 type name of the property type, omitted if
7006 the type was deleted
7007 start when TRUE property starts in this line
7008 end when TRUE property ends in this line
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007009
7010 When "start" is zero the property started in a previous line,
7011 the current one is a continuation.
7012 When "end" is zero the property continues in the next line.
7013 The line break after this line is included.
7014
7015 See |text-properties| for information about text properties.
7016
7017
7018 *prop_remove()* *E968*
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007019prop_remove({props} [, {lnum} [, {lnum-end}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007020 Remove a matching text property from line {lnum}. When
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007021 {lnum-end} is given, remove matching text properties from line
7022 {lnum} to {lnum-end} (inclusive).
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007023 When {lnum} is omitted remove matching text properties from
7024 all lines.
7025
7026 {props} is a dictionary with these fields:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007027 id remove text properties with this ID
7028 type remove text properties with this type name
7029 bufnr use this buffer instead of the current one
7030 all when TRUE remove all matching text properties,
7031 not just the first one
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007032 A property matches when either "id" or "type" matches.
7033
7034 Returns the number of properties that were removed.
7035
7036 See |text-properties| for information about text properties.
7037
7038
7039prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970*
7040 Add a text property type {name}. If a property type with this
7041 name already exists an error is given.
7042 {props} is a dictionary with these optional fields:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01007043 bufnr define the property only for this buffer; this
7044 avoids name collisions and automatically
7045 clears the property types when the buffer is
7046 deleted.
7047 highlight name of highlight group to use
7048 priority when a character has multiple text
7049 properties the one with the highest priority
7050 will be used; negative values can be used, the
7051 default priority is zero
7052 start_incl when TRUE inserts at the start position will
7053 be included in the text property
7054 end_incl when TRUE inserts at the end position will be
7055 included in the text property
Bram Moolenaar98aefe72018-12-13 22:20:09 +01007056
7057 See |text-properties| for information about text properties.
7058
7059
7060prop_type_change({name}, {props}) *prop_type_change()*
7061 Change properties of an existing text property type. If a
7062 property with this name does not exist an error is given.
7063 The {props} argument is just like |prop_type_add()|.
7064
7065 See |text-properties| for information about text properties.
7066
7067
7068prop_type_delete({name} [, {props}]) *prop_type_delete()*
7069 Remove the text property type {name}. When text properties
7070 using the type {name} are still in place, they will not have
7071 an effect and can no longer be removed by name.
7072
7073 {props} can contain a "bufnr" item. When it is given, delete
7074 a property type from this buffer instead of from the global
7075 property types.
7076
7077 When text property type {name} is not found there is no error.
7078
7079 See |text-properties| for information about text properties.
7080
7081
7082prop_type_get([{name} [, {props}]) *prop_type_get()*
7083 Returns the properties of property type {name}. This is a
7084 dictionary with the same fields as was given to
7085 prop_type_add().
7086 When the property type {name} does not exist, an empty
7087 dictionary is returned.
7088
7089 {props} can contain a "bufnr" item. When it is given, use
7090 this buffer instead of the global property types.
7091
7092 See |text-properties| for information about text properties.
7093
7094
7095prop_type_list([{props}]) *prop_type_list()*
7096 Returns a list with all property type names.
7097
7098 {props} can contain a "bufnr" item. When it is given, use
7099 this buffer instead of the global property types.
7100
7101 See |text-properties| for information about text properties.
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02007102
Bram Moolenaarf2732452018-06-03 14:47:35 +02007103
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007104pumvisible() *pumvisible()*
7105 Returns non-zero when the popup menu is visible, zero
7106 otherwise. See |ins-completion-menu|.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007107 This can be used to avoid some things that would remove the
7108 popup menu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007109
Bram Moolenaar30b65812012-07-12 22:01:11 +02007110py3eval({expr}) *py3eval()*
7111 Evaluate Python expression {expr} and return its result
7112 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007113 Numbers and strings are returned as they are (strings are
7114 copied though, Unicode strings are additionally converted to
Bram Moolenaar30b65812012-07-12 22:01:11 +02007115 'encoding').
7116 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007117 Dictionaries are represented as Vim |Dictionary| type with
Bram Moolenaar30b65812012-07-12 22:01:11 +02007118 keys converted to strings.
7119 {only available when compiled with the |+python3| feature}
7120
7121 *E858* *E859*
7122pyeval({expr}) *pyeval()*
7123 Evaluate Python expression {expr} and return its result
7124 converted to Vim data structures.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007125 Numbers and strings are returned as they are (strings are
Bram Moolenaar30b65812012-07-12 22:01:11 +02007126 copied though).
7127 Lists are represented as Vim |List| type.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007128 Dictionaries are represented as Vim |Dictionary| type,
Bram Moolenaard09acef2012-09-21 14:54:30 +02007129 non-string keys result in error.
Bram Moolenaar30b65812012-07-12 22:01:11 +02007130 {only available when compiled with the |+python| feature}
7131
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01007132pyxeval({expr}) *pyxeval()*
7133 Evaluate Python expression {expr} and return its result
7134 converted to Vim data structures.
7135 Uses Python 2 or 3, see |python_x| and 'pyxversion'.
7136 See also: |pyeval()|, |py3eval()|
7137 {only available when compiled with the |+python| or the
7138 |+python3| feature}
7139
Bram Moolenaar3a3a7232005-01-17 22:16:15 +00007140 *E726* *E727*
Bram Moolenaard8b02732005-01-14 21:48:43 +00007141range({expr} [, {max} [, {stride}]]) *range()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007142 Returns a |List| with Numbers:
Bram Moolenaard8b02732005-01-14 21:48:43 +00007143 - If only {expr} is specified: [0, 1, ..., {expr} - 1]
7144 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}]
7145 - If {stride} is specified: [{expr}, {expr} + {stride}, ...,
7146 {max}] (increasing {expr} with {stride} each time, not
7147 producing a value past {max}).
Bram Moolenaare7566042005-06-17 22:00:15 +00007148 When the maximum is one before the start the result is an
7149 empty list. When the maximum is more than one before the
7150 start this is an error.
Bram Moolenaard8b02732005-01-14 21:48:43 +00007151 Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007152 range(4) " [0, 1, 2, 3]
Bram Moolenaard8b02732005-01-14 21:48:43 +00007153 range(2, 4) " [2, 3, 4]
7154 range(2, 9, 3) " [2, 5, 8]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007155 range(2, -2, -1) " [2, 1, 0, -1, -2]
Bram Moolenaare7566042005-06-17 22:00:15 +00007156 range(0) " []
7157 range(2, 0) " error!
Bram Moolenaard8b02732005-01-14 21:48:43 +00007158<
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007159 *readfile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007160readfile({fname} [, {type} [, {max}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007161 Read file {fname} and return a |List|, each line of the file
Bram Moolenaar6100d022016-10-02 16:51:57 +02007162 as an item. Lines are broken at NL characters. Macintosh
7163 files separated with CR will result in a single long line
7164 (unless a NL appears somewhere).
Bram Moolenaar06583f12010-08-07 20:30:49 +02007165 All NUL characters are replaced with a NL character.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007166 When {type} contains "b" binary mode is used:
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007167 - When the last line ends in a NL an extra empty list item is
7168 added.
7169 - No CR characters are removed.
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007170 When {type} contains "B" a |Blob| is returned with the binary
7171 data of the file unmodified.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007172 Otherwise:
7173 - CR characters that appear before a NL are removed.
7174 - Whether the last line ends in a NL or not does not matter.
Bram Moolenaar06583f12010-08-07 20:30:49 +02007175 - When 'encoding' is Unicode any UTF-8 byte order mark is
7176 removed from the text.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007177 When {max} is given this specifies the maximum number of lines
7178 to be read. Useful if you only want to check the first ten
7179 lines of a file: >
7180 :for line in readfile(fname, '', 10)
7181 : if line =~ 'Date' | echo line | endif
7182 :endfor
Bram Moolenaar582fd852005-03-28 20:58:01 +00007183< When {max} is negative -{max} lines from the end of the file
7184 are returned, or as many as there are.
7185 When {max} is zero the result is an empty list.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007186 Note that without {max} the whole file is read into memory.
7187 Also note that there is no recognition of encoding. Read a
7188 file into a buffer if you need to.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +00007189 When the file can't be opened an error message is given and
7190 the result is an empty list.
7191 Also see |writefile()|.
7192
Bram Moolenaar0b6d9112018-05-22 20:35:17 +02007193reg_executing() *reg_executing()*
7194 Returns the single letter name of the register being executed.
7195 Returns an empty string when no register is being executed.
7196 See |@|.
7197
7198reg_recording() *reg_recording()*
7199 Returns the single letter name of the register being recorded.
7200 Returns an empty string string when not recording. See |q|.
7201
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007202reltime([{start} [, {end}]]) *reltime()*
7203 Return an item that represents a time value. The format of
7204 the item depends on the system. It can be passed to
Bram Moolenaar03413f42016-04-12 21:07:15 +02007205 |reltimestr()| to convert it to a string or |reltimefloat()|
7206 to convert to a Float.
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007207 Without an argument it returns the current time.
7208 With one argument is returns the time passed since the time
7209 specified in the argument.
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00007210 With two arguments it returns the time passed between {start}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007211 and {end}.
7212 The {start} and {end} arguments must be values returned by
7213 reltime().
Bram Moolenaardb84e452010-08-15 13:50:43 +02007214 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007215
Bram Moolenaar03413f42016-04-12 21:07:15 +02007216reltimefloat({time}) *reltimefloat()*
7217 Return a Float that represents the time value of {time}.
7218 Example: >
7219 let start = reltime()
7220 call MyFunction()
7221 let seconds = reltimefloat(reltime(start))
7222< See the note of reltimestr() about overhead.
7223 Also see |profiling|.
7224 {only available when compiled with the |+reltime| feature}
7225
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007226reltimestr({time}) *reltimestr()*
7227 Return a String that represents the time value of {time}.
7228 This is the number of seconds, a dot and the number of
7229 microseconds. Example: >
7230 let start = reltime()
7231 call MyFunction()
7232 echo reltimestr(reltime(start))
7233< Note that overhead for the commands will be added to the time.
7234 The accuracy depends on the system.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007235 Leading spaces are used to make the string align nicely. You
7236 can use split() to remove it. >
7237 echo split(reltimestr(reltime(start)))[0]
7238< Also see |profiling|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02007239 {only available when compiled with the |+reltime| feature}
Bram Moolenaar433f7c82006-03-21 21:29:36 +00007240
Bram Moolenaar071d4272004-06-13 20:20:40 +00007241 *remote_expr()* *E449*
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007242remote_expr({server}, {string} [, {idvar} [, {timeout}]])
Bram Moolenaar58b85342016-08-14 19:54:54 +02007243 Send the {string} to {server}. The string is sent as an
Bram Moolenaar071d4272004-06-13 20:20:40 +00007244 expression and the result is returned after evaluation.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007245 The result must be a String or a |List|. A |List| is turned
7246 into a String by joining the items with a line break in
7247 between (not at the end), like with join(expr, "\n").
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007248 If {idvar} is present and not empty, it is taken as the name
7249 of a variable and a {serverid} for later use with
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01007250 |remote_read()| is stored there.
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007251 If {timeout} is given the read times out after this many
7252 seconds. Otherwise a timeout of 600 seconds is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007253 See also |clientserver| |RemoteReply|.
7254 This function is not available in the |sandbox|.
7255 {only available when compiled with the |+clientserver| feature}
7256 Note: Any errors will cause a local error message to be issued
7257 and the result will be the empty string.
Bram Moolenaar01164a62017-11-02 22:58:42 +01007258
7259 Variables will be evaluated in the global namespace,
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007260 independent of a function currently being active. Except
Bram Moolenaar01164a62017-11-02 22:58:42 +01007261 when in debug mode, then local function variables and
7262 arguments can be evaluated.
7263
Bram Moolenaar071d4272004-06-13 20:20:40 +00007264 Examples: >
7265 :echo remote_expr("gvim", "2+2")
7266 :echo remote_expr("gvim1", "b:current_syntax")
7267<
7268
7269remote_foreground({server}) *remote_foreground()*
7270 Move the Vim server with the name {server} to the foreground.
7271 This works like: >
7272 remote_expr({server}, "foreground()")
7273< Except that on Win32 systems the client does the work, to work
7274 around the problem that the OS doesn't always allow the server
7275 to bring itself to the foreground.
Bram Moolenaar9372a112005-12-06 19:59:18 +00007276 Note: This does not restore the window if it was minimized,
7277 like foreground() does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007278 This function is not available in the |sandbox|.
7279 {only in the Win32, Athena, Motif and GTK GUI versions and the
7280 Win32 console version}
7281
7282
7283remote_peek({serverid} [, {retvar}]) *remote_peek()*
7284 Returns a positive number if there are available strings
7285 from {serverid}. Copies any reply string into the variable
Bram Moolenaar58b85342016-08-14 19:54:54 +02007286 {retvar} if specified. {retvar} must be a string with the
Bram Moolenaar071d4272004-06-13 20:20:40 +00007287 name of a variable.
7288 Returns zero if none are available.
7289 Returns -1 if something is wrong.
7290 See also |clientserver|.
7291 This function is not available in the |sandbox|.
7292 {only available when compiled with the |+clientserver| feature}
7293 Examples: >
7294 :let repl = ""
7295 :echo "PEEK: ".remote_peek(id, "repl").": ".repl
7296
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007297remote_read({serverid}, [{timeout}]) *remote_read()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007298 Return the oldest available reply from {serverid} and consume
Bram Moolenaar81b9d0b2017-03-19 21:20:53 +01007299 it. Unless a {timeout} in seconds is given, it blocks until a
7300 reply is available.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007301 See also |clientserver|.
7302 This function is not available in the |sandbox|.
7303 {only available when compiled with the |+clientserver| feature}
7304 Example: >
7305 :echo remote_read(id)
7306<
7307 *remote_send()* *E241*
7308remote_send({server}, {string} [, {idvar}])
Bram Moolenaar58b85342016-08-14 19:54:54 +02007309 Send the {string} to {server}. The string is sent as input
Bram Moolenaard4755bb2004-09-02 19:12:26 +00007310 keys and the function returns immediately. At the Vim server
7311 the keys are not mapped |:map|.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007312 If {idvar} is present, it is taken as the name of a variable
7313 and a {serverid} for later use with remote_read() is stored
7314 there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007315 See also |clientserver| |RemoteReply|.
7316 This function is not available in the |sandbox|.
7317 {only available when compiled with the |+clientserver| feature}
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01007318
Bram Moolenaar071d4272004-06-13 20:20:40 +00007319 Note: Any errors will be reported in the server and may mess
7320 up the display.
7321 Examples: >
7322 :echo remote_send("gvim", ":DropAndReply ".file, "serverid").
7323 \ remote_read(serverid)
7324
7325 :autocmd NONE RemoteReply *
7326 \ echo remote_read(expand("<amatch>"))
7327 :echo remote_send("gvim", ":sleep 10 | echo ".
7328 \ 'server2client(expand("<client>"), "HELLO")<CR>')
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007329<
Bram Moolenaar7416f3e2017-03-18 18:10:13 +01007330 *remote_startserver()* *E941* *E942*
7331remote_startserver({name})
7332 Become the server {name}. This fails if already running as a
7333 server, when |v:servername| is not empty.
7334 {only available when compiled with the |+clientserver| feature}
7335
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007336remove({list}, {idx} [, {end}]) *remove()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007337 Without {end}: Remove the item at {idx} from |List| {list} and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007338 return the item.
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007339 With {end}: Remove items from {idx} to {end} (inclusive) and
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007340 return a List with these items. When {idx} points to the same
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007341 item as {end} a list with one item is returned. When {end}
7342 points to an item before {idx} this is an error.
7343 See |list-index| for possible values of {idx} and {end}.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00007344 Example: >
7345 :echo "last item: " . remove(mylist, -1)
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007346 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007347<
7348 Use |delete()| to remove a file.
7349
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007350remove({blob}, {idx} [, {end}])
7351 Without {end}: Remove the byte at {idx} from |Blob| {blob} and
7352 return the byte.
7353 With {end}: Remove bytes from {idx} to {end} (inclusive) and
7354 return a |Blob| with these bytes. When {idx} points to the same
7355 byte as {end} a |Blob| with one byte is returned. When {end}
7356 points to a byte before {idx} this is an error.
7357 Example: >
7358 :echo "last byte: " . remove(myblob, -1)
7359 :call remove(mylist, 0, 9)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01007360
Bram Moolenaard8b02732005-01-14 21:48:43 +00007361remove({dict}, {key})
7362 Remove the entry from {dict} with key {key}. Example: >
7363 :echo "removed " . remove(dict, "one")
7364< If there is no {key} in {dict} this is an error.
7365
Bram Moolenaar071d4272004-06-13 20:20:40 +00007366rename({from}, {to}) *rename()*
7367 Rename the file by the name {from} to the name {to}. This
7368 should also work to move files across file systems. The
7369 result is a Number, which is 0 if the file was renamed
7370 successfully, and non-zero when the renaming failed.
Bram Moolenaar798b30b2009-04-22 10:56:16 +00007371 NOTE: If {to} exists it is overwritten without warning.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007372 This function is not available in the |sandbox|.
7373
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007374repeat({expr}, {count}) *repeat()*
7375 Repeat {expr} {count} times and return the concatenated
7376 result. Example: >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00007377 :let separator = repeat('-', 80)
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007378< When {count} is zero or negative the result is empty.
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007379 When {expr} is a |List| the result is {expr} concatenated
Bram Moolenaar58b85342016-08-14 19:54:54 +02007380 {count} times. Example: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +00007381 :let longlist = repeat(['a', 'b'], 3)
7382< Results in ['a', 'b', 'a', 'b', 'a', 'b'].
Bram Moolenaarab79bcb2004-07-18 21:34:53 +00007383
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007384
Bram Moolenaar071d4272004-06-13 20:20:40 +00007385resolve({filename}) *resolve()* *E655*
7386 On MS-Windows, when {filename} is a shortcut (a .lnk file),
7387 returns the path the shortcut points to in a simplified form.
Bram Moolenaardce1e892019-02-10 23:18:53 +01007388 When {filename} is a symbolic link or junction point, return
7389 the full path to the target. If the target of junction is
7390 removed, return {filename}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007391 On Unix, repeat resolving symbolic links in all path
7392 components of {filename} and return the simplified result.
7393 To cope with link cycles, resolving of symbolic links is
7394 stopped after 100 iterations.
7395 On other systems, return the simplified {filename}.
7396 The simplification step is done as by |simplify()|.
7397 resolve() keeps a leading path component specifying the
7398 current directory (provided the result is still a relative
7399 path name) and also keeps a trailing path separator.
7400
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007401 *reverse()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +01007402reverse({object})
7403 Reverse the order of items in {object} in-place.
7404 {object} can be a |List| or a |Blob|.
7405 Returns {object}.
7406 If you want an object to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00007407 :let revlist = reverse(copy(mylist))
7408
Bram Moolenaar446cb832008-06-24 21:56:24 +00007409round({expr}) *round()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00007410 Round off {expr} to the nearest integral value and return it
Bram Moolenaar446cb832008-06-24 21:56:24 +00007411 as a |Float|. If {expr} lies halfway between two integral
7412 values, then use the larger one (away from zero).
7413 {expr} must evaluate to a |Float| or a |Number|.
7414 Examples: >
7415 echo round(0.456)
7416< 0.0 >
7417 echo round(4.5)
7418< 5.0 >
7419 echo round(-4.5)
7420< -5.0
7421 {only available when compiled with the |+float| feature}
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007422
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007423screenattr({row}, {col}) *screenattr()*
Bram Moolenaar36f44c22016-08-28 18:17:20 +02007424 Like |screenchar()|, but return the attribute. This is a rather
Bram Moolenaar9a773482013-06-11 18:40:13 +02007425 arbitrary number that can only be used to compare to the
7426 attribute at other positions.
7427
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007428screenchar({row}, {col}) *screenchar()*
Bram Moolenaar9a773482013-06-11 18:40:13 +02007429 The result is a Number, which is the character at position
7430 [row, col] on the screen. This works for every possible
7431 screen position, also status lines, window separators and the
7432 command line. The top left position is row one, column one
7433 The character excludes composing characters. For double-byte
7434 encodings it may only be the first byte.
7435 This is mainly to be used for testing.
7436 Returns -1 when row or col is out of range.
7437
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007438screencol() *screencol()*
7439 The result is a Number, which is the current screen column of
7440 the cursor. The leftmost column has number 1.
7441 This function is mainly used for testing.
7442
7443 Note: Always returns the current screen column, thus if used
7444 in a command (e.g. ":echo screencol()") it will return the
7445 column inside the command line, which is 1 when the command is
7446 executed. To get the cursor position in the file use one of
7447 the following mappings: >
7448 nnoremap <expr> GG ":echom ".screencol()."\n"
7449 nnoremap <silent> GG :echom screencol()<CR>
7450<
7451screenrow() *screenrow()*
7452 The result is a Number, which is the current screen row of the
7453 cursor. The top line has number one.
7454 This function is mainly used for testing.
Bram Moolenaar437bafe2016-08-01 15:40:54 +02007455 Alternatively you can use |winline()|.
Bram Moolenaar34feacb2012-12-05 19:01:43 +01007456
7457 Note: Same restrictions as with |screencol()|.
7458
Bram Moolenaar76929292008-01-06 19:07:36 +00007459search({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *search()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007460 Search for regexp pattern {pattern}. The search starts at the
Bram Moolenaar383f9bc2005-01-19 22:18:32 +00007461 cursor position (you can use |cursor()| to set it).
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007462
Bram Moolenaar2df58b42012-11-28 18:21:11 +01007463 When a match has been found its line number is returned.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01007464 If there is no match a 0 is returned and the cursor doesn't
7465 move. No error message is given.
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01007466
Bram Moolenaar071d4272004-06-13 20:20:40 +00007467 {flags} is a String, which can contain these character flags:
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01007468 'b' search Backward instead of forward
7469 'c' accept a match at the Cursor position
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007470 'e' move to the End of the match
Bram Moolenaar5eb86f92004-07-26 12:53:41 +00007471 'n' do Not move the cursor
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01007472 'p' return number of matching sub-Pattern (see below)
7473 's' Set the ' mark at the previous location of the cursor
7474 'w' Wrap around the end of the file
7475 'W' don't Wrap around the end of the file
7476 'z' start searching at the cursor column instead of zero
Bram Moolenaar071d4272004-06-13 20:20:40 +00007477 If neither 'w' or 'W' is given, the 'wrapscan' option applies.
7478
Bram Moolenaar02743632005-07-25 20:42:36 +00007479 If the 's' flag is supplied, the ' mark is set, only if the
7480 cursor is moved. The 's' flag cannot be combined with the 'n'
7481 flag.
7482
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007483 'ignorecase', 'smartcase' and 'magic' are used.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007484
Bram Moolenaar85084ef2016-01-17 22:26:33 +01007485 When the 'z' flag is not given, searching always starts in
Bram Moolenaarad4d8a12015-12-28 19:20:36 +01007486 column zero and then matches before the cursor are skipped.
7487 When the 'c' flag is present in 'cpo' the next search starts
7488 after the match. Without the 'c' flag the next search starts
7489 one column further.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007490
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007491 When the {stopline} argument is given then the search stops
7492 after searching this line. This is useful to restrict the
7493 search to a range of lines. Examples: >
7494 let match = search('(', 'b', line("w0"))
7495 let end = search('END', '', line("w$"))
7496< When {stopline} is used and it is not zero this also implies
7497 that the search does not wrap around the end of the file.
Bram Moolenaar76929292008-01-06 19:07:36 +00007498 A zero value is equal to not giving the argument.
7499
7500 When the {timeout} argument is given the search stops when
Bram Moolenaar58b85342016-08-14 19:54:54 +02007501 more than this many milliseconds have passed. Thus when
Bram Moolenaar76929292008-01-06 19:07:36 +00007502 {timeout} is 500 the search stops after half a second.
7503 The value must not be negative. A zero value is like not
7504 giving the argument.
Bram Moolenaardb84e452010-08-15 13:50:43 +02007505 {only available when compiled with the |+reltime| feature}
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007506
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007507 *search()-sub-match*
7508 With the 'p' flag the returned value is one more than the
7509 first sub-match in \(\). One if none of them matched but the
7510 whole pattern did match.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007511 To get the column number too use |searchpos()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007512
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007513 The cursor will be positioned at the match, unless the 'n'
7514 flag is used.
7515
Bram Moolenaar071d4272004-06-13 20:20:40 +00007516 Example (goes over all files in the argument list): >
7517 :let n = 1
7518 :while n <= argc() " loop over all files in arglist
7519 : exe "argument " . n
7520 : " start at the last char in the file and wrap for the
7521 : " first search to find match at start of file
7522 : normal G$
7523 : let flags = "w"
7524 : while search("foo", flags) > 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00007525 : s/foo/bar/g
Bram Moolenaar071d4272004-06-13 20:20:40 +00007526 : let flags = "W"
7527 : endwhile
7528 : update " write the file if modified
7529 : let n = n + 1
7530 :endwhile
7531<
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007532 Example for using some flags: >
7533 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe')
7534< This will search for the keywords "if", "else", and "endif"
7535 under or after the cursor. Because of the 'p' flag, it
7536 returns 1, 2, or 3 depending on which keyword is found, or 0
7537 if the search fails. With the cursor on the first word of the
7538 line:
7539 if (foo == 0) | let foo = foo + 1 | endif ~
7540 the function returns 1. Without the 'c' flag, the function
7541 finds the "endif" and returns 3. The same thing happens
7542 without the 'e' flag if the cursor is on the "f" of "if".
7543 The 'n' flag tells the function not to move the cursor.
7544
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007545
Bram Moolenaarf75a9632005-09-13 21:20:47 +00007546searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()*
7547 Search for the declaration of {name}.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007548
Bram Moolenaarf75a9632005-09-13 21:20:47 +00007549 With a non-zero {global} argument it works like |gD|, find
7550 first match in the file. Otherwise it works like |gd|, find
7551 first match in the function.
7552
7553 With a non-zero {thisblock} argument matches in a {} block
7554 that ends before the cursor position are ignored. Avoids
7555 finding variable declarations only valid in another scope.
7556
Bram Moolenaar92d640f2005-09-05 22:11:52 +00007557 Moves the cursor to the found match.
7558 Returns zero for success, non-zero for failure.
7559 Example: >
7560 if searchdecl('myvar') == 0
7561 echo getline('.')
7562 endif
7563<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007564 *searchpair()*
Bram Moolenaar76929292008-01-06 19:07:36 +00007565searchpair({start}, {middle}, {end} [, {flags} [, {skip}
7566 [, {stopline} [, {timeout}]]]])
Bram Moolenaar071d4272004-06-13 20:20:40 +00007567 Search for the match of a nested start-end pair. This can be
7568 used to find the "endif" that matches an "if", while other
7569 if/endif pairs in between are ignored.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007570 The search starts at the cursor. The default is to search
7571 forward, include 'b' in {flags} to search backward.
7572 If a match is found, the cursor is positioned at it and the
7573 line number is returned. If no match is found 0 or -1 is
7574 returned and the cursor doesn't move. No error message is
7575 given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007576
7577 {start}, {middle} and {end} are patterns, see |pattern|. They
7578 must not contain \( \) pairs. Use of \%( \) is allowed. When
7579 {middle} is not empty, it is found when searching from either
7580 direction, but only when not in a nested start-end pair. A
7581 typical use is: >
7582 searchpair('\<if\>', '\<else\>', '\<endif\>')
7583< By leaving {middle} empty the "else" is skipped.
7584
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007585 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with
7586 |search()|. Additionally:
Bram Moolenaar071d4272004-06-13 20:20:40 +00007587 'r' Repeat until no more matches found; will find the
Bram Moolenaar446cb832008-06-24 21:56:24 +00007588 outer pair. Implies the 'W' flag.
7589 'm' Return number of matches instead of line number with
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00007590 the match; will be > 1 when 'r' is used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007591 Note: it's nearly always a good idea to use the 'W' flag, to
7592 avoid wrapping around the end of the file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007593
7594 When a match for {start}, {middle} or {end} is found, the
7595 {skip} expression is evaluated with the cursor positioned on
7596 the start of the match. It should return non-zero if this
7597 match is to be skipped. E.g., because it is inside a comment
7598 or a string.
7599 When {skip} is omitted or empty, every match is accepted.
7600 When evaluating {skip} causes an error the search is aborted
7601 and -1 returned.
Bram Moolenaar48570482017-10-30 21:48:41 +01007602 {skip} can be a string, a lambda, a funcref or a partial.
Bram Moolenaar675e8d62018-06-24 20:42:01 +02007603 Anything else makes the function fail.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007604
Bram Moolenaar76929292008-01-06 19:07:36 +00007605 For {stopline} and {timeout} see |search()|.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007606
Bram Moolenaar071d4272004-06-13 20:20:40 +00007607 The value of 'ignorecase' is used. 'magic' is ignored, the
7608 patterns are used like it's on.
7609
7610 The search starts exactly at the cursor. A match with
7611 {start}, {middle} or {end} at the next character, in the
7612 direction of searching, is the first one found. Example: >
7613 if 1
7614 if 2
7615 endif 2
7616 endif 1
7617< When starting at the "if 2", with the cursor on the "i", and
7618 searching forwards, the "endif 2" is found. When starting on
7619 the character just before the "if 2", the "endif 1" will be
Bram Moolenaar58b85342016-08-14 19:54:54 +02007620 found. That's because the "if 2" will be found first, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00007621 then this is considered to be a nested if/endif from "if 2" to
7622 "endif 2".
7623 When searching backwards and {end} is more than one character,
7624 it may be useful to put "\zs" at the end of the pattern, so
7625 that when the cursor is inside a match with the end it finds
7626 the matching start.
7627
7628 Example, to find the "endif" command in a Vim script: >
7629
7630 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W',
7631 \ 'getline(".") =~ "^\\s*\""')
7632
7633< The cursor must be at or after the "if" for which a match is
7634 to be found. Note that single-quote strings are used to avoid
7635 having to double the backslashes. The skip expression only
7636 catches comments at the start of a line, not after a command.
7637 Also, a word "en" or "if" halfway a line is considered a
7638 match.
7639 Another example, to search for the matching "{" of a "}": >
7640
7641 :echo searchpair('{', '', '}', 'bW')
7642
7643< This works when the cursor is at or before the "}" for which a
7644 match is to be found. To reject matches that syntax
7645 highlighting recognized as strings: >
7646
7647 :echo searchpair('{', '', '}', 'bW',
7648 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"')
7649<
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007650 *searchpairpos()*
Bram Moolenaar76929292008-01-06 19:07:36 +00007651searchpairpos({start}, {middle}, {end} [, {flags} [, {skip}
7652 [, {stopline} [, {timeout}]]]])
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007653 Same as |searchpair()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007654 column position of the match. The first element of the |List|
7655 is the line number and the second element is the byte index of
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007656 the column position of the match. If no match is found,
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02007657 returns [0, 0]. >
7658
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00007659 :let [lnum,col] = searchpairpos('{', '', '}', 'n')
7660<
7661 See |match-parens| for a bigger and more useful example.
7662
Bram Moolenaar76929292008-01-06 19:07:36 +00007663searchpos({pattern} [, {flags} [, {stopline} [, {timeout}]]]) *searchpos()*
Bram Moolenaara23ccb82006-02-27 00:08:02 +00007664 Same as |search()|, but returns a |List| with the line and
Bram Moolenaar32466aa2006-02-24 23:53:04 +00007665 column position of the match. The first element of the |List|
7666 is the line number and the second element is the byte index of
7667 the column position of the match. If no match is found,
7668 returns [0, 0].
Bram Moolenaar362e1a32006-03-06 23:29:24 +00007669 Example: >
7670 :let [lnum, col] = searchpos('mypattern', 'n')
7671
7672< When the 'p' flag is given then there is an extra item with
7673 the sub-pattern match number |search()-sub-match|. Example: >
7674 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np')
7675< In this example "submatch" is 2 when a lowercase letter is
7676 found |/\l|, 3 when an uppercase letter is found |/\u|.
7677
Bram Moolenaar81edd172016-04-14 13:51:37 +02007678server2client({clientid}, {string}) *server2client()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007679 Send a reply string to {clientid}. The most recent {clientid}
7680 that sent a string can be retrieved with expand("<client>").
7681 {only available when compiled with the |+clientserver| feature}
7682 Note:
7683 This id has to be stored before the next command can be
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007684 received. I.e. before returning from the received command and
Bram Moolenaar071d4272004-06-13 20:20:40 +00007685 before calling any commands that waits for input.
7686 See also |clientserver|.
7687 Example: >
7688 :echo server2client(expand("<client>"), "HELLO")
7689<
7690serverlist() *serverlist()*
7691 Return a list of available server names, one per line.
7692 When there are no servers or the information is not available
7693 an empty string is returned. See also |clientserver|.
7694 {only available when compiled with the |+clientserver| feature}
7695 Example: >
7696 :echo serverlist()
7697<
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007698setbufline({expr}, {lnum}, {text}) *setbufline()*
7699 Set line {lnum} to {text} in buffer {expr}. To insert
Bram Moolenaarb328cca2019-01-06 16:24:01 +01007700 lines use |append()|. Any text properties in {lnum} are
7701 cleared.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007702
7703 For the use of {expr}, see |bufname()| above.
7704
7705 {lnum} is used like with |setline()|.
7706 This works like |setline()| for the specified buffer.
7707 On success 0 is returned, on failure 1 is returned.
7708
7709 If {expr} is not a valid buffer or {lnum} is not valid, an
7710 error message is given.
7711
Bram Moolenaar071d4272004-06-13 20:20:40 +00007712setbufvar({expr}, {varname}, {val}) *setbufvar()*
7713 Set option or local variable {varname} in buffer {expr} to
7714 {val}.
7715 This also works for a global or local window option, but it
7716 doesn't work for a global or local window variable.
7717 For a local window option the global value is unchanged.
7718 For the use of {expr}, see |bufname()| above.
7719 Note that the variable name without "b:" must be used.
7720 Examples: >
7721 :call setbufvar(1, "&mod", 1)
7722 :call setbufvar("todo", "myvar", "foobar")
7723< This function is not available in the |sandbox|.
7724
Bram Moolenaar12969c02015-09-08 23:36:10 +02007725setcharsearch({dict}) *setcharsearch()*
Bram Moolenaardbd24b52015-08-11 14:26:19 +02007726 Set the current character search information to {dict},
7727 which contains one or more of the following entries:
7728
7729 char character which will be used for a subsequent
7730 |,| or |;| command; an empty string clears the
7731 character search
7732 forward direction of character search; 1 for forward,
7733 0 for backward
7734 until type of character search; 1 for a |t| or |T|
7735 character search, 0 for an |f| or |F|
7736 character search
7737
7738 This can be useful to save/restore a user's character search
7739 from a script: >
7740 :let prevsearch = getcharsearch()
7741 :" Perform a command which clobbers user's search
7742 :call setcharsearch(prevsearch)
7743< Also see |getcharsearch()|.
7744
Bram Moolenaar071d4272004-06-13 20:20:40 +00007745setcmdpos({pos}) *setcmdpos()*
7746 Set the cursor position in the command line to byte position
Bram Moolenaar58b85342016-08-14 19:54:54 +02007747 {pos}. The first position is 1.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007748 Use |getcmdpos()| to obtain the current position.
7749 Only works while editing the command line, thus you must use
Bram Moolenaard8b02732005-01-14 21:48:43 +00007750 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For
7751 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is
7752 set after the command line is set to the expression. For
7753 |c_CTRL-R_=| it is set after evaluating the expression but
7754 before inserting the resulting text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007755 When the number is too big the cursor is put at the end of the
7756 line. A number smaller than one has undefined results.
7757 Returns 0 when successful, 1 when not editing the command
7758 line.
7759
Bram Moolenaar80492532016-03-08 17:08:53 +01007760setfperm({fname}, {mode}) *setfperm()* *chmod*
7761 Set the file permissions for {fname} to {mode}.
7762 {mode} must be a string with 9 characters. It is of the form
7763 "rwxrwxrwx", where each group of "rwx" flags represent, in
7764 turn, the permissions of the owner of the file, the group the
7765 file belongs to, and other users. A '-' character means the
7766 permission is off, any other character means on. Multi-byte
7767 characters are not supported.
7768
7769 For example "rw-r-----" means read-write for the user,
7770 readable by the group, not accessible by others. "xx-x-----"
7771 would do the same thing.
7772
7773 Returns non-zero for success, zero for failure.
7774
7775 To read permissions see |getfperm()|.
7776
7777
Bram Moolenaar446cb832008-06-24 21:56:24 +00007778setline({lnum}, {text}) *setline()*
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +01007779 Set line {lnum} of the current buffer to {text}. To insert
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007780 lines use |append()|. To set lines in another buffer use
Bram Moolenaarb328cca2019-01-06 16:24:01 +01007781 |setbufline()|. Any text properties in {lnum} are cleared.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007782
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007783 {lnum} is used like with |getline()|.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007784 When {lnum} is just below the last line the {text} will be
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007785 added as a new line.
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007786
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007787 If this succeeds, 0 is returned. If this fails (most likely
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007788 because {lnum} is invalid) 1 is returned.
7789
7790 Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007791 :call setline(5, strftime("%c"))
Bram Moolenaarb31cf2b2017-09-02 19:45:19 +02007792
Bram Moolenaar446cb832008-06-24 21:56:24 +00007793< When {text} is a |List| then line {lnum} and following lines
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007794 will be set to the items in the list. Example: >
7795 :call setline(5, ['aaa', 'bbb', 'ccc'])
7796< This is equivalent to: >
Bram Moolenaar53bfca22012-04-13 23:04:47 +02007797 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']]
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00007798 : call setline(n, l)
7799 :endfor
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02007800
Bram Moolenaar071d4272004-06-13 20:20:40 +00007801< Note: The '[ and '] marks are not set.
7802
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007803setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()*
Bram Moolenaar17c7c012006-01-26 22:25:15 +00007804 Create or replace or add to the location list for window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +02007805 {nr} can be the window number or the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02007806 When {nr} is zero the current window is used.
7807
7808 For a location list window, the displayed location list is
7809 modified. For an invalid window number {nr}, -1 is returned.
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007810 Otherwise, same as |setqflist()|.
7811 Also see |location-list|.
7812
Bram Moolenaard823fa92016-08-12 16:29:27 +02007813 If the optional {what} dictionary argument is supplied, then
7814 only the items listed in {what} are set. Refer to |setqflist()|
7815 for the list of supported keys in {what}.
7816
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007817setmatches({list}) *setmatches()*
7818 Restores a list of matches saved by |getmatches()|. Returns 0
Bram Moolenaar446cb832008-06-24 21:56:24 +00007819 if successful, otherwise -1. All current matches are cleared
Bram Moolenaar6ee10162007-07-26 20:58:42 +00007820 before the list is restored. See example for |getmatches()|.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007821
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007822 *setpos()*
7823setpos({expr}, {list})
7824 Set the position for {expr}. Possible values:
7825 . the cursor
7826 'x mark x
7827
Bram Moolenaar493c1782014-05-28 14:34:46 +02007828 {list} must be a |List| with four or five numbers:
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007829 [bufnum, lnum, col, off]
Bram Moolenaar493c1782014-05-28 14:34:46 +02007830 [bufnum, lnum, col, off, curswant]
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007831
Bram Moolenaar58b85342016-08-14 19:54:54 +02007832 "bufnum" is the buffer number. Zero can be used for the
Bram Moolenaarf13e00b2017-01-28 18:23:54 +01007833 current buffer. When setting an uppercase mark "bufnum" is
7834 used for the mark position. For other marks it specifies the
7835 buffer to set the mark in. You can use the |bufnr()| function
7836 to turn a file name into a buffer number.
7837 For setting the cursor and the ' mark "bufnum" is ignored,
7838 since these are associated with a window, not a buffer.
Bram Moolenaardb552d602006-03-23 22:59:57 +00007839 Does not change the jumplist.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007840
7841 "lnum" and "col" are the position in the buffer. The first
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007842 column is 1. Use a zero "lnum" to delete a mark. If "col" is
7843 smaller than 1 then 1 is used.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007844
7845 The "off" number is only used when 'virtualedit' is set. Then
7846 it is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00007847 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007848 character.
7849
Bram Moolenaar493c1782014-05-28 14:34:46 +02007850 The "curswant" number is only used when setting the cursor
7851 position. It sets the preferred column for when moving the
7852 cursor vertically. When the "curswant" number is missing the
7853 preferred column is not set. When it is present and setting a
7854 mark position it is not used.
7855
Bram Moolenaardfb18412013-12-11 18:53:29 +01007856 Note that for '< and '> changing the line number may result in
7857 the marks to be effectively be swapped, so that '< is always
7858 before '>.
7859
Bram Moolenaar08250432008-02-13 11:42:46 +00007860 Returns 0 when the position could be set, -1 otherwise.
7861 An error message is given if {expr} is invalid.
7862
Bram Moolenaar6f6c0f82014-05-28 20:31:42 +02007863 Also see |getpos()| and |getcurpos()|.
Bram Moolenaar65c923a2006-03-03 22:56:30 +00007864
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007865 This does not restore the preferred column for moving
Bram Moolenaar493c1782014-05-28 14:34:46 +02007866 vertically; if you set the cursor position with this, |j| and
7867 |k| motions will jump to previous columns! Use |cursor()| to
7868 also set the preferred column. Also see the "curswant" key in
7869 |winrestview()|.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00007870
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007871setqflist({list} [, {action} [, {what}]]) *setqflist()*
Bram Moolenaarae338332017-08-11 20:25:26 +02007872 Create or replace or add to the quickfix list.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007873
Bram Moolenaarae338332017-08-11 20:25:26 +02007874 When {what} is not present, use the items in {list}. Each
7875 item must be a dictionary. Non-dictionary items in {list} are
7876 ignored. Each dictionary item can contain the following
7877 entries:
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007878
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00007879 bufnr buffer number; must be the number of a valid
Bram Moolenaar446cb832008-06-24 21:56:24 +00007880 buffer
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00007881 filename name of a file; only used when "bufnr" is not
Bram Moolenaar446cb832008-06-24 21:56:24 +00007882 present or it is invalid.
Bram Moolenaard76ce852018-05-01 15:02:04 +02007883 module name of a module; if given it will be used in
7884 quickfix error window instead of the filename.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007885 lnum line number in the file
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007886 pattern search pattern used to locate the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00007887 col column number
7888 vcol when non-zero: "col" is visual column
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007889 when zero: "col" is byte index
Bram Moolenaar582fd852005-03-28 20:58:01 +00007890 nr error number
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007891 text description of the error
Bram Moolenaar582fd852005-03-28 20:58:01 +00007892 type single-character error type, 'E', 'W', etc.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02007893 valid recognized error message
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007894
Bram Moolenaar582fd852005-03-28 20:58:01 +00007895 The "col", "vcol", "nr", "type" and "text" entries are
7896 optional. Either "lnum" or "pattern" entry can be used to
7897 locate a matching error line.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00007898 If the "filename" and "bufnr" entries are not present or
7899 neither the "lnum" or "pattern" entries are present, then the
7900 item will not be handled as an error line.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007901 If both "pattern" and "lnum" are present then "pattern" will
7902 be used.
Bram Moolenaarf1d21c82017-04-22 21:20:46 +02007903 If the "valid" entry is not supplied, then the valid flag is
7904 set when "bufnr" is a valid buffer or "filename" exists.
Bram Moolenaar00a927d2010-05-14 23:24:24 +02007905 If you supply an empty {list}, the quickfix list will be
7906 cleared.
Bram Moolenaar48b66fb2007-02-04 01:58:18 +00007907 Note that the list is not exactly the same as what
7908 |getqflist()| returns.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007909
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02007910 {action} values: *E927*
7911 'a' The items from {list} are added to the existing
7912 quickfix list. If there is no existing list, then a
7913 new list is created.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007914
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02007915 'r' The items from the current quickfix list are replaced
7916 with the items from {list}. This can also be used to
7917 clear the list: >
7918 :call setqflist([], 'r')
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007919<
Bram Moolenaarb6fa30c2017-03-29 14:19:25 +02007920 'f' All the quickfix lists in the quickfix stack are
7921 freed.
7922
Bram Moolenaar511972d2016-06-04 18:09:59 +02007923 If {action} is not present or is set to ' ', then a new list
Bram Moolenaar55b69262017-08-13 13:42:01 +02007924 is created. The new quickfix list is added after the current
7925 quickfix list in the stack and all the following lists are
7926 freed. To add a new quickfix list at the end of the stack,
Bram Moolenaar36538222017-09-02 19:51:44 +02007927 set "nr" in {what} to "$".
Bram Moolenaar35c54e52005-05-20 21:25:31 +00007928
Bram Moolenaard823fa92016-08-12 16:29:27 +02007929 If the optional {what} dictionary argument is supplied, then
7930 only the items listed in {what} are set. The first {list}
7931 argument is ignored. The following items can be specified in
7932 {what}:
Bram Moolenaar15142e22018-04-30 22:19:58 +02007933 context quickfix list context. See |quickfix-context|
Bram Moolenaar36538222017-09-02 19:51:44 +02007934 efm errorformat to use when parsing text from
7935 "lines". If this is not present, then the
7936 'errorformat' option value is used.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007937 See |quickfix-parse|
Bram Moolenaara539f4f2017-08-30 20:33:55 +02007938 id quickfix list identifier |quickfix-ID|
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007939 idx index of the current entry in the quickfix
7940 list specified by 'id' or 'nr'. If set to '$',
7941 then the last entry in the list is set as the
7942 current entry. See |quickfix-index|
Bram Moolenaar6a8958d2017-06-22 21:33:20 +02007943 items list of quickfix entries. Same as the {list}
7944 argument.
Bram Moolenaar2c809b72017-09-01 18:34:02 +02007945 lines use 'errorformat' to parse a list of lines and
7946 add the resulting entries to the quickfix list
7947 {nr} or {id}. Only a |List| value is supported.
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007948 See |quickfix-parse|
Bram Moolenaar875feea2017-06-11 16:07:51 +02007949 nr list number in the quickfix stack; zero
Bram Moolenaar36538222017-09-02 19:51:44 +02007950 means the current quickfix list and "$" means
Bram Moolenaar5b69c222019-01-11 14:50:06 +01007951 the last quickfix list.
7952 title quickfix list title text. See |quickfix-title|
Bram Moolenaard823fa92016-08-12 16:29:27 +02007953 Unsupported keys in {what} are ignored.
7954 If the "nr" item is not present, then the current quickfix list
Bram Moolenaar86f100dc2017-06-28 21:26:27 +02007955 is modified. When creating a new quickfix list, "nr" can be
7956 set to a value one greater than the quickfix stack size.
Bram Moolenaara539f4f2017-08-30 20:33:55 +02007957 When modifying a quickfix list, to guarantee that the correct
Bram Moolenaar36538222017-09-02 19:51:44 +02007958 list is modified, "id" should be used instead of "nr" to
Bram Moolenaara539f4f2017-08-30 20:33:55 +02007959 specify the list.
Bram Moolenaard823fa92016-08-12 16:29:27 +02007960
Bram Moolenaar15142e22018-04-30 22:19:58 +02007961 Examples (See also |setqflist-examples|): >
Bram Moolenaar2c809b72017-09-01 18:34:02 +02007962 :call setqflist([], 'r', {'title': 'My search'})
7963 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'})
Bram Moolenaar15142e22018-04-30 22:19:58 +02007964 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]})
Bram Moolenaard823fa92016-08-12 16:29:27 +02007965<
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007966 Returns zero for success, -1 for failure.
7967
7968 This function can be used to create a quickfix list
7969 independent of the 'errorformat' setting. Use a command like
Bram Moolenaar94237492017-04-23 18:40:21 +02007970 `:cc 1` to jump to the first position.
Bram Moolenaar68b76a62005-03-25 21:53:48 +00007971
7972
Bram Moolenaar071d4272004-06-13 20:20:40 +00007973 *setreg()*
Bram Moolenaare0fa3742016-02-20 15:47:01 +01007974setreg({regname}, {value} [, {options}])
Bram Moolenaar071d4272004-06-13 20:20:40 +00007975 Set the register {regname} to {value}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007976 {value} may be any value returned by |getreg()|, including
Bram Moolenaar5a50c222014-04-02 22:17:10 +02007977 a |List|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007978 If {options} contains "a" or {regname} is upper case,
7979 then the value is appended.
Bram Moolenaarc6485bc2010-07-28 17:02:55 +02007980 {options} can also contain a register type specification:
Bram Moolenaar071d4272004-06-13 20:20:40 +00007981 "c" or "v" |characterwise| mode
7982 "l" or "V" |linewise| mode
7983 "b" or "<CTRL-V>" |blockwise-visual| mode
7984 If a number immediately follows "b" or "<CTRL-V>" then this is
7985 used as the width of the selection - if it is not specified
7986 then the width of the block is set to the number of characters
Bram Moolenaard46bbc72007-05-12 14:38:41 +00007987 in the longest line (counting a <Tab> as 1 character).
Bram Moolenaar071d4272004-06-13 20:20:40 +00007988
7989 If {options} contains no register settings, then the default
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007990 is to use character mode unless {value} ends in a <NL> for
7991 string {value} and linewise mode for list {value}. Blockwise
Bram Moolenaar5a50c222014-04-02 22:17:10 +02007992 mode is never selected automatically.
7993 Returns zero for success, non-zero for failure.
7994
7995 *E883*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01007996 Note: you may not use |List| containing more than one item to
7997 set search and expression registers. Lists containing no
Bram Moolenaar5a50c222014-04-02 22:17:10 +02007998 items act like empty strings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007999
8000 Examples: >
8001 :call setreg(v:register, @*)
8002 :call setreg('*', @%, 'ac')
8003 :call setreg('a', "1\n2\n3", 'b5')
8004
8005< This example shows using the functions to save and restore a
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008006 register: >
Bram Moolenaar5a50c222014-04-02 22:17:10 +02008007 :let var_a = getreg('a', 1, 1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008008 :let var_amode = getregtype('a')
8009 ....
8010 :call setreg('a', var_a, var_amode)
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008011< Note: you may not reliably restore register value
8012 without using the third argument to |getreg()| as without it
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008013 newlines are represented as newlines AND Nul bytes are
8014 represented as newlines as well, see |NL-used-for-Nul|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008015
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02008016 You can also change the type of a register by appending
Bram Moolenaar071d4272004-06-13 20:20:40 +00008017 nothing: >
8018 :call setreg('a', '', 'al')
8019
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008020settabvar({tabnr}, {varname}, {val}) *settabvar()*
8021 Set tab-local variable {varname} to {val} in tab page {tabnr}.
8022 |t:var|
8023 Note that the variable name without "t:" must be used.
8024 Tabs are numbered starting with one.
Bram Moolenaar06b5d512010-05-22 15:37:44 +02008025 This function is not available in the |sandbox|.
8026
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008027settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()*
8028 Set option or local variable {varname} in window {winnr} to
8029 {val}.
8030 Tabs are numbered starting with one. For the current tabpage
8031 use |setwinvar()|.
Bram Moolenaar7571d552016-08-18 22:54:46 +02008032 {winnr} can be the window number or the |window-ID|.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008033 When {winnr} is zero the current window is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008034 This also works for a global or local buffer option, but it
8035 doesn't work for a global or local buffer variable.
8036 For a local buffer option the global value is unchanged.
8037 Note that the variable name without "w:" must be used.
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008038 Examples: >
8039 :call settabwinvar(1, 1, "&list", 0)
8040 :call settabwinvar(3, 2, "myvar", "foobar")
8041< This function is not available in the |sandbox|.
8042
Bram Moolenaarf49cc602018-11-11 15:21:05 +01008043settagstack({nr}, {dict} [, {action}]) *settagstack()*
8044 Modify the tag stack of the window {nr} using {dict}.
8045 {nr} can be the window number or the |window-ID|.
8046
8047 For a list of supported items in {dict}, refer to
8048 |gettagstack()|
8049 *E962*
8050 If {action} is not present or is set to 'r', then the tag
8051 stack is replaced. If {action} is set to 'a', then new entries
8052 from {dict} are pushed onto the tag stack.
8053
8054 Returns zero for success, -1 for failure.
8055
8056 Examples:
8057 Set current index of the tag stack to 4: >
8058 call settagstack(1005, {'curidx' : 4})
8059
8060< Empty the tag stack of window 3: >
8061 call settagstack(3, {'items' : []})
8062
8063< Push a new item onto the tag stack: >
8064 let pos = [bufnr('myfile.txt'), 10, 1, 0]
8065 let newtag = [{'tagname' : 'mytag', 'from' : pos}]
8066 call settagstack(2, {'items' : newtag}, 'a')
8067
8068< Save and restore the tag stack: >
8069 let stack = gettagstack(1003)
8070 " do something else
8071 call settagstack(1003, stack)
8072 unlet stack
8073<
Bram Moolenaarc6249bb2006-04-15 20:25:09 +00008074setwinvar({nr}, {varname}, {val}) *setwinvar()*
8075 Like |settabwinvar()| for the current tab page.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008076 Examples: >
8077 :call setwinvar(1, "&list", 0)
8078 :call setwinvar(2, "myvar", "foobar")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008079
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01008080sha256({string}) *sha256()*
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01008081 Returns a String with 64 hex characters, which is the SHA256
Bram Moolenaaraf9aeb92013-02-13 17:35:04 +01008082 checksum of {string}.
8083 {only available when compiled with the |+cryptv| feature}
8084
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008085shellescape({string} [, {special}]) *shellescape()*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008086 Escape {string} for use as a shell command argument.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008087 On MS-Windows and MS-DOS, when 'shellslash' is not set, it
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008088 will enclose {string} in double quotes and double all double
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008089 quotes within {string}.
Bram Moolenaare381d3d2016-07-07 14:50:41 +02008090 Otherwise it will enclose {string} in single quotes and
8091 replace all "'" with "'\''".
Bram Moolenaar875feea2017-06-11 16:07:51 +02008092
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008093 When the {special} argument is present and it's a non-zero
8094 Number or a non-empty String (|non-zero-arg|), then special
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008095 items such as "!", "%", "#" and "<cword>" will be preceded by
8096 a backslash. This backslash will be removed again by the |:!|
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008097 command.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008098
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008099 The "!" character will be escaped (again with a |non-zero-arg|
8100 {special}) when 'shell' contains "csh" in the tail. That is
8101 because for csh and tcsh "!" is used for history replacement
8102 even when inside single quotes.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008103
8104 With a |non-zero-arg| {special} the <NL> character is also
8105 escaped. When 'shell' containing "csh" in the tail it's
Bram Moolenaare37d50a2008-08-06 17:06:04 +00008106 escaped a second time.
Bram Moolenaar875feea2017-06-11 16:07:51 +02008107
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008108 Example of use with a |:!| command: >
8109 :exe '!dir ' . shellescape(expand('<cfile>'), 1)
8110< This results in a directory listing for the file under the
8111 cursor. Example of use with |system()|: >
8112 :call system("chmod +w -- " . shellescape(expand("%")))
Bram Moolenaar26df0922014-02-23 23:39:13 +01008113< See also |::S|.
Bram Moolenaar60a495f2006-10-03 12:44:42 +00008114
8115
Bram Moolenaarf9514162018-11-22 03:08:29 +01008116shiftwidth([{col}]) *shiftwidth()*
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008117 Returns the effective value of 'shiftwidth'. This is the
8118 'shiftwidth' value unless it is zero, in which case it is the
Bram Moolenaar009d84a2016-01-28 14:12:00 +01008119 'tabstop' value. This function was introduced with patch
Bram Moolenaarf9514162018-11-22 03:08:29 +01008120 7.3.694 in 2012, everybody should have it by now (however it
8121 did not allow for the optional {col} argument until 8.1.542).
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008122
Bram Moolenaarf9514162018-11-22 03:08:29 +01008123 When there is one argument {col} this is used as column number
8124 for which to return the 'shiftwidth' value. This matters for the
8125 'vartabstop' feature. If the 'vartabstop' setting is enabled and
8126 no {col} argument is given, column 1 will be assumed.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01008127
Bram Moolenaar162b7142018-12-21 15:17:36 +01008128sign_define({name} [, {dict}]) *sign_define()*
8129 Define a new sign named {name} or modify the attributes of an
8130 existing sign. This is similar to the |:sign-define| command.
Bram Moolenaar2d17fa32012-10-21 00:45:18 +02008131
Bram Moolenaar162b7142018-12-21 15:17:36 +01008132 Prefix {name} with a unique text to avoid name collisions.
8133 There is no {group} like with placing signs.
8134
8135 The {name} can be a String or a Number. The optional {dict}
8136 argument specifies the sign attributes. The following values
8137 are supported:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008138 icon full path to the bitmap file for the sign.
8139 linehl highlight group used for the whole line the
Bram Moolenaar162b7142018-12-21 15:17:36 +01008140 sign is placed in.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008141 text text that is displayed when there is no icon
Bram Moolenaar162b7142018-12-21 15:17:36 +01008142 or the GUI is not being used.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008143 texthl highlight group used for the text item
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008144
8145 If the sign named {name} already exists, then the attributes
8146 of the sign are updated.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008147
8148 Returns 0 on success and -1 on failure.
8149
8150 Examples: >
8151 call sign_define("mySign", {"text" : "=>", "texthl" :
8152 \ "Error", "linehl" : "Search"})
8153<
8154sign_getdefined([{name}]) *sign_getdefined()*
8155 Get a list of defined signs and their attributes.
8156 This is similar to the |:sign-list| command.
8157
8158 If the {name} is not supplied, then a list of all the defined
8159 signs is returned. Otherwise the attribute of the specified
8160 sign is returned.
8161
8162 Each list item in the returned value is a dictionary with the
8163 following entries:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008164 icon full path to the bitmap file of the sign
8165 linehl highlight group used for the whole line the
Bram Moolenaar162b7142018-12-21 15:17:36 +01008166 sign is placed in.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008167 name name of the sign
8168 text text that is displayed when there is no icon
Bram Moolenaar162b7142018-12-21 15:17:36 +01008169 or the GUI is not being used.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008170 texthl highlight group used for the text item
Bram Moolenaar162b7142018-12-21 15:17:36 +01008171
8172 Returns an empty List if there are no signs and when {name} is
8173 not found.
8174
8175 Examples: >
8176 " Get a list of all the defined signs
8177 echo sign_getdefined()
8178
8179 " Get the attribute of the sign named mySign
8180 echo sign_getdefined("mySign")
8181<
8182sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()*
8183 Return a list of signs placed in a buffer or all the buffers.
8184 This is similar to the |:sign-place-list| command.
8185
8186 If the optional buffer name {expr} is specified, then only the
8187 list of signs placed in that buffer is returned. For the use
8188 of {expr}, see |bufname()|. The optional {dict} can contain
8189 the following entries:
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008190 group select only signs in this group
8191 id select sign with this identifier
8192 lnum select signs placed in this line. For the use
Bram Moolenaar162b7142018-12-21 15:17:36 +01008193 of {lnum}, see |line()|.
8194 If {group} is '*', then signs in all the groups including the
Bram Moolenaar6436cd82018-12-27 00:28:33 +01008195 global group are returned. If {group} is not supplied or is an
8196 empty string, then only signs in the global group are
8197 returned. If no arguments are supplied, then signs in the
8198 global group placed in all the buffers are returned.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008199 See |sign-group|.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008200
8201 Each list item in the returned value is a dictionary with the
8202 following entries:
8203 bufnr number of the buffer with the sign
8204 signs list of signs placed in {bufnr}. Each list
8205 item is a dictionary with the below listed
8206 entries
8207
8208 The dictionary for each sign contains the following entries:
8209 group sign group. Set to '' for the global group.
8210 id identifier of the sign
8211 lnum line number where the sign is placed
8212 name name of the defined sign
8213 priority sign priority
8214
Bram Moolenaarb589f952019-01-07 22:10:00 +01008215 The returned signs in a buffer are ordered by their line
8216 number.
8217
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008218 Returns an empty list on failure or if there are no placed
8219 signs.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008220
8221 Examples: >
8222 " Get a List of signs placed in eval.c in the
8223 " global group
8224 echo sign_getplaced("eval.c")
8225
8226 " Get a List of signs in group 'g1' placed in eval.c
8227 echo sign_getplaced("eval.c", {'group' : 'g1'})
8228
8229 " Get a List of signs placed at line 10 in eval.c
8230 echo sign_getplaced("eval.c", {'lnum' : 10})
8231
8232 " Get sign with identifier 10 placed in a.py
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008233 echo sign_getplaced("a.py", {'id' : 10})
Bram Moolenaar162b7142018-12-21 15:17:36 +01008234
8235 " Get sign with id 20 in group 'g1' placed in a.py
8236 echo sign_getplaced("a.py", {'group' : 'g1',
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008237 \ 'id' : 20})
Bram Moolenaar162b7142018-12-21 15:17:36 +01008238
8239 " Get a List of all the placed signs
8240 echo sign_getplaced()
8241<
Bram Moolenaar6b7b7192019-01-11 13:42:41 +01008242 *sign_jump()*
8243sign_jump({id}, {group}, {expr})
8244 Open the buffer {expr} or jump to the window that contains
8245 {expr} and position the cursor at sign {id} in group {group}.
8246 This is similar to the |:sign-jump| command.
8247
8248 For the use of {expr}, see |bufname()|.
8249
8250 Returns the line number of the sign. Returns -1 if the
8251 arguments are invalid.
8252
8253 Example: >
8254 " Jump to sign 10 in the current buffer
8255 call sign_jump(10, '', '')
8256<
Bram Moolenaar162b7142018-12-21 15:17:36 +01008257 *sign_place()*
8258sign_place({id}, {group}, {name}, {expr} [, {dict}])
8259 Place the sign defined as {name} at line {lnum} in file {expr}
8260 and assign {id} and {group} to sign. This is similar to the
8261 |:sign-place| command.
8262
8263 If the sign identifier {id} is zero, then a new identifier is
8264 allocated. Otherwise the specified number is used. {group} is
8265 the sign group name. To use the global sign group, use an
8266 empty string. {group} functions as a namespace for {id}, thus
Bram Moolenaarb328cca2019-01-06 16:24:01 +01008267 two groups can use the same IDs. Refer to |sign-identifier|
Bram Moolenaar5b69c222019-01-11 14:50:06 +01008268 and |sign-group| for more information.
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008269
Bram Moolenaar162b7142018-12-21 15:17:36 +01008270 {name} refers to a defined sign.
8271 {expr} refers to a buffer name or number. For the accepted
8272 values, see |bufname()|.
8273
8274 The optional {dict} argument supports the following entries:
8275 lnum line number in the buffer {expr} where
8276 the sign is to be placed. For the
8277 accepted values, see |line()|.
8278 priority priority of the sign. See
8279 |sign-priority| for more information.
8280
8281 If the optional {dict} is not specified, then it modifies the
8282 placed sign {id} in group {group} to use the defined sign
8283 {name}.
8284
8285 Returns the sign identifier on success and -1 on failure.
8286
8287 Examples: >
8288 " Place a sign named sign1 with id 5 at line 20 in
8289 " buffer json.c
8290 call sign_place(5, '', 'sign1', 'json.c',
8291 \ {'lnum' : 20})
8292
8293 " Updates sign 5 in buffer json.c to use sign2
8294 call sign_place(5, '', 'sign2', 'json.c')
8295
8296 " Place a sign named sign3 at line 30 in
8297 " buffer json.c with a new identifier
8298 let id = sign_place(0, '', 'sign3', 'json.c',
8299 \ {'lnum' : 30})
8300
8301 " Place a sign named sign4 with id 10 in group 'g3'
8302 " at line 40 in buffer json.c with priority 90
8303 call sign_place(10, 'g3', 'sign4', 'json.c',
8304 \ {'lnum' : 40, 'priority' : 90})
8305<
8306sign_undefine([{name}]) *sign_undefine()*
8307 Deletes a previously defined sign {name}. This is similar to
8308 the |:sign-undefine| command. If {name} is not supplied, then
8309 deletes all the defined signs.
8310
8311 Returns 0 on success and -1 on failure.
8312
8313 Examples: >
8314 " Delete a sign named mySign
8315 call sign_undefine("mySign")
8316
8317 " Delete all the signs
8318 call sign_undefine()
8319<
8320sign_unplace({group} [, {dict}]) *sign_unplace()*
8321 Remove a previously placed sign in one or more buffers. This
Bram Moolenaarc8c88492018-12-27 23:59:26 +01008322 is similar to the |:sign-unplace| command.
Bram Moolenaar162b7142018-12-21 15:17:36 +01008323
8324 {group} is the sign group name. To use the global sign group,
8325 use an empty string. If {group} is set to '*', then all the
8326 groups including the global group are used.
8327 The signs in {group} are selected based on the entries in
8328 {dict}. The following optional entries in {dict} are
8329 supported:
8330 buffer buffer name or number. See |bufname()|.
8331 id sign identifier
8332 If {dict} is not supplied, then all the signs in {group} are
8333 removed.
8334
8335 Returns 0 on success and -1 on failure.
8336
8337 Examples: >
8338 " Remove sign 10 from buffer a.vim
8339 call sign_unplace('', {'buffer' : "a.vim", 'id' : 10})
8340
8341 " Remove sign 20 in group 'g1' from buffer 3
8342 call sign_unplace('g1', {'buffer' : 3, 'id' : 20})
8343
8344 " Remove all the signs in group 'g2' from buffer 10
8345 call sign_unplace('g2', {'buffer' : 10})
8346
8347 " Remove sign 30 in group 'g3' from all the buffers
8348 call sign_unplace('g3', {'id' : 30})
8349
8350 " Remove all the signs placed in buffer 5
8351 call sign_unplace('*', {'buffer' : 5})
8352
8353 " Remove the signs in group 'g4' from all the buffers
8354 call sign_unplace('g4')
8355
8356 " Remove sign 40 from all the buffers
8357 call sign_unplace('*', {'id' : 40})
8358
8359 " Remove all the placed signs from all the buffers
8360 call sign_unplace('*')
8361<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008362simplify({filename}) *simplify()*
8363 Simplify the file name as much as possible without changing
8364 the meaning. Shortcuts (on MS-Windows) or symbolic links (on
8365 Unix) are not resolved. If the first path component in
8366 {filename} designates the current directory, this will be
8367 valid for the result as well. A trailing path separator is
8368 not removed either.
8369 Example: >
8370 simplify("./dir/.././/file/") == "./file/"
8371< Note: The combination "dir/.." is only removed if "dir" is
8372 a searchable directory or does not exist. On Unix, it is also
8373 removed when "dir" is a symbolic link within the same
8374 directory. In order to resolve all the involved symbolic
8375 links before simplifying the path name, use |resolve()|.
8376
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008377
Bram Moolenaar446cb832008-06-24 21:56:24 +00008378sin({expr}) *sin()*
8379 Return the sine of {expr}, measured in radians, as a |Float|.
8380 {expr} must evaluate to a |Float| or a |Number|.
8381 Examples: >
8382 :echo sin(100)
8383< -0.506366 >
8384 :echo sin(-4.01)
8385< 0.763301
8386 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008387
Bram Moolenaar446cb832008-06-24 21:56:24 +00008388
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008389sinh({expr}) *sinh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008390 Return the hyperbolic sine of {expr} as a |Float| in the range
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008391 [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02008392 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008393 Examples: >
8394 :echo sinh(0.5)
8395< 0.521095 >
8396 :echo sinh(-0.9)
8397< -1.026517
Bram Moolenaardb84e452010-08-15 13:50:43 +02008398 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02008399
8400
Bram Moolenaar5f894962011-06-19 02:55:37 +02008401sort({list} [, {func} [, {dict}]]) *sort()* *E702*
Bram Moolenaar327aa022014-03-25 18:24:23 +01008402 Sort the items in {list} in-place. Returns {list}.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008403
Bram Moolenaar327aa022014-03-25 18:24:23 +01008404 If you want a list to remain unmodified make a copy first: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008405 :let sortedlist = sort(copy(mylist))
Bram Moolenaar822ff862014-06-12 21:46:14 +02008406
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008407< When {func} is omitted, is empty or zero, then sort() uses the
8408 string representation of each item to sort on. Numbers sort
8409 after Strings, |Lists| after Numbers. For sorting text in the
8410 current buffer use |:sort|.
Bram Moolenaar327aa022014-03-25 18:24:23 +01008411
Bram Moolenaar34401cc2014-08-29 15:12:19 +02008412 When {func} is given and it is '1' or 'i' then case is
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008413 ignored.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008414
Bram Moolenaar946e27a2014-06-25 18:50:27 +02008415 When {func} is given and it is 'n' then all items will be
8416 sorted numerical (Implementation detail: This uses the
8417 strtod() function to parse numbers, Strings, Lists, Dicts and
8418 Funcrefs will be considered as being 0).
8419
Bram Moolenaarb00da1d2015-12-03 16:33:12 +01008420 When {func} is given and it is 'N' then all items will be
8421 sorted numerical. This is like 'n' but a string containing
8422 digits will be used as the number they represent.
8423
Bram Moolenaar13d5aee2016-01-21 23:36:05 +01008424 When {func} is given and it is 'f' then all items will be
8425 sorted numerical. All values must be a Number or a Float.
8426
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008427 When {func} is a |Funcref| or a function name, this function
8428 is called to compare items. The function is invoked with two
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008429 items as argument and must return zero if they are equal, 1 or
8430 bigger if the first one sorts after the second one, -1 or
8431 smaller if the first one sorts before the second one.
Bram Moolenaar327aa022014-03-25 18:24:23 +01008432
8433 {dict} is for functions with the "dict" attribute. It will be
8434 used to set the local variable "self". |Dictionary-function|
8435
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02008436 The sort is stable, items which compare equal (as number or as
8437 string) will keep their relative position. E.g., when sorting
Bram Moolenaardb6ea062014-07-10 22:01:47 +02008438 on numbers, text strings will sort next to each other, in the
Bram Moolenaar8bb1c3e2014-07-04 16:43:17 +02008439 same order as they were originally.
8440
Bram Moolenaar327aa022014-03-25 18:24:23 +01008441 Also see |uniq()|.
8442
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008443 Example: >
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008444 func MyCompare(i1, i2)
8445 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1
8446 endfunc
8447 let sortedlist = sort(mylist, "MyCompare")
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008448< A shorter compare version for this specific simple case, which
8449 ignores overflow: >
8450 func MyCompare(i1, i2)
8451 return a:i1 - a:i2
8452 endfunc
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008453<
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00008454 *soundfold()*
8455soundfold({word})
8456 Return the sound-folded equivalent of {word}. Uses the first
Bram Moolenaar446cb832008-06-24 21:56:24 +00008457 language in 'spelllang' for the current window that supports
Bram Moolenaar42eeac32005-06-29 22:40:58 +00008458 soundfolding. 'spell' must be set. When no sound folding is
8459 possible the {word} is returned unmodified.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00008460 This can be used for making spelling suggestions. Note that
8461 the method can be quite slow.
8462
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008463 *spellbadword()*
Bram Moolenaar1e015462005-09-25 22:16:38 +00008464spellbadword([{sentence}])
8465 Without argument: The result is the badly spelled word under
8466 or after the cursor. The cursor is moved to the start of the
8467 bad word. When no bad word is found in the cursor line the
8468 result is an empty string and the cursor doesn't move.
8469
8470 With argument: The result is the first word in {sentence} that
8471 is badly spelled. If there are no spelling mistakes the
8472 result is an empty string.
8473
8474 The return value is a list with two items:
8475 - The badly spelled word or an empty string.
8476 - The type of the spelling error:
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008477 "bad" spelling mistake
Bram Moolenaar1e015462005-09-25 22:16:38 +00008478 "rare" rare word
8479 "local" word only valid in another region
8480 "caps" word should start with Capital
8481 Example: >
8482 echo spellbadword("the quik brown fox")
8483< ['quik', 'bad'] ~
8484
8485 The spelling information for the current window is used. The
8486 'spell' option must be set and the value of 'spelllang' is
8487 used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008488
8489 *spellsuggest()*
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00008490spellsuggest({word} [, {max} [, {capital}]])
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008491 Return a |List| with spelling suggestions to replace {word}.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008492 When {max} is given up to this number of suggestions are
8493 returned. Otherwise up to 25 suggestions are returned.
8494
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00008495 When the {capital} argument is given and it's non-zero only
8496 suggestions with a leading capital will be given. Use this
8497 after a match with 'spellcapcheck'.
8498
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008499 {word} can be a badly spelled word followed by other text.
8500 This allows for joining two words that were split. The
Bram Moolenaarf461c8e2005-06-25 23:04:51 +00008501 suggestions also include the following text, thus you can
8502 replace a line.
8503
8504 {word} may also be a good word. Similar words will then be
Bram Moolenaarc54b8a72005-09-30 21:20:29 +00008505 returned. {word} itself is not included in the suggestions,
8506 although it may appear capitalized.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008507
8508 The spelling information for the current window is used. The
Bram Moolenaar42eeac32005-06-29 22:40:58 +00008509 'spell' option must be set and the values of 'spelllang' and
8510 'spellsuggest' are used.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00008511
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008512
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008513split({expr} [, {pattern} [, {keepempty}]]) *split()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00008514 Make a |List| out of {expr}. When {pattern} is omitted or
8515 empty each white-separated sequence of characters becomes an
8516 item.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008517 Otherwise the string is split where {pattern} matches,
Bram Moolenaar97d62492012-11-15 21:28:22 +01008518 removing the matched characters. 'ignorecase' is not used
8519 here, add \c to ignore case. |/\c|
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008520 When the first or last item is empty it is omitted, unless the
8521 {keepempty} argument is given and it's non-zero.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008522 Other empty items are kept when {pattern} matches at least one
8523 character or when {keepempty} is non-zero.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008524 Example: >
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00008525 :let words = split(getline('.'), '\W\+')
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008526< To split a string in individual characters: >
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008527 :for c in split(mystring, '\zs')
Bram Moolenaar12969c02015-09-08 23:36:10 +02008528< If you want to keep the separator you can also use '\zs' at
8529 the end of the pattern: >
Bram Moolenaar0cb032e2005-04-23 20:52:00 +00008530 :echo split('abc:def:ghi', ':\zs')
8531< ['abc:', 'def:', 'ghi'] ~
Bram Moolenaar2389c3c2005-05-22 22:07:59 +00008532 Splitting a table where the first element can be empty: >
8533 :let items = split(line, ':', 1)
8534< The opposite function is |join()|.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008535
8536
Bram Moolenaar446cb832008-06-24 21:56:24 +00008537sqrt({expr}) *sqrt()*
8538 Return the non-negative square root of Float {expr} as a
8539 |Float|.
8540 {expr} must evaluate to a |Float| or a |Number|. When {expr}
8541 is negative the result is NaN (Not a Number).
8542 Examples: >
8543 :echo sqrt(100)
8544< 10.0 >
8545 :echo sqrt(-4.01)
8546< nan
Bram Moolenaarc236c162008-07-13 17:41:49 +00008547 "nan" may be different, it depends on system libraries.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008548 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008549
Bram Moolenaar446cb832008-06-24 21:56:24 +00008550
Bram Moolenaar81edd172016-04-14 13:51:37 +02008551str2float({expr}) *str2float()*
Bram Moolenaar446cb832008-06-24 21:56:24 +00008552 Convert String {expr} to a Float. This mostly works the same
8553 as when using a floating point number in an expression, see
8554 |floating-point-format|. But it's a bit more permissive.
8555 E.g., "1e40" is accepted, while in an expression you need to
Bram Moolenaard47d5222018-12-09 20:43:55 +01008556 write "1.0e40". The hexadecimal form "0x123" is also
8557 accepted, but not others, like binary or octal.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008558 Text after the number is silently ignored.
8559 The decimal point is always '.', no matter what the locale is
8560 set to. A comma ends the number: "12,345.67" is converted to
8561 12.0. You can strip out thousands separators with
8562 |substitute()|: >
8563 let f = str2float(substitute(text, ',', '', 'g'))
8564< {only available when compiled with the |+float| feature}
8565
8566
Bram Moolenaar81edd172016-04-14 13:51:37 +02008567str2nr({expr} [, {base}]) *str2nr()*
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008568 Convert string {expr} to a number.
Bram Moolenaarfa735342016-01-03 22:14:44 +01008569 {base} is the conversion base, it can be 2, 8, 10 or 16.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008570 When {base} is omitted base 10 is used. This also means that
8571 a leading zero doesn't cause octal conversion to be used, as
8572 with the default String to Number conversion.
8573 When {base} is 16 a leading "0x" or "0X" is ignored. With a
Bram Moolenaarfa735342016-01-03 22:14:44 +01008574 different base the result will be zero. Similarly, when
8575 {base} is 8 a leading "0" is ignored, and when {base} is 2 a
8576 leading "0b" or "0B" is ignored.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008577 Text after the number is silently ignored.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008578
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008579
Bram Moolenaar979243b2015-06-26 19:35:49 +02008580strchars({expr} [, {skipcc}]) *strchars()*
Bram Moolenaar72597a52010-07-18 15:31:08 +02008581 The result is a Number, which is the number of characters
Bram Moolenaar979243b2015-06-26 19:35:49 +02008582 in String {expr}.
8583 When {skipcc} is omitted or zero, composing characters are
8584 counted separately.
8585 When {skipcc} set to 1, Composing characters are ignored.
Bram Moolenaardc536092010-07-18 15:45:49 +02008586 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008587
Bram Moolenaar86ae7202015-07-10 19:31:35 +02008588 {skipcc} is only available after 7.4.755. For backward
8589 compatibility, you can define a wrapper function: >
8590 if has("patch-7.4.755")
8591 function s:strchars(str, skipcc)
8592 return strchars(a:str, a:skipcc)
8593 endfunction
8594 else
8595 function s:strchars(str, skipcc)
8596 if a:skipcc
8597 return strlen(substitute(a:str, ".", "x", "g"))
8598 else
8599 return strchars(a:str)
8600 endif
8601 endfunction
8602 endif
8603<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008604strcharpart({src}, {start} [, {len}]) *strcharpart()*
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008605 Like |strpart()| but using character index and length instead
8606 of byte index and length.
8607 When a character index is used where a character does not
Bram Moolenaar369b6f52017-01-17 12:22:32 +01008608 exist it is assumed to be one character. For example: >
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008609 strcharpart('abc', -1, 2)
8610< results in 'a'.
Bram Moolenaar86ae7202015-07-10 19:31:35 +02008611
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008612strdisplaywidth({expr} [, {col}]) *strdisplaywidth()*
Bram Moolenaardc536092010-07-18 15:45:49 +02008613 The result is a Number, which is the number of display cells
Bram Moolenaar979243b2015-06-26 19:35:49 +02008614 String {expr} occupies on the screen when it starts at {col}.
Bram Moolenaardc536092010-07-18 15:45:49 +02008615 When {col} is omitted zero is used. Otherwise it is the
8616 screen column where to start. This matters for Tab
8617 characters.
Bram Moolenaar4d32c2d2010-07-18 22:10:01 +02008618 The option settings of the current window are used. This
8619 matters for anything that's displayed differently, such as
8620 'tabstop' and 'display'.
Bram Moolenaardc536092010-07-18 15:45:49 +02008621 When {expr} contains characters with East Asian Width Class
8622 Ambiguous, this function's return value depends on 'ambiwidth'.
8623 Also see |strlen()|, |strwidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02008624
Bram Moolenaar071d4272004-06-13 20:20:40 +00008625strftime({format} [, {time}]) *strftime()*
8626 The result is a String, which is a formatted date and time, as
8627 specified by the {format} string. The given {time} is used,
8628 or the current time if no time is given. The accepted
8629 {format} depends on your system, thus this is not portable!
8630 See the manual page of the C function strftime() for the
8631 format. The maximum length of the result is 80 characters.
8632 See also |localtime()| and |getftime()|.
8633 The language can be changed with the |:language| command.
8634 Examples: >
8635 :echo strftime("%c") Sun Apr 27 11:49:23 1997
8636 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25
8637 :echo strftime("%y%m%d %T") 970427 11:53:55
8638 :echo strftime("%H:%M") 11:55
8639 :echo strftime("%c", getftime("file.c"))
8640 Show mod time of file.c.
Bram Moolenaara14de3d2005-01-07 21:48:26 +00008641< Not available on all systems. To check use: >
8642 :if exists("*strftime")
8643
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008644strgetchar({str}, {index}) *strgetchar()*
8645 Get character {index} from {str}. This uses a character
8646 index, not a byte index. Composing characters are considered
8647 separate characters here.
8648 Also see |strcharpart()| and |strchars()|.
8649
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008650stridx({haystack}, {needle} [, {start}]) *stridx()*
8651 The result is a Number, which gives the byte index in
8652 {haystack} of the first occurrence of the String {needle}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00008653 If {start} is specified, the search starts at index {start}.
8654 This can be used to find a second match: >
Bram Moolenaar81af9252010-12-10 20:35:50 +01008655 :let colon1 = stridx(line, ":")
8656 :let colon2 = stridx(line, ":", colon1 + 1)
Bram Moolenaar677ee682005-01-27 14:41:15 +00008657< The search is done case-sensitive.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00008658 For pattern searches use |match()|.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008659 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaar677ee682005-01-27 14:41:15 +00008660 See also |strridx()|.
8661 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008662 :echo stridx("An Example", "Example") 3
8663 :echo stridx("Starting point", "Start") 0
8664 :echo stridx("Starting point", "start") -1
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008665< *strstr()* *strchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00008666 stridx() works similar to the C function strstr(). When used
8667 with a single character it works similar to strchr().
8668
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008669 *string()*
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00008670string({expr}) Return {expr} converted to a String. If {expr} is a Number,
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01008671 Float, String, Blob or a composition of them, then the result
8672 can be parsed back with |eval()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008673 {expr} type result ~
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01008674 String 'string' (single quotes are doubled)
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00008675 Number 123
Bram Moolenaar446cb832008-06-24 21:56:24 +00008676 Float 123.123456 or 1.123456e8
Bram Moolenaard8b02732005-01-14 21:48:43 +00008677 Funcref function('name')
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01008678 Blob 0z00112233.44556677.8899
Bram Moolenaar5f2bb9f2005-01-11 21:29:04 +00008679 List [item, item]
Bram Moolenaar9ba0eb82005-06-13 22:28:56 +00008680 Dictionary {key: value, key: value}
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01008681
8682 When a List or Dictionary has a recursive reference it is
8683 replaced by "[...]" or "{...}". Using eval() on the result
8684 will then fail.
8685
Bram Moolenaaref2f6562007-05-06 13:32:59 +00008686 Also see |strtrans()|.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008687
Bram Moolenaar071d4272004-06-13 20:20:40 +00008688 *strlen()*
8689strlen({expr}) The result is a Number, which is the length of the String
Bram Moolenaare344bea2005-09-01 20:46:49 +00008690 {expr} in bytes.
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +00008691 If the argument is a Number it is first converted to a String.
8692 For other types an error is given.
Bram Moolenaar641e48c2015-06-25 16:09:26 +02008693 If you want to count the number of multi-byte characters use
8694 |strchars()|.
8695 Also see |len()|, |strdisplaywidth()| and |strwidth()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008696
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008697strpart({src}, {start} [, {len}]) *strpart()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008698 The result is a String, which is part of {src}, starting from
Bram Moolenaar9372a112005-12-06 19:59:18 +00008699 byte {start}, with the byte length {len}.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008700 To count characters instead of bytes use |strcharpart()|.
8701
8702 When bytes are selected which do not exist, this doesn't
8703 result in an error, the bytes are simply omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008704 If {len} is missing, the copy continues from {start} till the
8705 end of the {src}. >
8706 strpart("abcdefg", 3, 2) == "de"
8707 strpart("abcdefg", -2, 4) == "ab"
8708 strpart("abcdefg", 5, 4) == "fg"
Bram Moolenaar446cb832008-06-24 21:56:24 +00008709 strpart("abcdefg", 3) == "defg"
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008710
Bram Moolenaar071d4272004-06-13 20:20:40 +00008711< Note: To get the first character, {start} must be 0. For
8712 example, to get three bytes under and after the cursor: >
Bram Moolenaar61660ea2006-04-07 21:40:07 +00008713 strpart(getline("."), col(".") - 1, 3)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008714<
Bram Moolenaar677ee682005-01-27 14:41:15 +00008715strridx({haystack}, {needle} [, {start}]) *strridx()*
8716 The result is a Number, which gives the byte index in
8717 {haystack} of the last occurrence of the String {needle}.
8718 When {start} is specified, matches beyond this index are
8719 ignored. This can be used to find a match before a previous
8720 match: >
8721 :let lastcomma = strridx(line, ",")
8722 :let comma2 = strridx(line, ",", lastcomma - 1)
8723< The search is done case-sensitive.
Bram Moolenaar8f999f12005-01-25 22:12:55 +00008724 For pattern searches use |match()|.
8725 -1 is returned if the {needle} does not occur in {haystack}.
Bram Moolenaard4755bb2004-09-02 19:12:26 +00008726 If the {needle} is empty the length of {haystack} is returned.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00008727 See also |stridx()|. Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008728 :echo strridx("an angry armadillo", "an") 3
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008729< *strrchr()*
Bram Moolenaar05159a02005-02-26 23:04:13 +00008730 When used with a single character it works similar to the C
8731 function strrchr().
8732
Bram Moolenaar071d4272004-06-13 20:20:40 +00008733strtrans({expr}) *strtrans()*
8734 The result is a String, which is {expr} with all unprintable
8735 characters translated into printable characters |'isprint'|.
8736 Like they are shown in a window. Example: >
8737 echo strtrans(@a)
8738< This displays a newline in register a as "^@" instead of
8739 starting a new line.
8740
Bram Moolenaar72597a52010-07-18 15:31:08 +02008741strwidth({expr}) *strwidth()*
8742 The result is a Number, which is the number of display cells
8743 String {expr} occupies. A Tab character is counted as one
Bram Moolenaardc536092010-07-18 15:45:49 +02008744 cell, alternatively use |strdisplaywidth()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02008745 When {expr} contains characters with East Asian Width Class
8746 Ambiguous, this function's return value depends on 'ambiwidth'.
Bram Moolenaardc536092010-07-18 15:45:49 +02008747 Also see |strlen()|, |strdisplaywidth()| and |strchars()|.
Bram Moolenaar72597a52010-07-18 15:31:08 +02008748
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008749submatch({nr} [, {list}]) *submatch()* *E935*
Bram Moolenaar251e1912011-06-19 05:09:16 +02008750 Only for an expression in a |:substitute| command or
8751 substitute() function.
8752 Returns the {nr}'th submatch of the matched text. When {nr}
8753 is 0 the whole matched text is returned.
Bram Moolenaar41571762014-04-02 19:00:58 +02008754 Note that a NL in the string can stand for a line break of a
8755 multi-line match or a NUL character in the text.
Bram Moolenaar251e1912011-06-19 05:09:16 +02008756 Also see |sub-replace-expression|.
Bram Moolenaar41571762014-04-02 19:00:58 +02008757
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008758 If {list} is present and non-zero then submatch() returns
8759 a list of strings, similar to |getline()| with two arguments.
Bram Moolenaar41571762014-04-02 19:00:58 +02008760 NL characters in the text represent NUL characters in the
8761 text.
8762 Only returns more than one item for |:substitute|, inside
8763 |substitute()| this list will always contain one or zero
8764 items, since there are no real line breaks.
8765
Bram Moolenaar6100d022016-10-02 16:51:57 +02008766 When substitute() is used recursively only the submatches in
8767 the current (deepest) call can be obtained.
8768
Bram Moolenaar2f058492017-11-30 20:27:52 +01008769 Examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008770 :s/\d\+/\=submatch(0) + 1/
Bram Moolenaar2f058492017-11-30 20:27:52 +01008771 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '')
Bram Moolenaar071d4272004-06-13 20:20:40 +00008772< This finds the first number in the line and adds one to it.
8773 A line break is included as a newline character.
8774
8775substitute({expr}, {pat}, {sub}, {flags}) *substitute()*
8776 The result is a String, which is a copy of {expr}, in which
Bram Moolenaar251e1912011-06-19 05:09:16 +02008777 the first match of {pat} is replaced with {sub}.
8778 When {flags} is "g", all matches of {pat} in {expr} are
8779 replaced. Otherwise {flags} should be "".
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008780
Bram Moolenaar251e1912011-06-19 05:09:16 +02008781 This works like the ":substitute" command (without any flags).
8782 But the matching with {pat} is always done like the 'magic'
8783 option is set and 'cpoptions' is empty (to make scripts
Bram Moolenaar2df58b42012-11-28 18:21:11 +01008784 portable). 'ignorecase' is still relevant, use |/\c| or |/\C|
8785 if you want to ignore or match case and ignore 'ignorecase'.
8786 'smartcase' is not used. See |string-match| for how {pat} is
8787 used.
Bram Moolenaar251e1912011-06-19 05:09:16 +02008788
8789 A "~" in {sub} is not replaced with the previous {sub}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008790 Note that some codes in {sub} have a special meaning
Bram Moolenaar58b85342016-08-14 19:54:54 +02008791 |sub-replace-special|. For example, to replace something with
Bram Moolenaar071d4272004-06-13 20:20:40 +00008792 "\n" (two characters), use "\\\\n" or '\\n'.
Bram Moolenaar251e1912011-06-19 05:09:16 +02008793
Bram Moolenaar071d4272004-06-13 20:20:40 +00008794 When {pat} does not match in {expr}, {expr} is returned
8795 unmodified.
Bram Moolenaar251e1912011-06-19 05:09:16 +02008796
Bram Moolenaar071d4272004-06-13 20:20:40 +00008797 Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02008798 :let &path = substitute(&path, ",\\=[^,]*$", "", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008799< This removes the last component of the 'path' option. >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02008800 :echo substitute("testing", ".*", "\\U\\0", "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008801< results in "TESTING".
Bram Moolenaar251e1912011-06-19 05:09:16 +02008802
8803 When {sub} starts with "\=", the remainder is interpreted as
8804 an expression. See |sub-replace-expression|. Example: >
Bram Moolenaardf48fb42016-07-22 21:50:18 +02008805 :echo substitute(s, '%\(\x\x\)',
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02008806 \ '\=nr2char("0x" . submatch(1))', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00008807
Bram Moolenaardf48fb42016-07-22 21:50:18 +02008808< When {sub} is a Funcref that function is called, with one
8809 optional argument. Example: >
8810 :echo substitute(s, '%\(\x\x\)', SubNr, 'g')
8811< The optional argument is a list which contains the whole
Bram Moolenaar58b85342016-08-14 19:54:54 +02008812 matched string and up to nine submatches, like what
8813 |submatch()| returns. Example: >
8814 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g')
Bram Moolenaardf48fb42016-07-22 21:50:18 +02008815
Bram Moolenaar20aac6c2018-09-02 21:07:30 +02008816swapinfo({fname}) *swapinfo()*
Bram Moolenaar00f123a2018-08-21 20:28:54 +02008817 The result is a dictionary, which holds information about the
8818 swapfile {fname}. The available fields are:
Bram Moolenaar95bafa22018-10-02 13:26:25 +02008819 version Vim version
Bram Moolenaar00f123a2018-08-21 20:28:54 +02008820 user user name
8821 host host name
8822 fname original file name
Bram Moolenaar95bafa22018-10-02 13:26:25 +02008823 pid PID of the Vim process that created the swap
Bram Moolenaar00f123a2018-08-21 20:28:54 +02008824 file
8825 mtime last modification time in seconds
8826 inode Optional: INODE number of the file
Bram Moolenaar47ad5652018-08-21 21:09:07 +02008827 dirty 1 if file was modified, 0 if not
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02008828 Note that "user" and "host" are truncated to at most 39 bytes.
Bram Moolenaar00f123a2018-08-21 20:28:54 +02008829 In case of failure an "error" item is added with the reason:
8830 Cannot open file: file not found or in accessible
8831 Cannot read file: cannot read first block
Bram Moolenaar47ad5652018-08-21 21:09:07 +02008832 Not a swap file: does not contain correct block ID
8833 Magic number mismatch: Info in first block is invalid
Bram Moolenaar00f123a2018-08-21 20:28:54 +02008834
Bram Moolenaar110bd602018-09-16 18:46:59 +02008835swapname({expr}) *swapname()*
8836 The result is the swap file path of the buffer {expr}.
8837 For the use of {expr}, see |bufname()| above.
8838 If buffer {expr} is the current buffer, the result is equal to
8839 |:swapname| (unless no swap file).
8840 If buffer {expr} has no swap file, returns an empty string.
8841
Bram Moolenaar47136d72004-10-12 20:02:24 +00008842synID({lnum}, {col}, {trans}) *synID()*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008843 The result is a Number, which is the syntax ID at the position
Bram Moolenaar47136d72004-10-12 20:02:24 +00008844 {lnum} and {col} in the current window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008845 The syntax ID can be used with |synIDattr()| and
8846 |synIDtrans()| to obtain syntax information about text.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00008847
Bram Moolenaar47136d72004-10-12 20:02:24 +00008848 {col} is 1 for the leftmost column, {lnum} is 1 for the first
Bram Moolenaarce0842a2005-07-18 21:58:11 +00008849 line. 'synmaxcol' applies, in a longer line zero is returned.
Bram Moolenaarca635012015-09-25 20:34:21 +02008850 Note that when the position is after the last character,
8851 that's where the cursor can be in Insert mode, synID() returns
8852 zero.
Bram Moolenaarce0842a2005-07-18 21:58:11 +00008853
Bram Moolenaar79815f12016-07-09 17:07:29 +02008854 When {trans} is |TRUE|, transparent items are reduced to the
Bram Moolenaar58b85342016-08-14 19:54:54 +02008855 item that they reveal. This is useful when wanting to know
Bram Moolenaar79815f12016-07-09 17:07:29 +02008856 the effective color. When {trans} is |FALSE|, the transparent
Bram Moolenaar071d4272004-06-13 20:20:40 +00008857 item is returned. This is useful when wanting to know which
8858 syntax item is effective (e.g. inside parens).
8859 Warning: This function can be very slow. Best speed is
8860 obtained by going through the file in forward direction.
8861
8862 Example (echoes the name of the syntax item under the cursor): >
8863 :echo synIDattr(synID(line("."), col("."), 1), "name")
8864<
Bram Moolenaar7510fe72010-07-25 12:46:44 +02008865
Bram Moolenaar071d4272004-06-13 20:20:40 +00008866synIDattr({synID}, {what} [, {mode}]) *synIDattr()*
8867 The result is a String, which is the {what} attribute of
8868 syntax ID {synID}. This can be used to obtain information
8869 about a syntax item.
8870 {mode} can be "gui", "cterm" or "term", to get the attributes
Bram Moolenaar58b85342016-08-14 19:54:54 +02008871 for that mode. When {mode} is omitted, or an invalid value is
Bram Moolenaar071d4272004-06-13 20:20:40 +00008872 used, the attributes for the currently active highlighting are
8873 used (GUI, cterm or term).
8874 Use synIDtrans() to follow linked highlight groups.
8875 {what} result
8876 "name" the name of the syntax item
8877 "fg" foreground color (GUI: color name used to set
8878 the color, cterm: color number as a string,
8879 term: empty string)
Bram Moolenaar6f507d62008-11-28 10:16:05 +00008880 "bg" background color (as with "fg")
Bram Moolenaar12682fd2010-03-10 13:43:49 +01008881 "font" font name (only available in the GUI)
8882 |highlight-font|
Bram Moolenaar6f507d62008-11-28 10:16:05 +00008883 "sp" special color (as with "fg") |highlight-guisp|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008884 "fg#" like "fg", but for the GUI and the GUI is
8885 running the name in "#RRGGBB" form
8886 "bg#" like "fg#" for "bg"
Bram Moolenaar6f507d62008-11-28 10:16:05 +00008887 "sp#" like "fg#" for "sp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008888 "bold" "1" if bold
8889 "italic" "1" if italic
8890 "reverse" "1" if reverse
8891 "inverse" "1" if inverse (= reverse)
Bram Moolenaar12682fd2010-03-10 13:43:49 +01008892 "standout" "1" if standout
Bram Moolenaar071d4272004-06-13 20:20:40 +00008893 "underline" "1" if underlined
Bram Moolenaare2cc9702005-03-15 22:43:58 +00008894 "undercurl" "1" if undercurled
Bram Moolenaarcf4b00c2017-09-02 18:33:56 +02008895 "strike" "1" if strikethrough
Bram Moolenaar071d4272004-06-13 20:20:40 +00008896
8897 Example (echoes the color of the syntax item under the
8898 cursor): >
8899 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg")
8900<
8901synIDtrans({synID}) *synIDtrans()*
8902 The result is a Number, which is the translated syntax ID of
8903 {synID}. This is the syntax group ID of what is being used to
8904 highlight the character. Highlight links given with
8905 ":highlight link" are followed.
8906
Bram Moolenaar483c5d82010-10-20 18:45:33 +02008907synconcealed({lnum}, {col}) *synconcealed()*
Bram Moolenaar4d785892017-06-22 22:00:50 +02008908 The result is a List with currently three items:
8909 1. The first item in the list is 0 if the character at the
8910 position {lnum} and {col} is not part of a concealable
8911 region, 1 if it is.
8912 2. The second item in the list is a string. If the first item
8913 is 1, the second item contains the text which will be
8914 displayed in place of the concealed text, depending on the
8915 current setting of 'conceallevel' and 'listchars'.
Bram Moolenaarcc0750d2017-06-24 22:29:24 +02008916 3. The third and final item in the list is a number
8917 representing the specific syntax region matched in the
8918 line. When the character is not concealed the value is
8919 zero. This allows detection of the beginning of a new
8920 concealable region if there are two consecutive regions
8921 with the same replacement character. For an example, if
8922 the text is "123456" and both "23" and "45" are concealed
Bram Moolenaar95bafa22018-10-02 13:26:25 +02008923 and replaced by the character "X", then:
Bram Moolenaarcc0750d2017-06-24 22:29:24 +02008924 call returns ~
Bram Moolenaarc572da52017-08-27 16:52:01 +02008925 synconcealed(lnum, 1) [0, '', 0]
8926 synconcealed(lnum, 2) [1, 'X', 1]
8927 synconcealed(lnum, 3) [1, 'X', 1]
8928 synconcealed(lnum, 4) [1, 'X', 2]
8929 synconcealed(lnum, 5) [1, 'X', 2]
8930 synconcealed(lnum, 6) [0, '', 0]
Bram Moolenaar483c5d82010-10-20 18:45:33 +02008931
8932
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00008933synstack({lnum}, {col}) *synstack()*
8934 Return a |List|, which is the stack of syntax items at the
8935 position {lnum} and {col} in the current window. Each item in
8936 the List is an ID like what |synID()| returns.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00008937 The first item in the List is the outer region, following are
8938 items contained in that one. The last one is what |synID()|
8939 returns, unless not the whole item is highlighted or it is a
8940 transparent item.
8941 This function is useful for debugging a syntax file.
8942 Example that shows the syntax stack under the cursor: >
8943 for id in synstack(line("."), col("."))
8944 echo synIDattr(id, "name")
8945 endfor
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02008946< When the position specified with {lnum} and {col} is invalid
8947 nothing is returned. The position just after the last
8948 character in a line and the first column in an empty line are
8949 valid positions.
Bram Moolenaar9d188ab2008-01-10 21:24:39 +00008950
Bram Moolenaarc0197e22004-09-13 20:26:32 +00008951system({expr} [, {input}]) *system()* *E677*
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02008952 Get the output of the shell command {expr} as a string. See
8953 |systemlist()| to get the output as a List.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02008954
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008955 When {input} is given and is a string this string is written
8956 to a file and passed as stdin to the command. The string is
8957 written as-is, you need to take care of using the correct line
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02008958 separators yourself.
8959 If {input} is given and is a |List| it is written to the file
8960 in a way |writefile()| does with {binary} set to "b" (i.e.
8961 with a newline between each list item with newlines inside
Bram Moolenaar12c44922017-01-08 13:26:03 +01008962 list items converted to NULs).
8963 When {input} is given and is a number that is a valid id for
8964 an existing buffer then the content of the buffer is written
8965 to the file line by line, each line terminated by a NL and
8966 NULs characters where the text has a NL.
Bram Moolenaar069c1e72016-07-15 21:25:08 +02008967
8968 Pipes are not used, the 'shelltemp' option is not used.
Bram Moolenaar57ebe6e2014-04-05 18:55:46 +02008969
Bram Moolenaar04186092016-08-29 21:55:35 +02008970 When prepended by |:silent| the terminal will not be set to
Bram Moolenaar52a72462014-08-29 15:53:52 +02008971 cooked mode. This is meant to be used for commands that do
8972 not need the user to type. It avoids stray characters showing
8973 up on the screen which require |CTRL-L| to remove. >
8974 :silent let f = system('ls *.vim')
8975<
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01008976 Note: Use |shellescape()| or |::S| with |expand()| or
8977 |fnamemodify()| to escape special characters in a command
8978 argument. Newlines in {expr} may cause the command to fail.
8979 The characters in 'shellquote' and 'shellxquote' may also
Bram Moolenaar26df0922014-02-23 23:39:13 +01008980 cause trouble.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008981 This is not to be used for interactive commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008982
Bram Moolenaar05bb9532008-07-04 09:44:11 +00008983 The result is a String. Example: >
8984 :let files = system("ls " . shellescape(expand('%:h')))
Bram Moolenaar26df0922014-02-23 23:39:13 +01008985 :let files = system('ls ' . expand('%:h:S'))
Bram Moolenaar071d4272004-06-13 20:20:40 +00008986
8987< To make the result more system-independent, the shell output
8988 is filtered to replace <CR> with <NL> for Macintosh, and
8989 <CR><NL> with <NL> for DOS-like systems.
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02008990 To avoid the string being truncated at a NUL, all NUL
8991 characters are replaced with SOH (0x01).
8992
Bram Moolenaar071d4272004-06-13 20:20:40 +00008993 The command executed is constructed using several options:
8994 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote'
8995 ({tmp} is an automatically generated file name).
8996 For Unix and OS/2 braces are put around {expr} to allow for
8997 concatenated commands.
8998
Bram Moolenaar433f7c82006-03-21 21:29:36 +00008999 The command will be executed in "cooked" mode, so that a
9000 CTRL-C will interrupt the command (on Unix at least).
9001
Bram Moolenaar071d4272004-06-13 20:20:40 +00009002 The resulting error code can be found in |v:shell_error|.
9003 This function will fail in |restricted-mode|.
Bram Moolenaar4770d092006-01-12 23:22:24 +00009004
9005 Note that any wrong value in the options mentioned above may
9006 make the function fail. It has also been reported to fail
9007 when using a security agent application.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009008 Unlike ":!cmd" there is no automatic check for changed files.
9009 Use |:checktime| to force a check.
9010
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009011
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009012systemlist({expr} [, {input}]) *systemlist()*
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009013 Same as |system()|, but returns a |List| with lines (parts of
9014 output separated by NL) with NULs transformed into NLs. Output
9015 is the same as |readfile()| will output with {binary} argument
Bram Moolenaar68563932017-01-10 13:31:15 +01009016 set to "b". Note that on MS-Windows you may get trailing CR
9017 characters.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009018
Bram Moolenaar975b5272016-03-15 23:10:59 +01009019 Returns an empty string on error.
Bram Moolenaar39c29ed2014-04-05 19:44:40 +02009020
9021
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009022tabpagebuflist([{arg}]) *tabpagebuflist()*
Bram Moolenaar32466aa2006-02-24 23:53:04 +00009023 The result is a |List|, where each item is the number of the
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009024 buffer associated with each window in the current tab page.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009025 {arg} specifies the number of the tab page to be used. When
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009026 omitted the current tab page is used.
9027 When {arg} is invalid the number zero is returned.
9028 To get a list of all buffers in all tabs use this: >
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02009029 let buflist = []
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009030 for i in range(tabpagenr('$'))
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02009031 call extend(buflist, tabpagebuflist(i + 1))
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009032 endfor
9033< Note that a buffer may appear in more than one window.
9034
9035
9036tabpagenr([{arg}]) *tabpagenr()*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00009037 The result is a Number, which is the number of the current
9038 tab page. The first tab page has number 1.
9039 When the optional argument is "$", the number of the last tab
9040 page is returned (the tab page count).
9041 The number can be used with the |:tab| command.
9042
9043
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01009044tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()*
Bram Moolenaard04f4402010-08-15 13:30:34 +02009045 Like |winnr()| but for tab page {tabarg}.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00009046 {tabarg} specifies the number of tab page to be used.
9047 {arg} is used like with |winnr()|:
9048 - When omitted the current window number is returned. This is
9049 the window which will be used when going to this tab page.
9050 - When "$" the number of windows is returned.
9051 - When "#" the previous window nr is returned.
9052 Useful examples: >
9053 tabpagewinnr(1) " current window of tab page 1
9054 tabpagewinnr(4, '$') " number of windows in tab page 4
9055< When {tabarg} is invalid zero is returned.
9056
Bram Moolenaarfa1d1402006-03-25 21:59:56 +00009057 *tagfiles()*
9058tagfiles() Returns a |List| with the file names used to search for tags
9059 for the current buffer. This is the 'tags' option expanded.
9060
9061
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009062taglist({expr} [, {filename}]) *taglist()*
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009063 Returns a list of tags matching the regular expression {expr}.
Bram Moolenaarc6aafba2017-03-21 17:09:10 +01009064
9065 If {filename} is passed it is used to prioritize the results
9066 in the same way that |:tselect| does. See |tag-priority|.
9067 {filename} should be the full path of the file.
9068
Bram Moolenaard8c00872005-07-22 21:52:15 +00009069 Each list item is a dictionary with at least the following
9070 entries:
Bram Moolenaar280f1262006-01-30 00:14:18 +00009071 name Name of the tag.
9072 filename Name of the file where the tag is
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009073 defined. It is either relative to the
9074 current directory or a full path.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009075 cmd Ex command used to locate the tag in
9076 the file.
Bram Moolenaar280f1262006-01-30 00:14:18 +00009077 kind Type of the tag. The value for this
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009078 entry depends on the language specific
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009079 kind values. Only available when
9080 using a tags file generated by
9081 Exuberant ctags or hdrtag.
Bram Moolenaar280f1262006-01-30 00:14:18 +00009082 static A file specific tag. Refer to
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009083 |static-tag| for more information.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009084 More entries may be present, depending on the content of the
9085 tags file: access, implementation, inherits and signature.
9086 Refer to the ctags documentation for information about these
9087 fields. For C code the fields "struct", "class" and "enum"
9088 may appear, they give the name of the entity the tag is
9089 contained in.
Bram Moolenaar5a8684e2005-07-30 22:43:24 +00009090
Bram Moolenaar214641f2017-03-05 17:04:09 +01009091 The ex-command "cmd" can be either an ex search pattern, a
Bram Moolenaar4317d9b2005-03-18 20:25:31 +00009092 line number or a line number followed by a byte number.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009093
9094 If there are no matching tags, then an empty list is returned.
9095
9096 To get an exact tag match, the anchors '^' and '$' should be
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01009097 used in {expr}. This also make the function work faster.
9098 Refer to |tag-regexp| for more information about the tag
9099 search regular expression pattern.
Bram Moolenaare2cc9702005-03-15 22:43:58 +00009100
9101 Refer to |'tags'| for information about how the tags file is
9102 located by Vim. Refer to |tags-file-format| for the format of
9103 the tags file generated by the different ctags tools.
9104
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009105tan({expr}) *tan()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009106 Return the tangent of {expr}, measured in radians, as a |Float|
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009107 in the range [-inf, inf].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009108 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009109 Examples: >
9110 :echo tan(10)
9111< 0.648361 >
9112 :echo tan(-4.01)
9113< -1.181502
Bram Moolenaardb84e452010-08-15 13:50:43 +02009114 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009115
9116
9117tanh({expr}) *tanh()*
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009118 Return the hyperbolic tangent of {expr} as a |Float| in the
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009119 range [-1, 1].
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02009120 {expr} must evaluate to a |Float| or a |Number|.
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009121 Examples: >
9122 :echo tanh(0.5)
9123< 0.462117 >
9124 :echo tanh(-1)
9125< -0.761594
Bram Moolenaardb84e452010-08-15 13:50:43 +02009126 {only available when compiled with the |+float| feature}
Bram Moolenaardb7c6862010-05-21 16:33:48 +02009127
9128
Bram Moolenaar574860b2016-05-24 17:33:34 +02009129tempname() *tempname()* *temp-file-name*
9130 The result is a String, which is the name of a file that
Bram Moolenaar58b85342016-08-14 19:54:54 +02009131 doesn't exist. It can be used for a temporary file. The name
Bram Moolenaar574860b2016-05-24 17:33:34 +02009132 is different for at least 26 consecutive calls. Example: >
9133 :let tmpfile = tempname()
9134 :exe "redir > " . tmpfile
9135< For Unix, the file will be in a private directory |tempfile|.
9136 For MS-Windows forward slashes are used when the 'shellslash'
9137 option is set or when 'shellcmdflag' starts with '-'.
9138
Bram Moolenaard96ff162018-02-18 22:13:29 +01009139 *term_dumpdiff()*
9140term_dumpdiff({filename}, {filename} [, {options}])
9141 Open a new window displaying the difference between the two
9142 files. The files must have been created with
9143 |term_dumpwrite()|.
9144 Returns the buffer number or zero when the diff fails.
9145 Also see |terminal-diff|.
9146 NOTE: this does not work with double-width characters yet.
9147
9148 The top part of the buffer contains the contents of the first
9149 file, the bottom part of the buffer contains the contents of
9150 the second file. The middle part shows the differences.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009151 The parts are separated by a line of equals.
Bram Moolenaard96ff162018-02-18 22:13:29 +01009152
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009153 If the {options} argument is present, it must be a Dict with
9154 these possible members:
9155 "term_name" name to use for the buffer name, instead
9156 of the first file name.
9157 "term_rows" vertical size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009158 instead of using 'termwinsize'
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009159 "term_cols" horizontal size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009160 instead of using 'termwinsize'
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009161 "vertical" split the window vertically
9162 "curwin" use the current window, do not split the
9163 window; fails if the current buffer
9164 cannot be |abandon|ed
9165 "norestore" do not add the terminal window to a
9166 session file
Bram Moolenaard96ff162018-02-18 22:13:29 +01009167
9168 Each character in the middle part indicates a difference. If
9169 there are multiple differences only the first in this list is
9170 used:
9171 X different character
9172 w different width
9173 f different foreground color
9174 b different background color
9175 a different attribute
9176 + missing position in first file
9177 - missing position in second file
9178
9179 Using the "s" key the top and bottom parts are swapped. This
9180 makes it easy to spot a difference.
9181
9182 *term_dumpload()*
9183term_dumpload({filename} [, {options}])
9184 Open a new window displaying the contents of {filename}
9185 The file must have been created with |term_dumpwrite()|.
9186 Returns the buffer number or zero when it fails.
9187 Also see |terminal-diff|.
9188
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +01009189 For {options} see |term_dumpdiff()|.
Bram Moolenaard96ff162018-02-18 22:13:29 +01009190
9191 *term_dumpwrite()*
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01009192term_dumpwrite({buf}, {filename} [, {options}])
Bram Moolenaard96ff162018-02-18 22:13:29 +01009193 Dump the contents of the terminal screen of {buf} in the file
9194 {filename}. This uses a format that can be used with
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01009195 |term_dumpload()| and |term_dumpdiff()|.
Bram Moolenaar93a1df22018-09-10 11:51:50 +02009196 If the job in the terminal already finished an error is given:
9197 *E958*
9198 If {filename} already exists an error is given: *E953*
Bram Moolenaard96ff162018-02-18 22:13:29 +01009199 Also see |terminal-diff|.
9200
Bram Moolenaar6bb2cdf2018-02-24 19:53:53 +01009201 {options} is a dictionary with these optional entries:
9202 "rows" maximum number of rows to dump
9203 "columns" maximum number of columns to dump
9204
Bram Moolenaare41e3b42017-08-11 16:24:50 +02009205term_getaltscreen({buf}) *term_getaltscreen()*
9206 Returns 1 if the terminal of {buf} is using the alternate
9207 screen.
9208 {buf} is used as with |term_getsize()|.
9209 {only available when compiled with the |+terminal| feature}
9210
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009211term_getansicolors({buf}) *term_getansicolors()*
9212 Get the ANSI color palette in use by terminal {buf}.
9213 Returns a List of length 16 where each element is a String
9214 representing a color in hexadecimal "#rrggbb" format.
9215 Also see |term_setansicolors()| and |g:terminal_ansi_colors|.
9216 If neither was used returns the default colors.
9217
9218 {buf} is used as with |term_getsize()|. If the buffer does not
9219 exist or is not a terminal window, an empty list is returned.
9220 {only available when compiled with the |+terminal| feature and
9221 with GUI enabled and/or the |+termguicolors| feature}
9222
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009223term_getattr({attr}, {what}) *term_getattr()*
9224 Given {attr}, a value returned by term_scrape() in the "attr"
9225 item, return whether {what} is on. {what} can be one of:
9226 bold
9227 italic
9228 underline
9229 strike
9230 reverse
Bram Moolenaar45356542017-08-06 17:53:31 +02009231 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02009232
Bram Moolenaar97870002017-07-30 18:28:38 +02009233term_getcursor({buf}) *term_getcursor()*
Bram Moolenaar45356542017-08-06 17:53:31 +02009234 Get the cursor position of terminal {buf}. Returns a list with
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009235 two numbers and a dictionary: [row, col, dict].
Bram Moolenaar45356542017-08-06 17:53:31 +02009236
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009237 "row" and "col" are one based, the first screen cell is row
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009238 1, column 1. This is the cursor position of the terminal
9239 itself, not of the Vim window.
9240
9241 "dict" can have these members:
9242 "visible" one when the cursor is visible, zero when it
9243 is hidden.
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009244 "blink" one when the cursor is blinking, zero when it
9245 is not blinking.
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009246 "shape" 1 for a block cursor, 2 for underline and 3
9247 for a vertical bar.
Bram Moolenaar97870002017-07-30 18:28:38 +02009248
9249 {buf} must be the buffer number of a terminal window. If the
9250 buffer does not exist or is not a terminal window, an empty
9251 list is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009252 {only available when compiled with the |+terminal| feature}
Bram Moolenaar97870002017-07-30 18:28:38 +02009253
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009254term_getjob({buf}) *term_getjob()*
9255 Get the Job associated with terminal window {buf}.
9256 {buf} is used as with |term_getsize()|.
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009257 Returns |v:null| when there is no job.
Bram Moolenaar45356542017-08-06 17:53:31 +02009258 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02009259
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02009260term_getline({buf}, {row}) *term_getline()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009261 Get a line of text from the terminal window of {buf}.
9262 {buf} is used as with |term_getsize()|.
Bram Moolenaar74675a62017-07-15 13:53:23 +02009263
Bram Moolenaar45356542017-08-06 17:53:31 +02009264 The first line has {row} one. When {row} is "." the cursor
9265 line is used. When {row} is invalid an empty string is
9266 returned.
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +01009267
9268 To get attributes of each character use |term_scrape()|.
Bram Moolenaar45356542017-08-06 17:53:31 +02009269 {only available when compiled with the |+terminal| feature}
Bram Moolenaar74675a62017-07-15 13:53:23 +02009270
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02009271term_getscrolled({buf}) *term_getscrolled()*
9272 Return the number of lines that scrolled to above the top of
9273 terminal {buf}. This is the offset between the row number
9274 used for |term_getline()| and |getline()|, so that: >
9275 term_getline(buf, N)
9276< is equal to: >
Bram Moolenaar95bafa22018-10-02 13:26:25 +02009277 getline(N + term_getscrolled(buf))
Bram Moolenaar82b9ca02017-08-08 23:06:46 +02009278< (if that line exists).
9279
9280 {buf} is used as with |term_getsize()|.
9281 {only available when compiled with the |+terminal| feature}
9282
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009283term_getsize({buf}) *term_getsize()*
9284 Get the size of terminal {buf}. Returns a list with two
9285 numbers: [rows, cols]. This is the size of the terminal, not
9286 the window containing the terminal.
Bram Moolenaar74675a62017-07-15 13:53:23 +02009287
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009288 {buf} must be the buffer number of a terminal window. Use an
9289 empty string for the current buffer. If the buffer does not
9290 exist or is not a terminal window, an empty list is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009291 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009292
Bram Moolenaarb000e322017-07-30 19:38:21 +02009293term_getstatus({buf}) *term_getstatus()*
9294 Get the status of terminal {buf}. This returns a comma
9295 separated list of these items:
9296 running job is running
9297 finished job has finished
Bram Moolenaar45356542017-08-06 17:53:31 +02009298 normal in Terminal-Normal mode
Bram Moolenaarb000e322017-07-30 19:38:21 +02009299 One of "running" or "finished" is always present.
9300
9301 {buf} must be the buffer number of a terminal window. If the
9302 buffer does not exist or is not a terminal window, an empty
9303 string is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009304 {only available when compiled with the |+terminal| feature}
Bram Moolenaarb000e322017-07-30 19:38:21 +02009305
9306term_gettitle({buf}) *term_gettitle()*
9307 Get the title of terminal {buf}. This is the title that the
9308 job in the terminal has set.
9309
9310 {buf} must be the buffer number of a terminal window. If the
9311 buffer does not exist or is not a terminal window, an empty
9312 string is returned.
Bram Moolenaar45356542017-08-06 17:53:31 +02009313 {only available when compiled with the |+terminal| feature}
Bram Moolenaarb000e322017-07-30 19:38:21 +02009314
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02009315term_gettty({buf} [, {input}]) *term_gettty()*
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009316 Get the name of the controlling terminal associated with
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02009317 terminal window {buf}. {buf} is used as with |term_getsize()|.
9318
9319 When {input} is omitted or 0, return the name for writing
9320 (stdout). When {input} is 1 return the name for reading
9321 (stdin). On UNIX, both return same name.
Bram Moolenaar45356542017-08-06 17:53:31 +02009322 {only available when compiled with the |+terminal| feature}
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009323
Bram Moolenaar22aad2f2017-07-30 18:19:46 +02009324term_list() *term_list()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009325 Return a list with the buffer numbers of all buffers for
9326 terminal windows.
Bram Moolenaar45356542017-08-06 17:53:31 +02009327 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009328
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +02009329term_scrape({buf}, {row}) *term_scrape()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009330 Get the contents of {row} of terminal screen of {buf}.
9331 For {buf} see |term_getsize()|.
9332
Bram Moolenaar45356542017-08-06 17:53:31 +02009333 The first line has {row} one. When {row} is "." the cursor
9334 line is used. When {row} is invalid an empty string is
9335 returned.
Bram Moolenaar22aad2f2017-07-30 18:19:46 +02009336
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009337 Return a List containing a Dict for each screen cell:
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009338 "chars" character(s) at the cell
9339 "fg" foreground color as #rrggbb
9340 "bg" background color as #rrggbb
Bram Moolenaar7c9aec42017-08-03 13:51:25 +02009341 "attr" attributes of the cell, use |term_getattr()|
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009342 to get the individual flags
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009343 "width" cell width: 1 or 2
Bram Moolenaar45356542017-08-06 17:53:31 +02009344 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009345
9346term_sendkeys({buf}, {keys}) *term_sendkeys()*
9347 Send keystrokes {keys} to terminal {buf}.
9348 {buf} is used as with |term_getsize()|.
9349
9350 {keys} are translated as key sequences. For example, "\<c-x>"
9351 means the character CTRL-X.
Bram Moolenaar45356542017-08-06 17:53:31 +02009352 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009353
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009354term_setansicolors({buf}, {colors}) *term_setansicolors()*
9355 Set the ANSI color palette used by terminal {buf}.
9356 {colors} must be a List of 16 valid color names or hexadecimal
9357 color codes, like those accepted by |highlight-guifg|.
9358 Also see |term_getansicolors()| and |g:terminal_ansi_colors|.
9359
Bram Moolenaara42d3632018-04-14 17:05:38 +02009360 The colors normally are:
9361 0 black
9362 1 dark red
9363 2 dark green
9364 3 brown
9365 4 dark blue
9366 5 dark magenta
9367 6 dark cyan
9368 7 light grey
9369 8 dark grey
9370 9 red
9371 10 green
9372 11 yellow
9373 12 blue
9374 13 magenta
9375 14 cyan
9376 15 white
9377
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009378 These colors are used in the GUI and in the terminal when
9379 'termguicolors' is set. When not using GUI colors (GUI mode
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009380 or 'termguicolors'), the terminal window always uses the 16
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009381 ANSI colors of the underlying terminal.
9382 {only available when compiled with the |+terminal| feature and
9383 with GUI enabled and/or the |+termguicolors| feature}
9384
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +01009385term_setkill({buf}, {how}) *term_setkill()*
9386 When exiting Vim or trying to close the terminal window in
9387 another way, {how} defines whether the job in the terminal can
9388 be stopped.
9389 When {how} is empty (the default), the job will not be
9390 stopped, trying to exit will result in |E947|.
9391 Otherwise, {how} specifies what signal to send to the job.
9392 See |job_stop()| for the values.
9393
9394 After sending the signal Vim will wait for up to a second to
9395 check that the job actually stopped.
9396
Bram Moolenaarb5b75622018-03-09 22:22:21 +01009397term_setrestore({buf}, {command}) *term_setrestore()*
9398 Set the command to write in a session file to restore the job
9399 in this terminal. The line written in the session file is: >
9400 terminal ++curwin ++cols=%d ++rows=%d {command}
9401< Make sure to escape the command properly.
9402
9403 Use an empty {command} to run 'shell'.
9404 Use "NONE" to not restore this window.
9405 {only available when compiled with the |+terminal| feature}
9406
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009407term_setsize({buf}, {rows}, {cols}) *term_setsize()* *E955*
Bram Moolenaara42d3632018-04-14 17:05:38 +02009408 Set the size of terminal {buf}. The size of the window
9409 containing the terminal will also be adjusted, if possible.
9410 If {rows} or {cols} is zero or negative, that dimension is not
9411 changed.
9412
9413 {buf} must be the buffer number of a terminal window. Use an
9414 empty string for the current buffer. If the buffer does not
9415 exist or is not a terminal window, an error is given.
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009416 {only available when compiled with the |+terminal| feature}
9417
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009418term_start({cmd}, {options}) *term_start()*
9419 Open a terminal window and run {cmd} in it.
9420
Bram Moolenaar01164a62017-11-02 22:58:42 +01009421 {cmd} can be a string or a List, like with |job_start()|. The
9422 string "NONE" can be used to open a terminal window without
9423 starting a job, the pty of the terminal can be used by a
9424 command like gdb.
9425
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009426 Returns the buffer number of the terminal window. If {cmd}
9427 cannot be executed the window does open and shows an error
9428 message.
9429 If opening the window fails zero is returned.
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009430
Bram Moolenaar78712a72017-08-05 14:50:12 +02009431 {options} are similar to what is used for |job_start()|, see
9432 |job-options|. However, not all options can be used. These
9433 are supported:
9434 all timeout options
Bram Moolenaard473c8c2018-08-11 18:00:22 +02009435 "stoponexit", "cwd", "env"
9436 "callback", "out_cb", "err_cb", "exit_cb", "close_cb"
Bram Moolenaar78712a72017-08-05 14:50:12 +02009437 "in_io", "in_top", "in_bot", "in_name", "in_buf"
9438 "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
9439 "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
9440 However, at least one of stdin, stdout or stderr must be
9441 connected to the terminal. When I/O is connected to the
9442 terminal then the callback function for that part is not used.
9443
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009444 There are extra options:
Bram Moolenaardd693ce2017-08-10 23:15:19 +02009445 "term_name" name to use for the buffer name, instead
9446 of the command name.
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009447 "term_rows" vertical size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009448 instead of using 'termwinsize'
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009449 "term_cols" horizontal size to use for the terminal,
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02009450 instead of using 'termwinsize'
Bram Moolenaar0e5979a2018-06-17 19:36:33 +02009451 "vertical" split the window vertically; note that
9452 other window position can be defined with
9453 command modifiers, such as |:belowright|.
Bram Moolenaarda43b612017-08-11 22:27:50 +02009454 "curwin" use the current window, do not split the
9455 window; fails if the current buffer
9456 cannot be |abandon|ed
Bram Moolenaarb4d5fba2017-09-11 19:31:28 +02009457 "hidden" do not open a window
Bram Moolenaarb5b75622018-03-09 22:22:21 +01009458 "norestore" do not add the terminal window to a
9459 session file
Bram Moolenaar25cdd9c2018-03-10 20:28:12 +01009460 "term_kill" what to do when trying to close the
9461 terminal window, see |term_setkill()|
Bram Moolenaar08d384f2017-08-11 21:51:23 +02009462 "term_finish" What to do when the job is finished:
Bram Moolenaardd693ce2017-08-10 23:15:19 +02009463 "close": close any windows
9464 "open": open window if needed
9465 Note that "open" can be interruptive.
9466 See |term++close| and |term++open|.
Bram Moolenaar37c45832017-08-12 16:01:04 +02009467 "term_opencmd" command to use for opening the window when
9468 "open" is used for "term_finish"; must
9469 have "%d" where the buffer number goes,
9470 e.g. "10split|buffer %d"; when not
9471 specified "botright sbuf %d" is used
Bram Moolenaaref68e4f2017-09-02 16:28:36 +02009472 "eof_chars" Text to send after all buffer lines were
9473 written to the terminal. When not set
Bram Moolenaar2dc9d262017-09-08 14:39:30 +02009474 CTRL-D is used on MS-Windows. For Python
9475 use CTRL-Z or "exit()". For a shell use
9476 "exit". A CR is always added.
Bram Moolenaarf59c6e82018-04-10 15:59:11 +02009477 "ansi_colors" A list of 16 color names or hex codes
9478 defining the ANSI palette used in GUI
9479 color modes. See |g:terminal_ansi_colors|.
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01009480 "tty_type" (MS-Windows only): Specify which pty to
9481 use. See 'termwintype' for the values.
Bram Moolenaar37c45832017-08-12 16:01:04 +02009482
Bram Moolenaar45356542017-08-06 17:53:31 +02009483 {only available when compiled with the |+terminal| feature}
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009484
Bram Moolenaarf3402b12017-08-06 19:07:08 +02009485term_wait({buf} [, {time}]) *term_wait()*
Bram Moolenaarc6df10e2017-07-29 20:15:08 +02009486 Wait for pending updates of {buf} to be handled.
9487 {buf} is used as with |term_getsize()|.
Bram Moolenaarf3402b12017-08-06 19:07:08 +02009488 {time} is how long to wait for updates to arrive in msec. If
9489 not set then 10 msec will be used.
Bram Moolenaar45356542017-08-06 17:53:31 +02009490 {only available when compiled with the |+terminal| feature}
Bram Moolenaar574860b2016-05-24 17:33:34 +02009491
Bram Moolenaar8e8df252016-05-25 21:23:21 +02009492test_alloc_fail({id}, {countdown}, {repeat}) *test_alloc_fail()*
9493 This is for testing: If the memory allocation with {id} is
9494 called, then decrement {countdown}, and when it reaches zero
9495 let memory allocation fail {repeat} times. When {repeat} is
9496 smaller than one it fails one time.
9497
Bram Moolenaar6f1d9a02016-07-24 14:12:38 +02009498test_autochdir() *test_autochdir()*
9499 Set a flag to enable the effect of 'autochdir' before Vim
9500 startup has finished.
Bram Moolenaar8e8df252016-05-25 21:23:21 +02009501
Bram Moolenaar5e80de32017-09-03 15:48:12 +02009502test_feedinput({string}) *test_feedinput()*
9503 Characters in {string} are queued for processing as if they
9504 were typed by the user. This uses a low level input buffer.
9505 This function works only when with |+unix| or GUI is running.
9506
Bram Moolenaar574860b2016-05-24 17:33:34 +02009507test_garbagecollect_now() *test_garbagecollect_now()*
9508 Like garbagecollect(), but executed right away. This must
9509 only be called directly to avoid any structure to exist
9510 internally, and |v:testing| must have been set before calling
9511 any function.
9512
Bram Moolenaare0c31f62017-03-01 15:07:05 +01009513test_ignore_error({expr}) *test_ignore_error()*
9514 Ignore any error containing {expr}. A normal message is given
9515 instead.
9516 This is only meant to be used in tests, where catching the
9517 error with try/catch cannot be used (because it skips over
9518 following code).
9519 {expr} is used literally, not as a pattern.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +01009520 When the {expr} is the string "RESET" then the list of ignored
9521 errors is made empty.
Bram Moolenaare0c31f62017-03-01 15:07:05 +01009522
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009523test_null_blob() *test_null_blob()*
9524 Return a |Blob| that is null. Only useful for testing.
9525
Bram Moolenaar574860b2016-05-24 17:33:34 +02009526test_null_channel() *test_null_channel()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009527 Return a |Channel| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009528 {only available when compiled with the +channel feature}
9529
9530test_null_dict() *test_null_dict()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009531 Return a |Dict| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009532
9533test_null_job() *test_null_job()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009534 Return a |Job| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009535 {only available when compiled with the +job feature}
9536
9537test_null_list() *test_null_list()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009538 Return a |List| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009539
9540test_null_partial() *test_null_partial()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009541 Return a |Partial| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009542
9543test_null_string() *test_null_string()*
Bram Moolenaarc0f5a782019-01-13 15:16:13 +01009544 Return a |String| that is null. Only useful for testing.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009545
Bram Moolenaarfe8ef982018-09-13 20:31:54 +02009546test_option_not_set({name}) *test_option_not_set()*
9547 Reset the flag that indicates option {name} was set. Thus it
9548 looks like it still has the default value. Use like this: >
9549 set ambiwidth=double
9550 call test_option_not_set('ambiwidth')
9551< Now the 'ambiwidth' option behaves like it was never changed,
9552 even though the value is "double".
9553 Only to be used for testing!
9554
Bram Moolenaar036986f2017-03-16 17:41:02 +01009555test_override({name}, {val}) *test_override()*
Bram Moolenaar9d87a372018-12-18 21:41:50 +01009556 Overrides certain parts of Vim's internal processing to be able
Bram Moolenaar036986f2017-03-16 17:41:02 +01009557 to run tests. Only to be used for testing Vim!
9558 The override is enabled when {val} is non-zero and removed
9559 when {val} is zero.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009560 Current supported values for name are:
Bram Moolenaar036986f2017-03-16 17:41:02 +01009561
9562 name effect when {val} is non-zero ~
9563 redraw disable the redrawing() function
Bram Moolenaared5a9d62018-09-06 13:14:43 +02009564 redraw_flag ignore the RedrawingDisabled flag
Bram Moolenaar036986f2017-03-16 17:41:02 +01009565 char_avail disable the char_avail() function
Bram Moolenaar182a17b2017-06-25 20:57:18 +02009566 starting reset the "starting" variable, see below
Bram Moolenaarbcf94422018-06-23 14:21:42 +02009567 nfa_fail makes the NFA regexp engine fail to force a
9568 fallback to the old engine
Bram Moolenaar036986f2017-03-16 17:41:02 +01009569 ALL clear all overrides ({val} is not used)
9570
Bram Moolenaar182a17b2017-06-25 20:57:18 +02009571 "starting" is to be used when a test should behave like
9572 startup was done. Since the tests are run by sourcing a
9573 script the "starting" variable is non-zero. This is usually a
9574 good thing (tests run faster), but sometimes changes behavior
9575 in a way that the test doesn't work properly.
9576 When using: >
9577 call test_override('starting', 1)
Bram Moolenaar3cd43cc2017-08-12 19:51:41 +02009578< The value of "starting" is saved. It is restored by: >
Bram Moolenaar182a17b2017-06-25 20:57:18 +02009579 call test_override('starting', 0)
9580
Bram Moolenaarab186732018-09-14 21:27:06 +02009581test_scrollbar({which}, {value}, {dragging}) *test_scrollbar()*
9582 Pretend using scrollbar {which} to move it to position
9583 {value}. {which} can be:
9584 left Left scrollbar of the current window
9585 right Right scrollbar of the current window
9586 hor Horizontal scrollbar
9587
9588 For the vertical scrollbars {value} can be 1 to the
9589 line-count of the buffer. For the horizontal scrollbar the
9590 {value} can be between 1 and the maximum line length, assuming
9591 'wrap' is not set.
9592
9593 When {dragging} is non-zero it's like dragging the scrollbar,
9594 otherwise it's like clicking in the scrollbar.
9595 Only works when the {which} scrollbar actually exists,
9596 obviously only when using the GUI.
9597
Bram Moolenaarc95a3022016-06-12 23:01:46 +02009598test_settime({expr}) *test_settime()*
9599 Set the time Vim uses internally. Currently only used for
Bram Moolenaar1e96d9b2016-07-29 22:15:09 +02009600 timestamps in the history, as they are used in viminfo, and
9601 for undo.
Bram Moolenaar3df01732017-02-17 22:47:16 +01009602 Using a value of 1 makes Vim not sleep after a warning or
9603 error message.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02009604 {expr} must evaluate to a number. When the value is zero the
9605 normal behavior is restored.
Bram Moolenaar574860b2016-05-24 17:33:34 +02009606
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009607 *timer_info()*
9608timer_info([{id}])
9609 Return a list with information about timers.
9610 When {id} is given only information about this timer is
9611 returned. When timer {id} does not exist an empty list is
9612 returned.
9613 When {id} is omitted information about all timers is returned.
9614
9615 For each timer the information is stored in a Dictionary with
9616 these items:
9617 "id" the timer ID
9618 "time" time the timer was started with
9619 "remaining" time until the timer fires
9620 "repeat" number of times the timer will still fire;
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009621 -1 means forever
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009622 "callback" the callback
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009623 "paused" 1 if the timer is paused, 0 otherwise
9624
9625 {only available when compiled with the |+timers| feature}
9626
9627timer_pause({timer}, {paused}) *timer_pause()*
9628 Pause or unpause a timer. A paused timer does not invoke its
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009629 callback when its time expires. Unpausing a timer may cause
9630 the callback to be invoked almost immediately if enough time
9631 has passed.
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009632
9633 Pausing a timer is useful to avoid the callback to be called
9634 for a short time.
9635
9636 If {paused} evaluates to a non-zero Number or a non-empty
9637 String, then the timer is paused, otherwise it is unpaused.
9638 See |non-zero-arg|.
9639
9640 {only available when compiled with the |+timers| feature}
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009641
Bram Moolenaardc1f1642016-08-16 18:33:43 +02009642 *timer_start()* *timer* *timers*
Bram Moolenaar975b5272016-03-15 23:10:59 +01009643timer_start({time}, {callback} [, {options}])
9644 Create a timer and return the timer ID.
9645
9646 {time} is the waiting time in milliseconds. This is the
9647 minimum time before invoking the callback. When the system is
9648 busy or Vim is not waiting for input the time will be longer.
9649
9650 {callback} is the function to call. It can be the name of a
Bram Moolenaarf37506f2016-08-31 22:22:10 +02009651 function or a |Funcref|. It is called with one argument, which
Bram Moolenaar975b5272016-03-15 23:10:59 +01009652 is the timer ID. The callback is only invoked when Vim is
9653 waiting for input.
9654
9655 {options} is a dictionary. Supported entries:
9656 "repeat" Number of times to repeat calling the
Bram Moolenaarabd468e2016-09-08 22:22:43 +02009657 callback. -1 means forever. When not present
9658 the callback will be called once.
Bram Moolenaarc577d812017-07-08 22:37:34 +02009659 If the timer causes an error three times in a
9660 row the repeat is cancelled. This avoids that
9661 Vim becomes unusable because of all the error
9662 messages.
Bram Moolenaar975b5272016-03-15 23:10:59 +01009663
9664 Example: >
9665 func MyHandler(timer)
9666 echo 'Handler called'
9667 endfunc
9668 let timer = timer_start(500, 'MyHandler',
9669 \ {'repeat': 3})
9670< This will invoke MyHandler() three times at 500 msec
9671 intervals.
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009672
Bram Moolenaar975b5272016-03-15 23:10:59 +01009673 {only available when compiled with the |+timers| feature}
9674
Bram Moolenaar03602ec2016-03-20 20:57:45 +01009675timer_stop({timer}) *timer_stop()*
Bram Moolenaar06d2d382016-05-20 17:24:11 +02009676 Stop a timer. The timer callback will no longer be invoked.
9677 {timer} is an ID returned by timer_start(), thus it must be a
Bram Moolenaar8e97bd72016-08-06 22:05:07 +02009678 Number. If {timer} does not exist there is no error.
Bram Moolenaar03602ec2016-03-20 20:57:45 +01009679
Bram Moolenaarb73598e2016-08-07 18:22:53 +02009680 {only available when compiled with the |+timers| feature}
9681
9682timer_stopall() *timer_stopall()*
9683 Stop all timers. The timer callbacks will no longer be
9684 invoked. Useful if some timers is misbehaving. If there are
9685 no timers there is no error.
9686
9687 {only available when compiled with the |+timers| feature}
9688
Bram Moolenaar071d4272004-06-13 20:20:40 +00009689tolower({expr}) *tolower()*
9690 The result is a copy of the String given, with all uppercase
9691 characters turned into lowercase (just like applying |gu| to
9692 the string).
9693
9694toupper({expr}) *toupper()*
9695 The result is a copy of the String given, with all lowercase
9696 characters turned into uppercase (just like applying |gU| to
9697 the string).
9698
Bram Moolenaar8299df92004-07-10 09:47:34 +00009699tr({src}, {fromstr}, {tostr}) *tr()*
9700 The result is a copy of the {src} string with all characters
9701 which appear in {fromstr} replaced by the character in that
9702 position in the {tostr} string. Thus the first character in
9703 {fromstr} is translated into the first character in {tostr}
9704 and so on. Exactly like the unix "tr" command.
9705 This code also deals with multibyte characters properly.
9706
9707 Examples: >
9708 echo tr("hello there", "ht", "HT")
9709< returns "Hello THere" >
9710 echo tr("<blob>", "<>", "{}")
9711< returns "{blob}"
9712
Bram Moolenaard473c8c2018-08-11 18:00:22 +02009713trim({text} [, {mask}]) *trim()*
Bram Moolenaar295ac5a2018-03-22 23:04:02 +01009714 Return {text} as a String where any character in {mask} is
9715 removed from the beginning and end of {text}.
9716 If {mask} is not given, {mask} is all characters up to 0x20,
9717 which includes Tab, space, NL and CR, plus the non-breaking
9718 space character 0xa0.
9719 This code deals with multibyte characters properly.
9720
9721 Examples: >
Bram Moolenaarab943432018-03-29 18:27:07 +02009722 echo trim(" some text ")
9723< returns "some text" >
9724 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL"
Bram Moolenaar295ac5a2018-03-22 23:04:02 +01009725< returns "RESERVE_TAIL" >
Bram Moolenaarab943432018-03-29 18:27:07 +02009726 echo trim("rm<Xrm<>X>rrm", "rm<>")
9727< returns "Xrm<>X" (characters in the middle are not removed)
Bram Moolenaar295ac5a2018-03-22 23:04:02 +01009728
Bram Moolenaar446cb832008-06-24 21:56:24 +00009729trunc({expr}) *trunc()*
Bram Moolenaarc236c162008-07-13 17:41:49 +00009730 Return the largest integral value with magnitude less than or
Bram Moolenaar446cb832008-06-24 21:56:24 +00009731 equal to {expr} as a |Float| (truncate towards zero).
9732 {expr} must evaluate to a |Float| or a |Number|.
9733 Examples: >
9734 echo trunc(1.456)
9735< 1.0 >
9736 echo trunc(-5.456)
9737< -5.0 >
9738 echo trunc(4.0)
9739< 4.0
9740 {only available when compiled with the |+float| feature}
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009741
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00009742 *type()*
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009743type({expr}) The result is a Number representing the type of {expr}.
9744 Instead of using the number directly, it is better to use the
9745 v:t_ variable that has the value:
9746 Number: 0 |v:t_number|
9747 String: 1 |v:t_string|
9748 Funcref: 2 |v:t_func|
9749 List: 3 |v:t_list|
9750 Dictionary: 4 |v:t_dict|
9751 Float: 5 |v:t_float|
9752 Boolean: 6 |v:t_bool| (v:false and v:true)
Bram Moolenaar39536dd2019-01-29 22:58:21 +01009753 None: 7 |v:t_none| (v:null and v:none)
9754 Job: 8 |v:t_job|
9755 Channel: 9 |v:t_channel|
9756 Blob: 10 |v:t_blob|
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009757 For backward compatibility, this method can be used: >
Bram Moolenaar9588a0f2005-01-08 21:45:39 +00009758 :if type(myvar) == type(0)
9759 :if type(myvar) == type("")
9760 :if type(myvar) == type(function("tr"))
9761 :if type(myvar) == type([])
Bram Moolenaar748bf032005-02-02 23:04:36 +00009762 :if type(myvar) == type({})
Bram Moolenaar446cb832008-06-24 21:56:24 +00009763 :if type(myvar) == type(0.0)
Bram Moolenaar705ada12016-01-24 17:56:50 +01009764 :if type(myvar) == type(v:false)
Bram Moolenaar6463ca22016-02-13 17:04:46 +01009765 :if type(myvar) == type(v:none)
Bram Moolenaardf48fb42016-07-22 21:50:18 +02009766< To check if the v:t_ variables exist use this: >
9767 :if exists('v:t_number')
Bram Moolenaar071d4272004-06-13 20:20:40 +00009768
Bram Moolenaara17d4c12010-05-30 18:30:36 +02009769undofile({name}) *undofile()*
9770 Return the name of the undo file that would be used for a file
9771 with name {name} when writing. This uses the 'undodir'
9772 option, finding directories that exist. It does not check if
Bram Moolenaar860cae12010-06-05 23:22:07 +02009773 the undo file exists.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02009774 {name} is always expanded to the full path, since that is what
9775 is used internally.
Bram Moolenaar80716072012-05-01 21:14:34 +02009776 If {name} is empty undofile() returns an empty string, since a
9777 buffer without a file name will not write an undo file.
Bram Moolenaara17d4c12010-05-30 18:30:36 +02009778 Useful in combination with |:wundo| and |:rundo|.
Bram Moolenaarb328cca2019-01-06 16:24:01 +01009779 When compiled without the |+persistent_undo| option this always
Bram Moolenaara17d4c12010-05-30 18:30:36 +02009780 returns an empty string.
9781
Bram Moolenaara800b422010-06-27 01:15:55 +02009782undotree() *undotree()*
9783 Return the current state of the undo tree in a dictionary with
9784 the following items:
9785 "seq_last" The highest undo sequence number used.
9786 "seq_cur" The sequence number of the current position in
9787 the undo tree. This differs from "seq_last"
9788 when some changes were undone.
9789 "time_cur" Time last used for |:earlier| and related
9790 commands. Use |strftime()| to convert to
9791 something readable.
9792 "save_last" Number of the last file write. Zero when no
9793 write yet.
Bram Moolenaar730cde92010-06-27 05:18:54 +02009794 "save_cur" Number of the current position in the undo
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01009795 tree.
Bram Moolenaara800b422010-06-27 01:15:55 +02009796 "synced" Non-zero when the last undo block was synced.
9797 This happens when waiting from input from the
9798 user. See |undo-blocks|.
9799 "entries" A list of dictionaries with information about
9800 undo blocks.
9801
9802 The first item in the "entries" list is the oldest undo item.
9803 Each List item is a Dictionary with these items:
9804 "seq" Undo sequence number. Same as what appears in
9805 |:undolist|.
9806 "time" Timestamp when the change happened. Use
9807 |strftime()| to convert to something readable.
9808 "newhead" Only appears in the item that is the last one
9809 that was added. This marks the last change
9810 and where further changes will be added.
9811 "curhead" Only appears in the item that is the last one
9812 that was undone. This marks the current
9813 position in the undo tree, the block that will
9814 be used by a redo command. When nothing was
9815 undone after the last change this item will
9816 not appear anywhere.
9817 "save" Only appears on the last block before a file
9818 write. The number is the write count. The
9819 first write has number 1, the last one the
9820 "save_last" mentioned above.
9821 "alt" Alternate entry. This is again a List of undo
9822 blocks. Each item may again have an "alt"
9823 item.
9824
Bram Moolenaar327aa022014-03-25 18:24:23 +01009825uniq({list} [, {func} [, {dict}]]) *uniq()* *E882*
9826 Remove second and succeeding copies of repeated adjacent
9827 {list} items in-place. Returns {list}. If you want a list
9828 to remain unmodified make a copy first: >
9829 :let newlist = uniq(copy(mylist))
9830< The default compare function uses the string representation of
9831 each item. For the use of {func} and {dict} see |sort()|.
9832
Bram Moolenaar677ee682005-01-27 14:41:15 +00009833values({dict}) *values()*
Bram Moolenaar58b85342016-08-14 19:54:54 +02009834 Return a |List| with all the values of {dict}. The |List| is
Bram Moolenaar0d17f0d2019-01-22 22:20:38 +01009835 in arbitrary order. Also see |items()| and |keys()|.
Bram Moolenaar677ee682005-01-27 14:41:15 +00009836
9837
Bram Moolenaar071d4272004-06-13 20:20:40 +00009838virtcol({expr}) *virtcol()*
9839 The result is a Number, which is the screen column of the file
9840 position given with {expr}. That is, the last screen position
9841 occupied by the character at that position, when the screen
9842 would be of unlimited width. When there is a <Tab> at the
9843 position, the returned Number will be the column at the end of
9844 the <Tab>. For example, for a <Tab> in column 1, with 'ts'
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02009845 set to 8, it returns 8. |conceal| is ignored.
Bram Moolenaar477933c2007-07-17 14:32:23 +00009846 For the byte position use |col()|.
9847 For the use of {expr} see |col()|.
9848 When 'virtualedit' is used {expr} can be [lnum, col, off], where
Bram Moolenaar0b238792006-03-02 22:49:12 +00009849 "off" is the offset in screen columns from the start of the
Bram Moolenaard46bbc72007-05-12 14:38:41 +00009850 character. E.g., a position within a <Tab> or after the last
Bram Moolenaar97293012011-07-18 19:40:27 +02009851 character. When "off" is omitted zero is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009852 When Virtual editing is active in the current mode, a position
9853 beyond the end of the line can be returned. |'virtualedit'|
9854 The accepted positions are:
9855 . the cursor position
9856 $ the end of the cursor line (the result is the
9857 number of displayed characters in the cursor line
9858 plus one)
9859 'x position of mark x (if the mark is not set, 0 is
9860 returned)
Bram Moolenaare3faf442014-12-14 01:27:49 +01009861 v In Visual mode: the start of the Visual area (the
9862 cursor is the end). When not in Visual mode
9863 returns the cursor position. Differs from |'<| in
9864 that it's updated right away.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009865 Note that only marks in the current file can be used.
9866 Examples: >
9867 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5
9868 virtcol("$") with text "foo^Lbar", returns 9
Bram Moolenaar446cb832008-06-24 21:56:24 +00009869 virtcol("'t") with text " there", with 't at 'h', returns 6
Bram Moolenaar58b85342016-08-14 19:54:54 +02009870< The first column is 1. 0 is returned for an error.
Bram Moolenaaref2f6562007-05-06 13:32:59 +00009871 A more advanced example that echoes the maximum length of
9872 all lines: >
9873 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))
9874
Bram Moolenaar071d4272004-06-13 20:20:40 +00009875
9876visualmode([expr]) *visualmode()*
9877 The result is a String, which describes the last Visual mode
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009878 used in the current buffer. Initially it returns an empty
9879 string, but once Visual mode has been used, it returns "v",
9880 "V", or "<CTRL-V>" (a single CTRL-V character) for
9881 character-wise, line-wise, or block-wise Visual mode
9882 respectively.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009883 Example: >
9884 :exe "normal " . visualmode()
9885< This enters the same Visual mode as before. It is also useful
9886 in scripts if you wish to act differently depending on the
9887 Visual mode that was used.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009888 If Visual mode is active, use |mode()| to get the Visual mode
9889 (e.g., in a |:vmap|).
Bram Moolenaar05bb9532008-07-04 09:44:11 +00009890 If [expr] is supplied and it evaluates to a non-zero Number or
9891 a non-empty String, then the Visual mode will be cleared and
Bram Moolenaare381d3d2016-07-07 14:50:41 +02009892 the old value is returned. See |non-zero-arg|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009893
Bram Moolenaar8738fc12013-02-20 17:59:11 +01009894wildmenumode() *wildmenumode()*
Bram Moolenaare381d3d2016-07-07 14:50:41 +02009895 Returns |TRUE| when the wildmenu is active and |FALSE|
Bram Moolenaar8738fc12013-02-20 17:59:11 +01009896 otherwise. See 'wildmenu' and 'wildmode'.
9897 This can be used in mappings to handle the 'wildcharm' option
9898 gracefully. (Makes only sense with |mapmode-c| mappings).
9899
9900 For example to make <c-j> work like <down> in wildmode, use: >
9901 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>"
9902<
9903 (Note, this needs the 'wildcharm' option set appropriately).
9904
9905
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +01009906win_findbuf({bufnr}) *win_findbuf()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02009907 Returns a list with |window-ID|s for windows that contain
9908 buffer {bufnr}. When there is none the list is empty.
Bram Moolenaar9cdf86b2016-03-13 19:04:51 +01009909
Bram Moolenaar86edef62016-03-13 18:07:30 +01009910win_getid([{win} [, {tab}]]) *win_getid()*
Bram Moolenaar7571d552016-08-18 22:54:46 +02009911 Get the |window-ID| for the specified window.
Bram Moolenaar86edef62016-03-13 18:07:30 +01009912 When {win} is missing use the current window.
9913 With {win} this is the window number. The top window has
Bram Moolenaarba3ff532018-11-04 14:45:49 +01009914 number 1.
Bram Moolenaar86edef62016-03-13 18:07:30 +01009915 Without {tab} use the current tab, otherwise the tab with
9916 number {tab}. The first tab has number one.
9917 Return zero if the window cannot be found.
9918
9919win_gotoid({expr}) *win_gotoid()*
9920 Go to window with ID {expr}. This may also change the current
9921 tabpage.
9922 Return 1 if successful, 0 if the window cannot be found.
9923
Bram Moolenaar03413f42016-04-12 21:07:15 +02009924win_id2tabwin({expr}) *win_id2tabwin()*
Bram Moolenaar86edef62016-03-13 18:07:30 +01009925 Return a list with the tab number and window number of window
9926 with ID {expr}: [tabnr, winnr].
9927 Return [0, 0] if the window cannot be found.
9928
9929win_id2win({expr}) *win_id2win()*
9930 Return the window number of window with ID {expr}.
9931 Return 0 if the window cannot be found in the current tabpage.
9932
Bram Moolenaar22044dc2017-12-02 15:43:37 +01009933win_screenpos({nr}) *win_screenpos()*
9934 Return the screen position of window {nr} as a list with two
9935 numbers: [row, col]. The first window always has position
Bram Moolenaar7132ddc2018-07-15 17:01:11 +02009936 [1, 1], unless there is a tabline, then it is [2, 1].
Bram Moolenaar22044dc2017-12-02 15:43:37 +01009937 {nr} can be the window number or the |window-ID|.
9938 Return [0, 0] if the window cannot be found in the current
9939 tabpage.
9940
Bram Moolenaar071d4272004-06-13 20:20:40 +00009941 *winbufnr()*
9942winbufnr({nr}) The result is a Number, which is the number of the buffer
Bram Moolenaar888ccac2016-06-04 18:49:36 +02009943 associated with window {nr}. {nr} can be the window number or
Bram Moolenaar7571d552016-08-18 22:54:46 +02009944 the |window-ID|.
Bram Moolenaar888ccac2016-06-04 18:49:36 +02009945 When {nr} is zero, the number of the buffer in the current
9946 window is returned.
9947 When window {nr} doesn't exist, -1 is returned.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009948 Example: >
9949 :echo "The file in the current window is " . bufname(winbufnr(0))
9950<
9951 *wincol()*
9952wincol() The result is a Number, which is the virtual column of the
9953 cursor in the window. This is counting screen cells from the
9954 left side of the window. The leftmost column is one.
9955
9956winheight({nr}) *winheight()*
9957 The result is a Number, which is the height of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +02009958 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009959 When {nr} is zero, the height of the current window is
9960 returned. When window {nr} doesn't exist, -1 is returned.
9961 An existing window always has a height of zero or more.
Bram Moolenaar37c64c72017-09-19 22:06:03 +02009962 This excludes any window toolbar line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009963 Examples: >
9964 :echo "The current window has " . winheight(0) . " lines."
9965<
Bram Moolenaar0f6b4f02018-08-21 16:56:34 +02009966winlayout([{tabnr}]) *winlayout()*
9967 The result is a nested List containing the layout of windows
9968 in a tabpage.
9969
9970 Without {tabnr} use the current tabpage, otherwise the tabpage
9971 with number {tabnr}. If the tabpage {tabnr} is not found,
9972 returns an empty list.
9973
9974 For a leaf window, it returns:
9975 ['leaf', {winid}]
9976 For horizontally split windows, which form a column, it
9977 returns:
9978 ['col', [{nested list of windows}]]
9979 For vertically split windows, which form a row, it returns:
9980 ['row', [{nested list of windows}]]
9981
9982 Example: >
9983 " Only one window in the tab page
9984 :echo winlayout()
9985 ['leaf', 1000]
9986 " Two horizontally split windows
9987 :echo winlayout()
9988 ['col', [['leaf', 1000], ['leaf', 1001]]]
9989 " Three horizontally split windows, with two
9990 " vertically split windows in the middle window
9991 :echo winlayout(2)
9992 ['col', [['leaf', 1002], ['row', ['leaf', 1003],
9993 ['leaf', 1001]]], ['leaf', 1000]]
9994<
Bram Moolenaar071d4272004-06-13 20:20:40 +00009995 *winline()*
9996winline() The result is a Number, which is the screen line of the cursor
Bram Moolenaar58b85342016-08-14 19:54:54 +02009997 in the window. This is counting screen lines from the top of
Bram Moolenaar071d4272004-06-13 20:20:40 +00009998 the window. The first line is one.
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00009999 If the cursor was moved the view on the file will be updated
10000 first, this may cause a scroll.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010001
10002 *winnr()*
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000010003winnr([{arg}]) The result is a Number, which is the number of the current
10004 window. The top window has number 1.
10005 When the optional argument is "$", the number of the
Bram Moolenaar2df58b42012-11-28 18:21:11 +010010006 last window is returned (the window count). >
10007 let window_count = winnr('$')
10008< When the optional argument is "#", the number of the last
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000010009 accessed window is returned (where |CTRL-W_p| goes to).
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010010 If there is no previous window or it is in another tab page 0
10011 is returned.
Bram Moolenaar5eb86f92004-07-26 12:53:41 +000010012 The number can be used with |CTRL-W_w| and ":wincmd w"
10013 |:wincmd|.
Bram Moolenaar690afe12017-01-28 18:34:47 +010010014 Also see |tabpagewinnr()| and |win_getid()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010015
10016 *winrestcmd()*
10017winrestcmd() Returns a sequence of |:resize| commands that should restore
10018 the current window sizes. Only works properly when no windows
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010019 are opened or closed and the current window and tab page is
10020 unchanged.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010021 Example: >
10022 :let cmd = winrestcmd()
10023 :call MessWithWindowSizes()
10024 :exe cmd
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010025<
10026 *winrestview()*
10027winrestview({dict})
10028 Uses the |Dictionary| returned by |winsaveview()| to restore
10029 the view of the current window.
Bram Moolenaar82c25852014-05-28 16:47:16 +020010030 Note: The {dict} does not have to contain all values, that are
10031 returned by |winsaveview()|. If values are missing, those
10032 settings won't be restored. So you can use: >
10033 :call winrestview({'curswant': 4})
10034<
10035 This will only set the curswant value (the column the cursor
10036 wants to move on vertical movements) of the cursor to column 5
10037 (yes, that is 5), while all other settings will remain the
10038 same. This is useful, if you set the cursor position manually.
10039
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010040 If you have changed the values the result is unpredictable.
10041 If the window size changed the result won't be the same.
10042
10043 *winsaveview()*
10044winsaveview() Returns a |Dictionary| that contains information to restore
10045 the view of the current window. Use |winrestview()| to
10046 restore the view.
10047 This is useful if you have a mapping that jumps around in the
10048 buffer and you want to go back to the original view.
10049 This does not save fold information. Use the 'foldenable'
Bram Moolenaardb552d602006-03-23 22:59:57 +000010050 option to temporarily switch off folding, so that folds are
Bram Moolenaar07d87792014-07-19 14:04:47 +020010051 not opened when moving around. This may have side effects.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010052 The return value includes:
10053 lnum cursor line number
Bram Moolenaar82c25852014-05-28 16:47:16 +020010054 col cursor column (Note: the first column
10055 zero, as opposed to what getpos()
10056 returns)
Bram Moolenaar87b5ca52006-03-04 21:55:31 +000010057 coladd cursor column offset for 'virtualedit'
10058 curswant column for vertical movement
10059 topline first line in the window
10060 topfill filler lines, only in diff mode
10061 leftcol first column displayed
10062 skipcol columns skipped
10063 Note that no option values are saved.
10064
Bram Moolenaar071d4272004-06-13 20:20:40 +000010065
10066winwidth({nr}) *winwidth()*
10067 The result is a Number, which is the width of window {nr}.
Bram Moolenaar7571d552016-08-18 22:54:46 +020010068 {nr} can be the window number or the |window-ID|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010069 When {nr} is zero, the width of the current window is
10070 returned. When window {nr} doesn't exist, -1 is returned.
10071 An existing window always has a width of zero or more.
10072 Examples: >
10073 :echo "The current window has " . winwidth(0) . " columns."
10074 :if winwidth(0) <= 50
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010075 : 50 wincmd |
Bram Moolenaar071d4272004-06-13 20:20:40 +000010076 :endif
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010077< For getting the terminal or screen size, see the 'columns'
10078 option.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020010079
10080
Bram Moolenaared767a22016-01-03 22:49:16 +010010081wordcount() *wordcount()*
10082 The result is a dictionary of byte/chars/word statistics for
10083 the current buffer. This is the same info as provided by
10084 |g_CTRL-G|
10085 The return value includes:
10086 bytes Number of bytes in the buffer
10087 chars Number of chars in the buffer
10088 words Number of words in the buffer
10089 cursor_bytes Number of bytes before cursor position
10090 (not in Visual mode)
10091 cursor_chars Number of chars before cursor position
10092 (not in Visual mode)
10093 cursor_words Number of words before cursor position
10094 (not in Visual mode)
10095 visual_bytes Number of bytes visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010096 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010010097 visual_chars Number of chars visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010098 (only in Visual mode)
Bram Moolenaarc572da52017-08-27 16:52:01 +020010099 visual_words Number of words visually selected
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010100 (only in Visual mode)
Bram Moolenaared767a22016-01-03 22:49:16 +010010101
10102
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010103 *writefile()*
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010010104writefile({object}, {fname} [, {flags}])
10105 When {object} is a |List| write it to file {fname}. Each list
10106 item is separated with a NL. Each list item must be a String
10107 or Number.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010108 When {flags} contains "b" then binary mode is used: There will
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010109 not be a NL after the last list item. An empty item at the
10110 end does cause the last line in the file to end in a NL.
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010111
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010010112 When {object} is a |Blob| write the bytes to file {fname}
10113 unmodified.
10114
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010115 When {flags} contains "a" then append mode is used, lines are
Bram Moolenaar46fceaa2016-10-23 21:21:08 +020010116 appended to the file: >
Bram Moolenaar6b2e9382014-11-05 18:06:01 +010010117 :call writefile(["foo"], "event.log", "a")
10118 :call writefile(["bar"], "event.log", "a")
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010119<
10120 When {flags} contains "s" then fsync() is called after writing
10121 the file. This flushes the file to disk, if possible. This
10122 takes more time but avoids losing the file if the system
10123 crashes.
Bram Moolenaar74240d32017-12-10 15:26:15 +010010124 When {flags} does not contain "S" or "s" then fsync() is
10125 called if the 'fsync' option is set.
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010126 When {flags} contains "S" then fsync() is not called, even
10127 when 'fsync' is set.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010128
Bram Moolenaar7567d0b2017-11-16 23:04:15 +010010129 All NL characters are replaced with a NUL character.
Bram Moolenaar3a7c85b2005-02-05 21:39:53 +000010130 Inserting CR characters needs to be done before passing {list}
10131 to writefile().
10132 An existing file is overwritten, if possible.
10133 When the write fails -1 is returned, otherwise 0. There is an
10134 error message if the file can't be created or when writing
10135 fails.
10136 Also see |readfile()|.
10137 To copy a file byte for byte: >
10138 :let fl = readfile("foo", "b")
10139 :call writefile(fl, "foocopy", "b")
Bram Moolenaard6e256c2011-12-14 15:32:50 +010010140
10141
10142xor({expr}, {expr}) *xor()*
10143 Bitwise XOR on the two arguments. The arguments are converted
10144 to a number. A List, Dict or Float argument causes an error.
10145 Example: >
10146 :let bits = xor(bits, 0x80)
Bram Moolenaar6ee8d892012-01-10 14:55:01 +010010147<
Bram Moolenaard6e256c2011-12-14 15:32:50 +010010148
Bram Moolenaar071d4272004-06-13 20:20:40 +000010149
10150 *feature-list*
Bram Moolenaar946e27a2014-06-25 18:50:27 +020010151There are four types of features:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000101521. Features that are only supported when they have been enabled when Vim
10153 was compiled |+feature-list|. Example: >
10154 :if has("cindent")
101552. Features that are only supported when certain conditions have been met.
10156 Example: >
10157 :if has("gui_running")
10158< *has-patch*
Bram Moolenaar2f018892018-05-18 18:12:06 +0200101593. Beyond a certain version or at a certain version and including a specific
10160 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or
10161 later, or it is version 7.4 and patch 248 was included. Example: >
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010162 :if has("patch-7.4.248")
Bram Moolenaar2f018892018-05-18 18:12:06 +020010163< Note that it's possible for patch 248 to be omitted even though 249 is
10164 included. Only happens when cherry-picking patches.
10165 Note that this form only works for patch 7.4.237 and later, before that
10166 you need to check for the patch and the v:version. Example (checking
10167 version 6.2.148 or later): >
10168 :if v:version > 602 || (v:version == 602 && has("patch148"))
Bram Moolenaar071d4272004-06-13 20:20:40 +000010169
Bram Moolenaard823fa92016-08-12 16:29:27 +020010170Hint: To find out if Vim supports backslashes in a file name (MS-Windows),
10171use: `if exists('+shellslash')`
10172
10173
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020010174acl Compiled with |ACL| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010175all_builtin_terms Compiled with all builtin terminals enabled.
10176amiga Amiga version of Vim.
10177arabic Compiled with Arabic support |Arabic|.
10178arp Compiled with ARP support (Amiga).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010179autocmd Compiled with autocommand support. (always true)
Bram Moolenaar91f84f62018-07-29 15:07:52 +020010180autochdir Compiled with support for 'autochdir'
Bram Moolenaare42a6d22017-11-12 19:21:51 +010010181autoservername Automatically enable |clientserver|
Bram Moolenaar071d4272004-06-13 20:20:40 +000010182balloon_eval Compiled with |balloon-eval| support.
Bram Moolenaar45360022005-07-21 21:08:21 +000010183balloon_multiline GUI supports multiline balloons.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010184beos BeOS version of Vim.
10185browse Compiled with |:browse| support, and browse() will
10186 work.
Bram Moolenaar30b65812012-07-12 22:01:11 +020010187browsefilter Compiled with support for |browsefilter|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010188bsd Compiled on an OS in the BSD family (excluding macOS).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010189builtin_terms Compiled with some builtin terminals.
10190byte_offset Compiled with support for 'o' in 'statusline'
10191cindent Compiled with 'cindent' support.
10192clientserver Compiled with remote invocation support |clientserver|.
10193clipboard Compiled with 'clipboard' support.
10194cmdline_compl Compiled with |cmdline-completion| support.
10195cmdline_hist Compiled with |cmdline-history| support.
10196cmdline_info Compiled with 'showcmd' and 'ruler' support.
10197comments Compiled with |'comments'| support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010198compatible Compiled to be very Vi compatible.
Bram Moolenaaraa5df7e2019-02-03 14:53:10 +010010199conpty Platform where |ConPTY| can be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010200cryptv Compiled with encryption support |encryption|.
10201cscope Compiled with |cscope| support.
Bram Moolenaar314dd792019-02-03 15:27:20 +010010202cursorbind Compiled with |'cursorbind'| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010203debug Compiled with "DEBUG" defined.
10204dialog_con Compiled with console dialog support.
10205dialog_gui Compiled with GUI dialog support.
10206diff Compiled with |vimdiff| and 'diff' support.
10207digraphs Compiled with support for digraphs.
Bram Moolenaar58b85342016-08-14 19:54:54 +020010208directx Compiled with support for DirectX and 'renderoptions'.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010209dnd Compiled with support for the "~ register |quote_~|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010210ebcdic Compiled on a machine with ebcdic character set.
10211emacs_tags Compiled with support for Emacs tags.
10212eval Compiled with expression evaluation support. Always
10213 true, of course!
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010214ex_extra |+ex_extra| (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010215extra_search Compiled with support for |'incsearch'| and
10216 |'hlsearch'|
10217farsi Compiled with Farsi support |farsi|.
10218file_in_path Compiled with support for |gf| and |<cfile>|
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010219filterpipe When 'shelltemp' is off pipes are used for shell
10220 read/write/filter commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000010221find_in_path Compiled with support for include file searches
10222 |+find_in_path|.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010223float Compiled with support for |Float|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010224fname_case Case in file names matters (for Amiga, MS-DOS, and
10225 Windows this is not present).
10226folding Compiled with |folding| support.
10227footer Compiled with GUI footer support. |gui-footer|
10228fork Compiled to use fork()/exec() instead of system().
10229gettext Compiled with message translation |multi-lang|
10230gui Compiled with GUI enabled.
10231gui_athena Compiled with Athena GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010232gui_gnome Compiled with Gnome support (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010233gui_gtk Compiled with GTK+ GUI (any version).
10234gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined).
Bram Moolenaar98921892016-02-23 17:14:37 +010010235gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010236gui_mac Compiled with Macintosh GUI.
10237gui_motif Compiled with Motif GUI.
10238gui_photon Compiled with Photon GUI.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010239gui_running Vim is running in the GUI, or it will start soon.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010240gui_win32 Compiled with MS Windows Win32 GUI.
10241gui_win32s idem, and Win32s system being used (Windows 3.1)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010242hangul_input Compiled with Hangul input support. |hangul|
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010243hpux HP-UX version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010244iconv Can use iconv() for conversion.
10245insert_expand Compiled with support for CTRL-X expansion commands in
10246 Insert mode.
10247jumplist Compiled with |jumplist| support.
10248keymap Compiled with 'keymap' support.
Bram Moolenaar437bafe2016-08-01 15:40:54 +020010249lambda Compiled with |lambda| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010250langmap Compiled with 'langmap' support.
10251libcall Compiled with |libcall()| support.
Bram Moolenaar597a4222014-06-25 14:39:50 +020010252linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and
10253 'breakindent' support.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010254linux Linux version of Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010255lispindent Compiled with support for lisp indenting.
10256listcmds Compiled with commands for the buffer list |:files|
10257 and the argument list |arglist|.
10258localmap Compiled with local mappings and abbr. |:map-local|
Bram Moolenaar0ba04292010-07-14 23:23:17 +020010259lua Compiled with Lua interface |Lua|.
Bram Moolenaard0573012017-10-28 21:11:06 +020010260mac Any Macintosh version of Vim cf. osx
10261macunix Synonym for osxdarwin
Bram Moolenaar071d4272004-06-13 20:20:40 +000010262menu Compiled with support for |:menu|.
10263mksession Compiled with support for |:mksession|.
10264modify_fname Compiled with file name modifiers. |filename-modifiers|
10265mouse Compiled with support mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010266mouse_dec Compiled with support for Dec terminal mouse.
10267mouse_gpm Compiled with support for gpm (Linux console mouse)
10268mouse_netterm Compiled with support for netterm mouse.
10269mouse_pterm Compiled with support for qnx pterm mouse.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010270mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse)
Bram Moolenaar9b451252012-08-15 17:43:31 +020010271mouse_sgr Compiled with support for sgr mouse.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +010010272mouse_urxvt Compiled with support for urxvt mouse.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010273mouse_xterm Compiled with support for xterm mouse.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010274mouseshape Compiled with support for 'mouseshape'.
Bram Moolenaar42022d52008-12-09 09:57:49 +000010275multi_byte Compiled with support for 'encoding'
10276multi_byte_encoding 'encoding' is set to a multi-byte encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010277multi_byte_ime Compiled with support for IME input method.
10278multi_lang Compiled with support for multiple languages.
Bram Moolenaar325b7a22004-07-05 15:58:32 +000010279mzscheme Compiled with MzScheme interface |mzscheme|.
Bram Moolenaarb26e6322010-05-22 21:34:09 +020010280netbeans_enabled Compiled with support for |netbeans| and connected.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010281netbeans_intg Compiled with support for |netbeans|.
Bram Moolenaar22fcfad2016-07-01 18:17:26 +020010282num64 Compiled with 64-bit |Number| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010283ole Compiled with OLE automation support for Win32.
Bram Moolenaard0573012017-10-28 21:11:06 +020010284osx Compiled for macOS cf. mac
10285osxdarwin Compiled for macOS, with |mac-darwin-feature|
Bram Moolenaar91c49372016-05-08 09:50:29 +020010286packages Compiled with |packages| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010287path_extra Compiled with up/downwards search in 'path' and 'tags'
10288perl Compiled with Perl interface.
Bram Moolenaar55debbe2010-05-23 23:34:36 +020010289persistent_undo Compiled with support for persistent undo history.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010290postscript Compiled with PostScript file printing.
10291printer Compiled with |:hardcopy| support.
Bram Moolenaar05159a02005-02-26 23:04:13 +000010292profile Compiled with |:profile| support.
Bram Moolenaar84b242c2018-01-28 17:45:49 +010010293python Python 2.x interface available. |has-python|
10294python_compiled Compiled with Python 2.x interface. |has-python|
10295python_dynamic Python 2.x interface is dynamically loaded. |has-python|
10296python3 Python 3.x interface available. |has-python|
10297python3_compiled Compiled with Python 3.x interface. |has-python|
10298python3_dynamic Python 3.x interface is dynamically loaded. |has-python|
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +010010299pythonx Compiled with |python_x| interface. |has-pythonx|
Bram Moolenaar071d4272004-06-13 20:20:40 +000010300qnx QNX version of Vim.
10301quickfix Compiled with |quickfix| support.
Bram Moolenaard68071d2006-05-02 22:08:30 +000010302reltime Compiled with |reltime()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010303rightleft Compiled with 'rightleft' support.
10304ruby Compiled with Ruby interface |ruby|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010305scrollbind Compiled with 'scrollbind' support. (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010306showcmd Compiled with 'showcmd' support.
10307signs Compiled with |:sign| support.
10308smartindent Compiled with 'smartindent' support.
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010309spell Compiled with spell checking support |spell|.
Bram Moolenaaref94eec2009-11-11 13:22:11 +000010310startuptime Compiled with |--startuptime| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010311statusline Compiled with support for 'statusline', 'rulerformat'
10312 and special formats of 'titlestring' and 'iconstring'.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010313sun SunOS version of Vim.
Bram Moolenaard09091d2019-01-17 16:07:22 +010010314sun_workshop Support for Sun |workshop| has been removed.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +000010315syntax Compiled with syntax highlighting support |syntax|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010316syntax_items There are active syntax highlighting items for the
10317 current buffer.
10318system Compiled to use system() instead of fork()/exec().
10319tag_binary Compiled with binary searching in tags files
10320 |tag-binary-search|.
10321tag_old_static Compiled with support for old static tags
10322 |tag-old-static|.
10323tag_any_white Compiled with support for any white characters in tags
10324 files |tag-any-white|.
10325tcl Compiled with Tcl interface.
Bram Moolenaar91c49372016-05-08 09:50:29 +020010326termguicolors Compiled with true color in terminal support.
Bram Moolenaarc2ce52c2017-08-01 18:35:38 +020010327terminal Compiled with |terminal| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010328terminfo Compiled with terminfo instead of termcap.
10329termresponse Compiled with support for |t_RV| and |v:termresponse|.
10330textobjects Compiled with support for |text-objects|.
Bram Moolenaar98aefe72018-12-13 22:20:09 +010010331textprop Compiled with support for |text-properties|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010332tgetent Compiled with tgetent support, able to use a termcap
10333 or terminfo file.
Bram Moolenaar975b5272016-03-15 23:10:59 +010010334timers Compiled with |timer_start()| support.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010335title Compiled with window title support |'title'|.
10336toolbar Compiled with support for |gui-toolbar|.
Bram Moolenaar2cab0e12016-11-24 15:09:07 +010010337ttyin input is a terminal (tty)
10338ttyout output is a terminal (tty)
Bram Moolenaar37c64c72017-09-19 22:06:03 +020010339unix Unix version of Vim. *+unix*
Bram Moolenaar3df01732017-02-17 22:47:16 +010010340unnamedplus Compiled with support for "unnamedplus" in 'clipboard'
Bram Moolenaar071d4272004-06-13 20:20:40 +000010341user_commands User-defined commands.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +010010342vcon Win32: Virtual console support is working, can use
10343 'termguicolors'. Also see |+vtp|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010344vertsplit Compiled with vertically split windows |:vsplit|.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010345 (always true)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010346vim_starting True while initial source'ing takes place. |startup|
Bram Moolenaar4f3f6682016-03-26 23:01:59 +010010347 *vim_starting*
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010348viminfo Compiled with viminfo support.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010349virtualedit Compiled with 'virtualedit' option. (always true)
Bram Moolenaar5b69c222019-01-11 14:50:06 +010010350visual Compiled with Visual mode. (always true)
10351visualextra Compiled with extra Visual mode commands. (always
10352 true) |blockwise-operators|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010353vms VMS version of Vim.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010354vreplace Compiled with |gR| and |gr| commands. (always true)
Bram Moolenaar98ef2332018-03-18 14:44:37 +010010355vtp Compiled for vcon support |+vtp| (check vcon to find
Bram Moolenaar5a3a49e2018-03-20 18:35:53 +010010356 out if it works in the current console).
Bram Moolenaar071d4272004-06-13 20:20:40 +000010357wildignore Compiled with 'wildignore' option.
10358wildmenu Compiled with 'wildmenu' option.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010359win16 old version for MS-Windows 3.1 (always false)
Bram Moolenaard58e9292011-02-09 17:07:58 +010010360win32 Win32 version of Vim (MS-Windows 95 and later, 32 or
10361 64 bits)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010362win32unix Win32 version of Vim, using Unix files (Cygwin)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010363win64 Win64 version of Vim (MS-Windows 64 bit).
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010364win95 Win32 version for MS-Windows 95/98/ME (always false)
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +010010365winaltkeys Compiled with 'winaltkeys' option.
10366windows Compiled with support for more than one window.
Bram Moolenaar39536dd2019-01-29 22:58:21 +010010367 (always true)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010368writebackup Compiled with 'writebackup' default on.
10369xfontset Compiled with X fontset support |xfontset|.
10370xim Compiled with X input method support |xim|.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +020010371xpm Compiled with pixmap support.
10372xpm_w32 Compiled with pixmap support for Win32. (Only for
10373 backward compatibility. Use "xpm" instead.)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010374xsmp Compiled with X session management support.
10375xsmp_interact Compiled with interactive X session management support.
10376xterm_clipboard Compiled with support for xterm clipboard.
10377xterm_save Compiled with support for saving and restoring the
10378 xterm screen.
10379x11 Compiled with X11 support.
10380
10381 *string-match*
10382Matching a pattern in a String
10383
10384A regexp pattern as explained at |pattern| is normally used to find a match in
10385the buffer lines. When a pattern is used to find a match in a String, almost
10386everything works in the same way. The difference is that a String is handled
10387like it is one line. When it contains a "\n" character, this is not seen as a
10388line break for the pattern. It can be matched with a "\n" in the pattern, or
10389with ".". Example: >
10390 :let a = "aaaa\nxxxx"
10391 :echo matchstr(a, "..\n..")
10392 aa
10393 xx
10394 :echo matchstr(a, "a.x")
10395 a
10396 x
10397
10398Don't forget that "^" will only match at the first character of the String and
10399"$" at the last character of the string. They don't match after or before a
10400"\n".
10401
10402==============================================================================
104035. Defining functions *user-functions*
10404
10405New functions can be defined. These can be called just like builtin
10406functions. The function executes a sequence of Ex commands. Normal mode
10407commands can be executed with the |:normal| command.
10408
10409The function name must start with an uppercase letter, to avoid confusion with
10410builtin functions. To prevent from using the same name in different scripts
10411avoid obvious, short names. A good habit is to start the function name with
10412the name of the script, e.g., "HTMLcolor()".
10413
Bram Moolenaar92d640f2005-09-05 22:11:52 +000010414It's also possible to use curly braces, see |curly-braces-names|. And the
10415|autoload| facility is useful to define a function only when it's called.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010416
10417 *local-function*
10418A function local to a script must start with "s:". A local script function
10419can only be called from within the script and from functions, user commands
10420and autocommands defined in the script. It is also possible to call the
Bram Moolenaare37d50a2008-08-06 17:06:04 +000010421function from a mapping defined in the script, but then |<SID>| must be used
Bram Moolenaar071d4272004-06-13 20:20:40 +000010422instead of "s:" when the mapping is expanded outside of the script.
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010423There are only script-local functions, no buffer-local or window-local
10424functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010425
10426 *:fu* *:function* *E128* *E129* *E123*
10427:fu[nction] List all functions and their arguments.
10428
10429:fu[nction] {name} List function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010430 {name} can also be a |Dictionary| entry that is a
10431 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010432 :function dict.init
Bram Moolenaar92d640f2005-09-05 22:11:52 +000010433
10434:fu[nction] /{pattern} List functions with a name matching {pattern}.
10435 Example that lists all functions ending with "File": >
10436 :function /File$
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000010437<
10438 *:function-verbose*
10439When 'verbose' is non-zero, listing a function will also display where it was
10440last defined. Example: >
10441
10442 :verbose function SetFileTypeSH
10443 function SetFileTypeSH(name)
10444 Last set from /usr/share/vim/vim-7.0/filetype.vim
10445<
Bram Moolenaar8aff23a2005-08-19 20:40:30 +000010446See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +000010447
Bram Moolenaarbcb98982014-05-01 14:08:19 +020010448 *E124* *E125* *E853* *E884*
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010449:fu[nction][!] {name}([arguments]) [range] [abort] [dict] [closure]
Bram Moolenaar01164a62017-11-02 22:58:42 +010010450 Define a new function by the name {name}. The body of
10451 the function follows in the next lines, until the
10452 matching |:endfunction|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010010453
Bram Moolenaar01164a62017-11-02 22:58:42 +010010454 The name must be made of alphanumeric characters and
10455 '_', and must start with a capital or "s:" (see
10456 above). Note that using "b:" or "g:" is not allowed.
10457 (since patch 7.4.260 E884 is given if the function
10458 name has a colon in the name, e.g. for "foo:bar()".
10459 Before that patch no error was given).
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010460
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010461 {name} can also be a |Dictionary| entry that is a
10462 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010463 :function dict.init(arg)
Bram Moolenaar58b85342016-08-14 19:54:54 +020010464< "dict" must be an existing dictionary. The entry
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010465 "init" is added if it didn't exist yet. Otherwise [!]
Bram Moolenaar58b85342016-08-14 19:54:54 +020010466 is required to overwrite an existing function. The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010467 result is a |Funcref| to a numbered function. The
10468 function can only be used with a |Funcref| and will be
10469 deleted if there are no more references to it.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010470 *E127* *E122*
10471 When a function by this name already exists and [!] is
Bram Moolenaarded5f1b2018-11-10 17:33:29 +010010472 not used an error message is given. There is one
10473 exception: When sourcing a script again, a function
10474 that was previously defined in that script will be
10475 silently replaced.
10476 When [!] is used, an existing function is silently
10477 replaced. Unless it is currently being executed, that
10478 is an error.
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010479 NOTE: Use ! wisely. If used without care it can cause
10480 an existing function to be replaced unexpectedly,
10481 which is hard to debug.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010482
10483 For the {arguments} see |function-argument|.
10484
Bram Moolenaar8d043172014-01-23 14:24:41 +010010485 *:func-range* *a:firstline* *a:lastline*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010486 When the [range] argument is added, the function is
10487 expected to take care of a range itself. The range is
10488 passed as "a:firstline" and "a:lastline". If [range]
10489 is excluded, ":{range}call" will call the function for
10490 each line in the range, with the cursor on the start
10491 of each line. See |function-range-example|.
Bram Moolenaar2df58b42012-11-28 18:21:11 +010010492 The cursor is still moved to the first line of the
10493 range, as is the case with all Ex commands.
Bram Moolenaar8d043172014-01-23 14:24:41 +010010494 *:func-abort*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010495 When the [abort] argument is added, the function will
10496 abort as soon as an error is detected.
Bram Moolenaar8d043172014-01-23 14:24:41 +010010497 *:func-dict*
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000010498 When the [dict] argument is added, the function must
Bram Moolenaar58b85342016-08-14 19:54:54 +020010499 be invoked through an entry in a |Dictionary|. The
Bram Moolenaar2fda12f2005-01-15 22:14:15 +000010500 local variable "self" will then be set to the
10501 dictionary. See |Dictionary-function|.
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010502 *:func-closure* *E932*
10503 When the [closure] argument is added, the function
10504 can access variables and arguments from the outer
10505 scope. This is usually called a closure. In this
10506 example Bar() uses "x" from the scope of Foo(). It
10507 remains referenced even after Foo() returns: >
10508 :function! Foo()
10509 : let x = 0
10510 : function! Bar() closure
10511 : let x += 1
10512 : return x
10513 : endfunction
Bram Moolenaarbc8801c2016-08-02 21:04:33 +020010514 : return funcref('Bar')
Bram Moolenaar10ce39a2016-07-29 22:37:06 +020010515 :endfunction
10516
10517 :let F = Foo()
10518 :echo F()
10519< 1 >
10520 :echo F()
10521< 2 >
10522 :echo F()
10523< 3
Bram Moolenaar071d4272004-06-13 20:20:40 +000010524
Bram Moolenaar446cb832008-06-24 21:56:24 +000010525 *function-search-undo*
Bram Moolenaar98692072006-02-04 00:57:42 +000010526 The last used search pattern and the redo command "."
Bram Moolenaar446cb832008-06-24 21:56:24 +000010527 will not be changed by the function. This also
10528 implies that the effect of |:nohlsearch| is undone
10529 when the function returns.
Bram Moolenaar98692072006-02-04 00:57:42 +000010530
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010531 *:endf* *:endfunction* *E126* *E193* *W22*
Bram Moolenaar663bb232017-06-22 19:12:10 +020010532:endf[unction] [argument]
10533 The end of a function definition. Best is to put it
10534 on a line by its own, without [argument].
10535
10536 [argument] can be:
10537 | command command to execute next
10538 \n command command to execute next
10539 " comment always ignored
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010540 anything else ignored, warning given when
10541 'verbose' is non-zero
Bram Moolenaar663bb232017-06-22 19:12:10 +020010542 The support for a following command was added in Vim
10543 8.0.0654, before that any argument was silently
10544 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010545
Bram Moolenaarf8be4612017-06-23 20:52:40 +020010546 To be able to define a function inside an `:execute`
10547 command, use line breaks instead of |:bar|: >
10548 :exe "func Foo()\necho 'foo'\nendfunc"
10549<
Bram Moolenaar437bafe2016-08-01 15:40:54 +020010550 *:delf* *:delfunction* *E130* *E131* *E933*
Bram Moolenaar663bb232017-06-22 19:12:10 +020010551:delf[unction][!] {name}
10552 Delete function {name}.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010553 {name} can also be a |Dictionary| entry that is a
10554 |Funcref|: >
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010555 :delfunc dict.init
Bram Moolenaar58b85342016-08-14 19:54:54 +020010556< This will remove the "init" entry from "dict". The
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010557 function is deleted if there are no more references to
10558 it.
Bram Moolenaar663bb232017-06-22 19:12:10 +020010559 With the ! there is no error if the function does not
10560 exist.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010561 *:retu* *:return* *E133*
10562:retu[rn] [expr] Return from a function. When "[expr]" is given, it is
10563 evaluated and returned as the result of the function.
10564 If "[expr]" is not given, the number 0 is returned.
10565 When a function ends without an explicit ":return",
10566 the number 0 is returned.
10567 Note that there is no check for unreachable lines,
10568 thus there is no warning if commands follow ":return".
10569
10570 If the ":return" is used after a |:try| but before the
10571 matching |:finally| (if present), the commands
10572 following the ":finally" up to the matching |:endtry|
10573 are executed first. This process applies to all
10574 nested ":try"s inside the function. The function
10575 returns at the outermost ":endtry".
10576
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010577 *function-argument* *a:var*
Bram Moolenaar58b85342016-08-14 19:54:54 +020010578An argument can be defined by giving its name. In the function this can then
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010579be used as "a:name" ("a:" for argument).
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010580 *a:0* *a:1* *a:000* *E740* *...*
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010581Up to 20 arguments can be given, separated by commas. After the named
10582arguments an argument "..." can be specified, which means that more arguments
10583may optionally be following. In the function the extra arguments can be used
10584as "a:1", "a:2", etc. "a:0" is set to the number of extra arguments (which
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010585can be 0). "a:000" is set to a |List| that contains these arguments. Note
10586that "a:1" is the same as "a:000[0]".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000010587 *E742*
10588The a: scope and the variables in it cannot be changed, they are fixed.
Bram Moolenaar069c1e72016-07-15 21:25:08 +020010589However, if a composite type is used, such as |List| or |Dictionary| , you can
10590change their contents. Thus you can pass a |List| to a function and have the
10591function add an item to it. If you want to make sure the function cannot
10592change a |List| or |Dictionary| use |:lockvar|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010593
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010594When not using "...", the number of arguments in a function call must be equal
10595to the number of named arguments. When using "...", the number of arguments
10596may be larger.
10597
10598It is also possible to define a function without any arguments. You must
Bram Moolenaar01164a62017-11-02 22:58:42 +010010599still supply the () then.
10600
Bram Moolenaar98ef2332018-03-18 14:44:37 +010010601It is allowed to define another function inside a function body.
Bram Moolenaar8f999f12005-01-25 22:12:55 +000010602
10603 *local-variables*
Bram Moolenaar069c1e72016-07-15 21:25:08 +020010604Inside a function local variables can be used. These will disappear when the
10605function returns. Global variables need to be accessed with "g:".
Bram Moolenaar071d4272004-06-13 20:20:40 +000010606
10607Example: >
10608 :function Table(title, ...)
10609 : echohl Title
10610 : echo a:title
10611 : echohl None
Bram Moolenaar677ee682005-01-27 14:41:15 +000010612 : echo a:0 . " items:"
10613 : for s in a:000
10614 : echon ' ' . s
10615 : endfor
Bram Moolenaar071d4272004-06-13 20:20:40 +000010616 :endfunction
10617
10618This function can then be called with: >
Bram Moolenaar677ee682005-01-27 14:41:15 +000010619 call Table("Table", "line1", "line2")
10620 call Table("Empty Table")
Bram Moolenaar071d4272004-06-13 20:20:40 +000010621
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010622To return more than one value, return a |List|: >
10623 :function Compute(n1, n2)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010624 : if a:n2 == 0
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010625 : return ["fail", 0]
Bram Moolenaar071d4272004-06-13 20:20:40 +000010626 : endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010627 : return ["ok", a:n1 / a:n2]
Bram Moolenaar071d4272004-06-13 20:20:40 +000010628 :endfunction
10629
10630This function can then be called with: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010631 :let [success, div] = Compute(102, 6)
Bram Moolenaar071d4272004-06-13 20:20:40 +000010632 :if success == "ok"
10633 : echo div
10634 :endif
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010635<
Bram Moolenaar39f05632006-03-19 22:15:26 +000010636 *:cal* *:call* *E107* *E117*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010637:[range]cal[l] {name}([arguments])
10638 Call a function. The name of the function and its arguments
10639 are as specified with |:function|. Up to 20 arguments can be
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010640 used. The returned value is discarded.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010641 Without a range and for functions that accept a range, the
10642 function is called once. When a range is given the cursor is
10643 positioned at the start of the first line before executing the
10644 function.
10645 When a range is given and the function doesn't handle it
10646 itself, the function is executed for each line in the range,
10647 with the cursor in the first column of that line. The cursor
10648 is left at the last line (possibly moved by the last function
Bram Moolenaar58b85342016-08-14 19:54:54 +020010649 call). The arguments are re-evaluated for each line. Thus
Bram Moolenaar071d4272004-06-13 20:20:40 +000010650 this works:
10651 *function-range-example* >
10652 :function Mynumber(arg)
10653 : echo line(".") . " " . a:arg
10654 :endfunction
10655 :1,5call Mynumber(getline("."))
10656<
10657 The "a:firstline" and "a:lastline" are defined anyway, they
10658 can be used to do something different at the start or end of
10659 the range.
10660
10661 Example of a function that handles the range itself: >
10662
10663 :function Cont() range
10664 : execute (a:firstline + 1) . "," . a:lastline . 's/^/\t\\ '
10665 :endfunction
10666 :4,8call Cont()
10667<
10668 This function inserts the continuation character "\" in front
10669 of all the lines in the range, except the first one.
10670
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010671 When the function returns a composite value it can be further
10672 dereferenced, but the range will not be used then. Example: >
10673 :4,8call GetDict().method()
10674< Here GetDict() gets the range but method() does not.
10675
Bram Moolenaar071d4272004-06-13 20:20:40 +000010676 *E132*
10677The recursiveness of user functions is restricted with the |'maxfuncdepth'|
10678option.
10679
Bram Moolenaar7c626922005-02-07 22:01:03 +000010680
10681AUTOMATICALLY LOADING FUNCTIONS ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000010682 *autoload-functions*
10683When using many or large functions, it's possible to automatically define them
Bram Moolenaar7c626922005-02-07 22:01:03 +000010684only when they are used. There are two methods: with an autocommand and with
10685the "autoload" directory in 'runtimepath'.
10686
10687
10688Using an autocommand ~
10689
Bram Moolenaar05159a02005-02-26 23:04:13 +000010690This is introduced in the user manual, section |41.14|.
10691
Bram Moolenaar7c626922005-02-07 22:01:03 +000010692The autocommand is useful if you have a plugin that is a long Vim script file.
10693You can define the autocommand and quickly quit the script with |:finish|.
Bram Moolenaar58b85342016-08-14 19:54:54 +020010694That makes Vim startup faster. The autocommand should then load the same file
Bram Moolenaar7c626922005-02-07 22:01:03 +000010695again, setting a variable to skip the |:finish| command.
10696
10697Use the FuncUndefined autocommand event with a pattern that matches the
10698function(s) to be defined. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000010699
10700 :au FuncUndefined BufNet* source ~/vim/bufnetfuncs.vim
10701
10702The file "~/vim/bufnetfuncs.vim" should then define functions that start with
10703"BufNet". Also see |FuncUndefined|.
10704
Bram Moolenaar7c626922005-02-07 22:01:03 +000010705
10706Using an autoload script ~
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010707 *autoload* *E746*
Bram Moolenaar05159a02005-02-26 23:04:13 +000010708This is introduced in the user manual, section |41.15|.
10709
Bram Moolenaar7c626922005-02-07 22:01:03 +000010710Using a script in the "autoload" directory is simpler, but requires using
10711exactly the right file name. A function that can be autoloaded has a name
10712like this: >
10713
Bram Moolenaara7fc0102005-05-18 22:17:12 +000010714 :call filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000010715
10716When such a function is called, and it is not defined yet, Vim will search the
10717"autoload" directories in 'runtimepath' for a script file called
10718"filename.vim". For example "~/.vim/autoload/filename.vim". That file should
10719then define the function like this: >
10720
Bram Moolenaara7fc0102005-05-18 22:17:12 +000010721 function filename#funcname()
Bram Moolenaar7c626922005-02-07 22:01:03 +000010722 echo "Done!"
10723 endfunction
10724
Bram Moolenaar60a795a2005-09-16 21:55:43 +000010725The file name and the name used before the # in the function must match
Bram Moolenaar7c626922005-02-07 22:01:03 +000010726exactly, and the defined function must have the name exactly as it will be
10727called.
10728
Bram Moolenaara7fc0102005-05-18 22:17:12 +000010729It is possible to use subdirectories. Every # in the function name works like
10730a path separator. Thus when calling a function: >
Bram Moolenaar7c626922005-02-07 22:01:03 +000010731
Bram Moolenaara7fc0102005-05-18 22:17:12 +000010732 :call foo#bar#func()
Bram Moolenaar7c626922005-02-07 22:01:03 +000010733
10734Vim will look for the file "autoload/foo/bar.vim" in 'runtimepath'.
10735
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010736This also works when reading a variable that has not been set yet: >
10737
Bram Moolenaara7fc0102005-05-18 22:17:12 +000010738 :let l = foo#bar#lvar
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010739
Bram Moolenaara5792f52005-11-23 21:25:05 +000010740However, when the autoload script was already loaded it won't be loaded again
10741for an unknown variable.
10742
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010743When assigning a value to such a variable nothing special happens. This can
10744be used to pass settings to the autoload script before it's loaded: >
10745
Bram Moolenaara7fc0102005-05-18 22:17:12 +000010746 :let foo#bar#toggle = 1
10747 :call foo#bar#func()
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010748
Bram Moolenaar4399ef42005-02-12 14:29:27 +000010749Note that when you make a mistake and call a function that is supposed to be
10750defined in an autoload script, but the script doesn't actually define the
10751function, the script will be sourced every time you try to call the function.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010752And you will get an error message every time.
10753
10754Also note that if you have two script files, and one calls a function in the
Bram Moolenaar446cb832008-06-24 21:56:24 +000010755other and vice versa, before the used function is defined, it won't work.
Bram Moolenaar26a60b42005-02-22 08:49:11 +000010756Avoid using the autoload functionality at the toplevel.
Bram Moolenaar7c626922005-02-07 22:01:03 +000010757
Bram Moolenaar433f7c82006-03-21 21:29:36 +000010758Hint: If you distribute a bunch of scripts you can pack them together with the
10759|vimball| utility. Also read the user manual |distribute-script|.
10760
Bram Moolenaar071d4272004-06-13 20:20:40 +000010761==============================================================================
107626. Curly braces names *curly-braces-names*
10763
Bram Moolenaar84f72352012-03-11 15:57:40 +010010764In most places where you can use a variable, you can use a "curly braces name"
10765variable. This is a regular variable name with one or more expressions
10766wrapped in braces {} like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000010767 my_{adjective}_variable
10768
10769When Vim encounters this, it evaluates the expression inside the braces, puts
10770that in place of the expression, and re-interprets the whole as a variable
10771name. So in the above example, if the variable "adjective" was set to
10772"noisy", then the reference would be to "my_noisy_variable", whereas if
10773"adjective" was set to "quiet", then it would be to "my_quiet_variable".
10774
10775One application for this is to create a set of variables governed by an option
Bram Moolenaar58b85342016-08-14 19:54:54 +020010776value. For example, the statement >
Bram Moolenaar071d4272004-06-13 20:20:40 +000010777 echo my_{&background}_message
10778
10779would output the contents of "my_dark_message" or "my_light_message" depending
10780on the current value of 'background'.
10781
10782You can use multiple brace pairs: >
10783 echo my_{adverb}_{adjective}_message
10784..or even nest them: >
10785 echo my_{ad{end_of_word}}_message
10786where "end_of_word" is either "verb" or "jective".
10787
10788However, the expression inside the braces must evaluate to a valid single
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000010789variable name, e.g. this is invalid: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000010790 :let foo='a + b'
10791 :echo c{foo}d
10792.. since the result of expansion is "ca + bd", which is not a variable name.
10793
10794 *curly-braces-function-names*
10795You can call and define functions by an evaluated name in a similar way.
10796Example: >
10797 :let func_end='whizz'
10798 :call my_func_{func_end}(parameter)
10799
10800This would call the function "my_func_whizz(parameter)".
10801
Bram Moolenaar84f72352012-03-11 15:57:40 +010010802This does NOT work: >
10803 :let i = 3
10804 :let @{i} = '' " error
10805 :echo @{i} " error
10806
Bram Moolenaar071d4272004-06-13 20:20:40 +000010807==============================================================================
108087. Commands *expression-commands*
10809
10810:let {var-name} = {expr1} *:let* *E18*
10811 Set internal variable {var-name} to the result of the
10812 expression {expr1}. The variable will get the type
10813 from the {expr}. If {var-name} didn't exist yet, it
10814 is created.
10815
Bram Moolenaar13065c42005-01-08 16:08:21 +000010816:let {var-name}[{idx}] = {expr1} *E689*
10817 Set a list item to the result of the expression
10818 {expr1}. {var-name} must refer to a list and {idx}
10819 must be a valid index in that list. For nested list
10820 the index can be repeated.
Bram Moolenaar446cb832008-06-24 21:56:24 +000010821 This cannot be used to add an item to a |List|.
Bram Moolenaar58b85342016-08-14 19:54:54 +020010822 This cannot be used to set a byte in a String. You
Bram Moolenaar446cb832008-06-24 21:56:24 +000010823 can do that like this: >
10824 :let var = var[0:2] . 'X' . var[4:]
Bram Moolenaar6e5ea8d2019-01-12 22:47:31 +010010825< When {var-name} is a |Blob| then {idx} can be the
10826 length of the blob, in which case one byte is
10827 appended.
10828
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010829 *E711* *E719*
10830:let {var-name}[{idx1}:{idx2}] = {expr1} *E708* *E709* *E710*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010831 Set a sequence of items in a |List| to the result of
10832 the expression {expr1}, which must be a list with the
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000010833 correct number of items.
10834 {idx1} can be omitted, zero is used instead.
10835 {idx2} can be omitted, meaning the end of the list.
10836 When the selected range of items is partly past the
10837 end of the list, items will be added.
10838
Bram Moolenaarff697e62019-02-12 22:28:33 +010010839 *:let+=* *:let-=* *:letstar=*
10840 *:let/=* *:let%=* *:let.=* *E734*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010841:let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
10842:let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
Bram Moolenaarff697e62019-02-12 22:28:33 +010010843:let {var} *= {expr1} Like ":let {var} = {var} * {expr1}".
10844:let {var} /= {expr1} Like ":let {var} = {var} / {expr1}".
10845:let {var} %= {expr1} Like ":let {var} = {var} % {expr1}".
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010846:let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
10847 These fail if {var} was not set yet and when the type
10848 of {var} and {expr1} don't fit the operator.
10849
10850
Bram Moolenaar071d4272004-06-13 20:20:40 +000010851:let ${env-name} = {expr1} *:let-environment* *:let-$*
10852 Set environment variable {env-name} to the result of
10853 the expression {expr1}. The type is always String.
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010854:let ${env-name} .= {expr1}
10855 Append {expr1} to the environment variable {env-name}.
10856 If the environment variable didn't exist yet this
10857 works like "=".
Bram Moolenaar071d4272004-06-13 20:20:40 +000010858
10859:let @{reg-name} = {expr1} *:let-register* *:let-@*
10860 Write the result of the expression {expr1} in register
10861 {reg-name}. {reg-name} must be a single letter, and
10862 must be the name of a writable register (see
10863 |registers|). "@@" can be used for the unnamed
10864 register, "@/" for the search pattern.
10865 If the result of {expr1} ends in a <CR> or <NL>, the
10866 register will be linewise, otherwise it will be set to
10867 characterwise.
10868 This can be used to clear the last search pattern: >
10869 :let @/ = ""
10870< This is different from searching for an empty string,
10871 that would match everywhere.
10872
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010873:let @{reg-name} .= {expr1}
Bram Moolenaar58b85342016-08-14 19:54:54 +020010874 Append {expr1} to register {reg-name}. If the
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010875 register was empty it's like setting it to {expr1}.
10876
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010877:let &{option-name} = {expr1} *:let-option* *:let-&*
Bram Moolenaar071d4272004-06-13 20:20:40 +000010878 Set option {option-name} to the result of the
Bram Moolenaarfca34d62005-01-04 21:38:36 +000010879 expression {expr1}. A String or Number value is
10880 always converted to the type of the option.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010881 For an option local to a window or buffer the effect
10882 is just like using the |:set| command: both the local
Bram Moolenaara5fac542005-10-12 20:58:49 +000010883 value and the global value are changed.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000010884 Example: >
10885 :let &path = &path . ',/usr/local/include'
Bram Moolenaar3df01732017-02-17 22:47:16 +010010886< This also works for terminal codes in the form t_xx.
10887 But only for alphanumerical names. Example: >
10888 :let &t_k1 = "\<Esc>[234;"
10889< When the code does not exist yet it will be created as
10890 a terminal key code, there is no error.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010891
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010892:let &{option-name} .= {expr1}
10893 For a string option: Append {expr1} to the value.
10894 Does not insert a comma like |:set+=|.
10895
10896:let &{option-name} += {expr1}
10897:let &{option-name} -= {expr1}
10898 For a number or boolean option: Add or subtract
10899 {expr1}.
10900
Bram Moolenaar071d4272004-06-13 20:20:40 +000010901:let &l:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010902:let &l:{option-name} .= {expr1}
10903:let &l:{option-name} += {expr1}
10904:let &l:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000010905 Like above, but only set the local value of an option
10906 (if there is one). Works like |:setlocal|.
10907
10908:let &g:{option-name} = {expr1}
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010909:let &g:{option-name} .= {expr1}
10910:let &g:{option-name} += {expr1}
10911:let &g:{option-name} -= {expr1}
Bram Moolenaar071d4272004-06-13 20:20:40 +000010912 Like above, but only set the global value of an option
10913 (if there is one). Works like |:setglobal|.
10914
Bram Moolenaar13065c42005-01-08 16:08:21 +000010915:let [{name1}, {name2}, ...] = {expr1} *:let-unpack* *E687* *E688*
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010916 {expr1} must evaluate to a |List|. The first item in
Bram Moolenaarfca34d62005-01-04 21:38:36 +000010917 the list is assigned to {name1}, the second item to
10918 {name2}, etc.
10919 The number of names must match the number of items in
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010920 the |List|.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000010921 Each name can be one of the items of the ":let"
10922 command as mentioned above.
10923 Example: >
10924 :let [s, item] = GetItem(s)
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010925< Detail: {expr1} is evaluated first, then the
10926 assignments are done in sequence. This matters if
10927 {name2} depends on {name1}. Example: >
10928 :let x = [0, 1]
10929 :let i = 0
10930 :let [i, x[i]] = [1, 2]
10931 :echo x
10932< The result is [0, 2].
10933
10934:let [{name1}, {name2}, ...] .= {expr1}
10935:let [{name1}, {name2}, ...] += {expr1}
10936:let [{name1}, {name2}, ...] -= {expr1}
10937 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010938 |List| item.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000010939
10940:let [{name}, ..., ; {lastname}] = {expr1}
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010941 Like |:let-unpack| above, but the |List| may have more
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010942 items than there are names. A list of the remaining
10943 items is assigned to {lastname}. If there are no
10944 remaining items {lastname} is set to an empty list.
Bram Moolenaarfca34d62005-01-04 21:38:36 +000010945 Example: >
10946 :let [a, b; rest] = ["aval", "bval", 3, 4]
10947<
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000010948:let [{name}, ..., ; {lastname}] .= {expr1}
10949:let [{name}, ..., ; {lastname}] += {expr1}
10950:let [{name}, ..., ; {lastname}] -= {expr1}
10951 Like above, but append/add/subtract the value for each
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010952 |List| item.
Bram Moolenaar4a748032010-09-30 21:47:56 +020010953
10954 *E121*
Bram Moolenaar58b85342016-08-14 19:54:54 +020010955:let {var-name} .. List the value of variable {var-name}. Multiple
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000010956 variable names may be given. Special names recognized
10957 here: *E738*
Bram Moolenaarca003e12006-03-17 23:19:38 +000010958 g: global variables
10959 b: local buffer variables
10960 w: local window variables
Bram Moolenaar910f66f2006-04-05 20:41:53 +000010961 t: local tab page variables
Bram Moolenaarca003e12006-03-17 23:19:38 +000010962 s: script-local variables
10963 l: local function variables
Bram Moolenaardcaf10e2005-01-21 11:55:25 +000010964 v: Vim variables.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010965
Bram Moolenaard7ee7ce2005-01-03 21:02:03 +000010966:let List the values of all variables. The type of the
10967 variable is indicated before the value:
10968 <nothing> String
10969 # Number
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000010970 * Funcref
Bram Moolenaar071d4272004-06-13 20:20:40 +000010971
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000010972
Bram Moolenaaref2f6562007-05-06 13:32:59 +000010973:unl[et][!] {name} ... *:unlet* *:unl* *E108* *E795*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000010974 Remove the internal variable {name}. Several variable
10975 names can be given, they are all removed. The name
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010976 may also be a |List| or |Dictionary| item.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010977 With [!] no error message is given for non-existing
10978 variables.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010979 One or more items from a |List| can be removed: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000010980 :unlet list[3] " remove fourth item
10981 :unlet list[3:] " remove fourth item to last
Bram Moolenaar32466aa2006-02-24 23:53:04 +000010982< One item from a |Dictionary| can be removed at a time: >
Bram Moolenaar9cd15162005-01-16 22:02:49 +000010983 :unlet dict['two']
10984 :unlet dict.two
Bram Moolenaarc236c162008-07-13 17:41:49 +000010985< This is especially useful to clean up used global
10986 variables and script-local variables (these are not
10987 deleted when the script ends). Function-local
10988 variables are automatically deleted when the function
10989 ends.
Bram Moolenaar071d4272004-06-13 20:20:40 +000010990
Bram Moolenaar137374f2018-05-13 15:59:50 +020010991:unl[et] ${env-name} ... *:unlet-environment* *:unlet-$*
10992 Remove environment variable {env-name}.
10993 Can mix {name} and ${env-name} in one :unlet command.
10994 No error message is given for a non-existing
10995 variable, also without !.
10996 If the system does not support deleting an environment
10997 variable, it is made emtpy.
10998
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000010999:lockv[ar][!] [depth] {name} ... *:lockvar* *:lockv*
11000 Lock the internal variable {name}. Locking means that
11001 it can no longer be changed (until it is unlocked).
11002 A locked variable can be deleted: >
11003 :lockvar v
11004 :let v = 'asdf' " fails!
11005 :unlet v
Bram Moolenaare7877fe2017-02-20 22:35:33 +010011006< *E741* *E940*
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011007 If you try to change a locked variable you get an
Bram Moolenaare7877fe2017-02-20 22:35:33 +010011008 error message: "E741: Value is locked: {name}".
11009 If you try to lock or unlock a built-in variable you
11010 get an error message: "E940: Cannot lock or unlock
11011 variable {name}".
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011012
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011013 [depth] is relevant when locking a |List| or
11014 |Dictionary|. It specifies how deep the locking goes:
11015 1 Lock the |List| or |Dictionary| itself,
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011016 cannot add or remove items, but can
11017 still change their values.
11018 2 Also lock the values, cannot change
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011019 the items. If an item is a |List| or
11020 |Dictionary|, cannot add or remove
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011021 items, but can still change the
11022 values.
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011023 3 Like 2 but for the |List| /
11024 |Dictionary| in the |List| /
11025 |Dictionary|, one level deeper.
11026 The default [depth] is 2, thus when {name} is a |List|
11027 or |Dictionary| the values cannot be changed.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011028 *E743*
11029 For unlimited depth use [!] and omit [depth].
11030 However, there is a maximum depth of 100 to catch
11031 loops.
11032
Bram Moolenaar32466aa2006-02-24 23:53:04 +000011033 Note that when two variables refer to the same |List|
11034 and you lock one of them, the |List| will also be
Bram Moolenaar910f66f2006-04-05 20:41:53 +000011035 locked when used through the other variable.
11036 Example: >
Bram Moolenaar2ce06f62005-01-31 19:19:04 +000011037 :let l = [0, 1, 2, 3]
11038 :let cl = l
11039 :lockvar l
11040 :let cl[1] = 99 " won't work!
11041< You may want to make a copy of a list to avoid this.
11042 See |deepcopy()|.
11043
11044
11045:unlo[ckvar][!] [depth] {name} ... *:unlockvar* *:unlo*
11046 Unlock the internal variable {name}. Does the
11047 opposite of |:lockvar|.
11048
11049
Bram Moolenaar071d4272004-06-13 20:20:40 +000011050:if {expr1} *:if* *:endif* *:en* *E171* *E579* *E580*
11051:en[dif] Execute the commands until the next matching ":else"
11052 or ":endif" if {expr1} evaluates to non-zero.
11053
11054 From Vim version 4.5 until 5.0, every Ex command in
11055 between the ":if" and ":endif" is ignored. These two
11056 commands were just to allow for future expansions in a
Bram Moolenaar85084ef2016-01-17 22:26:33 +010011057 backward compatible way. Nesting was allowed. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +000011058 that any ":else" or ":elseif" was ignored, the "else"
11059 part was not executed either.
11060
11061 You can use this to remain compatible with older
11062 versions: >
11063 :if version >= 500
11064 : version-5-specific-commands
11065 :endif
11066< The commands still need to be parsed to find the
11067 "endif". Sometimes an older Vim has a problem with a
11068 new command. For example, ":silent" is recognized as
11069 a ":substitute" command. In that case ":execute" can
11070 avoid problems: >
11071 :if version >= 600
11072 : execute "silent 1,$delete"
11073 :endif
11074<
11075 NOTE: The ":append" and ":insert" commands don't work
11076 properly in between ":if" and ":endif".
11077
11078 *:else* *:el* *E581* *E583*
11079:el[se] Execute the commands until the next matching ":else"
11080 or ":endif" if they previously were not being
11081 executed.
11082
11083 *:elseif* *:elsei* *E582* *E584*
11084:elsei[f] {expr1} Short for ":else" ":if", with the addition that there
11085 is no extra ":endif".
11086
11087:wh[ile] {expr1} *:while* *:endwhile* *:wh* *:endw*
Bram Moolenaar3a3a7232005-01-17 22:16:15 +000011088 *E170* *E585* *E588* *E733*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011089:endw[hile] Repeat the commands between ":while" and ":endwhile",
11090 as long as {expr1} evaluates to non-zero.
11091 When an error is detected from a command inside the
11092 loop, execution continues after the "endwhile".
Bram Moolenaar12805862005-01-05 22:16:17 +000011093 Example: >
11094 :let lnum = 1
11095 :while lnum <= line("$")
11096 :call FixLine(lnum)
11097 :let lnum = lnum + 1
11098 :endwhile
11099<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011100 NOTE: The ":append" and ":insert" commands don't work
Bram Moolenaard8b02732005-01-14 21:48:43 +000011101 properly inside a ":while" and ":for" loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011102
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011103:for {var} in {object} *:for* *E690* *E732*
Bram Moolenaar12805862005-01-05 22:16:17 +000011104:endfo[r] *:endfo* *:endfor*
11105 Repeat the commands between ":for" and ":endfor" for
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011106 each item in {object}. {object} can be a |List| or
11107 a |Blob|. Variable {var} is set to the value of each
11108 item. When an error is detected for a command inside
11109 the loop, execution continues after the "endfor".
11110 Changing {object} inside the loop affects what items
11111 are used. Make a copy if this is unwanted: >
Bram Moolenaarde8866b2005-01-06 23:24:37 +000011112 :for item in copy(mylist)
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011113<
11114 When {object} is a |List| and not making a copy, Vim
11115 stores a reference to the next item in the |List|
11116 before executing the commands with the current item.
11117 Thus the current item can be removed without effect.
11118 Removing any later item means it will not be found.
11119 Thus the following example works (an inefficient way
11120 to make a |List| empty): >
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011121 for item in mylist
11122 call remove(mylist, 0)
11123 endfor
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011124< Note that reordering the |List| (e.g., with sort() or
Bram Moolenaar9588a0f2005-01-08 21:45:39 +000011125 reverse()) may have unexpected effects.
Bram Moolenaar12805862005-01-05 22:16:17 +000011126
Bram Moolenaar5e66b422019-01-24 21:58:10 +010011127 When {object} is a |Blob|, Vim always makes a copy to
11128 iterate over. Unlike with |List|, modifying the
11129 |Blob| does not affect the iteration.
11130
Bram Moolenaar12805862005-01-05 22:16:17 +000011131:for [{var1}, {var2}, ...] in {listlist}
11132:endfo[r]
11133 Like ":for" above, but each item in {listlist} must be
11134 a list, of which each item is assigned to {var1},
11135 {var2}, etc. Example: >
11136 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
11137 :echo getline(lnum)[col]
11138 :endfor
11139<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011140 *:continue* *:con* *E586*
Bram Moolenaar12805862005-01-05 22:16:17 +000011141:con[tinue] When used inside a ":while" or ":for" loop, jumps back
11142 to the start of the loop.
11143 If it is used after a |:try| inside the loop but
11144 before the matching |:finally| (if present), the
11145 commands following the ":finally" up to the matching
11146 |:endtry| are executed first. This process applies to
11147 all nested ":try"s inside the loop. The outermost
11148 ":endtry" then jumps back to the start of the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011149
11150 *:break* *:brea* *E587*
Bram Moolenaar12805862005-01-05 22:16:17 +000011151:brea[k] When used inside a ":while" or ":for" loop, skips to
11152 the command after the matching ":endwhile" or
11153 ":endfor".
11154 If it is used after a |:try| inside the loop but
11155 before the matching |:finally| (if present), the
11156 commands following the ":finally" up to the matching
11157 |:endtry| are executed first. This process applies to
11158 all nested ":try"s inside the loop. The outermost
11159 ":endtry" then jumps to the command after the loop.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011160
11161:try *:try* *:endt* *:endtry* *E600* *E601* *E602*
11162:endt[ry] Change the error handling for the commands between
11163 ":try" and ":endtry" including everything being
11164 executed across ":source" commands, function calls,
11165 or autocommand invocations.
11166
11167 When an error or interrupt is detected and there is
11168 a |:finally| command following, execution continues
11169 after the ":finally". Otherwise, or when the
11170 ":endtry" is reached thereafter, the next
11171 (dynamically) surrounding ":try" is checked for
11172 a corresponding ":finally" etc. Then the script
11173 processing is terminated. (Whether a function
11174 definition has an "abort" argument does not matter.)
11175 Example: >
11176 :try | edit too much | finally | echo "cleanup" | endtry
11177 :echo "impossible" " not reached, script terminated above
11178<
11179 Moreover, an error or interrupt (dynamically) inside
11180 ":try" and ":endtry" is converted to an exception. It
11181 can be caught as if it were thrown by a |:throw|
11182 command (see |:catch|). In this case, the script
11183 processing is not terminated.
11184
11185 The value "Vim:Interrupt" is used for an interrupt
11186 exception. An error in a Vim command is converted
11187 to a value of the form "Vim({command}):{errmsg}",
11188 other errors are converted to a value of the form
11189 "Vim:{errmsg}". {command} is the full command name,
11190 and {errmsg} is the message that is displayed if the
11191 error exception is not caught, always beginning with
11192 the error number.
11193 Examples: >
11194 :try | sleep 100 | catch /^Vim:Interrupt$/ | endtry
11195 :try | edit | catch /^Vim(edit):E\d\+/ | echo "error" | endtry
11196<
11197 *:cat* *:catch* *E603* *E604* *E605*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011198:cat[ch] /{pattern}/ The following commands until the next |:catch|,
Bram Moolenaar071d4272004-06-13 20:20:40 +000011199 |:finally|, or |:endtry| that belongs to the same
11200 |:try| as the ":catch" are executed when an exception
11201 matching {pattern} is being thrown and has not yet
11202 been caught by a previous ":catch". Otherwise, these
11203 commands are skipped.
11204 When {pattern} is omitted all errors are caught.
11205 Examples: >
11206 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
11207 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
11208 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
11209 :catch /^Vim(write):/ " catch all errors in :write
11210 :catch /^Vim\%((\a\+)\)\=:E123/ " catch error E123
11211 :catch /my-exception/ " catch user exception
11212 :catch /.*/ " catch everything
11213 :catch " same as /.*/
11214<
11215 Another character can be used instead of / around the
11216 {pattern}, so long as it does not have a special
11217 meaning (e.g., '|' or '"') and doesn't occur inside
11218 {pattern}.
Bram Moolenaar7e38ea22014-04-05 22:55:53 +020011219 Information about the exception is available in
11220 |v:exception|. Also see |throw-variables|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011221 NOTE: It is not reliable to ":catch" the TEXT of
11222 an error message because it may vary in different
11223 locales.
11224
11225 *:fina* *:finally* *E606* *E607*
11226:fina[lly] The following commands until the matching |:endtry|
11227 are executed whenever the part between the matching
11228 |:try| and the ":finally" is left: either by falling
11229 through to the ":finally" or by a |:continue|,
11230 |:break|, |:finish|, or |:return|, or by an error or
11231 interrupt or exception (see |:throw|).
11232
11233 *:th* *:throw* *E608*
11234:th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
11235 If the ":throw" is used after a |:try| but before the
11236 first corresponding |:catch|, commands are skipped
11237 until the first ":catch" matching {expr1} is reached.
11238 If there is no such ":catch" or if the ":throw" is
11239 used after a ":catch" but before the |:finally|, the
11240 commands following the ":finally" (if present) up to
11241 the matching |:endtry| are executed. If the ":throw"
11242 is after the ":finally", commands up to the ":endtry"
11243 are skipped. At the ":endtry", this process applies
11244 again for the next dynamically surrounding ":try"
11245 (which may be found in a calling function or sourcing
11246 script), until a matching ":catch" has been found.
11247 If the exception is not caught, the command processing
11248 is terminated.
11249 Example: >
11250 :try | throw "oops" | catch /^oo/ | echo "caught" | endtry
Bram Moolenaar662db672011-03-22 14:05:35 +010011251< Note that "catch" may need to be on a separate line
11252 for when an error causes the parsing to skip the whole
11253 line and not see the "|" that separates the commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011254
11255 *:ec* *:echo*
11256:ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
11257 first {expr1} starts on a new line.
11258 Also see |:comment|.
11259 Use "\n" to start a new line. Use "\r" to move the
11260 cursor to the first column.
11261 Uses the highlighting set by the |:echohl| command.
11262 Cannot be followed by a comment.
11263 Example: >
11264 :echo "the value of 'shell' is" &shell
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011265< *:echo-redraw*
11266 A later redraw may make the message disappear again.
11267 And since Vim mostly postpones redrawing until it's
11268 finished with a sequence of commands this happens
11269 quite often. To avoid that a command from before the
11270 ":echo" causes a redraw afterwards (redraws are often
11271 postponed until you type something), force a redraw
11272 with the |:redraw| command. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000011273 :new | redraw | echo "there is a new window"
11274<
11275 *:echon*
11276:echon {expr1} .. Echoes each {expr1}, without anything added. Also see
11277 |:comment|.
11278 Uses the highlighting set by the |:echohl| command.
11279 Cannot be followed by a comment.
11280 Example: >
11281 :echon "the value of 'shell' is " &shell
11282<
11283 Note the difference between using ":echo", which is a
11284 Vim command, and ":!echo", which is an external shell
11285 command: >
11286 :!echo % --> filename
11287< The arguments of ":!" are expanded, see |:_%|. >
11288 :!echo "%" --> filename or "filename"
11289< Like the previous example. Whether you see the double
11290 quotes or not depends on your 'shell'. >
11291 :echo % --> nothing
11292< The '%' is an illegal character in an expression. >
11293 :echo "%" --> %
11294< This just echoes the '%' character. >
11295 :echo expand("%") --> filename
11296< This calls the expand() function to expand the '%'.
11297
11298 *:echoh* *:echohl*
11299:echoh[l] {name} Use the highlight group {name} for the following
11300 |:echo|, |:echon| and |:echomsg| commands. Also used
11301 for the |input()| prompt. Example: >
11302 :echohl WarningMsg | echo "Don't panic!" | echohl None
11303< Don't forget to set the group back to "None",
11304 otherwise all following echo's will be highlighted.
11305
11306 *:echom* *:echomsg*
11307:echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
11308 message in the |message-history|.
11309 Spaces are placed between the arguments as with the
11310 |:echo| command. But unprintable characters are
11311 displayed, not interpreted.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011312 The parsing works slightly different from |:echo|,
11313 more like |:execute|. All the expressions are first
11314 evaluated and concatenated before echoing anything.
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010011315 If expressions does not evaluate to a Number or
11316 String, string() is used to turn it into a string.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011317 Uses the highlighting set by the |:echohl| command.
11318 Example: >
11319 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
Bram Moolenaaref2f6562007-05-06 13:32:59 +000011320< See |:echo-redraw| to avoid the message disappearing
11321 when the screen is redrawn.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011322 *:echoe* *:echoerr*
11323:echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
11324 message in the |message-history|. When used in a
11325 script or function the line number will be added.
11326 Spaces are placed between the arguments as with the
Bram Moolenaar461a7fc2018-12-22 13:28:07 +010011327 |:echomsg| command. When used inside a try conditional,
Bram Moolenaar071d4272004-06-13 20:20:40 +000011328 the message is raised as an error exception instead
11329 (see |try-echoerr|).
11330 Example: >
11331 :echoerr "This script just failed!"
11332< If you just want a highlighted message use |:echohl|.
11333 And to get a beep: >
11334 :exe "normal \<Esc>"
11335<
11336 *:exe* *:execute*
11337:exe[cute] {expr1} .. Executes the string that results from the evaluation
Bram Moolenaar00a927d2010-05-14 23:24:24 +020011338 of {expr1} as an Ex command.
11339 Multiple arguments are concatenated, with a space in
11340 between. To avoid the extra space use the "."
11341 operator to concatenate strings into one argument.
11342 {expr1} is used as the processed command, command line
11343 editing keys are not recognized.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011344 Cannot be followed by a comment.
11345 Examples: >
Bram Moolenaar00a927d2010-05-14 23:24:24 +020011346 :execute "buffer" nextbuf
11347 :execute "normal" count . "w"
Bram Moolenaar071d4272004-06-13 20:20:40 +000011348<
11349 ":execute" can be used to append a command to commands
11350 that don't accept a '|'. Example: >
11351 :execute '!ls' | echo "theend"
11352
11353< ":execute" is also a nice way to avoid having to type
11354 control characters in a Vim script for a ":normal"
11355 command: >
11356 :execute "normal ixxx\<Esc>"
11357< This has an <Esc> character, see |expr-string|.
11358
Bram Moolenaar446cb832008-06-24 21:56:24 +000011359 Be careful to correctly escape special characters in
11360 file names. The |fnameescape()| function can be used
Bram Moolenaar05bb9532008-07-04 09:44:11 +000011361 for Vim commands, |shellescape()| for |:!| commands.
11362 Examples: >
Bram Moolenaar446cb832008-06-24 21:56:24 +000011363 :execute "e " . fnameescape(filename)
Bram Moolenaar251835e2014-02-24 02:51:51 +010011364 :execute "!ls " . shellescape(filename, 1)
Bram Moolenaar446cb832008-06-24 21:56:24 +000011365<
Bram Moolenaar071d4272004-06-13 20:20:40 +000011366 Note: The executed string may be any command-line, but
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +010011367 starting or ending "if", "while" and "for" does not
11368 always work, because when commands are skipped the
11369 ":execute" is not evaluated and Vim loses track of
11370 where blocks start and end. Also "break" and
11371 "continue" should not be inside ":execute".
11372 This example does not work, because the ":execute" is
11373 not evaluated and Vim does not see the "while", and
11374 gives an error for finding an ":endwhile": >
11375 :if 0
11376 : execute 'while i > 5'
11377 : echo "test"
11378 : endwhile
11379 :endif
Bram Moolenaar071d4272004-06-13 20:20:40 +000011380<
11381 It is allowed to have a "while" or "if" command
11382 completely in the executed string: >
11383 :execute 'while i < 5 | echo i | let i = i + 1 | endwhile'
11384<
11385
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010011386 *:exe-comment*
Bram Moolenaar071d4272004-06-13 20:20:40 +000011387 ":execute", ":echo" and ":echon" cannot be followed by
11388 a comment directly, because they see the '"' as the
11389 start of a string. But, you can use '|' followed by a
11390 comment. Example: >
11391 :echo "foo" | "this is a comment
11392
11393==============================================================================
113948. Exception handling *exception-handling*
11395
11396The Vim script language comprises an exception handling feature. This section
11397explains how it can be used in a Vim script.
11398
11399Exceptions may be raised by Vim on an error or on interrupt, see
11400|catch-errors| and |catch-interrupt|. You can also explicitly throw an
11401exception by using the ":throw" command, see |throw-catch|.
11402
11403
11404TRY CONDITIONALS *try-conditionals*
11405
11406Exceptions can be caught or can cause cleanup code to be executed. You can
11407use a try conditional to specify catch clauses (that catch exceptions) and/or
11408a finally clause (to be executed for cleanup).
11409 A try conditional begins with a |:try| command and ends at the matching
11410|:endtry| command. In between, you can use a |:catch| command to start
11411a catch clause, or a |:finally| command to start a finally clause. There may
11412be none or multiple catch clauses, but there is at most one finally clause,
11413which must not be followed by any catch clauses. The lines before the catch
11414clauses and the finally clause is called a try block. >
11415
11416 :try
Bram Moolenaar446cb832008-06-24 21:56:24 +000011417 : ...
11418 : ... TRY BLOCK
11419 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011420 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000011421 : ...
11422 : ... CATCH CLAUSE
11423 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011424 :catch /{pattern}/
Bram Moolenaar446cb832008-06-24 21:56:24 +000011425 : ...
11426 : ... CATCH CLAUSE
11427 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011428 :finally
Bram Moolenaar446cb832008-06-24 21:56:24 +000011429 : ...
11430 : ... FINALLY CLAUSE
11431 : ...
Bram Moolenaar071d4272004-06-13 20:20:40 +000011432 :endtry
11433
11434The try conditional allows to watch code for exceptions and to take the
11435appropriate actions. Exceptions from the try block may be caught. Exceptions
11436from the try block and also the catch clauses may cause cleanup actions.
11437 When no exception is thrown during execution of the try block, the control
11438is transferred to the finally clause, if present. After its execution, the
11439script continues with the line following the ":endtry".
11440 When an exception occurs during execution of the try block, the remaining
11441lines in the try block are skipped. The exception is matched against the
11442patterns specified as arguments to the ":catch" commands. The catch clause
11443after the first matching ":catch" is taken, other catch clauses are not
11444executed. The catch clause ends when the next ":catch", ":finally", or
11445":endtry" command is reached - whatever is first. Then, the finally clause
11446(if present) is executed. When the ":endtry" is reached, the script execution
11447continues in the following line as usual.
11448 When an exception that does not match any of the patterns specified by the
11449":catch" commands is thrown in the try block, the exception is not caught by
11450that try conditional and none of the catch clauses is executed. Only the
11451finally clause, if present, is taken. The exception pends during execution of
11452the finally clause. It is resumed at the ":endtry", so that commands after
11453the ":endtry" are not executed and the exception might be caught elsewhere,
11454see |try-nesting|.
11455 When during execution of a catch clause another exception is thrown, the
Bram Moolenaar58b85342016-08-14 19:54:54 +020011456remaining lines in that catch clause are not executed. The new exception is
Bram Moolenaar071d4272004-06-13 20:20:40 +000011457not matched against the patterns in any of the ":catch" commands of the same
11458try conditional and none of its catch clauses is taken. If there is, however,
11459a finally clause, it is executed, and the exception pends during its
11460execution. The commands following the ":endtry" are not executed. The new
11461exception might, however, be caught elsewhere, see |try-nesting|.
11462 When during execution of the finally clause (if present) an exception is
Bram Moolenaar58b85342016-08-14 19:54:54 +020011463thrown, the remaining lines in the finally clause are skipped. If the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000011464clause has been taken because of an exception from the try block or one of the
11465catch clauses, the original (pending) exception is discarded. The commands
11466following the ":endtry" are not executed, and the exception from the finally
11467clause is propagated and can be caught elsewhere, see |try-nesting|.
11468
11469The finally clause is also executed, when a ":break" or ":continue" for
11470a ":while" loop enclosing the complete try conditional is executed from the
11471try block or a catch clause. Or when a ":return" or ":finish" is executed
11472from the try block or a catch clause of a try conditional in a function or
11473sourced script, respectively. The ":break", ":continue", ":return", or
11474":finish" pends during execution of the finally clause and is resumed when the
11475":endtry" is reached. It is, however, discarded when an exception is thrown
11476from the finally clause.
11477 When a ":break" or ":continue" for a ":while" loop enclosing the complete
11478try conditional or when a ":return" or ":finish" is encountered in the finally
11479clause, the rest of the finally clause is skipped, and the ":break",
11480":continue", ":return" or ":finish" is executed as usual. If the finally
11481clause has been taken because of an exception or an earlier ":break",
11482":continue", ":return", or ":finish" from the try block or a catch clause,
11483this pending exception or command is discarded.
11484
11485For examples see |throw-catch| and |try-finally|.
11486
11487
11488NESTING OF TRY CONDITIONALS *try-nesting*
11489
11490Try conditionals can be nested arbitrarily. That is, a complete try
11491conditional can be put into the try block, a catch clause, or the finally
11492clause of another try conditional. If the inner try conditional does not
11493catch an exception thrown in its try block or throws a new exception from one
11494of its catch clauses or its finally clause, the outer try conditional is
11495checked according to the rules above. If the inner try conditional is in the
11496try block of the outer try conditional, its catch clauses are checked, but
Bram Moolenaar58b85342016-08-14 19:54:54 +020011497otherwise only the finally clause is executed. It does not matter for
Bram Moolenaar071d4272004-06-13 20:20:40 +000011498nesting, whether the inner try conditional is directly contained in the outer
11499one, or whether the outer one sources a script or calls a function containing
11500the inner try conditional.
11501
11502When none of the active try conditionals catches an exception, just their
11503finally clauses are executed. Thereafter, the script processing terminates.
11504An error message is displayed in case of an uncaught exception explicitly
11505thrown by a ":throw" command. For uncaught error and interrupt exceptions
11506implicitly raised by Vim, the error message(s) or interrupt message are shown
11507as usual.
11508
11509For examples see |throw-catch|.
11510
11511
11512EXAMINING EXCEPTION HANDLING CODE *except-examine*
11513
11514Exception handling code can get tricky. If you are in doubt what happens, set
11515'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
11516script file. Then you see when an exception is thrown, discarded, caught, or
11517finished. When using a verbosity level of at least 14, things pending in
11518a finally clause are also shown. This information is also given in debug mode
11519(see |debug-scripts|).
11520
11521
11522THROWING AND CATCHING EXCEPTIONS *throw-catch*
11523
11524You can throw any number or string as an exception. Use the |:throw| command
11525and pass the value to be thrown as argument: >
11526 :throw 4711
11527 :throw "string"
11528< *throw-expression*
11529You can also specify an expression argument. The expression is then evaluated
11530first, and the result is thrown: >
11531 :throw 4705 + strlen("string")
11532 :throw strpart("strings", 0, 6)
11533
11534An exception might be thrown during evaluation of the argument of the ":throw"
11535command. Unless it is caught there, the expression evaluation is abandoned.
11536The ":throw" command then does not throw a new exception.
11537 Example: >
11538
11539 :function! Foo(arg)
11540 : try
11541 : throw a:arg
11542 : catch /foo/
11543 : endtry
11544 : return 1
11545 :endfunction
11546 :
11547 :function! Bar()
11548 : echo "in Bar"
11549 : return 4710
11550 :endfunction
11551 :
11552 :throw Foo("arrgh") + Bar()
11553
11554This throws "arrgh", and "in Bar" is not displayed since Bar() is not
11555executed. >
11556 :throw Foo("foo") + Bar()
11557however displays "in Bar" and throws 4711.
11558
11559Any other command that takes an expression as argument might also be
Bram Moolenaar58b85342016-08-14 19:54:54 +020011560abandoned by an (uncaught) exception during the expression evaluation. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000011561exception is then propagated to the caller of the command.
11562 Example: >
11563
11564 :if Foo("arrgh")
11565 : echo "then"
11566 :else
11567 : echo "else"
11568 :endif
11569
11570Here neither of "then" or "else" is displayed.
11571
11572 *catch-order*
11573Exceptions can be caught by a try conditional with one or more |:catch|
11574commands, see |try-conditionals|. The values to be caught by each ":catch"
11575command can be specified as a pattern argument. The subsequent catch clause
11576gets executed when a matching exception is caught.
11577 Example: >
11578
11579 :function! Foo(value)
11580 : try
11581 : throw a:value
11582 : catch /^\d\+$/
11583 : echo "Number thrown"
11584 : catch /.*/
11585 : echo "String thrown"
11586 : endtry
11587 :endfunction
11588 :
11589 :call Foo(0x1267)
11590 :call Foo('string')
11591
11592The first call to Foo() displays "Number thrown", the second "String thrown".
11593An exception is matched against the ":catch" commands in the order they are
11594specified. Only the first match counts. So you should place the more
11595specific ":catch" first. The following order does not make sense: >
11596
11597 : catch /.*/
11598 : echo "String thrown"
11599 : catch /^\d\+$/
11600 : echo "Number thrown"
11601
11602The first ":catch" here matches always, so that the second catch clause is
11603never taken.
11604
11605 *throw-variables*
11606If you catch an exception by a general pattern, you may access the exact value
11607in the variable |v:exception|: >
11608
11609 : catch /^\d\+$/
11610 : echo "Number thrown. Value is" v:exception
11611
11612You may also be interested where an exception was thrown. This is stored in
11613|v:throwpoint|. Note that "v:exception" and "v:throwpoint" are valid for the
11614exception most recently caught as long it is not finished.
11615 Example: >
11616
11617 :function! Caught()
11618 : if v:exception != ""
11619 : echo 'Caught "' . v:exception . '" in ' . v:throwpoint
11620 : else
11621 : echo 'Nothing caught'
11622 : endif
11623 :endfunction
11624 :
11625 :function! Foo()
11626 : try
11627 : try
11628 : try
11629 : throw 4711
11630 : finally
11631 : call Caught()
11632 : endtry
11633 : catch /.*/
11634 : call Caught()
11635 : throw "oops"
11636 : endtry
11637 : catch /.*/
11638 : call Caught()
11639 : finally
11640 : call Caught()
11641 : endtry
11642 :endfunction
11643 :
11644 :call Foo()
11645
11646This displays >
11647
11648 Nothing caught
11649 Caught "4711" in function Foo, line 4
11650 Caught "oops" in function Foo, line 10
11651 Nothing caught
11652
11653A practical example: The following command ":LineNumber" displays the line
11654number in the script or function where it has been used: >
11655
11656 :function! LineNumber()
11657 : return substitute(v:throwpoint, '.*\D\(\d\+\).*', '\1', "")
11658 :endfunction
11659 :command! LineNumber try | throw "" | catch | echo LineNumber() | endtry
11660<
11661 *try-nested*
11662An exception that is not caught by a try conditional can be caught by
11663a surrounding try conditional: >
11664
11665 :try
11666 : try
11667 : throw "foo"
11668 : catch /foobar/
11669 : echo "foobar"
11670 : finally
11671 : echo "inner finally"
11672 : endtry
11673 :catch /foo/
11674 : echo "foo"
11675 :endtry
11676
11677The inner try conditional does not catch the exception, just its finally
11678clause is executed. The exception is then caught by the outer try
11679conditional. The example displays "inner finally" and then "foo".
11680
11681 *throw-from-catch*
11682You can catch an exception and throw a new one to be caught elsewhere from the
11683catch clause: >
11684
11685 :function! Foo()
11686 : throw "foo"
11687 :endfunction
11688 :
11689 :function! Bar()
11690 : try
11691 : call Foo()
11692 : catch /foo/
11693 : echo "Caught foo, throw bar"
11694 : throw "bar"
11695 : endtry
11696 :endfunction
11697 :
11698 :try
11699 : call Bar()
11700 :catch /.*/
11701 : echo "Caught" v:exception
11702 :endtry
11703
11704This displays "Caught foo, throw bar" and then "Caught bar".
11705
11706 *rethrow*
11707There is no real rethrow in the Vim script language, but you may throw
11708"v:exception" instead: >
11709
11710 :function! Bar()
11711 : try
11712 : call Foo()
11713 : catch /.*/
11714 : echo "Rethrow" v:exception
11715 : throw v:exception
11716 : endtry
11717 :endfunction
11718< *try-echoerr*
11719Note that this method cannot be used to "rethrow" Vim error or interrupt
11720exceptions, because it is not possible to fake Vim internal exceptions.
11721Trying so causes an error exception. You should throw your own exception
11722denoting the situation. If you want to cause a Vim error exception containing
11723the original error exception value, you can use the |:echoerr| command: >
11724
11725 :try
11726 : try
11727 : asdf
11728 : catch /.*/
11729 : echoerr v:exception
11730 : endtry
11731 :catch /.*/
11732 : echo v:exception
11733 :endtry
11734
11735This code displays
11736
Bram Moolenaar446cb832008-06-24 21:56:24 +000011737 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000011738
11739
11740CLEANUP CODE *try-finally*
11741
11742Scripts often change global settings and restore them at their end. If the
11743user however interrupts the script by pressing CTRL-C, the settings remain in
Bram Moolenaar58b85342016-08-14 19:54:54 +020011744an inconsistent state. The same may happen to you in the development phase of
Bram Moolenaar071d4272004-06-13 20:20:40 +000011745a script when an error occurs or you explicitly throw an exception without
11746catching it. You can solve these problems by using a try conditional with
11747a finally clause for restoring the settings. Its execution is guaranteed on
11748normal control flow, on error, on an explicit ":throw", and on interrupt.
11749(Note that errors and interrupts from inside the try conditional are converted
Bram Moolenaar58b85342016-08-14 19:54:54 +020011750to exceptions. When not caught, they terminate the script after the finally
Bram Moolenaar071d4272004-06-13 20:20:40 +000011751clause has been executed.)
11752Example: >
11753
11754 :try
11755 : let s:saved_ts = &ts
11756 : set ts=17
11757 :
11758 : " Do the hard work here.
11759 :
11760 :finally
11761 : let &ts = s:saved_ts
11762 : unlet s:saved_ts
11763 :endtry
11764
11765This method should be used locally whenever a function or part of a script
11766changes global settings which need to be restored on failure or normal exit of
11767that function or script part.
11768
11769 *break-finally*
11770Cleanup code works also when the try block or a catch clause is left by
11771a ":continue", ":break", ":return", or ":finish".
11772 Example: >
11773
11774 :let first = 1
11775 :while 1
11776 : try
11777 : if first
11778 : echo "first"
11779 : let first = 0
11780 : continue
11781 : else
11782 : throw "second"
11783 : endif
11784 : catch /.*/
11785 : echo v:exception
11786 : break
11787 : finally
11788 : echo "cleanup"
11789 : endtry
11790 : echo "still in while"
11791 :endwhile
11792 :echo "end"
11793
11794This displays "first", "cleanup", "second", "cleanup", and "end". >
11795
11796 :function! Foo()
11797 : try
11798 : return 4711
11799 : finally
11800 : echo "cleanup\n"
11801 : endtry
11802 : echo "Foo still active"
11803 :endfunction
11804 :
11805 :echo Foo() "returned by Foo"
11806
11807This displays "cleanup" and "4711 returned by Foo". You don't need to add an
Bram Moolenaar58b85342016-08-14 19:54:54 +020011808extra ":return" in the finally clause. (Above all, this would override the
Bram Moolenaar071d4272004-06-13 20:20:40 +000011809return value.)
11810
11811 *except-from-finally*
11812Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
11813a finally clause is possible, but not recommended since it abandons the
11814cleanup actions for the try conditional. But, of course, interrupt and error
11815exceptions might get raised from a finally clause.
11816 Example where an error in the finally clause stops an interrupt from
11817working correctly: >
11818
11819 :try
11820 : try
11821 : echo "Press CTRL-C for interrupt"
11822 : while 1
11823 : endwhile
11824 : finally
11825 : unlet novar
11826 : endtry
11827 :catch /novar/
11828 :endtry
11829 :echo "Script still running"
11830 :sleep 1
11831
11832If you need to put commands that could fail into a finally clause, you should
11833think about catching or ignoring the errors in these commands, see
11834|catch-errors| and |ignore-errors|.
11835
11836
11837CATCHING ERRORS *catch-errors*
11838
11839If you want to catch specific errors, you just have to put the code to be
11840watched in a try block and add a catch clause for the error message. The
11841presence of the try conditional causes all errors to be converted to an
11842exception. No message is displayed and |v:errmsg| is not set then. To find
11843the right pattern for the ":catch" command, you have to know how the format of
11844the error exception is.
11845 Error exceptions have the following format: >
11846
11847 Vim({cmdname}):{errmsg}
11848or >
11849 Vim:{errmsg}
11850
11851{cmdname} is the name of the command that failed; the second form is used when
Bram Moolenaar58b85342016-08-14 19:54:54 +020011852the command name is not known. {errmsg} is the error message usually produced
Bram Moolenaar071d4272004-06-13 20:20:40 +000011853when the error occurs outside try conditionals. It always begins with
11854a capital "E", followed by a two or three-digit error number, a colon, and
11855a space.
11856
11857Examples:
11858
11859The command >
11860 :unlet novar
11861normally produces the error message >
11862 E108: No such variable: "novar"
11863which is converted inside try conditionals to an exception >
11864 Vim(unlet):E108: No such variable: "novar"
11865
11866The command >
11867 :dwim
11868normally produces the error message >
11869 E492: Not an editor command: dwim
11870which is converted inside try conditionals to an exception >
11871 Vim:E492: Not an editor command: dwim
11872
11873You can catch all ":unlet" errors by a >
11874 :catch /^Vim(unlet):/
11875or all errors for misspelled command names by a >
11876 :catch /^Vim:E492:/
11877
11878Some error messages may be produced by different commands: >
11879 :function nofunc
11880and >
11881 :delfunction nofunc
11882both produce the error message >
11883 E128: Function name must start with a capital: nofunc
11884which is converted inside try conditionals to an exception >
11885 Vim(function):E128: Function name must start with a capital: nofunc
11886or >
11887 Vim(delfunction):E128: Function name must start with a capital: nofunc
11888respectively. You can catch the error by its number independently on the
11889command that caused it if you use the following pattern: >
11890 :catch /^Vim(\a\+):E128:/
11891
11892Some commands like >
11893 :let x = novar
11894produce multiple error messages, here: >
11895 E121: Undefined variable: novar
11896 E15: Invalid expression: novar
11897Only the first is used for the exception value, since it is the most specific
11898one (see |except-several-errors|). So you can catch it by >
11899 :catch /^Vim(\a\+):E121:/
11900
11901You can catch all errors related to the name "nofunc" by >
11902 :catch /\<nofunc\>/
11903
11904You can catch all Vim errors in the ":write" and ":read" commands by >
11905 :catch /^Vim(\(write\|read\)):E\d\+:/
11906
11907You can catch all Vim errors by the pattern >
11908 :catch /^Vim\((\a\+)\)\=:E\d\+:/
11909<
11910 *catch-text*
11911NOTE: You should never catch the error message text itself: >
11912 :catch /No such variable/
Bram Moolenaar2b8388b2015-02-28 13:11:45 +010011913only works in the English locale, but not when the user has selected
Bram Moolenaar071d4272004-06-13 20:20:40 +000011914a different language by the |:language| command. It is however helpful to
11915cite the message text in a comment: >
11916 :catch /^Vim(\a\+):E108:/ " No such variable
11917
11918
11919IGNORING ERRORS *ignore-errors*
11920
11921You can ignore errors in a specific Vim command by catching them locally: >
11922
11923 :try
11924 : write
11925 :catch
11926 :endtry
11927
11928But you are strongly recommended NOT to use this simple form, since it could
11929catch more than you want. With the ":write" command, some autocommands could
11930be executed and cause errors not related to writing, for instance: >
11931
11932 :au BufWritePre * unlet novar
11933
11934There could even be such errors you are not responsible for as a script
11935writer: a user of your script might have defined such autocommands. You would
11936then hide the error from the user.
11937 It is much better to use >
11938
11939 :try
11940 : write
11941 :catch /^Vim(write):/
11942 :endtry
11943
11944which only catches real write errors. So catch only what you'd like to ignore
11945intentionally.
11946
11947For a single command that does not cause execution of autocommands, you could
11948even suppress the conversion of errors to exceptions by the ":silent!"
11949command: >
11950 :silent! nunmap k
11951This works also when a try conditional is active.
11952
11953
11954CATCHING INTERRUPTS *catch-interrupt*
11955
11956When there are active try conditionals, an interrupt (CTRL-C) is converted to
Bram Moolenaar58b85342016-08-14 19:54:54 +020011957the exception "Vim:Interrupt". You can catch it like every exception. The
Bram Moolenaar071d4272004-06-13 20:20:40 +000011958script is not terminated, then.
11959 Example: >
11960
11961 :function! TASK1()
11962 : sleep 10
11963 :endfunction
11964
11965 :function! TASK2()
11966 : sleep 20
11967 :endfunction
11968
11969 :while 1
11970 : let command = input("Type a command: ")
11971 : try
11972 : if command == ""
11973 : continue
11974 : elseif command == "END"
11975 : break
11976 : elseif command == "TASK1"
11977 : call TASK1()
11978 : elseif command == "TASK2"
11979 : call TASK2()
11980 : else
11981 : echo "\nIllegal command:" command
11982 : continue
11983 : endif
11984 : catch /^Vim:Interrupt$/
11985 : echo "\nCommand interrupted"
11986 : " Caught the interrupt. Continue with next prompt.
11987 : endtry
11988 :endwhile
11989
11990You can interrupt a task here by pressing CTRL-C; the script then asks for
Bram Moolenaar58b85342016-08-14 19:54:54 +020011991a new command. If you press CTRL-C at the prompt, the script is terminated.
Bram Moolenaar071d4272004-06-13 20:20:40 +000011992
11993For testing what happens when CTRL-C would be pressed on a specific line in
11994your script, use the debug mode and execute the |>quit| or |>interrupt|
11995command on that line. See |debug-scripts|.
11996
11997
11998CATCHING ALL *catch-all*
11999
12000The commands >
12001
12002 :catch /.*/
12003 :catch //
12004 :catch
12005
12006catch everything, error exceptions, interrupt exceptions and exceptions
12007explicitly thrown by the |:throw| command. This is useful at the top level of
12008a script in order to catch unexpected things.
12009 Example: >
12010
12011 :try
12012 :
12013 : " do the hard work here
12014 :
12015 :catch /MyException/
12016 :
12017 : " handle known problem
12018 :
12019 :catch /^Vim:Interrupt$/
12020 : echo "Script interrupted"
12021 :catch /.*/
12022 : echo "Internal error (" . v:exception . ")"
12023 : echo " - occurred at " . v:throwpoint
12024 :endtry
12025 :" end of script
12026
12027Note: Catching all might catch more things than you want. Thus, you are
12028strongly encouraged to catch only for problems that you can really handle by
12029specifying a pattern argument to the ":catch".
12030 Example: Catching all could make it nearly impossible to interrupt a script
12031by pressing CTRL-C: >
12032
12033 :while 1
12034 : try
12035 : sleep 1
12036 : catch
12037 : endtry
12038 :endwhile
12039
12040
12041EXCEPTIONS AND AUTOCOMMANDS *except-autocmd*
12042
12043Exceptions may be used during execution of autocommands. Example: >
12044
12045 :autocmd User x try
12046 :autocmd User x throw "Oops!"
12047 :autocmd User x catch
12048 :autocmd User x echo v:exception
12049 :autocmd User x endtry
12050 :autocmd User x throw "Arrgh!"
12051 :autocmd User x echo "Should not be displayed"
12052 :
12053 :try
12054 : doautocmd User x
12055 :catch
12056 : echo v:exception
12057 :endtry
12058
12059This displays "Oops!" and "Arrgh!".
12060
12061 *except-autocmd-Pre*
12062For some commands, autocommands get executed before the main action of the
12063command takes place. If an exception is thrown and not caught in the sequence
12064of autocommands, the sequence and the command that caused its execution are
12065abandoned and the exception is propagated to the caller of the command.
12066 Example: >
12067
12068 :autocmd BufWritePre * throw "FAIL"
12069 :autocmd BufWritePre * echo "Should not be displayed"
12070 :
12071 :try
12072 : write
12073 :catch
12074 : echo "Caught:" v:exception "from" v:throwpoint
12075 :endtry
12076
12077Here, the ":write" command does not write the file currently being edited (as
12078you can see by checking 'modified'), since the exception from the BufWritePre
12079autocommand abandons the ":write". The exception is then caught and the
12080script displays: >
12081
12082 Caught: FAIL from BufWrite Auto commands for "*"
12083<
12084 *except-autocmd-Post*
12085For some commands, autocommands get executed after the main action of the
12086command has taken place. If this main action fails and the command is inside
12087an active try conditional, the autocommands are skipped and an error exception
12088is thrown that can be caught by the caller of the command.
12089 Example: >
12090
12091 :autocmd BufWritePost * echo "File successfully written!"
12092 :
12093 :try
12094 : write /i/m/p/o/s/s/i/b/l/e
12095 :catch
12096 : echo v:exception
12097 :endtry
12098
12099This just displays: >
12100
12101 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
12102
12103If you really need to execute the autocommands even when the main action
12104fails, trigger the event from the catch clause.
12105 Example: >
12106
12107 :autocmd BufWritePre * set noreadonly
12108 :autocmd BufWritePost * set readonly
12109 :
12110 :try
12111 : write /i/m/p/o/s/s/i/b/l/e
12112 :catch
12113 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
12114 :endtry
12115<
12116You can also use ":silent!": >
12117
12118 :let x = "ok"
12119 :let v:errmsg = ""
12120 :autocmd BufWritePost * if v:errmsg != ""
12121 :autocmd BufWritePost * let x = "after fail"
12122 :autocmd BufWritePost * endif
12123 :try
12124 : silent! write /i/m/p/o/s/s/i/b/l/e
12125 :catch
12126 :endtry
12127 :echo x
12128
12129This displays "after fail".
12130
12131If the main action of the command does not fail, exceptions from the
12132autocommands will be catchable by the caller of the command: >
12133
12134 :autocmd BufWritePost * throw ":-("
12135 :autocmd BufWritePost * echo "Should not be displayed"
12136 :
12137 :try
12138 : write
12139 :catch
12140 : echo v:exception
12141 :endtry
12142<
12143 *except-autocmd-Cmd*
12144For some commands, the normal action can be replaced by a sequence of
12145autocommands. Exceptions from that sequence will be catchable by the caller
12146of the command.
12147 Example: For the ":write" command, the caller cannot know whether the file
Bram Moolenaar58b85342016-08-14 19:54:54 +020012148had actually been written when the exception occurred. You need to tell it in
Bram Moolenaar071d4272004-06-13 20:20:40 +000012149some way. >
12150
12151 :if !exists("cnt")
12152 : let cnt = 0
12153 :
12154 : autocmd BufWriteCmd * if &modified
12155 : autocmd BufWriteCmd * let cnt = cnt + 1
12156 : autocmd BufWriteCmd * if cnt % 3 == 2
12157 : autocmd BufWriteCmd * throw "BufWriteCmdError"
12158 : autocmd BufWriteCmd * endif
12159 : autocmd BufWriteCmd * write | set nomodified
12160 : autocmd BufWriteCmd * if cnt % 3 == 0
12161 : autocmd BufWriteCmd * throw "BufWriteCmdError"
12162 : autocmd BufWriteCmd * endif
12163 : autocmd BufWriteCmd * echo "File successfully written!"
12164 : autocmd BufWriteCmd * endif
12165 :endif
12166 :
12167 :try
12168 : write
12169 :catch /^BufWriteCmdError$/
12170 : if &modified
12171 : echo "Error on writing (file contents not changed)"
12172 : else
12173 : echo "Error after writing"
12174 : endif
12175 :catch /^Vim(write):/
12176 : echo "Error on writing"
12177 :endtry
12178
12179When this script is sourced several times after making changes, it displays
12180first >
12181 File successfully written!
12182then >
12183 Error on writing (file contents not changed)
12184then >
12185 Error after writing
12186etc.
12187
12188 *except-autocmd-ill*
12189You cannot spread a try conditional over autocommands for different events.
12190The following code is ill-formed: >
12191
12192 :autocmd BufWritePre * try
12193 :
12194 :autocmd BufWritePost * catch
12195 :autocmd BufWritePost * echo v:exception
12196 :autocmd BufWritePost * endtry
12197 :
12198 :write
12199
12200
12201EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS *except-hier-param*
12202
12203Some programming languages allow to use hierarchies of exception classes or to
12204pass additional information with the object of an exception class. You can do
12205similar things in Vim.
12206 In order to throw an exception from a hierarchy, just throw the complete
12207class name with the components separated by a colon, for instance throw the
12208string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
12209 When you want to pass additional information with your exception class, add
12210it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
12211for an error when writing "myfile".
12212 With the appropriate patterns in the ":catch" command, you can catch for
12213base classes or derived classes of your hierarchy. Additional information in
12214parentheses can be cut out from |v:exception| with the ":substitute" command.
12215 Example: >
12216
12217 :function! CheckRange(a, func)
12218 : if a:a < 0
12219 : throw "EXCEPT:MATHERR:RANGE(" . a:func . ")"
12220 : endif
12221 :endfunction
12222 :
12223 :function! Add(a, b)
12224 : call CheckRange(a:a, "Add")
12225 : call CheckRange(a:b, "Add")
12226 : let c = a:a + a:b
12227 : if c < 0
12228 : throw "EXCEPT:MATHERR:OVERFLOW"
12229 : endif
12230 : return c
12231 :endfunction
12232 :
12233 :function! Div(a, b)
12234 : call CheckRange(a:a, "Div")
12235 : call CheckRange(a:b, "Div")
12236 : if (a:b == 0)
12237 : throw "EXCEPT:MATHERR:ZERODIV"
12238 : endif
12239 : return a:a / a:b
12240 :endfunction
12241 :
12242 :function! Write(file)
12243 : try
Bram Moolenaar446cb832008-06-24 21:56:24 +000012244 : execute "write" fnameescape(a:file)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012245 : catch /^Vim(write):/
12246 : throw "EXCEPT:IO(" . getcwd() . ", " . a:file . "):WRITEERR"
12247 : endtry
12248 :endfunction
12249 :
12250 :try
12251 :
12252 : " something with arithmetics and I/O
12253 :
12254 :catch /^EXCEPT:MATHERR:RANGE/
12255 : let function = substitute(v:exception, '.*(\(\a\+\)).*', '\1', "")
12256 : echo "Range error in" function
12257 :
12258 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
12259 : echo "Math error"
12260 :
12261 :catch /^EXCEPT:IO/
12262 : let dir = substitute(v:exception, '.*(\(.\+\),\s*.\+).*', '\1', "")
12263 : let file = substitute(v:exception, '.*(.\+,\s*\(.\+\)).*', '\1', "")
12264 : if file !~ '^/'
12265 : let file = dir . "/" . file
12266 : endif
12267 : echo 'I/O error for "' . file . '"'
12268 :
12269 :catch /^EXCEPT/
12270 : echo "Unspecified error"
12271 :
12272 :endtry
12273
12274The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
12275a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
12276exceptions with the "Vim" prefix; they are reserved for Vim.
12277 Vim error exceptions are parameterized with the name of the command that
12278failed, if known. See |catch-errors|.
12279
12280
12281PECULIARITIES
12282 *except-compat*
12283The exception handling concept requires that the command sequence causing the
12284exception is aborted immediately and control is transferred to finally clauses
12285and/or a catch clause.
12286
12287In the Vim script language there are cases where scripts and functions
12288continue after an error: in functions without the "abort" flag or in a command
12289after ":silent!", control flow goes to the following line, and outside
12290functions, control flow goes to the line following the outermost ":endwhile"
12291or ":endif". On the other hand, errors should be catchable as exceptions
12292(thus, requiring the immediate abortion).
12293
12294This problem has been solved by converting errors to exceptions and using
12295immediate abortion (if not suppressed by ":silent!") only when a try
Bram Moolenaar58b85342016-08-14 19:54:54 +020012296conditional is active. This is no restriction since an (error) exception can
12297be caught only from an active try conditional. If you want an immediate
Bram Moolenaar071d4272004-06-13 20:20:40 +000012298termination without catching the error, just use a try conditional without
12299catch clause. (You can cause cleanup code being executed before termination
12300by specifying a finally clause.)
12301
12302When no try conditional is active, the usual abortion and continuation
12303behavior is used instead of immediate abortion. This ensures compatibility of
12304scripts written for Vim 6.1 and earlier.
12305
12306However, when sourcing an existing script that does not use exception handling
12307commands (or when calling one of its functions) from inside an active try
12308conditional of a new script, you might change the control flow of the existing
12309script on error. You get the immediate abortion on error and can catch the
12310error in the new script. If however the sourced script suppresses error
12311messages by using the ":silent!" command (checking for errors by testing
Bram Moolenaar58b85342016-08-14 19:54:54 +020012312|v:errmsg| if appropriate), its execution path is not changed. The error is
12313not converted to an exception. (See |:silent|.) So the only remaining cause
Bram Moolenaar071d4272004-06-13 20:20:40 +000012314where this happens is for scripts that don't care about errors and produce
12315error messages. You probably won't want to use such code from your new
12316scripts.
12317
12318 *except-syntax-err*
12319Syntax errors in the exception handling commands are never caught by any of
12320the ":catch" commands of the try conditional they belong to. Its finally
12321clauses, however, is executed.
12322 Example: >
12323
12324 :try
12325 : try
12326 : throw 4711
12327 : catch /\(/
12328 : echo "in catch with syntax error"
12329 : catch
12330 : echo "inner catch-all"
12331 : finally
12332 : echo "inner finally"
12333 : endtry
12334 :catch
12335 : echo 'outer catch-all caught "' . v:exception . '"'
12336 : finally
12337 : echo "outer finally"
12338 :endtry
12339
12340This displays: >
12341 inner finally
12342 outer catch-all caught "Vim(catch):E54: Unmatched \("
12343 outer finally
12344The original exception is discarded and an error exception is raised, instead.
12345
12346 *except-single-line*
12347The ":try", ":catch", ":finally", and ":endtry" commands can be put on
12348a single line, but then syntax errors may make it difficult to recognize the
12349"catch" line, thus you better avoid this.
12350 Example: >
12351 :try | unlet! foo # | catch | endtry
12352raises an error exception for the trailing characters after the ":unlet!"
12353argument, but does not see the ":catch" and ":endtry" commands, so that the
12354error exception is discarded and the "E488: Trailing characters" message gets
12355displayed.
12356
12357 *except-several-errors*
12358When several errors appear in a single command, the first error message is
12359usually the most specific one and therefor converted to the error exception.
12360 Example: >
12361 echo novar
12362causes >
12363 E121: Undefined variable: novar
12364 E15: Invalid expression: novar
12365The value of the error exception inside try conditionals is: >
12366 Vim(echo):E121: Undefined variable: novar
12367< *except-syntax-error*
12368But when a syntax error is detected after a normal error in the same command,
12369the syntax error is used for the exception being thrown.
12370 Example: >
12371 unlet novar #
12372causes >
12373 E108: No such variable: "novar"
12374 E488: Trailing characters
12375The value of the error exception inside try conditionals is: >
12376 Vim(unlet):E488: Trailing characters
12377This is done because the syntax error might change the execution path in a way
12378not intended by the user. Example: >
12379 try
12380 try | unlet novar # | catch | echo v:exception | endtry
12381 catch /.*/
12382 echo "outer catch:" v:exception
12383 endtry
12384This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
12385a "E600: Missing :endtry" error message is given, see |except-single-line|.
12386
12387==============================================================================
123889. Examples *eval-examples*
12389
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012390Printing in Binary ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012391>
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010012392 :" The function Nr2Bin() returns the binary string representation of a number.
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012393 :func Nr2Bin(nr)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012394 : let n = a:nr
12395 : let r = ""
12396 : while n
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012397 : let r = '01'[n % 2] . r
12398 : let n = n / 2
Bram Moolenaar071d4272004-06-13 20:20:40 +000012399 : endwhile
12400 : return r
12401 :endfunc
12402
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012403 :" The function String2Bin() converts each character in a string to a
12404 :" binary string, separated with dashes.
12405 :func String2Bin(str)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012406 : let out = ''
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012407 : for ix in range(strlen(a:str))
12408 : let out = out . '-' . Nr2Bin(char2nr(a:str[ix]))
12409 : endfor
12410 : return out[1:]
Bram Moolenaar071d4272004-06-13 20:20:40 +000012411 :endfunc
12412
12413Example of its use: >
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012414 :echo Nr2Bin(32)
12415result: "100000" >
12416 :echo String2Bin("32")
12417result: "110011-110010"
Bram Moolenaar071d4272004-06-13 20:20:40 +000012418
12419
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012420Sorting lines ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012421
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012422This example sorts lines with a specific compare function. >
12423
12424 :func SortBuffer()
12425 : let lines = getline(1, '$')
12426 : call sort(lines, function("Strcmp"))
12427 : call setline(1, lines)
Bram Moolenaar071d4272004-06-13 20:20:40 +000012428 :endfunction
12429
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012430As a one-liner: >
12431 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
Bram Moolenaar071d4272004-06-13 20:20:40 +000012432
Bram Moolenaar071d4272004-06-13 20:20:40 +000012433
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012434scanf() replacement ~
Bram Moolenaar071d4272004-06-13 20:20:40 +000012435 *sscanf*
12436There is no sscanf() function in Vim. If you need to extract parts from a
12437line, you can use matchstr() and substitute() to do it. This example shows
12438how to get the file name, line number and column number out of a line like
12439"foobar.txt, 123, 45". >
12440 :" Set up the match bit
12441 :let mx='\(\f\+\),\s*\(\d\+\),\s*\(\d\+\)'
12442 :"get the part matching the whole expression
12443 :let l = matchstr(line, mx)
12444 :"get each item out of the match
12445 :let file = substitute(l, mx, '\1', '')
12446 :let lnum = substitute(l, mx, '\2', '')
12447 :let col = substitute(l, mx, '\3', '')
12448
12449The input is in the variable "line", the results in the variables "file",
12450"lnum" and "col". (idea from Michael Geddes)
12451
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012452
12453getting the scriptnames in a Dictionary ~
12454 *scriptnames-dictionary*
12455The |:scriptnames| command can be used to get a list of all script files that
12456have been sourced. There is no equivalent function or variable for this
12457(because it's rarely needed). In case you need to manipulate the list this
12458code can be used: >
12459 " Get the output of ":scriptnames" in the scriptnames_output variable.
12460 let scriptnames_output = ''
12461 redir => scriptnames_output
12462 silent scriptnames
12463 redir END
Bram Moolenaarb0d45e72017-11-05 18:19:24 +010012464
Bram Moolenaar446cb832008-06-24 21:56:24 +000012465 " Split the output into lines and parse each line. Add an entry to the
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012466 " "scripts" dictionary.
12467 let scripts = {}
12468 for line in split(scriptnames_output, "\n")
12469 " Only do non-blank lines.
12470 if line =~ '\S'
12471 " Get the first number in the line.
Bram Moolenaar446cb832008-06-24 21:56:24 +000012472 let nr = matchstr(line, '\d\+')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012473 " Get the file name, remove the script number " 123: ".
Bram Moolenaar446cb832008-06-24 21:56:24 +000012474 let name = substitute(line, '.\+:\s*', '', '')
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012475 " Add an item to the Dictionary
Bram Moolenaar446cb832008-06-24 21:56:24 +000012476 let scripts[nr] = name
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012477 endif
12478 endfor
12479 unlet scriptnames_output
12480
Bram Moolenaar071d4272004-06-13 20:20:40 +000012481==============================================================================
1248210. No +eval feature *no-eval-feature*
12483
12484When the |+eval| feature was disabled at compile time, none of the expression
12485evaluation commands are available. To prevent this from causing Vim scripts
12486to generate all kinds of errors, the ":if" and ":endif" commands are still
12487recognized, though the argument of the ":if" and everything between the ":if"
12488and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
12489only if the commands are at the start of the line. The ":else" command is not
12490recognized.
12491
12492Example of how to avoid executing commands when the |+eval| feature is
12493missing: >
12494
12495 :if 1
12496 : echo "Expression evaluation is compiled in"
12497 :else
12498 : echo "You will _never_ see this message"
12499 :endif
12500
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +020012501To execute a command only when the |+eval| feature is disabled requires a trick,
12502as this example shows: >
Bram Moolenaar45d2cca2017-04-30 16:36:05 +020012503
12504 silent! while 0
12505 set history=111
12506 silent! endwhile
12507
12508When the |+eval| feature is available the command is skipped because of the
12509"while 0". Without the |+eval| feature the "while 0" is an error, which is
12510silently ignored, and the command is executed.
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +020012511
Bram Moolenaar071d4272004-06-13 20:20:40 +000012512==============================================================================
1251311. The sandbox *eval-sandbox* *sandbox* *E48*
12514
Bram Moolenaar368373e2010-07-19 20:46:22 +020012515The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
12516'foldtext' options may be evaluated in a sandbox. This means that you are
12517protected from these expressions having nasty side effects. This gives some
12518safety for when these options are set from a modeline. It is also used when
12519the command from a tags file is executed and for CTRL-R = in the command line.
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000012520The sandbox is also used for the |:sandbox| command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000012521
12522These items are not allowed in the sandbox:
12523 - changing the buffer text
Bram Moolenaarb477af22018-07-15 20:20:18 +020012524 - defining or changing mapping, autocommands, user commands
Bram Moolenaar071d4272004-06-13 20:20:40 +000012525 - setting certain options (see |option-summary|)
Bram Moolenaaref2f6562007-05-06 13:32:59 +000012526 - setting certain v: variables (see |v:var|) *E794*
Bram Moolenaar071d4272004-06-13 20:20:40 +000012527 - executing a shell command
12528 - reading or writing a file
12529 - jumping to another buffer or editing a file
Bram Moolenaar4770d092006-01-12 23:22:24 +000012530 - executing Python, Perl, etc. commands
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000012531This is not guaranteed 100% secure, but it should block most attacks.
12532
12533 *:san* *:sandbox*
Bram Moolenaar045e82d2005-07-08 22:25:33 +000012534:san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
Bram Moolenaar7b0294c2004-10-11 10:16:09 +000012535 option that may have been set from a modeline, e.g.
12536 'foldexpr'.
12537
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012538 *sandbox-option*
12539A few options contain an expression. When this expression is evaluated it may
Bram Moolenaar9b2200a2006-03-20 21:55:45 +000012540have to be done in the sandbox to avoid a security risk. But the sandbox is
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012541restrictive, thus this only happens when the option was set from an insecure
12542location. Insecure in this context are:
Bram Moolenaar551dbcc2006-04-25 22:13:59 +000012543- sourcing a .vimrc or .exrc in the current directory
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012544- while executing in the sandbox
12545- value coming from a modeline
Bram Moolenaarb477af22018-07-15 20:20:18 +020012546- executing a function that was defined in the sandbox
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012547
12548Note that when in the sandbox and saving an option value and restoring it, the
12549option will still be marked as it was set in the sandbox.
12550
12551==============================================================================
1255212. Textlock *textlock*
12553
12554In a few situations it is not allowed to change the text in the buffer, jump
12555to another window and some other things that might confuse or break what Vim
12556is currently doing. This mostly applies to things that happen when Vim is
Bram Moolenaar58b85342016-08-14 19:54:54 +020012557actually doing something else. For example, evaluating the 'balloonexpr' may
Bram Moolenaarb71eaae2006-01-20 23:10:18 +000012558happen any moment the mouse cursor is resting at some position.
12559
12560This is not allowed when the textlock is active:
12561 - changing the buffer text
12562 - jumping to another buffer or window
12563 - editing another file
12564 - closing a window or quitting Vim
12565 - etc.
12566
Bram Moolenaardc1f1642016-08-16 18:33:43 +020012567==============================================================================
1256813. Testing *testing*
12569
12570Vim can be tested after building it, usually with "make test".
12571The tests are located in the directory "src/testdir".
12572
12573There are several types of tests added over time:
12574 test33.in oldest, don't add any more
12575 test_something.in old style tests
12576 test_something.vim new style tests
12577
12578 *new-style-testing*
12579New tests should be added as new style tests. These use functions such as
12580|assert_equal()| to keep the test commands and the expected result in one
12581place.
12582 *old-style-testing*
12583In some cases an old style test needs to be used. E.g. when testing Vim
12584without the |+eval| feature.
12585
12586Find more information in the file src/testdir/README.txt.
12587
Bram Moolenaar071d4272004-06-13 20:20:40 +000012588
Bram Moolenaar91f84f62018-07-29 15:07:52 +020012589 vim:tw=78:ts=8:noet:ft=help:norl: